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):
Mandate PDA: ["mandate", ring_vault_pubkey, mandate_id_u64_le]Policy fields
| Field | Type | Enforcement on open_settlement |
|---|---|---|
agent | Pubkey | Must match the transaction signer (has_one = agent) |
per_call_cap_bound | u64 | amount <= per_call_cap_bound, else PerCallCapExceeded |
epoch_budget_bound | u64 | epoch_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_slots | u64 | Number of Solana slots per budget window (API validates 10 to 50,000,000) |
current_epoch_index | u64 | Automatically 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_providers | bool | Allows settling with any active registered provider when true |
expiry_slot | u64 | clock.slot <= expiry_slot, else MandateExpired |
active | bool | Must be true, else MandateRevoked |
auditor_key_tag | Option<[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:
elapsed_slots = clock.slot.saturating_sub(mandate.created_slot)
epoch_index = elapsed_slots / mandate.epoch_duration_slotsWhen 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_settlementcalls under the revoked mandate fail immediately withMandateRevoked. - Existing
Openescrows created before revocation still resolve normally viaclaim_settlement(if the provider delivers a valid TEE receipt beforedeadline_slot) orrefund_settlement(afterdeadline_slot). - Calling
revoke_mandateon an already revoked mandate fails withMandateRevoked.
See Issue an Agent Mandate for step-by-step issuance and revocation instructions.