/** * §4's mandatory check: **a keyset not committed on-chain must be rejected.** * * # Why this is the whole of the privacy argument * * px402 has no per-coin DLEQ proof. What replaces it is a single on-chain * commitment to the keyset: `PX402Reserve.keysets(epochId)` holds one * `bytes32`, and every wallet checks that the keyset it is about to withdraw * under hashes to that word. * * Remove the check and the blinding stops protecting anybody. An issuer that * can serve one victim a keyset nobody else holds — one extra denomination * key, or the same ladder with one modulus swapped — has partitioned the * anonymity set down to that victim: every coin signed under that key is * theirs, and the issuer recognises each one on the registry's public spend * log without breaking a single blind signature. The commitment is what makes * "everyone got the same keys" checkable, and the id is recomputed here from * the served preimage rather than taken from the issuer's own `keyset_id` * field, so a lying issuer has to break keccak256 rather than a JSON field. * * # The chain read is the caller's, on purpose * * This SDK holds no RPC dependency and opens no sockets a caller did not * hand it: {@link KeysetCommitmentReader} follows the same pattern as * `ChainConfig.reserveNonce`. What the SDK owns is that the check *happens*, * that a missing reader is loud, and that every way it can fail — the wrong * word, no word, an unreadable word, an RPC that never answers — ends in a * refusal rather than a wallet that quietly skipped it. */ import { type Keyset } from "./denom.js"; /** * Reads `PX402Reserve.keysets(epochId)` — one `bytes32` — from the chain. * * Returns the word as bytes or as hex (`0x`-prefixed or bare), or * `undefined`/`null` when the epoch has no commitment. An all-zero word means * the same thing: Solidity's zero value for an unset mapping entry. */ export type KeysetCommitmentReader = (epochId: bigint) => Promise; /** How long {@link verifyKeysetCommitment} waits for a reader: 15 seconds. */ export declare const DEFAULT_KEYSET_COMMITMENT_TIMEOUT_MS = 15000; /** Why a keyset could not be shown to be the committed one. */ export type KeysetCommitmentFailure = /** The chain holds a different word: this keyset is not the committed one. */ "mismatch" /** The chain holds nothing for this epoch. */ | "uncommitted" /** The word could not be read at all — a bad shape, a failed or hung reader. */ | "unreadable"; /** * A keyset that could not be shown to be the one committed on-chain (§4). * * A security failure, not a configuration one, which is why it is its own * class: the remedy is never "pass a flag", it is finding out why the issuer * served a keyset the chain does not name. */ export declare class PX402KeysetCommitmentError extends Error { readonly reason: KeysetCommitmentFailure; readonly epochId: bigint; /** The id recomputed from the served keyset, `0x`-prefixed. */ readonly expected: string; /** The word the chain holds, `0x`-prefixed, or `null` when none was read. */ readonly onChain: string | null; constructor(detail: { reason: KeysetCommitmentFailure; epochId: bigint; expected: string; onChain?: string | null; detail: string; cause?: unknown; }); } /** What {@link verifyKeysetCommitment} needs. */ export interface KeysetCommitmentCheck { /** The keyset to check. Validated (`canonicalBytes`) before anything is read. */ readonly keyset: Keyset; readonly read: KeysetCommitmentReader; /** Defaults to {@link DEFAULT_KEYSET_COMMITMENT_TIMEOUT_MS}. */ readonly timeoutMs?: number; } /** * Compare `keccak256(canonicalBytes(keyset))` against the chain's * `keysets(epochId)`, and refuse anything that is not an exact match. * * Standalone so a facilitator, a verifier or a test runs the same check a * wallet runs, without opening one. `px402.open` calls exactly this. * * The comparison is over the **recomputed** id: {@link keysetId} routes * through `canonicalBytes`, so a keyset that would not survive ingestion — an * unordered ladder, a shared modulus, `e ≠ 65537` — is rejected here with a * `RangeError` before any chain read happens. * * @returns the verified 32-byte keyset id. * @throws PX402KeysetCommitmentError on mismatch, on an epoch with no * commitment, on a word that is not a `bytes32`, and on a reader that fails or * does not answer inside `timeoutMs`. * @throws RangeError if the keyset itself does not validate. */ export declare function verifyKeysetCommitment(check: KeysetCommitmentCheck): Promise;