@satora/swap 1.3.3 → 1.5.0

package/dist/index.d.cts

@@ -161,6 +161,16 @@ type SwapActionInput = {
      * `false`, `pending` resolves to `wait` (not `fund`) and no refund is offered.
      */
     clientFunds?: boolean;
+    /**
+     * Whether the server's leg is an on-chain HTLC the client claims (the
+     * default). `false` for receive-on-Lightning swaps (`*_to_lightning`): there
+     * the server "funds" by paying the client's invoice off-chain, so there is
+     * nothing to claim and no claim window — {@link serverRefundLocktime} is
+     * meaningless. When `false`, `serverfunded` (the payment is in flight)
+     * resolves to `wait`, with the unilateral refund listed but blocked until
+     * the client's own timelock, exactly like `clientfunded`.
+     */
+    serverFunds?: boolean;
 };
 /** On-chain state of one HTLC in a swap. */
 type HtlcObservation = "absent" | "mempool" | "confirmed" | "invalid" | "spent_claim" | "spent_refund";
@@ -426,9 +436,10 @@ type SwapTrackerOptions = {
      * leg holds funds on-chain (≥ clientfunded, unresolved), where refund safety
      * must not depend on the server. Everything else advances on server hints
      * only ({@link applyHint}); a swap with nothing at stake costs zero chain
-     * reads. Default 60s.
+     * reads. A getter is read on every tick, so the cadence can follow a
+     * setting that changes on a live client. Default 60s.
      */
-    atRiskReconcileIntervalMs?: number;
+    atRiskReconcileIntervalMs?: number | (() => number);
 };
 declare class SwapTracker {
     #private;
@@ -462,6 +473,7 @@ declare class SwapTracker {
      */
     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;
@@ -682,6 +694,8 @@ declare class Client {
     /** Delegated to the legacy client (migration checkpoint). */
     createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
     /** Delegated to the legacy client (migration checkpoint). */
+    createEvmToLightningSwap(...args: Parameters<Client$1["createEvmToLightningSwap"]>): ReturnType<Client$1["createEvmToLightningSwap"]>;
+    /** 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"]>;
@@ -709,6 +723,17 @@ declare class Client {
     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"]>;
+    /** Confirmations a server-funded Bitcoin HTLC needs before it is claimable. */
+    getBitcoinMinConfirmations(): number | undefined;
+    /**
+     * At `0` the claim goes out against a mempool funding, trusting the funder
+     * not to replace it once the claim reveals the preimage.
+     *
+     * Only the chain monitors read a depth, so this does nothing unless the
+     * client was built with {@link ClientBuilder.withChainVerifiedTracking}.
+     * Takes effect on subsequent reads, including swaps already tracked.
+     */
+    setBitcoinMinConfirmations(minConfirmations: number | undefined): void;
     /**
      * Start observing the user's active swaps and deriving each one's next action.
      *
@@ -799,7 +824,8 @@ declare class ClientBuilder {
      * funding hits the mempool, which TRUSTS the funder not to double-spend it
      * (claiming publishes the preimage, so a funder that then replaced its
      * funding could take both legs). Set `1` (or more) for a block-depth policy
-     * that doesn't rely on the funder's good behaviour.
+     * that doesn't rely on the funder's good behaviour. Read only by the chain
+     * monitors, so it needs {@link withChainVerifiedTracking} to have any effect.
      */
     withBitcoinMinConfirmations(minConfirmations: number): this;
     /**
@@ -962,67 +988,6 @@ type BitcoinHtlcFacts = {
     spendWitness?: string[];
 };
 
-/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
-type BitcoinChainReader = {
-    /**
-     * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
-     * overrides the reader's default for this address alone — the two legs of a
-     * swap do not share one rule.
-     */
-    getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
-    /**
-     * Optional push capability: invoke `onChange` whenever the address's tx
-     * history changes (e.g. an Electrum scripthash subscription). Returns an
-     * unsubscribe function. When present, the manager reconciles on push
-     * instead of relying solely on the tracker's poll cadence.
-     */
-    subscribe?(address: string, onChange: () => void): () => void;
-};
-type BitcoinCreateConfig = {
-    /** One or more esplora REST base URLs; several are tried in rotation with failover. */
-    esploraUrl: string | string[];
-    /**
-     * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
-     * manager reads via Electrum (fresher than public explorers) and gets push
-     * reconciles via scripthash subscriptions; the esplora reader remains the
-     * fallback on Electrum errors.
-     */
-    electrumWsUrl?: string;
-    /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
-    network?: "mainnet" | "testnet" | "signet" | "regtest";
-    /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
-    chainTime?: () => Promise<number>;
-    /**
-     * Confirmations a funding tx needs before it observes as `confirmed`.
-     * Default `0`: accept an unconfirmed funding, trusting the funder not to
-     * double-spend it (the claim reveals the preimage against it). `1` = wait
-     * for a block.
-     */
-    minConfirmations?: number;
-};
-type BitcoinContractManagerDeps = {
-    reader: BitcoinChainReader;
-    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.
@@ -1050,6 +1015,12 @@ type EsploraTx = {
         block_height?: number;
     };
 };
+/** A depth already resolved to a number, for the pure classifier below. */
+type BitcoinConfirmationPolicy = {
+    minConfirmations?: number;
+};
+/** A depth, or a getter resolved per read so it can change without a rebuild. */
+type MinConfirmationsSource = number | (() => number | undefined);
 /**
  * When a funding tx counts as `confirmed` for observation purposes.
  *
@@ -1062,9 +1033,10 @@ type EsploraTx = {
  * `1` (or more) for a policy that doesn't rely on the funder's good behaviour;
  * values above 1 make the reader fetch the tip height to compute depth.
  */
-type BitcoinConfirmationPolicy = {
-    minConfirmations?: number;
+type BitcoinReaderPolicy = {
+    minConfirmations?: MinConfirmationsSource;
 };
+declare function resolveMinConfirmations(source: MinConfirmationsSource | undefined): number;
 /**
  * Reduce an address's esplora tx history to HTLC facts. If a tx spends an output
  * at the address, that's the resolving spend (its witness classifies claim vs
@@ -1086,7 +1058,69 @@ declare const DEFAULT_ESPLORA_URLS: string[];
  * providers) and fails over to the rest on error — so a throttled or failing
  * provider doesn't stall tracking.
  */
-declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
+declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinReaderPolicy): BitcoinChainReader;
+
+/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
+type BitcoinChainReader = {
+    /**
+     * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
+     * overrides the reader's default for this address alone — the two legs of a
+     * swap do not share one rule.
+     */
+    getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
+    /**
+     * Optional push capability: invoke `onChange` whenever the address's tx
+     * history changes (e.g. an Electrum scripthash subscription). Returns an
+     * unsubscribe function. When present, the manager reconciles on push
+     * instead of relying solely on the tracker's poll cadence.
+     */
+    subscribe?(address: string, onChange: () => void): () => void;
+};
+type BitcoinCreateConfig = {
+    /** One or more esplora REST base URLs; several are tried in rotation with failover. */
+    esploraUrl: string | string[];
+    /**
+     * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
+     * manager reads via Electrum (fresher than public explorers) and gets push
+     * reconciles via scripthash subscriptions; the esplora reader remains the
+     * fallback on Electrum errors.
+     */
+    electrumWsUrl?: string;
+    /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
+    network?: "mainnet" | "testnet" | "signet" | "regtest";
+    /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
+    chainTime?: () => Promise<number>;
+    /**
+     * Confirmations a funding tx needs before it observes as `confirmed`.
+     * Default `0`: accept an unconfirmed funding, trusting the funder not to
+     * double-spend it (the claim reveals the preimage against it). `1` = wait
+     * for a block. Only the server-funded leg reads it; `swapToTracked` pins the
+     * client-funded leg to 1.
+     */
+    minConfirmations?: MinConfirmationsSource;
+};
+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;
+}
 
 /**
  * An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
@@ -1121,7 +1155,7 @@ type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
  * Build a {@link BitcoinChainReader} over an Electrum connection, with push
  * support and an optional fallback reader for outages.
  */
-declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
+declare function electrumReader(client: ElectrumRpc, opts?: BitcoinReaderPolicy & {
     /** Network the HTLC addresses live on; defaults to mainnet. */
     network?: ElectrumReaderNetwork;
     /** Reader consulted when the Electrum server errors (e.g. esplora). */
@@ -1305,6 +1339,8 @@ type EvmLogClient = {
                 address: `0x${string}`[];
                 topics: (`0x${string}`[] | null)[];
                 fromBlock: `0x${string}`;
+                /** Set only when the read is chunked (see `maxBlockRange`). */
+                toBlock?: `0x${string}`;
             }
         ];
     }): Promise<RawLog[]>;
@@ -1317,8 +1353,16 @@ type EvmLogClient = {
     }>;
     getBlock(): Promise<Pick<Block, "timestamp" | "number">>;
 };
+type EvmReaderOptions = {
+    /**
+     * Largest block span one `eth_getLogs` may cover. Some providers cap it
+     * (rpc.rootstock.io: 2000 blocks); a read past the cap is split into
+     * consecutive chunks up to the latest block. Unset means one unbounded call.
+     */
+    maxBlockRange?: bigint;
+};
 /** Build an {@link EvmChainReader} over an existing viem-like client. */
-declare function evmReaderFromClient(client: EvmLogClient): EvmChainReader;
+declare function evmReaderFromClient(client: EvmLogClient, options?: EvmReaderOptions): EvmChainReader;
 /**
  * Build an {@link EvmChainReader} over one or more EVM JSON-RPC endpoints. With
  * several, viem's `fallback` tries them in order and fails over on error.
@@ -1327,7 +1371,7 @@ declare function evmReaderFromClient(client: EvmLogClient): EvmChainReader;
  * public RPCs rate-limiting us (publicnode 403s) — and it contradicts this
  * package's near-zero-RPC design.
  */
-declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
+declare function createEvmRpcReader(rpcUrls: string | string[], options?: EvmReaderOptions): EvmChainReader;
 /**
  * Resolve the per-chain readers used for tracking: the tested {@link
  * DEFAULT_EVM_RPCS} by default, with any `overrides` taking priority for their
@@ -1579,4 +1623,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, 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 };
+export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BitcoinReaderPolicy, 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 MinConfirmationsSource, 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, resolveMinConfirmations, swapToTracked };

package/dist/index.d.ts

@@ -161,6 +161,16 @@ type SwapActionInput = {
      * `false`, `pending` resolves to `wait` (not `fund`) and no refund is offered.
      */
     clientFunds?: boolean;
+    /**
+     * Whether the server's leg is an on-chain HTLC the client claims (the
+     * default). `false` for receive-on-Lightning swaps (`*_to_lightning`): there
+     * the server "funds" by paying the client's invoice off-chain, so there is
+     * nothing to claim and no claim window — {@link serverRefundLocktime} is
+     * meaningless. When `false`, `serverfunded` (the payment is in flight)
+     * resolves to `wait`, with the unilateral refund listed but blocked until
+     * the client's own timelock, exactly like `clientfunded`.
+     */
+    serverFunds?: boolean;
 };
 /** On-chain state of one HTLC in a swap. */
 type HtlcObservation = "absent" | "mempool" | "confirmed" | "invalid" | "spent_claim" | "spent_refund";
@@ -426,9 +436,10 @@ type SwapTrackerOptions = {
      * leg holds funds on-chain (≥ clientfunded, unresolved), where refund safety
      * must not depend on the server. Everything else advances on server hints
      * only ({@link applyHint}); a swap with nothing at stake costs zero chain
-     * reads. Default 60s.
+     * reads. A getter is read on every tick, so the cadence can follow a
+     * setting that changes on a live client. Default 60s.
      */
-    atRiskReconcileIntervalMs?: number;
+    atRiskReconcileIntervalMs?: number | (() => number);
 };
 declare class SwapTracker {
     #private;
@@ -462,6 +473,7 @@ declare class SwapTracker {
      */
     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;
@@ -682,6 +694,8 @@ declare class Client {
     /** Delegated to the legacy client (migration checkpoint). */
     createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
     /** Delegated to the legacy client (migration checkpoint). */
+    createEvmToLightningSwap(...args: Parameters<Client$1["createEvmToLightningSwap"]>): ReturnType<Client$1["createEvmToLightningSwap"]>;
+    /** 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"]>;
@@ -709,6 +723,17 @@ declare class Client {
     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"]>;
+    /** Confirmations a server-funded Bitcoin HTLC needs before it is claimable. */
+    getBitcoinMinConfirmations(): number | undefined;
+    /**
+     * At `0` the claim goes out against a mempool funding, trusting the funder
+     * not to replace it once the claim reveals the preimage.
+     *
+     * Only the chain monitors read a depth, so this does nothing unless the
+     * client was built with {@link ClientBuilder.withChainVerifiedTracking}.
+     * Takes effect on subsequent reads, including swaps already tracked.
+     */
+    setBitcoinMinConfirmations(minConfirmations: number | undefined): void;
     /**
      * Start observing the user's active swaps and deriving each one's next action.
      *
@@ -799,7 +824,8 @@ declare class ClientBuilder {
      * funding hits the mempool, which TRUSTS the funder not to double-spend it
      * (claiming publishes the preimage, so a funder that then replaced its
      * funding could take both legs). Set `1` (or more) for a block-depth policy
-     * that doesn't rely on the funder's good behaviour.
+     * that doesn't rely on the funder's good behaviour. Read only by the chain
+     * monitors, so it needs {@link withChainVerifiedTracking} to have any effect.
      */
     withBitcoinMinConfirmations(minConfirmations: number): this;
     /**
@@ -962,67 +988,6 @@ type BitcoinHtlcFacts = {
     spendWitness?: string[];
 };
 
-/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
-type BitcoinChainReader = {
-    /**
-     * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
-     * overrides the reader's default for this address alone — the two legs of a
-     * swap do not share one rule.
-     */
-    getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
-    /**
-     * Optional push capability: invoke `onChange` whenever the address's tx
-     * history changes (e.g. an Electrum scripthash subscription). Returns an
-     * unsubscribe function. When present, the manager reconciles on push
-     * instead of relying solely on the tracker's poll cadence.
-     */
-    subscribe?(address: string, onChange: () => void): () => void;
-};
-type BitcoinCreateConfig = {
-    /** One or more esplora REST base URLs; several are tried in rotation with failover. */
-    esploraUrl: string | string[];
-    /**
-     * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
-     * manager reads via Electrum (fresher than public explorers) and gets push
-     * reconciles via scripthash subscriptions; the esplora reader remains the
-     * fallback on Electrum errors.
-     */
-    electrumWsUrl?: string;
-    /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
-    network?: "mainnet" | "testnet" | "signet" | "regtest";
-    /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
-    chainTime?: () => Promise<number>;
-    /**
-     * Confirmations a funding tx needs before it observes as `confirmed`.
-     * Default `0`: accept an unconfirmed funding, trusting the funder not to
-     * double-spend it (the claim reveals the preimage against it). `1` = wait
-     * for a block.
-     */
-    minConfirmations?: number;
-};
-type BitcoinContractManagerDeps = {
-    reader: BitcoinChainReader;
-    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.
@@ -1050,6 +1015,12 @@ type EsploraTx = {
         block_height?: number;
     };
 };
+/** A depth already resolved to a number, for the pure classifier below. */
+type BitcoinConfirmationPolicy = {
+    minConfirmations?: number;
+};
+/** A depth, or a getter resolved per read so it can change without a rebuild. */
+type MinConfirmationsSource = number | (() => number | undefined);
 /**
  * When a funding tx counts as `confirmed` for observation purposes.
  *
@@ -1062,9 +1033,10 @@ type EsploraTx = {
  * `1` (or more) for a policy that doesn't rely on the funder's good behaviour;
  * values above 1 make the reader fetch the tip height to compute depth.
  */
-type BitcoinConfirmationPolicy = {
-    minConfirmations?: number;
+type BitcoinReaderPolicy = {
+    minConfirmations?: MinConfirmationsSource;
 };
+declare function resolveMinConfirmations(source: MinConfirmationsSource | undefined): number;
 /**
  * Reduce an address's esplora tx history to HTLC facts. If a tx spends an output
  * at the address, that's the resolving spend (its witness classifies claim vs
@@ -1086,7 +1058,69 @@ declare const DEFAULT_ESPLORA_URLS: string[];
  * providers) and fails over to the rest on error — so a throttled or failing
  * provider doesn't stall tracking.
  */
-declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
+declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinReaderPolicy): BitcoinChainReader;
+
+/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
+type BitcoinChainReader = {
+    /**
+     * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
+     * overrides the reader's default for this address alone — the two legs of a
+     * swap do not share one rule.
+     */
+    getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
+    /**
+     * Optional push capability: invoke `onChange` whenever the address's tx
+     * history changes (e.g. an Electrum scripthash subscription). Returns an
+     * unsubscribe function. When present, the manager reconciles on push
+     * instead of relying solely on the tracker's poll cadence.
+     */
+    subscribe?(address: string, onChange: () => void): () => void;
+};
+type BitcoinCreateConfig = {
+    /** One or more esplora REST base URLs; several are tried in rotation with failover. */
+    esploraUrl: string | string[];
+    /**
+     * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
+     * manager reads via Electrum (fresher than public explorers) and gets push
+     * reconciles via scripthash subscriptions; the esplora reader remains the
+     * fallback on Electrum errors.
+     */
+    electrumWsUrl?: string;
+    /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
+    network?: "mainnet" | "testnet" | "signet" | "regtest";
+    /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
+    chainTime?: () => Promise<number>;
+    /**
+     * Confirmations a funding tx needs before it observes as `confirmed`.
+     * Default `0`: accept an unconfirmed funding, trusting the funder not to
+     * double-spend it (the claim reveals the preimage against it). `1` = wait
+     * for a block. Only the server-funded leg reads it; `swapToTracked` pins the
+     * client-funded leg to 1.
+     */
+    minConfirmations?: MinConfirmationsSource;
+};
+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;
+}
 
 /**
  * An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
@@ -1121,7 +1155,7 @@ type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
  * Build a {@link BitcoinChainReader} over an Electrum connection, with push
  * support and an optional fallback reader for outages.
  */
-declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
+declare function electrumReader(client: ElectrumRpc, opts?: BitcoinReaderPolicy & {
     /** Network the HTLC addresses live on; defaults to mainnet. */
     network?: ElectrumReaderNetwork;
     /** Reader consulted when the Electrum server errors (e.g. esplora). */
@@ -1305,6 +1339,8 @@ type EvmLogClient = {
                 address: `0x${string}`[];
                 topics: (`0x${string}`[] | null)[];
                 fromBlock: `0x${string}`;
+                /** Set only when the read is chunked (see `maxBlockRange`). */
+                toBlock?: `0x${string}`;
             }
         ];
     }): Promise<RawLog[]>;
@@ -1317,8 +1353,16 @@ type EvmLogClient = {
     }>;
     getBlock(): Promise<Pick<Block, "timestamp" | "number">>;
 };
+type EvmReaderOptions = {
+    /**
+     * Largest block span one `eth_getLogs` may cover. Some providers cap it
+     * (rpc.rootstock.io: 2000 blocks); a read past the cap is split into
+     * consecutive chunks up to the latest block. Unset means one unbounded call.
+     */
+    maxBlockRange?: bigint;
+};
 /** Build an {@link EvmChainReader} over an existing viem-like client. */
-declare function evmReaderFromClient(client: EvmLogClient): EvmChainReader;
+declare function evmReaderFromClient(client: EvmLogClient, options?: EvmReaderOptions): EvmChainReader;
 /**
  * Build an {@link EvmChainReader} over one or more EVM JSON-RPC endpoints. With
  * several, viem's `fallback` tries them in order and fails over on error.
@@ -1327,7 +1371,7 @@ declare function evmReaderFromClient(client: EvmLogClient): EvmChainReader;
  * public RPCs rate-limiting us (publicnode 403s) — and it contradicts this
  * package's near-zero-RPC design.
  */
-declare function createEvmRpcReader(rpcUrls: string | string[]): EvmChainReader;
+declare function createEvmRpcReader(rpcUrls: string | string[], options?: EvmReaderOptions): EvmChainReader;
 /**
  * Resolve the per-chain readers used for tracking: the tested {@link
  * DEFAULT_EVM_RPCS} by default, with any `overrides` taking priority for their
@@ -1579,4 +1623,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, 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 };
+export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BitcoinReaderPolicy, 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 MinConfirmationsSource, 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, resolveMinConfirmations, swapToTracked };