DOCSEARCHbyAlgolia
Submit Docs

Cosmos SDK

repository·main·Indexed 27 days ago

https://github.com/cosmos/cosmos-sdk

A modular framework for building sovereign, high-performance Layer 1 blockchains with native IBC interoperability. It includes the Collections library for managing module state as typed Go objects (Map, KeySet, Item, Sequence, IndexedMap) and AutoCLI (client/v2), a Go library that automatically generates CLI commands and flags from gRPC service definitions.

Tokens
200.6K
Snippets
419
Records
1K
Agent score
92%

What's inside cosmos-sdk

  1. Overview of the Cosmos SDK

    main

    The Cosmos SDK is an open-source toolkit designed for building application-specific blockchains. It supports both multi-asset public Proof-of-Stake (PoS) blockchains and permissioned Proof-of-Authority (PoA) blockchains.

    Key features include:

    • Application-Specific Design: Unlike virtual-machine blockchains (e.g., Ethereum) that rely on smart contracts, the Cosmos SDK allows you to build a blockchain customized to a single application for optimal sovereignty, security, and performance.
    • Modularity: Developers can plug and play different layers for execution, consensus, settlement, and data availability. You can use the SDK with various consensus engines like CometBFT or Rollkit.
    • Composable Modules: You can use predefined modules (such as staking, governance, and token issuance) or build your own custom modules.
    • Capabilities-based Security: The system is designed to allow developers to reason about the security of interactions between modules using an object-capability model.

  2. Overview of Enterprise Modules

    main

    Enterprise modules are production-ready extensions for the Cosmos SDK designed for specialized use cases such as permissioned networks, consortium chains, and enterprise deployments. Unlike the core Cosmos SDK modules which are licensed under Apache-2.0, enterprise modules may use different licenses (e.g., Source Available Evaluation License). Always check the specific LICENSE file in the module directory before use.

    Available Modules

    • Proof of Authority (PoA): Implements a PoA consensus mechanism with admin-controlled validator sets, fee distribution, and governance integration.
    • Group: Enables on-chain multisig accounts and group-based governance with configurable decision policies (threshold or percentage-based).

  3. Overview of the x/distribution module

    main

    The x/distribution module provides a passive mechanism for distributing rewards (such as multi-token fees and inflated staked asset provisions) between validators and delegators.

    Key Characteristics:

    • Passive/Lazy Distribution: Rewards are pooled globally and divided out lazily. This means rewards are not sent to every account every block, but are calculated and withdrawn when specific actions occur.
    • Reward Types: It handles multi-token fees, inflated staked asset provisions, and validator commissions on delegator rewards.
    • Withdrawal Requirements: Due to the nature of lazy accounting, certain actions trigger a mandatory full withdrawal of rewards to ensure consistency:
      • Bonding, unbonding, or re-delegating tokens.
      • When a validator changes their commission rate.
      • Whenever withdrawing, one must withdraw the maximum amount entitled to, leaving nothing in the pool.

  4. Overview of the x/epochs module

    main

    The x/epochs module provides a generalized interface for other SDK modules to execute logic at fixed time intervals (epochs). It defines on-chain timers that trigger events at specific intervals (e.g., once a day or once a week).

    Key Concepts:

    • Epoch: The period between two timer ticks.
    • Timer Ticks: A timer ticks at the first block whose block time is greater than the timer's end time. If the chain is offline, it will tick once per block until it catches up to the current time.
    • Identifiers: Every timer has a unique identifier. On mainnet, the default is a one day interval.

  5. Overview of the x/circuit module

    main

    The x/circuit module (Circuit Breaker) is designed to prevent a chain from needing a full halt or shutdown in the presence of a vulnerability. Instead of halting the entire chain, the module allows specific message types (or all messages) to be disabled.

    Key features:

    • Granular Control: Disable specific Msg type URLs or all messages.
    • Permission System: Specific addresses can be granted rights to trip (disable) or reset (enable) the circuit breaker.
    • Two-point Validation: Transactions are checked via the CircuitBreakerDecorator (ante handler) and a message router check. Note that the ante handler may not check inner messages of a transaction, but the message router check will still catch and fail them.

  6. Overview of the crisis module

    main

    The x/crisis module is designed to halt the blockchain if a registered blockchain invariant is broken. Invariants are registered with the application during the initialization process.

    Note: x/crisis is deprecated as of Cosmos SDK v0.53 and will be removed in the next release.

  7. Overview of Cosmos SDK architecture

    main

    The Cosmos SDK is a modular, open-source framework for building sovereign, application-specific Layer 1 blockchains.

    Key architectural features include:

    • Modular Design: Use predefined modules for standard blockchain functionality or create custom modules for specific use cases.
    • Interoperability: Native integration with the Inter-Blockchain Communication Protocol (IBC) allows for out-of-the-box cross-chain communication.
    • Consensus Engine: While plug-and-play with any engine, it is highly recommended to use CometBFT for a high-throughput, configurable BFT state machine.
    • Abstractions: Provides built-in abstractions for permissioning, governance, state management, account abstraction, and tokenization.

  8. Overview of Cosmos SDK Node Endpoints

    main

    A Cosmos SDK node exposes three primary types of endpoints for interaction, each serving on a different default port. Note that all endpoints default to localhost and must be explicitly configured to be accessible over the public internet.

    • gRPC server: Default port 9090. Used for high-performance state queries and broadcasting transactions.
    • REST server: Default port 1317. Provides RESTful access to gRPC endpoints via gRPC-gateway, suitable for web applications.
    • CometBFT RPC endpoint: Default port 26657. Provides core consensus and networking functionality.

  9. Overview of Cosmos SDK Modules

    main

    The Cosmos SDK provides a variety of production-grade modules categorized by their role in a blockchain application. These include essential modules for core blockchain functionality, supplementary modules for extending capabilities, and enterprise modules for specialized use cases.

    Essential Modules

    These modules provide core behaviors required for users and operators:

    • Auth: Account and transaction authentication.
    • Bank: Token transfer functionalities.
    • Consensus: Modifies CometBFT's ABCI consensus parameters.
    • Distribution: Fee and staking token provision distribution.
    • Governance: On-chain proposals and voting.
    • Genutil: Genesis utilities.
    • Mint: Creation of new staking token units.
    • Slashing: Validator punishment mechanisms.
    • Staking: Proof-of-Stake layer.
    • Upgrade: Software upgrade handling and coordination.
    • Evidence: Handling for double signing and misbehavior.

    Supplementary Modules

    Modules used to extend or specialize blockchain capabilities:

    • Authz: Account authorization for performing actions on behalf of others.
    • Epochs: Timed ticker logic for SDK modules.
    • Feegrant: Fee allowances for transaction execution.

    Enterprise Modules

    Located in the enterprise/ directory, these modules use different licenses than the Apache 2.0 core SDK.

    • PoA (Proof of Authority): Admin-controlled validator sets for permissioned networks with governance integration.

  10. Overview of the x/nft module

    main

    The x/nft module is a Cosmos SDK implementation that allows for the creation, transfer, and management of Non-Fungible Tokens (NFTs). It is designed to be fully compatible with the Ethereum ERC721 specification.

    Note: This package is not actively maintained by Interchain Labs.

  12. Overview of the System Test framework

    main

    The System Tests package provides a black-box testing framework that sets up a local multi-node blockchain environment. It is designed to test the full stack via CLI and a running network, focusing on the critical path of the application.

    Key components include:

    • CLI: Command-line interface wrapper for interacting with the chain or keyring.
    • Servers: Server instances to run the blockchain environment.
    • Events: Event listeners.
    • RPC: Remote Procedure Call setup for communication.

    Dependencies include testify, gjson, and sjson. Server and client-side operations are executed on the host machine.