@artblocks/abx-cli 0.1.0-alpha.9 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,402 @@
+# @artblocks/abx-cli
+
+## 0.1.0
+
+### Minor Changes
+
+- 21e3d6c: Drop-in for existing v2 integrations; new deployments use the canonical v3 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.
+- 22abce8: Generalize the creator-wallet sponsorship lane to direct zero-value contract creation and
+  receipt-dependent on-chain image staging. Add `abx deploy-contract` for exact Foundry artifact or
+  initcode deployment through any signing lane.
+- ea57f7a: Add provider-neutral remote interface discovery, the ABX Creators account API client, and the Base
+  Sepolia creator-wallet `--sponsor` signing lane. A provider catalog may advertise its account and
+  wallet interfaces at a separate HTTPS origin without changing existing same-origin remotes.
+
+### Patch Changes
+
+- f9d7a44: Clarify fully on-chain image deployment tradeoffs and make static-project verification report
+  `onChainUri.chainComplete` as not applicable instead of false.
+- d50cecd: Classify env-key signing risk from the shared chain registry so newly supported testnets, including
+  Robinhood Chain Testnet, work in bounded autonomous smoke tests without being mistaken for mainnet.
+  The contributor smoke runner now pins one testnet, gives the worker a fresh small-funded wallet,
+  copies only the requested hosted-provider credential, and records evidence without per-transaction
+  prompts. Remote discovery accepts `remote list`, and on-chain image planning now calls out the
+  single-transaction inline-SVG alternative when it applies.
+- 90bde50: Document the supported creator-wallet sponsorship lane in hook, mint, and transfer command help.
+- 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.
+- b8f2876: Keep sponsored deploy guidance consistent: an ABX creator wallet no longer receives a faucet warning when its native balance is intentionally zero.
+- 56973c4: Preserve `maxInvocations` as an exact uint256 value instead of narrowing it through a JavaScript
+  number. Reuse an existing hosted-service credential on login and add self-service API-key listing
+  and revocation for accounts at their active-key limit.
+- 0a9ed51: Reuse Privy creator-wallet grants across sponsored CLI commands through the native operating-system credential store.
+- c324a8f: Make sponsored deployment previews resolve the existing ABX creator wallet without provisioning external state, so the preview and real send use the same owner, mint recipient, and deterministic salt.
+- 2290b0a: Recover ambiguous creator-wallet submissions through the existing operation status instead of replaying them. Sponsored sends now keep polling safely when the provider response is temporarily unknown and surface the operation ID if reconciliation cannot complete.
+- ee24497: Add machine-readable `--json` output to `contracturi` and `add`. Collection metadata reads now emit
+  the resolved document alone, while registration reports identify the target surface, chain and
+  address, scan floor, lifecycle status, and whether remote catch-up is complete or still backfilling.
+- 8ccbede: Enable Robinhood Chain production as beta after canonical deployment, paired-testnet qualification,
+  and managed-service validation. Surface the same real-funds warning and testnet-first gate used for
+  other production beta networks.
+- d925eb1: Breaking only for SDK callers that directly prepared an unsupported sponsored `to: null` request;
+  drop-in for existing hot, wallet, and unsigned deployments. Route sponsored custom-contract
+  deployments through ABX's existing keyless CREATE2 proxy, expose the exact signer-bound salt and
+  predicted address, verify code after confirmation, and document the proxy constructor-caller boundary.
+- e89896a: Reject deterministic deploy salts reserved to a different signer before authorization or broadcast.
+- 8f35dae: Prepare package metadata, release notes, and public-facing source comments for the initial public
+  source release.
+- 719b9fe: Make the bundled skill read network and sponsorship support from CLI capabilities and the live
+  service descriptor instead of a hardcoded network list. Refresh public documentation references in
+  the published packages.
+- f9ba363: Clarify edition live-supply caps, intentional ERC-721 self-transfer hook callbacks, and OP Stack
+  seed-source behavior in the bundled ABX skill.
+- c2400a7: Stage Robinhood Chain and its testnet as disabled qualification targets, keep the network registry
+  focused on the current roadmap, and stop sale inspection from turning RPC read failures into false
+  zero-state results.
+- cf2708c: Allow the beta creator-wallet sponsorship lane on Base mainnet when the live provider and account explicitly advertise eligibility, while retaining Base Sepolia as the recommended first run.
+- 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.
+- 3d7fe3c: Record the verified canonical Robinhood Chain Testnet deployment and enable the network for
+  experimental qualification with explicit CLI and agent guidance.
+- 66cf489: Mark the qualified creator-wallet sponsorship lane as supported while preserving Base mainnet's protocol-beta warnings.
+- 1294757: Make available ABX updates a clear pre-deployment recommendation in the CLI and bundled agent skill,
+  including the matching skill refresh and compatibility expectations for existing projects.
+- ddb2e0b: Refuse irreversible URI locks when the current token or collection base uses `abx.io`. Clarify that
+  managed resolver URLs must remain mutable unless a creator-controlled domain is routed and verified.
+- 5164922: Teach the bundled agent skill to prefer live-advertised gas sponsorship for eligible operations while
+  keeping hot-key, browser-wallet, and unsigned signing as first-class choices.
+- 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.
+- 76cfc6a: Follow each remote service interface's advertised origin so provider catalogs can separate token data from account and control APIs.
+- 04c0919: Remove ABX's artificial 3,000,000-gas ceiling from sponsored transactions. Sponsored calls now use
+  the network estimate and remain subject to the active chain and provider sponsorship policy.
+- Updated dependencies [21e3d6c]
+- Updated dependencies [22abce8]
+- Updated dependencies [4d5e2b1]
+- Updated dependencies [56973c4]
+- Updated dependencies [2290b0a]
+- Updated dependencies [b9197bc]
+- Updated dependencies [8ccbede]
+- Updated dependencies [d925eb1]
+- Updated dependencies [ea57f7a]
+- Updated dependencies [3ddba71]
+- Updated dependencies [8f35dae]
+- Updated dependencies [719b9fe]
+- Updated dependencies [9065128]
+- Updated dependencies [c2400a7]
+- Updated dependencies [3d7fe3c]
+- Updated dependencies [7b462e2]
+- Updated dependencies [ddb2e0b]
+- Updated dependencies [4512962]
+- Updated dependencies [76cfc6a]
+- Updated dependencies [5522192]
+  - @artblocks/abx-sdk@0.1.0
+  - @artblocks/abx-token-api@0.1.0
+  - @artblocks/abx-indexer@0.1.0
+  - @artblocks/abx-storage@0.1.0
+
+## 0.1.0-alpha.71
+
+### Patch Changes
+
+- 0a9ed51: Reuse Privy creator-wallet grants across sponsored CLI commands through the native operating-system credential store.
+
+## 0.1.0-alpha.70
+
+### Patch Changes
+
+- 1294757: Make available ABX updates a clear pre-deployment recommendation in the CLI and bundled agent skill,
+  including the matching skill refresh and compatibility expectations for existing projects.
+
+## 0.1.0-alpha.69
+
+### Patch Changes
+
+- 719b9fe: Make the bundled skill read network and sponsorship support from CLI capabilities and the live
+  service descriptor instead of a hardcoded network list. Refresh public documentation references in
+  the published packages.
+- Updated dependencies [719b9fe]
+  - @artblocks/abx-indexer@0.1.0-alpha.50
+  - @artblocks/abx-sdk@0.1.0-alpha.49
+  - @artblocks/abx-token-api@0.1.0-alpha.52
+  - @artblocks/abx-storage@0.1.0-alpha.49
+
+## 0.1.0-alpha.68
+
+### Patch Changes
+
+- Updated dependencies [4d5e2b1]
+  - @artblocks/abx-sdk@0.1.0-alpha.48
+  - @artblocks/abx-token-api@0.1.0-alpha.51
+  - @artblocks/abx-indexer@0.1.0-alpha.49
+  - @artblocks/abx-storage@0.1.0-alpha.48
+
+## 0.1.0-alpha.67
+
+### Patch Changes
+
+- 56973c4: Preserve `maxInvocations` as an exact uint256 value instead of narrowing it through a JavaScript
+  number. Reuse an existing hosted-service credential on login and add self-service API-key listing
+  and revocation for accounts at their active-key limit.
+- Updated dependencies [56973c4]
+  - @artblocks/abx-sdk@0.1.0-alpha.47
+  - @artblocks/abx-indexer@0.1.0-alpha.48
+  - @artblocks/abx-storage@0.1.0-alpha.47
+  - @artblocks/abx-token-api@0.1.0-alpha.50
+
+## 0.1.0-alpha.66
+
+### Patch Changes
+
+- ddb2e0b: Refuse irreversible URI locks when the current token or collection base uses `abx.io`. Clarify that
+  managed resolver URLs must remain mutable unless a creator-controlled domain is routed and verified.
+- 76cfc6a: Follow each remote service interface's advertised origin so provider catalogs can separate token data from account and control APIs.
+- Updated dependencies [ddb2e0b]
+- Updated dependencies [76cfc6a]
+  - @artblocks/abx-sdk@0.1.0-alpha.46
+  - @artblocks/abx-indexer@0.1.0-alpha.47
+  - @artblocks/abx-storage@0.1.0-alpha.46
+  - @artblocks/abx-token-api@0.1.0-alpha.49
+
+## 0.1.0-alpha.65
+
+### Patch Changes
+
+- 66cf489: Mark the qualified creator-wallet sponsorship lane as supported while preserving Base mainnet's protocol-beta warnings.
+
+## 0.1.0-alpha.64
+
+### Patch Changes
+
+- 90bde50: Document the supported creator-wallet sponsorship lane in hook, mint, and transfer command help.
+
+## 0.1.0-alpha.63
+
+### Patch Changes
+
+- d925eb1: Breaking only for SDK callers that directly prepared an unsupported sponsored `to: null` request;
+  drop-in for existing hot, wallet, and unsigned deployments. Route sponsored custom-contract
+  deployments through ABX's existing keyless CREATE2 proxy, expose the exact signer-bound salt and
+  predicted address, verify code after confirmation, and document the proxy constructor-caller boundary.
+- Updated dependencies [d925eb1]
+  - @artblocks/abx-sdk@0.1.0-alpha.45
+  - @artblocks/abx-indexer@0.1.0-alpha.46
+  - @artblocks/abx-storage@0.1.0-alpha.45
+  - @artblocks/abx-token-api@0.1.0-alpha.48
+
+## 0.1.0-alpha.62
+
+### Minor Changes
+
+- 22abce8: Generalize the creator-wallet sponsorship lane to direct zero-value contract creation and
+  receipt-dependent on-chain image staging. Add `abx deploy-contract` for exact Foundry artifact or
+  initcode deployment through any signing lane.
+
+### Patch Changes
+
+- Updated dependencies [22abce8]
+  - @artblocks/abx-sdk@0.1.0-alpha.44
+  - @artblocks/abx-indexer@0.1.0-alpha.45
+  - @artblocks/abx-storage@0.1.0-alpha.44
+  - @artblocks/abx-token-api@0.1.0-alpha.47
+
+## 0.1.0-alpha.61
+
+### Patch Changes
+
+- 04c0919: Remove ABX's artificial 3,000,000-gas ceiling from sponsored transactions. Sponsored calls now use
+  the network estimate and remain subject to the active chain and provider sponsorship policy.
+
+## 0.1.0-alpha.60
+
+### Patch Changes
+
+- 2290b0a: Recover ambiguous creator-wallet submissions through the existing operation status instead of replaying them. Sponsored sends now keep polling safely when the provider response is temporarily unknown and surface the operation ID if reconciliation cannot complete.
+- Updated dependencies [2290b0a]
+  - @artblocks/abx-sdk@0.1.0-alpha.43
+  - @artblocks/abx-indexer@0.1.0-alpha.44
+  - @artblocks/abx-storage@0.1.0-alpha.43
+  - @artblocks/abx-token-api@0.1.0-alpha.46
+
+## 0.1.0-alpha.59
+
+### Patch Changes
+
+- c324a8f: Make sponsored deployment previews resolve the existing ABX creator wallet without provisioning external state, so the preview and real send use the same owner, mint recipient, and deterministic salt.
+
+## 0.1.0-alpha.58
+
+### Patch Changes
+
+- b8f2876: Keep sponsored deploy guidance consistent: an ABX creator wallet no longer receives a faucet warning when its native balance is intentionally zero.
+- e89896a: Reject deterministic deploy salts reserved to a different signer before authorization or broadcast.
+- cf2708c: Allow the beta creator-wallet sponsorship lane on Base mainnet when the live provider and account explicitly advertise eligibility, while retaining Base Sepolia as the recommended first run.
+
+## 0.1.0-alpha.57
+
+### Patch Changes
+
+- 5164922: Teach the bundled agent skill to prefer live-advertised gas sponsorship for eligible operations while
+  keeping hot-key, browser-wallet, and unsigned signing as first-class choices.
+
+## 0.1.0-alpha.56
+
+### Minor Changes
+
+- ea57f7a: Add provider-neutral remote interface discovery, the ABX Creators account API client, and the Base
+  Sepolia creator-wallet `--sponsor` signing lane. A provider catalog may advertise its account and
+  wallet interfaces at a separate HTTPS origin without changing existing same-origin remotes.
+
+### Patch Changes
+
+- f9ba363: Clarify edition live-supply caps, intentional ERC-721 self-transfer hook callbacks, and OP Stack
+  seed-source behavior in the bundled ABX skill.
+- Updated dependencies [ea57f7a]
+  - @artblocks/abx-sdk@0.1.0-alpha.42
+  - @artblocks/abx-indexer@0.1.0-alpha.43
+  - @artblocks/abx-storage@0.1.0-alpha.42
+  - @artblocks/abx-token-api@0.1.0-alpha.45
+
+## 0.1.0-alpha.55
+
+### Patch Changes
+
+- 8ccbede: Enable Robinhood Chain production as beta after canonical deployment, paired-testnet qualification,
+  and managed-service validation. Surface the same real-funds warning and testnet-first gate used for
+  other production beta networks.
+- Updated dependencies [8ccbede]
+  - @artblocks/abx-sdk@0.1.0-alpha.41
+  - @artblocks/abx-indexer@0.1.0-alpha.42
+  - @artblocks/abx-storage@0.1.0-alpha.41
+  - @artblocks/abx-token-api@0.1.0-alpha.44
+
+## 0.1.0-alpha.54
+
+### Patch Changes
+
+- f9d7a44: Clarify fully on-chain image deployment tradeoffs and make static-project verification report
+  `onChainUri.chainComplete` as not applicable instead of false.
+- ee24497: Add machine-readable `--json` output to `contracturi` and `add`. Collection metadata reads now emit
+  the resolved document alone, while registration reports identify the target surface, chain and
+  address, scan floor, lifecycle status, and whether remote catch-up is complete or still backfilling.
+- Updated dependencies [b9197bc]
+  - @artblocks/abx-sdk@0.1.0-alpha.40
+  - @artblocks/abx-indexer@0.1.0-alpha.41
+  - @artblocks/abx-storage@0.1.0-alpha.40
+  - @artblocks/abx-token-api@0.1.0-alpha.43
+
+## 0.1.0-alpha.53
+
+### Patch Changes
+
+- d50cecd: Classify env-key signing risk from the shared chain registry so newly supported testnets, including
+  Robinhood Chain Testnet, work in bounded autonomous smoke tests without being mistaken for mainnet.
+  The contributor smoke runner now pins one testnet, gives the worker a fresh small-funded wallet,
+  copies only the requested hosted-provider credential, and records evidence without per-transaction
+  prompts. Remote discovery accepts `remote list`, and on-chain image planning now calls out the
+  single-transaction inline-SVG alternative when it applies.
+
+## 0.1.0-alpha.52
+
+### Patch Changes
+
+- 3d7fe3c: Record the verified canonical Robinhood Chain Testnet deployment and enable the network for
+  experimental qualification with explicit CLI and agent guidance.
+- Updated dependencies [3d7fe3c]
+- Updated dependencies [7b462e2]
+  - @artblocks/abx-sdk@0.1.0-alpha.39
+  - @artblocks/abx-indexer@0.1.0-alpha.40
+  - @artblocks/abx-storage@0.1.0-alpha.39
+  - @artblocks/abx-token-api@0.1.0-alpha.42
+
+## 0.1.0-alpha.51
+
+### Patch Changes
+
+- c2400a7: Stage Robinhood Chain and its testnet as disabled qualification targets, keep the network registry
+  focused on the current roadmap, and stop sale inspection from turning RPC read failures into false
+  zero-state results.
+- Updated dependencies [c2400a7]
+  - @artblocks/abx-sdk@0.1.0-alpha.38
+  - @artblocks/abx-indexer@0.1.0-alpha.39
+  - @artblocks/abx-storage@0.1.0-alpha.38
+  - @artblocks/abx-token-api@0.1.0-alpha.41
+
+## 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.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.
+
+### Patch Changes
+
+- Updated dependencies [21e3d6c]
+  - @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,26 +1,33 @@
-# 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.
+`abx` does **not** compile Solidity for you. Build and test with Foundry, then either deploy with
+Foundry or pass exact compiled creation bytecode to `abx deploy-contract`. Hand the deployed
+address(es) to `abx deploy-code`, which verifies they have code.
 
 ## 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 +36,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 +64,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) {}
+}