> For AI agents: the documentation index is at https://docs.umbraprivacy.com/llms.txt, and every page is available as Markdown at its URL with .md appended.

# Register (/docs/operations/register)

> **Umbra's clients, not the protocol**
>
> The pool requires a registration proof over your identity commitment, signed by the wallet whose address that commitment holds in slot 4. Deriving your keys and that wallet from one signature by your main wallet, and binding the two in the user registry, is the standard Umbra's SDKs and client interfaces follow; the protocol does not enforce it, and other clients can register their own way.

Registering adds your identity commitment to the shielded pool's identity tree, once and for good. It moves no value, and it is the one operation that publishes who you are: after it, your main wallet, your platform wallet and your identity commitment are linked on chain.

## Summary

Your device derives your keys, splits your outgoing viewing key among the three guardian nodes, proves in zero knowledge that everything was built correctly, and collects a signature from each guardian node and from the data endorser. One Solana transaction then binds your platform wallet to your main wallet in the user registry and registers your identity commitment in the shielded pool.

Your identity commitment (sometimes called the user commitment) is one field element that commits to all of your account's keys. Registering it is what later lets you receive notes and prove you own them; see [your identity commitment](https://docs.umbraprivacy.com/docs/account/identity).

## Preconditions

- Your main wallet can sign the account message and pay a Solana transaction fee.
- The guardian cluster is Active, and all three guardian nodes and the data endorser answer.
- Your identity commitment is not already registered in the pool index you are using (pool index 0 unless the application chooses another).

## How a registration runs

A registration has three phases: your device prepares everything locally, collects the attester signatures while it makes the registration proof, and then has your two wallets sign one transaction.

```mermaid
flowchart LR
A["Prepare on your device"] --> B["Collect attester signatures"]
A --> C["Make the proof"]
B --> D["Submit one transaction"]
C --> D
```

*The three phases of a registration: the proof and the attester signatures are made side by side.*

The proof and the signatures run side by side because neither needs the other.

## Phase 1: preparing on your device

Nothing that reveals a key leaves your device in this phase, and every check that can refuse the registration early runs before any share is sent.

```mermaid
sequenceDiagram
participant D as Your device
participant X as Context service
participant U as User registry
D->>D: derive keys and commitment
D->>U: read latest bind
U-->>D: bind or none
D->>X: standing of this commitment
X-->>D: cluster, root, absence witness
D->>D: check cluster and witness
D->>D: split viewing key, build digest
```

*Preparing a registration: your device reads the user registry and asks the context service whether this commitment is registered.*

### 1. Your device derives your keys and identity commitment

Your main wallet signs one fixed message, and from that signature the SDK derives your platform wallet (the Solana keypair Umbra uses for you), your spending, nullifier, outgoing viewing and proof-authorisation keys, and an ML-KEM-768 keypair that senders encrypt notes to. Your identity commitment is computed from those keys, your platform wallet's address and the hash of your ML-KEM-768 public key. See [keys](https://docs.umbraprivacy.com/docs/account/keys).

### 2. Your device asks whether you are already registered

The SDK reads your main wallet's latest bind from the user registry and asks the context service whether your commitment is registered. The context service answers in one call with the guardian cluster's state, the registration tree's current root and a witness that your commitment is absent from it, so the values all come from the same moment. If you are already registered nothing is sent; if your main wallet is bound to a different platform wallet, the SDK refuses.

### 3. Your device checks the cluster and the witness

The SDK checks that the guardian cluster is Active with the three nodes the circuit expects, that the witness's root is one the pool still accepts, and that the witness really shows your commitment is absent. All of this happens before a share leaves the device.

### 4. Your device splits your outgoing viewing key

The SDK splits your outgoing viewing key into three Shamir secret shares, one per guardian node, at the live cluster's threshold: any two shares rebuild the key, and one alone reveals nothing. The shares are derived from your identity's master secret, so a retry at the same threshold deals the same shares. Their commitments fold into one sharing root, which the nodes check their shares against and the proof binds the split to.

### 5. Your device builds the payload and its context digest

The SDK hashes the registration payload (your identity commitment, the sharing root, the cluster, the tree root, your encryption key hash and a few other values) and the transaction's six account addresses into the context digest. Every attester signs this one value, so each signature commits to the whole registration, and the proof's single public input is built from the same values.

## Phase 2: collecting the attester signatures

Your device now contacts the three guardian nodes and the data endorser; a registration needs neither the screener nor the fee enclave. The proof is made at the same time.

```mermaid
sequenceDiagram
participant D as Your device
participant G as Guardian nodes
participant E as Data endorser
par to each of three nodes
  D->>G: encrypted share, payload
  G-->>D: BLS signature
and to the endorser
  D->>E: payload, public key
  E-->>D: BLS signature
and on the device
  D->>D: registration proof
end
D->>D: check keys, combine
```

*Collecting signatures: each guardian node gets its own encrypted share, the data endorser gets your public key, and the proof runs on the device meanwhile.*

### 6. Your device sends each guardian node its share

Each node receives only its own share, encrypted to a transport key the node publishes for the request under a hybrid of ML-KEM-1024 and X25519, along with the payload, context digest and share commitments it needs to check the share. The three nodes are contacted at once.

### 7. Each guardian node checks its share and signs

Each node checks that the request is addressed to it, recomputes the context digest, decrypts its share, and checks that the share matches its commitment and that the three commitments rebuild the sharing root. That last check ties the share to the proof, which shows the root commits to a correct split of your outgoing viewing key. The node then stores a sealed, escrowed copy of its share where it cannot be overwritten, and returns a BLS signature over the context digest. It does not verify the proof or your encryption key; see [what a guardian node checks](https://docs.umbraprivacy.com/docs/guardian-nodes#what-they-check).

### 8. The data endorser checks your encryption key and signs

The data endorser checks that the hash of your ML-KEM-768 public key equals the encryption key hash in the payload and that the registration memo digest matches, which the proof cannot do because it binds only the hash. It then archives your public key, which is where senders later fetch it to encrypt notes to you (see [receiving payments](https://docs.umbraprivacy.com/docs/account/receiving)), and signs the context digest. Repeating the request returns the same signature.

### 9. Your device makes the registration proof

Meanwhile your device proves that your keys are non-zero, that your identity commitment is built correctly from them, your platform wallet's address and your encryption key hash, that the shares are a correct two-of-three split of your outgoing viewing key, and that your commitment is absent from the registration tree. The proof does not show that you hold the platform wallet, which its signature does, or that the key hash belongs to a real key, which the data endorser checked. The SDK then checks the proof's public input against the value from step 5 and stops on a mismatch.

### 10. Your device checks the guardian keys and combines the signatures

The SDK checks that the three guardian nodes' signing keys sum to the aggregate key the cluster publishes, so a node signing with the wrong key is caught here with a clear refusal rather than as an unexplained failure on chain. It then adds the four signatures into one combined attester signature.

## Phase 3: submitting the transaction

One Solana transaction carries up to two instructions. Your main wallet signs first and pays the fee; your platform wallet also signs.

```mermaid
sequenceDiagram
participant D as Your wallets
participant R as User registry
participant P as Shielded pool
D->>R: bind_platform_wallet
R-->>D: bind recorded
D->>P: register
P->>P: check signature and proof
P->>P: stage, then append
```

*Submitting: one transaction, two programs, both wallets signing.*

### 11. Your main wallet and platform wallet sign one transaction

The transaction includes `bind_platform_wallet` only when your main wallet has no bind yet, and `register` unless you are already registered. Your main wallet pays but authorises nothing in `register`; your platform wallet's signature is what proves you hold the address your identity commitment binds. See [the platform wallet](https://docs.umbraprivacy.com/docs/account/platform-wallet).

### 12. The user registry records the bind

The bind needs both wallets' signatures, so neither can be named without its consent, and the two must be different addresses. It refuses to run when another program invokes it, so a program holding your main wallet's signature cannot rebind you without your seeing it. Nothing is stored: every bind is listed under one address tied to your main wallet, and the latest one is current.

### 13. The shielded pool verifies and appends your commitment

The pool checks that both wallets signed and that no other program invoked `register`, that the proof's root is among the registration staging buffer's 120 most recent roots and not retired, that the cluster is Active and 2-of-3 (the only shape whose identities can later spend), and that the data endorser is registered and active. It verifies the combined attester signature against the cluster's aggregate key plus the endorser's key, verifies the proof, stages your commitment (refusing one already staged) and appends it to the identity tree.

The pool rebuilds the context digest and the proof's public input from what it reads itself, so a proof made for another wallet, root or cluster fails. Because the cluster's key is the sum of all three nodes' keys, the signature passes only if every guardian node and the data endorser signed.

## On chain afterwards

Your identity commitment is a new leaf of the identity tree, which is where senders find it. It also sits in the staging buffer until the forester proves it into the registration tree, the tree later registrations prove absence from. Besides the fields below, the transaction permanently carries the registration memo digest, the combined attester signature and the proof.

**Register: Everything a chain observer can read**

| Field                      | On chain                                                 |
| -------------------------- | -------------------------------------------------------- |
| Programs                   | User registry, shielded pool                             |
| Fee payer                  | Your main wallet                                         |
| Bound wallet               | Your platform wallet                                     |
| Identity commitment        | One field element                                        |
| Encryption key hash        | Keccak-256 of your ML-KEM-768 public key                 |
| Sharing root               | Commitment to the three shares                           |
| Keys behind the commitment | Private                                                  |
| Viewing-key shares         | Private. Sent only to the guardian nodes, never on chain |

*Registration keeps your keys private, not your identity: the commitment is published beside both of your wallets.*

## What can go wrong

- **Already registered.** The SDK sends nothing, and the pool refuses a duplicate that arrives anyway.
- **An attester does not answer, or refuses.** The combined attester signature needs all three guardian nodes and the data endorser, so nothing reaches the chain.
- **The cluster is not Active.** A cluster that is degraded, frozen or changing its membership is not Active, and both the SDK and the pool refuse.
- **The witness went stale.** A root that has left the window of 120 recent roots, or been retired, is refused; fetch a new witness and prove again.
- **The staging buffers are full.** With both 30,000-commitment buffers full, nothing is staged until the forester empties them.
- **The proof fails after the shares went out.** Three guardian nodes then hold shares of a viewing key for an identity that was never registered; the SDK can prove first instead, at the cost of time.
- **Your main wallet is bound to a different platform wallet.** The SDK refuses, and repairing it takes a new bind signed by both wallets, which the SDK does not make automatically.
- **Another program sent the registration.** The pool refuses it; `register` must be one of the transaction's own instructions.

## Privacy notes

- The link between your main wallet, your platform wallet and your identity commitment is public and permanent. Every later deposit from your platform wallet is attributable to you.
- The time you registered is public, and so is your position in the identity tree.
- The context service learns your identity commitment when you ask about it, together with your network address.

## Related

- [Your identity commitment](https://docs.umbraprivacy.com/docs/account/identity): What was just registered.
- [Registration circuit](https://docs.umbraprivacy.com/docs/proofs/registration-circuit): The proof in detail.
- [Guardian nodes](https://docs.umbraprivacy.com/docs/guardian-nodes): What they do, and what they can and cannot do.
- [Deposit](https://docs.umbraprivacy.com/docs/operations/deposit): The next step: moving tokens into the pool.


Last updated 12 October 2026