cosmosclient

package
v28.7.0 Latest Latest
Warning

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

 Go to latest Published: Jan 15, 2025 License: Apache-2.0 Imports: 39 Imported by: 12

Documentation

Overview

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

Index

Constants

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

Variables

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")
)

Functions

This section is empty.

Types

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 

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

func (Client) BankSendTx 

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 

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 

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

func (Client) CreateTxWithOptions added in v28.5.1 

func (c Client) CreateTxWithOptions(ctx context.Context, account cosmosaccount.Account, options TxOptions, msgs ...sdktypes.Msg) (TxService, error)

CreateTxWithOptions creates a transaction with the given options. Options override global client options.

func (Client) GetBlockTXs 

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 

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

LatestBlockHeight returns the latest block height of the app.

func (Client) SetConfigAddressPrefix 

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 

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 

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 

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 

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 

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

FaucetClient allows to mock the cosmosfaucet.Client.

type Gasometer 

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. Option, are global to the client and affect all transactions. If you want to override a global option on a transaction, use the TxOptions struct.

func WithAccountRetriever 

func WithAccountRetriever(accountRetriever client.AccountRetriever) Option

WithAccountRetriever sets the account retriever Already set by default.

func WithAddressPrefix 

func WithAddressPrefix(prefix string) Option

WithAddressPrefix sets the address prefix on the client.

func WithBankQueryClient 

func WithBankQueryClient(bankQueryClient banktypes.QueryClient) Option

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

func WithFaucetClient 

func WithFaucetClient(faucetClient FaucetClient) Option

WithFaucetClient sets the faucet client. Already set by default.

func WithFees 

func WithFees(fees string) Option

WithFees sets the fees (e.g. 10uatom) on the client. It will be used for all transactions if not overridden on the transaction options.

func WithGas 

func WithGas(gas string) Option

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

func WithGasAdjustment 

func WithGasAdjustment(gasAdjustment float64) Option

WithGasAdjustment sets the gas adjustment.

func WithGasPrices 

func WithGasPrices(gasPrices string) Option

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

func WithGasometer 

func WithGasometer(gasometer Gasometer) Option

WithGasometer sets the gasometer. Already set by default.

func WithGenerateOnly 

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 

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 

func WithRPCClient(rpc rpcclient.Client) Option

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

func WithSigner 

func WithSigner(signer Signer) Option

WithSigner sets the signer. Already set by default.

func WithUseFaucet 

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

WithUseFaucet sets the faucet address on the client.

type Response 

type Response struct {
	Codec codec.Codec

	// TxResponse is the underlying tx response.
	*sdktypes.TxResponse
}

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`.

```proto 

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

```

type Signer 

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

Signer allows to mock the tx.Sign func.

type TX 

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 

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

GetEvents returns the transaction events.

type TXEvent 

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

TXEvent defines a transaction event.

type TXEventAttribute 

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

TXEventAttribute defines a transaction event attribute.

type TxOptions added in v28.5.1 

type TxOptions struct {
	// Memo is the memo to be used for the transaction.
	Memo string

	// GasLimit is the gas limit to be used for the transaction.
	// If GasLimit is set to 0, the gas limit will be automatically calculated.
	GasLimit uint64

	// Fees is the fees to be used for the transaction.
	Fees string
}

TxOptions contains options for creating a transaction. It is used by the CreateTxWithOptions method.

type TxService 

type TxService struct {
	// contains filtered or unexported fields
}

func (TxService) Broadcast 

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 

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

EncodeJSON encodes the transaction as a json string.

func (TxService) Gas 

func (s TxService) Gas() uint64

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.