UTXO System

How funds are represented, committed, and discovered within the shielded pool.

UTXO Structure

A UTXO (Unspent Transaction Output) represents funds in the shielded pool. Unlike traditional account balances, each UTXO is a discrete unit of value with cryptographic ownership.

UTXO Fields

typescript

1class Utxo {
2amount: BN           // Value in base units (lamports, SPL base units)
3blinding: BN         // Random factor hiding the amount in the commitment
4pubkey: BN           // BN254 public key of the owner
5keypair?: Keypair    // BN254 keypair (only present if we own this UTXO)
6index: number        // Position in the Merkle tree
7mintAddress: string  // Token mint (SOL = "So1111...1112")
8version: 'v1'|'v2'  // Key derivation version
9}

ℹ️

The mintAddress field is used in the commitment hash and for UTXO filtering, but is not serialized in the current binary v2 encrypted format. Instead, it is provided by the caller from the per-token Merkle tree context during decryption — saving 32 bytes per output on-chain.

Commitment

The commitment is what goes on-chain — a Poseidon hash that hides all values while enabling ZK verification.

Commitment Formula

plaintext

commitment = Poseidon(amount, pubkey, blinding, mintAddressField)

Properties:
• Hiding: Cannot extract amount, pubkey, or blinding from the hash
• Binding: Cannot find different inputs that produce the same hash
• Verifiable: ZK circuit can prove knowledge of inputs without revealing them

ℹ️

The commitment uses the Poseidon hash function — specifically designed for efficient computation inside ZK circuits (SNARKs). Standard hashes like SHA-256 would be prohibitively expensive to prove in a circuit.

Nullifier

The nullifier prevents double-spending. When a UTXO is spent, its nullifier is published on-chain. If the same nullifier appears again, the transaction is rejected.

Nullifier Formula

plaintext

nullifier = Poseidon(commitment, index, Sign(commitment, index))

Key property: Requires the PRIVATE KEY to compute
→ Only the owner can produce a valid nullifier
→ Published on-chain when spending
→ If seen before → double-spend rejected

⚠️

Nullifiers are unlinkable to their source UTXO from an observer's perspective. An on-chain observer sees a nullifier hash but cannot determine which commitment it corresponds to — this is what breaks the deposit-to-withdrawal link.

Creation Modes

UTXOs are created differently depending on whether you're depositing for yourself or for a paylink recipient.

UTXO Creation Modes

typescript

1// SELF-DEPOSIT: Depositing for yourself
2const selfUtxo = new Utxo({
3amount: BN(1_500_000_000),   // 1.5 SOL
4keypair: myBN254Keypair,      // Full keypair (private + public)
5});
6// → Has private key → can generate nullifier → can spend
7
8// PAYLINK DEPOSIT: Depositing for a recipient
9const paylinkUtxo = new Utxo({
10amount: BN(1_500_000_000),   // 1.5 SOL
11publicKey: recipientBN254Pubkey,  // Only public key
12});
13// → No private key → can generate commitment → CANNOT spend
14// → The recipient, with their private key, can spend later

Mode	Has Private Key	Can Compute Nullifier	Can Spend
Self-deposit	Yes	Yes	Yes
Paylink deposit	No (pubkey only)	No	No (only recipient can)

UTXO Scanning

The Problem

The shielded pool contains all encrypted UTXOs from all users. To find your own, you'd need to attempt decryption on every single one. With thousands of UTXOs, this is prohibitively slow.

The Solution: Recipient ID Hash

Each encrypted note includes an 8-byte recipientIdHash — a truncated hash of the owner's public key. Before attempting expensive decryption, recipients perform a cheap byte comparison.

UTXO Scanning with Early Termination

Encrypted Output

[version][schema][recipientIdHash][payload...]

Compare recipientIdHash

SHA256(myPubKey)[0:8] vs stored[9:17]

No Match

SKIP

O(1) — 8-byte compare

~99.99% of outputs

Match

Attempt Decrypt

Expensive crypto op

Success

Found UTXO

Failure

False pos. (1/2^64)

Without Early Termination

50,000 UTXOs x decrypt = ~30s

With Early Termination

50,000 x compare + 5 x decrypt = ~0.5s

Implementation

Early Termination Check

typescript

1private shouldAttemptDecryption(encryptedBuffer: Buffer): boolean {
2const firstByte = encryptedBuffer[0];
3
4// Compact format (current): single-byte tag at position 0
5// recipientIdHash is at bytes 1-8
6if (firstByte === 0xC2 || firstByte === 0xC3) {
7  const storedHash = encryptedBuffer.subarray(1, 9);   // 8 bytes in blob
8  const myHash = this.deriveRecipientIdHash();          // 8 bytes from my key
9  return storedHash.equals(myHash);                     // Fast compare
10}
11
12// Standard format (legacy): schema version at byte 8
13// recipientIdHash is at bytes 9-17
14const schemaVersion = encryptedBuffer[8];
15if (schemaVersion === 0x02) {
16  const storedHash = encryptedBuffer.subarray(9, 17);
17  const myHash = this.deriveRecipientIdHash();
18  return storedHash.equals(myHash);
19}
20
21// Schema 0x01 (legacy) → must attempt decrypt (no hash in format)
22return true;
23}

False Positive Rate

The 8-byte hash provides 2^64 possible values. The probability of a false positive (hash collision) is approximately:

Collision Analysis

plaintext

P(false positive) = 1 / 2^64 ≈ 5.4 × 10⁻²⁰

With 50,000 UTXOs in the pool:
Expected false positives = 50,000 / 2^64 ≈ 0.0000000000000027

In practice: effectively zero false positives ever

💡

The recipientIdHash does NOT compromise privacy. An observer cannot reverse the hash to identify the recipient — it's derived from the BN254 public key which is itself unlinkable to the wallet address.

UTXO System

How funds are represented, committed, and discovered within the shielded pool.

UTXO Structure

A UTXO (Unspent Transaction Output) represents funds in the shielded pool. Unlike traditional account balances, each UTXO is a discrete unit of value with cryptographic ownership.

UTXO Fields

typescript

1class Utxo {
2amount: BN           // Value in base units (lamports, SPL base units)
3blinding: BN         // Random factor hiding the amount in the commitment
4pubkey: BN           // BN254 public key of the owner
5keypair?: Keypair    // BN254 keypair (only present if we own this UTXO)
6index: number        // Position in the Merkle tree
7mintAddress: string  // Token mint (SOL = "So1111...1112")
8version: 'v1'|'v2'  // Key derivation version
9}

ℹ️

Commitment

The commitment is what goes on-chain — a Poseidon hash that hides all values while enabling ZK verification.

Commitment Formula

plaintext

commitment = Poseidon(amount, pubkey, blinding, mintAddressField)

Properties:
• Hiding: Cannot extract amount, pubkey, or blinding from the hash
• Binding: Cannot find different inputs that produce the same hash
• Verifiable: ZK circuit can prove knowledge of inputs without revealing them

ℹ️

Nullifier

The nullifier prevents double-spending. When a UTXO is spent, its nullifier is published on-chain. If the same nullifier appears again, the transaction is rejected.

Nullifier Formula

plaintext

nullifier = Poseidon(commitment, index, Sign(commitment, index))

Key property: Requires the PRIVATE KEY to compute
→ Only the owner can produce a valid nullifier
→ Published on-chain when spending
→ If seen before → double-spend rejected

⚠️

Creation Modes

UTXOs are created differently depending on whether you're depositing for yourself or for a paylink recipient.

UTXO Creation Modes

typescript

1// SELF-DEPOSIT: Depositing for yourself
2const selfUtxo = new Utxo({
3amount: BN(1_500_000_000),   // 1.5 SOL
4keypair: myBN254Keypair,      // Full keypair (private + public)
5});
6// → Has private key → can generate nullifier → can spend
7
8// PAYLINK DEPOSIT: Depositing for a recipient
9const paylinkUtxo = new Utxo({
10amount: BN(1_500_000_000),   // 1.5 SOL
11publicKey: recipientBN254Pubkey,  // Only public key
12});
13// → No private key → can generate commitment → CANNOT spend
14// → The recipient, with their private key, can spend later

Mode	Has Private Key	Can Compute Nullifier	Can Spend
Self-deposit	Yes	Yes	Yes
Paylink deposit	No (pubkey only)	No	No (only recipient can)

UTXO Scanning

The Problem

The shielded pool contains all encrypted UTXOs from all users. To find your own, you'd need to attempt decryption on every single one. With thousands of UTXOs, this is prohibitively slow.

The Solution: Recipient ID Hash

Each encrypted note includes an 8-byte recipientIdHash — a truncated hash of the owner's public key. Before attempting expensive decryption, recipients perform a cheap byte comparison.

UTXO Scanning with Early Termination

Encrypted Output

[version][schema][recipientIdHash][payload...]

Compare recipientIdHash

SHA256(myPubKey)[0:8] vs stored[9:17]

No Match

SKIP

O(1) — 8-byte compare

~99.99% of outputs

Match

Attempt Decrypt

Expensive crypto op

Success

Found UTXO

Failure

False pos. (1/2^64)

Without Early Termination

50,000 UTXOs x decrypt = ~30s

With Early Termination

50,000 x compare + 5 x decrypt = ~0.5s

Implementation

Early Termination Check

typescript

1private shouldAttemptDecryption(encryptedBuffer: Buffer): boolean {
2const firstByte = encryptedBuffer[0];
3
4// Compact format (current): single-byte tag at position 0
5// recipientIdHash is at bytes 1-8
6if (firstByte === 0xC2 || firstByte === 0xC3) {
7  const storedHash = encryptedBuffer.subarray(1, 9);   // 8 bytes in blob
8  const myHash = this.deriveRecipientIdHash();          // 8 bytes from my key
9  return storedHash.equals(myHash);                     // Fast compare
10}
11
12// Standard format (legacy): schema version at byte 8
13// recipientIdHash is at bytes 9-17
14const schemaVersion = encryptedBuffer[8];
15if (schemaVersion === 0x02) {
16  const storedHash = encryptedBuffer.subarray(9, 17);
17  const myHash = this.deriveRecipientIdHash();
18  return storedHash.equals(myHash);
19}
20
21// Schema 0x01 (legacy) → must attempt decrypt (no hash in format)
22return true;
23}

False Positive Rate

The 8-byte hash provides 2^64 possible values. The probability of a false positive (hash collision) is approximately:

Collision Analysis

plaintext

P(false positive) = 1 / 2^64 ≈ 5.4 × 10⁻²⁰

With 50,000 UTXOs in the pool:
Expected false positives = 50,000 / 2^64 ≈ 0.0000000000000027

In practice: effectively zero false positives ever

💡

UTXO System

UTXO Structure

Commitment

Nullifier

Creation Modes

UTXO Scanning

The Problem

The Solution: Recipient ID Hash

Implementation

False Positive Rate

Further Reading

UTXO System

UTXO Structure

Commitment

Nullifier

Creation Modes

UTXO Scanning

The Problem

The Solution: Recipient ID Hash

Implementation

False Positive Rate

Further Reading