Register a user

Registering is a one-time Solana transaction. It creates Alice's identity, the public record of her private account, and links her wallet to it.

Nobody can pay Alice privately until she registers. That includes deposits into her own private balance, from her wallet or anyone else's.

In this guide, Alice checks whether she is registered, then registers from the wallet she connected.

What's publicCopy Anchor Link

Her platform wallet is a second Solana address the SDK derives from her signature. It signs her deposits alongside her wallet. Registering links the two wallets in public, so anyone can tell they belong to one private account.

Registering reveals nothing about what Alice later holds or pays. What each operation shows explains each line.

Check firstCopy Anchor Link

session.registration says where Alice stood when the session opened. It never changes while the session is open. To read where she stands now, call readRegistration:

import { readRegistration } from "@umbra/nimbus-solana-web";

if (session.registration.kind === "unregistered") {
  const standing = await readRegistration(session, {});
          
const standing: NimbusRegistrationStanding
  if (standing.kind === "unregistered") showRegisterButton();
}

• session.registration is current when the session opens. Use it to decide what to show first.
• readRegistration asks Nimbus again. Use it after register lands, or when another tab may have registered.

RegisterCopy Anchor Link

Create a registration context from the session, then call register.

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

const context = await createRegistrationContext(session);
const result = await register(context, {}, { transactionVersion });

• {} is the arguments, and there are none. The session says who registers.
• transactionVersion is what the wallet can sign. A registration fits one transaction at either version. See Connect a wallet.
• createRegistrationContext picks the newest open pool. Pass poolIndex to choose another.

First the SDK builds a proof on the device and collects Nimbus's approval. That takes a few seconds. Then Alice's wallet asks her to approve one transaction.

That transaction registers her and links her wallet in one step. She pays its network fee from her wallet. Registering opens no new account on Solana, so there is no rent to pay.

Her wallet needs a little SOL for that fee. The SDK checks her balance before it builds the proof. A wallet without enough throws at once, so she never waits for a proof that cannot be sent.

Handle the resultCopy Anchor Link

register returns a result instead of throwing for anything your user can cause. Check its kind:

A submitted result carries the transaction's fate in result.submission.submission.kind:

Here is the whole check in one function. TypeScript checks that it covers every case.

function describeRegistration(result: RegistrationResult): string {
  switch (result.kind) {
    case "complete":
      return "You are registered.";
    case "submitted":
      switch (result.submission.submission.kind) {
        case "landed":
          return "You are registered.";
        case "failed":
          return "Registration failed on Solana. Only the network fee was charged.";
        case "expired":
        case "refused":
          return "Registration never reached Solana. Try again.";
        case "unknown":
          return "Registration is still pending.";
      }
    case "declined":
      return "You declined to register in your wallet.";
    case "store-refused":
      return "This browser could not open your account data. Reload and try again.";
  }
}

Alice is registered when the result is complete, or submitted with a landed submission. She can deposit straight away.

Show progressCopy Anchor Link

Pass onProgress to tell Alice what is happening:

import { register } from "@umbra/nimbus-solana-web";

await register(context, {}, { onProgress: (event) => showStatus(event.stage) });

The stages are prepared, endorsed, proved, signed, sent and confirmed. endorsed and proved can arrive in either order. A registration with nothing left to send stops after prepared. Show progress has a message for each stage.

Edge casesCopy Anchor Link

Already registeredCopy Anchor Link

register checks first and sends only what is missing. If Alice is registered and her wallet is linked, it returns complete. Her wallet never asks her to sign.

A registration still settlingCopy Anchor Link

A submission of kind unknown may still land until its blockhash expires. Do not call register again straight away. Wait a minute, then call readRegistration. If it says unregistered, try again.

A landed registration lets Alice deposit at once. Spending takes a little longer. Her private balance can pay only once the registration is final on Solana and her device has synced. Until then, a Private Send or a withdrawal is refused with not-registered.

Two tabs registering at onceCopy Anchor Link

register holds a lock for Alice's wallet for the whole call. The lock is shared by every tab of your site in one browser. A second tab waits for the first to finish, then checks again. If the first tab's registration landed and Nimbus has seen it, the second returns complete.

Common errorsCopy Anchor Link

These are thrown, not returned, because your app usually cannot fix them by asking the user.

Handle errors shows one function that covers every error the SDK throws.

OptionsCopy Anchor Link

The API reference lists every option.

NextCopy Anchor Link