Encrypted Balances & UTXOs
How ShieldedVault PDAs, CommitmentNote UTXOs, NullifierRecord accounts, and Ring commitment roots work in mera_core.
Mera represents shielded balances as UTXO-style CommitmentNote accounts inside per-Ring, per-mint ShieldedVault PDAs. Instead of mutating a single public token balance per wallet on every trade, each deposit, trade output, or order refund creates a discrete commitment note, and spending a note consumes it with a unique nullifier.
Core on-chain objects
| Account | PDA seeds | Purpose |
|---|---|---|
ShieldedVault | ["vault", ring_pubkey, mint_pubkey] | Holds the authority for the Ring's SPL/Token-2022 vault_token_account and tracks total_shielded, total_locked_escrow, and total_fees_collected |
CommitmentNote | ["note", ring_pubkey, commitment_bytes] | Stores one encrypted UTXO note (ring, mint, owner, commitment, amount, spent, created_slot) |
NullifierRecord | ["nullifier", ring_pubkey, nullifier_bytes] | Permanent spent marker preventing any commitment note from being consumed more than once |
PrivateEscrowOrder | ["escrow", ring_pubkey, maker_pubkey, order_id_hash] | Holds a spent input note's value in escrow for a hidden-size limit order until fill, cancel, or expiry |
Commitment and nullifier derivation
Commitments and nullifiers are 32-byte domain-separated SHA-256 digests matching Solana Privacy Rings' commitment interface:
commitment = SHA-256("mera:commitment:v1:" || owner || ":" || mint || ":" || amount || ":" || salt_16)
nullifier = SHA-256("mera:nullifier:v1:" || commitment_hex || ":" || owner || ":" || salt_16)
size_commitment = SHA-256("mera:size:v1:" || size || ":" || limit_price_6dp || ":" || salt_16)Each commitment uses a fresh 16-byte random salt so two deposits of identical size by the same wallet produce distinct 32-byte commitments and distinct CommitmentNote PDAs.
Ring commitment root
Every RingConfig maintains a rolling 32-byte commitment_root and a monotonic commitment_count:
- On
deposit_shieldedorcancel_hidden_order:commitment_root = SHA-256(commitment_root || new_commitment)andcommitment_count += 1. - On
fill_hidden_order,settle_confidential_swap, orsettle_sealed_rfq:commitment_root = SHA-256(commitment_root || out_commitment_1 || out_commitment_2)andcommitment_count += 2.
This rolling accumulator binds every note created in a Ring into a single verifiable on-chain root.
How note selection works
Because shielded balances are stored as discrete UTXO notes, GET /v1/balances/:wallet returns both the aggregate shieldedBalance per mint and the individual notes array. When you submit a withdrawal, swap, hidden order, or RFQ acceptance, the transaction builder selects the smallest unspent note whose amount is greater than or equal to the required input (pickBestNote).
- If you hold a single
10 SOLnote and execute a2 SOLswap, the transaction spends the note on chain; for withdrawals you can also pass an explicitnoteIdinPOST /v1/shield/withdraw/build. - If you hold several small notes that sum to
10 SOLbut no single note covers6 SOL, the builder returnsINSUFFICIENT_SHIELDED_BALANCE(400) until a single note covers the amount.
Localnet verifier vs mainnet Privacy Rings switchover
In this build, mera_core verifies commitments, nullifiers, and vault solvency deterministically using SHA-256 and Ed25519 inside the program with real SPL and wrapped-SOL token transfers. On mainnet switchover (Build 2 on Mera's roadmap), mera_core invokes Helius Solana Privacy Rings' production verifier program via CPI so existing Solana Privacy Rings balances compose directly into Mera without unshielding.