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

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @artblocks/abx-cli
+
+## 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,18 @@ 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.
 
 ## Build, test, deploy
 
@@ -31,6 +34,10 @@ forge test                     # MUST pass — especially the never-revert cases
 
 # 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
 ```
 
 ## Wire it into a drop
@@ -44,6 +51,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

@@ -11,5 +11,6 @@ optimizer_runs = 1_000_000   # a renderer is deployed once and called forever
 
 # 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/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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,94 @@
+import type { Flags } from './flags.js';
+/**
+ * The machine-readable ABX capability contract.
+ *
+ * Keep this deliberately smaller than command help: it records product boundaries and the
+ * supported combinations agents routinely get wrong. Command-specific syntax still belongs to
+ * `abx help <command>`, while deploy planning belongs to `<deploy-command> --dry-run --json`.
+ * Human help, the shipped skill, and tests consume this object instead of maintaining competing
+ * matrices in prose.
+ */
+export declare const ABX_CAPABILITIES: {
+    readonly schemaVersion: 1;
+    readonly supportedChains: readonly string[];
+    readonly deploymentCommands: {
+        readonly deploy: {
+            readonly artifact: "one static work";
+            readonly unique: {
+                readonly contract: "OneOfOneImage (ERC-721)";
+                readonly inputs: readonly ["--image"];
+            };
+            readonly edition: {
+                readonly contract: "OneOfOneEdition (ERC-1155)";
+                readonly selector: "--copies <n|open>";
+                readonly summary: "one work × copies; supports on-chain bytes, on-chain JSON with external media, or a resolver";
+                readonly supported: readonly ["--onchain-image (hot or wallet signing)", "--onchain-uri", "--backend", "--public-base-url"];
+                readonly unsupported: readonly ["--onchain-image with --unsigned"];
+            };
+        };
+        readonly deploySeries: {
+            readonly artifact: "a folder of distinct static works";
+            readonly unique: {
+                readonly contract: "SeriesImage (ERC-721)";
+                readonly inputs: readonly ["--dir"];
+            };
+            readonly edition: {
+                readonly contract: "EditionImage (ERC-1155)";
+                readonly selector: "--copies <n|open>";
+                readonly summary: "N folder items × copies per id; supports on-chain bytes, on-chain JSON with external media, or a resolver";
+                readonly supported: readonly ["--onchain-image (hot or wallet signing)", "--onchain-uri", "--backend", "--public-base-url"];
+                readonly unsupported: readonly ["--onchain-image with --unsigned"];
+            };
+        };
+        readonly deployCode: {
+            readonly artifact: "a program or field renderer whose output depends on token state";
+            readonly unique: {
+                readonly contract: "SeriesCode (ERC-721)";
+                readonly inputs: readonly ["--script", "--code-dir", "--image-renderer", "--attributes-renderer"];
+            };
+            readonly edition: {
+                readonly contract: "EditionCode (ERC-1155)";
+                readonly selector: "--copies <n|open>";
+                readonly summary: "N generated ids × copies per id; supports scripts, dependencies, and Solidity image/trait renderers";
+                readonly supported: readonly ["--script", "--dep", "--dep-registry", "--image-renderer", "--attributes-renderer", "--onchain-uri", "--public-base-url"];
+                readonly unsupported: readonly ["--code-dir", "--image-base", "--resume", "--no-delegation"];
+            };
+        };
+    };
+    readonly extensionRoutes: readonly [{
+        readonly route: "custom minter";
+        readonly command: "abx set-minter";
+        readonly availableOn: "Series and editions";
+        readonly useFor: readonly ["auctions", "allowlists", "raffles", "free claims", "ERC-20 pricing"];
+    }, {
+        readonly route: "configure hook";
+        readonly command: "abx set-param-hooks --configure";
+        readonly availableOn: "SeriesCode and EditionCode";
+        readonly useFor: readonly ["validated writes", "monotonic values", "structured collector input"];
+    }, {
+        readonly route: "transfer hook";
+        readonly command: "abx set-param-hooks --transfer";
+        readonly availableOn: "SeriesCode and EditionCode";
+        readonly useFor: readonly ["transfer restrictions", "soulbinding", "vesting", "redemption", "escrow"];
+    }, {
+        readonly route: "augment hook";
+        readonly command: "abx set-param-hooks --augment";
+        readonly availableOn: "SeriesCode and EditionCode";
+        readonly useFor: readonly ["live derived data", "oracle-fed state", "read-time metadata"];
+    }, {
+        readonly route: "field renderer";
+        readonly command: "abx deploy-code --image-renderer/--attributes-renderer";
+        readonly availableOn: "SeriesCode and EditionCode";
+        readonly useFor: readonly ["on-chain SVG images", "on-chain computed traits"];
+    }];
+    readonly deployTimeChoices: readonly ["contract shape and token standard (--copies)", "code-capable versus static contract type", "burnability (--burnable)", "ERC-721C/ERC-1155C enrollment (--721c)"];
+    readonly unsupportedToday: readonly ["mainnet deployment through the toolkit", "unsupported chains", "secondary-market listings or an order book", "compiling or deploying custom Solidity through abx", "replacing a deployed code project script through the CLI", "retrofitting a deploy-time choice on an existing collection"];
+    readonly interpretation: {
+        readonly native: "A documented command/flag combination performs the request directly.";
+        readonly extension: "A canonical extension seam performs it while the token remains a factory clone.";
+        readonly unsupported: "The request is listed under unsupportedToday or is blocked by an irreversible choice already made.";
+        readonly unknown: "Do not infer support from absence. Inspect command help, contract type, and this contract; report uncertainty if no route is proven.";
+    };
+};
+export declare function cmdCapabilities(flags: Flags): void;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,YAAY,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmGnB,CAAC;AAEX,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAyBlD"}

package/dist/capabilities.js

@@ -0,0 +1,135 @@
+import { KNOWN_CHAIN_KEYS } from '@artblocks/abx-sdk';
+/**
+ * The machine-readable ABX capability contract.
+ *
+ * Keep this deliberately smaller than command help: it records product boundaries and the
+ * supported combinations agents routinely get wrong. Command-specific syntax still belongs to
+ * `abx help <command>`, while deploy planning belongs to `<deploy-command> --dry-run --json`.
+ * Human help, the shipped skill, and tests consume this object instead of maintaining competing
+ * matrices in prose.
+ */
+export const ABX_CAPABILITIES = {
+    schemaVersion: 1,
+    supportedChains: [...KNOWN_CHAIN_KEYS],
+    deploymentCommands: {
+        deploy: {
+            artifact: 'one static work',
+            unique: {
+                contract: 'OneOfOneImage (ERC-721)',
+                inputs: ['--image'],
+            },
+            edition: {
+                contract: 'OneOfOneEdition (ERC-1155)',
+                selector: '--copies <n|open>',
+                summary: 'one work × copies; supports on-chain bytes, on-chain JSON with external media, or a resolver',
+                supported: ['--onchain-image (hot or wallet signing)', '--onchain-uri', '--backend', '--public-base-url'],
+                unsupported: ['--onchain-image with --unsigned'],
+            },
+        },
+        deploySeries: {
+            artifact: 'a folder of distinct static works',
+            unique: {
+                contract: 'SeriesImage (ERC-721)',
+                inputs: ['--dir'],
+            },
+            edition: {
+                contract: 'EditionImage (ERC-1155)',
+                selector: '--copies <n|open>',
+                summary: 'N folder items × copies per id; supports on-chain bytes, on-chain JSON with external media, or a resolver',
+                supported: ['--onchain-image (hot or wallet signing)', '--onchain-uri', '--backend', '--public-base-url'],
+                unsupported: ['--onchain-image with --unsigned'],
+            },
+        },
+        deployCode: {
+            artifact: 'a program or field renderer whose output depends on token state',
+            unique: {
+                contract: 'SeriesCode (ERC-721)',
+                inputs: ['--script', '--code-dir', '--image-renderer', '--attributes-renderer'],
+            },
+            edition: {
+                contract: 'EditionCode (ERC-1155)',
+                selector: '--copies <n|open>',
+                summary: 'N generated ids × copies per id; supports scripts, dependencies, and Solidity image/trait renderers',
+                supported: ['--script', '--dep', '--dep-registry', '--image-renderer', '--attributes-renderer', '--onchain-uri', '--public-base-url'],
+                unsupported: ['--code-dir', '--image-base', '--resume', '--no-delegation'],
+            },
+        },
+    },
+    extensionRoutes: [
+        {
+            route: 'custom minter',
+            command: 'abx set-minter',
+            availableOn: 'Series and editions',
+            useFor: ['auctions', 'allowlists', 'raffles', 'free claims', 'ERC-20 pricing'],
+        },
+        {
+            route: 'configure hook',
+            command: 'abx set-param-hooks --configure',
+            availableOn: 'SeriesCode and EditionCode',
+            useFor: ['validated writes', 'monotonic values', 'structured collector input'],
+        },
+        {
+            route: 'transfer hook',
+            command: 'abx set-param-hooks --transfer',
+            availableOn: 'SeriesCode and EditionCode',
+            useFor: ['transfer restrictions', 'soulbinding', 'vesting', 'redemption', 'escrow'],
+        },
+        {
+            route: 'augment hook',
+            command: 'abx set-param-hooks --augment',
+            availableOn: 'SeriesCode and EditionCode',
+            useFor: ['live derived data', 'oracle-fed state', 'read-time metadata'],
+        },
+        {
+            route: 'field renderer',
+            command: 'abx deploy-code --image-renderer/--attributes-renderer',
+            availableOn: 'SeriesCode and EditionCode',
+            useFor: ['on-chain SVG images', 'on-chain computed traits'],
+        },
+    ],
+    deployTimeChoices: [
+        'contract shape and token standard (--copies)',
+        'code-capable versus static contract type',
+        'burnability (--burnable)',
+        'ERC-721C/ERC-1155C enrollment (--721c)',
+    ],
+    unsupportedToday: [
+        'mainnet deployment through the toolkit',
+        'unsupported chains',
+        'secondary-market listings or an order book',
+        'compiling or deploying custom Solidity through abx',
+        'replacing a deployed code project script through the CLI',
+        'retrofitting a deploy-time choice on an existing collection',
+    ],
+    interpretation: {
+        native: 'A documented command/flag combination performs the request directly.',
+        extension: 'A canonical extension seam performs it while the token remains a factory clone.',
+        unsupported: 'The request is listed under unsupportedToday or is blocked by an irreversible choice already made.',
+        unknown: 'Do not infer support from absence. Inspect command help, contract type, and this contract; report uncertainty if no route is proven.',
+    },
+};
+export function cmdCapabilities(flags) {
+    if (flags.json !== undefined) {
+        console.log(JSON.stringify(ABX_CAPABILITIES, null, 2));
+        return;
+    }
+    console.log('ABX capability contract v1\n');
+    console.log('Native deployment lanes:');
+    for (const [name, lane] of Object.entries(ABX_CAPABILITIES.deploymentCommands)) {
+        console.log(`  ${name}: ${lane.artifact}`);
+        console.log(`    unique  ${lane.unique.contract} — ${lane.unique.inputs.join(' | ')}`);
+        console.log(`    edition ${lane.edition.contract} — ${lane.edition.summary}`);
+        if (lane.edition.unsupported.length)
+            console.log(`    limits  ${lane.edition.unsupported.join(' · ')}`);
+    }
+    console.log('\nCanonical extension routes:');
+    for (const seam of ABX_CAPABILITIES.extensionRoutes) {
+        console.log(`  ${seam.route}: ${seam.availableOn} — ${seam.useFor.join(', ')}`);
+    }
+    console.log('\nUnsupported today:');
+    for (const item of ABX_CAPABILITIES.unsupportedToday)
+        console.log(`  - ${item}`);
+    console.log('\nUse `abx capabilities --json` for the stable machine-readable form,');
+    console.log('`abx help <command>` for current flags, and `<deploy-command> --dry-run --json` for a concrete plan.');
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}