Skip to content

Commit 2072e7f

Browse files
qj0r9j0vc2qj0r9j0vc2
authored
Merge pull request #202 from decipherhub/docs/adr-013-commonware-aggregation
docs: add ADR-013 and implementation status
2 parents d8cebeb + 7355fc0 commit 2072e7f

14 files changed

+272
-1259
lines changed

‎docs/TASKS.md‎

Lines changed: 0 additions & 1231 deletions
This file was deleted.

‎docs/architecture/README.md‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -21,32 +21,39 @@ See [ADR-002](./adr-002-evm-native-execution.md) for the complete analysis.
2121

2222
| ADR | Title | Status |
2323
|-----|-------|--------|
24-
| [ADR-001](./adr-001-three-layer-architecture.md) | Three-Layer Architecture (DCL/CL/EL) | PROPOSED |
25-
| [ADR-002](./adr-002-evm-native-execution.md) | EVM-Native Execution with Embedded revm | PROPOSED |
26-
| [ADR-003](./adr-003-malachite-consensus.md) | Malachite Consensus Integration | PROPOSED |
27-
| [ADR-004](./adr-004-primary-worker-architecture.md) | Autobahn BFT with Worker Scaling | PROPOSED |
24+
| [ADR-001](./adr-001-three-layer-architecture.md) | Three-Layer Architecture (DCL/CL/EL) | IMPLEMENTED |
25+
| [ADR-002](./adr-002-evm-native-execution.md) | EVM-Native Execution with Embedded revm | IMPLEMENTED |
26+
| [ADR-003](./adr-003-malachite-consensus.md) | Malachite Consensus Integration | IMPLEMENTED |
27+
| [ADR-004](./adr-004-primary-worker-architecture.md) | Autobahn BFT with Worker Scaling | IMPLEMENTED |
2828

2929
### Cryptography & Networking
3030

3131
| ADR | Title | Status |
3232
|-----|-------|--------|
33-
| [ADR-005](./adr-005-dual-signatures.md) | Dual Signature Scheme (Ed25519 + BLS12-381) | PROPOSED |
34-
| [ADR-007](./adr-007-p2p-networking.md) | P2P Networking with Malachite | PROPOSED |
33+
| [ADR-005](./adr-005-dual-signatures.md) | Dual Signature Scheme (Ed25519 + BLS12-381) | IMPLEMENTED |
34+
| [ADR-007](./adr-007-p2p-networking.md) | P2P Networking with Malachite | IMPLEMENTED |
3535

3636
### EVM & Storage
3737

3838
| ADR | Title | Status |
3939
|-----|-------|--------|
40-
| [ADR-006](./adr-006-mempool-design.md) | Mempool Integration with Reth Transaction Pool | PROPOSED |
41-
| [ADR-008](./adr-008-json-rpc-interface.md) | JSON-RPC Interface | PROPOSED |
42-
| [ADR-009](./adr-009-staking-precompile.md) | Staking Precompile | PROPOSED |
43-
| [ADR-010](./adr-010-storage-design.md) | Storage Design | PROPOSED |
40+
| [ADR-006](./adr-006-mempool-design.md) | Mempool Integration with Reth Transaction Pool | IMPLEMENTED |
41+
| [ADR-008](./adr-008-json-rpc-interface.md) | JSON-RPC Interface | IMPLEMENTED |
42+
| [ADR-009](./adr-009-staking-precompile.md) | Staking Precompile | IMPLEMENTED |
43+
| [ADR-010](./adr-010-storage-design.md) | Storage Design | IMPLEMENTED |
44+
| [ADR-012](./adr-012-state-root-handling.md) | State Root Handling and Delayed Commitment | IMPLEMENTED |
4445

4546
### Operations
4647

4748
| ADR | Title | Status |
4849
|-----|-------|--------|
49-
| [ADR-011](./adr-011-configuration-operations.md) | Configuration and Operations | PROPOSED |
50+
| [ADR-011](./adr-011-configuration-operations.md) | Configuration and Operations | PARTIAL |
51+
52+
### Sync & Performance
53+
54+
| ADR | Title | Status |
55+
|-----|-------|--------|
56+
| [ADR-013](./adr-013-commonware-aggregation.md) | Commonware Aggregation for Fast Sync | PROPOSED |
5057

5158
## Architecture Overview
5259

@@ -162,7 +169,7 @@ Pipelining: Collect attestations for height N+1 while consensus runs for height
162169
## ADR Lifecycle
163170

164171
```
165-
DRAFT ──▶ PROPOSED ──▶ ACCEPTED ──▶ IMPLEMENTED
172+
DRAFT ──▶ PROPOSED ──▶ ACCEPTED ──▶ PARTIAL ──▶ IMPLEMENTED
166173
│
167174
└──▶ SUPERSEDED
168175
```
@@ -172,5 +179,6 @@ DRAFT ──▶ PROPOSED ──▶ ACCEPTED ──▶ IMPLEMENTED
172179
| DRAFT | ADR is being written |
173180
| PROPOSED | Ready for review |
174181
| ACCEPTED | Approved, implementation starting |
182+
| PARTIAL | Core components implemented, some features pending |
175183
| IMPLEMENTED | Fully implemented and tested |
176184
| SUPERSEDED | Replaced by newer ADR |

‎docs/architecture/adr-001-three-layer-architecture.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,30 @@
22

33
## Changelog
44

5-
* 2025-12-06: Initial draft
5+
* 2026-02-01: Added implementation status
6+
* 2025-12-13: Enhanced with architecture diagram
7+
* 2025-12-07: Initial draft
68

79
## Status
810

9-
PROPOSED Not Implemented
11+
ACCEPTED Implemented
12+
13+
## Implementation Status
14+
15+
| Component | Status | Location |
16+
|-----------|--------|----------|
17+
| DCL (Data Chain Layer) | Implemented | `crates/data-chain/` |
18+
| CL (Consensus Layer) | Implemented | `crates/consensus/` |
19+
| EL (Execution Layer) | Implemented | `crates/execution/` |
20+
| Pipeline Manager | Implemented | `crates/data-chain/src/pipeline.rs` |
21+
| WAL (Write-Ahead Log) | Implemented | `crates/storage/src/wal.rs` |
22+
23+
### Implementation Notes
24+
25+
- **Layer Interfaces**: Trait-based boundaries implemented via `DataChainLayer`, `ConsensusLayer`, `ExecutionLayer` traits
26+
- **Malachite Integration**: Context trait implemented in `crates/consensus/src/context.rs`
27+
- **Error Handling**: Unified `CipherBftError` type with `is_critical()` method for halt conditions
28+
- **Atomic Commit**: WAL-based atomic commit across consensus and EVM state
1029

1130
## Abstract
1231
<img width="2320" height="1987" alt="image" src="https://github.com/user-attachments/assets/1be9339a-2375-4549-b699-77ad681d4552" />

‎docs/architecture/adr-002-evm-native-execution.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,31 @@
22

33
## Changelog
44

5-
* 2025-12-06: Initial draft
5+
* 2026-02-01: Added implementation status
6+
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| Embedded revm | Implemented | `crates/execution/` |
17+
| Reth crate integration | Implemented | See `Cargo.toml` dependencies |
18+
| ExecutionEngine trait | Implemented | `crates/execution/src/engine.rs` |
19+
| EVM Configuration | Implemented | `crates/execution/src/evm_config.rs` |
20+
| Staking Precompile | Implemented | `crates/execution/src/precompiles/staking.rs` |
21+
| State Root Calculation | Implemented | `crates/execution/src/state.rs` |
22+
| Transaction Validation | Implemented | `crates/execution/src/validation.rs` |
23+
24+
### Implementation Notes
25+
26+
- **Reth Version**: Pinned to v1.1.0 for API stability
27+
- **EVM Fork**: Supports Shanghai fork, Dencun activation configurable
28+
- **Gas Limit**: Default 30M gas per block, configurable via genesis
29+
- **State Sync**: Snap sync implemented for fast bootstrap
1030

1131
## Abstract
1232

‎docs/architecture/adr-003-malachite-consensus.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,30 @@
22

33
## Changelog
44

5-
* 2025-12-06: Initial draft
5+
* 2026-02-01: Added implementation status
6+
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| CipherBftContext | Implemented | `crates/consensus/src/context.rs` |
17+
| Type Implementations | Implemented | `crates/types/src/` |
18+
| Effect Handlers | Implemented | `crates/consensus/src/effects/` |
19+
| Consensus Engine | Implemented | `crates/consensus/src/engine.rs` |
20+
| Vote Aggregation | Implemented | `crates/consensus/src/vote.rs` |
21+
| WAL Integration | Implemented | `crates/storage/src/wal.rs` |
22+
23+
### Implementation Notes
24+
25+
- **Malachite Version**: Pinned to specific commit for stability
26+
- **Signing Scheme**: Uses `malachitebft-signing-ed25519` for CL
27+
- **Leader Selection**: Round-robin proposer selection implemented
28+
- **Equivocation Detection**: Integrated with slashing mechanism
1029

1130
## Abstract
1231

‎docs/architecture/adr-004-primary-worker-architecture.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,37 @@
22

33
## Changelog
44

5-
* 2025-12-06: Initial draft
5+
* 2026-02-01: Added implementation status
6+
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| Primary Process | Implemented | `crates/data-chain/src/primary.rs` |
17+
| Worker Process | Implemented | `crates/data-chain/src/worker/` |
18+
| Car Structure | Implemented | `crates/data-chain/src/car.rs` |
19+
| Cut Formation | Implemented | `crates/data-chain/src/cut.rs` |
20+
| Attestation Collection | Implemented | `crates/data-chain/src/attestation.rs` |
21+
| Batch Creation | Implemented | `crates/data-chain/src/worker/batch.rs` |
22+
| Pipeline Manager | Implemented | `crates/data-chain/src/pipeline.rs` |
23+
24+
### Implementation Notes
25+
26+
- **Worker Count**: Configurable 1-8 workers per validator (default: 4)
27+
- **Batch Size**: Max 1MB or 1000 transactions per batch
28+
- **Car Interval**: 100ms default, configurable
29+
- **Attestation Timeout**: 500ms base with exponential backoff
30+
31+
### Performance Validation
32+
33+
- Throughput baseline with 1 worker established
34+
- Worker scaling (2, 4, 8) validated with expected linear improvement
35+
- Pipeline overlap verified: attestation N+1 collected during consensus N
1036

1137
## Abstract
1238

‎docs/architecture/adr-005-dual-signatures.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,29 @@
22

33
## Changelog
44

5+
* 2026-02-01: Added implementation status
56
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| Ed25519 (CL) | Implemented | Via Malachite `malachitebft-signing-ed25519` |
17+
| BLS12-381 (DCL) | Implemented | `crates/crypto/src/bls.rs` |
18+
| Key Management | Implemented | `crates/crypto/src/keys.rs` |
19+
| Attestation Aggregation | Implemented | `crates/data-chain/src/attestation.rs` |
20+
| Domain Separation Tags | Implemented | `DST_CAR`, `DST_ATTESTATION` in `crates/crypto/` |
21+
22+
### Implementation Notes
23+
24+
- **BLS Library**: Uses `blst` crate for BLS12-381 operations
25+
- **Key Files**: Separate files for Ed25519 (`consensus.key`) and BLS (`dcl.key`)
26+
- **Aggregation**: f+1 attestations aggregated into single BLS signature
27+
- **Verification**: Batch verification for aggregated attestations
1028

1129
## Abstract
1230

‎docs/architecture/adr-006-mempool-design.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,29 @@
22

33
## Changelog
44

5+
* 2026-02-01: Added implementation status
56
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| Reth Transaction Pool | Implemented | `crates/mempool/` |
17+
| Pool Adapter | Implemented | `crates/mempool/src/adapter.rs` |
18+
| Transaction Validation | Implemented | `crates/mempool/src/validator.rs` |
19+
| Worker Integration | Implemented | `crates/data-chain/src/worker/` |
20+
| Post-Finalization Cleanup | Implemented | `crates/mempool/src/cleanup.rs` |
21+
22+
### Implementation Notes
23+
24+
- **Pool Size**: Default 10,000 transactions, configurable
25+
- **Gas Price Ordering**: Uses `CoinbaseTipOrdering` for EIP-1559
26+
- **Nonce Gap**: Maximum 16 nonce gap before rejection
27+
- **Memory Usage**: Bounded by pool config limits
1028

1129
## Abstract
1230

‎docs/architecture/adr-007-p2p-networking.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,30 @@
22

33
## Changelog
44

5+
* 2026-02-01: Added implementation status
56
* 2025-12-21: Added Malachite internal architecture analysis and channel extensibility
67
* 2025-12-07: Initial draft
78

89
## Status
910

10-
PROPOSED Not Implemented
11+
ACCEPTED Implemented
12+
13+
## Implementation Status
14+
15+
| Component | Status | Location |
16+
|-----------|--------|----------|
17+
| Consensus Message Broadcast | Implemented | `crates/consensus/src/network.rs` |
18+
| DCL Message Handler | Implemented | `crates/data-chain/src/network.rs` |
19+
| Worker Batch Dissemination | Implemented | `crates/data-chain/src/worker/network.rs` |
20+
| Transaction Gossip | Implemented | `crates/mempool/src/gossip.rs` |
21+
| Malachite P2P Crates | Implemented | Via Malachite network layer |
22+
| Channel Extensibility | Implemented | Custom channels for DCL |
23+
24+
### Implementation Notes
25+
26+
- **Network Stack**: Malachite P2P crates with GossipSub
27+
- **Rate Limiting**: 100 msg/sec per peer, 10 MB/sec bandwidth limit
28+
- **Peer Discovery**: Seed nodes + PEX protocol
1129

1230
## Abstract
1331

‎docs/architecture/adr-008-json-rpc-interface.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,30 @@
22

33
## Changelog
44

5+
* 2026-02-01: Added implementation status
56
* 2025-12-07: Initial draft
67

78
## Status
89

9-
PROPOSED Not Implemented
10+
ACCEPTED Implemented
11+
12+
## Implementation Status
13+
14+
| Component | Status | Location |
15+
|-----------|--------|----------|
16+
| eth_* Namespace | Implemented | `crates/rpc/src/eth/` |
17+
| net_* Namespace | Implemented | `crates/rpc/src/net.rs` |
18+
| web3_* Namespace | Implemented | `crates/rpc/src/web3.rs` |
19+
| WebSocket Subscriptions | Implemented | `crates/rpc/src/ws/` |
20+
| Health Endpoint | Implemented | `crates/rpc/src/health.rs` |
21+
| Rate Limiting | Implemented | `crates/rpc/src/middleware.rs` |
22+
23+
### Implementation Notes
24+
25+
- **Port**: Default 8545 (HTTP), 8546 (WebSocket)
26+
- **Batch Requests**: Supported with max 100 requests per batch
27+
- **Subscriptions**: `newHeads`, `logs`, `newPendingTransactions` supported
28+
- **Not Implemented**: `debug_*`, `trace_*`, `admin_*` namespaces (intentionally deferred)
1029

1130
## Abstract
1231

0 commit comments

Comments
 (0)