@gatedpath/preflight 0.2.2 → 0.2.3

package/README.md

@@ -90,6 +90,26 @@ Recorded runs against the real feeds, read-only, on 14 September 2026: `reports/
 and `reports/gas-151-2026-09-14.md`. On both, 21,000 gas came to 1.000 US cents and the scaffold's
 `GatedERC20` deploys for 1,898,391 gas, 383.7 RBNT, 90.4 cents at a feed price of US$0.002356 per RBNT.
 
+## redbelly fees
+
+What the calls a builder meets cost today, the command-line twin of the site's fee checker (`/fees/`,
+"What it costs"). `redbelly fees` reads both chains and prints, for each, the head block and its time,
+the base fee in gwei, RBNT in US dollars from the on-chain feed with the feed's time, then four
+measured calls (a native transfer, deploying the recipient guard, deploying the gated token, enabling
+a wallet) in gas, RBNT and US cents at today's base fee through the same integer arithmetic as
+`redbelly gas`, and the enable line against the network's fixed rate of US$0.01 per 21,000 gas. On
+mainnet it also reads the base fee at nine block heights from the first week to the head and prices
+the enable call at each, which is the site's two-year chart as a table. The gas figures are the ones
+measured on 17 October 2026 and carried in the report with the run that measured each. `--chain`
+limits it to one chain, `--rpc` names another endpoint (a fork works; with no `--chain` the RPC says
+which chain it is), `--no-history` skips the mainnet history, `--json` for agents. Exit 0 when every
+chain was read, 1 when one could not be (the line says which and why), 2 on bad arguments. Read-only,
+no key, nothing written.
+
+```
+redbelly fees [--chain 151|153] [--rpc <url>] [--timeout <ms>] [--no-history] [--json]
+```
+
 ## redbelly ship
 
 The mainnet gate that produces the document you wanted anyway (PLAN.md 18.3). `redbelly ship --chain

package/dist/dotenv.d.ts

@@ -3,5 +3,6 @@ export declare const ENV_NAMES: {
     readonly admin: "ADMIN_SAFE";
     readonly chain: "CHAIN_ID";
     readonly legacyAdmin: "PREFLIGHT_ADMIN";
+    readonly verifier: "VERIFIER";
 };
 export declare function readDotEnv(project: string, env: NodeJS.ProcessEnv): Record<string, string>;

package/dist/dotenv.js

@@ -4,7 +4,9 @@
 // git-secrets check covers what should never be in that file.
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-export const ENV_NAMES = { deployer: 'DEPLOYER', admin: 'ADMIN_SAFE', chain: 'CHAIN_ID', legacyAdmin: 'PREFLIGHT_ADMIN' };
+// VERIFIER joined on 25 October 2026: the deploy script reads it with vm.envOr, which sees only the
+// process environment, so ship has to see it there too or the two disagree (card 9's run, 23 October).
+export const ENV_NAMES = { deployer: 'DEPLOYER', admin: 'ADMIN_SAFE', chain: 'CHAIN_ID', legacyAdmin: 'PREFLIGHT_ADMIN', verifier: 'VERIFIER' };
 export function readDotEnv(project, env) {
     const out = {};
     const file = join(project, '.env');

package/dist/fees-cli.d.ts

@@ -0,0 +1,8 @@
+import type { FeesOptions } from './fees.js';
+export declare const FEES_HELP = "redbelly fees [options]\n\nReads both chains (151 mainnet, 153 testnet) and prints, for each, the head block and its time,\nthe base fee, RBNT in US dollars from the on-chain feed, the measured calls a builder meets (a\ntransfer, the recipient guard, the gated token, enabling a wallet) in gas, RBNT and US cents at\ntoday's base fee, and on mainnet the enable call at nine block heights since the first week.\nThe command-line twin of the site's fee checker. Read-only, no key.\n\n  --chain <151|153>    one chain instead of both\n  --rpc <url>          JSON-RPC endpoint in place of the chain's governors RPC (a fork works)\n  --timeout <ms>       per request (default 10000)\n  --no-history         skip the mainnet history reads\n  --json               print the report as JSON\n  --version, --help\n";
+export declare function parseFeesArgs(argv: readonly string[]): FeesOptions & {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+};
+export declare function feesMain(argv?: readonly string[]): Promise<number>;

package/dist/fees-cli.js

@@ -0,0 +1,96 @@
+// `redbelly fees`: what the measured calls cost on each chain today. Exit 0 when every chain was
+// read, 1 when one could not be (the line says which and why), 2 on bad arguments. --json for agents.
+import { FEES_VERSION, feesReportJson, renderFeesText, runFees } from './fees.js';
+export const FEES_HELP = `redbelly fees [options]
+
+Reads both chains (151 mainnet, 153 testnet) and prints, for each, the head block and its time,
+the base fee, RBNT in US dollars from the on-chain feed, the measured calls a builder meets (a
+transfer, the recipient guard, the gated token, enabling a wallet) in gas, RBNT and US cents at
+today's base fee, and on mainnet the enable call at nine block heights since the first week.
+The command-line twin of the site's fee checker. Read-only, no key.
+
+  --chain <151|153>    one chain instead of both
+  --rpc <url>          JSON-RPC endpoint in place of the chain's governors RPC (a fork works)
+  --timeout <ms>       per request (default 10000)
+  --no-history         skip the mainnet history reads
+  --json               print the report as JSON
+  --version, --help
+`;
+export function parseFeesArgs(argv) {
+    const o = { json: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const [flag, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+        const next = () => {
+            if (inline !== undefined)
+                return inline;
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`${flag} needs a value`);
+            return v;
+        };
+        switch (flag) {
+            case '--chain': {
+                const c = Number(next());
+                if (c !== 151 && c !== 153)
+                    throw new Error('--chain must be 151 or 153');
+                o.chain = c;
+                break;
+            }
+            case '--rpc':
+                o.rpc = next();
+                break;
+            case '--timeout': {
+                const t = Number(next());
+                if (!Number.isInteger(t) || t <= 0)
+                    throw new Error('--timeout must be a whole number of milliseconds');
+                o.timeoutMs = t;
+                break;
+            }
+            case '--no-history':
+                o.history = false;
+                break;
+            case '--json':
+                o.json = true;
+                break;
+            case '--help':
+            case '-h':
+                o.help = true;
+                break;
+            case '--version':
+                o.version = true;
+                break;
+            default:
+                if (/^(0x)?[0-9a-fA-F]{64}$/.test(a))
+                    throw new Error('that argument looks like a private key; redbelly fees reads the chain and never takes one');
+                throw new Error(`unknown argument "${a}"\n\n${FEES_HELP}`);
+        }
+    }
+    return o;
+}
+export async function feesMain(argv = process.argv.slice(2)) {
+    let args;
+    try {
+        args = parseFeesArgs(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    if (args.help) {
+        process.stdout.write(FEES_HELP);
+        return 0;
+    }
+    if (args.version) {
+        process.stdout.write(`${FEES_VERSION}\n`);
+        return 0;
+    }
+    const { json, help: _h, version: _v, ...opts } = args;
+    const report = await runFees(opts);
+    process.stdout.write(json ? feesReportJson(report) : renderFeesText(report));
+    // The failures are already in the report; repeat them on stderr so a pipe that keeps only stdout still shows the reason in a terminal.
+    for (const c of report.chains)
+        if (!c.ok)
+            process.stderr.write(`redbelly fees: chain ${c.chain ?? 'at ' + c.rpc} could not be read: ${c.error}\n`);
+    return report.ok ? 0 : 1;
+}

package/dist/fees.d.ts

@@ -0,0 +1,85 @@
+import type { GasQuote } from './gas.js';
+export declare const FEES_VERSION: string;
+export interface ReferenceCall {
+    readonly key: string;
+    readonly label: string;
+    readonly gas: bigint;
+    /** Where the gas figure comes from, with the date. */
+    readonly measured: string;
+}
+/** Calls a builder meets, with gas as measured, oldest measurement last. Same table as the site. */
+export declare const REFERENCE_CALLS: readonly ReferenceCall[];
+/** The network prices gas in US dollars: Vine's figure, measured in RESEARCH.md question 3 (US$0.01 for a 21,000-gas transfer). */
+export declare const USD_PER_GAS: number;
+/** Mainnet block heights sampled for the history: genesis week, then roughly every four months to the head. */
+export declare const HISTORY_BLOCKS_151: readonly number[];
+/** The call the history is drawn for: enabling a wallet. */
+export declare const HISTORY_GAS = 2154375n;
+export interface PricedCall extends ReferenceCall {
+    readonly wei: bigint;
+    readonly rbnt: string;
+    readonly usd: number;
+    /** US cents to three decimal places, as a number. */
+    readonly cents: number;
+}
+export interface HistoryPoint {
+    readonly block: number;
+    readonly time: string;
+    readonly baseFeeWei: bigint;
+    /** The enable call at that block's base fee. */
+    readonly rbnt: string;
+    /** The same call at the network's fixed dollar rate; the line that should not move. */
+    readonly usd: number;
+}
+export interface FeesChainOk {
+    readonly ok: true;
+    readonly chain: 151 | 153;
+    readonly network: 'mainnet' | 'testnet';
+    readonly rpc: string;
+    readonly latencyMs: number;
+    readonly quote: GasQuote;
+    readonly calls: readonly PricedCall[];
+    /** The history, mainnet only; null on testnet, and null with a reason when the reads failed. */
+    readonly history: readonly HistoryPoint[] | null;
+    readonly historyError: string | null;
+}
+export interface FeesChainFailed {
+    readonly ok: false;
+    readonly chain: 151 | 153 | null;
+    readonly network: 'mainnet' | 'testnet' | null;
+    readonly rpc: string;
+    readonly latencyMs: number;
+    readonly error: string;
+}
+export type FeesChain = FeesChainOk | FeesChainFailed;
+export interface FeesReport {
+    readonly tool: 'redbelly-fees';
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly chains: readonly FeesChain[];
+    /** True when every chain was read. */
+    readonly ok: boolean;
+}
+export interface FeesOptions {
+    /** One chain; both when absent. With --rpc and no chain, the RPC says which it is. */
+    chain?: 151 | 153;
+    rpc?: string;
+    /** Per request. Default 10 seconds. */
+    timeoutMs?: number;
+    /** Tests pass a fake; otherwise the global fetch. */
+    fetch?: typeof fetch;
+    /** Skip the mainnet history reads. */
+    history?: boolean;
+}
+export declare function priceCalls(quote: Pick<GasQuote, 'baseFeeWei' | 'priceRaw'>, calls?: readonly ReferenceCall[]): PricedCall[];
+/** The base fee at past block heights, each priced for the enable call; blocks the node does not have are left out. */
+export declare function readFeeHistory(rpc: string, blocks: readonly number[], opts?: {
+    fetch?: typeof fetch;
+    gas?: bigint;
+}): Promise<HistoryPoint[]>;
+/** One chain: the quote, the four calls priced, and on mainnet the history. Never throws; a failed read is a result. */
+export declare function readFeesChain(rpc: string, expected: 151 | 153 | undefined, opts?: FeesOptions): Promise<FeesChain>;
+export declare function runFees(opts?: FeesOptions): Promise<FeesReport>;
+export declare function renderFeesText(report: FeesReport): string;
+/** JSON with BigInt as decimal strings. */
+export declare function feesReportJson(report: FeesReport): string;

package/dist/fees.js

@@ -0,0 +1,128 @@
+// redbelly fees: the command-line twin of the site's fee checker (/fees/, "What it costs"). Per chain
+// it reads the head block, the base fee and the feed price (the same three reads as `redbelly gas`,
+// through quoteGas), prices the measured calls a builder meets at today's base fee, and on mainnet
+// reads the base fee at nine block heights so the enable call can be seen across the network's life.
+// Read-only, no key, nothing written. The gas figures below are copied from the site's data file;
+// each one names the run that measured it and is never typed from a document.
+import { createRpc, chainById } from '@gatedpath/chains';
+import { GAS_VERSION, priceGas, quoteGas } from './gas.js';
+export const FEES_VERSION = GAS_VERSION;
+/** Calls a builder meets, with gas as measured, oldest measurement last. Same table as the site. */
+export const REFERENCE_CALLS = [
+    { key: 'transfer', label: 'A native transfer', gas: 21000n, measured: 'the EVM constant; Vine prices it at US$0.01' },
+    { key: 'guard', label: 'Deploying the recipient guard (project 13)', gas: 503685n, measured: 'measured on 153, 17 October 2026, block 3,052,324' },
+    { key: 'token', label: 'Deploying the gated token (the scaffold)', gas: 1971486n, measured: 'the ship report on 153, 17 October 2026' },
+    { key: 'enable', label: 'Enabling a wallet on the network', gas: 2154375n, measured: 'measured on 151, 17 October 2026, block 3,228,354' },
+];
+/** The network prices gas in US dollars: Vine's figure, measured in RESEARCH.md question 3 (US$0.01 for a 21,000-gas transfer). */
+export const USD_PER_GAS = 0.01 / 21_000;
+/** Mainnet block heights sampled for the history: genesis week, then roughly every four months to the head. */
+export const HISTORY_BLOCKS_151 = [204, 400_000, 800_000, 1_200_000, 1_600_000, 2_000_000, 2_400_000, 2_800_000, 3_100_000];
+/** The call the history is drawn for: enabling a wallet. */
+export const HISTORY_GAS = 2154375n;
+/** Each request gets its own deadline; a node that hangs is reported as a timeout rather than waited on. */
+function withTimeout(doFetch, timeoutMs) {
+    return (input, init) => doFetch(input, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+}
+export function priceCalls(quote, calls = REFERENCE_CALLS) {
+    return calls.map((c) => ({ ...c, ...priceGas(c.gas, quote) }));
+}
+/** The base fee at past block heights, each priced for the enable call; blocks the node does not have are left out. */
+export async function readFeeHistory(rpc, blocks, opts = {}) {
+    const caller = createRpc(rpc, opts.fetch ? { fetch: opts.fetch } : {});
+    const gas = opts.gas ?? HISTORY_GAS;
+    const results = await Promise.all(blocks.map((b) => caller('eth_getBlockByNumber', ['0x' + b.toString(16), false])));
+    const points = [];
+    for (const b of results) {
+        if (!b?.number || !b.baseFeePerGas)
+            continue;
+        const baseFeeWei = BigInt(b.baseFeePerGas);
+        // The dollar figure is the fixed rate, not the feed at that block: it is the line the chart shows flat.
+        points.push({ block: Number(BigInt(b.number)), time: new Date(Number(BigInt(b.timestamp ?? '0x0')) * 1000).toISOString(), baseFeeWei, rbnt: priceGas(gas, { baseFeeWei, priceRaw: 0n }).rbnt, usd: Number(gas) * USD_PER_GAS });
+    }
+    return points.sort((a, b) => a.block - b.block);
+}
+/** One chain: the quote, the four calls priced, and on mainnet the history. Never throws; a failed read is a result. */
+export async function readFeesChain(rpc, expected, opts = {}) {
+    const doFetch = withTimeout(opts.fetch ?? fetch, opts.timeoutMs ?? 10_000);
+    const t0 = Date.now();
+    let quote;
+    try {
+        quote = await quoteGas(rpc, expected, { fetch: doFetch });
+    }
+    catch (e) {
+        const chain = expected ?? null;
+        return { ok: false, chain, network: chain === null ? null : chain === 151 ? 'mainnet' : 'testnet', rpc, latencyMs: Date.now() - t0, error: e.message };
+    }
+    const calls = priceCalls(quote);
+    let history = null;
+    let historyError = null;
+    if (quote.chain === 151 && opts.history !== false) {
+        try {
+            // The head is read again by height so the last point and the quote name the same block.
+            history = await readFeeHistory(rpc, [...HISTORY_BLOCKS_151.filter((b) => b < quote.block), quote.block], { fetch: doFetch });
+        }
+        catch (e) {
+            historyError = e.message;
+        }
+    }
+    return { ok: true, chain: quote.chain, network: quote.network, rpc, latencyMs: Date.now() - t0, quote, calls, history, historyError };
+}
+export async function runFees(opts = {}) {
+    let chains;
+    if (opts.rpc) {
+        chains = [await readFeesChain(opts.rpc, opts.chain, opts)];
+    }
+    else {
+        const ids = opts.chain ? [opts.chain] : [151, 153];
+        chains = await Promise.all(ids.map((id) => readFeesChain(chainById(id).rpcUrls.default.http[0], id, opts)));
+    }
+    return { tool: 'redbelly-fees', version: FEES_VERSION, generatedAt: new Date().toISOString(), chains, ok: chains.every((c) => c.ok) };
+}
+// ---- text ----
+const num = (n) => n.toLocaleString('en-US');
+const fixed = (n, d) => n.toLocaleString('en-US', { minimumFractionDigits: d, maximumFractionDigits: d });
+const gwei = (wei) => `${fixed(Number(wei) / 1e9, 2)} gwei`;
+const rbnt = (s) => {
+    const n = Number(s);
+    return n === 0 ? '0' : n < 0.000001 ? '<0.000001' : fixed(n, n < 1 ? 6 : 3);
+};
+const when = (iso) => iso.replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+export function renderFeesText(report) {
+    const lines = [];
+    lines.push(`redbelly fees ${report.version}  ${when(report.generatedAt)}`);
+    for (const c of report.chains) {
+        lines.push('');
+        if (!c.ok) {
+            lines.push(`chain ${c.chain ?? '?'}${c.network ? ` (${c.network})` : ''} via ${c.rpc}: could not be read: ${c.error}`);
+            continue;
+        }
+        const q = c.quote;
+        lines.push(`chain ${c.chain} (${c.network}) via ${c.rpc}  read in ${num(c.latencyMs)} ms`);
+        lines.push(`head block ${num(q.block)} at ${when(q.blockTimestamp)}  base fee ${gwei(q.baseFeeWei)}`);
+        lines.push(`RBNT US$${fixed(q.usdPerRbnt, 6)} from the feed at ${when(q.priceTimestamp)}`);
+        lines.push('');
+        const w = Math.max(...c.calls.map((r) => r.label.length));
+        lines.push(['Call'.padEnd(w), 'Gas'.padStart(11), 'RBNT'.padStart(12), 'US cents'.padStart(10)].join('  '));
+        for (const r of c.calls)
+            lines.push([r.label.padEnd(w), num(r.gas).padStart(11), rbnt(r.rbnt).padStart(12), fixed(r.cents, 3).padStart(10)].join('  '));
+        const enable = c.calls.find((r) => r.key === 'enable');
+        if (enable)
+            lines.push('', `enable: ${num(enable.gas)} gas = ${rbnt(enable.rbnt)} RBNT = US$${fixed(enable.usd, 4)} now; at the network's fixed rate of US$0.01 per 21,000 gas it is US$${fixed(Number(enable.gas) * USD_PER_GAS, 2)}, whatever RBNT trades at.`);
+        if (c.history && c.history.length) {
+            lines.push('', `the enable call across mainnet's life (${num(HISTORY_GAS)} gas at the base fee of each block; dollars at the fixed rate):`);
+            lines.push(['Block'.padStart(11), 'Date'.padEnd(10), 'Base fee'.padStart(20), 'RBNT'.padStart(12), 'US$'.padStart(8)].join('  '));
+            for (const p of c.history)
+                lines.push([num(p.block).padStart(11), p.time.slice(0, 10).padEnd(10), gwei(p.baseFeeWei).padStart(20), rbnt(p.rbnt).padStart(12), fixed(p.usd, 2).padStart(8)].join('  '));
+        }
+        else if (c.historyError) {
+            lines.push('', `history: not read (${c.historyError})`);
+        }
+    }
+    lines.push('', 'Gas is priced in US dollars and converted to RBNT at execution from the feed, so the cents column is the stable one; the RBNT column moves with the price. Base fee only: the chain charges no priority fee.');
+    return lines.join('\n') + '\n';
+}
+/** JSON with BigInt as decimal strings. */
+export function feesReportJson(report) {
+    return JSON.stringify(report, (_k, v) => (typeof v === 'bigint' ? v.toString() : v), 2) + '\n';
+}

package/dist/gas.d.ts

@@ -26,6 +26,8 @@ export interface GasQuote {
     readonly network: 'mainnet' | 'testnet';
     readonly rpc: string;
     readonly block: number;
+    /** The head block's timestamp as ISO, so a quote can be dated without a second block read. */
+    readonly blockTimestamp: string;
     readonly baseFeeWei: bigint;
     /** The feed's raw integer (six decimals) and the derived USD per RBNT. */
     readonly priceRaw: bigint;
@@ -114,7 +116,10 @@ export declare function priceRows(rows: readonly GasRow[], quote: Pick<GasQuote,
     added: string[];
     removed: string[];
 };
-export declare function quoteGas(rpc: string, expected?: 151 | 153): Promise<GasQuote>;
+/** `fetch` is for tests and for callers that wrap a timeout round the global one; the reads are the same either way. */
+export declare function quoteGas(rpc: string, expected?: 151 | 153, opts?: {
+    fetch?: typeof fetch;
+}): Promise<GasQuote>;
 /** A scaffold root's contracts/ when that is where foundry.toml is; otherwise the directory itself. */
 export declare function foundryDir(project: string): string;
 export declare function readGasSource(dir: string, opts: Pick<GasOptions, 'snapshot' | 'report' | 'env'>): Promise<{

package/dist/gas.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { basename, join, relative, resolve } from 'node:path';
-import { PRICE_FEED_DECIMALS, chainById, formatUnits, getLatestPrice, toCaller } from '@gatedpath/chains';
+import { PRICE_FEED_DECIMALS, chainById, createRpc, formatUnits, getLatestPrice, toCaller } from '@gatedpath/chains';
 import { run } from './proc.js';
 const require = createRequire(import.meta.url);
 export const GAS_VERSION = require('../package.json').version;
@@ -105,8 +105,9 @@ export function priceRows(rows, quote, before) {
     return { rows: priced, added: before ? rows.filter((r) => !prior.has(r.name)).map((r) => r.name) : [], removed: before ? [...prior.keys()].filter((n) => !names.has(n)) : [] };
 }
 // ---- the two reads ----
-export async function quoteGas(rpc, expected) {
-    const caller = toCaller(rpc);
+/** `fetch` is for tests and for callers that wrap a timeout round the global one; the reads are the same either way. */
+export async function quoteGas(rpc, expected, opts = {}) {
+    const caller = opts.fetch ? createRpc(rpc, { fetch: opts.fetch }) : toCaller(rpc);
     const reported = Number(BigInt((await caller('eth_chainId'))));
     if (reported !== 151 && reported !== 153)
         throw new Error(`the RPC at ${rpc} reports chain ${reported}; redbelly gas prices through the feed on 151 or 153 (a fork of either works)`);
@@ -115,12 +116,13 @@ export async function quoteGas(rpc, expected) {
     const block = (await caller('eth_getBlockByNumber', ['latest', false]));
     if (!block?.baseFeePerGas)
         throw new Error('the latest block has no baseFeePerGas');
-    const price = await getLatestPrice({ rpc });
+    const price = await getLatestPrice({ rpc: caller });
     return {
         chain: reported,
         network: reported === 151 ? 'mainnet' : 'testnet',
         rpc,
         block: Number(BigInt(block.number ?? '0x0')),
+        blockTimestamp: new Date(Number(BigInt(block.timestamp ?? '0x0')) * 1000).toISOString(),
         baseFeeWei: BigInt(block.baseFeePerGas),
         priceRaw: price.raw,
         usdPerRbnt: price.usdPerRbnt,

package/dist/index.d.ts

@@ -21,6 +21,9 @@ export { doctorMain, parseDoctorArgs, DOCTOR_HELP } from './doctor-cli.js';
 export { runGas, quoteGas, priceGas, priceRows, parseGasSnapshot, parseGasReportJson, parseGasFile, readGasSource, foundryDir, renderGasText, gasReportJson } from './gas.js';
 export type { GasRow, GasSource, GasQuote, PricedRow, GasReport, GasOptions } from './gas.js';
 export { gasMain, parseGasArgs, GAS_HELP } from './gas-cli.js';
+export { runFees, readFeesChain, readFeeHistory, priceCalls, renderFeesText, feesReportJson, REFERENCE_CALLS, USD_PER_GAS, HISTORY_BLOCKS_151, HISTORY_GAS, FEES_VERSION } from './fees.js';
+export type { ReferenceCall, PricedCall, HistoryPoint, FeesChain, FeesChainOk, FeesChainFailed, FeesReport, FeesOptions } from './fees.js';
+export { feesMain, parseFeesArgs, FEES_HELP } from './fees-cli.js';
 export { findGatedSuites, summariseTests } from './suites.js';
 export type { ForgeTestJson, SuiteSummary } from './suites.js';
 export { runShip, renderShipMarkdown, renderShipText, shipReportJson, shipReportPath, parseShipHeader, readShipContracts, routescanBase, utcDate, SHIP_HEADER } from './ship.js';

package/dist/index.js

@@ -15,6 +15,8 @@ export { runDoctor, renderDoctorText, whichOnPath, toolVersion, exitCodePropagat
 export { doctorMain, parseDoctorArgs, DOCTOR_HELP } from './doctor-cli.js';
 export { runGas, quoteGas, priceGas, priceRows, parseGasSnapshot, parseGasReportJson, parseGasFile, readGasSource, foundryDir, renderGasText, gasReportJson } from './gas.js';
 export { gasMain, parseGasArgs, GAS_HELP } from './gas-cli.js';
+export { runFees, readFeesChain, readFeeHistory, priceCalls, renderFeesText, feesReportJson, REFERENCE_CALLS, USD_PER_GAS, HISTORY_BLOCKS_151, HISTORY_GAS, FEES_VERSION } from './fees.js';
+export { feesMain, parseFeesArgs, FEES_HELP } from './fees-cli.js';
 export { findGatedSuites, summariseTests } from './suites.js';
 export { runShip, renderShipMarkdown, renderShipText, shipReportJson, shipReportPath, parseShipHeader, readShipContracts, routescanBase, utcDate, SHIP_HEADER } from './ship.js';
 export { shipMain, parseShipArgs, SHIP_HELP } from './ship-cli.js';

package/dist/redbelly.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // `redbelly <command>`: one bin for the checks a builder runs by hand. `preflight` is the seven
-// checks, `doctor` the machine, `gas` the report in RBNT and US cents, `ship` the mainnet gate that
-// writes its own report. Each is also its own bin (redbelly-preflight, redbelly-doctor) or an MCP tool.
+// checks, `doctor` the machine, `gas` the report in RBNT and US cents, `fees` what the measured calls
+// cost on each chain today, `ship` the mainnet gate that writes its own report. Each is also its own bin (redbelly-preflight, redbelly-doctor) or an MCP tool.
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { main as preflightMain } from './cli.js';
@@ -11,7 +11,8 @@ const HELP = `redbelly <command> [options]
   preflight   the seven checks before a deploy (redbelly-preflight)
   doctor      the machine before the first command (redbelly-doctor)
   gas         gas per function in RBNT and US cents at the chain's base fee and feed price
-  ship        pre-flight, Slither, the five-state tests and the gas figures, written to deployments/ship-<chain>-<date>.md
+  fees        what the measured calls cost on 151 and 153 today: head block, base fee, feed price, RBNT and US cents
+  ship       pre-flight, Slither, the five-state tests and the gas figures, written to deployments/ship-<chain>-<date>.md
 
 redbelly <command> --help for each. Nothing here takes a key; signing tools take a keystore name.
 `;
@@ -19,6 +20,7 @@ const commands = {
     preflight: preflightMain,
     doctor: doctorMain,
     gas: async (argv) => (await import('./gas-cli.js')).gasMain(argv),
+    fees: async (argv) => (await import('./fees-cli.js')).feesMain(argv),
     ship: async (argv) => (await import('./ship-cli.js')).shipMain(argv),
 };
 export async function redbellyMain(argv = process.argv.slice(2)) {

package/dist/ship.d.ts

@@ -33,6 +33,8 @@ export interface ShipContract {
     readonly name: string;
     readonly address: string;
     readonly record: string;
+    /** When the record file was last written, so a report made before a deploy is read as such. */
+    readonly writtenAt: string;
     readonly deployer: string | null;
     readonly admin: string | null;
     readonly verifier: string | null;

package/dist/ship.js

@@ -6,7 +6,7 @@
 // refuses to write when any check fails; the deploy script refuses to broadcast on 151 without a
 // report dated today. Nothing here signs: the account name resolves to an address through cast,
 // the RPC is read, forge runs tests on the local machine.
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { basename, join, relative, resolve } from 'node:path';
 import { chainById, decodeWords, ethCall, isAllowed, toCaller } from '@gatedpath/chains';
@@ -66,10 +66,15 @@ export function readShipContracts(dir, chain, pins) {
     for (const name of readdirSync(dep).sort()) {
         if (!(name === `${chain}.json` || (name.startsWith(`${chain}-`) && name.endsWith('.json'))))
             continue;
+        // The deploy script writes a dry run's record as <chain>-<Name>.dry-run.json (0.2.3) and says
+        // "broadcast": false inside it; neither describes a contract anyone can verify.
+        if (name.endsWith('.dry-run.json'))
+            continue;
         const record = readJson(join(dep, name));
         const address = str(record?.['contract']);
-        if (!record || !address)
+        if (!record || !address || record['broadcast'] === false)
             continue;
+        const writtenAt = statSync(join(dep, name)).mtime.toISOString();
         const contractName = str(record['contractName']) ?? basename(name, '.json').replace(new RegExp(`^${chain}-`), '');
         const sig = str(record['constructorSignature']);
         const args = str(record['constructorArgs']);
@@ -79,6 +84,7 @@ export function readShipContracts(dir, chain, pins) {
             name: contractName,
             address,
             record: join(dep, name),
+            writtenAt,
             deployer: str(record['deployer']),
             admin: str(record['admin']),
             verifier: str(record['verifier']),
@@ -158,7 +164,7 @@ export async function runShip(opts) {
         checks.push({ id: 'admin-required', status: 'fail', reason: 'Chain 151 needs --admin <safe> (or ADMIN_SAFE in .env): the Safe 1.4.1 that receives every role.' });
     // 3. the verifier the deploy script will bind
     const verifierAddr = opts.verifier ?? rootEnv['VERIFIER'] ?? null;
-    const verifierSource = opts.verifier ? '--verifier' : rootEnv['VERIFIER'] ? 'VERIFIER in .env' : 'none';
+    const verifierSource = opts.verifier ? '--verifier' : env['VERIFIER'] ? 'VERIFIER in the environment' : rootEnv['VERIFIER'] ? 'VERIFIER in .env' : 'none';
     let verifierIsContract = null;
     if (verifierAddr) {
         if (!/^0x[0-9a-fA-F]{40}$/.test(verifierAddr))
@@ -286,7 +292,22 @@ export class ShipUsageError extends Error {
 // ---- the document ----
 const fmt = (n) => n.toLocaleString('en-US');
 const short = (s) => (s && s.includes('.') ? s.replace(/(\.\d{4})\d+$/, '$1') : s ?? '');
+/** The document goes into deployments/, which is committed and, for a public project, published. So it
+ * names the project by its last two path segments, never by a path on the machine that wrote it, and
+ * says `<keystore-name>` where the terminal said the real one (found 25 October 2026 by the project
+ * export's scan on the escrow's report). The JSON and the terminal keep both. */
+function forTheRecord(text, r) {
+    const shown = r.project.split(/[\\/]/).filter(Boolean).slice(-2).join('/');
+    let out = text.split(r.project).join(shown);
+    const account = /--account (\S+)/.exec(r.deployer.how)?.[1];
+    if (account)
+        out = out.split(`--account ${account}`).join('--account <keystore-name>');
+    return out;
+}
 export function renderShipMarkdown(r) {
+    return forTheRecord(renderShipBody(r), r);
+}
+function renderShipBody(r) {
     const L = [];
     const fails = r.checks.filter((c) => c.status === 'fail');
     const warns = r.checks.filter((c) => c.status === 'warn');
@@ -324,6 +345,8 @@ export function renderShipMarkdown(r) {
             L.push('');
             L.push(`Record \`${relative(r.project, c.record)}\`${c.deployer ? `, deployed by ${c.deployer}` : ''}${c.admin ? `, admin ${c.admin}` : ''}${c.verifier ? `, verifier ${c.verifier}` : ''}${c.requestId ? `, request id ${c.requestId}` : ''}. Explorer: ${c.explorer}`);
             L.push('');
+            L.push(`This section describes the record as it stood at ${c.writtenAt}. A deploy made after that rewrites the record; run \`redbelly ship\` again afterwards and the command below follows the new address.`);
+            L.push('');
             if (c.constructorSignature)
                 L.push(`Constructor \`${c.constructorSignature}\`, arguments as encoded by the deploy script:`);
             else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/preflight",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Pre-flight checks before deploying to Redbelly Network (151 mainnet, 153 testnet): chain ID, deployer verification, Safe admin, compiler pins, secrets in git history, RBNT balance, Slither report.",
   "license": "MIT",
   "repository": {
@@ -35,13 +35,13 @@
   ],
   "scripts": {
     "build": "node scripts/ensure-deps-built.mjs && tsc -p tsconfig.json && node -e \"for (const f of ['cli.js','doctor-cli.js','redbelly.js']) require('fs').chmodSync('dist/'+f,0o755)\"",
-    "test": "npm run build && node --test --test-reporter=spec --test-concurrency=1 test/unit.test.mjs test/preflight.test.mjs test/doctor.test.mjs test/gas.test.mjs test/ship.test.mjs",
+    "test": "npm run build && node --test --test-reporter=spec --test-concurrency=1 test/unit.test.mjs test/preflight.test.mjs test/doctor.test.mjs test/gas.test.mjs test/fees.test.mjs test/ship.test.mjs",
     "test:live": "npm run build && node --test --test-reporter=spec test/live.test.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@gatedpath/agent-rules": "0.2.2",
-    "@gatedpath/chains": "0.2.2"
+    "@gatedpath/agent-rules": "0.2.3",
+    "@gatedpath/chains": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",