@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/bitcoin-reader-electrum-4DOJ7NGH.js +7 -0
- package/dist/bitcoin-reader-electrum-4DOJ7NGH.js.map +1 -0
- package/dist/chunk-VHXEU534.js +145 -0
- package/dist/chunk-VHXEU534.js.map +1 -0
- package/dist/index.cjs +266 -117
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +86 -14
- package/dist/index.d.ts +86 -14
- package/dist/index.js +102 -113
- package/dist/index.js.map +1 -1
- package/package.json +3 -2
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
|
|
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
|
|
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
|
|
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
|
|
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 };
|