README
¶
Cosmos SDK
The Cosmos SDK is a modular, open-source blockchain SDK for building secure, high-performance Layer 1 chains with full customizability used by 200+ chains in production. Developers can use the Cosmos SDK to easily and quickly spin up custom blockchains that can natively interoperate.
The Cosmos SDK is tailored for building secure, sovereign application-specific blockchains. Developers building with the Cosmos SDK can use predefined modules that cover standard blockchain functionality or create custom modules for their specific use case. This composable architecture enables robust customization. The SDK provides abstractions for permissioning, governance, state management, account abstraction, tokenization processes, application logic, and more.
Cosmos SDK blockchains get interoperability out-of-the-box via a native integration with the Inter-Blockchain Communication Protocol (IBC). ibc-go is implemented as a Go module in the Cosmos SDK.
While the Cosmos SDK is plug-and-play with any consensus engine, we recommend using CometBFT for a fast, battle-tested, high-throughput, configurable BFT state machine. CometBFT is developed as part of the Cosmos Stack and its releases are updated alongside the SDK.
WARNING: The Cosmos SDK has mostly stabilized, but we are still making some breaking changes.
Quick Start
To learn how the Cosmos SDK works from a high-level perspective, see the Cosmos SDK High-Level Intro.
If you want to get started quickly and learn how to build on top of Cosmos SDK, visit Cosmos SDK Tutorials. You can also fork the tutorial's repository to get started building your own Cosmos SDK application.
Note: We advise to always use the latest maintained Go version for building Cosmos SDK applications.
Modules
The Cosmos SDK maintains a set of modules that can be included in your blockchain application. For more information on modules, see our introduction doc.
Enterprise Modules
In addition to the core SDK modules, we maintain enterprise-grade modules designed for specialized use cases such as permissioned networks and consortium chains. These modules are located in the enterprise/ directory and have different licensing terms than the core SDK.
Maintainers
Cosmos Labs maintains the core components of the stack: Cosmos SDK, CometBFT, IBC, Cosmos EVM, and various developer tools and frameworks. The detailed maintenance policy can be found here. In addition to developing and maintaining the Cosmos Stack, Cosmos Labs provides advisory and engineering services for blockchain solutions. Get in touch with Cosmos Labs.
Cosmos Labs is a wholly-owned subsidiary of the Interchain Foundation, the Swiss nonprofit responsible for treasury management, funding public goods, and supporting governance for Cosmos.
The Cosmos Stack is supported by a robust community of open-source contributors.
History
The Cosmos SDK was first released in 2019, and the first blockchain to use the SDK in production was the Cosmos Hub. Today, the Cosmos SDK is a popular, battle-tested, open-source framework used by hundreds of chains.
The Cosmos Hub still receives the most up-to-date Cosmos SDK versions. The Cosmos Hub application, gaia, has its own cosmos/gaia repository.
Developer Community and Support
The issue list of this repo is exclusively for bug reports and feature requests. We have active, helpful communities on Discord, Telegram, and Slack.
| Need Help? | Support & Community: Discord - Telegram - Talk to an Expert - Join the #Cosmos-tech Slack Channel |
Documentation and Resources
View the Cosmos SDK documentation: https://docs.cosmos.network/
Cosmos Stack Libraries
- CometBFT - High-performance, 10k+ TPS configurable BFT consensus engine.
- The Inter-Blockchain Communication Protocol (IBC) - A blockchain interoperability protocol that allows blockchains to transfer any type of data encoded in bytes.
- Cosmos EVM - Native EVM layer for Cosmos SDK chains.
Disambiguation
This Cosmos SDK project is not related to the React-Cosmos project (yet). Many thanks to Evan Coury and Ovidiu (@skidding) for this Github organization name. As per our agreement, this disambiguation notice will stay here.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
module
|
|
|
Deprecated.
|
Deprecated. |
|
testutil/mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
blockstm
module
|
|
|
grpc/cmtservice
Package cmtservice is a reverse proxy.
|
Package cmtservice is a reverse proxy. |
|
grpc/node
Package node is a reverse proxy.
|
Package node is a reverse proxy. |
|
grpc/reflection
Package reflection is a reverse proxy.
|
Package reflection is a reverse proxy. |
|
legacy
Package legacy contains a global amino Cdc which is deprecated but still used in several places within the SDK.
|
Package legacy contains a global amino Cdc which is deprecated but still used in several places within the SDK. |
|
types
Package types defines the InterfaceRegistry type as well as aliases for types that now live in the github.com/cosmos/gogoproto/types/any package for backwards compatibility with legacy code.
|
Package types defines the InterfaceRegistry type as well as aliases for types that now live in the github.com/cosmos/gogoproto/types/any package for backwards compatibility with legacy code. |
|
unknownproto
unknownproto implements functionality to "type check" protobuf serialized byte sequences against an expected proto.Message to report:
|
unknownproto implements functionality to "type check" protobuf serialized byte sequences against an expected proto.Message to report: |
|
container
module
|
|
|
contrib
|
|
|
api/cosmos/circuit/module/v1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
api/cosmos/circuit/v1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
api/cosmos/crisis/module/v1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
api/cosmos/crisis/v1beta1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
api/cosmos/nft/module/v1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
api/cosmos/nft/v1beta1
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
x/circuit/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
x/crisis/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
x/nft
Package nft is a reverse proxy.
|
Package nft is a reverse proxy. |
|
x/nft/internal/conv
Package conv provides internal functions for conversions and data manipulation
|
Package conv provides internal functions for conversions and data manipulation |
|
x/nft/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmovisor
module
|
|
|
hd
Package hd provides support for hierarchical deterministic wallets generation and derivation.
|
Package hd provides support for hierarchical deterministic wallets generation and derivation. |
|
keyring
Package keyring provides common key management API.
|
Package keyring provides common key management API. |
|
keys/bcrypt
Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm.
|
Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm. |
|
keys/internal/ecdsa
Package ECDSA implements Cosmos-SDK compatible ECDSA public and private key.
|
Package ECDSA implements Cosmos-SDK compatible ECDSA public and private key. |
|
keys/secp256r1
Package secp256r1 implements Cosmos-SDK compatible ECDSA public and private key.
|
Package secp256r1 implements Cosmos-SDK compatible ECDSA public and private key. |
|
db
module
|
|
|
depinject
module
|
|
|
enterprise
|
|
|
group
module
|
|
|
poa
module
|
|
|
poa/simapp
module
|
|
|
errors
module
|
|
|
iavl
|
|
|
iavlx
module
|
|
|
conv
Package conv provides internal functions for conversions and data manipulation
|
Package conv provides internal functions for conversions and data manipulation |
|
log
module
|
|
|
math
module
|
|
|
orm
module
|
|
|
The commands from the SDK are defined with `cobra` and configured with the `viper` package.
|
The commands from the SDK are defined with `cobra` and configured with the `viper` package. |
|
grpc/gogoreflection
Package gogoreflection implements gRPC reflection for gogoproto consumers the normal reflection library does not work as it points to a different singleton registry.
|
Package gogoreflection implements gRPC reflection for gogoproto consumers the normal reflection library does not work as it points to a different singleton registry. |
|
grpc/reflection/v2alpha1
Package v2alpha1 is a reverse proxy.
|
Package v2alpha1 is a reverse proxy. |
|
Package std defines all the common and standard inter-module Cosmos SDK types and definitions modules and applications can depend on.
|
Package std defines all the common and standard inter-module Cosmos SDK types and definitions modules and applications can depend on. |
|
store
module
|
|
|
tools/ics23
module
|
|
|
Package telemetry initializes OpenTelemetry global using the OpenTelemetry declarative configuration API.
|
Package telemetry initializes OpenTelemetry global using the OpenTelemetry declarative configuration API. |
|
registry
Package registry provides an instrument registry for telemetry instrumentation.
|
Package registry provides an instrument registry for telemetry instrumentation. |
|
util/diskio
Package diskio provides an implementation of the disk I/O metrics following the OpenTelemetry semantic conventions for system metrics specified here: https://opentelemetry.io/docs/specs/semconv/system/system-metrics/.
|
Package diskio provides an implementation of the disk I/O metrics following the OpenTelemetry semantic conventions for system metrics specified here: https://opentelemetry.io/docs/specs/semconv/system/system-metrics/. |
|
util/host
Package host provides a telemetry instrument wrapper for host-level metrics.
|
Package host provides a telemetry instrument wrapper for host-level metrics. |
|
util/runtime
Package runtime provides a telemetry instrument wrapper for Go runtime metrics.
|
Package runtime provides a telemetry instrument wrapper for Go runtime metrics. |
|
tests
module
|
|
|
cmdtest
Package cmdtest contains a framework for testing cobra Commands within Go unit tests.
|
Package cmdtest contains a framework for testing cobra Commands within Go unit tests. |
|
integration
Integration contains the integration test setup used for SDK modules.
|
Integration contains the integration test setup used for SDK modules. |
|
mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
network
Package network implements and exposes a fully operational in-process CometBFT test network that consists of at least one or potentially many validators.
|
Package network implements and exposes a fully operational in-process CometBFT test network that consists of at least one or potentially many validators. |
|
x/counter/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
tools
|
|
|
systemtests
module
|
|
|
bech32/legacybech32
Deprecated: The module provides legacy bech32 functions which will be removed in a future release.
|
Deprecated: The module provides legacy bech32 functions which will be removed in a future release. |
|
errors
Package errors provides a shared set of errors for use in the SDK, aliases functionality in the cosmossdk.io/errors module that used to be in this package, and provides some helpers for converting errors to ABCI response code.
|
Package errors provides a shared set of errors for use in the SDK, aliases functionality in the cosmossdk.io/errors module that used to be in this package, and provides some helpers for converting errors to ABCI response code. |
|
module
Package module contains application module patterns and associated "manager" functionality.
|
Package module contains application module patterns and associated "manager" functionality. |
|
tx
Package tx is a reverse proxy.
|
Package tx is a reverse proxy. |
|
Package version is a convenience utility that provides SDK consumers with a ready-to-use version command that produces apps versioning information based on flags passed at compile time.
|
Package version is a convenience utility that provides SDK consumers with a ready-to-use version command that produces apps versioning information based on flags passed at compile time. |
|
x
|
|
|
auth/ante/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
auth/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
auth/tx/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
auth/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
|
auth/vesting/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
authz
Package authz is a reverse proxy.
|
Package authz is a reverse proxy. |
|
authz/codec
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgGrant or MsgExec instance so that they can be (de)serialized properly.
|
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgGrant or MsgExec instance so that they can be (de)serialized properly. |
|
authz/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
bank/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
bank/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
consensus/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
consensus/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
distribution
Package distribution implements a Cosmos SDK module, that provides an implementation of the F1 fee distribution algorithm.
|
Package distribution implements a Cosmos SDK module, that provides an implementation of the F1 fee distribution algorithm. |
|
distribution/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
distribution/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
epochs/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
evidence
Package evidence implements a Cosmos SDK module, per ADR 009, that allows for the submission and handling of arbitrary evidence of misbehavior.
|
Package evidence implements a Cosmos SDK module, per ADR 009, that allows for the submission and handling of arbitrary evidence of misbehavior. |
|
evidence/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
evidence/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
feegrant
Package feegrant provides functionality for authorizing the payment of transaction fees from one account (key) to another account (key).
|
Package feegrant provides functionality for authorizing the payment of transaction fees from one account (key) to another account (key). |
|
feegrant/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
genutil
Package genutil contains a variety of genesis utility functionality for usage within a blockchain application.
|
Package genutil contains a variety of genesis utility functionality for usage within a blockchain application. |
|
genutil/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
gov/codec
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgSubmitProposal instance so that they can be (de)serialized properly.
|
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgSubmitProposal instance so that they can be (de)serialized properly. |
|
gov/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
gov/types/v1
Package v1 is a reverse proxy.
|
Package v1 is a reverse proxy. |
|
gov/types/v1beta1
Package v1beta1 is a reverse proxy.
|
Package v1beta1 is a reverse proxy. |
|
mint/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
mint/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
params
Package params provides a namespaced module parameter store.
|
Package params provides a namespaced module parameter store. |
|
params/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
params/types
To prevent namespace collision between consumer modules, we define a type Subspace.
|
To prevent namespace collision between consumer modules, we define a type Subspace. |
|
params/types/proposal
Package proposal is a reverse proxy.
|
Package proposal is a reverse proxy. |
|
protocolpool/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
protocolpool/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
simulation
Package simulation implements a full fledged Cosmos SDK application used for executing simulation test suites.
|
Package simulation implements a full fledged Cosmos SDK application used for executing simulation test suites. |
|
slashing/migrations/v1
Package v040 is copy-pasted from: https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/x/slashing/types/keys.go
|
Package v040 is copy-pasted from: https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/x/slashing/types/keys.go |
|
slashing/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
slashing/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
|
staking/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
staking/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
tx/internal/testpb
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
tx/signing/aminojson/internal/aminojsonpb
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
tx/signing/aminojson/internal/testpb
Code generated by protoc-gen-go-pulsar.
|
Code generated by protoc-gen-go-pulsar. |
|
tx/signing/textual/internal/cbor
Package cbor implements just enough of the CBOR (Concise Binary Object Representation, RFC 8948) to deterministically encode simple data.
|
Package cbor implements just enough of the CBOR (Concise Binary Object Representation, RFC 8948) to deterministically encode simple data. |
|
tx/signing/textual/internal/textualpb
Package textualpb contains all protobuf definitions and generated codes used internally by Textual.
|
Package textualpb contains all protobuf definitions and generated codes used internally by Textual. |
|
upgrade
Package upgrade provides a Cosmos SDK module that can be used for smoothly upgrading a live Cosmos chain to a new software version.
|
Package upgrade provides a Cosmos SDK module that can be used for smoothly upgrading a live Cosmos chain to a new software version. |
|
upgrade/internal/conv
Package conv provides internal functions for conversions and data manipulation
|
Package conv provides internal functions for conversions and data manipulation |
|
upgrade/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
circuit
module
|
|
|
group
module
|
|
|
nft
module
|
Click to show internal directories.
Click to hide internal directories.