@artblocks/abx-cli 0.1.0-alpha.40 → 0.1.0-alpha.42

package/dist/riskgate.js

@@ -15,9 +15,9 @@
  * free just by routing through here — there is no owner-op-specific reason they lacked it; it was
  * simply never wired.
  */
-import { decodeErrorResult, zeroAddress } from 'viem';
+import { decodeErrorResult, formatEther, zeroAddress } from 'viem';
 import { createInterface } from 'node:readline';
-import { assertChainId, envSigningKey, makePublicClient, seriesCodeAbi } from '@artblocks/abx-sdk';
+import { assertChainId, envSigningKey, makePublicClient, pinGas, seriesCodeAbi, GasEstimateBelowFloorError, } from '@artblocks/abx-sdk';
 import { signTx } from './signer.js';
 import { isDryRun } from './flags.js';
 // ── tiny ANSI (kept local — every module here stands alone; see signer.ts/ownerops.ts) ───────
@@ -134,18 +134,36 @@ export function revertReason(err) {
     return short;
 }
 /**
- * `eth_call` the prepared transaction against current state, and say what would happen.
+ * Simulate the prepared transaction against current state, and say what would happen — honestly.
  *
  * This is what makes `--dry-run` an *answer* rather than an echo of its own input. It matters most
  * for a **multicall** — `attach`'s batched pairs, `deploy-code`'s setup — because a multicall is one
  * transaction, so simulating it exercises the whole sequence atomically against real state, with no
  * fork and no new surface.
  *
- * Reports **unknown**, never a false green, whenever it cannot actually prove anything: no signer to
- * simulate as (an owner-gated call from nobody reverts for the wrong reason), a contract deploy, a
- * target that does not exist yet, or an unreachable node.
+ * A dry run that reports `would-succeed` for a send whose real gas turned out to need 49% more than
+ * this function used to check, then failed for real, is a preview asserting an outcome it never
+ * established — the same class of bug fixed for `verify --remote --json` (see `cmdVerifyRemote`'s
+ * fail-closed comment in commands/project.ts): a payload must not claim success it hasn't earned.
+ * Two things had to be true before this could say "would succeed", and neither was checked:
+ *   1. The call executes without reverting — the ORIGINAL check (an `eth_call`, now folded into
+ *      {@link pinGas} below instead of a separate unconstrained call, so the preview shares the
+ *      real send's own gas math, not a second copy of it that could quietly disagree).
+ *   2. The signer can actually PAY for it. `estimateGas` succeeding proves the call is valid; it says
+ *      nothing about whether the account sending it has the ETH to cover `gas × gasPrice (+ value)`.
+ *      A preview that skips this is not "optimistic", it is wrong — the failure this fixes.
+ *
+ * Reports **unknown**, never a false green, whenever it cannot actually prove EITHER of those: no
+ * signer to simulate as, a contract deploy, a target that does not exist yet, an unreachable node, or
+ * a gas estimate that comes back below the transaction's provable floor even after retrying (the
+ * exact same refusal a real send makes — see {@link GasEstimateBelowFloorError}). `unknown` is never
+ * collapsed into `would-succeed` (an optimistic guess) or `would-revert` (a false alarm) — it says
+ * plainly that the question could not be answered, and why.
+ *
+ * `clientOverride` exists for tests: production callers always omit it and get a real client built
+ * from `chainKey`, exactly as before.
  */
-async function simulateDryRun(prepared, chainKey, expectedSigner, narrate = true) {
+async function simulateDryRun(prepared, chainKey, expectedSigner, narrate = true, clientOverride) {
     const label = 'simulation'.padEnd(12);
     const unknown = (why) => {
         if (narrate)
@@ -162,24 +180,47 @@ async function simulateDryRun(prepared, chainKey, expectedSigner, narrate = true
     // preview is the product; the simulation is a bonus). So even constructing the client is guarded —
     // `resolveChain` throws on a chain key it doesn't know, and that must degrade to `unknown`, never
     // turn a preview into a failure.
+    let client;
+    try {
+        client = clientOverride ?? makePublicClient({ chainKey });
+    }
+    catch (err) {
+        return unknown(`could not run the simulation (${revertReason(err)})`);
+    }
     try {
-        const client = makePublicClient({ chainKey });
         const code = await client.getCode({ address: prepared.to });
         if (!code || code === '0x')
             return unknown(`${prepared.to} has no code yet on this chain`);
-        await client.call({
-            account: expectedSigner,
+    }
+    catch (err) {
+        return unknown(`could not run the simulation (${revertReason(err)})`);
+    }
+    // Reuse the REAL send's own gas selection (`pinGas`, execute.ts — the exact function
+    // `makeHotSender` calls at send time) instead of a second, separately-written `eth_call`. Two
+    // benefits: (a) the preview can never independently drift from what the send would actually do,
+    // and (b) a transaction whose real send would REFUSE (every estimate attempt below the provable
+    // floor) is reported as such here too, rather than "succeeding" against an unconstrained call.
+    let gas;
+    try {
+        gas = await pinGas(client, {
+            from: expectedSigner,
             to: prepared.to,
             data: prepared.data,
-            ...(prepared.value && prepared.value !== '0x0' ? { value: BigInt(prepared.value) } : {}),
+            value: prepared.value,
+            gasFloor: prepared.gasFloor,
         });
-        if (narrate)
-            console.log(`    ${dim(label)} ${C.green}✓${C.reset} would succeed ${dim('(eth_call against current state)')}`);
-        return { status: 'would-succeed' };
     }
     catch (err) {
-        // A node that cannot answer is not a failing transaction — do not report one as the other.
+        if (err instanceof GasEstimateBelowFloorError) {
+            // Not a contract-logic revert and not a network hiccup — this is "cannot be determined safe",
+            // the same refusal a real send makes. Reported as `unknown`, never folded into `would-revert`
+            // (nothing was proven to revert) or `would-succeed` (nothing was proven safe either).
+            return unknown(`the gas estimate (${err.estimate}) came back below the ${err.floor} this transaction provably needs, ` +
+                `even after retrying — the same reason a real send would refuse rather than risk an under-funded ` +
+                `transaction. Retry in a few seconds, or against a different RPC.`);
+        }
         const reason = revertReason(err);
+        // A node that cannot answer is not a failing transaction — do not report one as the other.
         if (/fetch|network|timeout|ECONN|unknown chain/i.test(reason))
             return unknown(`could not run the simulation (${reason})`);
         if (narrate) {
@@ -188,6 +229,36 @@ async function simulateDryRun(prepared, chainKey, expectedSigner, narrate = true
         }
         return { status: 'would-revert', reason };
     }
+    // The call is provably executable at `gas` — what's left is whether the signer can actually PAY
+    // for it. This is the check that was missing entirely: a preview that never compares cost against
+    // balance is asserting an outcome it has not earned.
+    let gasPrice;
+    let balance;
+    try {
+        [gasPrice, balance] = await Promise.all([client.getGasPrice(), client.getBalance({ address: expectedSigner })]);
+    }
+    catch (err) {
+        // We proved the call itself would succeed; we just can't price it. Say so — do NOT fall back to
+        // a bare "would succeed" that quietly drops the affordability question it was just asked.
+        return unknown(`the call would succeed, but the cost to send it could not be priced (${revertReason(err)})`);
+    }
+    const value = prepared.value && prepared.value !== '0x0' ? BigInt(prepared.value) : 0n;
+    const cost = gas * gasPrice + value;
+    const priced = { estimatedGas: gas.toString(), estimatedCostWei: cost.toString(), balanceWei: balance.toString() };
+    if (balance < cost) {
+        const reason = `insufficient funds — this send needs ≈${formatEther(cost)} ETH (${gas} gas × ${formatEther(gasPrice)} ` +
+            `ETH/gas${value > 0n ? ` + ${formatEther(value)} ETH value` : ''}) but ${expectedSigner} has only ` +
+            `${formatEther(balance)} ETH — short by ${formatEther(cost - balance)} ETH.`;
+        if (narrate) {
+            console.log(`    ${dim(label)} ${C.orange}✗ would FAIL${C.reset} — ${reason}`);
+            console.log(`    ${dim(''.padEnd(12))} ${dim('sending this now would run out of funds before it lands.')}`);
+        }
+        return { status: 'would-revert', reason, ...priced };
+    }
+    if (narrate) {
+        console.log(`    ${dim(label)} ${C.green}✓${C.reset} would succeed ${dim(`(≈${gas} gas, ≈${formatEther(cost)} ETH — signer holds ${formatEther(balance)} ETH)`)}`);
+    }
+    return { status: 'would-succeed', ...priced };
 }
 /**
  * The one send choke point for a SINGLE already-prepared write: `--dry-run` preview (nothing sent,
@@ -202,19 +273,22 @@ export async function gatedSend(provider, flags, opts) {
     if (isDryRun(flags)) {
         const prepared = await resolveProvider(provider, opts.expectedSigner ?? zeroAddress);
         if (flags.json !== undefined) {
-            const simulation = await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner, false);
+            const simulation = await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner, false, opts.client);
             console.log(JSON.stringify({
                 dryRun: true,
                 sent: false,
                 lane: laneFromFlags(flags),
                 expectedSigner: opts.expectedSigner ?? null,
                 transaction: prepared,
+                // `transaction.gasFloor` (when present) is a PROVEN MINIMUM used to detect an implausible
+                // gas estimate — not a prediction of total cost. `simulation.estimatedGas`/`estimatedCostWei`
+                // are the real numbers, from the same gas selection the send itself uses; trust those.
                 simulation,
             }, null, 2));
         }
         else {
             printDryRunPreview(prepared, opts.expectedSigner);
-            await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner);
+            await simulateDryRun(prepared, opts.chainKey, opts.expectedSigner, true, opts.client);
             console.log(dim(`\n  Re-run without --dry-run to send (lane: ${laneFromFlags(flags)}).\n`));
         }
         return null;

package/dist/riskgate.js.map

@@ -1 +1 @@
-{"version":3,"file":"riskgate.js","sourceRoot":"","sources":["../src/riskgate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"riskgate.js","sourceRoot":"","sources":["../src/riskgate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAC,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAoB,MAAM,MAAM,CAAC;AACpF,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,MAAM,EACN,aAAa,EACb,0BAA0B,GAG3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,MAAM,EAA8C,MAAM,aAAa,CAAC;AAChF,OAAO,EAAC,QAAQ,EAAa,MAAM,YAAY,CAAC;AAEhD,gGAAgG;AAChG,MAAM,CAAC,GAAG,EAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,EAAC,CAAC;AACjH,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;AACpD,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;AAEtD;6FAC6F;AAC7F,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,oGAAoG;IACpG,mGAAmG;IACnG,mGAAmG;IACnG,wEAAwE;IACxE,MAAM,KAAK,GAAI,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC5F,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,8BAA8B,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI;YACzF,8FAA8F;YAC9F,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IACD,oGAAoG;IACpG,qGAAqG;IACrG,oGAAoG;IACpG,4EAA4E;IAC5E,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAClD,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC1C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC5C,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,qCAAqC;IAClE,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,MAAM;QAAE,OAAO,CAAC,gDAAgD;IAC7F,IAAI,aAAa,EAAE;QAAE,OAAO;IAC5B,MAAM,IAAI,KAAK,CACb,iGAAiG;QAC/F,0GAA0G;QAC1G,uFAAuF;QACvF,2DAA2D,CAC9D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe,EAAE,KAAY;IAC7D,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,eAAe;IACxD,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,CAAC,yBAAyB;IACtF,MAAM,EAAE,GAAG,eAAe,CAAC,EAAC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAC,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,OAAO,qBAAqB,EAAE,OAAO,CAAC,CAAC,CAAC;IACjH,EAAE,CAAC,KAAK,EAAE,CAAC;IACX,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;AAChG,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,QAAoB,EAAE,MAAe;IAClE,OAAO,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAoB,EAAE,cAAwB;IACxE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC;IACxF,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnG,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ,CAAC,EAAE,IAAI,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;IACtF,IAAI,cAAc;QAAE,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AACtF,CAAC;AAsBD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,MAAM,IAAI,GAAI,GAAkD,EAAE,IAAI,IAAK,GAAkC,EAAE,KAAK,EAAE,IAAI,CAAC;IAC3H,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,IAAoC,EAAE,IAAI,CAAC;IAC1F,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,iBAAiB,CAAC,EAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,GAAoB,EAAC,CAAC,CAAC;YACpF,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACpE,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAI,GAA+B,EAAE,YAAY,IAAK,GAAa,EAAE,OAAO,IAAI,UAAU,CAAC;IACtG,gGAAgG;IAChG,sDAAsD;IACtD,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,+HAA+H,CAAC;IACzI,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,KAAK,UAAU,cAAc,CAC3B,QAAoB,EACpB,QAAgB,EAChB,cAAwB,EACxB,OAAO,GAAG,IAAI,EACd,cAA6B;IAE7B,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAoB,EAAE;QAChD,IAAI,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,aAAa,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACzE,OAAO,EAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAC,CAAC;IAC1C,CAAC,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC,uDAAuD,CAAC,CAAC;IAC1F,IAAI,CAAC,cAAc,IAAI,cAAc,KAAK,WAAW,EAAE,CAAC;QACtD,OAAO,OAAO,CACZ,8FAA8F;YAC5F,+CAA+C,CAClD,CAAC;IACJ,CAAC;IACD,iGAAiG;IACjG,mGAAmG;IACnG,kGAAkG;IAClG,iCAAiC;IACjC,IAAI,MAAoB,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,cAAc,IAAI,gBAAgB,CAAC,EAAC,QAAQ,EAAC,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,iCAAiC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,QAAQ,CAAC,EAAE,gCAAgC,CAAC,CAAC;IAC7F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,OAAO,CAAC,iCAAiC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;IAED,qFAAqF;IACrF,8FAA8F;IAC9F,gGAAgG;IAChG,gGAAgG;IAChG,+FAA+F;IAC/F,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE;YACzB,IAAI,EAAE,cAAc;YACpB,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,0BAA0B,EAAE,CAAC;YAC9C,8FAA8F;YAC9F,8FAA8F;YAC9F,sFAAsF;YACtF,OAAO,OAAO,CACZ,qBAAqB,GAAG,CAAC,QAAQ,yBAAyB,GAAG,CAAC,KAAK,oCAAoC;gBACrG,kGAAkG;gBAClG,kEAAkE,CACrE,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACjC,2FAA2F;QAC3F,IAAI,4CAA4C,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,OAAO,CAAC,iCAAiC,MAAM,GAAG,CAAC,CAAC;QAC1H,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,iBAAiB,CAAC,CAAC,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;YACjF,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,qDAAqD,CAAC,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,OAAO,EAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAC,CAAC;IAC1C,CAAC;IAED,gGAAgG;IAChG,kGAAkG;IAClG,qDAAqD;IACrD,IAAI,QAAgB,CAAC;IACrB,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,EAAC,OAAO,EAAE,cAAc,EAAC,CAAC,CAAC,CAAC,CAAC;IAChH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gGAAgG;QAChG,0FAA0F;QAC1F,OAAO,OAAO,CAAC,wEAAwE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,MAAM,IAAI,GAAG,GAAG,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,MAAM,MAAM,GAAG,EAAC,YAAY,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAC,CAAC;IAEjH,IAAI,OAAO,GAAG,IAAI,EAAE,CAAC;QACnB,MAAM,MAAM,GACV,yCAAyC,WAAW,CAAC,IAAI,CAAC,SAAS,GAAG,UAAU,WAAW,CAAC,QAAQ,CAAC,GAAG;YACxG,UAAU,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,WAAW,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,SAAS,cAAc,YAAY;YACnG,GAAG,WAAW,CAAC,OAAO,CAAC,mBAAmB,WAAW,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/E,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,CAAC,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;YAC/E,OAAO,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,0DAA0D,CAAC,EAAE,CAAC,CAAC;QAC9G,CAAC;QACD,OAAO,EAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,EAAC,CAAC;IACrD,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CACT,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,kBAAkB,GAAG,CAAC,KAAK,GAAG,UAAU,WAAW,CAAC,IAAI,CAAC,uBAAuB,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CACtJ,CAAC;IACJ,CAAC;IACD,OAAO,EAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,EAAC,CAAC;AAC9C,CAAC;AAYD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAoB,EAAE,KAAY,EAAE,IAAsB;IACxF,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,IAAI,WAAW,CAAC,CAAC;QACrF,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1G,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;gBACzB,MAAM,EAAE,IAAI;gBACZ,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC;gBAC1B,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI;gBAC3C,WAAW,EAAE,QAAQ;gBACrB,0FAA0F;gBAC1F,8FAA8F;gBAC9F,uFAAuF;gBACvF,UAAU;aACX,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;aAAM,CAAC;YACN,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YAClD,MAAM,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACtF,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,+CAA+C,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9F,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,0EAA0E;IAC9G,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,IAAI,WAAW,CAAC,CAAC;IACpF,MAAM,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,QAAQ,EAAE;QACtB,IAAI,EAAE,aAAa,CAAC,KAAK,CAAC;QAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QACjD,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC;KACpC,CAAC,CAAC;AACL,CAAC"}

package/dist/script-chunks.d.ts

@@ -4,5 +4,5 @@ import { type Hex } from 'viem';
  * {@link splitScriptChunks} splits so that join is byte-identical to `source`. A program that does
  * not parse — before OR after that join — is refused here, because `abx verify` does not parse it.
  */
-export declare function planOnChainScript(source: string): Hex[];
+export declare function planOnChainScript(source: string, chunkSize?: number): Hex[];
 //# sourceMappingURL=script-chunks.d.ts.map

package/dist/script-chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-chunks.d.ts","sourceRoot":"","sources":["../src/script-chunks.ts"],"names":[],"mappings":"AAKA,OAAO,EAAQ,KAAK,GAAG,EAAC,MAAM,MAAM,CAAC;AAGrC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,CAWvD"}
+{"version":3,"file":"script-chunks.d.ts","sourceRoot":"","sources":["../src/script-chunks.ts"],"names":[],"mappings":"AAKA,OAAO,EAAQ,KAAK,GAAG,EAAC,MAAM,MAAM,CAAC;AAGrC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE,CAW3E"}

package/dist/script-chunks.js

@@ -10,9 +10,9 @@ import { joinScriptChunks, splitScriptChunks } from '@artblocks/abx-sdk';
  * {@link splitScriptChunks} splits so that join is byte-identical to `source`. A program that does
  * not parse — before OR after that join — is refused here, because `abx verify` does not parse it.
  */
-export function planOnChainScript(source) {
+export function planOnChainScript(source, chunkSize) {
     assertScriptParses(source, 'the script on disk');
-    const parts = splitScriptChunks(source);
+    const parts = chunkSize === undefined ? splitScriptChunks(source) : splitScriptChunks(source, chunkSize);
     const joined = joinScriptChunks(parts);
     if (joined !== source) {
         throw new Error('internal: script chunks do not reassemble to the source. The on-chain generator joins ' +

package/dist/script-chunks.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-chunks.js","sourceRoot":"","sources":["../src/script-chunks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAC,KAAK,EAAW,MAAM,MAAM,CAAC;AACrC,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,wFAAwF;YACtF,6EAA6E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc,EAAE,IAAY;IACtD,IAAI,CAAC;QACH,gGAAgG;QAChG,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAC,QAAQ,EAAE,WAAW,EAAC,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,kCAAkC,GAAG,iDAAiD;YAC3F,sFAAsF;YACtF,wDAAwD,CAC3D,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"script-chunks.js","sourceRoot":"","sources":["../src/script-chunks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAC,KAAK,EAAW,MAAM,MAAM,CAAC;AACrC,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAEvE;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,SAAkB;IAClE,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzG,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,wFAAwF;YACtF,6EAA6E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc,EAAE,IAAY;IACtD,IAAI,CAAC;QACH,gGAAgG;QAChG,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAC,QAAQ,EAAE,WAAW,EAAC,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,kCAAkC,GAAG,iDAAiD;YAC3F,sFAAsF;YACtF,wDAAwD,CAC3D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artblocks/abx-cli",
-  "version": "0.1.0-alpha.40",
+  "version": "0.1.0-alpha.42",
   "license": "MIT",
   "description": "Command-line interface for deploying, operating, indexing, and serving ABX projects.",
   "type": "module",
@@ -39,13 +39,13 @@
   },
   "dependencies": {
     "viem": "^2.56.0",
-    "@artblocks/abx-sdk": "0.1.0-alpha.30",
-    "@artblocks/abx-indexer": "0.1.0-alpha.31",
-    "@artblocks/abx-storage": "0.1.0-alpha.30",
-    "@artblocks/abx-token-api": "0.1.0-alpha.33"
+    "@artblocks/abx-sdk": "0.1.0-alpha.32",
+    "@artblocks/abx-indexer": "0.1.0-alpha.33",
+    "@artblocks/abx-token-api": "0.1.0-alpha.35",
+    "@artblocks/abx-storage": "0.1.0-alpha.32"
   },
   "optionalDependencies": {
-    "@artblocks/abx-effects": "0.1.0-alpha.30"
+    "@artblocks/abx-effects": "0.1.0-alpha.32"
   },
   "devDependencies": {
     "playwright": "1.62.1"

package/skill/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   change an ABX collection, or to determine whether ABX supports a mechanic.
 compatibility: Drives @artblocks/abx-cli on Node 22.13+. Co-versioned with the CLI; install or refresh with `abx skill install`.
 metadata:
-  version: "0.1.0-alpha.40"
+  version: "0.1.0-alpha.42"
 ---
 
 # ABX
@@ -106,8 +106,10 @@ Run `abx capabilities --json` for the current matrix, then load [deploy.md](refe
 
 Important boundaries:
 
-- `deploy-code --copies` supports `--script`, dependencies, and Solidity image/attributes renderers.
-  It does not currently support `--code-dir`, `--image-base`, or `--resume`.
+- `deploy-code --copies` supports `--script`, `--code-dir`, dependencies, Solidity image/attributes
+  renderers, `--image-base` (a deterministic per-id off-chain still, mutually exclusive with
+  `--image-renderer`), and `--resume` (a per-id mint diff — pass the same content flags plus
+  `--mint-amount` if the original deploy premint ids).
 - `--onchain-image` works for static 721s and editions in hot or wallet-signing lanes. It cannot be
   prepared as one cold `--unsigned` bundle because staged transactions depend on prior receipts.
 - A code project may need no public host when its image/traits are computed by Solidity renderers.
@@ -129,7 +131,7 @@ Before deploying, write down the promised value for each applicable row:
 | Animation/live view | the decoded `animation_url`, loaded with a real minted token |
 | Marketplace traits | decoded `attributes`, not merely console output from the program |
 | Parameters and values | `abx state` for schemas; `abx tokens --json` for token values |
-| Attached artifacts | resolver metadata and `/data/<key>`; attachments are not enumerable in bare on-chain metadata |
+| Attached artifacts | `abx artifacts <addr> --token <id>` (entries + current/stale effect rows); attachments are not enumerable in bare on-chain metadata |
 | Byte integrity | `abx verify <addr>` |
 | Hosted lifecycle | `abx status --remote <name> --watch` or provider status |
 

package/skill/reference/code.md

@@ -26,10 +26,27 @@ renderers, marketplace stills and traits, seeds, dependencies, parameters, and c
 | Solidity-computed fields | `--image-renderer` and/or `--attributes-renderer` | on-chain SVG image and/or traits |
 | Hybrid | script plus field renderers | program animation plus Solidity image/traits |
 
+`--script` splits the source into on-chain chunks automatically (default ~22 KB per chunk, the
+practical SSTORE2/EIP-170 limit). Pass `--chunk-size <bytes>` to override the split size — smaller
+values force a multi-chunk program cheaply, which is the fast way to exercise multi-chunk behavior on
+a tiny test script rather than needing a large real one. `abx replace-script`
+([operate.md](operate.md#replacing-an-unlocked-script)) accepts the same flag.
+
+There is no fixed supported script-size ceiling. Post-deploy setup (chunks, PostParam schemas,
+dependency declarations, on-chain-URI legs, reserve mints) rides one combined transaction when it
+fits; a large script splits it into several gas-bounded transactions instead — chunks first, then the
+remaining config, mints strictly last. The dry run's `transactions`/`approvals` reports the real
+count for the whole plan; if any single one is interrupted mid-sequence, `--resume` finishes it (see
+[diagnose.md](diagnose.md#incomplete-deployments)) — every non-mint leg is idempotent, so re-running
+resume is always safe.
+
 Without `--copies`, the contract is SeriesCode (ERC-721). With `--copies <n|open>`, it is EditionCode
 (ERC-1155): N generated ids, each with multiple copies. EditionCode currently supports scripts,
-dependencies, and field renderers. It does not support `--code-dir`, `--image-base`, or `--resume`.
-Run `abx capabilities --json` immediately before planning.
+directory builds (`--code-dir`), dependencies, field renderers, deterministic per-id off-chain stills
+(`--image-base`), and `--resume` for an incomplete deployment (see
+[diagnose.md](diagnose.md#incomplete-deployments) — the mint leg diffs per id, with a new
+`--mint-amount` naming each premint id's intended copy count). Run `abx capabilities --json`
+immediately before planning.
 
 For one generated work with 100 copies, use `--max 1 --copies 100`. Omitting `--max 1` leaves the
 default multi-id space, producing multiple generated ids with 100 copies available for each id.
@@ -105,16 +122,22 @@ a still published to a deterministic public `--image-base` is a manual/backfill
 after relevant parameter changes. An on-chain animation plus automatically updating off-chain still
 requires an operator watching state.
 
-EditionCode does not currently accept `--image-base`. Give it an on-chain image renderer, or run a
-resolver/effects path (`deploy-effects` for continuous rendering; `render --remote` for one-shot
-publication). Do not treat its on-chain animation as a marketplace still.
+EditionCode now accepts `--image-base` too: the same `{base}/{id}.png` url-template, one id space
+finer — `{id}` is the EditionCode id, and every copy of that id shares the one image (there is no
+per-copy addressing). The effect runner never renders an id with zero live copies (no mint-time seed
+has been drawn yet for it), so an unminted premint id is skipped, not errored — it renders once the
+first copy mints. `--image-base` stays mutually exclusive with `--image-renderer` on both lanes.
 
 ### Build directory
 
 Use `--code-dir` for an application bundle whose files are uploaded and addressed as a code artifact.
-It requires external storage and public resolution. Inspect the built output, not only the source
-tree, and verify that every referenced asset is included. `--code-dir` is not yet supported with
-`--copies`.
+It requires external storage and public resolution — a backend without directory upload (`fs`, the
+local default) is refused; pick `--backend ipfs` or `--backend arweave`. Inspect the built output, not
+only the source tree, and verify that every referenced asset is included. The live view 302s through
+the gateway, so the gateway must serve HTML (the shared Pinata public gateway does not — use a
+dedicated gateway or Arweave). `--code-dir` works with `--copies` too (EditionCode): the same upload,
+the same on-chain `code` field, the same gateway rules — `--script` and `--code-dir` remain mutually
+exclusive on both lanes.
 
 ## Plan Solidity field renderers
 

package/skill/reference/deploy.md

@@ -51,7 +51,9 @@ Use `--onchain-uri --backend arweave|ipfs|cloud`. The CLI uploads media, bakes i
 on-chain JSON, and does not require an ABX resolver. This is often the simplest durable path for
 static collections:
 
-- Arweave provides pay-once permanent custody through the configured uploader.
+- Arweave provides pay-once permanent custody through the configured uploader, but needs the
+  optional `@artblocks/abx-storage-arweave` package installed alongside the CLI first (see
+  [hosting.md](hosting.md#arweave)) — it is not part of the default install.
 - IPFS requires maintained pinning and a public gateway; a local kubo gateway is development-only.
 - Cloud requires an authenticated upload endpoint and a distinct public read base/CDN URL.
 
@@ -154,7 +156,12 @@ Do not import code-edition limits into static editions or vice versa. Use the ca
 1. Run `abx doctor`, storage/remote checks needed by the selected path, and command help.
 2. Run the exact command with `--dry-run --json` and a known `--for` address when needed.
 3. Read back contract family, id/copy arithmetic, custody, resolution, public URLs, signer lane,
-   initial mint, transaction count, cost/reach warnings, and irreversible options.
+   initial mint, transaction count, cost/reach warnings, and irreversible options. The JSON payload's
+   `plan` object (every `deploy`/`deploy-series`/`deploy-code` emit, including `--resume`) carries
+   most of this pre-structured — `transactions`, `roles`, `royalty`, `custody`, `mint`, `estimate`,
+   `warnings`, and (code lanes) `surfaces`/`dependencies` — versioned via `plan.schemaVersion`. Prefer
+   it over parsing the human prose for anything it covers; a field it has no answer for is `null`, not
+   absent.
 4. Receive explicit confirmation.
 5. Run the same normalized command without `--dry-run`; do not start another write using the EOA.
 6. Capture the chain, contract address, deploy block, owner, storage locators, and resolver/remote.

package/skill/reference/diagnose.md

@@ -76,8 +76,15 @@ Before resume:
 - read the resume dry run and confirm every proposed transaction;
 - ensure no second writer is operating the same EOA.
 
-EditionCode resume is not currently supported. Inspect state and stop for an explicit recovery or new
-deployment decision rather than applying the 721 recipe.
+EditionCode (`--copies`) targets are supported too — pass the exact same content flags the original
+deploy used, minus `--copies` itself (the standard was fixed at creation and is read from chain, not
+re-specified). The one difference from a 721 resume: name the intended premint plan with
+`--mint-count`/`--mint-amount` if the original deploy premint any ids — the mint leg diffs **per id**
+against that id's own on-chain copy count, not a single whole-contract total, and each shortfall sends
+as one transaction regardless of how many copies are missing. Getting `--mint-count`/`--mint-amount`
+wrong under-reports (an id you meant to premint stays at zero) rather than over-mints (a token cannot
+be un-minted, so the diff only ever tops up a shortfall) — but confirm the intended plan with the
+human before sending if there is any doubt about what the original deploy meant to premint.
 
 ## RPC and chain failures
 
@@ -154,6 +161,12 @@ idempotently skip an existing current artifact. A PostParam change produces a ne
 the watcher or run the explicit one-shot path. Solidity image renderers have no effects job—diagnose
 their on-chain call instead.
 
+`abx artifacts <addr> --token <id> --json` is the direct check for steps 5–7: it reports every
+registered effect row (current and stale) against the token's active `inputsHash`, without fetching
+and parsing the whole served document. A row present but labeled `stale` means a param changed since
+it rendered — re-render, don't assume it's missing. Add `--remote <name|url>` for a hosted project;
+the real artifact set lives on the resolver that serves it, not in this node's local projection.
+
 ## Secret-safe reporting
 
 Include command name, CLI version, chain key, redacted host labels, contract address, transaction hash,

package/skill/reference/hosting.md

@@ -128,6 +128,13 @@ change that prefix without changing the content.
 
 ### Arweave
 
+`--backend arweave` (the default `turbo` provider) needs the optional
+`@artblocks/abx-storage-arweave` package installed alongside the CLI — it is not part of the
+default install, deliberately, so a default `abx` install stays free of Turbo's browser
+wallet-connector dependency tree. If it is missing, the CLI names the exact install command
+(`npm install @artblocks/abx-storage-arweave`) rather than failing unhelpfully; run that command
+once, then retry. `--provider http-bundler` needs neither this package nor any of its dependencies.
+
 The accepted upload and a retrievable gateway object are separate lifecycle states. Use
 `abx storage status <locator> --json`; wait for `ready` instead of uploading duplicates during
 propagation. Upload deduplication is success, not an instruction to top up or switch backends.
@@ -165,6 +172,25 @@ Verify the operational graph:
 5. Token metadata exposes the resulting image/attributes.
 6. A PostParam change reaches the watcher and creates the next inputs-hash render.
 
+### SQLite maintenance for a long-running node
+
+The self-hosted store is one SQLite file. `abx serve` already reclaims freed pages automatically in
+small bounded passes between chain-watch ticks — never inline with a request, so it never adds
+latency to a metadata read. Nothing to schedule for that half.
+
+The other half is explicit and never automatic: a store created before this maintenance shipped
+needs a one-time conversion.
+
+```bash
+abx vacuum                          # status: auto_vacuum mode, page count, freelist size
+abx vacuum convert                  # one-time full VACUUM — only when abx vacuum says the store needs it
+abx vacuum incremental [--pages n]  # one bounded reclaim pass on demand (not running abx serve? use this)
+```
+
+Run `abx vacuum convert` deliberately, not on a schedule: it rewrites the entire file and can briefly
+need up to ~2x its on-disk size. Check `abx vacuum` first; if it already reports `auto_vacuum:
+incremental`, there is nothing to convert.
+
 ## Use lifecycle states
 
 Prefer status over retries. Typical nonterminal states include deployment accepted, indexing,

package/skill/reference/operate.md

@@ -22,8 +22,17 @@ abx tokens <address> --json
 abx contracturi <address>
 abx tokenuri <address> --token <id>
 abx verify <address> --json
+abx artifacts <address> --token <id> --json
 ```
 
+`abx artifacts` reads a token's `artifacts` manifest directly, without fetching and parsing the whole
+served document — entries plus every registered effect row (current and stale, labeled against the
+token's active `inputsHash`). Report which surface answered: this node's local projection, or (with
+`--remote <name|url>`) the hosted resolver that actually owns a hosted project's real artifact set.
+Neither "not registered here" nor "not registered on that remote" is an error — both return a stable
+`{surface, registered, available, reason, entries, effects}` shape. Nothing it reports is onchain data
+itself; every entry is a resolver-published projection.
+
 Use `abx status` or its remote form for projection/render lifecycle. Record active chain, detected
 family, owner/admin, supply and pause state, minter/payee, royalty/cap, URI renderer/pointers, code
 dependencies, schemas/hooks, and lock state.
@@ -116,15 +125,35 @@ repoint is not a re-upload and does not change the committed CID/transaction id.
 
 ### Attachments versus parameters
 
-`abx attach <addr> <key> <locator>` records a named artifact. The resolver exposes the complete
-artifacts list and `/data/<key>` retrieval. Bare on-chain metadata cannot enumerate arbitrary field
-keys, so consumers need a resolver to discover all attachments even when each locator is durable and
-hash-anchored.
+`abx attach <addr> <key> <locator>` records a named artifact. It prints the CANONICAL fetch URL for
+every key (`{base}/{chainId}/{address}[/<id>]/data/<key>`) directly — never hand-build that route.
+It also distinguishes the on-chain field write from off-chain SERVING: an on-chain write can succeed
+while nothing can serve it. With no resolver base baked in at all, it warns there is no serving path
+whatsoever. With one baked in, it probes whether a resolver actually answers for this token right
+now (before the write, since the key itself doesn't exist yet) and warns if not — "the on-chain
+document carries reserved fields only" is a real gap creators hit; the write landing is not proof
+anything can serve it. Bare on-chain metadata cannot enumerate arbitrary field keys, so consumers
+need a resolver to discover all attachments even when each locator is durable and hash-anchored.
 
 PostParams are different: the parameter store enumerates schemas and values on-chain. Read schemas
 with `state` and values with `tokens --json`. Parameters do not require a resolver merely to be
 canonical or enumerable.
 
+### Replacing an unlocked script
+
+`abx replace-script <addr> --script <file>` ships a fix to a code project's on-chain program any
+time before `abx lock-script`. It refuses outright — never warns and proceeds — on a locked script
+or a target that isn't SeriesCode/EditionCode. It diffs by content against what's on-chain (an index
+that already matches is never re-sent), folds every write and remove into ONE atomic transaction (so
+a revert can never leave a half-applied script), and reads the completed script back to verify exact
+reassembly before reporting success. Prefer this over hand-encoding `setScriptChunk` calls.
+
+`--chunk-size <bytes>` overrides the default on-chain split size (~22 KB) — the same flag
+`deploy-code` accepts (see [code.md](code.md#choose-the-runtime-lane)). A small value forces a
+multi-chunk layout, which is the cheap way to exercise growing/shrinking a program across several
+chunks (including the on-chain removal of surplus chunks when shrinking) without needing a large
+real program.
+
 ### Refresh and URI events
 
 `abx refresh` asks external marketplaces to fetch metadata again; it does not fix the metadata or
@@ -175,7 +204,29 @@ Important qualifications:
 - A locked pointer to an upgradeable proxy fixes the address, not its behavior.
 - A transfer-hook address represents a standing ability to veto mints/transfers. Freezing an empty
   hook set is the proof that this power cannot later be added.
+- `lock-field` targets one scope (token, or `--collection`); a token-scope value wins over a
+  collection-scope one when both are set. Locking a scope that ISN'T actually serving the value
+  freezes an empty or overridden slot, not what a viewer sees — the CLI refuses this by default and
+  names the correct command; only `--force-field` proceeds (with a loud warning, never silently).
+  Check `abx tokenuri --token <id>`'s `abx_provenance` (or just try the lock without `--force-field`)
+  before assuming a scope holds the value.
 
 Use `abx verify` and direct state reads to enumerate what remains mutable. Describe the guarantee as
 specific stored values and addresses that can no longer change; do not promise immutable output unless
 every live input and external implementation has actually been bounded.
+
+`abx state <address> --json` reports every lock above in one `locks` object — token/contract URI,
+script, dependencies, param hooks, and the standard `METADATA_FIELD` set — each as `true` (frozen),
+`false` (open), or `null` (unread; never report an unread lock as off). A project's own custom field
+keys are real and independently lockable but are not enumerable from a bare head read; say so rather
+than implying the field scan is exhaustive. Every lock is independent: never infer one lock's state
+from another's.
+
+`abx verify --json` separates two verdicts that must not be conflated: `ok`/`contentIntegrity` is
+content-integrity ONLY (a hash mismatch, or none to check) and is the only field the exit code
+reflects; `availability` is a sibling verdict for render/serve readiness (`available` / `partial` /
+`unavailable` / `unknown`) that a missing render or an un-refetched `ipfs`/`arweave`/`url` locator
+moves, while `ok` stays unaffected by design. Report both, never collapse one into the other.
+`abx verify` also flags whether the project's stored `tokenURIRenderer`/generator pointers are the
+CURRENT canonical singletons — a `false` here means an older-but-working deployment (or a fully
+custom one), never "broken".

package/skill/reference/setup.md

@@ -70,6 +70,20 @@ The local projection and managed Arweave identity remain in `.abx-self-host/` un
 `ABX_DATA_DIR` overrides it. That runtime directory is separate from the renamed `abx` skill and is
 not being renamed. Back up the managed Arweave key with `abx storage backup-key`; never print it.
 
+Every WRITE command (`deploy*`, `add`, `index`, `mint`, `set-*`, …) resolves `.abx-self-host`
+strictly relative to the current directory — it never searches upward, so it never creates a
+project's state somewhere unexpected. A handful of READ commands (`status`, `state`, `verify`,
+`doctor`, `capabilities`, `tokens`, `tokenuri`, `contracturi`, `inspect`, `minter show`) DO search
+upward, git-style, for an already-existing `.abx-self-host` if the current directory doesn't have
+one of its own — bounded at the home directory, a `.git` root, or the filesystem root. Practical
+consequence: `cd`-ing into a project's `contracts/` subdirectory before `abx status` still finds
+that project; the same `cd` before `abx add`/`abx deploy*` creates a NEW, empty node right there
+instead. If a status/verify/etc. answer looks emptier than expected, or a write seems to have
+landed in the wrong place, run bare `abx status` — its `data: <path>` line names the exact
+directory that answered, including a note when it was found by searching upward — or set
+`ABX_DATA_DIR` explicitly rather than guessing. See [Local data
+directory](https://docs.abx.io/docs/using-abx/self-hosting#local-data-directory) for the full rule.
+
 ## Choose one signing lane
 
 Every write uses one of three lanes: