diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index 15540d5ce9..99130c8292 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -2,5 +2,17 @@ default: true
MD010:
code_blocks: false
MD013: false
+MD025:
+ front_matter_title: ""
MD024:
siblings_only: true
+MD033:
+ allowed_elements:
+ - a
+ - div
+ - OAIntroduction
+ - OAOperation
+ - script
+ - span
+ - style
+ - CelestiaGasEstimator
diff --git a/CLAUDE.md b/CLAUDE.md
index ad122aab47..01dd13e705 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,3 @@
+# CLAUDE.md
+
See [AGENTS.md](./AGENTS.md)
diff --git a/README.md b/README.md
index 28967abead..ad98667441 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,9 @@
Ev-node is the basis of the Evolve Stack. For more in-depth information about Evolve, please visit our [website][docs].
-
[](https://goreportcard.com/report/github.com/evstack/ev-node)
[](https://codecov.io/gh/evstack/ev-node)
[](https://godoc.org/github.com/evstack/ev-node)
-
> **⚠️ Version Notice**: Do not use tags or releases before v1.*. Pre-v1 releases are not stable and should be considered abandoned.
diff --git a/RELEASE.md b/RELEASE.md
index 2ef79aa739..627de2ae78 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -348,25 +348,25 @@ go get github.com/evstack/ev-node/core@v0.3.0
### GitHub Releases
-**"Invalid tag format" error**
+#### "Invalid tag format" error
- Ensure tag follows semantic versioning: `v1.2.3`
- Check for typos or incorrect format
- Valid examples: `v1.2.3`, `v1.2.3-rc.4`, `v1.2.3-beta.1`
-**"Version not found in CHANGELOG.md"**
+#### "Version not found in CHANGELOG.md"
- Verify CHANGELOG.md contains a section for the version
- Check version format matches exactly (e.g., `v1.2.3` vs `1.2.3`)
- Ensure CHANGELOG.md is committed and pushed
-**"Claude API error"**
+#### "Claude API error"
- Verify `CLAUDE_CODE_OAUTH_TOKEN` secret is configured
- Check repository permissions for GitHub Actions
- Review workflow logs for specific error messages
-**Empty or incomplete release notes**
+#### Empty or incomplete release notes
- Ensure CHANGELOG.md has detailed entries for the version
- Check that changelog sections (Added, Changed, Fixed, etc.) are properly formatted
@@ -374,30 +374,30 @@ go get github.com/evstack/ev-node/core@v0.3.0
### Docker Releases
-**"App directory does not exist"**
+#### "App directory does not exist"
- Ensure tag matches app path: `apps/evm/` → `apps/evm/v0.2.0`
- Check spelling and case sensitivity
-**"Dockerfile not found"**
+#### "Dockerfile not found"
- Verify Dockerfile exists at `apps/{app-path}/Dockerfile`
- Check filename is exactly `Dockerfile`
-**"Image not found" in tests**
+#### "Image not found" in tests
- Wait for Docker build workflow to complete
- Check workflow dependencies in Actions tab
### Go Module Releases
-**Go proxy delay**
+#### Go proxy delay
- Wait 5-30 minutes for propagation
- Use `go list -m` to verify availability
- Check
-**Dependency version conflicts**
+#### Dependency version conflicts
- Ensure all dependencies are released before dependent modules
- Verify go.mod has correct versions
diff --git a/apps/evm/README.md b/apps/evm/README.md
index 08b14645f7..1e4cda6926 100644
--- a/apps/evm/README.md
+++ b/apps/evm/README.md
@@ -165,7 +165,7 @@ spamoor \
Transactions submitted to the Force Inclusion API are included in the chain at specific DA heights based on the `da_epoch_forced_inclusion` configuration in `genesis.json`. The API logs will show when the transaction will be force included:
-```
+```text
INF transaction successfully submitted to DA layer da_height=100
INF transaction will be force included blocks_until_inclusion=8 inclusion_at_height=110
```
diff --git a/block/internal/syncing/da_retriever.go b/block/internal/syncing/da_retriever.go
index d4fa93ce04..f0e12c1282 100644
--- a/block/internal/syncing/da_retriever.go
+++ b/block/internal/syncing/da_retriever.go
@@ -195,7 +195,7 @@ func (r *daRetriever) processBlobs(ctx context.Context, blobs [][]byte, daHeight
}
}
- var events []common.DAHeightEvent
+ events := make([]common.DAHeightEvent, 0, len(r.pendingHeaders))
// Match headers with data and create events
for height, header := range r.pendingHeaders {
diff --git a/docs/adr/adr-009-state-fraud-proofs.md b/docs/adr/adr-009-state-fraud-proofs.md
index f5beb0d46c..1d85f88c72 100644
--- a/docs/adr/adr-009-state-fraud-proofs.md
+++ b/docs/adr/adr-009-state-fraud-proofs.md
@@ -188,7 +188,7 @@ message ResponseGenerateFraudProof {
}
```
-Note that currently the only underlying store supported by Cosmos SDK is the Merkle IAVL+ tree. As part of generating state witnesses, we added preliminary support for Deep Subtrees to this library [here](https://github.com/rollkit/iavl/tree/deepsubtrees_0.19.x). It enables import and export of partial state and adds tracing to IAVL trees. Note that documentation and exploring optimizations of Deep Subtrees is a work in progress.
+Note that currently the only underlying store supported by Cosmos SDK is the Merkle IAVL+ tree. As part of generating state witnesses, we added preliminary support for Deep Subtrees to the [IAVL Deep Subtrees branch](https://github.com/rollkit/iavl/tree/deepsubtrees_0.19.x). It enables import and export of partial state and adds tracing to IAVL trees. Note that documentation and exploring optimizations of Deep Subtrees is a work in progress.
### Gossiping Fraud Proofs
diff --git a/docs/adr/adr-012-based-sequencing.md b/docs/adr/adr-012-based-sequencing.md
index 2e3456a60c..aba97d4599 100644
--- a/docs/adr/adr-012-based-sequencing.md
+++ b/docs/adr/adr-012-based-sequencing.md
@@ -159,7 +159,7 @@ When forced inclusion transactions exceed `MaxBytes`:
**Block 1**:
-```
+```text
Epoch [100-109] contains 3MB of transactions
Block at DA height 100: 2MB (partial)
Remaining in queue: 1MB
@@ -167,7 +167,7 @@ Remaining in queue: 1MB
**Block 2**:
-```
+```text
Block at DA height 101: 1MB (remainder) + new regular txs
Queue cleared
```
diff --git a/docs/adr/adr-019-forced-inclusion-mechanism.md b/docs/adr/adr-019-forced-inclusion-mechanism.md
index c603b0d57a..91140e05bd 100644
--- a/docs/adr/adr-019-forced-inclusion-mechanism.md
+++ b/docs/adr/adr-019-forced-inclusion-mechanism.md
@@ -47,7 +47,7 @@ We implement a **forced inclusion mechanism** that allows users to submit transa
### High-Level Architecture
-```
+```text
┌─────────────────────────────────────────────────────────────────┐
│ User Actions │
├─────────────────────────────────────────────────────────────────┤
@@ -385,7 +385,7 @@ func (s *Syncer) verifyForcedInclusionTxs(currentState State, data *Data) error
**Smoothing Example**:
-```
+```text
Epoch [100-109] contains 3MB of forced inclusion transactions
Block at DA height 100:
@@ -551,18 +551,18 @@ graceBoundary := epochEnd + (effectiveGracePeriod * DAEpochForcedInclusion)
Configuration: `DAEpochForcedInclusion = 50`, Base grace period of 1 epoch (dynamically adjusted)
-_Example 1: Normal Inclusion (Within Same Epoch)_
+#### Example 1: Normal Inclusion (Within Same Epoch)
-```
+```text
- Forced tx submitted to DA at height 75 (epoch 51-100)
- Sequencer fetches at height 101 (next epoch start)
- Sequencer includes tx in block at DA height 105
- Result: ✅ Valid - included within same epoch
```
-_Example 2: Grace Period Usage (Included in Next Epoch)_
+#### Example 2: Grace Period Usage (Included in Next Epoch)
-```
+```text
- Forced tx submitted to DA at height 75 (epoch 51-100)
- Sequencer fetches at height 101
- DA temporarily unavailable, sequencer cannot fetch
@@ -571,9 +571,9 @@ _Example 2: Grace Period Usage (Included in Next Epoch)_
- Result: ✅ Valid - within grace period
```
-_Example 3: Malicious Sequencer (Past Grace Boundary)_
+#### Example 3: Malicious Sequencer (Past Grace Boundary)
-```
+```text
- Forced tx submitted to DA at height 75 (epoch 51-100)
- Sequencer fetches at height 101
- Sequencer deliberately omits tx
@@ -582,9 +582,9 @@ _Example 3: Malicious Sequencer (Past Grace Boundary)_
- Result: ❌ Block rejected, sequencer flagged as malicious
```
-_Example 4: Low Chain Activity (Minimum Grace Period)_
+#### Example 4: Low Chain Activity (Minimum Grace Period)
-```
+```text
- Chain is mostly empty (<20% full)
- Grace period is at minimum (0.5x base period)
- Forced tx submitted at height 75 (epoch 51-100)
@@ -593,9 +593,9 @@ _Example 4: Low Chain Activity (Minimum Grace Period)_
- Result: Faster censorship detection when block space is available
```
-_Example 5: Multiple Pending Transactions_
+#### Example 5: Multiple Pending Transactions
-```
+```text
- Tx A from epoch ending at height 100, grace boundary 150
- Tx B from epoch ending at height 150, grace boundary 200
- Current DA height: 155
@@ -604,9 +604,9 @@ _Example 5: Multiple Pending Transactions_
- Result: Block rejected due to Tx A
```
-_Example 6: High Chain Activity (Extended Grace Period)_
+#### Example 6: High Chain Activity (Extended Grace Period)
-```
+```text
- Chain is highly congested (>80% full)
- Grace period is extended (up to 3x base period)
- Forced tx submitted at height 75 (epoch 51-100)
diff --git a/docs/guides/da/visualizer.md b/docs/guides/da/visualizer.md
index 55ebc99801..46a9a43c3e 100644
--- a/docs/guides/da/visualizer.md
+++ b/docs/guides/da/visualizer.md
@@ -38,7 +38,7 @@ rpc:
Once enabled, the DA Visualizer is accessible through your node's RPC server. By default, this is:
-```
+```text
http://localhost:7331/da
```
diff --git a/docs/guides/deploy/mainnet.md b/docs/guides/deploy/mainnet.md
index ba2c505bfe..080e82dc3f 100644
--- a/docs/guides/deploy/mainnet.md
+++ b/docs/guides/deploy/mainnet.md
@@ -162,7 +162,7 @@ All flows below assume usage of the proxy admin contract.
### Flow 1: Full Setup
-**Basefee redirect + feevault + native mint/burn + bridge (Hyperlane)**
+#### Basefee redirect + feevault + native mint/burn + bridge (Hyperlane)
#### Genesis Setup
@@ -187,8 +187,8 @@ Embed the proxy contract with an EOA address as admin. The EOA must have at leas
}
```
-4. Pick a max contract size (24kb default, 128kb is a safe upgrade)
-5. Pick EIP-1559 config:
+1. Pick a max contract size (24kb default, 128kb is a safe upgrade)
+2. Pick EIP-1559 config:
```json
{
diff --git a/docs/guides/deploy/overview.md b/docs/guides/deploy/overview.md
index dcc78ad54e..348b55fdae 100644
--- a/docs/guides/deploy/overview.md
+++ b/docs/guides/deploy/overview.md
@@ -6,7 +6,7 @@ description: This page provides an overview of some common ways to deploy chains
One of the benefits of building chains with Evolve is the flexibility you have as a developer to choose things like the DA layer, the settlement scheme, and the execution environment.
-You can learn more about Evolve architecture [here](../../learn/specs/overview.md).
+You can learn more in the [Evolve architecture overview](../../learn/specs/overview.md).
The challenge that comes with this flexibility is that there are more services that now need to be deployed and managed while running your chain.
diff --git a/docs/guides/deploy/testnet.md b/docs/guides/deploy/testnet.md
index 0d4e035899..3f11c4fa6c 100644
--- a/docs/guides/deploy/testnet.md
+++ b/docs/guides/deploy/testnet.md
@@ -2,7 +2,7 @@
This tutorial is going to show you how to deploy a Evolve testnet, focusing on the architecture choices and components that make up a complete EVM-based chain deployment.
-You can learn more about Evolve EVM architecture [here](../../learn/execution.md).
+You can learn more in the [Evolve EVM architecture guide](../../learn/execution.md).