Tx - Cosmos Docs

Generated from cosmos/cosmos-sdk@c1126e4e5460 on ref main.

Queries

A node exposes only the services its application registers:

gRPC on port 9090
REST on port 1317, if the method has an HTTP binding

Run grpcurl -plaintext localhost:9090 list to see what a node serves. Queries are read-only and never pass through consensus. See Queries. Replace <string> placeholders with real values and omit unused filters. Payloads use protobuf JSON, and some string fields accept enum constants listed under Types. Field tables give the encoding each value takes. Examples assume a local node. For TLS endpoints, use port 443 and omit -plaintext. See gRPC services for reflection, address formats, and decimal encoding.

BroadcastTx

BroadcastTx broadcast transaction.


gRPC	`cosmos.tx.v1beta1.Service/BroadcastTx`
REST	`POST /cosmos/tx/v1beta1/txs`

Request BroadcastTxRequest:

Field	Type	Description
`tx_bytes`	`bytes`	tx_bytes is the raw transaction.
`mode`	`BroadcastMode`

Response BroadcastTxResponse:

Field	Type	Description
`tx_response`	`TxResponse`	tx_response is the queried TxResponses.

grpcurl -plaintext -d '{"tx_bytes":"","mode":"BROADCAST_MODE_SYNC"}' \
  localhost:9090 cosmos.tx.v1beta1.Service/BroadcastTx

GetBlockWithTxs

GetBlockWithTxs fetches a block with decoded txs.


gRPC	`cosmos.tx.v1beta1.Service/GetBlockWithTxs`
REST	`GET /cosmos/tx/v1beta1/txs/block/{height}`

Request GetBlockWithTxsRequest:

Field	Type	Description
`height`	`int64`	height is the height of the block to query.
`pagination`	`PageRequest`	pagination defines a pagination for the request.

Response GetBlockWithTxsResponse:

Field	Type	Description
`txs`	`Tx`[]	txs are the transactions in the block.
`block_id`	`BlockID`
`block`	`Block`
`pagination`	`PageResponse`	pagination defines a pagination for the response.

grpcurl -plaintext -d '{"height":"1","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.tx.v1beta1.Service/GetBlockWithTxs

GetTx

GetTx fetches a tx by hash.


gRPC	`cosmos.tx.v1beta1.Service/GetTx`
REST	`GET /cosmos/tx/v1beta1/txs/{hash}`

Request GetTxRequest:

Field	Type	Description
`hash`	`string`	hash is the tx hash to query, encoded as a hex string.

Response GetTxResponse:

Field	Type	Description
`tx`	`Tx`	tx is the queried transaction.
`tx_response`	`TxResponse`	tx_response is the queried TxResponses.

grpcurl -plaintext -d '{"hash":"<string>"}' \
  localhost:9090 cosmos.tx.v1beta1.Service/GetTx

GetTxsEvent

GetTxsEvent fetches txs by event.


gRPC	`cosmos.tx.v1beta1.Service/GetTxsEvent`
REST	`GET /cosmos/tx/v1beta1/txs`

Request GetTxsEventRequest:

Field	Type	Description
`events`	`string`[]	events is the list of transaction event type. Deprecated post v0.47.x: use query instead, which should contain a valid events query. Deprecated.
`pagination`	`PageRequest`	pagination defines a pagination for the request. Deprecated post v0.46.x: use page and limit instead. Deprecated.
`order_by`	`OrderBy`
`page`	`uint64`	page is the page number to query, starts at 1. If not provided, will default to first page.
`limit`	`uint64`	limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app.
`query`	`string`	query defines the transaction event query that is proxied to Tendermint’s TxSearch RPC method. The query must be valid.

Response GetTxsEventResponse:

Field	Type	Description
`txs`	`Tx`[]	txs is the list of queried transactions.
`tx_responses`	`TxResponse`[]	tx_responses is the list of queried TxResponses.
`pagination`	`PageResponse`	pagination defines a pagination for the response. Deprecated post v0.46.x: use total instead. Deprecated.
`total`	`uint64`	total is total number of results available

grpcurl -plaintext -d '{"order_by":"ORDER_BY_ASC","page":"1","limit":"1","query":"<string>"}' \
  localhost:9090 cosmos.tx.v1beta1.Service/GetTxsEvent

Simulate

Simulate simulates executing a transaction for estimating gas usage.


gRPC	`cosmos.tx.v1beta1.Service/Simulate`
REST	`POST /cosmos/tx/v1beta1/simulate`

Request SimulateRequest:

Field	Type	Description
`tx`	`Tx`	tx is the transaction to simulate. Deprecated. Send raw tx bytes instead. Deprecated.
`tx_bytes`	`bytes`	tx_bytes is the raw transaction.

Response SimulateResponse:

Field	Type	Description
`gas_info`	`GasInfo`	gas_info is the information about gas used in the simulation.
`result`	`Result`	result is the result of the simulation.

grpcurl -plaintext -d '{"tx_bytes":""}' \
  localhost:9090 cosmos.tx.v1beta1.Service/Simulate

TxDecode

TxDecode decodes the transaction.


gRPC	`cosmos.tx.v1beta1.Service/TxDecode`
REST	`POST /cosmos/tx/v1beta1/decode`

Request TxDecodeRequest:

Field	Type	Description
`tx_bytes`	`bytes`	tx_bytes is the raw transaction.

Response TxDecodeResponse:

Field	Type	Description
`tx`	`Tx`	tx is the decoded transaction.

grpcurl -plaintext -d '{"tx_bytes":""}' \
  localhost:9090 cosmos.tx.v1beta1.Service/TxDecode

TxDecodeAmino

TxDecodeAmino decodes an Amino transaction from encoded bytes to JSON.


gRPC	`cosmos.tx.v1beta1.Service/TxDecodeAmino`
REST	`POST /cosmos/tx/v1beta1/decode/amino`

Request TxDecodeAminoRequest:

Field	Type	Description
`amino_binary`	`bytes`

Response TxDecodeAminoResponse:

Field	Type	Description
`amino_json`	`string`

grpcurl -plaintext -d '{"amino_binary":""}' \
  localhost:9090 cosmos.tx.v1beta1.Service/TxDecodeAmino

TxEncode

TxEncode encodes the transaction.


gRPC	`cosmos.tx.v1beta1.Service/TxEncode`
REST	`POST /cosmos/tx/v1beta1/encode`

Request TxEncodeRequest:

Field	Type	Description
`tx`	`Tx`	tx is the transaction to encode.

Response TxEncodeResponse:

Field	Type	Description
`tx_bytes`	`bytes`	tx_bytes is the encoded transaction bytes.

grpcurl -plaintext -d '{"tx":{"body":{"messages":[{"@type":"/cosmos.example.v1.MsgExample","...":"the fields of that message, inline"}],"memo":"<string>","timeout_height":"1","unordered":false,"timeout_timestamp":"<RFC 3339 timestamp>","extension_options":[{"@type":"/cosmos.example.v1.MsgExample","...":"the fields of that message, inline"}],"non_critical_extension_options":[{"@type":"/cosmos.example.v1.MsgExample","...":"the fields of that message, inline"}]},"auth_info":{"signer_infos":[{"public_key":{"@type":"/cosmos.example.v1.MsgExample","...":"the fields of that message, inline"},"mode_info":{"single":{}},"sequence":"1"}],"fee":{"amount":[{"denom":"<string>","amount":"<string>"}],"gas_limit":"1","payer":"<string>","granter":"<string>"}},"signatures":[""]}}' \
  localhost:9090 cosmos.tx.v1beta1.Service/TxEncode

TxEncodeAmino

TxEncodeAmino encodes an Amino transaction from JSON to encoded bytes.


gRPC	`cosmos.tx.v1beta1.Service/TxEncodeAmino`
REST	`POST /cosmos/tx/v1beta1/encode/amino`

Request TxEncodeAminoRequest:

Field	Type	Description
`amino_json`	`string`

Response TxEncodeAminoResponse:

Field	Type	Description
`amino_binary`	`bytes`

grpcurl -plaintext -d '{"amino_json":"<string>"}' \
  localhost:9090 cosmos.tx.v1beta1.Service/TxEncodeAmino

Types

Messages referenced by the fields above. Protocol buffers version 3 has no required fields, so every field is optional on the wire, and a [] suffix marks a repeated field.

cosmos.base.abci.v1beta1.ABCIMessageLog

ABCIMessageLog defines a structure containing an indexed tx ABCI message log.

Field	Type	Description
`msg_index`	`uint32`
`log`	`string`
`events`	`StringEvent`[]	Events contains a slice of Event objects that were emitted during some execution.

cosmos.base.abci.v1beta1.Attribute

Attribute defines an attribute wrapper where the key and value are strings instead of raw bytes.

Field	Type	Description
`key`	`string`
`value`	`string`

cosmos.base.abci.v1beta1.GasInfo

GasInfo defines tx execution gas context.

Field	Type	Description
`gas_wanted`	`uint64`	GasWanted is the maximum units of work we allow this tx to perform.
`gas_used`	`uint64`	GasUsed is the amount of gas actually consumed.

cosmos.base.abci.v1beta1.Result

Result is the union of ResponseFormat and ResponseCheckTx.

Field	Type	Description
`data`	`bytes`	Data is any data returned from message or handler execution. It MUST be length prefixed in order to separate data from multiple message executions. Deprecated. This field is still populated, but prefer msg_response instead because it also contains the Msg response typeURL. Deprecated.
`log`	`string`	Log contains the log information from message or handler execution.
`events`	`Event`[]	Events contains a slice of Event objects that were emitted during message or handler execution.
`msg_responses`	`Any`[]	msg_responses contains the Msg handler responses type packed in Anys.

cosmos.base.abci.v1beta1.StringEvent

StringEvent defines en Event object wrapper where all the attributes contain key/value pairs that are strings instead of raw bytes.

Field	Type	Description
`type`	`string`
`attributes`	`Attribute`[]

cosmos.base.abci.v1beta1.TxResponse

TxResponse defines a structure containing relevant tx data and metadata. The tags are stringified and the log is JSON decoded.

Field	Type	Description
`height`	`int64`	The block height
`txhash`	`string`	The transaction hash.
`codespace`	`string`	Namespace for the Code
`code`	`uint32`	Response code.
`data`	`string`	Result bytes, if any.
`raw_log`	`string`	The output of the application’s logger (raw string). May be non-deterministic.
`logs`	`ABCIMessageLog`[]	The output of the application’s logger (typed). May be non-deterministic.
`info`	`string`	Additional information. May be non-deterministic.
`gas_wanted`	`int64`	Amount of gas requested for transaction.
`gas_used`	`int64`	Amount of gas consumed by transaction.
`tx`	`Any`	The request transaction bytes.
`timestamp`	`string`	Time of the previous block. For heights > 1, it’s the weighted median of the timestamps of the valid votes in the block.LastCommit. For height == 1, it’s genesis time.
`events`	`Event`[]	Events defines all the events emitted by processing a transaction. Note, these events include those emitted by processing all the messages and those emitted from the ante. Whereas Logs contains the events, with additional metadata, emitted only by processing the messages.

cosmos.base.query.v1beta1.PageRequest

PageRequest is to be embedded in gRPC request messages for efficient pagination. Ex: message SomeRequest { Foo some_parameter = 1; PageRequest pagination = 2; }

Field	Type	Description
`key`	`bytes`	key is a value returned in PageResponse.next_key to begin querying the next page most efficiently. Only one of offset or key should be set.
`offset`	`uint64`	offset is a numeric offset that can be used when key is unavailable. It is less efficient than using key. Only one of offset or key should be set.
`limit`	`uint64`	limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app.
`count_total`	`bool`	count_total is set to true to indicate that the result set should include a count of the total number of items available for pagination in UIs. count_total is only respected when offset is used. It is ignored when key is set.
`reverse`	`bool`	reverse is set to true if results are to be returned in the descending order.

cosmos.base.query.v1beta1.PageResponse

PageResponse is to be embedded in gRPC response messages where the corresponding request message has used PageRequest. message SomeResponse { repeated Bar results = 1; PageResponse page = 2; }

Field	Type	Description
`next_key`	`bytes`	next_key is the key to be passed to PageRequest.key to query the next page most efficiently. It will be empty if there are no more results.
`total`	`uint64`	total is total number of results available if PageRequest.count_total was set, its value is undefined otherwise

cosmos.base.v1beta1.Coin

Coin defines a token with a denomination and an amount. NOTE: The amount field is an Int which implements the custom method signatures required by gogoproto.

Field	Type	Description
`denom`	`string`
`amount`	`string`	Encoded as cosmos.Int.

cosmos.crypto.multisig.v1beta1.CompactBitArray

CompactBitArray is an implementation of a space efficient bit array. This is used to ensure that the encoded data takes up a minimal amount of space after proto encoding. This is not thread safe, and is not intended for concurrent usage.

Field	Type	Description
`extra_bits_stored`	`uint32`
`elems`	`bytes`

cosmos.tx.signing.v1beta1.SignMode

Written as a quoted string in JSON.

Value
`SIGN_MODE_UNSPECIFIED`	Zero value. Handlers reject it.
`SIGN_MODE_DIRECT`
`SIGN_MODE_DIRECT_AUX`
`SIGN_MODE_LEGACY_AMINO_JSON`
`SIGN_MODE_EIP_191`

cosmos.tx.v1beta1.AuthInfo

AuthInfo describes the fee and signer modes that are used to sign a transaction.

Field	Type	Description
`signer_infos`	`SignerInfo`[]	signer_infos defines the signing modes for the required signers. The number and order of elements must match the required signers from TxBody’s messages. The first element is the primary signer and the one which pays the fee.
`fee`	`Fee`	Fee is the fee and gas limit for the transaction. The first signer is the primary signer and the one which pays the fee. The fee can be calculated based on the cost of evaluating the body and doing signature verification of the signers. This can be estimated via simulation.
`tip`	`Tip`	Tip is the optional tip used for transactions fees paid in another denom. This field is ignored if the chain didn’t enable tips, i.e. didn’t add the `TipDecorator` in its posthandler. Deprecated.

cosmos.tx.v1beta1.BroadcastMode

Written as a quoted string in JSON.

Value
`BROADCAST_MODE_UNSPECIFIED`	Zero value. Handlers reject it.
`BROADCAST_MODE_BLOCK`	Deprecated.
`BROADCAST_MODE_SYNC`
`BROADCAST_MODE_ASYNC`

cosmos.tx.v1beta1.Fee

Fee includes the amount of coins paid in fees and the maximum gas to be used by the transaction. The ratio yields an effective “gasprice”, which must be above some minimum to be accepted into the mempool.

Field	Type	Description
`amount`	`Coin`[]	amount is the amount of coins to be paid as a fee
`gas_limit`	`uint64`	gas_limit is the maximum gas that can be used in transaction processing before an out of gas error occurs
`payer`	`string`	if unset, the first signer is responsible for paying the fees. If set, the specified account must pay the fees. the payer must be a tx signer (and thus have signed this field in AuthInfo). setting this field does not change the ordering of required signers for the transaction. Encoded as cosmos.AddressString.
`granter`	`string`	if set, the fee payer (either the first signer or the value of the payer field) requests that a fee grant be used to pay fees instead of the fee payer’s own balance. If an appropriate fee grant does not exist or the chain does not support fee grants, this will fail Encoded as cosmos.AddressString.

cosmos.tx.v1beta1.ModeInfo

ModeInfo describes the signing mode of a single or nested multisig signer.

Field	Type	Description
`single`	`Single`	single represents a single signer
`multi`	`Multi`	multi represents a nested multisig signer

cosmos.tx.v1beta1.ModeInfo.Multi

Multi is the mode info for a multisig public key

Field	Type	Description
`bitarray`	`CompactBitArray`	bitarray specifies which keys within the multisig are signing
`mode_infos`	`ModeInfo`[]	mode_infos is the corresponding modes of the signers of the multisig which could include nested multisig public keys

cosmos.tx.v1beta1.ModeInfo.Single

Single is the mode info for a single signer. It is structured as a message to allow for additional fields such as locale for SIGN_MODE_TEXTUAL in the future

Field	Type	Description
`mode`	`SignMode`	mode is the signing mode of the single signer

cosmos.tx.v1beta1.OrderBy

Written as a quoted string in JSON.

Value
`ORDER_BY_UNSPECIFIED`	Zero value. Handlers reject it.
`ORDER_BY_ASC`
`ORDER_BY_DESC`

cosmos.tx.v1beta1.SignerInfo

SignerInfo describes the public key and signing mode of a single top-level signer.

Field	Type	Description
`public_key`	`Any`	public_key is the public key of the signer. It is optional for accounts that already exist in state. If unset, the verifier can use the required \ signer address for this position and lookup the public key.
`mode_info`	`ModeInfo`	mode_info describes the signing mode of the signer and is a nested structure to support nested multisig pubkey’s
`sequence`	`uint64`	sequence is the sequence of the account, which describes the number of committed transactions signed by a given address. It is used to prevent replay attacks.

cosmos.tx.v1beta1.Tip

Tip is the tip used for meta-transactions.

Field	Type	Description
`amount`	`Coin`[]	amount is the amount of the tip
`tipper`	`string`	tipper is the address of the account paying for the tip Encoded as cosmos.AddressString.

cosmos.tx.v1beta1.Tx

Tx is the standard type used for broadcasting transactions.

Field	Type	Description
`body`	`TxBody`	body is the processable content of the transaction
`auth_info`	`AuthInfo`	auth_info is the authorization related content of the transaction, specifically signers, signer modes and fee
`signatures`	`bytes`[]	signatures is a list of signatures that matches the length and order of AuthInfo’s signer_infos to allow connecting signature meta information like public key and signing mode by position.

cosmos.tx.v1beta1.TxBody

TxBody is the body of a transaction that all signers sign over.

Field	Type	Description
`messages`	`Any`[]	messages is a list of messages to be executed. The required signers of those messages define the number and order of elements in AuthInfo’s signer_infos and Tx’s signatures. Each required signer address is added to the list only the first time it occurs. By convention, the first required signer (usually from the first message) is referred to as the primary signer and pays the fee for the whole transaction.
`memo`	`string`	memo is any arbitrary note/comment to be added to the transaction. WARNING: in clients, any publicly exposed text should not be called memo, but should be called `note` instead (see https://github.com/cosmos/cosmos-sdk/issues/9122).
`timeout_height`	`uint64`	timeout_height is the block height after which this transaction will not be processed by the chain.
`unordered`	`bool`	unordered, when set to true, indicates that the transaction signer(s) intend for the transaction to be evaluated and executed in an un-ordered fashion. Specifically, the account’s nonce will NOT be checked or incremented, which allows for fire-and-forget as well as concurrent transaction execution. Note, when set to true, the existing ‘timeout_timestamp’ value must be set and will be used to correspond to a timestamp in which the transaction is deemed valid. When true, the sequence value MUST be 0, and any transaction with unordered=true and a non-zero sequence value will be rejected. External services that make assumptions about sequence values may need to be updated because of this.
`timeout_timestamp`	`Timestamp`	timeout_timestamp is the block time after which this transaction will not be processed by the chain. Note, if unordered=true this value MUST be set and will act as a short-lived TTL in which the transaction is deemed valid and kept in memory to prevent duplicates.
`extension_options`	`Any`[]	extension_options are arbitrary options that can be added by chains when the default options are not sufficient. If any of these are present and can’t be handled, the transaction will be rejected
`non_critical_extension_options`	`Any`[]	extension_options are arbitrary options that can be added by chains when the default options are not sufficient. If any of these are present and can’t be handled, they will be ignored

Overview

gRPC Services

REST (gRPC Gateway)

Tx

Queries

BroadcastTx

GetBlockWithTxs

GetTx

GetTxsEvent

Simulate

TxDecode

TxDecodeAmino

TxEncode

TxEncodeAmino

Types

cosmos.base.abci.v1beta1.ABCIMessageLog

cosmos.base.abci.v1beta1.Attribute

cosmos.base.abci.v1beta1.GasInfo

cosmos.base.abci.v1beta1.Result

cosmos.base.abci.v1beta1.StringEvent

cosmos.base.abci.v1beta1.TxResponse

cosmos.base.query.v1beta1.PageRequest

cosmos.base.query.v1beta1.PageResponse

cosmos.base.v1beta1.Coin

cosmos.crypto.multisig.v1beta1.CompactBitArray

cosmos.tx.signing.v1beta1.SignMode

cosmos.tx.v1beta1.AuthInfo

cosmos.tx.v1beta1.BroadcastMode

cosmos.tx.v1beta1.Fee

cosmos.tx.v1beta1.ModeInfo

cosmos.tx.v1beta1.ModeInfo.Multi

cosmos.tx.v1beta1.ModeInfo.Single

cosmos.tx.v1beta1.OrderBy

cosmos.tx.v1beta1.SignerInfo

cosmos.tx.v1beta1.Tip

cosmos.tx.v1beta1.Tx

cosmos.tx.v1beta1.TxBody

​Queries

​BroadcastTx

​GetBlockWithTxs

​GetTx

​GetTxsEvent

​Simulate

​TxDecode

​TxDecodeAmino

​TxEncode

​TxEncodeAmino

​Types

​cosmos.base.abci.v1beta1.ABCIMessageLog

​cosmos.base.abci.v1beta1.Attribute

​cosmos.base.abci.v1beta1.GasInfo

​cosmos.base.abci.v1beta1.Result

​cosmos.base.abci.v1beta1.StringEvent

​cosmos.base.abci.v1beta1.TxResponse

​cosmos.base.query.v1beta1.PageRequest

​cosmos.base.query.v1beta1.PageResponse

​cosmos.base.v1beta1.Coin

​cosmos.crypto.multisig.v1beta1.CompactBitArray

​cosmos.tx.signing.v1beta1.SignMode

​cosmos.tx.v1beta1.AuthInfo

​cosmos.tx.v1beta1.BroadcastMode

​cosmos.tx.v1beta1.Fee

​cosmos.tx.v1beta1.ModeInfo

​cosmos.tx.v1beta1.ModeInfo.Multi

​cosmos.tx.v1beta1.ModeInfo.Single

​cosmos.tx.v1beta1.OrderBy

​cosmos.tx.v1beta1.SignerInfo

​cosmos.tx.v1beta1.Tip

​cosmos.tx.v1beta1.Tx

​cosmos.tx.v1beta1.TxBody

Queries

BroadcastTx

GetBlockWithTxs

GetTx

GetTxsEvent

Simulate

TxDecode

TxDecodeAmino

TxEncode

TxEncodeAmino

Types

cosmos.base.abci.v1beta1.ABCIMessageLog

cosmos.base.abci.v1beta1.Attribute

cosmos.base.abci.v1beta1.GasInfo

cosmos.base.abci.v1beta1.Result

cosmos.base.abci.v1beta1.StringEvent

cosmos.base.abci.v1beta1.TxResponse

cosmos.base.query.v1beta1.PageRequest

cosmos.base.query.v1beta1.PageResponse

cosmos.base.v1beta1.Coin

cosmos.crypto.multisig.v1beta1.CompactBitArray

cosmos.tx.signing.v1beta1.SignMode

cosmos.tx.v1beta1.AuthInfo

cosmos.tx.v1beta1.BroadcastMode

cosmos.tx.v1beta1.Fee

cosmos.tx.v1beta1.ModeInfo

cosmos.tx.v1beta1.ModeInfo.Multi

cosmos.tx.v1beta1.ModeInfo.Single

cosmos.tx.v1beta1.OrderBy

cosmos.tx.v1beta1.SignerInfo

cosmos.tx.v1beta1.Tip

cosmos.tx.v1beta1.Tx

cosmos.tx.v1beta1.TxBody