/** * The reads a wallet needs from the chain, and the default §6.10 recovery * sources, over public endpoints only. * * # Why the SDK ships these * * {@link RecoverySources} is a port, and it stays one: a wallet may read the * chain through its own node, or the issuer's log through a mirror. But a * wallet that restarts must recover (a second `px402.open` of a used seed * re-derives counters it already spent, §6.13), and recovery that only works * once the developer has written four read ports is recovery most developers * would skip. So the SDK builds the ports from what it already knows: the * issuer and registry URLs of its {@link IssuerClient}, and a JSON-RPC * endpoint for the reserve contract. * * # What each read shows, and to whom * * - **The issuer's `/log`, read whole.** Every issuance and melt record ever * published; the wallet finds its own locally. Reading all of it names * nothing of yours. * - **The chain:** `reserves(addr)` for each reserve index the seed derives * (until `RESERVE_GAP_LIMIT`, 20, in a row were never funded), and the * `Deposit` / `BalanceReclaimed` logs of the funded ones from the * deployment block, `logBlockRange` blocks per `eth_getLogs`, both events * in one call. The RPC provider sees which reserve addresses you ask about. * - **The registry's spent total for each coin found** (`GET /spent/:C_p`), * with the refund credit beside it: a refunded coin's value comes back * through its melt. This names your coins to the registry, together, from * your network address. It is not read from the registry's public `/log` * because that log lists a spend only once a spend root covering it is * committed -- every 12 hours by default on mainnet -- so a coin spent * since then would come back as unspent and the wallet's next payment with * it would be refused. Route the {@link IssuerClient}'s `fetch` through a * proxy you control. * * Nothing here opens a socket of its own: every request goes through the * `fetch` given (the global `fetch` when none is). * * # The scan checkpoint * * The log scan is the part of recovery that grows with the chain: one * `eth_getLogs` per `logBlockRange` blocks since the reserve's deployment * block, on every start. On Base, at 500 blocks a call and a block every 2 * seconds, that is 86 more calls a day. A {@link RecoveryCheckpoint} * lets the next recovery start where this one's scan left off: per reserve, * the last block the scan fully read, that block's hash, and the two sums up * to it. * * It is trusted for exactly one thing, where to start reading logs (and so * the sums before that point, which feed only `wallet.reconcile()`'s chain * totals). Which reserves are funded is still read from `reserves(addr)`; * the coins, the withdraw counter and the spent totals still come from the * issuer's log and the registry, never from the checkpoint. And it is used * only when it is plausible for this chain: a checkpoint that does not parse, * names another chain id, reserve contract or deployment block, points past * the chain head, or whose block's hash is not the hash that block has on * this chain now (a reorganisation, or another chain under the same id) is * ignored with a warning, and that reserve is read from the deployment block. * A checkpoint records only a block {@link RECOVERY_CHECKPOINT_CONFIRMATIONS} * below the head, and only when that block's hash was the same before and * after the scan read up to it. */ import { type FetchLike, type IssuerClient } from "./client.js"; import { type KeysetCommitmentReader } from "./commitment.js"; import { type RecoveryProgress, type RecoverySources, type ReserveActivity } from "./recover.js"; /** * Blocks per `eth_getLogs` when none is configured: Base's public endpoint, * `mainnet.base.org`, refuses a wider window (`eth_getLogs is limited to a * 500 range`, measured 2026-10-05). A provider that refuses even this is met by halving * ({@link JsonRpcChain}). */ export declare const DEFAULT_LOG_BLOCK_RANGE = 500n; /** How long one JSON-RPC call may take before it fails, in milliseconds. */ export declare const DEFAULT_RPC_TIMEOUT_MS = 15000; /** * How far below the chain head a block must be before a checkpoint records * it. 1,000 blocks is about 33 minutes on Base (past its L1 finality) and * 3.3 hours on Ethereum. A deeper reorganisation is still caught: the * recorded block's hash is compared before the checkpoint is used. */ export declare const RECOVERY_CHECKPOINT_CONFIRMATIONS = 1000n; /** The version {@link recoveryCheckpointToJson} writes and {@link parseRecoveryCheckpoint} reads. */ export declare const RECOVERY_CHECKPOINT_VERSION = 1; /** Where one reserve's `Deposit` / `BalanceReclaimed` scan reached. */ export interface ReserveScanCoverage { /** The reserve address, `0x` lowercase. */ readonly reserve: string; /** The last block whose logs {@link deposits} and {@link reclaims} count, from the deployment block on. */ readonly block: bigint; /** That block's hash, `0x` lowercase: the chain the sums were read from. */ readonly blockHash: string; /** `Σ Deposit` amounts to this reserve, deployment block to {@link block}. */ readonly deposits: bigint; /** `Σ BalanceReclaimed` amounts out of it, over the same blocks. */ readonly reclaims: bigint; } /** * Where a recovery's log scan reached, so the next one need not read the * chain again from the deployment block. See the module docs for what it is * trusted with (where to start reading logs, and nothing else) and when it * is ignored. */ export interface RecoveryCheckpoint { readonly version: typeof RECOVERY_CHECKPOINT_VERSION; readonly chainId: number; /** The `PX402Reserve` address, `0x` lowercase. */ readonly reserveContract: string; /** The block the scan counted from. */ readonly deployBlock: bigint; readonly reserves: readonly ReserveScanCoverage[]; } /** What a checkpoint must match to be used: the wallet's own chain configuration. */ export interface CheckpointScope { readonly chainId: number; readonly reserveContract: string; readonly deployBlock: bigint; } /** A saved checkpoint, read: the checkpoint, or why it is not used. */ export type CheckpointReading = { readonly checkpoint: RecoveryCheckpoint; readonly refused?: undefined; } | { readonly checkpoint?: undefined; readonly refused: string; }; /** The text a checkpoint is saved as: JSON, with block numbers and amounts as decimal strings. */ export declare function recoveryCheckpointToJson(checkpoint: RecoveryCheckpoint): string; /** * Read a saved checkpoint for this wallet's chain, never throwing. Refused, * with the reason, when it is not JSON, not a version-1 checkpoint, for * another chain id, reserve contract or deployment block, or holds an entry * that is malformed, repeated, or before the deployment block. What it * cannot check without the chain (the head, the block hashes) the scan * checks before it uses an entry ({@link JsonRpcChain}). */ export declare function parseRecoveryCheckpoint(text: string, scope: CheckpointScope): CheckpointReading; /** Where a {@link JsonRpcChain} reads the reserve contract. */ export interface JsonRpcChainOptions { /** An Ethereum JSON-RPC endpoint for the reserve's chain. Never echoed into an error: it may carry an API key. */ readonly rpcUrl: string; /** The `PX402Reserve` address, `0x`-prefixed. */ readonly reserveContract: string; /** The reserve's deployment block: where a log scan starts. Needed only by {@link JsonRpcChain.reserveActivity}. */ readonly deployBlock?: bigint; /** * Blocks per `eth_getLogs`. Defaults to {@link DEFAULT_LOG_BLOCK_RANGE}. A * window the node refuses (a JSON-RPC error, not a rate limit) is halved * and asked again, down to one block, with a warning naming the width that * worked. */ readonly logBlockRange?: bigint; /** The `fetch` the calls go through. Defaults to the global `fetch`. */ readonly fetch?: FetchLike; /** Defaults to {@link DEFAULT_RPC_TIMEOUT_MS}. */ readonly timeoutMs?: number; /** * Where earlier scans reached ({@link RecoveryCheckpoint.reserves}, read * with {@link parseRecoveryCheckpoint} against this chain). An entry is * used only after its block is found at or below the head with the hash * it recorded; otherwise that reserve is read from {@link deployBlock}. */ readonly checkpoint?: readonly ReserveScanCoverage[]; /** How far below the head a block must be before {@link JsonRpcChain.scanCoverage} records it. Defaults to {@link RECOVERY_CHECKPOINT_CONFIRMATIONS}. */ readonly checkpointConfirmations?: bigint; /** Told about each log window read (`deposit-logs`). A hook that throws is ignored. */ readonly onProgress?: (progress: RecoveryProgress) => void; /** Told when a checkpoint entry is not used, and when the node refused a window as too wide. */ readonly onWarning?: (message: string) => void; } /** * The reserve contract over plain JSON-RPC: the three reads a wallet needs * (its withdraw nonce, the keyset commitment, and for recovery a reserve's * deposit history), and nothing that writes. * * What it reads it trusts the RPC provider for, exactly as a wallet that * passed its own readers would: use a provider you trust, or your own node. */ export declare class JsonRpcChain { private readonly options; private readonly fetchImpl; /** Blocks per `eth_getLogs`: the configured width, halved each time a node refuses one. */ private span; private readonly saved; private readonly covered; constructor(options: JsonRpcChainOptions); private rpc; private call; /** `reserves(addr)` is `(balance, nonce, createdAt)`. */ private reserve; /** `reserves(addr).nonce`: the reserve's next withdraw nonce. Nonzero once it has withdrawn. */ reserveNonce(reserveAddr: Uint8Array | string): Promise; /** `keysets(epochId)`: the keyset id the reserve committed for an epoch (spec §4). */ readonly keysetCommitment: KeysetCommitmentReader; /** * What §6.10 recovery needs to know about one reserve: `undefined` when it * was never funded, else the sums of its `Deposit` and `BalanceReclaimed` * events. `createdAt` (word 2 of `reserves(addr)`) is set by the first * deposit, so an address never used costs one `eth_call` and no log scan. * A funded one is read from the deployment block, or from a checkpoint * entry that holds up (see the module docs). */ reserveActivity(reserveAddr: Uint8Array): Promise; /** * Whether a reserve was ever funded: `createdAt` (word 2 of * `reserves(addr)`), set by its first deposit. One `eth_call`, no log scan * -- all a recovery needs to know to look for coins (`recover.ts`). */ reserveFunded(reserveAddr: Uint8Array): Promise; /** * Where this instance's scans reached, one entry per reserve scanned, for * the next recovery's checkpoint. An entry carries a block at least * {@link JsonRpcChainOptions.checkpointConfirmations} below the head the * scan read, or the checkpoint entry it started from when the chain has not * grown that far past it. Empty before any scan, and for a chain younger * than the confirmations since the deployment block. */ scanCoverage(): readonly ReserveScanCoverage[]; private warn; private blockNumber; /** The hash of block `n` on this chain, `0x` lowercase; `undefined` when the node has no such block. */ private blockHash; /** Why a checkpoint entry cannot be used against this chain now, or `undefined` when it can. */ private unusable; /** One reserve's `Deposit` and `BalanceReclaimed` sums, from the deployment block or a checkpoint. */ private scan; /** * One `eth_getLogs` from `from`, both events in one filter, at most * {@link span} blocks and never past `to`, added to `sums`. Returns the * last block read. A refusal halves the width for this and every later * window, down to one block. */ private window; } /** What {@link publicRecoverySources} needs. */ export interface PublicRecoverySourcesParams { /** The issuer (its `/log`) and, through its `registryUrl`, the registry (`/spent`). */ readonly issuer: IssuerClient; /** The chain read: `reserveActivity`, e.g. a {@link JsonRpcChain} with a `deployBlock`. */ readonly chain: Pick; /** Told how much of the issuer's log has been read (`issuer-log`). A hook that throws is ignored. */ readonly onProgress?: (progress: RecoveryProgress) => void; } /** * The default {@link RecoverySources}: the issuer's whole public log, the * chain, and the registry's spent totals. See the module docs for what each * read shows and to whom. * * The log is read once, here, and indexed locally; malformed records are * skipped, because recovery verifies every signature it uses (`recover.ts`) * and a record that does not parse could not have been one of yours. */ export declare function publicRecoverySources(params: PublicRecoverySourcesParams): Promise;