2.6.0 • Published 1 month ago
@electrum-cash/protocol
Licence
MIT
Version
2.6.0
Deps
3
Size
215 kB
Vulns
0
Weekly
0
Introduction
The Electrum Cash Protocol (@electrum-cash/protocol) provides fully typed functions and events for all Electrum Cash methods.
For complete information on all typings, arguments and options available, read to the documentation generated from the source code.
Usage
Installation
Installation is easy, just get the library from NPM:
npm install @electrum-cash/protocol
Setup
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 and subscribe to new information, it will emit fully typed subscription events.
// Set up handler functions for electrum events.
electrumClient.on('blockchain.headers.subscribe', handleNewBlockchainHeaders);
electrumClient.on('blockchain.address.subscribe', handleAddressStatusUpdates);
electrumClient.on('blockchain.transaction.subscribe', handleTransactionStatusUpdates);
electrumClient.on('blockchain.transaction.dsproof.subscribe', handleTransactionDoublespendEvents);
// Subscribe to block headers.
await subscribeToBlockheaderUpdates(electrumClient);
// Subscribe to address status updates for a given address.
await subscribeToAddressUpdates(electrumClient, someAddress);
// Subscribe to transaction block inclusion updates for a given transaction.
await subscribeToTransactionUpdates(electrumClient, someTransactionHash);
// Subscribe to transaction doublespend updates for a given transaction.
await subscribeToDoublespendUpdates(electrumClient, someTransactionHash);
Requesting data
After you have initialized an electrum client 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 address.
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 the block header and inclusion proof the server reports.
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';
// Ask the server to broadcast a transaction. The returned hash is checked against the transaction that was sent.
const transactionHash = await broadcastTransaction(electrumClient, someTransactionHex);
console.log('txhash', transactionHash);
// Fetch double spend proofs related to a transaction, if they exist.
const doublespendProof = await fetchDoublespendProof(electrumClient, someTransactionHash);
console.log('dsproof', doublespendProof);
// Fetch a raw transaction. Its hash is checked against the hash that was requested.
const transactionHex = await fetchTransaction(electrumClient, someTransactionHash);
console.log('fetch transaction', transactionHex);
// Fetch the block height a given transaction was included in, if possible.
const transactionBlockHeight= await fetchTransactionBlockHeight(electrumClient, someTransactionHash);
console.log('fetch transaction height', transactionBlockHeight);
// Fetch the merkle proof the server reports.
const transactionProof = await fetchTransactionProof(electrumClient, someTransactionHash, 800649);
console.log('fetch transaction proof', transactionProof);
UTXO
// Import UTXO related requests.
import { fetchUnspentTransactionOutputInfo } from '@electrum-cash/protocol';
// Fetch information about an unspent transaction output, or null if it does not exist or is spent.
const unspentOutput = await fetchUnspentTransactionOutputInfo(electrumClient, someTransactionHash, someOutputIndex);
console.log('unspent output', unspentOutput);
Mempool
// Import mempool related requests.
import { fetchMempoolFeeHistogram, fetchMempoolInfo } from '@electrum-cash/protocol';
// Fetch a histogram of the fee rates paid by transactions in the mempool.
const feeHistogram = await fetchMempoolFeeHistogram(electrumClient);
console.log('fee histogram', feeHistogram);
// Fetch mempool statistics, such as the current minimum fee rates.
const mempoolInfo = await fetchMempoolInfo(electrumClient);
console.log('mempool info', mempoolInfo);
Server
// Import server related requests.
import { fetchServerBanner, fetchServerDonationAddress, fetchServerFeatures, fetchServerPeers, pingServer } from '@electrum-cash/protocol';
// Fetch the banner of the server.
const banner = await fetchServerBanner(electrumClient);
console.log('banner', banner);
// Fetch the donation address of the server.
const donationAddress = await fetchServerDonationAddress(electrumClient);
console.log('donation address', donationAddress);
// Fetch the features and services supported by the server.
const features = await fetchServerFeatures(electrumClient);
console.log('features', features);
// Fetch a list of peer servers known to the server.
const peers = await fetchServerPeers(electrumClient);
console.log('peers', peers);
// Ping the server to ensure it is responding, and to keep the session alive.
await pingServer(electrumClient);
Support
If you find bugs or have problems using this library, you can file issues on the Gitlab.