btc-bridge
A simple library for broadcasting Bitcoin transactions and querying chain state over RPC and/or 3rd party provider APIs
Installation
npm install --save btc-bridge
Providers
All blockchain operations are performed through configurable Provider objects.
btc-bridge
offers the following providers:
JSON-RPC
This provider allows you to connect through a Bitcoin node's RPC interface.
Supported networks: MAINNET, TESTNET, REGTEST
const btcBridge = let network = btcBridgenetworksMAINNET // or btcBridge.networks.TESTNETlet uri = 'http://64.101.12.227:8332' // the node URIlet un = 'rpcuser' // the node rpc user namelet pw = 'rpcpass' // the node rpc passwordlet raw = false // additionally return the raw result from the provider (default: false) let rpcProvider = network uri un pw raw
Blockcypher
This provider allows you to connect using the Blockcypher API.
Supported networks: MAINNET, TESTNET
const btcBridge = let network = btcBridgenetworksMAINNET // or btcBridge.networks.TESTNETlet apiKey = '62a583e112d94dbacfe6143beef65e12' // your Blockcypher API keylet raw = false // additionally return the raw result from the provider (default: false) let bcProvider = network apiKey raw
Fallback
This provider allows you to fall back on other providers. The provider is configured with an array of JSON-RPC and/or Blockcypher providers. By default, the first provider in the array will be used, and in the event of failure, the next provider in the list will be attempted, in sequential order. You may optionally set randomize
to true
in order to randomize the order in which providers are used on each function call.
Supported networks: Dependent upon type of providers added, all added providers must use the same network.
const btcBridge = let network = btcBridgenetworksMAINNET // or btcBridge.networks.TESTNET let uri1 = 'http://64.101.12.111:8332' // the node URIlet un1 = 'rpcuser1' // the node rpc user namelet pw1 = 'rpcpass1' // the node rpc password let rpcProvider1 = network uri1 un1 pw1 let uri2 = 'http://64.101.12.222:8332' // the node URIlet un2 = 'rpcuser2' // the node rpc user namelet pw2 = 'rpcpass2' // the node rpc password let rpcProvider2 = network uri2 un2 pw2 let apiKey = '62a583e112d94dbacfe6143beef65e12' // your Blockcypher API key let bcProvider = network apiKey let randomize = true // randomize the order of providers on each function call (default: false)let providers = rpcProvider1 rpcProvider2 bcProvider // an array of already configured providerslet fbProvider = providers randomize
Provider Methods
Providers query their sources and return values using a uniform result schema. Setting raw
to true
in the methods below will also add a raw
field to the result containing the exact repsonse received from the provider's source.
Each provider contains the following methods:
getUnspentOutputsAsync
broadcastTransactionAsync
getTransactionDataAsync
getBlockDataAsync
getEstimatedFeeAsync
getUnspentOutputsAsync
This function is used to query for the UTXOs for a given bitcoin address.
let address = 'mvFu8oJiWjrTXqAkJ3iKR7F2UKmYuYWutF' // the bitcoin address to querylet raw = false // additionally return the raw result from the provider (default: false)let result = await fbProvider
Sample response:
IMPORTANT NOTE: When using the JSON-RPC provider, the address for which you are querying UTXO data MUST be under watch by the node, otherwise the results will always be an empty array! To be watched by a node, the address first needs to be imported or added to the node's wallet.
broadcastTransactionAsync
This function is used to broadcast a transaction out to the network.
let transactionHex = '0200000001e12891c625a8b727d86fcb785bf21666e16a27eb1ad54514a4d7fce0c018261e010000008a4730440220403386749a676873f658ffed210024595a28ea351ac281f5fc8d8e86f6934e4402207fe8e320c192d81339f82fb81813bd3616ca9acd5c09eb2535b1a469b69407dd014104ca65bc9fd7b1748b989dd86cc393b846ba89db71fc027b2db0dc5c3c3358a768b1431573e38526e3b969aac044b82c2908e01a006cb401cc73495c09af81da2effffffff020000000000000000086a06deadbeefcafec4ea0a0e000000001976a914a1b10285fa95a92cf4027112149de550d4c23ada88ac00000000' // the transaction bodylet raw = false // additionally return the raw result from the provider (default: false)let result = await fbProvider
Sample response:
getTransactionDataAsync
This function is used to retrieve information about a transaction by the transaction id. If an OP_RETURN output is discovered within the transaction, it will be displayed in the optional opReturnValue
field.
let transactionId = 'f09257b2bd15b294264d766bbc27c1f32b9c29b16e6a940d10116d6a7d389ba9' // the transaction idlet raw = false // additionally return the raw result from the provider (default: false)let result = await fbProvider
Sample response:
getBlockDataAsync
This function is used to retrieve information about a block by the block hash or block height.
let blockHash = '00000000000002a636af7536fe3672da255adcc18c4b17d3311320fb3f0cf4b4' // the block hashlet raw = false // additionally return the raw result from the provider (default: false)let result = await fbProvider
Sample response:
getEstimatedFeeAsync
This function is used to discover the estimated fee necessary for transaction confirmation over the next numBlocks
blocks.
The returned value is expressed in BTC per kilobyte.
let numBlocks = 2let raw = false // additionally return the raw result from the provider (default: false)let result = await fbProvider
Sample response:
Wallet
A Wallet object contains information about a bitcoin address as well as a provider to perform functions for that address. Currently, this is limited to the generation (and optional broadcast) of an OP_RETURN transaction.
generateOpReturnTxAsync
This function will automatically retrieve a fee estimate and calculate the final fee to be used in the transaction.
let pkWIF = 'c3sdjjXQfj2ncC3YXb8d1Xjg8rJ2oxXnp5BQ8iskE3aFbeefKVb' // the private key in WIF format for the addresslet provider = fbProvider // or any previous configured providerlet wallet = pkWIF provider let opReturnHexData = 'deadbeefcafe' // the hex data to be stored in the OP_RETURN outputlet confirmBlocks = 6 // the number of blocks blocks to target before confirmation, used for fee calculation (default: 2)let broadcast = true // optionaly broadcast the transaction to the network (default: false)let result = await wallet
Sample response:
generateOpReturnTxWithFeeAsync
This function requires the fee value (in BTC) to be explicitly supplied when invoked.
let pkWIF = 'c3sdjjXQfj2ncC3YXb8d1Xjg8rJ2oxXnp5BQ8iskE3aFbeefKVb' // the private key in WIF format for the addresslet provider = fbProvider // or any previous configured providerlet wallet = pkWIF provider let opReturnHexData = 'deadbeefcafe' // the hex data to be stored in the OP_RETURN outputlet fee = 0001 // the fee to pay to miners, expressed in BTC. Set to `false` to have the fee estimated automatically (default: false)let broadcast = true // optionaly broadcast the transaction to the network (default: false)let result = await wallet
Sample response: