Shielded pool contract

The shielded pool is an internal contract (built-in) that holds shielded balances and verifies proof-based spends.

Address

• SHIELDED_POOL_CONTRACT_ADDRESS in crates/mazzecore/parameters/src/internal_contract_addresses.rs

Public functions

• shield(bytes32,bytes)

  • Accepts a commitment and ciphertext with a non-zero value transfer.

  • Appends the commitment to the Poseidon Merkle tree.

  • Emits a ShieldedNote(bytes32,bytes) event.

• applyShieldedBundle(...)

  • Verifies a Groth16 proof against the anchor, nullifiers, commitments, outputs, values, and fee.

  • Marks nullifiers as spent.

  • Appends new commitments and emits ShieldedNote events.

  • Pays the fee and transparent outputs from the pool balance.

• root()

  • Returns the latest Merkle root.

• isNullifierSpent(bytes32)

  • Returns whether a nullifier has been spent.

• setVerifyingKey(bytes)

  • Sets the Groth16 verifying key once (admin only).

• verifyingKeyHash()

  • Returns the keccak hash of the verifying key.

Limits and parameters

• Tree depth: 32 levels.

• Root history: 64 roots.

• Max nullifiers per bundle: 8.

• Max commitments per bundle: 8.

• Max transparent outputs per bundle: 8.

• Max ciphertext size: 512 bytes.

• Max proof size: 256 bytes.

• Max verifying key size: 8192 bytes.

Storage layout (system storage)

The pool stores its state in system storage keyed by hashed prefixes:

• shielded:vk_len, shielded:vk_word:*, shielded:vk_hash

• shielded:nullifier:*

• shielded:root_index, shielded:root:*

• shielded:leaf_index, shielded:frontier:*

Genesis behavior

If a verifying key is provided at genesis, a setVerifyingKey transaction is executed and the shielded pool admin is cleared.

Genesis can also seed shielded pool balance using SHIELDED_POOL_GENESIS_FUND_MAZZE. That seed is transferred from treasury (not newly minted). See ../tokenomics/shielded-pool-genesis-fund.md.