Design principles
The eight rules the protocol is built around, why each exists, and what each costs.
Umbra makes the same few trade-offs everywhere, and knowing them explains most of the protocol's details. Each principle below comes with the reason for it and what it costs.
1. One transaction shape for everything
The rule. Every deposit, private transfer and withdrawal is the same instruction, process_3x3x2x2, proved by the same circuit. It always spends three notes, creates three notes and has two deposit lanes and two withdrawal lanes. Unused note slots are filled with dummy notes, and unused lanes are left idle.
Why. If each kind of transaction had its own shape, the shape alone would say what happened: how many notes were spent, how many recipients were paid. One shape also means one circuit and one verifying key to audit.
What it costs. A note is a dummy exactly when its amount is zero, and a dummy still publishes a real, fresh nullifier and a real commitment, with its encrypted note sealed to a throwaway key. Every transaction pays for the full shape whatever it does. Nothing larger fits in one transaction: combining ten notes takes several. The lanes are public, so the shape hides which notes moved but not whether tokens entered or left the pool.
2. The chain supplies the facts
The rule. Anything the chain can establish for itself, the program supplies to the proof instead of trusting the prover: tree roots, the current slot, token amounts actually received, token and destination addresses, and the fee policy.
Why. A value the prover supplies is a value the prover can choose.
What it costs. The proof has one public input, a hash of every public value, and the program recomputes that hash from its own accounts. A proof names each root by a sequence number, and the program looks the root up in its own history; once a root ages out of that history the proof has to be made again. The slot a proof names must not be in the future or older than the proof-age window, which governance sets between 300 and 216,000 slots. Deposits are credited at the measured increase in the pool token account, so a token that charges a transfer fee is credited with what actually arrived.
3. Private inside, accountable at the edges
The rule. Movement inside the pool is private. The screener checks every transaction's submitter and the public parties named by tokens entering or leaving the pool before it co-signs.
Why. At the edges tokens touch public accounts anyway, so that is where checks have something to look at without looking inside the pool.
What it costs. A deposit reveals its depositor, source token account, token and amount; a withdrawal reveals its destination, token and amount, but not who withdrew, since it is relayed and names no notes. The screener checks those public parties and the bound submitter of every value transaction, including a Private Send with no public lanes or relayer tip. For a relayed transaction it screens the relayer's wallet without learning the private recipient. Deposits are attributable, because the platform wallet that deposits is publicly bound to your main wallet and your identity commitment. See screening.
4. Attesters can refuse, never take
The rule. The combined signature of the six attesters is necessary for a value transaction and never enough on its own.
Why. Each attester checks something the chain cannot: a viewing-key share, a screening result, a fee opening, the encrypted notes. Giving them a veto without custody limits what a compromised or dishonest attester can do.
What it costs. Every value transaction also needs a valid transaction proof, which fixes the amounts, owners and destinations. The attesters sign a digest of the transaction's contents and of every account it names, the submitter's included, so their signatures cannot be reused on a different transaction. The pool token accounts belong to a program-derived address, and no attester key can move them. The flip side is that the combined signature is a plain sum of six keys with no threshold, so any one attester can halt every value transaction by not signing; principle 7 is the answer to that. Refusing is not the only power attesters have: the screener sees the public parties it screens and the fee enclave sees per-token fee totals.
5. One signature is the whole account
The rule. In Umbra's clients, every key you hold is derived from one signature: your main wallet's Ed25519 signature over a fixed, versioned Umbra message. This is the standard Umbra's SDKs and client interfaces follow; the protocol does not enforce it. The pool checks proofs against your identity commitment, not how the keys behind it were made, so other clients can set up accounts their own way.
Why. There is nothing extra to back up. Ed25519 signatures are deterministic (RFC 8032), so the same wallet signing the same message produces the same bytes on any device, and the account follows.
What it costs. Recovery is signing again. Whoever obtains that signature has your account permanently: they can spend, decrypt your notes and read your history, and the keys cannot be rotated. A wallet that wraps the message before signing, as some hardware wallets do, is refused, because the signature is checked over the exact message before any key is derived. A new version of the message would be a new account. See the account signature.
6. Post-quantum where data lives long
The rule. Anything recorded now that could be decrypted later is encrypted with post-quantum primitives. Proofs and signatures, which only have to be unforgeable, use classical elliptic-curve primitives, most of them on BN254.
Why. Confidentiality cannot be added after the fact: an encrypted note stored today can be attacked by whatever computers exist decades from now. Unforgeability can be replaced before the threat arrives.
What it costs. Notes are encrypted with ML-KEM-768 and AES-256-GCM, with no classical key exchange alongside. Viewing-key shares travel to guardian nodes under ML-KEM-1024 combined with X25519, and to the fee enclave under ML-KEM-768 combined with X25519. Groth16 proofs, the BLS attester signature, zone signatures and wallet signatures are not post-quantum: an attacker with a large enough quantum computer could forge them from that point on. They would have to be replaced before such an attacker exists. See security levels.
7. Always a way out
The rule. A note can leave the pool with nothing but a proof.
Why. Every value transaction needs all six attesters, so an outage or a refusal must not be able to lock funds in.
What it costs. The escape hatch spends one note per exit, to any public destination the owner chooses. It needs no attester, no screener, no zone signature and no token allowlist entry. In exchange it discloses that note's fields on chain, and the program charges a fee at the withdrawal rate. It is not private. See escape hatch.
8. Proven where it can be, honest where it is not
The rule. What can be machine-checked is; what cannot is written down as an assumption or a gap.
Why. A soundness bug in a program or circuit cannot be undone once value is in the pool.
What it costs. Lean libraries model the circuits and several programs, and Kani model-checks the nullifier staging buffer (which the code calls the turnstile), the pending set inside it and the Merkle tree code. The Lean circuit models are written by hand. That they match the Circom source is an axiom, not a theorem, and Poseidon is assumed injective. The escape-hatch model has not kept pace with every change to its circuit. Formal verification and known risks list these limits in full.
Related
Last updated