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 }