A justified software design choice that addresses a functional or non-functional requirement that is architecturally significant, documented to provide rationale and context for future maintainers.
Related Concepts
No related concepts available
Comprehensive Explanation
Architectural Decision Record (ADR)
Definition and Core Characteristics
An Architectural Decision Record (ADR) is a documented software design choice that meets three essential criteria:
Justified: The decision includes explicit rationale explaining why this particular approach was selected over alternative options
Requirement-driven: Addresses either functional requirements (what the system must accomplish) or non-functional requirements (how the system should perform, including qualities like security, scalability, maintainability)
Architecturally significant: The decision has substantial impact on system structure, behavior, component interactions, or future development trajectory
ADRs follow the standard methodology defined by the broader software architecture community at adr.github.io, providing a lightweight yet rigorous documentation pattern for recording important technical decisions. This methodology has been adopted across numerous open-source projects and is particularly valuable in distributed development environments where design rationale must be preserved across time and team membership changes.
Context in KERI/ACDC Ecosystem
Within the KERI (Key Event Receipt Infrastructure) protocol ecosystem and ACDC (Authentic Chained Data Container) credential framework, ADRs serve as the canonical documentation mechanism for recording design decisions that shape protocol architecture. The Web of Trust terminology framework explicitly includes ADR as a foundational reference term, appearing in multiple glossary repositories including the main WOT-terms glossary, the vLEI-specific glossary, and archived terminology collections.
Role in Protocol Development
Implementation Notes
Documentation Practice
ADRs in the KERI ecosystem should follow the standard ADR template structure:
Decision: The change being proposed or implemented
Consequences: The resulting context after applying the decision
Governance Role
For GLEIFvLEI implementations, ADRs serve as the technical foundation supporting the vLEI Ecosystem Governance Framework, documenting how technical architecture implements governance requirements for Legal Entity credential issuance and verification.
Evolution and Versioning
ADRs are immutable once accepted - they are not updated but may be superseded by new ADRs. This creates an architectural decision history that helps developers understand how the system evolved and why certain patterns exist in the codebase.
The KERI suite represents a complex distributed system encompassing multiple interrelated specifications:
KERI core protocol: Establishing autonomic identifiers through key event logs
ACDC: Verifiable credential structures with chained provenance
SAID (Self-Addressing IDentifier): Content-addressable identifier scheme
OOBI (Out-Of-Band Introduction): Discovery mechanism for identifier resolution
IPEX (Issuance and Presentation EXchange): Credential exchange protocol
TEL (Transaction Event Log): Registry infrastructure for credential state
Each of these specifications involves numerous architectural decisions that require clear documentation of design rationale, alternative approaches considered, and trade-off analysis. ADRs provide the structured mechanism for capturing this decision-making process.
ADR Structure and Common Sections
While ADR formats can vary, the standard structure typically includes the following sections:
Status
Indicates the current state of the decision:
Proposed: Under consideration and review
Accepted: Approved for implementation
Superseded: Replaced by a later decision (with reference to superseding ADR)
Deprecated: No longer recommended but not formally replaced
Rejected: Considered but explicitly not adopted
Context
Describes the forces at play, including:
Problem statement: What challenge or requirement necessitates this decision
Constraints: Technical, organizational, or resource limitations
Assumptions: Environmental factors or prerequisites
Stakeholders: Parties affected by or interested in the decision
In KERI development, context sections frequently address:
For example, a KERI ADR might document the decision to use pre-rotation for key management rather than alternative approaches like hierarchical deterministic keys or key escrow systems. The decision section would explain how pre-rotation enables cryptographic commitment to future keys before they're exposed, providing forward security even if current keys are compromised.
Consequences
Documents the outcomes and implications:
Positive consequences: Benefits and capabilities enabled
Negative consequences: Limitations or costs introduced
Trade-offs: What is gained versus what is sacrificed
Follow-on decisions: What subsequent decisions this necessitates
In the pre-rotation example, consequences might include:
Positive: Enhanced security against key compromise, support for partial rotation, enables custodial key management
Negative: Increased complexity in key management, requirement to maintain pre-rotated key digests
Trade-offs: Security improvement at the cost of operational complexity
The KERI ecosystem includes multiple independent implementations across different programming languages:
KERIpy: Python reference implementation
KERIox: Rust implementation
KERIA: Cloud agent server in Python
Signify: Typescript/JavaScript client library
Cesride: Rust CESR implementation
ADRs play a critical role in ensuring architectural consistency across these implementations. When a core design decision is made—such as the choice to use self-addressing identifiers (SAIDs) for content addressability—the ADR documents not only the decision itself but the specific requirements that all implementations must satisfy.
For instance, an ADR documenting SAID requirements would specify:
Digest algorithms: Which hash functions are mandatory versus optional
Canonicalization rules: How data structures must be serialized before hashing
Collision handling: What constitutes a valid SAID and how to handle edge cases
Version compatibility: How SAID formats evolve while maintaining backward compatibility
This level of specification enables independent implementation teams to make consistent architectural choices without requiring continuous coordination.
Integration with Specification Processes
ADRs serve as a bridge between informal design discussions and formal specifications. The typical flow in KERI development proceeds:
Initial discussion: Problem identification in community forums (Slack, GitHub issues, working group meetings)
ADR proposal: Formal documentation of proposed solution with alternatives analysis
Review and refinement: Community feedback, security analysis, implementation feasibility assessment
ADR acceptance: Consensus on approach and rationale
Specification development: Formal protocol specification incorporating the decision
Implementation: Multiple implementations following the specification
Testing and validation: Interoperability testing confirming consistent behavior
The ADR remains as permanent documentation of the design rationale even after the specification is complete. This proves invaluable when:
Extending functionality: New features must respect constraints that motivated original decisions
Debugging unexpected behavior: Implementation issues sometimes trace to misunderstanding design intent
Onboarding contributors: New developers can understand architectural philosophy
Trade-Off Documentation in Cryptographic Protocols
Cryptographic protocol design inherently involves complex trade-offs. KERI's architecture explicitly acknowledges the security-cost-performance architecture trade-off that appears throughout the glossary. ADRs provide the formal mechanism for documenting these trade-offs.
Example: CESR Encoding Design
The decision to create CESR (Composable Event Streaming Representation) rather than using existing encoding formats represents a significant architectural decision. An ADR for this decision would document:
Context: KERI requires both human-readable text representations for debugging and compact binary representations for production, with the ability to convert concatenated primitives between domains without loss (the composability property).
Alternatives Considered:
Standard Base64: Human-readable but cannot preserve primitive boundaries in concatenated streams
Pure binary formats (CBOR, MessagePack): Compact but not human-readable
JSON with binary attachments: Requires complex framing
Existing hybrid formats: None provide text-binary composability for cryptographic primitives
Decision: Develop CESR with:
Self-framing primitives: Each primitive includes type, size, and value information
Count codes: Supporting group operations for efficient streaming
Consequences:
Positive: Achieves composability, enables pipeline processing, supports debugging in text domain while maintaining production efficiency in binary domain
Negative: Requires new implementation rather than leveraging existing libraries, introduces KERI-specific encoding format
Trade-offs: Development investment and format novelty versus achieving precise requirements
Example: Pre-Rotation Mechanism
KERI's pre-rotation mechanism represents another critical architectural decision:
Context: Key management must address both security (protection against key compromise) and recoverability (ability to regain control after compromise).
Alternatives Considered:
Hierarchical deterministic keys: Derive keys from master seed
Key escrow: Third-party key backup
Social recovery: Multi-party key reconstruction
Time-locked rotation: Automatic rotation on schedule
Decision: Implement pre-rotation with:
Cryptographic commitment: Next key digest included in current establishment event
Binding to current state: Next key commitment anchored before exposure
Rotation authority separation: Enables custodial signing without custodial rotation
Partial rotation: Supports reserve keys for enhanced security
Consequences:
Positive: Forward security, supports custodial delegation, enables rotation without current key exposure, provides quantum-resistant migration path
Trade-offs: Operational complexity versus security guarantees
ADR Lifecycle and Version Management
ADRs follow a lifecycle that reflects their role in architectural governance:
Creation Phase
ADRs are typically created when:
Major architectural decisions must be made
Alternative approaches exist requiring evaluation
Trade-offs need formal analysis and consensus
Implementation impact crosses multiple components or repositories
In KERI development, this often occurs during:
Protocol extension: Adding new event types or features
Security enhancement: Improving duplicity detection or witness consensus
Performance optimization: Balancing cryptographic strength with computational efficiency
Interoperability requirements: Supporting new serialization formats or transport protocols
Review and Approval
ADR review typically involves:
Technical review: Evaluating correctness and completeness
Security analysis: Identifying potential vulnerabilities or attack vectors
Implementation feasibility: Confirming approach is practical across implementations
Governance approval: Ensuring alignment with project principles and roadmap
For KERI, this process occurs through:
Working group meetings: Regular calls where proposals are discussed
GitHub pull requests: Formal review of ADR documents
Implementation prototyping: Proof-of-concept to validate approach
Specification integration: Incorporation into formal protocol specifications
Supersession and Evolution
As protocols evolve, ADRs may be superseded by newer decisions. The supersession process requires:
Clear reference: New ADR explicitly references the superseded ADR
Migration guidance: Documenting how to transition from old to new approach
Compatibility considerations: Whether old and new approaches can coexist
Deprecation timeline: If applicable, when the old approach will be removed
For example, if KERI were to adopt a new digest algorithm (such as upgrading from Blake3-256 to a quantum-resistant alternative), the ADR would document:
Why the change: Quantum computing threat timeline
Which algorithm: Selection rationale for specific quantum-resistant function
Migration path: How existing identifiers transition
Compatibility period: Duration of dual-algorithm support
Testing requirements: Validation that migration preserves identifier properties
Governance Integration
ADRs serve as artifacts in the KERI ecosystem's governance framework. The vLEI Ecosystem Governance Framework and related governance documents reference architectural decisions that affect credential issuance, verification, and revocation processes.
Decision Authority
Different classes of architectural decisions have different decision authorities:
Core protocol decisions (affecting KERI fundamentals like key event structure, signature schemes, or witness requirements):
Require broad community consensus
Must be documented in ADRs that become part of IETF draft specifications
Affect all implementations and adopters
Implementation decisions (specific to particular codebases or platforms):
May be decided by maintainer teams
Should be documented if they affect interoperability
Examples include database choice, API design, deployment architecture
Extension decisions (new capabilities that don't affect core protocol):
Can be proposed and implemented independently
Should be documented to enable consistent adoption
Examples include new ACDC schema types, TEL registry variations, IPEX message formats
Governance Framework ADRs
The vLEI ecosystem governance framework likely contains ADRs addressing:
Credential schema decisions:
Which fields are mandatory versus optional in QVI, LE, OOR, and ECR credentials
How to handle schema evolution and versioning
Requirements for schema namespace registry
Issuance policy decisions:
When solicited versus unsolicited issuance is appropriate
Requirements for identity verification by QVIs
Credential validity periods and renewal processes
Revocation mechanism decisions:
Whether to use public or blinded TELs for different credential types
Registry backer requirements and thresholds
Revocation verification requirements for relying parties
Delegation policy decisions:
When GLEIF delegates to QVIs versus issuing directly
How QVIs delegate to sub-issuers if permitted
Constraints on delegation depth and scope
Documentation Standards and Best Practices
Effective ADRs in the KERI ecosystem follow several best practices:
Clarity and Precision
Use canonical terminology: Reference the KERI/GLEIF glossary (459 canonical terms) to ensure consistent language
Define scope explicitly: Clearly state what is in-scope versus out-of-scope for the decision
Quantify when possible: Rather than "more secure" or "better performance," provide specific metrics or attack models
Completeness
Document all alternatives: Even options quickly dismissed should be mentioned with brief rationale
Identify assumptions: Make explicit any prerequisites or environmental assumptions
Link to supporting materials: Reference specifications, academic papers, implementation PRs, security analyses
Maintainability
Use stable identifiers: ADRs should have permanent identifiers (numbers or meaningful names) that don't change
Track relationships: Clearly indicate which ADRs are related, dependent, or superseding
Version appropriately: If an ADR needs significant revision, consider whether it should be superseded by a new ADR rather than modified
Examples from KERI Development
While the provided source documents don't include full text of specific ADRs, we can infer several ADR topics that would exist based on architectural decisions evident in the specifications:
ADR: Self-Addressing Identifier (SAID) Design
Status: Accepted
Context: KERI requires content-addressable identifiers that cryptographically bind to the content they identify, supporting both compact disclosure and full disclosure variants of ACDCs.
Decision: Implement SAIDs using:
Hash of serialized content including a placeholder for the SAID itself
Multiple digest algorithm support with derivation codes
Deterministic canonicalization rules for reproducible hashing
Support for both compact (SAID-only) and full content representations
Context: KERI requires distributed consensus among witnesses without blockchain or proof-of-work, supporting both direct mode (no witnesses) and indirect mode (witnessed) identifier operation.
Decision: Implement KERI's Agreement Algorithm for Control Establishment (KAACE) using:
Witness threshold configuration in establishment events
Receipt logs for witness attestations
Threshold of accountable duplicity (TOAD) for liability
ADR rationale: Why these requirements exist, what alternatives were considered
Implementation guidance: How to satisfy requirements (in KIDs or implementation documentation)
Trust Over IP Foundation Specifications
TOIP maintains specifications for:
ACDC (Trust Registry)
vLEI Governance Framework
IPEX protocol
These specifications also benefit from ADR documentation for decisions about:
Schema design: Why certain field structures were chosen
Message flows: Why certain exchange patterns are required
Security properties: Why specific cryptographic operations are mandated
Stakeholder Communication
ADRs serve as communication tools for diverse stakeholders:
For Implementers
Developers building KERI implementations need to understand:
What must be implemented: The decision and its requirements
Why it matters: Security properties or capabilities enabled
How to test: What behaviors validate correct implementation
ADRs provide this context beyond bare specification requirements.
For Adopters
Organizations deploying KERI-based systems need to understand:
Architecture implications: How decisions affect their use cases
Security guarantees: What properties they can rely upon
Configuration options: Where they have flexibility
ADRs explain the reasoning that shapes these aspects.
For Governance Bodies
Entities like GLEIF establishing governance frameworks need:
Technical foundation: Understanding protocol capabilities and limitations
Policy alignment: Confirming technical decisions support governance requirements
Risk assessment: Evaluating security properties and attack resistance
ADRs provide authoritative documentation of these technical foundations.
For Researchers and Auditors
Academic researchers and security auditors examining KERI require:
Design rationale: Understanding why specific approaches were chosen
Threat models: What attacks the system resists and how
Formal properties: What guarantees the architecture provides
ADRs document these considerations, often with references to supporting formal analysis.
Tooling and Automation
While the source documents don't detail specific ADR tooling, modern ADR practices often include:
ADR Management Tools
adr-tools: Command-line utilities for creating, linking, and searching ADRs
GitHub integration: Using issues, pull requests, and wikis for ADR development and review
Documentation generation: Automatically building ADR indices and cross-references
Validation and Consistency Checking
Template enforcement: Ensuring all ADRs include required sections
Link validation: Checking that ADR cross-references remain valid
Status tracking: Maintaining accurate status as decisions evolve
Conclusion
Architectural Decision Records represent a critical documentation practice for the KERI protocol ecosystem. They provide:
Permanent record of design rationale that persists even as team membership changes
Communication tool enabling coordination across multiple independent implementations
Governance artifact supporting policy alignment between technical capabilities and organizational requirements
Educational resource helping new contributors understand architectural philosophy
Audit trail demonstrating rigorous consideration of security and design alternatives
For expert developers implementing KERI systems, ADRs offer essential context that transforms specifications from prescriptive requirements into comprehensible architectures. They answer not just "what must I implement" but "why was this approach chosen" and "what alternatives were considered and rejected."
The 459 canonical terms in the KERI/GLEIF glossary represent architectural decisions—about terminology, yes, but also about conceptual frameworks and abstractions. Each significant term likely has associated architectural decisions that shaped its definition and role in the protocol. ADRs provide the formal mechanism for documenting and preserving this architectural knowledge as the KERI ecosystem continues to evolve.