@umbra-privacy/sdk 1.0.0 → 2.0.1

package/dist/chunk-FSK2ICMB.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+var chunkQJAUUYZU_cjs = require('./chunk-QJAUUYZU.cjs');
+var chunkPK6SKIKE_cjs = require('./chunk-PK6SKIKE.cjs');
+
+// src/crypto/errors.ts
+var CryptographyError = class extends chunkQJAUUYZU_cjs.UmbraError {
+  static {
+    chunkPK6SKIKE_cjs.__name(this, "CryptographyError");
+  }
+  /**
+   * The cryptographic operation that failed.
+   */
+  operation;
+  constructor(message, options) {
+    super(message, {
+      code: options?.code ?? "CRYPTOGRAPHY_ERROR",
+      ...options?.context !== void 0 && {
+        context: options.context
+      },
+      ...options?.cause !== void 0 && {
+        cause: options.cause
+      }
+    });
+    this.name = "CryptographyError";
+    if (options?.operation !== void 0) {
+      this.operation = options.operation;
+    }
+  }
+};
+function isCryptographyError(error) {
+  return error instanceof CryptographyError;
+}
+chunkPK6SKIKE_cjs.__name(isCryptographyError, "isCryptographyError");
+
+exports.CryptographyError = CryptographyError;
+exports.isCryptographyError = isCryptographyError;
+//# sourceMappingURL=chunk-FSK2ICMB.cjs.map
+//# sourceMappingURL=chunk-FSK2ICMB.cjs.map

package/dist/chunk-FSK2ICMB.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/crypto/errors.ts"],"names":["UmbraError","__name"],"mappings":";;;;;;AA4BO,IAAM,iBAAA,GAAN,cAAgCA,4BAAA,CAAW;AAAA,EA5BlD;AA4BkD,IAAAC,wBAAA,CAAA,IAAA,EAAA,mBAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAIvC,SAAA;AAAA,EAET,WAAA,CACE,SACA,OAAA,EAMA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS;AAAA,MACb,IAAA,EAAM,SAAS,IAAA,IAAQ,oBAAA;AAAA,MACvB,GAAI,OAAA,EAAS,OAAA,KAAY,MAAA,IAAa;AAAA,QACpC,SAAS,OAAA,CAAQ;AAAA,OACnB;AAAA,MACA,GAAI,OAAA,EAAS,KAAA,KAAU,MAAA,IAAa;AAAA,QAClC,OAAO,OAAA,CAAQ;AAAA;AACjB,KACD,CAAA;AACD,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AACZ,IAAA,IAAI,OAAA,EAAS,cAAc,MAAA,EAAW;AACpC,MAAA,IAAA,CAAK,YAAY,OAAA,CAAQ,SAAA;AAAA,IAC3B;AAAA,EACF;AACF;AAKO,SAAS,oBAAoB,KAAA,EAA4C;AAC9E,EAAA,OAAO,KAAA,YAAiB,iBAAA;AAC1B;AAFgBA,wBAAA,CAAA,mBAAA,EAAA,qBAAA,CAAA","file":"chunk-FSK2ICMB.cjs","sourcesContent":["/**\n * Cryptography Error Classes\n *\n * This module provides error classes for cryptographic operation failures\n * in the Umbra SDK.\n *\n * @module crypto/errors\n */\n\nimport { UmbraError } from \"../common/errors\";\n\n/**\n * Error thrown when a cryptographic operation fails.\n *\n * This includes key derivation failures, encryption/decryption errors,\n * hash computation failures, and ZK proof generation errors.\n *\n * @example\n * ```typescript\n * try {\n *   const commitment = await generateUserCommitment(mvk, index, seed);\n * } catch (error) {\n *   if (error instanceof CryptographyError) {\n *     console.log('Crypto operation failed:', error.operation);\n *   }\n * }\n * ```\n */\nexport class CryptographyError extends UmbraError {\n  /**\n   * The cryptographic operation that failed.\n   */\n  readonly operation?: string;\n\n  constructor(\n    message: string,\n    options?: {\n      code?: string;\n      operation?: string;\n      context?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, {\n      code: options?.code ?? \"CRYPTOGRAPHY_ERROR\",\n      ...(options?.context !== undefined && {\n        context: options.context,\n      }),\n      ...(options?.cause !== undefined && {\n        cause: options.cause,\n      }),\n    });\n    this.name = \"CryptographyError\";\n    if (options?.operation !== undefined) {\n      this.operation = options.operation;\n    }\n  }\n}\n\n/**\n * Type guard to check if an error is a CryptographyError.\n */\nexport function isCryptographyError(error: unknown): error is CryptographyError {\n  return error instanceof CryptographyError;\n}\n"]}

package/dist/chunk-FZYWLQAF.cjs

@@ -0,0 +1,355 @@
+'use strict';
+
+var chunkPK6SKIKE_cjs = require('./chunk-PK6SKIKE.cjs');
+
+// src/solana/types.ts
+var SIGNATURE_BYTE_LENGTH = 64;
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE58_REGEX = /^[1-9A-HJ-NP-Za-km-z]+$/;
+var SolanaAssertionError = class _SolanaAssertionError extends Error {
+  static {
+    chunkPK6SKIKE_cjs.__name(this, "SolanaAssertionError");
+  }
+  /**
+   * The actual value that was passed to the assertion function and failed
+   * the type check.
+   *
+   * @remarks
+   * Typed as `unknown` because assertion functions accept values of unknown
+   * type before narrowing. Inspect carefully — the value may be `undefined`,
+   * `null`, or any primitive or object.
+   */
+  value;
+  /**
+   * The name of the expected type (e.g., `"TransactionSignature"`,
+   * `"SignatureBytes"`).
+   *
+   * @remarks
+   * Matches the TypeScript type name for the intended branded type, not a
+   * JavaScript `typeof` string.
+   */
+  expectedType;
+  /**
+   * A human-readable description of the specific constraint that was violated,
+   * if applicable.
+   *
+   * @remarks
+   * Examples:
+   * - `"length > 0"` — empty string passed to `assertTransactionSignature`
+   * - `"length === 64"` — wrong byte count passed to `assertSignatureBytes`
+   * - `"characters must be in base58 alphabet: 123...xyz"` — invalid character
+   *
+   * `undefined` when the only constraint is the TypeScript type itself
+   * (e.g., `assertString` only checks `typeof value === "string"`).
+   */
+  constraint;
+  /**
+   * Creates a new `SolanaAssertionError`.
+   *
+   * @param message - Human-readable description of the assertion failure.
+   * @param options - Structured context for the failed assertion.
+   * @param options.value - The value that failed the assertion.
+   * @param options.expectedType - The name of the expected branded type.
+   * @param options.constraint - The specific constraint that was violated, if any.
+   */
+  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);
+  }
+};
+function assertString(value) {
+  if (typeof value !== "string") {
+    throw new SolanaAssertionError(`Expected string, got ${typeof value}`, {
+      value,
+      expectedType: "String"
+    });
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertString, "assertString");
+function assertTransactionSignature(value) {
+  if (typeof value !== "string") {
+    throw new SolanaAssertionError(`Expected string, got ${typeof value}`, {
+      value,
+      expectedType: "TransactionSignature"
+    });
+  }
+  if (value.length === 0) {
+    throw new SolanaAssertionError("Transaction signature cannot be empty", {
+      value,
+      expectedType: "TransactionSignature",
+      constraint: "length > 0"
+    });
+  }
+  if (!BASE58_REGEX.test(value)) {
+    let invalidChar = "";
+    let invalidIndex = -1;
+    for (const [index, element] of Array.from(value).entries()) {
+      if (!BASE58_ALPHABET.includes(element)) {
+        invalidChar = element;
+        invalidIndex = index;
+        break;
+      }
+    }
+    throw new SolanaAssertionError(
+      `Invalid base58 character '${invalidChar}' at position ${String(invalidIndex)}`,
+      {
+        value,
+        expectedType: "TransactionSignature",
+        constraint: `characters must be in base58 alphabet: ${BASE58_ALPHABET}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertTransactionSignature, "assertTransactionSignature");
+function assertSolanaBytes(value) {
+  if (!(value instanceof Uint8Array)) {
+    throw new SolanaAssertionError(`Expected Uint8Array, got ${typeof value}`, {
+      value,
+      expectedType: "SolanaBytes"
+    });
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertSolanaBytes, "assertSolanaBytes");
+function assertSignatureBytes(value) {
+  if (!(value instanceof Uint8Array)) {
+    throw new SolanaAssertionError(`Expected Uint8Array, got ${typeof value}`, {
+      value,
+      expectedType: "SignatureBytes"
+    });
+  }
+  if (value.length !== SIGNATURE_BYTE_LENGTH) {
+    throw new SolanaAssertionError(
+      `Expected ${String(SIGNATURE_BYTE_LENGTH)} bytes, got ${String(value.length)}`,
+      {
+        value,
+        expectedType: "SignatureBytes",
+        constraint: `length === ${String(SIGNATURE_BYTE_LENGTH)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertSignatureBytes, "assertSignatureBytes");
+function asRelayableSignedTransaction(tx) {
+  return tx;
+}
+chunkPK6SKIKE_cjs.__name(asRelayableSignedTransaction, "asRelayableSignedTransaction");
+
+// src/common/temporal/types.ts
+var YEAR_MIN = 0n;
+var YEAR_MAX = 9999n;
+var MONTH_MIN = 1n;
+var MONTH_MAX = 12n;
+var DAY_MIN = 1n;
+var DAY_MAX = 31n;
+var HOUR_MIN = 0n;
+var HOUR_MAX = 23n;
+var MINUTE_MIN = 0n;
+var MINUTE_MAX = 59n;
+var SECOND_MIN = 0n;
+var SECOND_MAX = 59n;
+var TemporalAssertionError = class extends Error {
+  static {
+    chunkPK6SKIKE_cjs.__name(this, "TemporalAssertionError");
+  }
+  /**
+   * The actual value that failed the assertion.
+   * @readonly
+   */
+  value;
+  /**
+   * The type that was expected (e.g., `"Month"`, `"Hour"`).
+   * @readonly
+   */
+  expectedType;
+  /**
+   * Description of the constraint that was violated.
+   *
+   * @remarks
+   * `undefined` when the failure was a type mismatch (e.g., received a number instead of a
+   * bigint). Contains a human-readable range string (e.g., `"1 <= value <= 12"`) when the
+   * value was the correct type but out of the valid range.
+   * @readonly
+   */
+  constraint;
+  /**
+   * Creates a new TemporalAssertionError.
+   *
+   * @param message - Human-readable description of what went wrong
+   * @param details - Structured error details for programmatic inspection
+   * @param details.value - The value that failed the assertion
+   * @param details.expectedType - Name of the branded type that was expected
+   * @param details.constraint - Optional human-readable constraint that was violated
+   */
+  constructor(message, details) {
+    super(message);
+    this.name = "TemporalAssertionError";
+    this.value = details.value;
+    this.expectedType = details.expectedType;
+    this.constraint = details.constraint;
+  }
+};
+function assertTimestampComponent(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "TimestampComponent"
+    });
+  }
+  if (value < 0n) {
+    throw new TemporalAssertionError(`TimestampComponent must be non-negative`, {
+      value,
+      expectedType: "TimestampComponent",
+      constraint: "value >= 0"
+    });
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertTimestampComponent, "assertTimestampComponent");
+function assertYear(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Year"
+    });
+  }
+  if (value < YEAR_MIN || value > YEAR_MAX) {
+    throw new TemporalAssertionError(
+      `Year must be in range [${String(YEAR_MIN)}, ${String(YEAR_MAX)}]`,
+      {
+        value,
+        expectedType: "Year",
+        constraint: `${String(YEAR_MIN)} <= value <= ${String(YEAR_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertYear, "assertYear");
+function assertMonth(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Month"
+    });
+  }
+  if (value < MONTH_MIN || value > MONTH_MAX) {
+    throw new TemporalAssertionError(
+      `Month must be in range [${String(MONTH_MIN)}, ${String(MONTH_MAX)}]`,
+      {
+        value,
+        expectedType: "Month",
+        constraint: `${String(MONTH_MIN)} <= value <= ${String(MONTH_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertMonth, "assertMonth");
+function assertDay(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Day"
+    });
+  }
+  if (value < DAY_MIN || value > DAY_MAX) {
+    throw new TemporalAssertionError(
+      `Day must be in range [${String(DAY_MIN)}, ${String(DAY_MAX)}]`,
+      {
+        value,
+        expectedType: "Day",
+        constraint: `${String(DAY_MIN)} <= value <= ${String(DAY_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertDay, "assertDay");
+function assertHour(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Hour"
+    });
+  }
+  if (value < HOUR_MIN || value > HOUR_MAX) {
+    throw new TemporalAssertionError(
+      `Hour must be in range [${String(HOUR_MIN)}, ${String(HOUR_MAX)}]`,
+      {
+        value,
+        expectedType: "Hour",
+        constraint: `${String(HOUR_MIN)} <= value <= ${String(HOUR_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertHour, "assertHour");
+function assertMinute(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Minute"
+    });
+  }
+  if (value < MINUTE_MIN || value > MINUTE_MAX) {
+    throw new TemporalAssertionError(
+      `Minute must be in range [${String(MINUTE_MIN)}, ${String(MINUTE_MAX)}]`,
+      {
+        value,
+        expectedType: "Minute",
+        constraint: `${String(MINUTE_MIN)} <= value <= ${String(MINUTE_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertMinute, "assertMinute");
+function assertSecond(value) {
+  if (typeof value !== "bigint") {
+    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {
+      value,
+      expectedType: "Second"
+    });
+  }
+  if (value < SECOND_MIN || value > SECOND_MAX) {
+    throw new TemporalAssertionError(
+      `Second must be in range [${String(SECOND_MIN)}, ${String(SECOND_MAX)}]`,
+      {
+        value,
+        expectedType: "Second",
+        constraint: `${String(SECOND_MIN)} <= value <= ${String(SECOND_MAX)}`
+      }
+    );
+  }
+}
+chunkPK6SKIKE_cjs.__name(assertSecond, "assertSecond");
+
+exports.DAY_MAX = DAY_MAX;
+exports.DAY_MIN = DAY_MIN;
+exports.HOUR_MAX = HOUR_MAX;
+exports.HOUR_MIN = HOUR_MIN;
+exports.MINUTE_MAX = MINUTE_MAX;
+exports.MINUTE_MIN = MINUTE_MIN;
+exports.MONTH_MAX = MONTH_MAX;
+exports.MONTH_MIN = MONTH_MIN;
+exports.SECOND_MAX = SECOND_MAX;
+exports.SECOND_MIN = SECOND_MIN;
+exports.SIGNATURE_BYTE_LENGTH = SIGNATURE_BYTE_LENGTH;
+exports.SolanaAssertionError = SolanaAssertionError;
+exports.TemporalAssertionError = TemporalAssertionError;
+exports.YEAR_MAX = YEAR_MAX;
+exports.YEAR_MIN = YEAR_MIN;
+exports.asRelayableSignedTransaction = asRelayableSignedTransaction;
+exports.assertDay = assertDay;
+exports.assertHour = assertHour;
+exports.assertMinute = assertMinute;
+exports.assertMonth = assertMonth;
+exports.assertSecond = assertSecond;
+exports.assertSignatureBytes = assertSignatureBytes;
+exports.assertSolanaBytes = assertSolanaBytes;
+exports.assertString = assertString;
+exports.assertTimestampComponent = assertTimestampComponent;
+exports.assertTransactionSignature = assertTransactionSignature;
+exports.assertYear = assertYear;
+//# sourceMappingURL=chunk-FZYWLQAF.cjs.map
+//# sourceMappingURL=chunk-FZYWLQAF.cjs.map

package/dist/chunk-FZYWLQAF.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/solana/types.ts","../src/common/temporal/types.ts"],"names":["__name"],"mappings":"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","file":"chunk-FZYWLQAF.cjs","sourcesContent":["/**\n * Solana Types Module.\n *\n * This module provides branded types and runtime assertion functions for\n * Solana-specific data structures. By attaching nominal brands to primitive\n * `string` and `Uint8Array` values, and to `@solana/kit` transaction objects,\n * the SDK achieves compile-time safety that prevents common mistakes such as:\n * - Passing a raw string where a `TransactionSignature` is expected.\n * - Submitting an unsigned transaction to a `TransactionForwarder`.\n * - Mixing up different byte-array representations.\n *\n * @remarks\n * **Type hierarchy overview:**\n *\n * String types:\n * - {@link String} — root branded string (base type for all string sub-brands)\n *   - {@link TransactionSignature} — base58-encoded Ed25519 signature string\n *\n * Byte array types:\n * - {@link SolanaBytes} — root branded `Uint8Array` for Solana binary data\n *   - {@link SignatureBytes} — exactly 64-byte raw Ed25519 signature\n *\n * Transaction types (wrapping `@solana/kit`'s `Transaction`):\n * - {@link UnsignedTransaction} — no signatures present\n * - {@link SignedTransaction} — at least one signature; includes blockhash lifetime\n *   - {@link PartiallySignedTransaction} — some but not all required signatures\n *     - {@link FullySignedTransaction} — all required signatures present; ready for submission\n *\n * **Runtime assertions:**\n * - {@link assertString} — narrows `string` to `String`\n * - {@link assertTransactionSignature} — narrows `string` to `TransactionSignature` (base58 validated)\n * - {@link assertSolanaBytes} — narrows `Uint8Array` to `SolanaBytes`\n * - {@link assertSignatureBytes} — narrows `Uint8Array` to `SignatureBytes` (64-byte validated)\n *\n * **Error class:**\n * - {@link SolanaAssertionError} — thrown by all assertion functions with structured context\n *\n * @example\n * ```typescript\n * import {\n *   assertTransactionSignature,\n *   assertSignatureBytes,\n *   TransactionSignature,\n *   SignatureBytes,\n * } from \"./types\";\n *\n * const sigString = \"5wHu1qwD7q5menT3ydT9VdFPQfkLaWvqPgVbqsM1qwD7\";\n * assertTransactionSignature(sigString);\n * // sigString is now typed as TransactionSignature\n *\n * const sigBytes = new Uint8Array(64);\n * assertSignatureBytes(sigBytes);\n * // sigBytes is now typed as SignatureBytes\n * ```\n *\n * @see {@link BrandedType} for the underlying branding utility\n * @see {@link Bytes} for the generic byte array base type\n *\n * @packageDocumentation\n * @since 2.0.0\n * @module types/solana\n */\n\nimport type { Transaction, TransactionWithBlockhashLifetime } from \"@solana/kit\";\n\nimport type { BrandedType, SubBrandedType, SubSubBrandedType } from \"../common/branded\";\nimport type { Bytes } from \"../common/types\";\n\n/* =============================================================================\n * CONSTANTS\n * ============================================================================= */\n\n/**\n * Length of an Ed25519 signature in bytes.\n *\n * The Ed25519 signature scheme, used by Solana for all transaction signing,\n * always produces exactly 64-byte signatures:\n * - Bytes 0–31: the R component (a compressed point on the Ed25519 curve)\n * - Bytes 32–63: the S component (a scalar value)\n *\n * @remarks\n * This constant is used by {@link assertSignatureBytes} to validate the length\n * of raw signature byte arrays before branding them as {@link SignatureBytes}.\n *\n * @example\n * ```typescript\n * const raw = new Uint8Array(SIGNATURE_BYTE_LENGTH); // 64-byte zeroed buffer\n * assertSignatureBytes(raw);\n * ```\n *\n * @public\n */\nexport const SIGNATURE_BYTE_LENGTH = 64;\n\n/**\n * Valid characters in the Base58 alphabet used by Solana (and Bitcoin).\n *\n * Base58 deliberately omits four characters that are visually ambiguous in\n * common typefaces:\n * - `0` (zero) — easily confused with `O` (capital O)\n * - `O` (capital O) — easily confused with `0` (zero)\n * - `I` (capital I) — easily confused with `l` (lowercase L)\n * - `l` (lowercase L) — easily confused with `I` (capital I) or `1`\n *\n * The remaining 58 characters form the Base58 alphabet.\n *\n * @internal\n */\nconst BASE58_ALPHABET = \"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz\";\n\n/**\n * Regular expression pattern for validating base58-encoded strings.\n *\n * The character class `[1-9A-HJ-NP-Za-km-z]` corresponds exactly to the\n * 58-character Base58 alphabet — it excludes `0`, `I`, `O`, and `l`.\n *\n * @internal\n */\nconst BASE58_REGEX = /^[1-9A-HJ-NP-Za-km-z]+$/;\n\n/* =============================================================================\n * ERROR CLASSES\n * ============================================================================= */\n\n/**\n * Error thrown when a Solana type assertion function fails.\n *\n * All assertion functions in this module (`assertString`,\n * `assertTransactionSignature`, `assertSolanaBytes`, `assertSignatureBytes`)\n * throw `SolanaAssertionError` when the supplied value does not satisfy the\n * type constraint. The error carries structured fields that make it easy to\n * log diagnostics or write type-specific error handlers.\n *\n * @remarks\n * `SolanaAssertionError` sets `Error.captureStackTrace` (available in V8\n * environments) to exclude the assertion function's own frame from the stack,\n * making the stack trace point to the caller rather than the assertion body.\n *\n * The prototype is explicitly reset via `Object.setPrototypeOf` to ensure\n * `instanceof` works correctly across CommonJS module boundary re-exports.\n *\n * @example\n * Catching and inspecting a failed assertion:\n * ```typescript\n * import { assertTransactionSignature, SolanaAssertionError } from \"./types\";\n *\n * try {\n *   assertTransactionSignature(\"invalid!sig\");\n * } catch (error) {\n *   if (error instanceof SolanaAssertionError) {\n *     console.error(`Expected: ${error.expectedType}`);\n *     console.error(`Constraint: ${error.constraint}`);\n *     console.error(`Got: ${String(error.value)}`);\n *   }\n * }\n * ```\n *\n * @public\n */\nexport class SolanaAssertionError extends Error {\n  /**\n   * The actual value that was passed to the assertion function and failed\n   * the type check.\n   *\n   * @remarks\n   * Typed as `unknown` because assertion functions accept values of unknown\n   * type before narrowing. Inspect carefully — the value may be `undefined`,\n   * `null`, or any primitive or object.\n   */\n  public readonly value: unknown;\n\n  /**\n   * The name of the expected type (e.g., `\"TransactionSignature\"`,\n   * `\"SignatureBytes\"`).\n   *\n   * @remarks\n   * Matches the TypeScript type name for the intended branded type, not a\n   * JavaScript `typeof` string.\n   */\n  public readonly expectedType: string;\n\n  /**\n   * A human-readable description of the specific constraint that was violated,\n   * if applicable.\n   *\n   * @remarks\n   * Examples:\n   * - `\"length > 0\"` — empty string passed to `assertTransactionSignature`\n   * - `\"length === 64\"` — wrong byte count passed to `assertSignatureBytes`\n   * - `\"characters must be in base58 alphabet: 123...xyz\"` — invalid character\n   *\n   * `undefined` when the only constraint is the TypeScript type itself\n   * (e.g., `assertString` only checks `typeof value === \"string\"`).\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.\n   * @param options - Structured context for the failed assertion.\n   * @param options.value - The value that failed the assertion.\n   * @param options.expectedType - The name of the expected branded type.\n   * @param options.constraint - The specific constraint that was violated, if any.\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 * STRING TYPES\n *\n * Branded string types for Solana-specific string representations.\n * ============================================================================= */\n\n/**\n * Root branded string type for the Solana types module.\n *\n * This is the base type from which all specialized Solana string types derive.\n * Branding it prevents raw `string` literals from being used where a validated\n * Solana string is required, while still allowing structural compatibility with\n * `string` via the underlying primitive.\n *\n * @remarks\n * Prefer the more specific sub-types (e.g., {@link TransactionSignature}) over\n * `String` when the string has additional semantic meaning. Use `String` only\n * when building generic utilities that operate on any validated Solana string\n * and need to accept multiple sub-brands.\n *\n * @example\n * ```typescript\n * function logSolanaString(s: String): void {\n *   console.log(\"Solana string:\", s);\n * }\n *\n * const raw = \"hello\";\n * assertString(raw);\n * logSolanaString(raw); // OK — raw is now branded as String\n * ```\n *\n * @see {@link assertString} for the corresponding runtime assertion\n * @public\n */\nexport type String = BrandedType<string, \"String\">;\n\n/**\n * Base58-encoded Solana transaction signature.\n *\n * A transaction signature is the result of an Ed25519 sign operation on the\n * serialized transaction message. Solana encodes it as a base58 string\n * (approximately 87–88 characters) for human-readable display and API usage.\n *\n * @remarks\n * **Encoding details:**\n * - Underlying binary: 64 bytes (see {@link SignatureBytes})\n * - Base58 alphabet: 58 characters (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`)\n * - Excluded characters: `0`, `O`, `I`, `l` (visually ambiguous)\n * - Typical string length: 87–88 characters\n *\n * **Type safety:** The {@link assertTransactionSignature} function validates\n * that a `string` value is non-empty and contains only Base58 characters before\n * branding it as `TransactionSignature`. This catches obvious data errors at\n * the ingestion boundary.\n *\n * **Note:** Validation is character-level only. The assertion does NOT verify\n * cryptographic correctness (i.e., it does not verify that the signature was\n * produced by a specific keypair).\n *\n * @example\n * Narrowing a raw string to `TransactionSignature`:\n * ```typescript\n * const raw = \"5wHu1qwD7q5menT3ydT9VdFPQfkLaWvqPgVbqsM1qwD7\";\n * assertTransactionSignature(raw);\n * // raw is now typed as TransactionSignature\n * ```\n *\n * @example\n * Using in a function signature:\n * ```typescript\n * async function getTransactionDetails(sig: TransactionSignature) {\n *   return await rpc.getTransaction(sig).send();\n * }\n * ```\n *\n * @see {@link assertTransactionSignature} for the runtime assertion\n * @see {@link SignatureBytes} for the raw binary equivalent\n * @public\n */\nexport type TransactionSignature = SubBrandedType<String, \"TransactionSignature\">;\n\n/* =============================================================================\n * BYTE ARRAY TYPES\n *\n * Branded byte array types for Solana-specific binary data.\n * ============================================================================= */\n\n/**\n * Root branded `Uint8Array` type for Solana binary data.\n *\n * This is the base type for all Solana-specific byte array types. It derives\n * from the generic `Bytes` type and adds the `\"SolanaBytes\"` nominal brand,\n * distinguishing Solana binary data from other `Uint8Array` values in the SDK.\n *\n * @remarks\n * No specific length constraint — the length depends on the particular data\n * being represented. Sub-types like {@link SignatureBytes} impose their own\n * length requirements.\n *\n * Use `SolanaBytes` when the binary data is Solana-specific but does not fall\n * into a more precise category (e.g., serialized account data, raw message\n * bytes).\n *\n * @example\n * ```typescript\n * const accountData = new Uint8Array([0x01, 0x02, 0x03, 0x04]);\n * assertSolanaBytes(accountData);\n * // accountData is now typed as SolanaBytes\n * ```\n *\n * @see {@link assertSolanaBytes} for the runtime assertion\n * @see {@link SignatureBytes} for the 64-byte Ed25519 signature sub-type\n * @public\n */\nexport type SolanaBytes = SubBrandedType<Bytes, \"SolanaBytes\">;\n\n/**\n * 64-byte raw Ed25519 signature in binary form.\n *\n * This type represents the binary encoding of an Ed25519 signature as used\n * internally by the Solana runtime and the `@solana/kit` library. It is the\n * binary equivalent of a {@link TransactionSignature} string — the same 64\n * bytes, without the Base58 encoding.\n *\n * @remarks\n * **Structure:**\n * - Bytes 0–31: R component — a compressed Ed25519 curve point\n * - Bytes 32–63: S component — a scalar in the range `[0, l)` where `l` is\n *   the order of the Ed25519 base point\n *\n * **Conversion:**\n * - `SignatureBytes` → `TransactionSignature`: Base58-encode the bytes\n * - `TransactionSignature` → `SignatureBytes`: Base58-decode the string\n *\n * The {@link assertSignatureBytes} function validates both that the value is a\n * `Uint8Array` and that it is exactly {@link SIGNATURE_BYTE_LENGTH} (64) bytes.\n *\n * @example\n * Creating and validating a signature byte array:\n * ```typescript\n * const sigBytes = new Uint8Array(64);\n * // ... fill sigBytes with actual Ed25519 signature material ...\n * assertSignatureBytes(sigBytes);\n * // sigBytes is now typed as SignatureBytes\n * ```\n *\n * @example\n * Using with a Solana transaction builder:\n * ```typescript\n * declare function attachSignature(\n *   tx: UnsignedTransaction,\n *   publicKey: Address,\n *   signature: SignatureBytes,\n * ): PartiallySignedTransaction;\n * ```\n *\n * @see {@link assertSignatureBytes} for the runtime assertion\n * @see {@link TransactionSignature} for the base58-encoded equivalent\n * @see {@link SIGNATURE_BYTE_LENGTH} for the required byte length constant\n * @public\n */\nexport type SignatureBytes = SubSubBrandedType<SolanaBytes, \"SignatureBytes\">;\n\n/* =============================================================================\n * TRANSACTION TYPES\n *\n * Branded transaction types for compile-time transaction state safety.\n * These types wrap the @solana/kit Transaction type with state information.\n * ============================================================================= */\n\n/**\n * An unsigned Solana transaction — a transaction that has been constructed\n * but has not yet received any signatures.\n *\n * @remarks\n * This type wraps `Transaction` from `@solana/kit` with the `\"UnsignedTransaction\"`\n * brand. The brand prevents an unsigned transaction from being passed to a\n * `TransactionForwarder` or any function that requires a {@link SignedTransaction},\n * catching the mistake at compile time.\n *\n * **Lifecycle:** Build the transaction message → compile to `Transaction` →\n * brand as `UnsignedTransaction` → sign to produce {@link SignedTransaction}.\n *\n * @example\n * Type-safe transaction building:\n * ```typescript\n * import { UnsignedTransaction } from \"./types\";\n *\n * function buildTransfer(from: Address, to: Address, amount: bigint): UnsignedTransaction {\n *   // ... build and compile message ...\n *   return compiledTx as UnsignedTransaction;\n * }\n *\n * const tx = buildTransfer(sender, recipient, 1_000_000n);\n * // tx cannot be passed to forwarder.forwardSequentially — compile error\n * ```\n *\n * @see {@link SignedTransaction} for the signed counterpart\n * @public\n */\nexport type UnsignedTransaction = BrandedType<Transaction, \"UnsignedTransaction\">;\n\n/**\n * A Solana transaction that has at least one signature and a blockhash\n * lifetime constraint.\n *\n * This is the base type for all signed transaction variants. It intersects\n * `Transaction` with `TransactionWithBlockhashLifetime` from `@solana/kit`,\n * ensuring the blockhash expiry window (`blockhash` + `lastValidBlockHeight`)\n * is present alongside the signature data.\n *\n * @remarks\n * **Blockhash lifetime** — The `TransactionWithBlockhashLifetime` intersection\n * ensures that every `SignedTransaction` carries `lifetimeConstraint.blockhash`\n * and `lifetimeConstraint.lastValidBlockHeight`. The forwarder uses these to\n * detect expiry before submission.\n *\n * **Sub-types** — `SignedTransaction` is the common type used in forwarder\n * method signatures because it accepts both {@link PartiallySignedTransaction}\n * and {@link FullySignedTransaction}. Use the more specific sub-types when the\n * exact signing completeness matters to the API contract.\n *\n * @example\n * Accepting any signed transaction (partial or full):\n * ```typescript\n * function logSignedTx(tx: SignedTransaction): void {\n *   console.log(`Valid until block: ${tx.lifetimeConstraint.lastValidBlockHeight}`);\n * }\n * ```\n *\n * @see {@link PartiallySignedTransaction} for partial signing state\n * @see {@link FullySignedTransaction} for full signing state\n * @see {@link UnsignedTransaction} for the unsigned state\n * @public\n */\nexport type SignedTransaction = BrandedType<\n  Transaction & TransactionWithBlockhashLifetime,\n  \"SignedTransaction\"\n>;\n\n/**\n * A Solana transaction with some but potentially not all required signatures.\n *\n * A sub-brand of {@link SignedTransaction}. The transaction has been signed by\n * at least one party but may still be missing signatures from other required\n * signers. This state is common in multi-signature workflows where different\n * parties sign at different times or different locations.\n *\n * @remarks\n * In the Umbra SDK, partial signing arises when:\n * - The user's wallet signs the transaction locally.\n * - The relayer counter-signs before submission.\n * - A hardware wallet adds its signature after an initial software signature.\n *\n * A `PartiallySignedTransaction` cannot be submitted to the network until all\n * required signatures are collected, at which point it can be cast (or built\n * up) to {@link FullySignedTransaction}.\n *\n * @example\n * Multi-sig workflow:\n * ```typescript\n * const partial: PartiallySignedTransaction = await userWallet.sign(unsigned);\n * const full: FullySignedTransaction = await relayer.countersign(partial);\n * await forwarder.forwardSequentially([full]);\n * ```\n *\n * @see {@link FullySignedTransaction} for the fully-signed state\n * @see {@link SignedTransaction} for the base signed state\n * @public\n */\nexport type PartiallySignedTransaction = SubBrandedType<\n  SignedTransaction,\n  \"PartiallySignedTransaction\"\n>;\n\n/**\n * A Solana transaction with all required signatures present and ready for\n * network submission.\n *\n * This is the terminal transaction state in the signing lifecycle. A\n * `FullySignedTransaction` has been signed by every required signer and can be\n * submitted to the Solana network via a {@link TransactionForwarder}.\n *\n * @remarks\n * **Compile-time guarantee** — The {@link TransactionForwarder} interface's\n * `forwardSequentially` and `forwardInParallel` methods accept\n * `readonly SignedTransaction[]` (the common base type). Callers that track\n * signing state explicitly can use `FullySignedTransaction` in their own\n * function signatures to signal that all signatures are present.\n *\n * **Branding vs. validation** — The brand is a compile-time assertion — the\n * runtime does NOT verify that all required pubkeys have corresponding\n * signatures. It is the responsibility of the signing workflow to ensure\n * completeness before casting to `FullySignedTransaction`.\n *\n * @example\n * Enforcing full signing at a function boundary:\n * ```typescript\n * import { FullySignedTransaction } from \"./types\";\n * import type { TransactionForwarder } from \"./interfaces\";\n *\n * async function submitAll(\n *   forwarder: TransactionForwarder,\n *   txs: readonly FullySignedTransaction[],\n * ) {\n *   return forwarder.forwardSequentially(txs);\n * }\n * ```\n *\n * @see {@link PartiallySignedTransaction} for partial signing state\n * @see {@link SignedTransaction} for the base signed state\n * @see {@link TransactionForwarder} for the submission interface\n * @public\n */\nexport type FullySignedTransaction = SubSubBrandedType<\n  PartiallySignedTransaction,\n  \"FullySignedTransaction\"\n>;\n\n/* =============================================================================\n * STRING ASSERTIONS\n *\n * Assertion functions for Solana string types.\n * ============================================================================= */\n\n/**\n * Asserts that a value is a primitive `string` and narrows it to {@link String}.\n *\n * This is the base assertion for all Solana branded string types. It only\n * checks that the input is a primitive `string` — no format or content\n * validation is performed.\n *\n * @param value - The value to assert. Must be a primitive string.\n * @throws {SolanaAssertionError} If `typeof value !== \"string\"`.\n *\n * @remarks\n * For more specific string types, use the dedicated assertion functions:\n * - {@link assertTransactionSignature} — for base58-encoded signatures\n *\n * @example\n * ```typescript\n * const raw: unknown = \"hello world\";\n * assertString(raw as string);\n * // raw is now typed as String\n *\n * assertString(123 as unknown as string); // Throws: not a string\n * assertString(null as unknown as string); // Throws: not a string\n * ```\n *\n * @see {@link String} for the branded type\n * @see {@link assertTransactionSignature} for the signature-specific assertion\n * @public\n */\nexport function assertString(value: string): asserts value is String {\n  if (typeof value !== \"string\") {\n    throw new SolanaAssertionError(`Expected string, got ${typeof value}`, {\n      value,\n      expectedType: \"String\",\n    });\n  }\n}\n\n/**\n * Asserts that a value is a valid base58-encoded Solana transaction signature\n * and narrows it to {@link TransactionSignature}.\n *\n * Validation rules:\n * 1. `typeof value === \"string\"`\n * 2. `value.length > 0` (non-empty)\n * 3. Every character is in the Base58 alphabet (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`)\n *\n * @param value - The string to assert as a base58 transaction signature.\n * @throws {SolanaAssertionError} If the value is not a string, is empty, or\n *   contains characters outside the Base58 alphabet. The error's `constraint`\n *   field identifies which rule was violated, and for alphabet violations,\n *   includes the position and character that failed.\n *\n * @remarks\n * **Validation scope** — This function performs character-level validation only.\n * It does NOT verify cryptographic correctness (i.e., it does not check that\n * the 64 decoded bytes constitute a valid Ed25519 signature, nor that the\n * signature was produced by any particular keypair).\n *\n * **Excluded characters** — The Base58 alphabet deliberately omits `0` (zero),\n * `O` (capital O), `I` (capital I), and `l` (lowercase L) to avoid\n * transcription errors. Any of these characters in `value` will cause a throw.\n *\n * **Typical usage** — Call this function at SDK ingestion boundaries (e.g.,\n * when accepting a signature string from user input or an external API) to\n * ensure downstream code only ever sees branded, validated values.\n *\n * @example\n * Validating a signature from an external source:\n * ```typescript\n * const rawSig: string = apiResponse.signature;\n * assertTransactionSignature(rawSig);\n * // rawSig is now typed as TransactionSignature\n * ```\n *\n * @example\n * Invalid inputs:\n * ```typescript\n * assertTransactionSignature(\"\");            // Throws: empty string\n * assertTransactionSignature(\"hello!world\"); // Throws: invalid char '!'\n * assertTransactionSignature(\"0abc\");        // Throws: '0' not in Base58\n * assertTransactionSignature(\"IIII\");        // Throws: 'I' not in Base58\n * ```\n *\n * @see {@link TransactionSignature} for the branded type\n * @see {@link SignatureBytes} for the binary equivalent\n * @public\n */\nexport function assertTransactionSignature(value: string): asserts value is TransactionSignature {\n  if (typeof value !== \"string\") {\n    throw new SolanaAssertionError(`Expected string, got ${typeof value}`, {\n      value,\n      expectedType: \"TransactionSignature\",\n    });\n  }\n\n  if (value.length === 0) {\n    throw new SolanaAssertionError(\"Transaction signature cannot be empty\", {\n      value,\n      expectedType: \"TransactionSignature\",\n      constraint: \"length > 0\",\n    });\n  }\n\n  if (!BASE58_REGEX.test(value)) {\n    // Find the first invalid character for a helpful error message\n    let invalidChar = \"\";\n    let invalidIndex = -1;\n\n    for (const [index, element] of Array.from(value).entries()) {\n      if (!BASE58_ALPHABET.includes(element)) {\n        invalidChar = element;\n        invalidIndex = index;\n        break;\n      }\n    }\n\n    throw new SolanaAssertionError(\n      `Invalid base58 character '${invalidChar}' at position ${String(invalidIndex)}`,\n      {\n        value,\n        expectedType: \"TransactionSignature\",\n        constraint: `characters must be in base58 alphabet: ${BASE58_ALPHABET}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * BYTE ARRAY ASSERTIONS\n *\n * Assertion functions for Solana byte array types.\n * ============================================================================= */\n\n/**\n * Asserts that a value is a `Uint8Array` and narrows it to {@link SolanaBytes}.\n *\n * This is the base assertion for all Solana byte array types. It only checks\n * that the input is a `Uint8Array` instance — no length validation is performed.\n *\n * @param value - The `Uint8Array` to assert. Must be an instance of `Uint8Array`.\n * @throws {SolanaAssertionError} If `!(value instanceof Uint8Array)`.\n *\n * @remarks\n * For byte arrays with specific length requirements, use the more specific\n * assertion function:\n * - {@link assertSignatureBytes} — for 64-byte Ed25519 signature arrays\n *\n * @example\n * ```typescript\n * const data = new Uint8Array([0x01, 0x02, 0x03, 0x04]);\n * assertSolanaBytes(data);\n * // data is now typed as SolanaBytes\n *\n * assertSolanaBytes([] as unknown as Uint8Array);     // Throws: not a Uint8Array\n * assertSolanaBytes(\"bytes\" as unknown as Uint8Array); // Throws: not a Uint8Array\n * ```\n *\n * @see {@link SolanaBytes} for the branded type\n * @see {@link assertSignatureBytes} for the length-constrained variant\n * @public\n */\nexport function assertSolanaBytes(value: Uint8Array): asserts value is SolanaBytes {\n  if (!(value instanceof Uint8Array)) {\n    throw new SolanaAssertionError(`Expected Uint8Array, got ${typeof value}`, {\n      value,\n      expectedType: \"SolanaBytes\",\n    });\n  }\n}\n\n/**\n * Asserts that a value is a `Uint8Array` of exactly {@link SIGNATURE_BYTE_LENGTH}\n * (64) bytes and narrows it to {@link SignatureBytes}.\n *\n * Validation rules:\n * 1. `value instanceof Uint8Array`\n * 2. `value.length === 64`\n *\n * @param value - The `Uint8Array` to assert as a 64-byte Ed25519 signature.\n * @throws {SolanaAssertionError} If the value is not a `Uint8Array` or is not\n *   exactly 64 bytes. The error's `constraint` field specifies\n *   `\"length === 64\"` for length violations.\n *\n * @remarks\n * The 64-byte requirement is defined by the Ed25519 specification and is\n * invariant across all Solana Ed25519 signatures. Passing a 63- or 65-byte\n * array will always throw, regardless of the content.\n *\n * **Structure:**\n * - Bytes 0–31: R component (compressed curve point)\n * - Bytes 32–63: S component (scalar)\n *\n * @example\n * Validating a signature byte array:\n * ```typescript\n * const sigBytes = new Uint8Array(64);\n * // ... populate with actual Ed25519 signature bytes ...\n * assertSignatureBytes(sigBytes);\n * // sigBytes is now typed as SignatureBytes\n * ```\n *\n * @example\n * Invalid inputs:\n * ```typescript\n * assertSignatureBytes(new Uint8Array(63)); // Throws: expected 64 bytes, got 63\n * assertSignatureBytes(new Uint8Array(65)); // Throws: expected 64 bytes, got 65\n * assertSignatureBytes([] as unknown as Uint8Array); // Throws: not a Uint8Array\n * ```\n *\n * @see {@link SignatureBytes} for the branded type\n * @see {@link SIGNATURE_BYTE_LENGTH} for the required length constant\n * @see {@link TransactionSignature} for the base58-encoded equivalent\n * @public\n */\nexport function assertSignatureBytes(value: Uint8Array): asserts value is SignatureBytes {\n  if (!(value instanceof Uint8Array)) {\n    throw new SolanaAssertionError(`Expected Uint8Array, got ${typeof value}`, {\n      value,\n      expectedType: \"SignatureBytes\",\n    });\n  }\n\n  if (value.length !== SIGNATURE_BYTE_LENGTH) {\n    throw new SolanaAssertionError(\n      `Expected ${String(SIGNATURE_BYTE_LENGTH)} bytes, got ${String(value.length)}`,\n      {\n        value,\n        expectedType: \"SignatureBytes\",\n        constraint: `length === ${String(SIGNATURE_BYTE_LENGTH)}`,\n      },\n    );\n  }\n}\n\n/**\n * Brands a compiled `Transaction` as a {@link SignedTransaction} for relay\n * submission.\n *\n * @remarks\n * This function is used for transactions that will be signed by the **relayer**,\n * not by the client. In the Umbra relay flow, the client builds and serializes\n * a transaction message, which is then passed to the relayer service. The\n * relayer signs and submits the transaction. Because the blockhash lifetime is\n * already embedded in the compiled message bytes (`messageBytes`), the\n * transaction is treated as carrying a blockhash constraint even though\n * `lifetimeConstraint` is not set as a TypeScript property.\n *\n * **This is an escape hatch** — it performs an unchecked cast. Use only when\n * you are certain the compiled message bytes include a valid blockhash and the\n * relayer will supply the required signature before submission.\n *\n * @param tx - A `Transaction` object whose compiled message bytes already\n *   embed the blockhash lifetime constraint.\n * @returns The same `Transaction` value cast to {@link SignedTransaction}.\n *\n * @example\n * ```typescript\n * import { asRelayableSignedTransaction } from \"./types\";\n *\n * const compiledTx: Transaction = compileTransactionMessage(txMessage);\n * const relayable = asRelayableSignedTransaction(compiledTx);\n * // relayable can now be passed to relayer submission APIs\n * ```\n *\n * @public\n */\nexport function asRelayableSignedTransaction(tx: Transaction): SignedTransaction {\n  return tx as SignedTransaction;\n}\n","/**\n * Temporal Types\n *\n * This module defines branded types for timestamp components used in\n * time-scoped viewing key derivation. These types provide compile-time\n * safety for temporal values with runtime validation.\n *\n * ## Overview\n *\n * The module provides a hierarchical type system:\n * - `TimestampComponent` - Base branded type for all timestamp values\n * - `Year`, `Month`, `Day`, `Hour`, `Minute`, `Second` - Subbranded types\n *\n * ## Validation Ranges\n *\n * - Year: 0 to 9999 (reasonable range for most applications)\n * - Month: 1 to 12\n * - Day: 1 to 31\n * - Hour: 0 to 23\n * - Minute: 0 to 59\n * - Second: 0 to 59\n *\n * @remarks\n * All temporal component types are encoded as `bigint` to integrate directly with the BN254\n * field arithmetic used in viewing key derivation. The branded type system prevents accidentally\n * passing a `Month` where a `Year` is expected, catching a class of derivation-key bugs at\n * compile time.\n *\n * @packageDocumentation\n * @module common/temporal/types\n */\n\nimport type { BrandedType, SubBrandedType } from \"../branded\";\n\n/* =============================================================================\n * CONSTANTS\n * ============================================================================= */\n\n/**\n * Minimum valid year value (inclusive).\n *\n * @remarks Year 0 corresponds to 1 BCE in the proleptic Gregorian calendar.\n * @see {@link YEAR_MAX}\n * @see {@link assertYear}\n * @public\n */\nexport const YEAR_MIN = 0n;\n\n/**\n * Maximum valid year value (inclusive).\n *\n * @remarks Upper bound chosen to comfortably cover all practical use cases.\n * @see {@link YEAR_MIN}\n * @see {@link assertYear}\n * @public\n */\nexport const YEAR_MAX = 9999n;\n\n/**\n * Minimum valid month value (inclusive).\n *\n * @remarks January is represented as 1, following the ISO 8601 convention.\n * @see {@link MONTH_MAX}\n * @see {@link assertMonth}\n * @public\n */\nexport const MONTH_MIN = 1n;\n\n/**\n * Maximum valid month value (inclusive).\n *\n * @remarks December is represented as 12.\n * @see {@link MONTH_MIN}\n * @see {@link assertMonth}\n * @public\n */\nexport const MONTH_MAX = 12n;\n\n/**\n * Minimum valid day value (inclusive).\n *\n * @remarks The first day of any month.\n * @see {@link DAY_MAX}\n * @see {@link assertDay}\n * @public\n */\nexport const DAY_MIN = 1n;\n\n/**\n * Maximum valid day value (inclusive).\n *\n * @remarks\n * Set to 31 to accommodate all months. Month-specific validation (e.g., February having at most\n * 28 or 29 days) is not enforced here and must be handled at the application level if needed.\n *\n * @see {@link DAY_MIN}\n * @see {@link assertDay}\n * @public\n */\nexport const DAY_MAX = 31n;\n\n/**\n * Minimum valid hour value (inclusive), in 24-hour format.\n *\n * @see {@link HOUR_MAX}\n * @see {@link assertHour}\n * @public\n */\nexport const HOUR_MIN = 0n;\n\n/**\n * Maximum valid hour value (inclusive), in 24-hour format.\n *\n * @see {@link HOUR_MIN}\n * @see {@link assertHour}\n * @public\n */\nexport const HOUR_MAX = 23n;\n\n/**\n * Minimum valid minute value (inclusive).\n *\n * @see {@link MINUTE_MAX}\n * @see {@link assertMinute}\n * @public\n */\nexport const MINUTE_MIN = 0n;\n\n/**\n * Maximum valid minute value (inclusive).\n *\n * @see {@link MINUTE_MIN}\n * @see {@link assertMinute}\n * @public\n */\nexport const MINUTE_MAX = 59n;\n\n/**\n * Minimum valid second value (inclusive).\n *\n * @see {@link SECOND_MAX}\n * @see {@link assertSecond}\n * @public\n */\nexport const SECOND_MIN = 0n;\n\n/**\n * Maximum valid second value (inclusive).\n *\n * @remarks Leap seconds (value 60) are not supported.\n * @see {@link SECOND_MIN}\n * @see {@link assertSecond}\n * @public\n */\nexport const SECOND_MAX = 59n;\n\n/* =============================================================================\n * ASSERTION ERROR\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 * Every `assertXxx` function in this module throws `TemporalAssertionError` on failure.\n * Catch this specific type to distinguish temporal validation failures from other 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 *     }\n * }\n * ```\n *\n * @sealed\n * @public\n */\nexport class TemporalAssertionError extends Error {\n  /**\n   * The actual value that failed the assertion.\n   * @readonly\n   */\n  public readonly value: unknown;\n\n  /**\n   * The type that was expected (e.g., `\"Month\"`, `\"Hour\"`).\n   * @readonly\n   */\n  public readonly expectedType: string;\n\n  /**\n   * Description of the constraint that was violated.\n   *\n   * @remarks\n   * `undefined` when the failure was a type mismatch (e.g., received a number instead of a\n   * bigint). Contains a human-readable range string (e.g., `\"1 <= value <= 12\"`) when the\n   * value was the correct type but out of the valid range.\n   * @readonly\n   */\n  public readonly constraint: string | undefined;\n\n  /**\n   * Creates a new TemporalAssertionError.\n   *\n   * @param message - Human-readable description of what went wrong\n   * @param details - Structured error details for programmatic inspection\n   * @param details.value - The value that failed the assertion\n   * @param details.expectedType - Name of the branded type that was expected\n   * @param details.constraint - Optional human-readable constraint that was violated\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\n/* =============================================================================\n * BASE TIMESTAMP COMPONENT TYPE\n * ============================================================================= */\n\n/**\n * Base branded type for all timestamp components.\n *\n * `TimestampComponent` is a branded bigint that serves as the parent type for all\n * calendar-component types: `Year`, `Month`, `Day`, `Hour`, `Minute`, and `Second`.\n *\n * @remarks\n * All timestamp component types are subbrands of `TimestampComponent`. Code that accepts\n * any calendar component without caring which one (e.g., a generic key-derivation utility)\n * can accept `TimestampComponent` as its parameter type.\n *\n * @example\n * ```typescript\n * import { TimestampComponent, assertTimestampComponent } from \"./temporal\";\n *\n * const value: bigint = 2024n;\n * assertTimestampComponent(value);\n * // Now value is typed as TimestampComponent\n * ```\n *\n * @see {@link Year}\n * @see {@link Month}\n * @see {@link Day}\n * @see {@link Hour}\n * @see {@link Minute}\n * @see {@link Second}\n * @public\n */\nexport type TimestampComponent = BrandedType<bigint, \"TimestampComponent\">;\n\n/**\n * Asserts that a value is a valid TimestampComponent (non-negative bigint).\n *\n * @param value - The bigint to validate (must be `>= 0`)\n * @throws {TemporalAssertionError} If value is not a bigint or is negative\n * @returns `void` — narrows the type of `value` to `TimestampComponent` on success\n *\n * @example\n * ```typescript\n * const value = 100n;\n * assertTimestampComponent(value);\n * // value is now typed as TimestampComponent\n * ```\n *\n * @public\n */\nexport function assertTimestampComponent(value: bigint): asserts value is TimestampComponent {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"TimestampComponent\",\n    });\n  }\n  if (value < 0n) {\n    throw new TemporalAssertionError(`TimestampComponent must be non-negative`, {\n      value,\n      expectedType: \"TimestampComponent\",\n      constraint: \"value >= 0\",\n    });\n  }\n}\n\n/* =============================================================================\n * YEAR TYPE\n * ============================================================================= */\n\n/**\n * Branded type for year values in the Gregorian calendar.\n *\n * `Year` is a subbrand of `TimestampComponent` used to represent the year component of a\n * UTC timestamp in time-scoped viewing key derivation. Valid range: `YEAR_MIN` (0) to\n * `YEAR_MAX` (9999).\n *\n * @remarks\n * The type distinction between `Year`, `Month`, `Day`, etc. is intentional: passing\n * a `Month` value where a `Year` is expected is a compile-time error, preventing\n * subtle key-derivation bugs.\n *\n * @example\n * ```typescript\n * import { Year, assertYear } from \"./temporal\";\n *\n * const year: bigint = 2024n;\n * assertYear(year);\n * // year is now typed as Year\n *\n * const generator = getYearlyViewingKeyDeriver({ masterViewingKey });\n * const key = await generator(mint, year);\n * ```\n *\n * @see {@link assertYear}\n * @see {@link YEAR_MIN}\n * @see {@link YEAR_MAX}\n * @public\n */\nexport type Year = SubBrandedType<TimestampComponent, \"Year\">;\n\n/**\n * Asserts that a value is a valid `Year` in the range `[YEAR_MIN, YEAR_MAX]` (0–9999).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[YEAR_MIN, YEAR_MAX]`\n * @returns `void` — narrows the type of `value` to `Year` on success\n *\n * @example\n * ```typescript\n * const year = 2024n;\n * assertYear(year);\n * // year is now typed as Year\n * ```\n *\n * @public\n */\nexport function assertYear(value: bigint): asserts value is Year {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Year\",\n    });\n  }\n  if (value < YEAR_MIN || value > YEAR_MAX) {\n    throw new TemporalAssertionError(\n      `Year must be in range [${String(YEAR_MIN)}, ${String(YEAR_MAX)}]`,\n      {\n        value,\n        expectedType: \"Year\",\n        constraint: `${String(YEAR_MIN)} <= value <= ${String(YEAR_MAX)}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * MONTH TYPE\n * ============================================================================= */\n\n/**\n * Branded type for month values in the Gregorian calendar (1 = January, 12 = December).\n *\n * `Month` is a subbrand of `TimestampComponent`. Valid range: `MONTH_MIN` (1) to\n * `MONTH_MAX` (12).\n *\n * @example\n * ```typescript\n * import { Month, assertMonth } from \"./temporal\";\n *\n * const month: bigint = 6n; // June\n * assertMonth(month);\n * // month is now typed as Month\n * ```\n *\n * @see {@link assertMonth}\n * @see {@link MONTH_MIN}\n * @see {@link MONTH_MAX}\n * @public\n */\nexport type Month = SubBrandedType<TimestampComponent, \"Month\">;\n\n/**\n * Asserts that a value is a valid `Month` in the range `[MONTH_MIN, MONTH_MAX]` (1–12).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[MONTH_MIN, MONTH_MAX]`\n * @returns `void` — narrows the type of `value` to `Month` on success\n *\n * @example\n * ```typescript\n * const month = 6n;\n * assertMonth(month);\n * // month is now typed as Month\n * ```\n *\n * @public\n */\nexport function assertMonth(value: bigint): asserts value is Month {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Month\",\n    });\n  }\n  if (value < MONTH_MIN || value > MONTH_MAX) {\n    throw new TemporalAssertionError(\n      `Month must be in range [${String(MONTH_MIN)}, ${String(MONTH_MAX)}]`,\n      {\n        value,\n        expectedType: \"Month\",\n        constraint: `${String(MONTH_MIN)} <= value <= ${String(MONTH_MAX)}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * DAY TYPE\n * ============================================================================= */\n\n/**\n * Branded type for day-of-month values in the Gregorian calendar.\n *\n * `Day` is a subbrand of `TimestampComponent`. Valid range: `DAY_MIN` (1) to `DAY_MAX` (31).\n *\n * @remarks\n * This type does not enforce month-specific day limits (e.g., February has 28 or 29 days).\n * Additional calendar validation must be performed by the application if required.\n *\n * @example\n * ```typescript\n * import { Day, assertDay } from \"./temporal\";\n *\n * const day: bigint = 15n;\n * assertDay(day);\n * // day is now typed as Day\n * ```\n *\n * @see {@link assertDay}\n * @see {@link DAY_MIN}\n * @see {@link DAY_MAX}\n * @public\n */\nexport type Day = SubBrandedType<TimestampComponent, \"Day\">;\n\n/**\n * Asserts that a value is a valid `Day` in the range `[DAY_MIN, DAY_MAX]` (1–31).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[DAY_MIN, DAY_MAX]`\n * @returns `void` — narrows the type of `value` to `Day` on success\n *\n * @example\n * ```typescript\n * const day = 15n;\n * assertDay(day);\n * // day is now typed as Day\n * ```\n *\n * @public\n */\nexport function assertDay(value: bigint): asserts value is Day {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Day\",\n    });\n  }\n  if (value < DAY_MIN || value > DAY_MAX) {\n    throw new TemporalAssertionError(\n      `Day must be in range [${String(DAY_MIN)}, ${String(DAY_MAX)}]`,\n      {\n        value,\n        expectedType: \"Day\",\n        constraint: `${String(DAY_MIN)} <= value <= ${String(DAY_MAX)}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * HOUR TYPE\n * ============================================================================= */\n\n/**\n * Branded type for hour-of-day values in 24-hour format.\n *\n * `Hour` is a subbrand of `TimestampComponent`. Valid range: `HOUR_MIN` (0) to `HOUR_MAX` (23).\n *\n * @remarks\n * Uses 24-hour clock convention: midnight is 0, noon is 12, and 11 PM is 23.\n *\n * @example\n * ```typescript\n * import { Hour, assertHour } from \"./temporal\";\n *\n * const hour: bigint = 14n; // 2 PM\n * assertHour(hour);\n * // hour is now typed as Hour\n * ```\n *\n * @see {@link assertHour}\n * @see {@link HOUR_MIN}\n * @see {@link HOUR_MAX}\n * @public\n */\nexport type Hour = SubBrandedType<TimestampComponent, \"Hour\">;\n\n/**\n * Asserts that a value is a valid `Hour` in the range `[HOUR_MIN, HOUR_MAX]` (0–23).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[HOUR_MIN, HOUR_MAX]`\n * @returns `void` — narrows the type of `value` to `Hour` on success\n *\n * @example\n * ```typescript\n * const hour = 14n;\n * assertHour(hour);\n * // hour is now typed as Hour\n * ```\n *\n * @public\n */\nexport function assertHour(value: bigint): asserts value is Hour {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Hour\",\n    });\n  }\n  if (value < HOUR_MIN || value > HOUR_MAX) {\n    throw new TemporalAssertionError(\n      `Hour must be in range [${String(HOUR_MIN)}, ${String(HOUR_MAX)}]`,\n      {\n        value,\n        expectedType: \"Hour\",\n        constraint: `${String(HOUR_MIN)} <= value <= ${String(HOUR_MAX)}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * MINUTE TYPE\n * ============================================================================= */\n\n/**\n * Branded type for minute-of-hour values.\n *\n * `Minute` is a subbrand of `TimestampComponent`. Valid range: `MINUTE_MIN` (0) to\n * `MINUTE_MAX` (59).\n *\n * @example\n * ```typescript\n * import { Minute, assertMinute } from \"./temporal\";\n *\n * const minute: bigint = 30n;\n * assertMinute(minute);\n * // minute is now typed as Minute\n * ```\n *\n * @see {@link assertMinute}\n * @see {@link MINUTE_MIN}\n * @see {@link MINUTE_MAX}\n * @public\n */\nexport type Minute = SubBrandedType<TimestampComponent, \"Minute\">;\n\n/**\n * Asserts that a value is a valid `Minute` in the range `[MINUTE_MIN, MINUTE_MAX]` (0–59).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[MINUTE_MIN, MINUTE_MAX]`\n * @returns `void` — narrows the type of `value` to `Minute` on success\n *\n * @example\n * ```typescript\n * const minute = 30n;\n * assertMinute(minute);\n * // minute is now typed as Minute\n * ```\n *\n * @public\n */\nexport function assertMinute(value: bigint): asserts value is Minute {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Minute\",\n    });\n  }\n  if (value < MINUTE_MIN || value > MINUTE_MAX) {\n    throw new TemporalAssertionError(\n      `Minute must be in range [${String(MINUTE_MIN)}, ${String(MINUTE_MAX)}]`,\n      {\n        value,\n        expectedType: \"Minute\",\n        constraint: `${String(MINUTE_MIN)} <= value <= ${String(MINUTE_MAX)}`,\n      },\n    );\n  }\n}\n\n/* =============================================================================\n * SECOND TYPE\n * ============================================================================= */\n\n/**\n * Branded type for second-of-minute values.\n *\n * `Second` is a subbrand of `TimestampComponent`. Valid range: `SECOND_MIN` (0) to\n * `SECOND_MAX` (59). Leap seconds (value 60) are not supported.\n *\n * @example\n * ```typescript\n * import { Second, assertSecond } from \"./temporal\";\n *\n * const second: bigint = 45n;\n * assertSecond(second);\n * // second is now typed as Second\n * ```\n *\n * @see {@link assertSecond}\n * @see {@link SECOND_MIN}\n * @see {@link SECOND_MAX}\n * @public\n */\nexport type Second = SubBrandedType<TimestampComponent, \"Second\">;\n\n/**\n * Asserts that a value is a valid `Second` in the range `[SECOND_MIN, SECOND_MAX]` (0–59).\n *\n * @param value - The bigint to validate\n * @throws {TemporalAssertionError} If `value` is not a bigint or is outside `[SECOND_MIN, SECOND_MAX]`\n * @returns `void` — narrows the type of `value` to `Second` on success\n *\n * @example\n * ```typescript\n * const second = 45n;\n * assertSecond(second);\n * // second is now typed as Second\n * ```\n *\n * @public\n */\nexport function assertSecond(value: bigint): asserts value is Second {\n  if (typeof value !== \"bigint\") {\n    throw new TemporalAssertionError(`Expected bigint, got ${typeof value}`, {\n      value,\n      expectedType: \"Second\",\n    });\n  }\n  if (value < SECOND_MIN || value > SECOND_MAX) {\n    throw new TemporalAssertionError(\n      `Second must be in range [${String(SECOND_MIN)}, ${String(SECOND_MAX)}]`,\n      {\n        value,\n        expectedType: \"Second\",\n        constraint: `${String(SECOND_MIN)} <= value <= ${String(SECOND_MAX)}`,\n      },\n    );\n  }\n}\n"]}