Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nimiq/electrum-client

API to interact with ElectrumX servers from browsers
https://github.com/nimiq/electrum-client

bitcoin electrum electrumx websocket

Last synced: about 10 hours ago
JSON representation

API to interact with ElectrumX servers from browsers

Awesome Lists containing this project

README 

        
# Electrum API for Browsers



Access Bitcoin ElectrumX servers from browsers via a WebSocket-to-TCP proxy.



## Installation



There is no NPM package yet, so you need to set the `#build` branch of this repo

as the package source:



```bash

npm install @nimiq/electrum-client@https://github.com/nimiq/electrum-client#build

# or

yarn add @nimiq/electrum-client@https://github.com/nimiq/electrum-client#build

```



### BitcoinJS Library



`ElectrumApi` depends on [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib),

which is only natively available for NodeJS. To use it in browsers, you need to

create a build with Browserify and include it as a `` in your app HTML:



```bash

browserify -r bitcoinjs-lib -s BitcoinJS | terser --compress --mangle > public/bitcoinjs.min.js

```



You also need to mark the `bitcoinjs-lib` package as _external_ in your bundler to prevent

it from blowing up your app:



- [Rollup](https://rollupjs.org/guide/en/#warning-treating-module-as-external-dependency)

  ([example config](example/rollup.config.js#L37-L43))

- [Webpack](https://webpack.js.org/configuration/externals/#externals)



## Quick Start



```javascript

import { ElectrumApi } from '@nimiq/electrum-client'



// Connect to Blockstream Bitcoin Mainnet server via NIMIQ.WATCH proxy

const electrum = new ElectrumApi();



// Get an object with confirmed and unconfirmed balances in sats

const balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');



// Get a plain object describing a transaction

const tx = await electrum.getTransaction('18aa...b03f');

```



## Usage



### Initialization



```javascript

import { ElectrumApi } from '@nimiq/electrum-client'



const electrum = new ElectrumApi({

    /**

     * The URL and port of the Websocket-to-TCP proxy or ElectrumX server

     * with Websockets enabled.

     *

     * [optional]

     * Default: 'wss://api.nimiq.watch:50002'

     */

    endpoint: 'wss://api.nimiq.watch:50002',



    /**

     * Specify if you are using a Websocket-to-TCP proxy (set to true)

     * or a native ElectrumX websocket connection (set to false).

     *

     * [optional]

     * Default: true

     */

    proxy: true,



    /**

     * Connection token for Websockify proxies, to specify which server

     * to proxy to. Find tokens for available servers at

     * https://api.nimiqwatch.com:50002/tokens.txt.

     *

     * [optional]

     * Default: 'mainnet:electrum.blockstream.info'

     */

    token: 'mainnet:electrum.blockstream.info',



    /**

     * Which Bitcoin network to use to encode and decode addresses.

     * Can be either a BitcoinJS.Network object or either of

     * 'bitcoin' | 'testnet'.

     *

     * [optional]

     * Default: BitcoinJS.network.bitcoin

     */

    network: 'bitcoin',

});

```



### Methods



Get the balance for an address:



```javascript

const balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');



// Returns an object:

// {

//   confirmed: number,

//   unconfirmed: number,

// }

```



Get transaction receipts for an address:



```javascript

const receipts = await electrum.getReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');



// Returns an array of objects:

// Array<{

//   blockHeight: number,

//   transactionHash: string,

//   fee?: number, // When the transaction is unconfirmed

// }>

```



Get transaction history for an address:



```javascript

const txs = await electrum.getHistory('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');



// Returns an array of plain objects describing the address's transactions,

// including block height, block hash and timestamp.

```



Get a specific transaction:



```javascript

const tx = await electrum.getTransaction('18aa...b03f', 641085);

// The second argument (the transaction's block height) is optional.



// Returns a plain object describing the transaction. Includes the block header's

// block height, block hash and timestamp when the block height is given.

```



Get a block header for a block height:



```javascript

const header = await electrum.getBlockHeader(641085);



// Returns a plain object describing the block header.

// {

//   blockHash: string,

//   blockHeight: number,

//   timestamp: number,

//   bits: number,

//   nonce: number,

//   version: number,

//   weight: number,

//   prevHash: string | null,

//   merkleRoot: string | null,

// }

```



Broadcast a raw transaction to the network:



```javascript

const tx = await electrum.broadcastTransaction('0012...13d9');



// Returns a plain object describing the broadcast transaction.

// Throws an error on failure.

```



Subscribe for changing receipts for an address:



```javascript

await electrum.subscribeReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH', (receipts) => {

    // See the `getReceipts` function for the format of `receipts`.

});

// Calls the callback with the current receipts and whenever the receipts change

```



Subscribe to blockchain head changes:



```javascript

await electrum.subscribeHeaders((blockHeader) => {

    // See the `getBlockHeader` method for the format of `blockHeader`

});

// Calls the callback with the current header and whenever the header changes

```



## Websockify



This library uses [Websockify](https://github.com/novnc/websockify) as a WebSocket-to-TCP

proxy server for communicating with ElectrumX servers. Most ElectrumX server implementations

support native websocket connections by now, but no publicly listed server has them

enabled.



If you want to use your own ElectrumX server and have native websockets enabled,

you must set the `proxy` setting to `false` (Websockify requires appending a line-break

(`\n`) character at the end of messages, but native ElectrumX websockets do not).



A public Websockify instance is running at https://api.nimiqwatch.com:50002. You

can see the Electrum servers that it can proxy to [here](https://api.nimiqwatch.com:50002/tokens.txt).