Pre-requisite Readings

​
Abstract

This document specifies the x/auth/tx package of the Cosmos SDK. This package represents the Cosmos SDK implementation of the client.TxConfig, client.TxBuilder, client.TxEncoder and client.TxDecoder interfaces.

​
Contents

​
Transactions

​
TxConfig

client.TxConfig defines an interface a client can utilize to generate an application-defined concrete transaction type. The interface defines a set of methods for creating a client.TxBuilder. 
package client

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/types/tx"
	signingtypes "github.com/cosmos/cosmos-sdk/types/tx/signing"
    "github.com/cosmos/cosmos-sdk/x/auth/signing"
)

type (
	/ TxEncodingConfig defines an interface that contains transaction
	/ encoders and decoders
	TxEncodingConfig interface {
    TxEncoder()

sdk.TxEncoder
		TxDecoder()

sdk.TxDecoder
		TxJSONEncoder()

sdk.TxEncoder
		TxJSONDecoder()

sdk.TxDecoder
		MarshalSignatureJSON([]signingtypes.SignatureV2) ([]byte, error)

UnmarshalSignatureJSON([]byte) ([]signingtypes.SignatureV2, error)
}

	/ TxConfig defines an interface a client can utilize to generate an
	/ application-defined concrete transaction type. The type returned must
	/ implement TxBuilder.
	TxConfig interface {
    TxEncodingConfig

		NewTxBuilder()

TxBuilder
		WrapTxBuilder(sdk.Tx) (TxBuilder, error)

SignModeHandler()

signing.SignModeHandler
}

	/ TxBuilder defines an interface which an application-defined concrete transaction
	/ type must implement. Namely, it must be able to set messages, generate
	/ signatures, and provide canonical bytes to sign over. The transaction must
	/ also know how to encode itself.
	TxBuilder interface {
    GetTx()

signing.Tx

		SetMsgs(msgs ...sdk.Msg)

error
		SetSignatures(signatures ...signingtypes.SignatureV2)

error
		SetMemo(memo string)

SetFeeAmount(amount sdk.Coins)

SetFeePayer(feePayer sdk.AccAddress)

SetGasLimit(limit uint64)

SetTip(tip *tx.Tip)

SetTimeoutHeight(height uint64)

SetFeeGranter(feeGranter sdk.AccAddress)

AddAuxSignerData(tx.AuxSignerData)

error
}
)
The default implementation of client.TxConfig is instantiated by NewTxConfig in x/auth/tx module. 
package tx

import (
    
	"fmt"
    "github.com/cosmos/cosmos-sdk/client"
    "github.com/cosmos/cosmos-sdk/codec"
	sdk "github.com/cosmos/cosmos-sdk/types"
	signingtypes "github.com/cosmos/cosmos-sdk/types/tx/signing"
    "github.com/cosmos/cosmos-sdk/x/auth/signing"
)

type config struct {
    handler     signing.SignModeHandler
	decoder     sdk.TxDecoder
	encoder     sdk.TxEncoder
	jsonDecoder sdk.TxDecoder
	jsonEncoder sdk.TxEncoder
	protoCodec  codec.ProtoCodecMarshaler
}

/ NewTxConfig returns a new protobuf TxConfig using the provided ProtoCodec and sign modes. The
/ first enabled sign mode will become the default sign mode.
/ NOTE: Use NewTxConfigWithHandler to provide a custom signing handler in case the sign mode
/ is not supported by default (eg: SignMode_SIGN_MODE_EIP_191).
func NewTxConfig(protoCodec codec.ProtoCodecMarshaler, enabledSignModes []signingtypes.SignMode)

client.TxConfig {
    return NewTxConfigWithHandler(protoCodec, makeSignModeHandler(enabledSignModes))
}

/ NewTxConfig returns a new protobuf TxConfig using the provided ProtoCodec and signing handler.
func NewTxConfigWithHandler(protoCodec codec.ProtoCodecMarshaler, handler signing.SignModeHandler)

client.TxConfig {
    return &config{
    handler:     handler,
		decoder:     DefaultTxDecoder(protoCodec),
		encoder:     DefaultTxEncoder(),
		jsonDecoder: DefaultJSONTxDecoder(protoCodec),
		jsonEncoder: DefaultJSONTxEncoder(protoCodec),
		protoCodec:  protoCodec,
}
}

func (g config)

NewTxBuilder()

client.TxBuilder {
    return newBuilder(g.protoCodec)
}

/ WrapTxBuilder returns a builder from provided transaction
func (g config)

WrapTxBuilder(newTx sdk.Tx) (client.TxBuilder, error) {
    newBuilder, ok := newTx.(*wrapper)
    if !ok {
    return nil, fmt.Errorf("expected %T, got %T", &wrapper{
}, newTx)
}

return newBuilder, nil
}

func (g config)

SignModeHandler()

signing.SignModeHandler {
    return g.handler
}

func (g config)

TxEncoder()

sdk.TxEncoder {
    return g.encoder
}

func (g config)

TxDecoder()

sdk.TxDecoder {
    return g.decoder
}

func (g config)

TxJSONEncoder()

sdk.TxEncoder {
    return g.jsonEncoder
}

func (g config)

TxJSONDecoder()

sdk.TxDecoder {
    return g.jsonDecoder
}

​
TxBuilder

package client

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/types/tx"
	signingtypes "github.com/cosmos/cosmos-sdk/types/tx/signing"
    "github.com/cosmos/cosmos-sdk/x/auth/signing"
)

type (
	/ TxEncodingConfig defines an interface that contains transaction
	/ encoders and decoders
	TxEncodingConfig interface {
    TxEncoder()

sdk.TxEncoder
		TxDecoder()

sdk.TxDecoder
		TxJSONEncoder()

sdk.TxEncoder
		TxJSONDecoder()

sdk.TxDecoder
		MarshalSignatureJSON([]signingtypes.SignatureV2) ([]byte, error)

UnmarshalSignatureJSON([]byte) ([]signingtypes.SignatureV2, error)
}

	/ TxConfig defines an interface a client can utilize to generate an
	/ application-defined concrete transaction type. The type returned must
	/ implement TxBuilder.
	TxConfig interface {
    TxEncodingConfig

		NewTxBuilder()

TxBuilder
		WrapTxBuilder(sdk.Tx) (TxBuilder, error)

SignModeHandler()

signing.SignModeHandler
}

	/ TxBuilder defines an interface which an application-defined concrete transaction
	/ type must implement. Namely, it must be able to set messages, generate
	/ signatures, and provide canonical bytes to sign over. The transaction must
	/ also know how to encode itself.
	TxBuilder interface {
    GetTx()

signing.Tx

		SetMsgs(msgs ...sdk.Msg)

error
		SetSignatures(signatures ...signingtypes.SignatureV2)

error
		SetMemo(memo string)

SetFeeAmount(amount sdk.Coins)

SetFeePayer(feePayer sdk.AccAddress)

SetGasLimit(limit uint64)

SetTip(tip *tx.Tip)

SetTimeoutHeight(height uint64)

SetFeeGranter(feeGranter sdk.AccAddress)

AddAuxSignerData(tx.AuxSignerData)

error
}
)
The client.TxBuilder interface is as well implemented by x/auth/tx. A client.TxBuilder can be accessed with TxConfig.NewTxBuilder().

​
TxEncoder/ TxDecoder

More information about TxEncoder and TxDecoder can be found here.

​
Client

​
CLI

​
Query

The x/auth/tx module provides a CLI command to query any transaction, given its hash, transaction sequence or signature. Without any argument, the command will query the transaction using the transaction hash. 
simd query tx DFE87B78A630C0EFDF76C80CD24C997E252792E0317502AE1A02B9809F0D8685
When querying a transaction from an account given its sequence, use the --type=acc_seq flag: 
simd query tx --type=acc_seq cosmos1u69uyr6v9qwe6zaaeaqly2h6wnedac0xpxq325/1
When querying a transaction given its signature, use the --type=signature flag: 
simd query tx --type=signature Ofjvgrqi8twZfqVDmYIhqwRLQjZZ40XbxEamk/veH3gQpRF0hL2PH4ejRaDzAX+2WChnaWNQJQ41ekToIi5Wqw==
When querying a transaction given its events, use the --type=events flag: 
simd query txs --events 'message.sender=cosmos...' --page 1 --limit 30
The x/auth/block module provides a CLI command to query any block, given its hash, height, or events. When querying a block by its hash, use the --type=hash flag: 
simd query block --type=hash DFE87B78A630C0EFDF76C80CD24C997E252792E0317502AE1A02B9809F0D8685
When querying a block by its height, use the --type=height flag: 
simd query block --type=height 1357
When querying a block by its events, use the --query flag: 
simd query blocks --query 'message.sender=cosmos...' --page 1 --limit 30

​
Transactions

The x/auth/tx module provides a convinient CLI command for decoding and encoding transactions.

​
encode

The encode command encodes a transaction created with the --generate-only flag or signed with the sign command. The transaction is seralized it to Protobuf and returned as base64. 
$ simd tx encode tx.json
Co8BCowBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmwKLWNvc21vczFsNnZzcWhoN3Jud3N5cjJreXozampnM3FkdWF6OGd3Z3lsODI3NRItY29zbW9zMTU4c2FsZHlnOHBteHU3Znd2dDBkNng3amVzd3A0Z3d5a2xrNnkzGgwKBXN0YWtlEgMxMDASBhIEEMCaDA==
$ simd tx encode tx.signed.json
More information about the encode command can be found running simd tx encode --help.

​
decode

The decode commands decodes a transaction encoded with the encode command. 
simd tx decode Co8BCowBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmwKLWNvc21vczFsNnZzcWhoN3Jud3N5cjJreXozampnM3FkdWF6OGd3Z3lsODI3NRItY29zbW9zMTU4c2FsZHlnOHBteHU3Znd2dDBkNng3amVzd3A0Z3d5a2xrNnkzGgwKBXN0YWtlEgMxMDASBhIEEMCaDA==
More information about the decode command can be found running simd tx decode --help.

​
gRPC

A user can query the x/auth/tx module using gRPC endpoints.

​
TxDecode

The TxDecode endpoint allows to decode a transaction. 
cosmos.tx.v1beta1.Service/TxDecode
Example: 
grpcurl -plaintext \
    -d '{"tx_bytes":"Co8BCowBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmwKLWNvc21vczFsNnZzcWhoN3Jud3N5cjJreXozampnM3FkdWF6OGd3Z3lsODI3NRItY29zbW9zMTU4c2FsZHlnOHBteHU3Znd2dDBkNng3amVzd3A0Z3d5a2xrNnkzGgwKBXN0YWtlEgMxMDASBhIEEMCaDA=="}' \
    localhost:9090 \
    cosmos.tx.v1beta1.Service/TxDecode
Example Output: 
{
  "tx": {
    "body": {
      "messages": [
        {
          "@type": "/cosmos.bank.v1beta1.MsgSend",
          "amount": [
            {
              "denom": "stake",
              "amount": "100"
            }
          ],
          "fromAddress": "cosmos1l6vsqhh7rnwsyr2kyz3jjg3qduaz8gwgyl8275",
          "toAddress": "cosmos158saldyg8pmxu7fwvt0d6x7jeswp4gwyklk6y3"
        }
      ]
    },
    "authInfo": {
      "fee": {
        "gasLimit": "200000"
      }
    }
  }
}

​
TxEncode

The TxEncode endpoint allows to encode a transaction. 
cosmos.tx.v1beta1.Service/TxEncode
Example: 
grpcurl -plaintext \
    -d '{"tx": {
    "body": {
      "messages": [
        {"@type":"/cosmos.bank.v1beta1.MsgSend","amount":[{"denom":"stake","amount":"100"}],"fromAddress":"cosmos1l6vsqhh7rnwsyr2kyz3jjg3qduaz8gwgyl8275","toAddress":"cosmos158saldyg8pmxu7fwvt0d6x7jeswp4gwyklk6y3"}
      ]
    },
    "authInfo": {
      "fee": {
        "gasLimit": "200000"
      }
    }
  }}' \
    localhost:9090 \
    cosmos.tx.v1beta1.Service/TxEncode
Example Output: 
{
  "txBytes": "Co8BCowBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmwKLWNvc21vczFsNnZzcWhoN3Jud3N5cjJreXozampnM3FkdWF6OGd3Z3lsODI3NRItY29zbW9zMTU4c2FsZHlnOHBteHU3Znd2dDBkNng3amVzd3A0Z3d5a2xrNnkzGgwKBXN0YWtlEgMxMDASBhIEEMCaDA=="
}

​
TxDecodeAmino

The TxDecode endpoint allows to decode an amino transaction. 
cosmos.tx.v1beta1.Service/TxDecodeAmino
Example: 
grpcurl -plaintext \
    -d '{"amino_binary": "KCgWqQpvqKNhmgotY29zbW9zMXRzeno3cDJ6Z2Q3dnZrYWh5ZnJlNHduNXh5dTgwcnB0ZzZ2OWg1Ei1jb3Ntb3MxdHN6ejdwMnpnZDd2dmthaHlmcmU0d241eHl1ODBycHRnNnY5aDUaCwoFc3Rha2USAjEwEhEKCwoFc3Rha2USAjEwEMCaDCIGZm9vYmFy"}' \
    localhost:9090 \
    cosmos.tx.v1beta1.Service/TxDecodeAmino
Example Output: 
{
  "aminoJson": "{\"type\":\"cosmos-sdk/StdTx\",\"value\":{\"msg\":[{\"type\":\"cosmos-sdk/MsgSend\",\"value\":{\"from_address\":\"cosmos1tszz7p2zgd7vvkahyfre4wn5xyu80rptg6v9h5\",\"to_address\":\"cosmos1tszz7p2zgd7vvkahyfre4wn5xyu80rptg6v9h5\",\"amount\":[{\"denom\":\"stake\",\"amount\":\"10\"}]}}],\"fee\":{\"amount\":[{\"denom\":\"stake\",\"amount\":\"10\"}],\"gas\":\"200000\"},\"signatures\":null,\"memo\":\"foobar\",\"timeout_height\":\"0\"}}"
}

​
TxEncodeAmino

The TxEncodeAmino endpoint allows to encode an amino transaction. 
cosmos.tx.v1beta1.Service/TxEncodeAmino
Example: 
grpcurl -plaintext \
    -d '{"amino_json":"{\"type\":\"cosmos-sdk/StdTx\",\"value\":{\"msg\":[{\"type\":\"cosmos-sdk/MsgSend\",\"value\":{\"from_address\":\"cosmos1tszz7p2zgd7vvkahyfre4wn5xyu80rptg6v9h5\",\"to_address\":\"cosmos1tszz7p2zgd7vvkahyfre4wn5xyu80rptg6v9h5\",\"amount\":[{\"denom\":\"stake\",\"amount\":\"10\"}]}}],\"fee\":{\"amount\":[{\"denom\":\"stake\",\"amount\":\"10\"}],\"gas\":\"200000\"},\"signatures\":null,\"memo\":\"foobar\",\"timeout_height\":\"0\"}}"}' \
    localhost:9090 \
    cosmos.tx.v1beta1.Service/TxEncodeAmino
Example Output: 
{
  "amino_binary": "KCgWqQpvqKNhmgotY29zbW9zMXRzeno3cDJ6Z2Q3dnZrYWh5ZnJlNHduNXh5dTgwcnB0ZzZ2OWg1Ei1jb3Ntb3MxdHN6ejdwMnpnZDd2dmthaHlmcmU0d241eHl1ODBycHRnNnY5aDUaCwoFc3Rha2USAjEwEhEKCwoFc3Rha2USAjEwEMCaDCIGZm9vYmFy"
}