@umbra-privacy/sdk 1.0.0 → 2.0.0

package/dist/types-Ca7frykr.d.ts

@@ -0,0 +1,793 @@
+import { S as SubSubBrandedType, U as U128, a as SubSubSubBrandedType } from './types-C_V_CaKK.js';
+import { B as Bn254FieldElement } from './types-CW0oTT0j.js';
+
+/**
+ * Poseidon Cipher Types
+ *
+ * This module defines branded primitive types for all values that flow through
+ * Poseidon-based cryptographic operations in the Umbra SDK. Every type is a
+ * {@link SubSubSubBrandedType} — a four-level phantom brand layered on top of
+ * {@link Bn254FieldElement} — giving the TypeScript compiler enough information
+ * to reject accidental substitutions (e.g. passing a `PoseidonKey` where a
+ * `PoseidonCounter` is expected) while incurring zero runtime overhead.
+ *
+ * ## Why Poseidon?
+ *
+ * Poseidon is an algebraic hash function designed specifically for ZK-SNARK and
+ * ZK-STARK circuits. Unlike SHA-256, which operates on bits and requires thousands
+ * of R1CS constraints per invocation, Poseidon operates natively over prime fields
+ * using low-degree polynomial substitution boxes (x^5 over BN254's F_r). This
+ * reduces constraint count by 50-100x, making it practical to prove hashes inside
+ * Groth16 or PLONK circuits.
+ *
+ * In Umbra, Poseidon is used for:
+ * - UTXO commitment computation — binding amount, nullifier, and user commitment
+ *   into a single on-chain leaf via `H2 = Poseidon(...)`.
+ * - Fiat-Shamir challenge derivation — squeezing a deterministic challenge from
+ *   the transcript of public inputs to a ZK proof.
+ * - User commitment generation — binding a master viewing key (MVK) and a Poseidon
+ *   key to an on-chain commitment that the circuit can verify.
+ * - Keystream generation — acting as a PRF to produce per-counter keystream values
+ *   for stream-cipher encryption of confidential token account balances.
+ *
+ * All types in this module are valid BN254 scalar field elements:
+ * `0 ≤ value < BN254_FIELD_PRIME`.
+ *
+ * @see {@link https://eprint.iacr.org/2019/458} Poseidon: A New Hash Function for Zero-Knowledge Proof Systems
+ * @see {@link Bn254FieldElement} for the underlying field element type
+ * @see {@link BN254_FIELD_PRIME} for the field prime constant
+ *
+ * @packageDocumentation
+ * @module crypto/poseidon/types
+ */
+
+/**
+ * A plaintext field element that is an input to the Poseidon cipher or hash.
+ *
+ * `PoseidonPlaintext` wraps a {@link Bn254FieldElement} with an additional
+ * phantom brand to signal that the value has been validated as a suitable input
+ * for a Poseidon operation — i.e. it is a non-negative integer strictly less than
+ * the BN254 field prime.
+ *
+ * @remarks
+ * Poseidon operates natively over the BN254 scalar field F_r. Every input to a
+ * Poseidon hash or cipher invocation must therefore be a valid field element. This
+ * type makes that constraint explicit and compiler-enforced: you cannot pass an
+ * arbitrary `bigint` directly without first calling {@link assertPoseidonPlaintext}.
+ *
+ * In Umbra, plaintext values include:
+ * - Token amounts before encryption into confidential token accounts.
+ * - Blinding factors before they are committed.
+ * - UTXO data fields before being hashed into a commitment leaf.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonPlaintext, type PoseidonPlaintext } from "@umbra/sdk";
+ *
+ * const amount = 1_000_000n; // 1 USDC in micro-units
+ * assertPoseidonPlaintext(amount);
+ * // amount: PoseidonPlaintext — safe to pass to the Poseidon cipher
+ *
+ * const encryptor = getPoseidonEncryptor();
+ * const ciphertexts = await encryptor([amount], transactionViewingKey);
+ * ```
+ *
+ * @see {@link assertPoseidonPlaintext} for the corresponding assertion function
+ * @see {@link PoseidonEncryptorFunction} for the function that consumes this type
+ * @public
+ */
+type PoseidonPlaintext = SubSubSubBrandedType<Bn254FieldElement, "PoseidonPlaintext">;
+/**
+ * A hash output produced by the Poseidon hash function.
+ *
+ * `PoseidonHash` is the branded return type of a Poseidon invocation. It wraps
+ * the raw {@link Bn254FieldElement} output to distinguish a computed hash from an
+ * arbitrary field element at the type level.
+ *
+ * @remarks
+ * The Poseidon hash function maps N field elements (1 ≤ N ≤ 12 for this
+ * implementation) to a single field element. The output is:
+ * - Always a valid BN254 field element (in [0, BN254_FIELD_PRIME)).
+ * - Deterministic: identical inputs always produce identical output.
+ * - Collision-resistant under the algebraic hash security assumptions.
+ * - Pseudo-random: the output is computationally indistinguishable from a
+ *   uniformly random field element when at least one input is unknown.
+ *
+ * In Umbra, `PoseidonHash` values appear as:
+ * - UTXO commitment leaves in the indexed Merkle tree (IMT).
+ * - Aggregated public inputs fed to the on-chain Groth16 verifier.
+ * - User commitments binding a master viewing key to a Poseidon key.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonHash, type PoseidonHash } from "@umbra/sdk";
+ *
+ * // assertPoseidonHash is useful when receiving a bigint from an external
+ * // source (e.g. deserialized from JSON) that is claimed to be a hash.
+ * const rawHash = 12345678901234567890n;
+ * assertPoseidonHash(rawHash);
+ * // rawHash: PoseidonHash
+ * ```
+ *
+ * @see {@link assertPoseidonHash} for the corresponding assertion function
+ * @see {@link PoseidonAggregatorHashFunction} for the function that returns this type
+ * @public
+ */
+type PoseidonHash = SubSubSubBrandedType<Bn254FieldElement, "PoseidonHash">;
+/**
+ * The user's Poseidon private key — a secret field element derived from the master seed.
+ *
+ * `PoseidonKey` is NOT a parameter of the Poseidon hash function itself. Rather, it is
+ * a user-level cryptographic secret that is:
+ * 1. Derived deterministically from the user's master seed via a key-derivation path.
+ * 2. Used as a secret input to UTXO commitments, binding the commitment to this specific
+ *    user without revealing any information about the key to an observer.
+ * 3. Used as the master key for Poseidon-based stream cipher operations on confidential
+ *    token account balances (see {@link PoseidonEncryptorFunction}).
+ *
+ * @remarks
+ * ## Cryptographic Role
+ *
+ * In Umbra's UTXO scheme, the on-chain commitment to a note is computed as:
+ * ```
+ * userCommitment = Poseidon([masterViewingKey, poseidonKey])
+ * H2 = Poseidon([amount, nullifier, userCommitment, ...])
+ * ```
+ *
+ * The `poseidonKey` is the `PoseidonKey` value. Because it appears inside
+ * `userCommitment`, knowledge of the `PoseidonKey` is required to claim a UTXO
+ * directed at this user.
+ *
+ * ## Security Requirements
+ *
+ * - Must be generated using a cryptographically secure random source (CSPRNG).
+ * - Must be kept secret — exposure allows an attacker to claim all UTXOs directed
+ *   at the user that are encrypted with this key.
+ * - Must be in the BN254 field: `0 ≤ poseidonKey < BN254_FIELD_PRIME`.
+ * - Should be rotated if compromise is suspected.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonKey, type PoseidonKey } from "@umbra/sdk";
+ *
+ * // Derived from master seed in practice — never hardcode secrets.
+ * const derivedKey = deriveKeyFromMasterSeed(masterSeed, "poseidon-key");
+ * assertPoseidonKey(derivedKey);
+ * // derivedKey: PoseidonKey — safe to use in encryption operations
+ *
+ * const encryptor = getPoseidonEncryptor();
+ * const ciphertexts = await encryptor([amount], derivedKey);
+ * ```
+ *
+ * @see {@link assertPoseidonKey} for the corresponding assertion function
+ * @see {@link PoseidonEncryptorFunction} for encryption using this key
+ * @see {@link PoseidonKeystreamGeneratorFunction} for keystream generation
+ * @public
+ */
+type PoseidonKey = SubSubSubBrandedType<Bn254FieldElement, "PoseidonKey">;
+/**
+ * A ciphertext field element produced by Poseidon sponge encryption.
+ *
+ * `PoseidonCiphertext` is the branded output of encrypting a {@link PoseidonPlaintext}
+ * with a {@link PoseidonKey}. It is structurally a BN254 field element but is
+ * semantically distinct — it represents encrypted data, not raw plaintext.
+ *
+ * @remarks
+ * ## Encryption Scheme
+ *
+ * Umbra's Poseidon cipher uses a counter-mode (CTR) construction over the BN254
+ * field. For each plaintext at position `i`, the encryption is:
+ * ```
+ * ciphertext[i] = (plaintext[i] + keystream[i]) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * where `keystream[i] = Poseidon([transactionViewingKey, counter_i, 2n])`.
+ *
+ * This construction is additively homomorphic within the field: knowing the
+ * keystream allows recovery of the plaintext by subtraction modulo the field prime.
+ *
+ * ## Security Properties
+ *
+ * Under the PRF security of Poseidon, ciphertext values are computationally
+ * indistinguishable from uniformly random field elements. This provides semantic
+ * security (IND-CPA) as long as counter values are not reused with the same key.
+ *
+ * ## Stored On-Chain
+ *
+ * Ciphertexts are stored in confidential token accounts on Solana. The MXE
+ * (Multi-party eXecution Environment) decrypts them using the network's shared key
+ * during MPC computation; the account owner decrypts using their `PoseidonKey`.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonCiphertext, type PoseidonCiphertext } from "@umbra/sdk";
+ *
+ * // Received from on-chain state — assert before using
+ * const rawOnChainCiphertext = 99887766554433221100n;
+ * assertPoseidonCiphertext(rawOnChainCiphertext);
+ * // rawOnChainCiphertext: PoseidonCiphertext
+ *
+ * const decryptor = getPoseidonDecryptor();
+ * const [plaintext] = await decryptor([rawOnChainCiphertext], myPoseidonKey);
+ * ```
+ *
+ * @see {@link assertPoseidonCiphertext} for the corresponding assertion function
+ * @see {@link PoseidonEncryptorFunction} for how ciphertexts are produced
+ * @see {@link PoseidonDecryptorFunction} for how ciphertexts are recovered
+ * @public
+ */
+type PoseidonCiphertext = SubSubSubBrandedType<Bn254FieldElement, "PoseidonCiphertext">;
+/**
+ * A counter value (nonce) used to index positions in Poseidon counter-mode encryption.
+ *
+ * `PoseidonCounter` plays the same role as a nonce in AES-CTR mode, but operates
+ * over the BN254 scalar field. Each unique counter value, combined with the same
+ * {@link PoseidonKey}, produces a distinct keystream element via the Poseidon PRF.
+ *
+ * @remarks
+ * ## Counter-Mode Construction
+ *
+ * For a given key `k` and counter `c`, the keystream is:
+ * ```
+ * keystream(k, c) = Poseidon([k, c, 2n])
+ * ```
+ *
+ * The constant `2n` is a domain separation tag that binds the Poseidon invocation
+ * specifically to keystream generation, preventing cross-protocol misuse.
+ *
+ * ## Security Requirements
+ *
+ * - **Uniqueness**: Counter values MUST be unique for each distinct plaintext encrypted
+ *   under the same key. Reusing a `(key, counter)` pair for different plaintexts reveals
+ *   the XOR of those plaintexts (field difference, mod p).
+ * - **Range**: Must satisfy `0 ≤ counter < BN254_FIELD_PRIME`.
+ * - **Sequential use**: Counters are typically allocated sequentially starting at `0n`,
+ *   incrementing by 1 for each plaintext position.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   assertPoseidonCounter,
+ *   type PoseidonCounter,
+ *   BN254_FIELD_PRIME,
+ * } from "@umbra/sdk";
+ *
+ * // Allocate counters for encrypting three field elements
+ * const counters: PoseidonCounter[] = [0n, 1n, 2n].map((c) => {
+ *   assertPoseidonCounter(c);
+ *   return c;
+ * });
+ *
+ * // Increment safely (check upper bound for very long streams)
+ * const next = counters[2] + 1n;
+ * assertPoseidonCounter(next); // would throw if next >= BN254_FIELD_PRIME
+ *
+ * assertPoseidonCounter(-1n);          // throws: negative value
+ * assertPoseidonCounter(BN254_FIELD_PRIME); // throws: exceeds field prime
+ * ```
+ *
+ * @see {@link assertPoseidonCounter} for the corresponding assertion function
+ * @see {@link PoseidonKeystreamGeneratorFunction} for how counters are consumed
+ * @public
+ */
+type PoseidonCounter = SubSubSubBrandedType<Bn254FieldElement, "PoseidonCounter">;
+/**
+ * A pseudo-random field element generated by the Poseidon keystream PRF.
+ *
+ * `PoseidonKeystream` is the output of evaluating the Poseidon PRF at a specific
+ * {@link PoseidonCounter}. It is the secret "one-time pad" value added to a
+ * {@link PoseidonPlaintext} to produce a {@link PoseidonCiphertext}.
+ *
+ * @remarks
+ * ## Generation Formula
+ *
+ * For a master key `k` and counter `c`, the keystream is:
+ * ```
+ * keystream = Poseidon([k, c, 2n])
+ * ```
+ *
+ * The domain separation constant `2n` at the third input position ensures this
+ * Poseidon invocation is distinguishable from other uses of Poseidon in the
+ * protocol (e.g. hashing, commitment generation).
+ *
+ * ## Stream Cipher Operations
+ *
+ * ```
+ * // Encryption
+ * ciphertext = (plaintext + keystream) mod BN254_FIELD_PRIME
+ *
+ * // Decryption
+ * plaintext  = (ciphertext - keystream + BN254_FIELD_PRIME) mod BN254_FIELD_PRIME
+ * ```
+ *
+ * ## Security Properties
+ *
+ * - Keystreamvalues are computationally indistinguishable from uniformly random
+ *   field elements when the key is unknown (PRF security of Poseidon).
+ * - Each `(key, counter)` pair produces exactly one keystream value; counters must
+ *   not be reused (see {@link PoseidonCounter}).
+ * - Keystreamvalues themselves must remain secret; exposing a keystream for a given
+ *   counter reveals the corresponding plaintext.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   assertPoseidonKeystream,
+ *   type PoseidonKeystream,
+ *   BN254_FIELD_PRIME,
+ * } from "@umbra/sdk";
+ *
+ * const keystreamGenerator = getPoseidonKeystreamGenerator();
+ * const keystreamMap = await keystreamGenerator([0n, 1n, 2n], masterKey);
+ *
+ * const keystream0 = keystreamMap.get(0n)!; // PoseidonKeystream for counter 0
+ * // Encrypt one field element
+ * const ciphertext = (plaintext + keystream0) % BN254_FIELD_PRIME;
+ *
+ * // Externally supplied keystream must be validated before use
+ * const rawKeystream = 111222333n;
+ * assertPoseidonKeystream(rawKeystream);
+ * // rawKeystream: PoseidonKeystream
+ * ```
+ *
+ * @see {@link assertPoseidonKeystream} for the corresponding assertion function
+ * @see {@link PoseidonKeystreamGeneratorFunction} for the function that produces this type
+ * @public
+ */
+type PoseidonKeystream = SubSubSubBrandedType<Bn254FieldElement, "PoseidonKeystream">;
+/**
+ * A single 85-bit limb of a Base85 decomposition of a 256-bit value.
+ *
+ * Base85 limbs are the canonical way that the Umbra ZK circuits represent
+ * 256-bit field elements (e.g., Solana public keys and Ethereum addresses) when
+ * those values must be hashed or committed inside a Poseidon-based circuit.
+ * Because BN254 field elements are ~254 bits, a full 256-bit value cannot be
+ * reduced into a single field element without information loss. Instead, it is
+ * split into three 85-bit limbs, each of which is small enough to fit safely
+ * within the BN254 field.
+ *
+ * @remarks
+ * ## Why 85 bits?
+ *
+ * Three 85-bit limbs cover exactly 255 bits, which is sufficient for any value
+ * less than 2^255 — a superset of all 256-bit keys used in Umbra (Solana
+ * addresses are 32 bytes = 256 bits, but their top bit is effectively always 0
+ * for Ed25519 keys).
+ *
+ * ## Type Hierarchy
+ *
+ * ```
+ * bigint
+ *   └── UnsignedInteger  (brand: "UnsignedInteger")
+ *         └── U128        (brand: "U128")
+ *               └── Base85Limb (brand: "Base85Limb")
+ * ```
+ *
+ * `Base85Limb` extends `U128` because the actual limb value fits within 85 bits,
+ * which is a strict subset of the 128-bit unsigned range.
+ *
+ * @example
+ * ```typescript
+ * import { assertBase85Limb, BASE85_LIMB_MAX, type Base85Limb } from "@umbra/sdk";
+ *
+ * const lowBits = 123456789n;
+ * assertBase85Limb(lowBits, "lowBits");
+ * // lowBits: Base85Limb
+ *
+ * assertBase85Limb(BASE85_LIMB_MAX + 1n, "overflow"); // throws: exceeds max
+ * assertBase85Limb(-1n, "negative");                   // throws: negative value
+ * ```
+ *
+ * @see {@link BASE85_LIMB_MAX} for the maximum valid limb value (2^85 - 1)
+ * @see {@link Base85LimbTuple} for the three-limb tuple that represents a full 256-bit value
+ * @see {@link assertBase85Limb} for the corresponding assertion function
+ * @public
+ */
+type Base85Limb = SubSubBrandedType<U128, "Base85Limb">;
+/**
+ * The maximum value representable by a single Base85 limb.
+ *
+ * @remarks
+ * Equals `2^85 - 1`. Any `bigint` value greater than this constant is out of range
+ * for a `Base85Limb` and will be rejected by {@link assertBase85Limb}.
+ *
+ * The value in decimal is:
+ * `38685626227668133590597631`
+ *
+ * @example
+ * ```typescript
+ * import { BASE85_LIMB_MAX } from "@umbra/sdk";
+ *
+ * // Check before asserting
+ * if (value <= BASE85_LIMB_MAX) {
+ *   assertBase85Limb(value, "value");
+ * }
+ * ```
+ *
+ * @see {@link Base85Limb} for the type this constant bounds
+ * @public
+ */
+declare const BASE85_LIMB_MAX: bigint;
+/**
+ * A three-limb representation of a 256-bit value in Base85 encoding.
+ *
+ * `Base85LimbTuple` decomposes a 256-bit value `V` into three {@link Base85Limb}
+ * components according to the bit-slice layout:
+ * - `low`:    bits [0, 84]   — `V mod 2^85`
+ * - `middle`: bits [85, 169] — `(V >> 85) mod 2^85`
+ * - `high`:   bits [170, 255] — `(V >> 170) mod 2^86`
+ *
+ * All three limbs together reconstruct the original 256-bit value as:
+ * ```
+ * V = low + (middle * 2^85) + (high * 2^170)
+ * ```
+ *
+ * @remarks
+ * ## Use in ZK Circuits
+ *
+ * Inside a Groth16 or PLONK circuit, a 256-bit value (e.g., a Solana address)
+ * cannot be processed as a single field element because the BN254 prime is only
+ * ~254 bits. The standard approach is to pass the value as three limbs and let
+ * the circuit reconstruct it from the limb witnesses:
+ *
+ * ```circom
+ * signal input addrLow;    // bits [0, 84]
+ * signal input addrMiddle; // bits [85, 169]
+ * signal input addrHigh;   // bits [170, 255]
+ * ```
+ *
+ * The Umbra Poseidon aggregator hashes these limbs alongside other UTXO fields
+ * to produce the aggregated public input for the Groth16 verifier.
+ *
+ * ## Readonly Fields
+ *
+ * All three fields are `readonly` to prevent mutation after construction. Changing
+ * a limb without updating the others would produce an inconsistent representation.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   assertBase85Limb,
+ *   type Base85LimbTuple,
+ * } from "@umbra/sdk";
+ *
+ * function decompose256BitValue(v: bigint): Base85LimbTuple {
+ *   const mask = (1n << 85n) - 1n;
+ *   const low    = v & mask;
+ *   const middle = (v >> 85n) & mask;
+ *   const high   = (v >> 170n) & ((1n << 86n) - 1n);
+ *
+ *   assertBase85Limb(low,    "low");
+ *   assertBase85Limb(middle, "middle");
+ *   assertBase85Limb(high,   "high");
+ *
+ *   return { low, middle, high };
+ * }
+ * ```
+ *
+ * @see {@link Base85Limb} for the individual limb type
+ * @see {@link BASE85_LIMB_MAX} for the per-limb maximum value
+ * @public
+ */
+interface Base85LimbTuple {
+    /**
+     * The low 85 bits of the 256-bit value (bits 0–84, inclusive).
+     *
+     * @remarks
+     * Computed as `value mod 2^85`. This is the least-significant limb.
+     *
+     * @readonly
+     */
+    readonly low: Base85Limb;
+    /**
+     * The middle 85 bits of the 256-bit value (bits 85–169, inclusive).
+     *
+     * @remarks
+     * Computed as `(value >> 85n) mod 2^85`. This limb represents the second
+     * 85-bit segment of the original value.
+     *
+     * @readonly
+     */
+    readonly middle: Base85Limb;
+    /**
+     * The high bits of the 256-bit value (bits 170–255, inclusive).
+     *
+     * @remarks
+     * Computed as `value >> 170n`. Because a 256-bit value contributes at most
+     * 86 bits in this position (256 - 170 = 86), this limb may reach up to
+     * 2^86 - 1, which still fits within the `Base85Limb` maximum of 2^85 - 1
+     * for values that are actually ≤ 2^255 (i.e., all valid Ed25519 public keys
+     * and standard 32-byte Solana addresses).
+     *
+     * @readonly
+     */
+    readonly high: Base85Limb;
+}
+/**
+ * Narrows a `bigint` to {@link PoseidonPlaintext} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonPlaintext`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Assertion functions are the SDK's pattern for validating untrusted data at the
+ * boundary of typed and untyped code (e.g., values deserialized from JSON, received
+ * from on-chain accounts, or passed in from user input). After a successful call,
+ * the brand is established for the rest of the scope without any runtime cost beyond
+ * the validation itself.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonPlaintext } from "@umbra/sdk";
+ *
+ * // Good: valid field element
+ * const amount = 1_000_000n;
+ * assertPoseidonPlaintext(amount);
+ * // amount: PoseidonPlaintext ✓
+ *
+ * // Bad: negative value
+ * assertPoseidonPlaintext(-1n); // throws CryptographyAssertionError
+ *
+ * // Bad: at or above field prime
+ * assertPoseidonPlaintext(BN254_FIELD_PRIME); // throws CryptographyAssertionError
+ * ```
+ *
+ * @see {@link PoseidonPlaintext} for the type this function establishes
+ * @see {@link BN254_FIELD_PRIME} for the upper bound on valid values
+ * @public
+ */
+declare function assertPoseidonPlaintext(value: bigint): asserts value is PoseidonPlaintext;
+/**
+ * Narrows a `bigint` to {@link PoseidonHash} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonHash`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Use this function when receiving a hash output from an external source (on-chain
+ * account data, a network response, or a test fixture) and you need to re-establish
+ * the `PoseidonHash` brand before passing the value to hash-typed APIs.
+ *
+ * Note that the Poseidon hash functions in the SDK return `PoseidonHash` directly,
+ * so calling this assertion is only necessary at trust boundaries.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonHash } from "@umbra/sdk";
+ *
+ * // Received as raw bigint from deserialized on-chain data
+ * const onChainLeaf: bigint = readLeafFromChain();
+ * assertPoseidonHash(onChainLeaf);
+ * // onChainLeaf: PoseidonHash — safe to compare with locally computed hashes
+ *
+ * assertPoseidonHash(-5n);            // throws: negative
+ * assertPoseidonHash(BN254_FIELD_PRIME); // throws: out of range
+ * ```
+ *
+ * @see {@link PoseidonHash} for the type this function establishes
+ * @public
+ */
+declare function assertPoseidonHash(value: bigint): asserts value is PoseidonHash;
+/**
+ * Narrows a `bigint` to {@link PoseidonKey} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonKey`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Call this function after deriving a `PoseidonKey` from a master seed to establish
+ * the type brand. Because key derivation functions typically return raw `bigint` or
+ * `Uint8Array` values, the assertion is needed at the point where the raw output is
+ * interpreted as a Poseidon key.
+ *
+ * ## Security Warning
+ *
+ * A `PoseidonKey` is a long-lived secret. Validation does NOT check that the value
+ * was generated with sufficient entropy. It is the caller's responsibility to ensure
+ * the key was derived from a secure random source.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonKey } from "@umbra/sdk";
+ *
+ * const rawDerivedKey: bigint = deriveField(masterSeed, "poseidon/v1");
+ * assertPoseidonKey(rawDerivedKey);
+ * // rawDerivedKey: PoseidonKey — ready to pass to encryption functions
+ *
+ * assertPoseidonKey(-1n);             // throws: negative
+ * assertPoseidonKey(BN254_FIELD_PRIME); // throws: out of range
+ * ```
+ *
+ * @see {@link PoseidonKey} for the type this function establishes
+ * @see {@link PoseidonEncryptorFunction} for the primary consumer of this type
+ * @public
+ */
+declare function assertPoseidonKey(value: bigint): asserts value is PoseidonKey;
+/**
+ * Narrows a `bigint` to {@link PoseidonCiphertext} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonCiphertext`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Use this function when reading ciphertext values from on-chain account state
+ * (e.g., a confidential token account's encrypted balance fields) before passing
+ * them to {@link PoseidonDecryptorFunction}.
+ *
+ * Structurally, ciphertexts are indistinguishable from other BN254 field elements.
+ * The brand exists purely to prevent passing a plaintext where ciphertext is
+ * expected, or vice versa, at the type level.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonCiphertext } from "@umbra/sdk";
+ *
+ * // Reading raw ciphertext from a deserialized Solana account
+ * const rawCiphertext: bigint = accountData.encryptedBalance;
+ * assertPoseidonCiphertext(rawCiphertext);
+ * // rawCiphertext: PoseidonCiphertext — safe to pass to decryptor
+ *
+ * const [plaintext] = await decryptor([rawCiphertext], myKey);
+ * ```
+ *
+ * @see {@link PoseidonCiphertext} for the type this function establishes
+ * @see {@link PoseidonDecryptorFunction} for the function that consumes ciphertexts
+ * @public
+ */
+declare function assertPoseidonCiphertext(value: bigint): asserts value is PoseidonCiphertext;
+/**
+ * Narrows a `bigint` to {@link PoseidonCounter} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonCounter`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Counters are typically constructed from small non-negative integers (0, 1, 2, …)
+ * that index into a sequence of plaintext positions. In practice the upper-bound
+ * check is almost never triggered for counter values, but it is included for
+ * correctness and to guard against edge cases in long-running sessions.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonCounter, type PoseidonCounter } from "@umbra/sdk";
+ *
+ * // Typed allocation of sequential counters
+ * function makeCounters(n: number): PoseidonCounter[] {
+ *   return Array.from({ length: n }, (_, i) => {
+ *     const c = BigInt(i);
+ *     assertPoseidonCounter(c);
+ *     return c;
+ *   });
+ * }
+ *
+ * assertPoseidonCounter(-1n);          // throws: negative value
+ * assertPoseidonCounter(BN254_FIELD_PRIME); // throws: exceeds field prime
+ * ```
+ *
+ * @see {@link PoseidonCounter} for the type this function establishes
+ * @see {@link PoseidonKeystreamGeneratorFunction} for how counters are consumed
+ * @public
+ */
+declare function assertPoseidonCounter(value: bigint): asserts value is PoseidonCounter;
+/**
+ * Narrows a `bigint` to {@link PoseidonKeystream} by asserting it is a valid BN254 field element.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `PoseidonKeystream`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value < BN254_FIELD_PRIME`.
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` is out of range (`value >= BN254_FIELD_PRIME`).
+ *
+ * @remarks
+ * Keystreamvalues are outputs of the Poseidon PRF and therefore always valid field
+ * elements when produced by the SDK's {@link PoseidonKeystreamGeneratorFunction}.
+ * This assertion is primarily useful at trust boundaries where a keystream value
+ * arrives from an external or serialized source and must be re-validated.
+ *
+ * ## Security Note
+ *
+ * Keystreamvalues are cryptographic secrets. They must not be logged, serialized
+ * to persistent storage, or transmitted in any observable channel. Exposing a
+ * keystream allows recovery of the corresponding plaintext.
+ *
+ * @example
+ * ```typescript
+ * import { assertPoseidonKeystream, BN254_FIELD_PRIME } from "@umbra/sdk";
+ *
+ * // In tests: construct a keystream from a known value for deterministic checks
+ * const testKeystream = 999888777666n;
+ * assertPoseidonKeystream(testKeystream);
+ * // testKeystream: PoseidonKeystream
+ *
+ * assertPoseidonKeystream(-1n);            // throws: negative value
+ * assertPoseidonKeystream(BN254_FIELD_PRIME); // throws: exceeds field prime
+ * ```
+ *
+ * @see {@link PoseidonKeystream} for the type this function establishes
+ * @see {@link PoseidonKeystreamGeneratorFunction} for the function that produces keystreams
+ * @public
+ */
+declare function assertPoseidonKeystream(value: bigint): asserts value is PoseidonKeystream;
+/**
+ * Narrows a `bigint` to {@link Base85Limb} by asserting it is within the 85-bit range.
+ *
+ * This is a TypeScript assertion function: if it returns without throwing, the
+ * TypeScript compiler refines the type of `value` from `bigint` to `Base85Limb`
+ * in the calling scope.
+ *
+ * @param value - The `bigint` to validate. Must satisfy `0 ≤ value ≤ 2^85 - 1`.
+ * @param name - A human-readable name for the variable being asserted, included in
+ *   error messages to aid debugging when multiple limbs are validated in sequence.
+ *   @defaultValue `"value"`
+ * @throws {CryptographyAssertionError} If `value` is not a `bigint`.
+ * @throws {CryptographyAssertionError} If `value` is negative (`value < 0n`).
+ * @throws {CryptographyAssertionError} If `value` exceeds the maximum limb value (`value > BASE85_LIMB_MAX`).
+ *
+ * @remarks
+ * This assertion is distinct from the Poseidon field element assertions: it checks
+ * against `BASE85_LIMB_MAX` (2^85 - 1) rather than `BN254_FIELD_PRIME`. Use this
+ * when decomposing a 256-bit value into {@link Base85LimbTuple} components.
+ *
+ * The `name` parameter is optional and defaults to `"value"`. Providing descriptive
+ * names (`"low"`, `"middle"`, `"high"`) makes errors easier to trace when all three
+ * limbs are validated in sequence.
+ *
+ * @example
+ * ```typescript
+ * import { assertBase85Limb, BASE85_LIMB_MAX } from "@umbra/sdk";
+ *
+ * const low    = 12345n;
+ * const middle = 67890n;
+ * const high   = 111n;
+ *
+ * assertBase85Limb(low,    "low");
+ * assertBase85Limb(middle, "middle");
+ * assertBase85Limb(high,   "high");
+ * // All three: Base85Limb
+ *
+ * // Error messages include the name for easy identification
+ * assertBase85Limb(BASE85_LIMB_MAX + 1n, "low"); // throws: "low: Value exceeds Base85 limb maximum"
+ * assertBase85Limb(-1n, "middle");                // throws: "middle: Value -1 is negative"
+ * ```
+ *
+ * @see {@link Base85Limb} for the type this function establishes
+ * @see {@link BASE85_LIMB_MAX} for the maximum allowed value
+ * @see {@link Base85LimbTuple} for how three limbs form a 256-bit representation
+ * @public
+ */
+declare function assertBase85Limb(value: bigint, name?: string): asserts value is Base85Limb;
+
+export { BASE85_LIMB_MAX as B, type PoseidonCiphertext as P, type Base85Limb as a, type Base85LimbTuple as b, type PoseidonCounter as c, type PoseidonHash as d, type PoseidonKey as e, type PoseidonKeystream as f, type PoseidonPlaintext as g, assertBase85Limb as h, assertPoseidonCiphertext as i, assertPoseidonCounter as j, assertPoseidonHash as k, assertPoseidonKey as l, assertPoseidonKeystream as m, assertPoseidonPlaintext as n };