> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Learn how wallets, RPCs, and Solana programs interact with Solana Privacy Rings.

> [tab] Permissionless Confidential Ring
>
> ```mermaid theme={"system"}
> %%{init: {
>   'theme': 'base',
>   'themeVariables': {
>     'primaryColor': '#FFFFFF',
>     'primaryTextColor': '#737373',
>     'primaryBorderColor': '#9CA3AF',
>     'lineColor': '#FF6B35',
>     'secondaryColor': '#F5F5F5',
>     'tertiaryColor': '#FFFFFF',
>     'clusterBkg': '#FF6B350A',
>     'clusterBorder': '#9CA3AF',
>     'edgeLabelBackground': '#FFFFFF'
>   }
> }}%%
> flowchart LR
>     Users["Users"]
>
>     subgraph RPC["RPC"]
>         direction TB
>         Indexer["Photon Indexer"]
>         Prover["Prover"]
>         TransactionRPC["Transaction RPC"]
>     end
>
>     subgraph Solana["Solana"]
>         direction LR
>         Swap["ZK Swap Program"]
>         subgraph State[" "]
>             direction TB
>             SPP["SPP<br/>Solana Privacy Program"]
>             Pools["SPL interface"]
>             Trees["State Merkle tree account"]
>         end
>         Swap -->|CPI| SPP
>     end
>
>     Forester["Forester"]
>
>     Users <-.->|Fetch encrypted UTXOs| Indexer
>     Users <-.->|Fetch proofs| Prover
>     Users -->|Send transaction| TransactionRPC
>     TransactionRPC -->|Confidential transfer| SPP
>     TransactionRPC --> Swap
>     Forester --> Trees
>
>     style State fill:none,stroke:none
> ```

> [tab] Custom Confidential Ring
>
> ```mermaid theme={"system"}
> %%{init: {
>   'theme': 'base',
>   'themeVariables': {
>     'primaryColor': '#FFFFFF',
>     'primaryTextColor': '#737373',
>     'primaryBorderColor': '#9CA3AF',
>     'lineColor': '#FF6B35',
>     'secondaryColor': '#F5F5F5',
>     'tertiaryColor': '#FFFFFF',
>     'clusterBkg': '#FF6B350A',
>     'clusterBorder': '#9CA3AF',
>     'edgeLabelBackground': '#FFFFFF'
>   }
> }}%%
> flowchart LR
>     Users["Users"]
>
>     subgraph RPC["RPC"]
>         direction TB
>         Indexer["Photon Indexer"]
>         RingRPC["Ring RPC with auditor · optional"]
>         Prover["Prover"]
>         TransactionRPC["Transaction RPC"]
>     end
>
>     subgraph Solana["Solana"]
>         direction LR
>         Swap["ZK Swap Program"]
>         Ring1["Custom Ring Program 1"]
>         RingN["Custom Ring Program N"]
>         subgraph State[" "]
>             direction TB
>             SPP["SPP<br/>Solana Privacy Program"]
>             Pools["SPL interface"]
>             Trees["State Merkle tree account"]
>         end
>         Swap -->|CPI| Ring1
>         Ring1 -->|CPI| SPP
>         RingN -->|CPI| SPP
>     end
>
>     Forester["Forester"]
>
>     Users <-.->|Fetch encrypted UTXOs| Indexer
>     Users <-.->|Fetch decrypted UTXOs| RingRPC
>     Users <-.->|Fetch proofs| Prover
>     Users -->|Send transaction| TransactionRPC
>     TransactionRPC -->|Confidential transfer| Ring1
>     TransactionRPC --> RingN
>     TransactionRPC --> Swap
>     Forester --> Trees
>
>     style State fill:none,stroke:none
> ```

> [tab] Custom Anonymous Ring
>
> ```mermaid theme={"system"}
> %%{init: {
>   'theme': 'base',
>   'themeVariables': {
>     'primaryColor': '#FFFFFF',
>     'primaryTextColor': '#737373',
>     'primaryBorderColor': '#9CA3AF',
>     'lineColor': '#FF6B35',
>     'secondaryColor': '#F5F5F5',
>     'tertiaryColor': '#FFFFFF',
>     'clusterBkg': '#FF6B350A',
>     'clusterBorder': '#9CA3AF',
>     'edgeLabelBackground': '#FFFFFF'
>   }
> }}%%
> flowchart LR
>     Users["Users"]
>
>     subgraph RPC["RPC"]
>         direction TB
>         RingRPC["Ring RPC with auditor"]
>         Prover["Prover"]
>         TransactionRPC["Transaction RPC<br/>Relayer for anonymous transactions"]
>     end
>
>     subgraph Solana["Solana"]
>         direction LR
>         Swap["ZK Swap Program"]
>         Ring1["Custom Ring Program 1"]
>         RingN["Custom Ring Program N"]
>         subgraph State[" "]
>             direction TB
>             SPP["SPP<br/>Solana Privacy Program"]
>             Pools["SPL interface"]
>             Trees["State Merkle tree account"]
>         end
>         Swap -->|CPI| Ring1
>         Ring1 -->|CPI| SPP
>         RingN -->|CPI| SPP
>     end
>
>     Forester["Forester"]
>
>     Users <-.->|Fetch decrypted UTXOs| RingRPC
>     Users <-.->|Fetch proofs| Prover
>     Users -->|Send transaction| TransactionRPC
>     TransactionRPC -->|Relayed anonymous transaction| Ring1
>     TransactionRPC --> RingN
>     TransactionRPC --> Swap
>     Forester --> Trees
>
>     style State fill:none,stroke:none
> ```

## Private Wallet and User

Users hold their encrypted balance in a Private Wallet and sign private transactions with their existing Solana Ed25519 key. A private wallet integration adds a shielded keypair to your key management. You can [integrate it yourself](https://www.helius.dev/docs/privacy/integration/wallet.md) or use the [Embedded Private Wallet](https://www.helius.dev/docs/privacy/integration/embedded-wallet.md).

## Private Transactions

Private transfers are normal Solana transactions. The Solana runtime verifies the signatures and invokes the Solana Privacy Program, which verifies the ZK proof without revealing the encrypted state.

A typical confidential transfer consumes 1,279 bytes, well within v1’s 4,096-byte limit.

> [accordion] Example Confidential Transfer
>
> | Component | Bytes |
> | - | -: |
> | Groth16 proof | 192 |
> | Other privacy instruction data: ciphertexts, commitments, nullifiers, keys and metadata | 769 |
> | Six account addresses × 32 bytes | 192 |
> | One Ed25519 signature | 64 |
> | Recent blockhash | 32 |
> | Version, message header, config mask and counts | 10 |
> | Compute-unit and loaded-account-data limits | 8 |
> | Instruction header | 4 |
> | Eight instruction account indices | 8 |
> | **Total** | **1,279** |
>
> > [!NOTE]
> >
> > For the spec’s 2-input, 4-output confidential transfer example.
> > View source code: [Spec](https://github.com/helius-labs/zolana/blob/ded44879b3df35482d2871bc1d0f32f2d1be2879/docs/spec.md#transaction-size) · [xtask/src/main.rs](https://github.com/helius-labs/zolana/blob/ded44879b3df35482d2871bc1d0f32f2d1be2879/xtask/src/main.rs#L474)
> >
> > See the [Solana v1 transaction layout](https://solana.com/docs/core/transactions/versioned-transactions#v1-wire-layout).

## RPC

A single Helius RPC URL (https\://devnet.helius-rpc.com/?api-key=\\\<API\_KEY\\> or https\://mainnet.helius-rpc.com/?api-key=\\\<API\_KEY\\>) makes the Solana RPC, indexer, and a remote prover available.

* **Solana RPC** – Returns the public balance and submits transactions to the Solana network.

* **Indexer** – The indexer serves the encrypted state a wallet needs to read balances and build private transactions; anyone can also run their own indexer permissionlessly as a fallback.

* **Prover** – Zero-knowledge proofs can be generated locally or by a prover server in milliseconds, depending on the transaction and hardware. Helius uses GPU proving.

For custom Rings, optional features include an optional Ring RPC to serve decrypted balances and history using a shared viewing key or a configured Ring auditor key. Additionally, anonymous transactions use a relayer so the user does not appear as the transaction fee payer.

## Privacy and Solana Programs

The Solana Privacy Program (SPP) is the main program that verifies and executes all private state transitions. Custom Ring programs and ZK Solana programs add compliance or application logic, then invoke SPP to update private state.

Other Solana programs can interact with these programs through CPI in the same transaction, within Solana’s transaction limits, such as the CPI depth limit of 5.

> [accordion] ZK Program Transaction Flow
>
> > [tab] Permissionless Ring
> >
> > > [tab] ZK Program alone
> > >
> > > ```mermaid theme={"system"}
> > > %%{init: {
> > >   'theme': 'base',
> > >   'themeVariables': {
> > >     'lineColor':           '#FF6B35',
> > >     'primaryTextColor':    '#737373',
> > >     'primaryBorderColor':  '#9CA3AF',
> > >     'actorBkg':            '#FFFFFF',
> > >     'actorBorder':         '#9CA3AF',
> > >     'actorTextColor':      '#737373',
> > >     'signalColor':         '#FF6B35',
> > >     'signalTextColor':     '#737373',
> > >     'labelBoxBkgColor':    '#FF6B351F',
> > >     'labelBoxBorderColor': '#FF6B35',
> > >     'noteBkgColor':        '#F5F5F5',
> > >     'noteTextColor':       '#737373',
> > >     'noteBorderColor':     '#9CA3AF'
> > >   }
> > > }}%%
> > > sequenceDiagram
> > >     box Offchain
> > >     participant Client
> > >     end
> > >     box Onchain
> > >     participant Runtime as Solana Runtime
> > >     participant ZK as ZK Solana Program
> > >     participant SPP as Solana Privacy Program
> > >     end
> > >
> > >     Client->>Runtime: Sign and send transaction
> > >     Note over Runtime: Check signatures
> > >     Runtime->>ZK: invoke
> > >     Note over ZK: Verify proof for ZK program logic
> > >     ZK->>SPP: CPI
> > >     Note over SPP: Verify proof for private state transition
> > >     Note over SPP: Update private state<br/>(nullify input UTXOs, create output UTXOs)
> > >     Note over ZK: Update Solana accounts (optional)
> > >
> > > ```
> >
> > > [tab] ZK Program and additional Solana Program
> > >
> > > ```mermaid theme={"system"}
> > > %%{init: {
> > >   'theme': 'base',
> > >   'themeVariables': {
> > >     'lineColor':           '#FF6B35',
> > >     'primaryTextColor':    '#737373',
> > >     'primaryBorderColor':  '#9CA3AF',
> > >     'actorBkg':            '#FFFFFF',
> > >     'actorBorder':         '#9CA3AF',
> > >     'actorTextColor':      '#737373',
> > >     'signalColor':         '#FF6B35',
> > >     'signalTextColor':     '#737373',
> > >     'labelBoxBkgColor':    '#FF6B351F',
> > >     'labelBoxBorderColor': '#FF6B35',
> > >     'noteBkgColor':        '#F5F5F5',
> > >     'noteTextColor':       '#737373',
> > >     'noteBorderColor':     '#9CA3AF'
> > >   }
> > > }}%%
> > > sequenceDiagram
> > >     box Offchain
> > >     participant Client
> > >     end
> > >     box Onchain
> > >     participant Runtime as Solana Runtime
> > >     participant ZK as ZK Solana Program
> > >     participant SPP as Solana Privacy Program
> > >     participant Program as Solana Program
> > >     end
> > >
> > >     Client->>Runtime: Sign and send transaction
> > >     Note over Runtime: Check signatures
> > >     Runtime->>ZK: invoke
> > >     Note over ZK: Verify proof for ZK program logic
> > >     ZK->>SPP: CPI
> > >     Note over SPP: Verify proof for private state transition
> > >     Note over SPP: Update private state<br/>(nullify input UTXOs, create output UTXOs)
> > >     ZK->>Program: CPI
> > >     Note over Program: Update Solana accounts
> > >
> > > ```
>
> > [tab] Custom Rings
> >
> > > [tab] ZK Program alone
> > >
> > > ```mermaid theme={"system"}
> > > %%{init: {
> > >   'theme': 'base',
> > >   'themeVariables': {
> > >     'lineColor':           '#FF6B35',
> > >     'primaryTextColor':    '#737373',
> > >     'primaryBorderColor':  '#9CA3AF',
> > >     'actorBkg':            '#FFFFFF',
> > >     'actorBorder':         '#9CA3AF',
> > >     'actorTextColor':      '#737373',
> > >     'signalColor':         '#FF6B35',
> > >     'signalTextColor':     '#737373',
> > >     'labelBoxBkgColor':    '#FF6B351F',
> > >     'labelBoxBorderColor': '#FF6B35',
> > >     'noteBkgColor':        '#F5F5F5',
> > >     'noteTextColor':       '#737373',
> > >     'noteBorderColor':     '#9CA3AF'
> > >   }
> > > }}%%
> > > sequenceDiagram
> > >     box Offchain
> > >     participant Client
> > >     end
> > >     box Onchain
> > >     participant Runtime as Solana Runtime
> > >     participant ZK as ZK Solana Program
> > >     participant Ring as Custom Ring Program
> > >     participant SPP as Solana Privacy Program
> > >     end
> > >
> > >     Client->>Runtime: Sign and send transaction
> > >     Note over Runtime: Check signatures
> > >     Runtime->>ZK: invoke
> > >     Note over ZK: Verify proof for ZK program logic
> > >     ZK->>Ring: CPI
> > >     Note over Ring: Verify proof for custom compliance logic
> > >     Ring->>SPP: CPI
> > >     Note over SPP: Verify proof for private state transition
> > >     Note over SPP: Update private state<br/>(nullify input UTXOs, create output UTXOs)
> > >     Note over ZK: Update Solana accounts (optional)
> > >
> > > ```
> >
> > > [tab] ZK Program and additional Solana Program
> > >
> > > ```mermaid theme={"system"}
> > > %%{init: {
> > >   'theme': 'base',
> > >   'themeVariables': {
> > >     'lineColor':           '#FF6B35',
> > >     'primaryTextColor':    '#737373',
> > >     'primaryBorderColor':  '#9CA3AF',
> > >     'actorBkg':            '#FFFFFF',
> > >     'actorBorder':         '#9CA3AF',
> > >     'actorTextColor':      '#737373',
> > >     'signalColor':         '#FF6B35',
> > >     'signalTextColor':     '#737373',
> > >     'labelBoxBkgColor':    '#FF6B351F',
> > >     'labelBoxBorderColor': '#FF6B35',
> > >     'noteBkgColor':        '#F5F5F5',
> > >     'noteTextColor':       '#737373',
> > >     'noteBorderColor':     '#9CA3AF'
> > >   }
> > > }}%%
> > > sequenceDiagram
> > >     box Offchain
> > >     participant Client
> > >     end
> > >     box Onchain
> > >     participant Runtime as Solana Runtime
> > >     participant ZK as ZK Solana Program
> > >     participant Ring as Custom Ring Program
> > >     participant SPP as Solana Privacy Program
> > >     participant Program as Solana Program
> > >     end
> > >
> > >     Client->>Runtime: Sign and send transaction
> > >     Note over Runtime: Check signatures
> > >     Runtime->>ZK: invoke
> > >     Note over ZK: Verify proof for ZK program logic
> > >     ZK->>Ring: CPI
> > >     Note over Ring: Verify proof for custom compliance logic
> > >     Ring->>SPP: CPI
> > >     Note over SPP: Verify proof for private state transition
> > >     Note over SPP: Update private state<br/>(nullify input UTXOs, create output UTXOs)
> > >     ZK->>Program: CPI
> > >     Note over Program: Update Solana accounts
> > >
> > > ```

### Solana Privacy Program (SPP)

The Solana Privacy Program verifies zero-knowledge proofs and updates private state. Use it to deposit tokens, transfer private balances, and withdraw tokens to public accounts.

Other programs invoke SPP through CPI to execute private state transitions.

### Custom Ring Program

A Custom Ring program defines transfer permissions and any additional authorities, similar to Token-2022. Use it to configure auditors, require a co-signer, or allow an authority to freeze balances.

It verifies a ZK proof to enforce its custom compliance logic, then invokes SPP to update private state.

### ZK Solana Program

Zero-knowledge (ZK) Solana programs enable private escrows in Solana programs to enforce application logic over private balances. You can build private swaps, staking, lending, and more with ZK Solana programs. For example, a confidential swap can enforce the agreed amounts and price without making them public.

The program verifies a ZK proof of its application logic, then invokes SPP, directly or through a Custom Ring program, to update private state.

## State Merkle Tree and Forester

The Default Ring and all Custom Rings store private state in a state Merkle tree account, which is maintained by a Forester node.
Tree accounts commit to private state without storing it in separate Solana accounts.

Therefore, you read balances and transaction history with dedicated indexer RPC methods, such as `getShieldedTransactionsByTags`, instead of Solana account methods like `getAccountInfo`. See [Read a Private Balance](https://www.helius.dev/docs/privacy/guides/read-balance.md) and [Read Private Transaction History](https://www.helius.dev/docs/privacy/guides/read-history.md).

### Throughput

The tree is stored in one writable Solana account.
Private transfers that write to this account share Solana's 12 million CU per-account write-lock limit per block.
Different UTXOs can be spent independently, but transactions writing to the same tree still share Solana account locks and compute limits.

A confidential transfer consumes approximately 140,000 CU in the [instruction benchmark](https://github.com/helius-labs/zolana/blob/ded44879b3df35482d2871bc1d0f32f2d1be2879/program-tests/shielded-pool/CU_BENCHMARK.md#17-transfer-eddsa-2x2).
One tree therefore supports approximately 86 private transfers per block, or approximately 215 transactions per second at current Solana block times of about 400 milliseconds.

The protocol can add more trees to increase throughput.
Each tree is a separate writable account with its own per-account compute budget, so transactions on different trees do not compete for the same write-lock budget.

## SPL Interface

The SPL interface enables interoperability between publicly and privately held tokens. It is an escrow per mint, which can be created permissionlessly
but must be created once per mint.

* At deposit to a private balance of SOL and SPL assets, an interface PDA owned by the Solana Privacy Program escrows tokens and creates UTXOs with the user as owner.
* At withdrawal to a public balance, existing UTXOs are marked as spent, and tokens are released to the Solana token accounts.

For mints that do not have an interface PDA yet, the first deposit can include an instruction to create the interface PDA in the same transaction.

```mermaid theme={"system"}
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#FFFFFF',
    'primaryTextColor': '#737373',
    'primaryBorderColor': '#9CA3AF',
    'lineColor': '#FF6B35',
    'edgeLabelBackground': '#FFFFFF'
  }
}}%%
flowchart LR
    GetAccount["Get account"] --> Exists{"Interface PDA exists?"}
    Exists -->|Yes| Deposit["Deposit to private balance"]
    Exists -->|No| Create["Create interface PDA<br/>and token account"]
    Create --> Deposit
```

## Learn More

> [card] [Overview](https://www.helius.dev/docs/privacy/concepts/overview.md)
>
> Rings, privacy guarantees, and transaction flow.

> [card] [Private State and UTXOs](https://www.helius.dev/docs/privacy/concepts/utxo.md)
>
> How private balances are stored and spent.

> [card] [Encryption and Privacy Guarantees](https://www.helius.dev/docs/privacy/concepts/encryption.md)
>
> How assets are encrypted and the role of the shielded keypair.

> [card] [Custom Enterprise Rings](https://www.helius.dev/docs/privacy/integration/enterprise.md)
>
> Learn how to configure a custom Ring.

## Didn't find what you were looking for?

Reach out! [Telegram](https://t.me/tilo_light) | [E-Mail](mailto:sales@helius.xyz) | [Contact](https://www.helius.dev/contact)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.