@artblocks/abx-sdk 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/service.js

@@ -0,0 +1,376 @@
+/**
+ * The remote-service client — the SDK's one HTTP surface, speaking the provider-neutral
+ * control plane pinned by specs/self-host-toolkit/remote-services.md. A client is bound to an
+ * endpoint + an injected bearer token, never to a brand: the reference CLI, the effects runner,
+ * and any hosted agent drive a self-hosted node and a managed provider through this same class.
+ *
+ * The token authorizes index/metadata control only — never on-chain signing. No env reads here;
+ * credential resolution is the caller's concern (the CLI's named-remote convention lives in
+ * packages/cli/src/remote.ts).
+ */
+import { linearBackoffDelay, sleep } from './util.js';
+export const WELL_KNOWN_SERVICE_PATH = '/.well-known/abx-service';
+/**
+ * Versioned interface ids a service declares in its descriptor. Versions ride these ids
+ * (they track the `/v1` path prefix); the descriptor has no separate format version.
+ *
+ * There are exactly two, and they are **all-or-nothing**: declaring one asserts every route it names
+ * answers per the spec. The artifact-registry routes ride {@link CONTROL_PLANE_INTERFACE} rather
+ * than an id of their own — once referenced output is locator-only, accepting a registration is a
+ * database insert, so a separate capability flag would describe a distinction that doesn't exist.
+ * A service that won't take a given caller's artifacts refuses on the credential (`403`), which is
+ * the honest axis: interfaces describe wire grammar, tokens describe permission.
+ */
+export const TOKEN_API_INTERFACE = 'abx-token-api/v1';
+export const CONTROL_PLANE_INTERFACE = 'abx-control-plane/v1';
+/**
+ * Why this locator can't be accepted for a referenced artifact, or `null` if it passes.
+ *
+ * A locator is a **reachability** claim, not a durability one: it must resolve for a third party
+ * with no producer credentials and no private-network assumption. The protocol deliberately has
+ * **no preference among schemes** — `https://` (S3/R2, a producer's own public base, a chosen
+ * IPFS/Arweave gateway), `ipfs://` and `ar://` are peers, because derived output is re-creatable and
+ * a producer with an opinion about which gateway serves its art is making an operational call the
+ * protocol has no standing to override.
+ *
+ * Reachability can't be *proved* without fetching, and fetching a third-party URL while handling an
+ * authed write is byte custody through the back door plus an SSRF surface. So this checks the two
+ * things that are decidable from the string alone and are always wrong:
+ *   - a private / loopback host — resolvable only from the producer's own network;
+ *   - a presigned, expiring URL — resolvable now, dead later, which is the worst failure shape
+ *     (it passes every check at publish time and rots silently).
+ */
+export function locatorRejectionReason(locator) {
+    const trimmed = locator.trim();
+    if (!/^(https?|ipfs|ar):/i.test(trimmed)) {
+        return `unsupported scheme — use https://, ipfs:// or ar://`;
+    }
+    if (/^https?:/i.test(trimmed)) {
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            return 'not a parseable URL';
+        }
+        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+        const privateHost = host === 'localhost' ||
+            host.endsWith('.localhost') ||
+            host === '::1' ||
+            host === '0.0.0.0' ||
+            /^127\./.test(host) ||
+            /^10\./.test(host) ||
+            /^192\.168\./.test(host) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+            /^169\.254\./.test(host) ||
+            /^f[cd][0-9a-f]{2}:/.test(host);
+        if (privateHost) {
+            return `'${url.hostname}' is a loopback/private host — a locator must resolve for anyone, not just from the producer's network`;
+        }
+        const q = url.searchParams;
+        if (q.has('X-Amz-Signature') || q.has('Signature') || q.has('X-Goog-Signature') || q.has('sig') || q.has('Expires') || q.has('X-Amz-Expires')) {
+            return 'looks like a presigned/expiring URL — it would resolve now and rot later; publish a durable public URL instead';
+        }
+    }
+    return null;
+}
+/** Statuses a caller can stop waiting on — see {@link AbxServiceClient.awaitIndexed}. */
+export const TERMINAL_INDEX_STATUSES = ['live', 'failed'];
+/** The one message per class. Fixed strings — an upstream error is never interpolated, because a
+ *  keyed RPC URL *is* a credential and upstream messages routinely embed one. */
+const INDEX_ERROR_MESSAGES = {
+    rpc_unavailable: 'upstream RPC unavailable; will retry',
+    rpc_rate_limited: 'upstream RPC rate-limited; will retry',
+    not_abx_contract: 'address emits no ABX event spine on this chain',
+    internal: 'indexing failed; see the service operator’s logs',
+};
+/** Map a catch-up failure to its wire form. Sniffs the underlying error's shape only to CHOOSE a
+ *  class — nothing from it reaches the returned message. */
+export function classifyIndexError(err) {
+    const raw = err instanceof Error ? `${err.name} ${err.message}` : String(err);
+    const text = raw.toLowerCase();
+    let cls = 'internal';
+    if (/rate.?limit|too many requests|\b429\b|quota|exceeded .*(?:compute|cu)|throttl/.test(text)) {
+        cls = 'rpc_rate_limited';
+    }
+    else if (/timeout|timed out|econnrefused|econnreset|enotfound|eai_again|socket hang up|fetch failed|network|502|503|504|http request failed/.test(text)) {
+        cls = 'rpc_unavailable';
+    }
+    return { class: cls, message: INDEX_ERROR_MESSAGES[cls] };
+}
+/** Narrow a register response to the deferred-catch-up branch. */
+export function isAccepted(r) {
+    return r.accepted === true;
+}
+/**
+ * How far along a BACKFILL is, from a status read — `null` when there is no meaningful ratio.
+ *
+ * Deliberately `null` for anything but `backfilling`, because `toBlock` measures two different things
+ * depending on the state. During an initial sync it advances monotonically, so `toBlock` vs head IS
+ * progress. Once a project is `live` it only moves when that project has *events* — so a perfectly
+ * current project on a busy chain sits at a tiny fraction of head, and rendering that as "3%" reads
+ * as broken when nothing is wrong. Same reason the reference measures staleness against its watcher's
+ * watermark rather than a project's `toBlock`.
+ */
+export function indexProgress(s) {
+    if (s.status !== 'backfilling')
+        return null;
+    if (!s.headBlock || !s.toBlock)
+        return null;
+    try {
+        const from = BigInt(s.fromBlock);
+        const to = BigInt(s.toBlock);
+        const head = BigInt(s.headBlock);
+        if (head <= from || to < from)
+            return null;
+        const total = head - from;
+        const done = (to > head ? head : to) - from;
+        return { done, total, percent: Number((done * 100n) / total) };
+    }
+    catch {
+        return null;
+    }
+}
+/** A non-2xx control-plane response (or an unreachable service, after retries). `code` is the
+ *  spec's machine code when the service sent one — key behavior off it, never off `message`. */
+export class AbxServiceError extends Error {
+    status;
+    code;
+    url;
+    /** The failure CLASS when the service volunteered one (a credential-free hint about *why* — an
+     *  exhausted RPC reads very differently from a broken service). Optional on the wire. */
+    class;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AbxServiceError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.url = opts.url;
+        this.class = opts.class;
+    }
+}
+/** Waiting for a project to reach a terminal status ran out of time. The registration is durable —
+ *  this is "still working", never "the add failed". */
+export class AbxIndexTimeoutError extends Error {
+    last;
+    constructor(message, last) {
+        super(message);
+        this.name = 'AbxIndexTimeoutError';
+        this.last = last;
+    }
+}
+/**
+ * Retry discipline (shared with the effects runner's read lane): a hosted node can cold-start or
+ * briefly 502, so network errors / 5xx / 429 get 4 attempts with linear backoff — but a genuine
+ * 4xx is an answer, not weather, and throws immediately with the parsed `{error, code}` body.
+ */
+const ATTEMPTS = 4;
+/** The descriptor is a cheap PUBLIC read used to decide whether a URL is even a service — usually
+ *  interactively, often against a typo. Grinding the full ladder there just makes a wrong URL take
+ *  five seconds to say so, so it gets one retry for a blip and no more. */
+const DESCRIPTOR_ATTEMPTS = 2;
+export class AbxServiceClient {
+    baseUrl;
+    token;
+    timeoutMs;
+    retryDelayMs;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.token = opts.token;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.retryDelayMs = opts.retryDelayMs ?? 750;
+    }
+    /** The public service descriptor — no auth, safe to fetch before trusting a provider. */
+    async descriptor() {
+        return (await this.request('GET', WELL_KNOWN_SERVICE_PATH, undefined, { attempts: DESCRIPTOR_ATTEMPTS }));
+    }
+    /**
+     * Register + index a project (the HTTP form of `abx add`; a re-POST is the nudge). Returns the
+     * completed summary (HTTP 200) or the accepted-and-still-working shape (HTTP 202) — narrow with
+     * {@link isAccepted}, and follow a 202 with {@link awaitIndexed}.
+     *
+     * A timed-out register is NOT retried blind. A conforming service persists the registration before
+     * it starts catching up, so a timeout usually means "it's in there, still working" — and re-POSTing
+     * would kick off a *second* full reconstruct against the RPC that was already too slow to answer.
+     * So we ask the status route whether it landed, and if it did we return the async shape instead.
+     */
+    async registerProject(body) {
+        const landed = async () => {
+            const st = await this.projectStatus(body.chainId, body.address).catch(() => null);
+            if (!st)
+                return undefined; // not there (or the service is truly unreachable) — keep retrying
+            return { ok: true, accepted: true, project: { address: body.address, status: st.status } };
+        };
+        const { status, body: out } = await this.requestWithStatus('POST', '/v1/projects', body, { onTimeout: landed });
+        return normalizeRegisterResult(status, out, body.address);
+    }
+    /**
+     * Poll a project's status until it reaches a terminal lifecycle state (`live` or `failed`) — the
+     * one implementation of the wait loop, so the CLI, the effects runner, and any hosted agent all
+     * behave identically against any provider. `stale` keeps polling: it means lagging, not caught up.
+     */
+    async awaitIndexed(chainId, address, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 300_000;
+        const intervalMs = opts.intervalMs ?? 3_000;
+        const deadline = Date.now() + timeoutMs;
+        let last;
+        for (;;) {
+            last = await this.projectStatus(chainId, address);
+            opts.onProgress?.(last);
+            if (TERMINAL_INDEX_STATUSES.includes(last.status))
+                return last;
+            if (Date.now() + intervalMs > deadline) {
+                throw new AbxIndexTimeoutError(`${address} was still '${last.status}' after ${Math.round(timeoutMs / 1000)}s — the registration is durable and the service keeps working; check back with \`abx status ${address} --remote\``, last);
+            }
+            await sleep(intervalMs);
+        }
+    }
+    /** The projects this token may see. */
+    async listProjects() {
+        const out = (await this.request('GET', '/v1/projects'));
+        return out.projects ?? [];
+    }
+    /** Deregister (remote `abx forget`). `not_registered` means "already gone" — reported, not
+     *  thrown — but `disabled` still throws: a node that can't accept removals hasn't removed it. */
+    async removeProject(chainId, address) {
+        try {
+            await this.request('DELETE', `/v1/projects/${chainId}/${address}`);
+            return { removed: true };
+        }
+        catch (err) {
+            if (err instanceof AbxServiceError && err.code === 'not_registered')
+                return { removed: false };
+            throw err;
+        }
+    }
+    /** Nudge a re-index. Answers in the same two shapes as {@link registerProject} — a full replay is
+     *  the *most* likely call to outlive one HTTP request. */
+    async reindexProject(chainId, address) {
+        const { status, body } = await this.requestWithStatus('POST', `/v1/projects/${chainId}/${address}/reindex`, undefined, {
+            onTimeout: async () => {
+                const st = await this.projectStatus(chainId, address).catch(() => null);
+                return st ? { ok: true, accepted: true, project: { address, status: st.status } } : undefined;
+            },
+        });
+        return normalizeRegisterResult(status, body, address);
+    }
+    /** Indexing freshness for one project. */
+    async projectStatus(chainId, address) {
+        return (await this.request('GET', `/v1/projects/${chainId}/${address}/status`));
+    }
+    /** Publish a render output so a resolver that doesn't share the producer's disk can serve it. */
+    async publishEffectArtifact(body) {
+        return (await this.request('POST', '/v1/effect-artifacts', body));
+    }
+    /** Report a run's transient state for the artifact key it is producing. */
+    async reportEffectStatus(body) {
+        await this.request('POST', '/v1/effect-status', body);
+    }
+    async request(method, path, body, opts) {
+        return (await this.requestWithStatus(method, path, body, opts)).body;
+    }
+    async requestWithStatus(method, path, body, opts) {
+        const attempts = opts?.attempts ?? ATTEMPTS;
+        const url = this.baseUrl + path;
+        const headers = {};
+        if (this.token)
+            headers['authorization'] = `Bearer ${this.token}`;
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        let lastFailure = '';
+        let lastStatus = 0;
+        let lastCode;
+        let lastClass;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            let resp;
+            try {
+                resp = await fetch(url, {
+                    method,
+                    headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (err) {
+                lastFailure = err.message;
+                lastStatus = 0;
+                // "We waited the full timeout" and "nothing is listening" are different failures, and for a
+                // mutating POST the difference decides whether retrying is safe: the request may still be
+                // running on the service. Let the caller check before we hammer it again.
+                if (opts?.onTimeout && err.name === 'TimeoutError') {
+                    const resolved = await opts.onTimeout();
+                    if (resolved !== undefined)
+                        return { status: 202, body: resolved };
+                }
+                if (attempt < attempts)
+                    await sleep(linearBackoffDelay(attempt, this.retryDelayMs));
+                continue;
+            }
+            if (resp.ok) {
+                const text = await resp.text();
+                return { status: resp.status, body: text ? JSON.parse(text) : {} };
+            }
+            if (resp.status >= 500 || resp.status === 429) {
+                // Retryable — but KEEP the service's own words. A 5xx body carries the actual cause (an
+                // exhausted RPC, a misconfigured node); discarding it left the caller with a bare status and
+                // nothing to act on, which is the worst kind of error.
+                const said = await bodyMessage(resp);
+                lastStatus = resp.status;
+                lastCode = said.code;
+                lastClass = said.class;
+                lastFailure = said.error ? `${resp.status} ${said.error}` : `${resp.status} ${resp.statusText}`;
+                if (attempt < attempts)
+                    await sleep(linearBackoffDelay(attempt, this.retryDelayMs));
+                continue;
+            }
+            // A genuine 4xx is an answer, not weather — surface the service's own words + code.
+            const detail = await bodyMessage(resp);
+            throw new AbxServiceError(`${method} ${url}: ${resp.status} ${detail.error ?? resp.statusText}`, {
+                status: resp.status,
+                code: detail.code,
+                class: detail.class,
+                url,
+            });
+        }
+        // Retries exhausted. Distinguish "nothing answered" from "it answered, badly" — a 500 is not
+        // unreachable, and saying so sends the caller looking for a network problem that isn't there.
+        const summary = lastStatus
+            ? `service failed after ${attempts} attempt(s) — last response ${lastFailure}`
+            : `nothing responded after ${attempts} attempt(s) (${lastFailure})`;
+        throw new AbxServiceError(`${method} ${url}: ${summary}`, { status: lastStatus, code: lastCode, class: lastClass, url });
+    }
+}
+/** Normalize a register/reindex response: the HTTP status is the authoritative discriminator, and
+ *  the `accepted` flag is derived from it so callers switch on one field even against a service that
+ *  doesn't send it. */
+function normalizeRegisterResult(status, out, fallbackAddress) {
+    if (status === 202) {
+        const r = out;
+        return {
+            ok: r.ok ?? true,
+            accepted: true,
+            project: {
+                address: r.project?.address ?? fallbackAddress,
+                name: r.project?.name ?? null,
+                status: r.project?.status ?? 'backfilling',
+            },
+        };
+    }
+    return { ...out, accepted: false };
+}
+/** The service's own `{error, code, class?}` from a non-2xx body (never throws — a body may be
+ *  empty/HTML). `class` is the optional credential-free failure hint. */
+async function bodyMessage(resp) {
+    try {
+        const parsed = (await resp.json());
+        return {
+            error: parsed.error,
+            code: parsed.code,
+            class: parsed.class,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

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

package/dist/staging.d.ts

@@ -0,0 +1,95 @@
+import type { Address, Hex, PublicClient } from 'viem';
+import { type ChunkStoreEvent, type ContentTxPlan } from './chunks.js';
+import type { SendTx } from './execute.js';
+/**
+ * Content staging — putting a field's bytes on-chain behind the shared multi-chunk store/reader
+ * (`AbxChunkStore`), the SDK-native counterpart of {@link ChunkStoreEvent}'s bootstrap: this module
+ * layers the *content* side (plan → resolve a store → write chunks → encode the `reader` value) on
+ * top of `chunks.ts`'s primitives (`planChunks`/`planContentTxs`/`stageContent`/`ensureChunkStore`)
+ * and `token.ts`'s `encodeReader`, so an integrator gets ONE call instead of hand-wiring all four —
+ * the same reasoning `ensureChunkStore`'s own doc comment gives for the store half.
+ *
+ * `gzip` is deliberately NOT performed here: it's a Node-only transform (`node:zlib`), and this
+ * module is reachable from the browser bundle (browser-bundle.test.ts) like the rest of the SDK
+ * core. Callers that support `compress: 'gzip'` (the CLI) gzip the bytes themselves and hand the
+ * already-compressed result in as `content` — see {@link planStagedContent}.
+ */
+/** How staged content is compressed before chunking. `fastlz` is per-chunk and pure-JS
+ *  ({@link planChunks} does it right here); `gzip` compresses the WHOLE content off-chain (the
+ *  caller's job — see the module doc) and decodes off-chain too, hence the `reader-gzip`
+ *  representation rather than `reader`. */
+export type Compress = 'none' | 'fastlz' | 'gzip';
+export declare const ONCHAIN_IMAGE_SOFT_LIMIT: number;
+export declare const ONCHAIN_PROJECT_SOFT_LIMIT: number;
+/** Whether `bytesLen` is past the point where on-chain storage stops being the cost-sane choice —
+ *  the pure predicate behind the CLI's large-file warning (kept here so the SDK and the CLI can't
+ *  disagree about the threshold). */
+export declare function exceedsOnchainSoftLimit(bytesLen: number): boolean;
+/** The plan for staging one piece of content: how it chunks, how it compresses, and the
+ *  transaction shape ({@link planContentTxs}) that staging it will take. */
+export interface ContentPlan {
+    content: Uint8Array;
+    fastlz: boolean;
+    chunks: number;
+    stagedBytes: number;
+    plan: ContentTxPlan;
+    representation: string;
+}
+/**
+ * Pure staging plan for a piece of content — chunk count + transaction shape — with NO chain
+ * writes, no signer, no `ensureChunkStore`. Shared by {@link stageFieldContent} (which then
+ * actually stages) and a dry-run preview, so the count a human is told up front is the same one
+ * real staging produces. `content` must already be in its final pre-chunking form — gzipped when
+ * `compress === 'gzip'` (see the module doc for why that step isn't here). `chunkSize` defaults to
+ * {@link planChunks}'s default (currently 22 KB), so e.g. a 2.8 KB SVG is 1 chunk.
+ */
+export declare function planStagedContent(content: Uint8Array, compress: Compress): ContentPlan;
+/** Progress from {@link stageFieldContent}, so a caller can narrate without the SDK printing
+ *  anything itself (mirrors {@link ChunkStoreEvent} / `AnchorEvent`'s vocabulary). `chunk-store`
+ *  simply forwards `ensureChunkStore`'s own event — staging always resolves one. */
+export type StagingEvent = {
+    kind: 'chunk-store';
+    event: ChunkStoreEvent;
+} | {
+    kind: 'planned';
+    field: string;
+    store: Address;
+    contentPlan: ContentPlan;
+} | {
+    kind: 'staged';
+    field: string;
+    manifest: Address;
+    txHashes: Hex[];
+};
+export interface StageFieldContentArgs {
+    /** Content bytes, already in their final pre-chunking form (gzipped by the caller when
+     *  `compress === 'gzip'` — see the module doc). */
+    content: Uint8Array;
+    compress: Compress;
+    /** The metadata field this content is destined for — narration only (e.g. `'image'`). */
+    field: string;
+    send: SendTx;
+    publicClient: PublicClient;
+    chainId: number;
+    /** Pre-resolved store (batch staging reuses one across files); else resolve/deploy via
+     *  {@link ensureChunkStore}. */
+    store?: Address;
+    onEvent?: (e: StagingEvent) => void;
+}
+/**
+ * Put `content` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
+ * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
+ * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
+ * `reader-gzip` representation, not on-chain renderable).
+ *
+ * Staging is one atomic `writeContent` (content fits a single tx's gas) or gas-bounded chunk-write
+ * `multicall`s plus a final manifest write — {@link stageContent} picks. These store writes use
+ * `send` (typically the env key on the hot lane, or the connected wallet on the wallet lane) — the
+ * data contracts are ownerless, so any funded signer may write them; the caller signs the field-set
+ * that references the manifest separately.
+ */
+export declare function stageFieldContent(args: StageFieldContentArgs): Promise<{
+    value: Hex;
+    representation: string;
+}>;
+//# sourceMappingURL=staging.d.ts.map

package/dist/staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../src/staging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,OAAO,EAAE,GAAG,EAAE,YAAY,EAAC,MAAM,MAAM,CAAC;AACrD,OAAO,EAA6D,KAAK,eAAe,EAAE,KAAK,aAAa,EAAC,MAAM,aAAa,CAAC;AAGjI,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;GAYG;AAEH;;;2CAG2C;AAC3C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAMlD,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAClD,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;qCAEqC;AACrC,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;4EAC4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAOtF;AAED;;oFAEoF;AACpF,MAAM,MAAM,YAAY,GACpB;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAC,GAC7C;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAC,GAC1E;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,GAAG,EAAE,CAAA;CAAC,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC;uDACmD;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB;oCACgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAC,CAAC,CAalH"}

package/dist/staging.js

@@ -0,0 +1,57 @@
+import { ensureChunkStore, planChunks, planContentTxs, stageContent } from './chunks.js';
+import { encodeReader } from './token.js';
+import { METADATA_REPRESENTATION as R } from './spine.js';
+// On-chain image storage costs ~200 gas/byte (SSTORE2 code deposit) + per-chunk tx overhead, so it
+// is cost-effective ONLY for tiny art. Past these soft limits, off-chain (Arweave pay-once, or a
+// hosted resolver + IPFS) is FAR cheaper — on-chain's remaining edge is self-resolution, not cost.
+// Per-file limit ≈ one 22 KB storage chunk; project limit caps the whole collection's gas.
+export const ONCHAIN_IMAGE_SOFT_LIMIT = 24 * 1024; // per file
+export const ONCHAIN_PROJECT_SOFT_LIMIT = 256 * 1024; // whole collection
+/** Whether `bytesLen` is past the point where on-chain storage stops being the cost-sane choice —
+ *  the pure predicate behind the CLI's large-file warning (kept here so the SDK and the CLI can't
+ *  disagree about the threshold). */
+export function exceedsOnchainSoftLimit(bytesLen) {
+    return bytesLen > ONCHAIN_IMAGE_SOFT_LIMIT;
+}
+/**
+ * Pure staging plan for a piece of content — chunk count + transaction shape — with NO chain
+ * writes, no signer, no `ensureChunkStore`. Shared by {@link stageFieldContent} (which then
+ * actually stages) and a dry-run preview, so the count a human is told up front is the same one
+ * real staging produces. `content` must already be in its final pre-chunking form — gzipped when
+ * `compress === 'gzip'` (see the module doc for why that step isn't here). `chunkSize` defaults to
+ * {@link planChunks}'s default (currently 22 KB), so e.g. a 2.8 KB SVG is 1 chunk.
+ */
+export function planStagedContent(content, compress) {
+    const fastlz = compress === 'fastlz';
+    const planned = planChunks(content, { fastlz });
+    const plan = planContentTxs(planned);
+    const representation = compress === 'gzip' ? R.readerGzip : R.reader;
+    const stagedBytes = planned.reduce((n, c) => n + c.data.length, 0);
+    return { content, fastlz, chunks: planned.length, stagedBytes, plan, representation };
+}
+/**
+ * Put `content` on-chain as SSTORE2 chunks behind the shared reader, and return the field's
+ * `(representation, value)`. `fastlz` compresses per chunk (reader decodes on read → stays
+ * on-chain renderable); `gzip` compresses the whole content (off-chain decode → the
+ * `reader-gzip` representation, not on-chain renderable).
+ *
+ * Staging is one atomic `writeContent` (content fits a single tx's gas) or gas-bounded chunk-write
+ * `multicall`s plus a final manifest write — {@link stageContent} picks. These store writes use
+ * `send` (typically the env key on the hot lane, or the connected wallet on the wallet lane) — the
+ * data contracts are ownerless, so any funded signer may write them; the caller signs the field-set
+ * that references the manifest separately.
+ */
+export async function stageFieldContent(args) {
+    const notify = args.onEvent ?? (() => { });
+    const p = planStagedContent(args.content, args.compress);
+    const resolvedStore = args.store ??
+        (await ensureChunkStore(args.publicClient, args.send, {
+            chainId: args.chainId,
+            onEvent: (e) => notify({ kind: 'chunk-store', event: e }),
+        }));
+    notify({ kind: 'planned', field: args.field, store: resolvedStore, contentPlan: p });
+    const { manifest, txHashes } = await stageContent(args.send, { store: resolvedStore, content: p.content, fastlz: p.fastlz, chainId: args.chainId });
+    notify({ kind: 'staged', field: args.field, manifest, txHashes });
+    return { value: encodeReader(resolvedStore, manifest), representation: p.representation };
+}
+//# sourceMappingURL=staging.js.map

package/dist/staging.js.map

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

package/dist/tokendata.d.ts

@@ -1,5 +1,24 @@
-import { type Hex, type PublicClient } from 'viem';
-import type { MetadataField, ProjectState, TokenState } from './types.js';
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { MetadataField, ParamSchema, ParamValue, ProjectState, TokenState } from './types.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).
+ */
+/** The tokenData coordinates — never enumerable as params (the on-chain params store excludes
+ *  `seed` from its key lists, and the generator/renderer skip the other three defensively).
+ *  Exported because every off-chain surface that enumerates params must exclude exactly this
+ *  set: two lists that have to agree are one list. */
+export declare const RESERVED_TOKEN_DATA_KEYS: ReadonlySet<string>;
 export interface TokenDataResult {
     /** The flat object (values are canonical strings; `chainId` is a number). */
     data: Record<string, string | number>;
@@ -47,4 +66,45 @@ export declare function contentDigestOf(state: ProjectState): Hex | null;
  * 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;
+/**
+ * The **bound** effect outputs — `specs/protocol/effects.md → Bound vs referenced`. An output is
+ * bound iff a binding stitches its *content* into the metadata JSON, which is what decides who holds
+ * its bytes:
+ *
+ *  - **bound** (`render/traits` → `attributes`): the serving node holds the content, capped at
+ *    {@link BOUND_ARTIFACT_MAX_BYTES} and servable only at the current settled `inputsHash`. A
+ *    locator here cannot work — the content is assembled into `tokenURI`, so a locator would put a
+ *    third-party fetch on the hottest read the resolver serves.
+ *  - **referenced** (everything else — `render/image` projects a *URL*, a `video`/`model` only
+ *    appears in the manifest): the PRODUCER holds the bytes and the node stores a locator. Holding
+ *    these bytes buys a node no capability (it redirects either way) and costs it an object store.
+ *
+ * This is the wire rule for `POST /v1/effect-artifacts` in both directions: bytes for a referenced
+ * output and a locator for a bound one are each a `400`. Growing this set is an interface change —
+ * every serving node must be able to stitch a bound output's content.
+ */
+export declare const BOUND_EFFECT_OUTPUTS: ReadonlySet<string>;
+/** The cap a serving node MUST accept per bound output and MUST refuse above (~100× a real traits
+ *  payload — generous for JSON, far too small to become blob storage). */
+export declare const BOUND_ARTIFACT_MAX_BYTES: number;
+/** Is `{effectKey}/{outputKey}` a bound output — content the serving node must hold and stitch?
+ *  Unknown effects answer `false`: an output a node can't stitch is referenced by definition, since
+ *  bytes it can't stitch are bytes it could only redirect to. */
+export declare function isBoundOutput(effectKey: string, outputKey: string): boolean;
+/** One param's canonical decode, with the blob's SIZE alongside. */
+export interface DecodedParam {
+    /** The canonical string — what tokenData carries for this key. */
+    value: string;
+    /** A data-backed param's full content length in bytes; `null` for a literal, and for a blob
+     *  that didn't read (the value degraded to the hash). Callers that bound inline content —
+     *  the off-chain resolver's `abx_params`, mirroring the on-chain renderer's inline ceiling —
+     *  measure THIS, the same length the chain measures. */
+    contentBytes: number | null;
+}
+/**
+ * The canonical per-param decode — the one implementation every off-chain surface shares
+ * (tokenData assembly here, `abx_params` in the resolver), so a value reads the same
+ * everywhere and stays byte-parallel with the on-chain generator and renderer.
+ */
+export declare function decodeParam(client: PublicClient | null, token: Address, tokenId: string, p: ParamValue, tokenScope: boolean, schema: ParamSchema | undefined): Promise<DecodedParam>;
 //# sourceMappingURL=tokendata.d.ts.map

package/dist/tokendata.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"tokendata.d.ts","sourceRoot":"","sources":["../src/tokendata.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,OAAO,EACZ,KAAK,GAAG,EACR,KAAK,YAAY,EAClB,MAAM,MAAM,CAAC;AAGd,OAAO,KAAK,EAAC,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAC,MAAM,YAAY,CAAC;AAGjG;;;;;;;;;;;;;GAaG;AAEH;;;sDAGsD;AACtD,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAKvD,CAAC;AAMH,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;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAEpF;0EAC0E;AAC1E,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAElD;;iEAEiE;AACjE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3E;AAID,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd;;;4DAGwD;IACxD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,CAAC,EAAE,UAAU,EACb,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,YAAY,CAAC,CA4BvB"}