From 3674caf362334a85881c4b1d73d6cfa80a154625 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Thu, 12 Feb 2026 13:32:20 -0500 Subject: [PATCH 01/10] Create accounts.mdx --- sdk/v0.53/learn/concepts/accounts.mdx | 145 ++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 sdk/v0.53/learn/concepts/accounts.mdx diff --git a/sdk/v0.53/learn/concepts/accounts.mdx b/sdk/v0.53/learn/concepts/accounts.mdx new file mode 100644 index 00000000..cd2a2dbd --- /dev/null +++ b/sdk/v0.53/learn/concepts/accounts.mdx @@ -0,0 +1,145 @@ +--- +title: Accounts +--- + +Accounts represent identities on a Cosmos SDK chain. +They hold balances, authorize transactions with digital signatures, and prevent transaction replay using sequence numbers. + +Every account is controlled by a cryptographic keypair derived from a seed phrase. +A seed phrase yields one or more private keys, each of which produces a public key and an account address. + +## What is an account + +An account is an on-chain object that: + +- Holds one or more token balances +- Is identified by an address +- Signs transactions +- Tracks a sequence number + +Balances, the account number, and the sequence number are stored on-chain. The private key and seed phrase are never stored on-chain; they are kept locally by the user or wallet. + +An account does not execute logic itself. Instead, it authorizes transactions. When a transaction is submitted and accepted, the account's sequence number increases and its state, such as balances, may change. + +## Keys, seed phrases, and addresses + +Accounts are rooted in cryptographic keypairs. Cosmos SDK uses asymmetric cryptography, where a private key and public key form a pair. + +A private key is derived from a seed phrase using a deterministic algorithm. Cosmos wallets follow common standards such as: + +- BIP-39 (mnemonic phrases) + https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki +- BIP-32 (hierarchical deterministic wallets) + https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki +- BIP-44 (multi-account derivation paths) + https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki + +These standards define how a human-readable seed phrase is turned into a sequence of private keys. + +The private key remains secret. It is used to sign transactions. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. A public key cannot be used to recover the private key. + +An address is a shortened identifier derived from the public key. The public key is hashed and encoded, typically in Bech32 format, with a prefix that indicates the chain, for example `cosmos`. The address is what users share and what appears in state and transactions. + +At first use, a transaction includes a public key so that future signatures can be verified. Before that, the chain may know only the address. This separation is why accounts can be derived and displayed locally from a seed phrase even before any on-chain activity. + +Key relationships: + +``` +Seed Phrase + ↓ (BIP-39/BIP-32/BIP-44) +Private Key (secp256k1) + ↓ (elliptic curve math) +Public Key + ↓ (hash + Bech32 encoding) +Address +``` + +## Sequences and replay protection + +Each on-chain account tracks a sequence number. The sequence number starts at zero for a newly created account and increments by one after each successful transaction from that account. + +The sequence number exists to prevent replay attacks. A replay attack occurs when an old signed transaction is submitted a second time. Because the sequence number must be current, a previously signed transaction with an old sequence is rejected. + +Example: + +``` +Initial state: + sequence = 0 + +After first accepted transaction: + sequence = 1 + +After second accepted transaction: + sequence = 2 +``` + +If a signed transaction carries `sequence = 1` but the account's current sequence is `2`, the transaction is rejected. + +This ensures transactions are applied in order and cannot be reused. + +## Balances + +Accounts hold token balances. These balances are stored on-chain as part of account state. + +When tokens are sent from one account to another, balances are updated in state. Conceptually, a token transfer decreases the sender's balance and increases the recipient's balance. + +An account must have sufficient balance to cover: + +- The tokens being sent +- Any associated transaction fees + +If the balance is insufficient, the transaction is rejected during validation. + +--- + +## Types of accounts + +Cosmos SDK supports several account types that extend the base account model: + +- Base account: A standard account that holds balances and signs transactions. +- Module account: Owned by a module rather than a user. Modules use these accounts to manage tokens for protocol logic. +- Vesting account: Holds tokens that unlock gradually over time according to a schedule. + +All account types rely on the same key and address structure but may impose additional rules on balance usage. + +## Accounts and transactions + +Accounts authorize transactions. A transaction includes: + +- One or more messages +- A signature created using the private key +- A sequence number +- Fees + +During execution: + +1. The signature is verified using the public key. +2. The sequence number is checked. +3. Fees are deducted from the account's balance. +4. If execution succeeds, the sequence number increments and state updates are committed. + +High-level flow: + +``` +Seed Phrase + ↓ +Private Key + ↓ signs +Transaction + ↓ verified with +Public Key + ↓ identifies +Address + ↓ updates +State +``` + +Accounts provide identity and authorization. Transactions carry intent. +Modules execute logic. +State stores the result. + +## Summary + +Accounts are the foundation of user interaction with a Cosmos SDK chain. They connect cryptographic keys to on-chain identity, authorize transaction execution, and prevent replay attacks. Accounts also hold balances that change as transactions execute. + +Understanding keys, addresses, balances, and sequence numbers provides the basis for understanding transactions and execution, which are covered next. From d800cb23b391625d437afc97ce56ee803a9ef0f5 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:03:16 -0500 Subject: [PATCH 02/10] Create transactions.mdx --- sdk/v0.53/learn/concepts/transactions.mdx | 217 ++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 sdk/v0.53/learn/concepts/transactions.mdx diff --git a/sdk/v0.53/learn/concepts/transactions.mdx b/sdk/v0.53/learn/concepts/transactions.mdx new file mode 100644 index 00000000..82d77617 --- /dev/null +++ b/sdk/v0.53/learn/concepts/transactions.mdx @@ -0,0 +1,217 @@ +--- +title: Transactions, Messages, and Queries +--- + +In the previous section, you learned that accounts authorize activity on a chain using digital signatures and sequence numbers. Accounts provide identity and permission, but transactions are the actual mechanism that authorizes and executes logic on the chain. + +## Interacting with a chain + +A Cosmos SDK blockchain is a deterministic state machine. Its state changes only when transactions are executed and committed in blocks. + +Users and applications interact with the blockchain in two fundamental ways: + +- **Transactions** modify state and are included in blocks. When a user wants to **change** something (transfer tokens, delegate stake, submit a governance proposal), they submit a transaction. +- **Queries** read state and are not included in blocks. When a user wants to **inspect** something (check a balance, view delegations, read proposal details), they perform a query. + +Only transactions affect consensus state. + +## Transactions + +A **transaction** is a signed container that carries one or more actions to be executed on the blockchain. + +A transaction includes: + +- Messages - one or more actions you want to execute (send tokens, delegate stake, vote on a proposal) +- Signatures - cryptographic proof that you authorize these actions +- Sequence number - prevents someone from resubmitting your transaction (replay protection) +- Gas limit - the maximum computational resources you're willing to spend +- Fees - what you pay for the transaction to be processed + +The transaction itself does not define business logic. Instead, it packages intent (messages) to change state, proves authorization (signatures), and specifies execution limits (gas and fees). You can think of a transaction as an envelope you send to the blockchain, with a message inside containing instructions, a signature to prove authenticity, and a stamp to pay for postage. + +\``` +Transaction + ├── Message 1 + ├── Message 2 + ├── ... + ├── Signature(s) + ├── Sequence + ├── Gas limit + └── Fees +\``` + +In the Cosmos SDK, account metadata and transaction authorization are handled by the `x/auth` module. Transaction construction and encoding are configured through the SDK’s transaction system (commonly via `x/auth/tx`). + +## Messages + +A **message** (`sdk.Msg`) is the actual instruction inside a transaction. Each message is defined by a specific module and represents a single action. Messages are located in that module's `types` package (like `x/bank/types` or `x/staking/types`). Modules define which messages they support and the rules for executing them. While the transaction provides the envelope with signatures and fees, the message defines the specific action to execute. + +Examples include `MsgSend` (transfer tokens), `MsgDelegate` (delegate stake), and `MsgVote` (vote on proposals). + +If a transaction contains multiple messages, they execute in order. The transaction only succeeds if all messages execute successfully; it is an atomic unit. + +## How messages are defined + +Messages in the Cosmos SDK are defined in each module's `types.proto` file using **Protocol Buffers (protobuf)**, which provides deterministic serialization, backward compatibility, and cross-language support. Each message is defined in a `.proto` file that specifies its fields, data types, and unique identifiers. From this schema, code is generated that allows the message to be constructed, serialized, and validated. + +Here's what an actual transaction looks like in JSON format: + +```json +{ + "body": { + "messages": [ + { + "@type": "/cosmos.bank.v1beta1.MsgSend", + "from_address": "cosmos1...", + "to_address": "cosmos1...", + "amount": [{"denom": "uatom", "amount": "1000000"}] + } + ], + "memo": "", + "timeout_height": "0", + "extension_options": [], + "non_critical_extension_options": [] + }, + "auth_info": { + "signer_infos": [ + { + "public_key": { + "@type": "/cosmos.crypto.secp256k1.PubKey", + "key": "A..." + }, + "mode_info": {"single": {"mode": "SIGN_MODE_DIRECT"}}, + "sequence": "0" + } + ], + "fee": { + "amount": [{"denom": "uatom", "amount": "500"}], + "gas_limit": "200000", + "payer": "", + "granter": "" + } + }, + "signatures": ["MEUCIQDx..."] +} +``` + +This transaction transfers 1 ATOM (1,000,000 uatom) from one account to another. You can see the message in the `body.messages` array, the sender's public key and sequence in `auth_info.signer_infos`, the fee and gas limit in `auth_info.fee`, and the cryptographic signature in the `signatures` array. + +When broadcast, this JSON is serialized into bytes using protobuf, ensuring every validator interprets the transaction identically. + +## Message order and atomicity + +When a transaction contains multiple messages, they are executed **in the order they appear** in the transaction. + +Order matters. + +For example, a transaction might: + +1. Send tokens to another account. +2. Delegate those tokens to a validator. + +If the order were reversed, the delegation could fail due to insufficient balance. + +Messages inside a transaction are applied sequentially. The transaction succeeds only if all messages execute successfully. + +Conceptually: + +\``` +Transaction + ├── Msg 1 → execute + ├── Msg 2 → execute + ├── Msg 3 → execute +\``` + +If any message fails, the entire transaction fails, and none of its state changes are committed. + +Transactions behave as atomic units: they either fully succeed or fully fail. + +--- + +## Blocks and state transitions + +A blockchain can be understood as a sequence of blocks. Each block contains an ordered list of transactions. + +When a new block is committed: + +1. Each transaction in the block is applied to the current state. +2. Each transaction executes its messages in order. +3. Modules update their portion of state. +4. The resulting state becomes the starting point for the next block. + +Conceptually: + +\``` +State₀ + ↓ apply Block 1 (Tx₁, Tx₂, Tx₃) +State₁ + ↓ apply Block 2 (Tx₄, Tx₅) +State₂ + ↓ apply Block 3 (...) +State₃ +\``` + +In this way, the blockchain is a deterministic sequence of state transitions driven entirely by transactions. + +Blocks group transactions. Transactions drive execution. Execution updates state. + +--- + + +--- + +## What is a query? + +A **query** retrieves data from the blockchain’s state without modifying it. + +Queries: + +- Are read-only +- Do not require signatures +- Are not included in blocks +- Do not change consensus state + +Modules define query services using protobuf. These services are exposed over gRPC (and REST via a gateway). + +For example: + +- Query an account’s balance (`x/bank`) +- Query staking delegations (`x/staking`) +- Query governance proposal details (`x/gov`) + +--- + +## How everything fits together + + + + + + + + + + +
Transaction FlowQuery Flow
+
User
+  ↓ signs
+Transaction
+  ↓ contains
+Message(s)
+  ↓ handled by
+Module(s)
+  ↓ update
+State
+ 		+
User
+  ↓
+Query
+  ↓
+Module
+  ↓
+State (read-only)
+
+ +Transactions modify the blockchain. Messages define what modifications occur. Modules execute those modifications in order. Queries allow anyone to observe the resulting state. + +The next section follows a transaction from broadcast through validation, block inclusion, execution, and state commitment to show how these components work together in practice. From dc6a4e6783fe9bfdc54651b803a64d600b7e944d Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:03:18 -0500 Subject: [PATCH 03/10] Update accounts.mdx --- sdk/v0.53/learn/concepts/accounts.mdx | 108 +++++++++++++++----------- 1 file changed, 63 insertions(+), 45 deletions(-) diff --git a/sdk/v0.53/learn/concepts/accounts.mdx b/sdk/v0.53/learn/concepts/accounts.mdx index cd2a2dbd..2f7f5434 100644 --- a/sdk/v0.53/learn/concepts/accounts.mdx +++ b/sdk/v0.53/learn/concepts/accounts.mdx @@ -2,30 +2,44 @@ title: Accounts --- -Accounts represent identities on a Cosmos SDK chain. -They hold balances, authorize transactions with digital signatures, and prevent transaction replay using sequence numbers. +In [Blockchain Architecture](/sdk/v0.53/learn/intro/sdk-app-architecture), you learned that transactions change state and must be signed and validated. But who creates and signs these transactions? The answer is accounts. -Every account is controlled by a cryptographic keypair derived from a seed phrase. -A seed phrase yields one or more private keys, each of which produces a public key and an account address. +Accounts represent identities on a Cosmos SDK chain. They hold balances, authorize transactions with digital signatures, and prevent transaction replay using sequence numbers. Accounts are managed by the auth module (`x/auth`), which tracks account metadata like addresses, public keys, account numbers, and sequence numbers. + +Every account is controlled by a cryptographic keypair derived from a seed phrase. A seed phrase yields one or more private keys, each of which produces a public key and an account address. ## What is an account -An account is an on-chain object that: +An account is a container for a user's balances and a way to authorize transactions. + +It is an on-chain object that: - Holds one or more token balances - Is identified by an address - Signs transactions - Tracks a sequence number -Balances, the account number, and the sequence number are stored on-chain. The private key and seed phrase are never stored on-chain; they are kept locally by the user or wallet. +The account's balances, account number, and sequence number are all stored on-chain. The private key and seed phrase are never stored on-chain; they are kept locally by the user or wallet. + +An account does not execute logic itself; instead, it authorizes transactions. When a transaction is submitted and accepted, the account's sequence number increases and its state, such as balances, may change. + +## Public and private keys + +Accounts are rooted in cryptographic keypairs. Cosmos SDK uses asymmetric cryptography, where a private key and public key form a pair. This is a fundamental concept in cryptography and is used to secure data and transactions. + +- A **private key** is used to sign transactions. Before signing, the transaction data is serialized and hashed; the private key then produces a digital signature over this hash. This signature proves ownership of the private key without revealing it. Private keys must always remain secret. -An account does not execute logic itself. Instead, it authorizes transactions. When a transaction is submitted and accepted, the account's sequence number increases and its state, such as balances, may change. +- a **public key** is an identifying piece of information that is derived mathmatically from the private key. It is used to verify that a message was signed by the private key associated with the public key and is used to identify the account. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. Because the public key is derived from the private key through a one-way function, it is not possible to derive the private key from the public key. -## Keys, seed phrases, and addresses +## Seed phrases -Accounts are rooted in cryptographic keypairs. Cosmos SDK uses asymmetric cryptography, where a private key and public key form a pair. +Most wallets do not generate raw private keys directly. Instead, they start from a seed phrase (mnemonic), a list of human-readable words such as: -A private key is derived from a seed phrase using a deterministic algorithm. Cosmos wallets follow common standards such as: +``` text +apple maple river stone cloud frame picnic ladder jungle orbit solar velvet +``` + +A private key is then derived from the seed phrase using a deterministic algorithm. Cosmos wallets follow common standards such as: - BIP-39 (mnemonic phrases) https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki @@ -34,15 +48,13 @@ A private key is derived from a seed phrase using a deterministic algorithm. Cos - BIP-44 (multi-account derivation paths) https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki -These standards define how a human-readable seed phrase is turned into a sequence of private keys. - -The private key remains secret. It is used to sign transactions. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. A public key cannot be used to recover the private key. +From the seed phrase, a binary seed is computed and used to derive a master private key. From that master key, specific private keys are derived along a path (for example: `m/44'/118'/0'/0/0`, where `118` is the Cosmos coin type). Each private key produces a public key. -An address is a shortened identifier derived from the public key. The public key is hashed and encoded, typically in Bech32 format, with a prefix that indicates the chain, for example `cosmos`. The address is what users share and what appears in state and transactions. +Control of the seed phrase means control of the derived private keys and therefore control of the corresponding accounts. Losing the seed phrase without backing it up means losing access to the account forever. -At first use, a transaction includes a public key so that future signatures can be verified. Before that, the chain may know only the address. This separation is why accounts can be derived and displayed locally from a seed phrase even before any on-chain activity. +## Addresses -Key relationships: +An address is a shortened identifier derived from the public key. The public key is hashed and encoded, typically in Bech32 format, with a prefix that indicates the chain, for example `cosmos`. This address is what users share and what appears in state and transactions. ``` Seed Phrase @@ -54,11 +66,21 @@ Public Key Address ``` +An address is not the same thing as a public key. The address is derived from the public key, but it does not reveal the public key directly. + +When an account receives tokens for the first time, only the address is needed. The chain can credit balances to that address without knowing the public key. + +The public key is typically revealed on-chain the first time the account signs a transaction. That first transaction includes the public key so validators can verify the signature. After that, the chain stores the public key alongside the account metadata. + +This separation between address and public key is important: it allows accounts to be derived and displayed locally from a seed phrase before any on-chain activity. Users can generate addresses offline and receive funds without ever submitting a transaction. The account only needs to be initialized on-chain when the user sends their first transaction. + ## Sequences and replay protection Each on-chain account tracks a sequence number. The sequence number starts at zero for a newly created account and increments by one after each successful transaction from that account. -The sequence number exists to prevent replay attacks. A replay attack occurs when an old signed transaction is submitted a second time. Because the sequence number must be current, a previously signed transaction with an old sequence is rejected. +The sequence number exists to prevent replay attacks, which occur when an old signed transaction is submitted a second time. Because the sequence number must be current, a previously signed transaction with an old sequence is rejected. + +Sequence numbers also ensure transactions from a single account execute in a specific order, which matters when transactions depend on each other (for example, sending tokens then immediately staking them). Example: @@ -73,50 +95,48 @@ After second accepted transaction: sequence = 2 ``` -If a signed transaction carries `sequence = 1` but the account's current sequence is `2`, the transaction is rejected. - -This ensures transactions are applied in order and cannot be reused. +If a signed transaction carries `sequence = 1` but the account's current sequence is `2`, the transaction is rejected, ensuring that transactions are applied in order and cannot be reused. ## Balances -Accounts hold token balances. These balances are stored on-chain as part of account state. +Accounts are associated with token balances stored on-chain. Balances are managed by the bank module (`x/bank`) and indexed by account address. While account metadata (address, public key, sequence number) is stored in the auth module's state, token balances are stored separately in the bank module's state. -When tokens are sent from one account to another, balances are updated in state. Conceptually, a token transfer decreases the sender's balance and increases the recipient's balance. +When tokens are sent from one account to another, the bank module updates balances in state. Conceptually, a token transfer decreases the sender's balance and increases the recipient's balance. -An account must have sufficient balance to cover: - -- The tokens being sent -- Any associated transaction fees - -If the balance is insufficient, the transaction is rejected during validation. - ---- +An account must have sufficient balance to cover the tokens being sent and any associated transaction fees. If the balance is insufficient, the transaction is rejected during validation. ## Types of accounts Cosmos SDK supports several account types that extend the base account model: -- Base account: A standard account that holds balances and signs transactions. -- Module account: Owned by a module rather than a user. Modules use these accounts to manage tokens for protocol logic. -- Vesting account: Holds tokens that unlock gradually over time according to a schedule. +- **Base account**: A standard account that holds balances and signs transactions. This is the most common account type for users. + +- **Module account**: Owned by a module rather than a user. Module accounts are derived from the module name and cannot be controlled by a private key. For example, the staking module uses a module account to hold all delegated tokens, and the distribution module uses a module account to hold rewards before they are distributed. This design allows protocol logic to custody tokens without requiring a private key holder, which is essential for decentralized operations. + +- **Vesting account**: Holds tokens that unlock gradually over time according to a schedule. Vesting accounts are often used for team allocations or investor tokens that vest over months or years. They restrict spending to only unlocked tokens while still allowing the account to participate in staking and governance. All account types rely on the same key and address structure but may impose additional rules on balance usage. -## Accounts and transactions +## Accounts and transaction authorization -Accounts authorize transactions. A transaction includes: +Accounts authorize transactions by producing digital signatures. + +A transaction includes: - One or more messages - A signature created using the private key - A sequence number -- Fees +- Associated fees + +When a transaction is signed, the transaction bytes are serialized and hashed. The private key then generates a digital signature over that hash. This signature proves that the holder of the private key approved the transaction, without revealing the private key itself. During execution: -1. The signature is verified using the public key. -2. The sequence number is checked. -3. Fees are deducted from the account's balance. -4. If execution succeeds, the sequence number increments and state updates are committed. +1. The signature is verified using the account’s public key. +2. The sequence number is checked against the account’s current sequence. +3. Fees are deducted from the account’s balance. +4. If validation passes, messages execute and may update state. +5. If execution succeeds, the sequence number increments and state updates are committed. High-level flow: @@ -134,12 +154,10 @@ Address State ``` -Accounts provide identity and authorization. Transactions carry intent. -Modules execute logic. -State stores the result. +Accounts provide identity and authorization, transactions carry intent, and modules execute the logic. The result is stored in state. ## Summary -Accounts are the foundation of user interaction with a Cosmos SDK chain. They connect cryptographic keys to on-chain identity, authorize transaction execution, and prevent replay attacks. Accounts also hold balances that change as transactions execute. +Accounts are the foundation of user interaction with a Cosmos SDK chain. They connect cryptographic keys to on-chain identity, authorize transaction execution, and prevent replay attacks. -Understanding keys, addresses, balances, and sequence numbers provides the basis for understanding transactions and execution, which are covered next. +Understanding keys, addresses, balances, and sequence numbers provides the basis for understanding how transactions flow through the system. The next page, [Transaction Lifecycle](/sdk/v0.53/learn/beginner/tx-lifecycle), follows a transaction from creation through mempool admission, consensus, and execution to show how accounts interact with the broader blockchain architecture. From 3cea7f52a5cc161477b7a72e24761155182584dd Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:03:22 -0500 Subject: [PATCH 04/10] Update docs.json --- docs.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs.json b/docs.json index cca526a2..7df8ee08 100644 --- a/docs.json +++ b/docs.json @@ -183,6 +183,12 @@ "sdk/v0.53/learn/beginner/gas-fees" ] }, + { + "group": "Concepts", + "pages": [ + "sdk/v0.53/learn/concepts/accounts" + ] + }, { "group": "In-depth Concepts", "pages": [ From 2d41124fe052b0d07383edace9422b8a963e7e13 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:04:08 -0500 Subject: [PATCH 05/10] Update docs.json --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 7df8ee08..6f8810b4 100644 --- a/docs.json +++ b/docs.json @@ -186,7 +186,8 @@ { "group": "Concepts", "pages": [ - "sdk/v0.53/learn/concepts/accounts" + "sdk/v0.53/learn/concepts/accounts", + "sdk/v0.53/learn/concepts/transactions" ] }, { From 28cba589b2f47df623aba7c9e38f25e5a2ddd4c0 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 13 Feb 2026 17:11:08 -0500 Subject: [PATCH 06/10] Update transactions.mdx --- sdk/v0.53/learn/concepts/transactions.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/sdk/v0.53/learn/concepts/transactions.mdx b/sdk/v0.53/learn/concepts/transactions.mdx index 82d77617..b5ca901e 100644 --- a/sdk/v0.53/learn/concepts/transactions.mdx +++ b/sdk/v0.53/learn/concepts/transactions.mdx @@ -102,8 +102,6 @@ When broadcast, this JSON is serialized into bytes using protobuf, ensuring ever When a transaction contains multiple messages, they are executed **in the order they appear** in the transaction. -Order matters. - For example, a transaction might: 1. Send tokens to another account. @@ -111,7 +109,7 @@ For example, a transaction might: If the order were reversed, the delegation could fail due to insufficient balance. -Messages inside a transaction are applied sequentially. The transaction succeeds only if all messages execute successfully. +At execution time, messages inside a transaction are applied sequentially. The transaction succeeds only if all messages execute successfully. Conceptually: From 9056816506f4b528b9b3dd226c9c28df6fb24b56 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Wed, 18 Feb 2026 11:58:43 -0500 Subject: [PATCH 07/10] Address review comments on accounts.mdx - Clarify that accounts store identity fields, not balances; show BaseAccount struct - Explain that modules like x/bank and staking associate state with account addresses - Fix "for the first time" phrasing in Addresses section --- sdk/v0.53/learn/concepts/accounts.mdx | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/sdk/v0.53/learn/concepts/accounts.mdx b/sdk/v0.53/learn/concepts/accounts.mdx index 2f7f5434..51e08fde 100644 --- a/sdk/v0.53/learn/concepts/accounts.mdx +++ b/sdk/v0.53/learn/concepts/accounts.mdx @@ -10,18 +10,22 @@ Every account is controlled by a cryptographic keypair derived from a seed phras ## What is an account -An account is a container for a user's balances and a way to authorize transactions. - -It is an on-chain object that: +An account is an on-chain identity used to authorize transactions. Each account stores an address, a public key, an account number, and a sequence number: + +```go +type BaseAccount struct { + Address string + PubKey *anypb.Any + AccountNumber uint64 + Sequence uint64 +} +``` -- Holds one or more token balances -- Is identified by an address -- Signs transactions -- Tracks a sequence number +Accounts can be used in other modules to associate on-chain state with an identity. For example, the bank module (`x/bank`) maps account addresses to token balances, and the staking module maps them to delegations. -The account's balances, account number, and sequence number are all stored on-chain. The private key and seed phrase are never stored on-chain; they are kept locally by the user or wallet. +The private key and seed phrase are never stored on-chain; they are kept locally by the user or wallet. -An account does not execute logic itself; instead, it authorizes transactions. When a transaction is submitted and accepted, the account's sequence number increases and its state, such as balances, may change. +An account does not execute logic itself; instead, it authorizes transactions. When a transaction is submitted and accepted, the account's sequence number increases. Balance changes are handled by the modules that process the transaction's messages. ## Public and private keys @@ -68,7 +72,7 @@ Address An address is not the same thing as a public key. The address is derived from the public key, but it does not reveal the public key directly. -When an account receives tokens for the first time, only the address is needed. The chain can credit balances to that address without knowing the public key. +To receive tokens, only the address is needed. The chain can credit balances to that address without knowing the public key. The public key is typically revealed on-chain the first time the account signs a transaction. That first transaction includes the public key so validators can verify the signature. After that, the chain stores the public key alongside the account metadata. From 3b31d94e45ee563fc128eaf011f5ef8a84d55f63 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Wed, 18 Feb 2026 12:00:06 -0500 Subject: [PATCH 08/10] Address review comments on accounts.mdx - Clarify that accounts store identity fields, not balances; show BaseAccount struct - Explain that modules like x/bank and staking associate state with account addresses - Fix "for the first time" phrasing in Addresses section --- sdk/v0.53/learn/concepts/accounts.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sdk/v0.53/learn/concepts/accounts.mdx b/sdk/v0.53/learn/concepts/accounts.mdx index 51e08fde..4b6acd14 100644 --- a/sdk/v0.53/learn/concepts/accounts.mdx +++ b/sdk/v0.53/learn/concepts/accounts.mdx @@ -14,10 +14,10 @@ An account is an on-chain identity used to authorize transactions. Each account ```go type BaseAccount struct { - Address string - PubKey *anypb.Any - AccountNumber uint64 - Sequence uint64 + Address string `protobuf:"bytes,1,opt,name=address,proto3" json:"address,omitempty"` + PubKey *anypb.Any `protobuf:"bytes,2,opt,name=pub_key,json=pubKey,proto3" json:"pub_key,omitempty"` + AccountNumber uint64 `protobuf:"varint,3,opt,name=account_number,json=accountNumber,proto3" json:"account_number,omitempty"` + Sequence uint64 `protobuf:"varint,4,opt,name=sequence,proto3" json:"sequence,omitempty"` } ``` From efe84e4f739fcc3fbbf42825f324d96a120e6e92 Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 20 Feb 2026 13:03:29 -0500 Subject: [PATCH 09/10] Update transactions.mdx --- sdk/v0.53/learn/concepts/transactions.mdx | 58 ++++++++++------------- 1 file changed, 24 insertions(+), 34 deletions(-) diff --git a/sdk/v0.53/learn/concepts/transactions.mdx b/sdk/v0.53/learn/concepts/transactions.mdx index b5ca901e..bdc08589 100644 --- a/sdk/v0.53/learn/concepts/transactions.mdx +++ b/sdk/v0.53/learn/concepts/transactions.mdx @@ -21,14 +21,15 @@ A **transaction** is a signed container that carries one or more actions to be e A transaction includes: -- Messages - one or more actions you want to execute (send tokens, delegate stake, vote on a proposal) -- Signatures - cryptographic proof that you authorize these actions -- Sequence number - prevents someone from resubmitting your transaction (replay protection) -- Gas limit - the maximum computational resources you're willing to spend -- Fees - what you pay for the transaction to be processed +- Messages: one or more actions you want to execute (send tokens, delegate stake, vote on a proposal) +- Signatures: cryptographic proof that you authorize these actions +- Sequence number: prevents someone from resubmitting your transaction (replay protection) +- Gas limit: the maximum computational resources you're willing to spend +- Fees: what you pay for the transaction to be processed The transaction itself does not define business logic. Instead, it packages intent (messages) to change state, proves authorization (signatures), and specifies execution limits (gas and fees). You can think of a transaction as an envelope you send to the blockchain, with a message inside containing instructions, a signature to prove authenticity, and a stamp to pay for postage. + \``` Transaction ├── Message 1 @@ -40,21 +41,21 @@ Transaction └── Fees \``` -In the Cosmos SDK, account metadata and transaction authorization are handled by the `x/auth` module. Transaction construction and encoding are configured through the SDK’s transaction system (commonly via `x/auth/tx`). +In the Cosmos SDK, account metadata and transaction authorization are handled by the `x/auth` module. Transaction construction and encoding are configured through the SDK's transaction system (commonly via `x/auth/tx`). ## Messages A **message** (`sdk.Msg`) is the actual instruction inside a transaction. Each message is defined by a specific module and represents a single action. Messages are located in that module's `types` package (like `x/bank/types` or `x/staking/types`). Modules define which messages they support and the rules for executing them. While the transaction provides the envelope with signatures and fees, the message defines the specific action to execute. -Examples include `MsgSend` (transfer tokens), `MsgDelegate` (delegate stake), and `MsgVote` (vote on proposals). +Examples include `MsgSend` (transfer tokens), `MsgDelegate` (delegate stake), and `MsgVote` (vote on proposals). If a transaction contains multiple messages, they execute in order. The transaction only succeeds if all messages execute successfully; it is an atomic unit. -## How messages are defined +### How messages are defined -Messages in the Cosmos SDK are defined in each module's `types.proto` file using **Protocol Buffers (protobuf)**, which provides deterministic serialization, backward compatibility, and cross-language support. Each message is defined in a `.proto` file that specifies its fields, data types, and unique identifiers. From this schema, code is generated that allows the message to be constructed, serialized, and validated. +Messages in the Cosmos SDK are defined in each module's `tx.proto` file using **Protocol Buffers (protobuf)**, which provides deterministic serialization, backward compatibility, and cross-language support. Each message is defined in a `.proto` file that specifies its fields, data types, and unique identifiers. From this schema, code is generated that allows the message to be constructed, serialized, and validated. -Here's what an actual transaction looks like in JSON format: +Here's an example of a transaction in JSON format: ```json { @@ -98,7 +99,7 @@ This transaction transfers 1 ATOM (1,000,000 uatom) from one account to another. When broadcast, this JSON is serialized into bytes using protobuf, ensuring every validator interprets the transaction identically. -## Message order and atomicity +### Message order and atomicity When a transaction contains multiple messages, they are executed **in the order they appear** in the transaction. @@ -124,9 +125,11 @@ If any message fails, the entire transaction fails, and none of its state change Transactions behave as atomic units: they either fully succeed or fully fail. ---- + +In v0.53, transactions support an optional **unordered** mode. When `unordered=true`, the sequence number is bypassed and replay protection is handled via a `timeout_timestamp` instead. This enables fire-and-forget and concurrent transaction submission without coordinating sequence numbers. Unordered transactions must have a `timeout_timestamp` set and a sequence of `0`. + -## Blocks and state transitions +## Blocks and transactions A blockchain can be understood as a sequence of blocks. Each block contains an ordered list of transactions. @@ -151,35 +154,22 @@ State₃ In this way, the blockchain is a deterministic sequence of state transitions driven entirely by transactions. -Blocks group transactions. Transactions drive execution. Execution updates state. - ---- - +Blocks group transactions, transactions drive execution, and execution updates state. ---- - -## What is a query? - -A **query** retrieves data from the blockchain’s state without modifying it. +## Queries -Queries: +A **query** retrieves data from the blockchain's state without modifying it. -- Are read-only -- Do not require signatures -- Are not included in blocks -- Do not change consensus state - -Modules define query services using protobuf. These services are exposed over gRPC (and REST via a gateway). +Queries are read-only. They don't require signatures, aren't included in blocks, and don't affect consensus state. Modules define query services using protobuf, exposed over gRPC and REST. For example: -- Query an account’s balance (`x/bank`) -- Query staking delegations (`x/staking`) -- Query governance proposal details (`x/gov`) +- Query an account's balance (the `x/bank` module) +- Query staking delegations (the `x/staking` module) +- Query governance proposal details (the `x/gov` module) ---- -## How everything fits together +## Transaction and query flow From 26e3168f324d900ad71c22a81479fae16cc647ca Mon Sep 17 00:00:00 2001 From: Evan <87997759+evanorti@users.noreply.github.com> Date: Fri, 20 Feb 2026 13:03:30 -0500 Subject: [PATCH 10/10] Update accounts.mdx --- sdk/v0.53/learn/concepts/accounts.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/sdk/v0.53/learn/concepts/accounts.mdx b/sdk/v0.53/learn/concepts/accounts.mdx index 4b6acd14..69010b67 100644 --- a/sdk/v0.53/learn/concepts/accounts.mdx +++ b/sdk/v0.53/learn/concepts/accounts.mdx @@ -10,7 +10,7 @@ Every account is controlled by a cryptographic keypair derived from a seed phras ## What is an account -An account is an on-chain identity used to authorize transactions. Each account stores an address, a public key, an account number, and a sequence number: +An account is an on-chain identity used to authorize transactions. Each account stores an address, a public key, an account number, and a sequence number, as defined by [`BaseAccount`](https://github.com/cosmos/cosmos-sdk/blob/v0.53.0/x/auth/types/auth.pb.go#L32) in the `x/auth` module: ```go type BaseAccount struct { @@ -31,9 +31,9 @@ An account does not execute logic itself; instead, it authorizes transactions. W Accounts are rooted in cryptographic keypairs. Cosmos SDK uses asymmetric cryptography, where a private key and public key form a pair. This is a fundamental concept in cryptography and is used to secure data and transactions. -- A **private key** is used to sign transactions. Before signing, the transaction data is serialized and hashed; the private key then produces a digital signature over this hash. This signature proves ownership of the private key without revealing it. Private keys must always remain secret. +- A **private key** is used to sign transactions. Before signing, the transaction data is serialized and hashed; the private key then produces a digital signature over this hash. This signature proves ownership of the private key without revealing it. Private keys must always remain secret. -- a **public key** is an identifying piece of information that is derived mathmatically from the private key. It is used to verify that a message was signed by the private key associated with the public key and is used to identify the account. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. Because the public key is derived from the private key through a one-way function, it is not possible to derive the private key from the public key. +- a **public key** is an identifying piece of information that is derived mathematically from the private key. It is used to verify that a message was signed by the private key associated with the public key and is used to identify the account. The corresponding public key is derived mathematically from the private key and is used by the network to verify those signatures. Because the public key is derived from the private key through a one-way function, it is not possible to derive the private key from the public key. ## Seed phrases @@ -82,7 +82,7 @@ This separation between address and public key is important: it allows accounts Each on-chain account tracks a sequence number. The sequence number starts at zero for a newly created account and increments by one after each successful transaction from that account. -The sequence number exists to prevent replay attacks, which occur when an old signed transaction is submitted a second time. Because the sequence number must be current, a previously signed transaction with an old sequence is rejected. +The sequence number exists to prevent replay attacks, which occur when an old signed transaction is submitted a second time.} Because the sequence number must be current, a previously signed transaction with an old sequence is rejected.} Sequence numbers also ensure transactions from a single account execute in a specific order, which matters when transactions depend on each other (for example, sending tokens then immediately staking them). @@ -136,9 +136,9 @@ When a transaction is signed, the transaction bytes are serialized and hashed. T During execution: -1. The signature is verified using the account’s public key. -2. The sequence number is checked against the account’s current sequence. -3. Fees are deducted from the account’s balance. +1. The signature is verified using the account's public key. +2. The sequence number is checked against the account's current sequence. +3. Fees are deducted from the account's balance. 4. If validation passes, messages execute and may update state. 5. If execution succeeds, the sequence number increments and state updates are committed. @@ -162,6 +162,6 @@ Accounts provide identity and authorization, transactions carry intent, and modu ## Summary -Accounts are the foundation of user interaction with a Cosmos SDK chain. They connect cryptographic keys to on-chain identity, authorize transaction execution, and prevent replay attacks. +Accounts are the foundation of user interaction with a Cosmos SDK chain. They connect cryptographic keys to on-chain identity, authorize transaction execution, and prevent replay attacks. Understanding keys, addresses, balances, and sequence numbers provides the basis for understanding how transactions flow through the system. The next page, [Transaction Lifecycle](/sdk/v0.53/learn/beginner/tx-lifecycle), follows a transaction from creation through mempool admission, consensus, and execution to show how accounts interact with the broader blockchain architecture.