Reference

On-Chain Program Accounts & Instructions

Complete reference for kalo_protocol accounts, PDA seeds, instructions, events, and error codes on Solana.

Program identity

FieldValue
Program namekalo_protocol
Program ID7gvg3hFxPbtSkxjCoPHEXMPSen7X9H21y96JPVBbf47S
FrameworkAnchor (#[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"]

FieldTypeDescription
adminPubkeyProtocol administrator
launch_walletPubkeyRecipient of settled escrow fees (KALO buyback wallet)
fee_bpsu16Protocol fee in basis points (0..=1000)
ring_countu64Total Privacy Rings created
total_escrows_settledu64Total SealedEscrow PDAs settled
total_fees_collectedu64Cumulative base-unit fees routed to launch_wallet
bumpu8PDA 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)

FieldTypeDescription
ownerPubkeyRing sponsor
ring_idu64Sponsor-scoped Ring identifier
mintPubkeySPL or Token-2022 mint
compliance_modeu80 = Permissionless, 1 = Allowlisted
has_auditorboolWhether 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_countu64Number of shielded deposits appended
vault_balanceu64Available shielded balance in ring_vault
created_slotu64Solana slot at creation
bumpu8PrivacyRing PDA bump
vault_bumpu8ring_vault PDA bump

AuthorityMandate (162 bytes)

PDA seeds: ["authority_mandate", privacy_ring, agent_pubkey, version.to_le_bytes()]

FieldTypeDescription
ringPubkeyParent PrivacyRing PDA
ownerPubkeyRing sponsor
agent_pubkeyPubkeyDelegated agent Ed25519 key
versionu32Monotonic policy version
per_call_capu64Maximum base units per single lock_sealed_402
epoch_budgetu64Maximum base units per rolling epoch (>= per_call_cap)
epoch_spentu64Base units spent in the current epoch
epoch_duration_seci64Epoch length in seconds (>= 60)
epoch_start_tsi64Unix timestamp when current epoch started
category_masku32Bitmask of allowed provider categories (1..=31)
expires_ati64Unix timestamp after which locks reject
revokedboolPermanent revocation flag
bumpu8PDA bump

EnclaveRegistry (127 bytes)

PDA seeds: ["enclave_registry", enclave_pubkey]

FieldTypeDescription
authorityPubkeyProvider operator authority
enclave_pubkeyPubkeyEphemeral TEE Ed25519 signing public key
hardware_typeu80 = IntelTDX, 1 = AmdSevSnp
measurement_hash[u8; 32]Enclave image measurement digest
attested_slotu64Slot when enclave was registered
expires_slotu64Slot after which enclave is inactive
service_categoryu32Provider service category bit
activeboolEnclave active status
bumpu8PDA bump

ReputationAccumulator (97 bytes)

PDA seeds: ["reputation", enclave_pubkey]

FieldTypeDescription
enclave_pubkeyPubkeyPaired enclave Ed25519 key
settled_countu64Receipt-settled escrows
disputed_countu64Timed-out / refunded escrows
flow_witness_root[u8; 32]Rolling SHA-256 settlement witness hash
last_updated_slotu64Most recent update slot
bumpu8PDA bump

SealedEscrow (354 bytes)

PDA seeds: ["sealed_escrow", privacy_ring, nullifier]

FieldTypeDescription
ringPubkeyFunding PrivacyRing PDA
mandatePubkeyAuthorizing AuthorityMandate PDA
provider_authorityPubkeyProvider operator pubkey
enclave_pubkeyPubkeyExpected 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)
amountu64Locked base units
fee_amountu64floor(amount * fee_bps / 10_000)
timeout_slotu64lock_slot + timeout_slots
stateu80 = Locked, 1 = Settled, 2 = Refunded
bumpu8PDA bump

NullifierSet (81 bytes)

PDA seeds: ["nullifier", privacy_ring, nullifier]

FieldTypeDescription
ringPubkeyParent PrivacyRing PDA
nullifier[u8; 32]Spent 32-byte nullifier
spent_slotu64Slot when nullifier was consumed
bumpu8PDA bump

Instructions

InstructionArgumentsSignerPrimary accounts
initialize_protocolfee_bps: u16adminlaunch_wallet, protocol_config (init)
create_ringring_id: u64, compliance_mode: u8, auditor_key_hash: Option<[u8; 32]>ownerprotocol_config, mint, privacy_ring (init), ring_vault (init)
shield_depositamount: u64, commitment: [u8; 32], view_tag: [u8; 8]ownerprivacy_ring, owner_token_account, ring_vault, token_program
issue_mandateversion: u32, per_call_cap: u64, epoch_budget: u64, epoch_duration_sec: i64, category_mask: u32, expires_at: i64ownerprivacy_ring, agent_pubkey, authority_mandate (init)
revoke_mandateNoneownerauthority_mandate
register_enclavehardware_type: u8, measurement_hash: [u8; 32], expires_slot: u64, service_category: u32authorityenclave_pubkey, enclave_registry (init), reputation_accumulator (init)
lock_sealed_402nullifier: [u8; 32], request_hash: [u8; 32], commitment_in: [u8; 32], amount: u64, timeout_slots: u64agentprotocol_config, privacy_ring, authority_mandate, enclave_registry, nullifier_set (init), sealed_escrow (init)
settle_with_receiptoutput_hash: [u8; 32], provider_commitment: [u8; 32], fee_commitment: [u8; 32]relayerprotocol_config, privacy_ring, ring_vault, enclave_registry, reputation_accumulator, sealed_escrow, provider_token_account, launch_wallet_token_account, instructions_sysvar, token_program
refund_expired_escrowNonecallerprivacy_ring, reputation_accumulator, sealed_escrow
unshield_withdrawnullifier: [u8; 32], amount: u64ownerprivacy_ring, ring_vault, recipient_token_account, nullifier_set (init), token_program
claim_protocol_feesamount: u64adminprotocol_config, launch_wallet

Events (#[event_cpi])

Every instruction emits one CPI event recorded in inner instruction data:

EventEmitted byFields
ProtocolInitializedEventinitialize_protocoladmin, launch_wallet, fee_bps
RingCreatedEventcreate_ringring, owner, mint, ring_id, compliance_mode
ShieldDepositEventshield_depositring, owner, commitment, view_tag, leaf_index, merkle_root
MandateIssuedEventissue_mandatemandate, ring, agent_pubkey, version, per_call_cap, epoch_budget, category_mask, expires_at
MandateRevokedEventrevoke_mandatemandate, ring, agent_pubkey
EnclaveRegisteredEventregister_enclaveenclave_registry, enclave_pubkey, hardware_type, measurement_hash, attested_slot, expires_slot
EscrowLockedEventlock_sealed_402escrow, ring, mandate, enclave_pubkey, nullifier, request_hash, commitment_in, timeout_slot
EscrowSettledEventsettle_with_receiptescrow, ring, enclave_pubkey, output_hash, provider_commitment, fee_commitment, settled_count, flow_witness_root
EscrowRefundedEventrefund_expired_escrowescrow, ring, enclave_pubkey, disputed_count
UnshieldWithdrawEventunshield_withdrawring, recipient, nullifier, amount
ProtocolFeesClaimedEventclaim_protocol_feeslaunch_wallet, amount

Error codes (KaloError)

CodeNameMessage
6000FeeTooHighProtocol fee basis points exceed maximum allowed.
6001InvalidComplianceModeInvalid compliance mode.
6002ZeroAmountAmount must be greater than zero.
6003MathOverflowArithmetic overflow.
6004InvalidMandateBoundsInvalid AuthorityMandate bounds.
6005MandateRevokedAuthorityMandate has been revoked.
6006MandateExpiredAuthorityMandate has expired.
6007InvalidHardwareTypeInvalid TEE hardware type.
6008EnclaveExpiredEnclave attestation has expired.
6009EnclaveInactiveEnclave is not active or has expired.
6010CategoryForbiddenService category is not permitted by this mandate.
6011CapExceededSpend exceeds mandate per-call or epoch cap.
6012InsufficientShieldedBalanceInsufficient shielded balance in PrivacyRing vault.
6013InvalidTimeoutInvalid escrow timeout slot window.
6014EscrowNotLockedSealedEscrow is not in Locked state.
6015EscrowNotExpiredSealedEscrow has not passed its timeout slot yet.
6016InvalidTeeReceiptConfidential Compute Ed25519 receipt verification failed.

Confidential commerce infrastructure for autonomous software.

Shielded treasuries, scoped mandates, and receipt-bound HTTP 402 settlement on Solana L1.

Open consoleRead the docs