/** * When a wallet melts (§6.6), and why never at the head of a spend (v3 * §25.2). * * # Why refresh runs after the payment * * Refresh used to run at the head of the next payment: `wrapFetch` melted the * residual the previous payment had retired, then built and sent the new * payment. The melt names its coin -- to the registry, in the issuer's * database, and in the issuer's public `/log` with a timestamp -- and that * coin already names the payment that spent it. The next payment's commit then * landed at the registry the same second as the melt, so anyone reading the * two logs could join the two payments as one wallet's. Refresh exists to make the second * payment unlinkable to the first; timed that way it re-linked them. * * # The rule * * - **After the payment that made the residual, in the background.** A * payment that leaves residual schedules its melt when it ends, at a delay * drawn uniformly from `[0, window)` -- `window` being the longest §9.1 hold * a coin carries, one issuance window plus the jitter band. A melt timed * after its own payment reveals nothing new: its coin already names that * payment. * - **Never beside a spend.** A melt and a spend are never closer than * {@link MELT_SPEND_SEPARATION_SECONDS} on the wallet's clock, either way * round. A melt that comes due while a payment is in flight, or inside the * separation after one, is drawn again; a payment that begins while a melt * is in flight waits for it, then out the separation. Only the rare overlap * costs a payment anything. * - **Leftovers at boot.** Residual an earlier process left unmelted is melted * by `wallet.ready()`, after its hold logic and before the first payment -- * never inside a payment -- and the separation keeps the first payment out of * that melt's second. * - **When only the residual covers what `ready()` waits for**, it is melted * then rather than at its drawn moment, still clear of every spend: the * fresh coins' own hold keeps the payment that waits on them at least an * issuance window from the melt, and waiting for the drawn moment first * would add up to a second window to that wait for nothing. * - **The timer never keeps a process alive.** Agents make a handful of calls * and exit; a pending melt is `unref`'d, and what it did not reach is melted * at the next boot. The separation's own wait is an ordinary timer, because * a payment is waiting on it. * * Refreshed coins keep their §9.1 hold like any other new coin, so a melt * funds later payments and never the one in flight. */ import { type SpendLifecycle } from "./fetch.js"; /** * The least gap between a melt and a spend, either way round, in whole * seconds of the wallet's clock. * * Three, not one: the clock is in whole seconds, so a gap measured as `s` * may be as little as `s − 1` real seconds, and the issuer's and the * registry's own clocks -- whose timestamps an observer compares -- may each * sit a second apart from the wallet's. Three keeps the two events in * different seconds on any of them. */ export declare const MELT_SPEND_SEPARATION_SECONDS = 3; /** * How the scheduler waits. Injectable because the wallet's clock is: a test * that pins `now` must also own the timers, or a delay would run on wall time * against a clock that never moves. */ export interface MeltTimers { /** * Run `fn` after `ms` milliseconds in the background, returning a handle * for {@link cancel}. Must not keep the process alive. */ schedule(fn: () => void, ms: number): unknown; /** Cancel a {@link schedule}d call that has not run. */ cancel(handle: unknown): void; /** Resolve after `ms` milliseconds. A payment waits on this, so it keeps the process alive. */ sleep(ms: number): Promise; } /** `setTimeout`, with the background call `unref`'d where the runtime supports it. */ export declare const SYSTEM_MELT_TIMERS: MeltTimers; /** Construction-time wiring for {@link MeltScheduler}. */ export interface MeltSchedulerOptions { /** One melt pass. Expected never to throw; a rejection is reported and treated as a pass that melted nothing. */ readonly melt: () => Promise; /** Whether anything is waiting to be melted. */ readonly pending: () => boolean; /** Unix seconds: the wallet's clock. */ readonly now: () => number; readonly randomBytes: (n: number) => Uint8Array; /** Background delays are drawn from `[0, windowSeconds)` seconds. */ readonly windowSeconds: number; /** Defaults to {@link MELT_SPEND_SEPARATION_SECONDS}. */ readonly separationSeconds?: number; /** Defaults to {@link SYSTEM_MELT_TIMERS}. */ readonly timers?: MeltTimers; readonly onWarning?: (message: string) => void; } /** * The wallet's one melt timetable: the {@link SpendLifecycle} `wrapFetch` * reports its payments to, and the gate every melt the wallet starts goes * through. See the module docs for the rule it keeps. */ export declare class MeltScheduler implements SpendLifecycle { private readonly options; private readonly timers; private readonly separation; private handle; private dueAt; private readonly melting; private spendsInFlight; /** {@link meltNow}s waiting for the payments in flight to end. */ private readonly idleWaiters; private started; private lastSpendAt; private lastMeltAt; constructor(options: MeltSchedulerOptions); /** How many payments this process has begun. Zero means the wallet is still booting. */ get spendsStarted(): number; /** * When the background melt is due, in wallet-clock seconds (rounded up), * or `undefined` when none is scheduled. */ get scheduledFor(): number | undefined; /** Whether a melt is running now. */ get isMelting(): boolean; /** * A payment is about to begin. Never melts: it waits for a melt already in * flight, then out the separation since it finished. */ beforeSpend(): Promise; /** A payment has ended, settled or not. If it left residual, its melt is scheduled now. */ afterSpend(): void; /** * Residual appeared outside a payment: a refund credited coins the wallet * already retired (§6.7). Its melt is armed as a payment's is, at a delay * drawn from the window and clear of every spend. A melt timed after the * refund reveals nothing new: the coins already name the refunded payment. */ residualReturned(): void; /** * Melt what is pending now, clear of every spend: `wallet.ready()`'s boot * melt, and its melt of residual only a melt can turn into the amount it * was asked for. Waits for a payment in flight to end and out the * separation after it; joins a melt already running instead of starting a * second; does nothing with nothing pending. */ meltNow(): Promise; /** * Run a melt the caller asked for itself (`wallet.refresh()`), counted as * a melt so the next spend keeps the separation from it. */ track(melt: () => Promise): Promise; /** Arm the background melt if something is pending and nothing is armed or running. */ private ensureScheduled; private arm; private cancelTimer; private fire; /** One melt, counted while it runs; never rejects. */ private run; /** Count a melt while it runs; when it ends, arm the next one if anything is still pending. */ private register; /** `[0, windowSeconds)` seconds, in milliseconds, from the injected byte source. */ private drawDelayMs; private warn; }