@gatedpath/preflight 0.2.1 → 0.2.3

package/README.md

@@ -90,10 +90,31 @@ 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
-<151|153> --account <keystore-name> [--admin <safe>] [--gas <n>]` (also `npm run ship` in a scaffold
+<151|153> --account <keystore-name> [--admin <safe>] [--gas <n>]` (or `--address <0x…>` in place of
+`--account`, or `DEPLOYER` in `.env`; also `npm run ship` in a scaffold
 and the MCP server's `ship_report` tool) runs the gas report first (its deployment row is the gas the
 balance check prices), then pre-flight's seven checks with the keystore's address, checks the verifier
 (`--verifier` or `VERIFIER` in `.env`; required on 151, where a missing one fails and on 153 warns that
@@ -104,7 +125,16 @@ the deployer and admin readings, the contracts from `deployments/<chain>-*.json`
 constructor arguments and the exact `forge verify-contract` command, the gas table, the tests, the
 Slither line, the compiler pins, and the list of what the report does not prove. It refuses to write
 when any check fails and exits 1 with the failing lines. Run it again after the deploy to fill in the
-contract section; the file is dated in UTC.
+contract section; the file is dated in UTC. On 153 the report also says how many faucet claims the
+deployment needs at today's base fee (the deployment rows plus the 25% margin, 500 test RBNT a claim,
+one a day); `redbelly gas` prints the same line.
+
+Two things learnt on the first real deploy (17 October 2026). `cast wallet address --account` asks for
+the keystore password on a terminal, so run `redbelly ship` in one, not from an editor's run button;
+without a terminal pass `--password-file`, or `--address` and no cast call is made. And the deploy
+command itself needs `--sender <your address>` beside `--account`: without it forge rehearses as its
+default sender, which fails `isAllowed`, and the scaffold's deploy script now says so and refuses to
+broadcast.
 
 The scaffold's `RedbellyDeployScript.sol` refuses to broadcast on 151 without `deployments/ship-151-<today>.md`
 (a dry run says so and continues; 153 warns), and the Hardhat deploy script does the same. Tested on

package/dist/checks/compiler.js

@@ -6,6 +6,15 @@ export function checkCompilerPins(config) {
     const where = `${config.file}${config.profile ? ` (${config.kind === 'foundry' ? 'profile' : 'network'} ${config.profile})` : ''}`;
     const data = { solc: config.solc, evmVersion: config.evmVersion, file: config.file, profile: config.profile };
     const problems = [];
+    // A project that vendors a suite with its own compiler (ERC-3643's reference contracts pin 0.8.17, which
+    // knows neither prague nor cancun) can only build with solc detected per file. The pin then lives in each
+    // file's pragma, which this check does not read, so it warns instead of failing (card 15, 17 October 2026).
+    if (config.kind === 'foundry' && config.solc === null && config.autoDetectSolc) {
+        const evmOk = config.evmVersion !== null && config.evmVersion.toLowerCase() === EVM_PIN;
+        return { id: 'compiler-pins', status: evmOk ? 'warn' : 'fail', reason: evmOk
+                ? `${where} detects solc per file (auto_detect_solc = true) and sets EVM ${EVM_PIN}. The pin is not in the config: your own files must say pragma solidity ${SOLC_PIN}; a vendored dependency may compile with its own solc for the newest EVM it knows.`
+                : `${where} detects solc per file but ${config.evmVersion === null ? 'sets no evm_version' : `sets evm version ${config.evmVersion}, not ${EVM_PIN}`}; Redbelly is Prague.`, data };
+    }
     if (config.solc === null)
         problems.push(`no ${config.kind === 'foundry' ? 'solc_version' : 'solidity version'} is pinned`);
     else if (config.solc !== SOLC_PIN)

package/dist/checks/deployer.js

@@ -16,12 +16,12 @@ export async function resolveDeployer(src) {
         const args = ['wallet', 'address', '--account', src.account];
         if (src.passwordFile)
             args.push('--password-file', src.passwordFile);
-        const r = await run('cast', args, { cwd: src.cwd, env: src.env, timeoutMs: 60_000, stdin: '' });
+        const r = await run('cast', args, { cwd: src.cwd, env: src.env, timeoutMs: 180_000, stdin: '' });
         if (r.spawnError)
             return { address: null, how: '--account', error: `cast is not installed or not on PATH (${r.spawnError}); install Foundry or pass --address for a read-only run.` };
         const m = /0x[0-9a-fA-F]{40}/.exec(r.stdout);
         if (r.code !== 0 || !m)
-            return { address: null, how: '--account', error: `cast wallet address --account ${src.account} failed: ${(r.stderr || r.stdout).trim().split('\n').pop() ?? 'no output'}.` };
+            return { address: null, how: '--account', error: `cast wallet address --account ${src.account} failed: ${(r.stderr || r.stdout).trim().split('\n').pop() ?? 'no output'}. cast asks for the keystore password on a terminal; without one pass --password-file or --address.` };
         return { address: m[0], how: `cast wallet address --account ${src.account}` };
     }
     return { address: null, how: 'none' };

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export interface ProjectConfig {
     file: string | null;
     profile: string | null;
     solc: string | null;
+    /** foundry `auto_detect_solc = true`: solc chosen per file from its pragma; the pin cannot be read from the config alone. */
+    autoDetectSolc: boolean;
     evmVersion: string | null;
     optimizerRuns: number | null;
     /** foundry: `src`; hardhat: `contracts`. */

package/dist/config.js

@@ -16,7 +16,7 @@ export function readProjectConfig(project, profile, env = process.env) {
         if (existsSync(file))
             return readHardhatConfig(file, profile ?? null);
     }
-    return { kind: 'none', file: null, profile: null, solc: null, evmVersion: null, optimizerRuns: null, sourceDir: 'src', chainId: null, rpcEndpoints: {}, rpcUrl: null };
+    return { kind: 'none', file: null, profile: null, solc: null, autoDetectSolc: false, evmVersion: null, optimizerRuns: null, sourceDir: 'src', chainId: null, rpcEndpoints: {}, rpcUrl: null };
 }
 /** Enough TOML for foundry.toml: sections, dotted headers, scalars, one-line arrays, comments. */
 export function parseToml(text) {
@@ -125,6 +125,7 @@ export function readFoundryConfig(file, profile) {
         file,
         profile,
         solc: str('solc') ?? str('solc_version'),
+        autoDetectSolc: get('auto_detect_solc') === true,
         evmVersion: str('evm_version'),
         optimizerRuns: num('optimizer_runs'),
         sourceDir: str('src') ?? 'src',
@@ -166,6 +167,7 @@ export function readHardhatConfig(file, network) {
         file,
         profile: chosen,
         solc,
+        autoDetectSolc: false,
         evmVersion: evm ? evm[1] : null,
         optimizerRuns: runs ? Number(runs[1]) : null,
         sourceDir: contractsDir ? contractsDir[1].replace(/^\.\//, '') : 'contracts',

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;
@@ -62,7 +64,24 @@ export interface GasReport {
         readonly added: readonly string[];
         readonly removed: readonly string[];
     } | null;
+    /** Testnet only: what the deployment rows cost in faucet claims, with pre-flight's 25% margin, at this quote. */
+    readonly faucet: FaucetDays | null;
 }
+export interface FaucetDays {
+    /** What one FAUCETME claim pays, in test RBNT, and how often (read 15 September 2026). */
+    readonly perClaimRbnt: number;
+    readonly claimsPerDay: number;
+    /** Deployment gas summed over the rows, plus the 25% pre-flight's balance check adds. */
+    readonly gasWithMargin: bigint;
+    readonly rbnt: number;
+    readonly claims: number;
+    readonly days: number;
+    readonly pricedAt: string;
+}
+export declare const FAUCET_PER_CLAIM_RBNT = 500;
+export declare const FAUCET_CLAIMS_PER_DAY = 1;
+/** Faucet claims a project needs before its deploy: the deployment rows, 25% on top, at the quote's base fee and price. 153 only. */
+export declare function faucetDays(rows: readonly PricedRow[], quote: GasQuote): FaucetDays | null;
 export interface GasOptions {
     /** A Foundry project, or a scaffold root (its contracts/ is used). Default: cwd. */
     project?: string;
@@ -97,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,10 +7,25 @@
 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;
+export const FAUCET_PER_CLAIM_RBNT = 500;
+export const FAUCET_CLAIMS_PER_DAY = 1;
+/** Faucet claims a project needs before its deploy: the deployment rows, 25% on top, at the quote's base fee and price. 153 only. */
+export function faucetDays(rows, quote) {
+    if (quote.chain !== 153)
+        return null;
+    const deploys = rows.filter((r) => r.item === 'deployment');
+    if (deploys.length === 0)
+        return null;
+    const gas = deploys.reduce((a, r) => a + r.gas, 0n);
+    const gasWithMargin = gas + gas / 4n;
+    const rbnt = Number(gasWithMargin * quote.baseFeeWei) / 1e18;
+    const claims = Math.max(1, Math.ceil(rbnt / FAUCET_PER_CLAIM_RBNT));
+    return { perClaimRbnt: FAUCET_PER_CLAIM_RBNT, claimsPerDay: FAUCET_CLAIMS_PER_DAY, gasWithMargin, rbnt, claims, days: Math.ceil(claims / FAUCET_CLAIMS_PER_DAY), pricedAt: quote.priceTimestamp };
+}
 // ---- parsing, pure ----
 const SNAPSHOT_LINE = /^([A-Za-z0-9_$]+):(\S.*?)\s+\((.*)\)\s*$/;
 /** `.gas-snapshot`: `Contract:test() (gas: N)`, fuzz lines by their mean (μ), invariant lines (no gas) skipped. */
@@ -90,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)`);
@@ -100,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,
@@ -175,6 +192,7 @@ export async function runGas(opts = {}) {
         quote,
         rows: priced.rows,
         diff: diffFile ? { file: diffFile, rows: before.length, added: priced.added, removed: priced.removed } : null,
+        faucet: faucetDays(priced.rows, quote),
     };
 }
 // ---- text ----
@@ -212,6 +230,8 @@ export function renderGasText(report) {
     lines.push('');
     if (deploys.length)
         lines.push(`deployment: ${deploys.map((d) => `${d.contract} ${num(d.gas)} gas = ${rbnt6(d.rbnt)} RBNT = US$${fixed(d.usd, 4)}`).join('; ')}. Pre-flight's balance check adds 25% on top; pass its --gas the figure here.`);
+    if (report.faucet)
+        lines.push(`faucet: ${num(report.faucet.gasWithMargin)} gas with the 25% margin = ${fixed(report.faucet.rbnt, 1)} test RBNT at this base fee = ${report.faucet.claims} claim${report.faucet.claims === 1 ? '' : 's'} of ${report.faucet.perClaimRbnt} (${report.faucet.days} day${report.faucet.days === 1 ? '' : 's'}, one claim a day) before you can deploy. Priced at ${report.faucet.pricedAt}; the base fee moves, so re-run on the day.`);
     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';
 }

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-cli.d.ts

@@ -1,5 +1,5 @@
 import type { ShipOptions } from './ship.js';
-export declare const SHIP_HELP = "redbelly ship --chain <151|153> --account <keystore-name> [options]\n\nRuns pre-flight (seven checks) with the keystore's address, checks the Slither sidecar, runs\nforge test and the five-state suites, prices the gas report at the chain's base fee and feed\nprice, reads the deployer and the admin (isAllowed, Safe 1.4.1, threshold, owners), and writes\ndeployments/ship-<chain>-<date>.md with every check and its result, the addresses, the\nconstructor arguments and the verify command. Refuses to write when any check fails. The\ndeploy script refuses to broadcast on 151 without a report dated today; 153 warns.\n\n  --chain <151|153>        required\n  --account <name>         required; Foundry keystore name, resolved with cast wallet address\n  --password-file <path>   passed through to cast (or set ETH_PASSWORD)\n  --admin <0x\u2026>            the Safe that receives every role (or ADMIN_SAFE in .env); required on 151\n  --gas <units>            deployment gas for the balance check (default: the gas report's deployment row)\n  --verifier <0x\u2026>         the dApp's verifier (or VERIFIER in .env); required on 151\n  --project <dir>          Foundry project or scaffold root (default: current directory)\n  --rpc <url>              JSON-RPC endpoint (default: the governors RPC for --chain; a fork works)\n  --out <path>             write the report here instead\n  --json                   print the report as JSON (the file is still written when checks pass)\n  --version, --help\n";
+export declare const SHIP_HELP = "redbelly ship --chain <151|153> --account <keystore-name> [options]\n           (or --address <0x\u2026> in place of --account; DEPLOYER in .env also works)\n\nRuns pre-flight (seven checks) with the keystore's address, checks the Slither sidecar, runs\nforge test and the five-state suites, prices the gas report at the chain's base fee and feed\nprice, reads the deployer and the admin (isAllowed, Safe 1.4.1, threshold, owners), and writes\ndeployments/ship-<chain>-<date>.md with every check and its result, the addresses, the\nconstructor arguments and the verify command. Refuses to write when any check fails. The\ndeploy script refuses to broadcast on 151 without a report dated today; 153 warns.\n\n  --chain <151|153>        required\n  --account <name>         Foundry keystore name, resolved with cast wallet address. cast asks for the\n                           keystore password on the terminal, so run this in one (not from an editor's\n                           run button); without a terminal pass --password-file, or use --address\n  --address <0x\u2026>          the deployer's address, no cast call; the report says it came this way\n  --password-file <path>   passed through to cast (or set ETH_PASSWORD)\n  --admin <0x\u2026>            the Safe that receives every role (or ADMIN_SAFE in .env); required on 151\n  --gas <units>            deployment gas for the balance check (default: the gas report's deployment row)\n  --verifier <0x\u2026>         the dApp's verifier (or VERIFIER in .env); required on 151\n  --project <dir>          Foundry project or scaffold root (default: current directory)\n  --rpc <url>              JSON-RPC endpoint (default: the governors RPC for --chain; a fork works)\n  --out <path>             write the report here instead\n  --json                   print the report as JSON (the file is still written when checks pass)\n  --version, --help\n";
 export declare function parseShipArgs(argv: readonly string[]): (Partial<ShipOptions> & {
     json: boolean;
     help: boolean;

package/dist/ship-cli.js

@@ -3,6 +3,7 @@
 // arguments. --json for agents. Never takes a key: --account names a keystore that cast reads.
 import { SHIP_VERSION, renderShipText, runShip, shipReportJson, ShipUsageError } from './ship.js';
 export const SHIP_HELP = `redbelly ship --chain <151|153> --account <keystore-name> [options]
+           (or --address <0x…> in place of --account; DEPLOYER in .env also works)
 
 Runs pre-flight (seven checks) with the keystore's address, checks the Slither sidecar, runs
 forge test and the five-state suites, prices the gas report at the chain's base fee and feed
@@ -12,7 +13,10 @@ constructor arguments and the verify command. Refuses to write when any check fa
 deploy script refuses to broadcast on 151 without a report dated today; 153 warns.
 
   --chain <151|153>        required
-  --account <name>         required; Foundry keystore name, resolved with cast wallet address
+  --account <name>         Foundry keystore name, resolved with cast wallet address. cast asks for the
+                           keystore password on the terminal, so run this in one (not from an editor's
+                           run button); without a terminal pass --password-file, or use --address
+  --address <0x…>          the deployer's address, no cast call; the report says it came this way
   --password-file <path>   passed through to cast (or set ETH_PASSWORD)
   --admin <0x…>            the Safe that receives every role (or ADMIN_SAFE in .env); required on 151
   --gas <units>            deployment gas for the balance check (default: the gas report's deployment row)
@@ -50,6 +54,9 @@ export function parseShipArgs(argv) {
             case '--account':
                 o.account = next();
                 break;
+            case '--address':
+                o.address = next();
+                break;
             case '--password-file':
                 o.passwordFile = next();
                 break;
@@ -91,9 +98,13 @@ export function parseShipArgs(argv) {
     if (!o.help && !o.version) {
         if (!o.chain)
             throw new Error(`--chain 151 or 153 is required\n\n${SHIP_HELP}`);
-        if (!o.account)
-            throw new Error(`--account <keystore-name> is required: the report carries the deployer's address and its isAllowed reading\n\n${SHIP_HELP}`);
-        if (!/^[A-Za-z0-9._-]{1,64}$/.test(o.account))
+        if (!o.account && !o.address && !process.env['DEPLOYER'])
+            throw new Error(`--account <keystore-name> is required (or --address <0x…>, or DEPLOYER in the environment): the report carries the deployer's address and its isAllowed reading\n\n${SHIP_HELP}`);
+        if (o.account && o.address)
+            throw new Error('give --account or --address, not both');
+        if (o.address && !/^0x[0-9a-fA-F]{40}$/.test(o.address))
+            throw new Error('--address must be a 20-byte hex address');
+        if (o.account && !/^[A-Za-z0-9._-]{1,64}$/.test(o.account))
             throw new Error('--account: keystore names use letters, digits, dot, dash and underscore only');
     }
     return o;

package/dist/ship.d.ts

@@ -7,8 +7,10 @@ export interface ShipOptions {
     /** Foundry project or scaffold root (its contracts/ is used). Default: cwd. */
     project?: string;
     chain: 151 | 153;
-    /** Foundry keystore name; cast resolves the address, nothing else is read from it. */
-    account: string;
+    /** Foundry keystore name; cast resolves the address, nothing else is read from it. One of account, address or DEPLOYER in .env. */
+    account?: string;
+    /** The deployer's address given directly: no cast call, no password prompt. */
+    address?: string;
     passwordFile?: string;
     /** The Safe that receives every role. Required on 151; ADMIN_SAFE in .env fills it in. */
     admin?: string;
@@ -31,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,14 +6,14 @@
 // 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';
 import { readProjectConfig } from './config.js';
 import { readDotEnv } from './dotenv.js';
 import { readAdmin } from './checks/admin.js';
-import { parseGasReportJson, priceRows, quoteGas } from './gas.js';
+import { faucetDays, parseGasReportJson, priceRows, quoteGas } from './gas.js';
 import { run } from './proc.js';
 import { DEFAULT_GAS, runPreflight } from './run.js';
 import { findGatedSuites, summariseTests } from './suites.js';
@@ -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']),
@@ -151,14 +157,14 @@ export async function runShip(opts) {
     // 2. pre-flight, seven checks, with the keystore's address and the measured deployment gas
     const gasForBalance = opts.gas !== undefined ? BigInt(opts.gas) : (deploymentGas ?? DEFAULT_GAS);
     const admin = opts.admin ?? rootEnv['ADMIN_SAFE'];
-    const preflight = await runPreflight({ project: dir, chain, rpc, account: opts.account, ...(opts.passwordFile ? { passwordFile: opts.passwordFile } : {}), ...(admin ? { admin } : {}), gas: gasForBalance, env });
+    const preflight = await runPreflight({ project: dir, chain, rpc, ...(opts.account ? { account: opts.account } : {}), ...(opts.address ? { address: opts.address } : {}), ...(opts.passwordFile ? { passwordFile: opts.passwordFile } : {}), ...(admin ? { admin } : {}), gas: gasForBalance, env });
     for (const c of preflight.checks)
         checks.push({ id: c.id, status: c.status, reason: c.reason, ...(c.data ? { data: c.data } : {}) });
     if (chain === 151 && !admin)
         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))
@@ -214,7 +220,7 @@ export async function runShip(opts) {
     const deployerCheck = preflight.checks.find((c) => c.id === 'deployer-verified');
     const deployer = {
         address: preflight.deployer,
-        how: deployerCheck?.data?.['how'] ?? (opts.account ? `cast wallet address --account ${opts.account}` : 'none'),
+        how: deployerCheck?.data?.['how'] ?? (opts.account ? `cast wallet address --account ${opts.account}` : opts.address ? '--address' : 'none'),
         isAllowed: typeof deployerCheck?.data?.['allowed'] === 'boolean' ? deployerCheck.data['allowed'] : null,
         wellKnownDevAccount: deployerCheck?.data?.['wellKnownDevAccount'] === true,
     };
@@ -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');
@@ -316,7 +337,7 @@ export function renderShipMarkdown(r) {
     L.push('## Contracts');
     L.push('');
     if (r.contracts.length === 0) {
-        L.push(`No deployment record for chain ${r.chain} under \`deployments/\` yet. Deploy with \`forge script script/Deploy.s.sol --rpc-url ${r.network === 'mainnet' ? 'redbelly_mainnet' : 'redbelly_testnet'} --account <keystore-name> --broadcast\`, then run \`redbelly ship\` again today: this section fills in with the address, the constructor arguments and the exact verify command.`);
+        L.push(`No deployment record for chain ${r.chain} under \`deployments/\` yet. Deploy with \`forge script script/Deploy.s.sol --rpc-url ${r.network === 'mainnet' ? 'redbelly_mainnet' : 'redbelly_testnet'} --account <keystore-name> --sender ${r.deployer.address ?? '<your-address>'} --broadcast\`, then run \`redbelly ship\` again today: this section fills in with the address, the constructor arguments and the exact verify command.`);
     }
     else {
         for (const c of r.contracts) {
@@ -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
@@ -343,6 +366,9 @@ export function renderShipMarkdown(r) {
         const q = r.gas.quote;
         L.push(`Priced at block ${fmt(q.block)}: base fee ${(Number(q.baseFeeWei) / 1e9).toLocaleString('en-US', { maximumFractionDigits: 2 })} gwei, RBNT US$${q.usdPerRbnt} on the feed at ${q.priceFeed} (${q.priceTimestamp}). Gas is priced in US dollars on this chain and converted to RBNT at execution, so the cents column is the stable one.`);
         L.push('');
+        const faucet = faucetDays(r.gas.rows, r.gas.quote);
+        if (faucet)
+            L.push(`Faucet: the deployment rows with pre-flight's 25% margin come to ${fmt(faucet.gasWithMargin)} gas = ${faucet.rbnt.toFixed(1)} test RBNT at this base fee, ${faucet.claims} claim${faucet.claims === 1 ? '' : 's'} of ${faucet.perClaimRbnt} from the faucet (${faucet.days} day${faucet.days === 1 ? '' : 's'}, one claim a day). The base fee moves; re-run on the day.`, '');
         if (r.gas.deployment)
             L.push(`Deployment of ${r.gas.deployment.contract}: ${fmt(r.gas.deployment.gas)} gas = ${short(r.gas.deployment.rbnt)} RBNT = ${r.gas.deployment.cents.toFixed(2)} US cents. Pre-flight's balance check used ${fmt(BigInt(r.preflight.checks.find((c) => c.id === 'balance')?.data?.['gas'] ?? '0'))} gas with 25% on top.`);
         L.push('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/preflight",
-  "version": "0.2.1",
+  "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.1",
-    "@gatedpath/chains": "0.2.1"
+    "@gatedpath/agent-rules": "0.2.3",
+    "@gatedpath/chains": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",