ADRs

Overview

Architecture Decision Records (ADRs) capture significant technical decisions with context, alternatives considered, and rationale. They live in docs/adr/ in the repository.

Design documents in docs/design/ serve a similar role for larger proposals that are still evolving. See Design Documents for those.

ADR Format

Each ADR follows a standard structure:

• Title: ADR-NNNN: <Decision Title>
• Date: When the decision was made
• Status: Draft | Proposed | Accepted | Deprecated | Superseded
• Context: Why the decision was needed
• Decision: What was decided
• Consequences: Trade-offs and implications

ADR Index

ADR-0001: Rejected State Management Approaches

• Status: Accepted
• Date: 2026-01-28
• Summary: Documents rejected state management approaches (Copy-on-Write Snapshots, Two-Level Dirty Tracking) with rationale for why each was rejected. Recommends lighter-weight alternatives that preserve deterministic behavior.
• Source: docs/adr/adr-0001-rejected-state-management-approaches.md

Design Documents

Larger proposals and design drafts live in docs/design/. Key documents include:

Document	Status	Summary
VM Architecture	Canonical	RV64 ISA, tiered execution, cross-contract calls, state model, precompiles
Architecture & Boundaries	Reference	Core/execution/storage/consensus layering and dependency DAG
State Layout	Draft	Logical state layout, StateBackend mapping, Blake3 BMT commitments
DKG	Draft	Per-epoch threshold BLS key generation with crash recovery
Private Mempool	Draft	Sealed transactions and precommit protocol to prevent front-running
Access Lists	Draft	State prefetching, warm/cold gas pricing, parallel scheduling hints
Light Client MMR	Draft	Trustless on-chain light client via SHA256 MMR and BLS verification
Block-STM Parallel Execution	Proposed	Speculative parallel tx execution with conflict detection
Cross-Contract Call Tracing	Proposed	Hierarchical tracing capturing call trees, storage ops, gas
JIT Compilation	Draft	Tiered JIT for hot contracts with deterministic semantics
Consensus-Execution Pipelining	Deferred	Overlap consensus N+1 with execution of N
Simulation Mode	Proposed	Execution in scratch space returning detailed state previews
Vault Gas Token	Draft	Vault-backed gas token with staking/governance isolation
Data Availability Sampling	Draft	DAS via Reed-Solomon erasure coding for light clients
Cranelift AOT/JIT	Proposed	Native codegen tier using Cranelift
Network Channels	Reference	P2P channel multiplexing for consensus, gossip, DKG, DA
ChainStore Hardening	Draft	Concurrent access and large chain improvements
VM Implementation Guidelines	Non-normative	Recommended resource limits and operational parameters
Gas Profiler Flame Graphs	Proposed	Interactive flame graphs for per-function gas analysis
DAP Debugger	Proposed	Debug Adapter Protocol integration for VS Code
Verkle Tree Migration	Research	Evaluation of Verkle trees; recommends deferring to late 2026
DKG Refactor Analysis	Analysis	Custom DKG vs Commonware primitives comparison

See Design Documents for links to the full archive.

Writing a New ADR

1. Create docs/adr/adr-NNNN-<slug>.md with the next available number.
2. Use the format described above.
3. Set status to Draft or Proposed.
4. Link the ADR from this index page.