czzrpc

package
v3.1.7+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 1, 2021 License: ISC Imports: 27 Imported by: 1

README

czzrpc

Build Status ISC License GoDoc

Package czzrpc implements a gRPC server.

Overview

This package provides a gRPC 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, with 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

$ classzz --grpclisten=<your_interface>

License

Package czzrpc is licensed under the copyfree ISC License.

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 czzlog.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 czzrpc.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 outpoints for the given address. Offers offset, limit, and from block options.

**Requires AddressIndex**

func (*GrpcServer) GetBlock

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

GetBlock returns a full block.

func (*GrpcServer) GetBlockFilter

GetBlockFilter returns a block filter.

**Requires CfIndex**

func (*GrpcServer) GetBlockInfo

GetBlockInfo returns info about the given block.

func (*GrpcServer) GetBlockchainInfo

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

func (*GrpcServer) GetHeaders

GetHeaders sends a block locator object to the server and the server responds with 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.

func (*GrpcServer) GetMempoolInfo

GetMempoolInfo returns info about the mempool.

func (*GrpcServer) GetMerkleProof

GetMerkleProof returns a merkle (SPV) proof that the given transaction is 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 full serialized block.

func (*GrpcServer) GetRawTransaction

GetRawTransaction returns a serialized transaction given its hash.

**Requires TxIndex**

func (*GrpcServer) GetTransaction

GetTransaction returns a transaction given its hash.

**Requires TxIndex**

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.Czzrpc_SubscribeBlocksServer) error

SubscribeBlocks subscribes to notifications of new blocks being connected to the blockchain or blocks being disconnected.

func (*GrpcServer) SubscribeTransactionStream

func (s *GrpcServer) SubscribeTransactionStream(stream pb.Czzrpc_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 using bi-directional streaming it cannot be used with grpc-web.

**Requires TxIndex to receive input metadata**

func (*GrpcServer) SubscribeTransactions

SubscribeTransactions 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.

This RPC does not use bi-directional streams and therefore can be used with grpc-web. You will need to close and re-open the stream whenever you want to update the addresses. 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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL