@gatedpath/preflight 0.2.1 → 0.2.2

package/README.md

@@ -93,7 +93,8 @@ and `reports/gas-151-2026-09-14.md`. On both, 21,000 gas came to 1.000 US cents
 ## 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 +105,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/gas.d.ts

@@ -62,7 +62,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;

package/dist/gas.js

@@ -11,6 +11,21 @@ import { PRICE_FEED_DECIMALS, chainById, formatUnits, getLatestPrice, toCaller }
 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. */
@@ -175,6 +190,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 +228,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/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;

package/dist/ship.js

@@ -13,7 +13,7 @@ import { chainById, decodeWords, ethCall, isAllowed, toCaller } from '@gatedpath
 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';
@@ -151,7 +151,7 @@ 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)
@@ -214,7 +214,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,
     };
@@ -316,7 +316,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) {
@@ -343,6 +343,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.2",
   "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": {
@@ -40,8 +40,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@gatedpath/agent-rules": "0.2.1",
-    "@gatedpath/chains": "0.2.1"
+    "@gatedpath/agent-rules": "0.2.2",
+    "@gatedpath/chains": "0.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",