@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/errors-DAIrstEL.d.cts

@@ -0,0 +1,300 @@
+import { U as UmbraError } from './errors-B9EoPeWV.cjs';
+
+/**
+ * Arcium Error Classes
+ *
+ * Provides error classes for Arcium MPC computation monitoring failures.
+ * Each error carries a {@link ComputationMonitorStage} field that identifies
+ * exactly where in the monitoring pipeline the failure occurred.
+ *
+ * @module arcium/errors
+ * @since 2.0.0
+ */
+
+/**
+ * Stage of the computation monitoring operation where an error occurred.
+ *
+ * @remarks
+ * Each stage represents a distinct phase in the monitoring flow:
+ *
+ * - `subscription` — WebSocket subscription setup or notification stream failed
+ * - `account-fetch` — HTTP RPC fetch of the ComputationAccount failed
+ * - `account-decode` — Failed to decode the ComputationAccount from raw bytes
+ * - `timeout` — Monitoring timed out before the computation finalized
+ * - `signature-retrieval` — `getSignaturesForAddress` call failed after finalization
+ *
+ * @since 2.0.0
+ * @public
+ */
+type ComputationMonitorStage = "subscription" | "account-fetch" | "account-decode" | "timeout" | "signature-retrieval";
+/**
+ * Error thrown when a computation monitoring operation fails.
+ *
+ * @remarks
+ * Thrown by {@link ComputationMonitor} implementations when the monitoring
+ * loop encounters an unrecoverable failure. The {@link stage} field identifies
+ * exactly where in the monitoring pipeline the failure occurred, enabling
+ * callers to implement targeted recovery strategies.
+ *
+ * The error code follows the format `COMPUTATION_MONITOR_{STAGE}` where
+ * `{STAGE}` is the uppercase, underscore-delimited stage name.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await monitor.awaitComputation(computationAddress, {
+ *     timeoutMs: 60_000,
+ *   });
+ * } catch (error) {
+ *   if (isComputationMonitorError(error)) {
+ *     switch (error.stage) {
+ *       case "timeout":
+ *         console.log("MPC computation did not finalize in time");
+ *         break;
+ *       case "subscription":
+ *         console.log("WebSocket connection failed — try polling monitor");
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @public
+ */
+declare class ComputationMonitorError extends UmbraError {
+    /** The monitoring stage where the failure occurred. */
+    readonly stage: ComputationMonitorStage;
+    /**
+     * @param stage - The monitoring pipeline stage where the failure occurred.
+     * @param message - A human-readable description of the error.
+     * @param cause - The underlying error that caused this failure, if any.
+     */
+    constructor(stage: ComputationMonitorStage, message: string, cause?: Error);
+}
+/**
+ * Type guard to check if a value is a {@link ComputationMonitorError}.
+ *
+ * @param error - The value to test.
+ * @returns `true` and narrows `error` to {@link ComputationMonitorError} when
+ *   the value is an instance of `ComputationMonitorError`.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (isComputationMonitorError(error)) {
+ *     console.log(error.stage); // TypeScript knows this is ComputationMonitorStage
+ *   }
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @public
+ */
+declare function isComputationMonitorError(error: unknown): error is ComputationMonitorError;
+
+/**
+ * Umbra Error Classes
+ *
+ * This module provides error classes for all Umbra SDK operation failures,
+ * each carrying a `stage` field that identifies exactly where in the pipeline
+ * the failure occurred.
+ *
+ * @since 2.0.0
+ * @module umbra/errors
+ */
+
+/**
+ * Stage of the encrypted deposit operation where an error occurred.
+ *
+ * Each stage represents a distinct phase in the deposit flow:
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `mint-fetch` | Failed to fetch mint account data |
+ * | `fee-calculation` | Failed to calculate transfer fee |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `account-fetch` | Failed to fetch account data from RPC |
+ * | `instruction-build` | Failed to build the deposit instruction |
+ * | `transaction-build` | Failed to build transaction message |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Failed to sign the transaction |
+ * | `transaction-validate` | Transaction validation failed |
+ * | `transaction-send` | Failed to send or confirm the transaction |
+ */
+type EncryptedDepositStage = "initialization" | "validation" | "mint-fetch" | "fee-calculation" | "pda-derivation" | "account-fetch" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when an encrypted deposit operation fails. */
+declare class EncryptedDepositError extends UmbraError {
+    readonly stage: EncryptedDepositStage;
+    constructor(stage: EncryptedDepositStage, message: string, cause?: Error);
+}
+/** Type guard to check if an error is an EncryptedDepositError. */
+declare function isEncryptedDepositError(error: unknown): error is EncryptedDepositError;
+/**
+ * Stage of the encrypted withdrawal operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `mint-fetch` | Failed to fetch mint account data |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build the withdrawal instruction |
+ * | `transaction-build` | Failed to build transaction message |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Failed to sign the transaction |
+ * | `transaction-send` | Failed to send or confirm the transaction |
+ */
+type EncryptedWithdrawalStage = "initialization" | "validation" | "mint-fetch" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-send";
+/** Error thrown when an encrypted withdrawal operation fails. */
+declare class EncryptedWithdrawalError extends UmbraError {
+    readonly stage: EncryptedWithdrawalStage;
+    constructor(stage: EncryptedWithdrawalStage, message: string, cause?: Error);
+}
+/** Type guard to check if an error is an EncryptedWithdrawalError. */
+declare function isEncryptedWithdrawalError(error: unknown): error is EncryptedWithdrawalError;
+/**
+ * Stage of the user registration operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `master-seed-derivation` | Master seed signing was rejected or failed |
+ * | `account-fetch` | RPC call to read existing registration state failed |
+ * | `key-derivation` | Cryptographic key derivation from master seed failed |
+ * | `zk-proof-generation` | Groth16 proof generation failed (anonymous step) |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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` | Transaction sent but confirmation timed out |
+ */
+type RegistrationStage = "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";
+/** Error thrown when a user registration operation fails. */
+declare class RegistrationError extends UmbraError {
+    readonly stage: RegistrationStage;
+    constructor(stage: RegistrationStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a RegistrationError. */
+declare function isRegistrationError(error: unknown): error is RegistrationError;
+/**
+ * Stage of the MXE-to-Shared conversion operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `account-fetch` | Batch RPC fetch of token account PDAs failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build a conversion instruction |
+ * | `transaction-build` | Blockhash fetch or transaction assembly failed |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Wallet rejected signing for a per-mint transaction |
+ * | `transaction-validate` | Pre-flight simulation failed |
+ * | `transaction-send` | Transaction sent but confirmation timed out |
+ */
+type ConversionStage = "initialization" | "account-fetch" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when an MXE-to-Shared conversion operation fails. */
+declare class ConversionError extends UmbraError {
+    readonly stage: ConversionStage;
+    constructor(stage: ConversionStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a ConversionError. */
+declare function isConversionError(error: unknown): error is ConversionError;
+/**
+ * Stage of a UTXO creation operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `account-fetch` | Failed to fetch recipient or token account data |
+ * | `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` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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` | Transaction sent but confirmation timed out |
+ */
+type CreateUtxoStage = "initialization" | "validation" | "account-fetch" | "mint-fetch" | "fee-calculation" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when a UTXO creation operation fails. */
+declare class CreateUtxoError extends UmbraError {
+    readonly stage: CreateUtxoStage;
+    constructor(stage: CreateUtxoStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a CreateUtxoError. */
+declare function isCreateUtxoError(error: unknown): error is CreateUtxoError;
+/**
+ * Stage of a UTXO fetch operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory construction failed — missing indexerApiEndpoint |
+ * | `validation` | Invalid tree index or insertion index parameters |
+ * | `key-derivation` | X25519 private key derivation from master seed failed |
+ * | `indexer-fetch` | Indexer HTTP call failed |
+ * | `proof-fetch` | Merkle proof HTTP call failed |
+ */
+type FetchUtxosStage = "initialization" | "validation" | "key-derivation" | "indexer-fetch" | "proof-fetch" | "proof-enrichment";
+/** Error thrown when a UTXO fetch operation fails. */
+declare class FetchUtxosError extends UmbraError {
+    readonly stage: FetchUtxosStage;
+    constructor(stage: FetchUtxosStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a FetchUtxosError. */
+declare function isFetchUtxosError(error: unknown): error is FetchUtxosError;
+/**
+ * Stage of a UTXO claim operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Invalid UTXO data or Merkle proof parameters |
+ * | `key-derivation` | Key derivation from master seed failed |
+ * | `zk-proof-generation` | Groth16 proof generation failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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 — also surfaces stale Merkle proof |
+ * | `transaction-send` | Transaction sent but confirmation timed out |
+ */
+type ClaimUtxoStage = "initialization" | "validation" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when a UTXO claim operation fails. */
+declare class ClaimUtxoError extends UmbraError {
+    readonly stage: ClaimUtxoStage;
+    constructor(stage: ClaimUtxoStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a ClaimUtxoError. */
+declare function isClaimUtxoError(error: unknown): error is ClaimUtxoError;
+/**
+ * Stage of a query operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `account-fetch` | RPC fetch failed |
+ * | `account-decode` | On-chain account data could not be decoded |
+ * | `key-derivation` | X25519 key derivation failed (encrypted balance query) |
+ * | `decryption` | Rescue cipher decryption failed (encrypted balance query) |
+ */
+type QueryStage = "initialization" | "pda-derivation" | "account-fetch" | "account-decode" | "key-derivation" | "decryption";
+/** Error thrown when a query operation fails. */
+declare class QueryError extends UmbraError {
+    readonly stage: QueryStage;
+    constructor(stage: QueryStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a QueryError. */
+declare function isQueryError(error: unknown): error is QueryError;
+
+export { ClaimUtxoError as C, EncryptedDepositError as E, FetchUtxosError as F, QueryError as Q, RegistrationError as R, type ClaimUtxoStage as a, ComputationMonitorError as b, type ComputationMonitorStage as c, ConversionError as d, type ConversionStage as e, CreateUtxoError as f, type CreateUtxoStage as g, type EncryptedDepositStage as h, EncryptedWithdrawalError as i, type EncryptedWithdrawalStage as j, type FetchUtxosStage as k, type QueryStage as l, type RegistrationStage as m, isClaimUtxoError as n, isComputationMonitorError as o, isConversionError as p, isCreateUtxoError as q, isEncryptedDepositError as r, isEncryptedWithdrawalError as s, isFetchUtxosError as t, isQueryError as u, isRegistrationError as v };

package/dist/errors-DPNMfyh0.d.ts

@@ -0,0 +1,300 @@
+import { U as UmbraError } from './errors-B9EoPeWV.js';
+
+/**
+ * Arcium Error Classes
+ *
+ * Provides error classes for Arcium MPC computation monitoring failures.
+ * Each error carries a {@link ComputationMonitorStage} field that identifies
+ * exactly where in the monitoring pipeline the failure occurred.
+ *
+ * @module arcium/errors
+ * @since 2.0.0
+ */
+
+/**
+ * Stage of the computation monitoring operation where an error occurred.
+ *
+ * @remarks
+ * Each stage represents a distinct phase in the monitoring flow:
+ *
+ * - `subscription` — WebSocket subscription setup or notification stream failed
+ * - `account-fetch` — HTTP RPC fetch of the ComputationAccount failed
+ * - `account-decode` — Failed to decode the ComputationAccount from raw bytes
+ * - `timeout` — Monitoring timed out before the computation finalized
+ * - `signature-retrieval` — `getSignaturesForAddress` call failed after finalization
+ *
+ * @since 2.0.0
+ * @public
+ */
+type ComputationMonitorStage = "subscription" | "account-fetch" | "account-decode" | "timeout" | "signature-retrieval";
+/**
+ * Error thrown when a computation monitoring operation fails.
+ *
+ * @remarks
+ * Thrown by {@link ComputationMonitor} implementations when the monitoring
+ * loop encounters an unrecoverable failure. The {@link stage} field identifies
+ * exactly where in the monitoring pipeline the failure occurred, enabling
+ * callers to implement targeted recovery strategies.
+ *
+ * The error code follows the format `COMPUTATION_MONITOR_{STAGE}` where
+ * `{STAGE}` is the uppercase, underscore-delimited stage name.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await monitor.awaitComputation(computationAddress, {
+ *     timeoutMs: 60_000,
+ *   });
+ * } catch (error) {
+ *   if (isComputationMonitorError(error)) {
+ *     switch (error.stage) {
+ *       case "timeout":
+ *         console.log("MPC computation did not finalize in time");
+ *         break;
+ *       case "subscription":
+ *         console.log("WebSocket connection failed — try polling monitor");
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @public
+ */
+declare class ComputationMonitorError extends UmbraError {
+    /** The monitoring stage where the failure occurred. */
+    readonly stage: ComputationMonitorStage;
+    /**
+     * @param stage - The monitoring pipeline stage where the failure occurred.
+     * @param message - A human-readable description of the error.
+     * @param cause - The underlying error that caused this failure, if any.
+     */
+    constructor(stage: ComputationMonitorStage, message: string, cause?: Error);
+}
+/**
+ * Type guard to check if a value is a {@link ComputationMonitorError}.
+ *
+ * @param error - The value to test.
+ * @returns `true` and narrows `error` to {@link ComputationMonitorError} when
+ *   the value is an instance of `ComputationMonitorError`.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (isComputationMonitorError(error)) {
+ *     console.log(error.stage); // TypeScript knows this is ComputationMonitorStage
+ *   }
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @public
+ */
+declare function isComputationMonitorError(error: unknown): error is ComputationMonitorError;
+
+/**
+ * Umbra Error Classes
+ *
+ * This module provides error classes for all Umbra SDK operation failures,
+ * each carrying a `stage` field that identifies exactly where in the pipeline
+ * the failure occurred.
+ *
+ * @since 2.0.0
+ * @module umbra/errors
+ */
+
+/**
+ * Stage of the encrypted deposit operation where an error occurred.
+ *
+ * Each stage represents a distinct phase in the deposit flow:
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `mint-fetch` | Failed to fetch mint account data |
+ * | `fee-calculation` | Failed to calculate transfer fee |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `account-fetch` | Failed to fetch account data from RPC |
+ * | `instruction-build` | Failed to build the deposit instruction |
+ * | `transaction-build` | Failed to build transaction message |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Failed to sign the transaction |
+ * | `transaction-validate` | Transaction validation failed |
+ * | `transaction-send` | Failed to send or confirm the transaction |
+ */
+type EncryptedDepositStage = "initialization" | "validation" | "mint-fetch" | "fee-calculation" | "pda-derivation" | "account-fetch" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when an encrypted deposit operation fails. */
+declare class EncryptedDepositError extends UmbraError {
+    readonly stage: EncryptedDepositStage;
+    constructor(stage: EncryptedDepositStage, message: string, cause?: Error);
+}
+/** Type guard to check if an error is an EncryptedDepositError. */
+declare function isEncryptedDepositError(error: unknown): error is EncryptedDepositError;
+/**
+ * Stage of the encrypted withdrawal operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `mint-fetch` | Failed to fetch mint account data |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build the withdrawal instruction |
+ * | `transaction-build` | Failed to build transaction message |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Failed to sign the transaction |
+ * | `transaction-send` | Failed to send or confirm the transaction |
+ */
+type EncryptedWithdrawalStage = "initialization" | "validation" | "mint-fetch" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-send";
+/** Error thrown when an encrypted withdrawal operation fails. */
+declare class EncryptedWithdrawalError extends UmbraError {
+    readonly stage: EncryptedWithdrawalStage;
+    constructor(stage: EncryptedWithdrawalStage, message: string, cause?: Error);
+}
+/** Type guard to check if an error is an EncryptedWithdrawalError. */
+declare function isEncryptedWithdrawalError(error: unknown): error is EncryptedWithdrawalError;
+/**
+ * Stage of the user registration operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `master-seed-derivation` | Master seed signing was rejected or failed |
+ * | `account-fetch` | RPC call to read existing registration state failed |
+ * | `key-derivation` | Cryptographic key derivation from master seed failed |
+ * | `zk-proof-generation` | Groth16 proof generation failed (anonymous step) |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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` | Transaction sent but confirmation timed out |
+ */
+type RegistrationStage = "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";
+/** Error thrown when a user registration operation fails. */
+declare class RegistrationError extends UmbraError {
+    readonly stage: RegistrationStage;
+    constructor(stage: RegistrationStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a RegistrationError. */
+declare function isRegistrationError(error: unknown): error is RegistrationError;
+/**
+ * Stage of the MXE-to-Shared conversion operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `account-fetch` | Batch RPC fetch of token account PDAs failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build a conversion instruction |
+ * | `transaction-build` | Blockhash fetch or transaction assembly failed |
+ * | `transaction-compile` | Failed to compile the transaction |
+ * | `transaction-sign` | Wallet rejected signing for a per-mint transaction |
+ * | `transaction-validate` | Pre-flight simulation failed |
+ * | `transaction-send` | Transaction sent but confirmation timed out |
+ */
+type ConversionStage = "initialization" | "account-fetch" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when an MXE-to-Shared conversion operation fails. */
+declare class ConversionError extends UmbraError {
+    readonly stage: ConversionStage;
+    constructor(stage: ConversionStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a ConversionError. */
+declare function isConversionError(error: unknown): error is ConversionError;
+/**
+ * Stage of a UTXO creation operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Input parameter validation failed |
+ * | `account-fetch` | Failed to fetch recipient or token account data |
+ * | `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` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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` | Transaction sent but confirmation timed out |
+ */
+type CreateUtxoStage = "initialization" | "validation" | "account-fetch" | "mint-fetch" | "fee-calculation" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when a UTXO creation operation fails. */
+declare class CreateUtxoError extends UmbraError {
+    readonly stage: CreateUtxoStage;
+    constructor(stage: CreateUtxoStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a CreateUtxoError. */
+declare function isCreateUtxoError(error: unknown): error is CreateUtxoError;
+/**
+ * Stage of a UTXO fetch operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory construction failed — missing indexerApiEndpoint |
+ * | `validation` | Invalid tree index or insertion index parameters |
+ * | `key-derivation` | X25519 private key derivation from master seed failed |
+ * | `indexer-fetch` | Indexer HTTP call failed |
+ * | `proof-fetch` | Merkle proof HTTP call failed |
+ */
+type FetchUtxosStage = "initialization" | "validation" | "key-derivation" | "indexer-fetch" | "proof-fetch" | "proof-enrichment";
+/** Error thrown when a UTXO fetch operation fails. */
+declare class FetchUtxosError extends UmbraError {
+    readonly stage: FetchUtxosStage;
+    constructor(stage: FetchUtxosStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a FetchUtxosError. */
+declare function isFetchUtxosError(error: unknown): error is FetchUtxosError;
+/**
+ * Stage of a UTXO claim operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `validation` | Invalid UTXO data or Merkle proof parameters |
+ * | `key-derivation` | Key derivation from master seed failed |
+ * | `zk-proof-generation` | Groth16 proof generation failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `instruction-build` | Failed to build an 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 — also surfaces stale Merkle proof |
+ * | `transaction-send` | Transaction sent but confirmation timed out |
+ */
+type ClaimUtxoStage = "initialization" | "validation" | "key-derivation" | "zk-proof-generation" | "pda-derivation" | "instruction-build" | "transaction-build" | "transaction-compile" | "transaction-sign" | "transaction-validate" | "transaction-send";
+/** Error thrown when a UTXO claim operation fails. */
+declare class ClaimUtxoError extends UmbraError {
+    readonly stage: ClaimUtxoStage;
+    constructor(stage: ClaimUtxoStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a ClaimUtxoError. */
+declare function isClaimUtxoError(error: unknown): error is ClaimUtxoError;
+/**
+ * Stage of a query operation where an error occurred.
+ *
+ * | Stage | Description |
+ * |-------|-------------|
+ * | `initialization` | Factory-level validation failed |
+ * | `pda-derivation` | PDA address generation failed |
+ * | `account-fetch` | RPC fetch failed |
+ * | `account-decode` | On-chain account data could not be decoded |
+ * | `key-derivation` | X25519 key derivation failed (encrypted balance query) |
+ * | `decryption` | Rescue cipher decryption failed (encrypted balance query) |
+ */
+type QueryStage = "initialization" | "pda-derivation" | "account-fetch" | "account-decode" | "key-derivation" | "decryption";
+/** Error thrown when a query operation fails. */
+declare class QueryError extends UmbraError {
+    readonly stage: QueryStage;
+    constructor(stage: QueryStage, message: string, cause?: unknown);
+}
+/** Type guard to check if an error is a QueryError. */
+declare function isQueryError(error: unknown): error is QueryError;
+
+export { ClaimUtxoError as C, EncryptedDepositError as E, FetchUtxosError as F, QueryError as Q, RegistrationError as R, type ClaimUtxoStage as a, ComputationMonitorError as b, type ComputationMonitorStage as c, ConversionError as d, type ConversionStage as e, CreateUtxoError as f, type CreateUtxoStage as g, type EncryptedDepositStage as h, EncryptedWithdrawalError as i, type EncryptedWithdrawalStage as j, type FetchUtxosStage as k, type QueryStage as l, type RegistrationStage as m, isClaimUtxoError as n, isComputationMonitorError as o, isConversionError as p, isCreateUtxoError as q, isEncryptedDepositError as r, isEncryptedWithdrawalError as s, isFetchUtxosError as t, isQueryError as u, isRegistrationError as v };