@umbra-privacy/sdk 1.0.0 → 2.0.1

package/dist/chunk-4RHXVBNI.js

@@ -0,0 +1,203 @@
+import { __name } from './chunk-7QVYU63E.js';
+import { address } from '@solana/kit';
+
+var ENDPOINTS = {
+  /** Fetches relayer address, supported mints, and active stealth pool indices. */
+  RELAYER_INFO: `/v1/relayer/info`,
+  /** Submits a claim request (relayer builds transactions from crypto data). */
+  CLAIM_SUBMIT: `/v1/claims`,
+  /** Polls claim status by request ID. `{id}` is replaced at call time. */
+  CLAIM_STATUS: `/v1/claims/{id}`
+};
+var RelayerError = class _RelayerError extends Error {
+  static {
+    __name(this, "RelayerError");
+  }
+  /** The relayer operation that failed (e.g. `"getRelayerAddress"`, `"claimSubmit"`). */
+  operation;
+  /** HTTP status code if the server responded, `undefined` for transport errors. */
+  statusCode;
+  /** Machine-readable error code from the API error body. */
+  errorCode;
+  constructor(operation, message, statusCode, errorCode, cause) {
+    super(`Relayer operation '${operation}' failed: ${message}`);
+    this.name = "RelayerError";
+    this.operation = operation;
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.cause = cause;
+    if (Error.captureStackTrace !== void 0) {
+      Error.captureStackTrace(this, _RelayerError);
+    }
+  }
+};
+async function makeRequest(endpoint, fetchImpl, options) {
+  const { method = "GET", body, operation } = options;
+  try {
+    const requestInit = {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json"
+      }
+    };
+    if (body !== void 0) {
+      requestInit.body = JSON.stringify(body);
+    }
+    const response = await fetchImpl(endpoint, requestInit);
+    const data = await response.json();
+    if (!response.ok) {
+      const errorData = data;
+      const message = errorData.error?.message ?? errorData.message ?? `HTTP ${String(response.status)}`;
+      const code = errorData.error?.code ?? errorData.error_code;
+      throw new RelayerError(operation, message, response.status, code);
+    }
+    return data;
+  } catch (error) {
+    if (error instanceof RelayerError) {
+      throw error;
+    }
+    throw new RelayerError(
+      operation,
+      error instanceof Error ? error.message : "Unknown error",
+      void 0,
+      void 0,
+      error instanceof Error ? error : void 0
+    );
+  }
+}
+__name(makeRequest, "makeRequest");
+function convertClaimStatusResponse(api) {
+  return {
+    requestId: api.request_id,
+    status: api.status,
+    variant: api.variant,
+    resolvedVariant: api.resolved_variant,
+    txSignature: api.tx_signature,
+    callbackSignature: api.callback_signature,
+    computationAccount: api.computation_account,
+    failureReason: api.failure_reason,
+    createdAt: api.created_at,
+    updatedAt: api.updated_at
+  };
+}
+__name(convertClaimStatusResponse, "convertClaimStatusResponse");
+function getUmbraRelayer(args, deps) {
+  const { apiEndpoint } = args;
+  const fetchImpl = deps?.fetch ?? globalThis.fetch;
+  if (apiEndpoint === "") {
+    throw new RelayerError("initialization", "apiEndpoint must be a non-empty string");
+  }
+  const normalizedEndpoint = apiEndpoint.replace(/\/$/, "");
+  let cachedAddress = null;
+  let cachedInfo = null;
+  async function fetchInfo() {
+    if (cachedInfo !== null) {
+      return cachedInfo;
+    }
+    const response = await makeRequest(
+      `${normalizedEndpoint}${ENDPOINTS.RELAYER_INFO}`,
+      fetchImpl,
+      { operation: "getRelayerInfo" }
+    );
+    cachedInfo = response;
+    cachedAddress = address(response.address);
+    return response;
+  }
+  __name(fetchInfo, "fetchInfo");
+  return {
+    apiEndpoint: normalizedEndpoint,
+    async getFeePayer() {
+      if (cachedAddress !== null) {
+        return cachedAddress;
+      }
+      const info = await fetchInfo();
+      return address(info.address);
+    },
+    async getRelayerAddress() {
+      if (cachedAddress !== null) {
+        return cachedAddress;
+      }
+      const info = await fetchInfo();
+      return address(info.address);
+    },
+    async getSupportedMints() {
+      const info = await fetchInfo();
+      return {
+        relayer: info.address,
+        mints: info.supported_mints,
+        count: BigInt(info.supported_mints.length)
+      };
+    },
+    async submitClaim(request) {
+      const response = await makeRequest(
+        `${normalizedEndpoint}${ENDPOINTS.CLAIM_SUBMIT}`,
+        fetchImpl,
+        { method: "POST", body: request, operation: "claimSubmit" }
+      );
+      return {
+        requestId: response.request_id,
+        status: response.status
+      };
+    },
+    async pollClaimStatus(requestId) {
+      const url = `${normalizedEndpoint}${ENDPOINTS.CLAIM_STATUS.replace("{id}", requestId)}`;
+      const response = await makeRequest(url, fetchImpl, {
+        operation: "claimStatus"
+      });
+      return convertClaimStatusResponse(response);
+    }
+  };
+}
+__name(getUmbraRelayer, "getUmbraRelayer");
+var TERMINAL_CLAIM_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "timed_out"
+]);
+async function pollClaimUntilTerminal(pollClaimStatus, requestId, options) {
+  const pollingIntervalMs = options?.pollingIntervalMs ?? 3e3;
+  const timeoutMs = options?.timeoutMs ?? 12e4;
+  const onProgress = options?.onProgress;
+  const startTime = Date.now();
+  while (true) {
+    const status = await pollClaimStatus(requestId);
+    if (onProgress !== void 0) {
+      onProgress({
+        requestId: status.requestId,
+        status: status.status,
+        resolvedVariant: status.resolvedVariant,
+        txSignature: status.txSignature,
+        callbackSignature: status.callbackSignature,
+        failureReason: status.failureReason
+      });
+    }
+    if (TERMINAL_CLAIM_STATUSES.has(status.status)) {
+      const result = {
+        requestId: status.requestId,
+        status: status.status,
+        txSignature: status.txSignature,
+        callbackSignature: status.callbackSignature,
+        resolvedVariant: status.resolvedVariant,
+        failureReason: status.failureReason
+      };
+      return result;
+    }
+    if (Date.now() - startTime >= timeoutMs) {
+      const timedOutResult = {
+        requestId: status.requestId,
+        status: "timed_out",
+        failureReason: `Polling timed out after ${String(timeoutMs)}ms (last status: ${String(status.status)})`
+      };
+      return timedOutResult;
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, pollingIntervalMs);
+    });
+  }
+}
+__name(pollClaimUntilTerminal, "pollClaimUntilTerminal");
+
+export { RelayerError, getUmbraRelayer, pollClaimUntilTerminal };
+//# sourceMappingURL=chunk-4RHXVBNI.js.map
+//# sourceMappingURL=chunk-4RHXVBNI.js.map

package/dist/chunk-4RHXVBNI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/umbra/relayer.ts"],"names":[],"mappings":"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","file":"chunk-4RHXVBNI.js","sourcesContent":["/**\n * Relayer Module (V2 API).\n *\n * @remarks\n * This module provides the `getUmbraRelayer` factory for creating relayer instances\n * that interact with the Umbra relayer's V2 API. The relayer builds, signs, and\n * submits claim transactions on behalf of users.\n *\n * **What is the Relayer?**\n * The Umbra relayer is a semi-trusted intermediary that submits privacy-preserving\n * transactions on behalf of users. It receives cryptographic data (ZK proofs,\n * nullifiers, linker encryptions) and builds all Solana transactions server-side.\n *\n * **Trust Model (Semi-Trusted):**\n * The relayer is SEMI-TRUSTED. It can observe transaction contents (amounts,\n * mints, timing) because it must broadcast them. However, it CANNOT:\n * - Steal funds — ZK proofs and nullifier commitments prevent double-spending\n * - Forge signatures — Transactions use cryptographic commitments verified on-chain\n * - Link sender to recipient — Merkle commitments and ZK proofs sever that link\n *\n * **API Endpoints Used:**\n * - `GET /v1/relayer/info` — Get relayer address, supported mints, active pools\n * - `POST /v1/claims` — Submit a claim request (relayer builds transactions)\n * - `GET /v1/claims/{id}` — Poll claim status\n *\n * @packageDocumentation\n */\n\nimport { address, type Address } from \"@solana/kit\";\nimport type { U32 } from \"../types\";\nimport type {\n  IUmbraRelayer,\n  GetUmbraRelayerArgs,\n  GetUmbraRelayerDeps,\n  SupportedMintsResponse,\n  ClaimRequest,\n  ClaimSubmitResponse,\n  ClaimStatusResponse,\n  ClaimStatus,\n  ClaimBatchResult,\n} from \"./interfaces\";\n\n// ============================================================================\n// Constants\n// ============================================================================\n\n/**\n * Canonical endpoint paths for all relayer API operations.\n * @internal\n */\nconst ENDPOINTS = {\n  /** Fetches relayer address, supported mints, and active stealth pool indices. */\n  RELAYER_INFO: `/v1/relayer/info`,\n  /** Submits a claim request (relayer builds transactions from crypto data). */\n  CLAIM_SUBMIT: `/v1/claims`,\n  /** Polls claim status by request ID. `{id}` is replaced at call time. */\n  CLAIM_STATUS: `/v1/claims/{id}`,\n} as const;\n\n// ============================================================================\n// Error Class\n// ============================================================================\n\n/**\n * Error class for relayer-related failures.\n *\n * @remarks\n * Thrown when relayer API calls fail due to network issues, invalid responses,\n * transaction rejections, or server errors. Provides structured fields for\n * programmatic error handling.\n *\n * @public\n */\nexport class RelayerError extends Error {\n  /** The relayer operation that failed (e.g. `\"getRelayerAddress\"`, `\"claimSubmit\"`). */\n  public readonly operation: string;\n  /** HTTP status code if the server responded, `undefined` for transport errors. */\n  public readonly statusCode: number | undefined;\n  /** Machine-readable error code from the API error body. */\n  public readonly errorCode: string | undefined;\n\n  constructor(\n    operation: string,\n    message: string,\n    statusCode?: number,\n    errorCode?: string,\n    cause?: Error,\n  ) {\n    super(`Relayer operation '${operation}' failed: ${message}`);\n    this.name = \"RelayerError\";\n    this.operation = operation;\n    this.statusCode = statusCode;\n    this.errorCode = errorCode;\n    this.cause = cause;\n\n    if (Error.captureStackTrace !== undefined) {\n      Error.captureStackTrace(this, RelayerError);\n    }\n  }\n}\n\n// ============================================================================\n// Internal Types (API Response Shapes)\n// ============================================================================\n\n/** @internal */\ninterface ApiErrorResponse {\n  error?: {\n    code: string;\n    message: string;\n  };\n  success?: false;\n  error_code?: string;\n  message?: string;\n}\n\n/** Shape of `GET /v1/relayer/info` response. @internal */\ninterface ApiRelayerInfoResponse {\n  address: string;\n  supported_mints: string[];\n  active_stealth_pool_indices: string[];\n}\n\n/** Shape of `POST /v1/claims` response. @internal */\ninterface ApiClaimSubmitResponse {\n  request_id: string;\n  status: \"received\";\n}\n\n/** Shape of `GET /v1/claims/{id}` response. @internal */\ninterface ApiClaimStatusResponse {\n  request_id: string;\n  status: string;\n  variant: string;\n  resolved_variant?: string;\n  tx_signature?: string;\n  callback_signature?: string;\n  computation_account?: string;\n  failure_reason?: string | null;\n  created_at: string;\n  updated_at: string;\n}\n\n// ============================================================================\n// Internal Helpers\n// ============================================================================\n\n/**\n * Generic HTTP request helper with structured error handling.\n * @internal\n */\nasync function makeRequest<T>(\n  endpoint: string,\n  fetchImpl: typeof globalThis.fetch,\n  options: {\n    method?: \"GET\" | \"POST\";\n    body?: unknown;\n    operation: string;\n  },\n): Promise<T> {\n  const { method = \"GET\", body, operation } = options;\n\n  try {\n    const requestInit: RequestInit = {\n      method,\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Accept: \"application/json\",\n      },\n    };\n    if (body !== undefined) {\n      requestInit.body = JSON.stringify(body);\n    }\n    const response = await fetchImpl(endpoint, requestInit);\n\n    const data = (await response.json()) as T | ApiErrorResponse;\n\n    if (!response.ok) {\n      const errorData = data as ApiErrorResponse;\n      const message =\n        errorData.error?.message ?? errorData.message ?? `HTTP ${String(response.status)}`;\n      const code = errorData.error?.code ?? errorData.error_code;\n      throw new RelayerError(operation, message, response.status, code);\n    }\n\n    return data as T;\n  } catch (error) {\n    if (error instanceof RelayerError) {\n      throw error;\n    }\n    throw new RelayerError(\n      operation,\n      error instanceof Error ? error.message : \"Unknown error\",\n      undefined,\n      undefined,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n\n/** Converts wire-format claim status response to SDK type. @internal */\nfunction convertClaimStatusResponse(api: ApiClaimStatusResponse): ClaimStatusResponse {\n  return {\n    requestId: api.request_id,\n    status: api.status as ClaimStatus,\n    variant: api.variant as ClaimStatusResponse[\"variant\"],\n    resolvedVariant: api.resolved_variant,\n    txSignature: api.tx_signature,\n    callbackSignature: api.callback_signature,\n    computationAccount: api.computation_account,\n    failureReason: api.failure_reason,\n    createdAt: api.created_at,\n    updatedAt: api.updated_at,\n  };\n}\n\n// ============================================================================\n// Core Relayer Factory\n// ============================================================================\n\n/**\n * Creates an Umbra relayer instance.\n *\n * @remarks\n * The returned `IUmbraRelayer` object provides all methods needed by claim\n * services: relayer info, claim submission, and status polling. Pass it\n * directly as the `relayer` dependency to any claim function.\n *\n * **Address caching:**\n * `getRelayerAddress()` and `getFeePayer()` cache the result after the first\n * HTTP call. The cache is per-instance.\n *\n * @param args - Required arguments\n * @param args.apiEndpoint - The base URL of the relayer API\n * @param deps - Optional dependencies for testing\n * @param deps.fetch - Custom fetch implementation; defaults to `globalThis.fetch`\n * @returns An {@link IUmbraRelayer} instance\n *\n * @example\n * ```typescript\n * const relayer = getUmbraRelayer({ apiEndpoint: \"https://relayer.umbra.finance\" });\n *\n * // Use directly with claim functions\n * const claim = getSelfClaimableUtxoToEncryptedBalanceClaimerFunction(\n *   { client },\n *   { zkProver, relayer },\n * );\n * ```\n *\n * @public\n */\nexport function getUmbraRelayer(\n  args: GetUmbraRelayerArgs,\n  deps?: GetUmbraRelayerDeps,\n): IUmbraRelayer {\n  const { apiEndpoint } = args;\n  const fetchImpl = deps?.fetch ?? globalThis.fetch;\n\n  if (apiEndpoint === \"\") {\n    throw new RelayerError(\"initialization\", \"apiEndpoint must be a non-empty string\");\n  }\n\n  const normalizedEndpoint = apiEndpoint.replace(/\\/$/, \"\");\n\n  // Shared cache for relayer address (used by both getFeePayer and getRelayerAddress)\n  let cachedAddress: Address | null = null;\n  let cachedInfo: ApiRelayerInfoResponse | null = null;\n\n  async function fetchInfo(): Promise<ApiRelayerInfoResponse> {\n    if (cachedInfo !== null) {\n      return cachedInfo;\n    }\n    const response = await makeRequest<ApiRelayerInfoResponse>(\n      `${normalizedEndpoint}${ENDPOINTS.RELAYER_INFO}`,\n      fetchImpl,\n      { operation: \"getRelayerInfo\" },\n    );\n    cachedInfo = response;\n    cachedAddress = address(response.address);\n    return response;\n  }\n\n  return {\n    apiEndpoint: normalizedEndpoint,\n\n    async getFeePayer(): Promise<Address> {\n      if (cachedAddress !== null) {\n        return cachedAddress;\n      }\n      const info = await fetchInfo();\n      return address(info.address);\n    },\n\n    async getRelayerAddress(): Promise<Address> {\n      if (cachedAddress !== null) {\n        return cachedAddress;\n      }\n      const info = await fetchInfo();\n      return address(info.address);\n    },\n\n    async getSupportedMints(): Promise<SupportedMintsResponse> {\n      const info = await fetchInfo();\n      return {\n        relayer: info.address,\n        mints: info.supported_mints,\n        count: BigInt(info.supported_mints.length) as U32,\n      };\n    },\n\n    async submitClaim(request: ClaimRequest): Promise<ClaimSubmitResponse> {\n      const response = await makeRequest<ApiClaimSubmitResponse>(\n        `${normalizedEndpoint}${ENDPOINTS.CLAIM_SUBMIT}`,\n        fetchImpl,\n        { method: \"POST\", body: request, operation: \"claimSubmit\" },\n      );\n      return {\n        requestId: response.request_id,\n        status: response.status,\n      };\n    },\n\n    async pollClaimStatus(requestId: string): Promise<ClaimStatusResponse> {\n      const url = `${normalizedEndpoint}${ENDPOINTS.CLAIM_STATUS.replace(\"{id}\", requestId)}`;\n      const response = await makeRequest<ApiClaimStatusResponse>(url, fetchImpl, {\n        operation: \"claimStatus\",\n      });\n      return convertClaimStatusResponse(response);\n    },\n  };\n}\n\n// ============================================================================\n// Claim Polling Utility\n// ============================================================================\n\n/**\n * Terminal claim statuses. Polling stops when the status matches one of these.\n * @internal\n */\nconst TERMINAL_CLAIM_STATUSES: ReadonlySet<ClaimStatus> = new Set([\n  \"completed\",\n  \"failed\",\n  \"timed_out\",\n]);\n\n/**\n * Polls a claim request until it reaches a terminal status or times out.\n *\n * @remarks\n * Terminal statuses are: `completed`, `failed`, `timed_out`.\n * The `onProgress` callback is invoked after each poll with the latest status.\n *\n * @param pollClaimStatus - Function to poll claim status\n * @param requestId - The claim request ID to poll\n * @param options - Polling configuration\n * @returns The final {@link ClaimBatchResult}\n *\n * @public\n */\nexport async function pollClaimUntilTerminal(\n  pollClaimStatus: (requestId: string) => Promise<ClaimStatusResponse>,\n  requestId: string,\n  options?: {\n    pollingIntervalMs?: number;\n    timeoutMs?: number;\n    onProgress?: (event: {\n      readonly requestId: string;\n      readonly status: ClaimStatus;\n      readonly resolvedVariant?: string;\n      readonly txSignature?: string;\n      readonly callbackSignature?: string;\n      readonly failureReason?: string | null;\n    }) => void;\n  },\n): Promise<ClaimBatchResult> {\n  const pollingIntervalMs: number = options?.pollingIntervalMs ?? 3000;\n  const timeoutMs: number = options?.timeoutMs ?? 120_000;\n  const onProgress = options?.onProgress;\n\n  const startTime: number = Date.now();\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- polling loop\n  while (true) {\n    const status: ClaimStatusResponse = await pollClaimStatus(requestId);\n\n    if (onProgress !== undefined) {\n      onProgress({\n        requestId: status.requestId,\n        status: status.status,\n        resolvedVariant: status.resolvedVariant,\n        txSignature: status.txSignature,\n        callbackSignature: status.callbackSignature,\n        failureReason: status.failureReason,\n      });\n    }\n\n    if (TERMINAL_CLAIM_STATUSES.has(status.status)) {\n      const result: ClaimBatchResult = {\n        requestId: status.requestId,\n        status: status.status,\n        txSignature: status.txSignature,\n        callbackSignature: status.callbackSignature,\n        resolvedVariant: status.resolvedVariant,\n        failureReason: status.failureReason,\n      };\n      return result;\n    }\n\n    if (Date.now() - startTime >= timeoutMs) {\n      const timedOutResult: ClaimBatchResult = {\n        requestId: status.requestId,\n        status: \"timed_out\" as ClaimStatus,\n        failureReason: `Polling timed out after ${String(timeoutMs)}ms (last status: ${String(status.status)})`,\n      };\n      return timedOutResult;\n    }\n\n    await new Promise<void>((resolve) => {\n      setTimeout(resolve, pollingIntervalMs);\n    });\n  }\n}\n"]}

package/dist/chunk-4TZVXB5G.js

@@ -0,0 +1,324 @@
+import { __name } from './chunk-7QVYU63E.js';
+
+// src/common/errors.ts
+var UmbraError = class _UmbraError extends Error {
+  static {
+    __name(this, "UmbraError");
+  }
+  /**
+   * A machine-readable error code for programmatic error handling.
+   *
+   * @remarks
+   * Defaults to `"UMBRA_ERROR"` when no code is supplied in the constructor options.
+   * Sub-classes or specific throw sites should supply a more specific code to allow
+   * callers to branch on error identity without string-matching `message`.
+   *
+   * @readonly
+   */
+  code;
+  /**
+   * Additional context about the error.
+   *
+   * @remarks
+   * A free-form key-value map of diagnostic data attached to the error at the throw site.
+   * Useful for logging and debugging — consumers should not rely on specific keys for
+   * control flow; use `code` for programmatic branching instead.
+   *
+   * Will be `undefined` when no context was provided to the constructor.
+   *
+   * @readonly
+   */
+  context;
+  /**
+   * The original error that caused this error, if any.
+   *
+   * @remarks
+   * When an SDK function wraps a lower-level error (e.g., a failed RPC call or a
+   * cryptographic library error), it sets `cause` to the original thrown value so
+   * callers can inspect the full error chain.
+   *
+   * Will be `undefined` when there is no underlying cause.
+   *
+   * @readonly
+   */
+  cause;
+  /**
+   * Creates a new UmbraError.
+   *
+   * @param message - Human-readable description of what went wrong. Should be
+   *   actionable and specific enough for a developer to understand the failure
+   *   without reading source code.
+   * @param options - Optional structured metadata attached to the error.
+   * @param options.code - Machine-readable error code for programmatic branching.
+   *   Defaults to `"UMBRA_ERROR"` if omitted.
+   * @param options.context - Free-form diagnostic key-value pairs. Omit or set to
+   *   `undefined` to leave the `context` property unset.
+   * @param options.cause - The original error that triggered this one. Enables
+   *   full error-chain inspection. Omit or set to `undefined` when there is no
+   *   underlying cause.
+   *
+   * @defaultValue `options` — `undefined` (all options optional)
+   * @defaultValue `options.code` — `"UMBRA_ERROR"`
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "UmbraError";
+    this.code = options?.code ?? "UMBRA_ERROR";
+    if (options?.context !== void 0) {
+      this.context = options.context;
+    }
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+    Error.captureStackTrace(this, _UmbraError);
+  }
+};
+function isUmbraError(error) {
+  return error instanceof UmbraError;
+}
+__name(isUmbraError, "isUmbraError");
+var MathematicsAssertionError = class _MathematicsAssertionError extends Error {
+  static {
+    __name(this, "MathematicsAssertionError");
+  }
+  /**
+   * The actual value that failed the assertion.
+   *
+   * @remarks
+   * The runtime type reflects what was actually passed to the assertion function:
+   * - `bigint` for integer assertions (`assertU8`, `assertU256`, etc.)
+   * - `Uint8Array` for byte-array assertions (`assertU256LeBytes`, `assertU32LeBytes`, etc.)
+   * - Any other type when a non-numeric value was passed unexpectedly
+   *
+   * @readonly
+   */
+  value;
+  /**
+   * The type that was expected.
+   *
+   * @remarks
+   * Contains the branded type name exactly as it appears in the SDK type system,
+   * e.g., `"U8"`, `"U256"`, `"U32LeBytes"`. Use this for structured logging or
+   * to build user-facing error messages without parsing the `message` string.
+   *
+   * @readonly
+   */
+  expectedType;
+  /**
+   * Description of the constraint that was violated.
+   *
+   * @remarks
+   * Is `undefined` when only a type check failed (e.g., a `string` was passed where a
+   * `bigint` was expected). Contains a human-readable inequality or length rule when a
+   * value of the correct type was out of the allowed range.
+   *
+   * @example
+   * - `"0 <= value <= 255"` — U8 range violation
+   * - `"length === 32"` — U256LeBytes length violation
+   * - `"value >= 0"` — negative value passed to an unsigned integer assertion
+   *
+   * @readonly
+   */
+  constraint;
+  /**
+   * Creates a new MathematicsAssertionError.
+   *
+   * @param message - Human-readable description of the assertion failure. Should name
+   *   the assertion function, the expected type, and the constraint that was violated.
+   * @param options - Structured diagnostic details attached to the error.
+   * @param options.value - The actual value that was supplied and failed the assertion.
+   * @param options.expectedType - The name of the branded type that was expected
+   *   (e.g., `"U8"`, `"U256LeBytes"`).
+   * @param options.constraint - Optional human-readable constraint description
+   *   (e.g., `"0 <= value <= 255"`). Omit when the failure is a type mismatch rather
+   *   than a range violation.
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "MathematicsAssertionError";
+    this.value = options.value;
+    this.expectedType = options.expectedType;
+    this.constraint = options.constraint;
+    Error.captureStackTrace(this, _MathematicsAssertionError);
+    Object.setPrototypeOf(this, _MathematicsAssertionError.prototype);
+  }
+};
+var CryptographyAssertionError = class _CryptographyAssertionError extends Error {
+  static {
+    __name(this, "CryptographyAssertionError");
+  }
+  /**
+   * The actual value that failed the assertion.
+   *
+   * @remarks
+   * The runtime type reflects what was actually passed to the assertion function:
+   * - `bigint` for field element assertions (`assertBn254FieldElement`, etc.)
+   * - `Uint8Array` for byte-array assertions (`assertAesKey`, `assertX25519PrivateKey`, etc.)
+   * - Any other type when an entirely wrong value type was supplied
+   *
+   * @readonly
+   */
+  value;
+  /**
+   * The type that was expected (e.g., `"Bn254FieldElement"`, `"PoseidonKey"`, `"AesKey"`).
+   *
+   * @remarks
+   * Contains the branded type name exactly as it appears in the SDK type system.
+   * Use this property for structured logging without parsing the `message` string.
+   *
+   * @readonly
+   */
+  expectedType;
+  /**
+   * Description of the constraint that was violated.
+   *
+   * @remarks
+   * Is `undefined` for pure type-mismatch failures (e.g., `string` instead of `bigint`).
+   * Contains a human-readable constraint description for range and length violations
+   * (e.g., `"value < BN254_FIELD_PRIME"`, `"length === 32"`).
+   *
+   * @readonly
+   */
+  constraint;
+  /**
+   * Creates a new CryptographyAssertionError.
+   *
+   * @param message - Human-readable description of the assertion failure. Should name
+   *   the assertion function, the expected type, and the constraint that was violated.
+   * @param options - Structured diagnostic details attached to the error.
+   * @param options.value - The actual value that was supplied and failed the assertion.
+   * @param options.expectedType - The name of the branded cryptographic type that was
+   *   expected (e.g., `"Bn254FieldElement"`, `"AesKey"`).
+   * @param options.constraint - Optional human-readable constraint description.
+   *   Omit when the failure is a type mismatch rather than a range or length violation.
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "CryptographyAssertionError";
+    this.value = options.value;
+    this.expectedType = options.expectedType;
+    this.constraint = options.constraint;
+    Error.captureStackTrace(this, _CryptographyAssertionError);
+    Object.setPrototypeOf(this, _CryptographyAssertionError.prototype);
+  }
+};
+var SolanaAssertionError = class _SolanaAssertionError extends Error {
+  static {
+    __name(this, "SolanaAssertionError");
+  }
+  /**
+   * The actual value that failed the assertion.
+   *
+   * @remarks
+   * The runtime type reflects what was actually passed to the assertion function:
+   * - `string` for Base58-encoded assertions (`assertTransactionSignature`, etc.)
+   * - `Uint8Array` for byte-array assertions (`assertSignatureBytes`, etc.)
+   * - Any other type when a completely wrong value type was supplied
+   *
+   * @readonly
+   */
+  value;
+  /**
+   * The type that was expected (e.g., `"TransactionSignature"`, `"SignatureBytes"`).
+   *
+   * @remarks
+   * Contains the branded type name exactly as it appears in the SDK type system.
+   * Use this for structured logging without parsing the `message` string.
+   *
+   * @readonly
+   */
+  expectedType;
+  /**
+   * Description of the constraint that was violated.
+   *
+   * @remarks
+   * Is `undefined` for pure type-mismatch failures. Contains a human-readable rule
+   * for encoding or length violations (e.g., `"valid Base58"`, `"length === 64"`).
+   *
+   * @readonly
+   */
+  constraint;
+  /**
+   * Creates a new SolanaAssertionError.
+   *
+   * @param message - Human-readable description of the assertion failure. Should name
+   *   the assertion function, the expected type, and the constraint that was violated.
+   * @param options - Structured diagnostic details attached to the error.
+   * @param options.value - The actual value that was supplied and failed the assertion.
+   * @param options.expectedType - The name of the branded Solana type that was expected
+   *   (e.g., `"TransactionSignature"`, `"SignatureBytes"`).
+   * @param options.constraint - Optional human-readable constraint description.
+   *   Omit when the failure is a type mismatch rather than an encoding or length violation.
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "SolanaAssertionError";
+    this.value = options.value;
+    this.expectedType = options.expectedType;
+    this.constraint = options.constraint;
+    Error.captureStackTrace(this, _SolanaAssertionError);
+    Object.setPrototypeOf(this, _SolanaAssertionError.prototype);
+  }
+};
+var TemporalAssertionError = class extends Error {
+  static {
+    __name(this, "TemporalAssertionError");
+  }
+  /**
+   * The actual value that failed the assertion.
+   *
+   * @remarks
+   * Will be a `bigint` for all temporal assertions since the temporal types are
+   * BigInt-backed branded types (e.g., `Year`, `Month`, `Day`). May also be any
+   * other type when a non-bigint value was supplied unexpectedly.
+   *
+   * @readonly
+   */
+  value;
+  /**
+   * The type that was expected (e.g., `"Year"`, `"Month"`, `"Hour"`).
+   *
+   * @remarks
+   * Contains the branded temporal type name exactly as it appears in the SDK type system.
+   * Use this for structured logging without parsing the `message` string.
+   *
+   * @readonly
+   */
+  expectedType;
+  /**
+   * Description of the constraint that was violated.
+   *
+   * @remarks
+   * Contains a human-readable range rule for out-of-range values
+   * (e.g., `"1 <= value <= 12"` for a month violation). Is `undefined` only for
+   * pure type-mismatch failures (e.g., a `string` passed where a `bigint` was expected),
+   * which should not occur in normal usage.
+   *
+   * @readonly
+   */
+  constraint;
+  /**
+   * Creates a new TemporalAssertionError.
+   *
+   * @param message - Human-readable description of the assertion failure. Should name
+   *   the assertion function, the expected type, and the violated range constraint.
+   * @param details - Structured diagnostic details attached to the error.
+   * @param details.value - The actual `bigint` value (or other type) that was supplied
+   *   and failed the temporal assertion.
+   * @param details.expectedType - The name of the branded temporal type that was expected
+   *   (e.g., `"Year"`, `"Month"`, `"Hour"`).
+   * @param details.constraint - Optional human-readable range description
+   *   (e.g., `"1 <= value <= 12"`). Omit when the failure is a type mismatch.
+   */
+  constructor(message, details) {
+    super(message);
+    this.name = "TemporalAssertionError";
+    this.value = details.value;
+    this.expectedType = details.expectedType;
+    this.constraint = details.constraint;
+  }
+};
+
+export { CryptographyAssertionError, MathematicsAssertionError, SolanaAssertionError, TemporalAssertionError, UmbraError, isUmbraError };
+//# sourceMappingURL=chunk-4TZVXB5G.js.map
+//# sourceMappingURL=chunk-4TZVXB5G.js.map

package/dist/chunk-4TZVXB5G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/common/errors.ts"],"names":[],"mappings":"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","file":"chunk-4TZVXB5G.js","sourcesContent":["/**\n * Error Classes\n *\n * Centralized error hierarchy for the Umbra SDK.\n * Contains the base `UmbraError` and all domain-specific assertion error classes.\n *\n * @remarks\n * The SDK uses a two-level error hierarchy:\n *\n * 1. `UmbraError` — top-level base class for all SDK errors. Consumers can use\n *    `instanceof UmbraError` (or the `isUmbraError` type guard) to distinguish SDK errors\n *    from third-party or built-in errors in a catch block.\n *\n * 2. Domain assertion errors — thrown by type-assertion functions when a value fails\n *    validation. Each domain has its own class to make it easy to catch errors from a\n *    specific subsystem:\n *    - `MathematicsAssertionError` — thrown by `assertU8`, `assertU256`, etc.\n *    - `CryptographyAssertionError` — thrown by `assertBn254FieldElement`, `assertAesKey`, etc.\n *    - `SolanaAssertionError` — thrown by Solana-type assertion functions.\n *    - `TemporalAssertionError` — thrown by `assertYear`, `assertMonth`, etc.\n *\n * All four assertion error classes share the same three properties:\n * - `value` — the actual value that failed\n * - `expectedType` — the name of the expected branded type\n * - `constraint` — optional human-readable constraint description\n *\n * @packageDocumentation\n * @since 2.0.0\n * @module common/errors\n */\n\n/* =============================================================================\n * BASE ERROR\n *\n * The root error class for all Umbra SDK errors.\n * ============================================================================= */\n\n/**\n * Base error class for all Umbra SDK errors.\n *\n * All errors thrown by the SDK extend this class, allowing consumers\n * to distinguish SDK errors from other errors using `instanceof`.\n *\n * @remarks\n * Prefer using the `isUmbraError` type guard over `instanceof UmbraError` when writing\n * defensive catch handlers — the type guard also works across module boundaries and\n * iframe/realm boundaries where `instanceof` may fail due to different class references.\n *\n * Sub-classes (domain assertion errors) extend this class so callers can catch either\n * all SDK errors at once (`instanceof UmbraError`) or only a specific domain's failures\n * (e.g., `instanceof MathematicsAssertionError`).\n *\n * @example\n * ```typescript\n * try {\n *   await umbraClient.register();\n * } catch (error) {\n *   if (error instanceof UmbraError) {\n *     console.log('SDK error:', error.message);\n *     console.log('Error code:', error.code);\n *   } else {\n *     throw error; // Re-throw non-SDK errors\n *   }\n * }\n * ```\n *\n * @see {@link isUmbraError}\n * @public\n */\nexport class UmbraError extends Error {\n  /**\n   * A machine-readable error code for programmatic error handling.\n   *\n   * @remarks\n   * Defaults to `\"UMBRA_ERROR\"` when no code is supplied in the constructor options.\n   * Sub-classes or specific throw sites should supply a more specific code to allow\n   * callers to branch on error identity without string-matching `message`.\n   *\n   * @readonly\n   */\n  readonly code: string;\n\n  /**\n   * Additional context about the error.\n   *\n   * @remarks\n   * A free-form key-value map of diagnostic data attached to the error at the throw site.\n   * Useful for logging and debugging — consumers should not rely on specific keys for\n   * control flow; use `code` for programmatic branching instead.\n   *\n   * Will be `undefined` when no context was provided to the constructor.\n   *\n   * @readonly\n   */\n  readonly context?: Record<string, unknown>;\n\n  /**\n   * The original error that caused this error, if any.\n   *\n   * @remarks\n   * When an SDK function wraps a lower-level error (e.g., a failed RPC call or a\n   * cryptographic library error), it sets `cause` to the original thrown value so\n   * callers can inspect the full error chain.\n   *\n   * Will be `undefined` when there is no underlying cause.\n   *\n   * @readonly\n   */\n  override readonly cause?: unknown;\n\n  /**\n   * Creates a new UmbraError.\n   *\n   * @param message - Human-readable description of what went wrong. Should be\n   *   actionable and specific enough for a developer to understand the failure\n   *   without reading source code.\n   * @param options - Optional structured metadata attached to the error.\n   * @param options.code - Machine-readable error code for programmatic branching.\n   *   Defaults to `\"UMBRA_ERROR\"` if omitted.\n   * @param options.context - Free-form diagnostic key-value pairs. Omit or set to\n   *   `undefined` to leave the `context` property unset.\n   * @param options.cause - The original error that triggered this one. Enables\n   *   full error-chain inspection. Omit or set to `undefined` when there is no\n   *   underlying cause.\n   *\n   * @defaultValue `options` — `undefined` (all options optional)\n   * @defaultValue `options.code` — `\"UMBRA_ERROR\"`\n   */\n  constructor(\n    message: string,\n    options?: {\n      code?: string;\n      context?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message);\n    this.name = \"UmbraError\";\n    this.code = options?.code ?? \"UMBRA_ERROR\";\n    if (options?.context !== undefined) {\n      this.context = options.context;\n    }\n    if (options?.cause !== undefined) {\n      this.cause = options.cause;\n    }\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    Error.captureStackTrace(this, UmbraError);\n  }\n}\n\n/**\n * Type guard to check if an error is an UmbraError.\n *\n * @remarks\n * Prefer this guard over `error instanceof UmbraError` in generic catch handlers because\n * it is safe to call with any value (including `null`, primitives, and non-Error objects)\n * and narrows the type to `UmbraError` for TypeScript's type system in the true branch.\n *\n * @param error - The value to test. Typically the caught value in a `catch (error)` block,\n *   typed as `unknown`.\n * @returns `true` and narrows `error` to `UmbraError` when the value is an instance of\n *   `UmbraError` (or any sub-class such as `MathematicsAssertionError`). Returns `false`\n *   for all other values.\n *\n * @example\n * ```typescript\n * try {\n *   await operation();\n * } catch (error) {\n *   if (isUmbraError(error)) {\n *     // error is narrowed to UmbraError here\n *     console.log('SDK error code:', error.code);\n *     console.log('SDK error context:', error.context);\n *   }\n * }\n * ```\n *\n * @see {@link UmbraError}\n * @public\n */\nexport function isUmbraError(error: unknown): error is UmbraError {\n  return error instanceof UmbraError;\n}\n\n/* =============================================================================\n * MATHEMATICS ASSERTION ERROR\n *\n * Error thrown when mathematical type assertions fail.\n * ============================================================================= */\n\n/**\n * Error thrown when a value fails a mathematical type assertion.\n *\n * This error provides detailed information about why an assertion failed,\n * including the actual value, the expected type, and the constraint that\n * was violated.\n *\n * @remarks\n * All assertion functions in the mathematics module (e.g., `assertU8`, `assertU256`,\n * `assertU32LeBytes`) throw this error type on failure. Catch it specifically to handle\n * mathematical type validation failures differently from cryptographic or Solana errors.\n *\n * The three diagnostic properties together allow automated logging pipelines to produce\n * structured records without parsing the `message` string:\n * - `value` — the actual value that was supplied\n * - `expectedType` — the branded type name (e.g., `\"U8\"`, `\"U256LeBytes\"`)\n * - `constraint` — the violated range or length rule, or `undefined` for type mismatches\n *\n * Note that this class does NOT extend `UmbraError`. It extends `Error` directly to keep\n * the assertion error classes lightweight and independent of the UmbraError hierarchy.\n * Use `isUmbraError` only to detect top-level SDK operational errors; use\n * `instanceof MathematicsAssertionError` for assertion failures.\n *\n * @example\n * ```typescript\n * import { assertU8, MathematicsAssertionError } from \"./mathematics\";\n *\n * try {\n *     const value = assertU8(256n); // Will throw\n * } catch (error) {\n *     if (error instanceof MathematicsAssertionError) {\n *         console.error(`Assertion failed for ${error.expectedType}`);\n *         console.error(`Value: ${error.value}`);\n *         console.error(`Constraint: ${error.constraint}`);\n *         // Output:\n *         // Assertion failed for U8\n *         // Value: 256\n *         // Constraint: 0 <= value <= 255\n *     }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Safe parse pattern — returns null instead of throwing\n * function safeParseU8(value: bigint): U8 | null {\n *     try {\n *         return assertU8(value);\n *     } catch (error) {\n *         if (error instanceof MathematicsAssertionError) {\n *             console.warn(`Invalid U8 value: ${value}`);\n *             return null;\n *         }\n *         throw error; // Re-throw unexpected errors\n *     }\n * }\n * ```\n *\n * @sealed\n * @public\n */\nexport class MathematicsAssertionError extends Error {\n  /**\n   * The actual value that failed the assertion.\n   *\n   * @remarks\n   * The runtime type reflects what was actually passed to the assertion function:\n   * - `bigint` for integer assertions (`assertU8`, `assertU256`, etc.)\n   * - `Uint8Array` for byte-array assertions (`assertU256LeBytes`, `assertU32LeBytes`, etc.)\n   * - Any other type when a non-numeric value was passed unexpectedly\n   *\n   * @readonly\n   */\n  public readonly value: unknown;\n\n  /**\n   * The type that was expected.\n   *\n   * @remarks\n   * Contains the branded type name exactly as it appears in the SDK type system,\n   * e.g., `\"U8\"`, `\"U256\"`, `\"U32LeBytes\"`. Use this for structured logging or\n   * to build user-facing error messages without parsing the `message` string.\n   *\n   * @readonly\n   */\n  public readonly expectedType: string;\n\n  /**\n   * Description of the constraint that was violated.\n   *\n   * @remarks\n   * Is `undefined` when only a type check failed (e.g., a `string` was passed where a\n   * `bigint` was expected). Contains a human-readable inequality or length rule when a\n   * value of the correct type was out of the allowed range.\n   *\n   * @example\n   * - `\"0 <= value <= 255\"` — U8 range violation\n   * - `\"length === 32\"` — U256LeBytes length violation\n   * - `\"value >= 0\"` — negative value passed to an unsigned integer assertion\n   *\n   * @readonly\n   */\n  public readonly constraint: string | undefined;\n\n  /**\n   * Creates a new MathematicsAssertionError.\n   *\n   * @param message - Human-readable description of the assertion failure. Should name\n   *   the assertion function, the expected type, and the constraint that was violated.\n   * @param options - Structured diagnostic details attached to the error.\n   * @param options.value - The actual value that was supplied and failed the assertion.\n   * @param options.expectedType - The name of the branded type that was expected\n   *   (e.g., `\"U8\"`, `\"U256LeBytes\"`).\n   * @param options.constraint - Optional human-readable constraint description\n   *   (e.g., `\"0 <= value <= 255\"`). Omit when the failure is a type mismatch rather\n   *   than a range violation.\n   */\n  constructor(\n    message: string,\n    options: {\n      value: unknown;\n      expectedType: string;\n      constraint?: string;\n    },\n  ) {\n    super(message);\n    this.name = \"MathematicsAssertionError\";\n    this.value = options.value;\n    this.expectedType = options.expectedType;\n    this.constraint = options.constraint;\n\n    // Maintains proper stack trace for where our error was thrown (V8 only)\n    Error.captureStackTrace(this, MathematicsAssertionError);\n\n    // Set the prototype explicitly for proper instanceof checks\n    Object.setPrototypeOf(this, MathematicsAssertionError.prototype);\n  }\n}\n\n/* =============================================================================\n * CRYPTOGRAPHY ASSERTION ERROR\n *\n * Error thrown when cryptographic type assertions fail.\n * ============================================================================= */\n\n/**\n * Error thrown when a value fails a cryptographic type assertion.\n *\n * This error provides detailed information about why an assertion failed,\n * including the actual value, the expected type, and the constraint that\n * was violated.\n *\n * @remarks\n * Thrown by assertion functions in the cryptography module, such as\n * `assertBn254FieldElement`, `assertAesKey`, `assertX25519PrivateKey`, and similar.\n * Each function validates that a value conforms to a branded cryptographic type,\n * throwing this error with a precise `expectedType` and `constraint` when it does not.\n *\n * Common reasons for failure:\n * - A `bigint` field element exceeds the BN254 or Curve25519 field prime\n * - A byte array has the wrong length (e.g., a 31-byte array passed as an AES-256 key)\n * - A wrong JavaScript type was supplied (e.g., a `number` instead of a `bigint`)\n *\n * @example\n * ```typescript\n * import { assertBn254FieldElement, CryptographyAssertionError } from \"./cryptography\";\n *\n * try {\n *     assertBn254FieldElement(invalidValue); // Will throw\n * } catch (error) {\n *     if (error instanceof CryptographyAssertionError) {\n *         console.error(`Assertion failed for ${error.expectedType}`);\n *         console.error(`Value: ${error.value}`);\n *         console.error(`Constraint: ${error.constraint}`);\n *     }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Distinguish cryptographic assertion failures from mathematical ones\n * try {\n *     const key = assertAesKey(rawBytes);\n * } catch (error) {\n *     if (error instanceof CryptographyAssertionError) {\n *         console.warn(\"Crypto assertion failed:\", error.expectedType, error.constraint);\n *     } else if (error instanceof MathematicsAssertionError) {\n *         console.warn(\"Math assertion failed:\", error.expectedType, error.constraint);\n *     }\n * }\n * ```\n *\n * @see {@link MathematicsAssertionError}\n * @see {@link SolanaAssertionError}\n * @see {@link TemporalAssertionError}\n * @sealed\n * @public\n */\nexport class CryptographyAssertionError extends Error {\n  /**\n   * The actual value that failed the assertion.\n   *\n   * @remarks\n   * The runtime type reflects what was actually passed to the assertion function:\n   * - `bigint` for field element assertions (`assertBn254FieldElement`, etc.)\n   * - `Uint8Array` for byte-array assertions (`assertAesKey`, `assertX25519PrivateKey`, etc.)\n   * - Any other type when an entirely wrong value type was supplied\n   *\n   * @readonly\n   */\n  public readonly value: unknown;\n\n  /**\n   * The type that was expected (e.g., `\"Bn254FieldElement\"`, `\"PoseidonKey\"`, `\"AesKey\"`).\n   *\n   * @remarks\n   * Contains the branded type name exactly as it appears in the SDK type system.\n   * Use this property for structured logging without parsing the `message` string.\n   *\n   * @readonly\n   */\n  public readonly expectedType: string;\n\n  /**\n   * Description of the constraint that was violated.\n   *\n   * @remarks\n   * Is `undefined` for pure type-mismatch failures (e.g., `string` instead of `bigint`).\n   * Contains a human-readable constraint description for range and length violations\n   * (e.g., `\"value < BN254_FIELD_PRIME\"`, `\"length === 32\"`).\n   *\n   * @readonly\n   */\n  public readonly constraint: string | undefined;\n\n  /**\n   * Creates a new CryptographyAssertionError.\n   *\n   * @param message - Human-readable description of the assertion failure. Should name\n   *   the assertion function, the expected type, and the constraint that was violated.\n   * @param options - Structured diagnostic details attached to the error.\n   * @param options.value - The actual value that was supplied and failed the assertion.\n   * @param options.expectedType - The name of the branded cryptographic type that was\n   *   expected (e.g., `\"Bn254FieldElement\"`, `\"AesKey\"`).\n   * @param options.constraint - Optional human-readable constraint description.\n   *   Omit when the failure is a type mismatch rather than a range or length violation.\n   */\n  constructor(\n    message: string,\n    options: {\n      value: unknown;\n      expectedType: string;\n      constraint?: string;\n    },\n  ) {\n    super(message);\n    this.name = \"CryptographyAssertionError\";\n    this.value = options.value;\n    this.expectedType = options.expectedType;\n    this.constraint = options.constraint;\n\n    Error.captureStackTrace(this, CryptographyAssertionError);\n\n    Object.setPrototypeOf(this, CryptographyAssertionError.prototype);\n  }\n}\n\n/* =============================================================================\n * SOLANA ASSERTION ERROR\n *\n * Error thrown when Solana type assertions fail.\n * ============================================================================= */\n\n/**\n * Error thrown when a Solana type assertion fails.\n *\n * This error provides detailed information about why the assertion failed,\n * including the actual value, expected type, and constraint that was violated.\n *\n * @remarks\n * Thrown by assertion functions for Solana-specific branded types, such as\n * `assertTransactionSignature`, `assertSignatureBytes`, and similar validators.\n * These assertions verify that string or byte-array values conform to Solana's\n * encoding and length conventions (e.g., Base58-encoded 64-byte Ed25519 signatures).\n *\n * Common reasons for failure:\n * - A string that fails Base58 decoding or has the wrong decoded length\n * - A `Uint8Array` with the wrong byte length for a signature or public key\n * - A wrong JavaScript type (e.g., `number` instead of `string`)\n *\n * @example\n * ```typescript\n * import { assertTransactionSignature, SolanaAssertionError } from \"./solana\";\n *\n * try {\n *     assertTransactionSignature(\"invalid!signature\"); // Will throw\n * } catch (error) {\n *     if (error instanceof SolanaAssertionError) {\n *         console.error(`Assertion failed for ${error.expectedType}`);\n *         console.error(`Value: ${error.value}`);\n *         console.error(`Constraint: ${error.constraint}`);\n *     }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Safe parse pattern — returns null on failure\n * function tryParseSignature(raw: unknown): TransactionSignature | null {\n *     try {\n *         return assertTransactionSignature(raw);\n *     } catch (error) {\n *         if (error instanceof SolanaAssertionError) return null;\n *         throw error;\n *     }\n * }\n * ```\n *\n * @see {@link MathematicsAssertionError}\n * @see {@link CryptographyAssertionError}\n * @see {@link TemporalAssertionError}\n * @sealed\n * @public\n */\nexport class SolanaAssertionError extends Error {\n  /**\n   * The actual value that failed the assertion.\n   *\n   * @remarks\n   * The runtime type reflects what was actually passed to the assertion function:\n   * - `string` for Base58-encoded assertions (`assertTransactionSignature`, etc.)\n   * - `Uint8Array` for byte-array assertions (`assertSignatureBytes`, etc.)\n   * - Any other type when a completely wrong value type was supplied\n   *\n   * @readonly\n   */\n  public readonly value: unknown;\n\n  /**\n   * The type that was expected (e.g., `\"TransactionSignature\"`, `\"SignatureBytes\"`).\n   *\n   * @remarks\n   * Contains the branded type name exactly as it appears in the SDK type system.\n   * Use this for structured logging without parsing the `message` string.\n   *\n   * @readonly\n   */\n  public readonly expectedType: string;\n\n  /**\n   * Description of the constraint that was violated.\n   *\n   * @remarks\n   * Is `undefined` for pure type-mismatch failures. Contains a human-readable rule\n   * for encoding or length violations (e.g., `\"valid Base58\"`, `\"length === 64\"`).\n   *\n   * @readonly\n   */\n  public readonly constraint: string | undefined;\n\n  /**\n   * Creates a new SolanaAssertionError.\n   *\n   * @param message - Human-readable description of the assertion failure. Should name\n   *   the assertion function, the expected type, and the constraint that was violated.\n   * @param options - Structured diagnostic details attached to the error.\n   * @param options.value - The actual value that was supplied and failed the assertion.\n   * @param options.expectedType - The name of the branded Solana type that was expected\n   *   (e.g., `\"TransactionSignature\"`, `\"SignatureBytes\"`).\n   * @param options.constraint - Optional human-readable constraint description.\n   *   Omit when the failure is a type mismatch rather than an encoding or length violation.\n   */\n  constructor(\n    message: string,\n    options: {\n      value: unknown;\n      expectedType: string;\n      constraint?: string;\n    },\n  ) {\n    super(message);\n    this.name = \"SolanaAssertionError\";\n    this.value = options.value;\n    this.expectedType = options.expectedType;\n    this.constraint = options.constraint;\n\n    Error.captureStackTrace(this, SolanaAssertionError);\n\n    Object.setPrototypeOf(this, SolanaAssertionError.prototype);\n  }\n}\n\n/* =============================================================================\n * TEMPORAL ASSERTION ERROR\n *\n * Error thrown when temporal type assertions fail.\n * ============================================================================= */\n\n/**\n * Error thrown when a temporal type assertion fails.\n *\n * This error provides detailed information about why an assertion failed,\n * including the actual value, the expected type, and the constraint that\n * was violated.\n *\n * @remarks\n * Thrown by assertion functions for branded temporal types: `assertYear`, `assertMonth`,\n * `assertDay`, `assertHour`, `assertMinute`, and `assertSecond`. These functions validate\n * that a `bigint` value falls within the calendar range appropriate for each component\n * (e.g., months must be in `[1, 12]`, hours in `[0, 23]`).\n *\n * Temporal assertions are used to validate the output of UTC timestamp extraction before\n * the components are used in time-scoped viewing key derivation. In normal operation they\n * should never throw (JavaScript's `Date` always produces in-range values), but callers\n * that construct components manually can encounter these errors.\n *\n * @example\n * ```typescript\n * import { assertMonth, TemporalAssertionError } from \"./temporal\";\n *\n * try {\n *     assertMonth(13n); // Will throw — month must be 1–12\n * } catch (error) {\n *     if (error instanceof TemporalAssertionError) {\n *         console.error(`Assertion failed for ${error.expectedType}`);\n *         console.error(`Value: ${error.value}`);\n *         console.error(`Constraint: ${error.constraint}`);\n *         // Output:\n *         // Assertion failed for Month\n *         // Value: 13\n *         // Constraint: 1 <= value <= 12\n *     }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Safe parse of a user-supplied year value\n * function tryParseYear(raw: bigint): Year | null {\n *     try {\n *         return assertYear(raw);\n *     } catch (error) {\n *         if (error instanceof TemporalAssertionError) return null;\n *         throw error;\n *     }\n * }\n * ```\n *\n * @see {@link MathematicsAssertionError}\n * @see {@link CryptographyAssertionError}\n * @see {@link SolanaAssertionError}\n * @sealed\n * @public\n */\nexport class TemporalAssertionError extends Error {\n  /**\n   * The actual value that failed the assertion.\n   *\n   * @remarks\n   * Will be a `bigint` for all temporal assertions since the temporal types are\n   * BigInt-backed branded types (e.g., `Year`, `Month`, `Day`). May also be any\n   * other type when a non-bigint value was supplied unexpectedly.\n   *\n   * @readonly\n   */\n  public readonly value: unknown;\n\n  /**\n   * The type that was expected (e.g., `\"Year\"`, `\"Month\"`, `\"Hour\"`).\n   *\n   * @remarks\n   * Contains the branded temporal type name exactly as it appears in the SDK type system.\n   * Use this for structured logging without parsing the `message` string.\n   *\n   * @readonly\n   */\n  public readonly expectedType: string;\n\n  /**\n   * Description of the constraint that was violated.\n   *\n   * @remarks\n   * Contains a human-readable range rule for out-of-range values\n   * (e.g., `\"1 <= value <= 12\"` for a month violation). Is `undefined` only for\n   * pure type-mismatch failures (e.g., a `string` passed where a `bigint` was expected),\n   * which should not occur in normal usage.\n   *\n   * @readonly\n   */\n  public readonly constraint: string | undefined;\n\n  /**\n   * Creates a new TemporalAssertionError.\n   *\n   * @param message - Human-readable description of the assertion failure. Should name\n   *   the assertion function, the expected type, and the violated range constraint.\n   * @param details - Structured diagnostic details attached to the error.\n   * @param details.value - The actual `bigint` value (or other type) that was supplied\n   *   and failed the temporal assertion.\n   * @param details.expectedType - The name of the branded temporal type that was expected\n   *   (e.g., `\"Year\"`, `\"Month\"`, `\"Hour\"`).\n   * @param details.constraint - Optional human-readable range description\n   *   (e.g., `\"1 <= value <= 12\"`). Omit when the failure is a type mismatch.\n   */\n  constructor(\n    message: string,\n    details: {\n      value: unknown;\n      expectedType: string;\n      constraint?: string;\n    },\n  ) {\n    super(message);\n    this.name = \"TemporalAssertionError\";\n    this.value = details.value;\n    this.expectedType = details.expectedType;\n    this.constraint = details.constraint;\n  }\n}\n"]}