Reference

Anchor Program

Complete on-chain reference for tova_core: program ID, PDA seeds, accounts, instructions, emitted events, and error codes.

Program metadata

FieldValue
Crate / moduletova_core
Program IDC5K5LF7CGN5zKf7mxHxy5PYQHnvzHEui7dtkLZ1ytmb9
ProtocolConfig PDAFXsYi3agEshdEbiA499isr6tvU5abgEdnjNepZ2gNCTu
PROOF_DOMAIN"TOVA_GROTH16_PROOF_V1"
RECEIPT_DOMAIN"TOVA_TEE_RECEIPT_V1"
MAX_FEE_BPS1000 (10.00% hard cap)
Event emissionAnchor #[event_cpi] / emit_cpi! (inner instruction tag e445a52e51cb9a1d)
Measured open_settlement CU38,631 CU on localnet
Measured claim_settlement CU31,967 CU on localnet

PDA seeds

Account / VaultSeeds
ProtocolConfig["protocol_config"]
RingVault["ring_vault", principal_pubkey, mint_pubkey]
vault_escrow (SOL escrow PDA)["vault_escrow", ring_vault_pubkey]
Mandate["mandate", ring_vault_pubkey, mandate_id_u64_le]
ProviderRegistry["provider", provider_signer_pubkey]
provider_stake (stake escrow PDA)["provider_stake", provider_registry_pubkey]
SettlementEscrow["settlement", mandate_pubkey, settlement_id_u64_le]
NullifierRecord["nullifier", ring_vault_pubkey, nullifier_hash_32]
Event authority (#[event_cpi])["__event_authority"]

State accounts

ProtocolConfig

FieldTypeDescription
authorityPubkeyAdmin signer authorized to update config
fee_recipientPubkeyRecipient wallet receiving fee_bps on claim_settlement
fee_bpsu16Protocol fee in basis points (0..=1000, default 25)
pausedboolHalts vault creation, deposits, mandate issuance, provider registration, and opening settlements
vault_countu64Total RingVault accounts created
mandate_countu64Total Mandate accounts issued
provider_countu64Total ProviderRegistry accounts registered
settlement_countu64Total SettlementEscrow accounts opened
total_fees_collectedu64Cumulative protocol fees transferred to fee_recipient in lamports
bumpu8PDA bump

RingVault

FieldTypeDescription
principalPubkeyVault owner
mintPubkeyAsset mint (So111... for SOL or any SPL mint)
merkle_root[u8; 32]Rolling commitment tree root
note_countu64Total deposited notes
viewing_key_tag[u8; 32]Public identifier for principal viewing key
auditor_key_tagOption<[u8; 32]>Optional public identifier for read-only auditor viewing key
escrow_balanceu64Available escrowed lamports tracked for this vault
created_slotu64Slot when the vault was initialized
bumpu8RingVault PDA bump
escrow_bumpu8vault_escrow PDA bump

Mandate

FieldTypeDescription
vaultPubkeyParent RingVault PDA
principalPubkeyVault principal authorized to revoke
agentPubkeyDelegated agent signer authorized to open settlements
mandate_idu64Caller-chosen ID per vault
per_call_cap_commitment[u8; 32]Commitment to per-call ceiling
epoch_budget_commitment[u8; 32]Commitment to epoch budget
epoch_spent_commitment[u8; 32]Rolling hash `SHA256("TOVA_EPOCH_SPENT"epoch_spent_le)`
per_call_cap_boundu64Maximum amount per single settlement
epoch_budget_boundu64Maximum cumulative amount per epoch
epoch_spentu64Amount spent in current_epoch_index
epoch_duration_slotsu64Slots per epoch window
current_epoch_indexu64Current epoch index since created_slot
allowed_provider_root[u8; 32]Provider filter root when open_providers == false
open_providersboolWhether any active registered provider is permitted
expiry_slotu64Slot after which new settlements reject
activebooltrue until revoked by revoke_mandate
auditor_key_tagOption<[u8; 32]>Optional per-mandate auditor tag
created_slotu64Slot when issued
bumpu8PDA bump

ProviderRegistry

FieldTypeDescription
provider_pubkeyPubkeyProvider operator wallet
attestation_pubkeyPubkeyEd25519 hardware attestation key
hardware_typeu80 (IntelTDX), 1 (AmdSevSnp), or 2 (LocalAttested)
attestation_expiry_slotu64Slot when current attestation expires
staked_capacity_lamportsu64SOL locked in provider_stake, bounding concurrent unsettled volume
active_unsettled_lamportsu64Sum of locked_amount across currently Open escrows
total_settled_countu64Cumulative Claimed settlements
activeboolProvider active flag
bumpu8ProviderRegistry PDA bump
stake_bumpu8provider_stake PDA bump

SettlementEscrow

FieldTypeDescription
settlement_idu64Unique ID per mandate
vaultPubkeyOriginating RingVault PDA
mandatePubkeyAuthorizing Mandate PDA
providerPubkeyTarget ProviderRegistry PDA
request_hash[u8; 32]Hash of the HTTP 402 request
amount_commitment[u8; 32]Shielded amount commitment
nullifier_hash[u8; 32]Spent note nullifier
locked_amountu64Escrowed amount in base units
deadline_slotu64Final slot for claim_settlement; refunds unlock after this slot
statusu80 (Open), 1 (Claimed), 2 (Refunded)
response_hash[u8; 32]Attested response hash (zeroed until Claimed)
epoch_indexu64Mandate epoch index at open time
created_slotu64Slot when opened
bumpu8PDA bump

NullifierRecord

FieldTypeDescription
vaultPubkeyParent RingVault PDA
nullifier_hash[u8; 32]Spent nullifier bytes
settlementPubkeyAssociated SettlementEscrow PDA (Pubkey::default() for withdrawals)
spent_slotu64Slot when nullifier was consumed
bumpu8PDA bump

Instructions

Every instruction uses #[event_cpi] and therefore expects the two trailing Anchor event accounts (event_authority PDA and program account) in addition to the accounts listed below.

InstructionArgumentsRequired accounts
initialize_protocolfee_bps: u16authority (signer, mut), fee_recipient, protocol_config (init, mut), system_program
update_protocol_configfee_bps: Option<u16>, fee_recipient: Option<Pubkey>, paused: Option<bool>authority (signer), protocol_config (mut)
create_vaultviewing_key_tag: [u8; 32], auditor_key_tag: Option<[u8; 32]>principal (signer, mut), mint, protocol_config (mut), ring_vault (init, mut), vault_escrow (mut), system_program
deposit_shieldedamount: u64, note_commitment: [u8; 32]principal (signer, mut), protocol_config, ring_vault (mut), vault_escrow (mut), system_program
withdraw_shieldedamount: u64, nullifier_hash: [u8; 32], new_merkle_root: [u8; 32]principal (signer, mut), ring_vault (mut), vault_escrow (mut), nullifier_record (init, mut), system_program
issue_mandatemandate_id: u64, per_call_cap_commitment: [u8; 32], epoch_budget_commitment: [u8; 32], per_call_cap_bound: u64, epoch_budget_bound: u64, epoch_duration_slots: u64, allowed_provider_root: [u8; 32], open_providers: bool, expiry_slot: u64, auditor_key_tag: Option<[u8; 32]>principal (signer, mut), agent, protocol_config (mut), ring_vault, mandate (init, mut), system_program
revoke_mandatenoneprincipal (signer), mandate (mut)
register_providerattestation_pubkey: Pubkey, hardware_type: u8, attestation_expiry_slot: u64, stake_lamports: u64provider_signer (signer, mut), protocol_config (mut), provider_registry (init, mut), provider_stake (mut), system_program
update_provider_attestationattestation_pubkey: Pubkey, hardware_type: u8, attestation_expiry_slot: u64provider_signer (signer), provider_registry (mut)
open_settlementsettlement_id: u64, amount: u64, request_hash: [u8; 32], amount_commitment: [u8; 32], nullifier_hash: [u8; 32], groth16_proof: [u8; 192], deadline_slot: u64agent (signer, mut), protocol_config (mut), ring_vault, mandate (mut), provider_registry (mut), settlement_escrow (init, mut), nullifier_record (init, mut), system_program
claim_settlementresponse_hash: [u8; 32], tee_signature: [u8; 64], receipt_slot: u64provider_signer (signer, mut), protocol_config (mut), fee_recipient (mut), ring_vault (mut), vault_escrow (mut), provider_registry (mut), settlement_escrow (mut), instructions_sysvar, system_program
refund_settlementnonecaller (signer), mandate (mut), provider_registry (mut), settlement_escrow (mut)

Events (emit_cpi!)

EventFields
ProtocolInitializedauthority, fee_recipient, fee_bps
ProtocolConfigUpdatedfee_recipient, fee_bps, paused
VaultCreatedvault, principal, mint, viewing_key_tag, slot
ShieldedDepositedvault, principal, note_commitment, merkle_root, note_index, slot
ShieldedWithdrawnvault, nullifier_hash, merkle_root, slot
MandateIssuedmandate, vault, principal, agent, mandate_id, expiry_slot, slot
MandateRevokedEventmandate, vault, principal, slot
ProviderRegisteredprovider, provider_pubkey, attestation_pubkey, hardware_type, staked_capacity_lamports, attestation_expiry_slot
ProviderAttestationUpdatedprovider, attestation_pubkey, hardware_type, attestation_expiry_slot
SettlementOpenedsettlement, settlement_id, vault, mandate, provider, request_hash, amount_commitment, nullifier_hash, deadline_slot, slot
SettlementClaimedsettlement, settlement_id, provider, response_hash, fee_lamports, slot
SettlementRefundedsettlement, settlement_id, vault, slot

Error codes (TovaError)

CodeNameMessage
6000InvalidFeeBpsProtocol fee bps exceeds maximum allowed (1000 bps)
6001ProtocolPausedTova protocol is currently paused
6002ZeroAmountAmount must be greater than zero
6003ArithmeticOverflowArithmetic overflow
6004InsufficientVaultBalanceInsufficient shielded vault escrow balance
6005MandateRevokedMandate has been revoked by its principal
6006MandateExpiredMandate has expired
6007InvalidMandateLimitsMandate limits are invalid
6008PerCallCapExceededSettlement amount exceeds mandate per-call ceiling
6009EpochBudgetExceededSettlement amount exceeds mandate epoch budget
6010InvalidHardwareTypeInvalid hardware attestation type
6011AttestationExpiredProvider hardware attestation has expired
6012ProviderInactiveProvider is inactive
6013ProviderCapacityExceededProvider active unsettled volume exceeds staked capacity
6014InvalidGroth16ProofGroth16 budget compliance proof failed verification
6015SettlementNotOpenSettlement escrow is not in Open state
6016SettlementExpiredSettlement deadline slot has passed
6017SettlementNotExpiredSettlement deadline slot has not passed yet
6018InvalidAttestationTEE hardware attestation signature verification failed