bchrpc

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Jan 2, 2025 License: ISC Imports: 32 Imported by: 0

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.

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) CheckSlpTransaction 

func (s *GrpcServer) CheckSlpTransaction(ctx context.Context, req *pb.CheckSlpTransactionRequest) (*pb.CheckSlpTransactionResponse, error)

CheckSlpTransaction checks a supposed slp transaction for slp validity. The method returns the marshalled response including a slp validity boolean and a reason for invalid validity.

Using the slp specification as a basis for validity judgement can lead to confusion for new users and result in accidental token burns. use_spec_validity_judgement will cause the response's is_valid property to be returned according to the slp specification. Therefore, use_spec_validity_judgement is false by default in order to avoid accidental token burns. When use_spec_validity_judgement is false we return invalid in any case which would result in a burned token, unless the burn is explicitly included as an item in required_slp_burns property.

When use_spec_validity_judgement is true, there are three cases where the is_valid response property will be returned as valid, instead of invalid, as per the slp specification.

  1. inputs > outputs
  2. missing transaction outputs
  3. burned inputs from other tokens

required_slp_burns is not used when use_spec_validity_judgement is set to true.

func (*GrpcServer) GetAddressTransactions 

func (s *GrpcServer) GetAddressTransactions(ctx context.Context, req *pb.GetAddressTransactionsRequest) (*pb.GetAddressTransactionsResponse, error)

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

**Requires AddressIndex**

func (*GrpcServer) GetAddressUnspentOutputs 

func (s *GrpcServer) GetAddressUnspentOutputs(ctx context.Context, req *pb.GetAddressUnspentOutputsRequest) (*pb.GetAddressUnspentOutputsResponse, error)

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 

func (s *GrpcServer) GetBlockFilter(ctx context.Context, req *pb.GetBlockFilterRequest) (*pb.GetBlockFilterResponse, error)

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

**Requires CfIndex**

func (*GrpcServer) GetBlockInfo 

func (s *GrpcServer) GetBlockInfo(ctx context.Context, req *pb.GetBlockInfoRequest) (*pb.GetBlockInfoResponse, error)

GetBlockInfo returns metadata and info for a specified block.

func (*GrpcServer) GetBlockchainInfo 

func (s *GrpcServer) GetBlockchainInfo(ctx context.Context, req *pb.GetBlockchainInfoRequest) (*pb.GetBlockchainInfoResponse, error)

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

func (*GrpcServer) GetHeaders 

func (s *GrpcServer) GetHeaders(ctx context.Context, req *pb.GetHeadersRequest) (*pb.GetHeadersResponse, error)

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 

func (s *GrpcServer) GetMempool(ctx context.Context, req *pb.GetMempoolRequest) (*pb.GetMempoolResponse, error)

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 

func (s *GrpcServer) GetMempoolInfo(ctx context.Context, req *pb.GetMempoolInfoRequest) (*pb.GetMempoolInfoResponse, error)

GetMempoolInfo returns the state of the current mempool.

func (*GrpcServer) GetMerkleProof 

func (s *GrpcServer) GetMerkleProof(ctx context.Context, req *pb.GetMerkleProofRequest) (*pb.GetMerkleProofResponse, error)

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

**Requires TxIndex***

func (*GrpcServer) GetRawAddressTransactions 

func (s *GrpcServer) GetRawAddressTransactions(ctx context.Context, req *pb.GetRawAddressTransactionsRequest) (*pb.GetRawAddressTransactionsResponse, error)

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

**Requires AddressIndex**

func (*GrpcServer) GetRawBlock 

func (s *GrpcServer) GetRawBlock(ctx context.Context, req *pb.GetRawBlockRequest) (*pb.GetRawBlockResponse, error)

GetRawBlock returns a block in a serialized format.

func (*GrpcServer) GetRawTransaction 

func (s *GrpcServer) GetRawTransaction(ctx context.Context, req *pb.GetRawTransactionRequest) (*pb.GetRawTransactionResponse, error)

GetRawTransaction returns a serialized transaction given a transaction hash.

**Requires TxIndex**

func (*GrpcServer) GetSlpGraphSearch 

func (s *GrpcServer) GetSlpGraphSearch(ctx context.Context, req *pb.GetSlpGraphSearchRequest) (*pb.GetSlpGraphSearchResponse, error)

GetSlpGraphSearch returns all transactions required for a client to validate locally

func (*GrpcServer) GetSlpParsedScript 

func (s *GrpcServer) GetSlpParsedScript(ctx context.Context, req *pb.GetSlpParsedScriptRequest) (*pb.GetSlpParsedScriptResponse, error)

GetSlpParsedScript returns a parsed object from a provided serialized slp OP_RETURN message

func (*GrpcServer) GetSlpTokenMetadata 

func (s *GrpcServer) GetSlpTokenMetadata(ctx context.Context, req *pb.GetSlpTokenMetadataRequest) (*pb.GetSlpTokenMetadataResponse, error)

GetSlpTokenMetadata returns metadata associated with a Token ID

func (*GrpcServer) GetSlpTrustedValidation 

func (s *GrpcServer) GetSlpTrustedValidation(ctx context.Context, req *pb.GetSlpTrustedValidationRequest) (*pb.GetSlpTrustedValidationResponse, error)

GetSlpTrustedValidation returns slp validity information about a specific token output

func (*GrpcServer) GetTransaction 

func (s *GrpcServer) GetTransaction(ctx context.Context, req *pb.GetTransactionRequest) (*pb.GetTransactionResponse, error)

GetTransaction returns a transaction given its hash.

**Requires TxIndex** **Requires SlpIndex for all token metadata

func (*GrpcServer) GetUnspentOutput 

func (s *GrpcServer) GetUnspentOutput(ctx context.Context, req *pb.GetUnspentOutputRequest) (*pb.GetUnspentOutputResponse, error)

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 

func (s *GrpcServer) SubmitTransaction(ctx context.Context, req *pb.SubmitTransactionRequest) (*pb.SubmitTransactionResponse, error)

SubmitTransaction submits a transaction to all connected peers.

If slp index is enabled it will not allow slp burns unless the burned token is included in req.RequiredSlpBurns, or if req.SkipSlpValidityCheck is set to true

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 

func (s *GrpcServer) SubscribeTransactions(req *pb.SubscribeTransactionsRequest, stream pb.Bchrpc_SubscribeTransactionsServer) error

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
	SlpIndex  *indexers.SlpIndex
}

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.

Source Files

View all Source files

Directories

Path Synopsis
Package pb is a reverse proxy.
 Package pb is a reverse proxy.
middlewares

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.