Core Concepts
Messages, handlers, keepers, stores, and the security boundaries between modules.
Third-party documentation. This is independently authored analysis of the public Cosmos SDK codebase — not the official docs, and not reviewed or endorsed by the Cosmos SDK team.
Core Concepts
Four abstractions define module authorship in the SDK.
Messages and handlers
Everything a user does is a message — a protobuf-serialized struct carrying its own authorization data (typically a signer address). Each message type routes to exactly one module handler, which validates authority against state before mutating anything. There is no ambient permission: if the handler doesn't check the signer, no one will.
Keepers
A keeper is a module's state-access object — the only sanctioned way to read or write that module's stores. Keepers hold references to other modules' keepers they've been granted, forming an explicit, auditable dependency graph. This is the SDK's capability-security model: cross-module interaction happens through narrow, code-reviewed interfaces rather than open store access.
Stores
Persistent state lives in KV stores (plus indexed-key and memory variants) scoped by store key. Every access is gas-metered. Schema evolution is a versioning discipline: upgrades migrate genesis/state through registered migrators rather than mutating formats in place.
Genesis and migrations
Each module exports InitGenesis/ExportGenesis, making chain launches and state transfers declarative JSON round-trips. At a hard fork, the upgrade module coordinates switching to new application logic at a named height and running per-module store migrations — the mechanism behind every live app-chain upgrade.