README

bchrpc

Build Status ISC License GoDoc

Package bchrpc implements a gRPC server.

Overview

This package provides a gRPC API which when combined with the addrindex and txindex provides a powerful API for supporting Bitcoin Cash applications. At present the API only exposes public methods for interacting with transactions and blocks. It does not expose any methods which can control the node so it is safe to expose the API publicly. To control the node continue using the JSON-RPC API.

Why gRPC?

With gRPC it is extremely easy to build well-defined, easy to reason about APIs. Frontend development changes significantly:

  • no more hunting down API documentation - .proto is the canonical format for API contracts.
  • no more hand-crafted JSON call objects - all requests and responses are strongly typed and code-generated, with hints available in the IDE.
  • no more dealing with methods, headers, body and low level networking - everything is handled by gRPC.
  • no more second-guessing the meaning of error codes - gRPC status codes are a canonical way of representing issues in APIs.
  • no more one-off server-side request handlers to avoid concurrent connections - gRPC is based on HTTP2, which multiplexes multiple streams over the same connection.
  • no more problems streaming data from a server - gRPC-Web supports both 1:1 RPCs and 1:many streaming requests.
  • no more data parse errors when rolling out new binaries - backwards and forwards-compatibility of requests and responses.

In short, gRPC moves the interaction between frontend code and the server from the sphere of hand-crafted HTTP requests to well-defined user-logic methods.

Using the API

$ bchd --grpclisten=<your_interface>

License

Package bchrpc is licensed under the copyfree ISC License.

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisableLog

func DisableLog()

    DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

    func ServiceReady

    func ServiceReady(service string) error

      ServiceReady returns nil when the service is ready and a gRPC error when not.

      func UseLogger

      func UseLogger(logger bchlog.Logger)

        UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

        Types

        type GrpcServer

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

          GrpcServer is the gRPC server implementation. It holds all the objects necessary to serve the RPCs and implements the bchrpc.proto interface.

          func NewGrpcServer

          func NewGrpcServer(cfg *GrpcServerConfig) *GrpcServer

            NewGrpcServer returns a new GrpcServer which has not yet be started.

            func (*GrpcServer) GetAddressTransactions

              GetAddressTransactions returns the transactions for the given address. Offers offset, limit, and from block options.

              **Requires AddressIndex**

              func (*GrpcServer) GetAddressUnspentOutputs

                GetAddressUnspentOutputs returns all the unspent transaction outputs for the given address.

                **Requires AddressIndex**

                func (*GrpcServer) GetBlock

                func (s *GrpcServer) GetBlock(ctx context.Context, req *pb.GetBlockRequest) (*pb.GetBlockResponse, error)

                  GetBlock returns detailed data for a block.

                  func (*GrpcServer) GetBlockFilter

                    GetBlockFilter returns the compact filter (cf) of a block as a Golomb-Rice encoded set.

                    **Requires CfIndex**

                    func (*GrpcServer) GetBlockInfo

                      GetBlockInfo returns metadata and info for a specified block.

                      func (*GrpcServer) GetBlockchainInfo

                        GetBlockchainInfo returns info about the blockchain including the most recent block hash and height.

                        func (*GrpcServer) GetHeaders

                          GetHeaders takes a block locator object and returns a batch of no more than 2000 headers. Upon parsing the block locator, if the server concludes there has been a fork, it will send headers starting at the fork point, or genesis if no blocks in the locator are in the best chain. If the locator is already at the tip no headers will be returned. see: bchd/bchrpc/documentation/wallet_operation.md

                          func (*GrpcServer) GetMempool

                            GetMempool returns information about all of the transactions currently in the memory pool. Offers an option to return full transactions or just transactions hashes.

                            func (*GrpcServer) GetMempoolInfo

                              GetMempoolInfo returns the state of the current mempool.

                              func (*GrpcServer) GetMerkleProof

                                GetMerkleProof returns a Merkle (SPV) proof for a specific transaction in the provided block.

                                **Requires TxIndex***

                                func (*GrpcServer) GetRawAddressTransactions

                                  GetRawAddressTransactions returns the raw transactions for the given address. Offers offset, limit, and from block options.

                                  **Requires AddressIndex**

                                  func (*GrpcServer) GetRawBlock

                                    GetRawBlock returns a block in a serialized format.

                                    func (*GrpcServer) GetRawTransaction

                                      GetRawTransaction returns a serialized transaction given a transaction hash.

                                      **Requires TxIndex**

                                      func (*GrpcServer) GetTransaction

                                        GetTransaction returns a transaction given its hash.

                                        **Requires TxIndex**

                                        func (*GrpcServer) GetUnspentOutput

                                          GetUnspentOutput takes an unspent output in the utxo set and returns the utxo metadata or not found.

                                          func (*GrpcServer) NotifyNewTransactions

                                          func (s *GrpcServer) NotifyNewTransactions(txs []*mempool.TxDesc)

                                            NotifyNewTransactions is called by the server when new transactions are accepted in the mempool.

                                            func (*GrpcServer) Start

                                            func (s *GrpcServer) Start()

                                              Start will start the GrpcServer, subscribe to blockchain notifications and start the EventDispatcher in a new goroutine.

                                              func (*GrpcServer) Stop

                                              func (s *GrpcServer) Stop() error

                                                Stop is used by server.go to stop the gRPC listener.

                                                func (*GrpcServer) SubmitTransaction

                                                  SubmitTransaction submits a transaction to all connected peers.

                                                  func (*GrpcServer) SubscribeBlocks

                                                  func (s *GrpcServer) SubscribeBlocks(req *pb.SubscribeBlocksRequest, stream pb.Bchrpc_SubscribeBlocksServer) error

                                                    SubscribeBlocks creates a subscription for notifications of new blocks being connected to the blockchain or blocks being disconnected.

                                                    func (*GrpcServer) SubscribeTransactionStream

                                                    func (s *GrpcServer) SubscribeTransactionStream(stream pb.Bchrpc_SubscribeTransactionStreamServer) error

                                                      SubscribeTransactionStream subscribes to relevant transactions based on the subscription requests. The parameters to filter transactions on can be updated by sending new SubscribeTransactionsRequest objects on the stream.

                                                      Because this RPC is using bi-directional streaming it cannot be used with grpc-web.

                                                      **Requires TxIndex to receive input metadata**

                                                      func (*GrpcServer) SubscribeTransactions

                                                        SubscribeTransactions creates subscription to all relevant transactions based on the subscription filter.

                                                        This RPC does not use bidirectional streams and therefore can be used with grpc-web. You will need to close and reopen the stream whenever you want to update the subscription filter. If you are not using grpc-web then SubscribeTransactionStream is more appropriate.

                                                        **Requires TxIndex to receive input metadata**

                                                        type GrpcServerConfig

                                                        type GrpcServerConfig struct {
                                                        	Server     *grpc.Server
                                                        	HTTPServer *http.Server
                                                        
                                                        	TimeSource  blockchain.MedianTimeSource
                                                        	Chain       *blockchain.BlockChain
                                                        	ChainParams *chaincfg.Params
                                                        	DB          database.DB
                                                        	TxMemPool   *mempool.TxPool
                                                        	NetMgr      NetManager
                                                        
                                                        	TxIndex   *indexers.TxIndex
                                                        	AddrIndex *indexers.AddrIndex
                                                        	CfIndex   *indexers.CfIndex
                                                        }

                                                          GrpcServerConfig hols the various objects needed by the GrpcServer to perform its functions.

                                                          type NetManager

                                                          type NetManager interface {
                                                          	// AddRebroadcastInventory adds 'iv' to the list of inventories to be
                                                          	// rebroadcasted at random intervals until they show up in a block.
                                                          	AddRebroadcastInventory(iv *wire.InvVect, data interface{})
                                                          
                                                          	// AnnounceNewTransactions generates and relays inventory vectors and notifies
                                                          	// both websocket and getblocktemplate long poll clients of the passed
                                                          	// transactions.  This function should be called whenever new transactions
                                                          	// are added to the mempool.
                                                          	AnnounceNewTransactions(txns []*mempool.TxDesc)
                                                          }

                                                            NetManager is an interface which provides functions for handling new transactions. This is used by the SubmitTransaction RPC to notify the rest of the system a new transaction needs to be handled.

                                                            Directories

                                                            Path Synopsis