From df4214a1530318918f3664a5a89e91154152f663 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juli=C3=A1n=20Toledano?= Date: Mon, 15 Jul 2024 13:11:14 +0200 Subject: [PATCH] docs(x/tx): add README (#20913) --- x/README.md | 9 +-- x/tx/README.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+), 4 deletions(-) create mode 100644 x/tx/README.md diff --git a/x/README.md b/x/README.md index 106d39ba1105..8aadbbf776f2 100644 --- a/x/README.md +++ b/x/README.md @@ -9,21 +9,22 @@ Here are some production-grade modules that can be used in Cosmos SDK applicatio * [Auth](./auth/README.md) - Authentication of accounts and transactions for Cosmos SDK applications. * [Authz](./authz/README.md) - Authorization for accounts to perform actions on behalf of other accounts. * [Bank](./bank/README.md) - Token transfer functionalities. +* [Circuit](./circuit/README.md) - Circuit breaker module for pausing messages. +* [Consensus](./consensus/README.md) - Consensus module for modifying CometBFT's ABCI consensus params. * [Distribution](./distribution/README.md) - Fee distribution, and staking token provision distribution. * [Epochs](./epochs/README.md) - Allow other modules to set that they would like to be signaled once every period * [Evidence](./evidence/README.md) - Evidence handling for double signing, misbehaviour, etc. * [Feegrant](./feegrant/README.md) - Grant fee allowances for executing transactions. +* [Genutil](./genutil/README.md) - Genesis utilities for the Cosmos SDK. * [Governance](./gov/README.md) - On-chain proposals and voting. * [Mint](./mint/README.md) - Creation of new units of staking token. +* [NFT](./nft/README.md) - NFT module implemented based on [ADR43](https://docs.cosmos.network/main/build/architecture/adr-043-nft-module). * [Params](./params/README.md) - Globally available parameter store. * [Protocolpool](./protocolpool/README.md) - Functionalities handling community pool funds. * [Slashing](./slashing/README.md) - Validator punishment mechanisms. * [Staking](./staking/README.md) - Proof-of-Stake layer for public blockchains. +* [tx](./tx/README.md) - Tx utilities for the Cosmos SDK. * [Upgrade](./upgrade/README.md) - Software upgrades handling and coordination. -* [NFT](./nft/README.md) - NFT module implemented based on [ADR43](https://docs.cosmos.network/main/build/architecture/adr-043-nft-module). -* [Consensus](./consensus/README.md) - Consensus module for modifying CometBFT's ABCI consensus params. -* [Circuit](./circuit/README.md) - Circuit breaker module for pausing messages. -* [Genutil](./genutil/README.md) - Genesis utilities for the Cosmos SDK. To learn more about the process of building modules, visit the [building modules reference documentation](https://docs.cosmos.network/main/building-modules/intro). diff --git a/x/tx/README.md b/x/tx/README.md new file mode 100644 index 000000000000..600981407ade --- /dev/null +++ b/x/tx/README.md @@ -0,0 +1,171 @@ +--- +sidebar_position: 1 +--- + +# x/tx + +## Abstract + +This document specifies the tx module of the Cosmos SDK. + +The package is a crucial component of the Cosmos SDK, providing essential functionality for handling transactions +within the Cosmos ecosystem. It offers support for transaction decoding, allowing for parsing and interpretation of +transaction data. The package implements compatibility with ADR-027 for application-defined raw transaction +serialization, ensuring proper field ordering and encoding. A key feature of the package is its implementation of +various signing handlers. These handlers provide different methods for generating sign bytes. It also includes APIs for +custom signer definitions, allowing developers to tailor the signing process to their specific needs. + +**Note**: `x/tx` is not a traditional Cosmos SDK module (it's not an AppModule). + +## Contents + +- [x/tx](#xtx) + - [Abstract](#abstract) + - [Contents](#contents) + - [Signing](#signing) + - [Key Features](#key-features) + - [Decode](#decode) + - [Key Features](#key-features-1) + - [DecodedTx](#decodedtx) + - [Class Diagram](#class-diagram) + - [Decode Sequence Diagram](#decode-sequence-diagram) + - [Disambiguation Note](#disambiguation-note) + - [Disclaimer](#disclaimer) + + +## Signing + +The signing package handles the process of providing the bytes to be signed for transactions. It provides a set of +interfaces and implementations for different signing modes and methods. + +In summary, the signing package is responsible for preparing the data to be signed according to different signing modes, +but doesn't handle the actual signing process (i.e., applying a cryptographic signature to these bytes). + +### Key Features +1. SignModeHandler Interface: this is the core interface that defines how different signing modes should be implemented. +2. SignModeHandler Implementations: + * [aminojson](https://github.com/cosmos/cosmos-sdk/blob/v0.50.7/docs/architecture/adr-020-protobuf-transaction-encoding.md#sign_mode_legacy_amino) + * [direct](https://github.com/cosmos/cosmos-sdk/blob/v0.50.7/docs/architecture/adr-020-protobuf-transaction-encoding.md#sign_mode_direct) + * [direct aux](https://github.com/cosmos/cosmos-sdk/blob/v0.50.7/docs/architecture/adr-020-protobuf-transaction-encoding.md#sign_mode_direct_aux) + * [textual](https://github.com/cosmos/cosmos-sdk/blob/v0.50.7/docs/architecture/adr-050-sign-mode-textual-annex1.md#adr-050-sign_mode_textual-annex-1-value-renderers) +3. Context: the signing Context provides necessary information for retrieving signers from messages and resolving protobuf types. +4. TxData and SignerData: these structures contain the necessary data for generating sign bytes. TxData includes transaction details, while SignerData contains information about the signer. +5. HandlerMap: a collection of SignModeHandlers, allowing the system to support multiple signing modes. + + +## Decode + +The decode package provides functionality for decoding raw transaction bytes into structured transaction data. It's +designed to work with transactions that follow the [ADR-027](https://github.com/cosmos/cosmos-sdk/blob/v0.50.7/docs/architecture/adr-027-deterministic-protobuf-serialization.md#adr-027-deterministic-protobuf-serialization) +specification for application-defined raw transaction serialization. + +### Key Features +1. Transaction Decoding: Parses raw transaction bytes into a structured `DecodedTx` object. +2. ADR-027 Compatibility: Ensures compatibility with the ADR-027 specification. +3. Unknown Field Handling: Rejects unknown fields in TxRaw and AuthInfo, while allowing non-critical unknown fields in TxBody. +4. Signer Extraction: Extracts and deduplicates signers from transaction messages. +5. Support for Dynamic Messages: Handles both protobuf dynamic messages and gogoproto messages. + +### DecodedTx + +`DecodedTx` is a struct that represents a decoded transaction by implementing `transaction.Tx`. It contains various +components of a transaction after it has been parsed from its raw bytes. Here's a breakdown of its structure: + +The `DecodedTx` struct has the following fields: +1. DynamicMessages: A slice of proto.Message interfaces, representing the transaction messages in a dynamic format. +2. Messages: A slice of gogoproto.Message interfaces, representing the transaction messages in the gogo protobuf format. +3. Tx: A pointer to a v1beta1.Tx struct, which represents the full transaction in the Cosmos SDK v1beta1 format. +4. TxRaw: A pointer to a v1beta1.TxRaw struct, representing the raw transaction data. +5. Signers: A slice of byte slices, containing the addresses of the transaction signers. +6. TxBodyHasUnknownNonCriticals: A boolean flag indicating whether the transaction body contains unknown non-critical fields. + +The DecodedTx struct also implements several methods to satisfy the `transaction.Tx` interface, such as `Hash()`, +`GetGasLimit()`, `GetMessages()`, `GetSenders()`, and `Bytes()`. These methods allow the DecodedTx to be used in places +where a transaction is expected. The purpose of this struct is to provide a comprehensive representation of a decoded +transaction, making it easier for other parts of the system to work with transaction data in a structured format. + +### Class Diagram + +```mermaid +classDiagram + class DecodedTx { + DynamicMessages: []proto.Message + Messages: []gogoproto.Message + Tx: *v1beta1.Tx + TxRaw: *v1beta1.TxRaw + Signers: [][]byte + TxBodyHasUnknownNonCriticals: bool + cachedHash: [32]byte + cachedBytes: []byte + cachedHashed: bool + Hash() [32]byte + GetGasLimit() (uint64, error) + GetMessages() ([]transaction.Msg, error) + GetSenders() ([][]byte, error) + Bytes() []byte + computeHashAndBytes() + } + + class Decoder { + signingCtx: *signing.Context + codec: gogoProtoCodec + Decode(txBytes []byte) (*DecodedTx, error) + } + + class Options { + SigningContext: *signing.Context + ProtoCodec: gogoProtoCodec + } + + class gogoProtoCodec { + <> + Unmarshal([]byte, gogoproto.Message) error + } + +DecodedTx --|> `transaction.Tx` : implements +Decoder ..> DecodedTx : creates +Decoder o-- `signing.Context` : uses +Decoder o-- gogoProtoCodec : uses +Options --* Decoder : used to create +``` + +### Decode Sequence Diagram + +```mermaid +sequenceDiagram + participant C as Client + participant D as Decoder + participant R as Raw (v1beta1.TxRaw) + participant B as Body (v1beta1.TxBody) + participant A as AuthInfo (v1beta1.AuthInfo) + participant T as Tx (v1beta1.Tx) + participant DT as DecodedTx + + C->>+D: Decode(txBytes) + D->>D: rejectNonADR027TxRaw(txBytes) + D->>D: RejectUnknownFieldsStrict(txBytes, raw) + D->>R: proto.Unmarshal(txBytes, &raw) + D->>D: RejectUnknownFields(raw.BodyBytes, body) + D->>B: proto.Unmarshal(raw.BodyBytes, &body) + D->>D: RejectUnknownFieldsStrict(raw.AuthInfoBytes, authInfo) + D->>A: proto.Unmarshal(raw.AuthInfoBytes, &authInfo) + D->>T: Create Tx + loop For each message in body.Messages + D->>D: Unmarshal dynamic message + D->>D: Unmarshal gogoproto message + D->>D: Get signers + end + D->>DT: Create DecodedTx + D-->>-C: Return DecodedTx +``` + +## Disclaimer + +It's important to clarify that `x/tx` is distinct from `x/auth/tx`: + +* `x/tx`: This package (the one described in this README) provides core transaction handling functionality. +* `x/auth/tx`: This is a separate package and is typically used in the context of building a complete tx is that is going to be broadcast in Cosmos SDK applications. + +When you see a "tx" module referenced in `app_config.go` or similar application configuration files, it refers to +`x/auth/tx`, not `x/tx` (as it's not an Appmodule). This naming similarity can be confusing, so it's crucial to pay +attention to the import paths and context when working with these packages. \ No newline at end of file