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.

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

Parameter	Type	Default value	Description
`url`	`string`	`undefined`	Esplora base URL including any path prefix.
`fetchFn`	(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`<`Response`>	`fetch`	Optional `fetch` implementation. Defaults to the global `fetch`.
`options`	`EsploraOptions`	`{}`	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.

Parameters

Parameter	Type
`address`	`string`

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

Parameter	Type
`address`	`string`
`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

Parameter	Type
`txHex`	`string`

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

Parameter	Type
`height`	`number`

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.

Parameters

Parameter	Type
`target`	`number`

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

Parameter	Type
`txid`	`string`
`vout`	`number`

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

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`

Returns

Promise<number | null>

Inherited from

EsploraBase.getTxFee

getTxStatus()

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

Confirmation status of a transaction.

Parameters

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`
`vout`	`number`

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

Parameter	Type
`scriptHash`	`string`
`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

Parameter	Type	Default value	Description
`url`	`string`	`undefined`	Esplora base URL including any path prefix.
`fetchFn`	(`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`) => `Promise`<`Response`>	`fetch`	Optional `fetch` implementation. Defaults to the global `fetch`.
`options`	`EsploraOptions`	`{}`	Optional request settings, see EsploraOptions.

Returns

LiquidEsplora

Inherited from

EsploraBase.constructor

Methods

addressHistory()

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

Parameters

Parameter	Type
`address`	`string`

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

Parameter	Type
`address`	`string`
`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

Parameter	Type
`txHex`	`string`

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

Parameter	Type
`height`	`number`

Returns

Promise<string>

Inherited from

EsploraBase.getBlockHash

getFeeRate()

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

Parameters

Parameter	Type
`target`	`number`

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

Parameter	Type
`txid`	`string`
`vout`	`number`

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

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`

Returns

Promise<number | null>

Inherited from

EsploraBase.getTxFee

getTxStatus()

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

Confirmation status of a transaction.

Parameters

Parameter	Type
`txid`	`string`

Returns

Promise<TxStatus>

Inherited from

EsploraBase.getTxStatus

outspend()

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

Parameters

Parameter	Type
`txid`	`string`
`vout`	`number`

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

Parameter	Type
`scriptHash`	`string`
`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

Parameter	Type
`address`	`string`

Returns

Promise<HistoryTx[]>

addressTxs()

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

Transactions paying an address, newest first.

Parameters

Parameter	Type
`address`	`string`
`lastSeen?`	`string`

Returns

Promise<EsploraTx[]>

broadcast()

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

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

Parameters

Parameter	Type
`txHex`	`string`

Returns

Promise<string>

getBlockHash()

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

Block hash at a given height, hex-encoded.

Parameters

Parameter	Type
`height`	`number`

Returns

Promise<string>

getFeeRate()

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

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

Parameters

Parameter	Type
`target`	`number`

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

Parameter	Type
`txid`	`string`
`vout`	`number`

Returns

Promise<Outspend>

getTx()

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

Raw transaction hex, or null if not found.

Parameters

Parameter	Type
`txid`	`string`

Returns

Promise<string | null>

getTxConfirmations()

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

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

Parameters

Parameter	Type
`txid`	`string`

Returns

Promise<number>

getTxFee()

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

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

Parameters

Parameter	Type
`txid`	`string`

Returns

Promise<number | null>

getTxStatus()

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

Confirmation status of a transaction.

Parameters

Parameter	Type
`txid`	`string`

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

Parameter	Type
`txid`	`string`
`vout`	`number`

Returns

Promise<HistoryTx | undefined>

scripthashTxs()

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

Transactions paying a scripthash, newest first.

Parameters

Parameter	Type
`scriptHash`	`string`
`lastSeen?`	`string`

Returns

Promise<EsploraTx[]>

EsploraOptions

How an Esplora client makes its requests.

Properties

Property	Type	Description
`signal?`	`AbortSignal`	Aborts 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?`	`number`	Seconds one 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

Property	Type
`status`	`TxStatus`
`txid`	`string`

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

Property	Type
`height`	`number` \| `null`
`hex`	`string`

Outspend

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

Properties

Property	Type
`spent`	`boolean`
`status?`	`TxStatus`
`txid?`	`string`
`vin?`	`number`

TxStatus

Transaction confirmation status as returned by esplora.

Properties

Property	Type
`block_height?`	`number`
`confirmed`	`boolean`

Classes​

BitcoinEsplora​

Extends​

Constructors​

Constructor​

Parameters​

Returns​

Inherited from​

Methods​

addressHistory()​

Parameters​

Returns​

Inherited from​

addressTxs()​

Parameters​

Returns​

Inherited from​

broadcast()​

Parameters​

Returns​

Inherited from​

getBlockHash()​

Parameters​

Returns​

Inherited from​

getFeeRate()​

Parameters​

Returns​

Inherited from​

getHeight()​

Returns​

Inherited from​

getOutspend()​

Parameters​

Returns​

Inherited from​

getTx()​

Parameters​

Returns​

Inherited from​

getTxConfirmations()​

Parameters​

Returns​

Inherited from​

getTxFee()​

Parameters​

Returns​

Inherited from​

getTxStatus()​

Parameters​

Returns​

Inherited from​

outspend()​

Parameters​

Returns​

Inherited from​

scripthashTxs()​

Parameters​

Returns​

Inherited from​

LiquidEsplora​

Extends​

Constructors​

Constructor​

Parameters​

Returns​

Inherited from​

Methods​

addressHistory()​

Parameters​

Returns​

Inherited from​

addressTxs()​

Parameters​

Returns​

Inherited from​

broadcast()​

Parameters​

Returns​

Inherited from​

Classes

BitcoinEsplora

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Methods

addressHistory()

Parameters

Returns

Inherited from

addressTxs()

Parameters

Returns

Inherited from

broadcast()

Parameters

Returns

Inherited from

getBlockHash()

Parameters

Returns

Inherited from

getFeeRate()

Parameters

Returns

Inherited from

getHeight()

Returns

Inherited from

getOutspend()

Parameters

Returns

Inherited from

getTx()

Parameters

Returns

Inherited from

getTxConfirmations()

Parameters

Returns

Inherited from

getTxFee()

Parameters

Returns

Inherited from

getTxStatus()

Parameters

Returns

Inherited from

outspend()

Parameters

Returns

Inherited from

scripthashTxs()

Parameters

Returns

Inherited from

LiquidEsplora

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Methods

addressHistory()

Parameters

Returns

Inherited from

addressTxs()

Parameters

Returns

Inherited from

broadcast()

Parameters

Returns

Inherited from