@satora/swap 1.1.0 → 1.2.1

package/dist/index.d.cts

@@ -379,6 +379,20 @@ interface ContractManager {
     dispose(): void;
 }
 
+/**
+ * The reactive orchestration.
+ *
+ * A {@link SwapTracker} watches each tracked swap's on-chain HTLC leg(s) via
+ * per-ledger {@link ContractManager}s (two legs for chain↔chain swaps, one for
+ * Lightning). On any change it recomputes the next action
+ * (`deriveSwapStatus` → `deriveSwapActions`), and — deduped — notifies
+ * subscribers, dropping a swap once it reaches a terminal state.
+ *
+ * This is the observe-mode layer: it *notifies*. Auto-execution (recover/auto
+ * mode running the action) is a policy layer built on top of these same
+ * notifications, gated by each action's `automation`.
+ */
+
 /**
  * A swap the tracker watches: its HTLC legs + refund locktimes (from the recovery
  * bundle). Chain↔chain swaps have both legs; Lightning swaps have exactly one
@@ -391,6 +405,12 @@ type TrackedSwap = {
     serverHtlc?: HtlcRef;
     clientRefundLocktime: number;
     serverRefundLocktime: number;
+    /**
+     * The swap's last STORED server status, seeding hints-only tracking
+     * (`HintTracker`) with a first derivation before any hint arrives. Ignored by
+     * {@link SwapTracker}, which derives from chain observations only.
+     */
+    storedStatus?: SwapStatus;
 };
 type ActionSubscriber = (swapId: string, actions: SwapActions) => void;
 type SwapTrackerOptions = {
@@ -528,6 +548,14 @@ type TrackingConfig = {
     refreshIntervalMs?: number;
     /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
     autoClaim?: AutoClaimConfig;
+    /**
+     * Verify against the chain instead of trusting server hints. Off by default
+     * (TEMP while the chain monitors are buggy): tracking then runs a
+     * {@link HintTracker} that derives actions from the server's pushed status,
+     * with zero chain access. Setting explicit `managers` implies chain-verified
+     * tracking (they exist for nothing else).
+     */
+    chainVerified?: boolean;
 };
 declare class Client {
     #private;
@@ -680,8 +708,11 @@ declare class Client {
     /**
      * Start observing the user's active swaps and deriving each one's next action.
      *
-     * Loads stored swaps, maps the ones whose ledgers are observable to
-     * {@link TrackedSwap}s, and runs the per-ledger monitors. Idempotent. Requires
+     * Loads stored swaps, maps them to {@link TrackedSwap}s, and derives each
+     * one's actions — by default from the server's status hints alone (TEMP while
+     * the chain monitors are buggy; see
+     * {@link ClientBuilder.withChainVerifiedTracking} to re-enable the per-ledger
+     * chain monitors). Idempotent. Requires
      * the client to have been built with {@link ClientBuilder.withTracking}.
      * Subscribe with {@link subscribeToActions}; release with
      * {@link stopTracking}.
@@ -721,6 +752,13 @@ declare class ClientBuilder {
     }): this;
     /** Turn observe-mode tracking off. */
     withoutTracking(): this;
+    /**
+     * Verify swap state against the chain (per-ledger contract managers) instead
+     * of trusting the server's status hints. TEMPORARILY off by default while the
+     * chain monitors are being fixed — without it, tracking derives actions from
+     * the server's pushed status alone, with zero chain access.
+     */
+    withChainVerifiedTracking(): this;
     /**
      * Advanced: supply per-ledger {@link ContractManager}s explicitly instead of
      * letting the client auto-build them from config (useful for tests or custom
@@ -1293,6 +1331,74 @@ declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
  */
 declare function defaultEvmReaders(overrides?: Record<number, string>): Map<number, EvmChainReader>;
 
+/**
+ * A server-trusting stand-in for {@link SwapTracker}: derives each swap's next
+ * action from the SERVER's status instead of chain observations — zero chain
+ * access (no EVM RPCs, no Esplora/Electrum, no Arkade reads).
+ *
+ * TEMPORARY default while the chain monitors are being fixed. Unlike
+ * {@link SwapTracker} there is no independent verification: the client acts on
+ * the server's word. The pushed status is the same `SwapStatus` enum the chain
+ * derivation produces, so it feeds straight into {@link deriveSwapActions}.
+ * Failure containment: a claim run on a false `serverfunded` fails locally
+ * (nothing to spend / gas estimation reverts) rather than losing funds.
+ *
+ * Timelocks are evaluated against the wall clock, not chain clocks. The wall
+ * clock runs AHEAD of Bitcoin's MTP (by up to ~an hour), so a refund can look
+ * unlocked slightly early — the broadcast simply fails until the chain agrees,
+ * and refunds are user-confirmed anyway — while the claim window closes
+ * conservatively early, which is the safe direction.
+ */
+
+type HintTrackerOptions = {
+    /**
+     * Fetch a swap's current status from the server — the fallback for hints
+     * that don't carry one (the worker's retry re-verifies and its
+     * post-reconnect sweep).
+     */
+    fetchStatus: (swapId: string) => Promise<SwapStatus>;
+    /**
+     * Local tick interval (ms): recomputes every swap against the wall clock so
+     * timelock flips (a refund unlocking, a stale pending swap turning reapable)
+     * surface between hints. Pure local work. `0` disables the timer (tests
+     * drive recomputes via {@link applyHint}).
+     */
+    refreshIntervalMs?: number;
+};
+declare class HintTracker {
+    #private;
+    constructor(options: HintTrackerOptions);
+    /**
+     * Always `true`: with no chain readers there is no reachability constraint.
+     * (Claim/refund execution has its own chain configuration, independent of
+     * tracking.)
+     */
+    canObserve(_swap: TrackedSwap): boolean;
+    /** Register the swaps, derive each one's first action from its stored status. */
+    startTracking(swaps: TrackedSwap[]): Promise<void>;
+    /**
+     * Track one more swap after {@link startTracking}. Idempotent: a swap already
+     * tracked, or one already seen through to a terminal action, is ignored.
+     */
+    track(swap: TrackedSwap): Promise<void>;
+    /** The swap ids currently tracked — e.g. to subscribe them to the hint feed. */
+    trackedSwapIds(): string[];
+    /**
+     * Apply a server status to one swap and recompute its action. A hint that
+     * carries the pushed `status` is applied as-is; without one (the worker's
+     * retry and post-reconnect paths) the status is re-fetched from the server.
+     * A no-op for an untracked swap.
+     */
+    applyHint(swapId: string, opts?: {
+        force?: boolean;
+        status?: SwapStatus;
+    }): Promise<void>;
+    /** Notify `cb` of the current action for each tracked swap, then on every change. */
+    subscribeToActions(cb: ActionSubscriber): () => void;
+    /** Stop tracking: drop the tick timer, tracked swaps, and subscribers. */
+    stop(): void;
+}
+
 /**
  * Ties the hint feed and the action model together into auto-execution.
  *
@@ -1313,9 +1419,15 @@ declare function defaultEvmReaders(overrides?: Record<number, string>): Map<numb
 /** 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. */
+    /**
+     * Re-verify a swap, then recompute. `force` re-emits even if unchanged.
+     * `status` is the hint's pushed status: a chain-verifying tracker ignores it
+     * (the chain stays its source of truth); a hints-only tracker applies it
+     * directly, saving a server round-trip.
+     */
     applyHint(swapId: string, opts?: {
         force?: boolean;
+        status?: SwapStatus;
     }): Promise<void>;
     subscribeToActions(cb: (swapId: string, actions: SwapActions) => void): () => void;
 }
@@ -1327,6 +1439,7 @@ interface WorkerHintSource {
     unsubscribe(swapIds: string[]): void;
     onStatus(cb: (update: {
         swapId: string;
+        status?: SwapStatus;
     }) => void): () => void;
     /**
      * Optional: fires when the feed comes back up after an outage, during which
@@ -1462,4 +1575,4 @@ declare class WsStatusSource {
 
 declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
 
-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 ElectrumReaderNetwork, type ElectrumRpc, 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, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, 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 ElectrumReaderNetwork, type ElectrumRpc, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, HintTracker, type HintTrackerOptions, 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, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };

package/dist/index.d.ts

@@ -379,6 +379,20 @@ interface ContractManager {
     dispose(): void;
 }
 
+/**
+ * The reactive orchestration.
+ *
+ * A {@link SwapTracker} watches each tracked swap's on-chain HTLC leg(s) via
+ * per-ledger {@link ContractManager}s (two legs for chain↔chain swaps, one for
+ * Lightning). On any change it recomputes the next action
+ * (`deriveSwapStatus` → `deriveSwapActions`), and — deduped — notifies
+ * subscribers, dropping a swap once it reaches a terminal state.
+ *
+ * This is the observe-mode layer: it *notifies*. Auto-execution (recover/auto
+ * mode running the action) is a policy layer built on top of these same
+ * notifications, gated by each action's `automation`.
+ */
+
 /**
  * A swap the tracker watches: its HTLC legs + refund locktimes (from the recovery
  * bundle). Chain↔chain swaps have both legs; Lightning swaps have exactly one
@@ -391,6 +405,12 @@ type TrackedSwap = {
     serverHtlc?: HtlcRef;
     clientRefundLocktime: number;
     serverRefundLocktime: number;
+    /**
+     * The swap's last STORED server status, seeding hints-only tracking
+     * (`HintTracker`) with a first derivation before any hint arrives. Ignored by
+     * {@link SwapTracker}, which derives from chain observations only.
+     */
+    storedStatus?: SwapStatus;
 };
 type ActionSubscriber = (swapId: string, actions: SwapActions) => void;
 type SwapTrackerOptions = {
@@ -528,6 +548,14 @@ type TrackingConfig = {
     refreshIntervalMs?: number;
     /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
     autoClaim?: AutoClaimConfig;
+    /**
+     * Verify against the chain instead of trusting server hints. Off by default
+     * (TEMP while the chain monitors are buggy): tracking then runs a
+     * {@link HintTracker} that derives actions from the server's pushed status,
+     * with zero chain access. Setting explicit `managers` implies chain-verified
+     * tracking (they exist for nothing else).
+     */
+    chainVerified?: boolean;
 };
 declare class Client {
     #private;
@@ -680,8 +708,11 @@ declare class Client {
     /**
      * Start observing the user's active swaps and deriving each one's next action.
      *
-     * Loads stored swaps, maps the ones whose ledgers are observable to
-     * {@link TrackedSwap}s, and runs the per-ledger monitors. Idempotent. Requires
+     * Loads stored swaps, maps them to {@link TrackedSwap}s, and derives each
+     * one's actions — by default from the server's status hints alone (TEMP while
+     * the chain monitors are buggy; see
+     * {@link ClientBuilder.withChainVerifiedTracking} to re-enable the per-ledger
+     * chain monitors). Idempotent. Requires
      * the client to have been built with {@link ClientBuilder.withTracking}.
      * Subscribe with {@link subscribeToActions}; release with
      * {@link stopTracking}.
@@ -721,6 +752,13 @@ declare class ClientBuilder {
     }): this;
     /** Turn observe-mode tracking off. */
     withoutTracking(): this;
+    /**
+     * Verify swap state against the chain (per-ledger contract managers) instead
+     * of trusting the server's status hints. TEMPORARILY off by default while the
+     * chain monitors are being fixed — without it, tracking derives actions from
+     * the server's pushed status alone, with zero chain access.
+     */
+    withChainVerifiedTracking(): this;
     /**
      * Advanced: supply per-ledger {@link ContractManager}s explicitly instead of
      * letting the client auto-build them from config (useful for tests or custom
@@ -1293,6 +1331,74 @@ declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
  */
 declare function defaultEvmReaders(overrides?: Record<number, string>): Map<number, EvmChainReader>;
 
+/**
+ * A server-trusting stand-in for {@link SwapTracker}: derives each swap's next
+ * action from the SERVER's status instead of chain observations — zero chain
+ * access (no EVM RPCs, no Esplora/Electrum, no Arkade reads).
+ *
+ * TEMPORARY default while the chain monitors are being fixed. Unlike
+ * {@link SwapTracker} there is no independent verification: the client acts on
+ * the server's word. The pushed status is the same `SwapStatus` enum the chain
+ * derivation produces, so it feeds straight into {@link deriveSwapActions}.
+ * Failure containment: a claim run on a false `serverfunded` fails locally
+ * (nothing to spend / gas estimation reverts) rather than losing funds.
+ *
+ * Timelocks are evaluated against the wall clock, not chain clocks. The wall
+ * clock runs AHEAD of Bitcoin's MTP (by up to ~an hour), so a refund can look
+ * unlocked slightly early — the broadcast simply fails until the chain agrees,
+ * and refunds are user-confirmed anyway — while the claim window closes
+ * conservatively early, which is the safe direction.
+ */
+
+type HintTrackerOptions = {
+    /**
+     * Fetch a swap's current status from the server — the fallback for hints
+     * that don't carry one (the worker's retry re-verifies and its
+     * post-reconnect sweep).
+     */
+    fetchStatus: (swapId: string) => Promise<SwapStatus>;
+    /**
+     * Local tick interval (ms): recomputes every swap against the wall clock so
+     * timelock flips (a refund unlocking, a stale pending swap turning reapable)
+     * surface between hints. Pure local work. `0` disables the timer (tests
+     * drive recomputes via {@link applyHint}).
+     */
+    refreshIntervalMs?: number;
+};
+declare class HintTracker {
+    #private;
+    constructor(options: HintTrackerOptions);
+    /**
+     * Always `true`: with no chain readers there is no reachability constraint.
+     * (Claim/refund execution has its own chain configuration, independent of
+     * tracking.)
+     */
+    canObserve(_swap: TrackedSwap): boolean;
+    /** Register the swaps, derive each one's first action from its stored status. */
+    startTracking(swaps: TrackedSwap[]): Promise<void>;
+    /**
+     * Track one more swap after {@link startTracking}. Idempotent: a swap already
+     * tracked, or one already seen through to a terminal action, is ignored.
+     */
+    track(swap: TrackedSwap): Promise<void>;
+    /** The swap ids currently tracked — e.g. to subscribe them to the hint feed. */
+    trackedSwapIds(): string[];
+    /**
+     * Apply a server status to one swap and recompute its action. A hint that
+     * carries the pushed `status` is applied as-is; without one (the worker's
+     * retry and post-reconnect paths) the status is re-fetched from the server.
+     * A no-op for an untracked swap.
+     */
+    applyHint(swapId: string, opts?: {
+        force?: boolean;
+        status?: SwapStatus;
+    }): Promise<void>;
+    /** Notify `cb` of the current action for each tracked swap, then on every change. */
+    subscribeToActions(cb: ActionSubscriber): () => void;
+    /** Stop tracking: drop the tick timer, tracked swaps, and subscribers. */
+    stop(): void;
+}
+
 /**
  * Ties the hint feed and the action model together into auto-execution.
  *
@@ -1313,9 +1419,15 @@ declare function defaultEvmReaders(overrides?: Record<number, string>): Map<numb
 /** 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. */
+    /**
+     * Re-verify a swap, then recompute. `force` re-emits even if unchanged.
+     * `status` is the hint's pushed status: a chain-verifying tracker ignores it
+     * (the chain stays its source of truth); a hints-only tracker applies it
+     * directly, saving a server round-trip.
+     */
     applyHint(swapId: string, opts?: {
         force?: boolean;
+        status?: SwapStatus;
     }): Promise<void>;
     subscribeToActions(cb: (swapId: string, actions: SwapActions) => void): () => void;
 }
@@ -1327,6 +1439,7 @@ interface WorkerHintSource {
     unsubscribe(swapIds: string[]): void;
     onStatus(cb: (update: {
         swapId: string;
+        status?: SwapStatus;
     }) => void): () => void;
     /**
      * Optional: fires when the feed comes back up after an outage, during which
@@ -1462,4 +1575,4 @@ declare class WsStatusSource {
 
 declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
 
-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 ElectrumReaderNetwork, type ElectrumRpc, 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, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, 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 ElectrumReaderNetwork, type ElectrumRpc, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, HintTracker, type HintTrackerOptions, 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, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };

package/dist/index.js

@@ -1216,6 +1216,113 @@ function defaultEvmReaders(overrides) {
   return readers;
 }
 
+// src/hints/hint-tracker.ts
+var HintTracker = class {
+  #fetchStatus;
+  #refreshIntervalMs;
+  #swaps = /* @__PURE__ */ new Map();
+  /** Last server-reported status per swap (seeded from storage, updated by hints). */
+  #statuses = /* @__PURE__ */ new Map();
+  /** Last actions emitted per swap — for dedupe and the subscribe-time snapshot. */
+  #lastActions = /* @__PURE__ */ new Map();
+  #subscribers = /* @__PURE__ */ new Set();
+  #timer;
+  constructor(options) {
+    this.#fetchStatus = options.fetchStatus;
+    this.#refreshIntervalMs = options.refreshIntervalMs ?? 5e3;
+  }
+  /**
+   * Always `true`: with no chain readers there is no reachability constraint.
+   * (Claim/refund execution has its own chain configuration, independent of
+   * tracking.)
+   */
+  canObserve(_swap) {
+    return true;
+  }
+  /** Register the swaps, derive each one's first action from its stored status. */
+  async startTracking(swaps) {
+    for (const swap of swaps) this.#admit(swap);
+    this.#recomputeAll();
+    if (this.#refreshIntervalMs > 0)
+      this.#timer = setInterval(
+        () => this.#recomputeAll(),
+        this.#refreshIntervalMs
+      );
+  }
+  /**
+   * Track one more swap after {@link startTracking}. Idempotent: a swap already
+   * tracked, or one already seen through to a terminal action, is ignored.
+   */
+  async track(swap) {
+    if (this.#swaps.has(swap.swapId) || this.#lastActions.has(swap.swapId))
+      return;
+    this.#admit(swap);
+    this.#recompute(swap);
+  }
+  #admit(swap) {
+    this.#swaps.set(swap.swapId, swap);
+    if (swap.storedStatus !== void 0 && !this.#statuses.has(swap.swapId))
+      this.#statuses.set(swap.swapId, swap.storedStatus);
+  }
+  /** The swap ids currently tracked — e.g. to subscribe them to the hint feed. */
+  trackedSwapIds() {
+    return [...this.#swaps.keys()];
+  }
+  /**
+   * Apply a server status to one swap and recompute its action. A hint that
+   * carries the pushed `status` is applied as-is; without one (the worker's
+   * retry and post-reconnect paths) the status is re-fetched from the server.
+   * A no-op for an untracked swap.
+   */
+  async applyHint(swapId, opts) {
+    const swap = this.#swaps.get(swapId);
+    if (!swap) return;
+    const status = opts?.status ?? await this.#fetchStatus(swapId);
+    if (!this.#swaps.has(swapId)) return;
+    this.#statuses.set(swapId, status);
+    this.#recompute(swap, opts?.force ?? false);
+  }
+  /** Notify `cb` of the current action for each tracked swap, then on every change. */
+  subscribeToActions(cb) {
+    this.#subscribers.add(cb);
+    for (const [swapId, actions] of this.#lastActions) cb(swapId, actions);
+    return () => this.#subscribers.delete(cb);
+  }
+  /** Stop tracking: drop the tick timer, tracked swaps, and subscribers. */
+  stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = void 0;
+    this.#swaps.clear();
+    this.#subscribers.clear();
+  }
+  #recomputeAll() {
+    for (const swap of this.#swaps.values()) this.#recompute(swap);
+  }
+  #recompute(swap, force = false) {
+    const status = this.#statuses.get(swap.swapId);
+    if (status === void 0) return;
+    const now = Date.now();
+    const actions = deriveSwapActions({
+      status,
+      clientChainNow: now,
+      serverChainNow: now,
+      clientRefundLocktime: swap.clientRefundLocktime,
+      serverRefundLocktime: swap.serverRefundLocktime,
+      // Pay-on-Lightning swaps have no client-funded on-chain leg.
+      clientFunds: swap.clientHtlc !== void 0
+    });
+    const previous = this.#lastActions.get(swap.swapId);
+    if (!force && previous && JSON.stringify(previous) === JSON.stringify(actions))
+      return;
+    this.#lastActions.set(swap.swapId, actions);
+    for (const cb of this.#subscribers) cb(swap.swapId, actions);
+    if (actions.recommended === "none") {
+      this.#swaps.delete(swap.swapId);
+      this.#statuses.delete(swap.swapId);
+    }
+  }
+};
+
 // src/hints/swap-worker.ts
 var AUTO_EXECUTABLE = /* @__PURE__ */ new Set([
   "claim"
@@ -1249,8 +1356,8 @@ var SwapWorker = class {
     this.#started = true;
     this.#hintSource.subscribe(this.#tracker.trackedSwapIds());
     this.#unsubs.push(
-      this.#hintSource.onStatus(({ swapId }) => {
-        void this.#tracker.applyHint(swapId).catch((error) => {
+      this.#hintSource.onStatus(({ swapId, status }) => {
+        void this.#tracker.applyHint(swapId, { status }).catch((error) => {
           console.warn(`SwapWorker: applyHint(${swapId}) failed:`, error);
         });
       })
@@ -2415,8 +2522,11 @@ var Client = class {
   /**
    * Start observing the user's active swaps and deriving each one's next action.
    *
-   * Loads stored swaps, maps the ones whose ledgers are observable to
-   * {@link TrackedSwap}s, and runs the per-ledger monitors. Idempotent. Requires
+   * Loads stored swaps, maps them to {@link TrackedSwap}s, and derives each
+   * one's actions — by default from the server's status hints alone (TEMP while
+   * the chain monitors are buggy; see
+   * {@link ClientBuilder.withChainVerifiedTracking} to re-enable the per-ledger
+   * chain monitors). Idempotent. Requires
    * the client to have been built with {@link ClientBuilder.withTracking}.
    * Subscribe with {@link subscribeToActions}; release with
    * {@link stopTracking}.
@@ -2436,7 +2546,11 @@ var Client = class {
   }
   async #doStartTracking() {
     try {
-      const tracker = new SwapTracker(await this.#ensureManagers(), {
+      const chainVerified = this.#tracking.chainVerified || this.#tracking.managers !== void 0;
+      const tracker = chainVerified ? new SwapTracker(await this.#ensureManagers(), {
+        refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
+      }) : new HintTracker({
+        fetchStatus: async (swapId) => (await this.getSwap(swapId, { updateStorage: true })).status,
         refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
       });
       this.#tracker = tracker;
@@ -2485,7 +2599,9 @@ var Client = class {
     const swaps = await this.listAllSwaps();
     return swaps.filter((s) => !SETTLED_STORED_STATUSES.has(s.response.status)).map((s) => {
       try {
-        return swapToTracked(s);
+        const tracked = swapToTracked(s);
+        if (!tracked) return void 0;
+        return { ...tracked, storedStatus: s.response.status };
       } catch (error) {
         console.warn(
           `Client: skipping untrackable stored swap ${s.response.id}:`,
@@ -2563,7 +2679,7 @@ var Client = class {
    * otherwise it runs observe-only, hints in, no spends.
    */
   #startWorker(tracker) {
-    const serverUrl = this.#tracking.serverUrl;
+    const serverUrl = this.#tracking.serverUrl ?? legacyBaseUrl(this.#legacy);
     if (!serverUrl) return;
     const autoClaim = this.#tracking.autoClaim;
     const hintSource = new WsStatusSource({ serverUrl });
@@ -2661,6 +2777,7 @@ var ClientBuilder = class {
   #evmRpcUrls;
   #managers;
   #autoClaim;
+  #chainVerified = false;
   /**
    * Override the EVM JSON-RPC endpoint per chainId. Optional — tracking uses
    * tested public defaults otherwise; an override is tried first, with the
@@ -2687,6 +2804,16 @@ var ClientBuilder = class {
     this.#trackingEnabled = false;
     return this;
   }
+  /**
+   * Verify swap state against the chain (per-ledger contract managers) instead
+   * of trusting the server's status hints. TEMPORARILY off by default while the
+   * chain monitors are being fixed — without it, tracking derives actions from
+   * the server's pushed status alone, with zero chain access.
+   */
+  withChainVerifiedTracking() {
+    this.#chainVerified = true;
+    return this;
+  }
   /**
    * Advanced: supply per-ledger {@link ContractManager}s explicitly instead of
    * letting the client auto-build them from config (useful for tests or custom
@@ -2804,10 +2931,18 @@ var ClientBuilder = class {
       bitcoinNetwork: this.#bitcoinNetwork,
       bitcoinMinConfirmations: this.#bitcoinMinConfirmations,
       evmRpcUrls: this.#evmRpcUrls,
-      autoClaim: this.#autoClaim
+      autoClaim: this.#autoClaim,
+      chainVerified: this.#chainVerified
     });
   }
 };
+function legacyBaseUrl(legacy) {
+  try {
+    return legacy.baseUrl;
+  } catch {
+    return void 0;
+  }
+}
 var SETTLED_STORED_STATUSES = /* @__PURE__ */ new Set([
   "serverredeemed",
   "clientrefunded",
@@ -2828,6 +2963,7 @@ export {
   DEFAULT_ESPLORA_URLS,
   DEFAULT_EVM_RPCS,
   EvmContractManager,
+  HintTracker,
   SwapTracker,
   SwapWorker,
   WsStatusSource,