/** * Every keyset a wallet holds coins of (K1): the epochs it has used, each * checked against the reserve's `keysets(epochId)`. * * # Why a wallet holds more than one keyset * * An issuer starts a new key epoch (§4: a 30-day withdraw window, coins * spendable for 90 days from its start, refresh-only for 30 more), and from * then on withdraws and mints change under the new epoch. Coins of the old * one do not stop being money: the registry and the facilitator verify each * coin against the keyset its `denomId` names, and the issuer melts a coin of * any epoch it still holds into change of the newest. So a wallet that held * one keyset for its life -- as this SDK did until K1 -- had to be reopened * with the old keyset to spend old coins. A ring holds them all: * * - **withdrawals** use the newest epoch whose spend window is open * ({@link KeyRing.withdrawKeyset}) -- the rule the issuer signs by: the * newest epoch the reserve commits; * - **spending** draws coins of any epoch held, each presented with its own * keyset ({@link KeyRing.byDenomId}); * - **refresh** melts a coin of any epoch into change of the withdraw epoch, * which is how old coins migrate -- no step of the wallet's own. * * # An epoch the issuer can no longer refresh * * An issuer that lost an epoch's keys (its database, and a fresh issuer * began the next epoch) cannot check that epoch's coins and answers a melt of * one `EPOCH_RETIRED`. The ring records that ({@link KeyRing.markRetired}) -- * up front, when the issuer's `/keys` lists its epochs and omits this one, * or at the first refusal -- and the wallet then spends that epoch's coins * whole and never splits them. */ import { type KeysetStatus } from "./client.js"; import { type Keyset } from "./denom.js"; /** How a keyset in the ring was shown to be the one the reserve commits (§4). */ export type KeysetVerificationResult = "onchain" | "caller-verified-onchain" | "unchecked"; /** One keyset a wallet holds. */ export interface HeldKeyset { readonly keyset: Keyset; readonly epochId: bigint; /** `keccak256(canonicalBytes(keyset))`, recomputed. */ readonly keysetId: Uint8Array; /** The same, `0x`-prefixed lowercase hex: what a payload's `keysetId` carries. */ readonly keysetIdHex: string; /** Its smallest rung: the unit a fee-bearing total is rounded up to (v3 §25.1). */ readonly smallestDenomination: bigint; /** * What the issuer's `/keys` labelled it, when the issuer listed it. * Advisory only. `undefined`: the issuer predates K1's list, or this is a * copy the caller kept of an epoch the issuer does not list. */ readonly issuerStatus: KeysetStatus | undefined; /** Whether {@link KeyRing} confirmed it on the reserve, or was told it was. */ readonly verification: KeysetVerificationResult; } /** What one entry of a ring is built from. */ export interface KeyRingEntry { readonly keyset: Keyset; readonly issuerStatus?: KeysetStatus | undefined; readonly verification?: KeysetVerificationResult; } /** * The keysets one wallet holds, oldest epoch first, each resolvable by any * of its denomination ids. * * Holds public keys only; nothing here is secret. */ export declare class KeyRing { private readonly held; private readonly byDenom; private readonly byId; /** Keyset ids (`0x` hex) whose coins the issuer can no longer refresh. */ private readonly retired; constructor(entries: readonly (KeyRingEntry | Keyset)[]); /** * Adds keysets not held yet -- an epoch the issuer started since the * wallet opened ({@link Wallet.syncKeysets}) -- and returns how many were * new. A keyset already held is left as it is. * * @throws RangeError when a new keyset would share a denomination id with * one held, before anything is added. */ add(entries: readonly (KeyRingEntry | Keyset)[]): number; /** How many keysets are held. */ get size(): number; /** Every keyset held, oldest epoch first. */ entries(): readonly HeldKeyset[]; /** The keysets alone, oldest epoch first. */ keysets(): readonly Keyset[]; /** The newest epoch held, whatever its windows. */ newest(): HeldKeyset | undefined; /** The keyset a denomination id belongs to, or `undefined` for none held. */ byDenomId(denomId: string): HeldKeyset | undefined; /** A held keyset by its `0x`-prefixed id. */ byKeysetId(idHex: string): HeldKeyset | undefined; /** * The keyset this wallet withdraws, and mints change, under at `now`: the * newest held whose spend window is open and whose coins the issuer can * still refresh -- the issuer's own rule, since every keyset here was * checked against the reserve (§4) and the issuer signs under the newest * the reserve commits. `undefined` when none qualifies. */ withdrawKeyset(now: number): HeldKeyset | undefined; /** Record that the issuer can no longer refresh this keyset's coins. */ markRetired(idHex: string): void; /** Whether the issuer can no longer refresh this keyset's coins. */ isRetired(idHex: string): boolean; }