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

# Registration (/reference/registration)

A user registers once before their first deposit. [Register a user](https://sdk.nimbusprivacy.xyz/registration) walks through
the flow.

## readRegistration

Use it to learn whether the user is registered now. The session's own `registration` is fixed when
the session opens.

```ts
function readRegistration(
  session: NimbusSession,
  _args?: Readonly<Record<string, never>>,
): Promise<NimbusRegistrationStanding>;
```

Reads the session's registration standing again, from the context API: what `register` changed,
which the session's own `registration`, fixed when it opened, does not show.

Call it after [`register`](https://sdk.nimbusprivacy.xyz/reference/registration#register) lands to learn the identity is registered without reopening the
session. The standing is for pool 0, as the session's is.

**Parameters**

| Parameter | Type                              | Description                                              |
| --------- | --------------------------------- | -------------------------------------------------------- |
| `session` | `NimbusSession`                   | The opened session.                                      |
| `_args?`  | `Readonly<Record<string, never>>` | Unused; kept so every function takes the same arguments. |

**Returns**

`Promise<NimbusRegistrationStanding>`

`registered` or `unregistered`, with the pool the standing is for.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"service-unavailable"` when the context API cannot be
reached, or `"unreadable"` when it answers what cannot be read.

**Example**

```ts
import { readRegistration } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const standing = await readRegistration(session, {});
if (standing.kind === "registered") {
  console.log(`registered in pool ${String(standing.poolIndex)}`);
}
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/session.ts`.

## createRegistrationContext

Create one before you call `register`. It picks the pool the user registers in.

```ts
function createRegistrationContext(
  session: NimbusSession,
  options?: RegistrationContextOptions,
): Promise<RegistrationContext>;
```

Creates the context a session registers in.

Without `options.poolIndex` the pools' accounts are read from the RPC once, and the highest open
pool is chosen; the data endorser node and guardian cluster default to the cluster's preset.

**Parameters**

| Parameter  | Type                         | Description                                                |
| ---------- | ---------------------------- | ---------------------------------------------------------- |
| `session`  | `NimbusSession`              | The opened session.                                        |
| `options?` | `RegistrationContextOptions` | The pool, the data endorser node and the guardian cluster. |

**Returns**

`Promise<RegistrationContext>`

The context.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when an option is out of range or no
pool is open; `"service-unavailable"` or `"unreadable"` when the RPC cannot be read.

**Example**

```ts
import { createRegistrationContext, register } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const result = await register(await createRegistrationContext(session), {});
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/contexts.ts`.

## register

Use it once per user, while `readRegistration` says `unregistered`.

```ts
function register(
  context: RegistrationContext,
  _args?: Readonly<Record<string, never>>,
  options?: RegisterOptions,
): Promise<RegistrationResult>;
```

Registers the session's identity in the context's pool and binds the connected wallet to its
platform wallet, in one transaction the wallet signs, sending only what is still missing.

Reads the identity's standing from the context API, asks the guardians and the data endorser to
endorse it, proves it, has the wallet sign once and sends it. An identity already registered and
bound is `complete` with nothing sent.

**Parameters**

| Parameter  | Type                              | Description                                                                      |
| ---------- | --------------------------------- | -------------------------------------------------------------------------------- |
| `context`  | `RegistrationContext`             | The registration context.                                                        |
| `_args?`   | `Readonly<Record<string, never>>` | Unused; kept so every function takes the same arguments.                         |
| `options?` | `RegisterOptions`                 | The progress hook, the priority fee, the transaction version and the commitment. |

**Returns**

`Promise<RegistrationResult>`

`complete` when the identity was registered and bound already, with nothing sent;
`submitted` with the instructions sent and where the transaction ended up, which registered
only when its `submission.kind` is `landed`; `declined` when the wallet declined to sign; or
`store-refused` when the note store would not open for the identity.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"service-unavailable"` or `"unreadable"` when a
service or the RPC cannot answer, `"unauthorized"` when a gateway service refuses the session's
gateway token or the session has none, `"dependency-nonconforming"` when a proving key or the
prover breaks its contract, `"wallet-unsupported"` when the wallet fails, and `"misconfigured"`
when no prover worker or committee endpoint was configured; [`NimbusSolanaFlowError`](https://sdk.nimbusprivacy.xyz/reference/types#nimbussolanaflowerror),
which [`isNimbusSolanaFlowError`](https://sdk.nimbusprivacy.xyz/reference/errors#isnimbussolanaflowerror) recognises, when the protocol refuses the registration,
with reason `"fee-payer-unfunded"` when the connected wallet has no account or too few
lamports to pay the transaction's fee and keep its rent-exempt minimum, raised before any
proving key is downloaded or the committee is asked.

**Example**

```ts
import { createRegistrationContext, register } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const result = await register(await createRegistrationContext(session), {}, {
  onProgress: (event) => {
    console.log(event.stage);
  },
});
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/flows.ts`.


Last updated 21 October 2026