# Umbra protocol documentation

> How the Umbra protocol works: the private balance, the proofs behind it, the network that attests to it, and what each operation makes public.

Every page is also served as Markdown at its URL with `.md` appended. The full text of every page is at https://docs.umbraprivacy.com/llms-full.txt.

## Overview

- [Umbra at a glance](https://docs.umbraprivacy.com/docs.md): What Umbra is for, what it keeps private and what it does not, and what to know before you rely on it.
- [Guardian nodes](https://docs.umbraprivacy.com/docs/guardian-nodes.md): What the three guardian nodes are, what they do for every registration and value transaction, why their code can be trusted, and what they can and cannot do.
- [Screening](https://docs.umbraprivacy.com/docs/screening.md): What the screener checks before it co-signs a value transaction, which addresses it screens, what it refuses, and what it sees.
- [Zones](https://docs.umbraprivacy.com/docs/zones.md): What a zone is, the signatures it controls for notes entering and leaving it, what stays private, and how zones are created, frozen and revoked.
- [Disclosure](https://docs.umbraprivacy.com/docs/disclosure.md): The encrypted sender record every value transaction carries, the keys that open it, how it is shared with the guardian nodes, and how a sender can prove chosen fields to a zone.

## Introduction

- [What is Umbra](https://docs.umbraprivacy.com/docs/introduction/what-is-umbra.md): The problem Umbra addresses on Solana, how it works in outline, what sets it apart and what it is not.
- [Design principles](https://docs.umbraprivacy.com/docs/introduction/design-principles.md): The eight rules the protocol is built around, why each exists, and what each costs.

## Cryptography

- [Building blocks](https://docs.umbraprivacy.com/docs/cryptography/overview.md): Every cryptographic primitive Umbra uses, the job each one does, and which of them are post-quantum.
- [Hash functions](https://docs.umbraprivacy.com/docs/cryptography/hashing.md): How Umbra uses Poseidon in two forms and Keccak-256, how many values fold into one, and how each object's hash is kept apart from every other.
- [Commitments](https://docs.umbraprivacy.com/docs/cryptography/commitments.md): What hiding and binding mean, why every commitment carries a blinding factor, and where Umbra commits to values instead of publishing them.
- [Merkle trees](https://docs.umbraprivacy.com/docs/cryptography/merkle-trees.md): How Umbra proves that a note exists without saying which one, proves that a nullifier is new, and fits trees of four billion leaves into a few kilobytes on chain.
- [Zero-knowledge proofs](https://docs.umbraprivacy.com/docs/cryptography/zero-knowledge-proofs.md): What a statement, a witness and a public input are, how Groth16 proofs are built in Circom and verified by Solana programs, and what the verifier learns.
- [Signatures](https://docs.umbraprivacy.com/docs/cryptography/signatures.md): The signature schemes Umbra relies on, where each is checked, and why the attesters' signatures combine into one.
- [Encryption](https://docs.umbraprivacy.com/docs/cryptography/encryption.md): How new notes are encrypted to their recipients, how viewing-key shares reach the enclaves, and how the sender record is encrypted inside the proof.
- [Secret sharing](https://docs.umbraprivacy.com/docs/cryptography/secret-sharing.md): How Umbra splits viewing keys among the three guardian nodes so that any two can rebuild them, and how the proof and each node check the split.
- [Trusted execution](https://docs.umbraprivacy.com/docs/cryptography/trusted-execution.md): A short primer on enclaves, measurements and attestation, and how Solana programs check an enclave before its key may sign.
- [Security levels and quantum status](https://docs.umbraprivacy.com/docs/cryptography/security-levels.md): How strong each primitive is today, which ones a quantum computer would break, and what an attacker could and could not do if one existed.

## Your account

- [Everything you own](https://docs.umbraprivacy.com/docs/account/overview.md): The objects that make up an Umbra account, where each one lives, who can see it and how it comes back, and what Umbra's infrastructure holds about you.
- [The account signature](https://docs.umbraprivacy.com/docs/account/account-signature.md): The single wallet signature every Umbra key is derived from, why signing again recovers the whole account, and the ways it can go wrong.
- [The platform wallet](https://docs.umbraprivacy.com/docs/account/platform-wallet.md): The Solana keypair Umbra derives from your account signature, what it signs, how it is bound to your main wallet, and why that binding is public.
- [Your keys](https://docs.umbraprivacy.com/docs/account/keys.md): Every key derived from your account signature, what each one does in the protocol, who else holds it, and what a leak of each would cost.
- [Your identity commitment](https://docs.umbraprivacy.com/docs/account/identity.md): The single public value that stands for you in the shielded pool, the eight slots it commits to, where it is stored and what it reveals.
- [Receiving payments](https://docs.umbraprivacy.com/docs/account/receiving.md): How a sender turns your main wallet address into an identity commitment and an encryption key, what can be checked along the way, and how notes owned by a Solana address differ.
- [Recovery](https://docs.umbraprivacy.com/docs/account/recovery.md): How an Umbra account comes back on a new device, what the recovery depends on, and what cannot be recovered or undone.

## Notes and state

- [Notes](https://docs.umbraprivacy.com/docs/state/notes.md): What a note is, the thirteen fields it carries, the three kinds of note, and where a note's contents live when the chain holds only a hash of them.
- [Note commitments](https://docs.umbraprivacy.com/docs/state/commitments.md): How a note's thirteen fields become one commitment, why the chain wraps that commitment with a slot and a position before storing it, and what the chain checks about either.
- [The note tree](https://docs.umbraprivacy.com/docs/state/note-tree.md): The append-only Merkle tree that holds every note's leaf, how it fits four billion leaves into 19,249 bytes, how leaves are numbered across pool indexes, and what happens when a tree fills.
- [Every tree](https://docs.umbraprivacy.com/docs/state/trees.md): All eight Merkle trees the protocol keeps, what each one holds, its shape, how long its old roots stay usable, and which instruction writes it.
- [Nullifiers](https://docs.umbraprivacy.com/docs/state/nullifiers.md): How a spend cancels a note without saying which note it was, how a nullifier is derived, why every input slot publishes one, and why program-owned notes are linkable when spent.
- [Preventing double spends](https://docs.umbraprivacy.com/docs/state/double-spend.md): The two checks that stop a nullifier being accepted twice, a freshness proof against the nullifier tree and a staging buffer for nullifiers not yet in it, and the watermark that keeps the gap between them closed.
- [The forester](https://docs.umbraprivacy.com/docs/state/forester.md): The permissionless service that moves staged keys from the three staging buffers into their indexed trees, the proof it submits, what it can and cannot do, and what stops when no forester runs.
- [Pool token accounts and tokens](https://docs.umbraprivacy.com/docs/state/tokens.md): Where deposited tokens are held, which program-derived address controls them, which tokens the pool accepts and refuses, and how SOL moves in and out.
- [Value conservation](https://docs.umbraprivacy.com/docs/state/value-conservation.md): The per-token equation every value transaction proves, the range checks that make it mean what it says, and what the Lean proofs establish about it and under which assumptions.

## Proofs and circuits

- [How Umbra uses proofs](https://docs.umbraprivacy.com/docs/proofs/overview.md): Which facts each zero-knowledge proof establishes, which the shielded pool program checks itself, which the attesters vouch for, and how the program rebuilds every proof's public input from its own state.
- [The transaction circuit](https://docs.umbraprivacy.com/docs/proofs/transaction-circuit.md): The fixed 3×3×2×2 circuit behind every deposit, private transfer and withdrawal, its 53 public values, the fifteen conditions it proves, and what it leaves to the program and the attesters.
- [Nullifier freshness circuit](https://docs.umbraprivacy.com/docs/proofs/nullifier-freshness.md): The second proof in every value transaction, which shows the three nullifiers are absent from the nullifier tree at a recent root, who makes it, and what it leaves to the staging buffer.
- [Registration circuit](https://docs.umbraprivacy.com/docs/proofs/registration-circuit.md): What the registration proof shows about a new identity commitment, its eleven public values, how it shares the outgoing viewing key with the guardian nodes, and what the register instruction checks around it.
- [Batch append circuit](https://docs.umbraprivacy.com/docs/proofs/batch-append.md): The forester's proof that twelve staged values were inserted into an indexed tree correctly, what the program supplies to it, and what happens to the pool while no forester runs.
- [Escape-hatch circuit](https://docs.umbraprivacy.com/docs/proofs/escape-hatch-circuit.md): The proof that lets one note leave the pool without any attester, the eleven note values it discloses, what it proves and does not, and what the escape_hatch instruction computes itself.
- [Fee collection circuit](https://docs.umbraprivacy.com/docs/proofs/fee-collection-circuits.md): The circuit that lets the treasury identity collect up to twenty protocol fee notes at a time, what its proof shows, and what the claim_fee_20 handler checks and pays.
- [Merge circuit](https://docs.umbraprivacy.com/docs/proofs/merge.md): A circuit that combines up to eight of one owner's notes into one, written for the EVM port of the pool and not used by the Solana program.
- [Formal verification](https://docs.umbraprivacy.com/docs/proofs/formal-verification.md): What the Lean models of the circuits prove, what they assume, what they show cannot be proved, and what the Kani harnesses and Lean models check on the chain side.

## Operations

- [Register](https://docs.umbraprivacy.com/docs/operations/register.md): What happens when you register, from deriving your keys to the shielded pool appending your identity commitment, including what each attester checks and what becomes public.
- [Deposit](https://docs.umbraprivacy.com/docs/operations/deposit.md): How tokens move from your platform wallet into a pool token account and become private notes, and what each party checks along the way.
- [Private transfer (Private Send)](https://docs.umbraprivacy.com/docs/operations/private-send.md): How a private transfer spends your notes and creates new ones for a recipient, what the relayer adds, and what each party can and cannot learn.
- [Withdraw](https://docs.umbraprivacy.com/docs/operations/withdraw.md): How a withdrawal spends your notes and pays tokens out of a pool token account to a public Solana address, and what stays private when it does.
- [Receive and sync](https://docs.umbraprivacy.com/docs/operations/receive-and-sync.md): How an encrypted note reaches its recipient, how your device finds your notes among everyone's, and how it works out your balance and history.
- [Escape hatch](https://docs.umbraprivacy.com/docs/operations/escape-hatch.md): The exit that needs no attester, what it requires instead, and what it discloses about the note you take out.
- [Fee collection](https://docs.umbraprivacy.com/docs/operations/fee-collection.md): How the three kinds of fee the pool accrues are collected, who can collect each, and where the tokens go.

## Fees and relayers

- [The fee model](https://docs.umbraprivacy.com/docs/fees/fee-model.md): The three kinds of fee a value transaction can carry, how protocol fee rates are chosen and bounded, what stays private, and a worked example.
- [The fee enclave](https://docs.umbraprivacy.com/docs/fees/fee-enclave.md): The attester that checks a transaction's protocol fee notes, what it checks before it signs, what it can see, and how the chain decides to trust it.
- [Relayers](https://docs.umbraprivacy.com/docs/fees/relayers.md): Why relayers exist, what a relayer sees, what it can and cannot do to your transaction, how it is paid, and the policy Umbra's own relayer applies.

## Privacy model

- [What is private and what is visible](https://docs.umbraprivacy.com/docs/privacy/visibility.md): For every operation, what a chain observer can read, and what each party in the system can learn.
- [The anonymity set](https://docs.umbraprivacy.com/docs/privacy/anonymity-set.md): Which notes a spend cannot be told apart from, why every transaction has the same shape, and what makes that set smaller in practice.
- [How privacy is lost](https://docs.umbraprivacy.com/docs/privacy/leaks.md): Every known way information about your activity leaves the protocol, from the public edges of the pool to the services a transaction passes through.
- [Privacy practices](https://docs.umbraprivacy.com/docs/privacy/practices.md): Habits that keep your activity among many others, each tied to the way privacy is lost that it addresses.
- [Metadata and network privacy](https://docs.umbraprivacy.com/docs/privacy/metadata.md): What leaves your device besides the transaction itself, who receives it, and what the protocol can and cannot do about it.
- [Common misconceptions](https://docs.umbraprivacy.com/docs/privacy/misconceptions.md): Things people often assume about Umbra that are not true, each corrected with what the protocol actually does.

## Trust and security

- [Trust assumptions](https://docs.umbraprivacy.com/docs/security/assumptions.md): What you rely on for your funds to be safe, your activity to stay private and the protocol to keep running, who holds which power, and what no one can do.
- [Governance and upgrades](https://docs.umbraprivacy.com/docs/security/governance.md): How every administrative change goes through a public timelock, what governance can change in each program, what it cannot do, and the upgrade authority above it.
- [Liveness](https://docs.umbraprivacy.com/docs/security/liveness.md): What every value transaction needs, what stops when each part is unavailable, and how the escape hatch keeps funds reachable.
- [Known risks](https://docs.umbraprivacy.com/docs/security/risks.md): The risks the protocol carries today, grouped by funds, privacy and liveness.
- [Audits and verification](https://docs.umbraprivacy.com/docs/security/audits.md): What has been machine-checked, and the repeated AI audits the protocol has had.
- [Trusted setup](https://docs.umbraprivacy.com/docs/security/trusted-setup.md): Where Umbra's Groth16 keys came from, and what their soundness rests on.

## Architecture

- [System map](https://docs.umbraprivacy.com/docs/architecture/overview.md): The three layers of Umbra, what runs in each, and how a value transaction gathers its six signatures and reaches the chain and the indexer.
- [On-chain programs](https://docs.umbraprivacy.com/docs/architecture/programs.md): The eight Solana programs, what each one holds and checks, who may use it, and how they trust one another without calling each other.
- [wUSDv](https://docs.umbraprivacy.com/docs/architecture/wusdv.md): A Token-2022 token whose every unit is a share of the USDv the wUSDv program holds, worth more USDv as Solomon Labs' rewards are released to holders at one price for wrapping and unwrapping.
- [Off-chain services](https://docs.umbraprivacy.com/docs/architecture/services.md): Every service a transaction passes through, where it runs, what it holds, what it sees, and what happens when it is down.
- [Where data lives](https://docs.umbraprivacy.com/docs/architecture/data.md): Each kind of Umbra data, where it is stored, who can read it, and what depends on it staying available.
- [Solana specifics](https://docs.umbraprivacy.com/docs/architecture/solana.md): How Umbra fits Solana's transaction size, account and compute limits, and what that costs.
- [Versions](https://docs.umbraprivacy.com/docs/architecture/versions.md): How Umbra versions its instructions and accounts, and where to find the current version of each program's instructions.

## Resources

- [Glossary](https://docs.umbraprivacy.com/docs/resources/glossary.md): Every term these pages use, in one place, with a link to where it is explained.
- [Frequently asked questions](https://docs.umbraprivacy.com/docs/resources/faq.md): Short answers to the questions people ask most about how Umbra works, each linking to the full explanation.
- [Program addresses](https://docs.umbraprivacy.com/docs/resources/addresses.md): The address of every Umbra program, read from the repository at build time.
- [Changelog](https://docs.umbraprivacy.com/docs/resources/changelog.md): Changes to the protocol that these pages describe, newest first.
- [References](https://docs.umbraprivacy.com/docs/resources/references.md): The standards and papers behind the primitives Umbra uses.