@artblocks/abx-cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/skill/reference/creator-token.md

@@ -0,0 +1,71 @@
+# Royalty enforcement — opt-in ERC-721C (creator token)
+
+[← back to SKILL.md](../SKILL.md)
+
+**Read this ONLY because the creator brought it up** (royalty enforcement, "make OpenSea pay my
+royalties", ERC-721C, transfer restrictions, a transfer validator). If they didn't, this file has no
+business in the conversation: **plain ERC-721 is the default and the recommendation**, every deploy
+flow already does the right thing with zero 721C flags, and offering enforcement unprompted reads as
+a nudge toward a restricted asset. Never present `--721c` as a checklist item, a "should we also…",
+or a row in the deploy readout for a creator who never asked.
+
+## The stance (how to frame it when asked)
+
+- **Plain ERC-721 (the default) is the more sovereign asset**: no third-party contract on the
+  transfer path, tradeable everywhere, nothing anyone — creator included — can later switch off.
+  ABX royalties are already on-chain via ERC-2981 (`abx set-royalty`); marketplaces *choose* whether
+  to honor them.
+- **ERC-721C is enforcement for creators who specifically want it**: transfers are checked by a
+  validator contract, and sales that don't route through an authorized venue revert. It is a real
+  trade-off, decided at deploy, **permanently** — present it transparently, recommend it only when
+  the creator's stated goal is enforcement, and get an explicit yes before enrolling.
+- **The honest market picture (2026) — say it, don't oversell**: enforcement via 721C effectively
+  means **OpenSea** plus venues on Limit Break's Payment Processor. OpenSea's own help docs say
+  enforcement limits sales to those venues; Magic Eden's EVM marketplace shut down March 2026, and
+  Blur never honored 721C. The trade: enforced royalties on OpenSea, in exchange for not trading on
+  venues the validator doesn't authorize.
+
+## What enrolling does (the facts to relay)
+
+- **Deploy-time, permanent, both directions.** A plain ABX 721 can **never** grow transfer
+  restrictions later (that's a feature — collectors of unenrolled tokens keep that promise forever),
+  and an enrolled one never sheds the standard. No retrofit exists; the only path to enrollment for
+  a live plain collection is a redeploy.
+- **Suspend ≠ un-enroll.** The owner can re-point the validator or set it to zero (enforcement off,
+  token **stays** enrolled — the owner can re-enable any time). Collectors can see enrollment via
+  ERC-165, suspended or not.
+- **Mints and burns are NEVER validated** — no validator policy can brick minting, the shared
+  fixed-price minter, or a delegated minter.
+- **The recommended validator** (`--721c recommended`, or bare `--721c`) is OpenSea's
+  StrictAuthorizedTransferSecurityRegistry — under it, owner-initiated wallet-to-wallet transfers
+  pass; non-authorized operators revert. One decision, done.
+
+## Commands
+
+```bash
+# Enroll at deploy — all three deploy commands take the flag (absent = plain ERC-721, forever):
+abx deploy|deploy-series|deploy-code … --721c [recommended|0x<validator>]
+
+# Operate an ENROLLED collection (owner-only, any signing lane, --dry-run works):
+abx set-transfer-validator <addr> 0x<validator>   # re-point enforcement
+abx set-transfer-validator <addr> none            # suspend (stays enrolled)
+abx set-transfer-validator <addr> recommended     # the chain's recommended validator
+
+abx state <addr>   # shows a "721C validator" row ONLY when enrolled ("suspended" when zero)
+```
+
+Enrolling prints one plain statement of what enforcement means — relay it, don't embellish. An
+un-enrolled deploy prints nothing about 721C.
+
+## Refusals the CLI enforces (don't fight them; relay the reason)
+
+- **`--721c none`/zero at deploy** — refused: a zero validator never enrolls, and "enrolled but
+  suspended" is not a deploy-time state. Plain ERC-721 is already the default; drop the flag.
+- **`--721c recommended` on a chain with no known validator** — refused, naming the chains that have
+  one. Pass an explicit deployed validator address instead; never guess one.
+- **A codeless validator address** — refused before any gas at deploy AND at re-point (the contract
+  would revert `InvalidTransferValidator()`); a mixed-case address must pass its EIP-55 checksum.
+  A real deploy also refuses to enroll blind when the RPC can't verify code (a dry-run defers it).
+- **`set-transfer-validator` on a plain ERC-721** — refused up front: enrollment is a deploy-time
+  decision and this collection didn't enroll. Do not retry with different flags; if the creator
+  truly needs enforcement, that's a redeploy conversation.

package/skill/reference/decisions.md

@@ -26,13 +26,13 @@ placeholder. If you remember that limitation, it is gone.)
 
 **Picking IPFS (or Arweave) does NOT mean running a server.** The `--onchain-uri --backend ipfs|arweave` path (pattern 2) bakes the image's public **gateway** URL into on-chain JSON — a pinning service's read endpoint (a *dedicated* Pinata gateway for IPFS), not a resolver you host. So when a creator chooses IPFS, **default to this no-server path** — image on IPFS, JSON on-chain, nothing to keep running (just keep the pin alive). You only need a **resolver** (pattern 3 — managed or self-hosted) if they want *freely editable* metadata. Never present IPFS as blocked on "a public URL" or "a server always online": the gateway belongs to the pinning service and the JSON lives on-chain. (The one real input IPFS needs is `PINATA_JWT` in `.env` for pinning — that's an API upload, not a host.)
 
-**No-server tradeoff (patterns 1, 2, 4):** with the on-chain renderer only the *image* is off-chain — any **description / traits / animation_url live on-chain** (gas to write, permanent, lockable), vs a hosted resolver where they're free to edit. Cheap (a shared value is **one collection-scope field**, not one per token — the renderer falls back token→collection), but the creator should choose "no server" knowing their text metadata is on-chain.
+**No-server tradeoff (patterns 1, 2, 4):** with the on-chain renderer only the *image* is off-chain — any **description / traits / animation_url, and every configured PostParam (served as `abx_params`), live on-chain** (gas to write, permanent, lockable), vs a hosted resolver where they're free to edit. Cheap (a shared value is **one collection-scope field**, not one per token — the renderer falls back token→collection), but the creator should choose "no server" knowing their text metadata is on-chain.
 
 Get decisions 1–2 right before deploy (image commitment + resolver URL are written then; re-pointable, but):
 
 **1. Storage permanence** — where bytes live. Not irreversible: bytes are content-addressed by their on-chain keccak, so start on one backend and move later (`abx verify` confirms the hash). Don't let it block a first deploy.
 - `arweave` = pay-once permanent, no recurring fee. `cloud` (S3/R2) = durable, you maintain it. `ipfs` = decentralized, you pin it. `fs` = zero-config start, dies with the disk → move before it matters.
-- **`arweave` is nearly as easy as `fs` for small art** — Turbo default: **under 100 KB free, no setup** (a managed `.abx-self-host/arweave-key.json` minted on first upload; back it up with `abx storage backup-key`). Choose per command with `--backend` (stateless, no config file); a backend missing its secret falls back to `fs`.
+- **`arweave` is nearly as easy as `fs` for small art** — Turbo default: **under 100 KB free, no setup** (a managed `.abx-self-host/arweave-key.json` minted on first upload; back it up with `abx storage backup-key`). Choose per command with `--backend` (stateless, no config file). **A backend missing its secret does NOT fall back to `fs`** — it fails: `cloud` refuses up front naming the missing values, and `ipfs` without `PINATA_JWT` resolves to **kubo mode against a local node** (`http://127.0.0.1:5001`), which fails at upload time if you aren't running one. Check with `abx storage show` (it prints the resolved backend *and* mode) before a real upload.
 - **Who pays is a lane (`--storage-signer`)** — Turbo credits attach to an identity (managed key · `.env` key · browser wallet). **Before any top-up, check BOTH balances** (`abx storage balance --backend arweave` shows the managed key AND the wallet — spend the wallet's credits if present). On an upload error surface it verbatim — `…already been uploaded…` is *success* (dedup); don't reflexively top-up or switch to IPFS. Full lanes + failure playbook → [hosting.md](reference/hosting.md#arweave-via-turbo--the-easy-permanent-path-read-before-quoting-setup).
 
 **2. Public host URL — and who runs the resolver** (**off-chain custody only**). Baked into `tokenURI` at deploy, so the CLI **refuses an off-chain deploy without a public URL** (`ABX_PUBLIC_BASE_URL` or `--public-base-url https://…`) and **never bakes localhost** (that token resolves for no one). No exceptions.

package/skill/reference/operating.md

@@ -49,7 +49,7 @@ 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.
 - **`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** — a resolver serves the complete listing: `curl <resolver>/t/<chainId>/<addr>/<id>` shows the `artifacts` array, and `/t/<chainId>/<addr>/<id>/data/<key>` fetches (or 302-redirects to) each file. 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.
+- **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, so a bare `tokenURI` emits every set param under **`abx_params`** with no resolver in the picture. Say it to a creator as one line — *attachments always need a resolver; params never do.*
 
 ### Series-only owner ops