Reference
On-Chain Program Accounts & Instructions
Complete reference for kalo_protocol accounts, PDA seeds, instructions, events, and error codes on Solana.
Program identity
| Field | Value |
|---|
| Program name | kalo_protocol |
| Program ID | 7gvg3hFxPbtSkxjCoPHEXMPSen7X9H21y96JPVBbf47S |
| Framework | Anchor (#[event_cpi]) |
Fee ceiling (MAX_FEE_BPS) | 1000 (10%) |
Accounts
All byte sizes include the 8-byte Anchor account discriminator.
ProtocolConfig (99 bytes)
PDA seeds: ["protocol_config"]
| Field | Type | Description |
|---|
admin | Pubkey | Protocol administrator |
launch_wallet | Pubkey | Recipient of settled escrow fees (KALO buyback wallet) |
fee_bps | u16 | Protocol fee in basis points (0..=1000) |
ring_count | u64 | Total Privacy Rings created |
total_escrows_settled | u64 | Total SealedEscrow PDAs settled |
total_fees_collected | u64 | Cumulative base-unit fees routed to launch_wallet |
bump | u8 | PDA canonical bump |
PrivacyRing (172 bytes)
PDA seeds: ["privacy_ring", owner, ring_id.to_le_bytes()] Paired token vault PDA: ["ring_vault", privacy_ring] (SPL TokenAccount, authority = privacy_ring)
| Field | Type | Description |
|---|
owner | Pubkey | Ring sponsor |
ring_id | u64 | Sponsor-scoped Ring identifier |
mint | Pubkey | SPL or Token-2022 mint |
compliance_mode | u8 | 0 = Permissionless, 1 = Allowlisted |
has_auditor | bool | Whether an auditor key hash is committed |
auditor_key_hash | [u8; 32] | SHA-256 of auditor public key (zeroed if has_auditor == false) |
merkle_root | [u8; 32] | Rolling shielded UTXO commitment root |
commitment_count | u64 | Number of shielded deposits appended |
vault_balance | u64 | Available shielded balance in ring_vault |
created_slot | u64 | Solana slot at creation |
bump | u8 | PrivacyRing PDA bump |
vault_bump | u8 | ring_vault PDA bump |
AuthorityMandate (162 bytes)
PDA seeds: ["authority_mandate", privacy_ring, agent_pubkey, version.to_le_bytes()]
| Field | Type | Description |
|---|
ring | Pubkey | Parent PrivacyRing PDA |
owner | Pubkey | Ring sponsor |
agent_pubkey | Pubkey | Delegated agent Ed25519 key |
version | u32 | Monotonic policy version |
per_call_cap | u64 | Maximum base units per single lock_sealed_402 |
epoch_budget | u64 | Maximum base units per rolling epoch (>= per_call_cap) |
epoch_spent | u64 | Base units spent in the current epoch |
epoch_duration_sec | i64 | Epoch length in seconds (>= 60) |
epoch_start_ts | i64 | Unix timestamp when current epoch started |
category_mask | u32 | Bitmask of allowed provider categories (1..=31) |
expires_at | i64 | Unix timestamp after which locks reject |
revoked | bool | Permanent revocation flag |
bump | u8 | PDA bump |
EnclaveRegistry (127 bytes)
PDA seeds: ["enclave_registry", enclave_pubkey]
| Field | Type | Description |
|---|
authority | Pubkey | Provider operator authority |
enclave_pubkey | Pubkey | Ephemeral TEE Ed25519 signing public key |
hardware_type | u8 | 0 = IntelTDX, 1 = AmdSevSnp |
measurement_hash | [u8; 32] | Enclave image measurement digest |
attested_slot | u64 | Slot when enclave was registered |
expires_slot | u64 | Slot after which enclave is inactive |
service_category | u32 | Provider service category bit |
active | bool | Enclave active status |
bump | u8 | PDA bump |
ReputationAccumulator (97 bytes)
PDA seeds: ["reputation", enclave_pubkey]
| Field | Type | Description |
|---|
enclave_pubkey | Pubkey | Paired enclave Ed25519 key |
settled_count | u64 | Receipt-settled escrows |
disputed_count | u64 | Timed-out / refunded escrows |
flow_witness_root | [u8; 32] | Rolling SHA-256 settlement witness hash |
last_updated_slot | u64 | Most recent update slot |
bump | u8 | PDA bump |
SealedEscrow (354 bytes)
PDA seeds: ["sealed_escrow", privacy_ring, nullifier]
| Field | Type | Description |
|---|
ring | Pubkey | Funding PrivacyRing PDA |
mandate | Pubkey | Authorizing AuthorityMandate PDA |
provider_authority | Pubkey | Provider operator pubkey |
enclave_pubkey | Pubkey | Expected Ed25519 receipt signer |
nullifier | [u8; 32] | Single-use UTXO nullifier |
request_hash | [u8; 32] | SHA-256 of the HTTP 402 request body |
output_hash | [u8; 32] | SHA-256 of the response (set at settlement) |
commitment_in | [u8; 32] | Locked input commitment |
provider_commitment | [u8; 32] | Provider output commitment (set at settlement) |
fee_commitment | [u8; 32] | Protocol fee commitment (set at settlement) |
amount | u64 | Locked base units |
fee_amount | u64 | floor(amount * fee_bps / 10_000) |
timeout_slot | u64 | lock_slot + timeout_slots |
state | u8 | 0 = Locked, 1 = Settled, 2 = Refunded |
bump | u8 | PDA bump |
NullifierSet (81 bytes)
PDA seeds: ["nullifier", privacy_ring, nullifier]
| Field | Type | Description |
|---|
ring | Pubkey | Parent PrivacyRing PDA |
nullifier | [u8; 32] | Spent 32-byte nullifier |
spent_slot | u64 | Slot when nullifier was consumed |
bump | u8 | PDA bump |
Instructions
| Instruction | Arguments | Signer | Primary accounts |
|---|
initialize_protocol | fee_bps: u16 | admin | launch_wallet, protocol_config (init) |
create_ring | ring_id: u64, compliance_mode: u8, auditor_key_hash: Option<[u8; 32]> | owner | protocol_config, mint, privacy_ring (init), ring_vault (init) |
shield_deposit | amount: u64, commitment: [u8; 32], view_tag: [u8; 8] | owner | privacy_ring, owner_token_account, ring_vault, token_program |
issue_mandate | version: u32, per_call_cap: u64, epoch_budget: u64, epoch_duration_sec: i64, category_mask: u32, expires_at: i64 | owner | privacy_ring, agent_pubkey, authority_mandate (init) |
revoke_mandate | None | owner | authority_mandate |
register_enclave | hardware_type: u8, measurement_hash: [u8; 32], expires_slot: u64, service_category: u32 | authority | enclave_pubkey, enclave_registry (init), reputation_accumulator (init) |
lock_sealed_402 | nullifier: [u8; 32], request_hash: [u8; 32], commitment_in: [u8; 32], amount: u64, timeout_slots: u64 | agent | protocol_config, privacy_ring, authority_mandate, enclave_registry, nullifier_set (init), sealed_escrow (init) |
settle_with_receipt | output_hash: [u8; 32], provider_commitment: [u8; 32], fee_commitment: [u8; 32] | relayer | protocol_config, privacy_ring, ring_vault, enclave_registry, reputation_accumulator, sealed_escrow, provider_token_account, launch_wallet_token_account, instructions_sysvar, token_program |
refund_expired_escrow | None | caller | privacy_ring, reputation_accumulator, sealed_escrow |
unshield_withdraw | nullifier: [u8; 32], amount: u64 | owner | privacy_ring, ring_vault, recipient_token_account, nullifier_set (init), token_program |
claim_protocol_fees | amount: u64 | admin | protocol_config, launch_wallet |
Events (#[event_cpi])
Every instruction emits one CPI event recorded in inner instruction data:
| Event | Emitted by | Fields |
|---|
ProtocolInitializedEvent | initialize_protocol | admin, launch_wallet, fee_bps |
RingCreatedEvent | create_ring | ring, owner, mint, ring_id, compliance_mode |
ShieldDepositEvent | shield_deposit | ring, owner, commitment, view_tag, leaf_index, merkle_root |
MandateIssuedEvent | issue_mandate | mandate, ring, agent_pubkey, version, per_call_cap, epoch_budget, category_mask, expires_at |
MandateRevokedEvent | revoke_mandate | mandate, ring, agent_pubkey |
EnclaveRegisteredEvent | register_enclave | enclave_registry, enclave_pubkey, hardware_type, measurement_hash, attested_slot, expires_slot |
EscrowLockedEvent | lock_sealed_402 | escrow, ring, mandate, enclave_pubkey, nullifier, request_hash, commitment_in, timeout_slot |
EscrowSettledEvent | settle_with_receipt | escrow, ring, enclave_pubkey, output_hash, provider_commitment, fee_commitment, settled_count, flow_witness_root |
EscrowRefundedEvent | refund_expired_escrow | escrow, ring, enclave_pubkey, disputed_count |
UnshieldWithdrawEvent | unshield_withdraw | ring, recipient, nullifier, amount |
ProtocolFeesClaimedEvent | claim_protocol_fees | launch_wallet, amount |
Error codes (KaloError)
| Code | Name | Message |
|---|
6000 | FeeTooHigh | Protocol fee basis points exceed maximum allowed. |
6001 | InvalidComplianceMode | Invalid compliance mode. |
6002 | ZeroAmount | Amount must be greater than zero. |
6003 | MathOverflow | Arithmetic overflow. |
6004 | InvalidMandateBounds | Invalid AuthorityMandate bounds. |
6005 | MandateRevoked | AuthorityMandate has been revoked. |
6006 | MandateExpired | AuthorityMandate has expired. |
6007 | InvalidHardwareType | Invalid TEE hardware type. |
6008 | EnclaveExpired | Enclave attestation has expired. |
6009 | EnclaveInactive | Enclave is not active or has expired. |
6010 | CategoryForbidden | Service category is not permitted by this mandate. |
6011 | CapExceeded | Spend exceeds mandate per-call or epoch cap. |
6012 | InsufficientShieldedBalance | Insufficient shielded balance in PrivacyRing vault. |
6013 | InvalidTimeout | Invalid escrow timeout slot window. |
6014 | EscrowNotLocked | SealedEscrow is not in Locked state. |
6015 | EscrowNotExpired | SealedEscrow has not passed its timeout slot yet. |
6016 | InvalidTeeReceipt | Confidential Compute Ed25519 receipt verification failed. |