# Transactions

synopsis

In this section you will dive into the various functions and features of making transactions in Cosmos:

  • Transactions and Messages
  • Signing Transactions
  • Generating Transactions
  • Broadcasting Transactions
  • Introducing the CLI
  • Introducing the gRPC service
  • Intruducing the REST API
  • Introducing the Tendermint RPC service

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 validator includes them in a block.
Broadcast the signed transaction using one of the available interfaces.

Deciding and signing are the main interactions of a user. Generating and broadcasting 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:

This function is different from the ValidateBasic (opens new window) functions for sdk.Msg, which perform basic validity checks on messages only. For example, runTX first runs ValidateBasic on each message when it checks a transaction created from the auth module. Then it runs the auth module's AnteHandler (opens new window), which calls ValidateBasic for the transaction itself.

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. It 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 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 correctly encode 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 previously.

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.

# CLI

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 other module-agnostic gRPC services. One of these is the Tx service, which 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 an example can be helpful. Look at this code example (opens new window).

# REST

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 another example? See this code example (opens new window).

# Tendermint RPC

The three methods presented previously 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 HTTP.
  • JSONRPC over WebSockets.

For more information on broadcasting with Tendermint RPC, see 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 expectations, which means that you must create messages which are then placed into a transaction.

See the section on messages) to learn how to do that.