@electrum-cash/protocol NPM

Electrum Cash Protocol Library

The Electrum Cash Protocol (@electrum-cash/protocol) provides fully typed functions and events for all Electrum Cash methods.

Download (NPM)

Install the library with:

npm install @electrum-cash/protocol

Examples

Initialization

Before you can make requests you first need to set up and connect to a server.

// Import the electrum protocol library.
import { initializeElectrumClient } from '@electrum-cash/protocol';

// Initialize an electrum client with following the electrum protocol.
const electrumClient = await initializeElectrumClient('Electrum Protocol Test', 'bch.imaginary.cash');

Event handling

After you have initialized an electrum client with the @electrum-cash/protocol library, it will emit fully typed subscription events.

// Set up handler functions for electrum events.
electrumClient.on('blockchain.address.subscribe', handleAddressStatusUpdates);
electrumClient.on('blockchain.transaction.subscribe', handleTransactionStatusUpdates);
electrumClient.on('blockchain.transaction.dsproof.subscribe', handleTransactionDoublespendEvents);
electrumClient.on('blockchain.headers.subscribe', handleNewBlockchainHeaders);

Requests

After you have initialized an electrum client with the @electrum-cash/protocol library, you can request data with the following functions.

Address

// Import address related requests.
import { fetchHistory, fetchPendingTransactions, fetchBalance, fetchUnspentTransactionOutputs } from '@electrum-cash/protocol';

// Fetch transaction history for an address.
const currentAddressHistory = await fetchHistory(electrumClient, someAddress);
console.log('history', currentAddressHistory);

// Fetch pending transactions relating to an address.
const pendingTransactions = await fetchPendingTransactions(electrumClient, someAddress);
console.log('pending transactions', pendingTransactions);

// Fetch the current spendable balance of an addess.
const currentTrustedBalance = await fetchBalance(electrumClient, someAddress);
console.log('trusted balance', currentTrustedBalance);

// Fetch a list of unspent transaction outputs for an address.
const currentUnspentOutputs = await fetchUnspentTransactionOutputs(electrumClient, someAddress);
console.log('unspent outputs', currentUnspentOutputs);

Blockchain

// Import chain related requests.
import { fetchBlockHeaderFromBlockHeight, fetchBlockHeaders, fetchBlockHeaderWithProofFromBlockHeight, fetchCurrentChainTip } from '@electrum-cash/protocol';

// Fetch the block header of a given block height.
const checkpointBlockHeader = await fetchBlockHeaderFromBlockHeight(electrumClient, someBlockHeight);
console.log('header from height', checkpointBlockHeader);

// Fetch three block headers start at a specified height.
const blockHeaders = await fetchBlockHeaders(electrumClient, electrumCheckpoint.height, 3);
console.log('list of headers', blockHeaders);

// Fetch a block header and merkle proof of the blocks inclusion in the chain.
const checkpointBlockHeaderWithProof = await fetchBlockHeaderWithProofFromBlockHeight(electrumClient, electrumCheckpoint.height, someBlockHeight);
console.log('header with proof', checkpointBlockHeaderWithProof);

// Fetch the current block height, also called the chain tip.
const currentChainTip = await fetchCurrentChainTip(electrumClient);
console.log('current chaintip', currentChainTip);

Transaction

// Import transaction related requests.
import { broadcastTransaction, fetchDoublespendProof, fetchTransaction, fetchTransactionBlockHeight, fetchTransactionProof } from '@electrum-cash/protocol';

// Broadcast a transaction to the network.
const transactionHash = await broadcastTransaction(electrumClient, someTransaction);
console.log('txhash', transactionHash);

// Fetch double spend proofs related to a transaction, if they exist.
const doublespendProof = await fetchDoublespendProof(electrumClient, someTransaction);
console.log('dsproof', doublespendProof);

// Fetch a raw transaction.
const transactionHex = await fetchTransaction(electrumClient, someTransaction);
console.log('fetch transaction', transactionHex);

// Fetch the block height a given transaction was included in, if possible.
const transactionBlockHeight= await fetchTransactionBlockHeight(electrumClient, someTransaction);
console.log('fetch transaction height', transactionBlockHeight);

// Fetch a merkle proof that a transaction was included in a specific block.
const transactionProof = await fetchTransactionProof(electrumClient, someTransaction, 800649);
console.log('fetch transaction proof', transactionProof);