github.com/badrootd/nibiru-cometbft@v0.37.5-0.20240307173500-2a75559eee9b/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/nibiru-cometbft/libs/bytes"
    27  	"github.com/badrootd/nibiru-cometbft/libs/service"
    28  	ctypes "github.com/badrootd/nibiru-cometbft/rpc/core/types"
    29  	"github.com/badrootd/nibiru-cometbft/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  	BlockByHash(ctx context.Context, hash []byte) (*ctypes.ResultBlock, error)
    69  	BlockResults(ctx context.Context, height *int64) (*ctypes.ResultBlockResults, error)
    70  	Header(ctx context.Context, height *int64) (*ctypes.ResultHeader, error)
    71  	HeaderByHash(ctx context.Context, hash bytes.HexBytes) (*ctypes.ResultHeader, error)
    72  	Commit(ctx context.Context, height *int64) (*ctypes.ResultCommit, error)
    73  	Validators(ctx context.Context, height *int64, page, perPage *int) (*ctypes.ResultValidators, error)
    74  	Tx(ctx context.Context, hash []byte, prove bool) (*ctypes.ResultTx, error)
    75  
    76  	// TxSearch defines a method to search for a paginated set of transactions by
    77  	// DeliverTx event search criteria.
    78  	TxSearch(
    79  		ctx context.Context,
    80  		query string,
    81  		prove bool,
    82  		page, perPage *int,
    83  		orderBy string,
    84  	) (*ctypes.ResultTxSearch, error)
    85  
    86  	// BlockSearch defines a method to search for a paginated set of blocks by
    87  	// BeginBlock and EndBlock event search criteria.
    88  	BlockSearch(
    89  		ctx context.Context,
    90  		query string,
    91  		page, perPage *int,
    92  		orderBy string,
    93  	) (*ctypes.ResultBlockSearch, error)
    94  }
    95  
    96  // HistoryClient provides access to data from genesis to now in large chunks.
    97  type HistoryClient interface {
    98  	Genesis(context.Context) (*ctypes.ResultGenesis, error)
    99  	GenesisChunked(context.Context, uint) (*ctypes.ResultGenesisChunk, error)
   100  	BlockchainInfo(ctx context.Context, minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error)
   101  }
   102  
   103  // StatusClient provides access to general chain info.
   104  type StatusClient interface {
   105  	Status(context.Context) (*ctypes.ResultStatus, error)
   106  }
   107  
   108  // NetworkClient is general info about the network state. May not be needed
   109  // usually.
   110  type NetworkClient interface {
   111  	NetInfo(context.Context) (*ctypes.ResultNetInfo, error)
   112  	DumpConsensusState(context.Context) (*ctypes.ResultDumpConsensusState, error)
   113  	ConsensusState(context.Context) (*ctypes.ResultConsensusState, error)
   114  	ConsensusParams(ctx context.Context, height *int64) (*ctypes.ResultConsensusParams, error)
   115  	Health(context.Context) (*ctypes.ResultHealth, error)
   116  }
   117  
   118  // EventsClient is reactive, you can subscribe to any message, given the proper
   119  // string. see cometbft/types/events.go
   120  type EventsClient interface {
   121  	// Subscribe subscribes given subscriber to query. Returns a channel with
   122  	// cap=1 onto which events are published. An error is returned if it fails to
   123  	// subscribe. outCapacity can be used optionally to set capacity for the
   124  	// channel. Channel is never closed to prevent accidental reads.
   125  	//
   126  	// ctx cannot be used to unsubscribe. To unsubscribe, use either Unsubscribe
   127  	// or UnsubscribeAll.
   128  	Subscribe(ctx context.Context, subscriber, query string, outCapacity ...int) (out <-chan ctypes.ResultEvent, err error)
   129  	// Unsubscribe unsubscribes given subscriber from query.
   130  	Unsubscribe(ctx context.Context, subscriber, query string) error
   131  	// UnsubscribeAll unsubscribes given subscriber from all the queries.
   132  	UnsubscribeAll(ctx context.Context, subscriber string) error
   133  }
   134  
   135  // MempoolClient shows us data about current mempool state.
   136  type MempoolClient interface {
   137  	UnconfirmedTxs(ctx context.Context, limit *int) (*ctypes.ResultUnconfirmedTxs, error)
   138  	NumUnconfirmedTxs(context.Context) (*ctypes.ResultUnconfirmedTxs, error)
   139  	CheckTx(context.Context, types.Tx) (*ctypes.ResultCheckTx, error)
   140  }
   141  
   142  // EvidenceClient is used for submitting an evidence of the malicious
   143  // behavior.
   144  type EvidenceClient interface {
   145  	BroadcastEvidence(context.Context, types.Evidence) (*ctypes.ResultBroadcastEvidence, error)
   146  }
   147  
   148  // RemoteClient is a Client, which can also return the remote network address.
   149  type RemoteClient interface {
   150  	Client
   151  
   152  	// Remote returns the remote network address in a string form.
   153  	Remote() string
   154  }