Concepts

Shielded Mandates

Revocable cryptographic spending instruments that bound autonomous agents by per-call ceiling, epoch budget, provider scope, and expiry slot.

Why mandates replace hot wallets

Handing an autonomous agent a funded Solana keypair gives that software unrestricted custody of the entire wallet balance and broadcasts every vendor and payment amount on-chain. A Shielded Mandate (Mandate) separates custody from spending authority: the principal keeps funds in a Ring Vault and delegates a bounded, revocable spending policy to an agent's signing key.

Each mandate is a PDA keyed by its parent vault and a caller-chosen mandate_id (u64 little-endian):

text
Mandate PDA: ["mandate", ring_vault_pubkey, mandate_id_u64_le]

Policy fields

FieldTypeEnforcement on open_settlement
agentPubkeyMust match the transaction signer (has_one = agent)
per_call_cap_boundu64amount <= per_call_cap_bound, else PerCallCapExceeded
epoch_budget_boundu64epoch_spent + amount <= epoch_budget_bound, else EpochBudgetExceeded
per_call_cap_commitment[u8; 32]Bound into the 192-byte Groth16 proof envelope
epoch_budget_commitment[u8; 32]Bound into the 192-byte Groth16 proof envelope
epoch_duration_slotsu64Number of Solana slots per budget window (API validates 10 to 50,000,000)
current_epoch_indexu64Automatically rolls over when (clock.slot - created_slot) / epoch_duration_slots advances
allowed_provider_root[u8; 32]Optional provider restriction hash when open_providers is false
open_providersboolAllows settling with any active registered provider when true
expiry_slotu64clock.slot <= expiry_slot, else MandateExpired
activeboolMust be true, else MandateRevoked
auditor_key_tagOption<[u8; 32]>Optional per-mandate auditor tag for scoped disclosure

Epoch rollover

Budget windows reset lazily on-chain inside open_settlement with no external crank required:

text
elapsed_slots = clock.slot.saturating_sub(mandate.created_slot)
epoch_index   = elapsed_slots / mandate.epoch_duration_slots

When epoch_index > mandate.current_epoch_index, the program sets current_epoch_index = epoch_index and resets epoch_spent = 0 before checking epoch_spent + amount <= epoch_budget_bound.

If an open settlement times out and is refunded via refund_settlement during the same epoch (mandate.current_epoch_index == escrow.epoch_index), epoch_spent is decremented by the refunded amount so failed provider calls do not consume the agent's epoch budget.

Groth16 budget-compliance proof

Every open_settlement instruction takes a 192-byte groth16_proof envelope matching Helius Solana Privacy Rings' proof format. In tova_core, the verifier binds the proof directly to the vault's current merkle_root, the amount_commitment, the nullifier_hash, the Mandate PDA, the per_call_cap_commitment, and the epoch_budget_commitment. An invalid or mismatched proof fails with InvalidGroth16Proof.

Instant revocation semantics

The principal can call revoke_mandate at any slot. Revocation sets mandate.active = false and emits MandateRevokedEvent:

  • New open_settlement calls under the revoked mandate fail immediately with MandateRevoked.
  • Existing Open escrows created before revocation still resolve normally via claim_settlement (if the provider delivers a valid TEE receipt before deadline_slot) or refund_settlement (after deadline_slot).
  • Calling revoke_mandate on an already revoked mandate fails with MandateRevoked.

See Issue an Agent Mandate for step-by-step issuance and revocation instructions.