@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/types-CxfTIpN9.d.ts

@@ -0,0 +1,1052 @@
+import { N as Network } from './versions-BRlR36EA.js';
+import { h as U512, b as SubBrandedType, g as BrandedType, S as SubSubBrandedType, B as Bytes } from './types-C_V_CaKK.js';
+import { M as MasterSeed } from './cryptography-BFSJcvi6.js';
+import { Transaction, TransactionWithBlockhashLifetime } from '@solana/kit';
+
+/**
+ * Storage Types for Key Management
+ *
+ * This module defines types and interfaces for loading, storing, and generating
+ * cryptographic keys and derived values. The storage system supports both persistent
+ * storage (e.g., IndexedDB, local storage) and ephemeral storage (in-memory only).
+ *
+ * @remarks
+ * The storage abstraction allows callers to supply custom persistence backends for
+ * the SDK's cryptographic keys without coupling the SDK to any particular storage
+ * technology. The most security-sensitive type here is `MasterSeed`, whose loader,
+ * storer, and generator functions control the full lifecycle of the root key.
+ *
+ * All load/store operations are asynchronous to support remote key management services
+ * (e.g., cloud HSMs, encrypted databases) without blocking the main thread.
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module types/storage
+ */
+
+/**
+ * Result of a load operation.
+ *
+ * @remarks
+ * A discriminated union that signals whether a stored value was found. When `exists` is
+ * `true`, the `seed` field contains the loaded value. When `exists` is `false`, the caller
+ * should generate a new value and store it.
+ *
+ * @typeParam T - The type of value being loaded
+ *
+ * @example
+ * ```typescript
+ * const result = await loadMasterSeed();
+ * if (result.exists) {
+ *   // Use result.seed
+ * } else {
+ *   // Generate and store a new seed
+ * }
+ * ```
+ *
+ * @public
+ */
+type LoadResult<T> = {
+    readonly exists: true;
+    readonly seed: T;
+} | {
+    readonly exists: false;
+};
+/**
+ * Result of a store operation.
+ *
+ * @remarks
+ * A discriminated union that signals whether the store succeeded. When `success` is `false`,
+ * the `error` field contains a human-readable description of what went wrong (e.g., quota
+ * exceeded, permission denied, serialization failure).
+ *
+ * @example
+ * ```typescript
+ * const result = await storeMasterSeed(seed);
+ * if (!result.success) {
+ *   console.error("Failed to persist seed:", result.error);
+ *   // Optionally continue with in-memory seed only
+ * }
+ * ```
+ *
+ * @public
+ */
+type StoreResult = {
+    readonly success: true;
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Context information for key storage operations.
+ *
+ * This context is passed to load and store functions to provide all the necessary
+ * information about the key being stored or loaded, including versioning information,
+ * network, and derivation parameters.
+ *
+ * @remarks
+ * The context ensures that keys are stored and retrieved with the correct version and
+ * parameter information, preventing version mismatches across SDK upgrades. The combination
+ * of `signerAddress`, `network`, `domainSeparator`, and all three version strings forms a
+ * unique storage key that can be used as a lookup identifier in any key-value store.
+ *
+ * @example
+ * ```typescript
+ * const context: KeyStorageContext = {
+ *   signerAddress: "7xKXt...",
+ *   domainSeparator: "MasterViewingKey/0",
+ *   network: "mainnet-beta",
+ *   protocolVersion: "1.0.0",
+ *   algorithmVersion: "1.0.0",
+ *   schemeVersion: "1.0.0",
+ * };
+ * const result = await loaderFn(context);
+ * ```
+ *
+ * @public
+ */
+interface KeyStorageContext {
+    /**
+     * The signer's public key / wallet address (user identifier).
+     *
+     * @remarks
+     * Used to namespace stored keys per user so that multiple wallets can use the same
+     * storage backend without interference.
+     * @readonly
+     */
+    readonly signerAddress: string;
+    /**
+     * Domain separator for key derivation (e.g., `"MasterViewingKey/0"`).
+     *
+     * @remarks
+     * The domain separator ensures that keys derived for different purposes are
+     * cryptographically independent even when derived from the same root material.
+     * @readonly
+     */
+    readonly domainSeparator: string;
+    /**
+     * Network environment (e.g., `"mainnet-beta"`, `"devnet"`).
+     *
+     * @remarks
+     * Prevents keys generated on devnet from being mistakenly used on mainnet.
+     * @readonly
+     */
+    readonly network: Network;
+    /**
+     * Protocol version string (e.g., `"1.0.0"`).
+     *
+     * @remarks
+     * Bumped when the on-chain protocol changes in a way that requires fresh keys.
+     * @readonly
+     */
+    readonly protocolVersion: string;
+    /**
+     * Algorithm version string (e.g., `"1.0.0"`).
+     *
+     * @remarks
+     * Bumped when the cryptographic algorithm (hash function, cipher) changes.
+     * @readonly
+     */
+    readonly algorithmVersion: string;
+    /**
+     * Scheme version string (e.g., `"1.0.0"`).
+     *
+     * @remarks
+     * Bumped when the key derivation scheme (domain separators, input ordering) changes.
+     * @readonly
+     */
+    readonly schemeVersion: string;
+    /**
+     * Optional derivation parameters (e.g., `{ year: "2024", mint: "7xKXt..." }`).
+     *
+     * @remarks
+     * Supplied for parameterized keys (yearly viewing keys, mint-specific keys) to distinguish
+     * storage entries for different time periods or token mints.
+     * @readonly
+     */
+    readonly derivationParams?: Record<string, string>;
+    /**
+     * Optional offset used in key derivation.
+     *
+     * @remarks
+     * Used when a key is derived with an explicit 512-bit offset (e.g., for generation-indexed
+     * AES keys). Most keys do not use this field.
+     * @readonly
+     */
+    readonly offset?: U512;
+}
+/**
+ * Loads a value from storage.
+ *
+ * @remarks
+ * Implementations should be idempotent: calling load multiple times with the same context
+ * must return the same result (assuming no concurrent stores).
+ *
+ * @typeParam T - The type of value being loaded
+ * @param context - Storage context with version and parameter information
+ * @returns A promise that resolves to a `LoadResult` indicating whether the value exists
+ *
+ * @example
+ * ```typescript
+ * const loader: LoaderFunction<MasterViewingKey> = async (context) => {
+ *   const raw = await db.get(buildKey(context));
+ *   if (!raw) return { exists: false };
+ *   return { exists: true, seed: parseMvk(raw) };
+ * };
+ * ```
+ *
+ * @public
+ */
+type LoaderFunction<T> = (context: KeyStorageContext) => Promise<LoadResult<T>>;
+/**
+ * Stores a value to storage.
+ *
+ * @remarks
+ * Implementations should overwrite any previously stored value for the same context.
+ * Failures must be reported via a `StoreResult` with `success: false` rather than throwing,
+ * unless the failure is catastrophic.
+ *
+ * @typeParam T - The type of value being stored
+ * @param value - The value to store
+ * @param context - Storage context with version and parameter information
+ * @returns A promise that resolves to a `StoreResult` indicating success or describing the failure
+ *
+ * @example
+ * ```typescript
+ * const storer: StorerFunction<MasterViewingKey> = async (value, context) => {
+ *   try {
+ *     await db.put(buildKey(context), serializeMvk(value));
+ *     return { success: true };
+ *   } catch (error) {
+ *     return { success: false, error: String(error) };
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+type StorerFunction<T> = (value: T, context: KeyStorageContext) => Promise<StoreResult>;
+/**
+ * Generates a new value.
+ *
+ * @remarks
+ * Called when no stored value is found. The implementation should use the context to
+ * deterministically or randomly generate a fresh value. For security-critical keys, the
+ * generator should use a cryptographically secure random source.
+ *
+ * @typeParam T - The type of value being generated
+ * @param context - Storage context with version and parameter information
+ * @returns A promise that resolves to the freshly generated value
+ *
+ * @example
+ * ```typescript
+ * const generator: GeneratorFunction<MasterViewingKey> = async (context) => {
+ *   const entropy = crypto.getRandomValues(new Uint8Array(32));
+ *   return deriveMasterViewingKey(entropy, context.domainSeparator);
+ * };
+ * ```
+ *
+ * @public
+ */
+type GeneratorFunction<T> = (context: KeyStorageContext) => Promise<T>;
+/**
+ * Loads a value that requires additional parameters (e.g., year, mint address).
+ *
+ * @remarks
+ * Similar to `LoaderFunction`, but accepts an extra `params` argument to disambiguate
+ * storage entries when the same key type can exist for multiple parameter values (e.g.,
+ * a yearly viewing key for 2023 vs. 2024).
+ *
+ * @typeParam T - The type of value being loaded
+ * @typeParam TParams - The type of extra parameters required for lookup
+ * @param params - Parameters for key derivation and lookup (e.g., `{ year: 2024n }`)
+ * @param context - Storage context with version and base parameter information
+ * @returns A promise that resolves to a `LoadResult` indicating whether the value exists
+ *
+ * @example
+ * ```typescript
+ * const loader: ParameterizedLoaderFunction<YearlyViewingKey, { year: bigint }> =
+ *   async (params, context) => {
+ *     const key = buildYearKey(context, params.year);
+ *     const raw = await db.get(key);
+ *     if (!raw) return { exists: false };
+ *     return { exists: true, seed: parseYvk(raw) };
+ *   };
+ * ```
+ *
+ * @see {@link LoaderFunction}
+ * @public
+ */
+type ParameterizedLoaderFunction<T, TParams> = (params: TParams, context: KeyStorageContext) => Promise<LoadResult<T>>;
+/**
+ * Stores a value that requires additional parameters.
+ *
+ * @remarks
+ * Similar to `StorerFunction`, but accepts an extra `params` argument so the implementation
+ * can construct a unique storage key for each parameter combination.
+ *
+ * @typeParam T - The type of value being stored
+ * @typeParam TParams - The type of extra parameters required for storage
+ * @param value - The value to store
+ * @param params - Parameters for key derivation and storage (e.g., `{ year: 2024n }`)
+ * @param context - Storage context with version and base parameter information
+ * @returns A promise that resolves to a `StoreResult` indicating success or describing the failure
+ *
+ * @see {@link StorerFunction}
+ * @public
+ */
+type ParameterizedStorerFunction<T, TParams> = (value: T, params: TParams, context: KeyStorageContext) => Promise<StoreResult>;
+/**
+ * Generates a value that requires additional parameters.
+ *
+ * @remarks
+ * Similar to `GeneratorFunction`, but accepts `params` to derive a key that is specific to
+ * a given parameter set (e.g., deriving a yearly viewing key scoped to a particular year and mint).
+ *
+ * @typeParam T - The type of value being generated
+ * @typeParam TParams - The type of extra parameters required for derivation
+ * @param params - Parameters for key derivation (e.g., `{ year: 2024n, mint: "7xKXt..." }`)
+ * @param context - Storage context with version and base parameter information
+ * @returns A promise that resolves to the freshly generated value
+ *
+ * @see {@link GeneratorFunction}
+ * @public
+ */
+type ParameterizedGeneratorFunction<T, TParams> = (params: TParams, context: KeyStorageContext) => Promise<T>;
+/**
+ * Loads the master seed from storage.
+ *
+ * @remarks
+ * The master seed is the root of all key derivation. This function should:
+ * - Check if a master seed exists in storage
+ * - Return the seed if it exists
+ * - Return `{ exists: false }` if no seed is stored (caller will then generate one)
+ *
+ * This function takes no context argument because the master seed is not scoped to any
+ * particular set of derivation parameters — it is the single universal root.
+ *
+ * @returns A promise that resolves to a `LoadResult` containing the master seed if found
+ *
+ * @example
+ * ```typescript
+ * const loader: MasterSeedLoaderFunction = async () => {
+ *   const encrypted = localStorage.getItem("umbraMasterSeed");
+ *   if (!encrypted) return { exists: false };
+ *   const seed = await decrypt(encrypted);
+ *   return { exists: true, seed };
+ * };
+ * ```
+ *
+ * @see {@link MasterSeed}
+ * @see {@link MasterSeedStorerFunction}
+ * @see {@link MasterSeedGeneratorFunction}
+ * @public
+ */
+type MasterSeedLoaderFunction = () => Promise<LoadResult<MasterSeed>>;
+/**
+ * Stores the master seed to storage.
+ *
+ * @remarks
+ * This function should securely persist the master seed. The default SDK implementation
+ * uses an in-memory closure-based store, but production applications should provide a
+ * custom implementation that encrypts the seed before persisting it (e.g., AES-GCM
+ * with a password-derived key, or storing in a platform secure enclave).
+ *
+ * Security guidance:
+ * - Never store the raw seed in plaintext on disk or in localStorage
+ * - Use authenticated encryption (e.g., AES-256-GCM) to protect the seed at rest
+ * - Consider using the platform keychain (Keychain on iOS/macOS, Keystore on Android)
+ *
+ * @param seed - The master seed to store (64 bytes)
+ * @returns A promise that resolves to a `StoreResult` indicating success or describing the failure
+ *
+ * @example
+ * ```typescript
+ * const storer: MasterSeedStorerFunction = async (seed) => {
+ *   try {
+ *     const encrypted = await encryptWithUserPassword(seed);
+ *     localStorage.setItem("umbraMasterSeed", encrypted);
+ *     return { success: true };
+ *   } catch (error) {
+ *     return { success: false, error: String(error) };
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link MasterSeed}
+ * @see {@link MasterSeedLoaderFunction}
+ * @public
+ */
+type MasterSeedStorerFunction = (seed: MasterSeed) => Promise<StoreResult>;
+/**
+ * Generates a new master seed.
+ *
+ * @remarks
+ * The default SDK implementation follows these steps:
+ * 1. Constructs the message: `"Umbra Privacy - Master Seed Generation - {signerAddress}"`
+ * 2. Signs the message with the user's wallet signer (producing a deterministic Ed25519 signature)
+ * 3. Hashes the signature with KMAC256 (key derivation length = 64) to produce the 512-bit seed
+ *
+ * This approach makes seed generation deterministic and tied to the user's wallet keypair,
+ * so the same wallet always regenerates the same master seed. Applications that prefer
+ * non-deterministic seeds can supply a custom generator that uses `crypto.getRandomValues`.
+ *
+ * @returns A promise that resolves to the freshly generated `MasterSeed` (64 bytes)
+ *
+ * @example
+ * ```typescript
+ * // Deterministic (default): derived from wallet signature
+ * const generator: MasterSeedGeneratorFunction = async () => {
+ *   const msg = `Umbra Privacy - Master Seed Generation - ${signerAddress}`;
+ *   const sig = await signer.signMessage(msg);
+ *   return kmac256(sig, { dkLen: 64 }) as MasterSeed;
+ * };
+ * ```
+ *
+ * @see {@link MasterSeed}
+ * @see {@link MasterSeedLoaderFunction}
+ * @see {@link MasterSeedStorerFunction}
+ * @public
+ */
+type MasterSeedGeneratorFunction = () => Promise<MasterSeed>;
+
+/**
+ * Solana Types Module.
+ *
+ * This module provides branded types and runtime assertion functions for
+ * Solana-specific data structures. By attaching nominal brands to primitive
+ * `string` and `Uint8Array` values, and to `@solana/kit` transaction objects,
+ * the SDK achieves compile-time safety that prevents common mistakes such as:
+ * - Passing a raw string where a `TransactionSignature` is expected.
+ * - Submitting an unsigned transaction to a `TransactionForwarder`.
+ * - Mixing up different byte-array representations.
+ *
+ * @remarks
+ * **Type hierarchy overview:**
+ *
+ * String types:
+ * - {@link String} — root branded string (base type for all string sub-brands)
+ *   - {@link TransactionSignature} — base58-encoded Ed25519 signature string
+ *
+ * Byte array types:
+ * - {@link SolanaBytes} — root branded `Uint8Array` for Solana binary data
+ *   - {@link SignatureBytes} — exactly 64-byte raw Ed25519 signature
+ *
+ * Transaction types (wrapping `@solana/kit`'s `Transaction`):
+ * - {@link UnsignedTransaction} — no signatures present
+ * - {@link SignedTransaction} — at least one signature; includes blockhash lifetime
+ *   - {@link PartiallySignedTransaction} — some but not all required signatures
+ *     - {@link FullySignedTransaction} — all required signatures present; ready for submission
+ *
+ * **Runtime assertions:**
+ * - {@link assertString} — narrows `string` to `String`
+ * - {@link assertTransactionSignature} — narrows `string` to `TransactionSignature` (base58 validated)
+ * - {@link assertSolanaBytes} — narrows `Uint8Array` to `SolanaBytes`
+ * - {@link assertSignatureBytes} — narrows `Uint8Array` to `SignatureBytes` (64-byte validated)
+ *
+ * **Error class:**
+ * - {@link SolanaAssertionError} — thrown by all assertion functions with structured context
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   assertTransactionSignature,
+ *   assertSignatureBytes,
+ *   TransactionSignature,
+ *   SignatureBytes,
+ * } from "./types";
+ *
+ * const sigString = "5wHu1qwD7q5menT3ydT9VdFPQfkLaWvqPgVbqsM1qwD7";
+ * assertTransactionSignature(sigString);
+ * // sigString is now typed as TransactionSignature
+ *
+ * const sigBytes = new Uint8Array(64);
+ * assertSignatureBytes(sigBytes);
+ * // sigBytes is now typed as SignatureBytes
+ * ```
+ *
+ * @see {@link BrandedType} for the underlying branding utility
+ * @see {@link Bytes} for the generic byte array base type
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module types/solana
+ */
+
+/**
+ * Length of an Ed25519 signature in bytes.
+ *
+ * The Ed25519 signature scheme, used by Solana for all transaction signing,
+ * always produces exactly 64-byte signatures:
+ * - Bytes 0–31: the R component (a compressed point on the Ed25519 curve)
+ * - Bytes 32–63: the S component (a scalar value)
+ *
+ * @remarks
+ * This constant is used by {@link assertSignatureBytes} to validate the length
+ * of raw signature byte arrays before branding them as {@link SignatureBytes}.
+ *
+ * @example
+ * ```typescript
+ * const raw = new Uint8Array(SIGNATURE_BYTE_LENGTH); // 64-byte zeroed buffer
+ * assertSignatureBytes(raw);
+ * ```
+ *
+ * @public
+ */
+declare const SIGNATURE_BYTE_LENGTH = 64;
+/**
+ * Error thrown when a Solana type assertion function fails.
+ *
+ * All assertion functions in this module (`assertString`,
+ * `assertTransactionSignature`, `assertSolanaBytes`, `assertSignatureBytes`)
+ * throw `SolanaAssertionError` when the supplied value does not satisfy the
+ * type constraint. The error carries structured fields that make it easy to
+ * log diagnostics or write type-specific error handlers.
+ *
+ * @remarks
+ * `SolanaAssertionError` sets `Error.captureStackTrace` (available in V8
+ * environments) to exclude the assertion function's own frame from the stack,
+ * making the stack trace point to the caller rather than the assertion body.
+ *
+ * The prototype is explicitly reset via `Object.setPrototypeOf` to ensure
+ * `instanceof` works correctly across CommonJS module boundary re-exports.
+ *
+ * @example
+ * Catching and inspecting a failed assertion:
+ * ```typescript
+ * import { assertTransactionSignature, SolanaAssertionError } from "./types";
+ *
+ * try {
+ *   assertTransactionSignature("invalid!sig");
+ * } catch (error) {
+ *   if (error instanceof SolanaAssertionError) {
+ *     console.error(`Expected: ${error.expectedType}`);
+ *     console.error(`Constraint: ${error.constraint}`);
+ *     console.error(`Got: ${String(error.value)}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class SolanaAssertionError extends Error {
+    /**
+     * 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.
+     */
+    readonly value: unknown;
+    /**
+     * 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.
+     */
+    readonly expectedType: string;
+    /**
+     * 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"`).
+     */
+    readonly constraint: string | undefined;
+    /**
+     * 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: string, options: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Root branded string type for the Solana types module.
+ *
+ * This is the base type from which all specialized Solana string types derive.
+ * Branding it prevents raw `string` literals from being used where a validated
+ * Solana string is required, while still allowing structural compatibility with
+ * `string` via the underlying primitive.
+ *
+ * @remarks
+ * Prefer the more specific sub-types (e.g., {@link TransactionSignature}) over
+ * `String` when the string has additional semantic meaning. Use `String` only
+ * when building generic utilities that operate on any validated Solana string
+ * and need to accept multiple sub-brands.
+ *
+ * @example
+ * ```typescript
+ * function logSolanaString(s: String): void {
+ *   console.log("Solana string:", s);
+ * }
+ *
+ * const raw = "hello";
+ * assertString(raw);
+ * logSolanaString(raw); // OK — raw is now branded as String
+ * ```
+ *
+ * @see {@link assertString} for the corresponding runtime assertion
+ * @public
+ */
+type String = BrandedType<string, "String">;
+/**
+ * Base58-encoded Solana transaction signature.
+ *
+ * A transaction signature is the result of an Ed25519 sign operation on the
+ * serialized transaction message. Solana encodes it as a base58 string
+ * (approximately 87–88 characters) for human-readable display and API usage.
+ *
+ * @remarks
+ * **Encoding details:**
+ * - Underlying binary: 64 bytes (see {@link SignatureBytes})
+ * - Base58 alphabet: 58 characters (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`)
+ * - Excluded characters: `0`, `O`, `I`, `l` (visually ambiguous)
+ * - Typical string length: 87–88 characters
+ *
+ * **Type safety:** The {@link assertTransactionSignature} function validates
+ * that a `string` value is non-empty and contains only Base58 characters before
+ * branding it as `TransactionSignature`. This catches obvious data errors at
+ * the ingestion boundary.
+ *
+ * **Note:** Validation is character-level only. The assertion does NOT verify
+ * cryptographic correctness (i.e., it does not verify that the signature was
+ * produced by a specific keypair).
+ *
+ * @example
+ * Narrowing a raw string to `TransactionSignature`:
+ * ```typescript
+ * const raw = "5wHu1qwD7q5menT3ydT9VdFPQfkLaWvqPgVbqsM1qwD7";
+ * assertTransactionSignature(raw);
+ * // raw is now typed as TransactionSignature
+ * ```
+ *
+ * @example
+ * Using in a function signature:
+ * ```typescript
+ * async function getTransactionDetails(sig: TransactionSignature) {
+ *   return await rpc.getTransaction(sig).send();
+ * }
+ * ```
+ *
+ * @see {@link assertTransactionSignature} for the runtime assertion
+ * @see {@link SignatureBytes} for the raw binary equivalent
+ * @public
+ */
+type TransactionSignature = SubBrandedType<String, "TransactionSignature">;
+/**
+ * Root branded `Uint8Array` type for Solana binary data.
+ *
+ * This is the base type for all Solana-specific byte array types. It derives
+ * from the generic `Bytes` type and adds the `"SolanaBytes"` nominal brand,
+ * distinguishing Solana binary data from other `Uint8Array` values in the SDK.
+ *
+ * @remarks
+ * No specific length constraint — the length depends on the particular data
+ * being represented. Sub-types like {@link SignatureBytes} impose their own
+ * length requirements.
+ *
+ * Use `SolanaBytes` when the binary data is Solana-specific but does not fall
+ * into a more precise category (e.g., serialized account data, raw message
+ * bytes).
+ *
+ * @example
+ * ```typescript
+ * const accountData = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * assertSolanaBytes(accountData);
+ * // accountData is now typed as SolanaBytes
+ * ```
+ *
+ * @see {@link assertSolanaBytes} for the runtime assertion
+ * @see {@link SignatureBytes} for the 64-byte Ed25519 signature sub-type
+ * @public
+ */
+type SolanaBytes = SubBrandedType<Bytes, "SolanaBytes">;
+/**
+ * 64-byte raw Ed25519 signature in binary form.
+ *
+ * This type represents the binary encoding of an Ed25519 signature as used
+ * internally by the Solana runtime and the `@solana/kit` library. It is the
+ * binary equivalent of a {@link TransactionSignature} string — the same 64
+ * bytes, without the Base58 encoding.
+ *
+ * @remarks
+ * **Structure:**
+ * - Bytes 0–31: R component — a compressed Ed25519 curve point
+ * - Bytes 32–63: S component — a scalar in the range `[0, l)` where `l` is
+ *   the order of the Ed25519 base point
+ *
+ * **Conversion:**
+ * - `SignatureBytes` → `TransactionSignature`: Base58-encode the bytes
+ * - `TransactionSignature` → `SignatureBytes`: Base58-decode the string
+ *
+ * The {@link assertSignatureBytes} function validates both that the value is a
+ * `Uint8Array` and that it is exactly {@link SIGNATURE_BYTE_LENGTH} (64) bytes.
+ *
+ * @example
+ * Creating and validating a signature byte array:
+ * ```typescript
+ * const sigBytes = new Uint8Array(64);
+ * // ... fill sigBytes with actual Ed25519 signature material ...
+ * assertSignatureBytes(sigBytes);
+ * // sigBytes is now typed as SignatureBytes
+ * ```
+ *
+ * @example
+ * Using with a Solana transaction builder:
+ * ```typescript
+ * declare function attachSignature(
+ *   tx: UnsignedTransaction,
+ *   publicKey: Address,
+ *   signature: SignatureBytes,
+ * ): PartiallySignedTransaction;
+ * ```
+ *
+ * @see {@link assertSignatureBytes} for the runtime assertion
+ * @see {@link TransactionSignature} for the base58-encoded equivalent
+ * @see {@link SIGNATURE_BYTE_LENGTH} for the required byte length constant
+ * @public
+ */
+type SignatureBytes = SubSubBrandedType<SolanaBytes, "SignatureBytes">;
+/**
+ * An unsigned Solana transaction — a transaction that has been constructed
+ * but has not yet received any signatures.
+ *
+ * @remarks
+ * This type wraps `Transaction` from `@solana/kit` with the `"UnsignedTransaction"`
+ * brand. The brand prevents an unsigned transaction from being passed to a
+ * `TransactionForwarder` or any function that requires a {@link SignedTransaction},
+ * catching the mistake at compile time.
+ *
+ * **Lifecycle:** Build the transaction message → compile to `Transaction` →
+ * brand as `UnsignedTransaction` → sign to produce {@link SignedTransaction}.
+ *
+ * @example
+ * Type-safe transaction building:
+ * ```typescript
+ * import { UnsignedTransaction } from "./types";
+ *
+ * function buildTransfer(from: Address, to: Address, amount: bigint): UnsignedTransaction {
+ *   // ... build and compile message ...
+ *   return compiledTx as UnsignedTransaction;
+ * }
+ *
+ * const tx = buildTransfer(sender, recipient, 1_000_000n);
+ * // tx cannot be passed to forwarder.forwardSequentially — compile error
+ * ```
+ *
+ * @see {@link SignedTransaction} for the signed counterpart
+ * @public
+ */
+type UnsignedTransaction = BrandedType<Transaction, "UnsignedTransaction">;
+/**
+ * A Solana transaction that has at least one signature and a blockhash
+ * lifetime constraint.
+ *
+ * This is the base type for all signed transaction variants. It intersects
+ * `Transaction` with `TransactionWithBlockhashLifetime` from `@solana/kit`,
+ * ensuring the blockhash expiry window (`blockhash` + `lastValidBlockHeight`)
+ * is present alongside the signature data.
+ *
+ * @remarks
+ * **Blockhash lifetime** — The `TransactionWithBlockhashLifetime` intersection
+ * ensures that every `SignedTransaction` carries `lifetimeConstraint.blockhash`
+ * and `lifetimeConstraint.lastValidBlockHeight`. The forwarder uses these to
+ * detect expiry before submission.
+ *
+ * **Sub-types** — `SignedTransaction` is the common type used in forwarder
+ * method signatures because it accepts both {@link PartiallySignedTransaction}
+ * and {@link FullySignedTransaction}. Use the more specific sub-types when the
+ * exact signing completeness matters to the API contract.
+ *
+ * @example
+ * Accepting any signed transaction (partial or full):
+ * ```typescript
+ * function logSignedTx(tx: SignedTransaction): void {
+ *   console.log(`Valid until block: ${tx.lifetimeConstraint.lastValidBlockHeight}`);
+ * }
+ * ```
+ *
+ * @see {@link PartiallySignedTransaction} for partial signing state
+ * @see {@link FullySignedTransaction} for full signing state
+ * @see {@link UnsignedTransaction} for the unsigned state
+ * @public
+ */
+type SignedTransaction = BrandedType<Transaction & TransactionWithBlockhashLifetime, "SignedTransaction">;
+/**
+ * A Solana transaction with some but potentially not all required signatures.
+ *
+ * A sub-brand of {@link SignedTransaction}. The transaction has been signed by
+ * at least one party but may still be missing signatures from other required
+ * signers. This state is common in multi-signature workflows where different
+ * parties sign at different times or different locations.
+ *
+ * @remarks
+ * In the Umbra SDK, partial signing arises when:
+ * - The user's wallet signs the transaction locally.
+ * - The relayer counter-signs before submission.
+ * - A hardware wallet adds its signature after an initial software signature.
+ *
+ * A `PartiallySignedTransaction` cannot be submitted to the network until all
+ * required signatures are collected, at which point it can be cast (or built
+ * up) to {@link FullySignedTransaction}.
+ *
+ * @example
+ * Multi-sig workflow:
+ * ```typescript
+ * const partial: PartiallySignedTransaction = await userWallet.sign(unsigned);
+ * const full: FullySignedTransaction = await relayer.countersign(partial);
+ * await forwarder.forwardSequentially([full]);
+ * ```
+ *
+ * @see {@link FullySignedTransaction} for the fully-signed state
+ * @see {@link SignedTransaction} for the base signed state
+ * @public
+ */
+type PartiallySignedTransaction = SubBrandedType<SignedTransaction, "PartiallySignedTransaction">;
+/**
+ * A Solana transaction with all required signatures present and ready for
+ * network submission.
+ *
+ * This is the terminal transaction state in the signing lifecycle. A
+ * `FullySignedTransaction` has been signed by every required signer and can be
+ * submitted to the Solana network via a {@link TransactionForwarder}.
+ *
+ * @remarks
+ * **Compile-time guarantee** — The {@link TransactionForwarder} interface's
+ * `forwardSequentially` and `forwardInParallel` methods accept
+ * `readonly SignedTransaction[]` (the common base type). Callers that track
+ * signing state explicitly can use `FullySignedTransaction` in their own
+ * function signatures to signal that all signatures are present.
+ *
+ * **Branding vs. validation** — The brand is a compile-time assertion — the
+ * runtime does NOT verify that all required pubkeys have corresponding
+ * signatures. It is the responsibility of the signing workflow to ensure
+ * completeness before casting to `FullySignedTransaction`.
+ *
+ * @example
+ * Enforcing full signing at a function boundary:
+ * ```typescript
+ * import { FullySignedTransaction } from "./types";
+ * import type { TransactionForwarder } from "./interfaces";
+ *
+ * async function submitAll(
+ *   forwarder: TransactionForwarder,
+ *   txs: readonly FullySignedTransaction[],
+ * ) {
+ *   return forwarder.forwardSequentially(txs);
+ * }
+ * ```
+ *
+ * @see {@link PartiallySignedTransaction} for partial signing state
+ * @see {@link SignedTransaction} for the base signed state
+ * @see {@link TransactionForwarder} for the submission interface
+ * @public
+ */
+type FullySignedTransaction = SubSubBrandedType<PartiallySignedTransaction, "FullySignedTransaction">;
+/**
+ * Asserts that a value is a primitive `string` and narrows it to {@link String}.
+ *
+ * This is the base assertion for all Solana branded string types. It only
+ * checks that the input is a primitive `string` — no format or content
+ * validation is performed.
+ *
+ * @param value - The value to assert. Must be a primitive string.
+ * @throws {SolanaAssertionError} If `typeof value !== "string"`.
+ *
+ * @remarks
+ * For more specific string types, use the dedicated assertion functions:
+ * - {@link assertTransactionSignature} — for base58-encoded signatures
+ *
+ * @example
+ * ```typescript
+ * const raw: unknown = "hello world";
+ * assertString(raw as string);
+ * // raw is now typed as String
+ *
+ * assertString(123 as unknown as string); // Throws: not a string
+ * assertString(null as unknown as string); // Throws: not a string
+ * ```
+ *
+ * @see {@link String} for the branded type
+ * @see {@link assertTransactionSignature} for the signature-specific assertion
+ * @public
+ */
+declare function assertString(value: string): asserts value is String;
+/**
+ * Asserts that a value is a valid base58-encoded Solana transaction signature
+ * and narrows it to {@link TransactionSignature}.
+ *
+ * Validation rules:
+ * 1. `typeof value === "string"`
+ * 2. `value.length > 0` (non-empty)
+ * 3. Every character is in the Base58 alphabet (`123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`)
+ *
+ * @param value - The string to assert as a base58 transaction signature.
+ * @throws {SolanaAssertionError} If the value is not a string, is empty, or
+ *   contains characters outside the Base58 alphabet. The error's `constraint`
+ *   field identifies which rule was violated, and for alphabet violations,
+ *   includes the position and character that failed.
+ *
+ * @remarks
+ * **Validation scope** — This function performs character-level validation only.
+ * It does NOT verify cryptographic correctness (i.e., it does not check that
+ * the 64 decoded bytes constitute a valid Ed25519 signature, nor that the
+ * signature was produced by any particular keypair).
+ *
+ * **Excluded characters** — The Base58 alphabet deliberately omits `0` (zero),
+ * `O` (capital O), `I` (capital I), and `l` (lowercase L) to avoid
+ * transcription errors. Any of these characters in `value` will cause a throw.
+ *
+ * **Typical usage** — Call this function at SDK ingestion boundaries (e.g.,
+ * when accepting a signature string from user input or an external API) to
+ * ensure downstream code only ever sees branded, validated values.
+ *
+ * @example
+ * Validating a signature from an external source:
+ * ```typescript
+ * const rawSig: string = apiResponse.signature;
+ * assertTransactionSignature(rawSig);
+ * // rawSig is now typed as TransactionSignature
+ * ```
+ *
+ * @example
+ * Invalid inputs:
+ * ```typescript
+ * assertTransactionSignature("");            // Throws: empty string
+ * assertTransactionSignature("hello!world"); // Throws: invalid char '!'
+ * assertTransactionSignature("0abc");        // Throws: '0' not in Base58
+ * assertTransactionSignature("IIII");        // Throws: 'I' not in Base58
+ * ```
+ *
+ * @see {@link TransactionSignature} for the branded type
+ * @see {@link SignatureBytes} for the binary equivalent
+ * @public
+ */
+declare function assertTransactionSignature(value: string): asserts value is TransactionSignature;
+/**
+ * Asserts that a value is a `Uint8Array` and narrows it to {@link SolanaBytes}.
+ *
+ * This is the base assertion for all Solana byte array types. It only checks
+ * that the input is a `Uint8Array` instance — no length validation is performed.
+ *
+ * @param value - The `Uint8Array` to assert. Must be an instance of `Uint8Array`.
+ * @throws {SolanaAssertionError} If `!(value instanceof Uint8Array)`.
+ *
+ * @remarks
+ * For byte arrays with specific length requirements, use the more specific
+ * assertion function:
+ * - {@link assertSignatureBytes} — for 64-byte Ed25519 signature arrays
+ *
+ * @example
+ * ```typescript
+ * const data = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+ * assertSolanaBytes(data);
+ * // data is now typed as SolanaBytes
+ *
+ * assertSolanaBytes([] as unknown as Uint8Array);     // Throws: not a Uint8Array
+ * assertSolanaBytes("bytes" as unknown as Uint8Array); // Throws: not a Uint8Array
+ * ```
+ *
+ * @see {@link SolanaBytes} for the branded type
+ * @see {@link assertSignatureBytes} for the length-constrained variant
+ * @public
+ */
+declare function assertSolanaBytes(value: Uint8Array): asserts value is SolanaBytes;
+/**
+ * Asserts that a value is a `Uint8Array` of exactly {@link SIGNATURE_BYTE_LENGTH}
+ * (64) bytes and narrows it to {@link SignatureBytes}.
+ *
+ * Validation rules:
+ * 1. `value instanceof Uint8Array`
+ * 2. `value.length === 64`
+ *
+ * @param value - The `Uint8Array` to assert as a 64-byte Ed25519 signature.
+ * @throws {SolanaAssertionError} If the value is not a `Uint8Array` or is not
+ *   exactly 64 bytes. The error's `constraint` field specifies
+ *   `"length === 64"` for length violations.
+ *
+ * @remarks
+ * The 64-byte requirement is defined by the Ed25519 specification and is
+ * invariant across all Solana Ed25519 signatures. Passing a 63- or 65-byte
+ * array will always throw, regardless of the content.
+ *
+ * **Structure:**
+ * - Bytes 0–31: R component (compressed curve point)
+ * - Bytes 32–63: S component (scalar)
+ *
+ * @example
+ * Validating a signature byte array:
+ * ```typescript
+ * const sigBytes = new Uint8Array(64);
+ * // ... populate with actual Ed25519 signature bytes ...
+ * assertSignatureBytes(sigBytes);
+ * // sigBytes is now typed as SignatureBytes
+ * ```
+ *
+ * @example
+ * Invalid inputs:
+ * ```typescript
+ * assertSignatureBytes(new Uint8Array(63)); // Throws: expected 64 bytes, got 63
+ * assertSignatureBytes(new Uint8Array(65)); // Throws: expected 64 bytes, got 65
+ * assertSignatureBytes([] as unknown as Uint8Array); // Throws: not a Uint8Array
+ * ```
+ *
+ * @see {@link SignatureBytes} for the branded type
+ * @see {@link SIGNATURE_BYTE_LENGTH} for the required length constant
+ * @see {@link TransactionSignature} for the base58-encoded equivalent
+ * @public
+ */
+declare function assertSignatureBytes(value: Uint8Array): asserts value is SignatureBytes;
+/**
+ * Brands a compiled `Transaction` as a {@link SignedTransaction} for relay
+ * submission.
+ *
+ * @remarks
+ * This function is used for transactions that will be signed by the **relayer**,
+ * not by the client. In the Umbra relay flow, the client builds and serializes
+ * a transaction message, which is then passed to the relayer service. The
+ * relayer signs and submits the transaction. Because the blockhash lifetime is
+ * already embedded in the compiled message bytes (`messageBytes`), the
+ * transaction is treated as carrying a blockhash constraint even though
+ * `lifetimeConstraint` is not set as a TypeScript property.
+ *
+ * **This is an escape hatch** — it performs an unchecked cast. Use only when
+ * you are certain the compiled message bytes include a valid blockhash and the
+ * relayer will supply the required signature before submission.
+ *
+ * @param tx - A `Transaction` object whose compiled message bytes already
+ *   embed the blockhash lifetime constraint.
+ * @returns The same `Transaction` value cast to {@link SignedTransaction}.
+ *
+ * @example
+ * ```typescript
+ * import { asRelayableSignedTransaction } from "./types";
+ *
+ * const compiledTx: Transaction = compileTransactionMessage(txMessage);
+ * const relayable = asRelayableSignedTransaction(compiledTx);
+ * // relayable can now be passed to relayer submission APIs
+ * ```
+ *
+ * @public
+ */
+declare function asRelayableSignedTransaction(tx: Transaction): SignedTransaction;
+
+export { type FullySignedTransaction as F, type GeneratorFunction as G, type KeyStorageContext as K, type LoaderFunction as L, type MasterSeedLoaderFunction as M, type ParameterizedLoaderFunction as P, type SignedTransaction as S, type TransactionSignature as T, type UnsignedTransaction as U, type MasterSeedStorerFunction as a, type MasterSeedGeneratorFunction as b, type StorerFunction as c, type ParameterizedStorerFunction as d, type ParameterizedGeneratorFunction as e, type LoadResult as f, type StoreResult as g, type PartiallySignedTransaction as h, SIGNATURE_BYTE_LENGTH as i, type SignatureBytes as j, SolanaAssertionError as k, type SolanaBytes as l, type String as m, asRelayableSignedTransaction as n, assertSignatureBytes as o, assertSolanaBytes as p, assertString as q, assertTransactionSignature as r };