> For the complete documentation index, see [llms.txt](https://docs.hooded.cash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hooded.cash/protocol-and-architecture/on-chain-architecture.md).

# On-Chain Architecture

HoodedCash accounts are built directly on HoodedCash's confidential token contracts, deployed on Robinhood Chain. These are an encrypted-balance ERC-20 in the Zether lineage — the EVM has no native confidential-transfer primitive, so this layer is HoodedCash's own, open-source and verified on-chain. There is no separate HoodedCash ledger. If you understand the confidential token contract, you understand the core of how HoodedCash's balances and transfers work on-chain.

***

## Confidential token account state

Each user holds a balance in the confidential token contract for USDG (bridged USDC is also supported), which stores encrypted state alongside the normal public ERC-20 fields.

```solidity
struct ConfidentialAccount {
    bool approved;                       // Whether confidential transfers are enabled
    ElGamalPubkey elGamalPubkey;         // Public key used to encrypt this account's balance
    ElGamalCiphertext pendingBalanceLo;  // Encrypted incoming balance, low bits
    ElGamalCiphertext pendingBalanceHi;  // Encrypted incoming balance, high bits
    ElGamalCiphertext availableBalance;  // Encrypted spendable balance
    AeCiphertext decryptableAvailableBalance; // Balance encrypted for owner's fast local decryption
    bool allowConfidentialCredits;
    bool allowNonConfidentialCredits;
    uint64 pendingBalanceCreditCounter;
    uint64 maximumPendingBalanceCreditCounter;
    uint64 expectedPendingBalanceCreditCounter;
    uint64 actualPendingBalanceCreditCounter;
}
```

`availableBalance` and the pending balance fields are ciphertexts. Only the holder of the corresponding ElGamal private key, derived from your HoodedCash account key, can decrypt them.

***

## Transfer proof data

A confidential transfer call carries zero-knowledge proof data alongside the encrypted amount, generated client-side by the sender and passed as calldata:

```solidity
struct TransferProofData {
    ElGamalCiphertext newSourceCiphertext;       // Sender's updated encrypted balance
    ElGamalCiphertext transferAmountCiphertextLo; // Encrypted transfer amount, low bits
    ElGamalCiphertext transferAmountCiphertextHi; // Encrypted transfer amount, high bits
    Proof equalityProof;   // Proves ciphertext consistency
    Proof validityProof;   // Proves amount is well-formed
    Proof rangeProof;      // Proves amount is non-negative and in range
}
```

These proofs are checked by HoodedCash's on-chain verifier contract — Solidity, with Arbitrum Stylus (Rust/WASM) for the verification hot path — in the same transaction, before the encrypted balances are updated. Because Robinhood Chain settles to Ethereum through the Arbitrum stack's fraud proofs, that verification is ultimately secured by Ethereum. The proofs never reveal the transfer amount, only that it's valid.

***

## HoodedCash's off-chain index

HoodedCash maintains an off-chain PostgreSQL index, populated from contract event streams, purely for UI performance and search. It stores:

* Address to `@handle` mappings
* Transaction metadata that's already public on-chain: sender, receiver, timestamp, transaction hash
* 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, an ERC-4337 smart account holding a confidential token balance, with its own signing key. What makes it an "agent account" is its validation contract: HoodedCash's Agent Engine associates it with a parent account and provisions its spend policy into the account's on-chain validation logic, so a transaction that exceeds the policy fails validation on-chain. Policy checks also run client-side before a transaction is ever built, but the on-chain constraint is what keeps the limit binding even if the client is compromised. 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.hooded.cash/protocol-and-architecture/on-chain-architecture.md?ask=<question>&goal=<endgoal>
```

`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.