@artblocks/abx-cli 0.1.0-alpha.26 → 0.1.0-alpha.27

package/skill/reference/decisions.md

@@ -129,5 +129,46 @@ creator (and to their buyers) is "the metadata is frozen"; only a project whose
 that adapts to live chain state is a real thing to build — but it has to be said out loud either way.
 Background: https://abx.docs.artblocks.io/protocol/owner-powers/
 
-**6. When to mint** → [Deploy strategy](#deploy-strategy--when-to-mint).
-
+**6. When to mint** → [Deploy strategy](../SKILL.md#deploy-strategy--when-to-mint).
+
+## Locks — what actually freezes, and what a buyer is really asking
+
+Every lock in this toolkit freezes a **pointer or a stored value**, never *behavior*. Say "locked
+metadata", never "immutable work" — the difference is the whole of this section, and a creator who
+promises the second while shipping the first has mis-sold their collection.
+
+**An *ungoverned* PostParam has no lock at all.** The owner's raw setter keeps writing it past every
+metadata lock, and the generator keeps injecting the new value as `tokenData`. A *schema'd* param can
+be welded permanently (`set-schema … :lock=now`, `abx retire-param`), which freezes that key's
+**token-scope value** and its **schema** forever. So "no lock" is a statement about the ungoverned
+store, never about a governed key.
+
+**The documented exception to a weld: a contract-scope DEFAULT can still be deleted.**
+`clearContractParam` deliberately sits outside the schema guard — it is the recovery path out of a
+value poisoned before the schema existed. So an owner can set a collection-wide default, attach and
+expire a schema on that key, sell tokens that inherit the default, and *then* clear it; every token
+with no override of its own changes. Clearing can only *remove* a fallback — never forge a value,
+never bypass an auth rule, never touch a token-scope value already written. **If a creator is
+promising a frozen collection-wide value, write it per token** (governed, welded) rather than leaving
+it as an inherited default.
+
+**A `Registry` dependency's bytes are re-fetched on every read.** `lock-dependencies` pins which
+library a ref *means*, not what it returns. `abx verify`'s `chain-complete` is a claim about where
+bytes come from, not that they are frozen.
+
+**The one lock a BUYER asks about is `lock-param-hooks`.** A code project's `--transfer` hook is a
+**veto** — its revert fails a transfer, and mints too — so until the hooks are frozen the owner holds
+a standing power over whether a collector can ever sell. Freezing an empty set is how a creator proves
+they never will.
+
+**Every lock freezes a POINTER, not behavior.** A locked hook, renderer or reader is still a
+*contract*, and a contract can be a proxy whose code is upgraded later: `paramHooksLocked()` keeps
+reading `true` while a re-pointed proxy starts reverting every transfer. The protocol does not try to
+detect proxies on chain (complex, incomplete) — it defines locks as pointer locks and discloses it. So
+**for any permanence claim, the hook/renderer must itself be an immutable deployment**: say "these
+exact three addresses can never change" and check what is behind them, never "the behavior is frozen".
+
+A token that live-adapts to chain state is a legitimate thing to build. Just don't sell a frozen one as
+frozen unless it is. See also
+[code-projects.md → hooks](code-projects.md#live-data-the-augment-hook--the-hook-is-the-setting) and
+https://abx.docs.artblocks.io/protocol/owner-powers/

package/skill/reference/operating.md

@@ -41,7 +41,7 @@ After launch the owner operates the project. Each command builds a tx, signs it
 
 **Even with every lock engaged, don't tell a creator the OUTPUT is immutable.** A lock freezes what this contract *stores*, and the metadata locks reach fields and the URI config — not the param store. **An *ungoverned* param has no lock**, and the renderer serves it into `tokenURI` — so an owner can still change the served metadata and the render. (A *schema'd* param is different: it can be welded permanently — see "Welding a PARAM" below — but a welded value can still be *overridden at read time* by an `--augment` hook until `lock-param-hooks` freezes the hook set.) And a `name@version` **`--dep` resolves live from the dependency registry** on every read: `lock-dependencies` pins which library the ref means, not the bytes the registry hands back. `abx verify`'s `chain-complete` is about *where* bytes come from, not whether they change. Say **"the metadata is locked"**; the stronger claim needs on-chain `--dep 0x…` refs plus locked fields. **And a lock a buyer will ask about that isn't in the metadata set at all: `lock-param-hooks`** — a code project's transfer hook is a *veto* (its revert fails a transfer, and a mint), so an unfrozen hook set is a standing power over whether a collector can sell ([hooks](code-projects.md#live-data-the-augment-hook--the-hook-is-the-setting)). Read the other way it's a capability — a piece that adapts to live chain state is a real design, not a defect. Full disclosure list (what an owner can and cannot do, and the read for each) → https://abx.docs.artblocks.io/protocol/owner-powers/
 
-**Welding a PARAM is a different verb — and it IS a real weld.** Fields and [PostParams](code-projects.md#postparams) are separate namespaces that can share a name, and `lock-field` freezes the *field*. To make a param permanent, lock its schema: `abx set-schema <addr> --schema <key>:<Type>:<Auth>:lock=now` (or `abx retire-param <addr> <key>`, the one-arg form). Once that deadline is past, three things hold **forever**, all enforced on-chain:
+**Welding a PARAM is a different verb — and it IS a real weld.** Fields and [PostParams](code-projects.md#postparam-schema--the-type--auth-catalog) are separate namespaces that can share a name, and `lock-field` freezes the *field*. To make a param permanent, lock its schema: `abx set-schema <addr> --schema <key>:<Type>:<Auth>:lock=now` (or `abx retire-param <addr> <key>`, the one-arg form). Once that deadline is past, three things hold **forever**, all enforced on-chain:
 
 - every `configure-param` on the key reverts `ParamLockExpired`;
 - **the SCHEMA freezes too** — `set-schema` on the key also reverts `ParamLockExpired`, so its Type, Auth, bounds and `Select` option table can never be edited. (That matters concretely: without it, a locked `Select` param's options could be swapped afterwards and a collector's "Ember" would re-render as "Frost" with no param write at all.)
@@ -70,6 +70,10 @@ A token anchors **named, typed files**; the served JSON's **`artifacts`** array
   - scope: `--token <id>` (default 0) or `--collection`; any lane; `--dry-run` previews the tx.
 **Gateway ≠ field.** An `ipfs`/`arweave` field stores the bare CID/txid — identity — and the HTTPS prefix is a separate collection-wide setting. So "the gateway is slow / my Pinata plan lapsed / I bought a dedicated gateway" is **`abx set-gateway`**: one tx, moves every token, no re-upload, and it works on fields that are already **locked**. Do NOT reach for `set-field` here — it refuses the two gateway keys by name and points at `set-gateway`, because a token-scope write, a wrong representation, or a prefix missing its trailing path would each fail silently. Reserve `set-field` for the case where the CONTENT moved (a new CID, a new backend).
 
+- **The complete listing is a resolver surface; PostParams are not.** A resolver serves the full `artifacts` list at `/t/<chainId>/<addr>/<id>`, and `/data/<key>` fetches each file. The bare on-chain `tokenURI` enumerates **reserved fields only** — the EVM cannot enumerate arbitrary FIELD keys — so a project that must surface extra files to consumers today runs a resolver (attached files are stored + keccak-anchored regardless). The params store, by contrast, enumerates its own keys on chain, so any RPC reads a token's whole configuration straight from the contract. One line for a creator: *attachments always need a resolver; params never do.*
+- **Effect outputs are artifacts too.** A code project's runner publishes `render/image`, `render/traits`, and any extra declared output into the same manifest automatically, at the current settled state — files appear as tokens mint and params change.
+- **Set expectations honestly, up front.** No mainstream marketplace (OpenSea/Blur) shows a "files" tab **today** — they render `image`/`animation_url` only. Attached files are a durable, anchored part of the token *now*, read by data-plane-aware tools and any resolver; broad marketplace display is future adoption. So verify an attach with `abx tokenuri <addr> --fetch`, never by refreshing OpenSea.
+- **Not the same as a Series.** `deploy-series` makes N separate tokens, one file each; the data plane is how **one** token holds several named files.
 - **`artifacts` and `abx_provenance` are COMPUTED** — the resolver/renderer assembles them from your fields. `set-field`/`attach` refuse them: you never set the manifest, you attach the files it lists.
 - **Verify** — `abx tokenuri <addr> --fetch` follows the token's own URI and shows the served document, `artifacts` array included; that is the check after an attach, not a hand-built URL. (The route each file is fetched from is `/t/<chainId>/<addr>/<id>/data/<key>` on the resolver, which 302-redirects to the locator — worth knowing, not worth typing.) The attached bytes are stored on-chain + keccak-anchored either way.
 - **On-chain vs resolver reach.** The complete listing (arbitrary attached keys) is a **resolver** surface — the EVM can't enumerate an open set of FIELD keys, so the bare on-chain `tokenURI` (on-chain renderer) emits **reserved fields only**. Attaching is durable + anchored regardless, but to *surface* extra files to consumers today, the project is served by a resolver. **PostParams are the exception**: the params store enumerates its own keys on-chain (`paramSchemaKeys` · `contractParamKeys` · `tokenParamKeys`, then `tokenParam`/`contractParam`), so anyone with an RPC reads the complete configuration **directly from the contract** — no resolver, no indexer, and no metadata document in the middle. That store is the canonical surface, which is why params are *not* also projected into `tokenURI`; read them with `abx state` (schemas) and `abx tokens` (values). Say it to a creator as one line — *attachments always need a resolver; params never do.*
@@ -184,3 +188,32 @@ New resolver now serves byte-identical metadata, but traffic still hits the old
 ### Source-only ("node-custody") images — `migrate` handles these automatically
 
 An image committed by hash but never pinned to a durable backend serves from the source's own `/image` route — no portable URL, so copying it points the new host back at the dying old one. `migrate` instead fetches the bytes, re-hashes them against the on-chain commitment (trustless), re-pins them to **your** durable backend, and bridges the new locator. The one case it can't fix: a migrating machine with no durable backend (only `fs`/`cloud`) — it bridges nothing source-bound and tells you to re-run with `--backend ipfs|arweave`. So configure a durable backend before migrating a project that used local-disk custody.
+
+## Listing in the ABX App Store — `abx submit-app`
+
+**Not part of deploy.** After the collection is live, ask: *want this listed in the ABX App Store?* If no, stop. If yes, this is a second, explicit opt-in — minting a token in the store registry — not marketplace discovery.
+
+1. **Draft store copy with the creator.** `--name` / `--summary` / `--description` here are what someone can *do*, not the collection's NFT metadata. Do not silently copy deploy `--name` / `--description`. Confirm category, stage, launch URL, and icon mark/tone.
+2. **You run the command** (same signing lane as the deploy). `--dry-run` first, then send:
+
+```bash
+abx submit-app <collection> \
+  --name "…" --summary "…" --description "…" \
+  --category Create --stage Prototype \
+  --url https://… \
+  --sign
+```
+
+3. They sign once to mint the listing, then a few times to write metadata (the chain caps how much fits in one tx). If mint already succeeded, re-running skips the mint and only writes params.
+4. Humans can instead use the store's `/submit` page; same txs. Don't hand them a list of `configure-param` commands.
+
+The wallet must **own the collection** at mint (the gate checks `isAbxClone` + `owner()`). After that, control follows the **entry token**.
+
+## Deploy strategy — the mechanics
+
+- **`abx predict [--salt 0x..] [--for 0x..]`** pre-computes the address. No `--salt` → reserves a fresh, front-run-proof salt to the deployer; pass `--salt` for a vanity/known address. The salt's leading 20 bytes are an access guard: zero ⇒ anyone may deploy; non-zero ⇒ only that signer.
+- **`--dry-run` without `--salt` prints NO address** — enforced, not a trap to remember: without a pinned salt there's nothing real to quote, so it prints only the freshly-reserved salt plus a ready-to-paste `--salt …` re-run (or `abx predict --salt … --for …`). Pin that salt and re-run to see the real, reproducible address before you present anything.
+- **`abx refresh <addr>`** asks marketplaces to re-index. **Both lanes emit ERC-4906** on metadata/URI changes so 4906-aware marketplaces self-refresh, and `refresh` is the fallback (+ genesis mint). **An edition additionally has ERC-1155's native `URI` event, which is NOT emitted on a contract-wide re-point** (no range form exists) — so after `set-token-uri`/`set-renderer` on an edition also run `abx ping-uri <addr> --token-ids <ids>` for consumers that honor only that event. With `OPENSEA_API_KEY` it calls OpenSea directly; else it prints the links to click.
+- **There is no "add it to a marketplace" step — don't offer one.** Marketplaces discover the collection from chain (the mint, plus ERC-4906 on either lane); `abx refresh` — and `abx ping-uri` on an edition — is the only nudge. Suggesting a manual listing implies work that doesn't exist. **The ABX App Store is different** — that registry is an explicit opt-in (`abx submit-app`), not marketplace discovery. Offer it after deploy; never fold it into deploy. See [List in the App Store](../SKILL.md#list-in-the-abx-app-store-optional).
+- A `--no-mint` deploy reconstructs + serves normally (dashboard shows #0 "not yet minted"; metadata/image already resolve).
+- **Etherscan source is already verified** — your deploys are EIP-1167 clones Etherscan auto-recognizes as proxies of the verified implementation.

package/skill/reference/setup.md

@@ -1,7 +1,48 @@
-# Environment detail — RPC & troubleshooting
+# Setup — install `abx`, configure `.env`, then RPC & troubleshooting
 
 [← back to SKILL.md](../SKILL.md)
 
+**First time? Start at [Finding, installing and configuring `abx`](#finding-installing-and-configuring-abx)** —
+that section is the required setup. The RPC and troubleshooting material below it is reference you reach
+for when indexing is slow or a resolver will not serve, not something a first launch needs.
+
+## Finding, installing and configuring `abx`
+
+`abx` needs **Node ≥ 22.5** at runtime (the projection store uses built-in SQLite).
+
+### Find `abx` before you install it — local first, then global
+
+**Resolve in this order and use the first hit.** Don't jump to a global install; a project-local CLI is pinned in the creator's `package.json` (reproducible, and what `abx skill install` version-locks against), so it wins whenever it exists:
+
+```bash
+./node_modules/.bin/abx version   # 1. project-local — PREFER this (invoke as `npx abx <cmd>` once you know it's there)
+abx version                       # 2. a global install already on PATH
+```
+
+- **Probe the local binary by PATH, never with `npx abx`.** The bare `abx` name on npm is an **unrelated squatted package**, so a plain `npx abx` with nothing local *downloads that*. And `--no-install` does **not** make the probe safe or trustworthy: it only skips a *fresh download*, and npm will still happily run any `abx` binary sitting in the npx cache from an earlier run — which can be a stale version (a real sweep saw `--no-install` report a months-old build as the project's CLI) or, if a plain `npx abx` was ever run on that machine, the squatted package itself. `./node_modules/.bin/abx` is unambiguous: it exists in THIS project or it doesn't.
+- In the **abx source repo** (contributor), neither applies: use `pnpm abx <cmd>`, which runs the live `tsx` source.
+
+**Nothing found → install.** The package is **`@artblocks/abx-cli`** (not `@artblocks/abx-sdk` — that's the library, and installing it gets you no `abx` binary; a real session lost a cycle to exactly that mistake):
+
+| Situation | Install | Then invoke as |
+|---|---|---|
+| The creator has a project dir (a `package.json`) — **default** | `npm install --save-dev @artblocks/abx-cli` | `npx abx …` |
+| No project, or they asked for a machine-wide tool | `npm install -g @artblocks/abx-cli` | `abx …` |
+
+Ask before installing **globally** — it's a machine-wide change to their PATH, and the per-project install is the reversible one. A project install needs no permission beyond the usual.
+
+Whichever you land on, **keep using that same invocation for every command in the session** (`npx abx …` vs `abx …`) — don't mix them, or you'll silently drive two different CLI versions. Then run `abx doctor` (preflight: signing key/wallet, RPC, canonical factory, storage).
+
+`.env` (in the creator's project dir) = **secrets only**:
+- **Signing:** `ABX_DEPLOYER_PK` (the only name read — older `SEPOLIA_FUNDED_PK`/`SEPOLIA_WALLET_PK` are retired, and the CLI's error names them if it finds neither) is needed ONLY for hot/unattended signing. If the creator owns a wallet, prefer **`--sign`** — no key in `.env`. `doctor`'s missing-key ✗ is **not fatal** on the `--sign` path.
+- `ABX_RPC_URLS`, `ABX_PUBLIC_BASE_URL` (remote-resolver custody only), optional `OPENSEA_API_KEY`, plus any backend secret.
+- **One client-side credential grammar: `ABX_REMOTE_<NAME>_URL` + `ABX_REMOTE_<NAME>_TOKEN`** (same normalization as `ABX_RPC_URLS_<CHAIN>`) — a node you run is just the name **`self`** (`deploy-resolver` generates `ABX_REMOTE_SELF_TOKEN` locally; bare `--remote` defaults to it), a managed provider is its own name. `ABX_RESOLVER_ADMIN_TOKEN` is the **resolver's own server-side config** (never read client-side) — a stale copy of it in `.env` with no `ABX_REMOTE_SELF_TOKEN` gets a pointed error naming both vars, and `abx doctor` flags it too. Only `_URL`/`_TOKEN` are read — `ABX_REMOTE_<NAME>_KEY` is ignored (the CLI flags a near-miss name).
+
+<sub>Working from the abx **source repo** (contributor)? `pnpm install`, then `pnpm abx <cmd>` or `pnpm sandbox`. Every command below is identical.</sub>
+
+**Indexing reads the event log via `eth_getLogs` from the contract's deploy block**, which the CLI records at deploy and forwards to a resolver on `add` — so a normal deploy→index scans a small recent window, is fast on any RPC, and re-indexes incrementally. **If indexing is slow, or a hosted resolver won't serve, ASK IT: `abx status <addr> [--remote <name>]`** reports the lifecycle (`queued`→`backfilling`→`live`, plus `stale`/`failed` with a machine-readable cause), so "still catching up" and "broken" stop looking alike. Then **check the scan floor (is it scanning from block 0?) before blaming the RPC tier** — that mis-diagnosis is a known trap. Range caps, pruned log history, and which endpoint to give a resolver under load are covered below.
+
+
 ## Choosing an RPC (drives re-index speed)
 
 Reconstruction reads the event log via `eth_getLogs` **from the contract's deploy block** — the CLI records it at deploy and forwards it to a resolver on `add`, and discovers it on-chain (a getCode binary search) for a contract it didn't deploy here. So a normal deploy→index scans a *small, recent* window and is fast on **any** RPC. Providers cap the getLogs block range very differently **and these caps change** — treat any number as illustrative, re-verify before you quote it. *(Illustrative, Jun 2026: Alchemy free ≈10 blocks/call, Infura/Chainstack free ≈2000, PublicNode/dRPC vary; no-key public endpoints are the lowest-friction to try.)* The toolkit **auto-chunks**, so any RPC yields correct state — but a range cap is **not** cost-free to shrug off: a **from-genesis** or long-span reconstruction, or a resolver serving many code projects under load, is slow and rate-limit-prone on a capped endpoint. `abx doctor` rates each endpoint and flags a capped one; treat that flag as a real infra signal, not noise. **First diagnosis when indexing is slow or a hosted resolver won't serve: is it scanning from block 0? Check the scan floor before the RPC tier.**