@satora/swap 0.3.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -502,6 +502,18 @@ type TrackingConfig = {
502
502
  evmRpcUrls?: Record<number, string>;
503
503
  /** Esplora REST URL override for the Bitcoin manager; defaults to mainnet mempool.space. */
504
504
  esploraUrl?: string;
505
+ /**
506
+ * Electrum WebSocket URL (Fulcrum). When set, the Bitcoin manager reads via
507
+ * Electrum with scripthash-subscription push reconciles; esplora stays the
508
+ * fallback on Electrum errors.
509
+ */
510
+ electrumWsUrl?: string;
511
+ /**
512
+ * Network the Bitcoin HTLC addresses live on — needed by the Electrum
513
+ * reader to compute scripthashes. Defaults to mainnet; a signet/regtest
514
+ * deployment must set it or Electrum address decoding fails.
515
+ */
516
+ bitcoinNetwork?: "mainnet" | "testnet" | "signet" | "regtest";
505
517
  /**
506
518
  * Confirmations a Bitcoin funding tx needs before it observes as
507
519
  * `confirmed` (gating e.g. the evm→bitcoin claim). Default `0`: accept
@@ -630,26 +642,16 @@ declare class Client {
630
642
  /** Delegated to the legacy client (migration checkpoint). */
631
643
  createArkadeToEvmSwapGeneric(...args: Parameters<Client$1["createArkadeToEvmSwapGeneric"]>): ReturnType<Client$1["createArkadeToEvmSwapGeneric"]>;
632
644
  /** Delegated to the legacy client (migration checkpoint). */
633
- createLightningToEvmSwapGeneric(...args: Parameters<Client$1["createLightningToEvmSwapGeneric"]>): ReturnType<Client$1["createLightningToEvmSwapGeneric"]>;
634
- /** Delegated to the legacy client (migration checkpoint). */
635
645
  createBitcoinToEvmSwap(...args: Parameters<Client$1["createBitcoinToEvmSwap"]>): ReturnType<Client$1["createBitcoinToEvmSwap"]>;
636
646
  /** Delegated to the legacy client (migration checkpoint). */
637
647
  createBitcoinToArkadeSwap(...args: Parameters<Client$1["createBitcoinToArkadeSwap"]>): ReturnType<Client$1["createBitcoinToArkadeSwap"]>;
638
648
  /** Delegated to the legacy client (migration checkpoint). */
639
649
  createLightningToArkadeSwap(...args: Parameters<Client$1["createLightningToArkadeSwap"]>): ReturnType<Client$1["createLightningToArkadeSwap"]>;
640
650
  /** Delegated to the legacy client (migration checkpoint). */
641
- createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
642
- /** Delegated to the legacy client (migration checkpoint). */
643
- getArkadeToLightningQuote(...args: Parameters<Client$1["getArkadeToLightningQuote"]>): ReturnType<Client$1["getArkadeToLightningQuote"]>;
644
- /** Delegated to the legacy client (migration checkpoint). */
645
- retryArkadeToLightningSwap(...args: Parameters<Client$1["retryArkadeToLightningSwap"]>): ReturnType<Client$1["retryArkadeToLightningSwap"]>;
646
- /** Delegated to the legacy client (migration checkpoint). */
647
651
  createEvmToArkadeSwapGeneric(...args: Parameters<Client$1["createEvmToArkadeSwapGeneric"]>): ReturnType<Client$1["createEvmToArkadeSwapGeneric"]>;
648
652
  /** Delegated to the legacy client (migration checkpoint). */
649
653
  createEvmToBitcoinSwap(...args: Parameters<Client$1["createEvmToBitcoinSwap"]>): ReturnType<Client$1["createEvmToBitcoinSwap"]>;
650
654
  /** Delegated to the legacy client (migration checkpoint). */
651
- createEvmToLightningSwapGeneric(...args: Parameters<Client$1["createEvmToLightningSwapGeneric"]>): ReturnType<Client$1["createEvmToLightningSwapGeneric"]>;
652
- /** Delegated to the legacy client (migration checkpoint). */
653
655
  getCoordinatorFundingCallDataPermit2(...args: Parameters<Client$1["getCoordinatorFundingCallDataPermit2"]>): ReturnType<Client$1["getCoordinatorFundingCallDataPermit2"]>;
654
656
  /** Delegated to the legacy client (migration checkpoint). */
655
657
  getPermit2FundingParamsUnsigned(...args: Parameters<Client$1["getPermit2FundingParamsUnsigned"]>): ReturnType<Client$1["getPermit2FundingParamsUnsigned"]>;
@@ -732,6 +734,21 @@ declare class ClientBuilder {
732
734
  * otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
733
735
  */
734
736
  withEsploraUrl(url: string): this;
737
+ /**
738
+ * Set an Electrum server WebSocket URL (a Fulcrum `ws`/`wss` port) for
739
+ * Bitcoin claim/refund chain access. When set, the underlying client
740
+ * prefers it over Esplora for lookups and broadcasts, and waits for HTLC
741
+ * fundings via `blockchain.scripthash.subscribe` push instead of polling.
742
+ * Esplora remains the fallback whenever the Electrum server errors.
743
+ */
744
+ withElectrumWsUrl(url: string): this;
745
+ /**
746
+ * Declare the Bitcoin network of this deployment's HTLC addresses. Only
747
+ * needed together with {@link withElectrumWsUrl} on a non-mainnet
748
+ * deployment — the Electrum reader decodes addresses to scripthashes and
749
+ * defaults to mainnet parameters.
750
+ */
751
+ withBitcoinNetwork(network: "mainnet" | "testnet" | "signet" | "regtest"): this;
735
752
  /**
736
753
  * Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
737
754
  * (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
@@ -874,7 +891,7 @@ type ArkadeVhtlcInput = {
874
891
  unilateralRefundWithoutReceiverDelay: number;
875
892
  /** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
876
893
  expectedSats: number;
877
- /** Arkade HTLC script version. Missing means legacy v0 for old stored swaps. */
894
+ /** Arkade HTLC script version. Missing means strict v1. */
878
895
  arkadeHtlcScriptVersion?: number;
879
896
  };
880
897
  /**
@@ -901,19 +918,34 @@ type BitcoinHtlcFacts = {
901
918
  spendWitness?: string[];
902
919
  };
903
920
 
904
- /** The esplora surface the observer needs (a `BitcoinReaderEsplora` satisfies it). */
921
+ /** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
905
922
  type BitcoinChainReader = {
906
- /** Funding + spend facts for an HTLC witness-script address. */
907
923
  /**
908
924
  * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
909
925
  * overrides the reader's default for this address alone — the two legs of a
910
926
  * swap do not share one rule.
911
927
  */
912
928
  getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
929
+ /**
930
+ * Optional push capability: invoke `onChange` whenever the address's tx
931
+ * history changes (e.g. an Electrum scripthash subscription). Returns an
932
+ * unsubscribe function. When present, the manager reconciles on push
933
+ * instead of relying solely on the tracker's poll cadence.
934
+ */
935
+ subscribe?(address: string, onChange: () => void): () => void;
913
936
  };
914
937
  type BitcoinCreateConfig = {
915
938
  /** One or more esplora REST base URLs; several are tried in rotation with failover. */
916
939
  esploraUrl: string | string[];
940
+ /**
941
+ * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
942
+ * manager reads via Electrum (fresher than public explorers) and gets push
943
+ * reconciles via scripthash subscriptions; the esplora reader remains the
944
+ * fallback on Electrum errors.
945
+ */
946
+ electrumWsUrl?: string;
947
+ /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
948
+ network?: "mainnet" | "testnet" | "signet" | "regtest";
917
949
  /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
918
950
  chainTime?: () => Promise<number>;
919
951
  /**
@@ -1012,6 +1044,46 @@ declare const DEFAULT_ESPLORA_URLS: string[];
1012
1044
  */
1013
1045
  declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
1014
1046
 
1047
+ /**
1048
+ * An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
1049
+ * Fulcrum over WebSocket instead of public esplora REST endpoints.
1050
+ *
1051
+ * Two advantages over the esplora reader:
1052
+ *
1053
+ * - **Freshness**: our Fulcrum sees a transaction the moment its bitcoind
1054
+ * accepts it, while public explorers index with a lag — the exact lag that
1055
+ * made a server-funding hint's targeted verify come back "absent" and park
1056
+ * the claim on the 60s at-risk poller.
1057
+ * - **Push**: implements the reader's optional `subscribe` capability via
1058
+ * `blockchain.scripthash.subscribe`, so the manager reconciles the moment
1059
+ * an HTLC address's history changes instead of waiting for a poll tick.
1060
+ *
1061
+ * Reads fall back to a wrapped reader (typically the esplora one) whenever the
1062
+ * Electrum server errors, so a Fulcrum outage degrades to today's behavior
1063
+ * rather than blinding the tracker.
1064
+ */
1065
+
1066
+ /**
1067
+ * The Electrum client surface this reader needs. The pure SDK's
1068
+ * `ElectrumWsClient` satisfies it; tests inject a fake.
1069
+ */
1070
+ type ElectrumRpc = {
1071
+ request<T>(method: string, params: unknown[]): Promise<T>;
1072
+ subscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): Promise<string | null>;
1073
+ unsubscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): void;
1074
+ };
1075
+ type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
1076
+ /**
1077
+ * Build a {@link BitcoinChainReader} over an Electrum connection, with push
1078
+ * support and an optional fallback reader for outages.
1079
+ */
1080
+ declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
1081
+ /** Network the HTLC addresses live on; defaults to mainnet. */
1082
+ network?: ElectrumReaderNetwork;
1083
+ /** Reader consulted when the Electrum server errors (e.g. esplora). */
1084
+ fallback?: BitcoinChainReader;
1085
+ }): BitcoinChainReader;
1086
+
1015
1087
  /**
1016
1088
  * The `EvmContractManager`'s pure core.
1017
1089
  *
@@ -1388,4 +1460,4 @@ declare class WsStatusSource {
1388
1460
 
1389
1461
  declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
1390
1462
 
1391
- export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RawLog, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapOutcome, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WaitingOn, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };
1463
+ export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type ElectrumReaderNetwork, type ElectrumRpc, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RawLog, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapOutcome, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WaitingOn, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };
package/dist/index.d.ts CHANGED
@@ -502,6 +502,18 @@ type TrackingConfig = {
502
502
  evmRpcUrls?: Record<number, string>;
503
503
  /** Esplora REST URL override for the Bitcoin manager; defaults to mainnet mempool.space. */
504
504
  esploraUrl?: string;
505
+ /**
506
+ * Electrum WebSocket URL (Fulcrum). When set, the Bitcoin manager reads via
507
+ * Electrum with scripthash-subscription push reconciles; esplora stays the
508
+ * fallback on Electrum errors.
509
+ */
510
+ electrumWsUrl?: string;
511
+ /**
512
+ * Network the Bitcoin HTLC addresses live on — needed by the Electrum
513
+ * reader to compute scripthashes. Defaults to mainnet; a signet/regtest
514
+ * deployment must set it or Electrum address decoding fails.
515
+ */
516
+ bitcoinNetwork?: "mainnet" | "testnet" | "signet" | "regtest";
505
517
  /**
506
518
  * Confirmations a Bitcoin funding tx needs before it observes as
507
519
  * `confirmed` (gating e.g. the evm→bitcoin claim). Default `0`: accept
@@ -630,26 +642,16 @@ declare class Client {
630
642
  /** Delegated to the legacy client (migration checkpoint). */
631
643
  createArkadeToEvmSwapGeneric(...args: Parameters<Client$1["createArkadeToEvmSwapGeneric"]>): ReturnType<Client$1["createArkadeToEvmSwapGeneric"]>;
632
644
  /** Delegated to the legacy client (migration checkpoint). */
633
- createLightningToEvmSwapGeneric(...args: Parameters<Client$1["createLightningToEvmSwapGeneric"]>): ReturnType<Client$1["createLightningToEvmSwapGeneric"]>;
634
- /** Delegated to the legacy client (migration checkpoint). */
635
645
  createBitcoinToEvmSwap(...args: Parameters<Client$1["createBitcoinToEvmSwap"]>): ReturnType<Client$1["createBitcoinToEvmSwap"]>;
636
646
  /** Delegated to the legacy client (migration checkpoint). */
637
647
  createBitcoinToArkadeSwap(...args: Parameters<Client$1["createBitcoinToArkadeSwap"]>): ReturnType<Client$1["createBitcoinToArkadeSwap"]>;
638
648
  /** Delegated to the legacy client (migration checkpoint). */
639
649
  createLightningToArkadeSwap(...args: Parameters<Client$1["createLightningToArkadeSwap"]>): ReturnType<Client$1["createLightningToArkadeSwap"]>;
640
650
  /** Delegated to the legacy client (migration checkpoint). */
641
- createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
642
- /** Delegated to the legacy client (migration checkpoint). */
643
- getArkadeToLightningQuote(...args: Parameters<Client$1["getArkadeToLightningQuote"]>): ReturnType<Client$1["getArkadeToLightningQuote"]>;
644
- /** Delegated to the legacy client (migration checkpoint). */
645
- retryArkadeToLightningSwap(...args: Parameters<Client$1["retryArkadeToLightningSwap"]>): ReturnType<Client$1["retryArkadeToLightningSwap"]>;
646
- /** Delegated to the legacy client (migration checkpoint). */
647
651
  createEvmToArkadeSwapGeneric(...args: Parameters<Client$1["createEvmToArkadeSwapGeneric"]>): ReturnType<Client$1["createEvmToArkadeSwapGeneric"]>;
648
652
  /** Delegated to the legacy client (migration checkpoint). */
649
653
  createEvmToBitcoinSwap(...args: Parameters<Client$1["createEvmToBitcoinSwap"]>): ReturnType<Client$1["createEvmToBitcoinSwap"]>;
650
654
  /** Delegated to the legacy client (migration checkpoint). */
651
- createEvmToLightningSwapGeneric(...args: Parameters<Client$1["createEvmToLightningSwapGeneric"]>): ReturnType<Client$1["createEvmToLightningSwapGeneric"]>;
652
- /** Delegated to the legacy client (migration checkpoint). */
653
655
  getCoordinatorFundingCallDataPermit2(...args: Parameters<Client$1["getCoordinatorFundingCallDataPermit2"]>): ReturnType<Client$1["getCoordinatorFundingCallDataPermit2"]>;
654
656
  /** Delegated to the legacy client (migration checkpoint). */
655
657
  getPermit2FundingParamsUnsigned(...args: Parameters<Client$1["getPermit2FundingParamsUnsigned"]>): ReturnType<Client$1["getPermit2FundingParamsUnsigned"]>;
@@ -732,6 +734,21 @@ declare class ClientBuilder {
732
734
  * otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
733
735
  */
734
736
  withEsploraUrl(url: string): this;
737
+ /**
738
+ * Set an Electrum server WebSocket URL (a Fulcrum `ws`/`wss` port) for
739
+ * Bitcoin claim/refund chain access. When set, the underlying client
740
+ * prefers it over Esplora for lookups and broadcasts, and waits for HTLC
741
+ * fundings via `blockchain.scripthash.subscribe` push instead of polling.
742
+ * Esplora remains the fallback whenever the Electrum server errors.
743
+ */
744
+ withElectrumWsUrl(url: string): this;
745
+ /**
746
+ * Declare the Bitcoin network of this deployment's HTLC addresses. Only
747
+ * needed together with {@link withElectrumWsUrl} on a non-mainnet
748
+ * deployment — the Electrum reader decodes addresses to scripthashes and
749
+ * defaults to mainnet parameters.
750
+ */
751
+ withBitcoinNetwork(network: "mainnet" | "testnet" | "signet" | "regtest"): this;
735
752
  /**
736
753
  * Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
737
754
  * (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
@@ -874,7 +891,7 @@ type ArkadeVhtlcInput = {
874
891
  unilateralRefundWithoutReceiverDelay: number;
875
892
  /** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
876
893
  expectedSats: number;
877
- /** Arkade HTLC script version. Missing means legacy v0 for old stored swaps. */
894
+ /** Arkade HTLC script version. Missing means strict v1. */
878
895
  arkadeHtlcScriptVersion?: number;
879
896
  };
880
897
  /**
@@ -901,19 +918,34 @@ type BitcoinHtlcFacts = {
901
918
  spendWitness?: string[];
902
919
  };
903
920
 
904
- /** The esplora surface the observer needs (a `BitcoinReaderEsplora` satisfies it). */
921
+ /** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
905
922
  type BitcoinChainReader = {
906
- /** Funding + spend facts for an HTLC witness-script address. */
907
923
  /**
908
924
  * Funding + spend facts for an HTLC witness-script address. `minConfirmations`
909
925
  * overrides the reader's default for this address alone — the two legs of a
910
926
  * swap do not share one rule.
911
927
  */
912
928
  getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
929
+ /**
930
+ * Optional push capability: invoke `onChange` whenever the address's tx
931
+ * history changes (e.g. an Electrum scripthash subscription). Returns an
932
+ * unsubscribe function. When present, the manager reconciles on push
933
+ * instead of relying solely on the tracker's poll cadence.
934
+ */
935
+ subscribe?(address: string, onChange: () => void): () => void;
913
936
  };
914
937
  type BitcoinCreateConfig = {
915
938
  /** One or more esplora REST base URLs; several are tried in rotation with failover. */
916
939
  esploraUrl: string | string[];
940
+ /**
941
+ * Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
942
+ * manager reads via Electrum (fresher than public explorers) and gets push
943
+ * reconciles via scripthash subscriptions; the esplora reader remains the
944
+ * fallback on Electrum errors.
945
+ */
946
+ electrumWsUrl?: string;
947
+ /** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
948
+ network?: "mainnet" | "testnet" | "signet" | "regtest";
917
949
  /** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
918
950
  chainTime?: () => Promise<number>;
919
951
  /**
@@ -1012,6 +1044,46 @@ declare const DEFAULT_ESPLORA_URLS: string[];
1012
1044
  */
1013
1045
  declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
1014
1046
 
1047
+ /**
1048
+ * An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
1049
+ * Fulcrum over WebSocket instead of public esplora REST endpoints.
1050
+ *
1051
+ * Two advantages over the esplora reader:
1052
+ *
1053
+ * - **Freshness**: our Fulcrum sees a transaction the moment its bitcoind
1054
+ * accepts it, while public explorers index with a lag — the exact lag that
1055
+ * made a server-funding hint's targeted verify come back "absent" and park
1056
+ * the claim on the 60s at-risk poller.
1057
+ * - **Push**: implements the reader's optional `subscribe` capability via
1058
+ * `blockchain.scripthash.subscribe`, so the manager reconciles the moment
1059
+ * an HTLC address's history changes instead of waiting for a poll tick.
1060
+ *
1061
+ * Reads fall back to a wrapped reader (typically the esplora one) whenever the
1062
+ * Electrum server errors, so a Fulcrum outage degrades to today's behavior
1063
+ * rather than blinding the tracker.
1064
+ */
1065
+
1066
+ /**
1067
+ * The Electrum client surface this reader needs. The pure SDK's
1068
+ * `ElectrumWsClient` satisfies it; tests inject a fake.
1069
+ */
1070
+ type ElectrumRpc = {
1071
+ request<T>(method: string, params: unknown[]): Promise<T>;
1072
+ subscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): Promise<string | null>;
1073
+ unsubscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): void;
1074
+ };
1075
+ type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
1076
+ /**
1077
+ * Build a {@link BitcoinChainReader} over an Electrum connection, with push
1078
+ * support and an optional fallback reader for outages.
1079
+ */
1080
+ declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
1081
+ /** Network the HTLC addresses live on; defaults to mainnet. */
1082
+ network?: ElectrumReaderNetwork;
1083
+ /** Reader consulted when the Electrum server errors (e.g. esplora). */
1084
+ fallback?: BitcoinChainReader;
1085
+ }): BitcoinChainReader;
1086
+
1015
1087
  /**
1016
1088
  * The `EvmContractManager`'s pure core.
1017
1089
  *
@@ -1388,4 +1460,4 @@ declare class WsStatusSource {
1388
1460
 
1389
1461
  declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
1390
1462
 
1391
- export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RawLog, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapOutcome, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WaitingOn, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };
1463
+ export { type ActionSubscriber, ArkadeContractManager, type ArkadeContractManagerDeps, type ArkadeCreateConfig, type ArkadeVhtlcInput, type BitcoinChainReader, type BitcoinConfirmationPolicy, BitcoinContractManager, type BitcoinContractManagerDeps, type BitcoinCreateConfig, type BlockedBy, type BlockedReason, type CctpClaimEvidence, type ClaimAction, Client, ClientBuilder, type ContractManager, DEFAULT_ESPLORA_URLS, DEFAULT_EVM_RPCS, type ElectrumReaderNetwork, type ElectrumRpc, type EvmChainReader, EvmContractManager, type EvmContractManagerDeps, type EvmHtlcQuery, type EvmLogClient, type FundAction, type HtlcObservation, type HtlcRef, type Ledger, type NoneAction, type RawLog, type RecoverCctpClaimAction, type RefundCollaborativeAction, type RefundUnilateralAction, type SwapAction, type SwapActionAutomation, type SwapActionId, type SwapActionInput, type SwapActions, type SwapObservations, type SwapOutcome, type SwapStatusUpdate, SwapTracker, SwapWorker, type SwapWorkerOptions, type TrackedSwap, type WaitAction, type WaitingOn, type WebSocketLike, type WorkerHintSource, type WorkerTracker, WsStatusSource, type WsStatusSourceOptions, buildArkadeVhtlcRef, createEvmRpcReader, defaultArkadeServerUrl, defaultEvmReaders, deriveSwapActions, deriveSwapStatus, electrumReader, esploraReader, evmReaderFromClient, htlcFactsFromEsploraTxs, htlcKey, htlcQueryKey, swapToTracked };