Bitcoin.Core.RPC

We provide limited access to the bitcoin-core daemon RPC interface. RPC method descriptions come from the bitcoind RPC help pages.

Interacting with bitcoind

type BitcoindClient r = ReaderT BasicAuthData (ExceptT BitcoindException ClientM) r

runBitcoind

Arguments

:: Manager

-> String

host

-> Int

port

-> BasicAuthData

-> BitcoindClient a

-> IO (Either BitcoindException a)

Convenience function for sending a RPC call to bitcoind

cookieClient

Arguments

:: Manager

-> FilePath

path to the cookie file

-> String

host

-> Int

port

-> BitcoindClient r

-> IO (Either BitcoindException r)

Send a RPC call to bitcoind using credentials from a cookie file

basicAuthFromCookie

Arguments

:: FilePath

path to the cookie file

-> IO BasicAuthData

Parse a username and password from a file. The contents of the file should be exactly "username:password" (not base64 encoded).

mkBitcoindEnv

Arguments

:: Manager

-> String

bitcoind host

-> Int

bitcoind RPC port

-> ClientEnv

Convenience function for connecting to bitcoind

data BitcoindException

Exceptions resulting from interacting with bitcoind

Constructors

RpcException String

The error message returned by bitcoind on failure

ClientException ClientError

DecodingError String

Instances

Show BitcoindException

Defined in Servant.Bitcoind

Methods

showsPrec :: Int -> BitcoindException -> ShowS

show :: BitcoindException -> String

showList :: [BitcoindException] -> ShowS

Exception BitcoindException

Defined in Servant.Bitcoind

Methods

toException :: BitcoindException -> SomeException

fromException :: SomeException -> Maybe BitcoindException

displayException :: BitcoindException -> String

Transactions

getTransaction :: TxHash -> Maybe BlockHash -> BitcoindClient Tx

By default this function only works for mempool transactions. When called with a blockhash argument, getrawtransaction will return the transaction if the specified block is available and the transaction is found in that block. When called without a blockhash argument, getrawtransaction will return the transaction if it is in the mempool, or if -txindex is enabled and the transaction is in a block in the blockchain.

sendRawTransaction :: Text -> Maybe Double -> BitcoindClient TxHash

Submit a raw transaction (serialized, hex-encoded) to local node and network.

sendTransaction :: Tx -> Maybe Double -> BitcoindClient TxHash

A version of sendRawTransaction that handles serialization

testMempoolAccept :: [Tx] -> Maybe Double -> BitcoindClient [MempoolTestResult]

Returns result of mempool acceptance tests indicating if the transactions would be accepted by mempool. This checks if the transaction violates the consensus or policy rules.

Blocks

getBlock :: BlockHash -> BitcoindClient Block

Produce the block corresponding to the given BlockHash if it exists.

getBlockFilter :: BlockHash -> BitcoindClient CompactFilter

Retrieve a BIP 157 content filter for a particular block.

getBlockHeader :: BlockHash -> BitcoindClient BlockHeader

Returns the header of the block corresponding to the given BlockHash

getBlockHash :: BlockHeight -> BitcoindClient BlockHash

Returns hash of block in best-block-chain at height provided.

getBlockCount :: BitcoindClient Word32

Returns the height of the most-work fully-validated chain. The genesis block has height 0.

getDifficulty :: BitcoindClient Scientific

Returns the proof-of-work difficulty as a multiple of the minimum difficulty.

getBestBlockHash :: BitcoindClient BlockHash

Returns the hash of the best (tip) block in the most-work fully-validated chain.

getBlockStats :: BlockHash -> BitcoindClient BlockStats

Compute per block statistics for a given window. All amounts are in satoshis. It won't work for some heights with pruning.

getChainTips :: BitcoindClient [ChainTip]

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

getChainTxStats :: Maybe Word32 -> Maybe BlockHash -> BitcoindClient ChainTxStats

Compute statistics about the total number and rate of transactions in the chain.

Mempool

getMempoolInfo :: BitcoindClient MempoolInfo

Returns details on the active state of the TX memory pool.

getMempoolAncestors :: TxHash -> BitcoindClient [TxHash]

If txid is in the mempool, returns all in-mempool ancestors.

getMempoolDescendants :: TxHash -> BitcoindClient [TxHash]

If txid is in the mempool, returns all in-mempool descendants.

getRawMempool :: BitcoindClient [TxHash]

Returns all transaction ids in memory pool.

Network

getPeerInfo :: BitcoindClient [PeerInfo]

Returns data about each connected network node.

getConnectionCount :: BitcoindClient Word16

Returns the number of connections to other nodes.

getNodeAddresses :: Maybe Word32 -> BitcoindClient [NodeAddress]

Return known addresses which can potentially be used to find new nodes in the network

getAddedNodeInfo

Arguments

:: Maybe Text

optionally specify a node by address

-> BitcoindClient [NodeInfo]

Returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here)

listBanned :: BitcoindClient [Text]

List all banned IPs/Subnets.

getNetTotals :: BitcoindClient NetTotals

Returns information about network traffic, including bytes in, bytes out, and current time.

Control

stop :: BitcoindClient ()

Request a graceful shutdown of Bitcoin Core.

uptime :: BitcoindClient Word32

Returns the total uptime of the server (in seconds)

data Command

Commands as understood by addNode

Constructors

Add

Remove

OneTry

Instances

Enum Command

Defined in Bitcoin.Core.RPC.Network

Methods

succ :: Command -> Command

pred :: Command -> Command

toEnum :: Int -> Command

fromEnum :: Command -> Int

enumFrom :: Command -> [Command]

enumFromThen :: Command -> Command -> [Command]

enumFromTo :: Command -> Command -> [Command]

enumFromThenTo :: Command -> Command -> Command -> [Command]

Eq Command

Defined in Bitcoin.Core.RPC.Network

Methods

(==) :: Command -> Command -> Bool

(/=) :: Command -> Command -> Bool

Show Command

Defined in Bitcoin.Core.RPC.Network

Methods

showsPrec :: Int -> Command -> ShowS

show :: Command -> String

showList :: [Command] -> ShowS

ToJSON Command

Defined in Bitcoin.Core.RPC.Network

Methods

toJSON :: Command -> Value

toEncoding :: Command -> Encoding

toJSONList :: [Command] -> Value

toEncodingList :: [Command] -> Encoding

addNode

Arguments

:: Text

node address host:port

-> Command

-> BitcoindClient ()

Attempts to add or remove a node from the addnode list; or try a connection to a node once. Nodes added using addnode are protected from DoS disconnection and are not required to be full nodes/support SegWit as other outbound peers are (though such peers will not be synced from).

disconnectNode

Arguments

:: Text

node address host:port

-> BitcoindClient ()

Immediately disconnects from the specified peer node.

clearBanned :: BitcoindClient ()

Clear all banned IPs.

generateToAddress

Arguments

:: Word32

number of blocks to generate

-> Text

address for the coinbase reward

-> Maybe Word32

how many iterations to try

-> BitcoindClient [BlockHash]

Generate blocks in regtest mode

Response models

module Bitcoin.Core.RPC.Responses