bitcoinrpc

README

Bitcoin JSON-RPC Client - Golang

Another optimized Bitcoin JSON-RPC client implemented by GoLang.

Why we need to re-implement

A picture is worth a thousand words:

Once a time I dig deeper into why my service with really stupid slow response as query bitcoin block via btcd rpc client. I figure out that json unmarshal in Golang standard library cost most of the time.

This repository aim to optimize the performance between Go object and JSON conversion.

Documentation

Index

• Variables
• type BackendVersion
• type Client
  • func New(config *ConnConfig) (*Client, error)
  • func (c *Client) BackendVersion() (BackendVersion, error)
  • func (c *Client) GetBlockChainInfo() (*rpcproto.GetBlockChainInfoResult, error)
  • func (c *Client) GetBlockChainInfoAsync() FutureGetBlockChainInfoResult
  • func (c *Client) GetBlockHash(blockHeight int64) (*chainhash.Hash, error)
  • func (c *Client) GetBlockHashAsync(blockHeight int64) FutureGetBlockHashResult
  • func (c *Client) GetBlockVerboseTx(blockHash *chainhash.Hash) (*rpcproto.GetBlockVerboseTxResult, error)
  • func (c *Client) GetBlockVerboseTxAsync(blockHash *chainhash.Hash) FutureGetBlockVerboseTxResult
  • func (c *Client) GetNetworkInfo() (*btcjson.GetNetworkInfoResult, error)
  • func (c *Client) GetNetworkInfoAsync() FutureGetNetworkInfoResult
  • func (c *Client) NextID() uint64
  • func (c *Client) Shutdown()
  • func (c *Client) WaitForShutdown()
• type ConnConfig
• type FutureGetBlockChainInfoResult
  • func (r FutureGetBlockChainInfoResult) Receive() (*rpcproto.GetBlockChainInfoResult, error)
• type FutureGetBlockHashResult
  • func (r FutureGetBlockHashResult) Receive() (*chainhash.Hash, error)
• type FutureGetBlockVerboseTxResult
  • func (r FutureGetBlockVerboseTxResult) Receive() (*rpcproto.GetBlockVerboseTxResult, error)
• type FutureGetNetworkInfoResult
  • func (r FutureGetNetworkInfoResult) Receive() (*btcjson.GetNetworkInfoResult, error)

Variables

var (
	// ErrInvalidAuth is an error to describe the condition where the client
	// is either unable to authenticate or the specified endpoint is
	// incorrect.
	ErrInvalidAuth = errors.New("authentication failure")

	// ErrClientShutdown is an error to describe the condition where the
	// client is either already shutdown, or in the process of shutting
	// down.  Any outstanding futures when a client shutdown occurs will
	// return this error as will any new requests.
	ErrClientShutdown = errors.New("the client has been shutdown")
)

Types

type BackendVersion

type BackendVersion uint8

BackendVersion represents the version of the backend the client is currently connected to.

const (
	// BitcoindPre19 represents a bitcoind version before 0.19.0.
	BitcoindPre19 BackendVersion = iota

	// BitcoindPost19 represents a bitcoind version equal to or greater than
	// 0.19.0.
	BitcoindPost19
)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a Bitcoin RPC client which allows easy access to the various RPC methods available on a Bitcoin RPC server. Each of the wrapper functions handle the details of converting the passed and return types to and from the underlying JSON types which are required for the JSON-RPC invocations

The client provides each RPC in both synchronous (blocking) and asynchronous (non-blocking) forms. The asynchronous forms are based on the concept of futures where they return an instance of a type that promises to deliver the result of the invocation at some future time. Invoking the Receive method on the returned future will block until the result is available if it's not already.

func New

func New(config *ConnConfig) (*Client, error)

New creates a new RPC client based on the provided connection configuration details. The notification handlers parameter may be nil if you are not interested in receiving notifications and will be ignored if the configuration is set to run in HTTP POST mode.

func (*Client) BackendVersion

func (c *Client) BackendVersion() (BackendVersion, error)

BackendVersion retrieves the version of the backend the client is currently connected to.

func (*Client) GetBlockChainInfo

func (c *Client) GetBlockChainInfo() (*rpcproto.GetBlockChainInfoResult, error)

GetBlockChainInfo returns information related to the processing state of various chain-specific details such as the current difficulty from the tip of the main chain.

func (*Client) GetBlockChainInfoAsync

func (c *Client) GetBlockChainInfoAsync() FutureGetBlockChainInfoResult

GetBlockChainInfoAsync returns an instance of a type that can be used to get the result of the RPC at some future time by invoking the Receive function on the returned instance.

See GetBlockChainInfo for the blocking version and more details.

func (*Client) GetBlockHash

func (c *Client) GetBlockHash(blockHeight int64) (*chainhash.Hash, error)

GetBlockHash returns the hash of the block in the best block chain at the given height.

func (*Client) GetBlockHashAsync

func (c *Client) GetBlockHashAsync(blockHeight int64) FutureGetBlockHashResult

GetBlockHashAsync returns an instance of a type that can be used to get the result of the RPC at some future time by invoking the Receive function on the returned instance.

See GetBlockHash for the blocking version and more details.

func (*Client) GetBlockVerboseTx

func (c *Client) GetBlockVerboseTx(blockHash *chainhash.Hash) (*rpcproto.GetBlockVerboseTxResult, error)

GetBlockVerboseTx returns a data structure from the server with information about a block and its transactions given its hash.

See GetBlockVerbose if only transaction hashes are preferred. See GetBlock to retrieve a raw block instead.

func (*Client) GetBlockVerboseTxAsync

func (c *Client) GetBlockVerboseTxAsync(blockHash *chainhash.Hash) FutureGetBlockVerboseTxResult

GetBlockVerboseTxAsync returns an instance of a type that can be used to get the result of the RPC at some future time by invoking the Receive function on the returned instance.

See GetBlockVerboseTx or the blocking version and more details.

func (*Client) GetNetworkInfo

func (c *Client) GetNetworkInfo() (*btcjson.GetNetworkInfoResult, error)

GetNetworkInfo returns data about the current network.

func (*Client) GetNetworkInfoAsync

func (c *Client) GetNetworkInfoAsync() FutureGetNetworkInfoResult

GetNetworkInfoAsync returns an instance of a type that can be used to get the result of the RPC at some future time by invoking the Receive function on the returned instance.

See GetNetworkInfo for the blocking version and more details.

func (*Client) NextID

func (c *Client) NextID() uint64

NextID returns the next id to be used when sending a JSON-RPC message. This ID allows responses to be associated with particular requests per the JSON-RPC specification. Typically the consumer of the client does not need to call this function, however, if a custom request is being created and used this function should be used to ensure the ID is unique amongst all requests being made.

func (*Client) Shutdown

func (c *Client) Shutdown()

Shutdown shuts down the client by disconnecting any connections associated with the client and, when automatic reconnect is enabled, preventing future attempts to reconnect. It also stops all goroutines.

func (*Client) WaitForShutdown

func (c *Client) WaitForShutdown()

WaitForShutdown blocks until the client goroutines are stopped and the connection is closed.

type ConnConfig

type ConnConfig struct {
	// Host is the IP address and port of the RPC server you want to connect
	// to.
	Host string

	// User is the username to use to authenticate to the RPC server.
	User string

	// Pass is the passphrase to use to authenticate to the RPC server.
	Pass string

	// Params is the string representing the network that the server
	// is running. If there is no parameter set in the config, then
	// mainnet will be used by default.
	Params string

	// DisableTLS specifies whether transport layer security should be
	// disabled.  It is recommended to always use TLS if the RPC server
	// supports it as otherwise your username and password is sent across
	// the wire in cleartext.
	DisableTLS bool

	// DisableAutoReconnect specifies the client should not automatically
	// try to reconnect to the server when it has been disconnected.
	DisableAutoReconnect bool
}

ConnConfig describes the connection configuration parameters for the client. This

type FutureGetBlockChainInfoResult

type FutureGetBlockChainInfoResult struct {
	Response chan *response
	// contains filtered or unexported fields
}

FutureGetBlockChainInfoResult is a promise to deliver the result of a GetBlockChainInfoAsync RPC invocation (or an applicable error).

func (FutureGetBlockChainInfoResult) Receive

func (r FutureGetBlockChainInfoResult) Receive() (*rpcproto.GetBlockChainInfoResult, error)

Receive waits for the response promised by the future and returns chain info result provided by the server.

type FutureGetBlockHashResult

type FutureGetBlockHashResult chan *response

FutureGetBlockHashResult is a future promise to deliver the result of a GetBlockHashAsync RPC invocation (or an applicable error).

func (FutureGetBlockHashResult) Receive

func (r FutureGetBlockHashResult) Receive() (*chainhash.Hash, error)

Receive waits for the response promised by the future and returns the hash of the block in the best block chain at the given height.

type FutureGetBlockVerboseTxResult

type FutureGetBlockVerboseTxResult struct {
	Response chan *response
	// contains filtered or unexported fields
}

FutureGetBlockVerboseTxResult is a future promise to deliver the result of a GetBlockVerboseTxResult RPC invocation (or an applicable error).

func (FutureGetBlockVerboseTxResult) Receive

func (r FutureGetBlockVerboseTxResult) Receive() (*rpcproto.GetBlockVerboseTxResult, error)

Receive waits for the response promised by the future and returns a verbose version of the block including detailed information about its transactions.

type FutureGetNetworkInfoResult

type FutureGetNetworkInfoResult chan *response

FutureGetNetworkInfoResult is a future promise to deliver the result of a GetNetworkInfoAsync RPC invocation (or an applicable error).

func (FutureGetNetworkInfoResult) Receive

func (r FutureGetNetworkInfoResult) Receive() (*btcjson.GetNetworkInfoResult, error)

Receive waits for the response promised by the future and returns data about the current network.