Skip to main content

​
getUserRegistrationFunction

Import: @umbra-privacy/sdk/registration 
function getUserRegistrationFunction(
  args: GetUserRegistrationFunctionArgs,
  deps?: GetUserRegistrationFunctionDeps,
): UserRegistrationFunction
Registers the caller on-chain. Registration is a multi-step idempotent flow that enables confidential token accounts (encrypted balances) and anonymous usage (mixer eligibility). Steps already completed in a previous session are skipped.

​
GetUserRegistrationFunctionArgs

  • client: IUmbraClient - The configured client.

​
GetUserRegistrationFunctionDeps

All fields are optional overrides for SDK defaults. RPC overrides:
  • accountInfoProvider?: AccountInfoProviderFunction
  • getLatestBlockhash?: GetLatestBlockhash
  • transactionForwarder?: TransactionForwarder
Key derivation overrides:
  • userAccountX25519KeypairGenerator?: Curve25519KeypairGeneratorFunction
  • masterViewingKeyEncryptingX25519KeypairGenerator?: Curve25519KeypairGeneratorFunction
  • mintX25519KeypairGenerator?: MintX25519KeypairGeneratorFunction
  • masterViewingKeyGenerator?: MasterViewingKeyGeneratorFunction
  • masterViewingKeyBlindingFactorGenerator?: MasterViewingKeyBlindingFactorGeneratorFunction
  • poseidonPrivateKeyGenerator?: PoseidonPrivateKeyGeneratorFunction
  • poseidonBlindingFactorGenerator?: PoseidonBlindingFactorGeneratorFunction
  • rescueCommitmentBlindingFactorGenerator?: RescueEncryptionCommitmentBlindingFactorGeneratorFunction
  • randomFactorGenerator?: RandomFactorForPolynomialCommitmentGeneratorFunction
Rescue cipher overrides:
  • getRcKeyGenerator?: (privateKey: X25519PrivateKey) => RcKeyGeneratorFunction
  • getRcEncryptor?: (privateKey: X25519PrivateKey) => RcEncryptorWithNonceFunction
  • rescueCommitmentGenerator?: RescueEncryptionCommitmentGeneratorFunction
Commitment overrides:
  • userCommitmentGenerator?: UserCommitmentGeneratorFunction
Challenge / polynomial overrides:
  • fiatShamirChallengeGenerator?: FiatShamirChallengeGeneratorFunction
  • challengePowersFunction?: ChallengePowersFunction
  • polynomialEvaluator?: PolynomialEvaluatorFunction
Poseidon / BN254 overrides:
  • poseidonAggregator?: PoseidonAggregatorHashFunction
  • bn254ModInverter?: ModuleInvFunction
  • computeLimbwiseSumInverse?: (limbs: Base85LimbTuple) => Bn254FieldElement
ZK prover:
  • zkProver?: IZkProverForUserRegistration — ZK proof generator for the anonymous registration sub-step. Required only when options.anonymous is true. Use getUserRegistrationProver() from @umbra-privacy/sdk/zk-prover — see ZK Provers.

​
Returns

UserRegistrationFunction 
type UserRegistrationFunction = (
  options?: UserRegistrationOptions,
) => Promise<TransactionSignature[]>
Returns the signatures of all transactions submitted during the registration flow. Already-completed steps produce no transactions.

​
UserRegistrationOptions

  • confidential?: boolean - Register for confidential (encrypted) token account usage. Default: true.
  • anonymous?: boolean - Register for anonymous (mixer) usage. Requires a ZK proof. Default: true.
  • hooks?: RegistrationHooks - Per-step lifecycle hooks. Slots: initUserAccount, registerX25519PublicKey, registerAnonymousUsage (each SkippableDirectTransactionStepHooks or SkippableMpcTransactionStepHooks), plus top-level onValidationStart/Complete, onAccountFetchStart/Complete, onKeyDerivationStart/Complete, onComplete, onError.
  • optionalData?: OptionalData32 - 32-byte caller metadata attached to on-chain instructions.

​
Errors

Throws RegistrationError. See Errors for all stages.

​
Example

import { getUserRegistrationFunction } from "@umbra-privacy/sdk";
import { getUserRegistrationProver } from "@umbra-privacy/sdk/zk-prover";

const zkProver = getUserRegistrationProver();

const register = getUserRegistrationFunction({ client }, { zkProver });
const signatures = await register({ confidential: true, anonymous: true });

​
getUserEncryptionKeyRotatorFunction

Import: @umbra-privacy/sdk/account 
function getUserEncryptionKeyRotatorFunction(
  args: { client: IUmbraClient },
  deps?: GetUserRegistrationFunctionDeps,
): () => Promise<TransactionSignature[]>;
Rotates the X25519 public key stored in the on-chain user account. Synchronous, no MPC. Use this when the existing key may have been compromised. Accepts the same shape args / deps as getUserRegistrationFunction. Returns a zero-argument function. Call it with no arguments to execute the rotation.

​
getMasterViewingKeyRotatorFunction

Import: @umbra-privacy/sdk/account 
function getMasterViewingKeyRotatorFunction(
  args: { client: IUmbraClient },
  deps?: GetUserRegistrationFunctionDeps,
): () => Promise<TransactionSignature[]>;
Rotates the Master Viewing Key (MVK) X25519 encryption key. MPC + ZK — also rotates the on-chain user commitment. Accepts the same args / deps shape as getUserRegistrationFunction. Returns a zero-argument function. Call it with no arguments to execute the rotation.

​
getUserEntropySeedRotatorFunction

Import: @umbra-privacy/sdk/account 
function getUserEntropySeedRotatorFunction(
  args: { client: IUmbraClient },
  deps?: GetUserEntropySeedRotatorFunctionDeps,
): UserEntropySeedRotatorFunction;
Rotates the random generation seed stored in the on-chain user account. This seed contributes to commitment randomness in Stealth Pool Note operations. Synchronous, no MPC.

​
Deps

  • accountInfoProvider?: AccountInfoProviderFunction.
  • getLatestBlockhash?: GetLatestBlockhash.
  • transactionForwarder?: TransactionForwarder.

​
Returns

type UserEntropySeedRotatorFunction = (args: {
  newSeed: Uint8Array;
  optionalData?: OptionalData32;
}) => Promise<SimpleOperationResult>;
  • newSeed: Uint8Array — the 32-byte replacement seed.

​
getTokenEntropySeedRotatorFunction

Import: @umbra-privacy/sdk/account 
function getTokenEntropySeedRotatorFunction(
  args: { client: IUmbraClient },
  deps?: GetTokenEntropySeedRotatorFunctionDeps,
): TokenEntropySeedRotatorFunction;
Rotates the random generation seed on a per-mint EncryptedTokenAccount. Synchronous, no MPC.

​
Deps

  • accountInfoProvider?: AccountInfoProviderFunction.
  • getLatestBlockhash?: GetLatestBlockhash.
  • transactionForwarder?: TransactionForwarder.

​
Returns

type TokenEntropySeedRotatorFunction = (args: {
  mint: Address;
  newSeed: Uint8Array;
  optionalData?: OptionalData32;
  hooks?: DirectTransactionStepHooks;
}) => Promise<SimpleOperationResult>;
  • mint: Address — the token mint whose account seed to rotate.
  • newSeed: Uint8Array — the 32-byte replacement seed.

​
getStagedSolRecovererFunction

Import: @umbra-privacy/sdk/account 
function getStagedSolRecovererFunction(
  args: { client: IUmbraClient },
  deps?: GetStagedSolRecovererFunctionDeps,
): StagedSolRecovererFunction;
Recovers wSOL that was staged in the protocol’s pool custody during a failed MPC callback. Call this if a deposit / withdraw / convert callback never landed and you need to reclaim the staged SOL. Synchronous — no MPC, no ZK proof.

​
Deps

  • accountInfoProvider?: AccountInfoProviderFunction.
  • getLatestBlockhash?: GetLatestBlockhash.
  • transactionForwarder?: TransactionForwarder.

​
Returns

type StagedSolRecovererFunction = (args: {
  mint: Address;
  optionalData?: OptionalData32;
  hooks?: DirectTransactionStepHooks;
}) => Promise<SimpleOperationResult>;
  • mint: Address — the mint of the failed operation (typically the wSOL mint).

​
getStagedSplRecovererFunction

Import: @umbra-privacy/sdk/account 
function getStagedSplRecovererFunction(
  args: { client: IUmbraClient },
  deps?: GetStagedSplRecovererFunctionDeps,
): StagedSplRecovererFunction;
Recovers SPL tokens that were staged in the protocol’s pool custody during a failed MPC callback. Synchronous — no MPC, no ZK proof.

​
Deps

  • accountInfoProvider?: AccountInfoProviderFunction.
  • getLatestBlockhash?: GetLatestBlockhash.
  • transactionForwarder?: TransactionForwarder.

​
Returns

type StagedSplRecovererFunction = (args: {
  mint: Address;
  optionalData?: OptionalData32;
  hooks?: DirectTransactionStepHooks;
}) => Promise<SimpleOperationResult>;
  • mint: Address — the token mint of the staged SPL tokens.

​
RegistrationError

Thrown by getUserRegistrationFunction. See Errors. Stage values: "initialization" | "master-seed-derivation" | "account-fetch" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send"