@artblocks/abx-sdk 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/ops.d.ts

@@ -698,7 +698,7 @@ export declare function prepareLockScript(args: {
 }): PreparedTx;
 /** Set a CONTRACT-scope param to a literal `bytes32` (the raw owner setter — Params base).
  *  Only for schema-less keys (a schema'd key closes the raw path: `SchemaGoverned`). This is
- *  the write behind well-known contract params like `display.gateway`. The key joins the
+ *  the write behind well-known contract params like `display.animation`. The key joins the
  *  contract's on-chain key list automatically (`contractParamKeys`), so it is enumerated by
  *  the generator and the renderer with no separate declaration. Signer must be the owner. */
 export declare function prepareSetContractParam(args: {

package/dist/ops.js

@@ -1343,7 +1343,7 @@ export function prepareLockScript(args) {
 }
 /** Set a CONTRACT-scope param to a literal `bytes32` (the raw owner setter — Params base).
  *  Only for schema-less keys (a schema'd key closes the raw path: `SchemaGoverned`). This is
- *  the write behind well-known contract params like `display.gateway`. The key joins the
+ *  the write behind well-known contract params like `display.animation`. The key joins the
  *  contract's on-chain key list automatically (`contractParamKeys`), so it is enumerated by
  *  the generator and the renderer with no separate declaration. Signer must be the owner. */
 export function prepareSetContractParam(args) {

package/dist/probe.d.ts

@@ -1,3 +1,4 @@
+import { type PublicClient } from 'viem';
 /**
  * Capability probe for RPC endpoints. Reconstruction is `eth_getLogs`-heavy and
  * needs *archive* depth (to read a project's deploy block) plus a usable block
@@ -27,4 +28,32 @@ export declare function probeRpcEndpoints(opts?: {
     chainKey?: string;
     urls?: string[];
 }): Promise<RpcProbe[]>;
+/**
+ * Can this endpoint still serve LOG HISTORY at `blockNumber`?
+ *
+ * The check this replaced was `getLogs({address: zeroAddress, fromBlock: old, toBlock: old})` and
+ * "any non-throw counts as archive access" — which cannot fail on a pruning node. `zeroAddress`
+ * never emits logs, so an empty result is what a *perfect* archive node returns too: the assertion
+ * had no discriminating power and only caught endpoints that *error* on old blocks. A node that
+ * silently answers `[]` for pruned history was graded `best`, and `abx add` then ground through
+ * half a million blocks and reconstructed nothing, because a successful empty response is not an
+ * error and never fails over to the next endpoint.
+ *
+ * So assert on something that MUST come back. Blocks are retained by everyone; receipts and the log
+ * index are what get pruned. We read the probe block, ask for one of its transactions' receipts, and
+ * — when that receipt carries a log — require `getLogs` to return that same log. Measured on two
+ * Base Sepolia endpoints at 500k blocks back, same transaction: one returns a receipt with 1 log,
+ * the other returns null. That is the discriminator, and it needs no hardcoded address or block.
+ *
+ * Fails SAFE, in the direction of the old behaviour: when the probe block has no transactions, or
+ * the receipt has no logs, there is nothing to assert on, so we fall back to the lenient
+ * "getLogs didn't throw" signal rather than manufacturing a failure.
+ *
+ * Exported for tests — `probeOne` builds its own transport per URL, so the discriminating logic is
+ * what gets asserted directly.
+ */
+export declare function probeHistoryAt(client: PublicClient, blockNumber: bigint): Promise<{
+    retained: boolean;
+    reason?: string;
+}>;
 //# sourceMappingURL=probe.d.ts.map

package/dist/probe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,wBAAsB,iBAAiB,CACrC,IAAI,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAM,GAC9C,OAAO,CAAC,QAAQ,EAAE,CAAC,CAIrB"}
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6E,KAAK,YAAY,EAAC,MAAM,MAAM,CAAC;AAInH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,wBAAsB,iBAAiB,CACrC,IAAI,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAM,GAC9C,OAAO,CAAC,QAAQ,EAAE,CAAC,CAIrB;AAyDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,CAgD/C"}

package/dist/probe.js

@@ -2,7 +2,17 @@ import { createPublicClient, http, zeroAddress } from 'viem';
 import { resolveChain, resolveRpcUrls, redactRpcUrl } from './chains.js';
 import { isGetLogsRangeError } from './reconstruct.js';
 const RANGE_PROBE = 2000n; // "wide" recent range to test the getLogs window
-const ARCHIVE_DEPTH = 100000n; // deep enough that non-archive nodes refuse
+/**
+ * How far back "archive depth" means. Deliberately deep: reconstruction starts at a project's
+ * DEPLOY block, so the bar is "can this endpoint still serve a project that is not new?". At 500k
+ * blocks that is ~11 days on Base Sepolia (2s blocks) and ~10 weeks on Ethereum Sepolia (12s) —
+ * comfortably past the retention window of the pruning public endpoints, and far short of any
+ * genuinely archival node. It was 100_000, which sat *inside* the retained window of at least one
+ * default endpoint, so the probe passed on a node that could not reconstruct anything older.
+ */
+const ARCHIVE_DEPTH = 500000n;
+/** How many of a probe block's transactions to try a receipt for before giving up. */
+const RECEIPT_TRIES = 3;
 export async function probeRpcEndpoints(opts = {}) {
     const chain = resolveChain(opts.chainKey);
     const urls = opts.urls ?? resolveRpcUrls(opts.chainKey);
@@ -46,14 +56,10 @@ async function probeOne(chain, url) {
     }
     // archive depth — one block, deep in the past, to isolate archive from range
     const old = head > ARCHIVE_DEPTH ? head - ARCHIVE_DEPTH : 0n;
-    try {
-        await client.getLogs({ address: zeroAddress, fromBlock: old, toBlock: old });
-        probe.archive = true;
-    }
-    catch (err) {
-        if (!probe.reason)
-            probe.reason = firstLine(err);
-    }
+    const retention = await probeHistoryAt(client, old);
+    probe.archive = retention.retained;
+    if (!probe.archive && !probe.reason)
+        probe.reason = retention.reason;
     if (!probe.archive) {
         probe.verdict = 'unusable';
         probe.reason = probe.reason ?? 'no archive access — can’t read a project’s deploy block';
@@ -68,6 +74,95 @@ async function probeOne(chain, url) {
     }
     return probe;
 }
+/**
+ * Can this endpoint still serve LOG HISTORY at `blockNumber`?
+ *
+ * The check this replaced was `getLogs({address: zeroAddress, fromBlock: old, toBlock: old})` and
+ * "any non-throw counts as archive access" — which cannot fail on a pruning node. `zeroAddress`
+ * never emits logs, so an empty result is what a *perfect* archive node returns too: the assertion
+ * had no discriminating power and only caught endpoints that *error* on old blocks. A node that
+ * silently answers `[]` for pruned history was graded `best`, and `abx add` then ground through
+ * half a million blocks and reconstructed nothing, because a successful empty response is not an
+ * error and never fails over to the next endpoint.
+ *
+ * So assert on something that MUST come back. Blocks are retained by everyone; receipts and the log
+ * index are what get pruned. We read the probe block, ask for one of its transactions' receipts, and
+ * — when that receipt carries a log — require `getLogs` to return that same log. Measured on two
+ * Base Sepolia endpoints at 500k blocks back, same transaction: one returns a receipt with 1 log,
+ * the other returns null. That is the discriminator, and it needs no hardcoded address or block.
+ *
+ * Fails SAFE, in the direction of the old behaviour: when the probe block has no transactions, or
+ * the receipt has no logs, there is nothing to assert on, so we fall back to the lenient
+ * "getLogs didn't throw" signal rather than manufacturing a failure.
+ *
+ * Exported for tests — `probeOne` builds its own transport per URL, so the discriminating logic is
+ * what gets asserted directly.
+ */
+export async function probeHistoryAt(client, blockNumber) {
+    const depth = `~${ARCHIVE_DEPTH} blocks back`; // the FAULT only — each caller words its own remedy
+    let txHashes = [];
+    try {
+        const block = await client.getBlock({ blockNumber, includeTransactions: false });
+        txHashes = block.transactions.slice(0, RECEIPT_TRIES);
+    }
+    catch (err) {
+        return { retained: false, reason: `can't read a block ${depth} — ${firstLine(err)}` };
+    }
+    for (const hash of txHashes) {
+        let logAddress;
+        try {
+            const receipt = await client.getTransactionReceipt({ hash });
+            logAddress = receipt.logs[0]?.address;
+        }
+        catch (err) {
+            // Only a genuine "no such receipt" proves pruning. A rate-limit or a transport blip must NOT
+            // become a "history pruned" claim about an endpoint that is actually fine — so anything else
+            // falls through to the lenient check below, which is what this function did before.
+            if (!looksLikeReceiptMissing(err))
+                break;
+            // The node served the block but not the receipt of a transaction inside it: its history is
+            // pruned at this depth. This is exactly what a "recent logs only" endpoint looks like.
+            return {
+                retained: false,
+                reason: `history pruned ${depth} — it serves the block but not the receipts of transactions inside it`,
+            };
+        }
+        if (!logAddress)
+            continue; // nothing to assert on in this tx — try the next
+        try {
+            const logs = await client.getLogs({ address: logAddress, fromBlock: blockNumber, toBlock: blockNumber });
+            if (logs.length > 0)
+                return { retained: true };
+            return {
+                retained: false,
+                reason: `log index pruned ${depth} — eth_getLogs returns EMPTY for a block whose receipts still hold logs`,
+            };
+        }
+        catch (err) {
+            return { retained: false, reason: `eth_getLogs failed ${depth} — ${firstLine(err)}` };
+        }
+    }
+    // Inconclusive (no transactions at the probe block, or none of them logged anything): keep the
+    // old lenient signal rather than inventing a verdict.
+    try {
+        await client.getLogs({ address: zeroAddress, fromBlock: blockNumber, toBlock: blockNumber });
+        return { retained: true };
+    }
+    catch (err) {
+        return { retained: false, reason: firstLine(err) };
+    }
+}
+/**
+ * Does this error mean "that receipt does not exist here" (viem's `TransactionReceiptNotFoundError`,
+ * i.e. the node answered `null`) as opposed to "I could not ask" (rate limit, timeout, 5xx)? Only the
+ * first is evidence about retention; treating the second as evidence would libel a healthy endpoint.
+ */
+function looksLikeReceiptMissing(err) {
+    const e = err;
+    if (e?.name === 'TransactionReceiptNotFoundError')
+        return true;
+    return /receipt.*(not be found|not found)|could not be found/i.test(e?.message ?? '');
+}
 function firstLine(err) {
     return (err?.message ?? String(err)).split('\n')[0].slice(0, 100);
 }

package/dist/probe.js.map

@@ -1 +1 @@
-{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,kBAAkB,EAAE,IAAI,EAAE,WAAW,EAAyD,MAAM,MAAM,CAAC;AACnH,OAAO,EAAC,YAAY,EAAE,cAAc,EAAE,YAAY,EAAC,MAAM,aAAa,CAAC;AACvE,OAAO,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAC;AA6BrD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,iDAAiD;AAC5E;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,OAAQ,CAAC;AAC/B,sFAAsF;AACtF,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA6C,EAAE;IAE/C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,KAAY,EAAE,GAAW;IAC/C,MAAM,KAAK,GAAa,EAAC,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAC,CAAC;IACjI,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAC,UAAU,EAAE,CAAC,EAAC,CAAC,EAAC,CAAC,CAAC;IAElF,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,KAAK,CAAC,MAAM,GAAG,gBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IAElC,wFAAwF;IACxF,0FAA0F;IAC1F,kDAAkD;IAClD,IAAI,CAAC;QACH,KAAK,CAAC,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK,CAAC,EAAE,EAAE,CAAC;YAC/B,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC;YAC3B,KAAK,CAAC,MAAM,GAAG,gCAAgC,KAAK,CAAC,OAAO,cAAc,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;YACrG,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gFAAgF;IAClF,CAAC;IAED,wEAAwE;IACxE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAC,CAAC,CAAC;QACrH,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,uCAAuC;IACvG,CAAC;IAED,6EAA6E;IAC7E,MAAM,GAAG,GAAG,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;IAErE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC;QAC3B,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,yDAAyD,CAAC;IAC3F,CAAC;SAAM,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,OAAO,GAAG,QAAQ,CAAC;QACzB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,qEAAqE,CAAC;IACvG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAoB,EACpB,WAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,aAAa,cAAc,CAAC,CAAC,oDAAoD;IACnG,IAAI,QAAQ,GAAoB,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAC,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAC,CAAC,CAAC;QAC/E,QAAQ,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,EAAC,CAAC;IACtF,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,UAA+B,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,EAAC,IAAI,EAAC,CAAC,CAAC;YAC3D,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6FAA6F;YAC7F,6FAA6F;YAC7F,oFAAoF;YACpF,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC;gBAAE,MAAM;YACzC,2FAA2F;YAC3F,uFAAuF;YACvF,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,kBAAkB,KAAK,uEAAuE;aACvG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU;YAAE,SAAS,CAAC,iDAAiD;QAC5E,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAC,CAAC,CAAC;YACvG,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAC,QAAQ,EAAE,IAAI,EAAC,CAAC;YAC7C,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,oBAAoB,KAAK,yEAAyE;aAC3G,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,SAAS,CAAC,GAAG,CAAC,EAAE,EAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAED,+FAA+F;IAC/F,sDAAsD;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,EAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAC,CAAC,CAAC;QAC3F,OAAO,EAAC,QAAQ,EAAE,IAAI,EAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,EAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,GAAY;IAC3C,MAAM,CAAC,GAAG,GAAwC,CAAC;IACnD,IAAI,CAAC,EAAE,IAAI,KAAK,iCAAiC;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,uDAAuD,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,OAAO,CAAE,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC/E,CAAC"}

package/dist/reconstruct.d.ts

@@ -1,4 +1,4 @@
-import { type Address, type Hex, type PublicClient } from 'viem';
+import { type Address, type Hex, type PublicClient, type Log } from 'viem';
 import { AbxSdkError } from './errors.js';
 import type { DependencyInfo, ExtensionInfo, MetadataField, ParamHooks, ParamSchema, ParamValue, ProjectState, SpineEvent, TokenState } from './types.js';
 export interface ReconstructOptions {
@@ -46,6 +46,21 @@ export declare function reconstructIncremental(client: PublicClient, prior: Proj
     getLogsRange?: bigint;
     readUriDocuments?: boolean;
 }): Promise<ProjectState>;
+/**
+ * The fold / head-read half of {@link reconstructIncremental}, given logs the caller already
+ * fetched. A multi-address watch loop (`getLogs({address: Address[]})`) holds each touched
+ * project's delta; this consumes it so that loop is the only `eth_getLogs`. Folding stays here.
+ *
+ * `toBlock` is the inclusive scan head those logs cover — required even when `logs` is empty,
+ * so a quiet window still advances the checkpoint to the range the caller scanned, and so a
+ * caller that scanned a capped window (not chain head) cannot stamp `toBlock` past the last
+ * log they actually held.
+ */
+export declare function reconstructFromLogs(client: PublicClient, prior: ProjectState, logs: readonly Log[], opts: {
+    factory?: Address;
+    readUriDocuments?: boolean;
+    toBlock: bigint;
+}): Promise<ProjectState>;
 /** The structural projection folded from the spine (everything that isn't a head read).
  *  Exported for tests and advanced consumers; the shape may evolve with the spine. */
 export interface Fold {
@@ -113,6 +128,34 @@ export declare class GetLogsScanTooLargeError extends AbxSdkError {
  * contract has no code at block 0 (true for every ABX clone — deployed long after genesis).
  */
 export declare function discoverDeployBlock(client: PublicClient, address: Address, toBlock?: bigint): Promise<bigint | null>;
+/**
+ * Ordinary RPC tiers cap how many addresses one `eth_getLogs` filter may carry.
+ * This is an RPC-tier opinion, not a protocol constant — callers with a dedicated
+ * node can raise it; `0` disables splitting (one filter for the whole list).
+ */
+export declare const DEFAULT_GETLOGS_ADDRESS_BATCH = 1000;
+export interface GetLogsAdaptiveOptions {
+    maxChunks?: number;
+    range?: bigint;
+    /** Split `address[]` filters into this many addresses per request. Default
+     *  {@link DEFAULT_GETLOGS_ADDRESS_BATCH}. `0` = no split. */
+    addressBatch?: number;
+}
+/**
+ * Pull logs over a block range, adapting to RPC range caps — and, when `address` is
+ * a list, splitting that list so a registered-set watch scan stays one code path for
+ * self-host and hosted. Providers cap `eth_getLogs` very differently and the numbers
+ * change, so we don't hard-code a window: try the whole range, and when the RPC
+ * rejects it, halve the window and sweep. `ABX_GETLOGS_RANGE` overrides the starting
+ * window. Address-list chunking is a separate cap (`addressBatch`); 5000-block
+ * per-tick windows belong to the caller (the watcher), not here.
+ *
+ * Once the working window is known we estimate the whole job *before* grinding it: if
+ * it would exceed the cap, we stop early (only the probe calls spent) and throw
+ * {@link GetLogsScanTooLargeError} so the caller can offer the real fix (a higher-range
+ * RPC) or an explicit opt-in to chunk through it.
+ */
+export declare function getLogsAdaptive(client: PublicClient, address: Address | readonly Address[], fromBlock: bigint, toBlock: bigint, opts?: GetLogsAdaptiveOptions): Promise<Log[]>;
 /**
  * Multicall in chunks, tolerating per-leg failure — and, when a whole chunk comes back failed,
  * retrying its legs individually before believing it.

package/dist/reconstruct.d.ts.map

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

package/dist/reconstruct.js

@@ -38,14 +38,29 @@ export async function reconstructIncremental(client, prior, opts = {}) {
     const priorTo = BigInt(prior.toBlock);
     const origin = BigInt(prior.deployBlock ?? prior.fromBlock);
     const resumeFrom = priorTo + 1n > origin ? priorTo + 1n : origin;
-    let fresh = [];
+    let rawLogs = [];
     if (head >= resumeFrom) {
-        const rawLogs = await getLogsAdaptive(client, address, resumeFrom, head, {
+        rawLogs = await getLogsAdaptive(client, address, resumeFrom, head, {
             maxChunks: opts.maxChunks,
             range: opts.getLogsRange,
         });
-        fresh = decodedToSpineEvents(parseEventLogs({ abi: spineEventAbi, logs: rawLogs }));
     }
+    const toBlock = head >= priorTo ? head : priorTo;
+    return reconstructFromLogs(client, prior, rawLogs, { factory, readUriDocuments: opts.readUriDocuments, toBlock });
+}
+/**
+ * The fold / head-read half of {@link reconstructIncremental}, given logs the caller already
+ * fetched. A multi-address watch loop (`getLogs({address: Address[]})`) holds each touched
+ * project's delta; this consumes it so that loop is the only `eth_getLogs`. Folding stays here.
+ *
+ * `toBlock` is the inclusive scan head those logs cover — required even when `logs` is empty,
+ * so a quiet window still advances the checkpoint to the range the caller scanned, and so a
+ * caller that scanned a capped window (not chain head) cannot stamp `toBlock` past the last
+ * log they actually held.
+ */
+export async function reconstructFromLogs(client, prior, logs, opts) {
+    const factory = opts.factory ?? prior.factory ?? undefined;
+    const fresh = decodedToSpineEvents(parseEventLogs({ abi: spineEventAbi, logs: logs }));
     // Merge the prior log with the freshly-fetched tail, de-duping by position so an
     // overlapping/duplicate re-run can't double-count, then fold the complete spine.
     const seen = new Set();
@@ -58,8 +73,13 @@ export async function reconstructIncremental(client, prior, opts = {}) {
         all.push(ev);
     }
     all.sort(byOrder);
-    const toBlock = head >= priorTo ? head : priorTo;
-    return assembleState(client, address, all, foldSpine(all), BigInt(prior.fromBlock), toBlock, factory, !!opts.readUriDocuments);
+    // Chunk content has no log (too large); `ScriptUpdated` is the ping. A Transfer currently
+    // used to re-download every chunk. Keep the prior digest unless that ping is in `fresh`.
+    const scriptTouched = fresh.some((e) => e.name === 'ScriptUpdated');
+    const reuseScript = !scriptTouched && prior.script?.digest != null ? prior.script : undefined;
+    const priorTo = BigInt(prior.toBlock);
+    const toBlock = opts.toBlock >= priorTo ? opts.toBlock : priorTo;
+    return assembleState(client, prior.address, all, foldSpine(all), BigInt(prior.fromBlock), toBlock, factory, !!opts.readUriDocuments, reuseScript);
 }
 /** Turn decoded viem logs into the canonical, serializable {@link SpineEvent} list. */
 function decodedToSpineEvents(decoded) {
@@ -365,7 +385,7 @@ export function foldSpine(events) {
     return fold;
 }
 /** Build the full {@link ProjectState} from a fold + provenance, then overlay head reads. */
-async function assembleState(client, address, events, fold, fromBlock, toBlock, factory, readUriDocuments = false) {
+async function assembleState(client, address, events, fold, fromBlock, toBlock, factory, readUriDocuments = false, reuseScript) {
     // ensure a TokenState exists for every token referenced by on-chain fields/locks/params
     // (a deployed-but-unminted token can carry fields before any Transfer)
     for (const id of fold.tokenFields.keys())
@@ -477,7 +497,7 @@ async function assembleState(client, address, events, fold, fromBlock, toBlock,
         reconstructedAt: new Date().toISOString(),
         rpcUrl: client.transport?.url,
     };
-    await applyHeadReads(client, state, factory, readUriDocuments);
+    await applyHeadReads(client, state, factory, readUriDocuments, reuseScript);
     return state;
 }
 /** Default safety cap on chunk count; raise via the `maxChunks` opt (or ABX_GETLOGS_MAX_CHUNKS —
@@ -550,49 +570,68 @@ export async function discoverDeployBlock(client, address, toBlock) {
     }
 }
 /**
- * Pull a contract's logs over a block range, adapting to RPC range caps. Providers
- * cap `eth_getLogs` very differently and the numbers change, so we don't hard-code a
- * window: try the whole range, and when the RPC rejects it, halve the window and
- * sweep — adopting the smaller window for the rest of the run. So reconstruction is a
- * single request on a generous RPC, still completes on a constrained one, and (for a
- * 1/1, whose events cluster at the deploy block) stays cheap. `ABX_GETLOGS_RANGE`
- * overrides the starting window.
+ * Ordinary RPC tiers cap how many addresses one `eth_getLogs` filter may carry.
+ * This is an RPC-tier opinion, not a protocol constant — callers with a dedicated
+ * node can raise it; `0` disables splitting (one filter for the whole list).
+ */
+export const DEFAULT_GETLOGS_ADDRESS_BATCH = 1000;
+/**
+ * Pull logs over a block range, adapting to RPC range caps — and, when `address` is
+ * a list, splitting that list so a registered-set watch scan stays one code path for
+ * self-host and hosted. Providers cap `eth_getLogs` very differently and the numbers
+ * change, so we don't hard-code a window: try the whole range, and when the RPC
+ * rejects it, halve the window and sweep. `ABX_GETLOGS_RANGE` overrides the starting
+ * window. Address-list chunking is a separate cap (`addressBatch`); 5000-block
+ * per-tick windows belong to the caller (the watcher), not here.
  *
  * Once the working window is known we estimate the whole job *before* grinding it: if
  * it would exceed the cap, we stop early (only the probe calls spent) and throw
  * {@link GetLogsScanTooLargeError} so the caller can offer the real fix (a higher-range
  * RPC) or an explicit opt-in to chunk through it.
  */
-async function getLogsAdaptive(client, address, fromBlock, toBlock, opts = {}) {
+export async function getLogsAdaptive(client, address, fromBlock, toBlock, opts = {}) {
+    const addrs = (Array.isArray(address) ? address : [address]);
+    if (addrs.length === 0)
+        return [];
+    const batchSize = opts.addressBatch === 0 ? addrs.length : Math.max(1, opts.addressBatch ?? DEFAULT_GETLOGS_ADDRESS_BATCH);
+    const batches = [];
+    for (let i = 0; i < addrs.length; i += batchSize)
+        batches.push(addrs.slice(i, i + batchSize));
     const span = toBlock - fromBlock + 1n;
     const envRange = readEnv('ABX_GETLOGS_RANGE');
-    let window = opts.range && opts.range > 0n ? opts.range : envRange && BigInt(envRange) > 0n ? BigInt(envRange) : span;
+    const startWindow = opts.range && opts.range > 0n ? opts.range : envRange && BigInt(envRange) > 0n ? BigInt(envRange) : span;
     const out = [];
-    let start = fromBlock;
     let estimated = false;
-    while (start <= toBlock) {
-        const end = start + window - 1n < toBlock ? start + window - 1n : toBlock;
-        let logs;
-        try {
-            logs = (await client.getLogs({ address, fromBlock: start, toBlock: end }));
-        }
-        catch (err) {
-            if (isGetLogsRangeError(err) && window > 1n) {
-                window = window > 2n ? window / 2n : 1n; // RPC rejected this window — shrink and retry
-                continue;
+    for (const batch of batches) {
+        const filter = batch.length === 1 ? batch[0] : batch;
+        let window = startWindow;
+        let start = fromBlock;
+        while (start <= toBlock) {
+            const end = start + window - 1n < toBlock ? start + window - 1n : toBlock;
+            let logs;
+            try {
+                logs = (await client.getLogs({ address: filter, fromBlock: start, toBlock: end }));
+            }
+            catch (err) {
+                if (isGetLogsRangeError(err) && window > 1n) {
+                    window = window > 2n ? window / 2n : 1n; // RPC rejected this window — shrink and retry
+                    continue;
+                }
+                throw err; // genuine failure, or already at one block per call
+            }
+            out.push(...logs);
+            start = end + 1n;
+            // Window now proven. Estimate the whole job once (range chunks × address batches)
+            // and bail *before* grinding if absurd.
+            if (!estimated) {
+                estimated = true;
+                const remaining = toBlock - start + 1n;
+                const perBatch = (remaining > 0n ? Number(remaining / window) + 1 : 0) + 1; // +1 for the chunk just done
+                const need = perBatch * batches.length;
+                const cap = resolveMaxChunks(opts.maxChunks);
+                if (need > cap)
+                    throw new GetLogsScanTooLargeError(span, window, need, cap);
             }
-            throw err; // genuine failure, or already at one block per call
-        }
-        out.push(...logs);
-        start = end + 1n;
-        // Window now proven. Estimate the whole job once and bail *before* grinding if absurd.
-        if (!estimated) {
-            estimated = true;
-            const remaining = toBlock - start + 1n;
-            const need = (remaining > 0n ? Number(remaining / window) + 1 : 0) + 1; // +1 for the chunk just done
-            const cap = resolveMaxChunks(opts.maxChunks);
-            if (need > cap)
-                throw new GetLogsScanTooLargeError(span, window, need, cap);
         }
     }
     return out;
@@ -702,7 +741,7 @@ export async function multicallChunked(client, contracts, chunkSize) {
  *    actually wants to display it (`nothing served depends on it`, the one exception being a fresh
  *    `abx demo` read-back, which asks for it explicitly).
  */
-async function applyHeadReads(client, state, factory, readUriDocuments = false) {
+async function applyHeadReads(client, state, factory, readUriDocuments = false, reuseScript) {
     const token = { address: state.address, abi: oneOfOneImageAbi };
     const tokenIds = state.tokens.map((t) => t.tokenId);
     // The edition family (ERC-1155) shares every cheap fixed-return name with the 721 superset ABI
@@ -730,8 +769,11 @@ async function applyHeadReads(client, state, factory, readUriDocuments = false)
         cheap.push({ address: factory, abi: oneOfOneImageFactoryAbi, functionName: 'isAbxClone', args: [state.address] }, { address: factory, abi: oneOfOneImageFactoryAbi, functionName: 'implementation' });
     }
     // On-chain script: chunk content is too large to log, so the count is a head read.
+    // Skip when the caller already holds a digest and `fresh` had no `ScriptUpdated` —
+    // a Transfer must not re-download every chunk.
+    const keepPriorScript = !!(state.script && reuseScript?.digest != null);
     const scriptIdx = cheap.length;
-    if (state.script) {
+    if (state.script && !keepPriorScript) {
         cheap.push({ address: state.address, abi: seriesCodeAbi, functionName: 'scriptChunkCount' });
     }
     // ── unbounded returns: each one may assemble a whole document on-chain ──
@@ -774,7 +816,11 @@ async function applyHeadReads(client, state, factory, readUriDocuments = false)
                 tok.tokenURI = heavyVals[1 + k] ?? null;
         });
     }
-    if (state.script) {
+    if (state.script && keepPriorScript) {
+        state.script.chunkCount = reuseScript.chunkCount;
+        state.script.digest = reuseScript.digest;
+    }
+    else if (state.script) {
         const count = cheapVals[scriptIdx] ?? null;
         state.script.chunkCount = count === null ? null : Number(count);
         // digest = keccak over the concatenated chunks — the content half of effect inputsHash