/** * Denomination ladder and keyset identity (spec §4, §6.12). Mirrors * `crates/px402-core/src/denom.rs`; `vectors/keyset.json` is the contract * between the two. * * A {@link Keyset} is the unit an issuer commits on-chain once per epoch: one * RSA blind-signature public key per face value, plus the epoch's * withdraw/spend/refresh windows. px402 replaces per-coin DLEQ proofs with a * single on-chain commitment to the *keyset*, so {@link keysetId} must be a * faithful function of every field a tagging attack could vary: an issuer * able to serve two different byte encodings of "the same" keyset to * different wallets, both hashing to ids that verify, could tag victims by * which encoding they received. {@link canonicalBytes} is the injective, * length-prefixed serialization that rules this out. * * # This module is the keyset-ingestion boundary * * {@link canonicalBytes} is what must run before an externally supplied * keyset is trusted at all, and every other entry point here routes through * it -- {@link keysetId} so that a rejected keyset has no id, and * {@link denomById} so that a lookup is not a way around the check. It * rejects an empty ladder, out-of-order or equal-valued denominations, two * denominations sharing one RSA modulus, any public exponent other than * 65537 (RFC 9474), and any modulus that is undersized, oversized, or not * byte-aligned (§6.13). * * `blind.ts` deliberately re-checks the key domain on every arithmetic entry * point, but a `DenomPublic` is a plain object and nothing guarantees one * reached that code through a keyset. So this is the only place that can * catch an issuer *publishing* `e = 3`, which would make every "blind" * signature on that denomination forgeable, or a misaligned modulus, which * collapses `selectSeeded`'s acceptance rate by up to 256x -- permanently per * coin index, since the derivation is deterministic and never retries with * fresh randomness. Both are epoch-long failures baked in at ingestion rather * than transient ones. */ import { type DenomPublic } from "./blind.js"; /** * The launch face values in USDC base units (6 decimals): $0.001, $0.004, * $0.016, $0.064, $0.256, $1.024, $4.096 -- powers of four from a $0.001 * floor (spec §4, §12), a ladder checked against real x402 prices. Mirrors * `LAUNCH_LADDER` in `crates/px402-core/src/denom.rs`, and * `vectors/keyset.json` is what holds the two to one value. Partial spend * means the ladder sets refresh cadence, never whether a price is payable. */ export declare const LAUNCH_LADDER: readonly bigint[]; /** One denomination: a face value in USDC base units and the RSA key coins of that value are signed under. */ export interface Denomination { readonly valueBaseUnits: bigint; readonly key: DenomPublic; } /** * A set of denominations plus one epoch's validity windows. * * Fields carry no invariant on their own -- see {@link canonicalBytes} for * the checks that must run before an externally supplied keyset is trusted. * Timestamps and the epoch id are `bigint` because §6.12 encodes them as * `be64` and a `number` cannot carry the top of that range exactly. */ export interface Keyset { readonly epochId: bigint; readonly denoms: readonly Denomination[]; readonly withdrawStart: bigint; readonly spendEnd: bigint; readonly refreshEnd: bigint; /** The issuer's master Ed25519 public key: exactly 32 bytes. */ readonly issuerMaster: Uint8Array; } /** * Validate `ks` and return its canonical byte serialization (spec §6.12): * * ```text * keysetCanonical = be64(epochId) * ‖ be32(denomCount) * ‖ for each denomination, ascending by value: * be64(valueBaseUnits) * ‖ be32(L_n) ‖ pad(n, L_n) L_n = bitlen(n) / 8 * ‖ be32(e) MUST equal 65537 * ‖ be64(withdrawStart) ‖ be64(spendEnd) ‖ be64(refreshEnd) * ‖ issuerMasterEd25519Pub exactly 32 bytes, no prefix * ``` * * # `be32(denomCount)` is required for injectivity, not decoration * * Without it the denomination loop has no terminator inside the digest, and a * keyset with `k` denominations can in principle be made to serialize * identically to one with `k+1` whose extra entry is read out of the trailing * timestamp fields (§6.12). The count makes the encoding injective by * construction, which is the only property a canonical encoding actually has * to have. * * # Only `n` carries a length prefix * * `n` is the one genuinely variable-length field, so it gets `be32(L_n)`. * Everything else -- the counters, the timestamps, `e`, the issuer master key * -- is fixed-width and is emitted raw, per §6.12's "fixed-width fields take * no length prefix": a redundant prefix is a second encoding of the same * value that two implementations can disagree about. In particular `e` is a * bare `be32` and is **not** padded to the modulus width. * * # Six checks, and what each one buys * * - **Non-empty ladder.** A keyset naming no denomination commits an epoch * under which nothing can ever be withdrawn, and would still produce a * committable id. * - **Strictly ascending by value.** Two orderings of the same set are the * same keyset and must not hash differently; §4 fixes ascending as * canonical. Equal adjacent values are rejected too -- they are two * denominations of one face value, not an ordering. * - **No shared modulus across face values.** A signature is a statement * about a key, not about a face value: with one modulus on $0.001 and * $4.096, a coin signed for the smaller verifies identically against the * larger. This is value conservation, not tidiness. * - **Modulus at least 2048 bits, at most 16384, byte-aligned** (§3, §6.13), * delegated to `blind.ts`'s {@link modulusBits} so the SDK has exactly one * definition of the RSA key domain. * - **Public exponent exactly 65537** (RFC 9474). * - **Issuer master key exactly 32 bytes.** It is emitted with no length * prefix, so a short key would silently shorten the canonical bytes and * change the id. * * @throws RangeError on any of the above, naming the condition. */ export declare function canonicalBytes(ks: Keyset): Uint8Array; /** * `keccak256(canonicalBytes(ks))` -- 32 bytes, matching the `bytes32` the * reserve contract's `commitKeyset(epochId, keysetId)` stores on-chain (§4). * * # keccak256, not SHA-384 and not SHA3-256 * * A wallet's mandatory "is this keyset committed on-chain" check -- the * control that replaces per-coin DLEQ entirely -- compares this value * byte-for-byte against that on-chain word. A 48-byte SHA-384 digest cannot * be compared against a `bytes32` at all, which would silently void the check * and let a malicious issuer serve distinct keysets to different wallets, * deanonymizing every coin. SHA3-256 is the right width and the wrong * padding: it produces an id no on-chain value will ever match. * * Routes through {@link canonicalBytes} rather than a raw serializer, so this * -- the function every caller reaches for first -- is not a way to skip the * ingestion checks. */ export declare function keysetId(ks: Keyset): Uint8Array; /** * Format a denomination id: `usdc--` (spec §4). * * `ksId` is the 32-byte {@link keysetId}, not a `Keyset`: a caller holding an * unvalidated keyset must go through {@link keysetId} or * {@link canonicalBytes} first, which is what lets this function be a pure * formatter. * * # The suffix is a disambiguator, not a binding * * Only 32 bits of the id appear, and the canonical bytes are entirely * issuer-chosen -- varying `withdrawStart` by a second per trial grinds ~2^32 * keccaks and makes two epochs share a suffix. A `denomId` is therefore * **not** a collision-resistant name for a key. The authoritative binding is * the full 32-byte on-chain `commitKeyset` value, and resolution goes through * {@link denomById} against one keyset the caller has already verified * against that commitment. */ export declare function denomId(ksId: Uint8Array, value: bigint): string; /** * Resolve a `denomId` on the wire to the denomination it names, within one * keyset. * * # Never parse the value out of the id string * * `denomId` is an opaque name, not a record. Every hash in the protocol -- * §6.1's `commitmentHash`, §6.6's `h_C`, `s_L` -- binds the id to a blinded * message while taking the width `L` from the *key*, and since §6.13 makes * every launch denomination 2048-bit, `L` is 256 across the whole ladder. So * the key contributes nothing to any digest beyond a constant width: two * different moduli hashed under one id produce identical commitments. The * claim that §6.6's interleaved `s_L` layout "binds which blinded message * belongs to which denomination key" holds only if some component resolves * the id to a key -- this one. A consumer that instead resolved keys by * position in the `{D_j}` array would let a wallet re-point a committed * `m(γ,j)` at a richer denomination: value conservation again. * * Resolution runs {@link keysetId}, hence the whole ingestion check, so an * unvalidated keyset cannot be resolved against. * * @throws RangeError if no denomination of this keyset carries that id, or * whatever {@link canonicalBytes} rejects the keyset for. */ export declare function denomById(ks: Keyset, id: string): Denomination; /** * The smallest rung of a keyset's ladder, in base units: the unit a * fee-bearing payment's presented total is rounded up to (v3 §25.1). * * Read from the keyset every time, never assumed: ladders are per epoch, and * a constant here would be right for one epoch only. * * @throws RangeError for a keyset with no denominations. */ export declare function smallestDenomination(ks: Keyset): bigint;