@artblocks/abx-sdk 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/types.d.ts

@@ -79,15 +79,39 @@ export interface SpineEvent {
 export interface TokenState {
     tokenId: string;
     /**
-     * Has this id ever had a mint? For a 721 token (`Transfer` from `0x0`): latches `true` once
-     * minted and stays true (721 has no burn in the spine). For an ERC-1155 edition
-     * (`TransferSingle`/`TransferBatch`): means **`supply > 0` right now** — recomputed on every
-     * transfer leg rather than latched, since an edition id CAN return to zero (a full burn) and
-     * mint again. `false` = deployed but not yet issued (721), or currently zero live copies (1155).
+     * Does a token exist at this id **right now** — the one question a consumer is actually asking.
+     *
+     * - `'unminted'` — ERC-721: a valid id never issued (the deployed-but-unminted state a resolver
+     *   serves warming metadata for). Valid state, not a gap.
+     * - `'live'` — a token exists: a 721 with a holder, or an edition id with `supply > 0`.
+     * - `'burned'` — **terminal, and ERC-721 only.** The id was issued and destroyed, the contract
+     *   disowns it (`tokenURI` reverts `NonexistentToken`), and it can never come back: ABX mints from
+     *   a monotonic `nextTokenId`, so no mint path can reissue that id. This is the word a consumer
+     *   may act on irreversibly — drop it from a gallery, answer `410 Gone`.
+     * - `'no-live-copies'` — **ERC-1155 editions only, and never terminal.** Zero live copies of this
+     *   id right now: never minted, or every copy burned, or minted and fully burned twice over. It
+     *   makes no claim about history *because the two have no different consequence* — the id can mint
+     *   again either way, so anything that treats it as gone forever is wrong. `supply`/`holders`
+     *   carry the numbers; the event log carries the history.
+     *
+     * **Why `'burned'` is not shared across the standards**, though the first draft of this enum shared
+     * it: the correct response to destruction differs by standard, so one word covering both put every
+     * consumer one forgotten branch away from serving `410 Gone` for an edition id that can mint again.
+     * abx-services caught that in review — our own migration note told them to map the shared word
+     * straight onto their `410` sites. Splitting the word moves the rule out of prose that must be
+     * remembered and into the type: **`lifecycle === 'burned'` is safe to treat as permanent on either
+     * standard, with no carve-out**, which is the only version of this rule that survives a refactor.
+     *
+     * It replaced a `minted: boolean` that latched `true` at mint and was never recomputed on the 721
+     * lane, so a burned token reconstructed as live, held by `0x0` — every consumer asking "does this
+     * exist" got `true` forever (abx-services, 2026-08-20, `docs/23`). "Was it ever issued" is
+     * `lifecycle !== 'unminted'` on a 721; on an edition, ask the log.
      */
-    minted: boolean;
-    /** 721 only — the current holder. Always `null` for an edition (an id can have many
-     *  concurrent holders; see {@link holders}). */
+    lifecycle: 'unminted' | 'live' | 'burned' | 'no-live-copies';
+    /** 721 only — the current holder; `null` when `'unminted'` or `'burned'` (a destroyed token has
+     *  no holder — the zero address is never written here, so this field never has to be read as a
+     *  sentinel). Always `null` for an edition (an id can have many concurrent holders; see
+     *  {@link holders}). */
     owner: Address | null;
     tokenURI: string | null;
     fields: MetadataField[];
@@ -150,6 +174,29 @@ export interface ProjectState {
         receiver: Address;
         bps: number;
     } | null;
+    /**
+     * The royalty **ceiling** — owner-set at deploy, reduce-only forever after, folded from
+     * `MaxRoyaltyBpsUpdated` (last-writer-wins, so a later `reduceMaxRoyaltyBps` beats the deploy-time
+     * value). Tri-state, and the third state carries weight: `null` means **the spine never stated
+     * one** — an implementation with no `maxRoyaltyBps()` at all — which is a different fact from a
+     * collection that published a ceiling of 1000. Never report a default for a ceiling the contract
+     * never published.
+     *
+     * Deliberately NOT nested inside {@link royalty}: clearing the royalty to `(0x0, 0)` sets that
+     * field to `null`, and the ceiling survives that on chain — nesting would drop a still-binding
+     * fact. Present them together in any readout, though: a rate without its ceiling is half the fact
+     * (a ceiling above the live rate means the owner can raise the rate unilaterally, and a buyer
+     * cannot see that from a listing — so reducing the cap to the current rate is what turns "5%
+     * today" into a promise).
+     */
+    maxRoyaltyBps?: number | null;
+    /**
+     * Did this collection opt into burning (`BurnConfigured`, emitted once at deploy and fixed
+     * thereafter)? Tri-state on the same rule as {@link maxRoyaltyBps}: `null` = the spine never
+     * stated it, which is not `false`. An implementation predating the opt-in has no `burn`
+     * entrypoint at all; a collection with `burnable: false` has one that refuses.
+     */
+    burnable?: boolean | null;
     tokenURIRenderer: Address | null;
     tokenURILocked: boolean | null;
     contractURIRenderer: Address | null;

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artblocks/abx-sdk",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "license": "MIT",
   "description": "ABX SDK (Layer 2) — the neutral, low-level library that turns protocol operations into typed function calls. No provider, no chain, no UX baked in.",
   "type": "module",
@@ -22,6 +22,7 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,