@artblocks/abx-cli 0.1.0-alpha.5 → 0.1.0-alpha.50

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @artblocks/abx-cli
+
+## 0.1.0-alpha.50
+
+### Patch Changes
+
+- 4512962: Enable Base production as beta, add a keyless read fallback, and surface production risk and paired-testnet guidance in the CLI, agent skill, and public docs.
+- Updated dependencies [4512962]
+  - @artblocks/abx-sdk@0.1.0-alpha.37
+  - @artblocks/abx-indexer@0.1.0-alpha.38
+  - @artblocks/abx-storage@0.1.0-alpha.37
+  - @artblocks/abx-token-api@0.1.0-alpha.40
+
+## 0.1.0-alpha.49
+
+### Patch Changes
+
+- Updated dependencies [5522192]
+  - @artblocks/abx-sdk@0.1.0-alpha.36
+  - @artblocks/abx-indexer@0.1.0-alpha.37
+  - @artblocks/abx-storage@0.1.0-alpha.36
+  - @artblocks/abx-token-api@0.1.0-alpha.39
+
+## 0.1.0-alpha.48
+
+### Patch Changes
+
+- 70d2761: Make release-candidate automation fail closed: accept the documented hot-signing flag for code
+  editions, simulate purchase dry-runs as the configured hot signer, and return a failed exit status
+  when any requested render fails.
+
+## 0.1.0-alpha.47
+
+### Patch Changes
+
+- 5e93246: Correct the bundled agent guidance for Arbitrum Sepolia's canonical contract deployment.
+  - @artblocks/abx-storage@0.1.0-alpha.35
+
+## 0.1.0-alpha.46
+
+### Patch Changes
+
+- b6f941d: Preserve authorship fields in exact deploy replay commands, keep deferred-mint staging narration
+  accurate, and distinguish chain-resident image bytes from independently hash-verified content.
+
+## 0.1.0-alpha.45
+
+### Minor Changes
+
+- 21e3d6c: Drop-in for existing v2 integrations; new deployments use the v3 production-candidate contracts.
+  Record the synchronized v3 factory generation and testnet deployments, retain full v2 service
+  compatibility (including already-assigned v2 sale minters), and update the renderer scaffold to
+  `abx-contracts` 3.0.0.
+- a73922c: Add a typed, machine-readable chain-support registry. Deploy and record canonical contracts for
+  explicit Arbitrum Sepolia qualification while keeping Base, Arbitrum One, and Ethereum disabled until
+  production launch gates are complete.
+
+### Patch Changes
+
+- Updated dependencies [21e3d6c]
+- Updated dependencies [a73922c]
+  - @artblocks/abx-sdk@0.1.0-alpha.35
+  - @artblocks/abx-token-api@0.1.0-alpha.38
+  - @artblocks/abx-indexer@0.1.0-alpha.36
+  - @artblocks/abx-storage@0.1.0-alpha.35
+
+## 0.1.0-alpha.44
+
+### Patch Changes
+
+- Updated dependencies [3ddba71]
+- Updated dependencies [9065128]
+  - @artblocks/abx-sdk@0.1.0-alpha.34
+  - @artblocks/abx-token-api@0.1.0-alpha.37
+  - @artblocks/abx-storage@0.1.0-alpha.34
+  - @artblocks/abx-indexer@0.1.0-alpha.35
+
+## 0.1.0-alpha.43
+
+### Patch Changes
+
+- 9242a05: Prepare package metadata, release notes, and public-facing source comments for the initial public
+  source release.
+- Updated dependencies [9242a05]
+  - @artblocks/abx-indexer@0.1.0-alpha.34
+  - @artblocks/abx-sdk@0.1.0-alpha.33
+  - @artblocks/abx-storage@0.1.0-alpha.33
+  - @artblocks/abx-token-api@0.1.0-alpha.36

package/assets/renderer-scaffold/README.md

@@ -1,9 +1,10 @@
-# ABX in-chain renderer scaffold
+# ABX Solidity extension workspace
 
-A ready-to-build Foundry project for the **fully on-chain Solidity art lane** — the artwork is a
-smart contract that computes an SVG (and traits) from the token's `seed` and collector-set
-PostParams. No JavaScript, no browser, no bucket, no resolver, no effect runner: once the renderer
-is deployed and wired, `tokenURI` — name, image, traits — resolves from chain forever.
+A ready-to-build Foundry project for ABX's actual Solidity extension surfaces. Each role remains a
+separate deployable contract: image/traits rendering, configure-time validation, transfer lifecycle,
+and read-time augmentation. Use only the roles your project needs. There is intentionally no
+"minter hook": minting is an external-minter capability, while the three PostParam hooks are
+configure, transfer and augment.
 
 `abx` does **not** compile or deploy Solidity for you; you build, test, and deploy this project with
 Foundry, then hand the deployed address(es) to `abx deploy-code`, which verifies they have code.
@@ -11,16 +12,21 @@ Foundry, then hand the deployed address(es) to `abx deploy-code`, which verifies
 ## What's here
 
 - `src/MyRenderer.sol` — the **image** renderer: seed → geometry, a `palette` HexColor PostParam →
-  tint. **Fork the geometry/palette math for your own art.**
+  tint. **Fork the geometry/palette math for your own work.**
 - `src/MyTraits.sol` — the **attributes** renderer: reads the *same* seed math so traits agree with
   the image by construction.
-- `src/interfaces/` — the two ABX interfaces you implement/read (`IAbxFieldRenderer`, `IAbxParams`).
-  Read `IAbxFieldRenderer.sol` first: it documents **the five invariants** (above all, `render()`
-  must NEVER revert — a revert bricks the whole `tokenURI`, including the collection surface
-  `tokenId == type(uint256).max`).
+- `src/MyHooks.sol` — small wrappers around one reference implementation for each PostParam hook
+  role. Fork a role independently; do not merge their authority just because they share a workspace.
+- `abx-contracts~3.0.0` — the exact-pinned canonical interfaces, 721/1155 fixed-price minters,
+  reference hooks, token implementations and real-clone test harness. The scaffold carries no
+  hand-copied ABX interface.
 - `test/MyRenderer.t.sol` — proves `render()` never reverts (incl. no-seed, no-palette, the
   collection surface, and a fuzz over every seed/tokenId) and that image ↔ traits stay coherent.
-- `script/Deploy.s.sol` — deploys both renderers and prints the addresses + the next command.
+- `script/Deploy.s.sol` deploys renderers; `script/DeployHooks.s.sol` deploys the three hook examples
+  after a token address exists.
+- `script/Preview.s.sol` — a **local preview**, not a test: runs `render()` with representative
+  inputs and writes the actual output to `preview-out/` so you can look at it (open the `.svg` in a
+  browser). `forge test` proves render() behaves; this script is the only way to see what it drew.
 
 ## Build, test, deploy
 
@@ -29,10 +35,23 @@ forge soldeer install          # fetch solady + forge-std (pinned in foundry.tom
 forge build
 forge test                     # MUST pass — especially the never-revert cases
 
+# look at what the renderer actually produces (writes preview-out/image.svg + attributes.json):
+forge script script/Preview.s.sol
+# override the representative token id / seed / palette without editing the script:
+PREVIEW_TOKEN_ID=42 PREVIEW_SEED=0x00...abc PREVIEW_PALETTE=0x00...ff3366 forge script script/Preview.s.sol
+
 # deploy to your testnet, then copy the printed addresses:
 forge script script/Deploy.s.sol --rpc-url <your-rpc-url> --private-key <key> --broadcast
+
+# optional PostParam hooks, deployed separately after the token exists:
+forge script script/DeployHooks.s.sol --sig "run(address,uint256)" <token> 1024 \
+  --rpc-url <your-rpc-url> --private-key <key> --broadcast
 ```
 
+`script/Preview.s.sol`'s gas numbers are a local-EVM sanity check, not a production gas measurement —
+see the disclaimer in that file. For real gas numbers, deploy (above) and read `tokenURI` on the
+actual chain you're targeting.
+
 ## Wire it into a drop
 
 ```bash
@@ -44,6 +63,17 @@ abx deploy-code \
   --name "Your Collection" --symbol SYM [--max N] --sign --for <your wallet>
 ```
 
+Then, only if using the hook examples:
+
+```bash
+abx set-param-hooks <token> --configure <configure> --augment <augment> --transfer <transfer>
+```
+
+The transfer hook is a veto surface and also runs on mint. The reference counts only real
+non-zero-to-non-zero moves and pins `msg.sender` to the token. On ERC-1155 it counts copies moved per
+id; it never pretends a multi-copy id has one current owner. Freeze the selected hook addresses with
+`abx lock-param-hooks` when the project is ready to make that authority immutable.
+
 - `--onchain-uri` (no `--script`/`--code-dir`) is the in-chain lane — a small Solidity SVG is a
   great fit for an on-chain `tokenURI` (unlike a 200KB JS bundle).
 - `--schema palette:HexColor:TokenOwner` declares the collector param your renderer reads. **Omit it

package/assets/renderer-scaffold/foundry.toml

@@ -9,7 +9,12 @@ evm_version = "paris"        # broad multi-chain compatibility (no PUSH0/cancun
 optimizer = true
 optimizer_runs = 1_000_000   # a renderer is deployed once and called forever → optimize runtime
 
+# script/Preview.s.sol writes rendered output here for human inspection (vm.writeFileBinary).
+# Foundry denies filesystem writes by default; this is the narrowest grant that lets it work.
+fs_permissions = [{ access = "read-write", path = "./preview-out" }]
+
 # Dependencies are fetched with soldeer (`forge soldeer install`), pinned here.
 [dependencies]
+abx-contracts = "3.0.0"
 solady = "0.1.26"
 forge-std = "1.16.1"

package/assets/renderer-scaffold/remappings.txt

@@ -1,3 +1,3 @@
 solady/=dependencies/solady-0.1.26/src/
 forge-std/=dependencies/forge-std-1.16.1/src/
-abx/=src/interfaces/
+abx-contracts/=dependencies/abx-contracts-3.0.0/

package/assets/renderer-scaffold/script/DeployHooks.s.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Script, console2} from "forge-std/Script.sol";
+import {MyConfigureHook, MyTransferHook, MyAugmentHook} from "../src/MyHooks.sol";
+
+/// Deploy only the hook roles this project needs. TOKEN must already be deployed because every
+/// write-time hook is pinned to its caller; this avoids a reusable hook accidentally trusting any
+/// contract that knows its selector.
+contract DeployHooks is Script {
+    function run(address token, uint256 maxDataLength) external {
+        vm.startBroadcast();
+        MyConfigureHook configure = new MyConfigureHook(token, maxDataLength);
+        MyTransferHook transfer = new MyTransferHook(token);
+        MyAugmentHook augment = new MyAugmentHook(transfer);
+        vm.stopBroadcast();
+        console2.log("configure hook:", address(configure));
+        console2.log("augment hook  :", address(augment));
+        console2.log("transfer hook :", address(transfer));
+        console2.log(
+            "Next: abx set-param-hooks <token> --configure <configure> --augment <augment> --transfer <transfer>"
+        );
+    }
+}

package/assets/renderer-scaffold/script/Preview.s.sol

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Script, console2} from "forge-std/Script.sol";
+import {IAbxFieldRenderer} from "abx-contracts/src/uri/IAbxFieldRenderer.sol";
+import {MyRenderer} from "../src/MyRenderer.sol";
+import {MyTraits} from "../src/MyTraits.sol";
+import {MockParams} from "../test/MyRenderer.t.sol";
+
+/// @notice A human-inspection harness, not a test. `forge test` is what proves render() behaves
+///         (never reverts, traits agree with the image, etc) — this script exists ONLY because
+///         assertions don't let a person actually LOOK at the SVG/JSON a renderer produces. It
+///         calls the exact same `IAbxFieldRenderer.render(token, tokenId, field)` interface the
+///         deployed ABX token calls at read time, against a `MockParams` standing in for the
+///         token (the same stand-in `test/MyRenderer.t.sol` uses), and writes the raw output to
+///         disk so it can be opened in a browser or editor.
+///
+///         GAS DISCLAIMER — read before trusting any number this script prints: a local
+///         `forge script` run executes against an in-memory EVM with no real chain's calldata
+///         pricing, contract-size/warm-storage state, or congestion. The gas this script reports
+///         (and even a real `--broadcast` dry run) is NOT a production gas measurement. If you
+///         need real numbers, deploy with `script/Deploy.s.sol` and read `tokenURI` on the actual
+///         chain you're targeting.
+///
+/// Usage (from this scaffold's directory, after `forge soldeer install`):
+///   forge script script/Preview.s.sol
+/// Every input has a representative default and is overridable via env vars, so you can preview
+/// a specific token without editing this file:
+///   PREVIEW_TOKEN_ID=42 PREVIEW_SEED=0x00112233445566778899aabbccddeeff00112233445566778899aabbccddee \
+///   PREVIEW_PALETTE=0xff3366 forge script script/Preview.s.sol
+/// Set PREVIEW_TOKEN_ID to `115792089237316195423570985008687907853269984665640564039457584007913129639935`
+/// (type(uint256).max) to preview the collection surface (contractURI) instead of a token.
+/// Output lands in `preview-out/` at the repo root of this scaffold — open `preview-out/image.svg`
+/// in a browser, `preview-out/attributes.json` in an editor.
+contract Preview is Script {
+    function run() external {
+        uint256 tokenId = vm.envOr("PREVIEW_TOKEN_ID", uint256(7));
+        bytes32 seed = vm.envOr("PREVIEW_SEED", bytes32(uint256(0x1234)));
+        // `palette` is a HexColor PostParam: the RGB value packed into the low 3 bytes.
+        bytes32 palette = vm.envOr("PREVIEW_PALETTE", bytes32(uint256(0xff3366)));
+
+        // vm.writeFileBinary does not create parent directories; make sure ours exists.
+        vm.createDir("preview-out", true);
+
+        MyRenderer image = new MyRenderer();
+        MyTraits traits = new MyTraits();
+        MockParams params = new MockParams();
+        params.setToken(tokenId, "seed", seed);
+        params.setToken(tokenId, "palette", palette);
+
+        console2.log("== NOT a gas measurement (see script comment) ==");
+        console2.log("== preview inputs ==");
+        console2.log("tokenId:", tokenId);
+        console2.log("seed   :", vm.toString(seed));
+        console2.log("palette:", vm.toString(palette));
+
+        _renderAndDump(image, address(params), tokenId, "image", "image", "preview-out/image");
+        _renderAndDump(traits, address(params), tokenId, "attributes", "attributes", "preview-out/attributes");
+    }
+
+    /// @dev Runs the ACTUAL renderer interface — the same call the resolver/on-chain metadata
+    ///      renderer makes — and surfaces a revert instead of swallowing it, so a miswired field
+    ///      or a broken invariant shows up here instead of silently bricking `tokenURI` later.
+    function _renderAndDump(
+        IAbxFieldRenderer renderer,
+        address token,
+        uint256 tokenId,
+        bytes32 field,
+        string memory fieldLabel,
+        string memory pathNoExt
+    ) private {
+        console2.log(string.concat("== field: ", fieldLabel, " =="));
+        try renderer.render(token, tokenId, field) returns (string memory contentType, bytes memory data) {
+            string memory path = string.concat(pathNoExt, ".", _extFor(contentType));
+            vm.writeFileBinary(path, data);
+            console2.log("contentType:", contentType);
+            console2.log("bytes      :", data.length);
+            console2.log("written to :", path);
+        } catch Error(string memory reason) {
+            console2.log("REVERTED:", reason);
+        } catch Panic(uint256 code) {
+            console2.log("REVERTED, panic code:", code);
+        } catch (bytes memory lowLevelData) {
+            // A custom error (e.g. MyRenderer.UnsupportedField) has no ABI-decoded reason string —
+            // this is the raw revert data, selector first, so you can tell which error fired.
+            console2.log("REVERTED, raw data:", vm.toString(lowLevelData));
+        }
+    }
+
+    /// @dev Extension purely for local viewing convenience — not part of the on-chain contract.
+    function _extFor(string memory contentType) private pure returns (string memory) {
+        bytes32 ct = keccak256(bytes(contentType));
+        if (ct == keccak256("image/svg+xml")) return "svg";
+        if (ct == keccak256("application/json")) return "json";
+        if (ct == keccak256("text/html")) return "html";
+        if (ct == keccak256("text/plain")) return "txt";
+        return "bin";
+    }
+}

package/assets/renderer-scaffold/src/MyHooks.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {MaxDataLengthConfigureHook} from "abx-contracts/src/reference/MaxDataLengthConfigureHook.sol";
+import {TransferCounterHook} from "abx-contracts/src/reference/TransferCounterHook.sol";
+import {TransferCountAugmentHook} from "abx-contracts/src/reference/TransferCountAugmentHook.sol";
+
+/// Fork these thin wrappers when your project needs different policy. Keeping each lifecycle role
+/// in its own contract means a project only deploys and grants the authority it actually uses.
+contract MyConfigureHook is MaxDataLengthConfigureHook {
+    constructor(address token, uint256 maxDataLength) MaxDataLengthConfigureHook(token, maxDataLength) {}
+}
+
+contract MyTransferHook is TransferCounterHook {
+    constructor(address token) TransferCounterHook(token) {}
+}
+
+contract MyAugmentHook is TransferCountAugmentHook {
+    constructor(TransferCounterHook counter) TransferCountAugmentHook(counter) {}
+}

package/assets/renderer-scaffold/src/MyRenderer.sol

@@ -2,8 +2,8 @@
 pragma solidity ^0.8.20;
 
 import {LibString} from "solady/utils/LibString.sol";
-import {IAbxFieldRenderer} from "abx/IAbxFieldRenderer.sol";
-import {IAbxParams} from "abx/IAbxParams.sol";
+import {IAbxFieldRenderer} from "abx-contracts/src/uri/IAbxFieldRenderer.sol";
+import {IAbxParams} from "abx-contracts/src/extensions/params/IAbxParams.sol";
 
 /// @title MyRenderer — a fully on-chain generative image, tinted by a collector PostParam
 /// @notice FORK THIS. It renders the `image` field as an `image/svg+xml` document computed
@@ -19,7 +19,7 @@ import {IAbxParams} from "abx/IAbxParams.sol";
 ///         (declare the `palette` schema, or the param is fixed at the default and collectors
 ///          can't set it.) Pair with MyTraits.sol so image AND traits read the SAME seed math.
 ///
-///         Swap the geometry/palette math below for your own art. Keep the FIVE INVARIANTS in
+///         Swap the geometry/palette math below for your own work. Keep the FIVE INVARIANTS in
 ///         IAbxFieldRenderer — above all, NEVER revert (a revert bricks the whole tokenURI).
 contract MyRenderer is IAbxFieldRenderer {
     using LibString for uint256;
@@ -53,7 +53,7 @@ contract MyRenderer is IAbxFieldRenderer {
         return (CONTENT_TYPE, bytes(_svg(seed, palette)));
     }
 
-    // ── the art: seed → geometry, palette → tint (replace with your own) ──────────
+    // ── the work: seed → geometry, palette → tint (replace with your own) ─────────
 
     function _svg(bytes32 seed, string memory palette) private pure returns (string memory) {
         uint256 rings = 3 + (uint8(seed[0]) % 6); // 3..8 rings (MUST match MyTraits' math)

package/assets/renderer-scaffold/src/MyTraits.sol

@@ -2,8 +2,8 @@
 pragma solidity ^0.8.20;
 
 import {LibString} from "solady/utils/LibString.sol";
-import {IAbxFieldRenderer} from "abx/IAbxFieldRenderer.sol";
-import {IAbxParams} from "abx/IAbxParams.sol";
+import {IAbxFieldRenderer} from "abx-contracts/src/uri/IAbxFieldRenderer.sol";
+import {IAbxParams} from "abx-contracts/src/extensions/params/IAbxParams.sol";
 
 /// @title MyTraits — on-chain marketplace traits, coherent with MyRenderer
 /// @notice FORK THIS. Renders the `attributes` field as an `application/json` array a marketplace

package/assets/renderer-scaffold/test/MyRenderer.t.sol

@@ -4,7 +4,7 @@ pragma solidity ^0.8.20;
 import {Test} from "forge-std/Test.sol";
 import {MyRenderer} from "../src/MyRenderer.sol";
 import {MyTraits} from "../src/MyTraits.sol";
-import {IAbxParams} from "abx/IAbxParams.sol";
+import {IAbxParams} from "abx-contracts/src/extensions/params/IAbxParams.sol";
 
 /// A tiny stand-in for the ABX contract's param surface, so the renderers can be tested in
 /// isolation — set a seed / palette (or don't) and assert the renderer behaves.
@@ -13,16 +13,47 @@ contract MockParams is IAbxParams {
     mapping(uint256 => mapping(bytes32 => bool)) private ts;
     mapping(bytes32 => bytes32) private cv;
     mapping(bytes32 => bool) private cs;
+    // `Bytes`/`String` params: the bytes32 holds keccak(content), the content lives here.
+    mapping(uint256 => mapping(bytes32 => bytes)) private td;
+    mapping(bytes32 => bytes) private cd;
 
     function setToken(uint256 id, bytes32 key, bytes32 val) external { tv[id][key] = val; ts[id][key] = true; }
     function setContract(bytes32 key, bytes32 val) external { cv[key] = val; cs[key] = true; }
 
+    /// Set a payload-typed (`Bytes`/`String`) param the way the real contract does: the scalar slot
+    /// carries the keccak COMMITMENT and `valueIsHash` is true, so a renderer that reads the bytes32
+    /// gets a hash — the data reader is the only way to the content.
+    function setTokenData(uint256 id, bytes32 key, bytes memory content) external {
+        td[id][key] = content;
+        tv[id][key] = keccak256(content);
+        ts[id][key] = true;
+    }
+    function setContractData(bytes32 key, bytes memory content) external {
+        cd[key] = content;
+        cv[key] = keccak256(content);
+        cs[key] = true;
+    }
+
     function tokenParam(uint256 id, bytes32 key) external view returns (bytes32, bool, bool) {
-        return (tv[id][key], false, ts[id][key]);
+        return (tv[id][key], td[id][key].length > 0, ts[id][key]);
     }
     function contractParam(bytes32 key) external view returns (bytes32, bool, bool) {
-        return (cv[key], false, cs[key]);
+        return (cv[key], cd[key].length > 0, cs[key]);
+    }
+    function tokenParamData(uint256 id, bytes32 key) external view returns (bytes memory) {
+        return td[id][key];
+    }
+    function contractParamData(bytes32 key) external view returns (bytes memory) {
+        return cd[key];
     }
+    function tokenParamKeys(uint256) external pure returns (bytes32[] memory) { return new bytes32[](0); }
+    function tokenParamKeysPaged(uint256, uint256, uint256)
+        external pure returns (bytes32[] memory keys, uint256 total)
+    { return (new bytes32[](0), 0); }
+    function contractParamKeys() external pure returns (bytes32[] memory) { return new bytes32[](0); }
+    function contractParamKeysPaged(uint256, uint256)
+        external pure returns (bytes32[] memory keys, uint256 total)
+    { return (new bytes32[](0), 0); }
 }
 
 contract MyRendererTest is Test {
@@ -107,4 +138,30 @@ contract MyRendererTest is Test {
         (, bytes memory data) = img.render(address(params), tokenId, IMAGE);
         assertTrue(data.length > 0);
     }
+
+    /// READING A PAYLOAD PARAM (`Bytes`/`String`) — the pattern for carrying an actual work
+    /// payload on-chain. The scalar reader hands you a keccak COMMITMENT with `valueIsHash == true`;
+    /// the content only comes from `tokenParamData`. If your renderer reads a `Bytes` param through
+    /// `tokenParam` it will draw from a hash and produce garbage, silently — hence this test.
+    function test_bytesParam_readViaDataReader() public {
+        bytes memory grid = hex"00112233445566778899aabbccddeeff";
+        params.setTokenData(0, "grid", grid);
+
+        // The scalar surface: a commitment, explicitly flagged as one — NOT the content.
+        (bytes32 value, bool valueIsHash, bool isSet) = IAbxParams(address(params)).tokenParam(0, "grid");
+        assertTrue(isSet);
+        assertTrue(valueIsHash, "a Bytes param reports valueIsHash: read the data instead");
+        assertEq(value, keccak256(grid));
+
+        // The data surface: the real bytes, verifiable against that commitment.
+        bytes memory got = IAbxParams(address(params)).tokenParamData(0, "grid");
+        assertEq(got, grid);
+        assertEq(keccak256(got), value, "content must match the on-chain commitment");
+    }
+
+    /// An unset payload param returns empty bytes — your "use a default" signal, never a revert.
+    function test_bytesParam_unsetIsEmpty() public view {
+        assertEq(IAbxParams(address(params)).tokenParamData(0, "grid").length, 0);
+        assertEq(IAbxParams(address(params)).contractParamData("grid").length, 0);
+    }
 }

package/dist/bin.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * abx — the published binary's entry point, and nothing else.
+ *
+ * This file exists for one reason: **ESM links the entire static import graph before any module
+ * body runs.** `main.ts` reaches `@artblocks/abx-indexer` → `node:sqlite` through `output.ts` and
+ * `config.ts`, so on a Node that cannot load `node:sqlite` the process dies during *linking* —
+ * before a single line of our code executes. A guard at the top of `main.ts` could never fire. The
+ * only place a check can run first is a module that imports nothing statically and reaches the rest
+ * of the CLI through a dynamic `import()`.
+ *
+ * What that bought before this file existed: `npm i -g @artblocks/abx-cli && abx doctor` on Node
+ * 22.5 printed a raw `ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite` stack trace.
+ * No mention of abx, Node versions, or what to do — on the first command we tell every user to run.
+ *
+ * We probe the *capability*, not the version number. `node:sqlite` shipped in v22.5.0 behind
+ * `--experimental-sqlite` and lost the flag in v22.13.0 / v23.4.0, so an old Node run with
+ * `NODE_OPTIONS=--experimental-sqlite` genuinely works — refusing it on a version comparison would
+ * be a false negative on a setup the reporter proved out. `engines` states what we *support*; this
+ * guard blocks only what is actually broken.
+ *
+ * KEEP THIS FILE IMPORT-FREE. A single static `import` of anything in the CLI reintroduces the
+ * crash it exists to prevent.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/bin.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * abx — the published binary's entry point, and nothing else.
+ *
+ * This file exists for one reason: **ESM links the entire static import graph before any module
+ * body runs.** `main.ts` reaches `@artblocks/abx-indexer` → `node:sqlite` through `output.ts` and
+ * `config.ts`, so on a Node that cannot load `node:sqlite` the process dies during *linking* —
+ * before a single line of our code executes. A guard at the top of `main.ts` could never fire. The
+ * only place a check can run first is a module that imports nothing statically and reaches the rest
+ * of the CLI through a dynamic `import()`.
+ *
+ * What that bought before this file existed: `npm i -g @artblocks/abx-cli && abx doctor` on Node
+ * 22.5 printed a raw `ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite` stack trace.
+ * No mention of abx, Node versions, or what to do — on the first command we tell every user to run.
+ *
+ * We probe the *capability*, not the version number. `node:sqlite` shipped in v22.5.0 behind
+ * `--experimental-sqlite` and lost the flag in v22.13.0 / v23.4.0, so an old Node run with
+ * `NODE_OPTIONS=--experimental-sqlite` genuinely works — refusing it on a version comparison would
+ * be a false negative on a setup the reporter proved out. `engines` states what we *support*; this
+ * guard blocks only what is actually broken.
+ *
+ * KEEP THIS FILE IMPORT-FREE. A single static `import` of anything in the CLI reintroduces the
+ * crash it exists to prevent.
+ */
+/** Unflagged `node:sqlite`: v22.13.0 on the 22.x line, v23.4.0 on 23.x (nodejs/node#55890). */
+const NODE_FLOOR = '22.13.0';
+const color = !process.env.NO_COLOR && process.stderr.isTTY;
+const red = (s) => (color ? `\x1b[31m${s}\x1b[0m` : s);
+const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+const green = (s) => (color ? `\x1b[32m${s}\x1b[0m` : s);
+/**
+ * True when this Node has `node:sqlite` but only behind `--experimental-sqlite` — i.e. the
+ * v22.5.0–v22.12.x window (and v23.0–v23.3, which is EOL and not worth naming). Only then is the
+ * NODE_OPTIONS escape hatch real; below v22.5.0 the module does not exist at any flag.
+ */
+function flagWouldWork(version) {
+    const [major, minor] = version.split('.').map(Number);
+    if (major === 22)
+        return minor >= 5 && minor < 13;
+    return major === 23;
+}
+function nodeSqliteMessage(version) {
+    const escape = flagWouldWork(version)
+        ? `\n  Need to stay on this Node? It has SQLite, just flag-gated — but abx is untested there:\n    ${green(`NODE_OPTIONS=--experimental-sqlite abx ${process.argv[2] ?? 'doctor'}`)}\n`
+        : '';
+    return (`\n${red('✗')} abx needs Node's built-in SQLite (${dim('node:sqlite')}), and this Node can't load it.\n\n` +
+        `    you have   ${red(`v${version}`)}\n` +
+        `    abx needs  ${green(`v${NODE_FLOOR}`)} or newer\n\n` +
+        `  Upgrade Node, then re-run:\n` +
+        `    ${green('nvm install 22 && nvm use 22')}   ${dim('# or: brew upgrade node')}\n` +
+        `    ${green('abx doctor')}\n` +
+        escape);
+}
+try {
+    await import('node:sqlite');
+}
+catch {
+    process.stderr.write(nodeSqliteMessage(process.versions.node));
+    process.exit(1);
+}
+await import('./main.js');
+export {};
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+FAA+F;AAC/F,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;AAC5D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;IAClD,OAAO,KAAK,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe;IACxC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC;QACnC,CAAC,CAAC,mGAAmG,KAAK,CAAC,0CAA0C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,IAAI;QACvL,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,CACL,KAAK,GAAG,CAAC,GAAG,CAAC,sCAAsC,GAAG,CAAC,aAAa,CAAC,qCAAqC;QAC1G,kBAAkB,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,IAAI;QACxC,kBAAkB,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC,eAAe;QACxD,gCAAgC;QAChC,OAAO,KAAK,CAAC,8BAA8B,CAAC,MAAM,GAAG,CAAC,yBAAyB,CAAC,IAAI;QACpF,OAAO,KAAK,CAAC,YAAY,CAAC,IAAI;QAC9B,MAAM,CACP,CAAC;AACJ,CAAC;AAED,IAAI,CAAC;IACH,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAC9B,CAAC;AAAC,MAAM,CAAC;IACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC"}