@inversealtruism/cairn-sdk 0.8.0 → 0.8.2

package/dist/index.js

@@ -1,16 +1,16 @@
 import {
   Chain,
   LightClient
-} from "./chunk-C452UODV.js";
+} from "./chunk-IPBMMJ3Z.js";
 import {
   ContentClient
-} from "./chunk-DTPADO7N.js";
+} from "./chunk-2RR4ZJPQ.js";
 import {
   IndexerClient
-} from "./chunk-CI7YODPP.js";
+} from "./chunk-NRCTL7OI.js";
 import {
   CairnController
-} from "./chunk-JXBO4LV6.js";
+} from "./chunk-AHPXOYCC.js";
 import {
   WalletConnection,
   connect,
@@ -18,7 +18,7 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-WWO3FXHG.js";
+} from "./chunk-EVEBQSDK.js";
 import {
   CairnError,
   ContentVerificationError,
@@ -32,7 +32,7 @@ import {
   errorCode,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-UAPWZZQK.js";
+} from "./chunk-37OHCH7R.js";
 
 // src/http.ts
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
@@ -358,20 +358,23 @@ var NamesClient = class {
 // src/fillverify.ts
 import { rpcTxToTx } from "@inversealtruism/csd-client";
 import { txid, payloadHash } from "@inversealtruism/csd-codec";
+import { authorOf } from "@inversealtruism/csd-crypto";
 import {
-  DOMAIN,
   parseRecord,
   feeBpsAt,
   bindOfferTerms,
   provenOfferTerms,
+  provenOfferRefusal,
   fillOutputPlan,
   isTokenWant,
   fillEndorsement,
   fillIsSafe,
   requiredFillOutputs,
   previewFill,
-  TREASURY_ADDR,
-  epochOf
+  offerExpiryHeightOf,
+  offerFillTooLate,
+  FILL_TIP_MARGIN,
+  fillTargetId as fillTargetOf
 } from "@inversealtruism/cairnx-core";
 var ADDR = /^0x[0-9a-f]{40}$/;
 var BELOW_BASE = /^tx below the synced base \((\d+)\)/;
@@ -412,13 +415,116 @@ async function provenAuthor(client, provenTx) {
     return null;
   }
   if (String(txid(src)).toLowerCase() !== String(in0.prevTxid).toLowerCase()) return null;
-  const out = src.outputs?.[Number(in0.vout)];
-  const spk = out?.scriptPubkey ? String(out.scriptPubkey).toLowerCase() : null;
-  return spk && ADDR.test(spk) ? spk : null;
+  return authorOf(provenTx, src.outputs?.[Number(in0.vout)]?.scriptPubkey);
+}
+var has = (v) => v !== void 0 && v !== null;
+function fillInputs(o) {
+  const base = { pay: o.pay, plannedOutputs: o.plannedOutputs };
+  if (!has(o.me) && !has(o.tip) && !has(o.fillTargetId)) return base;
+  const me = typeof o.me === "string" ? o.me.toLowerCase() : "";
+  const target = has(o.fillTargetId) ? String(o.fillTargetId).toLowerCase() : void 0;
+  if (!ADDR.test(me) || !Number.isSafeInteger(o.tip) || o.tip < 0 || target !== void 0 && !HASH.test(target) || !has(o.pay))
+    return "invalid fill inputs: pass me (your 0x address), tip (the chain tip height) and pay together; fillTargetId, when given, is a 0x txid";
+  return { ...base, me, tip: o.tip, fillTargetId: target };
+}
+function judgeFill(rec, proven, served, f) {
+  const str = (v) => typeof v === "string" ? v : void 0;
+  const status = served?.status;
+  const terms = proven.terms;
+  const state = {
+    id: proven.id,
+    seller: proven.seller,
+    give: rec.give,
+    want: { ...rec.want, payto: proven.payto },
+    taker: rec.taker,
+    bid: rec.bid,
+    min: rec.min,
+    status,
+    expiresEpoch: proven.expiresEpoch,
+    height: terms.height,
+    feeBps: terms.feeBps,
+    paid: str(served?.paid),
+    delivered: str(served?.delivered),
+    claimedBy: str(served?.claimedBy),
+    claimUntilHeight: typeof served?.claimUntilHeight === "number" ? served.claimUntilHeight : void 0,
+    claimTxid: str(served?.claimTxid)
+  };
+  const j = { planBound: false };
+  const err = (e) => e?.message ?? String(e);
+  const token = isTokenWant(rec.want);
+  const progress = state.paid !== void 0 && state.delivered !== void 0;
+  if (typeof status === "string" && status !== "open")
+    j.refusal = `the resolver serves this offer as ${status}, not open - refusing (CairnX does not apply a fill of it)`;
+  if (token && has(f.plannedOutputs)) {
+    const legs = bindPlannedSums(f.plannedOutputs, []);
+    if (legs) j.refusal ??= `the offer is token-priced, so a fill moves no CSD: ${legs}`;
+  }
+  if (!has(f.pay)) j.planReason = "no `pay` was given, so no output plan was sized";
+  else if (j.refusal) j.planReason = "the fill is refused, so no output plan was sized";
+  else if (token) j.planReason = "the offer is token-priced: the payment is a token transfer, not CSD outputs";
+  else if (rec.min !== void 0) {
+    j.planReason = "the offer is partially fillable: its running paid/delivered is not provable here (the wallet's fill-SPV sizes it)";
+    if (typeof status === "string" && progress) {
+      try {
+        const p = previewFill(state, f.pay);
+        if (!p.deliverable) j.refusal = `this pay would not deliver against the offer's served progress (${p.reason}) - refusing (the CSD would be lost)`;
+      } catch (e) {
+        j.refusal = `couldn't size the fill against the offer (${err(e)}) - refusing`;
+      }
+    }
+  } else if (typeof status !== "string") j.planReason = "no served offer status: liveness is not provable here, so no output plan was sized (pass the resolver's offer object)";
+  else {
+    try {
+      const plan = fillOutputPlan(state, f.pay);
+      if (plan.kind === "csd-outputs") {
+        j.outputPlan = plan.outputs;
+        if (has(f.plannedOutputs)) {
+          j.refusal = bindPlannedSums(f.plannedOutputs, plan.outputs);
+          j.planBound = true;
+        }
+      } else if (plan.kind === "undeliverable") {
+        j.refusal = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+      } else {
+        j.planReason = `the proven offer settles without CSD outputs (${plan.kind})`;
+      }
+    } catch (e) {
+      j.refusal = `couldn't size the fill against the proven offer (${err(e)}) - refusing rather than sizing from served fields`;
+    }
+  }
+  if (f.me !== void 0 && f.tip !== void 0 && has(f.pay)) {
+    const unplan = () => {
+      delete j.outputPlan;
+      j.planBound = false;
+      j.planReason = "the fill is refused, so no output plan was sized";
+    };
+    if (offerFillTooLate(proven.expiresAt, f.tip)) {
+      j.refusal ??= `the offer's last live block ${proven.expiresAt - 1} leaves less than the ${FILL_TIP_MARGIN}-block cushion above tip ${f.tip}, so the fill is too close to the offer's expiry - do not sign it`;
+      unplan();
+    }
+    if (typeof status !== "string") j.refusal ??= "the fill endorsement needs the resolver's offer object (its status, claim and progress) - pass servedOffer";
+    else if (rec.min !== void 0 && !progress) j.refusal ??= "the served offer is missing paid or delivered (a partial offer's progress) - pass the resolver's full offer object";
+    else {
+      try {
+        const e = fillEndorsement(state, f.me, f.pay, f.tip, f.fillTargetId !== void 0 ? { fillTargetId: f.fillTargetId } : void 0);
+        j.endorsement = { verdict: e.verdict, reason: e.reason };
+        j.fillTarget = fillTargetOf(state, f.tip);
+        if (e.verdict === "refused") {
+          j.refusal ??= `CairnX would refuse this fill (${e.reason}) - do not sign it`;
+          unplan();
+        }
+      } catch (e) {
+        j.refusal ??= `couldn't judge the fill against the offer (${err(e)}) - refusing`;
+        unplan();
+      }
+    }
+  }
+  return j;
 }
 async function preverifyOffer(opts) {
   const id = String(opts.offerId).toLowerCase();
   if (!HASH.test(id)) return { ok: false, trust: "unverified", reason: "invalid offer id" };
+  const fill = fillInputs(opts);
+  if (typeof fill === "string") return { ok: false, trust: "unverified", reason: fill };
   let incl;
   try {
     incl = await opts.light.verifyTxInclusion(id);
@@ -442,8 +548,6 @@ async function preverifyOffer(opts) {
   if (String(provenId).toLowerCase() !== id) return { ok: false, trust: "unverified", reason: "the merkle-proven tx doesn't match the offer id" };
   const app = incl.tx.app;
   if (!app || app.type !== "Propose") return { ok: false, trust: "unverified", reason: "the offer tx is not a Propose" };
-  if (String(app.domain) !== DOMAIN)
-    return { ok: false, trust: "unverified", reason: `the offer tx is not a ${DOMAIN} Propose (wrong settlement domain)` };
   let rec;
   try {
     rec = parseRecord(app.uri, incl.appPayloadHash);
@@ -456,60 +560,23 @@ async function preverifyOffer(opts) {
   const seller = await provenAuthor(opts.client, provenTx);
   if (!seller) return { ok: false, trust: "verified", transient: true, blockHeight, reason: "couldn't prove the offer's on-chain author yet; the chain view may be catching up, try again" };
   const offerRec = rec;
+  const ee = app.expires_epoch;
+  const refusal = provenOfferRefusal(offerRec, { domain: String(app.domain), height: blockHeight, expiresEpoch: typeof ee === "bigint" ? ee : Number(ee), seller });
+  if (refusal) return { ok: false, trust: "verified", blockHeight, reason: `CairnX rejects this offer (${refusal}) - a fill would move CSD for nothing` };
   const w = rec.want ?? {};
   const payto = w.payto && ADDR.test(String(w.payto).toLowerCase()) ? String(w.payto).toLowerCase() : seller;
   const terms = provenOfferTerms(offerRec, blockHeight);
-  if (payto === TREASURY_ADDR)
-    return { ok: false, trust: "verified", blockHeight, reason: "the offer's payment recipient is the protocol treasury - the chain rejects it, and a fill would move CSD for nothing" };
-  const provenExpiresEpoch = Number(app.expires_epoch);
-  if (!Number.isSafeInteger(provenExpiresEpoch) || epochOf(blockHeight) > provenExpiresEpoch)
-    return { ok: false, trust: "verified", blockHeight, reason: "the offer was already expired when it was mined - the chain rejects it, and a fill would move CSD for nothing" };
-  let outputPlan;
-  let sumsMismatch;
-  let planReason;
-  let planBound = false;
-  const has = (v) => v !== void 0 && v !== null;
-  const servedStatus = opts.servedOffer?.status;
-  if (!has(opts.pay)) planReason = "no `pay` was given, so no output plan was sized";
-  else if (isTokenWant(offerRec.want)) planReason = "the offer is token-priced: the payment is a token transfer, not CSD outputs";
-  else if (offerRec.min !== void 0) planReason = "the offer is partially fillable: its running paid/delivered is not provable here (the wallet's fill-SPV sizes it)";
-  else if (typeof servedStatus !== "string") planReason = "no served offer status: liveness is not provable here, so no output plan was sized (pass the resolver's offer object)";
-  else {
-    const provenState = {
-      id,
-      seller,
-      give: offerRec.give,
-      want: { ...offerRec.want, payto },
-      taker: offerRec.taker,
-      bid: offerRec.bid,
-      status: servedStatus,
-      expiresEpoch: 0,
-      height: blockHeight,
-      feeBps: terms.feeBps
-    };
-    try {
-      const plan = fillOutputPlan(provenState, opts.pay);
-      if (plan.kind === "csd-outputs") {
-        outputPlan = plan.outputs;
-        if (has(opts.plannedOutputs)) {
-          sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
-          planBound = true;
-        }
-      } else if (plan.kind === "undeliverable") {
-        sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
-      } else {
-        planReason = `the proven offer settles without CSD outputs (${plan.kind})`;
-      }
-    } catch (e) {
-      sumsMismatch = `couldn't size the fill against the proven offer (${e?.message ?? e}) - refusing rather than sizing from served fields`;
-    }
-  }
+  const expiresEpoch = Number(ee);
+  const expiresAt = offerExpiryHeightOf(expiresEpoch, blockHeight);
+  const j = judgeFill(offerRec, { id, seller, payto, terms, expiresEpoch, expiresAt }, opts.servedOffer, fill);
   const planFields = {
-    ...outputPlan ? { outputPlan } : {},
-    ...has(opts.plannedOutputs) ? { planBound } : {},
-    ...!outputPlan && planReason && (has(opts.pay) || has(opts.plannedOutputs)) ? { planReason } : {}
+    ...j.outputPlan ? { outputPlan: j.outputPlan } : {},
+    ...has(opts.pay) ? { sized: j.outputPlan !== void 0 } : {},
+    ...has(opts.plannedOutputs) ? { planBound: j.planBound } : {},
+    ...!j.outputPlan && j.planReason && (has(opts.pay) || has(opts.plannedOutputs)) ? { planReason: j.planReason } : {},
+    ...j.endorsement ? { endorsement: j.endorsement, fillTarget: j.fillTarget } : {}
   };
-  const base = { payto, seller, terms, blockHeight, ...planFields };
+  const base = { payto, seller, terms, blockHeight, expiresEpoch, expiresAt, ...planFields };
   if (opts.servedOffer !== void 0 && opts.servedOffer !== null) {
     const so = opts.servedOffer;
     if (so?.want?.payto === void 0 || so?.want?.payto === null)
@@ -520,12 +587,10 @@ async function preverifyOffer(opts) {
       return { ok: false, trust: "verified", reason: "the served offer is missing seller (the rebate recipient) - pass the resolver's full offer object, or omit servedOffer", ...base };
     if (String(so.seller).toLowerCase() !== seller)
       return { ok: false, trust: "verified", reason: "the served seller doesn't match the offer's on-chain author (a lying resolver may be redirecting your payment)", ...base };
-    if (isTokenWant(offerRec.want) && (String(so?.want?.ticker) !== String(offerRec.want.ticker) || String(so?.want?.amount) !== String(offerRec.want.amount)))
-      return { ok: false, trust: "verified", reason: "the served want ticker/amount don't match the offer's on-chain record (a lying resolver could bait-and-switch the token price)", ...base };
     if (bindOfferTerms(opts.servedOffer, terms, { give: true, wantType: true }))
-      return { ok: false, trust: "verified", reason: "the served terms don't match the offer's on-chain record (fee, rebate, partial sizing, the give, or the want type - a lying resolver could mis-size or re-route the fill, redirecting or burning your payment)", ...base };
+      return { ok: false, trust: "verified", reason: "the served terms don't match the offer's on-chain record (fee, rebate, partial sizing, the give, or the want's type or token price - a lying resolver could mis-size, re-price or re-route the fill, redirecting or burning your payment)", ...base };
   }
-  if (sumsMismatch) return { ok: false, trust: "verified", reason: sumsMismatch, ...base };
+  if (j.refusal) return { ok: false, trust: "verified", reason: j.refusal, ...base };
   return { ok: true, trust: "verified", ...base };
 }
 
@@ -546,6 +611,20 @@ var spvBackoffMs = (attempt) => Math.min(4e3, 700 * (attempt + 1));
 var SPV_RETRY_WAIT_BUDGET_MS = 16e3;
 var SPV_RECHECK_DEPTH = 12;
 var spvTipOf = (lc) => lc.baseHeight + lc.chain.length - 1;
+var SPV_BEYOND_TIP = /^tx at \d+ is \d+ blocks beyond tip; sync\(\d+\) first$/;
+var SpvLightClient = class extends LightClient {
+  syncInFlight = null;
+  async sync(to, from) {
+    while (this.syncInFlight) await this.syncInFlight;
+    const run = super.sync(to, from);
+    this.syncInFlight = run;
+    try {
+      return await run;
+    } finally {
+      if (this.syncInFlight === run) this.syncInFlight = null;
+    }
+  }
+};
 var Cairn = class {
   config;
   chain;
@@ -561,6 +640,9 @@ var Cairn = class {
   // syncFromCheckpoint calls onto the same client (the loser would hit "seedTrusted must be called on a
   // fresh client"). Cleared when the seed settles; a failure leaves no cached state, so the next call retries.
   _spvSeedInflight = null;
+  // The in-flight reseed of withSpvReseed, shared by callers whose structural failures overlap. Cleared when it
+  // settles; each caller still commits the fresh client only after its own retry succeeds.
+  _spvReseedInflight = null;
   _spvCp;
   // W12: the cairn base the SPV header-batch provider fetches /api/headers from (same base the rest of the SDK uses).
   _cairnBase;
@@ -616,14 +698,18 @@ var Cairn = class {
   // (rate limit / gateway / timeout / non-dense / CF 200-HTML) keeps the cache and rethrows: wiping
   // on those turns one /api/headers 429 into a reseed storm (DOS-HDR-3). A second structural
   // failure propagates fail-closed; there is no loop. recheckCachedHeader feeds this path: a near-tip
-  // cached header that the served chain no longer carries is a structural failure.
+  // cached header that the served chain no longer carries is a structural failure. Callers whose failures overlap
+  // (waiters on one shared sync) share one reseed.
   async withSpvReseed(op) {
     const lc = await this.seededSpvLight();
     try {
       return await op(lc);
     } catch (e) {
       if (spvIsTransient(e)) throw e;
-      const fresh = await this.seedFreshSpvLight();
+      this._spvReseedInflight ??= this.seedFreshSpvLight().finally(() => {
+        this._spvReseedInflight = null;
+      });
+      const fresh = await this._spvReseedInflight;
       const out = await op(fresh);
       this._spvLight = fresh;
       return out;
@@ -643,7 +729,7 @@ var Cairn = class {
   // the caller commits the result only on success (MF-14; the wallet G8 posture - never null or
   // dirty the shared field while an attempt is in flight).
   async seedFreshSpvLight() {
-    const lc = new LightClient({
+    const lc = new SpvLightClient({
       client: this.chain.client,
       checkpoints: { [this._spvCp.height]: this._spvCp.hash },
       headersBatchProvider: (from, count) => this.fetchHeadersBatch(from, count)
@@ -685,11 +771,7 @@ var Cairn = class {
    * data-availability hiccup; back off (honouring Retry-After) a bounded number of times, then THROW so
    * `sync()` fails closed. A non-dense range is rejected terminally (never retried).
    *
-   * B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
-   * mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
-   * cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
-   * restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
-   * once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
+   * Cross-origin reach depends on the server's CORS mount on `/api/headers` (the cairn server mounts one).
    */
   async fetchHeadersBatch(from, count) {
     const g = this.config.fetch ?? globalThis.fetch;
@@ -737,7 +819,8 @@ var Cairn = class {
    * commitment, derives the payment recipient + seller from the offer's on-chain AUTHOR (the funding input's
    * prevout owner, txid-committed, NOT the malleable scriptSig), and, if you pass the resolver-SERVED `offer`
    * object, binds its payto/seller + fee/rebate/partial terms to the proven ones. Returns a TRUST-LABELED result
-   * (fail-closed on a positive mismatch, fail-soft `transient` on a lagging / below-checkpoint chain view).
+   * (fail-closed on a positive mismatch; `transient` on a lagging chain view; final, naming the anchor, for an
+   * offer mined below the SPV checkpoint).
    *
    * This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
    * fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
@@ -745,19 +828,44 @@ var Cairn = class {
    *
    * Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
    * non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
-   * EXACTLY the outputPlan, never resolver-served outputs.
+   * EXACTLY the outputPlan, never resolver-served outputs. Pass opts.me (your address) and opts.tip (the chain tip
+   * height) with pay to have cairnx-core's fillEndorsement and offerFillTooLate judge the fill for you at that tip; without them `ok`
+   * says the offer record is proven, not that you can fill it now.
    */
   async verifyOfferForFill(offerId, servedOffer, opts) {
     const light = {
       verifyTxInclusion: (txidHex) => this.withSpvReseed(async (lc) => {
         const haveTo = spvTipOf(lc);
-        const r = await lc.verifyTxInclusion(txidHex);
-        if (r.trustLevel === "verified-inclusion" && typeof r.blockHeight === "number" && r.blockHeight <= haveTo)
-          await this.recheckCachedHeader(lc, r.blockHeight, haveTo);
-        return r;
+        let r = await lc.verifyTxInclusion(txidHex);
+        if (r.trustLevel === "rpc-trusted" && SPV_BEYOND_TIP.test(r.reason ?? "")) {
+          let tipHeight;
+          try {
+            tipHeight = Number((await this.chain.tip()).height);
+          } catch (e) {
+            return { ...r, reason: `${r.reason} (the node tip read failed: ${e?.message ?? e})` };
+          }
+          if (Number.isSafeInteger(tipHeight) && tipHeight > spvTipOf(lc)) await lc.sync(tipHeight);
+          r = await lc.verifyTxInclusion(txidHex);
+        }
+        if (r.trustLevel !== "verified-inclusion") return r;
+        const height = Number(r.blockHeight);
+        if (!Number.isSafeInteger(height))
+          return { trustLevel: "rpc-trusted", included: false, reason: `the node's containing height for this tx is not a block height (${String(r.blockHeight)})` };
+        if (height <= haveTo) await this.recheckCachedHeader(lc, height, haveTo);
+        return { ...r, blockHeight: height };
       })
     };
-    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer, pay: opts?.pay, plannedOutputs: opts?.plannedOutputs });
+    return preverifyOffer({
+      light,
+      client: this.chain.client,
+      offerId,
+      servedOffer,
+      pay: opts?.pay,
+      plannedOutputs: opts?.plannedOutputs,
+      me: opts?.me,
+      tip: opts?.tip,
+      fillTargetId: opts?.fillTargetId
+    });
   }
   /**
    * Detect + connect the Cairn Wallet (browser only) and attach it as `cairn.wallet`.

package/dist/indexer.cjs

@@ -24,8 +24,81 @@ __export(indexer_exports, {
 });
 module.exports = __toCommonJS(indexer_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
+
+// src/errors.ts
+var SDK_VERSION = "0.8.2";
+var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
+var CairnError = class extends Error {
+  /** Stable machine code for programmatic branching. */
+  code;
+  /** The human message without the appended docs/version footer. */
+  shortMessage;
+  /** Relative docs path (under the SDK docs base), if any. */
+  docsPath;
+  /** The cairn-sdk version that produced this error. */
+  version = SDK_VERSION;
+  /**
+   * Whether a dApp may safely AUTO-retry this failure. `false` for fund-safety refusals and user-intent
+   * declines (the default); `true` only for provably transient infra faults where nothing was signed.
+   * A `SubmitInFlightError` is `false` too: reconcile its `txid`, never blind-retry.
+   */
+  retryable;
+  constructor(shortMessage, opts = {}) {
+    const docs = opts.docsPath;
+    super(
+      [shortMessage, docs ? `Docs: ${DOCS_BASE}${docs}` : "", `Version: cairn-sdk@${SDK_VERSION}`].filter(Boolean).join("\n"),
+      { cause: opts.cause }
+    );
+    this.name = new.target.name;
+    this.code = opts.code ?? "UNKNOWN";
+    this.shortMessage = shortMessage;
+    this.docsPath = docs;
+    this.retryable = opts.retryable ?? false;
+  }
+  /**
+   * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
+   * returns the DEEPEST cause (the root). Mirrors viem's `BaseError.walk()`.
+   */
+  walk(fn) {
+    let current = this;
+    let last = this;
+    while (current != null) {
+      if (fn && fn(current)) return current;
+      last = current;
+      current = current?.cause;
+    }
+    return fn ? null : last;
+  }
+};
+var HttpError = class extends CairnError {
+  status;
+  url;
+  body;
+  constructor(status, url, body) {
+    super(`HTTP ${status} for ${url}${body ? `: ${String(body).slice(0, 200)}` : ""}`, { code: "HTTP_ERROR" });
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+};
+
+// src/indexer.ts
 var HEX64 = /^0x[0-9a-fA-F]{64}$/;
 var MAX_SSE_BUF = 1024 * 1024;
+var UTXO_PAGE = 1e3;
+var UTXO_MAX_PAGES = 100;
+var UTXO_CURSOR = /^\d{1,16}:0x[0-9a-fA-F]{64}:\d{1,10}$/;
+function utxoCursor(row) {
+  const r = row;
+  const c = `${String(r?.status?.block_height)}:${String(r?.txid)}:${String(r?.vout)}`;
+  return UTXO_CURSOR.test(c) ? c : null;
+}
+function cursorAfter(a, b) {
+  const [ha, ta, va] = a.split(":"), [hb, tb, vb] = b.split(":");
+  if (Number(ha) !== Number(hb)) return Number(ha) > Number(hb);
+  if (ta.toLowerCase() !== tb.toLowerCase()) return ta.toLowerCase() > tb.toLowerCase();
+  return Number(va) > Number(vb);
+}
 function isValidMerkleProof(p) {
   if (!p || typeof p !== "object") return false;
   const m = p;
@@ -75,8 +148,29 @@ var IndexerClient = class {
   addressTxs(a) {
     return this.http.getJson(`/address/${encodeURIComponent(a)}/txs`);
   }
-  addressUtxo(a) {
-    return this.http.getJson(`/address/${encodeURIComponent(a)}/utxo`);
+  /** Every unspent output of an address. The indexer answers in pages of at most 1,000 rows; this follows its
+   *  `?after=` cursor until a short page, reading at most 100 pages: when the 100th is full (100,000 or more
+   *  outputs) it throws HttpError instead. An indexer that predates paging answers the whole set at once. */
+  async addressUtxo(a) {
+    const path = `/address/${encodeURIComponent(a)}/utxo`;
+    const first = await this.http.getJson(path);
+    if (!Array.isArray(first) || first.length !== UTXO_PAGE) return first;
+    const out = [...first];
+    let page = first;
+    let prev = null;
+    for (let pages = 1; page.length === UTXO_PAGE; pages++) {
+      if (pages === UTXO_MAX_PAGES)
+        throw new HttpError(200, this.http.url(path), `too many unspent outputs: addressUtxo reads at most ${UTXO_MAX_PAGES} pages of ${UTXO_PAGE} rows, and page ${UTXO_MAX_PAGES} is full`);
+      const after = utxoCursor(page[UTXO_PAGE - 1]);
+      if (!after) throw new HttpError(200, this.http.url(path), "malformed response: a utxo row has no block_height, txid and vout to page from");
+      if (prev !== null && !cursorAfter(after, prev)) throw new HttpError(200, this.http.url(path, { after }), "malformed response: the utxo pages do not advance");
+      page = await this.http.getJson(path, { after });
+      if (!Array.isArray(page)) throw new HttpError(200, this.http.url(path, { after }), "malformed response: a utxo page is not an array");
+      if (prev === null && page.length > 0 && utxoCursor(page[0]) === utxoCursor(first[0])) return first;
+      prev = after;
+      out.push(...page);
+    }
+    return out;
   }
   reputation(a) {
     return this.http.getJson(`/address/${encodeURIComponent(a)}/reputation`);
@@ -95,7 +189,8 @@ var IndexerClient = class {
   }
   // ---- trust-minimized inclusion ----------------------------------------
   /**
-   * Verify a tx is included in a block by folding its merkle branch to the root
+   * Verify that `txid` is a node of a block's merkle tree (an inner node or the root folds too, so pass an id you
+   * hashed from a transaction body you hold) by folding its merkle branch to the root
    * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
    * proof's root is cross-checked against the header merkle at that height →
    * trustLevel "verified-inclusion" (only as trustworthy as that header source —

package/dist/indexer.d.cts

@@ -62,6 +62,9 @@ declare class IndexerClient {
     txMerkleProof(id: string): Promise<MerkleProof>;
     address(a: string): Promise<unknown>;
     addressTxs(a: string): Promise<unknown[]>;
+    /** Every unspent output of an address. The indexer answers in pages of at most 1,000 rows; this follows its
+     *  `?after=` cursor until a short page, reading at most 100 pages: when the 100th is full (100,000 or more
+     *  outputs) it throws HttpError instead. An indexer that predates paging answers the whole set at once. */
     addressUtxo(a: string): Promise<unknown[]>;
     reputation(a: string): Promise<unknown>;
     domains(): Promise<unknown[]>;
@@ -69,7 +72,8 @@ declare class IndexerClient {
     proposal(id: string): Promise<unknown>;
     attestations(id: string): Promise<unknown[]>;
     /**
-     * Verify a tx is included in a block by folding its merkle branch to the root
+     * Verify that `txid` is a node of a block's merkle tree (an inner node or the root folds too, so pass an id you
+     * hashed from a transaction body you hold) by folding its merkle branch to the root
      * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
      * proof's root is cross-checked against the header merkle at that height →
      * trustLevel "verified-inclusion" (only as trustworthy as that header source —

package/dist/indexer.d.ts

@@ -62,6 +62,9 @@ declare class IndexerClient {
     txMerkleProof(id: string): Promise<MerkleProof>;
     address(a: string): Promise<unknown>;
     addressTxs(a: string): Promise<unknown[]>;
+    /** Every unspent output of an address. The indexer answers in pages of at most 1,000 rows; this follows its
+     *  `?after=` cursor until a short page, reading at most 100 pages: when the 100th is full (100,000 or more
+     *  outputs) it throws HttpError instead. An indexer that predates paging answers the whole set at once. */
     addressUtxo(a: string): Promise<unknown[]>;
     reputation(a: string): Promise<unknown>;
     domains(): Promise<unknown[]>;
@@ -69,7 +72,8 @@ declare class IndexerClient {
     proposal(id: string): Promise<unknown>;
     attestations(id: string): Promise<unknown[]>;
     /**
-     * Verify a tx is included in a block by folding its merkle branch to the root
+     * Verify that `txid` is a node of a block's merkle tree (an inner node or the root folds too, so pass an id you
+     * hashed from a transaction body you hold) by folding its merkle branch to the root
      * with csd-codec.verifyMerkleProof. If `headerMerkleAt` was provided, the
      * proof's root is cross-checked against the header merkle at that height →
      * trustLevel "verified-inclusion" (only as trustworthy as that header source —

package/dist/indexer.js

@@ -1,6 +1,7 @@
 import {
   IndexerClient
-} from "./chunk-CI7YODPP.js";
+} from "./chunk-NRCTL7OI.js";
+import "./chunk-37OHCH7R.js";
 export {
   IndexerClient
 };