Axiom V2 Docs Old
  • Introduction
    • What is Axiom?
    • Quickstart
  • Examples
    • Autonomous Airdrop
      • AxiomREPL Code
      • Contract
      • Web App
      • DataQuery-only Version
  • Developers
    • Axiom for Developers
    • Specifying a Query into Axiom
    • AxiomREPL
      • AxiomREPL Examples
    • Exporting a Client Side Prover
    • Handling Axiom Callbacks
    • Common Issues
      • Callback Debugging
  • SDK and REPL Reference
    • Axiom SDK Reference
      • QueryBuilderV2
      • Data Subqueries
        • Header Subquery
        • Account Subquery
        • Storage Subquery
        • Transaction Subquery
        • Receipt Subquery
        • Solidity Nested Mapping Subquery
    • AxiomREPL Reference
      • Circuit Types
      • Circuit Functions
      • Data Functions
      • Compute Functions
  • Protocol Design
    • Architecture Overview
    • Caching Block Hashes
    • Axiom Query Protocol
      • Axiom Query Format
    • ZK Circuits for Axiom Queries
    • Ethereum On-chain Data
    • Guardrails
  • Transparency and Security
    • KZG Trusted Setup
    • Contract Addresses
    • On-chain ZK Verifiers
    • Security
  • Zero Knowledge Proofs
    • Introduction to ZK
    • ZK Examples
    • Getting Started with halo2
    • halo2-repl
  • Additional Resources
    • Axiom V2 Explorer
    • Github
    • Website
    • Telegram
    • Discord
    • Axiom V1 Docs
Powered by GitBook
On this page
  • Freezing
  • Upgrades
  1. Protocol Design

Guardrails

Trust-minimized guardrails for Axiom

PreviousEthereum On-chain DataNextKZG Trusted Setup

Last updated 1 year ago

Axiom V2 is currently governed by three administrative roles. Although Axiom itself only holds user funds to accept payment for query fulfillment, the protocol has some administrative functions to:

  • Protect against catastrophic outcomes for downstream applications in case of an exploit.

  • Allow upgrades stay in sync with future changes to Ethereum.

The contracts , , , , , and implement , freezing, and unfreezing functionality, controlled by the AxiomAccess contract. The relevant roles are:

  • TIMELOCK_ROLE: All upgrades, including upgrades of the underlying SNARK verifier addresses, are controlled by a OpenZeppelin controlled by a Gnosis SAFE multisig (Axiom Timelock multisig).

  • GUARDIAN_ROLE: This role allows for immediate freezing of critical functions like AxiomV2Core block hash updates and AxiomV2Query query initiation and fulfillment. The freeze functionality is intended to be used in the event of an unforeseen ZK circuit bug. This role is held by a Gnosis SAFE multisig (Axiom Guardian multisig) with a lower threshold than the Axiom Timelock multisig.

  • UNFREEZE_ROLE: This role allows for immediate unfreezing of contracts. It is held by a Gnosis SAFE multisig.

  • PROVER_ROLE: This role is used only for and is given to accounts which are permissioned to prove in the Axiom system.

We further documents the capabilities and limitations of these roles below to provide transparency about their security implications.

Freezing

If a vulnerability is found in the Axiom smart contracts or ZK circuits, the GUARDIAN_ROLE, which is held by a Gnosis SAFE multisig (Axiom Guardian multisig), will use

function freezeAll() external onlyRole(GUARDIAN_ROLE)

to pause all update functionality to the Axiom ZK circuits, including:

  • Updates to the cache of historic block hashes in AxiomV2Core

  • Submission of new queries into AxiomV2Query

  • Fulfillment of queries into AxiomV2Query

By pausing updates to the contracts, this safety mechanism provides time for any potential issues to be mitigated. It is intended to be used only in the event of an exploit. As the protocol matures, we intend to remove this mechanism.

The contract can be unfrozen, after the issues in question have been mitigated, by the UNFREEZE_ROLE using

function unfreezeAll() external onlyRole(UNFREEZE_ROLE)

Upgrades

The upgrade functionality is intended to be used for three purposes:

  • Recovery from any vulnerabilities or exploits found in Axiom.

  • To upgrade the Axiom ZK circuits to match protocol upgrades to Ethereum.

  • To introduce new optimizations or extensions to the Axiom query format.

As the protocol matures, we intend to expand the set of multisig holders and perform non-mandatory upgrades infrequently.

The AxiomV2Core and AxiomV2Query contracts are currently upgradeable via the OpenZeppelin pattern and have upgradeable verifiers for ZK proofs of historic block hashes and query results. These upgrades are permissioned to the TIMELOCK_ROLE, which is assigned to an OpenZeppelin controller (AxiomTimelock) controlled by a Gnosis SAFE multisig. The timelock delay is set to 1 week on Mainnet and 10 minutes on Testnet.

We use a Timelock delay to provide users recourse in the event of a contract upgrade they disagree with. Because execution of upgrades can only take place after the timelock delay, users are able to verify upgrades are not malicious and have time to exit the protocol if they disagree with any changes. As detailed in , to guard against , users should check that each deployed verifier contract bytecode does not contain SELFDESTRUCT or DELEGATECALL.

UUPSUpgradeable
Timelock
AxiomV2Core
UUPS Upgradeability
TimelockController
metamorphic contract attacks
AxiomV2Query
AxiomV2Prover
AxiomV2HeaderVerifier
AxiomResultStore
AxiomV2Prover
Checking Verifiers are not Metamorphic