@satora/swap 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SwapStatus, Client as Client$1, ClientBuilder as ClientBuilder$1, StoredSwap } from '@lendasat/lendaswap-sdk-pure';
 export * from '@lendasat/lendaswap-sdk-pure';
 import { VirtualCoin } from '@arkade-os/sdk';
-import { Log, Block } from 'viem';
+import { Block } from 'viem';
 
 /**
  * The derived "what should the client do next?" model.
@@ -44,8 +44,37 @@ type CctpClaimEvidence = {
     burnTxHash: `0x${string}`;
     attestationAvailable: boolean;
 };
+/**
+ * What a `wait` is waiting FOR — machine-readable, so a consumer can pick the
+ * right surface (invoice page, "deposit seen…", processing spinner, refund
+ * countdown) by switching on this field instead of re-deriving it from
+ * status + observations.
+ *
+ * One caveat: `client_payment` covers the whole Lightning-funded window — the
+ * chain cannot see whether the invoice was already paid (the server is the
+ * only witness for that split), so a consumer that wants "invoice shown" vs
+ * "payment in flight" as separate screens still refines this one value with
+ * the server status.
+ */
+type WaitingOn = 
+/** A Lightning payment to be made / locked in as a funded HTLC. */
+"client_payment"
+/** The client's funding tx was seen and is awaiting confirmation. */
+ | "client_funding_confirmation"
+/** The client funded; the server's HTLC hasn't appeared yet. */
+ | "server_funding"
+/** The client's claim is in flight, awaiting confirmation. */
+ | "claim_confirmation"
+/** Nothing will progress — waiting for the client refund timelock to pass. */
+ | "refund_timelock";
+/**
+ * How a finished swap ended — so a consumer can render success vs refund vs
+ * expiry from the terminal `none` action without interpreting `SwapStatus`.
+ */
+type SwapOutcome = "completed" | "refunded" | "expired";
 type WaitAction = SwapActionBase & {
     id: "wait";
+    waitingOn: WaitingOn;
 };
 type FundAction = SwapActionBase & {
     id: "fund";
@@ -66,6 +95,7 @@ type RecoverCctpClaimAction = SwapActionBase & {
 };
 type NoneAction = SwapActionBase & {
     id: "none";
+    outcome: SwapOutcome;
 };
 /** A single next-action option. Discriminated union on `id`. */
 type SwapAction = WaitAction | FundAction | ClaimAction | RefundCollaborativeAction | RefundUnilateralAction | RecoverCctpClaimAction | NoneAction;
@@ -76,6 +106,14 @@ type SwapActions = {
     /** id of the recommended action, if any; convenience pointer into `actions`. */
     recommended?: SwapActionId;
     actions: SwapAction[];
+    /**
+     * The raw chain observations these actions were derived from (set by the
+     * tracker; absent from a bare `deriveSwapActions` call). Chain FACTS — which
+     * leg is funded/spent — not protocol states: lets a UI render progress from
+     * chain truth (even when the server is stale or unreachable) without ever
+     * interpreting the `SwapStatus` enum.
+     */
+    observations?: SwapObservations;
 };
 /**
  * The pure input to {@link deriveSwapActions}: a plain, fully-resolved snapshot.
@@ -228,15 +266,28 @@ type HtlcRef = {
     preimageHash: string;
     /** Expected funding amount in sats; a funding below this is `invalid`. */
     expectedSats: number;
+    /**
+     * Confirmations this leg's funding needs before it observes as
+     * `confirmed`, overriding the reader's default.
+     *
+     * Set per leg because the two directions are not symmetric. A funding the
+     * SERVER made can be taken at 0-conf: the server does not double-spend its
+     * own HTLC, and waiting a block would stall every claim. A funding the
+     * CLIENT made is read back under the rule the server applies to it — the
+     * server does not act until the tx has a blocktime, so calling it funded
+     * sooner reports progress the other side has not agreed to.
+     */
+    minConfirmations?: number;
 } | {
     ledger: "evm";
     chainId: number;
     /** The HTLCErc20 contract holding this leg — where its events are emitted. */
     htlc: `0x${string}`;
     /**
-     * SHA256 preimage hash (`0x`-prefixed) — the indexed topic that identifies
-     * this swap's HTLC in the contract's `SwapCreated`/`SwapRedeemed`/
-     * `SwapRefunded` events. Serves as the contract's unique id here.
+     * SHA256 preimage hash (`0x`-prefixed) — the indexed topic the contract's
+     * `SwapCreated`/`SwapRedeemed`/`SwapRefunded` events are filtered by. It
+     * narrows a log scan but identifies no single HTLC: any number can share
+     * one hash, so a swap is told apart by the rest of the tuple below.
      */
     preimageHash: `0x${string}`;
     /**
@@ -254,6 +305,22 @@ type HtlcRef = {
     expectedAmount: bigint;
     /** Expected token address; the funding is `invalid` if it locks another token. */
     expectedToken?: `0x${string}`;
+    /**
+     * The funder (the HTLC's refund address). Together with the other fields it
+     * completes the contract's swap-key tuple, enabling the cheap `isActive`
+     * eth_call fast path (which verifies the terms implicitly — the key hashes
+     * amount/token/addresses/timelock). Legs whose response omits a tuple field
+     * fall back to log scans.
+     */
+    sender?: `0x${string}`;
+    /** The HTLC refund timelock in unix SECONDS, exactly as funded on-chain. */
+    timelockSec?: number;
+    /**
+     * Swap creation time (ms). Lower-bounds log scans: the HTLC can have no
+     * events before the swap existed, so the scan starts near the corresponding
+     * block instead of genesis.
+     */
+    createdAtMs?: number;
 } | {
     ledger: "lightning";
     /** Payment hash — the contract's unique id. */
@@ -328,11 +395,20 @@ type TrackedSwap = {
 type ActionSubscriber = (swapId: string, actions: SwapActions) => void;
 type SwapTrackerOptions = {
     /**
-     * How often (ms) to re-poll every manager to advance clocks and reconcile
-     * observations. Needed because some ledgers (Arkade) have no event push, so
-     * state only moves on a poll. `0` disables the timer (tests drive `refresh`).
+     * The local tick interval (ms). Each tick recomputes every tracked swap from
+     * extrapolated chain clocks — pure local work, NO chain reads — so timelock
+     * flips (a refund unlocking, a stale pending swap turning reapable) surface
+     * between hints. `0` disables the timer (tests drive `refresh` manually).
      */
     refreshIntervalMs?: number;
+    /**
+     * Minimum ms between chain reconciles of AT-RISK swaps — those whose client
+     * leg holds funds on-chain (≥ clientfunded, unresolved), where refund safety
+     * must not depend on the server. Everything else advances on server hints
+     * only ({@link applyHint}); a swap with nothing at stake costs zero chain
+     * reads. Default 60s.
+     */
+    atRiskReconcileIntervalMs?: number;
 };
 declare class SwapTracker {
     #private;
@@ -411,6 +487,13 @@ type AutoClaimConfig = {
 type TrackingConfig = {
     /** Whether tracking is enabled at all (default on; `withoutTracking()` clears). */
     enabled: boolean;
+    /**
+     * The swap server URL (from `withBaseUrl`). When set, tracking opens the
+     * server's status WebSocket as a HINT feed: a pushed transition triggers a
+     * targeted chain verify, so the chain pollers can stay slow. Chain reads
+     * remain the source of truth.
+     */
+    serverUrl?: string;
     /** Explicit per-ledger managers, bypassing auto-construction (advanced/testing). */
     managers?: Map<Ledger, ContractManager>;
     /** Ark server URL override; defaults to the mainnet server when unset. */
@@ -419,7 +502,17 @@ type TrackingConfig = {
     evmRpcUrls?: Record<number, string>;
     /** Esplora REST URL override for the Bitcoin manager; defaults to mainnet mempool.space. */
     esploraUrl?: string;
-    /** Poll interval (ms) for advancing observations/clocks; defaults to 5s. */
+    /**
+     * Confirmations a Bitcoin funding tx needs before it observes as
+     * `confirmed` (gating e.g. the evm→bitcoin claim). Default `0`: accept
+     * 0-conf, trusting the funder not to double-spend. `1` = wait for a block.
+     */
+    bitcoinMinConfirmations?: number;
+    /**
+     * Local tick interval (ms) — recomputes actions off extrapolated clocks, no
+     * chain reads. Chain reads happen on server hints and, for swaps whose
+     * client leg holds funds, on the tracker's at-risk cadence. Defaults to 5s.
+     */
     refreshIntervalMs?: number;
     /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
     autoClaim?: AutoClaimConfig;
@@ -639,6 +732,15 @@ declare class ClientBuilder {
      * otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
      */
     withEsploraUrl(url: string): this;
+    /**
+     * Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
+     * (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
+     * funding hits the mempool, which TRUSTS the funder not to double-spend it
+     * (claiming publishes the preimage, so a funder that then replaced its
+     * funding could take both legs). Set `1` (or more) for a block-depth policy
+     * that doesn't rely on the funder's good behaviour.
+     */
+    withBitcoinMinConfirmations(minConfirmations: number): this;
     /**
      * Override the Ark server URL. Optional for tracking — it otherwise defaults to
      * the mainnet server; set this to track a non-mainnet (dev/signet) deployment.
@@ -663,7 +765,7 @@ type VirtualTxSource = {
 
 /**
  * The Arkade {@link ContractManager} — the stateful I/O adapter that observes a
- * swap's VHTLC by polling the Ark indexer.
+ * swap's VHTLC via the Ark indexer.
  *
  * We deliberately do NOT use `@arkade-os/sdk`'s `ContractManager`: its vtxo
  * annotation calls `script.forfeit()` on every contract, but a VHTLC script has
@@ -672,11 +774,14 @@ type VirtualTxSource = {
  * the legacy SDK's claim/refund paths do — and map them with the pure helpers in
  * `./arkade.js`.
  *
- * There is no event push here, so observations advance when {@link refresh} runs;
- * the SwapTracker drives that (initial prime + periodic poll).
+ * Observation is on-demand: {@link refresh} (tracker start / newly tracked
+ * swap) and targeted {@link reconcile}s (server hints, the tracker's at-risk
+ * safety net). There is no standing subscription or periodic poll.
  */
 
-/** The Ark indexer surface the observer needs (RestIndexerProvider satisfies it). */
+/**
+ * The Ark indexer surface the observer needs (RestIndexerProvider satisfies it).
+ */
 type ArkadeIndexer = VirtualTxSource & {
     getVtxos(opts: {
         scripts: string[];
@@ -716,7 +821,13 @@ declare class ArkadeContractManager implements ContractManager {
     getState(ref: HtlcRef): HtlcObservation | undefined;
     chainNow(_ref: HtlcRef): number | undefined;
     onEvent(cb: (ref: HtlcRef, state: HtlcObservation) => void): () => void;
+    /**
+     * Full reconcile of every tracked ref (clock + vtxos). Called on demand
+     * (tracker start / newly tracked swap), NOT periodically: onward, hints and
+     * the tracker's at-risk safety net drive targeted `reconcile`s.
+     */
     refresh(): Promise<void>;
+    /** Targeted verify (hint / pre-action path) — never gated. */
     reconcile(ref: HtlcRef): Promise<void>;
     dispose(): void;
     /** The verified preimage recovered from a claim spend, if one was seen. */
@@ -730,6 +841,15 @@ declare class ArkadeContractManager implements ContractManager {
  */
 declare function defaultArkadeServerUrl(network: string): string | undefined;
 
+/**
+ * Build the Arkade {@link HtlcRef} for a swap's VHTLC leg from the plain swap
+ * fields, deriving the pkScript and serialized contract params the
+ * `ArkadeContractManager` needs to register it for watching.
+ *
+ * This is the one place that reconstructs the VHTLC from a swap, mirroring the
+ * SDK VHTLC construction, so the mapper and manager stay free of VHTLC internals.
+ */
+
 type ArkadeRef = Extract<HtlcRef, {
     ledger: "arkade";
 }>;
@@ -754,6 +874,8 @@ type ArkadeVhtlcInput = {
     unilateralRefundWithoutReceiverDelay: number;
     /** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
     expectedSats: number;
+    /** Arkade HTLC script version. Missing means legacy v0 for old stored swaps. */
+    arkadeHtlcScriptVersion?: number;
 };
 /**
  * The VHTLC always commits to `ripemd160(sha256(preimage))` (HASH160). When
@@ -782,13 +904,25 @@ type BitcoinHtlcFacts = {
 /** The esplora surface the observer needs (a `BitcoinReaderEsplora` satisfies it). */
 type BitcoinChainReader = {
     /** Funding + spend facts for an HTLC witness-script address. */
-    getHtlcFacts(address: string): Promise<BitcoinHtlcFacts>;
+    /**
+     * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
+     * overrides the reader's default for this address alone — the two legs of a
+     * swap do not share one rule.
+     */
+    getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
 };
 type BitcoinCreateConfig = {
     /** One or more esplora REST base URLs; several are tried in rotation with failover. */
     esploraUrl: string | string[];
     /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
     chainTime?: () => Promise<number>;
+    /**
+     * Confirmations a funding tx needs before it observes as `confirmed`.
+     * Default `0`: accept an unconfirmed funding, trusting the funder not to
+     * double-spend it (the claim reveals the preimage against it). `1` = wait
+     * for a block.
+     */
+    minConfirmations?: number;
 };
 type BitcoinContractManagerDeps = {
     reader: BitcoinChainReader;
@@ -837,14 +971,33 @@ type EsploraTx = {
     }>;
     status?: {
         confirmed?: boolean;
+        block_height?: number;
     };
 };
+/**
+ * When a funding tx counts as `confirmed` for observation purposes.
+ *
+ * `minConfirmations: 0` (the default) accepts an UNCONFIRMED funding, so a swap
+ * claims as soon as the funding hits the mempool instead of waiting ~10min for
+ * a block. This TRUSTS the funder not to double-spend: claiming publishes the
+ * preimage, so a funder who then replaces its funding tx could take both legs.
+ * Our own server therefore broadcasts HTLC fundings without signalling RBF.
+ * Note that a non-signalling tx is still replaceable by full-RBF miners — set
+ * `1` (or more) for a policy that doesn't rely on the funder's good behaviour;
+ * values above 1 make the reader fetch the tip height to compute depth.
+ */
+type BitcoinConfirmationPolicy = {
+    minConfirmations?: number;
+};
 /**
  * Reduce an address's esplora tx history to HTLC facts. If a tx spends an output
  * at the address, that's the resolving spend (its witness classifies claim vs
- * refund); otherwise a tx paying the address is the funding.
+ * refund); otherwise a tx paying the address is the funding, gated by the
+ * confirmation policy (see {@link BitcoinConfirmationPolicy}).
  */
-declare function htlcFactsFromEsploraTxs(txs: EsploraTx[], address: string): BitcoinHtlcFacts;
+declare function htlcFactsFromEsploraTxs(txs: EsploraTx[], address: string, opts?: BitcoinConfirmationPolicy & {
+    tipHeight?: number;
+}): BitcoinHtlcFacts;
 /**
  * Public esplora endpoints tried in rotation (mainnet). blockstream.info runs the
  * reference esplora, so it's API-compatible with mempool.space; spreading calls
@@ -857,7 +1010,7 @@ declare const DEFAULT_ESPLORA_URLS: string[];
  * providers) and fails over to the rest on error — so a throttled or failing
  * provider doesn't stall tracking.
  */
-declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch): BitcoinChainReader;
+declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
 
 /**
  * The `EvmContractManager`'s pure core.
@@ -894,17 +1047,80 @@ type EvmHtlcEvent = {
  * {@link chainNow} is ref-scoped.
  */
 
+/** Identifies one HTLC to read: contract + preimageHash (+ the claim guard). */
+type EvmHtlcQuery = {
+    htlc: `0x${string}`;
+    preimageHash: `0x${string}`;
+    /** A `SwapCreated` counts only when it pays this address (term check). */
+    claimAddress: `0x${string}`;
+    /**
+     * The rest of the swap-key tuple, when the swap response exposed it. It makes
+     * {@link htlcQueryKey} unique to this HTLC, so two swaps sharing a preimage
+     * hash hold separate entries rather than one overwriting the other. It does
+     * not change how settlements are attributed — those go by hash either way.
+     */
+    terms?: EvmHtlcTerms;
+};
+/**
+ * The result key for one query in a batch.
+ *
+ * `preimageHash` identifies no single HTLC — any number can share one — so the
+ * rest of the swap-key tuple is what separates two HTLCs on the same contract.
+ * A caller that knows the tuple gets a key unique to its HTLC; one that does not
+ * falls back to contract + hash, which is ambiguous by construction — two such
+ * callers on one hash share an entry.
+ */
+declare function htlcQueryKey(q: {
+    htlc: `0x${string}`;
+    preimageHash: `0x${string}`;
+    claimAddress?: `0x${string}`;
+    terms?: EvmHtlcTerms;
+}): string;
+/** The swap-key tuple fields beyond contract, hash and claim address. */
+type EvmHtlcTerms = {
+    amount: bigint;
+    token: `0x${string}`;
+    sender: `0x${string}`;
+    timelockSec: number;
+};
+/**
+ * The contract's full swap-key tuple for one HTLC. `isActive` hashes all of it
+ * into the swap key, so an `isActive == true` with these EXPECTED values also
+ * proves the HTLC was funded on exactly the expected terms.
+ */
+type EvmActiveQuery = {
+    htlc: `0x${string}`;
+    preimageHash: `0x${string}`;
+    amount: bigint;
+    token: `0x${string}`;
+    sender: `0x${string}`;
+    claimAddress: `0x${string}`;
+    timelockSec: number;
+};
 /** Reads `HTLCErc20` state for one EVM chain. Implemented over viem/ethers/etc. */
 type EvmChainReader = {
     /**
-     * The decoded lifecycle events (oldest→newest) for the HTLC identified by
-     * `(htlc contract, preimageHash)`.
+     * The decoded lifecycle events for every queried HTLC, keyed by
+     * {@link htlcQueryKey}. Batched so a whole chain scan costs one RPC request
+     * regardless of how many swaps are tracked; a queried HTLC with no events maps
+     * to an empty array. `fromBlock` lower-bounds the scan (default genesis) —
+     * pass the swaps' creation-block estimate so providers never see an
+     * unbounded log query.
      */
-    getHtlcEvents(htlc: `0x${string}`, preimageHash: `0x${string}`, claimAddress: `0x${string}`): Promise<EvmHtlcEvent[]>;
-    /** The latest block's `block.timestamp`, in ms. */
-    getBlockTimeMs(): Promise<number>;
-    /** Fire `cb` when new blocks/logs may have changed watched HTLCs; returns unsubscribe. */
-    watch(cb: () => void): () => void;
+    getHtlcEventsBatch(queries: EvmHtlcQuery[], fromBlock?: bigint): Promise<Map<string, EvmHtlcEvent[]>>;
+    /**
+     * Whether each queried HTLC is currently open, keyed by {@link htlcQueryKey}.
+     * The cheap routine check (`eth_call`, batched via Multicall3): `true` means
+     * funded-and-unspent on exactly the queried terms; `false` is ambiguous
+     * (never funded / claimed / refunded) and needs {@link getHtlcEventsBatch}
+     * to classify.
+     */
+    isActiveBatch(queries: EvmActiveQuery[]): Promise<Map<string, boolean>>;
+    /** The latest block's timestamp (ms) and number. */
+    getLatestBlock(): Promise<{
+        timeMs: number;
+        number: bigint;
+    }>;
 };
 type EvmContractManagerDeps = {
     /** A chain reader per EVM `chainId` this manager serves. */
@@ -921,7 +1137,14 @@ declare class EvmContractManager implements ContractManager {
     getState(ref: HtlcRef): HtlcObservation | undefined;
     chainNow(ref: HtlcRef): number | undefined;
     onEvent(cb: (ref: HtlcRef, state: HtlcObservation) => void): () => void;
+    /**
+     * Full reconcile of every tracked chain — seeds clocks + observations. Called
+     * on demand (tracker start / newly tracked swap), NOT periodically: onward,
+     * hints drive targeted `reconcile`s and the tracker's at-risk safety net
+     * re-reads only swaps with client funds on the line.
+     */
     refresh(): Promise<void>;
+    /** Targeted verify (hint / pre-action path) — never gated. */
     reconcile(ref: HtlcRef): Promise<void>;
     dispose(): void;
     /** The preimage a claim revealed on this HTLC, if one was seen. */
@@ -935,83 +1158,58 @@ declare class EvmContractManager implements ContractManager {
  * Kept separate from the manager so the manager itself stays free of any
  * chain-library dependency (and unit-testable against a fake reader). This module
  * is the only place that touches viem and the `HTLCErc20` ABI.
+ *
+ * All HTLCs on a chain are read with a SINGLE `eth_getLogs` call: the three
+ * `HTLCErc20` lifecycle events all index `preimageHash` as topic1, so one filter
+ * ORs the three event signatures on topic0 and the tracked preimage hashes on
+ * topic1 across all HTLC contract addresses. Request count per scan is constant
+ * in the number of tracked swaps — this matters, since public RPCs rate-limit by
+ * request count.
  */
 
 /**
  * Tested public RPC endpoints per supported chainId, tried in order via viem's
- * ranked `fallback`. Mirrors the frontend's `evmTransport.ts` list — the client
+ * `fallback`. Mirrors the frontend's `evmTransport.ts` list — the client
  * uses these by default so Arkade↔EVM tracking works out of the box; a caller can
  * override per chain with `ClientBuilder.withEvmRpcUrls`.
  */
 declare const DEFAULT_EVM_RPCS: Record<number, string[]>;
-declare const SWAP_CREATED: {
-    readonly name: "SwapCreated";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly type: "bytes32";
-        readonly name: "preimageHash";
-        readonly indexed: true;
-    }, {
-        readonly type: "address";
-        readonly name: "refundAddress";
-        readonly indexed: true;
-    }, {
-        readonly type: "address";
-        readonly name: "claimAddress";
-        readonly indexed: true;
-    }, {
-        readonly type: "address";
-        readonly name: "token";
-    }, {
-        readonly type: "uint256";
-        readonly name: "amount";
-    }, {
-        readonly type: "uint256";
-        readonly name: "timelock";
-    }];
-};
-declare const SWAP_REDEEMED: {
-    readonly name: "SwapRedeemed";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly type: "bytes32";
-        readonly name: "preimageHash";
-        readonly indexed: true;
-    }, {
-        readonly type: "bytes32";
-        readonly name: "preimage";
-    }];
-};
-declare const SWAP_REFUNDED: {
-    readonly name: "SwapRefunded";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly type: "bytes32";
-        readonly name: "preimageHash";
-        readonly indexed: true;
-    }];
+/** The undecoded log shape `eth_getLogs` returns. */
+type RawLog = {
+    address: `0x${string}`;
+    topics: [`0x${string}`, ...`0x${string}`[]];
+    data: `0x${string}`;
 };
 /** The viem surface the reader needs — a seam so it can be faked in tests. */
 type EvmLogClient = {
-    getLogs(args: {
-        address: `0x${string}`;
-        event: typeof SWAP_CREATED | typeof SWAP_REDEEMED | typeof SWAP_REFUNDED;
-        args: {
-            preimageHash: `0x${string}`;
-            claimAddress?: `0x${string}`;
-        };
-        fromBlock: bigint | "earliest";
-    }): Promise<Log[]>;
-    getBlock(): Promise<Pick<Block, "timestamp">>;
-    watchBlocks(args: {
-        onBlock: () => void;
-    }): () => void;
+    request(args: {
+        method: "eth_getLogs";
+        params: [
+            {
+                address: `0x${string}`[];
+                topics: (`0x${string}`[] | null)[];
+                fromBlock: `0x${string}`;
+            }
+        ];
+    }): Promise<RawLog[]>;
+    /** A read-only `eth_call`. */
+    call(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }): Promise<{
+        data?: `0x${string}`;
+    }>;
+    getBlock(): Promise<Pick<Block, "timestamp" | "number">>;
 };
 /** Build an {@link EvmChainReader} over an existing viem-like client. */
 declare function evmReaderFromClient(client: EvmLogClient): EvmChainReader;
 /**
  * Build an {@link EvmChainReader} over one or more EVM JSON-RPC endpoints. With
- * several, viem's ranked `fallback` picks the healthiest and fails over.
+ * several, viem's `fallback` tries them in order and fails over on error.
+ * Deliberately NOT ranked: ranking health-pings every listed endpoint on an
+ * interval from every open tab, which is exactly the background burst that got
+ * public RPCs rate-limiting us (publicnode 403s) — and it contradicts this
+ * package's near-zero-RPC design.
  */
 declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
 /**
@@ -1056,6 +1254,12 @@ interface WorkerHintSource {
     onStatus(cb: (update: {
         swapId: string;
     }) => void): () => void;
+    /**
+     * Optional: fires when the feed comes back up after an outage, during which
+     * pushed transitions were lost for good. The worker answers by re-verifying
+     * every tracked swap against the chain.
+     */
+    onReconnect?(cb: () => void): () => void;
 }
 /** Backoff policy for retrying a failed auto-claim. */
 type SwapWorkerRetryOptions = {
@@ -1072,9 +1276,10 @@ type SwapWorkerOptions = {
     /**
      * Run the recommended auto action for a swap (today: claim). Reject to signal
      * failure — the worker re-verifies against chain and retries with backoff.
-     * Resolve once submitted.
+     * Resolve once submitted. OMIT for observe-only mode: hints still trigger
+     * chain re-verifies (fast, cheap derivations), but nothing is ever run.
      */
-    execute: (swapId: string, actionId: SwapActionId) => Promise<void>;
+    execute?: (swapId: string, actionId: SwapActionId) => Promise<void>;
     /**
      * Surface an action that needs the user rather than being auto-run — a manual
      * `fund`, a refund the user must confirm, or a claim whose retries are spent.
@@ -1146,6 +1351,15 @@ declare class WsStatusSource {
     stop(): void;
     /** Emit for each pushed status update. Returns an unsubscribe fn. */
     onStatus(cb: (update: SwapStatusUpdate) => void): () => void;
+    /**
+     * Emit whenever the socket comes (back) up after a disruption — a drop, or a
+     * first connect that had to be retried. NOT emitted on a pristine first open:
+     * hints were never live before it, so there is no gap to recover from. While
+     * the socket was down, pushed transitions were lost for good (the server only
+     * snapshots on subscribe), so a consumer should re-verify its world against
+     * the chain on this signal.
+     */
+    onReconnect(cb: () => void): () => void;
     /**
      * Track these swap ids — subscribe on the socket now if open, else on next open.
      *
@@ -1174,4 +1388,4 @@ declare class WsStatusSource {
 
 declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
 
-export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, swapToTracked };
+export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RawLog, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapOutcome, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WaitingOn, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };