/** * The coin buffer, and the selection policy §7 makes normative. * * # `privacy: "strict"` is the default and fails closed * * A coin becomes spendable only after **at least one issuance window** has * passed (§9.1: 60-second batch windows for both issuance and refresh, ≥ 1 * window hold before spend). That hold is the whole of what separates a * withdrawal from the spend that follows it: without it, the issuer sees a * coin issued and a merchant sees it spent moments later, and the timing * correlates the two sides of the graph the system exists to keep apart. * * So when nothing is spendable, {@link CoinStore.select} raises * {@link PX402NoCoinsError} rather than reaching for a fresh coin. "Spend it * anyway" is not a degraded mode; it is the failure the mode exists to * prevent, which is why there is **no silent fallback** — `besteffort` is a * value the caller has to write down. * * # Selection is randomized, and that is not cosmetic * * Coins come out in randomized order (§7). A store that always spent its * oldest, or its insertion-order head would hand every merchant a sample of * the wallet's own coin sequence, and two merchants comparing notes could * reassemble it. The shuffle uses a CSPRNG by default and is injectable so a * test can pin it. * * What the shuffle protects is **which coin** of an interchangeable set gets * spent, because a coin public key is the identifier two merchants can * compare. It is not which *rung* the spend draws from: that is a function of * the price and of what the buffer holds, and every policy that minimises coin * count arrives at the same denomination multiset. So {@link CoinStore.select} * walks rungs largest-first and draws from within each rung in the shuffled * order — see `descendingByResidual`. * * # A spend that leaves change costs a melt and a minute * * Splitting a coin retires its residual (§7 again: the merchant has seen the * key), and the only way back to spendable value is a §6.6 melt followed by a * fresh §9.1 issuance hold. So {@link CoinStore.select} tries an **exact * cover** in whole coins before it splits anything: ten whole coins are a * cheaper spend than one split coin, not a more expensive one. Dogfooding * measured the gap — a 20 USDC buffer paying $2.50 a call ran dry after four * calls, with the rest of the money parked in refresh holds. * * # Below the anonymity floor: warn, never downgrade * * §9.1 claims unlinkability only while there are ≥ 100 active reserves **and** * ≥ 1,000 coins per (denomination, epoch). Below that, {@link CoinStore.select} * emits a crowd-size warning and **still functions**. The warning is a * disclosure, not a mode change: there is never a silent fallback to * timing-linkable spending, and there is never a silent refusal either. * * # A coin is presented to at most one merchant, ever (§7, normative) * * The registry publishes each spend leaf `(C_p, f, H(contractTerms))` in a * **public** log. A coin that pays two merchants therefore puts both payments * under one coin key in that log: anyone grouping leaves by coin key * union-finds the wallet's payments into a single cluster, and the two * merchants — who each saw `coinPub` in their own `X-PAYMENT` payload — link * the payer to each other with no collusion and no privileged access. That is * the shopping history this product exists to prevent. * * So the buffer does not *avoid* reuse, it makes it unrepresentable: * {@link CoinStore.select} **records the presentation as it selects**, in the * same synchronous step, and {@link CoinStore.spendable} refuses every coin * carrying a presentation or a recorded spend. There is no window between * "chosen" and "retired" for a second selection to land in, and no argument a * caller can pass that reaches a coin some merchant has already seen. The * residual left on such a coin comes back only as **fresh** coins, through * §6.6 refresh — see {@link CoinStore.refreshable}. * * `strict` therefore fails closed with {@link PX402NoCoinsError} rather than * reuse. `besteffort` may return to *the merchant that already holds the coin * key* — telling that merchant nothing it does not already know — and warns * when it does. Neither mode will ever hand one coin to two merchants. */ import { type IssuedCoin } from "./client.js"; /** * The issuance batch window, in seconds (§12). A coin must be at least this * old before `strict` will spend it — §9.1's "≥ 1 window hold before spend". * The floor of every coin's hold, never the whole of it: see * {@link DEFAULT_HOLD_JITTER_SECONDS}. */ export declare const ISSUANCE_WINDOW_SECONDS = 60; /** * The default width of the band each coin's hold is drawn from, in seconds. * * A coin's hold is `ISSUANCE_WINDOW_SECONDS + U[0, holdJitterSeconds)`, one * draw per coin. A **fixed** hold is a sharper timing join than a spread one: * "the spend follows the withdrawal by exactly one window" is a signature an * observer can match on, where "by somewhere between one and two windows" is * a band the observer has to integrate over. The floor is never lowered — the * band only ever adds to §9.1's one window — and `besteffort` holds nothing * either way. * * What the hold does not do (v3 §25.3): it delays a first spend, it does not * hide which withdrawal it came from. With few withdrawals per hold, the most * recent withdrawal before a payment is likely the payer's own. The fixed * hold is kept; the answer is to pre-fund well before spending * (`wallet.prewarm`) and let the hold pass. A crowd-relative hold is the * documented future option. */ export declare const DEFAULT_HOLD_JITTER_SECONDS = 60; /** * The jitter a coin adds to its hold: `U[0, band)` whole seconds, derived * from the coin's own secret. * * # Derived, not drawn and stored * * The draw has to survive recovery: a wallet rebuilt from its seed (§6.10) or * resumed from a stored coin set must land every coin on the **same** * spendable-at instant, or a resume would either shorten a hold (a timing * leak) or restart one (money parked for nothing). Deriving the jitter from * the coin secret gives that for free — the secret is already what recovery * reproduces — with no new field to persist, no RNG transcript to replay, * and no change to how the injected `randomBytes` is consumed, so a seeded * shuffle draws exactly what it drew before. The secret is what a merchant * never sees, so the jitter is unpredictable to exactly the parties the band * exists to confuse. * * Reduced by `mod band` from a 64-bit draw rather than by rejection * sampling: a deterministic derivation has no "draw again", and the bias of * a 64-bit modulus over a band of seconds is below 2⁻⁵⁰ — nothing an * observer with second-granularity timestamps could ever see. */ export declare function holdJitterSeconds(secret: Uint8Array, band: number): number; /** * How many coins one payment may present. * * Mirrors `MAX_COINS` in `crates/px402-facilitator/src/lib.rs`, which refuses * a larger payload *before* any cryptography runs — steps 2 and 3 of §6.4 are * a modexp and an Ed25519 verification per coin, and an unauthenticated caller * choosing how many of those one request buys is a DoS sink. It is therefore a * bound a wallet has to plan inside rather than discover on a `BadRequest`. * * Fifteen, because that is what fits a 12 KiB `X-PAYMENT` header * (`payload.ts`, 2026-10-02): a launch-ladder coin is 768 bytes of header, * so 12,288 bytes hold fifteen with a resource URL of up to 228 bytes and * never sixteen. It was sixteen, and a sixteen-coin payment is a 12.5 KiB * header. This is the facilitator's acceptance cap, not what a payment * presents by default: the wallet's default header budget is 7.5 KiB * (`DEFAULT_MAX_PAYMENT_HEADER_BYTES`), which holds nine, so `wrapFetch` * plans inside nine unless the wallet is configured with a larger budget. * * Fifteen coins at the launch ladder's top rung ($4.096) cover a $61.44 * payment, and on a canonical (powers-of-four) ladder the *minimal* whole-coin * cover of any amount needs at most three coins per rung — so a seven-rung * ladder can want up to twenty-one, and this bound is reachable in practice. * See {@link CoinStore.select} for what happens then. */ export declare const MAX_COINS_PER_SPEND = 15; /** * §9.1's floor. Unlinkability is claimed only at or above **both** gauges; * the gauges themselves are public (§8). */ export declare const ANONYMITY_FLOOR: Readonly; /** The published crowd-size gauges (§8), as a wallet reads them. */ export interface AnonymityGauges { readonly activeReserves: number; readonly coinsPerDenomEpoch: number; } /** * `"strict"` (default) holds a coin for at least one issuance window and fails * closed; `"besteffort"` is the explicit opt-in to spending fresh coins * immediately. */ export type PrivacyMode = "strict" | "besteffort"; /** * One merchant, as the wallet must tell them apart for §7's one-coin-one-merchant * rule. * * Both halves are load-bearing and neither implies the other. `origin` is the * party that receives the `X-PAYMENT` header, so it is the party that reads * `coinPub` off the wire. `payTo` is the party the spend leaf's terms hash * pays, so it is the identity the public log attaches to that coin. Two * payments count as the same merchant only when **both** match; anything else * is a link between two distinct parties. */ export interface MerchantRef { /** Origin of the resource URL — the server that receives `X-PAYMENT`. */ readonly origin: string; /** The `payTo` from the chosen `accepts[]` entry, `0x`-prefixed (§6.14). */ readonly payTo: string; } /** One coin in the buffer, with what the store tracks about it. */ export interface StoredCoin { readonly coin: IssuedCoin; /** Unix seconds the coin was issued — the start of its issuance-window hold. */ readonly issuedAt: number; /** * Unix seconds at which `strict` will first spend this coin: `issuedAt` * plus its own hold (one window plus a per-coin jitter — see * {@link holdJitterSeconds}). `besteffort` ignores it. */ readonly spendableAt: number; /** How much of its face value has been committed to spends, in base units. */ readonly spent: bigint; /** * Every merchant this coin's public key has been handed to. * * Non-empty means the coin is retired from selection: §7 permits at most one * merchant per coin, and the only way back to spendable value is §6.6 * refresh. An entry with an empty `origin` is a merchant the wallet cannot * name — a selection whose caller named none, or a spend §6.10 recovery * found on the registry — and can never match one, which is the point. */ readonly presentedTo: readonly MerchantRef[]; } /** * What the buffer is worth, split by what {@link CoinStore.select} can * actually reach — the three-way split every capacity question needs. * * `spendable + held + retired === totalValue()`, always. The split is the * point: a caller that sees only a total cannot tell "I can pay now" from "I * can pay in 40 seconds" from "I need a melt first", and those three have * different remedies (none, wait, {@link CoinStore.refreshable}). */ export interface ValueSnapshot { /** Residual {@link CoinStore.select} would return **at this `now`**. */ readonly spendable: bigint; /** * Residual on coins no merchant has seen that are still inside §9.1's * issuance-window hold. Becomes spendable by waiting and by nothing else; * always zero under `besteffort`, which does not hold. */ readonly held: bigint; /** * Residual §7 retired — presented to a merchant, or carrying a recorded * spend. Real money, reachable only as fresh coins through §6.6 refresh. * * Counted as retired even under `besteffort`, where the coin's own merchant * could still be shown it: a snapshot names no merchant, so the only honest * answer is the one that holds for every merchant. */ readonly retired: bigint; /** * When each held coin leaves the hold, ascending by time. * * Ascending so a caller can answer "when is `amount` covered?" with one * forward scan rather than a poll. Empty whenever {@link held} is zero. */ readonly unlocks: readonly { readonly at: number; readonly value: bigint; }[]; } /** One coin and the fraction of it a selection assigns to a payment. */ export interface Selection { readonly coin: IssuedCoin; readonly fraction: bigint; } /** * The `X-PAYMENT` header budget one selection must fit (`payload.ts`). * * The store knows nothing of the wire format, so the caller that does * (`wrapFetch`) supplies the measurement: {@link sizeOf} is the exact header * a payment presenting those coins would carry, built from everything about * the payment except its coins. */ export interface HeaderBudget { /** The most bytes the header may take. */ readonly maxBytes: number; /** The header's size, in bytes, for a payment presenting exactly these coins. */ readonly sizeOf: (selections: readonly Selection[]) => number; } /** * What the store needs to know about a coin's epoch (K1), from the wallet * that knows its keysets. A store without one treats every coin as * spendable for ever and splittable, as before K1. */ export interface CoinPolicy { /** * Unix seconds after which the coin may no longer be offered to a merchant: * its epoch's spend window closes (§4). Past it the coin is refresh-only * -- {@link CoinStore.refreshable} queues it whole for a melt into the * current epoch -- and never selected. `undefined`: no limit known. */ spendableUntil(coin: IssuedCoin): number | undefined; /** * Whether a payment may split this coin. `false` for a coin of an epoch * whose issuer can no longer refresh it (`EPOCH_RETIRED`): a split would * leave change nothing returns, so such a coin is only ever spent whole. */ splittable(coin: IssuedCoin): boolean; } /** * How long before its epoch's spend window closes a coin stops being * offered, in seconds: a payment's verify, commit and payout take seconds, * and a coin the facilitator finds expired mid-payment is retired for * nothing. Five minutes. */ export declare const SPEND_WINDOW_MARGIN_SECONDS = 300; /** Construction-time defaults, all injectable for tests. */ export interface CoinStoreOptions { readonly randomBytes?: (n: number) => Uint8Array; readonly onWarning?: (message: string) => void; /** The coin's epoch, as the wallet knows it (K1). */ readonly policy?: CoinPolicy; /** * The width of the band each coin's hold is drawn from, in whole seconds. * Defaults to {@link DEFAULT_HOLD_JITTER_SECONDS}; `0` is a fixed * one-window hold. Never lowers the floor. */ readonly holdJitterSeconds?: number; } /** Per-selection options. Anything omitted falls back to the store's defaults. */ export interface SelectOptions { /** Defaults to `"strict"`. */ readonly privacy?: PrivacyMode; /** Unix seconds. Required for `strict`, which measures the hold against it. */ readonly now?: number; /** The published gauges, when the wallet has them. Omitted means "not checked". */ readonly anonymity?: AnonymityGauges; readonly onWarning?: (message: string) => void; /** * Who is about to see these coins (§7). * * Recorded against every coin selected, whatever the outcome of the payment * — a merchant that reads the payload has seen the key even if it then * refuses. Omitting it is safe but strictly weaker: the selection is still * retired, and `besteffort` has nothing to match against, so those coins * become refresh-only. */ readonly merchant?: MerchantRef; /** * How many coins this payment may present. Defaults to * {@link MAX_COINS_PER_SPEND}. * * Present so a wallet facing a facilitator that publishes a lower bound can * plan inside it, and so a test can pin the bound without building a * sixteen-coin buffer. Never *raises* the effective limit at the * facilitator, which enforces its own. */ readonly maxCoins?: number; /** * The header the selection must fit, when the caller is about to send one * (`wrapFetch` always passes it). A cover whose header would not fit is * not a cover: selection plans fewer, larger coins, and refuses with * {@link PX402HeaderBudgetError} when the pool has no cover that fits. */ readonly headerBudget?: HeaderBudget; } /** * The sum of the `k` largest of `values`: the most one payment of at most `k` * coins can carry from them (one coin split). Every amount up to it has a * cover of at most `k` coins, and no amount above it does -- which is what * makes it the capacity figure for a payment, where the plain sum is not. */ export declare function sumOfLargest(values: readonly bigint[], k: number): bigint; /** * The wallet's coin buffer. * * Holds `IssuedCoin`s — which include coin secrets — so it is secret material * in its entirety. Nothing here logs, prints, or embeds a coin in an error. */ export declare class CoinStore { private readonly byPub; private readonly randomBytes; private readonly onWarning; /** The band each coin's hold jitter is drawn from; see {@link holdJitterSeconds}. */ private readonly holdJitter; /** Distinguishes selections whose caller named no merchant; see {@link select}. */ private anonymousSelections; /** The coins' epochs (K1); see {@link CoinPolicy}. */ private policy; constructor(options?: CoinStoreOptions); /** Sets the policy the store reads each coin's epoch through (K1). */ setPolicy(policy: CoinPolicy | undefined): void; /** * Whether `record`'s epoch has closed its spend window at `now` (with * {@link SPEND_WINDOW_MARGIN_SECONDS} to spare): such a coin is never * offered, and is refresh-only. */ private pastSpendWindow; /** The policy's `spendableUntil`, for the selection tie-break. */ private untilOf; /** * Add a coin, keyed on its public key **bytes**. * * Bytes, not the decoded point: `σ` is computed over `C_p` and every * commitment binds those bytes, so two components that disagree about * whether a coin is its bytes or its point disagree about which coin is * which. `validateCoinPublic` (run at issuance) is what makes the mapping * from bytes to point injective on everything that gets here. * * Re-adding a coin that is already held is a no-op rather than a reset, so * a §6.10 recovery pass that re-derives an already-known coin cannot * resurrect value that was already spent. * * `spent` defaults to zero, correct for a coin fresh off `/withdraw` or * `/melt-reveal`. §6.10 recovery is the one caller with a nonzero value: * `recoverFromSeed` computes each coin's residual against the registry's * own `spentTotal` and refund credit, and a wallet resumed from that walk * must start each coin already debited by the difference — otherwise a * wallet recovered after any partial spend reports more spendable value * than it actually has. * * `retired` is recovery's too: a coin the registry has recorded a spend * of has had its key in a merchant's hands, so it is never offered again * (§7), even when a refund (§6.7) has credited all of it back and `spent` * nets to zero. Its residual waits in {@link refreshable} for a melt. The * coin is recorded as presented to a merchant nobody can name, which no * merchant ever matches. * * The coin's hold is fixed here, once, from its own secret: one window plus * {@link holdJitterSeconds}. Nothing about it is drawn from `randomBytes` * or kept anywhere but on the record, so the same coin added to any store * with the same band lands on the same spendable-at instant. */ add(coin: IssuedCoin, issuedAt: number, spent?: bigint, options?: { readonly retired?: boolean; }): void; /** Every coin held, spent or not. */ coins(): StoredCoin[]; get size(): number; /** What is left of one coin, in base units. Zero for a coin not held. */ residual(coinPub: Uint8Array): bigint; /** Total residual across the whole buffer, ignoring the issuance-window hold. */ totalValue(): bigint; /** * The coins this privacy mode will spend at `now`. * * Three filters, and the third is the one §7 makes normative: * * 1. residual above zero; * 2. in `strict`, past its own hold — at least {@link ISSUANCE_WINDOW_SECONDS} * old (§9.1) plus the coin's {@link holdJitterSeconds}; * 3. **no merchant has seen it**, and nothing has been spent against it. * * `besteffort` relaxes (3) in exactly one direction: a coin already * presented to `merchant`, and to nobody else, may go back to that same * merchant. It tells that merchant nothing it does not hold already. A coin * carrying a recorded spend but no named merchant — what §6.10 recovery * produces, since the registry knows the amount and not the merchant, even * when a refund has credited the amount back — is refused in **both** * modes, because there is no merchant to match it against and reuse cannot * be ruled out. */ spendable(now: number, privacy?: PrivacyMode, merchant?: MerchantRef): StoredCoin[]; /** * Coins holding residual value that {@link select} can no longer reach — * everything §6.6 refresh has to reclaim. * * This is the queue a refresh driver drains. It is not a garbage-collection * list: until these are melted their value is real, on the registry's books, * and unspendable. */ refreshable(now?: number): StoredCoin[]; /** * Residual value on coins no merchant has seen — what {@link select} can * still reach, ignoring the issuance-window hold because a coin inside the * hold becomes spendable by waiting. * * Distinct from {@link totalValue}, and the distinction is what keeps a * wallet from starving: after §7 retires a partially spent coin, its * residual is still the wallet's money (so it belongs in `totalValue`) but * it cannot pay for anything until it has been refreshed (so it does not * belong in a refill decision). A wallet that sized its refills against * `totalValue` would see a full balance, decline to withdraw, and fail * closed on every payment. */ unpresentedValue(now?: number): bigint; /** * The three-way split of {@link totalValue} at `now`, in one pass. * * Synchronous and allocation-light on purpose: the wallet's `runway()` is a * hot-path call and an agent asks it before every batch of work. The only * allocation is the unlock list, and that is built only when something is * actually held. * * Distinct from {@link unpresentedValue}, and the distinction is the whole * of the dogfooding finding: `unpresentedValue` deliberately ignores the * hold, because a refill decision must not withdraw again for coins that are * merely young. A *capacity* answer must not ignore it, because a coin * inside the hold cannot pay for anything. */ snapshot(now: number, privacy?: PrivacyMode): ValueSnapshot; /** §7's rule, as one predicate. The only place reuse is decided. */ private reachable; /** * Choose coins covering `amount` exactly, in randomized order, and record * the presentation that choice commits the wallet to. * * # Why this mutates, and why it must * * The **value** debit still waits for settlement — that is * {@link recordSpend}, and a selection that never settles leaves the * buffer's arithmetic untouched. What happens here is a different fact: * these coin public keys are about to be handed to a merchant, and that is * irreversible the moment the payload is built. If retirement waited for the * send, there would be a window — however short — in which a second * selection could pick the same coin, and §7's rule would hold only by * timing. Recorded here, in the same synchronous step as the choice, it * holds by construction: {@link spendable} cannot return a presented coin, * so no ordering of callers can produce one coin at two merchants. * * The cost is deliberate and one-directional: a selection abandoned before * it is sent retires coins nobody saw. Their value is not lost — it comes * back through §6.6 refresh, one melt later, as fresh coins. Over-retiring * costs a round trip; under-retiring costs the payment graph. * * # One payment, one header: the coin cap and the header budget * * A cover is planned inside `maxCoins` (the facilitator's cap) and, when * the caller passes one, inside `headerBudget`: x402 sends the coins in a * request header, and a cover whose header would not fit a merchant's * limit is a payment that fails before anyone reads it (`payload.ts`). A * cover that does not fit is planned again with fewer coins, which means * larger ones, until one fits. A pool with no cover that fits is * refused with {@link PX402HeaderBudgetError} **before anything is * retired** -- the wallet holds the value and cannot present it, and * sending it anyway would only retire the coins into a payment the * merchant or the facilitator refuses. * * @throws PX402NoCoinsError when the privacy mode leaves nothing spendable, * or when what it does leave cannot cover `amount`. Failing closed is the * point — see the module docs. Nothing is retired on this path. * @throws PX402HeaderBudgetError when the value is there and no cover of it * fits one payment. Nothing is retired on this path either. */ select(amount: bigint, options?: SelectOptions): Selection[]; /** * The cover {@link select} prefers, in at most `limit` coins: an exact * cover in whole coins, else whole coins and the smallest split that * closes them -- or `undefined` when no cover of `amount` exists within * `limit` coins. * * `undefined` means exactly that: {@link wholeThenPartial} finds a cover in * `limit` coins whenever the `limit` largest coins add up to `amount` * (either its greedy pass skipped a coin larger than what was left, and * that coin closes the gap, or it took the largest coins in order and the * next one does), and no cover exists when they do not. */ private coverWithin; /** * {@link select}'s refusal when the value is there and no cover fits one * payment, with the numbers that name the remedy: the fewest coins any * cover needs, the header they would make, and what the largest coins * that do fit add up to. */ private overBudget; /** * An exact cover of `amount` in **whole** coins, or `undefined`. * * # Why this is tried first * * A spend that splits a coin retires the residual (§7: one coin, one * merchant), and the only way back is a §6.6 melt followed by a fresh §9.1 * issuance hold. So a partial fraction is not a cheaper spend than a few * more whole coins — it is the same spend plus a round trip and a minute. * Dogfooding measured the difference on the original six-rung ladder: a 20 * USDC buffer paying $2.50 a call ran dry after four calls, because every * call landed its fraction on a $2.56 or $10.24 coin, while $2.50 had an * exact cover (3×$0.64 + 3×$0.16 + 2×$0.04 + 2×$0.01) that leaves nothing * behind. On the seven-rung $0.001 launch ladder that cover is seven coins * (2×$1.024 + $0.256 + 3×$0.064 + $0.004). * * # Whole means `spent === 0` * * A coin carrying a spend is one `besteffort` may return to its own * merchant, but presenting a partially spent coin is precisely what §7 * forbids in general, so it never joins a cover. It stays available to * {@link fewestCoins}, which is the path that already carries that warning. * * # Greedy largest-first, and nothing cleverer * * The launch ladder is canonical — each rung divides the next — so taking as * many of the largest affordable rung as the pool holds is the minimum-coin * cover whenever a cover exists. There is no subset search here and there * should not be: a wallet buffer is caller-supplied in size, and an * exponential search over it on the spend path is a denial of service the * caller inflicts on itself. */ private exactCover; /** * The first fallback: whole coins, then **one** split on the smallest coin * that closes the gap -- at most `wholeBudget` whole coins plus that one. * * Whole coins largest-first, then one partial fraction on the smallest coin * that can close what is left. Two properties follow, and both were absent * from the shuffle-and-take-in-order policy this replaces: * * - **exactly one coin is split**, so exactly one coin's residual goes into * a refresh hold, rather than one per coin the shuffle happened to * over-shoot on; * - **the split lands on the smallest coin that fits**, so the residual * retired is the least the buffer can retire — a $2.50 spend with no * exact cover takes $0.452 out of a $1.024 coin rather than $1.596 out of * a $4.096 one. * * The whole-coin phase stops one coin short of the cap to leave room for * that partial. If no coin can then close the gap, the wallet cannot * present this amount from this pool in that many coins (see * {@link coverWithin}), and {@link select} refuses rather than sending a * payment the merchant's header limit or the facilitator's coin cap would * refuse after the coins were retired. A buffer of nothing but $0.001 * coins genuinely cannot pay $2.50 inside fifteen coins. */ private wholeThenPartial; /** * §7: `besteffort` "MAY spend an unrefreshed coin only at the merchant it * was already presented to, and MUST warn". * * The warning is the disclosure that this payment is linkable to an earlier * one *at that merchant*. It is not a mode change and it never suppresses * the spend — the same discipline as the §9.1 crowd-size warning. */ private warnIfReturning; /** * Retire every selected coin against the merchant that is about to see it. * * A caller that named no merchant gets a placeholder that matches nothing, * ever — so the coins are retired outright rather than becoming reusable by * default. Re-presenting to the same merchant is idempotent, which is what * lets `besteffort` spend a coin's residual at that merchant more than once * without accumulating entries that would then fail the "presented to * exactly one" test. */ private present; /** * The fail-closed error, with the two counts that name the remedy: waiting * out the issuance-window hold, or refreshing retired residual (§6.6). */ private noCoins; /** * Commit a settled spend against the buffer. * * Called only after the payment succeeded. Refuses to take a coin past its * face value: the registry enforces `spentTotal(C_p) + f ≤ denomValue` on * its side (`INSUFFICIENT_VALUE`), and a local view that drifted above it * would keep proposing spends that can only be rejected. */ recordSpend(selections: readonly Selection[]): void; /** * Set one held coin to the registry's books, `GET /spent` read whole: what * is left is `face − spent + refundCredit`, exactly the residual the * registry's melt reserve locks. A coin this store does not hold is * ignored. * * What a running wallet does once it learns a payment was refunded * (§6.7): the registry credits each coin its share and never lowers * `spent`, so without this the local debit keeps the refunded value out of * {@link totalValue}, and a melt for the old residual is refused * `INSUFFICIENT_VALUE` on every attempt. The registry's figure replaces the * local one either way, since it is the one a melt is held to. * * The coin is melt-only from here, whatever the credit: a coin the * registry has recorded any spend of has had its key in a merchant's hands * (§7), and what is left of it is no longer what the registry lets it * spend -- a refunded coin's credit melts, it never spends. So it is * recorded against a merchant nobody can name too, as {@link add}'s * `retired` does, which also takes it off `besteffort`'s same-merchant * allowance. */ setRegistrySpent(coinPub: Uint8Array, standing: { readonly spent: bigint; readonly refundCredit: bigint; }): void; /** * Write a melted coin off in full (§6.6). * * A melt reserve locks the **whole** residual at the registry and never * gives it back — `MELT_TTL` bounds unconfirmed session state, not the * value — so once `/melt-reveal` has returned the change, the parent coin is * worth exactly zero and the change coins are its replacement. Debiting it * to its face value rather than deleting it keeps {@link add}'s * already-held check able to refuse a §6.10 recovery pass that re-derives * it, which would otherwise resurrect value the registry has already taken. */ markMelted(coinPub: Uint8Array): void; /** * §9.1's crowd-size disclosure. Warns below **either** gauge and never * changes behaviour: strict stays strict, and a wallet below the floor * keeps working rather than silently falling back to timing-linkable * spending. */ private warnIfBelowFloor; /** * Fisher-Yates over a copy, with indices drawn by rejection sampling from * the injected byte source. * * Rejection sampling rather than `% (i + 1)`: the modulo is biased toward * low indices whenever the range does not divide the byte space, and a * biased shuffle is a partially predictable spend order — which is the * property this function exists to remove. */ private shuffled; /** A uniform index in `[0, bound)`, unbiased. */ private randomIndex; }