Skip to main content
Version: v2.0.2

Useful Commands

Overview​

This reference provides commands for common sequencer operator tasks. You'll use Foundry's cast command to query onchain contract state, check sequencer status, and monitor governance processes.

If you need help with something not covered here, visit the Aztec Discord in the #operator-faq channel.

Prerequisites​

Before using these commands, ensure you have:

  • Foundry installed with the cast command available (installation guide)
  • Aztec CLI tool installed (see prerequisites guide)
  • Ethereum RPC endpoint (execution layer) for the network you're querying
  • Contract addresses for your deployment (Registry, Rollup, Governance)

Getting Started​

Set Up Your Environment​

For convenience, set your RPC URL as an environment variable:

export RPC_URL="https://your-ethereum-rpc-endpoint.com"

All examples below use --rpc-url $RPC_URL. In production, always include this flag with your actual RPC endpoint.

Understanding Deployments​

Assume there are multiple deployments of Aztec, such as testnet and ignition-testnet. Each deployment has a unique Registry contract address that remains constant across upgrades. If a governance upgrade deploys a new rollup contract, the Registry contract address stays the same.

Find the Registry Contract Address​

The Registry contract is your entrypoint to all other contracts for a specific deployment. You'll need this address to discover other contract addresses.

Contact the Aztec team or check the documentation for the Registry contract address for your target network (testnet, ignition-testnet, etc.).

Get the Rollup Contract Address​

Once you have the Registry address, retrieve the Rollup contract:

cast call [REGISTRY_CONTRACT_ADDRESS] "getCanonicalRollup()" --rpc-url $RPC_URL

Replace [REGISTRY_CONTRACT_ADDRESS] with your actual Registry contract address.

Example:

cast call 0x1234567890abcdef1234567890abcdef12345678 "getCanonicalRollup()" --rpc-url $RPC_URL

This returns the Rollup contract address in hexadecimal format.

Query the Sequencer Set​

Get the GSE Contract Address​

The GSE (Governance Staking Escrow) contract manages sequencer registrations and balances. Get its address from the Rollup contract:

cast call [ROLLUP_ADDRESS] "getGSE()" --rpc-url $RPC_URL

This returns the GSE contract address, which you'll need for some queries below.

Count Active Sequencers​

Get the total number of active sequencers in the set:

cast call [ROLLUP_ADDRESS] "getActiveAttesterCount()" --rpc-url $RPC_URL

This returns the count of currently active sequencers as a hexadecimal number.

List Sequencers by Index​

Retrieve individual sequencer addresses by their index (0-based):

cast call [ROLLUP_ADDRESS] "getAttesterAtIndex(uint256)" [INDEX] --rpc-url $RPC_URL

Replace:

  • [ROLLUP_ADDRESS] - Your Rollup contract address
  • [INDEX] - The index of the sequencer (starting from 0)

Example:

# Get the first sequencer (index 0)
cast call 0xabcdef1234567890abcdef1234567890abcdef12 "getAttesterAtIndex(uint256)" 0 --rpc-url $RPC_URL

# Get the second sequencer (index 1)
cast call 0xabcdef1234567890abcdef1234567890abcdef12 "getAttesterAtIndex(uint256)" 1 --rpc-url $RPC_URL

Check Sequencer Status​

Query the complete status and information for a specific sequencer:

cast call [ROLLUP_ADDRESS] "getAttesterView(address)" [ATTESTER_ADDRESS] --rpc-url $RPC_URL

Replace:

  • [ROLLUP_ADDRESS] - Your Rollup contract address
  • [ATTESTER_ADDRESS] - The sequencer's attester address you want to check

Example:

cast call 0xabcdef1234567890abcdef1234567890abcdef12 "getAttesterView(address)" 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb --rpc-url $RPC_URL

Interpret the Response​

The getAttesterView command returns an AttesterView struct containing:

  1. status - The sequencer's current status code (see Status Codes below)
  2. effectiveBalance - The sequencer's effective stake balance
  3. exit - Exit information struct (if the sequencer is exiting):
    • withdrawalId - Withdrawal ID in the GSE contract
    • amount - Amount being withdrawn
    • exitableAt - Timestamp when withdrawal can be finalized
    • recipientOrWithdrawer - Address that receives funds or can initiate withdrawal
    • isRecipient - Whether the exit has a recipient set
    • exists - Whether an exit exists
  4. config - Attester configuration struct:
    • publicKey - BLS public key (G1 point with x and y coordinates)
    • withdrawer - Address authorized to withdraw stake

Get Individual Sequencer Information​

Query specific pieces of information using the GSE contract:

# Check if a sequencer is registered
cast call [GSE_ADDRESS] "isRegistered(address,address)" [ROLLUP_ADDRESS] [ATTESTER_ADDRESS] --rpc-url $RPC_URL

# Get sequencer's balance on this rollup instance
cast call [GSE_ADDRESS] "balanceOf(address,address)" [ROLLUP_ADDRESS] [ATTESTER_ADDRESS] --rpc-url $RPC_URL

# Get sequencer's effective balance (includes bonus if latest rollup)
cast call [GSE_ADDRESS] "effectiveBalanceOf(address,address)" [ROLLUP_ADDRESS] [ATTESTER_ADDRESS] --rpc-url $RPC_URL

# Get sequencer's configuration (withdrawer and public key)
cast call [ROLLUP_ADDRESS] "getConfig(address)" [ATTESTER_ADDRESS] --rpc-url $RPC_URL

# Get only the status
cast call [ROLLUP_ADDRESS] "getStatus(address)" [ATTESTER_ADDRESS] --rpc-url $RPC_URL

Status Codes​

StatusNameMeaning
0NONEThe sequencer does not exist in the sequencer set
1VALIDATINGThe sequencer is currently active and participating in consensus
2ZOMBIEThe sequencer is not active (balance fell below ejection threshold, possibly due to slashing) but still has funds in the system
3EXITINGThe sequencer has initiated withdrawal and is in the exit delay period

Governance Operations​

Get Governance Contract Addresses​

First, get the Governance contract from the Registry, then query it for the GovernanceProposer contract:

# Get the Governance contract
cast call [REGISTRY_ADDRESS] "getGovernance()" --rpc-url $RPC_URL

# Get the GovernanceProposer contract
cast call [GOVERNANCE_ADDRESS] "governanceProposer()" --rpc-url $RPC_URL

Replace [REGISTRY_ADDRESS] and [GOVERNANCE_ADDRESS] with your actual addresses.

Check Governance Quorum Requirements​

Query the quorum parameters for the governance system:

# Get the signaling round size (in L2 blocks)
cast call [GOVERNANCE_PROPOSER_ADDRESS] "M()" --rpc-url $RPC_URL

# Get the number of signals required for quorum in any single round
cast call [GOVERNANCE_PROPOSER_ADDRESS] "N()" --rpc-url $RPC_URL

What these values mean:

  • M() - The size of any signaling round, measured in L2 blocks (e.g., 1000 blocks)
  • N() - The number of signals needed within a round for a payload to reach quorum (e.g., 750 signals, which is 75% of M)

Find the Current Round Number​

Calculate which governance round corresponds to a specific L2 slot:

cast call [GOVERNANCE_PROPOSER_ADDRESS] "computeRound(uint256)" [SLOT_NUMBER] --rpc-url $RPC_URL

Replace:

  • [GOVERNANCE_PROPOSER_ADDRESS] - Your GovernanceProposer contract address
  • [SLOT_NUMBER] - The L2 slot number you want to check

This returns the round number in hexadecimal format. Convert it to decimal for use in the next command.

Example:

# Check which round slot 5000 belongs to
cast call 0x9876543210abcdef9876543210abcdef98765432 "computeRound(uint256)" 5000 --rpc-url $RPC_URL

# Output: 0x0000000000000000000000000000000000000000000000000000000000000005 (round 5)

Check Signal Count for a Payload​

Check how many sequencers have signaled support for a specific payload in a given round:

cast call [GOVERNANCE_PROPOSER_ADDRESS] "yeaCount(address,uint256,address)" [ROLLUP_ADDRESS] [ROUND_NUMBER] [PAYLOAD_ADDRESS] --rpc-url $RPC_URL

Replace:

  • [GOVERNANCE_PROPOSER_ADDRESS] - Your GovernanceProposer contract address
  • [ROLLUP_ADDRESS] - Your Rollup contract address
  • [ROUND_NUMBER] - The round number as a decimal integer (not hex)
  • [PAYLOAD_ADDRESS] - The address of the payload contract you're checking

Example:

cast call 0x9876543210abcdef9876543210abcdef98765432 "yeaCount(address,uint256,address)" 0xabcdef1234567890abcdef1234567890abcdef12 5 0x1111111111111111111111111111111111111111 --rpc-url $RPC_URL

This returns the number of signals the payload has received in that round. Compare this to the quorum threshold (N) to determine if the payload can be promoted to a proposal.

Get Current Proposal Count​

Check how many governance proposals exist:

cast call [GOVERNANCE_CONTRACT_ADDRESS] "proposalCount()" --rpc-url $RPC_URL

Query a Specific Proposal​

Get details about a specific proposal:

cast call [GOVERNANCE_CONTRACT_ADDRESS] "proposals(uint256)" [PROPOSAL_ID] --rpc-url $RPC_URL

Replace:

  • [GOVERNANCE_CONTRACT_ADDRESS] - Your Governance contract address
  • [PROPOSAL_ID] - The proposal ID (zero-indexed, so the first proposal is 0)

This returns the proposal struct containing:

  • Payload address
  • Creation timestamp
  • Voting start and end times
  • Current vote tallies

Tips and Best Practices​

Using Etherscan​

You can also query these contracts through Etherscan's "Read Contract" interface:

  1. Navigate to the contract address on Etherscan
  2. Go to the "Contract" tab
  3. Click "Read Contract" or "Read as Proxy"
  4. Find the function you want to call and enter parameters

This provides a user-friendly interface without requiring command-line tools.

Monitoring Automation​

Consider creating scripts that regularly query sequencer status and governance signals. This helps you:

  • Track your sequencer's health
  • Monitor governance proposals you care about
  • Receive alerts when action is needed

Decoding Hex Output​

Some commands return hexadecimal values. Use cast to convert them:

# Convert hex to decimal
cast --to-dec 0x03e8

# Convert hex to address format
cast --to-address 0x000000000000000000000000742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Troubleshooting​

"Invalid JSON RPC response"​

Issue: Command fails with JSON RPC error.

Solutions:

  • Verify your RPC endpoint is accessible and correct
  • Check that you're connected to the right network (Sepolia for testnet)
  • Ensure your RPC provider supports the eth_call method
  • Try a different RPC endpoint

"Reverted" or "Execution reverted"​

Issue: Contract call reverts.

Solutions:

  • Verify the contract address is correct
  • Check that the function signature matches the contract's ABI
  • Ensure you're passing the correct parameter types
  • Verify the contract is deployed on the network you're querying

"Could not find function"​

Issue: Function not found in contract.

Solutions:

  • Verify the function name spelling and capitalization
  • Check that you're querying the correct contract
  • Ensure the contract version matches the function you're calling
  • Try querying through Etherscan to verify the contract ABI

Next Steps​