Architecture Decision Records (ADR)
Overview
Architecture Decision Records (ADRs) were the primary mechanism used by the Cosmos SDK team to document significant architectural decisions from 2019 to 2023. While the ADR process is no longer actively used for new decisions, these historical documents remain valuable references for understanding the design rationale behind many core SDK features. An ADR captured a single architectural decision, addressing functional or non-functional requirements that were architecturally significant. These records formed the project’s decision log and served as a form of Architectural Knowledge Management.What Were ADRs?
ADRs documented implementation and design decisions that had already been discussed and agreed upon by the team. Unlike RFCs (Request for Comments) which facilitated discussion, ADRs recorded decisions that had already reached consensus through either:- Prior RFC discussions
- Synchronous team meetings
- Working group sessions
- Context on the relevant goals and current state
- Proposed changes to achieve those goals
- Analysis of pros and cons
- References to related work
- Implementation status and changelog
The ADR Lifecycle
The ADR process followed a defined lifecycle:- Consensus Building: Every ADR started with either an RFC or discussion where consensus was reached
- Documentation: A pull request was created using the ADR template
- Review: Project stakeholders reviewed the proposed architecture
- Acceptance: ADRs were merged regardless of outcome (accepted, rejected, or abandoned) to maintain historical record
- Supersession: ADRs could be superseded by newer decisions as the project evolved
Status Classifications
ADRs used a two-component status system:- Consensus Status: Draft → Proposed → Last Call → Accepted/Rejected → Superseded
- Implementation Status: Implemented or Not Implemented
Historical ADR Index
The complete collection of ADRs can be found in the Cosmos SDK repository. Below are some of the most significant ADRs that shaped the current SDK architecture:Core Architecture
- ADR 002: SDK Documentation Structure - Established documentation organization
- ADR 057: App Wiring - Introduced dependency injection system
- ADR 063: Core Module API - Defined module interface standards
State Management
- ADR 004: Split Denomination Keys - Optimized denomination storage
- ADR 062: Collections State Layer - Simplified state management
- ADR 065: Store V2 - Next generation storage layer
Protocol & Encoding
- ADR 019: Protocol Buffer State Encoding - Protobuf adoption for state
- ADR 020: Protocol Buffer Transaction Encoding - Protobuf for transactions
- ADR 027: Deterministic Protobuf Serialization - Ensuring determinism
Module System
- ADR 030: Authorization Module - Authorization framework
- ADR 029: Fee Grant Module - Fee abstraction
- ADR 031: Protobuf Msg Services - Message service pattern
Consensus & ABCI
- ADR 060: ABCI 1.0 - ABCI 1.0 integration
- ADR 064: ABCI 2.0 - ABCI 2.0 planning
Developer Experience
- ADR 058: Auto-Generated CLI - AutoCLI system
- ADR 055: ORM - Object-relational mapping
Why ADRs Matter
Although the formal ADR process is no longer active, these documents remain valuable because they:- Preserve Design Rationale: They explain not just what was built, but why specific design choices were made
- Document Trade-offs: They capture the pros and cons considered for each decision
- Show Evolution: They demonstrate how the SDK architecture evolved over time
- Provide Context: They help developers understand the historical context of current features
Current Decision Process
The Cosmos SDK team has transitioned to more agile decision-making processes, utilizing:- GitHub Discussions for community input
- Pull requests for implementation proposals
- Working groups for synchronous collaboration
- Direct implementation with iterative refinement
Additional Resources
- Complete ADR Archive - Full collection of all historical ADRs
- ADR Template - The template that was used for creating ADRs
- ADR Process Documentation - Detailed process that was followed