Skip to main content

Esplora

Esplora blockchain clients for fetching on-chain data needed during swap execution.

The driver's ChainClient on each chain: it reads address histories and spends, broadcasts the user's claim or refund, and estimates fee rates.

One client per chain: BitcoinEsplora and LiquidEsplora. The two chains need separate backends and floor their fee estimates at different relay minimums.

Optional: both implement Esplora, a structural interface, so anything with those methods replaces them.

A read answered 429, 500 or 503 is asked again up to 6 times, waiting from 256 ms and doubling, and so is a broadcast answered 429, so a rate limit slows a pass rather than failing it.

Classes​

BitcoinEsplora​

Esplora client for Bitcoin.

Extends​

  • EsploraBase

Constructors​

Constructor​
new BitcoinEsplora(
url: string,
fetchFn?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>,
options?: EsploraOptions): BitcoinEsplora;
Parameters​
ParameterTypeDefault valueDescription
urlstringundefinedEsplora base URL including any path prefix.
fetchFn(input: string | URL | Request, init?: RequestInit) => Promise<Response>fetchOptional fetch implementation. Defaults to the global fetch.
optionsEsploraOptions{}Optional request settings, see EsploraOptions.
Returns​

BitcoinEsplora

Inherited from​
EsploraBase.constructor

Methods​

addressHistory()​
addressHistory(address: string): Promise<HistoryTx[]>;

Every transaction paying or spending address, mempool included, with its raw hex and confirming height. Pages through the whole history, so a deposit can never hide behind unrelated transactions; a transaction the indexer has dropped since listing it is left out. Confirmed bodies are fetched one at a time and kept as each arrives, so a later read fetches only new ones, and one that fails partway leaves the next less to fetch. An unconfirmed body is fetched on every read.

Parameters​
ParameterType
addressstring
Returns​

Promise<HistoryTx[]>

Inherited from​
EsploraBase.addressHistory
addressTxs()​
addressTxs(address: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying an address, newest first. lastSeen pages past 25.

Parameters​
ParameterType
addressstring
lastSeen?string
Returns​

Promise<EsploraTx[]>

Inherited from​
EsploraBase.addressTxs
broadcast()​
broadcast(txHex: string): Promise<string>;

Broadcasts a raw transaction (hex). Returns the broadcast txid.

Parameters​
ParameterType
txHexstring
Returns​

Promise<string>

Inherited from​
EsploraBase.broadcast
getBlockHash()​
getBlockHash(height: number): Promise<string>;

Block hash at a given height, hex-encoded.

Height 0 is the genesis hash a SwapContext needs for Liquid. Read it from your own Esplora, never from the swap server: every taproot signature the wallet produces commits to it.

Parameters​
ParameterType
heightnumber
Returns​

Promise<string>

Inherited from​
EsploraBase.getBlockHash
getFeeRate()​
getFeeRate(target: number): Promise<number>;

Estimates the fee rate in sat/vB for a given confirmation target (in blocks), fractional, floored at the chain's relay minimum. The indexer reports a fixed set of targets, so this takes the cheapest one that still confirms within target. With none, it throws on Bitcoin and takes the relay minimum on Liquid.

Parameters​
ParameterType
targetnumber
Returns​

Promise<number>

Inherited from​
EsploraBase.getFeeRate
getHeight()​
getHeight(): Promise<number>;

Current chain tip height.

Returns​

Promise<number>

Inherited from​
EsploraBase.getHeight
getOutspend()​
getOutspend(txid: string, vout: number): Promise<Outspend>;

Whether a specific output has been spent, and by which transaction.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<Outspend>

Inherited from​
EsploraBase.getOutspend
getTx()​
getTx(txid: string): Promise<string | null>;

Returns the raw transaction as hex, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<string | null>

Inherited from​
EsploraBase.getTx
getTxConfirmations()​
getTxConfirmations(txid: string): Promise<number>;

Number of confirmations for a transaction, or 0 if unconfirmed.

Parameters​
ParameterType
txidstring
Returns​

Promise<number>

Inherited from​
EsploraBase.getTxConfirmations
getTxFee()​
getTxFee(txid: string): Promise<number | null>;

Miner fee paid by a transaction, in satoshis, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<number | null>

Inherited from​
EsploraBase.getTxFee
getTxStatus()​
getTxStatus(txid: string): Promise<TxStatus>;

Confirmation status of a transaction.

Parameters​
ParameterType
txidstring
Returns​

Promise<TxStatus>

Inherited from​
EsploraBase.getTxStatus
outspend()​
outspend(txid: string, vout: number): Promise<HistoryTx | undefined>;

The transaction spending output vout of txid, mempool included, with its raw hex and confirming height, or undefined while the output is unspent. Read from the output itself, so a spend is found however many other transactions crowd the address's mempool history, which Esplora caps at 50. A spend the indexer no longer serves counts as none.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<HistoryTx | undefined>

Inherited from​
EsploraBase.outspend
scripthashTxs()​
scripthashTxs(scriptHash: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying a scripthash, newest first. lastSeen pages past 25.

Parameters​
ParameterType
scriptHashstring
lastSeen?string
Returns​

Promise<EsploraTx[]>

Inherited from​
EsploraBase.scripthashTxs

LiquidEsplora​

Esplora client for Liquid.

Extends​

  • EsploraBase

Constructors​

Constructor​
new LiquidEsplora(
url: string,
fetchFn?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>,
options?: EsploraOptions): LiquidEsplora;
Parameters​
ParameterTypeDefault valueDescription
urlstringundefinedEsplora base URL including any path prefix.
fetchFn(input: string | URL | Request, init?: RequestInit) => Promise<Response>fetchOptional fetch implementation. Defaults to the global fetch.
optionsEsploraOptions{}Optional request settings, see EsploraOptions.
Returns​

LiquidEsplora

Inherited from​
EsploraBase.constructor

Methods​

addressHistory()​
addressHistory(address: string): Promise<HistoryTx[]>;

Every transaction paying or spending address, mempool included, with its raw hex and confirming height. Pages through the whole history, so a deposit can never hide behind unrelated transactions; a transaction the indexer has dropped since listing it is left out. Confirmed bodies are fetched one at a time and kept as each arrives, so a later read fetches only new ones, and one that fails partway leaves the next less to fetch. An unconfirmed body is fetched on every read.

Parameters​
ParameterType
addressstring
Returns​

Promise<HistoryTx[]>

Inherited from​
EsploraBase.addressHistory
addressTxs()​
addressTxs(address: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying an address, newest first. lastSeen pages past 25.

Parameters​
ParameterType
addressstring
lastSeen?string
Returns​

Promise<EsploraTx[]>

Inherited from​
EsploraBase.addressTxs
broadcast()​
broadcast(txHex: string): Promise<string>;

Broadcasts a raw transaction (hex). Returns the broadcast txid.

Parameters​
ParameterType
txHexstring
Returns​

Promise<string>

Inherited from​
EsploraBase.broadcast
getBlockHash()​
getBlockHash(height: number): Promise<string>;

Block hash at a given height, hex-encoded.

Height 0 is the genesis hash a SwapContext needs for Liquid. Read it from your own Esplora, never from the swap server: every taproot signature the wallet produces commits to it.

Parameters​
ParameterType
heightnumber
Returns​

Promise<string>

Inherited from​
EsploraBase.getBlockHash
getFeeRate()​
getFeeRate(target: number): Promise<number>;

Estimates the fee rate in sat/vB for a given confirmation target (in blocks), fractional, floored at the chain's relay minimum. The indexer reports a fixed set of targets, so this takes the cheapest one that still confirms within target. With none, it throws on Bitcoin and takes the relay minimum on Liquid.

Parameters​
ParameterType
targetnumber
Returns​

Promise<number>

Inherited from​
EsploraBase.getFeeRate
getHeight()​
getHeight(): Promise<number>;

Current chain tip height.

Returns​

Promise<number>

Inherited from​
EsploraBase.getHeight
getOutspend()​
getOutspend(txid: string, vout: number): Promise<Outspend>;

Whether a specific output has been spent, and by which transaction.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<Outspend>

Inherited from​
EsploraBase.getOutspend
getTx()​
getTx(txid: string): Promise<string | null>;

Returns the raw transaction as hex, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<string | null>

Inherited from​
EsploraBase.getTx
getTxConfirmations()​
getTxConfirmations(txid: string): Promise<number>;

Number of confirmations for a transaction, or 0 if unconfirmed.

Parameters​
ParameterType
txidstring
Returns​

Promise<number>

Inherited from​
EsploraBase.getTxConfirmations
getTxFee()​
getTxFee(txid: string): Promise<number | null>;

Miner fee paid by a transaction, in satoshis, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<number | null>

Inherited from​
EsploraBase.getTxFee
getTxStatus()​
getTxStatus(txid: string): Promise<TxStatus>;

Confirmation status of a transaction.

Parameters​
ParameterType
txidstring
Returns​

Promise<TxStatus>

Inherited from​
EsploraBase.getTxStatus
outspend()​
outspend(txid: string, vout: number): Promise<HistoryTx | undefined>;

The transaction spending output vout of txid, mempool included, with its raw hex and confirming height, or undefined while the output is unspent. Read from the output itself, so a spend is found however many other transactions crowd the address's mempool history, which Esplora caps at 50. A spend the indexer no longer serves counts as none.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<HistoryTx | undefined>

Inherited from​
EsploraBase.outspend
scripthashTxs()​
scripthashTxs(scriptHash: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying a scripthash, newest first. lastSeen pages past 25.

Parameters​
ParameterType
scriptHashstring
lastSeen?string
Returns​

Promise<EsploraTx[]>

Inherited from​
EsploraBase.scripthashTxs

Interfaces​

Esplora​

The chain reads a swap needs, as BitcoinEsplora and LiquidEsplora provide them.

Program against this rather than a concrete class, and implement it yourself to drive the SDK from your own indexer.

Methods​

addressHistory()?​
optional addressHistory(address: string): Promise<HistoryTx[]>;

Every transaction paying or spending an address, mempool included. Needed only to serve the driver as its ChainClient.

Parameters​
ParameterType
addressstring
Returns​

Promise<HistoryTx[]>

addressTxs()​
addressTxs(address: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying an address, newest first.

Parameters​
ParameterType
addressstring
lastSeen?string
Returns​

Promise<EsploraTx[]>

broadcast()​
broadcast(txHex: string): Promise<string>;

Broadcasts a raw transaction (hex). Returns the broadcast txid.

Parameters​
ParameterType
txHexstring
Returns​

Promise<string>

getBlockHash()​
getBlockHash(height: number): Promise<string>;

Block hash at a given height, hex-encoded.

Parameters​
ParameterType
heightnumber
Returns​

Promise<string>

getFeeRate()​
getFeeRate(target: number): Promise<number>;

Fee rate in sat/vB for a confirmation target, in blocks. Fractional.

Parameters​
ParameterType
targetnumber
Returns​

Promise<number>

getHeight()​
getHeight(): Promise<number>;

Current chain tip height.

Returns​

Promise<number>

getOutspend()​
getOutspend(txid: string, vout: number): Promise<Outspend>;

Whether a specific output has been spent, and by which transaction.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<Outspend>

getTx()​
getTx(txid: string): Promise<string | null>;

Raw transaction hex, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<string | null>

getTxConfirmations()​
getTxConfirmations(txid: string): Promise<number>;

Number of confirmations for a transaction, or 0 if unconfirmed.

Parameters​
ParameterType
txidstring
Returns​

Promise<number>

getTxFee()​
getTxFee(txid: string): Promise<number | null>;

Miner fee paid by a transaction, in satoshis, or null if not found.

Parameters​
ParameterType
txidstring
Returns​

Promise<number | null>

getTxStatus()​
getTxStatus(txid: string): Promise<TxStatus>;

Confirmation status of a transaction.

Parameters​
ParameterType
txidstring
Returns​

Promise<TxStatus>

outspend()?​
optional outspend(txid: string, vout: number): Promise<HistoryTx | undefined>;

The transaction spending an output, mempool included, or undefined while it is unspent. Needed only to serve the driver as its ChainClient.

Parameters​
ParameterType
txidstring
voutnumber
Returns​

Promise<HistoryTx | undefined>

scripthashTxs()​
scripthashTxs(scriptHash: string, lastSeen?: string): Promise<EsploraTx[]>;

Transactions paying a scripthash, newest first.

Parameters​
ParameterType
scriptHashstring
lastSeen?string
Returns​

Promise<EsploraTx[]>


EsploraOptions​

How an Esplora client makes its requests.

Properties​

PropertyTypeDescription
signal?AbortSignalAborts every request of this client, beside the timeout, for good once aborted. Aborting is safe at any time, but a swap-out that is Claiming needs passes that finish, or the server's CSV refund can take the opening.
timeout?numberSeconds each try of a request may go unanswered before it fails, above zero. Defaults to 30. A fetch passed in gets the timeout in init.signal, so its own error handling sees the TimeoutError.

EsploraTx​

Minimal transaction record returned by address- and scripthash-lookup endpoints.

Properties​

PropertyType
statusTxStatus
txidstring

HistoryTx​

One transaction of an address's history: its raw hex and confirming height, null in the mempool. What the WASM driver's ChainClient reads.

Properties​

PropertyType
heightnumber | null
hexstring

Outspend​

Whether a specific output has been spent, and - if so - the spending transaction and its status.

Properties​

PropertyType
spentboolean
status?TxStatus
txid?string
vin?number

TxStatus​

Transaction confirmation status as returned by esplora.

Properties​

PropertyType
block_height?number
confirmedboolean