@satora/swap 0.0.5 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,1177 @@
+import { SwapStatus, Client as Client$1, ClientBuilder as ClientBuilder$1, StoredSwap } from '@lendasat/lendaswap-sdk-pure';
 export * from '@lendasat/lendaswap-sdk-pure';
-import '@lendasat/lendaswap-sdk-pure/node';
-import '@lendasat/lendaswap-sdk-pure/delegate';
-import '@lendasat/lendaswap-sdk-pure/cctp-bridge';
+import { VirtualCoin } from '@arkade-os/sdk';
+import { Log, Block } from 'viem';
+
+/**
+ * The derived "what should the client do next?" model.
+ *
+ * `SwapStatus` says what *happened*; `SwapActions` says what the client *can or
+ * should do*. Actions are produced by the pure resolver {@link deriveSwapActions}
+ * from a plain {@link SwapActionInput} snapshot — no I/O, so the whole decision
+ * matrix is testable with mocked states.
+ */
+
+/**
+ * How the background worker may run an action — the load-bearing safety field.
+ * `fund` is never `auto` (spends new money); claim / cctp-mint completion are
+ * safe to `auto` (they protect or continue existing funds); refunds are
+ * `confirm` (the user should know).
+ */
+type SwapActionAutomation = "auto" | "confirm" | "manual";
+/** Typed reasons an action can't run yet — no free strings. */
+type BlockedReason = "timelock_not_expired";
+type BlockedBy = {
+    kind: BlockedReason;
+    message: string;
+};
+/** Fields common to every action variant. */
+type SwapActionBase = {
+    /** The SDK's suggested pick among the set. Exactly one action is recommended. */
+    recommended: boolean;
+    automation: SwapActionAutomation;
+    /** Human-readable why — for UI copy and worker logs. */
+    reason: string;
+    /**
+     * Why the action can't run yet. Absent ⟺ the action is runnable now; present
+     * ⟺ it's a valid-but-blocked option the UI can surface (e.g. "refund after the
+     * timelock"). The recommended action is always runnable (no `blockedBy`).
+     */
+    blockedBy?: BlockedBy;
+};
+/** Strongly-typed evidence, only where an action needs it. */
+type CctpClaimEvidence = {
+    burnTxHash: `0x${string}`;
+    attestationAvailable: boolean;
+};
+type WaitAction = SwapActionBase & {
+    id: "wait";
+};
+type FundAction = SwapActionBase & {
+    id: "fund";
+};
+type ClaimAction = SwapActionBase & {
+    id: "claim";
+};
+type RefundCollaborativeAction = SwapActionBase & {
+    id: "refund_collaborative";
+};
+/** Reclaim the deposit yourself once the timelock passes — venue-agnostic (BTC L1, EVM, or Arkade). */
+type RefundUnilateralAction = SwapActionBase & {
+    id: "refund_unilateral";
+};
+type RecoverCctpClaimAction = SwapActionBase & {
+    id: "recover_cctp_claim";
+    evidence: CctpClaimEvidence;
+};
+type NoneAction = SwapActionBase & {
+    id: "none";
+};
+/** A single next-action option. Discriminated union on `id`. */
+type SwapAction = WaitAction | FundAction | ClaimAction | RefundCollaborativeAction | RefundUnilateralAction | RecoverCctpClaimAction | NoneAction;
+/** Every valid action id — derived from the union so it can't drift. */
+type SwapActionId = SwapAction["id"];
+/** The resolver's result: what happened is `status`; what to do is here. */
+type SwapActions = {
+    /** id of the recommended action, if any; convenience pointer into `actions`. */
+    recommended?: SwapActionId;
+    actions: SwapAction[];
+};
+/**
+ * The pure input to {@link deriveSwapActions}: a plain, fully-resolved snapshot.
+ *
+ * The resolver reads nothing ambient — `now` is injected (never `Date.now()`),
+ * and every environment fact is a field here. Grows as more states are modelled;
+ * unknown/omitted live facts make the resolver return a provisional or blocked
+ * action rather than reaching out for them.
+ */
+type SwapActionInput = {
+    /**
+     * The swap's lifecycle status. Trusted source is the chain-derived status from
+     * {@link deriveSwapStatus}; the server's status is only a hint the wrapper
+     * cross-checks against it.
+     */
+    status: SwapStatus;
+    /**
+     * Current time (ms) on the chain holding the CLIENT's HTLC — the chain's own
+     * clock used to evaluate its timelock, NOT wall-clock: MTP (median-time-past)
+     * for Bitcoin/Arkade, block.timestamp for EVM, invoice-clock for Lightning.
+     * Injected so the resolver stays deterministic. (A wall-clock approximation
+     * works for a UI hint, but the chain's clock is what actually gates the swap.)
+     */
+    clientChainNow: number;
+    /** As {@link clientChainNow}, for the chain holding the SERVER's HTLC. */
+    serverChainNow: number;
+    /**
+     * Timelock (ms) on the client's HTLC, evaluated against {@link clientChainNow}.
+     * Bounds funding (pending: fund before it) and unlocks the unilateral refund
+     * (clientfunded: refund after it) — the same locktime, two readings.
+     */
+    clientRefundLocktime: number;
+    /**
+     * Timelock (ms) on the server's HTLC, evaluated against {@link serverChainNow}
+     * — the client's deadline to claim. Past it the server may reclaim its funds,
+     * so claiming becomes a race.
+     */
+    serverRefundLocktime: number;
+    /**
+     * Whether the client's deposit is an on-chain HTLC it funds itself (the
+     * default). `false` for pay-on-Lightning swaps (`lightning_to_*`): there the
+     * client "funds" by paying a Lightning invoice off-chain, so there is nothing
+     * for us to recommend funding and nothing to unilaterally refund — the
+     * Lightning wallet auto-unwinds a hold invoice that never settles. When
+     * `false`, `pending` resolves to `wait` (not `fund`) and no refund is offered.
+     */
+    clientFunds?: boolean;
+};
+/** On-chain state of one HTLC in a swap. */
+type HtlcObservation = "absent" | "mempool" | "confirmed" | "invalid" | "spent_claim" | "spent_refund";
+/**
+ * On-chain facts about a swap's two HTLCs, from the client's own observation (no
+ * server trust). `clientHtlc` is the HTLC the client funded; `serverHtlc` the one
+ * the server funded and the client claims.
+ *
+ * Spend semantics differ per side: on `clientHtlc`, `spent_claim` = the server
+ * swept it with the revealed preimage and `spent_refund` = the client reclaimed
+ * its deposit; on `serverHtlc`, `spent_claim` = the client redeemed and
+ * `spent_refund` = the server reclaimed its funds.
+ *
+ * One leg may be `undefined` for Lightning swaps. These are Boltz submarine swaps
+ * between an Arkade VHTLC and Lightning, so the "Lightning side" is itself realized
+ * on-chain as an Arkade VHTLC (`boltz_vhtlc_address`, or reconstructed for the EVM
+ * directions) — except `lightning_to_arkade`, whose Boltz reverse swap outputs the
+ * very VHTLC the client claims. That Boltz-side VHTLC is observable but not tracked
+ * yet: the client never funds or claims it, so it doesn't change the next action.
+ * We watch only the single leg the client funds or claims:
+ * - `serverHtlc` undefined (receive-on-LN, `*_to_lightning`): the client funds
+ *   the on-chain leg and receives via Lightning; the server sweeping the
+ *   client's leg (`spent_claim`) is the completion signal.
+ * - `clientHtlc` undefined (pay-on-LN, `lightning_to_*`): the client pays a
+ *   Lightning invoice and claims the on-chain leg; that claim completes the swap.
+ */
+type SwapObservations = {
+    clientHtlc?: HtlcObservation;
+    serverHtlc?: HtlcObservation;
+};
+
+declare function deriveSwapActions(input: SwapActionInput): SwapActions;
+
+/**
+ * Derive a swap's lifecycle status from on-chain observations alone — the
+ * trusted, server-independent source of truth.
+ *
+ * Pure: `deriveSwapStatus(observations) -> SwapStatus | undefined`. The wrapper
+ * gathers the {@link SwapObservations} from chain (the server's status is only a
+ * hint used to fetch efficiently), then cross-checks: if this disagrees with the
+ * server, act on this. If the server is unavailable, derive from the local
+ * recovery bundle's HTLC addresses — recovery still works.
+ *
+ * Returns `undefined` for contradictory/indeterminate observations (e.g. the
+ * server's HTLC swept-by-claim while the client's HTLC was never involved — the
+ * server can't hold the preimage before the client reveals it).
+ *
+ * Scope: this maps *settled* HTLC state to a status. Time- or param-dependent
+ * refinements aren't derivable from HTLC state alone and are layered on
+ * afterwards (or collapse into the state here):
+ * - `expired` / `clientfundedtoolate`: `pending`/`clientfunded` + a clock check.
+ * - `clientinvalidfunded`: needs the expected HTLC params, not just "confirmed".
+ * - `serverwontfund`: a server intention, invisible on-chain — acts like
+ *   `clientfunded` (refund after the timelock), so it never needs deriving.
+ * - `clientredeeming`: an in-flight (mempool) claim — a transient, not modelled
+ *   from settled state here.
+ */
+
+declare function deriveSwapStatus(obs: SwapObservations): SwapStatus | undefined;
+
+/**
+ * The contract-monitoring layer — modeled on @arkade-os/sdk's
+ * `ContractManager`.
+ *
+ * A {@link ContractManager} is the per-ledger, stateful I/O layer that watches a
+ * set of HTLCs and maps their on-chain state to {@link HtlcObservation}. The pure
+ * pipeline (`deriveSwapStatus` → `deriveSwapActions`) consumes the observations
+ * it produces; a `SwapTracker` (built later) combines the two ledgers of each
+ * swap and notifies subscribers of the next action.
+ */
+
+/** Ledgers a swap HTLC can live on. */
+type Ledger = "arkade" | "bitcoin" | "evm" | "lightning";
+/**
+ * Identifies and parameterises one HTLC on its ledger — enough for a
+ * {@link ContractManager} to observe it. Sourced from the swap's recovery
+ * bundle. Discriminated by `ledger`.
+ */
+type HtlcRef = {
+    ledger: "arkade";
+    /** VHTLC pkScript (hex) — the contract's unique id. */
+    script: string;
+    address: string;
+    /** SHA256 of the preimage, to tell a claim spend from a refund spend. */
+    preimageHash: string;
+    /**
+     * Expected funding amount in sats. A funding below this is `invalid` (not on
+     * the swap's terms) rather than `confirmed` — so the client never claims a
+     * server leg the server short-funded.
+     */
+    expectedSats: number;
+    /**
+     * Serialized VHTLC parameters (`@arkade-os/sdk`'s `Contract.params`) — the
+     * sender/receiver/server keys, preimage hash, and timelocks needed to
+     * register the contract for watching. Opaque here: the Client serializes
+     * it from the swap's recovery bundle so this layer stays VHTLC-agnostic.
+     */
+    params: Record<string, string>;
+} | {
+    ledger: "bitcoin";
+    /** HTLC witness-script address — the contract's unique id. */
+    address: string;
+    preimageHash: string;
+    /** Expected funding amount in sats; a funding below this is `invalid`. */
+    expectedSats: 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.
+     */
+    preimageHash: `0x${string}`;
+    /**
+     * The address that can claim this HTLC — the second indexed topic used to
+     * filter `SwapCreated`, so only the HTLC actually claimable on the swap's
+     * terms is observed (an HTLC with our hash but a different recipient is
+     * never seen). Client's EVM address for a server-funded leg; the server's
+     * for the client's own leg.
+     */
+    claimAddress: `0x${string}`;
+    /**
+     * Expected locked amount (token's smallest unit). A `SwapCreated` below this
+     * → `invalid`, so the client never claims a short-funded leg.
+     */
+    expectedAmount: bigint;
+    /** Expected token address; the funding is `invalid` if it locks another token. */
+    expectedToken?: `0x${string}`;
+} | {
+    ledger: "lightning";
+    /** Payment hash — the contract's unique id. */
+    paymentHash: string;
+};
+/** Stable, cross-ledger unique key for an {@link HtlcRef}. */
+declare function htlcKey(ref: HtlcRef): string;
+/**
+ * Per-ledger contract monitor. Implementations keep an internal, event-driven
+ * cache: `register` seeds it, `onEvent` pushes changes, `getState` reads it
+ * synchronously, `dispose` tears down subscriptions/loops.
+ *
+ * One manager exists per ledger actually in use and watches every tracked HTLC
+ * on that ledger at once (one connection, not one per HTLC).
+ */
+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. */
+    unregister(ref: HtlcRef): Promise<void>;
+    /**
+     * Current known observation for a tracked HTLC, or `undefined` if it isn't
+     * tracked or its state isn't known yet.
+     */
+    getState(ref: HtlcRef): HtlcObservation | undefined;
+    /**
+     * The current clock (ms) for evaluating this HTLC's timelock — MTP for
+     * Bitcoin/Arkade, `block.timestamp` for EVM. Ref-scoped because one ledger can
+     * span several chains with independent clocks (EVM chains); managers whose
+     * ledger has a single clock (Arkade) ignore the ref. `undefined` until known.
+     */
+    chainNow(ref: HtlcRef): number | undefined;
+    /** Subscribe to observation changes for any tracked HTLC. Returns unsubscribe. */
+    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;
+}
+
+/**
+ * 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
+ * on-chain leg (the other side is an off-chain Lightning payment) — see
+ * {@link SwapObservations}.
+ */
+type TrackedSwap = {
+    swapId: string;
+    clientHtlc?: HtlcRef;
+    serverHtlc?: HtlcRef;
+    clientRefundLocktime: number;
+    serverRefundLocktime: number;
+};
+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`).
+     */
+    refreshIntervalMs?: 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;
+    /**
+     * Stop tracking: unregister every still-tracked leg (releasing its manager's
+     * watch — e.g. the EVM per-chain block watch that only `unregister` tears down),
+     * drop the poll timer, and detach event listeners + subscribers. Mirrors
+     * `startTracking`'s `register`, so no manager keeps watching a stopped tracker's
+     * swaps. The managers themselves are not owned here, so they are unregistered but
+     * never disposed.
+     */
+    stop(): void;
+}
+
+/**
+ * @satora/swap — the Satora swap client.
+ *
+ * A standalone `Client` with the same public surface as the legacy
+ * `@lendasat/lendaswap-sdk-pure` client, so it is a drop-in replacement. For
+ * now every legacy method is forwarded to an internally-owned legacy client
+ * instance (see the `@deprecated` delegators below). New Satora-native features
+ * are added directly on this class, and
+ * 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;
+    /** Explicit per-ledger managers, bypassing auto-construction (advanced/testing). */
+    managers?: Map<Ledger, ContractManager>;
+    /** Ark server URL override; defaults to the mainnet server when unset. */
+    arkadeServerUrl?: string;
+    /** Per-chain EVM RPC overrides; the EVM manager is auto-built either way. */
+    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. */
+    refreshIntervalMs?: number;
+    /** Opt-in hint-driven auto-claim; unset leaves tracking observe-only. */
+    autoClaim?: AutoClaimConfig;
+};
+declare class Client {
+    #private;
+    /**
+     * Creates a new Client instance.
+     *
+     * Prefer {@link Client.builder} for new code.
+     */
+    constructor(...args: ConstructorParameters<typeof Client$1>);
+    /** @internal Wrap an already-built legacy client, optionally with tracking. */
+    constructor(legacy: Client$1, tracking?: TrackingConfig);
+    /** Start building a {@link Client}. */
+    static builder(): ClientBuilder;
+    /** Escape hatch: the underlying legacy client, during migration. */
+    get legacy(): Client$1;
+    /** Delegated to the legacy client (migration checkpoint). */
+    get api(): Client$1["api"];
+    /** Delegated to the legacy client (migration checkpoint). */
+    get baseUrl(): Client$1["baseUrl"];
+    /** Delegated to the legacy client (migration checkpoint). */
+    get cctpInbound(): Client$1["cctpInbound"];
+    /** Delegated to the legacy client (migration checkpoint). */
+    get swapStorage(): Client$1["swapStorage"];
+    /** Delegated to the legacy client (migration checkpoint). */
+    subscribeToSwaps(...args: Parameters<Client$1["subscribeToSwaps"]>): ReturnType<Client$1["subscribeToSwaps"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    unsubscribeFromSwaps(...args: Parameters<Client$1["unsubscribeFromSwaps"]>): ReturnType<Client$1["unsubscribeFromSwaps"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    closeSwapStatusSocket(...args: Parameters<Client$1["closeSwapStatusSocket"]>): ReturnType<Client$1["closeSwapStatusSocket"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getMnemonic(...args: Parameters<Client$1["getMnemonic"]>): ReturnType<Client$1["getMnemonic"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    loadMnemonic(...args: Parameters<Client$1["loadMnemonic"]>): ReturnType<Client$1["loadMnemonic"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getNostrKeyHex(...args: Parameters<Client$1["getNostrKeyHex"]>): ReturnType<Client$1["getNostrKeyHex"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getUserIdXpub(...args: Parameters<Client$1["getUserIdXpub"]>): ReturnType<Client$1["getUserIdXpub"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    deriveSwapParams(...args: Parameters<Client$1["deriveSwapParams"]>): ReturnType<Client$1["deriveSwapParams"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    deriveSwapParamsAtIndex(...args: Parameters<Client$1["deriveSwapParamsAtIndex"]>): ReturnType<Client$1["deriveSwapParamsAtIndex"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getEvmAddress(...args: Parameters<Client$1["getEvmAddress"]>): ReturnType<Client$1["getEvmAddress"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getKeyIndex(...args: Parameters<Client$1["getKeyIndex"]>): ReturnType<Client$1["getKeyIndex"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    setKeyIndex(...args: Parameters<Client$1["setKeyIndex"]>): ReturnType<Client$1["setKeyIndex"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getStatus(...args: Parameters<Client$1["getStatus"]>): ReturnType<Client$1["getStatus"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    healthCheck(...args: Parameters<Client$1["healthCheck"]>): ReturnType<Client$1["healthCheck"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getVersion(...args: Parameters<Client$1["getVersion"]>): ReturnType<Client$1["getVersion"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getSupportAgents(...args: Parameters<Client$1["getSupportAgents"]>): ReturnType<Client$1["getSupportAgents"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getMtp(...args: Parameters<Client$1["getMtp"]>): ReturnType<Client$1["getMtp"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getTokens(...args: Parameters<Client$1["getTokens"]>): ReturnType<Client$1["getTokens"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getSwapPairs(...args: Parameters<Client$1["getSwapPairs"]>): ReturnType<Client$1["getSwapPairs"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getChainConfig(...args: Parameters<Client$1["getChainConfig"]>): ReturnType<Client$1["getChainConfig"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getReferralFee(...args: Parameters<Client$1["getReferralFee"]>): ReturnType<Client$1["getReferralFee"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getNetworkFees(...args: Parameters<Client$1["getNetworkFees"]>): ReturnType<Client$1["getNetworkFees"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getDexQuote(...args: Parameters<Client$1["getDexQuote"]>): ReturnType<Client$1["getDexQuote"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    composeQuote(...args: Parameters<Client$1["composeQuote"]>): ReturnType<Client$1["composeQuote"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getQuote(...args: Parameters<Client$1["getQuote"]>): ReturnType<Client$1["getQuote"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getSwap(...args: Parameters<Client$1["getSwap"]>): ReturnType<Client$1["getSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getBulkStatus(...args: Parameters<Client$1["getBulkStatus"]>): ReturnType<Client$1["getBulkStatus"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getStoredSwap(...args: Parameters<Client$1["getStoredSwap"]>): ReturnType<Client$1["getStoredSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    listAllSwaps(...args: Parameters<Client$1["listAllSwaps"]>): ReturnType<Client$1["listAllSwaps"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    deleteSwap(...args: Parameters<Client$1["deleteSwap"]>): ReturnType<Client$1["deleteSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    clearSwapStorage(...args: Parameters<Client$1["clearSwapStorage"]>): ReturnType<Client$1["clearSwapStorage"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    recoverSwaps(...args: Parameters<Client$1["recoverSwaps"]>): ReturnType<Client$1["recoverSwaps"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    recoverAllSwaps(...args: Parameters<Client$1["recoverAllSwaps"]>): ReturnType<Client$1["recoverAllSwaps"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    amountsForSwap(...args: Parameters<Client$1["amountsForSwap"]>): ReturnType<Client$1["amountsForSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    claim(...args: Parameters<Client$1["claim"]>): ReturnType<Client$1["claim"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    claimViaGasless(...args: Parameters<Client$1["claimViaGasless"]>): ReturnType<Client$1["claimViaGasless"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    claimArkade(...args: Parameters<Client$1["claimArkade"]>): ReturnType<Client$1["claimArkade"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    continueArkadeClaimSwap(...args: Parameters<Client$1["continueArkadeClaimSwap"]>): ReturnType<Client$1["continueArkadeClaimSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    refundSwap(...args: Parameters<Client$1["refundSwap"]>): ReturnType<Client$1["refundSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getCollabRefundEvmParams(...args: Parameters<Client$1["getCollabRefundEvmParams"]>): ReturnType<Client$1["getCollabRefundEvmParams"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    buildCollabRefundEvmTypedData(...args: Parameters<Client$1["buildCollabRefundEvmTypedData"]>): ReturnType<Client$1["buildCollabRefundEvmTypedData"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    collabRefundEvmSwap(...args: Parameters<Client$1["collabRefundEvmSwap"]>): ReturnType<Client$1["collabRefundEvmSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    submitCollabRefundEvm(...args: Parameters<Client$1["submitCollabRefundEvm"]>): ReturnType<Client$1["submitCollabRefundEvm"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createSwap(...args: Parameters<Client$1["createSwap"]>): ReturnType<Client$1["createSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createArkadeToEvmSwapGeneric(...args: Parameters<Client$1["createArkadeToEvmSwapGeneric"]>): ReturnType<Client$1["createArkadeToEvmSwapGeneric"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createLightningToEvmSwapGeneric(...args: Parameters<Client$1["createLightningToEvmSwapGeneric"]>): ReturnType<Client$1["createLightningToEvmSwapGeneric"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createBitcoinToEvmSwap(...args: Parameters<Client$1["createBitcoinToEvmSwap"]>): ReturnType<Client$1["createBitcoinToEvmSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createBitcoinToArkadeSwap(...args: Parameters<Client$1["createBitcoinToArkadeSwap"]>): ReturnType<Client$1["createBitcoinToArkadeSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createLightningToArkadeSwap(...args: Parameters<Client$1["createLightningToArkadeSwap"]>): ReturnType<Client$1["createLightningToArkadeSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getArkadeToLightningQuote(...args: Parameters<Client$1["getArkadeToLightningQuote"]>): ReturnType<Client$1["getArkadeToLightningQuote"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    retryArkadeToLightningSwap(...args: Parameters<Client$1["retryArkadeToLightningSwap"]>): ReturnType<Client$1["retryArkadeToLightningSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createEvmToArkadeSwapGeneric(...args: Parameters<Client$1["createEvmToArkadeSwapGeneric"]>): ReturnType<Client$1["createEvmToArkadeSwapGeneric"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createEvmToBitcoinSwap(...args: Parameters<Client$1["createEvmToBitcoinSwap"]>): ReturnType<Client$1["createEvmToBitcoinSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    createEvmToLightningSwapGeneric(...args: Parameters<Client$1["createEvmToLightningSwapGeneric"]>): ReturnType<Client$1["createEvmToLightningSwapGeneric"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getCoordinatorFundingCallDataPermit2(...args: Parameters<Client$1["getCoordinatorFundingCallDataPermit2"]>): ReturnType<Client$1["getCoordinatorFundingCallDataPermit2"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getPermit2FundingParamsUnsigned(...args: Parameters<Client$1["getPermit2FundingParamsUnsigned"]>): ReturnType<Client$1["getPermit2FundingParamsUnsigned"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    fundSwap(...args: Parameters<Client$1["fundSwap"]>): ReturnType<Client$1["fundSwap"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    refundEvmWithSigner(...args: Parameters<Client$1["refundEvmWithSigner"]>): ReturnType<Client$1["refundEvmWithSigner"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    collabRefundEvmWithSigner(...args: Parameters<Client$1["collabRefundEvmWithSigner"]>): ReturnType<Client$1["collabRefundEvmWithSigner"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    fundSwapGasless(...args: Parameters<Client$1["fundSwapGasless"]>): ReturnType<Client$1["fundSwapGasless"]>;
+    /** Delegated to the legacy client (migration checkpoint). */
+    getSwapDepositorKey(...args: Parameters<Client$1["getSwapDepositorKey"]>): ReturnType<Client$1["getSwapDepositorKey"]>;
+    /** 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"]>;
+    /**
+     * 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
+     * the client to have been built with {@link ClientBuilder.withTracking}.
+     * Subscribe with {@link subscribeToActions}; release with
+     * {@link stopTracking}.
+     */
+    startTracking(): Promise<void>;
+    /**
+     * Subscribe to next-action updates: `cb` fires with the current action for each
+     * tracked swap immediately, then on every change. Call after
+     * {@link startTracking}. Returns an unsubscribe fn.
+     */
+    subscribeToActions(cb: ActionSubscriber): () => void;
+    /** Stop tracking and drop subscribers. The managers themselves are not disposed. */
+    stopTracking(): void;
+}
+/**
+ * Builds a {@link Client}. Mirrors the legacy `ClientBuilder` fluent surface and
+ * constructs the legacy client internally, then wraps it.
+ */
+declare class ClientBuilder {
+    #private;
+    /**
+     * Override the EVM JSON-RPC endpoint per chainId. Optional — tracking uses
+     * tested public defaults otherwise; an override is tried first, with the
+     * 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;
+    /**
+     * Advanced: supply per-ledger {@link ContractManager}s explicitly instead of
+     * letting the client auto-build them from config (useful for tests or custom
+     * chain sources).
+     */
+    withContractManagers(managers: Map<Ledger, ContractManager>): this;
+    withBaseUrl(...args: Parameters<ClientBuilder$1["withBaseUrl"]>): this;
+    withReferralCode(...args: Parameters<ClientBuilder$1["withReferralCode"]>): this;
+    withOrgCode(...args: Parameters<ClientBuilder$1["withOrgCode"]>): this;
+    withDefaultHeaders(...args: Parameters<ClientBuilder$1["withDefaultHeaders"]>): this;
+    /**
+     * Override the Esplora REST URL. Optional for tracking — the Bitcoin manager
+     * otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
+     */
+    withEsploraUrl(url: string): 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.
+     */
+    withArkadeServerUrl(url: string): this;
+    withSignerStorage(...args: Parameters<ClientBuilder$1["withSignerStorage"]>): this;
+    withSwapStorage(...args: Parameters<ClientBuilder$1["withSwapStorage"]>): this;
+    withMnemonic(...args: Parameters<ClientBuilder$1["withMnemonic"]>): this;
+    withXprv(...args: Parameters<ClientBuilder$1["withXprv"]>): this;
+    withAa(...args: Parameters<ClientBuilder$1["withAa"]>): this;
+    withLogger(...args: Parameters<ClientBuilder$1["withLogger"]>): this;
+    withLogLevel(...args: Parameters<ClientBuilder$1["withLogLevel"]>): this;
+    build(): Promise<Client>;
+}
+
+/** The slice of `@arkade-os/sdk`'s indexer the spend classifier needs. */
+type VirtualTxSource = {
+    getVirtualTxs(txids: string[]): Promise<{
+        txs: string[];
+    }>;
+};
+
+/**
+ * The Arkade {@link ContractManager} — the stateful I/O adapter that observes a
+ * swap's VHTLC by polling 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
+ * no `forfeit()` leaf (it exposes `claim()`/`refund()`), so watching a VHTLC
+ * through it throws. Instead we read vtxos directly by pkScript — exactly what
+ * 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).
+ */
+
+/** The Ark indexer surface the observer needs (RestIndexerProvider satisfies it). */
+type ArkadeIndexer = VirtualTxSource & {
+    getVtxos(opts: {
+        scripts: string[];
+        spendableOnly?: boolean;
+    }): Promise<{
+        vtxos: VirtualCoin[];
+    }>;
+};
+type ArkadeCreateConfig = {
+    /** Ark server base URL — used for the indexer. */
+    serverUrl: string;
+    /**
+     * The current Bitcoin MTP (ms) for evaluating VHTLC timelocks. Typically
+     * `async () => (await client.getMtp()).mtp * 1000`.
+     */
+    chainTime?: () => Promise<number>;
+};
+type ArkadeContractManagerDeps = {
+    indexer: ArkadeIndexer;
+    /**
+     * The current Bitcoin MTP (ms) — arkade CLTV timelocks are evaluated against
+     * Bitcoin's clock, not the Ark server's. Optional: until wired, `chainNow()`
+     * reports `undefined` and the tracker holds swaps as provisional.
+     */
+    chainTime?: () => Promise<number>;
+};
+declare class ArkadeContractManager implements ContractManager {
+    #private;
+    readonly ledger: Ledger;
+    private constructor();
+    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;
+}
+
+/**
+ * The default Ark server URL for a Bitcoin network name (case-insensitive), or
+ * `undefined` for networks without a public default (e.g. regtest/testnet),
+ * where a URL must be supplied explicitly.
+ */
+declare function defaultArkadeServerUrl(network: string): string | undefined;
+
+type ArkadeRef = Extract<HtlcRef, {
+    ledger: "arkade";
+}>;
+type ArkadeVhtlcInput = {
+    /** Pubkey hex (x-only or compressed) for each VHTLC role. */
+    senderPk: string;
+    receiverPk: string;
+    serverPk: string;
+    /**
+     * The swap's `hash_lock`, hex, `0x`-prefixed or not. Either `sha256(preimage)`
+     * (32 bytes — most directions) or the `ripemd160(sha256(preimage))` HASH160 the
+     * VHTLC commits to directly (20 bytes — `btc_to_arkade`). Length disambiguates.
+     */
+    hashLock: string;
+    /** The VHTLC address the server reported. */
+    address: string;
+    /** Absolute CLTV refund locktime (unix seconds). */
+    refundLocktime: number;
+    /** Relative unilateral delays (seconds). */
+    unilateralClaimDelay: number;
+    unilateralRefundDelay: number;
+    unilateralRefundWithoutReceiverDelay: number;
+    /** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
+    expectedSats: number;
+};
+/**
+ * The VHTLC always commits to `ripemd160(sha256(preimage))` (HASH160). When
+ * `hashLock` is `sha256(preimage)` (32 bytes) we hash it once more to get that;
+ * when it is already the HASH160 (20 bytes, `btc_to_arkade`) we use it as-is. The
+ * ref keeps `preimageHash` as the raw `hashLock` — whatever length — and the spend
+ * classifier verifies a revealed preimage against it, auto-detecting the algorithm
+ * from that length.
+ */
+declare function buildArkadeVhtlcRef(input: ArkadeVhtlcInput): ArkadeRef;
+
+/** On-chain funding state of the HTLC address. */
+type BitcoinFunding = "absent" | "mempool" | "confirmed";
+/** Facts gathered for an HTLC address from esplora. */
+type BitcoinHtlcFacts = {
+    funding: BitcoinFunding;
+    /** Total sats paid to the HTLC address by the funding tx (0 when absent). */
+    fundedSats: number;
+    /**
+     * The witness stack (hex items) of the input that spent the HTLC output, if it
+     * was spent. Absent while the output is still unspent.
+     */
+    spendWitness?: string[];
+};
+
+/** 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>;
+};
+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>;
+};
+type BitcoinContractManagerDeps = {
+    reader: BitcoinChainReader;
+    chainTime?: () => Promise<number>;
+};
+declare class BitcoinContractManager implements ContractManager {
+    #private;
+    readonly ledger: Ledger;
+    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;
+}
+
+/**
+ * A esplora-backed {@link BitcoinChainReader} — the concrete chain source the
+ * {@link BitcoinContractManager} uses in production.
+ *
+ * Kept separate from the manager so the manager stays free of any HTTP/esplora
+ * dependency (and unit-testable against a fake reader). A single
+ * `GET /address/{addr}/txs` yields both the funding state and the spending
+ * input's witness, so no extra round-trips are needed.
+ */
+
+/** The slice of esplora's tx JSON we read. */
+type EsploraTx = {
+    vin: Array<{
+        witness?: string[];
+        prevout?: {
+            scriptpubkey_address?: string;
+        } | null;
+    }>;
+    vout: Array<{
+        scriptpubkey_address?: string;
+        value?: number;
+    }>;
+    status?: {
+        confirmed?: boolean;
+    };
+};
+/**
+ * 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.
+ */
+declare function htlcFactsFromEsploraTxs(txs: EsploraTx[], address: string): BitcoinHtlcFacts;
+/**
+ * Public esplora endpoints tried in rotation (mainnet). blockstream.info runs the
+ * reference esplora, so it's API-compatible with mempool.space; spreading calls
+ * across both halves the per-provider load and survives one being throttled.
+ */
+declare const DEFAULT_ESPLORA_URLS: string[];
+/**
+ * Build a {@link BitcoinChainReader} over one or more esplora REST endpoints.
+ * With several, each call starts at a rotating endpoint (to spread load across
+ * 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;
+
+/**
+ * The `EvmContractManager`'s pure core.
+ *
+ * An EVM HTLC (an `HTLCErc20` swap) exposes its lifecycle as three events, all
+ * indexed by the swap's `preimageHash`: `SwapCreated` (funded), `SwapRedeemed`
+ * (claimed — reveals the preimage), and `SwapRefunded` (reclaimed after the
+ * timelock). This maps a decoded event history to an {@link HtlcObservation}.
+ */
+
+/** One decoded `HTLCErc20` lifecycle event for a single swap's `preimageHash`. */
+type EvmHtlcEvent = {
+    kind: "created";
+    amount: bigint;
+    token: `0x${string}`;
+} | {
+    kind: "redeemed";
+    preimage: `0x${string}`;
+} | {
+    kind: "refunded";
+};
+
+/**
+ * The EVM {@link ContractManager} — the stateful I/O adapter that observes
+ * `HTLCErc20` swaps across one or more EVM chains.
+ *
+ * Reading chain state is delegated to an injected {@link EvmChainReader} (one per
+ * chainId) rather than a bundled viem/ethers client, so the swap package stays
+ * chain-library-agnostic and this adapter is testable against a fake. The pure
+ * event→observation mapping lives in `./evm.js`.
+ *
+ * Unlike Arkade, EVM spans multiple chains with independent `block.timestamp`
+ * clocks, so this manager is chain-aware: it routes each ref by `chainId` and
+ * {@link chainNow} is ref-scoped.
+ */
+
+/** 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)`.
+     */
+    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;
+};
+type EvmContractManagerDeps = {
+    /** A chain reader per EVM `chainId` this manager serves. */
+    readers: Map<number, EvmChainReader>;
+};
+declare class EvmContractManager implements ContractManager {
+    #private;
+    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;
+}
+
+/**
+ * A viem-backed {@link EvmChainReader} — the concrete chain source the
+ * {@link EvmContractManager} uses in production.
+ *
+ * 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.
+ */
+
+/**
+ * Tested public RPC endpoints per supported chainId, tried in order via viem's
+ * ranked `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 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;
+};
+/** 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.
+ */
+declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
+/**
+ * Resolve the per-chain readers used for tracking: the tested {@link
+ * DEFAULT_EVM_RPCS} by default, with any `overrides` taking priority for their
+ * chain (kept ahead of the defaults, which remain as fallbacks).
+ */
+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.
+ *
+ * The recovery bundle (`StoredSwap.response`) is a discriminated union over swap
+ * directions; each carries the two HTLC legs and their refund locktimes. This
+ * extracts the client-funded and server-funded HTLCs plus their locktimes so the
+ * pure pipeline can derive the next action.
+ *
+ * Directions whose both legs are observable today (Arkade↔EVM, Bitcoin↔EVM) are
+ * mapped; others return `undefined` until their ledger managers exist, rather than
+ * producing a half-watchable swap.
+ */
+
+declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
+
+export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, swapToTracked };