@artblocks/abx-sdk 0.1.0-alpha.0

package/dist/spine.d.ts

@@ -0,0 +1,110 @@
+import { type Hex } from 'viem';
+/**
+ * The native-dialect vocabulary of the event spine, expressed once so every
+ * consumer (indexer, token API, UX) speaks it identically.
+ *
+ * Extensions are identified on-chain by `keccak256(name)` and announced via
+ * `AbxExtensionVersionSet(id, version)`. We keep the *names* here and derive the
+ * ids, so adding a future extension is one line — never a magic constant.
+ */
+export declare const EXTENSION_NAMES: {
+    readonly royalty: "abx.extension.royalty";
+    readonly onChainMetadata: "abx.extension.onchain-metadata";
+    readonly maxInvocations: "abx.extension.max-invocations";
+    readonly externalMinter: "abx.extension.external-minter";
+    readonly primaryPayee: "abx.extension.primary-payee";
+    readonly paused: "abx.extension.paused";
+    readonly params: "abx.extension.params";
+    readonly configurableParams: "abx.extension.configurable-params";
+    readonly onChainScript: "abx.extension.onchain-script";
+    readonly dependencies: "abx.extension.dependencies";
+    readonly seedSource: "abx.extension.seed-source";
+};
+export type ExtensionKey = keyof typeof EXTENSION_NAMES;
+export declare const EXTENSION_ID: Record<ExtensionKey, Hex>;
+/** Friendly extension name for an on-chain id (falls back to the raw id). */
+export declare function extensionName(id: Hex): string;
+/**
+ * On-chain metadata `field` and `representation` tags are `bytes32` holding a short
+ * ASCII string, right-padded with zeros (a Solidity `bytes32` string literal). These
+ * encode/decode the readable tag both axes share (e.g. "image", "inline", "keccak256").
+ */
+export declare function decodeTag(bytes32: Hex): string;
+/** Encode a short metadata tag (a `field` or `representation`, e.g. "image") as a `bytes32`. */
+export declare function encodeTag(tag: string): Hex;
+/** Canonical on-chain metadata field tags (mirror `MetadataFields.sol`; a field key = its JSON key). */
+export declare const METADATA_FIELD: {
+    readonly name: "name";
+    readonly description: "description";
+    readonly image: "image";
+    readonly animationUrl: "animation_url";
+    readonly externalUrl: "external_url";
+    readonly attributes: "attributes";
+    readonly backgroundColor: "background_color";
+    readonly youtubeUrl: "youtube_url";
+    readonly bannerImage: "banner_image";
+    readonly featuredImage: "featured_image";
+    readonly externalLink: "external_link";
+    readonly collaborators: "collaborators";
+    readonly artist: "artist";
+    readonly displayNotes: "display_notes";
+    readonly artistLinks: "artist_links";
+    readonly license: "license";
+};
+/**
+ * Canonical representation tags — the *how* of an on-chain metadata field. These are
+ * protocol convention (the contract stores `bytes32` opaquely; it never branches on them).
+ * A field carries exactly one. `reader` delegates on-chain decoding to a separate
+ * `IAbxOnChainReader` contract (value = `(reader, pointer)`); `gzip` variants are
+ * inflated off-chain by the indexer.
+ */
+export declare const METADATA_REPRESENTATION: {
+    readonly inline: "inline";
+    readonly reader: "reader";
+    readonly renderer: "renderer";
+    readonly readerGzip: "reader-gzip";
+    readonly keccak256: "keccak256";
+    readonly sha256: "sha256";
+    readonly arweave: "arweave";
+    readonly ipfs: "ipfs";
+    readonly url: "url";
+    readonly urlTemplate: "url-template";
+    readonly inlineGzip: "inline-gzip";
+};
+/**
+ * The Configurable Params type + auth vocabularies — index-aligned with the
+ * Solidity enums (`IAbxConfigurableParams.ParamType` / `.AuthOption`), so a
+ * uint8 from an event decodes to its canonical name by index.
+ */
+export declare const PARAM_TYPES: readonly ["Bool", "Select", "Uint256Range", "Int256Range", "DecimalRange", "HexColor", "Timestamp", "String", "Bytes"];
+export type ParamTypeName = (typeof PARAM_TYPES)[number];
+export declare const AUTH_OPTIONS: readonly ["Artist", "TokenOwner", "Address", "ArtistOrTokenOwner", "ArtistOrAddress", "TokenOwnerOrAddress", "ArtistOrTokenOwnerOrAddress"];
+export type AuthOptionName = (typeof AUTH_OPTIONS)[number];
+/** The canonical delegate.xyz v2 registry — the TokenOwner-auth-leg default (same address every chain). */
+export declare const DELEGATE_REGISTRY_DEFAULT: Hex;
+/**
+ * The canonical scalar decode — the JS twin of `TokenDataLib.decodeScalar`: one
+ * stored `bytes32` → the canonical string `tokenData` carries. `String`/`Bytes`
+ * are data-backed (UTF-8 passthrough / base64 at read) and never pass through here.
+ */
+export declare function decodeScalarParam(paramType: ParamTypeName, value: Hex | bigint): string;
+/** `DecimalRange`: stored uint ÷ 1e10, trailing zeros trimmed, no point when whole. */
+export declare function decodeDecimalParam(v: bigint): string;
+/**
+ * The reverse canonical decode: a human input string → the stored `bytes32`, per the
+ * schema's type — what a configure UI (or `abx configure-param`) writes with. Returns
+ * the canonical display form alongside (round-tripped through {@link decodeScalarParam}).
+ */
+export declare function encodeScalarParam(paramType: ParamTypeName, input: string, selectOptions?: string[]): {
+    value: Hex;
+    display: string;
+};
+/**
+ * Human-facing descriptions of each spine signal — used by the dashboard to
+ * narrate "what the chain told us." Keyed by event name.
+ */
+export declare const SPINE_EVENT_DOC: Record<string, {
+    register: 1 | 2;
+    what: string;
+}>;
+//# sourceMappingURL=spine.d.ts.map

package/dist/spine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.d.ts","sourceRoot":"","sources":["../src/spine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,KAAK,GAAG,EAAC,MAAM,MAAM,CAAC;AAEtE;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;CAelB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,eAAe,CAAC;AAExD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,GAAG,CAErB,CAAC;AAM/B,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,EAAE,EAAE,GAAG,GAAG,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,CAM9C;AAED,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAE1C;AAED,wGAAwG;AACxG,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;CAoBjB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAY1B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,WAAW,wHAUd,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,eAAO,MAAM,YAAY,6IAQf,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,2GAA2G;AAC3G,eAAO,MAAM,yBAAyB,EAAE,GAAkD,CAAC;AAK3F;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,MAAM,CAevF;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpD;AAGD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,MAAM,EACb,aAAa,GAAE,MAAM,EAAO,GAC3B;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAoD/B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;IAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAyC3E,CAAC"}

package/dist/spine.js.map

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

package/dist/token.d.ts

@@ -0,0 +1,33 @@
+import { type Address, type Hex } from 'viem';
+import type { MetadataField, ProjectState, TokenState } from './types.js';
+/** The token in a reconstructed project, or null. */
+export declare function findToken(state: ProjectState, tokenId: string | number): TokenState | null;
+/** A field's single active on-chain entry (`{field, representation, value}`), or null if unset. */
+export declare function fieldOf(fields: MetadataField[], fieldName: string): MetadataField | null;
+export declare function isOnChain(representation: string): boolean;
+/** Decode an `inline` field value as UTF-8 text. */
+export declare function inlineText(field: MetadataField): string;
+/** Decode an `inline` field value as raw bytes. */
+export declare function inlineBytes(field: MetadataField): Uint8Array;
+/** Verify bytes against a field carried as a `keccak256`/`sha256` hash; null if not a hash representation. */
+export declare function verifyAgainstHash(bytes: Uint8Array | string, field: MetadataField): boolean | null;
+/**
+ * Decode a `reader` field value → `(reader, pointer)` addresses. Content is then
+ * obtained on-chain by `IAbxOnChainReader(reader).read(pointer)` (an `eth_call`). The
+ * reader encapsulates storage + on-chain decoding; this just unpacks the two addresses.
+ */
+export declare function decodeReader(value: Hex): {
+    reader: Address;
+    pointer: Address;
+};
+/** Encode a `reader` field value from `(reader, pointer)` — the write-side counterpart. */
+export declare function encodeReader(reader: Address, pointer: Address): Hex;
+/**
+ * Encode a `renderer` field value — `abi.encode(address fieldRenderer)` (the representations
+ * table, specs/protocol/onchain-metadata.md). Content is COMPUTED at read: the metadata
+ * renderer (and the off-chain resolver) staticcall `render(token, tokenId, field)` on it.
+ */
+export declare function encodeFieldRenderer(fieldRenderer: Address): Hex;
+/** Decode a `renderer` field value back to the field-renderer address (the read-side twin). */
+export declare function decodeFieldRenderer(value: Hex): Address;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,GAAG,EACT,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAAC,aAAa,EAAE,YAAY,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AAExE,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CAG1F;AAED,mGAAmG;AACnG,wBAAgB,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAExF;AAED,wBAAgB,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAMvD;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAE5D;AAED,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,IAAI,CAKlG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAG5E;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,GAAG,CAInE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,OAAO,GAAG,GAAG,CAE/D;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAGvD"}

package/dist/token.js

@@ -0,0 +1,66 @@
+import { keccak256, sha256, hexToString, hexToBytes, decodeAbiParameters, } from 'viem';
+import { METADATA_REPRESENTATION as R } from './spine.js';
+/** The token in a reconstructed project, or null. */
+export function findToken(state, tokenId) {
+    const id = String(tokenId);
+    return state.tokens.find((t) => t.tokenId === id) ?? null;
+}
+/** A field's single active on-chain entry (`{field, representation, value}`), or null if unset. */
+export function fieldOf(fields, fieldName) {
+    return fields.find((f) => f.field === fieldName) ?? null;
+}
+export function isOnChain(representation) {
+    return representation === R.inline || representation === R.reader;
+}
+// ── value decoding by representation ─────────────────────────────────────────
+/** Decode an `inline` field value as UTF-8 text. */
+export function inlineText(field) {
+    try {
+        return hexToString(field.value);
+    }
+    catch {
+        return '';
+    }
+}
+/** Decode an `inline` field value as raw bytes. */
+export function inlineBytes(field) {
+    return hexToBytes(field.value);
+}
+/** Verify bytes against a field carried as a `keccak256`/`sha256` hash; null if not a hash representation. */
+export function verifyAgainstHash(bytes, field) {
+    const input = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes;
+    if (field.representation === R.keccak256)
+        return keccak256(input) === field.value;
+    if (field.representation === R.sha256)
+        return sha256(input) === field.value;
+    return null;
+}
+/**
+ * Decode a `reader` field value → `(reader, pointer)` addresses. Content is then
+ * obtained on-chain by `IAbxOnChainReader(reader).read(pointer)` (an `eth_call`). The
+ * reader encapsulates storage + on-chain decoding; this just unpacks the two addresses.
+ */
+export function decodeReader(value) {
+    const [reader, pointer] = decodeAbiParameters([{ type: 'address' }, { type: 'address' }], value);
+    return { reader, pointer };
+}
+/** Encode a `reader` field value from `(reader, pointer)` — the write-side counterpart. */
+export function encodeReader(reader, pointer) {
+    // abi.encode(address, address)
+    const strip = (a) => a.slice(2).toLowerCase().padStart(64, '0');
+    return (`0x${strip(reader)}${strip(pointer)}`);
+}
+/**
+ * Encode a `renderer` field value — `abi.encode(address fieldRenderer)` (the representations
+ * table, specs/protocol/onchain-metadata.md). Content is COMPUTED at read: the metadata
+ * renderer (and the off-chain resolver) staticcall `render(token, tokenId, field)` on it.
+ */
+export function encodeFieldRenderer(fieldRenderer) {
+    return (`0x${fieldRenderer.slice(2).toLowerCase().padStart(64, '0')}`);
+}
+/** Decode a `renderer` field value back to the field-renderer address (the read-side twin). */
+export function decodeFieldRenderer(value) {
+    const [renderer] = decodeAbiParameters([{ type: 'address' }], value);
+    return renderer;
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/dist/tokendata.d.ts

@@ -0,0 +1,50 @@
+import { type Hex, type PublicClient } from 'viem';
+import type { MetadataField, ProjectState, TokenState } from './types.js';
+export interface TokenDataResult {
+    /** The flat object (values are canonical strings; `chainId` is a number). */
+    data: Record<string, string | number>;
+    /** The canonical serialization: keys sorted lexicographically, no insignificant whitespace. */
+    json: string;
+}
+/** The `code` collection field (directory mode), if any — locators only per the registry. */
+export declare function codeField(state: ProjectState): MetadataField | null;
+/** Whether this project has executable content (a `code` field, or on-chain script chunks). */
+export declare function isCodeProject(state: ProjectState): boolean;
+/** A well-known contract param's canonical string (e.g. `display.animation`), or null. */
+export declare function contractParamString(state: ProjectState, key: string): string | null;
+/**
+ * Assemble canonical tokenData. `client` null ⇒ best-effort (no blobs, no augment hook).
+ *
+ * `opts.augment` picks between the two canonical forms:
+ *  - **full** (default, `augment: true`) — settled params + the augment hook's LIVE entries.
+ *    What the live view injects: current by construction, stale the moment after.
+ *  - **settled** (`augment: false`) — event-derived state only (explicit params ∪ seed ∪
+ *    data-backed blobs; all deterministic chain reads). This is what effect outputs are
+ *    ADDRESSED by: a still is a snapshot of settled state, so a volatile augment hook
+ *    (block timestamp, an oracle) animates the live view without re-addressing the render
+ *    every block — the cache stays hot, and re-render triggers are settled-state changes only.
+ */
+export declare function buildTokenData(client: PublicClient | null, state: ProjectState, token: TokenState, opts?: {
+    augment?: boolean;
+}): Promise<TokenDataResult>;
+/** The canonical serialization: lexicographically sorted keys, compact JSON, UTF-8. */
+export declare function canonicalTokenDataJson(data: Record<string, string | number>): string;
+/**
+ * The effect run identity (`specs/protocol/effects.md`):
+ * `keccak256(contentDigest ‖ canonical tokenData ‖ environmentId)`. Deterministic across
+ * producers and consumers — the resolver computes the CURRENT hash and looks up exactly
+ * that artifact, so a param change re-addresses output and stale renders are never served.
+ */
+export declare function inputsHash(contentDigest: Hex | null, canonicalJson: string, environmentId?: string): Hex;
+/** The project's content digest: on-chain script digest (head-read), else keccak of the
+ *  `code` field's locator value (content-addressed forms carry their own integrity). */
+export declare function contentDigestOf(state: ProjectState): Hex | null;
+/**
+ * The canonical artifact address for an effect output, mapped onto the hash-keyed
+ * byte-custody interface: `keccak256` of the path
+ * `{chainId}/{address}/{tokenId}/{effectKey}/{inputsHash}/{outputKey}` — so every
+ * conforming producer (the `abx render` CLI, a hosted node) and consumer (this
+ * resolver) agree on where a run's artifacts live, over any storage backend.
+ */
+export declare function renderArtifactKey(chainId: number, address: string, tokenId: string, hash: Hex, outputKey?: string, effectKey?: string): Hex;
+//# sourceMappingURL=tokendata.d.ts.map

package/dist/tokendata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokendata.d.ts","sourceRoot":"","sources":["../src/tokendata.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,GAAG,EACR,KAAK,YAAY,EAClB,MAAM,MAAM,CAAC;AAGd,OAAO,KAAK,EAAC,aAAa,EAA2B,YAAY,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AAuBjG,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACtC,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,GAAG,IAAI,CAEnE;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE1D;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAM,GAC7B,OAAO,CAAC,eAAe,CAAC,CAyC1B;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAIpF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,aAAa,EAAE,GAAG,GAAG,IAAI,EACzB,aAAa,EAAE,MAAM,EACrB,aAAa,SAAY,GACxB,GAAG,CAQL;AAED;wFACwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,GAAG,GAAG,IAAI,CAI/D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,GAAG,EACT,SAAS,GAAE,MAAgB,EAC3B,SAAS,SAAW,GACnB,GAAG,CAIL"}

package/dist/tokendata.js

@@ -0,0 +1,178 @@
+import { concat, hexToBytes, keccak256, parseAbi, stringToBytes, } from 'viem';
+import { seriesCodeAbi } from './abi/index.js';
+import { decodeScalarParam } from './spine.js';
+/**
+ * The canonical `tokenData` assembly — the off-chain serializer the spec names as
+ * authoritative (`specs/protocol/code-projects.md`). One flat object: the reserved
+ * coordinates + every param (contract ∪ token scope, token wins) + the augment hook's
+ * entries (augment wins per key), every value its canonical string (`chainId` alone is
+ * a number). The serialization is canonical because it is *hashed*: an effect's
+ * `inputsHash` commits to it, so this exact byte shape is what makes render outputs
+ * addressable and self-invalidating.
+ *
+ * Decode rules: a schema'd param decodes per its type (`Select` → the option string,
+ * `DecimalRange` ÷ 1e10, …); a schema-less literal stays the raw `bytes32` hex (a
+ * schema is what buys a human decode — `seed` is the canonical example); a data-backed
+ * value reads its blob (`String` → UTF-8, `Bytes`/schema-less → base64).
+ */
+const RESERVED = new Set(['chainId', 'contractAddress', 'tokenId', 'seed']);
+const augmentHookAbi = parseAbi([
+    'function augmentTokenParams(address token, uint256 tokenId) view returns ((bytes32 key, string value)[])',
+]);
+/** The `code` collection field (directory mode), if any — locators only per the registry. */
+export function codeField(state) {
+    return state.collectionFields.find((f) => f.field === 'code') ?? null;
+}
+/** Whether this project has executable content (a `code` field, or on-chain script chunks). */
+export function isCodeProject(state) {
+    return codeField(state) !== null || ((state.script?.chunkCount ?? 0) > 0);
+}
+/** A well-known contract param's canonical string (e.g. `display.animation`), or null. */
+export function contractParamString(state, key) {
+    const p = state.contractParams?.find((x) => x.key === key);
+    if (!p || p.valueIsHash)
+        return null;
+    return decodeTagLoose(p.value);
+}
+/**
+ * Assemble canonical tokenData. `client` null ⇒ best-effort (no blobs, no augment hook).
+ *
+ * `opts.augment` picks between the two canonical forms:
+ *  - **full** (default, `augment: true`) — settled params + the augment hook's LIVE entries.
+ *    What the live view injects: current by construction, stale the moment after.
+ *  - **settled** (`augment: false`) — event-derived state only (explicit params ∪ seed ∪
+ *    data-backed blobs; all deterministic chain reads). This is what effect outputs are
+ *    ADDRESSED by: a still is a snapshot of settled state, so a volatile augment hook
+ *    (block timestamp, an oracle) animates the live view without re-addressing the render
+ *    every block — the cache stays hot, and re-render triggers are settled-state changes only.
+ */
+export async function buildTokenData(client, state, token, opts = {}) {
+    const schemas = new Map((state.paramSchemas ?? []).map((s) => [s.key, s]));
+    const data = {
+        chainId: state.chainId,
+        contractAddress: state.address.toLowerCase(),
+        tokenId: token.tokenId,
+    };
+    // contract ∪ token scope, token wins — decoded per schema (or the schema-less rule)
+    const merged = new Map();
+    for (const p of state.contractParams ?? [])
+        merged.set(p.key, { p, tokenScope: false });
+    for (const p of token.params ?? [])
+        merged.set(p.key, { p, tokenScope: true });
+    for (const [key, { p, tokenScope }] of merged) {
+        if (RESERVED.has(key) && key !== 'seed')
+            continue; // coordinates win
+        data[key] = await decodeParam(client, state.address, token.tokenId, p, tokenScope, schemas.get(key));
+    }
+    // augment hook — last, wins per key (except the reserved coordinates). Skipped for the
+    // SETTLED form (opts.augment false): live data belongs in the live view, never in the
+    // address of a render artifact.
+    const hook = state.paramHooks?.augmentHook ?? null;
+    if (client && hook && (opts.augment ?? true)) {
+        try {
+            const entries = (await client.readContract({
+                address: hook,
+                abi: augmentHookAbi,
+                functionName: 'augmentTokenParams',
+                args: [state.address, BigInt(token.tokenId)],
+            }));
+            for (const e of entries) {
+                const key = decodeBytes32Key(e.key);
+                if (RESERVED.has(key))
+                    continue;
+                data[key] = e.value;
+            }
+        }
+        catch {
+            // best-effort by design: a broken augment hook must never take tokenData down
+        }
+    }
+    return { data, json: canonicalTokenDataJson(data) };
+}
+/** The canonical serialization: lexicographically sorted keys, compact JSON, UTF-8. */
+export function canonicalTokenDataJson(data) {
+    const sorted = {};
+    for (const key of Object.keys(data).sort())
+        sorted[key] = data[key];
+    return JSON.stringify(sorted);
+}
+/**
+ * The effect run identity (`specs/protocol/effects.md`):
+ * `keccak256(contentDigest ‖ canonical tokenData ‖ environmentId)`. Deterministic across
+ * producers and consumers — the resolver computes the CURRENT hash and looks up exactly
+ * that artifact, so a param change re-addresses output and stale renders are never served.
+ */
+export function inputsHash(contentDigest, canonicalJson, environmentId = 'web:any') {
+    return keccak256(concat([
+        contentDigest ? hexToBytes(contentDigest) : new Uint8Array([0]),
+        stringToBytes(canonicalJson),
+        stringToBytes(environmentId),
+    ]));
+}
+/** The project's content digest: on-chain script digest (head-read), else keccak of the
+ *  `code` field's locator value (content-addressed forms carry their own integrity). */
+export function contentDigestOf(state) {
+    if (state.script?.digest)
+        return state.script.digest;
+    const code = codeField(state);
+    return code ? keccak256(code.value) : null;
+}
+/**
+ * The canonical artifact address for an effect output, mapped onto the hash-keyed
+ * byte-custody interface: `keccak256` of the path
+ * `{chainId}/{address}/{tokenId}/{effectKey}/{inputsHash}/{outputKey}` — so every
+ * conforming producer (the `abx render` CLI, a hosted node) and consumer (this
+ * resolver) agree on where a run's artifacts live, over any storage backend.
+ */
+export function renderArtifactKey(chainId, address, tokenId, hash, outputKey = 'image', effectKey = 'render') {
+    return keccak256(stringToBytes(`${chainId}/${address.toLowerCase()}/${tokenId}/${effectKey}/${hash}/${outputKey}`));
+}
+// ── internals ──────────────────────────────────────────────────────────────────
+async function decodeParam(client, token, tokenId, p, tokenScope, schema) {
+    if (!p.valueIsHash) {
+        if (!schema)
+            return p.key === 'seed' ? p.value : decodeTagLoose(p.value);
+        if (schema.paramType === 'Select') {
+            const idx = Number(BigInt(p.value));
+            return schema.selectOptions[idx] ?? String(idx);
+        }
+        return decodeScalarParam(schema.paramType, p.value);
+    }
+    // data-backed: read the blob (token scope falls back to contract scope by construction)
+    if (!client)
+        return p.value; // best-effort floor: the hash itself
+    try {
+        const blob = (await client.readContract({
+            address: token,
+            abi: seriesCodeAbi,
+            functionName: tokenScope ? 'tokenParamData' : 'contractParamData',
+            args: tokenScope ? [BigInt(tokenId), keyToBytes32(p.key)] : [keyToBytes32(p.key)],
+        }));
+        const bytes = hexToBytes(blob);
+        if (schema?.paramType === 'String')
+            return new TextDecoder().decode(bytes);
+        return Buffer.from(bytes).toString('base64'); // Bytes + schema-less: base64 at read
+    }
+    catch {
+        return p.value;
+    }
+}
+/** A readable-ASCII `bytes32` literal as its string (e.g. a `display.animation` value). */
+function decodeTagLoose(value) {
+    const bytes = hexToBytes(value);
+    let end = bytes.length;
+    while (end > 0 && bytes[end - 1] === 0)
+        end--;
+    const trimmed = bytes.slice(0, end);
+    const isAscii = trimmed.length > 0 && trimmed.every((b) => b >= 0x20 && b < 0x7f);
+    return isAscii ? new TextDecoder().decode(trimmed) : value;
+}
+function decodeBytes32Key(key) {
+    return decodeTagLoose(key);
+}
+function keyToBytes32(key) {
+    const bytes = new Uint8Array(32);
+    bytes.set(stringToBytes(key).slice(0, 32));
+    return `0x${Buffer.from(bytes).toString('hex')}`;
+}
+//# sourceMappingURL=tokendata.js.map

package/dist/tokendata.js.map

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

package/dist/traits.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenSea-style token traits (`attributes`). The protocol stores them as one
+ * metadata field (`attributes`) carrying **inline JSON** when on-chain; off-chain,
+ * an operator keeps the same array in their resolver's registration. Either way the
+ * shape is the marketplace standard — `{trait_type, value, display_type?}` — and
+ * NOT a dumping ground for protocol facts (version, canonical, royalty); those are
+ * `abx_provenance` / ERC-2981 concerns, never traits. This module is the one place
+ * the toolkit parses, validates, and merges them, so the CLI (write side) and the
+ * resolver (read side) agree on exactly one normal form.
+ */
+export interface OpenSeaAttribute {
+    trait_type: string;
+    value: string | number;
+    /** OpenSea display hint, e.g. `number`, `boost_percentage`, `date`. Omitted for plain string traits. */
+    display_type?: string;
+}
+/**
+ * Normalize arbitrary input into a validated OpenSea attribute array. Accepts either
+ * the canonical array form (`[{trait_type, value, display_type?}]`) or a convenience
+ * object map (`{Background: "Blue", Edition: 3}`). Drops entries with an empty
+ * `trait_type`. Throws only on a value that's structurally not traits at all.
+ */
+export declare function normalizeAttributes(input: unknown): OpenSeaAttribute[];
+/**
+ * Parse the quick inline trait form used on the CLI: `"Background=Blue; Edition=3"`.
+ * Semicolon- (or newline-) separated `key=value` pairs; a numeric value becomes a
+ * number. For anything richer (display_type, etc.) use a JSON file via
+ * {@link normalizeAttributes}.
+ */
+export declare function parseTraitPairs(spec: string): OpenSeaAttribute[];
+/**
+ * Merge on-chain and off-chain attributes into the served set. **On-chain wins per
+ * `trait_type`** (case-insensitively) — a trait committed on-chain overrides an
+ * off-chain one of the same name — and the rest are unioned. On-chain order is kept
+ * first, then any off-chain traits the chain didn't already define.
+ */
+export declare function stitchAttributes(onChain: OpenSeaAttribute[] | null | undefined, offChain: OpenSeaAttribute[] | null | undefined): OpenSeaAttribute[];
+//# sourceMappingURL=traits.d.ts.map

package/dist/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AASD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAyBtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAchE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,GAAG,SAAS,EAC9C,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,GAAG,SAAS,GAC9C,gBAAgB,EAAE,CAKpB"}

package/dist/traits.js

@@ -0,0 +1,92 @@
+/**
+ * OpenSea-style token traits (`attributes`). The protocol stores them as one
+ * metadata field (`attributes`) carrying **inline JSON** when on-chain; off-chain,
+ * an operator keeps the same array in their resolver's registration. Either way the
+ * shape is the marketplace standard — `{trait_type, value, display_type?}` — and
+ * NOT a dumping ground for protocol facts (version, canonical, royalty); those are
+ * `abx_provenance` / ERC-2981 concerns, never traits. This module is the one place
+ * the toolkit parses, validates, and merges them, so the CLI (write side) and the
+ * resolver (read side) agree on exactly one normal form.
+ */
+/** Coerce a loose value to a trait value: numbers stay numbers, everything else is a trimmed string. */
+function coerceValue(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'boolean')
+        return v ? 'true' : 'false';
+    return String(v).trim();
+}
+/**
+ * Normalize arbitrary input into a validated OpenSea attribute array. Accepts either
+ * the canonical array form (`[{trait_type, value, display_type?}]`) or a convenience
+ * object map (`{Background: "Blue", Edition: 3}`). Drops entries with an empty
+ * `trait_type`. Throws only on a value that's structurally not traits at all.
+ */
+export function normalizeAttributes(input) {
+    if (input == null)
+        return [];
+    const rows = [];
+    if (Array.isArray(input)) {
+        for (const raw of input) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const r = raw;
+            const trait_type = String(r.trait_type ?? r.traitType ?? '').trim();
+            if (!trait_type)
+                continue;
+            const attr = { trait_type, value: coerceValue(r.value) };
+            const dt = r.display_type ?? r.displayType;
+            if (dt != null && String(dt).trim())
+                attr.display_type = String(dt).trim();
+            rows.push(attr);
+        }
+        return rows;
+    }
+    if (typeof input === 'object') {
+        for (const [k, v] of Object.entries(input)) {
+            const trait_type = k.trim();
+            if (!trait_type)
+                continue;
+            rows.push({ trait_type, value: coerceValue(v) });
+        }
+        return rows;
+    }
+    throw new Error('attributes must be a JSON array of {trait_type, value} or an object map of {name: value}');
+}
+/**
+ * Parse the quick inline trait form used on the CLI: `"Background=Blue; Edition=3"`.
+ * Semicolon- (or newline-) separated `key=value` pairs; a numeric value becomes a
+ * number. For anything richer (display_type, etc.) use a JSON file via
+ * {@link normalizeAttributes}.
+ */
+export function parseTraitPairs(spec) {
+    const out = [];
+    for (const part of spec.split(/[;\n]+/)) {
+        const s = part.trim();
+        if (!s)
+            continue;
+        const eq = s.indexOf('=');
+        if (eq === -1)
+            throw new Error(`trait "${s}" must be key=value`);
+        const trait_type = s.slice(0, eq).trim();
+        const rawValue = s.slice(eq + 1).trim();
+        if (!trait_type)
+            throw new Error(`trait "${s}" has an empty name`);
+        const num = Number(rawValue);
+        out.push({ trait_type, value: rawValue !== '' && Number.isFinite(num) ? num : rawValue });
+    }
+    return out;
+}
+/**
+ * Merge on-chain and off-chain attributes into the served set. **On-chain wins per
+ * `trait_type`** (case-insensitively) — a trait committed on-chain overrides an
+ * off-chain one of the same name — and the rest are unioned. On-chain order is kept
+ * first, then any off-chain traits the chain didn't already define.
+ */
+export function stitchAttributes(onChain, offChain) {
+    const chain = onChain ?? [];
+    const off = offChain ?? [];
+    const seen = new Set(chain.map((a) => a.trait_type.toLowerCase()));
+    return [...chain, ...off.filter((a) => !seen.has(a.trait_type.toLowerCase()))];
+}
+//# sourceMappingURL=traits.js.map

package/dist/traits.js.map

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