@inversealtruism/cairn-sdk 0.8.0 → 0.8.2

package/README.md

@@ -5,7 +5,7 @@ The **Compute Substrate dApp kit:** one cohesive toolkit for building apps on CS
 | | |
 |---|---|
 | `cairn.wallet` | Connect the **Cairn Wallet**, sign things (clear-signed approvals). The key never leaves the extension. |
-| `cairn.chain` | Node RPC + transaction builders + a verifying **light client** (re-exports the `csd-*` primitives). |
+| `cairn.chain` | Node RPC + transaction builders + the **light client** primitives (re-exports the `csd-*` primitives). |
 | `cairn.index` | The L2 **explorer/indexer**: REST + merkle proofs + live SSE/WS feeds. |
 | `cairn.content` | **Self-certifying content:** hash for an on-chain Propose, fetch with client-side verification. |
 | `cairn.names` | **.csd names + CairnX reads:** name resolution, reverse/primary lookup, tokens, offers, bids, canonical state. |
@@ -56,13 +56,13 @@ try {
 
 ## API by namespace
 
-**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `domains()/domainProposals(domain)`, `proposal()/attestations()`, `reputation()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
+**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()` (every unspent output, read in pages of 1,000 up to 100 pages; a full 100th page throws `HttpError`), `domains()/domainProposals(domain)`, `proposal()/attestations()`, `reputation()`, **`verifyInclusion(txid)`** (proves `txid` is a node of a PoW-verified block's merkle tree; an inner node or a block's root folds too, so hash the transaction body you hold to get the id, see the guide), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
 
 **`cairn.names`:** `resolve(name)` (display-path name to address), `name(name)`/`nameHistory(name)`, `primary(addr)` (reverse lookup)/`namesOf(addr)`, `names()`, `tokens()/token(ticker)`, `offers()`/`bids()` (open rows by default; pass `{ status }` for another status, or `{ status: "all" }` for every row), `state()` (the canonical CairnX state). Reads go through the public `/trade/api/cairnx/*` proxy; for payment-grade name resolution verify through the wallet or a replaying resolver, not a bare read (see `src/names.ts` header).
 
 **`cairn.content`:** `prepare(obj)`/`put(obj)` → `{ payloadHash, canonical, bytes }`; `get(hash)` / `getBytes(hash)` (fetch **and verify** `sha256(bytes) === hash`, throws `ContentVerificationError` on tamper); `hash(obj)`.
 
-**`cairn.chain`:** `tip()`, `utxos(addr)`, `submit(nodeJsonTx)`, `.client` (full `CsdClient`), `.light()` (verifying light client). The package also re-exports the primitives under the `/chain` subpath: `buildSend/buildPropose/buildAttest`, `signTx`, `keygen`, `payloadHash`, `verifyMerkleProof`, `LightClient`, etc.
+**`cairn.chain`:** `tip()`, `utxos(addr)`, `submit(nodeJsonTx)`, `.client` (full `CsdClient`), `.light()` (a `LightClient` over the same RPC with no checkpoint and no batch header source: it proves nothing until seeded, and a sync from it reads one block per height through the RPC; for verified reads use `cairn.index.verifyInclusion()` and `cairn.verifyOfferForFill()`, which run the facade's light client seeded from `DEFAULT_SPV_CHECKPOINT`, or build your own `new LightClient({ client, checkpoints, headersBatchProvider })` from a pinned checkpoint). The package also re-exports the primitives under the `/chain` subpath: `buildSendVerified/buildProposeVerified/buildAttestVerified` (they check each input's value against its source transaction; use them over the bare `buildSend/buildPropose/buildAttest` with any RPC you do not run), `signTx`, `keygen`, `payloadHash`, `verifyMerkleProof`, `LightClient`, etc.
 
 Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,indexer,content,chain,controller,react}`.
 

package/dist/chain.cjs

@@ -27,7 +27,9 @@ __export(chain_exports, {
   addrFromPriv: () => import_csd_crypto.addrFromPriv,
   addrFromPub: () => import_csd_crypto.addrFromPub,
   buildAttest: () => import_csd_tx.buildAttest,
+  buildAttestVerified: () => import_csd_tx.buildAttestVerified,
   buildPropose: () => import_csd_tx.buildPropose,
+  buildProposeVerified: () => import_csd_tx.buildProposeVerified,
   buildSend: () => import_csd_tx.buildSend,
   buildSendVerified: () => import_csd_tx.buildSendVerified,
   canonicalJson: () => import_csd_codec.canonicalJson,
@@ -74,6 +76,69 @@ var import_csd_client2 = require("@inversealtruism/csd-client");
 var import_csd_light2 = require("@inversealtruism/csd-light");
 var import_csd_tx2 = require("@inversealtruism/csd-tx");
 var import_csd_crypto2 = require("@inversealtruism/csd-crypto");
+
+// 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 SubmitInFlightError = class extends CairnError {
+  /** The locally-computed consensus txid to reconcile against the chain (undefined when it is not known). */
+  txid;
+  /** The signed transaction, set only when `Chain.send` threw this (a wallet write keeps it in the wallet).
+   *  `chain.submit(nodeJson)` resends it unchanged: the same coins under the same txid, so it cannot pay twice,
+   *  where a new send may select other coins. */
+  nodeJson;
+  /** Always true: the tx MAY be in the mempool. Reconcile via `txid` or the balance; never blind-retry. */
+  maybeSent = true;
+  constructor(message, code, txid2, cause, nodeJson) {
+    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false, cause });
+    this.txid = txid2;
+    this.nodeJson = nodeJson;
+  }
+};
+
+// src/chain.ts
 var Chain = class {
   client;
   opts;
@@ -100,7 +165,11 @@ var Chain = class {
    * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
    * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
    * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
-   * `broadcast:false` to get the signed tx back without submitting.
+   * `broadcast:false` to get the signed tx back without submitting. A submit request that fails after signing
+   * throws a `SubmitInFlightError` carrying the signed `txid` and `nodeJson`: the node may have taken it, so check
+   * before resending, and resend that `nodeJson` with `submit` rather than a new send. A 4xx answer (a proxy's
+   * body cap or rate limit, or the node refusing the request) broadcast nothing and throws a final `CairnError`
+   * with code `SUBMIT_REJECTED`.
    */
   async send(p) {
     const from = (0, import_csd_crypto2.addrFromPriv)(p.priv);
@@ -114,10 +183,19 @@ var Chain = class {
       verify: (inputs) => (0, import_csd_client2.verifyInputValues)(this.client, inputs)
     });
     if (!built.ok || p.broadcast === false) return built;
-    const submitResult = await this.client.submit(built.nodeJson);
+    let submitResult;
+    try {
+      submitResult = await this.client.submit(built.nodeJson);
+    } catch (e) {
+      const what = e?.message ?? String(e);
+      if (e?.terminal === true)
+        throw new CairnError(`the submit request was refused (${what}), so nothing was broadcast; a 400 or 413 from a proxy is usually its request body cap (a transaction with many inputs), a 429 its rate limit`, { code: "SUBMIT_REJECTED", cause: e });
+      throw new SubmitInFlightError(`the submit request failed after signing (${what}); the node may have taken the transaction, so check ${built.txid} before sending again`, "SUBMIT_MAYBE_INFLIGHT", built.txid, e, built.nodeJson);
+    }
     return { ...built, ok: built.ok && submitResult.ok !== false, submitResult };
   }
-  /** A verifying light client over the same RPC (built once, reused). */
+  /** A light client over the same RPC (built once, reused), with no checkpoint and no batch header provider: it proves
+   *  nothing until seeded. The facade's seeded client backs `cairn.index.verifyInclusion` and `verifyOfferForFill`. */
   light() {
     if (!this._light) {
       this._light = new import_csd_light2.LightClient({ client: this.client });
@@ -134,7 +212,9 @@ var Chain = class {
   addrFromPriv,
   addrFromPub,
   buildAttest,
+  buildAttestVerified,
   buildPropose,
+  buildProposeVerified,
   buildSend,
   buildSendVerified,
   canonicalJson,

package/dist/chain.d.cts

@@ -2,7 +2,7 @@ import * as _inversealtruism_csd_client from '@inversealtruism/csd-client';
 import { CsdClient } from '@inversealtruism/csd-client';
 export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx, verifyInputValues } from '@inversealtruism/csd-client';
 import { BuildResult } from '@inversealtruism/csd-tx';
-export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
+export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildAttestVerified, buildPropose, buildProposeVerified, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
 export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb, headerHash, hx, merkleBranch, merkleRoot, payloadHash, serialize, sha256d, sighash, strip0x, strippedTx, txid, verifyContentBytes, verifyMerkleProof } from '@inversealtruism/csd-codec';
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
@@ -17,7 +17,7 @@ interface ChainOptions {
 }
 /**
  * Convenience handle over a CSD node RPC. `client` is the full typed RPC client;
- * `light()` lazily builds a verifying light client over the same endpoint.
+ * `light()` lazily builds an unseeded light client over the same endpoint.
  */
 declare class Chain {
     readonly client: CsdClient;
@@ -36,7 +36,11 @@ declare class Chain {
      * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
      * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
      * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
-     * `broadcast:false` to get the signed tx back without submitting.
+     * `broadcast:false` to get the signed tx back without submitting. A submit request that fails after signing
+     * throws a `SubmitInFlightError` carrying the signed `txid` and `nodeJson`: the node may have taken it, so check
+     * before resending, and resend that `nodeJson` with `submit` rather than a new send. A 4xx answer (a proxy's
+     * body cap or rate limit, or the node refusing the request) broadcast nothing and throws a final `CairnError`
+     * with code `SUBMIT_REJECTED`.
      */
     send(p: {
         priv: string;
@@ -50,7 +54,8 @@ declare class Chain {
     }): Promise<BuildResult & {
         submitResult?: _inversealtruism_csd_client.RpcSubmit;
     }>;
-    /** A verifying light client over the same RPC (built once, reused). */
+    /** A light client over the same RPC (built once, reused), with no checkpoint and no batch header provider: it proves
+     *  nothing until seeded. The facade's seeded client backs `cairn.index.verifyInclusion` and `verifyOfferForFill`. */
     light(): LightClient;
 }
 

package/dist/chain.d.ts

@@ -2,7 +2,7 @@ import * as _inversealtruism_csd_client from '@inversealtruism/csd-client';
 import { CsdClient } from '@inversealtruism/csd-client';
 export { ClientOptions, CsdClient, RpcBlock, RpcHeaderJson, RpcSubmit, RpcTip, RpcTxJson, RpcUtxo, RpcUtxos, rpcHeaderToHeader, rpcTxToTx, verifyInputValues } from '@inversealtruism/csd-client';
 import { BuildResult } from '@inversealtruism/csd-tx';
-export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildPropose, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
+export { BuildResult, InputVerifier, Selection, Signed, Utxo, buildAttest, buildAttestVerified, buildPropose, buildProposeVerified, buildSend, buildSendVerified, selectInputs, signTx, txSize, txToNodeJson } from '@inversealtruism/csd-tx';
 export { App, BlockHeader, Tx, TxInput, TxOutput, canonicalJson, deserialize, hb, headerHash, hx, merkleBranch, merkleRoot, payloadHash, serialize, sha256d, sighash, strip0x, strippedTx, txid, verifyContentBytes, verifyMerkleProof } from '@inversealtruism/csd-codec';
 export { ADDR_RE, addrFromPriv, addrFromPub, hash160, isValidAddr, isValidPriv, keygen, pubFromPriv, randomNonce, signDigest, verifyDigest } from '@inversealtruism/csd-crypto';
 import { LightClient } from '@inversealtruism/csd-light';
@@ -17,7 +17,7 @@ interface ChainOptions {
 }
 /**
  * Convenience handle over a CSD node RPC. `client` is the full typed RPC client;
- * `light()` lazily builds a verifying light client over the same endpoint.
+ * `light()` lazily builds an unseeded light client over the same endpoint.
  */
 declare class Chain {
     readonly client: CsdClient;
@@ -36,7 +36,11 @@ declare class Chain {
      * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
      * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
      * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
-     * `broadcast:false` to get the signed tx back without submitting.
+     * `broadcast:false` to get the signed tx back without submitting. A submit request that fails after signing
+     * throws a `SubmitInFlightError` carrying the signed `txid` and `nodeJson`: the node may have taken it, so check
+     * before resending, and resend that `nodeJson` with `submit` rather than a new send. A 4xx answer (a proxy's
+     * body cap or rate limit, or the node refusing the request) broadcast nothing and throws a final `CairnError`
+     * with code `SUBMIT_REJECTED`.
      */
     send(p: {
         priv: string;
@@ -50,7 +54,8 @@ declare class Chain {
     }): Promise<BuildResult & {
         submitResult?: _inversealtruism_csd_client.RpcSubmit;
     }>;
-    /** A verifying light client over the same RPC (built once, reused). */
+    /** A light client over the same RPC (built once, reused), with no checkpoint and no batch header provider: it proves
+     *  nothing until seeded. The facade's seeded client backs `cairn.index.verifyInclusion` and `verifyOfferForFill`. */
     light(): LightClient;
 }
 

package/dist/chain.js

@@ -6,7 +6,9 @@ import {
   addrFromPriv,
   addrFromPub,
   buildAttest,
+  buildAttestVerified,
   buildPropose,
+  buildProposeVerified,
   buildSend,
   buildSendVerified,
   canonicalJson,
@@ -42,7 +44,8 @@ import {
   verifyDigest,
   verifyInputValues,
   verifyMerkleProof
-} from "./chunk-C452UODV.js";
+} from "./chunk-IPBMMJ3Z.js";
+import "./chunk-37OHCH7R.js";
 export {
   ADDR_RE,
   Chain,
@@ -51,7 +54,9 @@ export {
   addrFromPriv,
   addrFromPub,
   buildAttest,
+  buildAttestVerified,
   buildPropose,
+  buildProposeVerified,
   buildSend,
   buildSendVerified,
   canonicalJson,

package/dist/{chunk-DTPADO7N.js → chunk-2RR4ZJPQ.js}

@@ -1,7 +1,7 @@
 import {
   CairnError,
   ContentVerificationError
-} from "./chunk-UAPWZZQK.js";
+} from "./chunk-37OHCH7R.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";

package/dist/{chunk-UAPWZZQK.js → chunk-37OHCH7R.js}

@@ -1,5 +1,5 @@
 // src/errors.ts
-var SDK_VERSION = "0.8.0";
+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. */
@@ -82,17 +82,22 @@ var ContentVerificationError = class extends CairnError {
   }
 };
 var SubmitInFlightError = class extends CairnError {
-  /** The locally-computed consensus txid to reconcile against the chain (may be undefined if the wallet omitted it). */
+  /** The locally-computed consensus txid to reconcile against the chain (undefined when it is not known). */
   txid;
-  /** Always true: the tx MAY be in the mempool. Reconcile via `txid`; never blind-retry. */
+  /** The signed transaction, set only when `Chain.send` threw this (a wallet write keeps it in the wallet).
+   *  `chain.submit(nodeJson)` resends it unchanged: the same coins under the same txid, so it cannot pay twice,
+   *  where a new send may select other coins. */
+  nodeJson;
+  /** Always true: the tx MAY be in the mempool. Reconcile via `txid` or the balance; never blind-retry. */
   maybeSent = true;
-  constructor(message, code, txid) {
-    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false });
+  constructor(message, code, txid, cause, nodeJson) {
+    super(message, { code, docsPath: "/errors#submit-inflight", retryable: false, cause });
     this.txid = txid;
+    this.nodeJson = nodeJson;
   }
 };
 var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
-var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN", "WALLET_UNAVAILABLE", "REVIEW_REQUIRED"]);
+var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN", "WALLET_UNAVAILABLE", "REVIEW_REQUIRED", "SEAL_NOT_MINED"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
   "FILL_WRONG_TARGET",
@@ -114,7 +119,9 @@ var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "OFFER_SOURCE_CONFLICT",
   "FILL_LEGACY_SUNSET",
   "VERIFY_HORIZON",
-  "VERIFY_UNREPRESENTABLE"
+  "VERIFY_UNREPRESENTABLE",
+  "RESERVATION_DENIED",
+  "RPC_BLOCK_MISMATCH"
 ]);
 function mapProviderError(error, code) {
   if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
@@ -132,11 +139,15 @@ function mapProviderError(error, code) {
 function mapSubmitResultError(result) {
   const code = result?.code;
   const msg = typeof result?.error === "string" && result.error || code || "The wallet refused the transaction.";
-  if (code === "SUBMIT_MAYBE_INFLIGHT" || code === "SUBMIT_DUPLICATE") {
+  if (code === "SUBMIT_MAYBE_INFLIGHT" || code === "SUBMIT_DUPLICATE" || code === "WALLET_UNAVAILABLE") {
     return new SubmitInFlightError(msg, code, typeof result?.txid === "string" ? result.txid : void 0);
   }
   return mapProviderError(msg, code);
 }
+function mapWriteProviderError(error, code) {
+  if (code === "WALLET_UNAVAILABLE") return new SubmitInFlightError(error || code, code);
+  return mapProviderError(error, code);
+}
 function errorCode(err) {
   return err instanceof CairnError ? err.code : "UNKNOWN";
 }
@@ -153,5 +164,6 @@ export {
   SubmitInFlightError,
   mapProviderError,
   mapSubmitResultError,
+  mapWriteProviderError,
   errorCode
 };

package/dist/{chunk-JXBO4LV6.js → chunk-AHPXOYCC.js}

@@ -1,6 +1,6 @@
 import {
   getWallet
-} from "./chunk-WWO3FXHG.js";
+} from "./chunk-EVEBQSDK.js";
 
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });

package/dist/{chunk-WWO3FXHG.js → chunk-EVEBQSDK.js}

@@ -1,10 +1,12 @@
 import {
   CairnError,
   NotInstalledError,
+  SubmitInFlightError,
   UnsupportedMethodError,
   mapProviderError,
-  mapSubmitResultError
-} from "./chunk-UAPWZZQK.js";
+  mapSubmitResultError,
+  mapWriteProviderError
+} from "./chunk-37OHCH7R.js";
 
 // src/connect.ts
 var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
@@ -78,7 +80,8 @@ function unwrap(reply) {
   throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 function unwrapWrite(reply) {
-  const result = unwrap(reply);
+  if (!reply || !reply.ok) throw mapWriteProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
+  const result = reply.result;
   if (result && typeof result === "object" && result.ok === false) {
     throw mapSubmitResultError(result);
   }
@@ -94,10 +97,12 @@ var WalletConnection = class {
     this.provider = provider;
     this._timeoutMs = opts.timeoutMs ?? DEFAULT_PROVIDER_TIMEOUT_MS;
   }
-  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed CairnError
-  // (retryable:false: a write may already have reached the wallet, so never invite a blind auto-retry). The
-  // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
-  call(op, label) {
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed error
+  // (retryable:false). A write's request stays open in the wallet and may still be approved and sent, so its
+  // timeout is a maybe-sent SubmitInFlightError (WALLET_TIMEOUT, no txid); while that request stays open, a resend
+  // opens a second one, and approving both sends twice. The genuine wallet resolves quickly
+  // once the user acts; this only fires on a truly hung/absent response.
+  call(op, label, write = false) {
     const ms = this._timeoutMs;
     const invoke = () => new Promise((resolve) => {
       resolve(op());
@@ -105,7 +110,7 @@ var WalletConnection = class {
     if (!Number.isFinite(ms) || ms <= 0) return invoke();
     let timer;
     const timeout = new Promise((_, reject) => {
-      timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
+      timer = setTimeout(() => reject(write ? new SubmitInFlightError(`the wallet did not respond to ${label} within ${ms}ms; the request may still be open in the wallet and be sent if approved, so reject it in the wallet and check the chain before sending it again`, "WALLET_TIMEOUT") : new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
     return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
@@ -181,7 +186,7 @@ var WalletConnection = class {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
     this.adviseFillSpvCapability();
-    return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
+    return this.call(() => this.provider.fillOffer(params), "fillOffer", true).then(unwrapWrite);
   }
   // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
   // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
@@ -229,26 +234,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
+    return this.call(() => this.provider.send(params), "send", true).then(unwrapWrite);
   }
   /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
-    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose", true).then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest", true).then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim", true).then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid) {
     if (typeof txid !== "string" || !txid) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return this.call(() => this.provider.revealClaim(txid), "revealClaim").then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid), "revealClaim", true).then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {

package/dist/{chunk-C452UODV.js → chunk-IPBMMJ3Z.js}

@@ -1,3 +1,8 @@
+import {
+  CairnError,
+  SubmitInFlightError
+} from "./chunk-37OHCH7R.js";
+
 // src/chain.ts
 import {
   CsdClient,
@@ -13,7 +18,9 @@ import {
   buildSend,
   buildSendVerified,
   buildPropose,
-  buildAttest
+  buildAttest,
+  buildProposeVerified,
+  buildAttestVerified
 } from "@inversealtruism/csd-tx";
 import {
   payloadHash,
@@ -77,7 +84,11 @@ var Chain = class {
    * chain (`verifyInputValues` recomputes each source tx's txid, so a lying RPC can't under-report) and
    * computes change from the VERIFIED total — closing the UTXO-VALUE-1 implicit-fee-burn. Fail-closed:
    * if any source can't be verified it signs nothing. Prefer this over the pure `buildSend`. Pass
-   * `broadcast:false` to get the signed tx back without submitting.
+   * `broadcast:false` to get the signed tx back without submitting. A submit request that fails after signing
+   * throws a `SubmitInFlightError` carrying the signed `txid` and `nodeJson`: the node may have taken it, so check
+   * before resending, and resend that `nodeJson` with `submit` rather than a new send. A 4xx answer (a proxy's
+   * body cap or rate limit, or the node refusing the request) broadcast nothing and throws a final `CairnError`
+   * with code `SUBMIT_REJECTED`.
    */
   async send(p) {
     const from = addrFromPriv2(p.priv);
@@ -91,10 +102,19 @@ var Chain = class {
       verify: (inputs) => verifyInputValues2(this.client, inputs)
     });
     if (!built.ok || p.broadcast === false) return built;
-    const submitResult = await this.client.submit(built.nodeJson);
+    let submitResult;
+    try {
+      submitResult = await this.client.submit(built.nodeJson);
+    } catch (e) {
+      const what = e?.message ?? String(e);
+      if (e?.terminal === true)
+        throw new CairnError(`the submit request was refused (${what}), so nothing was broadcast; a 400 or 413 from a proxy is usually its request body cap (a transaction with many inputs), a 429 its rate limit`, { code: "SUBMIT_REJECTED", cause: e });
+      throw new SubmitInFlightError(`the submit request failed after signing (${what}); the node may have taken the transaction, so check ${built.txid} before sending again`, "SUBMIT_MAYBE_INFLIGHT", built.txid, e, built.nodeJson);
+    }
     return { ...built, ok: built.ok && submitResult.ok !== false, submitResult };
   }
-  /** A verifying light client over the same RPC (built once, reused). */
+  /** A light client over the same RPC (built once, reused), with no checkpoint and no batch header provider: it proves
+   *  nothing until seeded. The facade's seeded client backs `cairn.index.verifyInclusion` and `verifyOfferForFill`. */
   light() {
     if (!this._light) {
       this._light = new LightClient2({ client: this.client });
@@ -117,6 +137,8 @@ export {
   buildSendVerified,
   buildPropose,
   buildAttest,
+  buildProposeVerified,
+  buildAttestVerified,
   payloadHash,
   canonicalJson,
   verifyContentBytes,

package/dist/{chunk-CI7YODPP.js → chunk-NRCTL7OI.js}

@@ -1,7 +1,25 @@
+import {
+  HttpError
+} from "./chunk-37OHCH7R.js";
+
 // src/indexer.ts
 import { verifyMerkleProof } from "@inversealtruism/csd-codec";
 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;
@@ -51,8 +69,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`);
@@ -71,7 +110,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 —