Package org.consensusj.bitcoin.jsonrpc

Class BitcoinClient

java.lang.Object

org.consensusj.jsonrpc.DefaultRpcClient

org.consensusj.bitcoin.jsonrpc.BitcoinClient

All Implemented Interfaces:

AutoCloseable, ChainTipClient, AsyncSupport, JsonRpcClient<JavaType>, JsonRpcTransport<JavaType>

Direct Known Subclasses:

BitcoinExtendedClient, NamecoinClient

public class BitcoinClient
extends DefaultRpcClient
implements ChainTipClient

JSON-RPC Client for Bitcoin Core.

A strongly-typed wrapper for a Bitcoin Core JSON-RPC client using the Bitcoin Core JSON-RPC API.

bitcoinj types are used where appropriate. For example, requesting a block hash will return a Sha256Hash:

 
 Sha256Hash hash = client.getBlockHash(342650);
 

Requesting a Bitcoin balance will return the amount as a Coin:

 
 Coin balance = client.getBalance();
 

This version is written to be compatible with Bitcoin Core 0.20 and later. If used with Omni Core (an enhanced version of Bitcoin Core with Omni Protocol support) Omni Core 0.11.0 or later is required.

Note that according to Issue #2960: Support JSON-RPC 2.0 Bitcoin Core does not correctly follow the JSON-RPC 2.0 specification.

See Also:

• JsonRpcClient
• Bitcoin Core JSON-RPC API reference
• Bitcoin Core Issue #2960: Support JSON-RPC 2.0

  This is still a work-in-progress and the API will change.

Nested Class Summary

Nested classes/interfaces inherited from class org.consensusj.jsonrpc.DefaultRpcClient

DefaultRpcClient.TransientErrorMapper<T>, DefaultRpcClient.TransportFactory

Nested classes/interfaces inherited from interface org.consensusj.jsonrpc.AsyncSupport

AsyncSupport.ThrowingSupplier<T>, AsyncSupport.TransientErrorFilter

Field Summary

Fields

Modifier and Type	Field	Description
static final int	BITCOIN_CORE_VERSION_DESC_DEFAULT
static final int	BITCOIN_CORE_VERSION_MIN

Fields inherited from class org.consensusj.jsonrpc.DefaultRpcClient

jsonRpcVersion, mapper

Constructor Summary

Constructors

Constructor	Description
BitcoinClient(URI server, String rpcuser, String rpcpassword)	Incubating constructor that doesn't require a Network.
BitcoinClient(SSLContext sslContext, URI server, String rpcuser, String rpcpassword)	Incubating constructor that doesn't require a Network.
BitcoinClient(SSLContext sslContext, org.bitcoinj.base.Network network, URI server, String rpcuser, String rpcpassword)
BitcoinClient(org.bitcoinj.base.Network network, URI server, String rpcuser, String rpcpassword)	Construct a BitcoinClient from Network, URI, user name, and password.
BitcoinClient(RpcConfig config)	Construct a BitcoinClient from an RPCConfig data object.

Method Summary

Modifier and Type	Method	Description
void	addNode(String node, String command)	Attempt to add or remove a node from the addnode list, or to try a connection to a node once.
void	close()	Shutdown our thread pool, etc.
Boolean	commandExists(String command)	Checks whether a command exists.
CompletableFuture<Void>	connectToServer(Duration timeout)	Actively connect to server (one time) waiting for it to start if necessary
String	createRawTransaction(List<Outpoint> inputs, Map<org.bitcoinj.base.Address,org.bitcoinj.base.Coin> outputs)	Creates a raw transaction spending the given inputs to the given destinations.
LoadWalletResult	createWallet(String name, Boolean disablePrivateKeys, Boolean blank)
LoadWalletResult	createWallet(String name, Boolean disablePrivateKeys, Boolean blank, String passPhrase, Boolean avoidReuse)
LoadWalletResult	createWallet(String name, Boolean disablePrivateKeys, Boolean blank, String passPhrase, Boolean avoidReuse, Boolean descriptors, Boolean loadOnStartup, Boolean externalSigner)
org.bitcoinj.crypto.ECKey	dumpPrivKey(org.bitcoinj.base.Address address)	Return the private key from the server.
List<org.bitcoinj.base.Sha256Hash>	generateToAddress(int numBlocks, org.bitcoinj.base.Address address)	Mine blocks immediately (RegTest mode)
List<org.bitcoinj.base.Sha256Hash>	generateToAddress(int numBlocks, org.bitcoinj.base.Address address, Integer maxtries)	Mine blocks immediately (RegTest mode)
JsonNode	getAddedNodeInfo(boolean details)	Return information about all added nodes
JsonNode	getAddedNodeInfo(boolean details, String node)	Return information about the given added node
AddressBalanceInfo	getAddressBalance(List<org.bitcoinj.base.Address> addressList)
AddressBalanceInfo	getAddressBalance(org.bitcoinj.base.Address address)
AddressInfo	getAddressInfo(org.bitcoinj.base.Address address)
List<AddressUtxoInfo>	getAddressUtxos(List<org.bitcoinj.base.Address> addressList)
List<AddressUtxoInfo>	getAddressUtxos(org.bitcoinj.base.Address address)
org.bitcoinj.base.Coin	getBalance()	Get the balance for a the default Bitcoin "account"
org.bitcoinj.base.Coin	getBalance(String account)	Get the balance for a Bitcoin "account"
org.bitcoinj.base.Coin	getBalance(String account, Integer minConf)	Get the balance for a Bitcoin "account"
CompletableFuture<org.bitcoinj.core.Block>	getBestBlock()	Composite query that first calls ChainTips, then gets best block for the active tip
org.bitcoinj.core.Block	getBlock(org.bitcoinj.base.Sha256Hash hash)	Returns information about a block with the given block hash.
CompletableFuture<org.bitcoinj.core.Block>	getBlockAsync(org.bitcoinj.base.Sha256Hash hash)
BlockChainInfo	getBlockChainInfo()	The getblockchaininfo RPC provides information about the current state of the block chain.
CompletableFuture<BlockChainInfo>	getBlockChainInfoAsync()
Integer	getBlockCount()	Returns the number of blocks in the longest block chain.
org.bitcoinj.base.Sha256Hash	getBlockHash(Integer index)	Returns the hash of block in best-block-chain at index provided.
BlockInfo	getBlockInfo(org.bitcoinj.base.Sha256Hash hash)	Returns information about a block with the given block hash.
List<ChainTip>	getChainTips()	Deprecated. Use getChainTipsAsync()
CompletableFuture<List<ChainTip>>	getChainTipsAsync()
List<String>	getCommands()	Returns a list of available commands.
ExecutorService	getDefaultAsyncExecutor()	Return the default executor for supplying asynchronicity.
org.bitcoinj.base.Network	getNetwork()	Get network.
NetworkInfo	getNetworkInfo()	The getnetworkinfo RPC returns information about the node's connection to the network.
org.bitcoinj.base.Address	getNewAddress()	Creates a new Bitcoin address for receiving payments, linked to the default account "".
org.bitcoinj.base.Address	getNewAddress(String label)	Creates a new Bitcoin address for receiving payments.
org.bitcoinj.core.Transaction	getRawTransaction(org.bitcoinj.base.Sha256Hash txid)	Get a "raw" transaction (which we use to construct a bitcoinj Transaction)
RawTransactionInfo	getRawTransactionInfo(org.bitcoinj.base.Sha256Hash txid)	Get a "raw" transaction as JSON (which we map to a RawTransactionInfo POJO)
org.bitcoinj.base.Coin	getReceivedByAddress(org.bitcoinj.base.Address address)
org.bitcoinj.base.Coin	getReceivedByAddress(org.bitcoinj.base.Address address, Integer minConf)	get total amount received by an address.
WalletTransactionInfo	getTransaction(org.bitcoinj.base.Sha256Hash txid)
WalletTransactionInfo	getTransaction(org.bitcoinj.base.Sha256Hash txid, Boolean includeWatchOnly, Boolean verbose)
TxOutInfo	getTxOut(org.bitcoinj.base.Sha256Hash txid, Integer vout)	Returns details about an unspent transaction output.
TxOutInfo	getTxOut(org.bitcoinj.base.Sha256Hash txid, Integer vout, Boolean includeMemoryPool)	Returns details about an unspent transaction output.
TxOutSetInfo	getTxOutSetInfo()	Returns statistics about the unspent transaction output set.
List<ZmqNotification>	getZmqNotifications()	The getzmqnotifications RPC returns information about which configured ZMQ notifications are enabled and on which ports.
CompletableFuture<List<ZmqNotification>>	getZmqNotificationsAsync()
String	help()	Returns a human-readable list of available commands.
String	help(String command)	Returns helpful information for a specific command.
List<String>	helpAsLines()	Returns a human-readable list of available commands.
List<MethodHelpEntry>	helpAsMethodEntries()	Returns a human-readable list of available commands.
Stream<String>	helpAsStream()	Returns a human-readable list of available commands.
void	importPrivKey(org.bitcoinj.crypto.ECKey privateKey, String label, boolean rescan)	Import a private key into the server's wallet
void	invalidateBlock(org.bitcoinj.base.Sha256Hash hash)	Permanently marks a block as invalid, as if it violated a consensus rule.
boolean	isAddressIndexEnabled()	Test if address index is enabled, caching the result of the first successful check
List<List<AddressGroupingItem>>	listAddressGroupings()	Returns list of related addresses.
List<ReceivedByAddressInfo>	listReceivedByAddress(Integer minConf, Boolean includeEmpty)
List<BitcoinTransactionInfo>	listTransactions()	List the default number (10) of wallet transactions.
List<BitcoinTransactionInfo>	listTransactions(String label, Integer count)	List wallet transactions.
List<BitcoinTransactionInfo>	listTransactions(String label, Integer count, Integer skip, Boolean includeWatchOnly)	List wallet transactions
List<UnspentOutput>	listUnspent()	Returns a list of unspent transaction outputs with at least one confirmation.
List<UnspentOutput>	listUnspent(Integer minConf, Integer maxConf)	Returns a list of unspent transaction outputs with at least minConf and not more than maxConf confirmations.
List<UnspentOutput>	listUnspent(Integer minConf, Integer maxConf, List<org.bitcoinj.base.Address> filter)
List<UnspentOutput>	listUnspent(Integer minConf, Integer maxConf, List<org.bitcoinj.base.Address> filter, Boolean includeUnsafe)	Returns a list of unspent transaction outputs with at least minConf and not more than maxConf confirmations, filtered by a list of addresses.
List<UnspentOutput>	listUnspent(Integer minConf, Integer maxConf, org.bitcoinj.base.Address address)
List<String>	listWallets()
protected <T> CompletableFuture<JsonRpcResponse<T>>	mapBitcoinTransientErrors(JsonRpcRequest request, JsonRpcResponse<T> response, Throwable t)	TransientErrorMapper suitable for waiting for a temporarily down or restarting Bitcoin JSON-RPC server.
void	reconsiderBlock(org.bitcoinj.base.Sha256Hash hash)	Removes invalidity status of a block and its descendants, reconsider them for activation.
org.bitcoinj.base.Sha256Hash	sendFrom(String account, org.bitcoinj.base.Address address, org.bitcoinj.base.Coin amount)
org.bitcoinj.base.Sha256Hash	sendMany(String account, Map<org.bitcoinj.base.Address,org.bitcoinj.base.Coin> amounts)
org.bitcoinj.base.Sha256Hash	sendRawTransaction(String hexTx)	Submit a raw transaction to local node and network using server's default `maxFeeRate`
org.bitcoinj.base.Sha256Hash	sendRawTransaction(String hexTx, org.bitcoinj.base.Coin maxFeeRate)	Submit a raw transaction to local node and network
org.bitcoinj.base.Sha256Hash	sendRawTransaction(org.bitcoinj.core.Transaction tx)	Submit a raw transaction to local node and network using server's default `maxFeeRate`
org.bitcoinj.base.Sha256Hash	sendRawTransaction(org.bitcoinj.core.Transaction tx, org.bitcoinj.base.Coin maxFeeRate)	Submit a raw transaction to local node and network
org.bitcoinj.base.Sha256Hash	sendToAddress(org.bitcoinj.base.Address address, org.bitcoinj.base.Coin amount)
org.bitcoinj.base.Sha256Hash	sendToAddress(org.bitcoinj.base.Address address, org.bitcoinj.base.Coin amount, String comment, String commentTo)
Boolean	setTxFee(org.bitcoinj.base.Coin amount)	Set the transaction fee per kB.
SignedRawTransaction	signRawTransactionWithWallet(String unsignedTransaction)	Signs inputs of a raw transaction using the wallet.
String	stop()	Tell the server to stop
UnloadWalletResult	unloadWallet()
UnloadWalletResult	unloadWallet(String name, Boolean loadOnStartup)
Boolean	waitForBlock(int blockHeight, int timeout)	Wait for RPC server to reach specified block height.
protected CompletableFuture<BlockChainInfo>	waitForBlockchainInfoAsync(Duration timeout, Duration retry)
CompletableFuture<Void>	waitForConnected()	This is like waitForServer but does not initiate a connection.
CompletableFuture<Void>	waitForConnected(Duration timeout)
boolean	waitForServer(int timeoutSeconds)	Deprecated. Use waitForServer(Duration)
boolean	waitForServer(Duration timeout)	Poll the server regularly until it responds.
protected CompletableFuture<Boolean>	waitForServerAsync(Duration timeout, Duration retry)	Wait for a connection to the server.

Methods inherited from class org.consensusj.jsonrpc.DefaultRpcClient

collectionTypeForClasses, collectionTypeForClasses, defaultType, getJsonRpcVersion, getMapper, getServerURI, identityTransientErrorMapper, pollOnce, responseTypeFor, responseTypeFor, sendRequestForResponseAsync, sendRequestForResponseAsync, statusFromErrorResponse, temporarilyUnavailableResponse, typeForClass, waitForServer, waitForServer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.consensusj.jsonrpc.AsyncSupport

supplyAsync, supplyAsync

Methods inherited from interface org.consensusj.jsonrpc.JsonRpcClient

buildJsonRequest, buildJsonRequest, send, send, send, send, send, send, sendAsync, sendAsync, sendAsync, sendAsync, sendAsync

Methods inherited from interface org.consensusj.jsonrpc.JsonRpcTransport

sendRequestForResponse, syncGet

Field Details

BITCOIN_CORE_VERSION_MIN

public static final int BITCOIN_CORE_VERSION_MIN

See Also:

• Constant Field Values

BITCOIN_CORE_VERSION_DESC_DEFAULT

public static final int BITCOIN_CORE_VERSION_DESC_DEFAULT

See Also:

• Constant Field Values

Constructor Details

BitcoinClient

public BitcoinClient(SSLContext sslContext,
 org.bitcoinj.base.Network network,
 URI server,
 String rpcuser,
 String rpcpassword)

BitcoinClient

public BitcoinClient(SSLContext sslContext,
 URI server,
 String rpcuser,
 String rpcpassword)

Incubating constructor that doesn't require a Network.

When using this constructor, it is recommended that getNetwork() be called after construction and before any other methods are called, to allow the Bitcoin network type to be initialized.

Parameters:

sslContext - Custom socket factory

server - URI of the Bitcoin RPC server

rpcuser - Username (if required)

rpcpassword - Password (if required)

BitcoinClient

public BitcoinClient(URI server,
 String rpcuser,
 String rpcpassword)

Incubating constructor that doesn't require a Network.

When using this constructor, it is recommended that getNetwork() be called after construction and before any other methods are called, to allow the Bitcoin network type to be initialized.

Parameters:

server - URI of the Bitcoin RPC server

rpcuser - Username (if required)

rpcpassword - Password (if required)

BitcoinClient

public BitcoinClient(org.bitcoinj.base.Network network,
 URI server,
 String rpcuser,
 String rpcpassword)

Construct a BitcoinClient from Network, URI, user name, and password.

Parameters:

network - Correct Network Parameters for destination server

server - URI of the Bitcoin RPC server

rpcuser - Username (if required)

rpcpassword - Password (if required)

BitcoinClient

public BitcoinClient(RpcConfig config)

Construct a BitcoinClient from an RPCConfig data object.

Parameters:

config - Contains URI, user name, and password

Method Details

getNetwork

public org.bitcoinj.base.Network getNetwork()

Get network.

Historically the Bitcoin network has been required as a constructor parameter and required to match the mode of the server. However, to simplify client configuration we have added a constructor that doesn't require specification of a network. This changes some assumptions about how BitcoinClient works. Previously, no JSON-RPC I/O calls would be performed unless something was explicitly requested -- which also gave users of BitcoinClient the ability to call waitForServer(Duration) before calling any RPCs.

Until further improvements/changes are made, if you use one of the constructors that does not specify a Network you should call connectToServer(Duration) as soon as possible after calling the constructor (especially before calling any JSON-RPC I/O methods.

Well-behaved users of BitcoinClient should only call this method after either providing a Network in the constructor or calling one of the methods that makes a connection. Because this method is also used internally and indirectly, there is a short timeout specified for extra safety.

Returns:

network for the server

getDefaultAsyncExecutor

public ExecutorService getDefaultAsyncExecutor()

Description copied from interface: AsyncSupport

Return the default executor for supplying asynchronicity.

Specified by:

getDefaultAsyncExecutor in interface AsyncSupport

Returns:

An executor.

close

public void close()
           throws InterruptedException

Shutdown our thread pool, etc.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface JsonRpcClient<JavaType>

Throws:

InterruptedException - if one happens

isAddressIndexEnabled

public boolean isAddressIndexEnabled()
                              throws JsonRpcException,
IOException

Test if address index is enabled, caching the result of the first successful check

Returns:

true if enabled, false if not enabled

Throws:

JsonRpcException - an exception other than 1 of the two expected exceptions is thrown

IOException - something else went wrong

waitForServer

@Deprecated
public boolean waitForServer(int timeoutSeconds)
                      throws JsonRpcException

Deprecated.

Use waitForServer(Duration)

Wait until the server is available.

Keep trying, ignoring (and logging) a known list of exception conditions that may occur while waiting for a bitcoind server to start up. This is similar to the behavior enabled by the -rpcwait option to the bitcoin-cli command-line tool.

Parameters:

timeoutSeconds - Timeout in seconds

Returns:

true if ready, false if timeout or interrupted

Throws:

JsonRpcException - if an "unexpected" exception happens (i.e. an error other than what happens during normal server startup)

waitForServer

public boolean waitForServer(Duration timeout)
                      throws JsonRpcException

Poll the server regularly until it responds.

Parameters:

timeout - how long to wait for server

Returns:

Completes with true if server responded, false for timeout

Throws:

JsonRpcException - if an unexpected JsonRpcException occurs

connectToServer

public CompletableFuture<Void> connectToServer(Duration timeout)

Actively connect to server (one time) waiting for it to start if necessary

Parameters:

timeout - how long to wait

Returns:

completes successfully on connection or exceptionally on fatal error or timeout

waitForConnected

public CompletableFuture<Void> waitForConnected()

This is like waitForServer but does not initiate a connection. It depends upon something else having done so.

Returns:

a future (possibly already completed) that indicates we have connected at least once to the server

waitForConnected

public CompletableFuture<Void> waitForConnected(Duration timeout)

waitForServerAsync

protected CompletableFuture<Boolean> waitForServerAsync(Duration timeout,
 Duration retry)

Wait for a connection to the server. Uses getblockchaininfo to poll server.

Parameters:

timeout - how long to wait for server

retry - time to wait between retries

Returns:

Completes with true if server responded, false for timeout, exceptionally for unexpected errors.

waitForBlockchainInfoAsync

protected CompletableFuture<BlockChainInfo> waitForBlockchainInfoAsync(Duration timeout,
 Duration retry)

waitForBlock

public Boolean waitForBlock(int blockHeight,
 int timeout)
                     throws JsonRpcStatusException,
IOException

Wait for RPC server to reach specified block height.

Parameters:

blockHeight - Block height to wait for

timeout - Timeout in seconds

Returns:

True if blockHeight reached, false if timeout or interrupted

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

mapBitcoinTransientErrors

protected <T> CompletableFuture<JsonRpcResponse<T>> mapBitcoinTransientErrors(JsonRpcRequest request,
 JsonRpcResponse<T> response,
 Throwable t)

TransientErrorMapper suitable for waiting for a temporarily down or restarting Bitcoin JSON-RPC server. This can be used to implement the -rpcwait command-line option, for instance.

stop

public String stop()
            throws JsonRpcStatusException,
IOException

Tell the server to stop

Returns:

A status string

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockCount

public Integer getBlockCount()
                      throws JsonRpcStatusException,
IOException

Returns the number of blocks in the longest block chain.

Returns:

The current block count

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockHash

public org.bitcoinj.base.Sha256Hash getBlockHash(Integer index)
                                          throws JsonRpcStatusException,
IOException

Returns the hash of block in best-block-chain at index provided.

Parameters:

index - The block index

Returns:

The block hash

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockInfo

public BlockInfo getBlockInfo(org.bitcoinj.base.Sha256Hash hash)
                       throws JsonRpcStatusException,
IOException

Returns information about a block with the given block hash.

Parameters:

hash - The block hash

Returns:

The information about the block (JSON/POJO object)

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlock

public org.bitcoinj.core.Block getBlock(org.bitcoinj.base.Sha256Hash hash)
                                 throws JsonRpcStatusException,
IOException

Returns information about a block with the given block hash.

Parameters:

hash - The block hash

Returns:

The information about the block (bitcoinj Block object)

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockAsync

public CompletableFuture<org.bitcoinj.core.Block> getBlockAsync(org.bitcoinj.base.Sha256Hash hash)

getBestBlock

public CompletableFuture<org.bitcoinj.core.Block> getBestBlock()

Composite query that first calls ChainTips, then gets best block for the active tip

Returns:

The current best block

generateToAddress

public List<org.bitcoinj.base.Sha256Hash> generateToAddress(int numBlocks,
 org.bitcoinj.base.Address address,
 Integer maxtries)
                                                     throws IOException

Mine blocks immediately (RegTest mode)

Parameters:

numBlocks - Number of blocks to mine

address - Address to send mined coins to

maxtries - How many iterations to try (or null to use server default -- currently 1,000,000)

Returns:

list containing block header hashes of the generated blocks

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.13.0

generateToAddress

public List<org.bitcoinj.base.Sha256Hash> generateToAddress(int numBlocks,
 org.bitcoinj.base.Address address)
                                                     throws IOException

Mine blocks immediately (RegTest mode)

Parameters:

numBlocks - Number of blocks to mine

address - Address to send mined coins to

Returns:

list containing block header hashes of the generated blocks

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.13.0

listWallets

public List<String> listWallets()
                         throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

createWallet

public LoadWalletResult createWallet(String name,
 Boolean disablePrivateKeys,
 Boolean blank)
                              throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

createWallet

public LoadWalletResult createWallet(String name,
 Boolean disablePrivateKeys,
 Boolean blank,
 String passPhrase,
 Boolean avoidReuse)
                              throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

createWallet

public LoadWalletResult createWallet(String name,
 Boolean disablePrivateKeys,
 Boolean blank,
 String passPhrase,
 Boolean avoidReuse,
 Boolean descriptors,
 Boolean loadOnStartup,
 Boolean externalSigner)
                              throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

unloadWallet

public UnloadWalletResult unloadWallet()
                                throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

unloadWallet

public UnloadWalletResult unloadWallet(String name,
 Boolean loadOnStartup)
                                throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

getNewAddress

public org.bitcoinj.base.Address getNewAddress()
                                        throws JsonRpcStatusException,
IOException

Creates a new Bitcoin address for receiving payments, linked to the default account "".

Returns:

A new Bitcoin address

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getNewAddress

public org.bitcoinj.base.Address getNewAddress(String label)
                                        throws JsonRpcStatusException,
IOException

Creates a new Bitcoin address for receiving payments.

Parameters:

label - The label name for the address to be linked to.

Returns:

A new Bitcoin address

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

dumpPrivKey

public org.bitcoinj.crypto.ECKey dumpPrivKey(org.bitcoinj.base.Address address)
                                      throws JsonRpcStatusException,
IOException

Return the private key from the server. Note: must be in wallet mode with unlocked or unencrypted wallet.

Parameters:

address - Address corresponding to the private key to return

Returns:

The private key

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

importPrivKey

public void importPrivKey(org.bitcoinj.crypto.ECKey privateKey,
 String label,
 boolean rescan)
                   throws JsonRpcStatusException,
IOException

Import a private key into the server's wallet

Parameters:

privateKey - An ECKey (containing a private key)

label - The server-side label for the key

rescan - Rescan the blockchain to find transactions for this key

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

createRawTransaction

public String createRawTransaction(List<Outpoint> inputs,
 Map<org.bitcoinj.base.Address,org.bitcoinj.base.Coin> outputs)
                            throws JsonRpcStatusException,
IOException

Creates a raw transaction spending the given inputs to the given destinations. Note: the transaction inputs are not signed, and the transaction is not stored in the wallet or transmitted to the network.

Parameters:

inputs - The outpoints to spent

outputs - The destinations and amounts to transfer

Returns:

The hex-encoded raw transaction

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

signRawTransactionWithWallet

public SignedRawTransaction signRawTransactionWithWallet(String unsignedTransaction)
                                                  throws JsonRpcStatusException,
IOException

Signs inputs of a raw transaction using the wallet. Arguments 2 and 3 of the RPC are currently not supported, which means UTXOs not currently in the blockchain can't be used and `sighashtype` defaults to `ALL`.

Parameters:

unsignedTransaction - The hex-encoded raw transaction

Returns:

The signed transaction and information whether it has a complete set of signature

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core v0.17

getRawTransaction

public org.bitcoinj.core.Transaction getRawTransaction(org.bitcoinj.base.Sha256Hash txid)
                                                throws JsonRpcStatusException,
IOException

Get a "raw" transaction (which we use to construct a bitcoinj Transaction)

Parameters:

txid - Transaction ID/hash

Returns:

bitcoinj Transaction

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getRawTransactionInfo

public RawTransactionInfo getRawTransactionInfo(org.bitcoinj.base.Sha256Hash txid)
                                         throws JsonRpcStatusException,
IOException

Get a "raw" transaction as JSON (which we map to a RawTransactionInfo POJO)

Parameters:

txid - Transaction ID/hash

Returns:

RawTransactionInfo POJO

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

sendRawTransaction

public org.bitcoinj.base.Sha256Hash sendRawTransaction(org.bitcoinj.core.Transaction tx,
 org.bitcoinj.base.Coin maxFeeRate)
                                                throws JsonRpcStatusException,
IOException

Submit a raw transaction to local node and network

Parameters:

tx - The raw transaction

maxFeeRate - Reject transactions whose fee rate is higher than this value, expressed in BTC/kB. Set to 0 to accept any fee rate.

Returns:

SHA256 Transaction ID

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.19

sendRawTransaction

public org.bitcoinj.base.Sha256Hash sendRawTransaction(String hexTx,
 org.bitcoinj.base.Coin maxFeeRate)
                                                throws JsonRpcStatusException,
IOException

Submit a raw transaction to local node and network

Parameters:

hexTx - The raw transaction as a hex-encoded string

maxFeeRate - Reject transactions whose fee rate is higher than this value, expressed in BTC/kB. Set to 0 to accept any fee rate.

Returns:

SHA256 Transaction ID

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.19

sendRawTransaction

public org.bitcoinj.base.Sha256Hash sendRawTransaction(org.bitcoinj.core.Transaction tx)
                                                throws JsonRpcStatusException,
IOException

Submit a raw transaction to local node and network using server's default `maxFeeRate`

Parameters:

tx - The raw transaction

Returns:

SHA256 Transaction ID

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

sendRawTransaction

public org.bitcoinj.base.Sha256Hash sendRawTransaction(String hexTx)
                                                throws JsonRpcStatusException,
IOException

Submit a raw transaction to local node and network using server's default `maxFeeRate`

Parameters:

hexTx - The raw transaction as a hex-encoded string

Returns:

SHA256 Transaction ID

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.19

getAddressInfo

public AddressInfo getAddressInfo(org.bitcoinj.base.Address address)
                           throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

getReceivedByAddress

public org.bitcoinj.base.Coin getReceivedByAddress(org.bitcoinj.base.Address address)
                                            throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

getReceivedByAddress

public org.bitcoinj.base.Coin getReceivedByAddress(org.bitcoinj.base.Address address,
 Integer minConf)
                                            throws JsonRpcStatusException,
IOException

get total amount received by an address.

Parameters:

address - Address to query

minConf - minimum number of confirmations

Returns:

Is now returning `Coin`, if you need to convert use `BitcoinMath.btcToCoin(result)`

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

listReceivedByAddress

public List<ReceivedByAddressInfo> listReceivedByAddress(Integer minConf,
 Boolean includeEmpty)
                                                  throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

listUnspent

public List<UnspentOutput> listUnspent()
                                throws JsonRpcStatusException,
IOException

Returns a list of unspent transaction outputs with at least one confirmation.

Returns:

The unspent transaction outputs

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

listUnspent

public List<UnspentOutput> listUnspent(Integer minConf,
 Integer maxConf)
                                throws JsonRpcStatusException,
IOException

Returns a list of unspent transaction outputs with at least minConf and not more than maxConf confirmations.

Parameters:

minConf - The minimum confirmations to filter

maxConf - The maximum confirmations to filter

Returns:

The unspent transaction outputs

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

listUnspent

public List<UnspentOutput> listUnspent(Integer minConf,
 Integer maxConf,
 org.bitcoinj.base.Address address)
                                throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

listUnspent

public List<UnspentOutput> listUnspent(Integer minConf,
 Integer maxConf,
 List<org.bitcoinj.base.Address> filter)
                                throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

listUnspent

public List<UnspentOutput> listUnspent(Integer minConf,
 Integer maxConf,
 List<org.bitcoinj.base.Address> filter,
 Boolean includeUnsafe)
                                throws JsonRpcStatusException,
IOException

Returns a list of unspent transaction outputs with at least minConf and not more than maxConf confirmations, filtered by a list of addresses.

Parameters:

minConf - The minimum confirmations to filter

maxConf - The maximum confirmations to filter

filter - Include only transaction outputs to the specified addresses

includeUnsafe - optional

Returns:

The unspent transaction outputs

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getTxOut

public TxOutInfo getTxOut(org.bitcoinj.base.Sha256Hash txid,
 Integer vout)
                   throws JsonRpcStatusException,
IOException

Returns details about an unspent transaction output.

Parameters:

txid - The transaction hash

vout - The transaction output index

Returns:

Details about an unspent output or nothing, if the output was already spent

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getTxOut

public TxOutInfo getTxOut(org.bitcoinj.base.Sha256Hash txid,
 Integer vout,
 Boolean includeMemoryPool)
                   throws JsonRpcStatusException,
IOException

Returns details about an unspent transaction output.

Parameters:

txid - The transaction hash

vout - The transaction output index

includeMemoryPool - Whether to included the memory pool

Returns:

Details about an unspent output or nothing, if the output was already spent

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getTxOutSetInfo

public TxOutSetInfo getTxOutSetInfo()
                             throws JsonRpcStatusException,
IOException

Returns statistics about the unspent transaction output set. Note this call may take some time.

Returns:

statistics about the unspent transaction output set

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBalance

public org.bitcoinj.base.Coin getBalance()
                                  throws JsonRpcStatusException,
IOException

Get the balance for a the default Bitcoin "account"

Returns:

Is now returning `Coin`, if you need to convert use `BitcoinMath.btcToCoin(result)`

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBalance

public org.bitcoinj.base.Coin getBalance(String account)
                                  throws JsonRpcStatusException,
IOException

Get the balance for a Bitcoin "account"

Parameters:

account - A Bitcoin "account". (Be wary of using this feature.)

Returns:

Is now returning `Coin`, if you need to convert use `BitcoinMath.btcToCoin(result)`

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBalance

public org.bitcoinj.base.Coin getBalance(String account,
 Integer minConf)
                                  throws JsonRpcStatusException,
IOException

Get the balance for a Bitcoin "account"

Parameters:

account - A Bitcoin "account". (Be wary of using this feature.)

minConf - minimum number of confirmations

Returns:

Is now returning `Coin`, if you need to convert use `BitcoinMath.btcToCoin(result)`

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

sendToAddress

public org.bitcoinj.base.Sha256Hash sendToAddress(org.bitcoinj.base.Address address,
 org.bitcoinj.base.Coin amount)
                                           throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

sendToAddress

public org.bitcoinj.base.Sha256Hash sendToAddress(org.bitcoinj.base.Address address,
 org.bitcoinj.base.Coin amount,
 String comment,
 String commentTo)
                                           throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

sendFrom

public org.bitcoinj.base.Sha256Hash sendFrom(String account,
 org.bitcoinj.base.Address address,
 org.bitcoinj.base.Coin amount)
                                      throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

sendMany

public org.bitcoinj.base.Sha256Hash sendMany(String account,
 Map<org.bitcoinj.base.Address,org.bitcoinj.base.Coin> amounts)
                                      throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

setTxFee

public Boolean setTxFee(org.bitcoinj.base.Coin amount)
                 throws JsonRpcStatusException,
IOException

Set the transaction fee per kB.

Parameters:

amount - The transaction fee in BTC/kB rounded to the nearest 0.00000001.

Returns:

True if successful

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getTransaction

public WalletTransactionInfo getTransaction(org.bitcoinj.base.Sha256Hash txid)
                                     throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

getTransaction

public WalletTransactionInfo getTransaction(org.bitcoinj.base.Sha256Hash txid,
 Boolean includeWatchOnly,
 Boolean verbose)
                                     throws JsonRpcStatusException,
IOException

Throws:

JsonRpcStatusException

IOException

listTransactions

public List<BitcoinTransactionInfo> listTransactions()
                                              throws JsonRpcStatusException,
IOException

List the default number (10) of wallet transactions.

Returns:

A list of wallet transactions

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

listTransactions

public List<BitcoinTransactionInfo> listTransactions(String label,
 Integer count)
                                              throws JsonRpcStatusException,
IOException

List wallet transactions.

Parameters:

label - Return transactions matching this address label, use "*" to return all transactions. null will use the server default ("*")

count - Maximum number of transactions to return. null will use the sever default number (10)

Returns:

A list of wallet transactions

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

listTransactions

public List<BitcoinTransactionInfo> listTransactions(String label,
 Integer count,
 Integer skip,
 Boolean includeWatchOnly)
                                              throws JsonRpcStatusException,
IOException

List wallet transactions

Parameters:

label - Return transactions matching this address label, use "*" to return all transactions. null will use the server default ("*")

count - Maximum number of transactions to return. null will use the sever default number (10)

skip - Number of transactions to skip. null will use the server default (0)

includeWatchOnly - Include transactions to/from watch-only addresses. null will use the server default, which is (true) for watch-only wallets, false otherwise.

Returns:

A list of wallet transactions

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockChainInfo

public BlockChainInfo getBlockChainInfo()
                                 throws JsonRpcStatusException,
IOException

The getblockchaininfo RPC provides information about the current state of the block chain.

Returns:

An object containing information about the current state of the block chain.

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getBlockChainInfoAsync

public CompletableFuture<BlockChainInfo> getBlockChainInfoAsync()

getNetworkInfo

public NetworkInfo getNetworkInfo()
                           throws JsonRpcStatusException,
IOException

The getnetworkinfo RPC returns information about the node's connection to the network.

Returns:

information about the node's connection to the network

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getZmqNotifications

public List<ZmqNotification> getZmqNotifications()
                                          throws JsonRpcStatusException,
IOException

The getzmqnotifications RPC returns information about which configured ZMQ notifications are enabled and on which ports.

Returns:

A List of ZMQ Notification info records

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getZmqNotificationsAsync

public CompletableFuture<List<ZmqNotification>> getZmqNotificationsAsync()

listAddressGroupings

public List<List<AddressGroupingItem>> listAddressGroupings()
                                                     throws JsonRpcStatusException,
IOException

Returns list of related addresses. Also useful for finding all change addresses in the wallet

Returns:

a list of address groupings

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

help

public String help()
            throws JsonRpcStatusException,
IOException

Returns a human-readable list of available commands.

Bitcoin Core 0.10+ returns a categorized list of commands including blank lines and header lines.

Returns:

The list of commands as string

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

helpAsStream

public Stream<String> helpAsStream()
                            throws JsonRpcStatusException,
IOException

Returns a human-readable list of available commands.

Returns:

The response as a stream of one String for each line

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

helpAsLines

public List<String> helpAsLines()
                         throws JsonRpcStatusException,
IOException

Returns a human-readable list of available commands.

Returns:

The response as a list one String for each line

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

helpAsMethodEntries

public List<MethodHelpEntry> helpAsMethodEntries()
                                          throws JsonRpcStatusException,
IOException

Returns a human-readable list of available commands.

Returns:

The response as a list one MethodHelpEntry for each method

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

help

public String help(String command)
            throws JsonRpcStatusException,
IOException

Returns helpful information for a specific command.

Parameters:

command - The name of the command to get help for

Returns:

The help text

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getCommands

public List<String> getCommands()
                         throws JsonRpcStatusException,
IOException

Returns a list of available commands.

Commands which are unavailable will not be listed, such as wallet RPCs, if wallet support is disabled.

Returns:

The list of commands

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

commandExists

public Boolean commandExists(String command)
                      throws JsonRpcStatusException,
IOException

Checks whether a command exists.

This is done indirectly, by using {help(String) help} to get information about the command, and if information about the command is available, then the command exists. The absence of information does not necessarily imply the non-existence of a command.

Parameters:

command - The name of the command to check

Returns:

True if the command exists

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

invalidateBlock

public void invalidateBlock(org.bitcoinj.base.Sha256Hash hash)
                     throws JsonRpcStatusException,
IOException

Permanently marks a block as invalid, as if it violated a consensus rule.

Parameters:

hash - The block hash

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.10

reconsiderBlock

public void reconsiderBlock(org.bitcoinj.base.Sha256Hash hash)
                     throws JsonRpcStatusException,
IOException

Removes invalidity status of a block and its descendants, reconsider them for activation.

This can be used to undo the effects of {link invalidateBlock(Sha256Hash) invalidateBlock}.

Parameters:

hash - The hash of the block to reconsider

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.10

getChainTips

public List<ChainTip> getChainTips()
                            throws JsonRpcStatusException,
IOException

Deprecated.

Use getChainTipsAsync()

Return information about all known tips in the block tree, including the main chain as well as orphaned branches.

Specified by:

getChainTips in interface ChainTipClient

Returns:

A list of chain tip information

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

Since:

Bitcoin Core 0.10

getChainTipsAsync

public CompletableFuture<List<ChainTip>> getChainTipsAsync()

Specified by:

getChainTipsAsync in interface ChainTipClient

addNode

public void addNode(String node,
 String command)
             throws JsonRpcStatusException,
IOException

Attempt to add or remove a node from the addnode list, or to try a connection to a node once.

Parameters:

node - node to add as a string in the form of IP_address:port

command - `add`, `remove`, or `onetry`

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getAddedNodeInfo

public JsonNode getAddedNodeInfo(boolean details,
 String node)
                          throws JsonRpcStatusException,
IOException

Return information about the given added node

Parameters:

details - `true` to return detailed information

node - the node to provide information about

Returns:

A Jackson JsonNode object (until we define a POJO)

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getAddedNodeInfo

public JsonNode getAddedNodeInfo(boolean details)
                          throws JsonRpcStatusException,
IOException

Return information about all added nodes

Parameters:

details - `true` to return detailed information

Returns:

A Jackson JsonNode object (until we define a POJO)

Throws:

JsonRpcStatusException - JSON RPC status exception

IOException - network error

getAddressBalance

public AddressBalanceInfo getAddressBalance(org.bitcoinj.base.Address address)
                                     throws JsonRpcException,
IOException

Throws:

JsonRpcException

IOException

getAddressBalance

public AddressBalanceInfo getAddressBalance(List<org.bitcoinj.base.Address> addressList)
                                     throws JsonRpcException,
IOException

Throws:

JsonRpcException

IOException

getAddressUtxos

public List<AddressUtxoInfo> getAddressUtxos(org.bitcoinj.base.Address address)
                                      throws JsonRpcException,
IOException

Throws:

JsonRpcException

IOException

getAddressUtxos

public List<AddressUtxoInfo> getAddressUtxos(List<org.bitcoinj.base.Address> addressList)
                                      throws JsonRpcException,
IOException

Throws:

JsonRpcException

IOException