@satora/swap 0.3.2 → 1.1.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/README.md +1 -1
- package/dist/bitcoin-reader-electrum-PY7DHD6T.js +7 -0
- package/dist/{bitcoin-reader-esplora-HV6CANAA.js → bitcoin-reader-esplora-ZLPMM5FF.js} +2 -2
- package/dist/bitcoin-reader-esplora-ZLPMM5FF.js.map +1 -0
- package/dist/chunk-FTPIQSRW.js +152 -0
- package/dist/chunk-FTPIQSRW.js.map +1 -0
- package/dist/{chunk-EIWELJJK.js → chunk-THI4UO6R.js} +11 -5
- package/dist/chunk-THI4UO6R.js.map +1 -0
- package/dist/index.cjs +295 -112
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +86 -12
- package/dist/index.d.ts +86 -12
- package/dist/index.js +116 -106
- package/dist/index.js.map +1 -1
- package/package.json +3 -2
- package/dist/chunk-EIWELJJK.js.map +0 -1
- /package/dist/{bitcoin-reader-esplora-HV6CANAA.js.map → bitcoin-reader-electrum-PY7DHD6T.js.map} +0 -0
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,8 +642,6 @@ 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"]>;
|
|
@@ -640,16 +650,10 @@ declare class Client {
|
|
|
640
650
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
641
651
|
createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
|
|
642
652
|
/** 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
653
|
createEvmToArkadeSwapGeneric(...args: Parameters<Client$1["createEvmToArkadeSwapGeneric"]>): ReturnType<Client$1["createEvmToArkadeSwapGeneric"]>;
|
|
648
654
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
649
655
|
createEvmToBitcoinSwap(...args: Parameters<Client$1["createEvmToBitcoinSwap"]>): ReturnType<Client$1["createEvmToBitcoinSwap"]>;
|
|
650
656
|
/** 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
657
|
getCoordinatorFundingCallDataPermit2(...args: Parameters<Client$1["getCoordinatorFundingCallDataPermit2"]>): ReturnType<Client$1["getCoordinatorFundingCallDataPermit2"]>;
|
|
654
658
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
655
659
|
getPermit2FundingParamsUnsigned(...args: Parameters<Client$1["getPermit2FundingParamsUnsigned"]>): ReturnType<Client$1["getPermit2FundingParamsUnsigned"]>;
|
|
@@ -732,6 +736,21 @@ declare class ClientBuilder {
|
|
|
732
736
|
* otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
|
|
733
737
|
*/
|
|
734
738
|
withEsploraUrl(url: string): this;
|
|
739
|
+
/**
|
|
740
|
+
* Set an Electrum server WebSocket URL (a Fulcrum `ws`/`wss` port) for
|
|
741
|
+
* Bitcoin claim/refund chain access. When set, the underlying client
|
|
742
|
+
* prefers it over Esplora for lookups and broadcasts, and waits for HTLC
|
|
743
|
+
* fundings via `blockchain.scripthash.subscribe` push instead of polling.
|
|
744
|
+
* Esplora remains the fallback whenever the Electrum server errors.
|
|
745
|
+
*/
|
|
746
|
+
withElectrumWsUrl(url: string): this;
|
|
747
|
+
/**
|
|
748
|
+
* Declare the Bitcoin network of this deployment's HTLC addresses. Only
|
|
749
|
+
* needed together with {@link withElectrumWsUrl} on a non-mainnet
|
|
750
|
+
* deployment — the Electrum reader decodes addresses to scripthashes and
|
|
751
|
+
* defaults to mainnet parameters.
|
|
752
|
+
*/
|
|
753
|
+
withBitcoinNetwork(network: "mainnet" | "testnet" | "signet" | "regtest"): this;
|
|
735
754
|
/**
|
|
736
755
|
* Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
|
|
737
756
|
* (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
|
|
@@ -874,7 +893,7 @@ type ArkadeVhtlcInput = {
|
|
|
874
893
|
unilateralRefundWithoutReceiverDelay: number;
|
|
875
894
|
/** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
|
|
876
895
|
expectedSats: number;
|
|
877
|
-
/** Arkade HTLC script version. Missing means
|
|
896
|
+
/** Arkade HTLC script version. Missing means strict v1. */
|
|
878
897
|
arkadeHtlcScriptVersion?: number;
|
|
879
898
|
};
|
|
880
899
|
/**
|
|
@@ -901,19 +920,34 @@ type BitcoinHtlcFacts = {
|
|
|
901
920
|
spendWitness?: string[];
|
|
902
921
|
};
|
|
903
922
|
|
|
904
|
-
/** The
|
|
923
|
+
/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
|
|
905
924
|
type BitcoinChainReader = {
|
|
906
|
-
/** Funding + spend facts for an HTLC witness-script address. */
|
|
907
925
|
/**
|
|
908
926
|
* Funding + spend facts for an HTLC witness-script address. `minConfirmations`
|
|
909
927
|
* overrides the reader's default for this address alone — the two legs of a
|
|
910
928
|
* swap do not share one rule.
|
|
911
929
|
*/
|
|
912
930
|
getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
|
|
931
|
+
/**
|
|
932
|
+
* Optional push capability: invoke `onChange` whenever the address's tx
|
|
933
|
+
* history changes (e.g. an Electrum scripthash subscription). Returns an
|
|
934
|
+
* unsubscribe function. When present, the manager reconciles on push
|
|
935
|
+
* instead of relying solely on the tracker's poll cadence.
|
|
936
|
+
*/
|
|
937
|
+
subscribe?(address: string, onChange: () => void): () => void;
|
|
913
938
|
};
|
|
914
939
|
type BitcoinCreateConfig = {
|
|
915
940
|
/** One or more esplora REST base URLs; several are tried in rotation with failover. */
|
|
916
941
|
esploraUrl: string | string[];
|
|
942
|
+
/**
|
|
943
|
+
* Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
|
|
944
|
+
* manager reads via Electrum (fresher than public explorers) and gets push
|
|
945
|
+
* reconciles via scripthash subscriptions; the esplora reader remains the
|
|
946
|
+
* fallback on Electrum errors.
|
|
947
|
+
*/
|
|
948
|
+
electrumWsUrl?: string;
|
|
949
|
+
/** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
|
|
950
|
+
network?: "mainnet" | "testnet" | "signet" | "regtest";
|
|
917
951
|
/** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
|
|
918
952
|
chainTime?: () => Promise<number>;
|
|
919
953
|
/**
|
|
@@ -1012,6 +1046,46 @@ declare const DEFAULT_ESPLORA_URLS: string[];
|
|
|
1012
1046
|
*/
|
|
1013
1047
|
declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
|
|
1014
1048
|
|
|
1049
|
+
/**
|
|
1050
|
+
* An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
|
|
1051
|
+
* Fulcrum over WebSocket instead of public esplora REST endpoints.
|
|
1052
|
+
*
|
|
1053
|
+
* Two advantages over the esplora reader:
|
|
1054
|
+
*
|
|
1055
|
+
* - **Freshness**: our Fulcrum sees a transaction the moment its bitcoind
|
|
1056
|
+
* accepts it, while public explorers index with a lag — the exact lag that
|
|
1057
|
+
* made a server-funding hint's targeted verify come back "absent" and park
|
|
1058
|
+
* the claim on the 60s at-risk poller.
|
|
1059
|
+
* - **Push**: implements the reader's optional `subscribe` capability via
|
|
1060
|
+
* `blockchain.scripthash.subscribe`, so the manager reconciles the moment
|
|
1061
|
+
* an HTLC address's history changes instead of waiting for a poll tick.
|
|
1062
|
+
*
|
|
1063
|
+
* Reads fall back to a wrapped reader (typically the esplora one) whenever the
|
|
1064
|
+
* Electrum server errors, so a Fulcrum outage degrades to today's behavior
|
|
1065
|
+
* rather than blinding the tracker.
|
|
1066
|
+
*/
|
|
1067
|
+
|
|
1068
|
+
/**
|
|
1069
|
+
* The Electrum client surface this reader needs. The pure SDK's
|
|
1070
|
+
* `ElectrumWsClient` satisfies it; tests inject a fake.
|
|
1071
|
+
*/
|
|
1072
|
+
type ElectrumRpc = {
|
|
1073
|
+
request<T>(method: string, params: unknown[]): Promise<T>;
|
|
1074
|
+
subscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): Promise<string | null>;
|
|
1075
|
+
unsubscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): void;
|
|
1076
|
+
};
|
|
1077
|
+
type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
|
|
1078
|
+
/**
|
|
1079
|
+
* Build a {@link BitcoinChainReader} over an Electrum connection, with push
|
|
1080
|
+
* support and an optional fallback reader for outages.
|
|
1081
|
+
*/
|
|
1082
|
+
declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
|
|
1083
|
+
/** Network the HTLC addresses live on; defaults to mainnet. */
|
|
1084
|
+
network?: ElectrumReaderNetwork;
|
|
1085
|
+
/** Reader consulted when the Electrum server errors (e.g. esplora). */
|
|
1086
|
+
fallback?: BitcoinChainReader;
|
|
1087
|
+
}): BitcoinChainReader;
|
|
1088
|
+
|
|
1015
1089
|
/**
|
|
1016
1090
|
* The `EvmContractManager`'s pure core.
|
|
1017
1091
|
*
|
|
@@ -1388,4 +1462,4 @@ declare class WsStatusSource {
|
|
|
1388
1462
|
|
|
1389
1463
|
declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
|
|
1390
1464
|
|
|
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 };
|
|
1465
|
+
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,8 +642,6 @@ 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"]>;
|
|
@@ -640,16 +650,10 @@ declare class Client {
|
|
|
640
650
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
641
651
|
createArkadeToLightningSwap(...args: Parameters<Client$1["createArkadeToLightningSwap"]>): ReturnType<Client$1["createArkadeToLightningSwap"]>;
|
|
642
652
|
/** 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
653
|
createEvmToArkadeSwapGeneric(...args: Parameters<Client$1["createEvmToArkadeSwapGeneric"]>): ReturnType<Client$1["createEvmToArkadeSwapGeneric"]>;
|
|
648
654
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
649
655
|
createEvmToBitcoinSwap(...args: Parameters<Client$1["createEvmToBitcoinSwap"]>): ReturnType<Client$1["createEvmToBitcoinSwap"]>;
|
|
650
656
|
/** 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
657
|
getCoordinatorFundingCallDataPermit2(...args: Parameters<Client$1["getCoordinatorFundingCallDataPermit2"]>): ReturnType<Client$1["getCoordinatorFundingCallDataPermit2"]>;
|
|
654
658
|
/** Delegated to the legacy client (migration checkpoint). */
|
|
655
659
|
getPermit2FundingParamsUnsigned(...args: Parameters<Client$1["getPermit2FundingParamsUnsigned"]>): ReturnType<Client$1["getPermit2FundingParamsUnsigned"]>;
|
|
@@ -732,6 +736,21 @@ declare class ClientBuilder {
|
|
|
732
736
|
* otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
|
|
733
737
|
*/
|
|
734
738
|
withEsploraUrl(url: string): this;
|
|
739
|
+
/**
|
|
740
|
+
* Set an Electrum server WebSocket URL (a Fulcrum `ws`/`wss` port) for
|
|
741
|
+
* Bitcoin claim/refund chain access. When set, the underlying client
|
|
742
|
+
* prefers it over Esplora for lookups and broadcasts, and waits for HTLC
|
|
743
|
+
* fundings via `blockchain.scripthash.subscribe` push instead of polling.
|
|
744
|
+
* Esplora remains the fallback whenever the Electrum server errors.
|
|
745
|
+
*/
|
|
746
|
+
withElectrumWsUrl(url: string): this;
|
|
747
|
+
/**
|
|
748
|
+
* Declare the Bitcoin network of this deployment's HTLC addresses. Only
|
|
749
|
+
* needed together with {@link withElectrumWsUrl} on a non-mainnet
|
|
750
|
+
* deployment — the Electrum reader decodes addresses to scripthashes and
|
|
751
|
+
* defaults to mainnet parameters.
|
|
752
|
+
*/
|
|
753
|
+
withBitcoinNetwork(network: "mainnet" | "testnet" | "signet" | "regtest"): this;
|
|
735
754
|
/**
|
|
736
755
|
* Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
|
|
737
756
|
* (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
|
|
@@ -874,7 +893,7 @@ type ArkadeVhtlcInput = {
|
|
|
874
893
|
unilateralRefundWithoutReceiverDelay: number;
|
|
875
894
|
/** Expected funding amount in sats (a short funding is `invalid`, not confirmed). */
|
|
876
895
|
expectedSats: number;
|
|
877
|
-
/** Arkade HTLC script version. Missing means
|
|
896
|
+
/** Arkade HTLC script version. Missing means strict v1. */
|
|
878
897
|
arkadeHtlcScriptVersion?: number;
|
|
879
898
|
};
|
|
880
899
|
/**
|
|
@@ -901,19 +920,34 @@ type BitcoinHtlcFacts = {
|
|
|
901
920
|
spendWitness?: string[];
|
|
902
921
|
};
|
|
903
922
|
|
|
904
|
-
/** The
|
|
923
|
+
/** The chain surface the observer needs (the esplora and electrum readers satisfy it). */
|
|
905
924
|
type BitcoinChainReader = {
|
|
906
|
-
/** Funding + spend facts for an HTLC witness-script address. */
|
|
907
925
|
/**
|
|
908
926
|
* Funding + spend facts for an HTLC witness-script address. `minConfirmations`
|
|
909
927
|
* overrides the reader's default for this address alone — the two legs of a
|
|
910
928
|
* swap do not share one rule.
|
|
911
929
|
*/
|
|
912
930
|
getHtlcFacts(address: string, minConfirmations?: number): Promise<BitcoinHtlcFacts>;
|
|
931
|
+
/**
|
|
932
|
+
* Optional push capability: invoke `onChange` whenever the address's tx
|
|
933
|
+
* history changes (e.g. an Electrum scripthash subscription). Returns an
|
|
934
|
+
* unsubscribe function. When present, the manager reconciles on push
|
|
935
|
+
* instead of relying solely on the tracker's poll cadence.
|
|
936
|
+
*/
|
|
937
|
+
subscribe?(address: string, onChange: () => void): () => void;
|
|
913
938
|
};
|
|
914
939
|
type BitcoinCreateConfig = {
|
|
915
940
|
/** One or more esplora REST base URLs; several are tried in rotation with failover. */
|
|
916
941
|
esploraUrl: string | string[];
|
|
942
|
+
/**
|
|
943
|
+
* Optional Electrum WebSocket URL (Fulcrum `ws`/`wss` port). When set, the
|
|
944
|
+
* manager reads via Electrum (fresher than public explorers) and gets push
|
|
945
|
+
* reconciles via scripthash subscriptions; the esplora reader remains the
|
|
946
|
+
* fallback on Electrum errors.
|
|
947
|
+
*/
|
|
948
|
+
electrumWsUrl?: string;
|
|
949
|
+
/** Network the HTLC addresses live on (for Electrum scripthashes); default mainnet. */
|
|
950
|
+
network?: "mainnet" | "testnet" | "signet" | "regtest";
|
|
917
951
|
/** The current Bitcoin MTP (ms); typically `async () => (await client.getMtp()).mtp * 1000`. */
|
|
918
952
|
chainTime?: () => Promise<number>;
|
|
919
953
|
/**
|
|
@@ -1012,6 +1046,46 @@ declare const DEFAULT_ESPLORA_URLS: string[];
|
|
|
1012
1046
|
*/
|
|
1013
1047
|
declare function esploraReader(esploraUrls: string | string[], fetchImpl?: typeof fetch, policy?: BitcoinConfirmationPolicy): BitcoinChainReader;
|
|
1014
1048
|
|
|
1049
|
+
/**
|
|
1050
|
+
* An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own
|
|
1051
|
+
* Fulcrum over WebSocket instead of public esplora REST endpoints.
|
|
1052
|
+
*
|
|
1053
|
+
* Two advantages over the esplora reader:
|
|
1054
|
+
*
|
|
1055
|
+
* - **Freshness**: our Fulcrum sees a transaction the moment its bitcoind
|
|
1056
|
+
* accepts it, while public explorers index with a lag — the exact lag that
|
|
1057
|
+
* made a server-funding hint's targeted verify come back "absent" and park
|
|
1058
|
+
* the claim on the 60s at-risk poller.
|
|
1059
|
+
* - **Push**: implements the reader's optional `subscribe` capability via
|
|
1060
|
+
* `blockchain.scripthash.subscribe`, so the manager reconciles the moment
|
|
1061
|
+
* an HTLC address's history changes instead of waiting for a poll tick.
|
|
1062
|
+
*
|
|
1063
|
+
* Reads fall back to a wrapped reader (typically the esplora one) whenever the
|
|
1064
|
+
* Electrum server errors, so a Fulcrum outage degrades to today's behavior
|
|
1065
|
+
* rather than blinding the tracker.
|
|
1066
|
+
*/
|
|
1067
|
+
|
|
1068
|
+
/**
|
|
1069
|
+
* The Electrum client surface this reader needs. The pure SDK's
|
|
1070
|
+
* `ElectrumWsClient` satisfies it; tests inject a fake.
|
|
1071
|
+
*/
|
|
1072
|
+
type ElectrumRpc = {
|
|
1073
|
+
request<T>(method: string, params: unknown[]): Promise<T>;
|
|
1074
|
+
subscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): Promise<string | null>;
|
|
1075
|
+
unsubscribeScriptHash(scripthash: string, onChange: (status: string | null) => void): void;
|
|
1076
|
+
};
|
|
1077
|
+
type ElectrumReaderNetwork = "mainnet" | "testnet" | "signet" | "regtest";
|
|
1078
|
+
/**
|
|
1079
|
+
* Build a {@link BitcoinChainReader} over an Electrum connection, with push
|
|
1080
|
+
* support and an optional fallback reader for outages.
|
|
1081
|
+
*/
|
|
1082
|
+
declare function electrumReader(client: ElectrumRpc, opts?: BitcoinConfirmationPolicy & {
|
|
1083
|
+
/** Network the HTLC addresses live on; defaults to mainnet. */
|
|
1084
|
+
network?: ElectrumReaderNetwork;
|
|
1085
|
+
/** Reader consulted when the Electrum server errors (e.g. esplora). */
|
|
1086
|
+
fallback?: BitcoinChainReader;
|
|
1087
|
+
}): BitcoinChainReader;
|
|
1088
|
+
|
|
1015
1089
|
/**
|
|
1016
1090
|
* The `EvmContractManager`'s pure core.
|
|
1017
1091
|
*
|
|
@@ -1388,4 +1462,4 @@ declare class WsStatusSource {
|
|
|
1388
1462
|
|
|
1389
1463
|
declare function swapToTracked(stored: StoredSwap): TrackedSwap | undefined;
|
|
1390
1464
|
|
|
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 };
|
|
1465
|
+
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 };
|