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

package/dist/types.d.ts

@@ -33,11 +33,18 @@ export interface ParamSchema {
     max: Hex;
     selectOptions: string[];
 }
-/** The three param lifecycle hooks (any may be null = none). */
+/** The three param lifecycle hooks (any may be null = none), plus whether the set is frozen. */
 export interface ParamHooks {
     configureHook: Address | null;
     augmentHook: Address | null;
+    /** Ownership-change lifecycle — a **VETO**: its revert fails the transfer, and a mint is a
+     *  transfer from `0x0`, so a reverting hook also stops minting. Read `locked` next to it. */
     transferHook: Address | null;
+    /** `lockParamHooks()` was sent: the three addresses above can never change again. The read that
+     *  turns "the hooks are whatever the owner currently says" into something a buyer can verify —
+     *  it matters most for `transferHook`, an unlocked one being a standing power over a collector's
+     *  ability to sell. Folded from `ParamHooksFrozen`. */
+    locked: boolean;
 }
 /** One declared code dependency (Dependencies extension); index 0 = the runtime. */
 export interface DependencyInfo {
@@ -71,13 +78,54 @@ 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).
+     */
     minted: boolean;
+    /** 721 only — the current holder. Always `null` for an edition (an id can have many
+     *  concurrent holders; see {@link holders}). */
     owner: Address | null;
     tokenURI: string | null;
     fields: MetadataField[];
     lockedFields: string[];
     /** Token-scope params (Params extension) — `seed`, PostParam values, … Absent/empty ⇒ none. */
     params?: ParamValue[];
+    /** ERC-1155 editions only — total live copies of this id (minted − burned), folded from
+     *  `TransferSingle`/`TransferBatch`. Absent for a 721 token. */
+    supply?: string;
+    /**
+     * ERC-1155 editions only — this id's **effective** supply cap: its own override when one exists,
+     * otherwise the collection default ({@link ProjectState.defaultMaxSupply}). Absent for a 721
+     * token. Equals the on-chain `maxSupply(id)` view, and therefore its head-read twin
+     * (`TokenRow.maxSupply` in `tokens.ts`) — one field name, one meaning, whichever lane produced it.
+     *
+     * It used to fold `MaxSupplyUpdated` alone, which made the two lanes disagree on the DEFAULT
+     * shape: `--copies 10` sets the cap at `initialize` and never calls `setMaxSupply`, so no id had
+     * an event of its own and this read *absent* — "open, uncapped" — for every capped edition ever
+     * deployed. The head read said `10`. That is the sibling-drift class, on the field that decides
+     * whether a buy button renders.
+     *
+     * `'0'` carries the on-chain overload deliberately: **open** when {@link maxSupplyOverridden} is
+     * false, **closed forever** when it is true.
+     */
+    maxSupply?: string;
+    /** ERC-1155 editions only — has this id ever been explicitly overridden (`setMaxSupply`)? The
+     *  distinction the on-chain getter cannot make and the log can, now that `DefaultMaxSupplySet`
+     *  completes the log: it disambiguates a `'0'` cap (open vs deliberately closed) and tells you
+     *  whether the monotonic never-increase rule is already in force for this id. Absent ⇒ false. */
+    maxSupplyOverridden?: boolean;
+    /** ERC-1155 editions only — current balances by holder address, folded from
+     *  `TransferSingle`/`TransferBatch`. Zero balances are deleted, so a key's presence IS "holds
+     *  at least one copy." Omitted/empty when unknown (a 721 token, or an edition with no folded
+     *  history). Not chain-enumerable outside the event log — this is why {@link owner} can't
+     *  simply generalize to "the current holders": a chain-only head read (no event scan) has no
+     *  way to list them (see `tokens.ts`'s `listTokens`, which is exactly that head-read-only path
+     *  and therefore never populates this field). */
+    holders?: Record<Address, string>;
 }
 /**
  * The full reconstructed state of an ABX project — rebuilt from the event log
@@ -108,10 +156,19 @@ export interface ProjectState {
     contractURILocked: boolean | null;
     collectionFields: MetadataField[];
     lockedCollectionFields: string[];
-    /** Which concrete token type this is, inferred from the enabled extensions. */
-    contractType?: '1of1' | 'series' | 'code';
+    /** Which concrete token type this is, inferred from the enabled extensions. The `-edition`
+     *  suffix is the ERC-1155 family (detected via the Edition Supply extension), a parallel
+     *  ladder to the ERC-721 one: `1of1-edition` ↔ `1of1`, `edition` ↔ `series`,
+     *  `edition-code` ↔ `code`. */
+    contractType?: '1of1' | 'series' | 'code' | '1of1-edition' | 'edition' | 'edition-code';
     /** Supply cap "X of Y" (Max Invocations extension); null/absent ⇒ uncapped 1/1. */
     maxInvocations?: string | null;
+    /** ERC-1155 editions only — the collection-wide DEFAULT per-id cap (`editionSize` at
+     *  `initialize`), folded from `DefaultMaxSupplySet`. `'0'` ⇒ open by default; null ⇒ not an
+     *  edition. The 1155 analogue of {@link maxInvocations}: it is the project-level ceiling, while
+     *  {@link TokenState.maxSupply} is a single id's. Every id that has never been overridden carries
+     *  this, which is why the event exists — see `IAbxEditionSupply`. */
+    defaultMaxSupply?: string | null;
     /** The single authorized minter (External Minter extension); null ⇒ owner-only. */
     minter?: Address | null;
     /** Whether minting is paused (Paused extension) — true ⇒ owner-only. Absent/false ⇒ open. */

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":"AAAA,OAAO,KAAK,EAAC,OAAO,EAAE,GAAG,EAAC,MAAM,MAAM,CAAC;AAEvC,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,GAAG,CAAC;IACR,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,GAAG,CAAC;CACZ;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,GAAG,CAAC;IACX,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B;iGAC6F;IAC7F,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B;;;2DAGuD;IACvD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,GAAG,EAAE,GAAG,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB;+EAC2E;IAC3E,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,GAAG,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;oDACgD;IAChD,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB;oEACgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;qGAGiG;IACjG,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;qDAMiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAGhB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAG5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAC;IAKjD,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,mBAAmB,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAGlC,gBAAgB,EAAE,aAAa,EAAE,CAAC;IAClC,sBAAsB,EAAE,MAAM,EAAE,CAAC;IAGjC;;;mCAG+B;IAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,cAAc,CAAC;IACxF,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;yEAIqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAG9B,gDAAgD;IAChD,cAAc,CAAC,EAAE,UAAU,EAAE,CAAC;IAC9B,uFAAuF;IACvF,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B,iFAAiF;IACjF,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B;8FAC0F;IAC1F,gBAAgB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,oFAAoF;IACpF,YAAY,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAExC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IAGrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/util.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Small, environment-neutral helpers shared across the SDK core. Nothing here imports
+ * `node:*` or references a Node-only global (`Buffer`, `process` unguarded) — this module
+ * is reachable from the browser bundle (see `test/browser-bundle.test.ts`), so it has to
+ * run identically wherever a caller (Node, a bundler, a browser tab) loads it.
+ */
+import type { Address, PublicClient } from 'viem';
+/** `process.env[name]`, or `undefined` — safe to call even where `process` doesn't exist
+ *  (a browser bundle). The SDK core never assumes Node; a host (the CLI, the effects
+ *  runner) is where `process.env` is actually meaningful. */
+export declare function readEnv(name: string): string | undefined;
+/** Wait `ms` milliseconds. The one place the SDK debounces/retries, so every caller shares
+ *  the same primitive instead of re-declaring `new Promise((r) => setTimeout(r, ms))`. */
+export declare function sleep(ms: number): Promise<void>;
+/** The delay before retry `attempt` (1-indexed) under a LINEAR backoff: `attempt * baseMs`.
+ *  Matches the shape `service.ts`'s request ladder already used (`retryDelayMs * attempt`) —
+ *  pulled out here so every linear-backoff retry loop (the service client, the effects
+ *  runner's resolver poll) computes the same delay the same way. */
+export declare function linearBackoffDelay(attempt: number, baseMs: number): number;
+/**
+ * The delay before retry `attempt` (1-indexed) under an EXPONENTIAL backoff, capped:
+ * `min(baseMs * 2^(attempt-1), capMs)`. Attempt 1 waits `baseMs`, attempt 2 waits `2*baseMs`,
+ * attempt 3 `4*baseMs`, and so on until the cap takes over.
+ *
+ * Prefer this over {@link linearBackoffDelay} for a SUSTAINED rate limit or an overloaded
+ * upstream, where a caller wants each retry to back off faster than the last so a burst of
+ * callers doesn't keep landing on the same wall-clock second (linear backoff's delays grow by a
+ * constant step, which under sustained pressure just re-synchronizes the retry storm at a lower
+ * frequency instead of spreading it out). Prefer `linearBackoffDelay` for a transient/one-off
+ * failure (a dropped connection, a single flaky read) where the retry ladder just needs to not
+ * hammer immediately — exponential growth there overshoots into multi-minute waits for what was
+ * likely a one-time blip.
+ */
+export declare function exponentialBackoffDelay(attempt: number, baseMs: number, capMs: number): number;
+/**
+ * A parsed `data:` URI (RFC 2397) — the most permissive of the three ad hoc parses this
+ * replaces (a bare `data:,...`, a `;base64` flag anywhere in the parameter list, and an
+ * arbitrary `;charset=...` alongside it). `mime` is empty-string-normalized to `text/plain`
+ * (RFC 2397's own default); `body` is returned VERBATIM — still percent-encoded for a
+ * non-base64 URI, still base64 text for one that is — so the caller decodes it exactly the
+ * way it always did (`decodeURIComponent` vs a base64 decode).
+ */
+export interface ParsedDataUri {
+    mime: string;
+    base64: boolean;
+    body: string;
+}
+/** Parse a `data:` URI, or `null` if `uri` isn't one. */
+export declare function parseDataUri(uri: string): ParsedDataUri | null;
+/**
+ * Read a contract, swallowing any failure ("no data" from a codeless address, a revert on
+ * an extension the target doesn't compose) into `undefined` rather than a throw — the shape
+ * every "does this getter exist / is there even a contract here" caller wants. Replaces the
+ * three near-identical try/catch wrappers this SDK's callers each hand-rolled (a resume
+ * planner's field-by-field read, a state dump's per-getter read, an owner-op's diagnostic
+ * read) with one implementation.
+ *
+ * A caller that wants to DISTINGUISH "no contract at all" from "contract exists but this
+ * call reverted" (the CLI's `assertContractExists` diagnostic) still does that itself — this
+ * helper only knows "did the read come back", not why it didn't.
+ */
+export declare function tryReadContract<T>(client: PublicClient, args: {
+    address: Address;
+    abi: readonly unknown[];
+    functionName: string;
+    args?: readonly unknown[];
+}): Promise<T | undefined>;
+/** Bytes → base64 (RFC 4648). No `Buffer`, no `btoa` — both are runtime-conditional (Node
+ *  lacks the latter, and a stricter embedder than a browser can lack the former too), and the
+ *  SDK core needs exactly one behavior everywhere it runs. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** base64 → bytes — the inverse of {@link bytesToBase64}. */
+export declare function base64ToBytes(b64: string): Uint8Array;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,OAAO,EAAE,YAAY,EAAC,MAAM,MAAM,CAAC;AAEhD;;6DAE6D;AAC7D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGxD;AAED;0FAC0F;AAC1F,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;oEAGoE;AACpE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAID,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAS9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAAC,GACjG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAMxB;AAID;;8DAE8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYvD;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAcrD"}

package/dist/util.js

@@ -0,0 +1,106 @@
+/** `process.env[name]`, or `undefined` — safe to call even where `process` doesn't exist
+ *  (a browser bundle). The SDK core never assumes Node; a host (the CLI, the effects
+ *  runner) is where `process.env` is actually meaningful. */
+export function readEnv(name) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    return process.env[name];
+}
+/** Wait `ms` milliseconds. The one place the SDK debounces/retries, so every caller shares
+ *  the same primitive instead of re-declaring `new Promise((r) => setTimeout(r, ms))`. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** The delay before retry `attempt` (1-indexed) under a LINEAR backoff: `attempt * baseMs`.
+ *  Matches the shape `service.ts`'s request ladder already used (`retryDelayMs * attempt`) —
+ *  pulled out here so every linear-backoff retry loop (the service client, the effects
+ *  runner's resolver poll) computes the same delay the same way. */
+export function linearBackoffDelay(attempt, baseMs) {
+    return attempt * baseMs;
+}
+/**
+ * The delay before retry `attempt` (1-indexed) under an EXPONENTIAL backoff, capped:
+ * `min(baseMs * 2^(attempt-1), capMs)`. Attempt 1 waits `baseMs`, attempt 2 waits `2*baseMs`,
+ * attempt 3 `4*baseMs`, and so on until the cap takes over.
+ *
+ * Prefer this over {@link linearBackoffDelay} for a SUSTAINED rate limit or an overloaded
+ * upstream, where a caller wants each retry to back off faster than the last so a burst of
+ * callers doesn't keep landing on the same wall-clock second (linear backoff's delays grow by a
+ * constant step, which under sustained pressure just re-synchronizes the retry storm at a lower
+ * frequency instead of spreading it out). Prefer `linearBackoffDelay` for a transient/one-off
+ * failure (a dropped connection, a single flaky read) where the retry ladder just needs to not
+ * hammer immediately — exponential growth there overshoots into multi-minute waits for what was
+ * likely a one-time blip.
+ */
+export function exponentialBackoffDelay(attempt, baseMs, capMs) {
+    return Math.min(baseMs * 2 ** (attempt - 1), capMs);
+}
+const DATA_URI_RE = /^data:([^;,]*)((?:;[^,]*)?),([\s\S]*)$/;
+/** Parse a `data:` URI, or `null` if `uri` isn't one. */
+export function parseDataUri(uri) {
+    const m = DATA_URI_RE.exec(uri);
+    if (!m)
+        return null;
+    const params = m[2] ?? '';
+    return {
+        mime: m[1] || 'text/plain',
+        base64: /(^|;)base64(;|$)/.test(params),
+        body: m[3],
+    };
+}
+/**
+ * Read a contract, swallowing any failure ("no data" from a codeless address, a revert on
+ * an extension the target doesn't compose) into `undefined` rather than a throw — the shape
+ * every "does this getter exist / is there even a contract here" caller wants. Replaces the
+ * three near-identical try/catch wrappers this SDK's callers each hand-rolled (a resume
+ * planner's field-by-field read, a state dump's per-getter read, an owner-op's diagnostic
+ * read) with one implementation.
+ *
+ * A caller that wants to DISTINGUISH "no contract at all" from "contract exists but this
+ * call reverted" (the CLI's `assertContractExists` diagnostic) still does that itself — this
+ * helper only knows "did the read come back", not why it didn't.
+ */
+export async function tryReadContract(client, args) {
+    try {
+        return (await client.readContract(args));
+    }
+    catch {
+        return undefined;
+    }
+}
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Bytes → base64 (RFC 4648). No `Buffer`, no `btoa` — both are runtime-conditional (Node
+ *  lacks the latter, and a stricter embedder than a browser can lack the former too), and the
+ *  SDK core needs exactly one behavior everywhere it runs. */
+export function bytesToBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = bytes[i + 1];
+        const b2 = bytes[i + 2];
+        out += BASE64_CHARS[b0 >> 2];
+        out += BASE64_CHARS[((b0 & 0x03) << 4) | (b1 === undefined ? 0 : b1 >> 4)];
+        out += b1 === undefined ? '=' : BASE64_CHARS[((b1 & 0x0f) << 2) | (b2 === undefined ? 0 : b2 >> 6)];
+        out += b2 === undefined ? '=' : BASE64_CHARS[b2 & 0x3f];
+    }
+    return out;
+}
+/** base64 → bytes — the inverse of {@link bytesToBase64}. */
+export function base64ToBytes(b64) {
+    const clean = b64.replace(/=+$/, '');
+    const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let p = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const c0 = BASE64_CHARS.indexOf(clean[i]);
+        const c1 = BASE64_CHARS.indexOf(clean[i + 1]);
+        const c2 = clean[i + 2] === undefined ? -1 : BASE64_CHARS.indexOf(clean[i + 2]);
+        const c3 = clean[i + 3] === undefined ? -1 : BASE64_CHARS.indexOf(clean[i + 3]);
+        out[p++] = (c0 << 2) | (c1 >> 4);
+        if (c2 >= 0)
+            out[p++] = ((c1 & 0x0f) << 4) | (c2 >> 2);
+        if (c3 >= 0)
+            out[p++] = ((c2 & 0x03) << 6) | c3;
+    }
+    return out;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artblocks/abx-sdk",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "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",
@@ -13,7 +13,12 @@
     "./abi": {
       "types": "./dist/abi/index.d.ts",
       "import": "./dist/abi/index.js"
-    }
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -45,6 +50,9 @@
   "dependencies": {
     "viem": "^2.21.0"
   },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",
     "sync-abis": "tsx scripts/sync-abis.ts"