WIP Architecture doc #191
Open
WIP Architecture doc #191
+239
−73
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
aljo242
reviewed
Jan 30, 2026
aljo242
left a comment
aljo242
left a comment
There was a problem hiding this comment.
overall looks great - just left some nits
|
|
||
| ## Nodes and Daemons | ||
|
|
||
| A blockchain is made up of nodes, or participants in the blockchain network. Each node runs a daemon process (for example, `simd` for a chain built with SimApp) that includes both a CometBFT instance for consensus and networking, and a Cosmos SDK application for the state machine and execution logic. The daemon participates in networking, reaches consensus with other nodes, and executes transactions to update the application state. |
There was a problem hiding this comment.
Will folks know what simd or SimApp are?
Contributor
Author
There was a problem hiding this comment.
I'll make this clearer. Good suggestion
|
|
||
| ## CometBFT | ||
|
|
||
| CometBFT is a Byzantine Fault Tolerant consensus engine that provides fast, deterministic finality. It's used by Cosmos SDK blockchains to replicate the state machine across a decentralized network. |
Contributor
Author
There was a problem hiding this comment.
Yes, I'll link out in all of these sections
| As the driver of block production, CometBFT controls when the Cosmos SDK application is invoked. It calls the application through ABCI at specific points during block production to validate transactions for the mempool (CheckTx), to construct or evaluate block proposals (PrepareProposal and ProcessProposal), to execute finalized blocks (FinalizeBlock), and to persist state (Commit). The SDK application responds to these calls but cannot initiate them. This means CometBFT, not the SDK application, determines the timing and cadence of block production and state transitions. This ABCI boundary also prevents application logic from influencing consensus. | ||
|
|
||
|
|
||
| ```python |
Contributor
Author
There was a problem hiding this comment.
No, the syntax highlighter just adds some better color on the mintlify site if it's a python codeblock. Not necessary though.
|
|
||
| ### Block Lifecycle Methods | ||
|
|
||
| Modern Cosmos SDK applications (v0.50+) use ABCI 2.0, which provides several key methods that CometBFT calls at different points in the block lifecycle. |
There was a problem hiding this comment.
We probably should just not even mention older veersions of ABCI and assume this is the only paradigm that exists
| SDK v0.53 introduces **PreBlock** hooks, which run before BeginBlock. PreBlockers must be explicitly ordered using `SetOrderPreBlockers`. Some core modules (notably `x/auth`) require PreBlock execution; missing PreBlock wiring will cause runtime errors. | ||
| </Note> | ||
|
|
||
| {/* todo: talk about finality */} |
| - **[Keepers](#keepers)**: providing interfaces for accessing module state while enforcing access control. | ||
| - **[app.go](#baseapp-and-appgo)**: serving as the composition root that wires everything together. | ||
|
|
||
| SDK v0.53 supports both manual wiring in app.go and declarative runtime-based wiring via `runtime.AppBuilder`, which reduces boilerplate and provides clear dependency graphs. Modern SDK chains typically use Governance v1, where proposals are submitted via `MsgSubmitProposal` containing executable messages. |
There was a problem hiding this comment.
I want us to remove all mentions of runtime.AppBuilder and depinject
Co-authored-by: Alex | Cosmos Labs <alex@cosmoslabs.io>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
WIP
Overview of Cosmos SDK architecture: Comet, ABCI, SDK