@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/chunk-QJAUUYZU.cjs

@@ -0,0 +1,331 @@
+'use strict';
+
+var chunkPK6SKIKE_cjs = require('./chunk-PK6SKIKE.cjs');
+
+// src/common/errors.ts
+var UmbraError = class _UmbraError extends Error {
+  static {
+    chunkPK6SKIKE_cjs.__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;
+}
+chunkPK6SKIKE_cjs.__name(isUmbraError, "isUmbraError");
+var MathematicsAssertionError = class _MathematicsAssertionError extends Error {
+  static {
+    chunkPK6SKIKE_cjs.__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 {
+    chunkPK6SKIKE_cjs.__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 {
+    chunkPK6SKIKE_cjs.__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 {
+    chunkPK6SKIKE_cjs.__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;
+  }
+};
+
+exports.CryptographyAssertionError = CryptographyAssertionError;
+exports.MathematicsAssertionError = MathematicsAssertionError;
+exports.SolanaAssertionError = SolanaAssertionError;
+exports.TemporalAssertionError = TemporalAssertionError;
+exports.UmbraError = UmbraError;
+exports.isUmbraError = isUmbraError;
+//# sourceMappingURL=chunk-QJAUUYZU.cjs.map
+//# sourceMappingURL=chunk-QJAUUYZU.cjs.map

package/dist/chunk-QJAUUYZU.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/common/errors.ts"],"names":["__name"],"mappings":"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","file":"chunk-QJAUUYZU.cjs","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"]}