client

Documentation

Overview

Package client defines interfaces and types that facilitate interactions with blockchain functionalities, both transactional and observational. It is built to provide an abstraction layer for sending, receiving, and querying blockchain data, thereby offering a standardized way of integrating with various blockchain platforms.

The client package leverages external libraries like cosmos-sdk and cometbft, but there is a preference to minimize direct dependencies on these external libraries, when defining interfaces, aiming for a cleaner decoupling. It seeks to provide a flexible and comprehensive interface layer, adaptable to different blockchain configurations and requirements.

Index

• func NewTestApplicationServiceConfig(prefix string, count int) []*sharedtypes.ApplicationServiceConfig
• type AccountQueryClient
• type ApplicationQueryClient
• type Block
• type BlockClient
• type BlockClientOption
• type BlockQueryClient
• type BlockReplayObservable
• type Connection
• type DelegationClient
• type DelegationClientOption
• type Dialer
• type EventsBytesObservable
• type EventsObservable
• type EventsQueryClient
• type EventsQueryClientOption
• type EventsReplayClient
• type EventsReplayClientOption
• type MsgCreateClaim
• type MsgSubmitProof
• type ProofParams
• type ProofQueryClient
• type Redelegation
• type RedelegationReplayObservable
• type ServiceQueryClient
• type SessionQueryClient
• type SharedQueryClient
• type SupplierClient
• type SupplierClientOption
• type SupplierQueryClient
• type TokenomicsQueryClient
• type TokenomicsRelayMiningDifficulty
• type TxClient
• type TxClientOption
• type TxContext

Functions

func NewTestApplicationServiceConfig

func NewTestApplicationServiceConfig(prefix string, count int) []*sharedtypes.ApplicationServiceConfig

NewTestApplicationServiceConfig returns a slice of application service configs for testing.

Types

type AccountQueryClient

type AccountQueryClient interface {
	// GetAccount queries the chain for the details of the account provided
	GetAccount(ctx context.Context, address string) (cosmostypes.AccountI, error)

	// GetPubKeyFromAddress returns the public key of the given address.
	GetPubKeyFromAddress(ctx context.Context, address string) (cryptotypes.PubKey, error)
}

AccountQueryClient defines an interface that enables the querying of the on-chain account information

type ApplicationQueryClient

type ApplicationQueryClient interface {
	// GetApplication queries the chain for the details of the application provided
	GetApplication(ctx context.Context, appAddress string) (apptypes.Application, error)

	// GetAllApplications queries all on-chain applications
	GetAllApplications(ctx context.Context) ([]apptypes.Application, error)
}

ApplicationQueryClient defines an interface that enables the querying of the on-chain application information

type Block

type Block interface {
	Height() int64
	Hash() []byte
	Txs() []comettypes.Tx
}

Block is an interface which abstracts the details of a block to its minimal necessary components.

type BlockClient

type BlockClient interface {
	// CommittedBlocksSequence returns a BlockObservable that emits the
	// latest blocks that have been committed to the chain.
	CommittedBlocksSequence(context.Context) BlockReplayObservable
	// LastBlock returns the latest block that has been committed on-chain.
	LastBlock(context.Context) Block
	// Close unsubscribes all observers of the committed block sequence
	// observable and closes the events query client.
	Close()
}

BlockClient is an interface that wraps the EventsReplayClient interface specific for the EventsReplayClient[Block] implementation

type BlockClientOption

type BlockClientOption func(BlockClient)

BlockClientOption defines a function type that modifies the BlockClient.

type BlockQueryClient

type BlockQueryClient interface {
	Block(ctx context.Context, height *int64) (*cometrpctypes.ResultBlock, error)
}

BlockQueryClient defines an interface that enables the querying of on-chain block information for a given height. If height is nil, the latest block is returned.

type BlockReplayObservable

type BlockReplayObservable EventsObservable[Block]

BlockReplayObservable is a defined type which is a replay observable of type Block. NB: This cannot be an alias due to gomock's lack of support for generic types.

type Connection

type Connection interface {
	// Receive blocks until a message is received or an error occurs.
	Receive() (msg []byte, err error)
	// Send sends a message and may return a synchronous error.
	Send(msg []byte) error
	// Close closes the connection.
	Close() error
}

Connection is a transport agnostic, bi-directional, message-passing interface.

type DelegationClient

type DelegationClient interface {
	// RedelegationsSequence returns a Observable of Redelegations that
	// emits the latest redelegation events that have occurred on chain.
	RedelegationsSequence(context.Context) RedelegationReplayObservable
	// LastNRedelegations returns the latest N redelegation events that have
	// occurred on chain.
	LastNRedelegations(context.Context, int) []Redelegation
	// Close unsubscribes all observers of the committed block sequence
	// observable and closes the events query client.
	Close()
}

DelegationClient is an interface that wraps the EventsReplayClient interface specific for the EventsReplayClient[Redelegation] implementation

type DelegationClientOption

type DelegationClientOption func(DelegationClient)

DelegationClientOption defines a function type that modifies the DelegationClient.

type Dialer

type Dialer interface {
	// DialContext constructs a connection to the given URL and returns it or
	// potentially a synchronous error.
	DialContext(ctx context.Context, urlStr string) (Connection, error)
}

Dialer encapsulates the construction of connections.

type EventsBytesObservable

type EventsBytesObservable observable.Observable[either.Bytes]

EventsBytesObservable is an observable which is notified with an either value which contains either an error or the event message bytes.

TODO_HACK: The purpose of this type is to work around gomock's lack of support for generic types. For the same reason, this type cannot be an alias (i.e. EventsBytesObservable = observable.Observable[either.Bytes]).

type EventsObservable

type EventsObservable[T any] observable.ReplayObservable[T]

EventsObservable is a replay observable for events of some type T. NB: This cannot be an alias due to gomock's lack of support for generic types.

type EventsQueryClient

type EventsQueryClient interface {
	// EventsBytes returns an observable which is notified about chain event messages
	// matching the given query. It receives an either value which contains either an
	// error or the event message bytes.
	EventsBytes(
		ctx context.Context,
		query string,
	) (EventsBytesObservable, error)
	// Close unsubscribes all observers of each active query's events bytes
	// observable and closes the connection.
	Close()
}

EventsQueryClient is used to subscribe to chain event messages matching the given query,

TODO_CONSIDERATION: the cosmos-sdk CLI code seems to use a cometbft RPC client which includes a `#Subscribe()` method for a similar purpose. Perhaps we could replace our custom implementation with one which wraps that. (see: https://github.com/cometbft/cometbft/blob/main/rpc/client/http/http.go#L110) (see: https://github.com/cosmos/cosmos-sdk/blob/main/client/rpc/tx.go#L114)

NOTE: a branch which attempts this is available at: https://github.com/pokt-network/poktroll/pull/74

type EventsQueryClientOption

type EventsQueryClientOption func(EventsQueryClient)

EventsQueryClientOption defines a function type that modifies the EventsQueryClient.

type EventsReplayClient

type EventsReplayClient[T any] interface {
	// EventsSequence returns an observable which emits new events.
	EventsSequence(context.Context) observable.ReplayObservable[T]
	// LastNEvents returns the latest N events that has been received.
	LastNEvents(ctx context.Context, n int) []T
	// Close unsubscribes all observers of the events sequence observable
	// and closes the events query client.
	Close()
}

EventsReplayClient is an interface which provides notifications about newly received events as well as direct access to the latest event via some blockchain API.

type EventsReplayClientOption

type EventsReplayClientOption[T any] func(EventsReplayClient[T])

EventsReplayClientOption defines a function type that modifies the ReplayClient.

type MsgCreateClaim

type MsgCreateClaim interface {
	cosmostypes.Msg
	GetRootHash() []byte
	GetSessionHeader() *sessiontypes.SessionHeader
	GetSupplierOperatorAddress() string
}

MsgCreateClaim is an interface satisfying proof.MsgCreateClaim concrete type used by the SupplierClient interface to avoid cyclic dependencies.

type MsgSubmitProof

type MsgSubmitProof interface {
	cosmostypes.Msg
	GetProof() []byte
	GetSessionHeader() *sessiontypes.SessionHeader
	GetSupplierOperatorAddress() string
}

MsgSubmitProof is an interface satisfying proof.MsgSubmitProof concrete type used by the SupplierClient interface to avoid cyclic dependencies.

type ProofParams

type ProofParams interface {
	GetProofRequestProbability() float32
	GetProofRequirementThreshold() uint64
	GetProofMissingPenalty() *cosmostypes.Coin
}

ProofParams is a go interface type which corresponds to the poktroll.proof.Params protobuf message. Since the generated go types don't include interface types, this is necessary to prevent dependency cycles.

type ProofQueryClient

type ProofQueryClient interface {
	// GetParams queries the chain for the current shared module parameters.
	GetParams(ctx context.Context) (ProofParams, error)
}

ProofQueryClient defines an interface that enables the querying of the on-chain proof module params.

type Redelegation

type Redelegation interface {
	GetAppAddress() string
	GetGatewayAddress() string
}

Redelegation is an interface which wraps the EventRedelegation event emitted by the application module. See: proto/poktroll/application/types/event.proto#EventRedelegation

type RedelegationReplayObservable

type RedelegationReplayObservable EventsObservable[Redelegation]

RedelegationReplayObservable is a defined type which is a replay observable of type Redelegation. NB: This cannot be an alias due to gomock's lack of support for generic types.

type ServiceQueryClient

type ServiceQueryClient interface {
	// GetService queries the chain for the details of the service provided
	GetService(ctx context.Context, serviceId string) (sharedtypes.Service, error)
}

ServiceQueryClient defines an interface that enables the querying of the on-chain service information

type SessionQueryClient

type SessionQueryClient interface {
	// GetSession queries the chain for the details of the session provided
	GetSession(
		ctx context.Context,
		appAddress string,
		serviceId string,
		blockHeight int64,
	) (*sessiontypes.Session, error)
}

SessionQueryClient defines an interface that enables the querying of the on-chain session information

type SharedQueryClient

type SharedQueryClient interface {
	// GetParams queries the chain for the current shared module parameters.
	GetParams(ctx context.Context) (*sharedtypes.Params, error)
	// GetSessionGracePeriodEndHeight returns the block height at which the grace period
	// for the session that includes queryHeight elapses.
	// The grace period is the number of blocks after the session ends during which relays
	// SHOULD be included in the session which most recently ended.
	GetSessionGracePeriodEndHeight(ctx context.Context, queryHeight int64) (int64, error)
	// GetClaimWindowOpenHeight returns the block height at which the claim window of
	// the session that includes queryHeight opens.
	GetClaimWindowOpenHeight(ctx context.Context, queryHeight int64) (int64, error)
	// GetEarliestSupplierClaimCommitHeight returns the earliest block height at which a claim
	// for the session that includes queryHeight can be committed for a given supplier.
	GetEarliestSupplierClaimCommitHeight(ctx context.Context, queryHeight int64, supplierOperatorAddr string) (int64, error)
	// GetProofWindowOpenHeight returns the block height at which the proof window of
	// the session that includes queryHeight opens.
	GetProofWindowOpenHeight(ctx context.Context, queryHeight int64) (int64, error)
	// GetEarliestSupplierProofCommitHeight returns the earliest block height at which a proof
	// for the session that includes queryHeight can be committed for a given supplier.
	GetEarliestSupplierProofCommitHeight(ctx context.Context, queryHeight int64, supplierOperatorAddr string) (int64, error)
}

SharedQueryClient defines an interface that enables the querying of the on-chain shared module params.

type SupplierClient

type SupplierClient interface {
	// CreateClaims sends claim messages which creates an on-chain commitment by
	// calling supplier to the given smt.SparseMerkleSumTree root hash of the given
	// session's mined relays.
	CreateClaims(
		ctx context.Context,
		claimMsgs ...MsgCreateClaim,
	) error
	// SubmitProof sends proof messages which contain the smt.SparseMerkleClosestProof,
	// corresponding to some previously created claim for the same session.
	// The proof is validated on-chain as part of the pocket protocol.
	// TODO_MAINNET(#427): Use SparseCompactClosestProof here to reduce
	// the amount of data stored on-chain.
	SubmitProofs(
		ctx context.Context,
		sessionProofs ...MsgSubmitProof,
	) error
	// Address returns the operator address of the SupplierClient that will be submitting proofs & claims.
	OperatorAddress() *cosmostypes.AccAddress
}

SupplierClient is an interface for sufficient for a supplier operator to be able to construct blockchain transactions from pocket protocol-specific messages related to its role.

type SupplierClientOption

type SupplierClientOption func(SupplierClient)

SupplierClientOption defines a function type that modifies the SupplierClient.

type SupplierQueryClient

type SupplierQueryClient interface {
	// GetSupplier queries the chain for the details of the supplier provided
	GetSupplier(ctx context.Context, supplierOperatorAddress string) (sharedtypes.Supplier, error)
}

SupplierQueryClient defines an interface that enables the querying of the on-chain supplier information

type TokenomicsQueryClient

type TokenomicsQueryClient interface {
	GetServiceRelayDifficultyTargetHash(ctx context.Context, serviceId string) (TokenomicsRelayMiningDifficulty, error)
}

type TokenomicsRelayMiningDifficulty

type TokenomicsRelayMiningDifficulty interface {
	GetTargetHash() []byte
}

TokenomicsRelayMiningDifficulty is a go interface type which corresponding to the poktroll.tokenomics.RelayMiningDifficulty protobuf message. This is necessary to prevent dependency cycles.

type TxClient

type TxClient interface {
	SignAndBroadcast(
		ctx context.Context,
		msgs ...cosmostypes.Msg,
	) either.AsyncError
}

TxClient provides a synchronous interface initiating and waiting for transactions derived from cosmos-sdk messages, in a cosmos-sdk based blockchain network.

type TxClientOption

type TxClientOption func(TxClient)

TxClientOption defines a function type that modifies the TxClient.

type TxContext

type TxContext interface {
	// GetKeyring returns the associated key management mechanism for the transaction context.
	GetKeyring() cosmoskeyring.Keyring

	// NewTxBuilder creates and returns a new transaction builder instance.
	NewTxBuilder() cosmosclient.TxBuilder

	// SignTx signs a transaction using the specified key name. It can operate in offline mode,
	// and can overwrite any existing signatures based on the provided flags.
	SignTx(
		keyName string,
		txBuilder cosmosclient.TxBuilder,
		offline, overwriteSig bool,
	) error

	// EncodeTx takes a transaction builder and encodes it, returning its byte representation.
	EncodeTx(txBuilder cosmosclient.TxBuilder) ([]byte, error)

	// BroadcastTx broadcasts the given transaction to the network.
	BroadcastTx(txBytes []byte) (*cosmostypes.TxResponse, error)

	// QueryTx retrieves a transaction status based on its hash and optionally provides
	// proof of the transaction.
	QueryTx(
		ctx context.Context,
		txHash []byte,
		prove bool,
	) (*cometrpctypes.ResultTx, error)

	// GetClientCtx returns the cosmos-sdk client context associated with the transaction context.
	GetClientCtx() cosmosclient.Context
}

TxContext provides an interface which consolidates the operational dependencies required to facilitate the sender side of the transaction lifecycle: build, sign, encode, broadcast, and query (optional).

TODO_IMPROVE: Avoid depending on cosmos-sdk structs or interfaces; add Pocket interface types to substitute:

• ResultTx
• TxResponse
• Keyring
• TxBuilder