@umbra-privacy/sdk 1.0.0

package/dist/types/index.d.cts

@@ -0,0 +1,1853 @@
+import { a3 as MasterSeed, K as U512, B as BrandedType, S as SubBrandedType, a2 as SubSubBrandedType, c as Bytes, V as U8, X as X25519PublicKey$1, k as PoseidonHash, U as U128, F as U256LeBytes } from '../cryptography-BTGC72u-.cjs';
+export { am as AES_AUTH_TAG_LENGTH, an as AES_IV_LENGTH, ao as AES_KEY_LENGTH, ap as AES_METADATA_OVERHEAD, a7 as AesCiphertextWithMetadata, a6 as AesKey, a8 as AesPlaintext, aq as BASE85_LIMB_MAX, ar as BN254_FIELD_PRIME, a1 as Base85Limb, a0 as Base85LimbTuple, a as BeBytes, b as Bn254FieldElement, as as CURVE25519_FIELD_PRIME, at as CryptographyAssertionError, C as Curve25519FieldElement, ad as DailyViewingKey, au as ExtractBrand, av as GROTH16_G1_BYTE_LENGTH, aw as GROTH16_G2_BYTE_LENGTH, ax as GenerationSeed, ay as Groth16Proof, aj as Groth16ProofA, ak as Groth16ProofB, al as Groth16ProofC, ae as HourlyViewingKey, I as I1024, az as I1024_MAX, aA as I1024_MIN, d as I128, aB as I128_MAX, aC as I128_MIN, e as I16, aD as I16_MAX, aE as I16_MIN, f as I256, aF as I256_MAX, aG as I256_MIN, g as I32, aH as I32_MAX, aI as I32_MIN, h as I512, aJ as I512_MAX, aK as I512_MIN, i as I64, aL as I64_MAX, aM as I64_MIN, j as I8, aN as I8_MAX, aO as I8_MIN, aP as Keccak256Hash, aQ as Keccak512Hash, L as LeBytes, ab as MasterViewingKey, aR as MathematicsAssertionError, af as MintViewingKey, ag as MinuteViewingKey, ah as MonthlyViewingKey, a4 as Nonce, aS as OPTIONAL_DATA_BYTE_LENGTH, a5 as OptionalData32, P as PoseidonCiphertext, a9 as PoseidonCounter, l as PoseidonKey, aa as PoseidonKeystream, m as PoseidonPlaintext, R as RcCiphertext, n as RcCounter, o as RcEncryptionNonce, p as RcKey, q as RcPlaintext, ac as SecondViewingKey, r as SharedSecret, s as SignedInteger, aT as SubSubSubBrandedType, aU as SubSubSubSubBrandedType, t as U1024, u as U1024BeBytes, v as U1024LeBytes, aV as U1024_BYTE_LENGTH, aW as U1024_MAX, w as U128BeBytes, x as U128LeBytes, aX as U128_BYTE_LENGTH, aY as U128_MAX, y as U16, z as U16BeBytes, A as U16LeBytes, aZ as U16_BYTE_LENGTH, a_ as U16_MAX, D as U256, E as U256BeBytes, a$ as U256_BYTE_LENGTH, b0 as U256_MAX, G as U32, H as U32BeBytes, J as U32LeBytes, b1 as U32_BYTE_LENGTH, b2 as U32_MAX, M as U512BeBytes, N as U512LeBytes, b3 as U512_BYTE_LENGTH, b4 as U512_MAX, O as U64, Q as U64BeBytes, T as U64LeBytes, b5 as U64_BYTE_LENGTH, b6 as U64_MAX, W as U8BeBytes, Y as U8LeBytes, b7 as U8_BYTE_LENGTH, b8 as U8_MAX, Z as UnsignedInteger, b9 as UnwrapBrand, _ as X25519Bytes, ba as X25519Keypair, $ as X25519PrivateKey, bb as X25519_BYTE_LENGTH, ai as YearlyViewingKey, bc as ZK_PROOF_BYTE_LENGTH, bd as ZkProofBytes, be as assertAesCiphertextWithMetadata, bf as assertAesKey, bg as assertAesPlaintext, bh as assertBase85Limb, bi as assertBeBytes, bj as assertBn254FieldElement, bk as assertBytes, bl as assertCurve25519FieldElement, bm as assertDailyViewingKey, bn as assertGenerationSeed, bo as assertGroth16ProofA, bp as assertGroth16ProofB, bq as assertGroth16ProofC, br as assertHourlyViewingKey, bs as assertI1024, bt as assertI128, bu as assertI16, bv as assertI256, bw as assertI32, bx as assertI512, by as assertI64, bz as assertI8, bA as assertKeccak256Hash, bB as assertKeccak512Hash, bC as assertLeBytes, bD as assertMasterSeed, bE as assertMasterViewingKey, bF as assertMintViewingKey, bG as assertMinuteViewingKey, bH as assertMonthlyViewingKey, bI as assertOptionalData32, bJ as assertPoseidonCiphertext, bK as assertPoseidonCounter, bL as assertPoseidonHash, bM as assertPoseidonKey, bN as assertPoseidonKeystream, bO as assertPoseidonPlaintext, bP as assertRcCiphertext, bQ as assertRcCounter, bR as assertRcEncryptionNonce, bS as assertRcKey, bT as assertRcPlaintext, bU as assertSecondViewingKey, bV as assertSharedSecret, bW as assertSignedInteger, bX as assertU1024, bY as assertU1024BeBytes, bZ as assertU1024LeBytes, b_ as assertU128, b$ as assertU128BeBytes, c0 as assertU128LeBytes, c1 as assertU16, c2 as assertU16BeBytes, c3 as assertU16LeBytes, c4 as assertU256, c5 as assertU256BeBytes, c6 as assertU256LeBytes, c7 as assertU32, c8 as assertU32BeBytes, c9 as assertU32LeBytes, ca as assertU512, cb as assertU512BeBytes, cc as assertU512LeBytes, cd as assertU64, ce as assertU64BeBytes, cf as assertU64LeBytes, cg as assertU8, ch as assertU8BeBytes, ci as assertU8LeBytes, cj as assertUnsignedInteger, ck as assertX25519Bytes, cl as assertX25519Keypair, cm as assertX25519PrivateKey, cn as assertX25519PublicKey, co as assertYearlyViewingKey, cp as assertZkProofBytes } from '../cryptography-BTGC72u-.cjs';
+import { N as Network } from '../versions-D9PqsEvj.cjs';
+import { Transaction, TransactionWithBlockhashLifetime } from '@solana/kit';
+export { b as DAY_MAX, c as DAY_MIN, D as Day, d as HOUR_MAX, e as HOUR_MIN, H as Hour, f as MINUTE_MAX, g as MINUTE_MIN, h as MONTH_MAX, i as MONTH_MIN, a as Minute, M as Month, j as SECOND_MAX, k as SECOND_MIN, S as Second, T as TemporalAssertionError, l as TimestampComponent, m as YEAR_MAX, n as YEAR_MIN, Y as Year, o as assertDay, p as assertHour, q as assertMinute, r as assertMonth, s as assertSecond, t as assertTimestampComponent, u as assertYear } from '../types-BBuELtY8.cjs';
+
+/**
+ * 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
+ * @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
+ * @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;
+
+/**
+ * Umbra Protocol Types
+ *
+ * Defines the TypeScript interfaces for the core on-chain state accounts used by the
+ * Umbra privacy protocol, and the discriminated union result types returned by SDK
+ * query functions.
+ *
+ * ## EncryptedUserAccount
+ *
+ * The central on-chain record for each Umbra user. It is stored at a PDA derived from
+ * the user's on-chain wallet address and contains:
+ * - Protocol version and PDA metadata
+ * - Status flags that gate access to privacy features
+ * - The X25519 public key used for shared-mode encryption
+ * - The Poseidon commitment to the user's secret key tree
+ * - A generation counter for deterministic nonce derivation
+ * - A random seed for additional entropy during nonce computation
+ *
+ * ## Result Types
+ *
+ * `QueryUserAccountResult` and `QueryComplianceGrantResult` are discriminated unions
+ * whose `state` field acts as a type discriminant. Pattern-match on `state` to safely
+ * access the data payload:
+ *
+ * ```typescript
+ * const result = await queryUserAccount(address);
+ * if (result.state === "exists") {
+ *   // result.data: EncryptedUserAccount
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ * @module umbra/types
+ */
+
+/**
+ * The decoded on-chain state of a user's Arcium encrypted user account.
+ *
+ * @remarks
+ * This account is the root of a user's participation in the Umbra protocol. It is a
+ * Program Derived Account (PDA) owned by the Umbra program and indexed by the user's
+ * wallet public key. The account is written by `init_encrypted_user_account`
+ * and mutated by registration and conversion instructions.
+ *
+ * ### Token Account Mode Logic
+ *
+ * Umbra supports two modes for encrypted token accounts:
+ *
+ * - **MXE-only** — balances are encrypted under the Arcium MXE (Multi-party eXecution
+ *   Environment) network key. Only the MXE can decrypt them; the user themselves cannot
+ *   decrypt without going through MPC. Available to all users regardless of X25519 key
+ *   registration.
+ * - **Shared** — balances are encrypted under the user's X25519 public key. The user
+ *   can decrypt locally without MPC involvement. Only available after
+ *   `isUserAccountX25519KeyRegistered` is `true`.
+ *
+ * ### Status Flag Progression
+ *
+ * A freshly initialized account will have all flags `false`. The user registers their
+ * keys via separate instructions:
+ *
+ * 1. `isInitialized = true` — set by `init_encrypted_user_account`.
+ * 2. `isUserAccountX25519KeyRegistered = true` — set by `register_x25519_public_key`.
+ * 3. `isUserCommitmentRegistered = true` — set by `register_user_commitment`.
+ * 4. `isActiveForAnonymousUsage = true` — set by `activate_for_anonymous_usage`
+ *    (requires step 2 and 3 to be complete).
+ *
+ * ### Nonce Derivation
+ *
+ * New token account nonces are derived deterministically from:
+ * - `generationIndex` (incremented each time a new token account is created or a
+ *   conversion is performed)
+ * - `randomGenerationSeed` (fixed at registration; can be rotated via
+ *   `update_random_generation_seed`)
+ * - `x25519PublicKey` (user identity anchor)
+ *
+ * This ensures that a given user's token account nonces are unique across all mints and
+ * instruction variants without requiring on-chain storage of each nonce individually.
+ *
+ * @example
+ * ```typescript
+ * import { getQueryUserAccountFunction } from "@umbra-privacy/sdk";
+ * import type { EncryptedUserAccount } from "@umbra-privacy/sdk";
+ *
+ * const query = getQueryUserAccountFunction({ accountInfoProvider });
+ * const result = await query(userWalletAddress);
+ *
+ * if (result.state === "exists") {
+ *   const account: EncryptedUserAccount = result.data;
+ *
+ *   // Check whether Shared mode token accounts are available:
+ *   if (!account.isUserAccountX25519KeyRegistered) {
+ *     console.warn("Register X25519 key first to enable Shared mode.");
+ *   }
+ *
+ *   // Use the generation index for nonce derivation:
+ *   console.log("Current generation index:", account.generationIndex);
+ * }
+ * ```
+ *
+ * @see {@link QueryUserAccountResult} for the result wrapper returned by query functions.
+ * @public
+ */
+interface EncryptedUserAccount {
+    /**
+     * Protocol version byte stored at the beginning of the account discriminator.
+     *
+     * @remarks
+     * Used for forward-compatibility checks. The SDK verifies that the decoded version
+     * matches the expected protocol version before further processing. A mismatch
+     * indicates that the account was created by an incompatible version of the program.
+     *
+     * @readonly
+     */
+    readonly versionByte: U8;
+    /**
+     * Canonical bump seed for this account's PDA.
+     *
+     * @remarks
+     * Stored on-chain to avoid recomputing `findProgramAddress` in callbacks. Anchor
+     * macro-generated accounts always store their canonical bump as the first non-discriminator
+     * field. The SDK reads it back during PDA validation to confirm account authenticity.
+     *
+     * @readonly
+     */
+    readonly canonicalBump: U8;
+    /**
+     * Whether the account has been fully initialized by `init_encrypted_user_account`.
+     *
+     * @remarks
+     * Set to `true` during the initial `init_encrypted_user_account` instruction. If
+     * `false`, all other fields should be considered uninitialized / zero-valued. The
+     * on-chain program checks this flag before allowing any state-mutating instruction to
+     * proceed.
+     *
+     * @readonly
+     */
+    readonly isInitialised: boolean;
+    /**
+     * Whether anonymous usage (mixer transactions using unspent output notes) has been enabled for this
+     * account.
+     *
+     * @remarks
+     * Controlled by the `activate_for_anonymous_usage` instruction. Both
+     * `isUserAccountX25519KeyRegistered` and `isUserCommitmentRegistered` must be `true` before
+     * anonymous usage can be activated. When `false`, the user cannot submit output note
+     * creation or claim instructions.
+     *
+     * @readonly
+     */
+    readonly isActiveForAnonymousUsage: boolean;
+    /**
+     * Whether the user has registered a Poseidon commitment to their secret key tree.
+     *
+     * @remarks
+     * Set by the `register_user_commitment` instruction. The commitment is the Poseidon
+     * hash of the root node of the user's binary secret tree (see {@link userCommitment}).
+     * It is used in challenge transcript computation and ZK proof public inputs for note
+     * claim proofs to bind the proof to the user's identity without revealing any private
+     * key material.
+     *
+     * @readonly
+     */
+    readonly isUserCommitmentRegistered: boolean;
+    /**
+     * Whether the user has registered an X25519 public key for shared-mode encryption.
+     *
+     * @remarks
+     * Set by the `register_x25519_public_key` instruction. Until this flag is `true`:
+     * - The `x25519PublicKey` field is zero-valued (all bytes are 0).
+     * - Token accounts must be created in MXE-only mode; Shared mode is unavailable.
+     * - Anonymous usage cannot be activated.
+     *
+     * Once `true`, the user can create Shared-mode token accounts and the stored key is
+     * used in nonce derivation for all subsequent account creation operations.
+     *
+     * @readonly
+     */
+    readonly isUserAccountX25519KeyRegistered: boolean;
+    /**
+     * The user's X25519 public key for shared-mode token account encryption and note
+     * operations.
+     *
+     * @remarks
+     * This is the 32-byte Curve25519 public key derived from the user's X25519 private
+     * key during the `register_x25519_public_key` instruction. It serves as the
+     * user's persistent on-chain identity for:
+     *
+     * - Encrypting Shared-mode token account balances: the sender encrypts under this key
+     *   so the receiver can decrypt locally without MPC.
+     * - Identity anchoring in challenge transcripts and ZK proof public inputs:
+     *   the key is hashed into the challenge transcript and the aggregated Poseidon hash
+     *   to bind proofs to this user.
+     * - Nonce derivation for new token account initialization: the key is included in the
+     *   nonce hash pre-image alongside `generationIndex` and `randomGenerationSeed`.
+     *
+     * If `isUserAccountX25519KeyRegistered` is `false`, this field contains a zero-valued byte
+     * array and must not be used.
+     *
+     * @readonly
+     */
+    readonly x25519PublicKey: X25519PublicKey$1;
+    /**
+     * Poseidon hash commitment to the root of the user's secret binary tree.
+     *
+     * @remarks
+     * The user's private key material is arranged as a 4-leaf binary tree whose structure
+     * is committed to on-chain:
+     *
+     * ```
+     *                    userCommitment   (this field)
+     *                          |
+     *            +-------------+-------------+
+     *            |                           |
+     *     +------+------+             +------+------+
+     *     |             |             |             |
+     *   masterViewing  masterViewing  shieldingPriv  shieldingPriv
+     *   Key            Commitment     Key            KeyBlindingFactor
+     * ```
+     *
+     * The on-chain program never sees any leaf values — only this root commitment. ZK proofs
+     * (ZK proofs) demonstrate knowledge of the leaves and their correct Poseidon relationship
+     * to this root. The Fiat-Shamir challenge computation also includes this commitment to
+     * prevent replay attacks.
+     *
+     * Set by `register_user_commitment`; the commitment is recomputed from private inputs
+     * in the ZK circuit and must match the on-chain stored value for proof verification
+     * to succeed.
+     *
+     * If `isUserCommitmentRegistered` is `false`, this field is zero-valued.
+     *
+     * @readonly
+     */
+    readonly userCommitment: PoseidonHash;
+    /**
+     * Monotonically increasing 128-bit counter used for deterministic nonce derivation.
+     *
+     * @remarks
+     * Incremented by the on-chain program at the end of the handler instruction (before
+     * the MPC callback fires) for each of the following operations:
+     *
+     * - Creating a new MXE-mode encrypted token account.
+     * - Creating a new Shared-mode encrypted token account.
+     * - Converting an existing MXE-mode token account to Shared-mode.
+     *
+     * When the SDK computes the nonce for a new token account (`newNonce`), it reads the
+     * current `generationIndex` from the fetched `EncryptedUserAccount` and combines it
+     * with `randomGenerationSeed` and `x25519PublicKey` in a domain-separated Poseidon
+     * hash. The handler then increments this counter on-chain so that the next account
+     * creation produces a distinct nonce.
+     *
+     * For existing token accounts the nonce is stored in the `ArciumEncryptedTokenAccount`
+     * PDA and is validated by the callback without using `generationIndex`.
+     *
+     * @readonly
+     */
+    readonly generationIndex: U128;
+    /**
+     * 256-bit random seed providing additional entropy during nonce derivation.
+     *
+     * @remarks
+     * Set once during account initialization (via `init_encrypted_user_account` or the
+     * first registration call) using a client-generated random value. Can be rotated by
+     * the user via the `update_random_generation_seed` instruction without invalidating
+     * existing token accounts (which store their own nonces).
+     *
+     * Included in the nonce hash pre-image alongside `generationIndex` and
+     * `x25519PublicKey`. Its purpose is to ensure that even if an adversary learns the
+     * user's `generationIndex`, they cannot predict token account nonces without also
+     * knowing this seed.
+     *
+     * Stored as a 32-byte little-endian byte array (`U256LeBytes`).
+     *
+     * @readonly
+     */
+    readonly randomGenerationSeed: U256LeBytes;
+}
+/**
+ * Result of querying whether an `EncryptedUserAccount` exists on-chain for a given
+ * wallet address.
+ *
+ * @remarks
+ * Returned by `getQueryUserAccountFunction` implementations. The `state` field is the
+ * discriminant for narrowing:
+ *
+ * - `"non_existent"` — no account was found at the expected PDA. The user has not yet
+ *   called `init_encrypted_user_account`.
+ * - `"exists"` — the account was found and successfully decoded. The `data` property
+ *   contains the parsed `EncryptedUserAccount`.
+ *
+ * Pattern-match on `state` to safely access `data`:
+ *
+ * ```typescript
+ * const result: QueryUserAccountResult = await query(walletAddress);
+ *
+ * switch (result.state) {
+ *   case "non_existent":
+ *     console.log("User not registered — call initEncryptedUserAccount first.");
+ *     break;
+ *   case "exists":
+ *     const { isUserAccountX25519KeyRegistered, generationIndex } = result.data;
+ *     break;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { getQueryUserAccountFunction } from "@umbra-privacy/sdk";
+ *
+ * const query = getQueryUserAccountFunction({ accountInfoProvider });
+ * const result = await query(userAddress);
+ *
+ * if (result.state === "non_existent") {
+ *   // Prompt the user to register.
+ *   return;
+ * }
+ *
+ * // Narrowed: result.data is EncryptedUserAccount
+ * console.log("Generation index:", result.data.generationIndex);
+ * ```
+ *
+ * @see {@link EncryptedUserAccount} for the account data shape.
+ * @public
+ */
+type QueryUserAccountResult = {
+    readonly state: "non_existent";
+} | {
+    readonly state: "exists";
+    readonly data: EncryptedUserAccount;
+};
+/**
+ * Result of checking whether a compliance grant PDA exists on-chain for a given
+ * (granter, nonce, receiver) triple.
+ *
+ * @remarks
+ * Compliance grants are marker accounts — their existence on-chain is the sole signal
+ * that a grant is active. There is no structured data payload to decode; only the
+ * account's presence matters.
+ *
+ * - `"non_existent"` — no grant PDA was found. The granter has not granted the
+ *   receiver access to view their encrypted balances for the given nonce.
+ * - `"exists"` — the grant PDA exists. The receiver is permitted to request
+ *   re-encryption of the granter's encrypted outputs (subject to on-chain program checks).
+ *
+ * Returned by `getQueryComplianceGrantFunction` implementations.
+ *
+ * @example
+ * ```typescript
+ * import { getQueryComplianceGrantFunction } from "@umbra-privacy/sdk";
+ *
+ * const query = getQueryComplianceGrantFunction({ accountInfoProvider });
+ * const result = await query(granterAddress, nonce, receiverAddress);
+ *
+ * if (result.state === "non_existent") {
+ *   console.log("No compliance grant — receiver cannot view balances.");
+ * } else {
+ *   console.log("Compliance grant active — receiver has been granted access.");
+ * }
+ * ```
+ *
+ * @see {@link QueryUserAccountResult} for the analogous user account query result type.
+ * @public
+ */
+type QueryComplianceGrantResult = {
+    readonly state: "non_existent";
+} | {
+    readonly state: "exists";
+};
+
+/**
+ * Key Derivation Types
+ *
+ * This module defines branded types for Curve25519 (Ed25519/X25519) key exchange,
+ * Keccak hashing, master seeds, and hierarchical viewing key derivation.
+ *
+ * @remarks
+ * All types in this module are "branded" nominal types built on top of primitive
+ * TypeScript types (`Uint8Array` or `bigint`). Branding prevents accidental
+ * cross-use of structurally identical values that have different semantic meanings
+ * (e.g., passing an X25519 public key where a private key is expected).
+ *
+ * ## Type Hierarchy Overview
+ *
+ * ```
+ * Bytes
+ *   └── X25519Bytes (32 bytes, endianness-agnostic)
+ *         ├── X25519PrivateKey   — secret scalar; never share
+ *         ├── X25519PublicKey    — public curve point; safe to share
+ *         └── SharedSecret       — ECDH output; feed into a KDF before use
+ *
+ * LeBytes
+ *   └── U256LeBytes
+ *         └── Keccak256Hash      — 32-byte Keccak-256 digest
+ *   └── U512LeBytes
+ *         └── Keccak512Hash      — 64-byte Keccak-512 digest
+ *               ├── MasterSeed   — root of the key hierarchy; 64 bytes
+ *               └── GenerationSeed — ephemeral seed input; 64 bytes
+ *
+ * bigint
+ *   └── U256
+ *         └── Bn254FieldElement
+ *               ├── MasterViewingKey          — < 2^252, views all txs
+ *               ├── YearlyViewingKey          — views one calendar year
+ *               ├── MonthlyViewingKey         — views one calendar month
+ *               ├── DailyViewingKey           — views one calendar day
+ *               ├── HourlyViewingKey          — views one calendar hour
+ *               ├── MinuteViewingKey          — views one calendar minute
+ *               ├── SecondViewingKey          — views one calendar second
+ *               └── MintViewingKey            — views one token (mint)
+ * ```
+ *
+ * ## Security Model
+ *
+ * - The `MasterSeed` is the single secret from which all other keys are derived.
+ *   Compromising it compromises the entire key hierarchy.
+ * - KMAC256 domain separation ensures that different derived keys are
+ *   computationally independent: knowledge of one does not reveal another.
+ * - Viewing keys (MVK and sub-keys) grant read-only access to transaction
+ *   history and can be selectively shared for compliance purposes.
+ * - X25519 private keys are used for ECDH with token senders to enable
+ *   encrypted token account balance decryption.
+ *
+ * @packageDocumentation
+ * @public
+ *
+ * @module crypto/key-derivation/types
+ */
+
+/**
+ * Base branded byte-array type for X25519 key exchange operations.
+ *
+ * X25519 is an elliptic curve Diffie-Hellman (ECDH) protocol using Curve25519
+ * in Montgomery form. All X25519 values (public keys, private keys, shared
+ * secrets) are exactly 32 bytes.
+ *
+ * @remarks
+ * - Size: 32 bytes (256 bits)
+ * - Used as the parent brand for X25519PrivateKey, X25519PublicKey, and SharedSecret
+ * - Parallel to LeBytes/BeBytes as a sub-brand of Bytes
+ * - Endianness-agnostic: the X25519 spec defines a fixed byte ordering
+ *
+ * ## Type Hierarchy
+ * ```
+ * Bytes (base)
+ *   └── X25519Bytes (sub-brand, 32 bytes)
+ *         ├── X25519PrivateKey
+ *         ├── X25519PublicKey
+ *         └── SharedSecret
+ * ```
+ *
+ * @see {@link X25519PrivateKey}
+ * @see {@link X25519PublicKey}
+ * @see {@link SharedSecret}
+ * @see https://cr.yp.to/ecdh/curve25519-20060209.pdf
+ * @see https://tools.ietf.org/html/rfc7748
+ * @public
+ */
+type X25519Bytes = SubBrandedType<Bytes, "X25519Bytes">;
+/**
+ * X25519 private key for elliptic curve Diffie-Hellman key exchange.
+ *
+ * A private key is a 32-byte scalar derived from the master seed via KMAC256
+ * with domain separator `"UserAccountX25519Keypair"`. It is used together
+ * with a counterparty's public key to compute a shared secret.
+ *
+ * @remarks
+ * - Size: 32 bytes (256 bits)
+ * - MUST be kept secret and never shared or logged
+ * - The X25519 algorithm applies RFC 8032 clamping to the scalar during use
+ * - In Umbra, private keys are derived deterministically from the master seed;
+ *   they must never be generated independently with a random number generator
+ *
+ * ## Security Warning
+ *
+ * Exposure of this key allows the holder to decrypt all balances encrypted to
+ * the corresponding public key. Store it only in memory during use.
+ *
+ * ## Type Hierarchy
+ * ```
+ * Bytes (base)
+ *   └── X25519Bytes (sub-brand, 32 bytes)
+ *         └── X25519PrivateKey (sub-sub-brand)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Generate a new private key
+ * const rawPrivateKey = crypto.getRandomValues(new Uint8Array(32));
+ * assertX25519PrivateKey(rawPrivateKey);
+ * // rawPrivateKey is now typed as X25519PrivateKey
+ *
+ * // Derive the public key
+ * const publicKey = x25519GetPublicKey(rawPrivateKey);
+ * ```
+ *
+ * @see {@link assertX25519PrivateKey}
+ * @see {@link X25519Keypair}
+ * @see https://tools.ietf.org/html/rfc7748#section-5
+ * @public
+ */
+type X25519PrivateKey = SubSubBrandedType<X25519Bytes, "X25519PrivateKey">;
+/**
+ * X25519 public key for elliptic curve Diffie-Hellman key exchange.
+ *
+ * A public key is a 32-byte Montgomery curve point derived from a private key
+ * via scalar multiplication of the Curve25519 base point. It is stored on-chain
+ * in the encrypted token account and used by token senders to encrypt balances
+ * for the account holder.
+ *
+ * @remarks
+ * - Size: 32 bytes (256 bits)
+ * - Safe to transmit over insecure channels and store on-chain
+ * - Derived from the corresponding X25519PrivateKey
+ * - Used as input to X25519 ECDH: both parties independently compute the same shared secret
+ *
+ * ## Type Hierarchy
+ * ```
+ * Bytes (base)
+ *   └── X25519Bytes (sub-brand, 32 bytes)
+ *         └── X25519PublicKey (sub-sub-brand)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Receive a public key from another party
+ * const theirPublicKey = receivePublicKey();
+ * assertX25519PublicKey(theirPublicKey);
+ * // theirPublicKey is now typed as X25519PublicKey
+ *
+ * // Compute shared secret
+ * const sharedSecret = x25519(myPrivateKey, theirPublicKey);
+ * ```
+ *
+ * @see {@link assertX25519PublicKey}
+ * @see {@link X25519Keypair}
+ * @see https://tools.ietf.org/html/rfc7748#section-5
+ * @public
+ */
+type X25519PublicKey = SubSubBrandedType<X25519Bytes, "X25519PublicKey">;
+/**
+ * An X25519 key pair consisting of a private key and its corresponding public key.
+ *
+ * X25519 is an elliptic curve Diffie-Hellman (ECDH) protocol using Curve25519
+ * in Montgomery form. In Umbra, this keypair is derived deterministically from
+ * the master seed and is used to establish shared secrets with token senders,
+ * enabling the account holder to decrypt their encrypted balance.
+ *
+ * @remarks
+ * ## Key Generation
+ * - Private key: 32 bytes derived via KMAC256 from the master seed
+ * - Public key: Scalar multiplication of the private key with the Curve25519 base point
+ *
+ * ## Security Properties
+ * - Private key MUST be kept secret; it enables decryption of all balances sent to this account
+ * - Public key can be freely shared and is stored on-chain in the token account PDA
+ * - Shared secret is computed as: `X25519(myPrivate, senderPublic)` — symmetric by construction
+ * - Compromise of the private key does not reveal the master seed or other derived keys
+ *
+ * ## Use Cases in Umbra
+ * - `registerTokenPublicKey`: The public key is registered on-chain for a token account
+ * - Balance decryption: The private key is used to decrypt AES-GCM ciphertexts from senders
+ * - ECDH with ephemeral sender keys for forward secrecy of individual transfers
+ *
+ * @example
+ * ```typescript
+ * import { X25519Keypair, generateX25519Keypair } from "./cryptography";
+ *
+ * // Generate a new keypair
+ * const keypair: X25519Keypair = await generateX25519Keypair();
+ *
+ * // Share public key with peer
+ * sendPublicKey(peer, keypair.publicKey);
+ *
+ * // Compute shared secret with peer's public key
+ * const sharedSecret = x25519(keypair.privateKey, peerPublicKey);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Ephemeral key exchange for forward secrecy
+ * const ephemeralKeypair: X25519Keypair = await generateX25519Keypair();
+ *
+ * // Use ephemeral keypair for this session only
+ * const sessionKey = deriveSessionKey(
+ *     x25519(ephemeralKeypair.privateKey, recipientPublicKey)
+ * );
+ *
+ * // Discard private key after use for forward secrecy
+ * ```
+ *
+ * @see {@link assertX25519Keypair}
+ * @see {@link X25519PrivateKey}
+ * @see {@link X25519PublicKey}
+ * @public
+ */
+interface X25519Keypair {
+    /**
+     * The X25519 private key (32 bytes).
+     *
+     * This key MUST be kept secret. It is used to:
+     * - Compute shared secrets with other parties' public keys
+     * - Derive the corresponding public key
+     *
+     * @remarks
+     * The private key is derived from the master seed via KMAC256 with the
+     * domain separator `"UserAccountX25519Keypair"`. The X25519 algorithm applies
+     * RFC 8032 §5.1.5 clamping to the scalar during use.
+     *
+     * @readonly
+     */
+    readonly privateKey: X25519PrivateKey;
+    /**
+     * The X25519 public key (32 bytes).
+     *
+     * This key can be freely shared. It is:
+     * - Computed from the private key via scalar multiplication with the base point
+     * - Used by other parties to compute shared secrets with their own private key
+     * - Stored on-chain in the Umbra token account PDA
+     * - Safe to transmit over insecure channels
+     *
+     * @readonly
+     */
+    readonly publicKey: X25519PublicKey;
+}
+/**
+ * Ed25519 keypair for digital signatures on the Edwards form of Curve25519.
+ *
+ * Ed25519 is the signing scheme defined in RFC 8032. In Umbra, an Ed25519
+ * keypair is derived from the same 32-byte seed as the corresponding X25519
+ * keypair (they are related via the birational equivalence of Curve25519 in
+ * Edwards vs Montgomery form). The Ed25519 public key is used as the on-chain
+ * signer identity in registration transactions.
+ *
+ * @remarks
+ * ## Key Derivation
+ * - Seed: First 32 bytes of a 64-byte KMAC256 output keyed by the master seed
+ * - Public key: Derived via `ed25519.getPublicKey(seed)`; uses SHA-512 internally
+ * - The relationship to X25519: the Ed25519 public key can be converted to the
+ *   Montgomery form via `ed25519.utils.toMontgomery(edPublicKey)`
+ *
+ * ## Relationship to X25519
+ * - Ed25519 uses compressed Edwards curve coordinates
+ * - X25519 uses Montgomery curve coordinates
+ * - Both represent points on the same underlying elliptic curve (Curve25519)
+ * - The birational map between them is cheap and deterministic
+ *
+ * @example
+ * ```typescript
+ * import { ed25519 } from "@noble/curves/ed25519";
+ *
+ * const seed = crypto.getRandomValues(new Uint8Array(32));
+ * const publicKey = ed25519.getPublicKey(seed);
+ *
+ * const keypair: Ed25519Keypair = { seed, publicKey };
+ * ```
+ *
+ * @see {@link assertEd25519Keypair}
+ * @see {@link Curve25519KeypairResult}
+ * @public
+ */
+interface Ed25519Keypair {
+    /**
+     * The Ed25519 private key seed (32 bytes).
+     *
+     * This is the raw 32-byte seed from which both the signing scalar and the
+     * public key are derived (via SHA-512 key expansion defined in RFC 8032).
+     * MUST be kept secret.
+     */
+    readonly seed: Uint8Array;
+    /**
+     * The Ed25519 public key (32 bytes).
+     *
+     * A compressed Edwards curve point derived from the seed via SHA-512 key
+     * expansion and scalar multiplication. Can be freely shared and is used
+     * as the on-chain signer identity.
+     */
+    readonly publicKey: Uint8Array;
+}
+/**
+ * Combined Curve25519 keypair result containing both Ed25519 and X25519 keypairs.
+ *
+ * This interface represents the result of deriving both Ed25519 (Edwards curve)
+ * and X25519 (Montgomery curve) keypairs from a single 32-byte seed. Both
+ * keypairs are cryptographically linked through the same underlying Curve25519
+ * and are derived together for efficiency.
+ *
+ * @remarks
+ * ## Derivation Pipeline
+ *
+ * 1. **Ed25519 Keypair**:
+ *    - Input: First 32 bytes of a 64-byte KMAC256 output
+ *    - Output: Ed25519 public key via `ed25519.getPublicKey(seed)`
+ *
+ * 2. **X25519 Keypair**:
+ *    - Hash seed with SHA-512 → 64 bytes
+ *    - Clamp first 32 bytes per RFC 8032 §5.1.5
+ *    - Use clamped bytes as X25519 private key
+ *    - Derive X25519 public key via birational map: `ed25519.utils.toMontgomery(ed25519Pub)`
+ *
+ * ## Security Properties
+ *
+ * - **Deterministic**: Same master seed always produces the same keypairs
+ * - **Domain Separated**: Independent from all other key derivations via KMAC256
+ * - **Cryptographically Linked**: Both keypairs share the same Curve25519 foundation
+ *
+ * @example
+ * ```typescript
+ * import { getUserAccountX25519KeypairGenerator } from "@umbra-privacy/sdk";
+ *
+ * const generator = getUserAccountX25519KeypairGenerator({ client });
+ * const result: Curve25519KeypairResult = await generator();
+ *
+ * // Use Ed25519 for signing
+ * const signature = ed25519.sign(message, result.ed25519Keypair.seed);
+ *
+ * // Use X25519 for key exchange
+ * const sharedSecret = x25519.getSharedSecret(
+ *   result.x25519Keypair.privateKey,
+ *   peerPublicKey
+ * );
+ * ```
+ *
+ * @see {@link Ed25519Keypair}
+ * @see {@link X25519Keypair}
+ * @see {@link assertCurve25519KeypairResult}
+ * @public
+ */
+interface Curve25519KeypairResult {
+    /**
+     * Ed25519 keypair for digital signatures.
+     *
+     * Contains the 32-byte seed and the derived 32-byte compressed Edwards
+     * public key. Used as the on-chain signer for registration transactions.
+     */
+    readonly ed25519Keypair: Ed25519Keypair;
+    /**
+     * X25519 keypair for Diffie-Hellman key exchange.
+     *
+     * Contains the RFC 8032-clamped 32-byte private key (derived from SHA-512
+     * of the Ed25519 seed) and the derived 32-byte Montgomery public key (via
+     * birational conversion from the Ed25519 public key).
+     */
+    readonly x25519Keypair: X25519Keypair;
+}
+/**
+ * Asserts that a value is a valid Ed25519Keypair.
+ *
+ * Validates that the value is a non-null object with `seed` (exactly 32 bytes)
+ * and `publicKey` (exactly 32 bytes) properties.
+ *
+ * @param value - The object to assert as an Ed25519Keypair (must have seed and publicKey properties)
+ * @throws {CryptographyAssertionError} If the value is not a non-null object
+ * @throws {CryptographyAssertionError} If `seed` or `publicKey` are missing
+ * @throws {CryptographyAssertionError} If `seed` or `publicKey` are not Uint8Array(32)
+ *
+ * @example
+ * ```typescript
+ * const keypair = { seed, publicKey };
+ * assertEd25519Keypair(keypair);
+ * // keypair is now typed as Ed25519Keypair
+ * ```
+ *
+ * @see {@link Ed25519Keypair}
+ * @public
+ */
+declare function assertEd25519Keypair(value: {
+    seed: Uint8Array;
+    publicKey: Uint8Array;
+}): asserts value is Ed25519Keypair;
+/**
+ * Asserts that a value is a valid Curve25519KeypairResult.
+ *
+ * Validates that the value is a non-null object with valid `ed25519Keypair`
+ * and `x25519Keypair` fields, each of which must pass their respective assertions.
+ *
+ * @param value - The object to assert as a Curve25519KeypairResult
+ * @throws {CryptographyAssertionError} If the value is not a non-null object
+ * @throws {CryptographyAssertionError} If either nested keypair is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * const result = { ed25519Keypair, x25519Keypair };
+ * assertCurve25519KeypairResult(result);
+ * // result is now typed as Curve25519KeypairResult
+ * ```
+ *
+ * @see {@link Curve25519KeypairResult}
+ * @see {@link assertEd25519Keypair}
+ * @see {@link assertX25519Keypair}
+ * @public
+ */
+declare function assertCurve25519KeypairResult(value: {
+    ed25519Keypair: {
+        seed: Uint8Array;
+        publicKey: Uint8Array;
+    };
+    x25519Keypair: {
+        privateKey: Uint8Array;
+        publicKey: Uint8Array;
+    };
+}): asserts value is Curve25519KeypairResult;
+
+export { BrandedType, Bytes, type Curve25519KeypairResult, type Ed25519Keypair, type EncryptedUserAccount, type FullySignedTransaction, type GeneratorFunction, type KeyStorageContext, type LoadResult, type LoaderFunction, MasterSeed, type MasterSeedGeneratorFunction, type MasterSeedLoaderFunction, type MasterSeedStorerFunction, type ParameterizedGeneratorFunction, type ParameterizedLoaderFunction, type ParameterizedStorerFunction, type PartiallySignedTransaction, PoseidonHash, type QueryComplianceGrantResult, type QueryUserAccountResult, SIGNATURE_BYTE_LENGTH, type SignatureBytes, type SignedTransaction, SolanaAssertionError, type SolanaBytes, type StoreResult, type StorerFunction, type String, SubBrandedType, SubSubBrandedType, type TransactionSignature, U128, U256LeBytes, U512, U8, type UnsignedTransaction, X25519PublicKey$1 as X25519PublicKey, asRelayableSignedTransaction, assertCurve25519KeypairResult, assertEd25519Keypair, assertSignatureBytes, assertSolanaBytes, assertString, assertTransactionSignature };