The KERI suite represents a complex distributed system encompassing multiple interrelated specifications:

• KERI core protocol: Establishing autonomic identifiers through key event logs
• CESR (Composable Event Streaming Representation): Dual text-binary encoding for cryptographic primitives
• 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:

• Cryptographic security requirements: Ensuring post-quantum resistance, preventing replay attacks, maintaining duplicity detection
• Performance constraints: Stream processing requirements, bandwidth efficiency, computational overhead
• Interoperability goals: Cross-platform compatibility, multiple serialization format support
• Governance requirements: Decentralization mandates, witness consensus mechanisms

Decision

The core section stating:

• What decision was made
• Why this approach was chosen
• How it addresses the stated problem
• Alternatives that were considered and rejected

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
• Follow-on: Requires decisions about key generation entropy, digest algorithm selection, rotation cadence policies

References

Links to supporting materials:

• Relevant specifications or standards
• Academic papers or security analyses
• Implementation repositories
• Related ADRs
• Discussion threads or meeting notes

ADRs in Multi-Implementation Coordination

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:

1. Initial discussion: Problem identification in community forums (Slack, GitHub issues, working group meetings)
2. ADR proposal: Formal documentation of proposed solution with alternatives analysis
3. Review and refinement: Community feedback, security analysis, implementation feasibility assessment
4. ADR acceptance: Consensus on approach and rationale
5. Specification development: Formal protocol specification incorporating the decision
6. Implementation: Multiple implementations following the specification
7. 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:

• Revisiting decisions: Understanding why alternatives were rejected prevents rehashing settled debates
• 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
• 24-bit boundary alignment: Enabling clean text-binary conversion
• Stable code tables: Preserving forward compatibility
• 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
• Negative: Increased key management complexity, requires secure generation of pre-rotated keys
• 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

Consequences: Enables graduated disclosure, supports selective disclosure patterns, provides content integrity verification, requires careful serialization handling.

ADR: Witness Consensus Algorithm (KAACE)

Status: Accepted

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
• Configurable witness rotation

Consequences: Enables scalable distributed consensus, supports witness pool management, provides duplicity detection, requires careful threshold configuration.

ADR: ACDC Edge Operators (I2I, DI2I, NI2I)

Status: Accepted

Context: ACDCs form directed acyclic graphs requiring edge semantics that define authorization relationships between chained credentials.

Decision: Define three edge operators:

• I2I (Issuer-to-Issuee): Strict constraint requiring child issuer to be parent issuee
• DI2I (Delegated-Issuer-to-Issuee): Extends I2I to include delegates
• NI2I (Not-Issuer-to-Issuee): Permissive for reference without delegation

Consequences: Enables flexible authorization chains, supports both strict and permissive linking, requires clear operator semantics in ACDC schemas.

Integration with KERI Improvement Documents (KIDs)

The glossary distinguishes between ADRs and KERI Improvement Documents (KIDs):

ADRs focus on "why": The rationale for architectural decisions, alternatives considered, trade-offs accepted

KIDs focus on "how": Modular documentation of implementation approaches, procedures, and techniques

This separation allows:

• ADRs to remain stable: Once accepted, they document the reasoning that led to a decision
• KIDs to evolve: As implementation experience grows, procedures can be refined without reopening architectural debates
• Clear responsibility: Architecture teams focus on ADRs, implementation teams focus on KIDs

Together, ADRs and KIDs provide comprehensive documentation:

• For decision-makers: ADRs explain the "what and why"
• For implementers: KIDs explain the "how"
• For maintainers: Both provide context for future changes
• For auditors: Both demonstrate architectural rigor and implementation fidelity

Role in Protocol Specification Development

ADRs feed into the formal specification process for KERI and related protocols:

IETF Draft Specifications

The KERI suite includes multiple IETF internet drafts:

• draft-ssmith-keri (core KERI protocol)
• draft-ssmith-cesr (CESR encoding)
• draft-ssmith-acdc (ACDC credentials)
• draft-ssmith-said (SAID specification)
• draft-ssmith-oobi (OOBI discovery)

Each specification incorporates architectural decisions that would ideally be documented first as ADRs:

• Specification text: Normative requirements ("MUST", "SHOULD", "MAY")
• 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:

1. Permanent record of design rationale that persists even as team membership changes
2. Communication tool enabling coordination across multiple independent implementations
3. Governance artifact supporting policy alignment between technical capabilities and organizational requirements
4. Educational resource helping new contributors understand architectural philosophy
5. 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.