@satora/swap 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -272,6 +272,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 +301,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;
 }
@@ -321,8 +337,36 @@ type SwapTrackerOptions = {
 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,6 +391,22 @@ 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). */
@@ -361,6 +421,8 @@ type TrackingConfig = {
     esploraUrl?: string;
     /** Poll interval (ms) for advancing observations/clocks; defaults to 5s. */
     refreshIntervalMs?: number;
+    /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
+    autoClaim?: AutoClaimConfig;
 };
 declare class Client {
     #private;
@@ -511,6 +573,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 +611,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;
     /**
@@ -633,12 +710,14 @@ 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;
     refresh(): Promise<void>;
+    reconcile(ref: HtlcRef): Promise<void>;
     dispose(): void;
     /** The verified preimage recovered from a claim spend, if one was seen. */
     getPreimage(ref: HtlcRef): Uint8Array | undefined;
@@ -721,12 +800,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;
@@ -834,12 +915,14 @@ 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;
     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): `0x${string}` | undefined;
@@ -938,6 +1021,144 @@ 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;
+}
+/** 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.
+     */
+    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;
+    /**
+     * 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 +1174,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, 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 };

package/dist/index.d.ts

@@ -272,6 +272,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 +301,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;
 }
@@ -321,8 +337,36 @@ type SwapTrackerOptions = {
 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,6 +391,22 @@ 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). */
@@ -361,6 +421,8 @@ type TrackingConfig = {
     esploraUrl?: string;
     /** Poll interval (ms) for advancing observations/clocks; defaults to 5s. */
     refreshIntervalMs?: number;
+    /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
+    autoClaim?: AutoClaimConfig;
 };
 declare class Client {
     #private;
@@ -511,6 +573,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 +611,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;
     /**
@@ -633,12 +710,14 @@ 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;
     refresh(): Promise<void>;
+    reconcile(ref: HtlcRef): Promise<void>;
     dispose(): void;
     /** The verified preimage recovered from a claim spend, if one was seen. */
     getPreimage(ref: HtlcRef): Uint8Array | undefined;
@@ -721,12 +800,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;
@@ -834,12 +915,14 @@ 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;
     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): `0x${string}` | undefined;
@@ -938,6 +1021,144 @@ 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;
+}
+/** 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.
+     */
+    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;
+    /**
+     * 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 +1174,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, 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 };