DOCSEARCHbyAlgolia
Submit Docs

Cosmos SDK Developer Documentation

website·Indexed 40 days ago

https://docs.cosmos.network

Documentation for the Cosmos SDK, a Layer 1 blockchain stack used by over 200 production chains. It covers module design, ABCI (Application Blockchain Interface), state management via the Collections API, parallel transaction execution with Block-STM, and post-quantum security using ML-DSA keys. Includes guides on chain upgrades with Cosmovisor, remote signing best practices, and enterprise Proof of Authority (PoA) modules.

Tokens
715.4K
Snippets
2.9K
Records
4.7K
Agent score
73%

What's inside Cosmos SDK

  1. Overview of the Cosmos Blockchain Stack

    The Cosmos stack is a modular Layer 1 blockchain framework designed for building secure, high-performance blockchains. It allows developers to use pre-built components or integrate custom features for consensus, governance, and compliance. The stack is capable of processing up to 10,000 transactions per second and provides full control over blockchain infrastructure, including EVM compatibility.

  2. Overview of EIP-1559 Dynamic Fee Market

    The x/feemarket module implements EIP-1559 dynamic fee pricing for EVM transactions. This mechanism manages network congestion by automatically adjusting the base fee based on block gas utilization.

    Key Components:

    • Base Fee: An algorithmically determined fee per gas unit that is burned (deflationary).
    • Priority Fee (Tip): An optional additional fee paid directly to validators to incentivize transaction ordering.
    • Max Fee: The absolute maximum fee per gas a user is willing to pay.

    Fee Calculation: effective_gas_price = base_fee + priority_fee total_fee = gas_used * effective_gas_price

    Adjustment Logic:

    • If block gas usage > target: Base fee increases (up to 12.5% per block by default).
    • If block gas usage < target: Base fee decreases (down to 12.5% per block by default).
    • If block gas usage = target: Base fee remains constant.

  3. Overview of the IBC Routing Module

    The Routing Module is a default implementation of a secondary module that acts as an intermediary between the IBC protocol handler and individual modules on a host state machine. It simplifies the relayer's task by maintaining a lookup table of modules and routing external datagrams (packets and handshakes) to the appropriate module via a callback interface. It also functions as a module manager, controlling port binding and allocation logic.

  4. Overview of the Tendermint (CometBFT) IBC Light Client

    The Tendermint light client allows an IBC-enabled chain to track a counterparty running CometBFT consensus. It implements the IBC light client module interface to verify the state of the counterparty chain without storing full headers. Instead, it stores a compressed ConsensusState containing the AppHash (for verifying key/value pairs) and the NextValidatorsHash and Timestamp (to serve as the root of trust for future updates).

  5. Overview of the Collections storage layer

    Collections is a simplified storage layer for cosmos-sdk modules that leverages Go generics to standardize how state is handled. It removes the need for developers to manually define key-to-bytes and value-to-bytes formats, reducing boilerplate and errors associated with lexicographic ordering and namespace collisions. It is designed to be a lightweight, pure Go alternative to the SDK's ORM, avoiding the need for complex protobuf options or external tooling.

  6. Overview of Cosmos SDK node interfaces

    A Cosmos SDK node exposes several interfaces for interacting with the blockchain. Modules define their functionality using protobuf services, typically split into a Query service (for reading state) and a Msg service (for state changes via transactions).

  7. Overview of the Cosmos Stack architecture

    The Cosmos stack is a modular blockchain infrastructure designed for high throughput (10,000+ TPS) and fast finality. It separates the consensus and networking layers from the application business logic, allowing developers to build customizable, interoperable blockchains. The stack consists of several key layers: the Cosmos SDK for application logic, CometBFT for consensus, the IBC Protocol for cross-chain communication, and Cosmos EVM for Ethereum compatibility.

  8. Overview of the Cosmos SDK Transaction Lifecycle

    The Cosmos SDK transaction lifecycle is managed by the interaction between CometBFT (the consensus engine) and the SDK application (the state machine) via the Application Blockchain Interface (ABCI).

    • CometBFT: Responsible for ordering transactions, managing validators, and driving block production.
    • SDK Application (BaseApp + modules): Responsible for executing transactions and updating the chain's state.
    • ABCI: The protocol CometBFT uses to call methods on the SDK application to drive the block lifecycle.

  9. Overview of IBC Rate Limiting Middleware

    The Rate Limiting Middleware is a governance-configured tool that caps the net token flow across IBC transfers for ICS-20 fungible tokens. It protects a chain from draining faster than governance allows by measuring token movement over a specific path (identified by channel ID in IBC v1 or client ID in IBC v2) within a rolling time window. If a transfer would push the running total past the configured cap, the middleware rejects the transfer.

  10. Overview of SIGN_MODE_TEXTUAL

    SIGN_MODE_TEXTUAL is a text-based signing mode designed for hardware devices with limited processing and display capabilities. Unlike SIGN_MODE_DIRECT (which is binary-based), SIGN_MODE_TEXTUAL renders transactions into a sequence of human-readable 'screens'. This prevents 'blind signing' by allowing users to review transaction details on a small screen before signing.

    Note: This mode was removed in Cosmos SDK v0.55 and is now archived; the proto enum value is reserved.

  11. Overview of the ICS-008 Wasm Client

    The ICS-008 Wasm Client provides an interface for light clients stored as Wasm bytecode on a blockchain. This allows light clients to be dynamically upgradable without requiring hard forks of the blockchain binary and removes the dependency on the Go programming language, as clients can be written in any language targeting Wasm (e.g., Rust, C, C++). The Wasm Client Proxy acts as a pass-through to the Wasm contract, which implements the ICS-02 client semantics.

  12. Overview of IBC Chain Upgrades

    IBC-connected chains must be able to upgrade without breaking connections to other chains. While many upgrades are irrelevant to IBC, some can break counterparty clients. When a chain performs an IBC-client-breaking upgrade, it must execute an IBC upgrade process to allow counterparty clients to securely transition to the new light client version. This prevents the disruption of high-value IBC connections and allows the ecosystem to evolve.