Private State and UTXOs

A private balance is stored in UTXOs (unspent transaction outputs). You can think of UTXOs as private SPL token accounts, with two core differences:

1. A UTXO is not a Solana account, so it needs no rent-exemption.
2. Its balance is encrypted onchain.

The UTXO data layout is similar to SPL token accounts:

• Owner – Solana keypair, PDA, or P-256 key.
• Asset – the mint (SOL, SPL or Token-2022).
• Amount – the number of units of asset, in its smallest unit.
• Data – a UTXO can store arbitrary data, for example the owner of escrowed tokens.
• Program and policy data – optional configured Ring compliance.

View Solana token account

• Diagram
• Code

pub struct Account {
    /// The mint associated with this account
    pub mint: Pubkey,
    /// The owner of this account.
    pub owner: Pubkey,
    /// The amount of tokens this account holds.
    pub amount: u64,
    /// If `delegate` is `Some` then `delegated_amount` represents
    /// the amount authorized by the delegate
    pub delegate: COption<Pubkey>,
    /// The account's state
    pub state: AccountState,
    /// If is_native.is_some, this is a native token, and the value logs the
    /// rent-exempt reserve. An Account is required to be rent-exempt, so
    /// the value is used by the Processor to ensure that wrapped SOL
    /// accounts do not drop below this threshold.
    pub is_native: COption<u64>,
    /// The amount delegated
    pub delegated_amount: u64,
    /// Optional authority to close the account.
    pub close_authority: COption<Pubkey>,
}

​

Private Balance

The private balance is the sum of all UTXOs of one asset owned by a private wallet. The wallet displays one balance, regardless of whether a private balance consists of one, or multiple UTXOs. A private transfer can spend several UTXOs at once.

​

Private Transfer

Private transfers with UTXOs work differently from public transfers with SPL token accounts:

• A transfer from an SPL token account updates the amount.
• A private transfer with UTXOs does not update the amount of a UTXO. Instead, private transfers spend existing UTXOs and create new UTXOs for the recipient and for the sender’s remaining balance.

Still for the user, public transfer with Solana token accounts and private transfers with UTXOs feel similar. For example, Alice has 50 USDC and sends Bob 35 USDC.

• With SPL token accounts, Alice’s amount decreases from 50 to 15, and Bob’s increases by 35.
• With UTXOs, Alice holds one UTXO for 50 USDC. The transaction spends the existing UTXO and creates two new UTXOs: one with 35 USDC for Bob and one with 15 USDC for Alice.

​

UTXO Selection

For private transfers, the SDK selects unspent UTXOs that cover the amount you want to transfer. The UTXO selection algorithm spends as few UTXOs as possible per transfer:

1. The SDK filters your UTXOs by the asset being sent and sorts them by amount.
2. The SDK selects as many UTXOs as necessary to cover the transfer amount. It selects the largest UTXOs first until the transfer amount is covered.

For example, Alice sends Bob 80 USDC. Her three largest UTXOs are enough to cover the transfer: Fewer UTXOs keep the transaction small. Each spent UTXO adds 66 bytes for a nullifier account, which marks the UTXO as spent. The account prevents the UTXO from being spent again. Example private transfers without additional data, or other instructions:

​

Transaction Variants

Every private transfer uses a transaction variant: a fixed number of slots for UTXOs to spend and new UTXOs to create. Variants range from 1 to 36 spent UTXOs, and each variant has its own ZK circuit. The circuit proves that the spent UTXOs are valid and that the new UTXOs hold the same total amount. If a transfer needs more than 36 UTXOs, merge them first. The SDK picks a variant that fits the transfer and fills unused slots with dummy UTXOs. Dummy UTXOs hold no value and look like real UTXOs onchain.

Supported transaction variants

UTXOs spent	New UTXOs
1	1, 2, or 8
2	2 or 3
3	3
4	3 or 4
5	3 or 4
36	2

View source code: Spec · Supported variants

​

Merging UTXOs

Receiving many transfers without spending can fragment the private balance across many UTXOs. If a transfer needs more than 36 UTXOs, merge them first so the user can spend the entire balance in one transfer. Most users will rarely encounter a fragmented balance since one transfer can spend up to 36 UTXOs.

• A merge combines UTXOs of the same owner and asset into one UTXO with the same total value.
• A merge cannot spend funds or change the owner.
• Merging can be done under the hood without impacting UX for end users.

The number of merges needed to spend the whole balance in one transfer depends on how many UTXOs hold it: Each merge is one Solana transaction with a ZK proof and turns up to 36 UTXOs into one. Because the merge outcome is deterministic, the merge proofs and the transfer proof are generated in parallel.

​

Example Merge Instruction Usage

Your application can merge at two points:

• When syncing the private balance: on wallet unlock, private wallet open, app resume, network reconnect, stream gap, or wallet restore.
• Before a transfer: when the transfer needs more than 36 UTXOs.

Example for Merge

For example, a private wallet holds 1,296 USDC in 1,296 UTXOs after receiving 1,296 private transfers of 1 USDC. A transfer spends at most 36 UTXOs, so the wallet spends the balance in two stages:

1. 36 merge transactions run in parallel and create 36 UTXOs of 36 USDC each.
2. One 36-input transfer spends the entire 1,296 USDC balance.

View example code: sdk-tests/client/rust/optimized_merge_transfer.rs · sdk-tests/client/typescript/optimized-merge-transfer.test.ts

​

UTXO Concurrency

Users can spend private balances as soon as transactions are final. A private balance can be spent concurrently when it is split across several UTXOs. Each UTXO can be spent in a separate transaction at the same time. For example, a balance of three UTXOs of 100 USDC each can fund three transfers of up to 100 USDC at once. The wallet selects which UTXOs to spend. A single UTXO can only be spent once. For the protocol’s throughput limits, see State Merkle Tree and Forester.

​

Learn More

​

Didn’t find what you were looking for?