@satora/swap 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -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. */
@@ -272,6 +339,15 @@ declare function htlcKey(ref: HtlcRef): string;
 interface ContractManager {
     /** The ledger this manager observes. */
     readonly ledger: Ledger;
+    /**
+     * Whether this manager can observe `ref` at all — a permanent capability check,
+     * not a transient health probe. `false` means the ledger/chain is not configured
+     * (e.g. an EVM chain with no RPC), so the ref can never be observed and the
+     * tracker should skip the swap rather than {@link register} it (which throws).
+     * Distinct from a register failure, which is a recoverable error on an
+     * observable ref.
+     */
+    canObserve(ref: HtlcRef): boolean;
     /** Start tracking an HTLC (idempotent); seeds its state from the ledger. */
     register(ref: HtlcRef): Promise<void>;
     /** Stop tracking an HTLC. */
@@ -292,6 +368,13 @@ interface ContractManager {
     onEvent(cb: (ref: HtlcRef, state: HtlcObservation) => void): () => void;
     /** Force a reconcile from the ledger. */
     refresh(): Promise<void>;
+    /**
+     * Re-observe a single tracked HTLC from the ledger now — a targeted refresh, so
+     * a faster server hint can trigger an immediate on-chain verification of just
+     * that swap's legs without re-scanning every tracked HTLC. A no-op if the ref
+     * isn't tracked.
+     */
+    reconcile(ref: HtlcRef): Promise<void>;
     /** Tear down subscriptions and background work. */
     dispose(): void;
 }
@@ -312,17 +395,54 @@ 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;
     constructor(managers: Map<Ledger, ContractManager>, options?: SwapTrackerOptions);
+    /**
+     * Whether every on-chain leg of `swap` is observable — i.e. the tracker can
+     * derive its status from chain. `false` means a leg is on a ledger/chain this
+     * client can't reach (no manager, or an EVM chain with no RPC), so the swap
+     * can't be tracked. Pure predicate — callers decide the policy (skip vs reject).
+     */
+    canObserve(swap: TrackedSwap): boolean;
     /** Register each swap's on-chain leg(s), subscribe to manager events, and seed state. */
     startTracking(swaps: TrackedSwap[]): Promise<void>;
+    /**
+     * Track one more swap after {@link startTracking} — register its on-chain
+     * leg(s), seed the managers they touch, and derive its first action. Idempotent:
+     * a swap already tracked, or one already seen through to a terminal action, is
+     * ignored. New swaps are picked up by the existing per-manager event listeners
+     * and poll timer, so nothing else needs re-wiring. Lets a swap created after
+     * start (e.g. via `createSwap`) be tracked without a restart.
+     */
+    track(swap: TrackedSwap): Promise<void>;
+    /** The swap ids currently tracked — e.g. to subscribe them to a hint feed. */
+    trackedSwapIds(): string[];
+    /**
+     * Re-verify one swap against the chain right now — the hook a faster server
+     * status hint drives. Reconciles just that swap's legs (targeted, on the
+     * managers), then recomputes its action. The hint is only a *trigger*: the
+     * chain stays the source of truth, so a premature hint that the chain doesn't
+     * yet reflect changes nothing. A no-op for an untracked swap.
+     */
+    applyHint(swapId: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
     /** Notify `cb` of the current action for each tracked swap, then on every change. */
     subscribeToActions(cb: ActionSubscriber): () => void;
     /**
@@ -347,10 +467,33 @@ declare class SwapTracker {
  * individual delegators get replaced with native implementations over time.
  */
 
+/**
+ * Hint-driven auto-execution, opt-in via {@link ClientBuilder.withAutoClaim}.
+ *
+ * When set, tracking also opens the server status WebSocket (a faster trigger
+ * than the chain poll) and runs a {@link SwapWorker}: it auto-claims a swap the
+ * moment the chain confirms it is claimable, and surfaces the rest — a manual
+ * `fund`, or a refund the user must confirm — via {@link onActionRequired}.
+ */
+type AutoClaimConfig = {
+    /**
+     * Surface an action that needs the user rather than being auto-run — a manual
+     * `fund`, or a refund to confirm. The seam a frontend notification center
+     * plugs into. Omit to only auto-claim and ignore the rest.
+     */
+    onActionRequired?: (swapId: string, actions: SwapActions) => void;
+};
 /** How the client should set up observe-mode tracking. */
 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. */
@@ -359,8 +502,20 @@ 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;
 };
 declare class Client {
     #private;
@@ -511,6 +666,10 @@ declare class Client {
     /** Delegated to the legacy client (migration checkpoint). */
     getEvmDepositorKey(...args: Parameters<Client$1["getEvmDepositorKey"]>): ReturnType<Client$1["getEvmDepositorKey"]>;
     /** Delegated to the legacy client (migration checkpoint). */
+    getRefundedEvmSwapContinuation(...args: Parameters<Client$1["getRefundedEvmSwapContinuation"]>): ReturnType<Client$1["getRefundedEvmSwapContinuation"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    continueRefundedEvmSwap(...args: Parameters<Client$1["continueRefundedEvmSwap"]>): ReturnType<Client$1["continueRefundedEvmSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
     recoverGaslessFunds(...args: Parameters<Client$1["recoverGaslessFunds"]>): ReturnType<Client$1["recoverGaslessFunds"]>;
     /** Delegated to the legacy client (migration checkpoint). */
     hasReceivedVtxo(...args: Parameters<Client$1["hasReceivedVtxo"]>): ReturnType<Client$1["hasReceivedVtxo"]>;
@@ -545,6 +704,17 @@ declare class ClientBuilder {
      * defaults kept as fallbacks.
      */
     withEvmRpcUrls(urls: Record<number, string>): this;
+    /**
+     * Opt in to hint-driven auto-claim. Tracking then also subscribes to the
+     * server status WebSocket (a faster trigger than the chain poll) and, when the
+     * chain confirms a swap is claimable, claims it automatically. Actions that
+     * need the user — a manual `fund`, or a refund to confirm — are surfaced via
+     * `onActionRequired` instead of being run. Off by default: this auto-spends on
+     * the user's behalf, so it must be explicit.
+     */
+    withAutoClaim(options?: {
+        onActionRequired?: (swapId: string, actions: SwapActions) => void;
+    }): this;
     /** Turn observe-mode tracking off. */
     withoutTracking(): this;
     /**
@@ -562,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.
@@ -586,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
@@ -595,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[];
@@ -633,12 +815,20 @@ declare class ArkadeContractManager implements ContractManager {
     static fromDeps(deps: ArkadeContractManagerDeps): ArkadeContractManager;
     /** Construct a manager backed by a `RestIndexerProvider` over the Ark server. */
     static create(config: ArkadeCreateConfig): Promise<ArkadeContractManager>;
+    canObserve(ref: HtlcRef): boolean;
     register(ref: HtlcRef): Promise<void>;
     unregister(ref: HtlcRef): Promise<void>;
     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. */
     getPreimage(ref: HtlcRef): Uint8Array | undefined;
@@ -651,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";
 }>;
@@ -675,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
@@ -703,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;
@@ -721,12 +934,14 @@ declare class BitcoinContractManager implements ContractManager {
     private constructor();
     static fromDeps(deps: BitcoinContractManagerDeps): BitcoinContractManager;
     static create(config: BitcoinCreateConfig): Promise<BitcoinContractManager>;
+    canObserve(ref: HtlcRef): boolean;
     register(ref: HtlcRef): Promise<void>;
     unregister(ref: HtlcRef): Promise<void>;
     getState(ref: HtlcRef): HtlcObservation | undefined;
     chainNow(_ref: HtlcRef): number | undefined;
     onEvent(cb: (ref: HtlcRef, state: HtlcObservation) => void): () => void;
     refresh(): Promise<void>;
+    reconcile(ref: HtlcRef): Promise<void>;
     dispose(): void;
     /** The preimage a claim revealed on this HTLC, if one was seen. */
     getPreimage(ref: HtlcRef): Uint8Array | undefined;
@@ -756,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
@@ -776,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.
@@ -813,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. */
@@ -834,12 +1131,21 @@ declare class EvmContractManager implements ContractManager {
     readonly ledger: Ledger;
     private constructor();
     static fromDeps(deps: EvmContractManagerDeps): EvmContractManager;
+    canObserve(ref: HtlcRef): boolean;
     register(ref: HtlcRef): Promise<void>;
     unregister(ref: HtlcRef): Promise<void>;
     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. */
     getPreimage(ref: HtlcRef): `0x${string}` | undefined;
@@ -852,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;
 /**
@@ -938,6 +1219,160 @@ declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
  */
 declare function defaultEvmReaders(overrides?: Record<number, string>): Map<number, EvmChainReader>;
 
+/**
+ * Ties the hint feed and the action model together into auto-execution.
+ *
+ * On a server status hint it verifies the swap against the chain
+ * (`tracker.applyHint`) — the hint only makes the derivation faster, the chain
+ * stays the source of truth. Then, on every derived action, it AUTO-RUNS the
+ * recommended action when it is auto-safe (a claim) and SURFACES the rest — a
+ * manual `fund`, or a refund the user must confirm — via `onActionRequired`, the
+ * seam a frontend notification center plugs into.
+ *
+ * A failed auto-claim is RETRIED with backoff. Each retry first re-verifies
+ * against chain (a forced `applyHint`) and only re-runs if the swap is still
+ * claimable — so we never blindly re-submit a claim (which on EVM would waste gas
+ * or double-submit). After the attempt budget is spent the swap is surfaced via
+ * `onActionRequired`, so it is never silently stuck.
+ */
+
+/** The tracker surface the worker drives. */
+interface WorkerTracker {
+    trackedSwapIds(): string[];
+    /** Reconcile a swap's legs from chain, then recompute. `force` re-emits even if unchanged. */
+    applyHint(swapId: string, opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    subscribeToActions(cb: (swapId: string, actions: SwapActions) => void): () => void;
+}
+/** The hint feed surface the worker consumes (`WsStatusSource` satisfies it). */
+interface WorkerHintSource {
+    start(): void;
+    stop(): void;
+    subscribe(swapIds: string[]): void;
+    unsubscribe(swapIds: string[]): void;
+    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 = {
+    /** Attempts before giving up and surfacing the swap. Default 5. */
+    maxAttempts?: number;
+    /** Base backoff (ms), doubled each attempt. Default 2000. */
+    baseDelayMs?: number;
+    /** Backoff ceiling (ms). Default 30000. */
+    maxDelayMs?: number;
+};
+type SwapWorkerOptions = {
+    tracker: WorkerTracker;
+    hintSource: WorkerHintSource;
+    /**
+     * 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. 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>;
+    /**
+     * 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.
+     * Where a UI notification hooks in.
+     */
+    onActionRequired?: (swapId: string, actions: SwapActions) => void;
+    /** Auto-claim retry policy; sensible defaults otherwise. */
+    retry?: SwapWorkerRetryOptions;
+};
+declare class SwapWorker {
+    #private;
+    constructor(options: SwapWorkerOptions);
+    /** Watch tracked swaps on the hint feed, wire hints → verify, react to actions. */
+    start(): void;
+    /** Stop reacting, cancel pending retries, and close the hint feed. */
+    stop(): void;
+}
+
+/**
+ * A standalone subscriber to the server's swap-status WebSocket (`GET /ws`).
+ *
+ * Holds a single reconnecting connection, tracks a live set of subscribed swap
+ * ids, and emits `{ swapId, status }` on every status transition the server
+ * pushes — including the snapshot the server sends right after a subscribe. This
+ * is a *hint* feed only: it neither trusts nor acts on the status. A consumer is
+ * expected to verify against the chain (the contract managers) before doing
+ * anything with it.
+ *
+ * Protocol (see `swap/src/api/ws.rs`):
+ *   → {"op":"subscribe","channel":"swap_status","args":[<uuid>,...]}   (≤64 ids/frame)
+ *   ← {"channel":"swap_status","data":{"<uuid>":"<status>",...}}
+ *   ← {"op":"subscribed",...} (ack)     ← {"op":...,"message":...} (error)
+ * A single connection carries up to 256 subscriptions; that cap is enforced
+ * client-side (see {@link WsStatusSource.subscribe}) because the server silently
+ * drops the overflow.
+ */
+
+/** A status update pushed by the server for one swap. */
+type SwapStatusUpdate = {
+    swapId: string;
+    status: SwapStatus;
+};
+/** The minimal WebSocket surface the source needs (the global `WebSocket` satisfies it). */
+interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: (() => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+type WsStatusSourceOptions = {
+    /** Server base URL (http/https); the `ws(s)://…/ws` endpoint is derived from it. */
+    serverUrl: string;
+    /** WebSocket factory — defaults to the global `WebSocket` (browsers, Node ≥ 22). */
+    webSocketFactory?: (url: string) => WebSocketLike;
+    /** Reconnect backoff floor/ceiling (ms). Defaults: 1_000 / 30_000. */
+    reconnectMinMs?: number;
+    reconnectMaxMs?: number;
+};
+declare class WsStatusSource {
+    #private;
+    constructor(options: WsStatusSourceOptions);
+    /** Open the connection and begin (re)subscribing. Idempotent. */
+    start(): void;
+    /** Close the connection and stop reconnecting. */
+    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.
+     *
+     * Enforces the server's per-connection cap locally. The server silently stops
+     * adding once it is full (it breaks out of the loop but still acks every id),
+     * so sending more would leave us believing ids are subscribed that will never
+     * receive an update. Overflow is queued instead and promoted as slots free.
+     */
+    subscribe(swapIds: string[]): void;
+    /** Stop tracking these swap ids, promoting queued ones into the freed slots. */
+    unsubscribe(swapIds: string[]): void;
+}
+
 /**
  * Map a stored swap to the {@link TrackedSwap} the {@link SwapTracker} watches.
  *
@@ -953,4 +1388,4 @@ declare function defaultEvmReaders(overrides?: Record<number, string>): Map<numb
 
 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, SwapTracker, type TrackedSwap, type WaitAction, 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 };