Reference
Anchor Program
Complete on-chain reference for tova_core: program ID, PDA seeds, accounts, instructions, emitted events, and error codes.
Program metadata
| Field | Value |
|---|---|
| Crate / module | tova_core |
| Program ID | C5K5LF7CGN5zKf7mxHxy5PYQHnvzHEui7dtkLZ1ytmb9 |
| ProtocolConfig PDA | FXsYi3agEshdEbiA499isr6tvU5abgEdnjNepZ2gNCTu |
PROOF_DOMAIN | "TOVA_GROTH16_PROOF_V1" |
RECEIPT_DOMAIN | "TOVA_TEE_RECEIPT_V1" |
MAX_FEE_BPS | 1000 (10.00% hard cap) |
| Event emission | Anchor #[event_cpi] / emit_cpi! (inner instruction tag e445a52e51cb9a1d) |
Measured open_settlement CU | 38,631 CU on localnet |
Measured claim_settlement CU | 31,967 CU on localnet |
PDA seeds
| Account / Vault | Seeds |
|---|---|
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
| Field | Type | Description |
|---|---|---|
authority | Pubkey | Admin signer authorized to update config |
fee_recipient | Pubkey | Recipient wallet receiving fee_bps on claim_settlement |
fee_bps | u16 | Protocol fee in basis points (0..=1000, default 25) |
paused | bool | Halts vault creation, deposits, mandate issuance, provider registration, and opening settlements |
vault_count | u64 | Total RingVault accounts created |
mandate_count | u64 | Total Mandate accounts issued |
provider_count | u64 | Total ProviderRegistry accounts registered |
settlement_count | u64 | Total SettlementEscrow accounts opened |
total_fees_collected | u64 | Cumulative protocol fees transferred to fee_recipient in lamports |
bump | u8 | PDA bump |
RingVault
| Field | Type | Description |
|---|---|---|
principal | Pubkey | Vault owner |
mint | Pubkey | Asset mint (So111... for SOL or any SPL mint) |
merkle_root | [u8; 32] | Rolling commitment tree root |
note_count | u64 | Total deposited notes |
viewing_key_tag | [u8; 32] | Public identifier for principal viewing key |
auditor_key_tag | Option<[u8; 32]> | Optional public identifier for read-only auditor viewing key |
escrow_balance | u64 | Available escrowed lamports tracked for this vault |
created_slot | u64 | Slot when the vault was initialized |
bump | u8 | RingVault PDA bump |
escrow_bump | u8 | vault_escrow PDA bump |
Mandate
| Field | Type | Description | ||
|---|---|---|---|---|
vault | Pubkey | Parent RingVault PDA | ||
principal | Pubkey | Vault principal authorized to revoke | ||
agent | Pubkey | Delegated agent signer authorized to open settlements | ||
mandate_id | u64 | Caller-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_bound | u64 | Maximum amount per single settlement | ||
epoch_budget_bound | u64 | Maximum cumulative amount per epoch | ||
epoch_spent | u64 | Amount spent in current_epoch_index | ||
epoch_duration_slots | u64 | Slots per epoch window | ||
current_epoch_index | u64 | Current epoch index since created_slot | ||
allowed_provider_root | [u8; 32] | Provider filter root when open_providers == false | ||
open_providers | bool | Whether any active registered provider is permitted | ||
expiry_slot | u64 | Slot after which new settlements reject | ||
active | bool | true until revoked by revoke_mandate | ||
auditor_key_tag | Option<[u8; 32]> | Optional per-mandate auditor tag | ||
created_slot | u64 | Slot when issued | ||
bump | u8 | PDA bump |
ProviderRegistry
| Field | Type | Description |
|---|---|---|
provider_pubkey | Pubkey | Provider operator wallet |
attestation_pubkey | Pubkey | Ed25519 hardware attestation key |
hardware_type | u8 | 0 (IntelTDX), 1 (AmdSevSnp), or 2 (LocalAttested) |
attestation_expiry_slot | u64 | Slot when current attestation expires |
staked_capacity_lamports | u64 | SOL locked in provider_stake, bounding concurrent unsettled volume |
active_unsettled_lamports | u64 | Sum of locked_amount across currently Open escrows |
total_settled_count | u64 | Cumulative Claimed settlements |
active | bool | Provider active flag |
bump | u8 | ProviderRegistry PDA bump |
stake_bump | u8 | provider_stake PDA bump |
SettlementEscrow
| Field | Type | Description |
|---|---|---|
settlement_id | u64 | Unique ID per mandate |
vault | Pubkey | Originating RingVault PDA |
mandate | Pubkey | Authorizing Mandate PDA |
provider | Pubkey | Target 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_amount | u64 | Escrowed amount in base units |
deadline_slot | u64 | Final slot for claim_settlement; refunds unlock after this slot |
status | u8 | 0 (Open), 1 (Claimed), 2 (Refunded) |
response_hash | [u8; 32] | Attested response hash (zeroed until Claimed) |
epoch_index | u64 | Mandate epoch index at open time |
created_slot | u64 | Slot when opened |
bump | u8 | PDA bump |
NullifierRecord
| Field | Type | Description |
|---|---|---|
vault | Pubkey | Parent RingVault PDA |
nullifier_hash | [u8; 32] | Spent nullifier bytes |
settlement | Pubkey | Associated SettlementEscrow PDA (Pubkey::default() for withdrawals) |
spent_slot | u64 | Slot when nullifier was consumed |
bump | u8 | PDA 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.
| Instruction | Arguments | Required accounts |
|---|---|---|
initialize_protocol | fee_bps: u16 | authority (signer, mut), fee_recipient, protocol_config (init, mut), system_program |
update_protocol_config | fee_bps: Option<u16>, fee_recipient: Option<Pubkey>, paused: Option<bool> | authority (signer), protocol_config (mut) |
create_vault | viewing_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_shielded | amount: u64, note_commitment: [u8; 32] | principal (signer, mut), protocol_config, ring_vault (mut), vault_escrow (mut), system_program |
withdraw_shielded | amount: 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_mandate | mandate_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_mandate | none | principal (signer), mandate (mut) |
register_provider | attestation_pubkey: Pubkey, hardware_type: u8, attestation_expiry_slot: u64, stake_lamports: u64 | provider_signer (signer, mut), protocol_config (mut), provider_registry (init, mut), provider_stake (mut), system_program |
update_provider_attestation | attestation_pubkey: Pubkey, hardware_type: u8, attestation_expiry_slot: u64 | provider_signer (signer), provider_registry (mut) |
open_settlement | settlement_id: u64, amount: u64, request_hash: [u8; 32], amount_commitment: [u8; 32], nullifier_hash: [u8; 32], groth16_proof: [u8; 192], deadline_slot: u64 | agent (signer, mut), protocol_config (mut), ring_vault, mandate (mut), provider_registry (mut), settlement_escrow (init, mut), nullifier_record (init, mut), system_program |
claim_settlement | response_hash: [u8; 32], tee_signature: [u8; 64], receipt_slot: u64 | provider_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_settlement | none | caller (signer), mandate (mut), provider_registry (mut), settlement_escrow (mut) |
Events (emit_cpi!)
| Event | Fields |
|---|---|
ProtocolInitialized | authority, fee_recipient, fee_bps |
ProtocolConfigUpdated | fee_recipient, fee_bps, paused |
VaultCreated | vault, principal, mint, viewing_key_tag, slot |
ShieldedDeposited | vault, principal, note_commitment, merkle_root, note_index, slot |
ShieldedWithdrawn | vault, nullifier_hash, merkle_root, slot |
MandateIssued | mandate, vault, principal, agent, mandate_id, expiry_slot, slot |
MandateRevokedEvent | mandate, vault, principal, slot |
ProviderRegistered | provider, provider_pubkey, attestation_pubkey, hardware_type, staked_capacity_lamports, attestation_expiry_slot |
ProviderAttestationUpdated | provider, attestation_pubkey, hardware_type, attestation_expiry_slot |
SettlementOpened | settlement, settlement_id, vault, mandate, provider, request_hash, amount_commitment, nullifier_hash, deadline_slot, slot |
SettlementClaimed | settlement, settlement_id, provider, response_hash, fee_lamports, slot |
SettlementRefunded | settlement, settlement_id, vault, slot |
Error codes (TovaError)
| Code | Name | Message |
|---|---|---|
6000 | InvalidFeeBps | Protocol fee bps exceeds maximum allowed (1000 bps) |
6001 | ProtocolPaused | Tova protocol is currently paused |
6002 | ZeroAmount | Amount must be greater than zero |
6003 | ArithmeticOverflow | Arithmetic overflow |
6004 | InsufficientVaultBalance | Insufficient shielded vault escrow balance |
6005 | MandateRevoked | Mandate has been revoked by its principal |
6006 | MandateExpired | Mandate has expired |
6007 | InvalidMandateLimits | Mandate limits are invalid |
6008 | PerCallCapExceeded | Settlement amount exceeds mandate per-call ceiling |
6009 | EpochBudgetExceeded | Settlement amount exceeds mandate epoch budget |
6010 | InvalidHardwareType | Invalid hardware attestation type |
6011 | AttestationExpired | Provider hardware attestation has expired |
6012 | ProviderInactive | Provider is inactive |
6013 | ProviderCapacityExceeded | Provider active unsettled volume exceeds staked capacity |
6014 | InvalidGroth16Proof | Groth16 budget compliance proof failed verification |
6015 | SettlementNotOpen | Settlement escrow is not in Open state |
6016 | SettlementExpired | Settlement deadline slot has passed |
6017 | SettlementNotExpired | Settlement deadline slot has not passed yet |
6018 | InvalidAttestation | TEE hardware attestation signature verification failed |