/** * Keeping the receipt chain, and the recovery checkpoint, across restarts. * * `wallet.receipts.export("json")` writes the chain; `receiptsFromJson` reads * it back into the shape `px402.recover({ receipts })` verifies on load, * together with the recourse of any bridge payment still being pursued. The * file is your purchase history: what you paid for, to whom, and when. Keep * it on the agent's machine, private, out of git, and never send it anywhere. * * `mode: 0o600` makes a new file readable by your user alone on Linux and * macOS. Windows ignores it: there, keep the files in a folder under your * user profile (`%USERPROFILE%`), which by default only you, SYSTEM and * administrators can read (check with `icacls `), and not in a * shared or synced folder. */ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"; import { receiptsFromJson, type StoredReceipt, type Wallet, type WalletState, type WalletStore } from "px402"; /** Write the whole chain, atomically: a crash mid-write leaves the previous file. */ export function saveReceipts(path: string, wallet: Wallet): void { writeFileSync(`${path}.tmp`, wallet.receipts.export("json"), { mode: 0o600 }); renameSync(`${path}.tmp`, path); } /** The saved chain, verified when the wallet loads it; empty on a first run. */ export function loadReceipts(path: string): StoredReceipt[] { if (!existsSync(path)) { return []; } // The inverse of export("json"), a bridge payment's recourse included. return receiptsFromJson(readFileSync(path, "utf8")); } /** Where the recovery checkpoint lives: beside the receipt file. */ export function checkpointFileFor(receiptsFile: string): string { return receiptsFile.replace(/(\.json)?$/, ".checkpoint.json"); } /** * Where the last recovery's log scan reached, as it saved it. A missing or * unreadable file is only a slower start: recovery then reads the reserve's * logs from the deployment block. The SDK checks whatever is here (its chain, * its reserve contract, its block's hash on the chain now) before it uses it. */ export function loadCheckpoint(path: string): string | undefined { try { return readFileSync(path, "utf8"); } catch { return undefined; } } /** Save where this recovery's log scan reached, atomically. Public data, but it names your reserve. */ export function saveCheckpoint(path: string, wallet: Wallet): void { const checkpoint = wallet.recoveryCheckpoint(); if (checkpoint === undefined) { return; } writeFileSync(`${path}.tmp`, checkpoint, { mode: 0o600 }); renameSync(`${path}.tmp`, path); } /** * The drop-in's store (`wrapFetchWithPayment`, `createWallet`) over the same * two files: the receipt chain, and the checkpoint beside it. */ export function walletStore(receiptsFile: string): WalletStore { const checkpointFile = checkpointFileFor(receiptsFile); const write = (path: string, text: string): void => { writeFileSync(`${path}.tmp`, text, { mode: 0o600 }); renameSync(`${path}.tmp`, path); }; return { load: (): WalletState => { const receipts = existsSync(receiptsFile) ? readFileSync(receiptsFile, "utf8") : undefined; const checkpoint = loadCheckpoint(checkpointFile); return { ...(receipts === undefined ? {} : { receipts }), ...(checkpoint === undefined ? {} : { checkpoint }), }; }, save: (state) => { if (state.receipts !== undefined) { write(receiptsFile, state.receipts); } if (state.checkpoint !== undefined) { write(checkpointFile, state.checkpoint); } }, }; }