@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/interfaces-43cReBcS.d.cts

@@ -0,0 +1,3346 @@
+import { C as Curve25519FieldElement, B as Bn254FieldElement, g as PoseidonHash, h as PoseidonCounter, P as PoseidonKey, i as PoseidonKeystream, j as PoseidonCiphertext, k as PoseidonPlaintext, R as RcEncryptionNonce, D as DailyViewingKey, M as MasterSeed, H as HourlyViewingKey, d as MasterViewingKey, f as MintViewingKey, l as MinuteViewingKey, e as MonthlyViewingKey, S as SecondViewingKey, Y as YearlyViewingKey, m as RcCiphertext, n as RcPlaintext, o as RcCounter, p as RcKey } from './cryptography-D6tPDh-Y.cjs';
+import { Address } from '@solana/kit';
+import { i as U512BeBytes, f as U256 } from './types-C_V_CaKK.cjs';
+import { Y as Year, M as Month, D as Day, H as Hour, a as Minute, S as Second } from './types-IMGYmlv-.cjs';
+import { C as Curve25519KeypairResult } from './types-CuKeoI19.cjs';
+
+/**
+ * Fiat-Shamir Challenge Interfaces
+ *
+ * This module defines TypeScript function type interfaces and dependency injection
+ * interfaces for Fiat-Shamir challenge generation and related polynomial operations
+ * used in Umbra's zero-knowledge proof systems.
+ *
+ * ## Fiat-Shamir Heuristic — Background
+ *
+ * An interactive sigma-protocol requires a verifier who sends a uniformly random
+ * challenge after seeing the prover's first message. The Fiat-Shamir transform
+ * replaces this interactive step with a hash of the transcript, turning the proof
+ * into a non-interactive argument of knowledge (NIAOK) secure in the Random
+ * Oracle Model (ROM).
+ *
+ * For Umbra's Groth16-based claim instructions, the challenge is derived from a
+ * 10-element transcript that includes all public inputs (nullifiers, commitments,
+ * root, fee parameters, etc.) in a canonical order defined in
+ * `rules/fiat-shamir-and-aggregated-hash.md`. The ordering **must not change**
+ * because the Circom circuit and the on-chain verifier both encode the same
+ * ordering — a mismatch silently produces wrong proofs.
+ *
+ * ## Security Considerations
+ *
+ * - Challenge generation must be deterministic given the same transcript.
+ * - Outputs must be uniformly distributed over the Curve25519 prime field GF(p).
+ * - All arithmetic must use constant-time field operations to prevent timing side-channels.
+ * - The hash function used (Keccak-256) must be modelled as a random oracle; do
+ *   not substitute weaker primitives.
+ *
+ * @packageDocumentation
+ * @module interfaces/cryptography/challenges
+ * @public
+ */
+
+/**
+ * Function type for generating Fiat-Shamir challenges from a proof transcript.
+ *
+ * Takes a serialised transcript (an arbitrary byte array representing all public
+ * inputs in canonical order) and produces a uniformly distributed element of the
+ * Curve25519 prime field GF(p = 2^255 - 19) using Keccak-256 with rejection
+ * sampling.
+ *
+ * @param input - The serialised transcript byte array. Must contain all public
+ *   proof inputs concatenated in the order mandated by the Circom circuit and
+ *   on-chain verifier. The transcript is treated as opaque bytes; no internal
+ *   parsing is performed.
+ * @returns A {@link Curve25519FieldElement} in the range [0, 2^255 - 19) derived
+ *   deterministically from `input`.
+ *
+ * @remarks
+ * ## Contract
+ *
+ * Implementations of this type **must** guarantee:
+ * 1. **Determinism** — the same `input` always produces the same output.
+ * 2. **Uniform distribution** — the output is statistically indistinguishable
+ *    from a uniformly random element of GF(p). Bias from simple modular
+ *    reduction is not acceptable; use rejection sampling.
+ * 3. **No additional state** — the function must be pure (no caches or counters
+ *    that could make two calls with the same `input` return different values).
+ *
+ * ## Algorithm (reference implementation)
+ *
+ * 1. Compute `h = Keccak256(input)` — 256-bit output.
+ * 2. Clear bit 255 (`h[31] &= 0x7F` in little-endian) to constrain to 255 bits.
+ * 3. Interpret `h` as a little-endian 256-bit unsigned integer `v`.
+ * 4. If `v < p`, return `v` as the challenge.
+ * 5. Otherwise, re-hash `h` (hash chaining) and repeat from step 2.
+ *
+ * ## Why Transcript Ordering Matters for Soundness
+ *
+ * In the ROM, the challenge is bound to the *entire* transcript. If two different
+ * transcripts (e.g. the same inputs in a different order) collide to the same
+ * challenge, an adversary could craft a proof that passes for one statement but
+ * was computed for another. The canonical element ordering in
+ * `rules/fiat-shamir-and-aggregated-hash.md` is part of the protocol definition
+ * and must be respected by all callers.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const generateChallenge: FiatShamirChallengeGeneratorFunction =
+ *   getFiatShamirChallengeGeneratorFunction();
+ *
+ * // Serialise public inputs in canonical order before hashing:
+ * const transcript = buildFiatShamirTranscript({
+ *   merkleRoot,
+ *   nullifiers,
+ *   utxoCommitments,
+ *   recipientPublicKey,
+ *   fees,
+ * });
+ * const challenge: Curve25519FieldElement = generateChallenge(transcript);
+ * ```
+ *
+ * @see {@link getFiatShamirChallengeGeneratorFunction} — factory that returns the default implementation
+ */
+type FiatShamirChallengeGeneratorFunction = (input: Uint8Array) => Curve25519FieldElement;
+/**
+ * Function type for computing successive powers of a Fiat-Shamir challenge value.
+ *
+ * Returns an array `[c^0, c^1, c^2, ..., c^maxPower]` where `c` is the challenge
+ * and all arithmetic is performed in the Curve25519 prime field GF(p = 2^255 - 19).
+ *
+ * @param challenge - The base challenge value to exponentiate.
+ *   Must be a valid {@link Curve25519FieldElement} (i.e. `0 <= challenge < p`).
+ * @param maxPower - The highest power to compute (inclusive). Must be a
+ *   non-negative integer. `maxPower === 0` returns `[1n]`.
+ * @returns An array of length `maxPower + 1` containing
+ *   `[1, challenge, challenge^2, ..., challenge^maxPower]` as
+ *   {@link Curve25519FieldElement} values.
+ *
+ * @throws {Error} If `maxPower` is negative.
+ *
+ * @remarks
+ * ## Contract
+ *
+ * Implementations of this type **must** guarantee:
+ * - The returned array has exactly `maxPower + 1` elements.
+ * - `result[0] === 1n` always (challenge^0 = 1 by convention).
+ * - `result[1] === challenge` when `maxPower >= 1`.
+ * - All elements are valid {@link Curve25519FieldElement} values in [0, p).
+ * - The computation uses O(maxPower) field multiplications (no repeated squaring
+ *   is necessary because all intermediate values are needed).
+ *
+ * ## Use in ZK Protocols
+ *
+ * Challenge powers appear in batched polynomial commitment schemes: if a verifier
+ * wants to check multiple polynomial evaluations simultaneously, it combines
+ * the checks using challenge powers as random coefficients. For example, in
+ * a 10-element Fiat-Shamir transcript the Groth16 circuit may need
+ * `[c^0, ..., c^9]` to batch-verify all input commitments in a single pairing.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const computePowers: ChallengePowersFunction = getChallengePowersFunction();
+ * const challenge = generateChallenge(transcript);
+ * const powers = computePowers(challenge, 9);
+ * // powers[0] === 1n
+ * // powers[1] === challenge
+ * // powers[9] === challenge^9 mod p
+ * ```
+ *
+ * @see {@link getChallengePowersFunction} — factory that returns the default implementation
+ * @see {@link FiatShamirChallengeGeneratorFunction} — produces the challenge input
+ */
+type ChallengePowersFunction = (challenge: Curve25519FieldElement, maxPower: number) => Curve25519FieldElement[];
+/**
+ * Function type for evaluating a univariate polynomial over the Curve25519 field.
+ *
+ * For a polynomial P(x) = c[0] + c[1]·x + c[2]·x² + ... + c[n]·x^n,
+ * computes `P(point)` using Horner's method. All arithmetic is performed in
+ * GF(p = 2^255 - 19).
+ *
+ * @param coefficients - The coefficient array `[c[0], c[1], ..., c[n]]`
+ *   where `c[i]` is the coefficient of `x^i` (constant term first, highest
+ *   degree last). All elements must be valid {@link Curve25519FieldElement} values.
+ *   An empty array represents the zero polynomial and returns `0n`.
+ * @param point - The evaluation point, must be a valid {@link Curve25519FieldElement}.
+ * @returns `P(point) mod p` as a {@link Curve25519FieldElement}.
+ *
+ * @remarks
+ * ## Contract
+ *
+ * Implementations of this type **must** guarantee:
+ * - The result is a valid {@link Curve25519FieldElement} in [0, p).
+ * - Empty `coefficients` returns `0n`.
+ * - The evaluation uses Horner's method or equivalent (n multiplications and
+ *   n additions for a degree-n polynomial), not the naïve O(n^2) approach.
+ *
+ * ## Horner's Method — Mathematical Derivation
+ *
+ * ```
+ * P(x) = c[0] + c[1]·x + c[2]·x² + ... + c[n]·x^n
+ *       = c[0] + x·(c[1] + x·(c[2] + ... + x·c[n]))
+ * ```
+ *
+ * Starting from the innermost term `c[n]`, multiply by `x` and add `c[n-1]`,
+ * repeat until `c[0]` is incorporated. This requires exactly n multiplications
+ * and n additions regardless of the polynomial's degree — the minimum possible.
+ *
+ * ## Edge Cases
+ * - Empty coefficients array → returns `0n`.
+ * - Single coefficient `[c]` → returns `c` (constant polynomial, `point` is ignored).
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const evaluate: PolynomialEvaluatorFunction = getPolynomialEvaluatorFunction();
+ *
+ * // P(x) = 1 + 2x + 3x^2
+ * const coefficients = [1n, 2n, 3n] as Curve25519FieldElement[];
+ * const point = 2n as Curve25519FieldElement;
+ * const value = evaluate(coefficients, point);
+ * // value === 1 + 2*2 + 3*4 === 17n
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Zero polynomial
+ * const zero = evaluate([], anyPoint); // === 0n
+ *
+ * // Constant polynomial
+ * const constant = evaluate([42n as Curve25519FieldElement], anyPoint); // === 42n
+ * ```
+ *
+ * @see {@link getPolynomialEvaluatorFunction} — factory that returns the default implementation
+ */
+type PolynomialEvaluatorFunction = (coefficients: Curve25519FieldElement[], point: Curve25519FieldElement) => Curve25519FieldElement;
+/**
+ * Function type for modular exponentiation over the Curve25519 prime field.
+ *
+ * Computes `base^exp mod p` where `p = 2^255 - 19` is the Curve25519 field prime.
+ * The exponent may be any non-negative `bigint`.
+ *
+ * @param base - The base value. Must be a valid {@link Curve25519FieldElement} in [0, p).
+ * @param exp - The exponent. May be any non-negative `bigint`; large values (e.g. the
+ *   Rescue-XLIX inverse alpha exponent) are supported.
+ * @returns `base^exp mod p` as a {@link Curve25519FieldElement}.
+ *
+ * @remarks
+ * ## Contract
+ *
+ * Implementations of this type **must** guarantee:
+ * - The result is a valid {@link Curve25519FieldElement} in [0, p).
+ * - `base^0 === 1n` for all bases (including `0^0 = 1` by convention).
+ * - The algorithm runs in O(log exp) field multiplications.
+ *
+ * ## Algorithm
+ *
+ * Uses the standard binary square-and-multiply (right-to-left) method. For
+ * the special case where `exp === 0n`, returns `1n` immediately without entering
+ * the multiplication loop.
+ *
+ * ## Use Cases
+ *
+ * This function type is primarily used:
+ * - In the Rescue-XLIX inverse S-box: `x^(1/alpha)` requires computing the
+ *   multiplicative inverse exponent over GF(p).
+ * - In pairing-based protocols where field element inversions are expressed
+ *   as exponentiations using Fermat's little theorem: `x^(p-2)`.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const modPow: ModuloPowCurve25519Function = getModuloPowCurve25519Function();
+ * const base = 2n as Curve25519FieldElement;
+ * const result = modPow(base, 10n);
+ * // result === 1024n
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Fermat's little theorem: x^(p-2) === x^(-1) mod p
+ * const modPow = getModuloPowCurve25519Function();
+ * const inverse = modPow(someElement, CURVE25519_FIELD_PRIME - 2n);
+ * ```
+ *
+ * @see {@link getModuloPowCurve25519Function} — factory that returns the default implementation
+ */
+type ModuloPowCurve25519Function = (base: Curve25519FieldElement, exp: bigint) => Curve25519FieldElement;
+/**
+ * Optional dependency injection bag for {@link getChallengePowersFunction}.
+ *
+ * Allows callers to substitute a custom modular multiplication implementation,
+ * primarily for unit testing (e.g. wrapping with a spy) or for environments
+ * that provide a native field arithmetic implementation. When fields are
+ * omitted, the default constant-time Curve25519 multiplication is used.
+ *
+ * @remarks
+ * ## Why Dependency Injection?
+ *
+ * The challenge powers function captures `modMul` in a closure. Injecting
+ * the function at construction time (rather than calling a global singleton
+ * on every multiplication) avoids global state and makes the function's
+ * behaviour fully deterministic for a given `modMul` implementation.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getChallengePowersFunction } from './challenges';
+ *
+ * // Testing: use a spy to count multiplications
+ * let mulCount = 0;
+ * const spyModMul = (a: bigint, b: bigint) => { mulCount++; return (a * b) % CURVE25519_FIELD_PRIME; };
+ * const powers = getChallengePowersFunction({ modMul: spyModMul })(challenge, 5);
+ * console.log(mulCount); // === 4 (for maxPower === 5)
+ * ```
+ */
+interface ChallengePowersDeps {
+    /**
+     * Custom modular multiplication function over GF(p = 2^255 - 19).
+     *
+     * If provided, this function is used in place of the default constant-time
+     * Curve25519 multiplication. The function **must** return a value in [0, p)
+     * for any pair of inputs `(a, b)` in [0, p).
+     *
+     * @defaultValue The default constant-time implementation from `math/curve25519/field-arithmetic`.
+     */
+    readonly modMul?: (a: bigint, b: bigint) => bigint;
+}
+/**
+ * Optional dependency injection bag for {@link getPolynomialEvaluatorFunction}.
+ *
+ * Allows callers to substitute custom modular addition and/or multiplication
+ * implementations, primarily for unit testing or specialised environments.
+ * When fields are omitted, the default constant-time Curve25519 operations are used.
+ *
+ * @remarks
+ * ## Partial Overrides
+ *
+ * Either `modAdd` or `modMul` may be omitted independently. If only one is
+ * provided, the other falls back to its default implementation. This is useful
+ * when you want to test only one of the two arithmetic paths in isolation.
+ *
+ * ## Caching Caveat
+ *
+ * When any custom dependency is provided, the returned evaluator function is
+ * **not** cached (unlike the no-deps default singleton). Each call to
+ * `getPolynomialEvaluatorFunction` with non-empty deps creates a fresh closure.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getPolynomialEvaluatorFunction } from './challenges';
+ *
+ * // Testing with a modular addition spy
+ * let addCount = 0;
+ * const spyModAdd = (a: bigint, b: bigint) => { addCount++; return (a + b) % PRIME; };
+ * const evaluate = getPolynomialEvaluatorFunction({ modAdd: spyModAdd });
+ * evaluate([1n, 2n, 3n] as Curve25519FieldElement[], 4n as Curve25519FieldElement);
+ * console.log(addCount); // === 2 (for a degree-2 polynomial)
+ * ```
+ */
+interface PolynomialEvaluatorDeps {
+    /**
+     * Custom modular addition function over GF(p = 2^255 - 19).
+     *
+     * If provided, this function is used in place of the default constant-time
+     * Curve25519 addition. The function **must** return a value in [0, p) for
+     * any pair of inputs `(a, b)` in [0, p).
+     *
+     * @defaultValue The default constant-time implementation from `math/curve25519/field-arithmetic`.
+     */
+    readonly modAdd?: (a: bigint, b: bigint) => bigint;
+    /**
+     * Custom modular multiplication function over GF(p = 2^255 - 19).
+     *
+     * If provided, this function is used in place of the default constant-time
+     * Curve25519 multiplication. The function **must** return a value in [0, p)
+     * for any pair of inputs `(a, b)` in [0, p).
+     *
+     * @defaultValue The default constant-time implementation from `math/curve25519/field-arithmetic`.
+     */
+    readonly modMul?: (a: bigint, b: bigint) => bigint;
+}
+
+/**
+ * Poseidon Cipher Interfaces
+ *
+ * This module defines the TypeScript interface types for Poseidon hash and cipher
+ * operations. Poseidon is a cryptographic hash function optimized for zero-knowledge
+ * proof systems, operating natively on field elements.
+ *
+ * ## Overview
+ *
+ * Poseidon is designed for efficiency in SNARK and STARK circuits. It uses
+ * the BN254 (alt_bn128) field, making it compatible with Ethereum precompiles
+ * and widely-used ZK proof systems like Groth16 and PLONK.
+ *
+ * ## Features
+ *
+ * - **Hash Function**: Collision-resistant hashing of field elements
+ * - **Encryption**: Symmetric encryption using Poseidon permutation
+ * - **Decryption**: Symmetric decryption recovering original plaintexts
+ * - **Keystream Generation**: Counter-mode key derivation for streaming encryption
+ *
+ * ## Interface Design: Dependency Injection
+ *
+ * Every function type in this module is defined as a `type` alias for a function
+ * signature rather than as a concrete implementation. This enables dependency
+ * injection throughout the SDK: callers declare what they need
+ * (e.g., `PoseidonHashFunction`) and receive an implementation via a getter
+ * (e.g., `getPoseidonHasher()`). Tests can substitute mock implementations, and
+ * the production code remains decoupled from the underlying `@noble/curves` library.
+ *
+ * ## Aggregation vs. Hashing
+ *
+ * Two distinct hash function types are provided:
+ * - {@link PoseidonHashFunction} — low-level, returns an unbranded `Bn254FieldElement`.
+ *   Suitable for recursive hashing, Merkle tree construction, and any use where the
+ *   caller manages the output type.
+ * - {@link PoseidonAggregatorHashFunction} — high-level aggregator, returns a branded
+ *   {@link PoseidonHash}. Used specifically for the aggregated ZK public input (the
+ *   70-element Poseidon chain that collapses all UTXO fields into a single on-chain
+ *   verifier input).
+ *
+ * @see {@link https://eprint.iacr.org/2019/458} Poseidon: A New Hash Function for Zero-Knowledge Proof Systems
+ * @see {@link PoseidonKey} for the user's Poseidon private key type
+ * @see {@link PoseidonHashFunction} for the low-level hash interface
+ * @see {@link PoseidonAggregatorHashFunction} for the high-level aggregator interface
+ *
+ * @packageDocumentation
+ * @module crypto/poseidon/interfaces
+ */
+
+/**
+ * An asynchronous function that computes a Poseidon hash over N BN254 field elements.
+ *
+ * This is the foundational Poseidon interface in the SDK. It maps an ordered array of
+ * {@link Bn254FieldElement} values to a single {@link Bn254FieldElement} output using
+ * the Poseidon permutation with parameters tuned for the BN254 scalar field. The
+ * implementation is compatible with Circom's `Poseidon(N)` template.
+ *
+ * @param dataPoints - An ordered, readonly array of {@link Bn254FieldElement} values to hash.
+ *   The implementation supports 1 to 12 elements. Input order is significant:
+ *   `hash([a, b]) ≠ hash([b, a])`.
+ * @returns A `Promise` resolving to a single {@link Bn254FieldElement} — the Poseidon
+ *   hash output. The output is always a valid BN254 field element.
+ *
+ * @remarks
+ * ## Poseidon Construction
+ *
+ * The Poseidon hash function uses a sponge construction with a width-`t` state
+ * (where `t = N + 1`) over the BN254 scalar field F_r. The permutation consists of:
+ * - Full rounds (applying x^5 to the entire state) at the beginning and end.
+ * - Partial rounds (applying x^5 only to the first element) in the middle.
+ *
+ * Round counts and MDS matrix coefficients are fixed parameters determined by
+ * the security analysis in the Poseidon paper (eprint 2019/458). They cannot
+ * be changed without breaking compatibility with existing ZK circuits.
+ *
+ * ## ZK-Friendliness
+ *
+ * Poseidon requires approximately 8N R1CS constraints per hash of N field elements,
+ * compared to ~25,000 for SHA-256. This makes it practical to prove hash pre-images
+ * inside a Groth16 proof. In Umbra, this property is essential for:
+ * - Proving knowledge of a UTXO's opening (amount, nullifier, blinding factor).
+ * - Proving membership in the indexed Merkle tree (IMT) without revealing the leaf.
+ * - Generating Fiat-Shamir challenges from a transcript of public values.
+ *
+ * ## Async Interface
+ *
+ * The `Promise` wrapper is used for consistency with the rest of the SDK's
+ * cryptographic API. The underlying computation is synchronous, but callers should
+ * always `await` the result.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonHasher } from "@umbra/sdk";
+ *
+ * const hasher: PoseidonHashFunction = getPoseidonHasher();
+ *
+ * // Hash two field elements (order matters)
+ * const h1 = await hasher([123n, 456n]);
+ * const h2 = await hasher([456n, 123n]);
+ * // h1 !== h2 in general
+ *
+ * // Hash a single element (used as a PRF output or commitment)
+ * const commitment = await hasher([secretValue]);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Merkle tree parent node computation
+ * const parent = await hasher([leftChild, rightChild]);
+ * ```
+ *
+ * @see {@link PoseidonAggregatorHashFunction} for the branded-output aggregation variant
+ * @see {@link PoseidonPrfFunction} for the PRF interface built on top of this hash
+ * @public
+ */
+type PoseidonHashFunction = (dataPoints: readonly Bn254FieldElement[]) => Promise<Bn254FieldElement>;
+/**
+ * An asynchronous function that encrypts an array of {@link PoseidonPlaintext} values
+ * using Poseidon counter-mode encryption.
+ *
+ * This encryptor is the write side of Umbra's confidential token account scheme.
+ * For each plaintext at position `i` (0-indexed), it derives an independent keystream
+ * via the Poseidon PRF and adds it to the plaintext modulo the BN254 field prime,
+ * producing the corresponding ciphertext.
+ *
+ * @param plaintexts - An ordered, readonly array of {@link PoseidonPlaintext} values to encrypt.
+ *   Each element is encrypted independently at its array position. The array length
+ *   determines how many counter values are consumed.
+ * @param key - The {@link PoseidonKey} (user's Poseidon private key, derived from the master
+ *   seed) used as the PRF key for keystream generation. Must be kept secret.
+ * @returns A `Promise` resolving to an array of {@link PoseidonCiphertext} values, in the
+ *   same order as the input plaintexts. `result[i]` is the encryption of `plaintexts[i]`.
+ *
+ * @remarks
+ * ## Encryption Scheme
+ *
+ * For each plaintext position `i`, the cipher operates as:
+ * ```
+ * keystream[i] = Poseidon([key, i, 2n])
+ * ciphertext[i] = (plaintext[i] + keystream[i]) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * The domain separation constant `2n` in the third argument slot ensures that
+ * keystream generation is distinct from any other Poseidon usage in the protocol
+ * (e.g., commitment hashing, Fiat-Shamir challenges).
+ *
+ * ## What Is Encrypted
+ *
+ * In Umbra's confidential token account model, the encrypted fields are:
+ * - Token balance (as a field element representing the token amount).
+ * - Blinding factors associated with UTXO commitments.
+ *
+ * These ciphertexts are stored in the on-chain `EncryptedTokenAccount` state and
+ * can only be decrypted by the holder of the corresponding `PoseidonKey`.
+ *
+ * ## IND-CPA Security
+ *
+ * Under the PRF security assumption for Poseidon, each ciphertext is computationally
+ * indistinguishable from a uniformly random field element. The scheme provides
+ * IND-CPA security as long as the key is secret and counter values are not reused.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonEncryptor } from "@umbra/sdk";
+ *
+ * const encryptor: PoseidonEncryptorFunction = getPoseidonEncryptor();
+ *
+ * // Encrypt a token balance and blinding factor together
+ * const balance: PoseidonPlaintext = ...; // amount as field element
+ * const blinding: PoseidonPlaintext = ...; // random blinding factor
+ *
+ * const ciphertexts = await encryptor([balance, blinding], myPoseidonKey);
+ * // ciphertexts[0] = encryption of balance  (counter 0)
+ * // ciphertexts[1] = encryption of blinding (counter 1)
+ * ```
+ *
+ * @see {@link PoseidonDecryptorFunction} for the corresponding decryption function
+ * @see {@link PoseidonKeystreamGeneratorFunction} for direct keystream access
+ * @see {@link PoseidonKey} for the key type accepted by this function
+ * @public
+ */
+type PoseidonEncryptorFunction = (plaintexts: readonly PoseidonPlaintext[], key: PoseidonKey) => Promise<PoseidonCiphertext[]>;
+/**
+ * An asynchronous function that decrypts an array of {@link PoseidonCiphertext} values
+ * using Poseidon counter-mode decryption.
+ *
+ * This decryptor is the read side of Umbra's confidential token account scheme. For
+ * each ciphertext at position `i`, it regenerates the same keystream that was used
+ * during encryption and subtracts it (modulo the BN254 field prime) to recover the
+ * original plaintext.
+ *
+ * @param ciphertexts - An ordered, readonly array of {@link PoseidonCiphertext} values to decrypt.
+ *   The array length determines how many counter values are consumed. `result[i]` is
+ *   the decryption of `ciphertexts[i]`.
+ * @param key - The {@link PoseidonKey} that was used during encryption. Using a different
+ *   key will produce garbage output without any error — the cipher has no authentication
+ *   and does not detect wrong-key decryption.
+ * @returns A `Promise` resolving to an array of {@link PoseidonPlaintext} values, in the
+ *   same order as the input ciphertexts.
+ *
+ * @remarks
+ * ## Decryption Formula
+ *
+ * For each ciphertext at position `i`:
+ * ```
+ * keystream[i] = Poseidon([key, i, 2n])
+ * plaintext[i] = (ciphertext[i] - keystream[i] + BN254_FIELD_PRIME) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * The addition of `BN254_FIELD_PRIME` before the modulo ensures the result is
+ * non-negative even when `ciphertext[i] < keystream[i]` (subtraction would underflow
+ * without it).
+ *
+ * ## No Authentication
+ *
+ * This cipher provides confidentiality (IND-CPA) but NOT integrity. A wrong key
+ * silently produces incorrect plaintexts rather than throwing. Callers that need
+ * authenticated decryption must layer a MAC or use a scheme that includes a
+ * commitment to the ciphertext (e.g., comparing against an on-chain hash).
+ *
+ * In Umbra, ciphertext integrity is enforced externally via ZK proof verification:
+ * the prover must demonstrate knowledge of the plaintext that satisfies the
+ * circuit's constraints, which transitively checks correctness.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonDecryptor } from "@umbra/sdk";
+ *
+ * const decryptor: PoseidonDecryptorFunction = getPoseidonDecryptor();
+ *
+ * // Recover balance and blinding factor from on-chain ciphertexts
+ * const [balance, blinding] = await decryptor(
+ *   [encryptedBalance, encryptedBlinding],
+ *   myPoseidonKey
+ * );
+ * // balance: PoseidonPlaintext — original amount
+ * // blinding: PoseidonPlaintext — original blinding factor
+ * ```
+ *
+ * @see {@link PoseidonEncryptorFunction} for the corresponding encryption function
+ * @see {@link PoseidonKey} for the key type accepted by this function
+ * @public
+ */
+type PoseidonDecryptorFunction = (ciphertexts: readonly PoseidonCiphertext[], key: PoseidonKey) => Promise<PoseidonPlaintext[]>;
+/**
+ * An asynchronous function that generates per-counter Poseidon keystream values.
+ *
+ * This function is the core PRF primitive underlying Umbra's stream cipher. Given a set of
+ * counter values and a master {@link PoseidonKey}, it returns a map from each counter to
+ * its corresponding {@link PoseidonKeystream} value. Callers use these keystream values
+ * directly to perform field-element encryption and decryption, or they can rely on the
+ * higher-level {@link PoseidonEncryptorFunction} and {@link PoseidonDecryptorFunction}.
+ *
+ * @param counters - A readonly array of {@link PoseidonCounter} values specifying which
+ *   positions in the keystream to generate. Counters may be provided in any order; the
+ *   returned `Map` is keyed by counter value for random-access lookup.
+ * @param key - The master {@link PoseidonKey} (user's Poseidon private key) from which all
+ *   keystream elements are derived. This value must remain secret.
+ * @returns A `Promise` resolving to a `Map<PoseidonCounter, PoseidonKeystream>` where each
+ *   entry maps a requested counter to the corresponding derived keystream.
+ *
+ * @remarks
+ * ## Keystream Generation Formula
+ *
+ * For each counter `c` in the input array, the keystream element is:
+ * ```
+ * keystream(c) = Poseidon([key, c, 2n])
+ * ```
+ *
+ * - `key`: the user's {@link PoseidonKey} — 1 field element.
+ * - `c`: the {@link PoseidonCounter} — 1 field element (typically a small non-negative integer).
+ * - `2n`: domain separation constant — distinguishes keystream PRF from other Poseidon
+ *   usages within the Umbra protocol.
+ *
+ * Total Poseidon inputs: 3 elements → state width t = 4.
+ *
+ * ## Usage as a Stream Cipher
+ *
+ * ```
+ * // Encrypt position i:
+ * ciphertext[i] = (plaintext[i] + keystream(i)) mod BN254_FIELD_PRIME
+ *
+ * // Decrypt position i:
+ * plaintext[i]  = (ciphertext[i] - keystream(i) + BN254_FIELD_PRIME) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * ## Keystream Commitment
+ *
+ * In Umbra's linker encryption scheme, keystream values are also committed on-chain via
+ * {@link KeystreamCommitmentFunction}:
+ * ```
+ * commitment = Poseidon([keystream, blindingFactor])
+ * ```
+ * This allows a ZK proof to verify that the correct keystream was used in a specific
+ * encryption operation without revealing the keystream itself.
+ *
+ * ## Security
+ *
+ * - Keystream values are cryptographic secrets. They must never be stored persistently,
+ *   logged, or transmitted outside the current computation context.
+ * - Counter reuse with the same key reveals the field difference between the two
+ *   plaintexts encrypted at that position.
+ * - The output `Map` uses `PoseidonCounter` as its key type, so `Map.get(c)` requires
+ *   the same branded `PoseidonCounter` value used as input.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonKeystreamGenerator } from "@umbra/sdk";
+ *
+ * const keystreamGenerator: PoseidonKeystreamGeneratorFunction =
+ *   getPoseidonKeystreamGenerator();
+ *
+ * // Generate keystreams for positions 0, 1, and 2
+ * const counters: PoseidonCounter[] = [0n, 1n, 2n].map((c) => {
+ *   assertPoseidonCounter(c); return c;
+ * });
+ *
+ * const keystreamMap = await keystreamGenerator(counters, myPoseidonKey);
+ *
+ * // Access individual keystream values
+ * const ks0 = keystreamMap.get(counters[0])!;
+ * const ks1 = keystreamMap.get(counters[1])!;
+ *
+ * // Encrypt manually
+ * const ciphertext0 = (plaintext0 + ks0) % BN254_FIELD_PRIME;
+ * const ciphertext1 = (plaintext1 + ks1) % BN254_FIELD_PRIME;
+ * ```
+ *
+ * @see {@link PoseidonEncryptorFunction} for the higher-level encryption interface
+ * @see {@link PoseidonDecryptorFunction} for the higher-level decryption interface
+ * @see {@link KeystreamCommitmentFunction} for committing keystream values in ZK proofs
+ * @see {@link PoseidonCounter} for the counter (nonce) type
+ * @see {@link PoseidonKeystream} for the keystream output type
+ * @public
+ */
+type PoseidonKeystreamGeneratorFunction = (counters: readonly PoseidonCounter[], key: PoseidonKey) => Promise<Map<PoseidonCounter, PoseidonKeystream>>;
+/**
+ * An asynchronous function that aggregates multiple BN254 field elements into a single
+ * branded {@link PoseidonHash} via a sequence of Poseidon invocations.
+ *
+ * The aggregator is the high-level interface used to produce the single on-chain public
+ * input for the Groth16 verifier. Rather than passing all UTXO fields individually
+ * (which would be impractical on-chain), Umbra aggregates them into one field element
+ * that the ZK circuit can verify matches a committed value.
+ *
+ * @param plaintexts - A readonly array of {@link Bn254FieldElement} values representing
+ *   the full set of UTXO fields to aggregate. In the Umbra claim protocol, this array
+ *   contains exactly 70 elements: the Fiat-Shamir transcript concatenated with all
+ *   per-UTXO field values (amounts, nullifiers, addresses, blinding factors). The
+ *   order of elements must match the Circom circuit's expected ordering exactly.
+ * @returns A `Promise` resolving to a branded {@link PoseidonHash} — the single
+ *   aggregated public input. This value is compared on-chain against the hash
+ *   embedded in the Groth16 proof's public signals.
+ *
+ * @remarks
+ * ## Aggregation Algorithm
+ *
+ * The aggregator processes the input array in a chain: each Poseidon invocation takes
+ * two inputs — the running accumulator and the next element — and produces an updated
+ * accumulator:
+ * ```
+ * acc = plaintexts[0]
+ * for i in 1..N-1:
+ *   acc = Poseidon([acc, plaintexts[i]])
+ * result = acc  (as PoseidonHash)
+ * ```
+ *
+ * This is a serial (non-tree) aggregation. The result depends on the order of all
+ * inputs; swapping any two elements produces a completely different hash.
+ *
+ * ## Role in Umbra's ZK Protocol
+ *
+ * The 70-element aggregated public input condenses the Fiat-Shamir transcript and
+ * all UTXO data fields into a single on-chain verifiable value. The Groth16 prover
+ * produces a proof that the circuit constraints are satisfied given this exact public
+ * input, and the Solana program verifies both:
+ * 1. The Groth16 proof is valid for the given public input.
+ * 2. The public input matches the locally computed aggregated hash.
+ *
+ * ## Difference from `PoseidonHashFunction`
+ *
+ * While {@link PoseidonHashFunction} accepts up to 12 elements in a single call and
+ * returns an unbranded `Bn254FieldElement`, this function handles arbitrarily many
+ * elements via chaining and returns a branded `PoseidonHash`. The branded return type
+ * ensures aggregated hashes are not accidentally mixed with raw field elements in
+ * downstream code.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonAggregator } from "@umbra/sdk";
+ *
+ * const aggregator: PoseidonAggregatorHashFunction = getPoseidonAggregator();
+ *
+ * // Build the 70-element input array (Fiat-Shamir + UTXO fields)
+ * const publicInputs: Bn254FieldElement[] = buildAggregatedInputArray(utxos, transcript);
+ * // publicInputs.length === 70
+ *
+ * const aggregatedHash = await aggregator(publicInputs);
+ * // aggregatedHash: PoseidonHash — single value submitted to the on-chain verifier
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Smaller example: aggregate three commitment values
+ * const data: Bn254FieldElement[] = [commitment1, commitment2, commitment3];
+ * const fingerprint = await aggregator(data);
+ * // fingerprint uniquely identifies the ordered set of commitments
+ * ```
+ *
+ * @see {@link PoseidonHashFunction} for the low-level, unbranded, single-call hash interface
+ * @see {@link PoseidonHash} for the branded output type
+ * @public
+ */
+type PoseidonAggregatorHashFunction = (plaintexts: readonly Bn254FieldElement[]) => Promise<PoseidonHash>;
+/**
+ * An asynchronous function that evaluates the Poseidon Pseudo-Random Function (PRF).
+ *
+ * A PRF is a deterministic keyed function whose outputs are computationally
+ * indistinguishable from random when the key (seeds) is unknown. This Poseidon-based
+ * PRF is the foundation for all key derivation, nullifier generation, and keystream
+ * computation in the Umbra SDK.
+ *
+ * @param seeds - A readonly array of 1 to 11 {@link Bn254FieldElement} values serving as
+ *   the secret key material. In combination with the evaluation point, the total number
+ *   of Poseidon inputs must not exceed 12 (`seeds.length + 1 ≤ 12`).
+ * @param evaluationPoint - A public {@link Bn254FieldElement} at which to evaluate the PRF.
+ *   Different evaluation points yield completely different outputs from the same seeds,
+ *   allowing a single set of seeds to derive multiple independent values (one per point).
+ * @returns A `Promise` resolving to a {@link Bn254FieldElement} — the PRF output.
+ *   The output is deterministic for the same `(seeds, evaluationPoint)` pair.
+ *
+ * @remarks
+ * ## PRF Construction
+ *
+ * The PRF is instantiated as a Poseidon hash over all seeds followed by the evaluation
+ * point:
+ * ```
+ * PRF(seeds, x) = Poseidon([seeds[0], seeds[1], ..., seeds[n-1], x])
+ * ```
+ *
+ * The evaluation point `x` is always the last input, ensuring a clean separation
+ * between the key material and the index.
+ *
+ * ## Input Constraints
+ *
+ * - `seeds.length` must be at least 1 and at most 11.
+ * - The total `seeds.length + 1` must not exceed 12, which is the maximum arity
+ *   supported by this Poseidon implementation (state width t = 13).
+ * - Violating these constraints will produce an error from the underlying hasher.
+ *
+ * ## Security Properties
+ *
+ * - **Deterministic**: Identical `(seeds, evaluationPoint)` always yields the same output.
+ * - **Pseudo-random**: If at least one seed is unknown to the adversary, the output
+ *   is computationally indistinguishable from a uniformly random field element.
+ * - **Key-dependent**: Even a single bit difference in seeds produces an entirely
+ *   different output (avalanche effect of Poseidon's non-linear permutation).
+ * - **Collision-resistant**: Inherited from Poseidon's second-preimage resistance.
+ *
+ * ## Use Cases in Umbra
+ *
+ * - **Keystream generation**: `PRF(poseidonKey, counter)` derives per-counter keystreams
+ *   for counter-mode encryption of confidential token balances.
+ * - **Nullifier derivation**: `PRF(viewingKey, utxoIndex)` produces the nullifier
+ *   that is published on-chain when a UTXO is spent, preventing double-spending.
+ * - **User commitment**: `PRF([masterViewingKey, poseidonKey], domainTag)` produces the
+ *   user's on-chain commitment that binds their cryptographic identity to a single
+ *   field element verifiable in a ZK circuit.
+ *
+ * @example
+ * ```typescript
+ * import { getPoseidonPrf } from "@umbra/sdk";
+ *
+ * const prf: PoseidonPrfFunction = getPoseidonPrf();
+ *
+ * // Derive three independent values from the same secret seed
+ * const secretSeed: Bn254FieldElement = myDerivedKey;
+ * const keystream0 = await prf([secretSeed], 0n); // at point 0
+ * const keystream1 = await prf([secretSeed], 1n); // at point 1
+ * const keystream2 = await prf([secretSeed], 2n); // at point 2
+ * // All three are distinct and computationally random
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nullifier generation in a ZK UTXO protocol
+ * const prf: PoseidonPrfFunction = getPoseidonPrf();
+ *
+ * const viewingKey: Bn254FieldElement = userViewingKey;
+ * const utxoIndex: Bn254FieldElement = BigInt(noteIndex);
+ *
+ * // Nullifier: PRF(viewingKey, utxoIndex)
+ * const nullifier = await prf([viewingKey], utxoIndex);
+ * // nullifier uniquely identifies the spent note without revealing the viewing key
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multi-seed PRF for user commitment (binds two keys)
+ * const userCommitment = await prf([masterViewingKey, poseidonKey], domainSeparator);
+ * ```
+ *
+ * @see {@link PoseidonHashFunction} for the underlying hash primitive
+ * @see {@link PoseidonKeystreamGeneratorFunction} for the keystream-specific wrapper
+ * @public
+ */
+type PoseidonPrfFunction = (seeds: readonly Bn254FieldElement[], evaluationPoint: Bn254FieldElement) => Promise<Bn254FieldElement>;
+/**
+ * Parameters for generating the H2 UTXO leaf as a flat Poseidon(6) hash.
+ *
+ * ```
+ * H2 = Poseidon([amount, nullifier, userCommitment, addrLow, addrHigh, h2BlindingFactor])
+ * ```
+ *
+ * The BN254 field constraint means the Solana address (32 bytes = 256 bits) must be
+ * split into two 128-bit halves (`finalDestinationAddressLow` and
+ * `finalDestinationAddressHigh`) for compatibility with Poseidon's field element inputs.
+ *
+ * Input ordering must exactly match the Circom circuit's witness assignment.
+ *
+ * @see {@link H2CircuitProvableHashFunction}
+ * @see {@link H2HashFunction}
+ * @public
+ */
+interface H2CircuitProvableParams {
+    /**
+     * The transaction amount in the smallest token unit (after protocol fees have been deducted).
+     *
+     * @remarks
+     * This is the net amount that will be claimable by the UTXO recipient after protocol
+     * and relayer fees. Must be a valid BN254 field element. For token amounts that fit
+     * within 64 bits (all SPL token amounts), this is always safely within field range.
+     *
+     * The circuit constrains the amount to be non-negative and consistent with the
+     * encrypted balance stored in the sender's confidential token account.
+     */
+    amount: Bn254FieldElement;
+    /**
+     * The nullifier that uniquely identifies this UTXO and prevents double-spending.
+     *
+     * @remarks
+     * The nullifier is derived deterministically from the user's viewing key and the
+     * UTXO's position or index:
+     * ```
+     * nullifier = Poseidon([viewingKey, utxoIndex])
+     * ```
+     *
+     * When a UTXO is claimed, its nullifier is published on-chain and inserted into the
+     * treap nullifier set. Subsequent claim attempts for the same UTXO are rejected by
+     * checking for the nullifier's presence in the treap.
+     *
+     * The ZK circuit proves knowledge of the pre-image (viewing key + index) that
+     * produces this nullifier, without revealing the viewing key.
+     */
+    nullifier: Bn254FieldElement;
+    /**
+     * The on-chain commitment that identifies the user authorized to claim this UTXO.
+     *
+     * @remarks
+     * The `userCommitment` is computed as:
+     * ```
+     * userCommitment = Poseidon([masterViewingKey, poseidonKey])
+     * ```
+     *
+     * Two locking modes exist in the Umbra protocol:
+     * - **Ephemeral unlocking**: the `userCommitment` is derived from a per-UTXO ephemeral
+     *   key, allowing claim by anyone who knows that ephemeral key.
+     * - **Receiver unlocking**: the `userCommitment` is the receiver's registered
+     *   commitment, requiring the receiver's `masterViewingKey` and `poseidonKey`.
+     *
+     * The circuit proves that the claimer knows the opening of this commitment.
+     */
+    userCommitment: Bn254FieldElement;
+    /**
+     * The lower 128 bits of the final destination Solana address (bytes 0–15).
+     *
+     * @remarks
+     * Solana public keys are 32 bytes (256 bits). Because BN254 field elements are
+     * only ~254 bits, a full Solana address cannot be represented as a single field
+     * element without potential reduction. The address is therefore split into two
+     * 128-bit halves for safe inclusion as Poseidon inputs.
+     *
+     * The split is:
+     * ```
+     * finalDestinationAddressLow  = address & 0xFFFFFFFF_FFFFFFFF_FFFFFFFF_FFFFFFFFn
+     * finalDestinationAddressHigh = address >> 128n
+     * ```
+     */
+    finalDestinationAddressLow: Bn254FieldElement;
+    /**
+     * The upper 128 bits of the final destination Solana address (bytes 16–31).
+     *
+     * @remarks
+     * Pair of {@link H2CircuitProvableParams.finalDestinationAddressLow}. Together, the
+     * two halves reconstruct the full 32-byte Solana destination address:
+     * ```
+     * address = finalDestinationAddressLow | (finalDestinationAddressHigh << 128n)
+     * ```
+     */
+    finalDestinationAddressHigh: Bn254FieldElement;
+    /**
+     * A uniformly random BN254 field element that provides hiding for the H2 commitment.
+     *
+     * @remarks
+     * Without a blinding factor, the UTXO commitment `H2` would be deterministic given
+     * the other public fields (amount, destination address). An observer could enumerate
+     * candidate amounts and precompute commitments to deanonymize transactions. The
+     * blinding factor makes each UTXO commitment computationally unique even for
+     * identical amounts and destinations.
+     *
+     * Must be generated using a CSPRNG and must remain secret until the UTXO is claimed.
+     */
+    h2BlindingFactor: Bn254FieldElement;
+}
+/**
+ * Backward-compatible alias for {@link H2CircuitProvableParams}.
+ *
+ * H2 is now computed as a flat Poseidon(6) hash — identical to the circuit-provable hash.
+ * This alias exists so that code referencing `H2FullParams` continues to compile.
+ *
+ * @public
+ */
+type H2FullParams = H2CircuitProvableParams;
+/**
+ * Computes the circuit-provable Poseidon(6) hash over the six core UTXO fields.
+ *
+ * ```
+ * H2 = Poseidon([amount, nullifier, userCommitment, addrLow, addrHigh, h2BlindingFactor])
+ * ```
+ *
+ * Input ordering must exactly match the Circom circuit's witness assignment.
+ *
+ * @see {@link H2CircuitProvableParams}
+ * @public
+ */
+type H2CircuitProvableHashFunction = (params: H2CircuitProvableParams) => Promise<Bn254FieldElement>;
+/**
+ * Computes the complete H2 UTXO leaf commitment as a flat Poseidon(6) hash.
+ *
+ * ```
+ * H2 = Poseidon([amount, nullifier, userCommitment, addrLow, addrHigh, h2BlindingFactor])
+ * ```
+ *
+ * The result is the leaf inserted into the mixer's indexed Merkle tree (IMT).
+ *
+ * @see {@link H2CircuitProvableParams}
+ * @public
+ */
+type H2HashFunction = (params: H2CircuitProvableParams) => Promise<Bn254FieldElement>;
+/**
+ * Bundle of H2-related hash generation functions for dependency injection.
+ *
+ * Obtain via `getUtxoCommitmentHashGenerator()`. Both functions share the same Poseidon instance.
+ *
+ * @see {@link H2CircuitProvableHashFunction}
+ * @see {@link H2HashFunction}
+ * @public
+ */
+interface H2GeneratorFns {
+    /** Computes the Poseidon(6) hash over the six core UTXO fields. */
+    generateCircuitProvableHash: H2CircuitProvableHashFunction;
+    /**
+     * Computes the complete H2 UTXO leaf — flat Poseidon(6), identical to
+     * `generateCircuitProvableHash`.
+     */
+    generateH2: H2HashFunction;
+}
+/**
+ * An asynchronous function that generates a Poseidon commitment to a keystream value.
+ *
+ * Keystream commitments allow a ZK proof to verify that a specific keystream value was
+ * used in a Poseidon encryption operation without revealing the keystream itself. They
+ * are a core component of Umbra's linker encryption scheme, which provides
+ * zero-knowledge proofs of correct encryption.
+ *
+ * @param keystream - The {@link Bn254FieldElement} keystream value to commit to (produced by
+ *   {@link PoseidonKeystreamGeneratorFunction}). This value is kept secret; only its
+ *   commitment is published.
+ * @param blindingFactor - A uniformly random {@link Bn254FieldElement} that hides the
+ *   keystream in the commitment. Must be generated using a CSPRNG.
+ * @returns A `Promise` resolving to a {@link Bn254FieldElement} — the keystream commitment.
+ *   This value is safe to publish on-chain or include in a ZK proof's public inputs.
+ *
+ * @remarks
+ * ## Commitment Formula
+ *
+ * ```
+ * commitment = Poseidon([keystream, blindingFactor])
+ * ```
+ *
+ * This is a standard Poseidon-based Pedersen-style commitment: the `blindingFactor`
+ * provides hiding (the commitment reveals no information about `keystream` to an
+ * observer who does not know `blindingFactor`), and the collision resistance of
+ * Poseidon provides binding (the committer cannot find two different `keystream`
+ * values that open to the same commitment).
+ *
+ * ## Role in the Linker Encryption Scheme
+ *
+ * When a sender encrypts a value for a recipient, the keystream used in the
+ * encryption is committed on-chain:
+ * 1. The sender generates `keystream = Poseidon([transactionViewingKey, counter, 2n])`.
+ * 2. The sender computes and publishes `commitment = Poseidon([keystream, blindingFactor])`.
+ * 3. A ZK proof verifies that:
+ *    - The ciphertext was correctly formed using this keystream.
+ *    - The keystream corresponds to the published commitment.
+ *
+ * This binds the encryption to the commitment without revealing the keystream or
+ * the transaction viewing key.
+ *
+ * @example
+ * ```typescript
+ * import { getKeystreamCommitmentGenerator } from "@umbra/sdk";
+ *
+ * const commitmentGenerator: KeystreamCommitmentFunction =
+ *   getKeystreamCommitmentGenerator();
+ *
+ * // Generate a keystream for counter 0
+ * const keystreamMap = await keystreamGenerator([counter0], transactionViewingKey);
+ * const keystream = keystreamMap.get(counter0)!;
+ *
+ * // Generate a random blinding factor (must use CSPRNG in production)
+ * const blindingFactor: Bn254FieldElement = secureRandomFieldElement();
+ *
+ * // Commit to the keystream
+ * const commitment = await commitmentGenerator(keystream, blindingFactor);
+ * // commitment: Bn254FieldElement — safe to publish on-chain or in a ZK public input
+ * ```
+ *
+ * @see {@link PoseidonKeystreamGeneratorFunction} for the function that produces keystreams
+ * @see {@link PoseidonEncryptorFunction} for the encryption function whose keystream is committed
+ * @public
+ */
+type KeystreamCommitmentFunction = (keystream: Bn254FieldElement, blindingFactor: Bn254FieldElement) => Promise<Bn254FieldElement>;
+
+/**
+ * User Commitment Interfaces
+ *
+ * This module defines TypeScript function type interfaces for user commitment
+ * generation used in the Umbra privacy protocol.
+ *
+ * ## Overview
+ *
+ * User commitments are cryptographic hashes that bind a user's identity to their
+ * on-chain account without revealing the underlying keys. The commitment is
+ * computed as a depth-2 Merkle tree root using Poseidon hashing, a hash function
+ * specifically designed to be efficient inside zero-knowledge circuits.
+ *
+ * ## Tree Structure
+ *
+ * The commitment is computed as:
+ * ```
+ * left  = Poseidon(masterViewingKey, mvkBlindingFactor)
+ * right = Poseidon(poseidonPrivateKey, poseidonPrivateKeyBlindingFactor)
+ * root  = Poseidon(left, right)
+ * ```
+ *
+ * ## Security Properties
+ *
+ * - The commitment is hiding (reveals nothing about the underlying inputs)
+ * - The commitment is binding (cannot be opened to different input values)
+ * - Poseidon is ZK-friendly, enabling efficient on-chain and off-circuit verification
+ *
+ * @packageDocumentation
+ * @module interfaces/cryptography/commitment
+ */
+
+/**
+ * Function type for generating user commitments.
+ *
+ * Computes a depth-2 Merkle tree root from four BN254 field elements using
+ * Poseidon hashing. The four inputs are grouped into two leaf nodes:
+ *
+ * - The left leaf commits to the master viewing key and its blinding factor.
+ * - The right leaf commits to the Poseidon private key and its blinding factor.
+ * - The root is the Poseidon hash of the two leaves.
+ *
+ * This function type is returned by {@link getUserCommitmentGeneratorFunction}
+ * and is the primary interface consumers depend on when computing commitments.
+ *
+ * @param masterViewingKey - The user's master viewing key, a BN254 field element
+ *   derived from the user's wallet signature. This key governs decryption of all
+ *   confidential balances belonging to the user.
+ * @param mvkBlindingFactor - A random BN254 field element used to blind the
+ *   master viewing key inside the left leaf, ensuring the leaf hides the key
+ *   from observers who only see the commitment.
+ * @param poseidonPrivateKey - The user's Poseidon private key, a BN254 field
+ *   element used within ZK proof computations. This key is distinct from the
+ *   master viewing key and governs UTXO claim operations.
+ * @param poseidonPrivateKeyBlindingFactor - A random BN254 field element used
+ *   to blind the Poseidon private key inside the right leaf.
+ * @returns A `Promise` resolving to a {@link Bn254FieldElement} representing
+ *   the Merkle root commitment. This value is stored on-chain inside the
+ *   `EncryptedUserAccount`.
+ *
+ * @remarks
+ * ## On-Chain Usage
+ *
+ * The user commitment is stored in the `EncryptedUserAccount` and is
+ * used to:
+ * - Bind the user's identity to their on-chain account without revealing keys
+ * - Enable on-chain verification of key ownership during claim operations
+ * - Support privacy-preserving balance proofs where the circuit checks the
+ *   commitment opening as a precondition for spending
+ *
+ * ## Blinding Factor Freshness
+ *
+ * The blinding factors MUST be sampled freshly from a cryptographically secure
+ * random source for each new commitment. Reusing blinding factors across
+ * commitments may allow an adversary to correlate commitments and deduce key
+ * material.
+ *
+ * ## Security Properties
+ *
+ * - Hiding: the commitment reveals nothing about its four inputs
+ * - Binding: it is computationally infeasible to open the commitment to
+ *   different input values under the Poseidon collision-resistance assumption
+ * - ZK-friendliness: Poseidon has low multiplicative complexity, making
+ *   commitments cheap to verify inside Groth16 circuits
+ *
+ * @example
+ * ```typescript
+ * import { getUserCommitmentGeneratorFunction } from "./index";
+ *
+ * const generateCommitment = getUserCommitmentGeneratorFunction();
+ *
+ * const commitment = await generateCommitment(
+ *   masterViewingKey,
+ *   mvkBlindingFactor,
+ *   poseidonPrivateKey,
+ *   poseidonPrivateKeyBlindingFactor,
+ * );
+ *
+ * // Store `commitment` in the EncryptedUserAccount on-chain
+ * ```
+ *
+ * @see {@link getUserCommitmentGeneratorFunction} for the factory that produces
+ *   instances of this function type
+ * @see {@link UserCommitmentGeneratorDeps} for optional dependency injection
+ * @public
+ */
+type UserCommitmentGeneratorFunction = (masterViewingKey: Bn254FieldElement, mvkBlindingFactor: Bn254FieldElement, poseidonPrivateKey: Bn254FieldElement, poseidonPrivateKeyBlindingFactor: Bn254FieldElement) => Promise<Bn254FieldElement>;
+/**
+ * Optional dependency injection bag for the user commitment generator.
+ *
+ * Allows callers to substitute the default Poseidon hasher with a custom
+ * implementation. This is useful in two scenarios:
+ *
+ * - **Testing**: inject a deterministic or mock hasher to make tests
+ *   reproducible without relying on the default WASM-backed implementation.
+ * - **Performance**: inject a pre-warmed hasher instance to avoid the
+ *   per-call initialisation cost of {@link getPoseidonHasher}.
+ *
+ * If the `hasher` field is omitted or `undefined`, the factory falls back to
+ * the default singleton returned by `getPoseidonHasher()`.
+ *
+ * @example
+ * ```typescript
+ * import { getUserCommitmentGeneratorFunction } from "./index";
+ * import type { UserCommitmentGeneratorDeps } from "./interfaces";
+ *
+ * // Inject a custom hasher for testing
+ * const deps: UserCommitmentGeneratorDeps = { hasher: mockPoseidonHasher };
+ * const generateCommitment = getUserCommitmentGeneratorFunction(deps);
+ * ```
+ *
+ * @see {@link getUserCommitmentGeneratorFunction} for the factory that consumes
+ *   this interface
+ * @see {@link PoseidonHashFunction} for the hasher contract
+ * @public
+ */
+interface UserCommitmentGeneratorDeps {
+    /**
+     * Custom Poseidon hash function to use when generating commitments.
+     *
+     * If not provided, the factory uses the default implementation returned by
+     * `getPoseidonHasher()`. Supplying a custom hasher also causes the factory
+     * to maintain a separate cache entry keyed on the hasher reference, so
+     * different hasher instances produce isolated generator functions.
+     *
+     * @defaultValue `getPoseidonHasher()` — the default WASM-backed Poseidon
+     *   hasher over the BN254 scalar field
+     */
+    readonly hasher?: PoseidonHashFunction;
+}
+
+/**
+ * External Cryptography Dependency Interfaces
+ *
+ * This module defines interface types for external cryptographic functions
+ * that are used by the SDK. These interfaces allow dependency injection
+ * for testing and customization.
+ *
+ * @module interfaces/cryptography/external
+ */
+
+/**
+ * KMAC256 (Keccak Message Authentication Code) function interface.
+ *
+ * KMAC256 is a keyed hash function based on Keccak that provides
+ * both authentication and domain separation capabilities.
+ *
+ * @param key - The key (customization string) as bytes
+ * @param message - The message to authenticate
+ * @param opts - Options object with output length
+ * @returns The KMAC256 output as a Uint8Array
+ *
+ * @remarks
+ * The default implementation uses `kmac256` from `@noble/hashes/sha3-addons`.
+ *
+ * @example
+ * ```typescript
+ * import { kmac256 } from "@noble/hashes/sha3-addons";
+ *
+ * const myKmac: Kmac256Function = (key, message, opts) =>
+ *     kmac256(key, message, opts);
+ * ```
+ */
+type Kmac256Function = (key: Uint8Array, message: Uint8Array, options: {
+    dkLen: number;
+    personalization?: Uint8Array;
+}) => Uint8Array;
+/**
+ * X25519 shared secret derivation function interface.
+ *
+ * This function computes the X25519 Diffie-Hellman shared secret from
+ * a private key and a public key.
+ *
+ * @param privateKey - The X25519 private key (32 bytes)
+ * @param publicKey - The X25519 public key of the counterparty (32 bytes)
+ * @returns The shared secret as a Uint8Array (32 bytes)
+ *
+ * @remarks
+ * The default implementation uses `x25519.getSharedSecret` from `@noble/curves/ed25519`.
+ *
+ * @example
+ * ```typescript
+ * import { x25519 } from "@noble/curves/ed25519";
+ *
+ * const myGetSharedSecret: X25519GetSharedSecretFunction =
+ *     (privateKey, publicKey) => x25519.getSharedSecret(privateKey, publicKey);
+ * ```
+ */
+type X25519GetSharedSecretFunction = (privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array;
+/**
+ * Random nonce generator function interface.
+ *
+ * This function generates a cryptographically secure random nonce
+ * for use in encryption operations.
+ *
+ * @returns A random RcEncryptionNonce (128-bit value)
+ *
+ * @remarks
+ * The default implementation uses `generateRandomNonce` from the SDK utilities.
+ *
+ * @example
+ * ```typescript
+ * import { generateRandomNonce } from "@umbra/sdk";
+ *
+ * const myGenerator: RandomNonceGeneratorFunction = () => generateRandomNonce();
+ * ```
+ */
+type RandomNonceGeneratorFunction = () => RcEncryptionNonce;
+
+/**
+ * Key Generator Function Types
+ *
+ * This module defines function types (generator contracts) for all cryptographic
+ * key generation operations in the Umbra key derivation system. Each type
+ * specifies the signature that a conforming generator implementation must expose.
+ *
+ * @remarks
+ * ## Design Philosophy
+ *
+ * All key generators follow a dependency-injection (DI) pattern:
+ * - **Factory functions** (in `index.ts`) accept a client and optional deps and
+ *   return a generator function of one of the types defined here.
+ * - **Generator function types** (this file) define the contract: parameter names,
+ *   types, and the Promise-based return value.
+ *
+ * This separation allows components to depend on the abstract generator type
+ * without coupling to a concrete implementation, enabling easy testing via
+ * mock generators and flexibility to swap cryptographic backends.
+ *
+ * ## Key Hierarchy and Generator Relationships
+ *
+ * ```
+ * MasterSeed (64 bytes — root secret)
+ *     │
+ *     ├── [MasterSeedGeneratorFunction]         — generates from entropy
+ *     ├── [EphemeralMasterSeedDeriverFunction] — generates per-offset ephemeral seed
+ *     │
+ *     ├── [MasterViewingKeyDeriverFunction]           — KMAC256 → 252-bit BN254 element
+ *     ├── [MasterViewingKeyBlindingFactorDeriverFunction] — KMAC256 → BN254 element
+ *     │
+ *     ├── [PoseidonPrivateKeyDeriverFunction]         — KMAC256 → BN254 element
+ *     ├── [PoseidonBlindingFactorDeriverFunction]     — KMAC256 → BN254 element
+ *     │
+ *     ├── [Curve25519KeypairGeneratorFunction]   — UserAccountX25519 keypair
+ *     ├── [MintX25519KeypairDeriverFunction]   — per-(mint, offset) keypair
+ *     │
+ *     └── MVK → Poseidon hash chain → time-scoped viewing keys
+ *           [MintViewingKeyDeriverFunction]
+ *           [YearlyViewingKeyGeneratorFunction]
+ *           [MonthlyViewingKeyGeneratorFunction]
+ *           [DailyViewingKeyGeneratorFunction]
+ *           [HourlyViewingKeyGeneratorFunction]
+ *           [MinuteViewingKeyGeneratorFunction]
+ *           [SecondViewingKeyGeneratorFunction]
+ * ```
+ *
+ * @packageDocumentation
+ * @public
+ *
+ * @module interfaces/cryptography/key-generator
+ */
+
+/**
+ * Options accepted by viewing key generator functions that use Poseidon hashing.
+ *
+ * @remarks
+ * Viewing key derivation below the MVK level (mint, yearly, monthly, etc.) uses
+ * the Poseidon hash function defined over the BN254 scalar field. This options
+ * bag allows callers to inject a custom Poseidon implementation — useful for
+ * testing with a mock hasher or for using a hardware-accelerated backend.
+ *
+ * If the `hasher` field is omitted, implementations MUST fall back to the
+ * default `getPoseidonHasher()` implementation from the Poseidon module.
+ *
+ * @example
+ * ```typescript
+ * const generator = getMintViewingKeyDeriver({ client });
+ * // Inject a test-double hasher for deterministic unit tests
+ * const mintKey = await generator(usdcMint, { hasher: mockPoseidonHasher });
+ * ```
+ *
+ * @see {@link MintViewingKeyDeriverFunction}
+ * @see {@link YearlyViewingKeyGeneratorFunction}
+ * @public
+ */
+interface ViewingKeyGeneratorOptions {
+    /**
+     * Optional custom Poseidon hasher function.
+     *
+     * @remarks
+     * If omitted, implementations use the default `getPoseidonHasher()`.
+     * The hasher must accept an array of BN254 field elements and return
+     * a single BN254 field element that is the Poseidon hash output.
+     *
+     * @readonly
+     */
+    readonly hasher?: PoseidonHashFunction;
+}
+/**
+ * Generates a new master seed from high-entropy input.
+ *
+ * @remarks
+ * The master seed is the root of the Umbra key derivation hierarchy. Implementations
+ * MUST source entropy from a cryptographically secure random number generator
+ * (CSPRNG) and hash it with Keccak-512 to produce the 64-byte master seed.
+ *
+ * Pre-conditions:
+ * - The runtime environment MUST provide a CSPRNG (e.g., `crypto.getRandomValues`).
+ *
+ * Post-conditions:
+ * - The returned `MasterSeed` is exactly 64 bytes.
+ * - The seed has at least 256 bits of effective entropy.
+ *
+ * @returns A Promise resolving to a 64-byte MasterSeed
+ *
+ * @see {@link MasterSeed}
+ * @public
+ */
+type MasterSeedGeneratorFunction = () => Promise<MasterSeed>;
+/**
+ * Generates a deterministic ephemeral master seed from a U256 offset index.
+ *
+ * @remarks
+ * Ephemeral seeds are used to derive single-use key sub-hierarchies for forward
+ * secrecy. Each offset produces an independent seed via KMAC256 keyed by the
+ * long-lived master seed. This ensures:
+ * - Two different offsets always produce different ephemeral seeds.
+ * - The same offset always produces the same ephemeral seed (deterministic).
+ * - Knowledge of an ephemeral seed does not reveal the master seed.
+ *
+ * ## Algorithm
+ *
+ * Uses the internal pseudorandom U512 generator with domain separator:
+ * `"Ephemeral Seed - {offset}"` where `offset` is formatted as a decimal string.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - The returned value is exactly 64 bytes.
+ * - Distinct offsets produce computationally independent outputs.
+ *
+ * @param offset - A U256 value used as the derivation offset (typically a generation index)
+ * @returns A Promise resolving to a 64-byte MasterSeed usable for ephemeral key derivation
+ *
+ * @example
+ * ```typescript
+ * import { EphemeralMasterSeedDeriverFunction } from "@umbra/sdk";
+ *
+ * const generator: EphemeralMasterSeedDeriverFunction = getGenerator(client);
+ *
+ * // Generate ephemeral seeds with different offsets
+ * const seed0 = await generator(0n as U256);
+ * const seed1 = await generator(1n as U256);
+ * const seed42 = await generator(42n as U256);
+ *
+ * // Use ephemeral seed for single-use key derivation; discard after use
+ * ```
+ *
+ * @see {@link MasterSeed}
+ * @public
+ */
+type EphemeralMasterSeedDeriverFunction = (offset: U256) => Promise<MasterSeed>;
+/**
+ * Generates the master viewing key (MVK) from the client's master seed.
+ *
+ * @remarks
+ * The master viewing key is the root of the read-only key tree. Sharing the MVK
+ * allows a recipient to view ALL of the user's transactions across all tokens
+ * and all time periods, without gaining any spending capability.
+ *
+ * ## Algorithm
+ *
+ * 1. Compute `KMAC256(key="Umbra Privacy - MasterViewingKey - {offset}", msg=masterSeed, dkLen=32)`
+ *    using the version-aware personalization string from the client.
+ * 2. Interpret the 32-byte output as a big-endian unsigned integer.
+ * 3. Mask to 252 bits: `value = value & (2^252 - 1)`.
+ * 4. Assert `value < BN254_FIELD_PRIME`.
+ *
+ * The 252-bit constraint ensures compatibility with ZK circuits that perform
+ * range checks on BN254 field element inputs.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - The client's offset for the master viewing key MUST be set.
+ *
+ * Post-conditions:
+ * - The returned value is a BN254 field element strictly less than 2^252.
+ *
+ * @returns A Promise resolving to a MasterViewingKey (BN254 field element < 2^252)
+ *
+ * @example
+ * ```typescript
+ * import { getMasterViewingKeyDeriver } from "@umbra/sdk";
+ *
+ * const generator = getMasterViewingKeyDeriver({ masterSeed });
+ * const mvk = await generator();
+ *
+ * // The MVK is constrained to 252 bits for ZK circuit compatibility
+ * console.assert(mvk < 2n ** 252n);
+ * ```
+ *
+ * @see {@link MasterViewingKey}
+ * @see {@link MintViewingKeyDeriverFunction}
+ * @public
+ */
+type MasterViewingKeyDeriverFunction = () => Promise<MasterViewingKey>;
+/**
+ * Generates a blinding factor for the master viewing key commitment.
+ *
+ * @remarks
+ * The blinding factor is used to conceal the master viewing key in a Pedersen
+ * commitment: `commitment = g^mvk * h^blindingFactor`. This allows the user to
+ * prove knowledge of the MVK in a ZK proof without revealing it directly.
+ *
+ * ## Algorithm
+ *
+ * Derives a BN254 field element via KMAC256 with the domain separator
+ * `"UmbraPrivacy - Master Viewing Key Blinding Factor"` keyed by the master seed.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a uniformly distributed BN254 field element in [0, BN254_FIELD_PRIME).
+ * - Deterministic: same master seed always produces the same blinding factor.
+ *
+ * @returns A Promise resolving to a BN254 field element for use as the blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getMasterViewingKeyBlindingFactorDeriver({ client });
+ * const blindingFactor = await generator();
+ *
+ * // Use in Pedersen commitment: commitment = g^mvk * h^blindingFactor
+ * ```
+ *
+ * @see {@link MasterViewingKey}
+ * @public
+ */
+type MasterViewingKeyBlindingFactorDeriverFunction = () => Promise<Bn254FieldElement>;
+/**
+ * Generates the Poseidon private key for the user's master seed.
+ *
+ * @remarks
+ * The Poseidon private key is used as the secret key input to the Poseidon
+ * cipher (`PoseidonEnc`) for encrypting balances and UTXO fields. Each master
+ * seed is associated with exactly one Poseidon private key.
+ *
+ * ## Algorithm
+ *
+ * Derives a BN254 field element via KMAC256 with the domain separator
+ * `"PoseidonPrivateKey - {offset}"` where `offset` comes from the client's
+ * `offsets.poseidonPrivateKey` field.
+ *
+ * ## Security Properties
+ *
+ * - Compromise of this key allows decryption of Poseidon-encrypted data.
+ * - Different offsets produce independent Poseidon private keys.
+ * - Knowledge of this key does NOT reveal the master seed or other keys.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a uniformly distributed BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @returns A Promise resolving to a BN254 field element for use as the Poseidon private key
+ *
+ * @example
+ * ```typescript
+ * const generator = getPoseidonPrivateKeyDeriver({ client });
+ * const privateKey = await generator();
+ *
+ * // Use as key for Poseidon encryption
+ * const ciphertext = await poseidonEncrypt(plaintext, privateKey);
+ * ```
+ *
+ * @see {@link PoseidonBlindingFactorDeriverFunction}
+ * @public
+ */
+type PoseidonPrivateKeyDeriverFunction = () => Promise<Bn254FieldElement>;
+/**
+ * Generates the Poseidon blinding factor for the user's master seed.
+ *
+ * @remarks
+ * Blinding factors add randomness to Poseidon-based commitments while preserving
+ * the ability to prove knowledge of the committed value in a ZK circuit.
+ * Each master seed is associated with exactly one Poseidon blinding factor.
+ *
+ * ## Algorithm
+ *
+ * Derives a BN254 field element via KMAC256 with the domain separator
+ * `"PoseidonBlindingFactor"` keyed by the master seed.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a uniformly distributed BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @returns A Promise resolving to a BN254 field element for use as the blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getPoseidonBlindingFactorDeriver({ client });
+ * const blindingFactor = await generator();
+ *
+ * // Use in Poseidon commitment: commitment = Poseidon([value, blindingFactor])
+ * const commitment = await poseidonHash([value, blindingFactor]);
+ * ```
+ *
+ * @see {@link PoseidonPrivateKeyDeriverFunction}
+ * @public
+ */
+type PoseidonBlindingFactorDeriverFunction = () => Promise<Bn254FieldElement>;
+/**
+ * Generates a mint-specific viewing key from the master viewing key and a mint address.
+ *
+ * @remarks
+ * A mint viewing key grants read-only visibility into all transactions involving
+ * a specific SPL token (identified by its mint address) without revealing
+ * transactions of other tokens. It is the first Poseidon-hash step below the MVK.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * ```
+ *
+ * Where:
+ * - `MVK` is the master viewing key (derived internally from the client's master seed)
+ * - `mintAddressLow` = bytes 0–15 of the base58-decoded mint address as a little-endian U128
+ * - `mintAddressHigh` = bytes 16–31 of the base58-decoded mint address as a little-endian U128
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `mint` MUST be a valid Solana address (32-byte base58-encoded string).
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ * - Deterministic: same MVK and same mint always produce the same mint viewing key.
+ *
+ * @param mint - The Solana SPL token mint address
+ * @param options - Optional configuration, including a custom Poseidon hasher
+ * @returns A Promise resolving to a MintViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { getMintViewingKeyDeriver } from "@umbra/sdk";
+ * import { address } from "@solana/kit";
+ *
+ * const generator = getMintViewingKeyDeriver({ masterViewingKey });
+ * const usdcMint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+ *
+ * const mintKey = await generator(usdcMint);
+ *
+ * // Share with auditor for USDC-specific review only
+ * shareViewingKey(auditor, mintKey);
+ * ```
+ *
+ * @see {@link MintViewingKey}
+ * @see {@link MasterViewingKey}
+ * @public
+ */
+type MintViewingKeyDeriverFunction = (mint: Address, options?: ViewingKeyGeneratorOptions) => Promise<MintViewingKey>;
+/**
+ * Generates a yearly viewing key for a specific calendar year and token.
+ *
+ * @remarks
+ * A yearly viewing key scopes visibility to a single calendar year for a specific
+ * token mint. It is derived by extending the mint viewing key with the year value.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)    // YearlyViewingKey
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `year` MUST be a valid bigint in the `Year` branded type range.
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a YearlyViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear } from "@umbra/sdk";
+ *
+ * const generator = getYearlyViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * assertYear(year);
+ * const yearlyKey = await generator(usdcMint, year);
+ *
+ * // Share with tax authority for 2024 USDC audit
+ * shareViewingKey(taxAuthority, yearlyKey);
+ * ```
+ *
+ * @see {@link YearlyViewingKey}
+ * @see {@link MintViewingKeyDeriverFunction}
+ * @public
+ */
+type YearlyViewingKeyGeneratorFunction = (mint: Address, year: Year, options?: ViewingKeyGeneratorOptions) => Promise<YearlyViewingKey>;
+/**
+ * Generates a monthly viewing key for a specific calendar month and token.
+ *
+ * @remarks
+ * A monthly viewing key scopes visibility to a single calendar month (within a
+ * specific year) for a specific token mint. It extends the yearly viewing key
+ * with the month value.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)
+ * h2 = Poseidon(h1, month)    // MonthlyViewingKey
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `year` and `month` MUST be in their respective branded type ranges.
+ * - `month` MUST be in [1, 12].
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param month - The calendar month, 1–12 (e.g., `6n as Month` for June)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a MonthlyViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear, assertMonth } from "@umbra/sdk";
+ *
+ * const generator = getMonthlyViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * const month = 6n;
+ * assertYear(year);
+ * assertMonth(month);
+ * const monthlyKey = await generator(usdcMint, year, month); // June 2024
+ *
+ * // Share with accountant for monthly review
+ * shareViewingKey(accountant, monthlyKey);
+ * ```
+ *
+ * @see {@link MonthlyViewingKey}
+ * @see {@link YearlyViewingKeyGeneratorFunction}
+ * @public
+ */
+type MonthlyViewingKeyGeneratorFunction = (mint: Address, year: Year, month: Month, options?: ViewingKeyGeneratorOptions) => Promise<MonthlyViewingKey>;
+/**
+ * Generates a daily viewing key for a specific calendar day and token.
+ *
+ * @remarks
+ * A daily viewing key scopes visibility to a single calendar day (within a
+ * specific year and month) for a specific token mint. It extends the monthly
+ * viewing key with the day value.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)
+ * h2 = Poseidon(h1, month)
+ * h3 = Poseidon(h2, day)    // DailyViewingKey
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `year`, `month`, and `day` MUST be in their respective branded type ranges.
+ * - `day` MUST be in [1, 31].
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param month - The calendar month, 1–12 (e.g., `6n as Month`)
+ * @param day - The calendar day, 1–31 (e.g., `15n as Day`)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a DailyViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear, assertMonth, assertDay } from "@umbra/sdk";
+ *
+ * const generator = getDailyViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * const month = 6n;
+ * const day = 15n;
+ * assertYear(year);
+ * assertMonth(month);
+ * assertDay(day);
+ * const dailyKey = await generator(usdcMint, year, month, day); // June 15, 2024
+ *
+ * // Share for investigating a specific date
+ * shareViewingKey(investigator, dailyKey);
+ * ```
+ *
+ * @see {@link DailyViewingKey}
+ * @see {@link MonthlyViewingKeyGeneratorFunction}
+ * @public
+ */
+type DailyViewingKeyGeneratorFunction = (mint: Address, year: Year, month: Month, day: Day, options?: ViewingKeyGeneratorOptions) => Promise<DailyViewingKey>;
+/**
+ * Generates an hourly viewing key for a specific hour and token.
+ *
+ * @remarks
+ * An hourly viewing key scopes visibility to a single hour (within a specific
+ * year, month, and day) for a specific token mint. It extends the daily viewing
+ * key with the hour value (0–23).
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)
+ * h2 = Poseidon(h1, month)
+ * h3 = Poseidon(h2, day)
+ * h4 = Poseidon(h3, hour)    // HourlyViewingKey
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - All time parameters MUST be in their respective branded type ranges.
+ * - `hour` MUST be in [0, 23].
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param month - The calendar month, 1–12
+ * @param day - The calendar day, 1–31
+ * @param hour - The hour of the day, 0–23 (e.g., `14n as Hour` for 2 PM UTC)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a HourlyViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear, assertMonth, assertDay, assertHour } from "@umbra/sdk";
+ *
+ * const generator = getHourlyViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * const month = 6n;
+ * const day = 15n;
+ * const hour = 14n;
+ * assertYear(year);
+ * assertMonth(month);
+ * assertDay(day);
+ * assertHour(hour);
+ * const hourlyKey = await generator(usdcMint, year, month, day, hour); // June 15, 2024 2PM
+ *
+ * // Share for high-frequency trading audit within this hour
+ * shareViewingKey(auditor, hourlyKey);
+ * ```
+ *
+ * @see {@link HourlyViewingKey}
+ * @see {@link DailyViewingKeyGeneratorFunction}
+ * @public
+ */
+type HourlyViewingKeyGeneratorFunction = (mint: Address, year: Year, month: Month, day: Day, hour: Hour, options?: ViewingKeyGeneratorOptions) => Promise<HourlyViewingKey>;
+/**
+ * Generates a minute viewing key for a specific minute and token.
+ *
+ * @remarks
+ * A minute viewing key scopes visibility to a single minute within a specific
+ * hour, day, month, and year for a specific token mint. It extends the hourly
+ * viewing key with the minute value (0–59).
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)
+ * h2 = Poseidon(h1, month)
+ * h3 = Poseidon(h2, day)
+ * h4 = Poseidon(h3, hour)
+ * h5 = Poseidon(h4, minute)    // MinuteViewingKey
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - All time parameters MUST be in their respective branded type ranges.
+ * - `minute` MUST be in [0, 59].
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param month - The calendar month, 1–12
+ * @param day - The calendar day, 1–31
+ * @param hour - The hour of the day, 0–23
+ * @param minute - The minute within the hour, 0–59 (e.g., `30n as Minute`)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a MinuteViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear, assertMonth, assertDay, assertHour, assertMinute } from "@umbra/sdk";
+ *
+ * const generator = getMinuteViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * const month = 6n;
+ * const day = 15n;
+ * const hour = 14n;
+ * const minute = 30n;
+ * assertYear(year);
+ * assertMonth(month);
+ * assertDay(day);
+ * assertHour(hour);
+ * assertMinute(minute);
+ * const minuteKey = await generator(usdcMint, year, month, day, hour, minute);
+ *
+ * // Share for precise forensic analysis of a specific minute
+ * shareViewingKey(forensicAnalyst, minuteKey);
+ * ```
+ *
+ * @see {@link MinuteViewingKey}
+ * @see {@link HourlyViewingKeyGeneratorFunction}
+ * @public
+ */
+type MinuteViewingKeyGeneratorFunction = (mint: Address, year: Year, month: Month, day: Day, hour: Hour, minute: Minute, options?: ViewingKeyGeneratorOptions) => Promise<MinuteViewingKey>;
+/**
+ * Generates a second viewing key for a specific second and token.
+ *
+ * @remarks
+ * The second viewing key is the finest-granularity key in the Umbra viewing
+ * key hierarchy, scoping visibility to a single second within a specific minute.
+ * It is the leaf node of the Poseidon hash chain.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * h0 = Poseidon(MVK, mintAddressLow, mintAddressHigh)
+ * h1 = Poseidon(h0, year)
+ * h2 = Poseidon(h1, month)
+ * h3 = Poseidon(h2, day)
+ * h4 = Poseidon(h3, hour)
+ * h5 = Poseidon(h4, minute)
+ * TVK = Poseidon(h5, second)    // SecondViewingKey (Terminal Viewing Key)
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - All time parameters MUST be in their respective branded type ranges.
+ * - `second` MUST be in [0, 59].
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element in [0, BN254_FIELD_PRIME).
+ * - No further time-scoped keys can be derived from a SecondViewingKey.
+ *
+ * @param mint - The Solana mint address of the token
+ * @param year - The calendar year (e.g., `2024n as Year`)
+ * @param month - The calendar month, 1–12
+ * @param day - The calendar day, 1–31
+ * @param hour - The hour of the day, 0–23
+ * @param minute - The minute within the hour, 0–59
+ * @param second - The second within the minute, 0–59 (e.g., `45n as Second`)
+ * @param options - Optional configuration including custom Poseidon hasher
+ * @returns A Promise resolving to a SecondViewingKey (BN254 field element)
+ *
+ * @example
+ * ```typescript
+ * import { assertYear, assertMonth, assertDay, assertHour, assertMinute, assertSecond } from "@umbra/sdk";
+ *
+ * const generator = getSecondViewingKeyDeriver({ masterViewingKey });
+ *
+ * const year = 2024n;
+ * const month = 6n;
+ * const day = 15n;
+ * const hour = 14n;
+ * const minute = 30n;
+ * const second = 45n;
+ * assertYear(year);
+ * assertMonth(month);
+ * assertDay(day);
+ * assertHour(hour);
+ * assertMinute(minute);
+ * assertSecond(second);
+ * const secondKey = await generator(usdcMint, year, month, day, hour, minute, second);
+ *
+ * // Share for investigating a specific transaction
+ * shareViewingKey(investigator, secondKey);
+ * ```
+ *
+ * @see {@link SecondViewingKey}
+ * @see {@link MinuteViewingKeyGeneratorFunction}
+ * @public
+ */
+type SecondViewingKeyGeneratorFunction = (mint: Address, year: Year, month: Month, day: Day, hour: Hour, minute: Minute, second: Second, options?: ViewingKeyGeneratorOptions) => Promise<SecondViewingKey>;
+/**
+ * Generates a complete Curve25519 keypair (Ed25519 + X25519) from the master seed.
+ *
+ * @remarks
+ * This function derives both an Ed25519 (Edwards curve) signing keypair and
+ * an X25519 (Montgomery curve) ECDH keypair from the master seed using a single
+ * deterministic derivation pipeline. The two keypairs share the same Curve25519
+ * foundation and are used together in token account registration.
+ *
+ * ## Derivation Pipeline
+ *
+ * 1. Derive 64 bytes via `KMAC256(key="Umbra Privacy - {domain} - {offset}", msg=masterSeed, dkLen=64)`
+ * 2. **Ed25519 Keypair**:
+ *    - Use first 32 bytes as the Ed25519 seed
+ *    - Derive Ed25519 public key: `ed25519.getPublicKey(seed)`
+ * 3. **X25519 Keypair**:
+ *    - Hash seed with SHA-512 → 64 bytes
+ *    - Clamp first 32 bytes per RFC 8032 §5.1.5
+ *    - 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
+ * - **Forward Secure**: Different offsets produce independent keypairs
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a valid `Curve25519KeypairResult` with both Ed25519 and X25519 keypairs.
+ *
+ * @returns A Promise resolving to a Curve25519KeypairResult with ed25519Keypair and x25519Keypair
+ *
+ * @example
+ * ```typescript
+ * import { getUserAccountX25519KeypairDeriver } from "@umbra/sdk";
+ *
+ * const generator = getUserAccountX25519KeypairDeriver({ client });
+ * const result = 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 Curve25519KeypairResult}
+ * @see {@link MintX25519KeypairDeriverFunction}
+ * @public
+ */
+type Curve25519KeypairGeneratorFunction = () => Promise<Curve25519KeypairResult>;
+/**
+ * Generates a per-mint Curve25519 keypair (Ed25519 + X25519) for a given mint.
+ *
+ * @remarks
+ * Used for `reencrypt_shared` operations — produces a unique keypair for each
+ * mint address. The offset is taken from `client.offsets.mintX25519PrivateKey`
+ * at construction time, consistent with all other key types.
+ *
+ * ## Algorithm
+ *
+ * Domain separator: `"MintX25519Keypair - {mint} - {client.offsets.mintX25519PrivateKey}"`
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `mint` MUST be a valid Solana address.
+ *
+ * Post-conditions:
+ * - Returns a valid `Curve25519KeypairResult`.
+ * - Different mints produce independent keypairs.
+ * - Different `client.offsets.mintX25519PrivateKey` values produce independent keypairs.
+ *
+ * @param mint - The Solana SPL token mint address
+ * @returns A Promise resolving to a Curve25519KeypairResult
+ *
+ * @example
+ * ```typescript
+ * const generator = getMintX25519KeypairDeriver({ client });
+ * const usdcKeypair = await generator(usdcMint);
+ * const solKeypair = await generator(solMint);
+ * // usdcKeypair and solKeypair are independent due to different mints
+ * ```
+ *
+ * @see {@link Curve25519KeypairGeneratorFunction}
+ * @see {@link Curve25519KeypairResult}
+ * @public
+ */
+type MintX25519KeypairDeriverFunction = (mint: Address) => Promise<Curve25519KeypairResult>;
+/**
+ * Generates a 512-bit pseudorandom value from the master seed and a domain separator.
+ *
+ * @remarks
+ * This is the base primitive for all KMAC256-based key derivation in Umbra.
+ * It produces 512 bits of pseudorandom output from the master seed using
+ * a single KMAC256 call with a domain-separated key. The 512-bit output size
+ * ensures negligible bias when reducing to BN254 or Curve25519 field elements.
+ *
+ * ## Algorithm
+ *
+ * 1. Construct the KMAC key string: `"Umbra Privacy - {domainSeparator}"`
+ * 2. Compute `KMAC256(key, masterSeed, dkLen=64, personalization=versionString)`
+ * 3. Return the 64-byte big-endian output as `U512BeBytes`
+ *
+ * ## Security Properties
+ *
+ * - **Domain Separation**: Different domain separators produce computationally
+ *   independent outputs, even with the same master seed.
+ * - **Deterministic**: Same domain separator and master seed always produce
+ *   the same output.
+ * - **Pseudorandom**: Output is computationally indistinguishable from random
+ *   under standard assumptions about KMAC256.
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns exactly 64 bytes encoded as big-endian `U512BeBytes`.
+ *
+ * @param domainSeparator - A string that uniquely identifies the derivation context
+ * @returns A Promise resolving to a 512-bit big-endian byte array (U512BeBytes)
+ *
+ * @example
+ * ```typescript
+ * import { PseudorandomU512DeriverFunction } from "@umbra/sdk";
+ *
+ * const generator: PseudorandomU512DeriverFunction = getGenerator(client);
+ *
+ * // Generate different 512-bit values using domain separation
+ * const value1 = await generator("MasterViewingKey");
+ * const value2 = await generator("EphemeralSeed-12345");
+ *
+ * // Each domain separator produces a completely independent output
+ * ```
+ *
+ * @see {@link MasterSeedBasedFieldElementDeriverFunction}
+ * @public
+ */
+type PseudorandomU512DeriverFunction = (domainSeparator: string) => Promise<U512BeBytes>;
+/**
+ * Derives a BN254 field element from the master seed using domain separation.
+ *
+ * @remarks
+ * This function builds on top of `PseudorandomU512DeriverFunction` to reduce
+ * the 512-bit pseudorandom output to a uniformly distributed BN254 field element.
+ * The reduction uses constant-time modular arithmetic to prevent timing side-channels.
+ *
+ * ## Algorithm
+ *
+ * 1. Generate 512-bit pseudorandom value via KMAC256 with `domainSeparator`
+ * 2. Reduce to BN254 field element using constant-time modular reduction:
+ *    `fieldElement = u512Value mod BN254_FIELD_PRIME`
+ *
+ * ## Security Properties
+ *
+ * - **Domain Separation**: Different domain separators produce independent outputs
+ * - **Deterministic**: Same inputs always produce the same field element
+ * - **Uniform Distribution**: Output is uniformly distributed in [0, BN254_FIELD_PRIME)
+ *   with bias 2^(-512 + log2(BN254_FIELD_PRIME)) ≈ 2^{-256}, which is negligible
+ * - **Constant-Time**: Reduction is performed without data-dependent branches
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a bigint in [0, BN254_FIELD_PRIME).
+ *
+ * @param domainSeparator - A string that uniquely identifies the derivation context
+ * @returns A Promise resolving to a BN254 field element in range [0, BN254_FIELD_PRIME)
+ *
+ * @example
+ * ```typescript
+ * import { getMasterSeedBasedFieldElementDeriver } from "@umbra/sdk";
+ *
+ * const deriver = getMasterSeedBasedFieldElementDeriver({ client });
+ *
+ * // Derive different keys using domain separation
+ * const viewingKey = await deriver("MasterViewingKey");
+ * const encryptionKey = await deriver("EncryptionKey");
+ * const nullifierKey = await deriver("NullifierKey");
+ *
+ * // Each domain separator produces a completely independent output
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Deriving time-scoped keys
+ * const yearlyKey = await deriver("YearlyViewingKey-2024");
+ * const monthlyKey = await deriver("MonthlyViewingKey-2024-01");
+ * const dailyKey = await deriver("DailyViewingKey-2024-01-15");
+ * ```
+ *
+ * @see {@link PseudorandomU512DeriverFunction}
+ * @public
+ */
+type MasterSeedBasedFieldElementDeriverFunction = (domainSeparator: string) => Promise<Bn254FieldElement>;
+
+/**
+ * Generates a BN254 field element blinding factor for Rescue encryption commitments.
+ *
+ * @remarks
+ * Rescue encryption commitment blinding factors are used to commit to ciphertexts
+ * and plaintexts in UTXO creation ZK proofs. The derivation binds an offset
+ * (typically derived from the generation index) to ensure unique blinding factors
+ * for each UTXO creation event.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"RescueEncryptionCommitmentBlindingFactor - {totalOffset}"`
+ *    where `totalOffset = client.offsets.rescueCommitmentBlindingFactor + offset`
+ * 2. Generate 512-bit pseudorandom value using KMAC256
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a BN254 field element uniformly distributed in [0, BN254_FIELD_PRIME).
+ * - Different offsets produce independent blinding factors.
+ *
+ * @param offset - A U256 offset for unique derivation context (e.g., generation index)
+ * @returns A Promise resolving to a BN254 field element blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getRescueCommitmentBlindingFactorDeriver({ client });
+ * const blindingFactor = await generator(0n as U256);
+ * ```
+ *
+ * @see {@link EphemeralRescueCommitmentBlindingFactorDeriverFunction}
+ * @public
+ */
+type RescueCommitmentBlindingFactorDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a Curve25519 field element random factor for polynomial commitment evaluation.
+ *
+ * @remarks
+ * Random factors for polynomial commitments are Curve25519 field elements used
+ * in Kate-style commitment evaluation to hide the committed polynomial from
+ * a verifier who knows only the commitment, not the coefficients.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"RandomFactorForPolynomialCommitment - {totalOffset}"`
+ *    where `totalOffset = client.offsets.randomCommitmentFactor + offset`
+ * 2. Generate 512-bit pseudorandom value using KMAC256
+ * 3. Sample Curve25519 field element using constant-time reduction
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ *
+ * Post-conditions:
+ * - Returns a Curve25519 field element uniformly distributed in [0, curve25519_order).
+ *
+ * @param offset - A U256 offset for unique derivation context
+ * @returns A Promise resolving to a Curve25519 field element random factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getPolynomialCommitmentFactorDeriver({ client });
+ * const randomFactor = await generator(0n as U256);
+ * ```
+ *
+ * @see {@link RescueCommitmentBlindingFactorDeriverFunction}
+ * @public
+ */
+type PolynomialCommitmentFactorDeriverFunction = (offset: U256) => Promise<Curve25519FieldElement>;
+/**
+ * Generates an ephemeral master viewing key for sender-claimable UTXOs.
+ *
+ * @remarks
+ * Ephemeral UTXO master viewing keys are BN254 field elements used as the
+ * "MVK" component of UTXOs that the sender can reclaim. Each generation index
+ * produces an independent ephemeral MVK, ensuring that different UTXOs cannot
+ * be linked through a shared key.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO MasterViewingKey - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)` with version personalization
+ * 3. Sample BN254 field element and mask to 252 bits (consistent with main MVK)
+ *
+ * ## Security Properties
+ *
+ * - **Keyed Derivation**: Only the holder of the master seed can derive this value
+ * - **Domain Separated**: Different offsets produce independent ephemeral MVKs
+ * - **Deterministic**: Same client and offset always produce the same key
+ *
+ * @param offset - A U256 offset for unique derivation (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element for the ephemeral MVK
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoMasterViewingKeyDeriver({ client });
+ * const ephemeralMvk = await generator(generationIndex);
+ * ```
+ *
+ * @see {@link EphemeralUtxoMasterViewingKeyBlindingFactorDeriverFunction}
+ * @public
+ */
+type EphemeralUtxoMasterViewingKeyDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a blinding factor for the ephemeral MVK commitment.
+ *
+ * @remarks
+ * Pairs with `EphemeralUtxoMasterViewingKeyDeriverFunction` to produce the
+ * blinding factor for the Pedersen commitment to the ephemeral MVK.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO MasterViewingKeyBlindingFactor - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)`
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * @param offset - A U256 offset for unique derivation context (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoMasterViewingKeyBlindingFactorDeriver({ client });
+ * const ephemeralMvkBf = await generator(generationIndex);
+ * ```
+ *
+ * @see {@link EphemeralUtxoMasterViewingKeyDeriverFunction}
+ * @public
+ */
+type EphemeralUtxoMasterViewingKeyBlindingFactorDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates an ephemeral Poseidon private key for sender-claimable UTXOs.
+ *
+ * @remarks
+ * Ephemeral UTXO Poseidon private keys serve as the secret key for the
+ * Poseidon cipher used to encrypt UTXO fields in sender-claimable UTXOs.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO PoseidonPrivateKey - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)`
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * @param offset - A U256 offset for unique derivation context (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element for the ephemeral Poseidon private key
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoPoseidonPrivateKeyDeriver({ client });
+ * const ephemeralPk = await generator(generationIndex);
+ * ```
+ *
+ * @see {@link EphemeralUtxoPoseidonPrivateKeyBlindingFactorDeriverFunction}
+ * @public
+ */
+type EphemeralUtxoPoseidonPrivateKeyDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a blinding factor for the ephemeral Poseidon private key commitment.
+ *
+ * @remarks
+ * Pairs with `EphemeralUtxoPoseidonPrivateKeyDeriverFunction` to produce the
+ * blinding factor for the Pedersen commitment to the ephemeral Poseidon private key.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO PoseidonPrivateKeyBlindingFactor - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)`
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * @param offset - A U256 offset for unique derivation context (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoPoseidonPrivateKeyBlindingFactorDeriver({ client });
+ * const ephemeralPkBf = await generator(generationIndex);
+ * ```
+ *
+ * @see {@link EphemeralUtxoPoseidonPrivateKeyDeriverFunction}
+ * @public
+ */
+type EphemeralUtxoPoseidonPrivateKeyBlindingFactorDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a nullifier for an ephemeral UTXO to prevent double-spending.
+ *
+ * @remarks
+ * Nullifiers are BN254 field elements that uniquely identify a UTXO spend event.
+ * When a UTXO is claimed, its nullifier is burned in an on-chain Indexed Merkle
+ * Tree (treap); any subsequent claim with the same nullifier is rejected.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO Nullifier - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)`
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * ## Security Properties
+ *
+ * - **Unique per UTXO**: Each generation index produces a distinct nullifier
+ * - **Keyed Derivation**: Only the master seed holder can compute the nullifier
+ * - **Deterministic**: Same client and offset always produce the same nullifier
+ *
+ * @param offset - A U256 offset for unique derivation context (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element nullifier
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoNullifierDeriver({ client });
+ * const nullifier = await generator(generationIndex);
+ * // nullifier is submitted on-chain when claiming the UTXO
+ * ```
+ *
+ * @public
+ */
+type EphemeralUtxoNullifierDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates an H2 random secret (blinding factor) for ephemeral UTXO creation.
+ *
+ * @remarks
+ * The H2 random secret is a privacy-preserving blinding factor included in the
+ * H2 hash of a UTXO. It prevents the verifier from learning the other UTXO
+ * fields (amount, nullifier, commitment, destination) through the H2 commitment.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - Ephemeral UTXO H2RandomSecret - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)`
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * ## Usage in H2 Hash
+ *
+ * The H2 hash is computed as:
+ * ```
+ * H2 = Poseidon([amount, nullifier, userCommitment, destAddrLow, destAddrHigh, h2RandomSecret])
+ * ```
+ *
+ * @param offset - A U256 offset for unique derivation context (typically the generation index)
+ * @returns A Promise resolving to a BN254 field element random secret
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralUtxoH2RandomSecretDeriver({ client });
+ * const h2BlindingFactor = await generator(generationIndex);
+ * ```
+ *
+ * @see {@link EphemeralUtxoNullifierDeriverFunction}
+ * @public
+ */
+type EphemeralUtxoH2RandomSecretDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a blinding factor for Poseidon keystream commitments.
+ *
+ * @remarks
+ * Poseidon keystream blinding factors are used to commit to individual keystream
+ * values in Poseidon cipher operations. Binding the blinding factor to both the
+ * keystream value and an offset ensures that each keystream position has a unique,
+ * independently derived blinding factor.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator: `"Umbra Privacy - PoseidonKeystreamBlindingFactor - {offset}"`
+ * 2. Concatenate `masterSeed` (64 bytes) || `keystream` (32 bytes, LE) || `offset` (32 bytes, LE)
+ * 3. Compute `KMAC256(key=domainSeparator, data=concatenated, dkLen=64)`
+ * 4. Sample BN254 field element using constant-time reduction
+ *
+ * ## Usage in Keystream Commitments
+ *
+ * ```
+ * commitment = Poseidon([keystream, blindingFactor])
+ * ```
+ *
+ * Pre-conditions:
+ * - The client MUST have a valid master seed loaded.
+ * - `keystream` MUST be a valid BN254 field element.
+ *
+ * Post-conditions:
+ * - Different `(keystream, offset)` pairs produce independent blinding factors.
+ *
+ * @param keystream - The Poseidon keystream value (BN254 field element) to bind to
+ * @param offset - A U256 offset for additional domain separation (e.g., keystream counter index)
+ * @returns A Promise resolving to a BN254 field element blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getPoseidonKeystreamBlindingFactorDeriver({ client });
+ *
+ * // Generate blinding factors for each keystream position
+ * const bf0 = await generator(keystream0, 0n as U256);
+ * const bf1 = await generator(keystream1, 1n as U256);
+ * const bf2 = await generator(keystream2, 2n as U256);
+ * ```
+ *
+ * @public
+ */
+type PoseidonKeystreamBlindingFactorDeriverFunction = (keystream: Bn254FieldElement, offset: U256) => Promise<Bn254FieldElement>;
+/**
+ * Generates a blinding factor for ephemeral Rescue encryption commitments in UTXO creation.
+ *
+ * @remarks
+ * Ephemeral Rescue encryption commitment blinding factors bind ciphertexts,
+ * plaintexts, keys, nonce, and public key components into a zero-knowledge
+ * verifiable commitment. This variant uses keyed derivation (master seed as
+ * the KMAC key) rather than the offset-combined approach of the non-ephemeral variant.
+ *
+ * ## Algorithm
+ *
+ * 1. Build domain separator:
+ *    `"Umbra Privacy - Ephemeral RescueEncryptionCommitmentBlindingFactor - {offset}"`
+ * 2. Compute `KMAC256(domainSeparator, masterSeed, dkLen=64)` with version personalization
+ * 3. Sample BN254 field element using constant-time reduction
+ *
+ * ## Security Properties
+ *
+ * - **Keyed Derivation**: Uses the client's master seed as the KMAC message
+ * - **Domain Separated**: Different offsets produce independent values
+ * - **ZK-Friendly**: Output is a valid BN254 field element for circuit use
+ *
+ * @param offset - A U256 offset for unique derivation context (typically `expandedModifiedGenerationIndexU256`)
+ * @returns A Promise resolving to a BN254 field element blinding factor
+ *
+ * @example
+ * ```typescript
+ * const generator = getEphemeralRescueCommitmentBlindingFactorDeriver({ client });
+ * const blindingFactor = await generator(expandedModifiedGenerationIndexU256);
+ * ```
+ *
+ * @see {@link RescueCommitmentBlindingFactorDeriverFunction}
+ * @public
+ */
+type EphemeralRescueCommitmentBlindingFactorDeriverFunction = (offset: U256) => Promise<Bn254FieldElement>;
+
+/**
+ * Rescue Cipher Interface Types
+ *
+ * This module defines the function type signatures for Rescue cipher operations
+ * at the high-level key-exchange layer. These types abstract over the private-key
+ * binding so that callers can work with pre-configured encryptors, decryptors,
+ * and key generators without repeatedly supplying raw key material.
+ *
+ * ## Design Philosophy
+ *
+ * Each factory function in `./index.ts` (e.g. `getRescueEncryptorFromPrivateKey`)
+ * accepts a private key once and returns a function matching one of the types
+ * defined here. Callers then use the returned function repeatedly without
+ * re-exposing the private key. This minimises the surface area over which raw
+ * key bytes are visible in calling code.
+ *
+ * ## Contract for All Implementors
+ *
+ * Implementations of these function types **must**:
+ * 1. Validate all typed inputs at the boundary (assert branded types).
+ * 2. Not cache cipher instances or shared secrets internally.
+ * 3. Create a fresh cipher instance on each invocation to limit how long
+ *    sensitive material remains in heap memory.
+ * 4. Return values in the expected branded types with appropriate assertions.
+ *
+ * ## Nonce Security
+ *
+ * The Rescue cipher uses counter mode (CTR): the keystream is generated by
+ * encrypting successive counter values with the derived key. The nonce
+ * determines the initial counter state. **Nonce reuse with the same key is
+ * catastrophic** — it allows an attacker to cancel the keystream and recover
+ * the XOR (or field-sum) of the two plaintexts. Always use
+ * {@link RcEncryptorFunction} (which generates random nonces) unless you have
+ * a specific reason to manage nonces externally.
+ *
+ * @packageDocumentation
+ * @module interfaces/cryptography/rescue-cipher
+ * @public
+ */
+
+/**
+ * Encryption function type with automatic nonce generation.
+ *
+ * A pre-configured encryptor that generates a fresh random nonce for each
+ * encryption call. The nonce is returned alongside the ciphertexts because it
+ * is required for decryption and must be stored by the caller.
+ *
+ * @param plaintext - Array of {@link RcPlaintext} field elements to encrypt.
+ *   Each element must be a valid Curve25519 field element (< 2^255 - 19).
+ *   The array may contain any number of elements; each is encrypted at a
+ *   successive counter position in the Rescue CTR stream.
+ * @returns A promise resolving to an object containing:
+ *   - `ciphertexts` — one {@link RcCiphertext} per plaintext element.
+ *   - `nonce` — the 128-bit {@link RcEncryptionNonce} used for this encryption.
+ *     Store this alongside the ciphertexts; it is public and does not need
+ *     to be kept secret, but it must be unique per (key, nonce) pair.
+ *
+ * @remarks
+ * ## Implementation Contract
+ *
+ * - A **fresh cryptographically random nonce** is generated for each call.
+ * - The returned `ciphertexts` array has the same length as `plaintext`.
+ * - All returned values are valid branded types (asserted before return).
+ * - No cipher instance, shared secret, or nonce is retained after the
+ *   call completes.
+ *
+ * ## Nonce Properties
+ *
+ * Nonces generated by the default implementation are 128-bit values from
+ * `generateRandomNonce()` in `../../common/arcium`. With 128-bit nonces,
+ * the birthday-bound collision probability over N calls is approximately
+ * N²/2^128, which is negligible for any practical N.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const encryptor: RcEncryptorFunction = getRescueEncryptorFromPrivateKey(
+ *   myPrivateKey,
+ *   { umbraX25519PublicKey: networkConfig.mxePubkey },
+ * );
+ *
+ * const plaintexts: RcPlaintext[] = [balance, auxiliaryData];
+ * const { ciphertexts, nonce } = await encryptor(plaintexts);
+ *
+ * // Both ciphertexts and nonce must be stored for later decryption:
+ * await persistEncryptedBalance({ ciphertexts, nonce });
+ * ```
+ *
+ * @see {@link RcEncryptorWithNonceFunction} — variant requiring explicit nonce
+ * @see {@link getRescueEncryptorFromPrivateKey} — factory that produces this function type
+ */
+type RcEncryptorFunction = (plaintext: readonly RcPlaintext[]) => Promise<{
+    ciphertexts: RcCiphertext[];
+    nonce: RcEncryptionNonce;
+}>;
+/**
+ * Encryption function type with explicit nonce parameter.
+ *
+ * A pre-configured encryptor where the caller supplies the nonce on each call.
+ * This variant is appropriate when nonces are managed externally (e.g. as a
+ * counter maintained by the caller) or when deterministic encryption is required
+ * (e.g. for generating test vectors with a fixed nonce).
+ *
+ * @param plaintext - Array of {@link RcPlaintext} field elements to encrypt.
+ *   Each element must be a valid Curve25519 field element (< 2^255 - 19).
+ * @param nonce - The 128-bit nonce to use for this encryption. Must be a valid
+ *   {@link RcEncryptionNonce} (bigint in [0, 2^128 - 1]).
+ *   **CRITICAL**: This nonce MUST be unique for each encryption call with the
+ *   same underlying key. See the nonce security note in the module documentation.
+ * @returns A promise resolving to an array of {@link RcCiphertext} values,
+ *   one per input plaintext element.
+ *
+ * @remarks
+ * ## Implementation Contract
+ *
+ * - `nonce` is validated via {@link assertRcEncryptionNonce} before use.
+ * - The returned array has the same length as `plaintext`.
+ * - All returned values are valid {@link RcCiphertext} branded types.
+ * - No state is retained after the call completes.
+ *
+ * ## When to Prefer This Over `RcEncryptorFunction`
+ *
+ * - When the same nonce must be used across multiple related encryption calls
+ *   (e.g. encrypting a batch of UTXOs that share a nonce for on-chain space
+ *   efficiency).
+ * - When reproducing exact ciphertexts from a known (plaintext, nonce, key)
+ *   triple for testing or recovery purposes.
+ * - When the nonce is derived from a protocol-level counter rather than random
+ *   sampling (e.g. the transaction sequence number).
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const encryptor: RcEncryptorWithNonceFunction = getRescueEncryptorWithNonceFromPrivateKey(
+ *   myPrivateKey,
+ *   { umbraX25519PublicKey: networkConfig.mxePubkey },
+ * );
+ *
+ * // Caller-managed nonce (must be unique per key):
+ * const nonce = generateRandomNonce();
+ * const plaintexts: RcPlaintext[] = [balance];
+ * const ciphertexts = await encryptor(plaintexts, nonce);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Deterministic test encryption (NEVER reuse in production with different plaintexts):
+ * const fixedNonce = 1n as RcEncryptionNonce;
+ * const ciphertexts = await encryptor(plaintexts, fixedNonce);
+ * ```
+ *
+ * @see {@link RcEncryptorFunction} — preferred variant with automatic nonce generation
+ * @see {@link getRescueEncryptorWithNonceFromPrivateKey} — factory that produces this function type
+ */
+type RcEncryptorWithNonceFunction = (plaintext: readonly RcPlaintext[], nonce: RcEncryptionNonce) => Promise<RcCiphertext[]>;
+/**
+ * Decryption function type using a nonce.
+ *
+ * A pre-configured decryptor that recovers the original plaintext elements from
+ * Rescue ciphertexts using the same nonce that was used during encryption.
+ *
+ * @param ciphertext - Array of {@link RcCiphertext} values to decrypt.
+ *   Must be the ciphertexts produced by a matching encryptor with the same
+ *   private key and public key. Each element must be a valid Curve25519 field
+ *   element.
+ * @param nonce - The {@link RcEncryptionNonce} used during encryption.
+ *   Must exactly match the nonce stored alongside the ciphertexts; using a
+ *   different nonce will silently produce incorrect (garbage) plaintexts.
+ * @returns A promise resolving to an array of {@link RcPlaintext} values,
+ *   one per input ciphertext element.
+ *
+ * @remarks
+ * ## Implementation Contract
+ *
+ * - All `ciphertext` elements are validated via {@link assertRcCiphertext} before use.
+ * - `nonce` is validated via {@link assertRcEncryptionNonce} before use.
+ * - The returned array has the same length as `ciphertext`.
+ * - All returned values are valid {@link RcPlaintext} branded types (asserted).
+ * - No state is retained after the call completes.
+ *
+ * ## No Authentication
+ *
+ * Unlike AES-256-GCM, the Rescue cipher in CTR mode does not include an
+ * authentication tag. This function will **not** detect:
+ * - A wrong nonce (will silently return garbage).
+ * - Tampered ciphertexts (will silently return incorrect plaintexts).
+ *
+ * Authentication is provided at the protocol level by the Arcium MPC computation
+ * signature. For client-side usage, callers should cross-validate the decrypted
+ * values against the on-chain commitments (e.g. Poseidon hash of the balance).
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const decryptor: RcDecryptorFunction = getRescueDecryptorFromPrivateKey(
+ *   myPrivateKey,
+ *   { umbraX25519PublicKey: networkConfig.mxePubkey },
+ * );
+ *
+ * // Load stored ciphertexts and the nonce used during encryption:
+ * const { ciphertexts, nonce } = await loadEncryptedBalance(accountId);
+ * const plaintexts = await decryptor(ciphertexts, nonce);
+ * const [balance] = plaintexts;
+ * ```
+ *
+ * @see {@link RcEncryptorFunction} — paired encryption function type
+ * @see {@link getRescueDecryptorFromPrivateKey} — factory that produces this function type
+ */
+type RcDecryptorFunction = (ciphertext: readonly RcCiphertext[], nonce: RcEncryptionNonce) => Promise<RcPlaintext[]>;
+/**
+ * Key generation function type for counter-based encryption schemes.
+ *
+ * Generates symmetric encryption keys for specified counter positions by
+ * encrypting zero-value plaintexts at those positions. The resulting keys can
+ * be used as independent per-counter symmetric keys in protocols that require
+ * key separation between different token account positions.
+ *
+ * @param counters - Array of counter values identifying the key positions to
+ *   generate. Each must be a valid {@link RcCounter} (non-negative Curve25519
+ *   field element). Duplicates are allowed; the map will contain a single entry
+ *   per unique counter value.
+ * @param nonce - The 128-bit {@link RcEncryptionNonce} to use for the internal
+ *   encryption that generates the keys. Must be unique per (key, nonce) pair.
+ * @returns A promise resolving to a `ReadonlyMap<RcCounter, RcKey>` mapping
+ *   each requested counter to its derived {@link RcKey}. Counters not present
+ *   in the `counters` input are not included in the map.
+ *
+ * @remarks
+ * ## Key Generation Algorithm
+ *
+ * The key for counter `c` is defined as:
+ * ```
+ * key[c] = Rescue-CTR-Encrypt(key=sharedSecret, nonce=nonce, plaintext=0n)[c]
+ * ```
+ *
+ * That is, a zero-value plaintext is placed at each position from 0 to
+ * `max(counters)` and all positions are encrypted in a single CTR invocation.
+ * Only the positions in `counters` are returned.
+ *
+ * ## Security Properties
+ *
+ * - Keys generated with the same (private key, public key, nonce) are deterministic.
+ * - Keys generated at different counter positions are computationally independent
+ *   (due to the CTR mode keystream).
+ * - The nonce must be unique per key-generation session; reusing the nonce with
+ *   the same key pair produces the same keys (which may be intentional for
+ *   deterministic recovery, but is a security risk if used with different plaintexts).
+ *
+ * ## Implementation Notes
+ *
+ * - Counter values are compared as `bigint` to avoid precision loss.
+ * - The function internally allocates `max(counters) + 1` zero plaintexts, so
+ *   very large sparse counter sets (e.g. `[0n, 2^128]`) would be impractical.
+ *   Callers should use small, dense counter ranges.
+ *
+ * ## Use Cases
+ *
+ * - Pre-computing AES-equivalent stream-cipher keys for batch operations.
+ * - Deriving per-UTXO keys for counter-mode encryption schemes.
+ * - Key derivation for specific token account generation indices.
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const keyGenerator: RcKeyGeneratorFunction = getRescueKeyGeneratorFromPrivateKey(
+ *   myPrivateKey,
+ *   { umbraX25519PublicKey: networkConfig.mxePubkey },
+ * );
+ *
+ * const counters: RcCounter[] = [0n, 1n, 5n];
+ * const nonce = generateRandomNonce();
+ * const keysMap = await keyGenerator(counters, nonce);
+ *
+ * const key0 = keysMap.get(0n); // RcKey — key for counter 0
+ * const key5 = keysMap.get(5n); // RcKey — key for counter 5
+ * // keysMap.get(2n) === undefined — counter 2 was not requested
+ * ```
+ *
+ * @see {@link RcEncryptorWithNonceFunction} — used internally to generate the keys
+ * @see {@link getRescueKeyGeneratorFromPrivateKey} — factory that produces this function type
+ */
+type RcKeyGeneratorFunction = (counters: readonly RcCounter[], nonce: RcEncryptionNonce) => Promise<ReadonlyMap<RcCounter, RcKey>>;
+/**
+ * Rescue Cipher Internal Interfaces
+ *
+ * Type definitions and dependency injection interfaces for the Rescue-XLIX
+ * cipher and Rescue-Prime hash function. All types in this module are internal
+ * to the `rescue-cipher` package; consumers interact only with the public API
+ * exported from `index.ts`.
+ *
+ * ## Design Rationale
+ *
+ * The interfaces in this file serve two purposes:
+ *
+ * - **Abstraction**: `FieldArithmetic` decouples the cipher and hash logic from
+ *   any specific field implementation. The default production path uses the
+ *   SDK's `math/curve25519/field-arithmetic` module, but tests can substitute
+ *   alternative implementations (e.g., slow-but-correct reference versions).
+ *
+ * - **Compatibility**: `RescueCipherInstance` mirrors the shape of
+ *   `@arcium-hq/client`'s `RescueCipher` class, allowing the SDK to drop in
+ *   its own implementation without breaking callers that depend on that shape.
+ *
+ * ## Dependency Injection
+ *
+ * `RescueCipherDeps` and `RescuePrimeHashDeps` follow the SDK-wide convention
+ * of optional `*Deps` parameters on factory functions. Omitting them selects
+ * the production defaults. Providing them bypasses module-level caches, so
+ * tests can exercise the pure functional logic in isolation.
+ *
+ * @packageDocumentation
+ * @module crypto/rescue-cipher/interfaces
+ * @internal
+ */
+/**
+ * A stateful Rescue-XLIX cipher instance capable of encrypting and decrypting
+ * vectors of field elements in CTR (counter) mode.
+ *
+ * @remarks
+ * This interface is intentionally designed to be structurally compatible with
+ * the `RescueCipher` class from `@arcium-hq/client`, enabling the SDK to serve
+ * as a drop-in replacement without any upstream changes to callers.
+ *
+ * ## CTR Mode Overview
+ *
+ * Counter mode turns the Rescue-XLIX block cipher into a stream cipher:
+ *
+ * 1. A counter block `[nonce, blockIndex, 0, 0, 0]` is assembled for each
+ *    block of `BLOCK_SIZE = 5` plaintext elements.
+ * 2. The Rescue permutation is applied to the counter block to produce a
+ *    keystream block.
+ * 3. Each plaintext element is added (modulo p) to the corresponding keystream
+ *    element to produce ciphertext.
+ *
+ * Decryption is identical to encryption because field addition is its own
+ * inverse: `c - k ≡ p + k - k ≡ p` when the same keystream is generated.
+ *
+ * ## Key Material
+ *
+ * The cipher instance embeds a key schedule derived from the shared secret at
+ * construction time (see `createRescueCipherInstance` in `index.ts`). The key
+ * schedule consists of the intermediate states produced by running the Rescue
+ * permutation on the derived key, used as round keys.
+ *
+ * ## Security Notes
+ *
+ * - Nonces MUST be unique for every (key, nonce) pair. Nonce reuse under the
+ *   same key results in complete loss of confidentiality (two-time-pad attack).
+ * - Cipher instances are not cached; each call to `getRescueCipherInstance`
+ *   creates a fresh instance to limit key material lifetime in memory.
+ *
+ * @example
+ * ```typescript
+ * import { getRescueCipherInstance } from "./index";
+ *
+ * const sharedSecret = new Uint8Array(32).fill(0xab); // from X25519 ECDH
+ * const nonce = crypto.getRandomValues(new Uint8Array(16));
+ *
+ * const cipher = getRescueCipherInstance(sharedSecret);
+ *
+ * // Encrypt a vector of field elements
+ * const plaintext: bigint[] = [1n, 2n, 3n, 4n, 5n];
+ * const ciphertext = cipher.encrypt(plaintext, nonce);
+ * // ciphertext: number[][], each inner array is 32 bytes (LE field element)
+ *
+ * // Decrypt back
+ * const recovered = cipher.decrypt(ciphertext, nonce);
+ * // recovered: bigint[] === plaintext
+ * ```
+ *
+ * @see {@link RescueCipherDeps} — dependency injection for custom field arithmetic and KDF
+ * @see `getRescueCipherInstance` in `index.ts` — factory function that returns this instance
+ *
+ * @internal
+ */
+interface RescueCipherInstance {
+    /**
+     * Encrypts an array of field elements using Rescue-XLIX in CTR mode.
+     *
+     * @remarks
+     * Plaintext elements must be valid field elements: `0 <= x < p`.
+     * The nonce must be exactly `NONCE_BYTES = 16` bytes.
+     *
+     * The returned ciphertext is a parallel array of 32-byte little-endian
+     * serialisations of the encrypted field elements. The length of the returned
+     * array always equals `plaintext.length`.
+     *
+     * @param plaintext - Array of bigint field elements to encrypt; each must
+     *   satisfy `0 <= x < FIELD_PRIME`
+     * @param nonce - 16-byte unique nonce; must not be reused under the same key
+     * @returns Array of `number[]` where each inner array is a 32-byte
+     *   little-endian encoding of one ciphertext field element
+     *
+     * @throws `Error` if `nonce.length !== 16`
+     *
+     * @example
+     * ```typescript
+     * const nonce = crypto.getRandomValues(new Uint8Array(16));
+     * const plain = [0n, 1n, 2n];
+     * const cipher = getRescueCipherInstance(sharedSecret);
+     * const enc = cipher.encrypt(plain, nonce);
+     * // enc.length === 3, enc[0].length === 32
+     * ```
+     */
+    encrypt: (plaintext: bigint[], nonce: Uint8Array) => number[][];
+    /**
+     * Decrypts an array of 32-byte ciphertext elements using Rescue-XLIX in CTR mode.
+     *
+     * @remarks
+     * The nonce must be the same 16-byte value that was used during encryption.
+     * Each element of `ciphertext` must be exactly 32 bytes (one serialised
+     * field element in little-endian byte order).
+     *
+     * Decryption is structurally identical to encryption (CTR mode symmetry):
+     * the same keystream is generated and subtracted (mod p) from each
+     * ciphertext element.
+     *
+     * @param ciphertext - Array of `number[]`; each inner array must be exactly
+     *   32 bytes representing one little-endian field element
+     * @param nonce - The same 16-byte nonce used during encryption
+     * @returns Array of bigint plaintext field elements
+     *
+     * @throws `Error` if `nonce.length !== 16`
+     * @throws `Error` if any element of `ciphertext` does not have length 32
+     *
+     * @example
+     * ```typescript
+     * const plain = [10n, 20n, 30n];
+     * const nonce = crypto.getRandomValues(new Uint8Array(16));
+     * const enc = cipher.encrypt(plain, nonce);
+     * const dec = cipher.decrypt(enc, nonce);
+     * // dec deepEquals plain
+     * ```
+     */
+    decrypt: (ciphertext: number[][], nonce: Uint8Array) => bigint[];
+}
+/**
+ * Unified interface for finite field arithmetic over GF(p).
+ *
+ * @remarks
+ * This interface abstracts all modular arithmetic needed by the Rescue-XLIX
+ * permutation so that the cipher and hash implementations are independent of
+ * the specific underlying library. The production default binds this to the
+ * SDK's `math/curve25519/field-arithmetic` module, which targets the prime
+ * `p = 2^255 - 19`.
+ *
+ * Implementations must enforce that all returned values are in the canonical
+ * reduced range `[0, ORDER)`. In particular:
+ *
+ * - `create` must reduce any `bigint` into the field.
+ * - `add`, `sub`, `mul`, `pow` must all return values in `[0, ORDER)`.
+ * - `inv(0)` is undefined and implementations may throw or return 0.
+ *
+ * ## Compatibility
+ *
+ * The interface is intentionally aligned with the field accessor objects
+ * exposed by `@noble/curves` (which uses `ORDER`, `BYTES`, `ZERO`, `ONE`,
+ * `create`, `add`, `sub`, `mul`, `inv`, `pow`, `is0`), so that a `@noble`
+ * field can be adapted to this interface with minimal glue code.
+ *
+ * @example
+ * ```typescript
+ * import { getFieldArithmetic } from "./index";
+ *
+ * const F = getFieldArithmetic();
+ * const a = F.create(12345678901234567890n);
+ * const b = F.create(98765432109876543210n);
+ *
+ * const sum = F.add(a, b);      // (a + b) mod p
+ * const prod = F.mul(a, b);     // (a * b) mod p
+ * const inv = F.inv(a);         // a^(-1) mod p
+ * const pow5 = F.pow(a, 5n);    // a^5 mod p
+ * console.log(F.is0(F.sub(a, a))); // true
+ * ```
+ *
+ * @see {@link RescueCipherDeps} — inject a custom `FieldArithmetic` into the cipher
+ * @see {@link RescuePrimeHashDeps} — inject a custom `FieldArithmetic` into the hash
+ * @see `getFieldArithmetic` in `index.ts` — the default production implementation
+ *
+ * @internal
+ */
+interface FieldArithmetic {
+    /**
+     * The field modulus (prime characteristic p).
+     *
+     * @remarks
+     * For the production implementation this equals `FIELD_PRIME = 2^255 - 19`.
+     * All arithmetic results are in the range `[0, ORDER)`.
+     *
+     * @readonly
+     */
+    readonly ORDER: bigint;
+    /**
+     * Number of bytes required to represent one field element.
+     *
+     * @remarks
+     * For `p = 2^255 - 19`, this is 32 bytes (255 bits rounded up to the
+     * nearest byte boundary).
+     *
+     * @readonly
+     */
+    readonly BYTES: number;
+    /**
+     * Additive identity: 0 in GF(p).
+     *
+     * @readonly
+     */
+    readonly ZERO: bigint;
+    /**
+     * Multiplicative identity: 1 in GF(p).
+     *
+     * @readonly
+     */
+    readonly ONE: bigint;
+    /**
+     * Reduces an arbitrary bigint into the canonical field range `[0, ORDER)`.
+     *
+     * @param value - Any bigint, possibly negative or >= ORDER
+     * @returns `((value % ORDER) + ORDER) % ORDER`
+     */
+    create: (value: bigint) => bigint;
+    /**
+     * Field addition: `(a + b) mod p`.
+     *
+     * @param a - First operand; must be in `[0, ORDER)`
+     * @param b - Second operand; must be in `[0, ORDER)`
+     * @returns `(a + b) mod ORDER`, in `[0, ORDER)`
+     */
+    add: (a: bigint, b: bigint) => bigint;
+    /**
+     * Field subtraction: `(a - b) mod p`.
+     *
+     * @param a - Minuend; must be in `[0, ORDER)`
+     * @param b - Subtrahend; must be in `[0, ORDER)`
+     * @returns `(a - b + ORDER) mod ORDER`, in `[0, ORDER)`
+     */
+    sub: (a: bigint, b: bigint) => bigint;
+    /**
+     * Field multiplication: `(a * b) mod p`.
+     *
+     * @param a - First factor; must be in `[0, ORDER)`
+     * @param b - Second factor; must be in `[0, ORDER)`
+     * @returns `(a * b) mod ORDER`, in `[0, ORDER)`
+     */
+    mul: (a: bigint, b: bigint) => bigint;
+    /**
+     * Modular inverse: `a^(-1) mod p`.
+     *
+     * @remarks
+     * Typically computed via Fermat's little theorem as `a^(p-2) mod p`,
+     * which requires a full modular exponentiation. The result satisfies
+     * `mul(a, inv(a)) === ONE`.
+     *
+     * Behaviour for `a === 0` is undefined. The production implementation may
+     * return `0n` or throw.
+     *
+     * @param a - Operand; must be in `(0, ORDER)`
+     * @returns `a^(-1) mod ORDER`, in `[0, ORDER)`
+     */
+    inv: (a: bigint) => bigint;
+    /**
+     * Modular exponentiation: `a^exponent mod p`.
+     *
+     * @remarks
+     * Used for both the forward S-box (`x^ALPHA`) and the inverse S-box
+     * (`x^ALPHA_INVERSE`). The exponent may be up to 255 bits long.
+     *
+     * @param a - Base; must be in `[0, ORDER)`
+     * @param exponent - Non-negative exponent
+     * @returns `a^exponent mod ORDER`, in `[0, ORDER)`
+     */
+    pow: (a: bigint, exponent: bigint) => bigint;
+    /**
+     * Tests whether a field element is the additive identity (zero).
+     *
+     * @param a - Field element to test; must be in `[0, ORDER)`
+     * @returns `true` if and only if `a === 0n`
+     */
+    is0: (a: bigint) => boolean;
+}
+/**
+ * A function that applies the Rescue-XLIX permutation to a state vector in place.
+ *
+ * @remarks
+ * The Rescue-XLIX permutation maps a vector of `m` field elements to another
+ * vector of `m` field elements. It is a bijection (invertible map) used as the
+ * underlying primitive for both the cipher (in a key-dependent manner) and the
+ * hash sponge (in a key-independent manner).
+ *
+ * The state is passed as a flat `bigint[]` and the permuted state is returned
+ * as a new flat `bigint[]` of the same length. The original array is not mutated.
+ *
+ * In cipher mode: `m = BLOCK_SIZE = 5`, round keys are embedded in the closure.
+ * In hash mode:   `m = HASH_STATE_SIZE = 12`, round constants are public and fixed.
+ *
+ * @example
+ * ```typescript
+ * // Hash-mode permutation (internal usage)
+ * const permute: RescuePermuteFunction = createHashPermutationFunction(fieldArithmetic);
+ * const inputState = Array(12).fill(0n);
+ * const outputState = permute(inputState);
+ * // outputState.length === 12
+ * ```
+ *
+ * @see `createHashPermutationFunction` in `index.ts` — hash-mode factory
+ * @see `createRescueCipherInstance` in `index.ts` — cipher-mode factory (key-dependent)
+ *
+ * @internal
+ */
+type RescuePermuteFunction = (state: bigint[]) => bigint[];
+/**
+ * A function that computes the Rescue-Prime hash digest of a message.
+ *
+ * @remarks
+ * Rescue-Prime is a sponge hash built on the Rescue-XLIX permutation. The
+ * function accepts a message of arbitrary length (as field elements), applies
+ * multi-rate padding, absorbs blocks of `HASH_RATE = 7` elements per
+ * permutation call, then squeezes `HASH_DIGEST_LENGTH = 5` elements.
+ *
+ * ## Padding
+ *
+ * The message is padded with the "10*" scheme (a mandatory 1 bit followed by
+ * zeros to the next multiple of the rate):
+ * ```
+ * paddedMessage = [...message, 1n, 0n, ..., 0n]
+ * ```
+ * where padding brings `paddedMessage.length` to a multiple of `HASH_RATE`.
+ *
+ * ## Output
+ *
+ * The digest is exactly `HASH_DIGEST_LENGTH = 5` field elements
+ * (approximately 1275 bits total).
+ *
+ * @example
+ * ```typescript
+ * const hash = getRescuePrimeHashFunction();
+ * const digest = hash([1n, 2n, 3n]);
+ * // digest.length === 5, each element in [0, FIELD_PRIME)
+ * ```
+ *
+ * @see `getRescuePrimeHashFunction` in `index.ts` — public factory
+ * @see `createRescuePrimeHashFunction` in `index.ts` — implementation
+ * @see {@link RescuePrimeHashDeps} — optional dependency injection
+ *
+ * @internal
+ */
+type RescuePrimeHashFunction = (message: bigint[]) => bigint[];
+/**
+ * A function that derives a `BLOCK_SIZE`-element cipher key from a shared secret.
+ *
+ * @remarks
+ * The key derivation function (KDF) maps a raw 32-byte Diffie-Hellman output
+ * to a vector of `BLOCK_SIZE = 5` field elements suitable for use as a
+ * Rescue-XLIX cipher key.
+ *
+ * The default implementation (`deriveRescueCipherKey` in `index.ts`) follows
+ * NIST SP 800-56C Rev 2, Section 4, Option 1, using Rescue-Prime as the
+ * underlying hash:
+ * ```
+ * key = RescuePrimeHash([counter=1, secret_as_field_element, L=5])
+ * ```
+ *
+ * Custom implementations provided via `RescueCipherDeps.deriveKey` must
+ * return exactly `BLOCK_SIZE = 5` bigints in `[0, FIELD_PRIME)`.
+ *
+ * @example
+ * ```typescript
+ * // Custom test-only KDF that uses a fixed key
+ * const fixedKey: RescueKeyDerivationFunction = (_secret) =>
+ *   [1n, 2n, 3n, 4n, 5n];
+ *
+ * const cipher = getRescueCipherInstance(sharedSecret, { deriveKey: fixedKey });
+ * ```
+ *
+ * @see {@link RescueCipherDeps} — the deps interface that carries this function
+ * @see `deriveRescueCipherKey` in `index.ts` — the default production KDF
+ *
+ * @internal
+ */
+type RescueKeyDerivationFunction = (sharedSecret: Uint8Array) => bigint[];
+/**
+ * Optional dependency injection bag for `getRescueCipherInstance`.
+ *
+ * @remarks
+ * Both fields are optional. When omitted, the production defaults are used:
+ *
+ * - `getFieldArithmetic` defaults to the SDK's `math/curve25519/field-arithmetic`
+ *   adapter (the {@link FieldArithmetic} singleton returned by `getFieldArithmetic()`
+ *   in `index.ts`).
+ * - `deriveKey` defaults to the Rescue-Prime-based KDF (`deriveRescueCipherKey`
+ *   in `index.ts`) which follows NIST SP 800-56C Rev 2 Section 4.
+ *
+ * Providing custom deps bypasses the module-level caches, so each
+ * `getRescueCipherInstance` call with custom deps creates independent instances.
+ * This is intentional to facilitate test isolation and benchmarking.
+ *
+ * @example
+ * ```typescript
+ * // Test with a trivial field (not cryptographically secure)
+ * const testDeps: RescueCipherDeps = {
+ *   getFieldArithmetic: () => myTestFieldArithmetic,
+ *   deriveKey: (secret) => Array.from({ length: 5 }, (_, i) => BigInt(i)),
+ * };
+ *
+ * const cipher = getRescueCipherInstance(sharedSecret, testDeps);
+ * ```
+ *
+ * @see `getRescueCipherInstance` in `index.ts` — the factory that consumes this interface
+ * @see {@link FieldArithmetic} — the field arithmetic interface to implement
+ * @see {@link RescueKeyDerivationFunction} — the KDF function signature
+ *
+ * @internal
+ */
+interface RescueCipherDeps {
+    /**
+     * Factory that returns a custom {@link FieldArithmetic} implementation.
+     *
+     * @remarks
+     * When provided, this overrides the default SDK field arithmetic adapter.
+     * The returned implementation must operate over the same prime field
+     * (`p = 2^255 - 19`) as the round constants and MDS matrices.
+     *
+     * @defaultValue `getFieldArithmetic` from `index.ts` (SDK Curve25519 adapter)
+     */
+    readonly getFieldArithmetic?: () => FieldArithmetic;
+    /**
+     * Custom key derivation function that maps a 32-byte secret to a key vector.
+     *
+     * @remarks
+     * When provided, this replaces the NIST SP 800-56C Rescue-Prime KDF entirely.
+     * The function must return exactly `BLOCK_SIZE = 5` bigints in `[0, FIELD_PRIME)`.
+     *
+     * @defaultValue `deriveRescueCipherKey` from `index.ts`
+     */
+    readonly deriveKey?: RescueKeyDerivationFunction;
+}
+/**
+ * Optional dependency injection bag for `getRescuePrimeHashFunction`.
+ *
+ * @remarks
+ * Provides a hook to substitute a custom {@link FieldArithmetic} implementation
+ * when constructing the Rescue-Prime sponge hash. This is useful for:
+ *
+ * - Unit testing with a small or mock field to verify the sponge logic
+ *   independently of the field arithmetic library.
+ * - Benchmarking alternative field implementations.
+ *
+ * When the `getFieldArithmetic` field is omitted, the production default
+ * (the SDK's `math/curve25519` adapter) is used and the result is cached
+ * as a module-level singleton.
+ *
+ * @example
+ * ```typescript
+ * // Inject a custom field for testing
+ * const hashFn = getRescuePrimeHashFunction({
+ *   getFieldArithmetic: () => myReferenceFieldImpl,
+ * });
+ * const digest = hashFn([1n, 2n, 3n]);
+ * ```
+ *
+ * @see `getRescuePrimeHashFunction` in `index.ts` — the factory that consumes this interface
+ * @see {@link FieldArithmetic} — the interface to implement
+ *
+ * @internal
+ */
+interface RescuePrimeHashDeps {
+    /**
+     * Factory that returns a custom {@link FieldArithmetic} implementation.
+     *
+     * @remarks
+     * When provided, this bypasses the module-level `cachedRescuePrimeHashFunction`
+     * cache and creates a fresh hash function instance backed by the custom field.
+     *
+     * @defaultValue `getFieldArithmetic` from `index.ts` (SDK Curve25519 adapter)
+     */
+    readonly getFieldArithmetic?: () => FieldArithmetic;
+}
+
+export type { RescuePrimeHashDeps as $, MinuteViewingKeyGeneratorFunction as A, ModuloPowCurve25519Function as B, Curve25519KeypairGeneratorFunction as C, DailyViewingKeyGeneratorFunction as D, EphemeralMasterSeedDeriverFunction as E, FiatShamirChallengeGeneratorFunction as F, MonthlyViewingKeyGeneratorFunction as G, H2CircuitProvableHashFunction as H, PolynomialEvaluatorDeps as I, PoseidonDecryptorFunction as J, KeystreamCommitmentFunction as K, PoseidonEncryptorFunction as L, MintX25519KeypairDeriverFunction as M, PoseidonHashFunction as N, PoseidonKeystreamBlindingFactorDeriverFunction as O, PoseidonPrivateKeyDeriverFunction as P, PoseidonKeystreamGeneratorFunction as Q, RescueCommitmentBlindingFactorDeriverFunction as R, PoseidonPrfFunction as S, PseudorandomU512DeriverFunction as T, UserCommitmentGeneratorFunction as U, RcDecryptorFunction as V, RcEncryptorFunction as W, RescueCipherDeps as X, RescueCipherInstance as Y, RescueKeyDerivationFunction as Z, RescuePermuteFunction as _, MasterViewingKeyDeriverFunction as a, RescuePrimeHashFunction as a0, SecondViewingKeyGeneratorFunction as a1, UserCommitmentGeneratorDeps as a2, ViewingKeyGeneratorOptions as a3, YearlyViewingKeyGeneratorFunction as a4, Kmac256Function as a5, RandomNonceGeneratorFunction as a6, X25519GetSharedSecretFunction as a7, MasterViewingKeyBlindingFactorDeriverFunction as b, PoseidonBlindingFactorDeriverFunction as c, PolynomialCommitmentFactorDeriverFunction as d, RcKeyGeneratorFunction as e, RcEncryptorWithNonceFunction as f, ChallengePowersFunction as g, PolynomialEvaluatorFunction as h, PoseidonAggregatorHashFunction as i, ChallengePowersDeps as j, EphemeralRescueCommitmentBlindingFactorDeriverFunction as k, EphemeralUtxoH2RandomSecretDeriverFunction as l, EphemeralUtxoMasterViewingKeyBlindingFactorDeriverFunction as m, EphemeralUtxoMasterViewingKeyDeriverFunction as n, EphemeralUtxoNullifierDeriverFunction as o, EphemeralUtxoPoseidonPrivateKeyBlindingFactorDeriverFunction as p, EphemeralUtxoPoseidonPrivateKeyDeriverFunction as q, FieldArithmetic as r, H2CircuitProvableParams as s, H2FullParams as t, H2GeneratorFns as u, H2HashFunction as v, HourlyViewingKeyGeneratorFunction as w, MasterSeedBasedFieldElementDeriverFunction as x, MasterSeedGeneratorFunction as y, MintViewingKeyDeriverFunction as z };