> For the complete documentation index, see [llms.txt](https://docs.useshadowpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useshadowpay.com/protocol-and-architecture/on-chain-architecture.md). # On-Chain Architecture ShadowPay accounts are built directly on Solana's Token-2022 program using the Confidential Transfer extension. There is no separate ShadowPay ledger. If you understand Token-2022's confidential transfer extension, you understand the core of how ShadowPay's balances and transfers work on-chain. *** ## Confidential Transfer Token Account Each user holds a standard SPL token account for USDC, configured with the Confidential Transfer extension enabled. This adds encrypted state alongside the normal public balance fields. ```rust pub struct ConfidentialTransferAccount { pub approved: bool, // Whether confidential transfers are enabled pub elgamal_pubkey: ElGamalPubkey, // Public key used to encrypt this account's balance pub pending_balance_lo: ElGamalCiphertext, // Encrypted incoming balance, low bits pub pending_balance_hi: ElGamalCiphertext, // Encrypted incoming balance, high bits pub available_balance: ElGamalCiphertext, // Encrypted spendable balance pub decryptable_available_balance: AeCiphertext, // Balance encrypted for owner's fast local decryption pub allow_confidential_credits: bool, pub allow_non_confidential_credits: bool, pub pending_balance_credit_counter: u64, pub maximum_pending_balance_credit_counter: u64, pub expected_pending_balance_credit_counter: u64, pub actual_pending_balance_credit_counter: u64, } ``` `available_balance` and the pending balance fields are ciphertexts. Only the holder of the corresponding ElGamal private key, derived from your ShadowPay account key, can decrypt them. *** ## Transfer proof data A confidential transfer instruction carries zero-knowledge proof data alongside the encrypted amount, generated client-side by the sender: ```rust pub struct TransferProofData { pub new_source_ciphertext: ElGamalCiphertext, // Sender's updated encrypted balance pub transfer_amount_ciphertext_lo: ElGamalCiphertext, // Encrypted transfer amount, low bits pub transfer_amount_ciphertext_hi: ElGamalCiphertext, // Encrypted transfer amount, high bits pub equality_proof: CiphertextCommitmentEqualityProof, // Proves ciphertext consistency pub validity_proof: BatchedGroupedCiphertext3HandlesValidityProof, // Proves amount is well-formed pub range_proof: BatchedRangeProof, // Proves amount is non-negative and in range } ``` These proofs are verified by Solana's runtime, using native zk-ElGamal-proof program syscalls, before the encrypted balances are updated. The proofs never reveal the transfer amount, only that it's valid. *** ## ShadowPay's off-chain index ShadowPay maintains an off-chain PostgreSQL index, populated via Helius webhooks, purely for UI performance and search. It stores: * Public key to `@handle` mappings * Transaction metadata that's already public on-chain: sender, receiver, timestamp, signature * Webhook subscription and delivery state It never stores decrypted balances or transfer amounts. Anything sensitive lives only encrypted on-chain and decrypted on your own device. *** ## Agent account structure An Agent account is, on-chain, just another Confidential Transfer Token Account with its own keypair. What makes it an "agent account" is entirely an off-chain construct: ShadowPay's Agent Engine associates it with a parent account and a spend policy, and gates its signing flow accordingly. The chain has no concept of a spend policy; enforcement happens before a transaction is ever built. See [Trust & Security Model](/protocol-and-architecture/trust-and-security.md) for what that means for agent security. *** ## Further reading * [Protocol Overview](/protocol-and-architecture/protocol-overview.md) * [Trust & Security Model](/protocol-and-architecture/trust-and-security.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.useshadowpay.com/protocol-and-architecture/on-chain-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.