Skip to main content

​
Import Path

import {
  // Staged errors
  EncryptedDepositError,
  EncryptedWithdrawalError,
  RegistrationError,
  ConversionError,
  CreateUtxoError,
  FetchUtxosError,
  ClaimUtxoError,
  QueryError,
  AccountError,
  ComplianceError,
  isEncryptedDepositError,
  isEncryptedWithdrawalError,
  isRegistrationError,
  isConversionError,
  isCreateUtxoError,
  isFetchUtxosError,
  isClaimUtxoError,
  isQueryError,
  isAccountError,
  isComplianceError,

  // Base primitives
  UmbraError,
  CryptographyError,
  InstructionError,
  RpcError,
  TransactionError,
  TransactionSigningError,
  MasterSeedSigningRejectedError,
  isUmbraError,
  isCryptographyError,
  isInstructionError,
  isRpcError,
  isTransactionError,
  isTransactionSigningError,
} from "@umbra-privacy/sdk/errors";

​
Error Hierarchy

Error
└── UmbraError
    ├── CryptographyError
    ├── InstructionError
    ├── RpcError
    ├── TransactionError
    │   └── TransactionSigningError
    │       └── MasterSeedSigningRejectedError
    ├── EncryptedDepositError
    ├── EncryptedWithdrawalError
    ├── RegistrationError
    ├── ConversionError
    ├── CreateUtxoError
    ├── FetchUtxosError
    ├── ClaimUtxoError
    ├── QueryError
    ├── AccountError
    └── ComplianceError

​
Staged Errors

Every major SDK operation throws a dedicated staged error. The stage field pinpoints exactly where in the pipeline the failure occurred.

​
EncryptedDepositError

Thrown by getATAIntoETADirectDepositorFunction. 
class EncryptedDepositError extends UmbraError {
  readonly stage: EncryptedDepositStage;
}

function isEncryptedDepositError(error: unknown): error is EncryptedDepositError;
Stage values:
  • "initialization" - Factory construction failed. Missing required arguments.
  • "validation" - Invalid mint address, zero amount, or unregistered destination.
  • "mint-fetch" - Failed to fetch the mint account. Check RPC and mint address.
  • "fee-calculation" - Token-2022 transfer fee calculation failed. Epoch info issue.
  • "pda-derivation" - Failed to derive required PDAs.
  • "account-fetch" - Failed to fetch the destination user or token account.
  • "instruction-build" - Failed to construct the instruction. Protocol state mismatch.
  • "transaction-build" - Failed to assemble the transaction. Blockhash fetch failure.
  • "transaction-compile" - Failed to compile the transaction. Lookup table mismatch.
  • "transaction-sign" - Wallet rejected signing.
  • "transaction-validate" - Pre-flight simulation failed. Insufficient funds or account state mismatch.
  • "transaction-send" - Transaction sent but confirmation timed out. May still have landed.

​
EncryptedWithdrawalError

Thrown by getETAIntoATAWithdrawerFunction. 
class EncryptedWithdrawalError extends UmbraError {
  readonly stage: EncryptedWithdrawalStage;
}

function isEncryptedWithdrawalError(error: unknown): error is EncryptedWithdrawalError;
Stage values:
  • "initialization" - Factory construction failed.
  • "validation" - Zero amount or no encrypted balance exists for this mint.
  • "mint-fetch" - Failed to fetch the mint account.
  • "pda-derivation" - Failed to derive required PDAs.
  • "instruction-build" - Failed to construct the instruction.
  • "transaction-build" - Blockhash fetch failure.
  • "transaction-compile" - Failed to compile the transaction.
  • "transaction-sign" - Wallet rejected signing.
  • "transaction-send" - Confirmation timed out. May still have landed.

​
RegistrationError

Thrown by getUserRegistrationFunction. 
class RegistrationError extends UmbraError {
  readonly stage: RegistrationStage;
}

function isRegistrationError(error: unknown): error is RegistrationError;
Stage values:
  • "initialization" - Factory construction failed.
  • "master-seed-derivation" - User declined to sign the master seed derivation message.
  • "account-fetch" - Failed to fetch on-chain account state. RPC connectivity issue.
  • "key-derivation" - Cryptographic key derivation from master seed failed.
  • "zk-proof-generation" - Groth16 proof generation failed (anonymous step only).
  • "pda-derivation" - Failed to derive required PDAs.
  • "instruction-build" - Failed to construct an instruction.
  • "transaction-build" - Blockhash fetch failure.
  • "transaction-compile" - Failed to compile the transaction.
  • "transaction-sign" - Wallet rejected signing.
  • "transaction-validate" - Pre-flight simulation failed.
  • "transaction-send" - Confirmation timed out. May still have landed.

​
ConversionError

Thrown by getNetworkEncryptionToSharedEncryptionConverterFunction and getMintEncryptionKeyRotatorFunction. 
class ConversionError extends UmbraError {
  readonly stage: ConversionStage;
}

function isConversionError(error: unknown): error is ConversionError;
Stage values:
  • "initialization" - Factory construction failed.
  • "account-fetch" - Failed to fetch token account state.
  • "pda-derivation" - Failed to derive required PDAs.
  • "instruction-build" - Failed to construct the conversion instruction.
  • "transaction-build" - Blockhash fetch or transaction assembly failed.
  • "transaction-compile" - Failed to compile the transaction.
  • "transaction-sign" - Wallet rejected a per-mint transaction.
  • "transaction-validate" - Pre-flight simulation failed.
  • "transaction-send" - Confirmation timed out. Already-converted mints remain on-chain.

​
CreateUtxoError

Thrown by all four Stealth Pool Note creator factory functions in @umbra-privacy/sdk/deposit. 
class CreateUtxoError extends UmbraError {
  readonly stage: CreateUtxoStage;
}

function isCreateUtxoError(error: unknown): error is CreateUtxoError;
Stage values:
  • "initialization" - Factory construction failed.
  • "validation" - Invalid recipient, mint, or amount.
  • "account-fetch" - Failed to fetch the recipient’s on-chain account.
  • "mint-fetch" - Failed to fetch mint account data.
  • "fee-calculation" - Token-2022 transfer fee calculation failed.
  • "key-derivation" - Key derivation from master seed failed.
  • "zk-proof-generation" - Groth16 proof generation failed.
  • "pda-derivation" - Failed to derive required PDAs.
  • "instruction-build" - Failed to construct the instruction.
  • "transaction-build" - Blockhash fetch or transaction assembly failed.
  • "transaction-compile" - Failed to compile the transaction.
  • "transaction-sign" - Wallet rejected signing.
  • "transaction-validate" - Pre-flight simulation failed.
  • "transaction-send" - Confirmation timed out. May still have landed - check before retrying.

​
FetchUtxosError

Thrown by getBurnableStealthPoolNoteScannerFunction in @umbra-privacy/sdk/burn. 
class FetchUtxosError extends UmbraError {
  readonly stage: FetchUtxosStage;
}

function isFetchUtxosError(error: unknown): error is FetchUtxosError;
Stage values:
  • "initialization" — factory construction failed. indexerApiEndpoint not configured.
  • "validation" — invalid scanner-level input.
  • "key-derivation" — X25519 private key derivation from master seed failed.
  • "indexer-fetch" — indexer HTTP call failed (unreachable, rate-limited, or error response).
  • "proof-fetch" — Merkle proof HTTP call failed (from the burner’s per-batch proof fetch).
  • "proof-enrichment" — enrichWithMerkleProof failed to attach a proof entry to a scanned note (missing proof for the note’s insertion index).

​
ClaimUtxoError

Thrown by all three burner factory functions in @umbra-privacy/sdk/burn. 
class ClaimUtxoError extends UmbraError {
  readonly stage: ClaimUtxoStage;
}

function isClaimUtxoError(error: unknown): error is ClaimUtxoError;
Stage values:
  • "initialization" - Factory construction failed.
  • "validation" — invalid Stealth Pool Note data or parameters.
  • "key-derivation" - Key derivation from master seed failed.
  • "zk-proof-generation" - Groth16 proof generation failed.
  • "pda-derivation" - Failed to derive required PDAs.
  • "instruction-build" - Failed to construct the instruction.
  • "transaction-build" - Blockhash fetch or transaction assembly failed.
  • "transaction-compile" - Failed to compile the transaction.
  • "transaction-sign" - Wallet rejected signing.
  • "transaction-validate" — pre-flight simulation failed. Often indicates a stale Merkle proof — the burner refetches the proof on a retry, so just re-run the burn.
  • "transaction-send" - Confirmation timed out. Verify on-chain before retrying - the nullifier may have been burned.

​
QueryError

Thrown by getUserAccountQuerierFunction and getEncryptedBalanceQuerierFunction. 
class QueryError extends UmbraError {
  readonly stage: QueryStage;
}

function isQueryError(error: unknown): error is QueryError;
Stage values:
  • "initialization" — factory-level validation failed.
  • "pda-derivation" — PDA address generation failed.
  • "account-fetch" — RPC fetch failed (node unreachable or returned an error).
  • "account-decode" — on-chain account data could not be decoded. Unexpected on-chain state.
  • "key-derivation" — X25519 key derivation failed (encrypted balance query only).
  • "decryption" — Rescue cipher decryption failed (encrypted balance query only).

​
AccountError

Thrown by every factory in @umbra-privacy/sdk/account — staged-token recoverers (getStagedSolRecovererFunction, getStagedSplRecovererFunction), key rotators (getUserEncryptionKeyRotatorFunction, getMasterViewingKeyRotatorFunction, getMintEncryptionKeyRotatorFunction), and entropy-seed rotators (getUserEntropySeedRotatorFunction, getTokenEntropySeedRotatorFunction). 
class AccountError extends UmbraError {
  readonly stage: AccountStage;
}

function isAccountError(error: unknown): error is AccountError;
Stage values: "initialization" | "validation" | "account-fetch" | "account-decode" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send". "zk-proof-generation" is only reachable from getMasterViewingKeyRotatorFunction (the only account operation that runs a ZK proof).

​
ComplianceError

Thrown by every factory in @umbra-privacy/sdk/compliance — grant issuer / revoker / queriers / re-encryptors. 
class ComplianceError extends UmbraError {
  readonly stage: ComplianceStage;
}

function isComplianceError(error: unknown): error is ComplianceError;
Stage values: "initialization" | "validation" | "key-derivation" | "pda-derivation" | "account-fetch" | "account-decode" | "decryption" | "reencryption" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send". "decryption" / "reencryption" are only reachable from the re-encryptor factories (getSharedCiphertextReencryptorForUserGrantFunction, etc.). The grant lifecycle factories (issue / revoke) never hit those stages.

​
Base Error Primitives

These are the underlying error types. All staged errors extend UmbraError.

​
UmbraError

Base class for all SDK errors. 
class UmbraError extends Error {
  constructor(
    message: string,
    options?: {
      code?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly code: string;          // Machine-readable code. Defaults to "UMBRA_ERROR".
  readonly context?: Record<string, unknown>;
  override readonly cause?: unknown;
}

function isUmbraError(error: unknown): error is UmbraError;

​
CryptographyError

Thrown when a cryptographic operation fails - most commonly ZK proof generation or Rescue cipher encryption/decryption. 
class CryptographyError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      operation?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly operation?: string;    // Name of the failed operation, e.g. "groth16-prove".
}

function isCryptographyError(error: unknown): error is CryptographyError;

​
InstructionError

Thrown when instruction construction fails - typically a protocol state mismatch or missing on-chain account. 
class InstructionError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      instructionName?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly instructionName?: string;    // Name of the instruction that failed to build.
}

function isInstructionError(error: unknown): error is InstructionError;

​
RpcError

Thrown when an RPC or indexer HTTP call fails. 
class RpcError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      endpoint?: string;
      statusCode?: number;
      rpcErrorCode?: number;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly endpoint?: string;       // The URL that was called.
  readonly statusCode?: number;     // HTTP status code (e.g. 429 for rate limit, 503 for unavailable).
  readonly rpcErrorCode?: number;   // JSON-RPC error code from the node.
}

function isRpcError(error: unknown): error is RpcError;

​
TransactionError

Thrown when a transaction fails on-chain (simulation rejection or network rejection). 
class TransactionError extends UmbraError {
  constructor(
    message: string,
    options?: {
      code?: string;
      signature?: string;
      simulationLogs?: string[];
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly signature?: string;          // Base58 tx signature. Present even on failure - tx may have landed.
  readonly simulationLogs?: string[]    // Program log output from pre-flight simulation.
}

function isTransactionError(error: unknown): error is TransactionError;

​
TransactionSigningError

Thrown when a wallet rejects a transaction signing request. Extends TransactionError. 
class TransactionSigningError extends TransactionError {
  constructor(
    message: string,
    options?: {
      code?: string;
      wasRejected?: boolean;
      signerAddress?: string;
      signature?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );

  readonly wasRejected: boolean;      // true = user explicitly cancelled; false = wallet error.
  readonly signerAddress?: string;    // Address of the wallet that rejected.
}

function isTransactionSigningError(error: unknown): error is TransactionSigningError;

​
MasterSeedSigningRejectedError

Thrown when the user declines to sign the master seed derivation message. Extends TransactionSigningError. Always has wasRejected: true. Error code: "MASTER_SEED_SIGNING_REJECTED". This surfaces during the first operation that needs key material in a session - typically register(), or getUmbraClient() in non-deferred mode. 
class MasterSeedSigningRejectedError extends TransactionSigningError {
  constructor(
    message?: string,
    options?: {
      signerAddress?: string;
      context?: Record<string, unknown>;
      cause?: unknown;
    },
  );
}

​
Retry Strategy

  • "transaction-sign" / MasterSeedSigningRejectedError - Do not retry. User cancelled. Never auto-retry a wallet prompt rejection.
  • "transaction-send" with a signature present - Check first. The transaction may have landed. Verify on-chain before submitting again to avoid double submissions.
  • "transaction-validate" - Fix inputs first. Pre-flight simulation failed. Diagnose the root cause before retrying.
  • "transaction-validate" for burns — may indicate a stale Merkle proof. Re-run the burner; it fetches a fresh per-batch proof on each attempt.
  • isRpcError - Safe to retry with exponential backoff. Transient network issue.
  • All other stages - Safe to retry with exponential backoff.