@artblocks/abx-cli 0.1.0-alpha.4 → 0.1.0-alpha.41

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+# @artblocks/abx-cli
+
+## 0.1.0-alpha.41
+
+### Minor Changes
+
+- c068a0f: `abx artifacts <address> [--token <id>]` reads a token's `artifacts` manifest directly, instead of
+  fetching and parsing the whole served tokenURI document. Reports every entry plus every
+  producer-registered effect row — current AND stale — each labeled against the token's active
+  `inputsHash`, so a param change that re-addressed a render is diagnosable rather than silently
+  absent. `--remote <name|url>` reads what a hosted resolver actually reports (the surface that owns a
+  hosted project's real artifact set), mirroring the existing `abx verify` / `abx verify --remote`
+  split. Neither "not registered here" nor "not registered on that remote" fails the command — both
+  return a stable `{surface, registered, available, reason, entries, effects}` JSON shape.
+  `@artblocks/abx-token-api` exports the underlying `tokenArtifacts()` read for direct SDK/server use.
+- c068a0f: `abx attach` now distinguishes the on-chain field write from off-chain SERVING — the write can
+  succeed while nothing is able to serve it. It prints the canonical, directly-fetchable URL for every
+  attached key (`{base}/{chainId}/{address}[/<id>]/data/<key>`) so nobody hand-assembles the route, and
+  probes whether a resolver actually answers for the project right now, warning when none does (with
+  no resolver base baked in at all, or with one baked in that isn't currently reachable). `--collection`
+  now correctly reads `contractURIBase` (it previously always read `tokenURIBase`, even for a
+  collection-scope attach).
+- c068a0f: Local data-directory resolution (`.abx-self-host` / `ABX_DATA_DIR`) is now centralized in one SDK
+  resolver (`resolveDataDir` from `@artblocks/abx-sdk/node`) instead of five independent copies of the
+  same fallback across the CLI, indexer, and storage packages — the setup that could silently split a
+  project's SQLite projection from its managed Arweave key into two different directories.
+
+  A handful of READ commands (`status`, `state`, `verify`, `doctor`, `capabilities`, `tokens`,
+  `tokenuri`, `contracturi`, `inspect`, `minter show`) now search upward from the current directory,
+  git-style, for an already-existing `.abx-self-host` before falling back to creating one at cwd —
+  bounded at the home directory, a `.git` repository root, or the filesystem root, and never crossing
+  into an unrelated directory tree. Running one of these from a project subdirectory (e.g. a
+  `contracts/` folder) now finds the same node a run from the project root would, instead of quietly
+  reporting an empty one. `abx status`'s existing `data: <path>` line — and a new one-line notice —
+  name the directory whenever it was found this way. Every WRITE command is unaffected: it always
+  resolves strictly to the current directory, exactly as before, so nothing is ever created somewhere
+  you didn't `cd` into. `ABX_DATA_DIR`, when set, still always wins outright and disables the search
+  entirely.
+
+- c068a0f: Every `deploy` / `deploy-series` / `deploy-code` `--json` emit — dry-run and real send, across every
+  product lane and `deploy-code --resume` — now carries a versioned, structured `plan` object alongside
+  the existing fields: wallet transaction/approval count, expected signer/owner/royalty/minter/payee
+  roles, custody and URI-resolution choices, the mint plan, a cost estimate where one is computed, every
+  warning that run raised, and (code lanes) the per-surface thumbnail/traits/postParams disposition plus
+  dependency-registry info. A field a lane has no answer for is reported as `null`, never silently
+  absent. The human dry-run/confirm output is unchanged, byte for byte.
+- c068a0f: `deploy-code --copies --code-dir <dir>` now works: an EditionCode project can point `code` at a
+  hosted directory build (index.html + assets uploaded to ipfs/arweave/cloud), the same as the
+  existing SeriesCode (721) lane.
+- c068a0f: `deploy-code --copies --image-base <url>` now works: an EditionCode project can bake a
+  deterministic per-id off-chain still (`{base}/{id}.png`), the same field write as the existing
+  SeriesCode (721) lane, mutually exclusive with an on-chain `--image-renderer`. The effect runner's
+  render sweep excludes an id with zero live copies (no mint-time seed drawn yet), mirroring how a
+  burned 721 token is already excluded.
+- c068a0f: `deploy-code --resume <address>` now works against an EditionCode (`--copies`) target, not just
+  SeriesCode. The mint leg diffs per id against that id's own `totalSupply(id)` — pass the same
+  content flags the original deploy used, plus `--mint-count`/`--mint-amount` if it premint any ids.
+- c068a0f: `reconstructProject()` and `reconstructIncremental()` accept `toBlock: 'safe' | 'finalized'` in
+  addition to a literal block number and the existing `'latest'` default. The tag is resolved to a
+  concrete inclusive block number (via the new `resolveBlockTag()`) before any `eth_getLogs` scan
+  starts, and that number — never the tag — is what lands in the persisted `ProjectState.toBlock`. An
+  RPC that doesn't support the requested tag throws the new `BlockTagUnavailableError` instead of
+  silently falling back to `latest`. `SelfHostIndexer#reindex` gained a matching `blockTag` option.
+  Existing callers (the `'latest'`/unset default) are unaffected.
+
+  `abx index --to-block safe|finalized` stops a re-index at a reorg-safe boundary.
+
+- c068a0f: The Solidity renderer scaffold (`abx scaffold renderer` / `abx scaffold solidity`) now ships
+  `script/Preview.s.sol`: a Forge script that runs the actual `IAbxFieldRenderer.render` interface
+  against representative token id / seed / PostParam inputs (all overridable via env vars) and writes
+  the SVG/JSON output to `preview-out/` for human inspection — `forge test` proves the renderer
+  behaves, but never let you look at what it drew. Reverts are surfaced clearly; the script is explicit
+  that its gas output is a local-EVM sanity check, not a production gas measurement.
+- c068a0f: Add `abx replace-script <address> --script <file>` — a safe, first-class way to replace an UNLOCKED
+  code project's on-chain program (`SeriesCode`/`EditionCode`, before `abx lock-script`). It refuses
+  outright on a locked script or a non-code target, diffs the replacement by content against what's
+  on-chain (an index that already matches is never re-sent), handles a smaller replacement by queuing
+  the trailing `removeLastScriptChunk` calls it needs, folds every write and remove into ONE atomic
+  transaction (a revert can never leave a half-applied script), and reads the completed script back to
+  verify it reassembles exactly to the file before reporting success. Supports `--dry-run` and every
+  signing lane.
+
+  The SDK gains the primitives this is built on: `prepareSetScriptChunk`/`prepareRemoveLastScriptChunk`
+  (no `prepare*` wrapper existed for `OnChainScript.sol`'s writers before this — every caller hand-
+  encoded `encodeFunctionData`), plus `planScriptReplace`/`verifyScriptReplace`, which take a small
+  reader interface (mirroring `resume.ts`'s own reader seam) so the diff and post-write verification
+  are testable without a chain.
+
+- c068a0f: SQLite maintenance for existing and long-running self-hosted stores (issue #113). `SqliteStore`
+  gains `autoVacuumMode`/`vacuumStats` (detection), `vacuumConvert` (a one-time, explicit full
+  `VACUUM` for a store that predates incremental auto-vacuum), and `runIncrementalVacuum` (a bounded
+  reclaim pass). `SelfHostIndexer.startVacuumMaintenance` runs that bounded reclaim automatically
+  between chain-watch ticks — never inline with a request. The new `abx vacuum [status|convert|
+incremental]` CLI command exposes both halves to an operator. Also fixes a pragma-ordering bug that
+  left EVERY store — not just pre-existing ones — stuck at `auto_vacuum='none'` despite the earlier
+  incremental auto-vacuum fix (`PRAGMA auto_vacuum` must precede `PRAGMA journal_mode = WAL`, not just
+  the schema's first `CREATE TABLE`).
+- c068a0f: `abx state` now reports every irreversible lock a collection can carry — token/contract URI, script,
+  dependencies, param hooks, and the standard `METADATA_FIELD` set — for both ERC-721 and ERC-1155
+  families, not just `paramHooks.locked`. Each lock is a distinct `true` (frozen) / `false` (open) /
+  `null` (unread — never collapsed into `false`) reading, in both human and `--json` output, alongside
+  the exact owner command that freezes it.
+- c068a0f: `abx verify --json` gains a sibling `availability` field (render/serve-readiness: `available` /
+  `partial` / `unavailable` / `unknown`), kept separate from the integrity-only `ok`/`contentIntegrity`
+  that the command's exit status still reflects exactly as before. A locator-committed `image` field
+  (ipfs/arweave/url/url-template) this command doesn't re-fetch now reports as a `verified: null`
+  content check instead of silently reading as no commitment at all. Fixes a side-bug: `abx verify
+--remote <r> --json` used to route around `--json` entirely and emit no payload — it now emits the
+  same shape as the local lane, plus a `"not-checked"` `contentIntegrity` state for when byte
+  integrity genuinely wasn't asked (no credential, rejected token, or an older resolver).
+- c068a0f: Additive for SDK consumers — a new exported function, nothing existing changed shape or behavior.
+
+  `abx verify` now compares a collection's actual `tokenURIRenderer` and `animation_url` generator
+  pointers against the current canonical singletons for its chain, reporting each as current or
+  not-current (never treating an older-but-working deployment as broken). Adds the SDK helper
+  `isCurrentGenerator` alongside the existing `isCurrentRenderer` probe.
+
+### Patch Changes
+
+- c068a0f: `abx storage upload <path>` now stats the path before reading it, so a directory, a missing file, or
+  an unreadable file gets an actionable error instead of a raw Node errno (`EISDIR: illegal operation
+on a directory, read`, a bare `ENOENT` stack). The directory message points at the commands that
+  actually upload folder content — `abx deploy-series --dir` and `abx deploy-code --code-dir` — since
+  `storage upload` only ever handles a single file.
+- c068a0f: `abx submit-app` no longer fails silently on RPC catch-up: the mint's token id is now recoverable
+  even under `--json` if metadata configuration can't proceed, the first metadata write after a fresh
+  mint retries a few times with backoff before giving up, and a caller who exhausts that bound gets an
+  explicit message naming the token id and confirming a re-run picks up exactly where it left off
+  (never a duplicate mint — the collection is already `claimed`). `--json`'s `withJson` helper also now
+  flushes whatever payload a command already `emit()`-ed before a later step throws, instead of leaving
+  `--json` callers with nothing on stdout when a command fails partway through.
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+- Updated dependencies [c068a0f]
+  - @artblocks/abx-token-api@0.1.0-alpha.34
+  - @artblocks/abx-sdk@0.1.0-alpha.31
+  - @artblocks/abx-indexer@0.1.0-alpha.32
+  - @artblocks/abx-storage@0.1.0-alpha.31
+
+## 0.1.0-alpha.40
+
+### Patch Changes
+
+- 64248d9: Establish the public source baseline and refresh dependency constraints.
+- Updated dependencies [64248d9]
+  - @artblocks/abx-indexer@0.1.0-alpha.31
+  - @artblocks/abx-sdk@0.1.0-alpha.30
+  - @artblocks/abx-storage@0.1.0-alpha.30
+  - @artblocks/abx-token-api@0.1.0-alpha.33
+
+## Unreleased
+
+Public release history begins here.

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~2.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 = "2.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-2.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