# Transactions

Transactions are objects created by end-users to trigger state changes in applications. They are comprised of metadata that defines a context and one or more sdk.Msg (opens new window) that trigger state changes within a module through the module’s Protobuf message service.

# Transaction process from an end-user perspective

While there is much to explore as you journey through the stack, begin by understanding the transaction process from a user perspective:

Decide on the messages to put into the transaction. This is normally done with the assistance of a wallet or application and a user interface.
Generate the transaction using the Cosmos SDK's TxBuilder. TxBuilder is the preferred way to generate a transaction.
Sign the transaction. Transactions must be signed before a validators includes them in a block.
Broadcast the signed transaction using one of the available interfaces.

Decide and sign are the main interactions of a user. Generate and broadcast are attended to by the user interface and other automation.

# Transaction objects

Transaction objects are Cosmos SDK types that implement the Tx (opens new window) interface. They contain the following methods:

You should rarely manipulate a Tx object directly. It is an intermediate type used for transaction generation. Developers usually use the TxBuilder (opens new window) interface.

# Messages

Transaction messages are not to be confused with ABCI messages, which define interactions between Tendermint and application layers.

Messages or sdk.Msg (opens new window) are module-specific objects that trigger state transitions within the scope of the module they belong to. Module developers define module messages by adding methods to the Protobuf Msg service and defining a MsgServer. Each sdk.Msg is related to exactly one Protobuf Msg service RPC defined inside each module's tx.proto file. A Cosmos SDK app router automatically maps every sdk.Msg to a corresponding RPC service, which routes it to the appropriate method. Protobuf generates a MsgServer interface for each module's Msg service and the module developer implements this interface.

This design puts more responsibility on module developers. This allows application developers to reuse common functionalities without having to repetitively implement state transition logic. While messages contain the information for the state transition logic, a transaction's other metadata and relevant information are stored in the TxBuilder and Context.

# Signing Transactions

Every message in a transaction must be signed by the addresses specified by its GetSigners (opens new window). The Cosmos SDK currently allows signing transactions in two different ways:

# Generating transactions

The TxBuilder interface contains metadata closely related to the generation of transactions. The end-user can freely set these parameters for the transaction to be generated:

As there are currently two modes for signing transactions, there are also two implementations of TxBuilder. There is a wrapper for SIGN_MODE_DIRECT and the StdTxBuilder (opens new window) for SIGN_MODE_LEGACY_AMINO_JSON. The two possibilities should normally be hidden away because end-users should prefer the overarching TxConfig (opens new window) interface. TxConfig is an app-wide (opens new window) configuration for managing transactions accessible from the context. Most importantly, it holds the information about whether to sign each transaction with SIGN_MODE_DIRECT or SIGN_MODE_LEGACY_AMINO_JSON.

A new TxBuilder will be instantiated with the appropriate sign mode by calling txBuilder := txConfig.NewTxBuilder(). TxConfig will also take care of correctly encoding the bytes either using SIGN_MODE_DIRECT or SIGN_MODE_LEGACY_AMINO_JSON once TxBuilder is correctly populated with the setters of the fields described above.

This is a pseudo-code snippet of how to generate and encode a transaction using the TxEncoder() method:

Copy txBuilder := txConfig.NewTxBuilder() txBuilder.SetMsgs(...) // and other setters on txBuilder

# Broadcasting the transaction

Once the transaction bytes are generated and signed, there are three primary ways of broadcasting the transaction:

  • Using the command-line interface (CLI).
  • Using gRPC.
  • Using REST endpoints.

Application developers create entrypoints to the application by creating a command-line interface typically found in the application's ./cmd folder, gRPC, and/or REST interface. These interfaces allow users to interact with the application.


For the command-line interface (CLI) module developers create subcommands to add as children to the application top-level transaction command TxCmd (opens new window).

CLI commands bundle all the steps of transaction processing into one simple command:

  • Creating messages
  • Generating transactions
  • Signing
  • Broadcasting

# gRPC

The principal usage of gRPC is in the context of module query services. The Cosmos SDK also exposes a few other module-agnostic gRPC services. One of them is the Tx service. The Tx service exposes a handful of utility functions such as simulating a transaction or querying a transaction and also one method to broadcast transactions (opens new window).

Sometimes looking at an example can be helpful. Take a closer look at this code example (opens new window).


Each gRPC method has its corresponding REST endpoint generated using gRPC-gateway. Rather than using gRPC, you can also use HTTP to broadcast the same transaction on the POST /cosmos/tx/v1beta1/txs endpoint.

Need an example? Check out this code example (opens new window).

# Tendermint RPC

The three methods presented above are higher abstractions on the Tendermint RPC /broadcast_tx_{async,sync,commit} endpoints. You can use the Tendermint RPC endpoints (opens new window) to directly broadcast the transaction through Tendermint if you wish to.

Tendermint supports the following RPC protocols:

  • URI over HTTP
  • JSONRPC over WebSockets

Want more information on broadcasting with Tendermint RPC? Why not take a closer look at the documentation on Tendermint RPC transactions broadcast APIs (opens new window)?

# Next up

In the next section), you can learn how transaction messages are generated and handled in the Cosmos SDK.

Previously, the ABCI application knew of a single transaction type: a checkers move with four int. This is no longer sufficient with multiple games. You need to conform to its Tx ways, which means that you have to create messages then placed in to a transaction.

Head to the section on messages) to learn how to do just that.