Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

25.5 KB
Raw Blame
// @ts-check
// api/_lib/economy-ledger.js
//
// The financial book of record for the economy master funding wallet
// (api/_lib/economy-master.js). Every sweep appends an append-only, hash-chained
// batch of rows to `economy_master_ledger`: one `transfer` row per SOL movement
// (with the signature, a running balance, and the USD value at the instant of the
// transfer), one `failed`/`blocked` row per rejected attempt, and one `sweep`
// heartbeat summary — so there is a durable, ordered, tamper-evident record of
// what left the wallet, to whom, when, why, and what it was worth.
//
// Tamper-evidence: each row's `entry_hash` = sha256(canonical fields | prev_hash),
// so the head commits the entire history (a Merkle-equivalent). Editing or
// deleting any historical row breaks the chain from that point; verifyChain()
// and the economy-reconcile cron detect the break and the gap.
//
// This module never throws into the money path: a DB stall drops the ledger batch
// (logged + surfaced), it never blocks or reverts a transfer that already landed.

import { createHash } from 'node:crypto';
import { sql } from './db.js';
import { withDbRetry } from './db-retry.js';
import { solPriceUsd } from './sol-price.js';

let _schemaReady = false;

/** Lazily create the ledger table (mirror of the migration) so a fresh env works. */
export async function ensureSchema() {
	if (_schemaReady) return;
	await withDbRetry(() => sql`
		CREATE TABLE IF NOT EXISTS economy_master_ledger (
			id                bigserial   PRIMARY KEY,
			seq               bigint      NOT NULL,
			ts                timestamptz NOT NULL,
			run_id            uuid,
			master_pubkey     text        NOT NULL,
			event             text        NOT NULL,
			target_name       text,
			target_pubkey     text,
			lamports          bigint,
			sol               numeric(20,9),
			sol_usd           numeric(20,6),
			usd_value         numeric(20,6),
			tx_signature      text,
			reason            text,
			master_sol_before numeric(20,9),
			master_sol_after  numeric(20,9),
			reserve_sol       numeric(20,9),
			run_cap_sol       numeric(20,9),
			per_topup_max_sol numeric(20,9),
			network           text        NOT NULL DEFAULT 'mainnet',
			detail            jsonb,
			prev_hash         text,
			entry_hash        text        NOT NULL
		)
	`);
	await withDbRetry(() => sql`
		CREATE UNIQUE INDEX IF NOT EXISTS economy_master_ledger_seq_idx
			ON economy_master_ledger (master_pubkey, seq)
	`);
	await withDbRetry(() => sql`
		CREATE INDEX IF NOT EXISTS economy_master_ledger_sig_idx
			ON economy_master_ledger (tx_signature)
	`);
	_schemaReady = true;
}

function sha256hex(s) {
	return createHash('sha256').update(s).digest('hex');
}

/**
 * Canonical hash of a ledger row given the prior row's hash. The field set is
 * fixed and order-stable — it commits the position (seq, ts), the movement
 * (event, target, lamports, signature), the resulting balance, and the prior
 * hash. verifyChain() recomputes exactly this, so any of these fields changing
 * after the fact is detectable.
 * @param {string} prevHash
 * @param {object} r
 * @returns {string}
 */
export function hashEntry(prevHash, r) {
	const payload = [
		r.seq,
		r.ts,
		r.master_pubkey,
		r.event,
		r.target_pubkey || '',
		r.lamports == null ? '' : String(r.lamports),
		r.tx_signature || '',
		r.reason || '',
		// master_sol_after is numeric(20,9). Canonicalize to a fixed 9-decimal
		// string so the WRITE side (which hashes the JS number, e.g. 0.30223827)
		// and the VERIFY side (which reads the DB's scale-9 string "0.302238270")
		// produce the SAME hash. Before this, `String(value)` dropped the JS
		// number's trailing zeros while Postgres kept them, so every row's content
		// hash mismatched — verifyChain broke at the first row and stopped, masking
		// it as a single "tamper at seq 5". Number().toFixed(9) is stable for both
		// a JS number and the DB decimal string.
		canonicalSol9(r.master_sol_after),
		prevHash || '',
	].join('|');
	return sha256hex(payload);
}

// Fixed 9-decimal canonical form for a SOL amount that round-trips a JS number
// and a Postgres numeric(_,9) string to the same string. Empty for null.
function canonicalSol9(v) {
	if (v == null || v === '') return '';
	const n = Number(v);
	return Number.isFinite(n) ? n.toFixed(9) : String(v);
}

function round9(n) {
	return Math.round(Number(n) * 1e9) / 1e9;
}
function round6(n) {
	return Math.round(Number(n) * 1e6) / 1e6;
}

/** Current chain head (highest seq) for a master, or null before genesis. */
export async function getHead(masterPubkey) {
	const rows = await withDbRetry(() => sql`
		SELECT seq, entry_hash FROM economy_master_ledger
		WHERE master_pubkey = ${masterPubkey}
		ORDER BY seq DESC LIMIT 1
	`);
	return rows[0] ? { seq: Number(rows[0].seq), entryHash: rows[0].entry_hash } : null;
}

/**
 * Chain a batch of built rows onto the current head and insert them. One retry
 * if a concurrent writer took our seq. Shared by every record* entry point so
 * the chaining, the conflict retry, and the fail-soft contract are defined once.
 *
 * @param {{ masterPubkey: string, runId: string, rows: Array<object>, label: string }} args
 * @returns {Promise<{written:number, seqFrom:number|null, seqTo:number|null, headHash:string|null, skippedWrite?:string}>}
 */
async function appendChain({ masterPubkey, runId, rows, label }) {
	for (let attempt = 0; attempt < 2; attempt++) {
		const head = await getHead(masterPubkey);
		const seq = head ? head.seq : 0;
		let prevHash = head ? head.entryHash : '';
		const chained = rows.map((r, i) => {
			const row = { ...r, seq: seq + i + 1, prev_hash: prevHash, run_id: runId };
			row.entry_hash = hashEntry(prevHash, row);
			prevHash = row.entry_hash;
			return row;
		});
		try {
			for (const row of chained) await insertRow(row);
			return {
				written: chained.length,
				seqFrom: chained[0].seq,
				seqTo: chained[chained.length - 1].seq,
				headHash: prevHash,
			};
		} catch (err) {
			const conflict = /duplicate key|unique/i.test(err?.message || '');
			if (conflict && attempt === 0) continue; // re-read head and rebuild the chain
			console.error(`[economy-ledger] ${label} write failed`, { runId, error: err?.message });
			return { written: 0, seqFrom: null, seqTo: null, headHash: null, skippedWrite: err?.message || 'write_failed' };
		}
	}
	return { written: 0, seqFrom: null, seqTo: null, headHash: null, skippedWrite: 'seq_conflict' };
}

/**
 * Append one sweep's worth of events to the ledger as a single hash-chained
 * batch. Pure-ish orchestration around DB writes; returns what it wrote.
 *
 * @param {object} args
 * @param {string} args.runId
 * @param {string} args.masterPubkey
 * @param {'mainnet'|'devnet'} [args.network]
 * @param {object} args.result   the object returned by sweepTopUps()
 * @param {{reserveSol?:number, runCapSol?:number, perTopupMaxSol?:number}} [args.caps]
 * @param {number} [args.now]    epoch ms (injectable for tests)
 * @returns {Promise<{written:number, seqFrom:number|null, seqTo:number|null, headHash:string|null, skippedWrite?:string}>}
 */
export async function recordSweep({ runId, masterPubkey, network = 'mainnet', result, caps = {}, now = Date.now() }) {
	await ensureSchema();
	const solUsd = round6((await solPriceUsd(now)) || 0);
	const rows = buildSweepRows({ masterPubkey, network, result, caps, solUsd, now });
	if (!rows.length) return { written: 0, seqFrom: null, seqTo: null, headHash: null };
	return appendChain({ masterPubkey, runId, rows, label: 'recordSweep' });
}

/**
 * Turn a sweepTopUps() result into ordered ledger rows with a running balance.
 * Pure — no DB, no clock beyond the injected `now` — so it is unit-tested.
 * @returns {Array<object>}
 */
export function buildSweepRows({ masterPubkey, network = 'mainnet', result, caps = {}, solUsd = 0, now = Date.now() }) {
	const rows = [];
	const before = round9(result?.masterSol ?? 0);
	let running = before;
	const baseTs = now;
	let i = 0;
	const ts = () => new Date(baseTs + i++).toISOString();

	const common = {
		master_pubkey: masterPubkey,
		network,
		reserve_sol: caps.reserveSol ?? result?.reserveSol ?? null,
		run_cap_sol: caps.runCapSol ?? null,
		per_topup_max_sol: caps.perTopupMaxSol ?? null,
		master_sol_before: before,
	};

	for (const f of result?.funded || []) {
		const solAfter = round9(running - f.sol);
		rows.push({
			...common,
			ts: ts(),
			event: 'transfer',
			target_name: f.name,
			target_pubkey: f.pubkey,
			lamports: Math.round(f.sol * 1e9),
			sol: round9(f.sol),
			sol_usd: solUsd || null,
			usd_value: solUsd ? round6(f.sol * solUsd) : null,
			tx_signature: f.signature,
			reason: null,
			master_sol_after: solAfter,
			detail: null,
		});
		running = solAfter;
	}
	for (const f of result?.failed || []) {
		rows.push({
			...common,
			ts: ts(),
			event: 'failed',
			target_name: f.name,
			target_pubkey: f.pubkey,
			lamports: f.sol != null ? Math.round(f.sol * 1e9) : null,
			sol: f.sol != null ? round9(f.sol) : null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: null,
			reason: f.reason || 'send_failed',
			master_sol_after: running,
			detail: null,
		});
	}
	for (const r of result?.rejected || []) {
		rows.push({
			...common,
			ts: ts(),
			event: 'blocked',
			target_name: r.name,
			target_pubkey: r.pubkey,
			lamports: null,
			sol: null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: null,
			reason: r.reason || 'not_in_registry',
			master_sol_after: running,
			detail: null,
		});
	}
	// Heartbeat summary — always written, even on a no-op sweep, so a continuous
	// monitoring trail exists (regulatory "we watch this every 30 min" evidence).
	rows.push({
		...common,
		ts: ts(),
		event: 'sweep',
		target_name: null,
		target_pubkey: null,
		lamports: null,
		sol: round9(result?.spentSol ?? 0),
		sol_usd: solUsd || null,
		usd_value: solUsd ? round6((result?.spentSol ?? 0) * solUsd) : null,
		tx_signature: null,
		reason: result?.configured === false ? 'unconfigured' : null,
		master_sol_after: running,
		detail: {
			configured: result?.configured ?? false,
			funded: (result?.funded || []).length,
			failed: (result?.failed || []).length,
			blocked: (result?.rejected || []).length,
			skipped: result?.skipped || [],
			spent_sol: round9(result?.spentSol ?? 0),
			spendable_sol: result?.spendableSol ?? null,
		},
	});
	return rows;
}

/**
 * Append one consolidation sweep's events (api/_lib/economy-sweepback.js) to the
 * same hash chain: one `inflow` row per SOL return, one `inflow_token` row per
 * token transfer, `inflow_failed` for what didn't land, and a `sweepback`
 * summary. Inflows raise the running balance — the mirror image of recordSweep.
 *
 * @param {object} args
 * @param {string} args.runId
 * @param {string} args.masterPubkey
 * @param {'mainnet'|'devnet'} [args.network]
 * @param {object} args.result   the object returned by sweepBack()
 * @param {number} [args.now]    epoch ms (injectable for tests)
 * @returns {Promise<{written:number, seqFrom:number|null, seqTo:number|null, headHash:string|null, skippedWrite?:string}>}
 */
export async function recordSweepback({ runId, masterPubkey, network = 'mainnet', result, now = Date.now() }) {
	await ensureSchema();
	const solUsd = round6((await solPriceUsd(now)) || 0);
	const rows = buildSweepbackRows({ masterPubkey, network, result, solUsd, now });
	if (!rows.length) return { written: 0, seqFrom: null, seqTo: null, headHash: null };
	return appendChain({ masterPubkey, runId, rows, label: 'recordSweepback' });
}

/**
 * Turn a sweepBack() result into ordered ledger rows with a rising running
 * balance. Pure — no DB, no clock beyond the injected `now` — so it is
 * unit-tested alongside buildSweepRows.
 * @returns {Array<object>}
 */
export function buildSweepbackRows({ masterPubkey, network = 'mainnet', result, solUsd = 0, now = Date.now() }) {
	const rows = [];
	const before = result?.masterSolBefore == null ? null : round9(result.masterSolBefore);
	let running = before ?? 0;
	const baseTs = now;
	let i = 0;
	const ts = () => new Date(baseTs + i++).toISOString();

	const common = {
		master_pubkey: masterPubkey,
		network,
		reserve_sol: null,
		run_cap_sol: null,
		per_topup_max_sol: null,
		master_sol_before: before,
	};

	for (const s of result?.sweptSol || []) {
		const solAfter = round9(running + s.sol);
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow',
			target_name: s.name,
			target_pubkey: s.pubkey,
			lamports: Math.round(s.sol * 1e9),
			sol: round9(s.sol),
			sol_usd: solUsd || null,
			usd_value: solUsd ? round6(s.sol * solUsd) : null,
			tx_signature: s.signature,
			reason: null,
			master_sol_after: solAfter,
			detail: null,
		});
		running = solAfter;
	}
	for (const t of result?.sweptTokens || []) {
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow_token',
			target_name: t.name,
			target_pubkey: t.pubkey,
			lamports: null,
			sol: null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: t.signature,
			reason: null,
			master_sol_after: running,
			detail: { mint: t.mint, amount: t.amount, decimals: t.decimals },
		});
	}
	for (const f of result?.failed || []) {
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow_failed',
			target_name: f.name,
			target_pubkey: f.pubkey,
			lamports: f.sol != null ? Math.round(f.sol * 1e9) : null,
			sol: f.sol != null ? round9(f.sol) : null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: null,
			reason: f.reason || 'send_failed',
			master_sol_after: running,
			detail: null,
		});
	}
	// Summary — always written, even on a no-op sweep, so the consolidation trail
	// is as continuous as the funding trail.
	rows.push({
		...common,
		ts: ts(),
		event: 'sweepback',
		target_name: null,
		target_pubkey: null,
		lamports: null,
		sol: round9(result?.receivedSol ?? 0),
		sol_usd: solUsd || null,
		usd_value: solUsd ? round6((result?.receivedSol ?? 0) * solUsd) : null,
		tx_signature: null,
		reason: null,
		master_sol_after: result?.masterSolAfter == null ? running : round9(result.masterSolAfter),
		detail: {
			mode: result?.mode || 'excess',
			sol_transfers: (result?.sweptSol || []).length,
			token_transfers: (result?.sweptTokens || []).length,
			failed: (result?.failed || []).length,
			skipped: result?.skipped || [],
			received_sol: round9(result?.receivedSol ?? 0),
			master_sol_before: before,
			master_sol_after: result?.masterSolAfter == null ? null : round9(result.masterSolAfter),
		},
	});
	return rows;
}

// Read-error rows written per run before the summary takes over. A dead RPC tier
// fails EVERY candidate at once, and 40 identical `rpc_error` rows would bloat
// the chain without saying anything the summary's count does not. Twenty is
// enough to see which wallets were affected.
const MAX_READ_ERROR_ROWS = 20;

/**
 * Turn a `reclaimIdleAgentSol()` result into ordered ledger rows.
 *
 * The agent reclaim leg was the ONLY money path in the economy that wrote
 * nothing to the book of record when it failed: the engine leg writes
 * `inflow_failed`, the agent leg wrote nothing at all. That silence is not
 * theoretical. On 2026-07-29 every Solana RPC lane was in quota cooldown, so
 * every balance read failed, no candidate was ever planned, and 0.12 SOL sat
 * reclaimable in agent wallets for ~11 hours while the sponsor stayed under its
 * settle floor and every 402 challenge dropped its Solana accept. Nothing in the
 * ledger recorded that the self-heal had even been attempted.
 *
 * Three row kinds, and the distinction between the last two is the whole point:
 *   `inflow`             SOL that came back, with its signature.
 *   `inflow_failed`      an attempt that did not land. `reason` names which
 *                        stage failed (`rpc_error:` could not read the balance,
 *                        `secret_undecryptable:` a KEY problem no funding fixes,
 *                        anything else: the broadcast).
 *   `agent_reclaim`      the summary, ALWAYS written, even on a no-op run, so
 *                        "the loop ran and found nothing" and "the loop never
 *                        ran" are different rows rather than the same absence.
 *
 * Pure: no DB, no clock beyond the injected `now`.
 *
 * @param {object} args
 * @param {string} args.masterPubkey
 * @param {'mainnet'|'devnet'} [args.network]
 * @param {{master?:string, reclaimedSol?:number, moves?:Array<object>,
 *          skipped?:Array<object>, failed?:Array<object>,
 *          readErrors?:Array<object>, error?:string, dryRun?:boolean}} args.result
 * @param {number} [args.masterSolBefore]
 * @param {number} [args.deficitSol] the deficit the reclaim was trying to close
 * @param {number} [args.solUsd]
 * @param {number} [args.now] epoch ms
 * @returns {Array<object>}
 */
export function buildAgentReclaimRows({
	masterPubkey,
	network = 'mainnet',
	result,
	masterSolBefore = null,
	deficitSol = null,
	solUsd = 0,
	now = Date.now(),
}) {
	const rows = [];
	const before = masterSolBefore == null ? null : round9(masterSolBefore);
	let running = before ?? 0;
	const baseTs = now;
	let i = 0;
	const ts = () => new Date(baseTs + i++).toISOString();

	const common = {
		master_pubkey: masterPubkey,
		network,
		reserve_sol: null,
		run_cap_sol: null,
		per_topup_max_sol: null,
		master_sol_before: before,
	};

	const moves = result?.moves || [];
	const failed = result?.failed || [];
	const readErrors = result?.readErrors || [];
	const skipped = result?.skipped || [];

	for (const m of moves) {
		const solAfter = round9(running + (Number(m.sol) || 0));
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow',
			target_name: m.name || 'agent',
			target_pubkey: m.address || null,
			lamports: m.sol != null ? Math.round(m.sol * 1e9) : null,
			sol: m.sol != null ? round9(m.sol) : null,
			sol_usd: solUsd || null,
			usd_value: solUsd && m.sol != null ? round6(m.sol * solUsd) : null,
			tx_signature: m.signature || null,
			reason: null,
			master_sol_after: solAfter,
			detail: { source: 'agent_reclaim', agent_id: m.agentId || null },
		});
		running = solAfter;
	}

	for (const f of failed) {
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow_failed',
			target_name: f.name || 'agent',
			target_pubkey: f.address || null,
			lamports: f.sol != null ? Math.round(f.sol * 1e9) : null,
			sol: f.sol != null ? round9(f.sol) : null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: null,
			reason: f.reason || 'send_failed',
			master_sol_after: running,
			detail: { source: 'agent_reclaim', stage: f.stage || 'send' },
		});
	}

	for (const e of readErrors.slice(0, MAX_READ_ERROR_ROWS)) {
		rows.push({
			...common,
			ts: ts(),
			event: 'inflow_failed',
			target_name: e.name || 'agent',
			target_pubkey: e.address || null,
			lamports: null,
			sol: null,
			sol_usd: solUsd || null,
			usd_value: null,
			tx_signature: null,
			// A balance we could not READ is not a wallet that is empty. Keeping the
			// stage on the row is what stops a future reader sizing a funding ask
			// from a run where the fleet was simply unreadable.
			reason: e.reason || 'rpc_error',
			master_sol_after: running,
			detail: { source: 'agent_reclaim', stage: 'read' },
		});
	}

	const reclaimed = round9(result?.reclaimedSol ?? 0);
	rows.push({
		...common,
		ts: ts(),
		event: 'agent_reclaim',
		target_name: null,
		target_pubkey: null,
		lamports: null,
		sol: reclaimed,
		sol_usd: solUsd || null,
		usd_value: solUsd ? round6(reclaimed * solUsd) : null,
		tx_signature: null,
		// The summary's own reason names the outcome class an operator acts on:
		// `blocked` means we could not read or could not send (fix the RPC tier or
		// the encryption key, no money required); `nothing_reclaimable` means every
		// source is genuinely at its floor, which is the only case that needs funds.
		reason: result?.error
			? `leg_error: ${String(result.error).slice(0, 180)}`
			: reclaimed > 0
				? null
				: failed.length + readErrors.length > 0
					? 'blocked'
					: 'nothing_reclaimable',
		master_sol_after: running,
		detail: {
			source: 'agent_reclaim',
			dry_run: Boolean(result?.dryRun),
			moves: moves.length,
			failed: failed.length,
			read_errors: readErrors.length,
			read_errors_logged: Math.min(readErrors.length, MAX_READ_ERROR_ROWS),
			skipped: skipped.length,
			// Bucket on the reason CLASS, the text before the first colon. Skip reasons
			// carry their numbers now (`at_or_below_floor:0.0006<0.015`,
			// `below_swap_rent:1253408<1870569`) so an operator can tell a fenced wallet
			// from an empty one; keying the histogram on the whole string would give a
			// fleet-wide run one bucket per wallet balance and destroy the count this
			// field exists to provide.
			skipped_reasons: skipped.reduce((acc, s) => {
				const key = String(s?.reason || 'unknown').split(':')[0];
				acc[key] = (acc[key] || 0) + 1;
				return acc;
			}, {}),
			// SOL sitting on skipped wallets that is real but fenced by a floor. Zero
			// means the sources are genuinely empty and only owner capital moves the
			// rail; non-zero means a floor decision would release funds we already own.
			skipped_floor_held_sol: round9(
				skipped.reduce((sum, s) => sum + (Number(s?.heldSol) || 0), 0),
			),
			reclaimed_sol: reclaimed,
			deficit_sol: deficitSol == null ? null : round9(deficitSol),
			master_sol_before: before,
		},
	});
	return rows;
}

/**
 * Append one agent-reclaim run to the hash chain. Fail-soft in the same way every
 * other recorder here is: a DB stall drops the batch and is reported, it never
 * throws into the money path that already moved (or failed to move) SOL.
 *
 * @param {object} args
 * @param {string} args.runId
 * @param {string} args.masterPubkey
 * @param {'mainnet'|'devnet'} [args.network]
 * @param {object} args.result the object returned by reclaimIdleAgentSol()
 * @param {number} [args.masterSolBefore]
 * @param {number} [args.deficitSol]
 * @param {number} [args.now]
 * @returns {Promise<{written:number, seqFrom:number|null, seqTo:number|null, headHash:string|null, skippedWrite?:string}>}
 */
export async function recordAgentReclaim({
	runId,
	masterPubkey,
	network = 'mainnet',
	result,
	masterSolBefore = null,
	deficitSol = null,
	now = Date.now(),
}) {
	await ensureSchema();
	const solUsd = round6((await solPriceUsd(now)) || 0);
	const rows = buildAgentReclaimRows({
		masterPubkey, network, result, masterSolBefore, deficitSol, solUsd, now,
	});
	if (!rows.length) return { written: 0, seqFrom: null, seqTo: null, headHash: null };
	return appendChain({ masterPubkey, runId, rows, label: 'recordAgentReclaim' });
}

async function insertRow(r) {
	await withDbRetry(() => sql`
		INSERT INTO economy_master_ledger
			(seq, ts, run_id, master_pubkey, event, target_name, target_pubkey,
			 lamports, sol, sol_usd, usd_value, tx_signature, reason,
			 master_sol_before, master_sol_after, reserve_sol, run_cap_sol,
			 per_topup_max_sol, network, detail, prev_hash, entry_hash)
		VALUES
			(${r.seq}, ${r.ts}, ${r.run_id}, ${r.master_pubkey}, ${r.event},
			 ${r.target_name}, ${r.target_pubkey}, ${r.lamports}, ${r.sol},
			 ${r.sol_usd}, ${r.usd_value}, ${r.tx_signature}, ${r.reason},
			 ${r.master_sol_before}, ${r.master_sol_after}, ${r.reserve_sol},
			 ${r.run_cap_sol}, ${r.per_topup_max_sol}, ${r.network},
			 ${r.detail ? JSON.stringify(r.detail) : null}, ${r.prev_hash}, ${r.entry_hash})
	`);
}

/**
 * Recompute the hash chain for a master and report any integrity failure. This is
 * the tamper detector — a broken link means a historical row was edited/deleted,
 * a seq gap means a row is missing. Reads the whole chain (bounded by `limit`).
 *
 * @param {string} masterPubkey
 * @param {{limit?:number}} [opts]
 * @returns {Promise<{ok:boolean, count:number, brokenAtSeq:number|null, gapAtSeq:number|null, headSeq:number|null, headHash:string|null}>}
 */
export async function verifyChain(masterPubkey, { limit = 100_000 } = {}) {
	const rows = await withDbRetry(() => sql`
		SELECT seq, ts, master_pubkey, event, target_pubkey, lamports, tx_signature,
		       reason, master_sol_after, prev_hash, entry_hash
		FROM economy_master_ledger
		WHERE master_pubkey = ${masterPubkey}
		ORDER BY seq ASC LIMIT ${limit}
	`);
	let prevHash = '';
	let prevSeq = 0;
	for (const row of rows) {
		const seq = Number(row.seq);
		if (seq !== prevSeq + 1) {
			return { ok: false, count: rows.length, brokenAtSeq: null, gapAtSeq: seq, headSeq: null, headHash: null };
		}
		// Normalize ts to the ISO form we hashed (Postgres returns a Date).
		const tsIso = row.ts instanceof Date ? row.ts.toISOString() : String(row.ts);
		const recomputed = hashEntry(row.prev_hash || '', {
			seq,
			ts: tsIso,
			master_pubkey: row.master_pubkey,
			event: row.event,
			target_pubkey: row.target_pubkey,
			lamports: row.lamports,
			tx_signature: row.tx_signature,
			reason: row.reason,
			master_sol_after: row.master_sol_after == null ? null : String(row.master_sol_after),
		});
		if ((row.prev_hash || '') !== (prevHash || '') || recomputed !== row.entry_hash) {
			return { ok: false, count: rows.length, brokenAtSeq: seq, gapAtSeq: null, headSeq: null, headHash: null };
		}
		prevHash = row.entry_hash;
		prevSeq = seq;
	}
	return {
		ok: true,
		count: rows.length,
		brokenAtSeq: null,
		gapAtSeq: null,
		headSeq: prevSeq || null,
		headHash: prevHash || null,
	};
}

/**
 * Read ledger rows for accounting/reconciliation over a window.
 * @param {{masterPubkey?:string, from?:string, to?:string, event?:string, limit?:number}} [opts]
 */
export async function readLedger({ masterPubkey = null, from = null, to = null, event = null, limit = 10_000 } = {}) {
	return withDbRetry(() => sql`
		SELECT * FROM economy_master_ledger
		WHERE (${masterPubkey}::text IS NULL OR master_pubkey = ${masterPubkey})
		  AND (${from}::timestamptz IS NULL OR ts >= ${from})
		  AND (${to}::timestamptz IS NULL OR ts <= ${to})
		  AND (${event}::text IS NULL OR event = ${event})
		ORDER BY seq ASC LIMIT ${limit}
	`);
}