github.com/badrootd/celestia-core@v0.0.0-20240305091328-aa4207a4b25d/rpc/client/interface.go (about)

     1  package client
     2  
     3  /*
     4  The client package provides a general purpose interface (Client) for connecting
     5  to a CometBFT node, as well as higher-level functionality.
     6  
     7  The main implementation for production code is client.HTTP, which
     8  connects via http to the jsonrpc interface of the CometBFT node.
     9  
    10  For connecting to a node running in the same process (eg. when
    11  compiling the abci app in the same process), you can use the client.Local
    12  implementation.
    13  
    14  For mocking out server responses during testing to see behavior for
    15  arbitrary return values, use the mock package.
    16  
    17  In addition to the Client interface, which should be used externally
    18  for maximum flexibility and testability, and two implementations,
    19  this package also provides helper functions that work on any Client
    20  implementation.
    21  */
    22  
    23  import (
    24  	"context"
    25  
    26  	"github.com/badrootd/celestia-core/libs/bytes"
    27  	"github.com/badrootd/celestia-core/libs/service"
    28  	ctypes "github.com/badrootd/celestia-core/rpc/core/types"
    29  	"github.com/badrootd/celestia-core/types"
    30  )
    31  
    32  // Client wraps most important rpc calls a client would make if you want to
    33  // listen for events, test if it also implements events.EventSwitch.
    34  type Client interface {
    35  	service.Service
    36  	ABCIClient
    37  	EventsClient
    38  	HistoryClient
    39  	NetworkClient
    40  	SignClient
    41  	StatusClient
    42  	EvidenceClient
    43  	MempoolClient
    44  }
    45  
    46  // ABCIClient groups together the functionality that principally affects the
    47  // ABCI app.
    48  //
    49  // In many cases this will be all we want, so we can accept an interface which
    50  // is easier to mock.
    51  type ABCIClient interface {
    52  	// Reading from abci app
    53  	ABCIInfo(context.Context) (*ctypes.ResultABCIInfo, error)
    54  	ABCIQuery(ctx context.Context, path string, data bytes.HexBytes) (*ctypes.ResultABCIQuery, error)
    55  	ABCIQueryWithOptions(ctx context.Context, path string, data bytes.HexBytes,
    56  		opts ABCIQueryOptions) (*ctypes.ResultABCIQuery, error)
    57  
    58  	// Writing to abci app
    59  	BroadcastTxCommit(context.Context, types.Tx) (*ctypes.ResultBroadcastTxCommit, error)
    60  	BroadcastTxAsync(context.Context, types.Tx) (*ctypes.ResultBroadcastTx, error)
    61  	BroadcastTxSync(context.Context, types.Tx) (*ctypes.ResultBroadcastTx, error)
    62  }
    63  
    64  // SignClient groups together the functionality needed to get valid signatures
    65  // and prove anything about the chain.
    66  type SignClient interface {
    67  	Block(ctx context.Context, height *int64) (*ctypes.ResultBlock, error)
    68  	SignedBlock(ctx context.Context, height *int64) (*ctypes.ResultSignedBlock, error)
    69  	BlockByHash(ctx context.Context, hash []byte) (*ctypes.ResultBlock, error)
    70  	BlockResults(ctx context.Context, height *int64) (*ctypes.ResultBlockResults, error)
    71  	Header(ctx context.Context, height *int64) (*ctypes.ResultHeader, error)
    72  	HeaderByHash(ctx context.Context, hash bytes.HexBytes) (*ctypes.ResultHeader, error)
    73  	Commit(ctx context.Context, height *int64) (*ctypes.ResultCommit, error)
    74  
    75  	DataCommitment(ctx context.Context, start, end uint64) (*ctypes.ResultDataCommitment, error)
    76  	DataRootInclusionProof(
    77  		ctx context.Context,
    78  		height uint64,
    79  		start,
    80  		end uint64,
    81  	) (*ctypes.ResultDataRootInclusionProof, error)
    82  
    83  	Validators(ctx context.Context, height *int64, page, perPage *int) (*ctypes.ResultValidators, error)
    84  	Tx(ctx context.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)
    85  
    86  	ProveShares(_ context.Context, height uint64, startShare uint64, endShare uint64) (types.ShareProof, error)
    87  
    88  	// TxSearch defines a method to search for a paginated set of transactions by
    89  	// DeliverTx event search criteria.
    90  	TxSearch(
    91  		ctx context.Context,
    92  		query string,
    93  		prove bool,
    94  		page, perPage *int,
    95  		orderBy string,
    96  	) (*ctypes.ResultTxSearch, error)
    97  
    98  	// BlockSearch defines a method to search for a paginated set of blocks by
    99  	// BeginBlock and EndBlock event search criteria.
   100  	BlockSearch(
   101  		ctx context.Context,
   102  		query string,
   103  		page, perPage *int,
   104  		orderBy string,
   105  	) (*ctypes.ResultBlockSearch, error)
   106  }
   107  
   108  // HistoryClient provides access to data from genesis to now in large chunks.
   109  type HistoryClient interface {
   110  	Genesis(context.Context) (*ctypes.ResultGenesis, error)
   111  	GenesisChunked(context.Context, uint) (*ctypes.ResultGenesisChunk, error)
   112  	BlockchainInfo(ctx context.Context, minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error)
   113  }
   114  
   115  // StatusClient provides access to general chain info.
   116  type StatusClient interface {
   117  	Status(context.Context) (*ctypes.ResultStatus, error)
   118  }
   119  
   120  // NetworkClient is general info about the network state. May not be needed
   121  // usually.
   122  type NetworkClient interface {
   123  	NetInfo(context.Context) (*ctypes.ResultNetInfo, error)
   124  	DumpConsensusState(context.Context) (*ctypes.ResultDumpConsensusState, error)
   125  	ConsensusState(context.Context) (*ctypes.ResultConsensusState, error)
   126  	ConsensusParams(ctx context.Context, height *int64) (*ctypes.ResultConsensusParams, error)
   127  	Health(context.Context) (*ctypes.ResultHealth, error)
   128  }
   129  
   130  // EventsClient is reactive, you can subscribe to any message, given the proper
   131  // string. see cometbft/types/events.go
   132  type EventsClient interface {
   133  	// Subscribe subscribes given subscriber to query. Returns a channel with
   134  	// cap=1 onto which events are published. An error is returned if it fails to
   135  	// subscribe. outCapacity can be used optionally to set capacity for the
   136  	// channel. Channel is never closed to prevent accidental reads.
   137  	//
   138  	// ctx cannot be used to unsubscribe. To unsubscribe, use either Unsubscribe
   139  	// or UnsubscribeAll.
   140  	Subscribe(ctx context.Context, subscriber, query string, outCapacity ...int) (out <-chan ctypes.ResultEvent, err error)
   141  	// Unsubscribe unsubscribes given subscriber from query.
   142  	Unsubscribe(ctx context.Context, subscriber, query string) error
   143  	// UnsubscribeAll unsubscribes given subscriber from all the queries.
   144  	UnsubscribeAll(ctx context.Context, subscriber string) error
   145  }
   146  
   147  // MempoolClient shows us data about current mempool state.
   148  type MempoolClient interface {
   149  	UnconfirmedTxs(ctx context.Context, limit *int) (*ctypes.ResultUnconfirmedTxs, error)
   150  	NumUnconfirmedTxs(context.Context) (*ctypes.ResultUnconfirmedTxs, error)
   151  	CheckTx(context.Context, types.Tx) (*ctypes.ResultCheckTx, error)
   152  }
   153  
   154  // EvidenceClient is used for submitting an evidence of the malicious
   155  // behaviour.
   156  type EvidenceClient interface {
   157  	BroadcastEvidence(context.Context, types.Evidence) (*ctypes.ResultBroadcastEvidence, error)
   158  }
   159  
   160  // RemoteClient is a Client, which can also return the remote network address.
   161  type RemoteClient interface {
   162  	Client
   163  
   164  	// Remote returns the remote network address in a string form.
   165  	Remote() string
   166  }