v0.27.2 Latest Latest

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

Go to latest
Published: Oct 18, 2023 License: Apache-2.0 Imports: 41 Imported by: 12



Package cosmosclient provides a standalone client to connect to Cosmos SDK chains.



View Source
const (
	// GasAuto allows to calculate gas automatically when sending transaction.
	GasAuto = "auto"


View Source
var (
	// FaucetTransferEnsureDuration is the duration that BroadcastTx will wait when a faucet transfer
	// is triggered prior to broadcasting but transfer's tx is not committed in the state yet.
	FaucetTransferEnsureDuration = time.Second * 40

	// ErrInvalidBlockHeight is returned when a block height value is not valid.
	ErrInvalidBlockHeight = errors.New("block height must be greater than 0")


This section is empty.


type Client

type Client struct {
	// RPC is Tendermint RPC.
	RPC rpcclient.Client

	// TxFactory is a Cosmos SDK tx factory.
	TxFactory tx.Factory

	// AccountRegistry is the registry to access accounts.
	AccountRegistry cosmosaccount.Registry
	// contains filtered or unexported fields

Client is a client to access your chain by querying and broadcasting transactions.

func New

func New(ctx context.Context, options ...Option) (Client, error)

New creates a new client with given options.

func (Client) Account

func (c Client) Account(nameOrAddress string) (cosmosaccount.Account, error)

Account returns the account with name or address equal to nameOrAddress.

func (Client) Address

func (c Client) Address(accountName string) (string, error)

Address returns the account address from account name.

func (Client) BankBalances added in v0.24.0

func (c Client) BankBalances(ctx context.Context, address string, pagination *query.PageRequest) (sdk.Coins, error)

func (Client) BankSendTx added in v0.24.0

func (c Client) BankSendTx(ctx context.Context, fromAccount cosmosaccount.Account, toAddress string, amount sdk.Coins) (TxService, error)

func (Client) BroadcastTx

func (c Client) BroadcastTx(ctx context.Context, account cosmosaccount.Account, msgs ...sdktypes.Msg) (Response, error)

func (Client) CollectTXs added in v0.25.0

func (c Client) CollectTXs(ctx context.Context, fromHeight int64, tc chan<- []TX) error

CollectTXs collects transactions from multiple consecutive blocks. Transactions from a single block are send to the channel only if all transactions from that block are collected successfully. Blocks are traversed sequentially starting from a height until the latest block height available at the moment this method is called. The channel might contain the transactions collected successfully up until that point when an error is returned.

func (Client) ConsensusInfo

func (c Client) ConsensusInfo(ctx context.Context, height int64) (ConsensusInfo, error)

ConsensusInfo returns the appropriate tendermint consensus state by given height and the validator set for the next height.

func (Client) Context

func (c Client) Context() client.Context

Context returns client context.

func (Client) CreateTx added in v0.24.0

func (c Client) CreateTx(goCtx context.Context, account cosmosaccount.Account, msgs ...sdktypes.Msg) (TxService, error)

func (Client) GetBlockTXs added in v0.25.0

func (c Client) GetBlockTXs(ctx context.Context, height int64) (txs []TX, err error)

GetBlockTXs returns the transactions in a block. The list of transactions can be empty if there are no transactions in the block at the moment this method is called. Tendermint might index a limited number of block so trying to fetch transactions from a block that is not indexed would return an error.

func (Client) LatestBlockHeight added in v0.24.0

func (c Client) LatestBlockHeight(ctx context.Context) (int64, error)

LatestBlockHeight returns the latest block height of the app.

func (Client) SetConfigAddressPrefix added in v0.24.0

func (c Client) SetConfigAddressPrefix()

SetConfigAddressPrefix sets the account prefix in the SDK global config.

func (Client) Status

func (c Client) Status(ctx context.Context) (*ctypes.ResultStatus, error)

Status returns the node status.

func (Client) WaitForBlockHeight added in v0.24.0

func (c Client) WaitForBlockHeight(ctx context.Context, h int64) error

WaitForBlockHeight waits until block height h is committed, or returns an error if ctx is canceled.

func (Client) WaitForNBlocks added in v0.24.0

func (c Client) WaitForNBlocks(ctx context.Context, n int64) error

WaitForNBlocks reads the current block height and then waits for another n blocks to be committed, or returns an error if ctx is canceled.

func (Client) WaitForNextBlock added in v0.24.0

func (c Client) WaitForNextBlock(ctx context.Context) error

WaitForNextBlock waits until next block is committed. It reads the current block height and then waits for another block to be committed, or returns an error if ctx is canceled.

func (Client) WaitForTx added in v0.25.0

func (c Client) WaitForTx(ctx context.Context, hash string) (*ctypes.ResultTx, error)

WaitForTx requests the tx from hash, if not found, waits for next block and tries again. Returns an error if ctx is canceled.

type ConsensusInfo

type ConsensusInfo struct {
	Timestamp          string                `json:"Timestamp"`
	Root               string                `json:"Root"`
	NextValidatorsHash string                `json:"NextValidatorsHash"`
	ValidatorSet       *tmproto.ValidatorSet `json:"ValidatorSet"`

ConsensusInfo is the validator consensus info.

type FaucetClient added in v0.24.0

type FaucetClient interface {
	Transfer(context.Context, cosmosfaucet.TransferRequest) (cosmosfaucet.TransferResponse, error)

FaucetClient allows to mock the cosmosfaucet.Client.

type Gasometer added in v0.24.0

type Gasometer interface {
	CalculateGas(clientCtx gogogrpc.ClientConn, txf tx.Factory, msgs ...sdktypes.Msg) (*txtypes.SimulateResponse, uint64, error)

Gasometer allows to mock the tx.CalculateGas func.

type Option

type Option func(*Client)

Option configures your client.

func WithAccountRetriever added in v0.24.0

func WithAccountRetriever(accountRetriever client.AccountRetriever) Option

WithAccountRetriever sets the account retriever Already set by default.

func WithAddressPrefix

func WithAddressPrefix(prefix string) Option

func WithBankQueryClient added in v0.24.0

func WithBankQueryClient(bankQueryClient banktypes.QueryClient) Option

WithBankQueryClient sets the bank query client. Already set by default.

func WithFaucetClient added in v0.24.0

func WithFaucetClient(faucetClient FaucetClient) Option

WithFaucetClient sets the faucet client. Already set by default.

func WithFees added in v0.24.0

func WithFees(fees string) Option

WithFees sets the fees (e.g. 10uatom).

func WithGas added in v0.24.0

func WithGas(gas string) Option

WithGas sets an explicit gas-limit on transactions. Set to "auto" to calculate automatically.

func WithGasAdjustment added in v0.27.0

func WithGasAdjustment(gasAdjustment float64) Option

WithGasAdjustment sets the gas adjustment.

func WithGasPrices added in v0.24.0

func WithGasPrices(gasPrices string) Option

WithGasPrices sets the price per gas (e.g. 0.1uatom).

func WithGasometer added in v0.24.0

func WithGasometer(gasometer Gasometer) Option

WithGasometer sets the gasometer. Already set by default.

func WithGenerateOnly added in v0.24.0

func WithGenerateOnly(generateOnly bool) Option

WithGenerateOnly tells if txs will be generated only.

func WithHome

func WithHome(path string) Option

WithHome sets the data dir of your chain. This option is used to access your chain's file based keyring which is only needed when you deal with creating and signing transactions. when it is not provided, your data dir will be assumed as `$HOME/.your-chain-id`.

func WithKeyringBackend

func WithKeyringBackend(backend cosmosaccount.KeyringBackend) Option

WithKeyringBackend sets your keyring backend. By default, it is `test`.

func WithKeyringDir added in v0.24.0

func WithKeyringDir(keyringDir string) Option

WithKeyringDir sets the directory of the keyring. By default, it uses cosmosaccount.KeyringHome.

func WithKeyringServiceName

func WithKeyringServiceName(name string) Option

WithKeyringServiceName used as the keyring name when you are using OS keyring backend. by default, it is `cosmos`.

func WithNodeAddress

func WithNodeAddress(addr string) Option

WithNodeAddress sets the node address of your chain. When this option is not provided `http://localhost:26657` is used as default.

func WithRPCClient added in v0.24.0

func WithRPCClient(rpc rpcclient.Client) Option

WithRPCClient sets a tendermint RPC client. Already set by default.

func WithSigner added in v0.25.0

func WithSigner(signer Signer) Option

WithSigner sets the signer. Already set by default.

func WithUseFaucet

func WithUseFaucet(faucetAddress, denom string, minAmount uint64) Option

type Response

type Response struct {
	Codec codec.Codec

	// TxResponse is the underlying tx response.

Response of your broadcasted transaction.

func (Response) Decode

func (r Response) Decode(message proto.Message) error

Decode decodes the proto func response defined in your Msg service into your message type. message needs to be a pointer. and you need to provide the correct proto message(struct) type to the Decode func.

e.g., for the following CreateChain func the type would be: `types.MsgCreateChainResponse`.


service Msg {
  rpc CreateChain(MsgCreateChain) returns (MsgCreateChainResponse);


type Signer added in v0.25.0

type Signer interface {
	Sign(txf tx.Factory, name string, txBuilder client.TxBuilder, overwriteSig bool) error

Signer allows to mock the tx.Sign func.

type TX added in v0.25.0

type TX struct {
	// BlockTime returns the time of the block that contains the transaction.
	BlockTime time.Time

	// Raw contains the transaction as returned by the Tendermint API.
	Raw *ctypes.ResultTx

TX defines a block transaction.

func (TX) GetEvents added in v0.25.0

func (t TX) GetEvents() (events []TXEvent, err error)

GetEvents returns the transaction events.

type TXEvent added in v0.25.0

type TXEvent struct {
	Type       string             `json:"type"`
	Attributes []TXEventAttribute `json:"attributes"`

TXEvent defines a transaction event.

type TXEventAttribute added in v0.25.0

type TXEventAttribute struct {
	Key   string `json:"key"`
	Value []byte `json:"value"`

TXEventAttribute defines a transaction event attribute.

type TxService added in v0.24.0

type TxService struct {
	// contains filtered or unexported fields

func (TxService) Broadcast added in v0.24.0

func (s TxService) Broadcast(ctx context.Context) (Response, error)

Broadcast signs and broadcasts this tx. If faucet is enabled and if the "from" account doesn't have enough funds, is it automatically filled with the default amount, and the tx is broadcasted again. Note that this may still end with the same error if the amount is greater than the amount dumped by the faucet.

func (TxService) EncodeJSON added in v0.24.0

func (s TxService) EncodeJSON() ([]byte, error)

EncodeJSON encodes the transaction as a json string.

func (TxService) Gas added in v0.24.0

func (s TxService) Gas() uint64

Gas is gas decided to use for this tx. either calculated or configured by the caller.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL