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

package/dist/execute.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Gas limits for a sequenced transaction — decided HERE, once, rather than re-read at signing time.
+ *
+ * The failure this exists to prevent, in full, because it is not obvious and it cost a reporter every
+ * `deploy-code` attempt of a session: a project deploys in two transactions, and the second targets
+ * the contract the first just created. If the node answering `eth_estimateGas` has not yet seen the
+ * deploy block, the target looks like an account with no code — and an estimate for a call to a
+ * codeless account is just the calldata cost, around 200k. That number is then sent as the gas limit.
+ * Once the contract does exist the same call needs ~941k, because storing a program on-chain is
+ * dominated by CREATE code deposit at ~200 gas per byte. The CREATE receives 63/64 of a budget that
+ * cannot cover the deposit, returns 0, and Solady's `SSTORE2.write` reverts `DeploymentFailed()` — a
+ * revert that reads like a contract bug and is really an out-of-gas.
+ *
+ * (Measured, from the real transactions: `gasLimit 201,616 / gasUsed 198,870` and
+ * `gasLimit 169,301 / gasUsed 166,810` — 98.6% and 98.5% of their limits. Replaying those payloads
+ * against a codeless address reproduces both limits to the gas; against the real contract the same
+ * calls estimate at 941,331.)
+ *
+ * The deploy loop already pinned the *nonce* against exactly this read-after-write lag on a
+ * distributed RPC. The rule generalizes, and it is the reason this module exists: **anything read at
+ * send time on a distributed RPC needs pinning, not just the nonce.**
+ */
+import type { Account, Address, Hex, PublicClient, TransactionReceipt, WalletClient } from 'viem';
+import type { PreparedTx } from './ops.js';
+/**
+ * Wait until `address` has code from THIS client's point of view. A deploy receipt proves the
+ * contract exists on chain; it does not prove the node answering the next request has caught up.
+ * Bounded — on timeout we proceed and let the gas floor carry it, since a slow RPC is not a reason
+ * to refuse to continue a deploy that already spent money.
+ */
+export declare function waitForCodeAt(client: PublicClient, address: Address, timeoutMs?: number): Promise<boolean>;
+/**
+ * Decide a transaction's gas limit once, here.
+ *
+ * The important design point, because the obvious approach is wrong: when an estimate looks too low
+ * we do **not** substitute a computed number. A caller can only compute the *provable* part of a
+ * payload's cost (see `PreparedTx.gasFloor` — code deposit is 200 gas/byte and nothing else is
+ * physics); the same setup multicall also carries schema writes, dependency legs, URI legs and
+ * mints, whose cost we cannot derive without simulating them. A "probably enough" constant is a
+ * number tuned to whatever case was in front of its author: it papers over the symptom, then
+ * under-funds the next payload that carries a few more legs, producing the identical
+ * `DeploymentFailed()` with a fresh mystery attached.
+ *
+ * So the floor is used as a **detector**. An estimate below a provable minimum is not "low", it is
+ * *impossible* — proof that the node answering us is looking at the wrong state (typically it has
+ * not seen the deploy block yet, so the target reads as an account with no code and the estimate
+ * comes back as the calldata cost alone). The right response to a broken measurement is to take it
+ * again, and if it stays broken, to refuse — sending a transaction we can prove is under-funded
+ * would burn the gas AND orphan the contract.
+ *
+ * When the estimate IS plausible it is trusted, plus headroom for state drift between estimate and
+ * inclusion.
+ */
+export declare function pinGas(client: PublicClient, tx: {
+    from: Address;
+    to: Address | null;
+    data: Hex;
+    value?: Hex;
+    gasFloor?: Hex;
+}, opts?: {
+    attempts?: number;
+    delayMs?: number;
+}): Promise<bigint>;
+/** Sign + broadcast one {@link PreparedTx} and return its mined receipt (for event parsing). The
+ *  SDK's one send-injection point: a hot key ({@link makeHotSender}), a browser wallet (a
+ *  `WalletSession`), or anything else a caller wires up — the SDK never picks or performs the
+ *  signing itself. */
+export type SendTx = (tx: PreparedTx) => Promise<TransactionReceipt>;
+/** Progress from a {@link SendTx} built by {@link makeHotSender}, so a caller can narrate without
+ *  the SDK printing anything itself (the SDK never prints — see clients.ts / chunks.ts for the same
+ *  `onEvent` pattern). */
+export type SendEvent = {
+    kind: 'sending';
+    tx: PreparedTx;
+} | {
+    kind: 'mined';
+    receipt: TransactionReceipt;
+    tx: PreparedTx;
+};
+/**
+ * Build a {@link SendTx} that signs with an env-style hot key and broadcasts — the generalization of
+ * what used to be hand-rolled per call site (a deploy-then-setup loop in the CLI, the hot lane in
+ * `signer.ts`, the chunk-staging sender in `ownerops.ts`): one function that gets the read-after-
+ * write-lag handling right ONCE.
+ *
+ * Two lags, pinned once at construction / tracked locally per send, rather than re-read at send time:
+ *   - the NONCE — fetched once here, then incremented locally per tx. Right after a tx is mined a
+ *     distributed RPC (e.g. Alchemy) can briefly serve a stale `pending` transaction count
+ *     (read-after-write lag), so re-fetching it for the NEXT send in the same sequence risks reusing
+ *     the just-spent nonce — the tx it already has in the mempool rejects the duplicate as
+ *     "replacement transaction underpriced", and that send is silently lost.
+ *   - GAS, one field over: a tx after the first in a sequence may target a contract an EARLIER tx in
+ *     this same sequence just created. If the node answering `eth_estimateGas` hasn't seen that
+ *     block yet, the target looks codeless and the estimate comes back as the calldata cost alone —
+ *     see `pinGas` above for the full story (and the measured numbers). So every send after the
+ *     first waits for its target's code to be visible before estimating.
+ *
+ * Every send: wait for code at the target when it's not the first send in this sender's sequence
+ * (mirrors the exact rule the deploy-code hot lane hand-rolled: every tx after the first, since the
+ * first is what creates what the rest target), pin the gas (a provable floor detector, never a
+ * substitute limit), broadcast, wait for the receipt, and throw a typed {@link TxRevertedError} —
+ * carrying the tx hash — on a `reverted` status rather than reporting a burned transaction as
+ * "confirmed".
+ */
+export declare function makeHotSender(args: {
+    wallet: WalletClient;
+    account: Account;
+    publicClient: PublicClient;
+    onEvent?: (e: SendEvent) => void;
+}): SendTx;
+/** Send a list of prepared txs, in order, via `send`; returns their receipts in the same order.
+ *  A small convenience for the common "just run this sequence" case — narration (if any) rides
+ *  `send`'s own `onEvent`, not a callback here. */
+export declare function runPrepared(txs: PreparedTx[], send: SendTx): Promise<TransactionReceipt[]>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAC,MAAM,MAAM,CAAC;AAChG,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,UAAU,CAAC;AAGzC;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQhH;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAA;CAAC,EAC/E,IAAI,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAM,GAC/C,OAAO,CAAC,MAAM,CAAC,CA8BjB;AAED;;;sBAGsB;AACtB,MAAM,MAAM,MAAM,GAAG,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAErE;;0BAE0B;AAC1B,MAAM,MAAM,SAAS,GACjB;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAC,GACjC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,EAAE,EAAE,UAAU,CAAA;CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;CAClC,GAAG,MAAM,CAkCT;AAED;;mDAEmD;AACnD,wBAAsB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAIhG"}

package/dist/execute.js

@@ -0,0 +1,142 @@
+import { GasEstimateBelowFloorError, TxRevertedError } from './errors.js';
+/**
+ * Wait until `address` has code from THIS client's point of view. A deploy receipt proves the
+ * contract exists on chain; it does not prove the node answering the next request has caught up.
+ * Bounded — on timeout we proceed and let the gas floor carry it, since a slow RPC is not a reason
+ * to refuse to continue a deploy that already spent money.
+ */
+export async function waitForCodeAt(client, address, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const code = await client.getCode({ address }).catch(() => undefined);
+        if (code && code !== '0x')
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 750));
+    }
+}
+/**
+ * Decide a transaction's gas limit once, here.
+ *
+ * The important design point, because the obvious approach is wrong: when an estimate looks too low
+ * we do **not** substitute a computed number. A caller can only compute the *provable* part of a
+ * payload's cost (see `PreparedTx.gasFloor` — code deposit is 200 gas/byte and nothing else is
+ * physics); the same setup multicall also carries schema writes, dependency legs, URI legs and
+ * mints, whose cost we cannot derive without simulating them. A "probably enough" constant is a
+ * number tuned to whatever case was in front of its author: it papers over the symptom, then
+ * under-funds the next payload that carries a few more legs, producing the identical
+ * `DeploymentFailed()` with a fresh mystery attached.
+ *
+ * So the floor is used as a **detector**. An estimate below a provable minimum is not "low", it is
+ * *impossible* — proof that the node answering us is looking at the wrong state (typically it has
+ * not seen the deploy block yet, so the target reads as an account with no code and the estimate
+ * comes back as the calldata cost alone). The right response to a broken measurement is to take it
+ * again, and if it stays broken, to refuse — sending a transaction we can prove is under-funded
+ * would burn the gas AND orphan the contract.
+ *
+ * When the estimate IS plausible it is trusted, plus headroom for state drift between estimate and
+ * inclusion.
+ */
+export async function pinGas(client, tx, opts = {}) {
+    const floor = tx.gasFloor ? BigInt(tx.gasFloor) : 0n;
+    const attempts = opts.attempts ?? 3;
+    let lastEstimate = null;
+    let lastError;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            const estimate = await client.estimateGas({
+                account: tx.from,
+                to: tx.to ?? undefined,
+                data: tx.data,
+                ...(tx.value && tx.value !== '0x0' ? { value: BigInt(tx.value) } : {}),
+            });
+            // Plausible (or nothing provable to check it against) → trust it.
+            if (estimate >= floor)
+                return (estimate * 125n) / 100n;
+            lastEstimate = estimate;
+        }
+        catch (err) {
+            lastError = err;
+            // A revert during estimation is a real answer about the transaction, not a lagging node —
+            // surface it immediately, since its message ("caller is not the owner") is the useful part.
+            if (floor === 0n)
+                throw err;
+        }
+        if (i < attempts - 1)
+            await new Promise((r) => setTimeout(r, opts.delayMs ?? 1_500));
+    }
+    if (lastEstimate !== null) {
+        throw new GasEstimateBelowFloorError(lastEstimate, floor);
+    }
+    throw lastError instanceof Error ? lastError : new Error('gas estimation failed');
+}
+/**
+ * Build a {@link SendTx} that signs with an env-style hot key and broadcasts — the generalization of
+ * what used to be hand-rolled per call site (a deploy-then-setup loop in the CLI, the hot lane in
+ * `signer.ts`, the chunk-staging sender in `ownerops.ts`): one function that gets the read-after-
+ * write-lag handling right ONCE.
+ *
+ * Two lags, pinned once at construction / tracked locally per send, rather than re-read at send time:
+ *   - the NONCE — fetched once here, then incremented locally per tx. Right after a tx is mined a
+ *     distributed RPC (e.g. Alchemy) can briefly serve a stale `pending` transaction count
+ *     (read-after-write lag), so re-fetching it for the NEXT send in the same sequence risks reusing
+ *     the just-spent nonce — the tx it already has in the mempool rejects the duplicate as
+ *     "replacement transaction underpriced", and that send is silently lost.
+ *   - GAS, one field over: a tx after the first in a sequence may target a contract an EARLIER tx in
+ *     this same sequence just created. If the node answering `eth_estimateGas` hasn't seen that
+ *     block yet, the target looks codeless and the estimate comes back as the calldata cost alone —
+ *     see `pinGas` above for the full story (and the measured numbers). So every send after the
+ *     first waits for its target's code to be visible before estimating.
+ *
+ * Every send: wait for code at the target when it's not the first send in this sender's sequence
+ * (mirrors the exact rule the deploy-code hot lane hand-rolled: every tx after the first, since the
+ * first is what creates what the rest target), pin the gas (a provable floor detector, never a
+ * substitute limit), broadcast, wait for the receipt, and throw a typed {@link TxRevertedError} —
+ * carrying the tx hash — on a `reverted` status rather than reporting a burned transaction as
+ * "confirmed".
+ */
+export function makeHotSender(args) {
+    const { wallet, account, publicClient } = args;
+    const notify = args.onEvent ?? (() => { });
+    let nonce;
+    let sent = 0;
+    return async (tx) => {
+        if (nonce === undefined) {
+            // Fetch once, then increment locally per send — see the read-after-write-lag reasoning above.
+            nonce = await publicClient.getTransactionCount({ address: account.address, blockTag: 'pending' });
+        }
+        // The SAME lag, one field over: every send after the first in this sender's sequence may target
+        // what an earlier send just created.
+        if (sent > 0 && tx.to)
+            await waitForCodeAt(publicClient, tx.to);
+        const gas = await pinGas(publicClient, { from: account.address, to: tx.to, data: tx.data, value: tx.value, gasFloor: tx.gasFloor });
+        notify({ kind: 'sending', tx });
+        const hash = await wallet.sendTransaction({
+            to: tx.to ?? undefined,
+            data: tx.data,
+            value: tx.value && tx.value !== '0x0' ? BigInt(tx.value) : undefined,
+            account,
+            chain: wallet.chain,
+            nonce,
+            gas,
+        });
+        nonce += 1;
+        sent += 1;
+        const receipt = await publicClient.waitForTransactionReceipt({ hash });
+        if (receipt.status !== 'success')
+            throw new TxRevertedError(tx.op, hash);
+        notify({ kind: 'mined', receipt, tx });
+        return receipt;
+    };
+}
+/** Send a list of prepared txs, in order, via `send`; returns their receipts in the same order.
+ *  A small convenience for the common "just run this sequence" case — narration (if any) rides
+ *  `send`'s own `onEvent`, not a callback here. */
+export async function runPrepared(txs, send) {
+    const receipts = [];
+    for (const tx of txs)
+        receipts.push(await send(tx));
+    return receipts;
+}
+//# sourceMappingURL=execute.js.map

package/dist/execute.js.map

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

package/dist/gateways.d.ts

@@ -0,0 +1,79 @@
+import type { ProjectState } from './types.js';
+/** The locator's network, which decides which gateways can be asked about it. `http` locators
+ *  carry their own base (they are already an absolute URL) and resolve to `''` here — a caller
+ *  returns them verbatim before consulting a gateway. */
+export type LocatorNetwork = 'arweave' | 'ipfs' | 'http';
+/** Resolved gateway overrides for the two content-addressed networks — the shape both
+ *  {@link resolveGatewayBase} and {@link gatewayConfigFromEnv} speak. */
+export interface GatewayOverrides {
+    ipfs?: string;
+    arweave?: string;
+}
+/**
+ * The gateway BASE for a locator network, given already-resolved `overrides` — PURE, no env
+ * read. Defaults to the generic public gateways (`ipfs.io` / `arweave.net`) when `overrides`
+ * doesn't name one; any other `network` (e.g. `http`, which carries its own base) resolves to
+ * `''`. Callers that want override → env → default precedence compose this with
+ * {@link gatewayConfigFromEnv} themselves (see `@artblocks/abx-storage`'s `resolveGatewayBase`
+ * for the reference compose) — kept separate so a host with its own config source never has this
+ * function reach into `process.env` on its behalf.
+ */
+export declare function resolveGatewayBase(network: 'ipfs' | 'arweave' | string, overrides?: GatewayOverrides): string;
+/**
+ * The ONLY env-reading piece of this module: `ABX_IPFS_GATEWAY` / `ABX_ARWEAVE_GATEWAY`, read via
+ * {@link readEnv} (safe where `process` doesn't exist). Exported separately from
+ * {@link resolveGatewayBase} so a host with its own gateway configuration (a database row, a
+ * remote config service) never has to touch `process.env` through this package at all — it just
+ * never calls this function and passes its own overrides straight to the pure resolver instead.
+ */
+export declare function gatewayConfigFromEnv(): GatewayOverrides;
+/** Build the URL that asks `gateway` for `id`. A locator that is already an absolute URL is asked
+ *  verbatim — rewriting someone's URL would answer a question they didn't ask. */
+export declare function gatewayUrlFor(network: LocatorNetwork, id: string, gateway: string): string;
+/** A scheme whose locator is content-addressed, and therefore its own integrity anchor. */
+export type ContentAddressedNetwork = 'ipfs' | 'arweave';
+/**
+ * Normalize a gateway HOST (the `ABX_IPFS_GATEWAY` / `ABX_ARWEAVE_GATEWAY` shape, and what
+ * {@link resolveGatewayBase} returns) into the on-chain PREFIX shape — trailing path included, so
+ * projection is a raw concat. A value that already ends in the scheme's path segment is left
+ * alone, so an operator may configure either form.
+ */
+export declare function gatewayPrefixFrom(network: ContentAddressedNetwork, base: string): string;
+/**
+ * The gateway prefix this project prefers for a scheme: the collection's reserved
+ * `abx_gateway_*` field, else the host's env/override default, else the public floor.
+ *
+ * The env read is a FLOOR, never an override. When a project has stated a preference on chain,
+ * every conforming resolver must serve that one — otherwise the same token renders differently
+ * depending on who is serving it, which is the property `abx_provenance` exists to make checkable.
+ * When a project has stated nothing, a host with its own gateway is strictly better than
+ * `ipfs.io`, and a managed provider serving a token it does not own has no other way to say so.
+ */
+export declare function projectGatewayPrefix(state: Pick<ProjectState, 'collectionFields'>, network: ContentAddressedNetwork, overrides?: GatewayOverrides): string;
+/**
+ * Project a content-addressed field value into its https URL, byte-identically to the deployed
+ * renderer. `null` when the value locates nothing (`ipfs://` with no CID) — the caller omits an
+ * optional field or falls back on a required one, rather than emitting a bare prefix that 404s.
+ *
+ * Order is load-bearing and mirrors the Solidity exactly: strip the scheme, THEN substitute
+ * `{id}`, THEN check for an absolute URL. That last check is what stops a value which already
+ * names its own host — precisely what a `backend.locator()` return looks like — from coming back
+ * as `https://arweave.net/https://arweave.net/<txid>`.
+ */
+export declare function projectGatewayUrl(network: ContentAddressedNetwork, value: string, prefix: string, tokenId?: string): string | null;
+/**
+ * The inverse of {@link gatewayUrlFor} / {@link projectGatewayUrl}: recover the bare content id
+ * (CID or txid, plus any path suffix) from whatever form a locator arrived in.
+ *
+ * This exists because a storage backend's `locator()` returns a **gateway HTTPS URL** — the form an
+ * operator can click — while an `ipfs` / `arweave` metadata field must hold IDENTITY, with the
+ * gateway supplied at read time. Baking the operator's gateway host into the field is exactly the
+ * weld this projection was built to remove: it makes a CID unmigratable and makes the chain report
+ * `source: url` for bytes that live on IPFS.
+ *
+ * `null` when no id can be recovered — notably a subdomain-style gateway
+ * (`https://<cid>.ipfs.dweb.link`), which ABX's own backends never produce. A caller that gets
+ * `null` should keep the URL as a plain `url` field and SAY so, rather than guess.
+ */
+export declare function contentIdFromLocator(network: ContentAddressedNetwork, locator: string): string | null;
+//# sourceMappingURL=gateways.d.ts.map

package/dist/gateways.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateways.d.ts","sourceRoot":"","sources":["../src/gateways.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAgB,YAAY,EAAC,MAAM,YAAY,CAAC;AAE5D;;yDAEyD;AACzD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD;yEACyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAI7G;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAOvD;AAED;kFACkF;AAClF,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK1F;AAaD,2FAA2F;AAC3F,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAAC;AAIzD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,kBAAkB,CAAC,EAC7C,OAAO,EAAE,uBAAuB,EAChC,SAAS,CAAC,EAAE,gBAAgB,GAC3B,MAAM,CAgBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,uBAAuB,EAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBrG"}

package/dist/gateways.js

@@ -0,0 +1,156 @@
+/**
+ * Gateway resolution for content-addressed locators (`ipfs://…`, `ar://…`) — hoisted from
+ * `@artblocks/abx-storage` (the abx-services integrator ask), split into a PURE resolver and a
+ * separate env-reading piece so a host with its own gateway config never has to touch
+ * `process.env` through this module at all, and so this stays reachable from a browser bundle
+ * (see `test/browser-bundle.test.ts` — no `process.env` read outside {@link gatewayConfigFromEnv},
+ * which itself goes through {@link readEnv} and degrades to "no override" rather than throwing
+ * where `process` doesn't exist).
+ */
+import { readEnv } from './util.js';
+import { GATEWAY_FIELD, GATEWAY_FLOOR, METADATA_REPRESENTATION as R } from './spine.js';
+import { inlineText } from './token.js';
+/**
+ * The gateway BASE for a locator network, given already-resolved `overrides` — PURE, no env
+ * read. Defaults to the generic public gateways (`ipfs.io` / `arweave.net`) when `overrides`
+ * doesn't name one; any other `network` (e.g. `http`, which carries its own base) resolves to
+ * `''`. Callers that want override → env → default precedence compose this with
+ * {@link gatewayConfigFromEnv} themselves (see `@artblocks/abx-storage`'s `resolveGatewayBase`
+ * for the reference compose) — kept separate so a host with its own config source never has this
+ * function reach into `process.env` on its behalf.
+ */
+export function resolveGatewayBase(network, overrides) {
+    if (network === 'ipfs')
+        return overrides?.ipfs || 'https://ipfs.io';
+    if (network === 'arweave')
+        return overrides?.arweave || 'https://arweave.net';
+    return '';
+}
+/**
+ * The ONLY env-reading piece of this module: `ABX_IPFS_GATEWAY` / `ABX_ARWEAVE_GATEWAY`, read via
+ * {@link readEnv} (safe where `process` doesn't exist). Exported separately from
+ * {@link resolveGatewayBase} so a host with its own gateway configuration (a database row, a
+ * remote config service) never has to touch `process.env` through this package at all — it just
+ * never calls this function and passes its own overrides straight to the pure resolver instead.
+ */
+export function gatewayConfigFromEnv() {
+    const ipfs = readEnv('ABX_IPFS_GATEWAY');
+    const arweave = readEnv('ABX_ARWEAVE_GATEWAY');
+    const out = {};
+    if (ipfs)
+        out.ipfs = ipfs;
+    if (arweave)
+        out.arweave = arweave;
+    return out;
+}
+/** Build the URL that asks `gateway` for `id`. A locator that is already an absolute URL is asked
+ *  verbatim — rewriting someone's URL would answer a question they didn't ask. */
+export function gatewayUrlFor(network, id, gateway) {
+    if (/^https?:\/\//i.test(id))
+        return id;
+    const base = gateway.replace(/\/+$/, '');
+    // A path suffix (a directory manifest entry, e.g. `<txid>/index.html`) rides along untouched.
+    return network === 'ipfs' ? `${base}/ipfs/${id}` : `${base}/${id}`;
+}
+const SCHEME = { ipfs: 'ipfs://', arweave: 'ar://' };
+/**
+ * Normalize a gateway HOST (the `ABX_IPFS_GATEWAY` / `ABX_ARWEAVE_GATEWAY` shape, and what
+ * {@link resolveGatewayBase} returns) into the on-chain PREFIX shape — trailing path included, so
+ * projection is a raw concat. A value that already ends in the scheme's path segment is left
+ * alone, so an operator may configure either form.
+ */
+export function gatewayPrefixFrom(network, base) {
+    const trimmed = base.replace(/\/+$/, '');
+    if (!trimmed)
+        return GATEWAY_FLOOR[network];
+    if (network === 'arweave')
+        return `${trimmed}/`;
+    return trimmed.endsWith('/ipfs') ? `${trimmed}/` : `${trimmed}/ipfs/`;
+}
+/**
+ * The gateway prefix this project prefers for a scheme: the collection's reserved
+ * `abx_gateway_*` field, else the host's env/override default, else the public floor.
+ *
+ * The env read is a FLOOR, never an override. When a project has stated a preference on chain,
+ * every conforming resolver must serve that one — otherwise the same token renders differently
+ * depending on who is serving it, which is the property `abx_provenance` exists to make checkable.
+ * When a project has stated nothing, a host with its own gateway is strictly better than
+ * `ipfs.io`, and a managed provider serving a token it does not own has no other way to say so.
+ */
+export function projectGatewayPrefix(state, network, overrides) {
+    const onChain = state.collectionFields.find(
+    // Only `inline` counts. A prefix is a short UTF-8 string, and accepting exactly one
+    // representation keeps this rule identical on the renderer, the generator and here.
+    (f) => f.field === GATEWAY_FIELD[network] && f.representation === R.inline);
+    if (onChain) {
+        // No `.trim()`: the on-chain `_gatewayPrefix` returns the stored bytes verbatim (any non-empty
+        // `inline` value wins), so trimming here would make the two serving planes disagree on a
+        // whitespace-padded prefix — the same byte-parity class this projection exists to hold. The field
+        // store rejects an empty value, so a set field is always non-empty.
+        const stated = inlineText(onChain);
+        if (stated)
+            return stated;
+    }
+    const host = overrides?.[network];
+    return host ? gatewayPrefixFrom(network, host) : GATEWAY_FLOOR[network];
+}
+/**
+ * Project a content-addressed field value into its https URL, byte-identically to the deployed
+ * renderer. `null` when the value locates nothing (`ipfs://` with no CID) — the caller omits an
+ * optional field or falls back on a required one, rather than emitting a bare prefix that 404s.
+ *
+ * Order is load-bearing and mirrors the Solidity exactly: strip the scheme, THEN substitute
+ * `{id}`, THEN check for an absolute URL. That last check is what stops a value which already
+ * names its own host — precisely what a `backend.locator()` return looks like — from coming back
+ * as `https://arweave.net/https://arweave.net/<txid>`.
+ */
+export function projectGatewayUrl(network, value, prefix, tokenId) {
+    let id = value;
+    const scheme = SCHEME[network];
+    if (id.startsWith(scheme))
+        id = id.slice(scheme.length);
+    if (!id)
+        return null;
+    // One collection-scope `ipfs` field addresses a whole pinned directory. Skipped on the
+    // collection surface, which has no tokenId — the same reason `url-template` is omitted there.
+    if (tokenId !== undefined)
+        id = id.split('{id}').join(tokenId);
+    if (/^https?:\/\//i.test(id))
+        return id;
+    return prefix + id;
+}
+/**
+ * The inverse of {@link gatewayUrlFor} / {@link projectGatewayUrl}: recover the bare content id
+ * (CID or txid, plus any path suffix) from whatever form a locator arrived in.
+ *
+ * This exists because a storage backend's `locator()` returns a **gateway HTTPS URL** — the form an
+ * operator can click — while an `ipfs` / `arweave` metadata field must hold IDENTITY, with the
+ * gateway supplied at read time. Baking the operator's gateway host into the field is exactly the
+ * weld this projection was built to remove: it makes a CID unmigratable and makes the chain report
+ * `source: url` for bytes that live on IPFS.
+ *
+ * `null` when no id can be recovered — notably a subdomain-style gateway
+ * (`https://<cid>.ipfs.dweb.link`), which ABX's own backends never produce. A caller that gets
+ * `null` should keep the URL as a plain `url` field and SAY so, rather than guess.
+ */
+export function contentIdFromLocator(network, locator) {
+    const trimmed = locator.trim();
+    if (!trimmed)
+        return null;
+    const scheme = SCHEME[network];
+    if (trimmed.startsWith(scheme))
+        return trimmed.slice(scheme.length) || null;
+    if (!/^https?:\/\//i.test(trimmed))
+        return trimmed; // already bare
+    if (network === 'ipfs') {
+        const at = trimmed.lastIndexOf('/ipfs/');
+        return at === -1 ? null : trimmed.slice(at + '/ipfs/'.length) || null;
+    }
+    // Strip the origin by hand rather than via `new URL().pathname`, which percent-encodes: an Arweave
+    // directory template `https://arweave.net/TXDIR/{id}.png` came back as `TXDIR/%7Bid%7D.png`, and
+    // that value would have been COMMITTED ON CHAIN — where nothing substitutes `%7Bid%7D`, so every
+    // token in the collection would resolve to the same missing file.
+    const afterOrigin = trimmed.replace(/^https?:\/\/[^/]*\/?/i, '');
+    return afterOrigin || null;
+}
+//# sourceMappingURL=gateways.js.map

package/dist/gateways.js.map

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

package/dist/generator-document.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The generator-document family — the template-mode runtime companion, the inline-safety
+ * escapes, and the pure document-shape builders. Hoisted from `@artblocks/abx-token-api`
+ * (the abx-services integrator ask): every piece here is a pure string operation with no chain
+ * access and no Node dependency, so it belongs in the neutral layer a resolver, a CLI preview,
+ * and any third-party provider all consume identically — one definition of the runtime surface
+ * and the document shape, so none of them can quietly drift from what the others emit.
+ */
+/**
+ * `abx.js` — the runtime companion (the hl-gen.js analog), served at `/abx.js` and
+ * inlined into template-mode documents. Convention, not protocol: a directory build
+ * includes it; the generator injects the same surface.
+ *
+ * tokenData resolution order (the durability chain): the injected `window.abxTokenData`
+ * global (template mode) → the `?abx=` query param (base64url canonical JSON — the
+ * live-view route) → the `?chainId&contract&tokenId` coordinate floor (a build opened
+ * bare from a gateway still knows which token it is; full param reads from RPC are the
+ * render-node's job, not this shim's).
+ */
+export declare const ABX_JS = "(function () {\n  var abx = (window.abx = window.abx || {});\n  function fromQuery() {\n    try {\n      var q = new URLSearchParams(location.search);\n      var packed = q.get('abx');\n      if (packed) {\n        var b64 = packed.replace(/-/g, '+').replace(/_/g, '/');\n        return JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(b64), function (c) { return c.charCodeAt(0); })));\n      }\n      // coordinate floor: enough for a deterministic piece opened bare from a gateway\n      if (q.get('contract') && q.get('tokenId')) {\n        return {\n          chainId: Number(q.get('chainId') || 1),\n          contractAddress: String(q.get('contract')).toLowerCase(),\n          tokenId: String(q.get('tokenId')),\n        };\n      }\n    } catch (e) {}\n    return null;\n  }\n  abx.tokenData = window.abxTokenData || fromQuery();\n  abx.__traits = null;\n  abx.__done = false;\n  /** The script reports its computed traits (script-defined features; captured at render). */\n  abx.traits = function (t) {\n    abx.__traits = t;\n    try { document.dispatchEvent(new CustomEvent('abx:traits', {detail: t})); } catch (e) {}\n    return t;\n  };\n  /** Output-complete \u2014 the capture point for the render effect. Optional (timeout fallback). */\n  abx.done = function () {\n    abx.__done = true;\n    try { document.dispatchEvent(new CustomEvent('abx:done')); } catch (e) {}\n  };\n})();\n";
+/**
+ * Inline-document safety — the one HTML parsing rule that matters when embedding
+ * content inside <script> elements: the parser ends the element at the first
+ * `</script`, regardless of JS string/comment context. Two content shapes, two
+ * semantics-preserving escapes:
+ *
+ *  - JS source (libraries, creator scripts): `</script` → `<\/script`. In valid JS the
+ *    sequence can only occur inside a string, template, regex, or comment — contexts
+ *    where `\/` is identical to `/` — so the transform never changes behavior.
+ *  - JSON (the injected `window.abxTokenData`): every `<` → `\u003c`. `<` only occurs
+ *    inside JSON strings (never in the syntax), and `\u003c` parses to the same
+ *    character — the canonical (hashed) serialization is untouched; only the delivery
+ *    form differs.
+ */
+/** JS source safe to inline inside a <script> element. Case-insensitive because HTML end tags
+ *  are; the on-chain generator matches this (see `AbxGenerator._escapedScript`). */
+export declare function escapeInlineScript(src: string): string;
+/** A JSON payload safe to inline inside a <script> element (parse-identical). */
+export declare function escapeInlineJson(json: string): string;
+/**
+ * Inject `window.abxTokenData` (and, when the document doesn't already carry one, a
+ * `<base href="{code root}/">` so relative asset paths keep riding the gateway) at the
+ * very top of `<head>` — before any build script can execute; abx.js resolves the global
+ * first. String-level and deliberately robust rather than a full HTML parse: no `<head>`
+ * → inject right after `<html …>`; neither → prepend. First `<base>` wins in HTML, so an
+ * existing one is never doubled.
+ */
+export declare function injectTokenDataIntoHtml(html: string, tokenDataJson: string, codeRoot: string): string;
+/**
+ * The template-mode document shape, pure — no chain access, so a caller that already has a
+ * script + dep tags in hand (the resolver's own chain-fetched assembly; `abx preview`'s offline
+ * studio, local-file + CDN-resolved) can build the byte-identical document. Exported for exactly
+ * that reason: **one** definition of the shape, so a caller can never quietly drift from what the
+ * generator actually serves — the failure mode a hand-maintained duplicate (with a "keep these in
+ * sync" comment and nothing enforcing it) invites.
+ */
+export declare function buildGeneratorDocument(script: string, tokenDataJson: string, depTags: string[]): string;
+//# sourceMappingURL=generator-document.d.ts.map

package/dist/generator-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator-document.d.ts","sourceRoot":"","sources":["../src/generator-document.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,o4CAoClB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAEH;oFACoF;AACpF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAcrG;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAYvG"}