@@ -9,6 +9,7 @@ The block package is the core of ev-node's block management system. It handles b
99## Core Components
1010
1111### Manager (` manager.go ` )
12+
1213- ** Purpose** : Central orchestrator for all block operations
1314- ** Key Responsibilities** :
1415 - Transaction aggregation into blocks
@@ -18,6 +19,7 @@ The block package is the core of ev-node's block management system. It handles b
1819 - P2P block/header gossiping
1920
2021### Aggregation (` aggregation.go ` , ` lazy_aggregation_test.go ` )
22+
2123- ** Purpose** : Collects transactions from mempool and creates blocks
2224- ** Modes** :
2325 - ** Normal Mode** : Produces blocks at regular intervals (BlockTime)
@@ -28,6 +30,7 @@ The block package is the core of ev-node's block management system. It handles b
2830 - ` normalAggregationLoop ` : Regular block production
2931
3032### Synchronization (` sync.go ` , ` sync_test.go ` )
33+
3134- ** Purpose** : Keeps the node synchronized with the network
3235- ** Key Functions** :
3336 - ` SyncLoop ` : Main synchronization loop
@@ -36,6 +39,7 @@ The block package is the core of ev-node's block management system. It handles b
3639 - Handles header and data caching
3740
3841### Data Availability (` da_includer.go ` , ` submitter.go ` , ` retriever.go ` )
42+
3943- ** DA Includer** : Manages DA blob inclusion proofs and validation
4044- ** Submitter** : Handles block submission to the DA layer with retry logic
4145- ** Retriever** : Fetches blocks from the DA layer
@@ -45,6 +49,7 @@ The block package is the core of ev-node's block management system. It handles b
4549 - Batch submission optimization
4650
4751### Storage (` store.go ` , ` store_test.go ` )
52+
4853- ** Purpose** : Persistent storage for blocks and state
4954- ** Key Features** :
5055 - Block height tracking
@@ -53,6 +58,7 @@ The block package is the core of ev-node's block management system. It handles b
5358 - Migration support for namespace changes
5459
5560### Pending Blocks (` pending_base.go ` , ` pending_headers.go ` , ` pending_data.go ` )
61+
5662- ** Purpose** : Manages blocks awaiting DA inclusion or validation
5763- ** Components** :
5864 - ** PendingBase** : Base structure for pending blocks
@@ -64,6 +70,7 @@ The block package is the core of ev-node's block management system. It handles b
6470 - Memory-efficient caching
6571
6672### Metrics (` metrics.go ` , ` metrics_helpers.go ` )
73+
6774- ** Purpose** : Performance monitoring and observability
6875- ** Key Metrics** :
6976 - Block production times
@@ -74,20 +81,23 @@ The block package is the core of ev-node's block management system. It handles b
7481## Key Workflows
7582
7683### Block Production Flow
84+
77851 . Transactions collected from mempool
78862 . Block created with proper header and data
79873 . Block executed through executor
80884 . Block submitted to DA layer
81895 . Block gossiped to P2P network
8290
8391### Synchronization Flow
92+
84931 . Headers received from P2P network
85942 . Headers validated and cached
86953 . Block data retrieved from DA layer
87964 . Blocks applied to state
88975 . Sync progress updated
8998
9099### DA Submission Flow
100+
911011 . Block prepared for submission
921022 . Blob created with block data
931033 . Submission attempted with retries
@@ -97,47 +107,55 @@ The block package is the core of ev-node's block management system. It handles b
97107## Configuration
98108
99109### Time Parameters
110+
100111- ` BlockTime ` : Target time between blocks (default: 1s)
101112- ` DABlockTime ` : DA layer block time (default: 6s)
102113- ` LazyBlockTime ` : Max time between blocks in lazy mode (default: 60s)
103114
104115### Limits
116+
105117- ` maxSubmitAttempts ` : Max DA submission retries (30)
106118- ` defaultMempoolTTL ` : Blocks until tx dropped (25)
107119
108120## Testing Strategy
109121
110122### Unit Tests
123+
111124- Test individual components in isolation
112125- Mock external dependencies (DA, executor, sequencer)
113126- Focus on edge cases and error conditions
114127
115128### Integration Tests
129+
116130- Test component interactions
117131- Verify block flow from creation to storage
118132- Test synchronization scenarios
119133
120134### Performance Tests (` da_speed_test.go ` )
135+
121136- Measure DA submission performance
122137- Test batch processing efficiency
123138- Validate metrics accuracy
124139
125140## Common Development Tasks
126141
127142### Adding a New DA Feature
143+
1281441 . Update DA interfaces in ` core/da `
1291452 . Modify ` da_includer.go ` for inclusion logic
1301463 . Update ` submitter.go ` for submission flow
1311474 . Add retrieval logic in ` retriever.go `
1321485 . Update tests and metrics
133149
134150### Modifying Block Production
151+
1351521 . Update aggregation logic in ` aggregation.go `
1361532 . Adjust timing in Manager configuration
1371543 . Update metrics collection
1381554 . Test both normal and lazy modes
139156
140157### Implementing New Sync Strategy
158+
1411591 . Modify ` SyncLoop ` in ` sync.go `
1421602 . Update pending block handling
1431613 . Adjust cache strategies
@@ -182,4 +200,4 @@ The block package is the core of ev-node's block management system. It handles b
182200- Log with structured fields
183201- Return errors with context
184202- Use metrics for observability
185- - Test error conditions thoroughly
203+ - Test error conditions thoroughly
0 commit comments