tx

package
v0.52.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2024 License: Apache-2.0 Imports: 44 Imported by: 2,901

README

sidebar_position: 1

x/auth/tx

:::note 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.

It contains as well a depinject module and app module the registration of ante/post handler via runtime and tx validator via runtime/v2.

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.

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/tx_config.go#L25-L31

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

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/x/auth/tx/config.go#L22-L28

TxBuilder

https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/client/tx_config.go#L33-L50

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.

Depinject & App Module

The x/auth/tx/config contains a depinject module and app module. The depinject module is there to setup ante/post handlers on an runtime app (via baseapp options) and the tx validator on the runtime/v2 app (via app module). It as well outputs the TxConfig and TxConfigOptions for the app.

The app module is purely there for registering tx validators, due to the design of tx validators (tx validator belong to modules).

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 convenient 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 serialized 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"
}

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultSignModes = []signingtypes.SignMode{
	signingtypes.SignMode_SIGN_MODE_DIRECT,
	signingtypes.SignMode_SIGN_MODE_DIRECT_AUX,
	signingtypes.SignMode_SIGN_MODE_LEGACY_AMINO_JSON,
}

DefaultSignModes are the default sign modes enabled for protobuf transactions.

Functions

func DefaultJSONTxDecoder 

func DefaultJSONTxDecoder(addrCodec address.Codec, cdc codec.Codec, decoder *decode.Decoder) sdk.TxDecoder

DefaultJSONTxDecoder returns a default protobuf JSON TxDecoder using the provided Marshaler.

func DefaultJSONTxEncoder 

func DefaultJSONTxEncoder(cdc codec.Codec) sdk.TxEncoder

DefaultJSONTxEncoder returns a default protobuf JSON TxEncoder using the provided Marshaler.

func DefaultTxEncoder 

func DefaultTxEncoder() sdk.TxEncoder

DefaultTxEncoder returns a default protobuf TxEncoder using the provided Marshaler

func ModeInfoAndSigToSignatureData 

func ModeInfoAndSigToSignatureData(modeInfoPb *txv1beta1.ModeInfo, sig []byte) (signing.SignatureData, error)

ModeInfoAndSigToSignatureData converts a ModeInfo and raw bytes signature to a SignatureData or returns an error

func NewSignModeLegacyAminoJSONHandler added in v0.50.1 

func NewSignModeLegacyAminoJSONHandler() signing.SignModeHandler

NewSignModeLegacyAminoJSONHandler returns a new signModeLegacyAminoJSONHandler. Note: The public constructor is only used for testing. Deprecated: Please use x/tx/signing/aminojson instead.

func NewSigningHandlerMap added in v0.50.1 

func NewSigningHandlerMap(configOpts ConfigOptions) (*txsigning.HandlerMap, error)

NewSigningHandlerMap returns a new txsigning.HandlerMap using the provided ConfigOptions. It is recommended to use types.InterfaceRegistry in the field ConfigOptions.FileResolver as shown in NewTxConfigWithOptions but this fn does not enforce it.

func NewSigningOptions 

func NewSigningOptions(addressCodec, validatorAddressCodec address.Codec) *txsigning.Options

NewSigningOptions returns signing options used by x/tx. This includes account and validator address prefix enabled codecs.

func NewTxConfig 

func NewTxConfig(protoCodec codec.Codec, addressCodec, validatorAddressCodec address.Codec, enabledSignModes []signingtypes.SignMode, customSignModes ...txsigning.SignModeHandler,
) client.TxConfig

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 NewTxConfigWithOptions to provide a custom signing handler in case the sign mode is not supported by default (eg: SignMode_SIGN_MODE_EIP_191), or to enable SIGN_MODE_TEXTUAL.

We prefer to use depinject to provide client.TxConfig, but we permit this constructor usage. Within the SDK, this constructor is primarily used in tests, but also sees usage in app chains like: https://github.com/evmos/evmos/blob/719363fbb92ff3ea9649694bd088e4c6fe9c195f/encoding/config.go#L37

func NewTxConfigWithOptions added in v0.50.1 

func NewTxConfigWithOptions(protoCodec codec.Codec, configOptions ConfigOptions) (client.TxConfig, error)

NewTxConfigWithOptions returns a new protobuf TxConfig using the provided ProtoCodec, ConfigOptions and custom sign mode handlers. If ConfigOptions is an empty struct then default values will be used.

func NewTxServer 

func NewTxServer(clientCtx client.Context, simulate baseAppSimulateFn, interfaceRegistry codectypes.InterfaceRegistry) txtypes.ServiceServer

NewTxServer creates a new Tx service server.

func QueryTx added in v0.43.0 

func QueryTx(clientCtx client.Context, hashHexStr string) (*sdk.TxResponse, error)

QueryTx queries for a single transaction by a hash string in hex format. An error is returned if the transaction does not exist or cannot be queried.

func QueryTxsByEvents added in v0.43.0 

func QueryTxsByEvents(clientCtx client.Context, page, limit int, query, orderBy string) (*sdk.SearchTxsResult, error)

QueryTxsByEvents retrieves a list of paginated transactions from CometBFT's TxSearch RPC method given a set of pagination criteria and an events query. Note, the events query must be valid based on CometBFT's query semantics. An error is returned if the query or parsing fails or if the query is empty.

Note, if an empty orderBy is provided, the default behavior is ascending. If negative values are provided for page or limit, defaults will be used.

func RegisterGRPCGatewayRoutes 

func RegisterGRPCGatewayRoutes(clientConn gogogrpc.ClientConn, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes mounts the tx service's GRPC-gateway routes on the given Mux.

func RegisterTxService 

func RegisterTxService(
	qrt gogogrpc.Server,
	clientCtx client.Context,
	simulateFn baseAppSimulateFn,
	interfaceRegistry codectypes.InterfaceRegistry,
)

RegisterTxService registers the tx service on the gRPC router.

func SignatureDataToModeInfoAndSig 

func SignatureDataToModeInfoAndSig(data signing.SignatureData) (*tx.ModeInfo, []byte)

SignatureDataToModeInfoAndSig converts a SignatureData to a ModeInfo and raw bytes signature

Types

type ConfigOptions added in v0.50.1 

type ConfigOptions struct {
	// If SigningHandler is specified it will be used instead constructing one.
	// This option supersedes all below options, whose sole purpose are to configure the creation of
	// txsigning.HandlerMap.
	SigningHandler *txsigning.HandlerMap
	// EnabledSignModes is the list of sign modes that will be enabled in the txsigning.HandlerMap.
	EnabledSignModes []signingtypes.SignMode
	// If SigningContext is specified it will be used when constructing sign mode handlers. If nil, one will be created
	// with the options specified in SigningOptions.
	SigningContext *txsigning.Context
	// SigningOptions are the options that will be used when constructing a txsigning.Context and sign mode handlers.
	// If nil defaults will be used.
	SigningOptions *txsigning.Options
	// TextualCoinMetadataQueryFn is the function that will be used to query coin metadata when constructing
	// textual sign mode handler. This is required if SIGN_MODE_TEXTUAL is enabled.
	TextualCoinMetadataQueryFn textual.CoinMetadataQueryFn
	// CustomSignModes are the custom sign modes that will be added to the txsigning.HandlerMap.
	CustomSignModes []txsigning.SignModeHandler
	// ProtoDecoder is the decoder that will be used to decode protobuf transactions.
	ProtoDecoder sdk.TxDecoder
	// ProtoEncoder is the encoder that will be used to encode protobuf transactions.
	ProtoEncoder sdk.TxEncoder
	// JSONDecoder is the decoder that will be used to decode json transactions.
	JSONDecoder sdk.TxDecoder
	// JSONEncoder is the encoder that will be used to encode json transactions.
	JSONEncoder sdk.TxEncoder
}

ConfigOptions define the configuration of a TxConfig when calling NewTxConfigWithOptions. An empty struct is a valid configuration and will result in a TxConfig with default values.

type ExtensionOptionsTxBuilder 

type ExtensionOptionsTxBuilder interface {
	client.TxBuilder

	SetExtensionOptions(...*codectypes.Any)
	SetNonCriticalExtensionOptions(...*codectypes.Any)
}

ExtensionOptionsTxBuilder defines a TxBuilder that can also set extensions.

Source Files

View all Source files

Directories

Path Synopsis
Package testutil is a generated GoMock package.
 Package testutil is a generated GoMock package.

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.