@artblocks/abx-cli 0.1.0-alpha.31 → 0.1.0-alpha.32

package/skill/reference/decisions.md

@@ -10,8 +10,8 @@ Master call is **custody × mutability**:
 
 | | **Mutable** (name/desc/traits may change) | **Immutable** (never changes) |
 |---|---|---|
-| **Small static** (≲ 40 KB/file — the READ ceiling, see below) | **on-chain renderer** — `--onchain-image --compress fastlz`. No host, mutable via `set-field`, permanent. | on-chain renderer + `lock-field` + `lock-uri` once it resolves. |
-| **Bigger / dynamic** (most PNG/JPEG) | **image off-chain, JSON on-chain, no server** — `--onchain-uri --backend arweave` (or `ipfs`). Renderer assembles JSON pointing at the bytes; many files → one `url-template` (O(1)). For metadata you edit often, a **resolver** instead — a managed provider or your own (`abx deploy-resolver`), [hosting.md](reference/hosting.md). Not fully on-chain (~200 gas/byte). | image off-chain (Arweave = permanent) + on-chain renderer + `lock-field`/`lock-uri`. Or a frozen `ipfs://` override + `lock-uri`. |
+| **Small static** (≲ 117 KB/file reads on any endpoint — bigger is supported, see below) | **on-chain renderer** — `--onchain-image --compress fastlz`. No host, mutable via `set-field`, permanent. | on-chain renderer + `lock-field` + `lock-uri` once it resolves. |
+| **Bigger / dynamic** (most PNG/JPEG) | **image off-chain, JSON on-chain, no server** — `--onchain-uri --backend arweave` (or `ipfs`). Renderer assembles JSON pointing at the bytes; many files → one `url-template` (O(1)). For metadata you edit often, a **resolver** instead — a managed provider or your own (`abx deploy-resolver`), [hosting.md](hosting.md). Not fully on-chain (~200 gas/byte). | image off-chain (Arweave = permanent) + on-chain renderer + `lock-field`/`lock-uri`. Or a frozen `ipfs://` override + `lock-uri`. |
 
 **Four patterns, by where bytes live × how `tokenURI` resolves:**
 1. **Fully on-chain** (`--onchain-image`) — bytes + JSON on-chain. Small content only, and the binding limit is READ gas, not storage cost (below).
@@ -59,16 +59,16 @@ Get decisions 1–2 right before deploy (image commitment + resolver URL are wri
 **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 content** — Turbo default: **under 100 KB free, no setup** (a managed `.abx-self-host/arweave-key.json` minted the first time a command needs it — an upload, or a `storage balance`/`topup`; 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).
+- **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](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.
 - **First ask whether you need a host at all** — tiny content is cheaper and more durable on-chain (no host). For bigger content, Arweave (no host to run) beats a resolver unless you need mutability or serve many files.
 - **A named remote is already configured (`ABX_REMOTE_<NAME>_URL` in `.env`)? Use it.** The creator already chose a provider — don't stand up new infrastructure beside it. **Run `abx remote <name>` FIRST, before registering anything**: it prints the provider's chain coverage + whether rendering is managed, and it *validates the key* (`401` = the token in `ABX_REMOTE_<NAME>_TOKEN` is stale/wrong → they replace the value in `.env`; `403` = the key is fine but not authorized for this contract/chain → provider-side scoping, don't touch the key). Then register: `abx add <addr> --remote <name>`. Testing a replacement key without editing `.env` first: `abx remote <name> --remote-token <new-key>`.
-- **Otherwise, two equal ways to have a resolver, one config change apart.** A **managed provider** — one base URL + one API key, no cloud account, nothing to keep alive; often **managed rendering** too, so a code drop needs no effects runner (**lead with this when the creator doesn't already run infrastructure or doesn't want to** — [hosting.md → Managed providers](reference/hosting.md#managed-providers--a-resolver-someone-else-runs---remote-name)). Or **self-host** (`abx deploy-resolver`, [hosting.md](reference/hosting.md)) — the creator owns the node and the cloud account. Same interface, same commands; a project moves between them with one re-point + re-register. **No provider key in hand and none to get? Self-host is the fully-supported path today** — the provider market is only starting to form; never invent or recommend a provider that isn't in front of you.
+- **Otherwise, two equal ways to have a resolver, one config change apart.** A **managed provider** — one base URL + one API key, no cloud account, nothing to keep alive; often **managed rendering** too, so a code drop needs no effects runner (**lead with this when the creator doesn't already run infrastructure or doesn't want to** — [hosting.md → Managed providers](hosting.md#managed-providers--a-resolver-someone-else-runs---remote-name)). Or **self-host** (`abx deploy-resolver`, [hosting.md](hosting.md)) — the creator owns the node and the cloud account. Same interface, same commands; a project moves between them with one re-point + re-register. **No provider key in hand and none to get? Self-host is the fully-supported path today** — the provider market is only starting to form; never invent or recommend a provider that isn't in front of you.
 - **Tunnels (ngrok/cloudflared) are preview-only — never bake one on-chain** (dies on sleep, rotates on restart). A real launch puts the resolver on a host you control under your own domain (move = a DNS re-point), or behind a provider.
 
 **3. Identity** — `--name`, `--symbol`, `--royalty-bps` (default 500 = 5%), `--royalty-cap` (the permanent, **reduce-only** royalty ceiling — default 10%, or your royalty rate if higher; shown in the deploy readout, lowered later with `abx set-royalty-cap`), `--burnable` (opt-in: holders may burn their own token, default off), `--description "…"`, `--external-url <url>` (both served in the metadata — set them or the description is boilerplate). Owner + royalty receiver = the deploying wallet. These default to off-chain operator metadata (editable via `abx add <addr> --description "…"`). For a description that should outlast any node, add `--description-onchain` (or later `abx set-field <addr> --field description --text "…"`) → on-chain, freezable via `lock-field`; the resolver prefers the on-chain value. This is the per-field on-chain model — any field on-chain or off, one active `representation` (inline · reader · keccak256 · arweave · ipfs · url). Background: [metadata model](https://abx.docs.artblocks.io/protocol/metadata/).
-- **Credit + license** — deploy flags `--creator "…"` · `--license "…"` (also `--display-notes`, `--creator-links`) bake authorship + rights ON-CHAIN in the deploy tx (all three deploy commands); or set/change them later with `abx set-field <addr> --collection --field creator|license --text "…"`. Reserved collection fields served in `contractURI`, on any type (1/1 · Series · code). Detail: [operating.md → Authorship + rights](reference/operating.md#authorship--rights-credit--license).
+- **Credit + license** — deploy flags `--creator "…"` · `--license "…"` (also `--display-notes`, `--creator-links`) bake authorship + rights ON-CHAIN in the deploy tx (all three deploy commands); or set/change them later with `abx set-field <addr> --collection --field creator|license --text "…"`. Reserved collection fields served in `contractURI`, on any type (1/1 · Series · code). Detail: [operating.md → Authorship + rights](operating.md#authorship--rights-credit--license).
 - **Propose a real name/symbol and confirm — never silently bake a generic folder-name guess.** A folder called `series`/`images`/`photos` infers junk ("Series" / "SRS"), and on all three deploy commands the CLI *refuses* a real send that would bake its own placeholder identity (`--name`/`--symbol` missing) — because on-chain identity is effectively permanent. **In `--dry-run` the same check only warns** (so a preview still runs before you have the creator's title); don't read that warning as "the CLI allows it" — the real deploy stops. Suggest a specific title + a short ticker-style symbol drawn from the actual work, and get an explicit yes before deploying. Inference is a suggestion to confirm, not a default to ship — if the folder name is generic, say so and ask rather than proposing it.
 
 **4. Image placement** — `--image <path>` (png · jpg · gif · svg · webp). The on-chain keccak256 (`image` field) anchors integrity; size is bounded by the backend, not the chain.
@@ -77,59 +77,67 @@ Get decisions 1–2 right before deploy (image commitment + resolver URL are wri
 
 **Inline vs reader — default to the reader for real work.** `--onchain-uri` alone inlines the SVG (1 tx, ~700 gas/byte); `--onchain-image --compress fastlz` stages via SSTORE2 + a small `reader` pointer (~200 gas/byte, +1 tx) — **cheaper above ~0.5 KB** and widening with size. So: tiny (<~0.5 KB, a one-line SVG/short text) → `--onchain-uri` inline; real work (a few KB+) → `--onchain-image --compress fastlz`. **Never `--compress gzip` for an on-chain-rendered token** — gzip decodes off-chain only, breaking `--onchain-uri`; use fastlz (it decodes *in* the reader).
 
-### The READ ceiling — the number that actually decides "can this go on-chain?"
+### The READ cost — who can see it, and why nothing is refused
 
-Storage cost is not the constraint people think it is. **`tokenURI` reassembles the whole document on
-every call, measured at ~360,000–405,000 gas per KB across the 10–100 KB range that matters — and the
-rate climbs with size** (~460,000/KB at 187 KB, ~510,000/KB at 256 KB), because EVM memory expansion is
-quadratic. Quote it as a range, never as one flat per-KB number. `inline` and `reader` measure within
-~1% of each other up to 75 KB (the cost is the renderer's string building, not the storage mechanism),
-diverging to ~5% at 187 KB and ~10% at 256 KB as the chunk store's read loop dominates. So
-`--compress fastlz` makes it cheaper to *write* and not one gas cheaper to *read*.
+Two axes, and only one of them is about size limits at all.
 
-| On-chain content per token | `tokenURI` read (measured) | What it means |
+**WRITE is chunked and unbounded.** Content is split into 22,000-byte SSTORE2 chunks across separate
+transactions, so no block gas limit binds it at any size. It is purely money: ~200 gas/byte, paid once.
+
+**READ is one `eth_call`, and whether it succeeds belongs to whoever's endpoint is asking.** `tokenURI`
+reassembles the whole document per call, measured at ~360,000–405,000 gas per KB across 10–100 KB and
+climbing (~460,000/KB at 187 KB, ~510,000/KB at 256 KB) because EVM memory expansion is quadratic. Quote
+it as a range, never one flat per-KB number. `inline` and `reader` measure within ~1% of each other up
+to 75 KB, diverging to ~5% at 187 KB — so `--compress fastlz` makes content cheaper to *write* and not
+one gas cheaper to *read*.
+
+**The toolkit refuses NO size.** It used to refuse past 100 KB, reasoning from geth's 50M
+`--rpc.gascap` default minus a margin because hosted providers "commonly cap lower". Measured
+2026-08-24, they do not — and the refusal sat below every endpoint that could be found:
+
+| Endpoint | `eth_call` cap | Content it serves |
 |---|---|---|
-| ≲ **40 KB** | ~15M gas or less | fine — ordinary RPC tooling reads it |
-| **40–100 KB** | ~15–40M gas | **CLI warns.** Needs a deliberately high-gas RPC; past ~90 KB (~36M) no contract can read it inside a tx |
-| **> 100 KB** | ~40M+ | **CLI refuses** — a margin, not a wall: geth's own 50M `eth_call` default is not exhausted until ~120 KB, but hosted providers cap lower, so past 100 KB many marketplaces and indexers see a *revert* rather than the token |
-
-The refusal has an override, `--allow-unreadable-onchain`, and it is a real choice rather than a
-formality: maximum durability, nothing to run, ever — in exchange for a token most marketplaces and
-indexers cannot display. **Do not reach for it to get past a warning.** Name the trade to the creator in
-their words ("almost nothing will show your work unless someone runs a beefy node") and get an explicit
-yes; if they hesitate, the answer is `--backend arweave` (image off-chain, JSON still on-chain, no
-server) — same no-server promise, no read problem.
-
-**The gate is PER TOKEN, not per project.** Each token's `tokenURI` assembles only its own content, so a
-300-piece collection of 5 KB SVGs reads perfectly. The old "≲ 256 KB total per project" figure is a
-*write*-cost note only — the CLI still flags it, and it says nothing about readability.
-
-For a **code** project the same arithmetic applies to the assembled document, so a registry-hosted
-library (`--dep p5@1.0.0`, ~200 KB in the document) is inherently past the readable range. That lane is
-not refused — a big document is legitimate there and clients assemble it from the generator's piecewise
-getters (`document`, `tokenDataJson`, `dependencyTag`, `abxJs`, `gunzipScript`, `registryScriptChunk`) —
-but `deploy-code --dry-run` prints the gas figure, and you should relay it before the creator commits.
-
-**5. On-chain vs off-chain resolution** — by default `tokenURI`/`contractURI` point at your resolver. `--onchain-uri` = JSON assembled *on-chain* by the shared `AbxMetadataRenderer`, self-resolving forever — so it pairs with on-chain content, cost-effective only for tiny content (thresholds above).
-- **Fully on-chain = no server.** Don't stand one up; never cite a localhost URL. **Prove it with `abx tokenuri <addr>`** (reads `tokenURI(0)` over RPC, no `serve`). `abx serve` is only for off-chain-resolving tokens.
-- **The off-chain `tokenURI` is a base, not a per-token URL** — the contract stores a base and derives `{base}/{chainId}/{address}/{tokenId}`. Set via `--public-base-url` or `set-token-uri --uri <base>` later.
-- **Don't default to a frozen `ipfs://` tokenURI** — every edit then = re-pin + on-chain re-point, and the event spine stops driving the token (exiting the spec). Right only for true immutability, then lock it (`set-token-uri --override ipfs://<cid>` then `lock-uri`).
-- **Store ≠ lock; lock last.** On-chain ≠ frozen. Deploy unlocked, confirm it resolves in production, *then* freeze. For a static image/1-of-1, two locks freeze the metadata: `lock-field <addr> --field <name>` (a value) + `lock-uri <addr>` (how it resolves). **For a generative/code drop these are NOT enough** — the work is the on-chain program, which stays rewritable until you also run `lock-script <addr>` (and `lock-dependencies <addr>` for the library set). The full set for a code project = `lock-script` + `lock-dependencies` + `lock-field`/`lock-uri`. A deliberate follow-up, not the first deploy.
-
-**Say "locked metadata", never "immutable work".** Every lock freezes what *this contract stores*, and
-two things sit downstream of that: **an *ungoverned* PostParam has no lock** (the metadata locks cover
-fields and the URI config, not the param store — so the owner's raw setter keeps writing it and the
-renderer keeps serving it into `tokenURI`; a *schema'd* param can be welded permanently with
-`set-schema … :lock=now`, value **and** schema, so never say "params can't be locked"), and a **`Registry` dependency
-is re-fetched from the registry on every read** — `lock-dependencies` pins which library the ref means,
-not the bytes the registry hands back. `abx verify` reports `chain-complete` for a registry dep either
-way, because that flag is about *where* bytes come from, not whether they change. So the honest line to a
-creator (and to their buyers) is "the metadata is frozen"; only a project whose whole graph is on-chain
-`--dep 0x…` refs plus locked fields is a frozen *output*. Read the other way this is a feature — a piece
-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](../SKILL.md#deploy-strategy--when-to-mint).
+| **`sepolia.base.org`** — the default endpoint of our default chain | **600M** | **~729 KB** |
+| `base-sepolia.publicnode.com` · `base-sepolia.drpc.org` | 50M | ~117 KB |
+| `ethereum-sepolia.publicnode.com` | 50M | ~117 KB |
+
+So 50M is the **floor**, not the ceiling, and a fixed byte threshold could never express this. The CLI
+now **measures the RPC you are actually using** (a state-override `eth_call` that sends nothing and
+costs nothing) and reports it:
+
+| Content per token | What the CLI says |
+|---|---|
+| ≲ **117 KB** (~50M gas) | a plain note with the write and read figures — every endpoint measured serves it |
+| **above that** | ⚠ names your RPC's measured cap, what it can serve, and that a 50M-capped provider stops at ~117 KB and will show a **revert** instead of the token |
+| **past your own RPC's cap** | ⚠ says so plainly — nothing you can point at renders it, your own tooling included |
+
+**Your RPC is not the marketplace's RPC.** That is the distinction to carry into the conversation: a
+measured cap proves *you* can read the token, never that OpenSea can. So the honest framing is
+permanence versus reach — *"this will exist forever and a lot of viewers won't see it"* — and
+`--backend arweave` (image off-chain, JSON still on-chain, no server) is the other side of that trade.
+Say the numbers, name the trade, let the creator choose. Never call a supported size "impractical", and
+never route them to another protocol for something this does.
+
+**Three different limits get called "the gas limit", and conflating them is how this goes wrong.**
+Measured 2026-08-24: an **`eth_call` cap** bounds a read (600M on `sepolia.base.org`, 50M on
+publicnode/drpc) — the one that decides whether a token displays. An **`eth_estimateGas` cap** bounds
+what can be *sent* (16,777,216 on every endpoint tried, which is why writes batch at 8M). A **block
+gas limit** bounds a contract reading another contract *inside a transaction* — 1,200M on Base
+Sepolia, 400M on Base, 60M on Ethereum and Sepolia, so a contract on our default chain can read
+~1,100 KB in a tx, not the ~90 KB this file used to claim. Three limits, three orders of magnitude.
+
+**Reach is fixable after the fact — the bytes are permanent either way.** The read cost decides
+whether a token resolves *in one `eth_call`*, not whether the content is reachable. A resolver
+(`abx deploy-resolver`, or a hosted one) reads on-chain content with **its own** RPC and serves it as
+ordinary HTTP, so a marketplace fetches a URL and never makes the big call; `abx set-renderer <addr>
+--off` points `tokenURI` at it while every byte stays exactly where it is. So keep the two questions
+separate: **storage** is where the bytes live and whether they outlive you (on-chain is the strongest
+answer at any size); **serving** is how a viewer gets them today (self-resolving is purest and has a
+reach ceiling, a resolver has none and is a thing someone runs). Choosing on-chain does not commit a
+creator to self-resolving forever.
+
+One more thing not to garble: the gate is **per token**, so a 300-piece collection of 5 KB SVGs is
+fine.
 
 ## Locks — what actually freezes, and what a buyer is really asking