Conversation
|
The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).
|
|
Claude finished @tac0turtle's task in 3m 37s —— View job PR Review: docs: rewrite and restructure docsTasks:
This PR adds significant documentation. Most of the structure and content is solid, but I found several technical inaccuracies where documented flag names, defaults, and code signatures don't match the actual codebase. These would cause confusion or breakage for users following the docs. 🔴 Critical: Incorrect Flag Names in Multiple Files
|
Summary of ChangesHello @tac0turtle, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation, providing a more organized and in-depth resource for developers and operators. It covers fundamental concepts, practical implementation steps for different execution environments, operational best practices, and detailed technical specifications, making it easier for users to understand, integrate, and manage Evolve-based chains. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3026 +/- ##
==========================================
- Coverage 60.97% 60.95% -0.03%
==========================================
Files 113 113
Lines 11617 11617
==========================================
- Hits 7084 7081 -3
- Misses 3734 3738 +4
+ Partials 799 798 -1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant rewrite and restructuring of the documentation, adding a large volume of new content across concepts, guides, and reference sections. The effort to improve the documentation is commendable. However, there are several areas that need attention before this can be merged.
Firstly, there's a notable amount of content duplication, particularly between docs/concepts/block-lifecycle.md and docs/reference/specs/block-manager.md. This could lead to maintenance issues and should be resolved, perhaps by using includes or linking between documents.
Secondly, a large number of placeholder files have been added, containing only TODO comments. These should be either completed or removed.
Finally, there are various inconsistencies in technical details, formatting issues (like the use of :::: instead of ::: for VitePress admonitions), minor typos, and some broken links. Addressing these points will greatly improve the quality and usability of the new documentation.
- Updated Celestia guide to clarify prerequisites, installation, and configuration for connecting Evolve chains to Celestia. - Enhanced Local DA documentation with installation instructions, configuration options, and use cases for development and testing. - Expanded troubleshooting guide with detailed diagnostic commands, common issues, and solutions for node operations. - Created comprehensive upgrades guide covering minor and major upgrades, version compatibility, and rollback procedures. - Added aggregator node documentation detailing configuration, block production settings, and monitoring options. - Introduced attester node overview with configuration and use cases for low-latency applications. - Removed outdated light node documentation. - Improved formatting and clarity in ev-reth chainspec reference for better readability.
tac0turtle
requested review from
alpe,
chatton,
julienrbrt,
pthmas and
randygrok
pthmas
left a comment
pthmas
left a comment
There was a problem hiding this comment.
A lot of duplicate that we need to remove but overall looks good. I can't guarantee that the evm part is correct i don't have enough knowledge about it.
| - The component architecture supports the separation of header and data structures in Evolve. This allows for expanding the sequencing scheme beyond single sequencing and enables the use of a decentralized sequencer mode. For detailed information on this architecture, see the [Header and Data Separation ADR](../../adr/adr-014-header-and-data-separation.md) | ||
| - Components process blocks with a minimal header format, which is designed to eliminate dependency on CometBFT's header format and can be used to produce an execution layer tailored header if needed. For details on this header structure, see the [Evolve Minimal Header](../../adr/adr-015-rollkit-minimal-header.md) specification | ||
|
|
||
| ## Metrics |
There was a problem hiding this comment.
Should the metric get a dedicated page?
docs/concepts/data-availability.md
Outdated
| - **Guarantee**: Data availability sampling (DAS) | ||
| - **Latency**: ~12 seconds to finality | ||
|
|
||
| ### Custom DA |
|
|
||
| We are now ready to run our full node. If we are running the full node on the same machine as the sequencer, we need to make sure we update the ports to avoid conflicts. | ||
|
|
||
| Make sure to include these flags with your start command: |
There was a problem hiding this comment.
may we could also add that the config/ev-node file can be updated
| | **Aggregator** | Yes | Yes | Yes | Block producer (sequencer) | | ||
| | **Full Node** | No | Yes | No | RPC provider, validator | | ||
| | **Light Node** | No | Headers only | No | Mobile, embedded clients | | ||
| | **Attester** | No | Yes | No | Soft consensus participant | |
There was a problem hiding this comment.
Should specify that this is not yet available
| @@ -0,0 +1,185 @@ | |||
| # Architecture | |||
There was a problem hiding this comment.
this feels also a bit like a duplicate of the docs/concepts folder
| @@ -0,0 +1,95 @@ | |||
| # Introduction | |||
There was a problem hiding this comment.
imo the overview folder should be one page, for more information the reader should go to the concepts folder
| @@ -0,0 +1,193 @@ | |||
| # DA Interface | |||
There was a problem hiding this comment.
It's probably hard to maintain all the interfaces changes up to date and documented. Could we just point to the correct files in the repo?
📝 WalkthroughWalkthroughLarge documentation addition: introduces conceptual docs, integration/migration guides, quickstarts, operational and developer guides, API/config/interface/spec references, and minor makefile linting change. No code or public API signatures modified. Changes
Sequence Diagram(s)(omitted — changes are documentation additions and do not introduce new runtime control flow to diagram) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
♻️ Duplicate comments (1)
docs/guides/advanced/based-sequencing.md (1)
17-23: Confirm “all full nodes independently construct identical batches” matches current implementation.If the implementation still relies on a single sequencer (even in “based” mode), this statement needs adjustment to avoid overpromising decentralization. Please verify against current code/config docs.
#!/bin/bash # Look for based sequencing/forced inclusion implementation notes rg -n --type=go --type=md -C2 'based sequencing|forced inclusion|DAEpochForcedInclusion|sequencer'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/advanced/based-sequencing.md` around lines 17 - 23, The doc claim "all full nodes independently construct identical batches" may be inaccurate if the code/config still uses a single sequencer or centralized path; search the codebase for symbols like DAEpochForcedInclusion, forced inclusion, based sequencing, and sequencer to confirm whether batch construction is decentralized, and if not, update the doc to reflect the actual implementation: either state that full nodes independently construct batches (if code shows per-node batch logic) or explicitly mention a single/sequencer-based flow (e.g., sequencer/DAEpochForcedInclusion responsible for batch assembly) and any config flags that toggle modes so the guide matches behavior.
🟡 Minor comments (38)
docs/guides/tools/blob-decoder.md-156-158 (1)
156-158:⚠️ Potential issue | 🟡 MinorCelestia section is incomplete.
The
### Celestiasubsection contains only a single sentence pointing to an external link, with no API example, no sample payload, and no decoded output — unlike every other example section. Either expand it with a concretecurlexample and sample response (similar to the### Decoding a Block Blobsection), or fold the note into the### Decoding DA Commitmentexample above it as a prose callout rather than leaving a stub subsection.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/tools/blob-decoder.md` around lines 156 - 158, The Celestia subsection ("### Celestia") is incomplete — either expand it to match other examples by adding a concrete API usage (e.g., a curl request against the blob-decoding endpoint), a representative sample payload and the expected decoded output, or remove the subsection and fold the note into the preceding "### Decoding DA Commitment" as a prose callout; update the "### Celestia" block (or the DA Commitment text) to include the sample request/response and a short explanation of decoding namespace/payment fields so readers have a complete, consistent example like the "Decoding a Block Blob" section.docs/guides/tools/blob-decoder.md-59-76 (1)
59-76:⚠️ Potential issue | 🟡 MinorJSON code blocks contain invalid
//comments.JSON does not support inline comments. The
//annotations in the request and response format blocks will cause parse errors if readers copy-paste them into tooling (e.g.,curl, Postman,jq). Use a commented-out version via a non-JSON block, or strip the comments and rely on surrounding prose to explain each field.📝 Proposed fix
#### API Request Format -```json -{ - "data": "string", // The encoded blob data - "encoding": "string" // Either "hex" or "base64" -} -``` +| Field | Type | Description | +|------------|--------|-------------------------------| +| `data` | string | The encoded blob data | +| `encoding` | string | Either `"hex"` or `"base64"` | #### API Response Format -```json -{ - "success": true, - "decoded": { - // Decoded data structure - }, - "error": "string" // Only present if success is false -} -``` +| Field | Type | Description | +|-----------|---------|------------------------------------------| +| `success` | boolean | Whether decoding succeeded | +| `decoded` | object | Decoded data structure | +| `error` | string | Error message; only present on failure |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/tools/blob-decoder.md` around lines 59 - 76, The JSON examples in docs/guides/tools/blob-decoder.md include invalid `//` comments; locate the request/response JSON blocks that reference the fields `data`, `encoding`, `success`, `decoded`, and `error` and replace them so they are valid and copy-paste-safe — either convert the examples to plain JSON with the comments removed, or change the examples to a non-JSON fenced block (e.g., plain text) or a Markdown table documenting each field (as in the proposed fix) so that the descriptions for `data`, `encoding`, `success`, `decoded`, and `error` remain present but not embedded as `//` comments.scripts/utils.mk-18-18 (2)
18-18:⚠️ Potential issue | 🟡 Minor
--ignore './changelog.md'is absent fromlintbut present inlint-fix.
lint(line 18) will report violations inchangelog.md, butlint-fix(line 34) never auto-fixes it. Because not all rules include fix information when reporting issues, fixes may overlap, and not all issues are fixable — so ifchangelog.mdcarries unfixable violations,lintwill fail indefinitely whilelint-fixsilently skips the file, making the CI failure unresolvable. Align both targets.🔧 Proposed fix — add the same ignore to `lint`
- `@npx` markdownlint-cli --config .markdownlint.yaml '**/*.md' + `@npx` markdownlint-cli --config .markdownlint.yaml --ignore './changelog.md' '**/*.md'Also applies to: 34-34
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/utils.mk` at line 18, The `lint` target runs "npx markdownlint-cli" without the ignore used by `lint-fix`, causing CI to fail on changelog.md; update the `lint` target's command (the line invoking npx markdownlint-cli in scripts/utils.mk) to include the same --ignore './changelog.md' flag so both targets (`lint` and `lint-fix`) have identical ignore behavior and the changelog is skipped consistently.
18-18:⚠️ Potential issue | 🟡 Minor
--ignore './changelog.md'is absent fromlintbut present inlint-fix.If
changelog.mdcontains any markdownlint violations,lintwill fail on it, butlint-fixwill never auto-fix it — creating a CI failure thatmake lint-fixcannot resolve. Either add the same--ignoreto thelinttarget, or remove it fromlint-fixif changelog violations should be caught and fixed.🔧 Proposed fix — align both targets
- `@npx` markdownlint-cli --config .markdownlint.yaml '**/*.md' + `@npx` markdownlint-cli --config .markdownlint.yaml --ignore './changelog.md' '**/*.md'Also applies to: 34-34
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/utils.mk` at line 18, The lint and lint-fix Makefile targets are inconsistent: lint-fix passes --ignore './changelog.md' to npx markdownlint-cli but lint does not, causing CI flakes; update the targets so they match by either adding --ignore './changelog.md' to the lint target's npx markdownlint-cli invocation or removing the --ignore from the lint-fix target (choose the behavior you want), ensuring both the lint and lint-fix invocations of markdownlint-cli use the same flags so changelog.md is treated consistently.docs/guides/operations/monitoring.md-40-40 (1)
40-40:⚠️ Potential issue | 🟡 MinorIncorrect article: "a Evolve" → "an Evolve".
✏️ Proposed fix
-Here's a basic Prometheus configuration to scrape metrics from a Evolve node: +Here's a basic Prometheus configuration to scrape metrics from an Evolve node:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/operations/monitoring.md` at line 40, Fix the grammar in the sentence "Here's a basic Prometheus configuration to scrape metrics from a Evolve node:" by changing "a Evolve" to "an Evolve" so it reads "Here's a basic Prometheus configuration to scrape metrics from an Evolve node:"; update the string in docs/guides/operations/monitoring.md where that sentence appears.docs/concepts/finality.md-55-55 (1)
55-55:⚠️ Potential issue | 🟡 MinorHyphenate "6-second" as a compound modifier.
✏️ Proposed fix
-DA finality depends on the DA layer. Celestia provides ~6 second finality. +DA finality depends on the DA layer. Celestia provides ~6-second finality.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/concepts/finality.md` at line 55, Update the sentence "DA finality depends on the DA layer. Celestia provides ~6 second finality." to hyphenate the compound modifier by changing "6 second" to "6-second" (i.e., replace the fragment "Celestia provides ~6 second finality." with "Celestia provides ~6-second finality.") so the phrase reads correctly as a compound adjective.docs/ev-reth/overview.md-15-32 (1)
15-32:⚠️ Potential issue | 🟡 MinorAdd a language specifier to the fenced code block.
The architecture diagram's fenced block is missing a language identifier, which triggers the MD040 lint warning.
🔧 Proposed fix
-``` +```text ┌─────────────────────────────────────────┐🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ev-reth/overview.md` around lines 15 - 32, The fenced ASCII diagram block in overview.md is missing a language specifier causing MD040; update the opening fence for the diagram (the triple backticks before the ASCII art) to include a language tag such as "text" (i.e., change ``` to ```text) so the block is explicitly marked and the linter warning is resolved.docs/guides/running-nodes/attester.md-24-24 (1)
24-24:⚠️ Potential issue | 🟡 MinorStale Celestia latency range; align with
finality.md."~6-12 seconds" reflects the pre/post-Ginger range but the Ginger upgrade has been live on Celestia mainnet since December 2024, making ~6 seconds the current single-slot finality.
finality.mdalready states ~6 seconds; this line should match.✏️ Proposed fix
-Without attesters, finality depends on DA confirmation (~6-12 seconds for Celestia). With an attester network: +Without attesters, finality depends on DA confirmation (~6 seconds for Celestia). With an attester network:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/running-nodes/attester.md` at line 24, Update the stale latency range text in the attester doc: replace "Without attesters, finality depends on DA confirmation (~6-12 seconds for Celestia)." with wording that matches finality.md (use "~6 seconds" as current single-slot finality post-Ginger) and, if helpful, add a brief parenthetical or link noting Ginger is live since Dec 2024 so the doc aligns with finality.md; ensure the sentence now reads something like "Without attesters, finality depends on DA confirmation (~6 seconds for Celestia)."docs/getting-started/choose-your-path.md-94-110 (1)
94-110:⚠️ Potential issue | 🟡 MinorAdd a language specifier to the decision tree code block.
The fenced code block for the decision tree is missing a language identifier, triggering the MD040 lint warning.
🔧 Proposed fix
-``` +```text Do you have an existing Cosmos SDK chain?🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/choose-your-path.md` around lines 94 - 110, The fenced decision-tree code block (the triple-backtick block containing "Do you have an existing Cosmos SDK chain? ...") lacks a language specifier causing MD040; update that block opener from ``` to ```text so the block becomes a plain-text code fence (ensure you edit the exact triple-backtick that precedes the decision tree and only add the "text" specifier).docs/concepts/data-availability.md-29-29 (1)
29-29:⚠️ Potential issue | 🟡 MinorCelestia latency figure is outdated and conflicts with
finality.md.This line states "~12 seconds to finality" for Celestia, but
finality.mdcorrectly states ~6 seconds, andattester.mdshows "~6-12 seconds." Celestia's Ginger upgrade (celestia-app v3) decreased block times from 12 seconds to 6 seconds, also improving transaction single-slot finality times. This Ginger upgrade deployed to mainnet in December 2024. All three files should consistently reflect the current ~6-second figure.✏️ Proposed fix
-- **Latency**: ~12 seconds to finality +- **Latency**: ~6 seconds to finality🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/concepts/data-availability.md` at line 29, The "Latency" figure in docs/concepts/data-availability.md currently reads "~12 seconds to finality" and must be updated to the post-Ginger value of "~6 seconds to finality" to match finality.md and attester.md; locate the markdown line containing "**Latency**" (the exact string "- **Latency**: ~12 seconds to finality") and replace the numeric value to "~6 seconds to finality", then scan and update the same phrasing in finality.md and attester.md so all three files consistently state "~6 seconds" (and, if present, adjust any parenthetical ranges like "~6-12 seconds" to reflect "~6 seconds" or "~6-12 seconds" as appropriate per attester.md guidance).docs/overview/architecture.md-7-28 (1)
7-28:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced blocks (MD040).
markdownlint flags these fences without a language; adding
textkeeps formatting and passes lint.✅ Suggested fix
-``` +```text ┌─────────────────────────────────────────────────────────────────┐ ... └─────────────────────────────────────────────────────────────────┘```diff -``` +```text ┌─────────────┐ ... └─────────────┘```diff -``` +```text User Tx → Execution Layer Mempool ... DA Layer (hard confirmation)```diff -``` +```text ┌────────────────────────────────────────┐ ... Validate → Execute → Persist</details> Also applies to: 54-78, 116-136, 140-155 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/overview/architecture.mdaround lines 7 - 28, The fenced ASCII diagrams
in architecture.md (the blocks containing "ev-node", "Executor", "DA Layer
(Celestia)" and the other ASCII diagrams like "User Tx → Execution Layer
Mempool" and "Validate → Execute → Persist") lack a language identifier and
trigger MD040; change each opening triple-fence fromtotext for every
ASCII diagram block (including the ones corresponding to the "ev-node" diagram
and the other blocks you noted) so the diagrams keep formatting and markdownlint
passes.</details> </blockquote></details> <details> <summary>docs/guides/tools/visualizer.md-41-43 (1)</summary><blockquote> `41-43`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language identifier to fenced URL block (MD040).** <details> <summary>✅ Suggested fix</summary> ```diff -``` +```text http://localhost:7331/da ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/guides/tools/visualizer.md` around lines 41 - 43, The fenced code block containing the URL "http://localhost:7331/da" in docs/guides/tools/visualizer.md lacks a language identifier; update that fenced block to include a language tag (e.g., use the "text" info string) so the block becomes a fenced code block with an explicit language identifier to satisfy MD040. ``` </details> </blockquote></details> <details> <summary>docs/reference/configuration/ev-reth-chainspec.md-143-146 (1)</summary><blockquote> `143-146`: _⚠️ Potential issue_ | _🟡 Minor_ **Use a valid hex address placeholder in the example.** `"0xBridgeContract"` isn’t a valid hex address and may confuse readers copying the example. Consider replacing it with a proper `0x...` address placeholder. <details> <summary>🔧 Suggested fix</summary> ```diff "mintPrecompile": { - "admin": "0xBridgeContract", + "admin": "0x1234567890123456789012345678901234567890", "address": "0x0000000000000000000000000000000000000100" } ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/configuration/ev-reth-chainspec.md` around lines 143 - 146, The example in the mintPrecompile object uses an invalid placeholder admin value ("0xBridgeContract"); replace that string with a valid hex address placeholder (for example "0x0000000000000000000000000000000000000001" or another 0x-prefixed 40-hex-character value) so readers won’t be confused when copying the example; update the mintPrecompile.admin entry accordingly. ``` </details> </blockquote></details> <details> <summary>docs/overview/execution-environments.md-5-5 (1)</summary><blockquote> `5-5`: _⚠️ Potential issue_ | _🟡 Minor_ **Missing hyphen: "Reth-compatible"** `Reth compatible applications` should be `Reth-compatible applications` (compound modifier before a noun). <details> <summary>✏️ Proposed fix</summary> ```diff -This means you can use a variety of Cosmos SDK or Reth compatible applications as the execution environment for your chain: choose the execution environment that best fits your use case. +This means you can use a variety of Cosmos SDK or Reth-compatible applications as the execution environment for your chain: choose the execution environment that best fits your use case. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/overview/execution-environments.md` at line 5, Replace the phrase "Reth compatible applications" with the hyphenated compound modifier "Reth-compatible applications" in the sentence that reads "use a variety of Cosmos SDK or Reth compatible applications as the execution environment for your chain" so the compound adjective correctly modifies "applications." ``` </details> </blockquote></details> <details> <summary>docs/overview/execution-environments.md-28-28 (1)</summary><blockquote> `28-28`: _⚠️ Potential issue_ | _🟡 Minor_ **Celestia hardcoded as the only DA layer — contradicts the broader documentation** The statement "uses Celestia as its data availability layer" presents Celestia as the sole option. The PR itself introduces docs for Local DA and the broader multi-DA architecture (`docs/guides/da-layers/local-da.md`, `docs/concepts/data-availability.md`). This framing will mislead users who want to run with a different DA backend. <details> <summary>✏️ Proposed fix</summary> ```diff -- Evolve acts as the consensus and uses Celestia as its data availability layer. +- Evolve acts as the consensus layer and delegates data availability to a pluggable DA layer (e.g., Celestia or Local DA). ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/overview/execution-environments.md` at line 28, The sentence in docs/overview/execution-environments.md currently hardcodes Celestia as the DA layer; change it to state that Evolve uses a pluggable/multi-DA data availability layer and mention or link to the DA architecture docs (refer to docs/concepts/data-availability.md and docs/guides/da-layers/local-da.md) so readers know Celestia is one supported option rather than the only one (update the sentence that currently reads "uses Celestia as its data availability layer" to a neutral phrasing like "uses a pluggable data availability layer (e.g., Celestia; see ...)" or similar). ``` </details> </blockquote></details> <details> <summary>docs/reference/interfaces/da.md-149-152 (1)</summary><blockquote> `149-152`: _⚠️ Potential issue_ | _🟡 Minor_ **Documentation syntax error — mixed named and unnamed return values** The function signature has named returns `(height uint64, commitment []byte)` mixed with an unnamed return `(error)`, which is invalid Go syntax. The actual implementation at `pkg/da/types/types.go:78` uses all-unnamed returns. <details> <summary>🐛 Proposed fix</summary> ```diff -func SplitID(id []byte) (height uint64, commitment []byte, error) +func SplitID(id []byte) (uint64, []byte, error) ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/interfaces/da.md` around lines 149 - 152, The documented Go signature for SplitID mixes named and unnamed returns which is invalid; update the doc to match the actual implementation by changing the return tuple to all-unnamed types (uint64, []byte, error) so the signature reads SplitID(id []byte) (uint64, []byte, error); reference the SplitID function to locate and replace the incorrect signature in the docs. ``` </details> </blockquote></details> <details> <summary>docs/ev-reth/engine-api.md-139-156 (1)</summary><blockquote> `139-156`: _⚠️ Potential issue_ | _🟡 Minor_ **`engine_newPayloadV3` first param is incorrectly wrapped** Per the official Engine API specification, `engine_newPayloadV3`'s first parameter is the `ExecutionPayloadV3` object directly — not nested inside a `{ "executionPayload": "..." }` wrapper. The wrapper is not part of the spec and would confuse developers implementing against this reference. The first parameter should contain fields like `parentHash`, `feeRecipient`, `stateRoot`, `receiptsRoot`, `logsBloom`, `prevRandao`, `blockNumber`, `gasLimit`, `gasUsed`, `timestamp`, `extraData`, `baseFeePerGas`, `blockHash`, `transactions`, `withdrawals`, `blobGasUsed`, and `excessBlobGas` directly, not nested. <details> <summary>🐛 Proposed fix</summary> ```diff { "method": "engine_newPayloadV3", "params": [ - { "executionPayload": "..." }, + { + "parentHash": "0x...", + "feeRecipient": "0x...", + "stateRoot": "0x...", + "receiptsRoot": "0x...", + "logsBloom": "0x...", + "prevRandao": "0x...", + "blockNumber": "0x1", + "gasLimit": "0x...", + "gasUsed": "0x...", + "timestamp": "0x...", + "extraData": "0x", + "baseFeePerGas": "0x...", + "blockHash": "0x...", + "transactions": ["0x..."], + "withdrawals": [], + "blobGasUsed": "0x0", + "excessBlobGas": "0x0" + }, ["0x...versionedHashes"], "0x...parentBeaconBlockRoot" ] } ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/ev-reth/engine-api.md` around lines 139 - 156, The example for engine_newPayloadV3 incorrectly wraps the ExecutionPayloadV3 inside { "executionPayload": ... }; update the example so the first param is the ExecutionPayloadV3 object itself (with fields like parentHash, feeRecipient, stateRoot, receiptsRoot, logsBloom, prevRandao, blockNumber, gasLimit, gasUsed, timestamp, extraData, baseFeePerGas, blockHash, transactions, withdrawals, blobGasUsed, excessBlobGas), keep the second param as the versioned hashes array and the third as the parentBeaconBlockRoot, and ensure the response example remains unchanged (status and latestValidHash). ``` </details> </blockquote></details> <details> <summary>docs/getting-started/cosmos/quickstart.md-65-68 (1)</summary><blockquote> `65-68`: _⚠️ Potential issue_ | _🟡 Minor_ **Fenced code block lacks a language specifier (MD040).** The log output block has no language hint, which triggers the `MD040` markdownlint warning. Add `text` or `console`: <details> <summary>✏️ Proposed fix</summary> ```diff -``` +```text INF block marked as DA included blockHeight=1 INF block marked as DA included blockHeight=2 ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/getting-started/cosmos/quickstart.mdaround lines 65 - 68, The fenced
code block containing the two log lines "INF block marked as DA included
blockHeight=1" and "INF block marked as DA included blockHeight=2" is missing a
language specifier and triggers MD040; update that code fence to include a
language hint such as text or console (e.g., change the openingtotext)
so the block is properly annotated.</details> </blockquote></details> <details> <summary>docs/reference/api/engine-api.md-13-17 (1)</summary><blockquote> `13-17`: _⚠️ Potential issue_ | _🟡 Minor_ **"Generate JWT from shared secret" is misleading — the command generates the shared secret, not a JWT.** `openssl rand -hex 32 > jwt.hex` produces the 32-byte shared secret file. The JWT token that goes in the `Authorization: Bearer` header is derived from this secret by the client at runtime. <details> <summary>✏️ Suggested fix</summary> ```diff -Generate JWT from shared secret: +Generate the shared secret file used for JWT authentication: ```bash openssl rand -hex 32 > jwt.hex ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/api/engine-api.md` around lines 13 - 17, The heading "Generate JWT from shared secret" is misleading; update the text that precedes the code block to say that the command generates a 32-byte shared secret (e.g., "Generate shared secret" or "Generate 32-byte shared secret") and add a short clarifying sentence that the JWT used in the Authorization: Bearer header is derived by the client at runtime from that secret; change the label/reference to the openssl command `openssl rand -hex 32 > jwt.hex` accordingly so the docs reflect that the command creates the secret file, not the JWT. ``` </details> </blockquote></details> <details> <summary>docs/ev-abci/modules/staking-wrapper.md-53-67 (1)</summary><blockquote> `53-67`: _⚠️ Potential issue_ | _🟡 Minor_ **Missing `authtypes` and `govtypes` imports in the `app.go` snippet.** `authtypes.NewModuleAddress(govtypes.ModuleName).String()` on line 65 references two packages that are absent from the import block. Developers copying this snippet will get a compile error. <details> <summary>🐛 Proposed fix</summary> ```diff import ( + authtypes "github.com/cosmos/cosmos-sdk/x/auth/types" + govtypes "github.com/cosmos/cosmos-sdk/x/gov/types" stakingkeeper "github.com/evstack/ev-abci/modules/staking/keeper" stakingtypes "github.com/cosmos/cosmos-sdk/x/staking/types" ) ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/ev-abci/modules/staking-wrapper.md` around lines 53 - 67, The snippet calling authtypes.NewModuleAddress(govtypes.ModuleName).String() is missing the authtypes and govtypes imports; update the import block used with NewKeeper to include authtypes and govtypes (e.g., the packages that expose NewModuleAddress and ModuleName from the x/auth/types and x/gov/types modules) so the reference in app.StakingKeeper = stakingkeeper.NewKeeper(...) compiles. ``` </details> </blockquote></details> <details> <summary>docs/reference/api/rpc-endpoints.md-133-151 (1)</summary><blockquote> `133-151`: _⚠️ Potential issue_ | _🟡 Minor_ **Type inconsistency in `/da_status` response: `pending_blocks` is an integer while heights are JSON strings.** `da_height` and `last_submitted_height` are serialized as strings (e.g., `"5000"`), but `pending_blocks` is a bare integer (`1`). Consumers deserialising this response will need to handle mixed numeric types. If this reflects the actual wire format, add a note explaining the distinction; otherwise, make the types consistent. <details> <summary>💡 Proposed fix (if heights and counts should align)</summary> ```diff "result": { "da_height": "5000", "last_submitted_height": "999", - "pending_blocks": 1 + "pending_blocks": "1" }, ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/api/rpc-endpoints.md` around lines 133 - 151, The example response for the POST /da_status endpoint is inconsistent: da_height and last_submitted_height are JSON strings while pending_blocks is an integer; update the example so types are consistent (e.g., change pending_blocks to a string "1") and add a short note next to the /da_status docs clarifying the chosen convention for da_height, last_submitted_height and pending_blocks (or, if you prefer numeric counts, convert da_height and last_submitted_height to numbers instead); target the response JSON example and the /da_status documentation entry, referencing the fields da_height, last_submitted_height, and pending_blocks. ``` </details> </blockquote></details> <details> <summary>docs/guides/running-nodes/aggregator.md-98-105 (1)</summary><blockquote> `98-105`: _⚠️ Potential issue_ | _🟡 Minor_ **Passphrase on the command line is a documentation anti-pattern.** All three complete examples (`--evnode.signer.passphrase "secret"` / `"your-passphrase"`) expose the passphrase via shell history and process listings. Add a brief callout recommending the use of an environment variable or a prompt-based approach in production: <details> <summary>💡 Suggested note</summary> ```diff +> **Note:** Avoid passing the passphrase on the command line in production. Use an environment variable +> (e.g. `EVNODE_SIGNER_PASSPHRASE`) or a secrets manager instead, as command-line arguments are visible +> in the process list and stored in shell history. + # Using file-based signer evnode start \ --evnode.node.aggregator \ ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/guides/running-nodes/aggregator.md` around lines 98 - 105, The examples currently show using --evnode.signer.passphrase on the command line which leaks secrets; update the aggregator.md examples to remove the inline passphrase and add a short callout recommending using an environment variable (e.g., EVNODE_SIGNER_PASSPHRASE) or an interactive prompt/secret manager for production, and include a one-sentence warning that command-line passphrases are exposed via shell history and process listings; place this note adjacent to the examples that reference --evnode.signer.passphrase so readers see the recommendation when scanning the example block. ``` </details> </blockquote></details> <details> <summary>docs/reference/specs/store.md-34-35 (1)</summary><blockquote> `34-35`: _⚠️ Potential issue_ | _🟡 Minor_ **Grammar: “An Evolve full node”.** Replace “A Evolve…” with “An Evolve…” for correct article usage. As per coding guidelines, user-facing text quality issues such as typographical/grammatical errors should be flagged. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/specs/store.md` around lines 34 - 35, Change the article in the sentence that currently reads "A Evolve full node is [initialized]..." to "An Evolve full node is [initialized]..." so the user-facing documentation uses correct grammar; update the exact string "A Evolve full node is [initialized][full_node_store_initialization] using `NewDefaultKVStore`..." to the corrected "An Evolve full node..." in docs/reference/specs/store.md. ``` </details> </blockquote></details> <details> <summary>docs/reference/specs/full-node.md-84-85 (1)</summary><blockquote> `84-85`: _⚠️ Potential issue_ | _🟡 Minor_ **Hyphenate “Peer‑to‑Peer” consistently.** The reference label uses “Peer to Peer” while the body uses “peer‑to‑peer.” Consider standardizing to “Peer‑to‑Peer.” As per coding guidelines, user-facing text quality issues such as typographical/grammatical errors should be flagged. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/specs/full-node.md` around lines 84 - 85, Update the reference label text to use a consistent "Peer-to-Peer" hyphenation: change the link label "[Peer to Peer Client]" to "[Peer-to-Peer Client]" so it matches the body usage (and keep the reference target "[peer-to-peer client]" unchanged); ensure any other occurrences of the label in this document follow the same "Peer-to-Peer" capitalization and hyphenation. ``` </details> </blockquote></details> <details> <summary>docs/getting-started/evm/deploy-contracts.md-86-93 (1)</summary><blockquote> `86-93`: _⚠️ Potential issue_ | _🟡 Minor_ **Avoid `undefined` accounts when `PRIVATE_KEY` is unset.** As written, `accounts: [process.env.PRIVATE_KEY]` will pass `[undefined]` if the env var isn’t set. Recommend documenting the required `0x`‑prefixed key or adding a guard in the snippet. <details> <summary>✍️ Suggested snippet</summary> ```diff - accounts: [process.env.PRIVATE_KEY], + accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [], ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/evm/deploy-contracts.md` around lines 86 - 93, The Hardhat config snippet currently sets networks.local.accounts to [process.env.PRIVATE_KEY] which can yield [undefined] if PRIVATE_KEY is unset; update the networks.local.accounts assignment in the exported config to guard against undefined (e.g., only include the key when process.env.PRIVATE_KEY is truthy or filter out falsy values) and document that PRIVATE_KEY must be a 0x‑prefixed private key; change references to networks.local.accounts and process.env.PRIVATE_KEY accordingly and ensure the exported module still exports solidity and networks as before. ``` </details> </blockquote></details> <details> <summary>docs/guides/advanced/custom-precompiles.md-27-54 (1)</summary><blockquote> `27-54`: _⚠️ Potential issue_ | _🟡 Minor_ **Use valid hex addresses in examples.** `"0xBridgeContract"` and `0xRecipient` are not valid hex addresses and will break copy/paste for users. Replace with 20‑byte hex literals. <details> <summary>🛠️ Suggested fix</summary> ```diff - "admin": "0xBridgeContract", + "admin": "0x000000000000000000000000000000000000b0b0", ``` ```diff - 0xRecipient, + 0x000000000000000000000000000000000000dEaD, ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/guides/advanced/custom-precompiles.md` around lines 27 - 54, Replace the placeholder non-hex identifiers with real 20-byte hex literals in both the JSON precompile config ("mintPrecompile" -> "admin" and "address") and the Solidity usage example that calls IMint.mint; specifically, change `"0xBridgeContract"` and `0xRecipient` to valid 20-byte hex addresses (0x-prefixed 40-hex-character values) so the JSON example and the IMint(0x000...0100).mint(...) call are copy/paste-ready and use proper Ethereum address formats. ``` </details> </blockquote></details> <details> <summary>docs/reference/specs/block-validity.md-53-114 (1)</summary><blockquote> `53-114`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix markdown/backtick typo and pseudocode casing.** There are stray double backticks in “Verify()`` step” and inconsistent `If` capitalization in the pseudocode block. <details> <summary>✅ Suggested edits</summary> ```diff - If !sd.Signer.IsEmpty(): + if !sd.Signer.IsEmpty(): - | Height | Height of the previous accepted header, plus 1. | checked in the `Verify()`` step | + | Height | Height of the previous accepted header, plus 1. | checked in the `Verify()` step | ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/specs/block-validity.md` around lines 53 - 114, Fix the markdown and pseudocode casing: remove the stray double backticks so instances like "checked in the `Verify()`` step" and "checked in the `ValidateBasic()`` step" read with a single code span (e.g., `Verify()` and `ValidateBasic()`), and normalize pseudocode capitalization in the Verify pseudocode block by changing `If` to `if` (e.g., lines inside SignedHeader.Verify / Header.Verify such as "If untrustedHeader.Height != h.Height + 1" -> "if untrustedHeader.Height != h.Height + 1") to match the rest of the docs and the function names SignedHeader.Verify and Header.Verify. ``` </details> </blockquote></details> <details> <summary>docs/getting-started/evm/quickstart.md-20-22 (1)</summary><blockquote> `20-22`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the log-output fence.** Use `text` for the expected log snippet. <details> <summary>💡 Suggested fix</summary> ```diff -``` +```text INF Listening on host=localhost port=7980 ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/getting-started/evm/quickstart.mdaround lines 20 - 22, Update the
fenced code block that currently contains the log line "INF Listening on
host=localhost port=7980" to include a language identifier (use "text") after
the opening backticks so the snippet is rendered as text; locate the markdown
fenced block containing that exact log output and change the opening fence from
totext.</details> </blockquote></details> <details> <summary>docs/reference/specs/block-manager.md-667-669 (1)</summary><blockquote> `667-669`: _⚠️ Potential issue_ | _🟡 Minor_ **Hyphenate “execution-layer” for readability.** Small grammar tweak improves clarity. <details> <summary>✍️ Suggested edit</summary> ```diff -...produce an execution layer tailored header if needed. +...produce an execution-layer tailored header if needed. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/specs/block-manager.md` around lines 667 - 669, The phrase "execution layer" in the listed bullets should be hyphenated as "execution-layer" for readability; update the text occurrences in this section (references such as the bullet text containing "execution layer tailored header" and nearby mentions in the lines discussing "Evolve Minimal Header" and "Executor supports custom signature payload providers for headers") to use "execution-layer" consistently. ``` </details> </blockquote></details> <details> <summary>docs/getting-started/evm/quickstart.md-62-65 (1)</summary><blockquote> `62-65`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the block-output fence.** Use `text` to satisfy markdownlint. <details> <summary>💡 Suggested fix</summary> ```diff -``` +```text INF block marked as DA included blockHeight=1 INF block marked as DA included blockHeight=2 ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/getting-started/evm/quickstart.mdaround lines 62 - 65, Update the
Markdown fenced code block that contains the lines starting with "INF block
marked as DA included blockHeight=1" and "INF block marked as DA included
blockHeight=2" to specify a language for the fence (use "text") so the block
becomestext ...; locate the triple-backtick fence in quickstart.md that
wraps those INF lines and add the language identifier immediately after the
opening backticks.</details> </blockquote></details> <details> <summary>docs/reference/specs/da.md-26-28 (1)</summary><blockquote> `26-28`: _⚠️ Potential issue_ | _🟡 Minor_ **Use “etc.” with a period.** Minor punctuation fix. <details> <summary>✍️ Suggested edit</summary> ```diff -...setting low gas price, etc, could return error. +...setting low gas price, etc., could return error. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/specs/da.md` around lines 26 - 28, Update the second bullet point text that mentions "[celestia-da-json-rpc][jsonrpc]" so that "etc" is written with a trailing period: change "etc" to "etc." (so the phrase becomes "... setting low gas price, etc., could return error.") to follow the reviewer punctuation suggestion. ``` </details> </blockquote></details> <details> <summary>docs/ev-abci/integration-guide.md-74-79 (1)</summary><blockquote> `74-79`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the “Expected flags” fence.** This block is currently an untyped fence; markdownlint flags it. Use `text` to keep it explicit. <details> <summary>💡 Suggested fix</summary> ```diff -``` +```text --evnode.node.aggregator Run as block producer --evnode.da.address DA layer address --evnode.signer.passphrase Signer passphrase --evnode.node.block_time Block production interval ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/ev-abci/integration-guide.mdaround lines 74 - 79, The fenced block
showing the expected flags is missing a language identifier; update the markdown
fence to usetext so it becomes a typed code block (e.g., replace the openingwith ```text) for the block containing the lines like
--evnode.node.aggregator, --evnode.da.address, --evnode.signer.passphrase, and
--evnode.node.block_time to satisfy markdownlint.</details> </blockquote></details> <details> <summary>docs/ev-abci/migration-from-cometbft.md-241-244 (1)</summary><blockquote> `241-244`: _⚠️ Potential issue_ | _🟡 Minor_ **Rephrase the “due to pruning” sentence for clarity.** This paragraph is a key instruction; a small wording tweak reads better. <details> <summary>✍️ Suggested edit</summary> ```diff -If blocks are missing (e.g., due to pruning), they will be skipped. +If blocks are missing (for example, because of pruning), they will be skipped. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/ev-abci/migration-from-cometbft.md` around lines 241 - 244, Reword the second bullet for clarity: replace "If blocks are missing (e.g., due to pruning), they will be skipped. Migration stops if more than the configured maximum number of blocks are missing" with a single clearer sentence such as "If blocks are missing—for example, because they were pruned—they will be skipped; if the number of missing blocks exceeds the configured maximum, the migration will stop," ensuring the meaning (skip missing blocks, abort when missing > configured maximum) remains unchanged. ``` </details> </blockquote></details> <details> <summary>docs/reference/configuration/ev-node-config.md-27-29 (1)</summary><blockquote> `27-29`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the DA Header Namespace ToC entry (missing/duplicate anchor).** The ToC links “DA Header Namespace” to `#da-namespace`, but there is no dedicated section for a header namespace and the anchor duplicates “DA Namespace.” Either add the section (with a distinct anchor) or remove the ToC entry. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/configuration/ev-node-config.md` around lines 27 - 29, The Table of Contents entry "DA Header Namespace" currently links to the duplicate anchor "#da-namespace"; fix by either removing the "DA Header Namespace" ToC line or adding a dedicated header section titled "DA Header Namespace" with a unique anchor (for example "#da-header-namespace") and ensure the ToC link points to that new anchor; update any heading text to match the ToC entry (e.g., add a heading "DA Header Namespace" and its content) so the anchor is unique and not duplicated with "DA Namespace". ``` </details> </blockquote></details> <details> <summary>docs/reference/configuration/ev-node-config.md-733-800 (1)</summary><blockquote> `733-800`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix relative paths to guides documentation.** The relative paths `../guides/da/visualizer.md` and `../guides/metrics.md` are incorrect. From `docs/reference/configuration/ev-node-config.md`, these resolve to a non-existent `docs/reference/guides/` directory. The correct paths should be `../../guides/da/visualizer.md` and `../../guides/metrics.md` to properly reference the files at `docs/guides/da/visualizer.md` and `docs/guides/metrics.md`. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/configuration/ev-node-config.md` around lines 733 - 800, Update the broken relative links in ev-node-config.md by replacing the link target "../guides/da/visualizer.md" with "../../guides/da/visualizer.md" and "../guides/metrics.md" with "../../guides/metrics.md" so the references from docs/reference/configuration/ev-node-config.md correctly resolve to docs/guides/da/visualizer.md and docs/guides/metrics.md; ensure both markdown links (the DA Visualizer Guide link and the "See [Metrics]" link) are updated accordingly. ``` </details> </blockquote></details> <details> <summary>docs/concepts/block-lifecycle.md-652-654 (1)</summary><blockquote> `652-654`: _⚠️ Potential issue_ | _🟡 Minor_ **Change `P2PConfig.Seeds` to `P2PConfig.Peers` in the documentation.** The P2PConfig struct in `pkg/config/config.go` defines the field as `Peers`, not `Seeds`. This should be updated to match the actual configuration parameter name: - Current (incorrect): `P2PConfig.Seeds` - Correct: `P2PConfig.Peers` <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/concepts/block-lifecycle.md` around lines 652 - 654, Update the documentation to reference the actual config field name: replace the incorrect P2PConfig.Seeds with P2PConfig.Peers in the text describing block sync over P2P; ensure any other mentions of P2PConfig.Seeds in this document are changed to P2PConfig.Peers so the docs match the struct defined in pkg/config/config.go. ``` </details> </blockquote></details> <details> <summary>docs/reference/configuration/ev-node-config.md-101-105 (1)</summary><blockquote> `101-105`: _⚠️ Potential issue_ | _🟡 Minor_ **Clarify the config file name (evnode.yml vs config.yaml).** This section references both `evnode.yml` and `config.yaml` as the YAML config. Please standardize on the actual filename used by ev-node to avoid confusion. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/configuration/ev-node-config.md` around lines 101 - 105, The doc references two different YAML filenames (`evnode.yml` and `config.yaml`) causing confusion; pick the canonical filename used by ev-node (e.g., `evnode.yml`) and update the paragraph to consistently use that name in both the path examples and the explanatory list, replacing any `config.yaml` occurrences with the chosen filename (`evnode.yml`) so the configuration precedence text and file path examples match exactly. ``` </details> </blockquote></details> <details> <summary>docs/reference/configuration/ev-node-config.md-407-410 (1)</summary><blockquote> `407-410`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix the example flag prefix in the signing_addresses documentation.** The flag name on line 408 is correct (`--evnode.da.signing_addresses`), but the example on line 409 incorrectly uses the `--rollkit.*` prefix. Update the example to use `--evnode.da.signing_addresses` to match the actual flag name defined in the code. <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/reference/configuration/ev-node-config.md` around lines 407 - 410, Update the documentation example to use the correct flag prefix for the signing addresses: replace the incorrect `--rollkit.da.signing_addresses` example with `--evnode.da.signing_addresses` so it matches the actual flag name `--evnode.da.signing_addresses` and the documented `signing_addresses` setting. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (10)</summary><blockquote> <details> <summary>scripts/utils.mk (2)</summary><blockquote> `18-18`: **Pin the `markdownlint-cli` version in both invocations to ensure reproducible linting.** `npx markdownlint-cli` without a version tag resolves to whatever npm finds at runtime. Since there is no `package.json` at the repository root to manage dependencies locally, inline version pinning is the appropriate solution here. Pin to `0.47.0` or your chosen stable version: ```diff - `@npx` markdownlint-cli --config .markdownlint.yaml '**/*.md' + `@npx` markdownlint-cli@0.47.0 --config .markdownlint.yaml '**/*.md' ``` ```diff - `@npx` markdownlint-cli --config .markdownlint.yaml --ignore './changelog.md' '**/*.md' -f + `@npx` markdownlint-cli@0.47.0 --config .markdownlint.yaml --ignore './changelog.md' '**/*.md' -f ``` Also applies to: 34-34 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@scripts/utils.mk` at line 18, Pin the markdownlint-cli invocation by replacing plain "npx markdownlint-cli" with a versioned invocation like "npx markdownlint-cli@0.47.0" in both places where it appears (the rule that runs "npx markdownlint-cli '**/*.md'"); ensure each occurrence uses the same pinned version to guarantee reproducible linting. ``` </details> --- `18-18`: **Update `markdownlint-cli` version pin to 0.47.0 or add as a pinned dev dependency.** `npx markdownlint-cli` without a version tag resolves to whatever version npm finds at runtime, producing non-deterministic results across environments. The current repository does not pin this in `package.json`, so version pinning at the command level is necessary. <details> <summary>🔧 Proposed fix — pin the version</summary> ```diff - `@npx` markdownlint-cli --config .markdownlint.yaml '**/*.md' + `@npx` markdownlint-cli@0.47.0 --config .markdownlint.yaml '**/*.md' ``` ```diff - `@npx` markdownlint-cli --config .markdownlint.yaml --ignore './changelog.md' '**/*.md' -f + `@npx` markdownlint-cli@0.47.0 --config .markdownlint.yaml --ignore './changelog.md' '**/*.md' -f ``` </details> Alternatively, add `markdownlint-cli` as a pinned dev dependency in `package.json`. Also applies to: 34-34 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@scripts/utils.mk` at line 18, The markdown lint invocation uses an unpinned npx call ("npx markdownlint-cli ...") which causes non-deterministic versions; update the command to pin the CLI to 0.47.0 (e.g., use "npx markdownlint-cli@0.47.0") or instead add "markdownlint-cli": "0.47.0" to package.json devDependencies and update scripts to call "npx markdownlint-cli" reliably; modify the line invoking npx markdownlint-cli to use the pinned version or add the devDependency and ensure CI/locals use that pinned version. ``` </details> </blockquote></details> <details> <summary>docs/guides/operations/upgrades.md (1)</summary><blockquote> `51-61`: **Consider pinning versions instead of `latest` for reproducible upgrades.** Using `@latest`/`:latest` can make upgrades non-deterministic. Consider aligning with the versioned examples already shown (e.g., `v1.2.3`). <details> <summary>🔧 Suggested tweak</summary> ```diff -# Using Go: -go install github.com/evstack/ev-node@latest +# Using Go: +go install github.com/evstack/ev-node@v1.2.3 ``` ```diff -# Using Docker: -docker pull evstack/evnode:latest +# Using Docker: +docker pull evstack/evnode:v1.2.3 ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/guides/operations/upgrades.md` around lines 51 - 61, Replace the non-deterministic `@latest` and `:latest` examples with pinned release tags so upgrades are reproducible: update the Go example `go install github.com/evstack/ev-node@latest` to use a versioned tag like `go install github.com/evstack/ev-node@vX.Y.Z` and update the Docker example `docker pull evstack/evnode:latest` to `docker pull evstack/evnode:vX.Y.Z`; optionally show a placeholder variable (e.g., `RELEASE=v1.2.3`) and examples using that to encourage consistent pinning. ``` </details> </blockquote></details> <details> <summary>docs/overview/what-is-evolve.md (1)</summary><blockquote> `7-16`: **Tighten phrasing and hyphenation for readability.** Minor style tweaks will improve flow and consistency (e.g., avoid repeated “No …” openers, use “open-source”). <details> <summary>✍️ Suggested edits</summary> ```diff -This isn't a toolkit. It's a launch stack. - -No fees. No middlemen. No revenue share. +This isn't a toolkit. It's a launch stack. +No fees, no middlemen, no revenue share. @@ -- **Customizability:** Evolve is built as an open source modular framework, to make it easier for developers to reuse the four main components and customize their chains. +- **Customizability:** Evolve is built as an open-source modular framework, to make it easier for developers to reuse the four main components and customize their chains. ``` </details> Also applies to: 63-64 <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/overview/what-is-evolve.md` around lines 7 - 16, Tighten phrasing and hyphenation under the "## What is Evolve" section: replace the repeated short sentences "No fees. No middlemen. No revenue share." with a single, smoother negative phrase (e.g., "No fees, middlemen, or revenue share."), use "open-source" (hyphenated) instead of "open source"/"open-source" inconsistency, and prefer explicit subject phrasing (replace "It's open-source, production-ready, and fully composable." with "Evolve is open-source, production-ready, and fully composable.") to improve flow; apply the same hyphenation and phrasing consistency to the similar occurrence referenced (63-64). ``` </details> </blockquote></details> <details> <summary>docs/ev-reth/engine-api.md (1)</summary><blockquote> `25-25`: **Add language specifier to the flow diagram code fence (MD040)** <details> <summary>✏️ Proposed fix</summary> ```diff -``` +```text ev-node ev-reth ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/ev-reth/engine-api.mdat line 25, The code fence containing the flow
diagram currently uses a plainfence; update it to include a language specifier (e.g., changetotext) so the block becomestext with the
diagram lines (ev-node ev-reth) inside; this
satisfies MD040 and ensures the diagram is treated as plain text by markdown
renderers.</details> </blockquote></details> <details> <summary>docs/concepts/fee-systems.md (1)</summary><blockquote> `11-13`: **Add language specifiers to unlabeled fenced code blocks (MD040)** Three code fences lack a language token. Use `text` for the formula and ASCII diagram blocks to satisfy the markdownlint rule and be consistent with the rest of the file. <details> <summary>✏️ Proposed fix</summary> ```diff -``` +```text Transaction Fee = (Base Fee + Priority Fee) × Gas Used ``` ``` ```diff -``` +```text Transaction Fee = Gas Price × Gas Used ``` ``` ```diff -``` +```text User Transaction ... ``` ``` </details> Also applies to: 41-43, 110-131 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@docs/concepts/fee-systems.mdaround lines 11 - 13, Add the missing language
specifiertextto the unlabeled fenced code blocks that contain the formula
"Transaction Fee = (Base Fee + Priority Fee) × Gas Used", the formula
"Transaction Fee = Gas Price × Gas Used", and the ASCII diagram starting with
"User Transaction ..."; update those triple-backtick fences to begin withto the other unlabeled fences referenced in the review).docs/ev-abci/rpc-compatibility.md (1)
87-102:{ ... }placeholder makes the commit example invalid JSON.Using
{ ... }as a stand-in is a common pattern, but JSON parsers (and doc linters that validate code blocks) will reject it. Use an empty object or a commented-out placeholder instead:✏️ Suggested fix
"signed_header": { - "header": { ... }, + "header": {},🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ev-abci/rpc-compatibility.md` around lines 87 - 102, The JSON example under "signed_header" uses an invalid "{ ... }" placeholder for the "header" field; replace that placeholder with a valid empty object or a JSON-safe placeholder (e.g., "{}" or a clear commented note outside the code block) so the "signed_header" -> "header" object becomes valid JSON and doc linters/parsers will accept the example; ensure the structure still shows "signed_header", "header", and "commit" with their fields intact.docs/getting-started/custom/implement-executor.md (1)
204-217: Test example references undefined variablesctx,genesis, andtxs.Readers who try to run this directly will see compile errors. A brief setup showing how to obtain these values would make the example self-contained.
✏️ Suggested addition
func TestExecuteTxs(t *testing.T) { exec := NewMyExecutor() + ctx := context.Background() + genesis := Genesis{AppState: []byte(`{"balances":{}}`)} + txs := [][]byte{} // Initialize _, err := exec.InitChain(ctx, genesis)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/custom/implement-executor.md` around lines 204 - 217, The test snippet references undefined variables (ctx, genesis, txs) causing compile errors; update TestExecuteTxs so it is self-contained by showing minimal setup: create a context (e.g., context.Background()) and assign it to ctx, construct a small example genesis state and pass it to exec.InitChain (or call the package helper that builds genesis) for the genesis variable, and prepare a sample tx slice (e.g., one or two simple transactions or an appropriately typed empty slice) to use as txs before calling exec.ExecuteTxs; keep the existing calls to NewMyExecutor, exec.InitChain, and exec.ExecuteTxs unchanged, only adding the setup lines to define ctx, genesis, and txs.docs/reference/api/rpc-endpoints.md (1)
60-105: Inconsistent response examples for/header,/block_by_hash, and/tx.These three endpoints document only the request, while
/blockdocuments both request and response. Similarly,/statusand/da_statusdocument only the response. For a consistent reference, each endpoint should include both a request and a response example.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reference/api/rpc-endpoints.md` around lines 60 - 105, The documentation is inconsistent: the endpoints "header", "block_by_hash", and "tx" only show request examples while "block" shows both request and response (and "status"/"da_status" show only response). Add a matching response example for each of the "header", "block_by_hash", and "tx" endpoints following the same JSON-RPC response structure used by "block" (include "jsonrpc", "id", and a representative "result" object with realistic fields), and ensure "status" and "da_status" also include corresponding request examples or explicitly mirror the chosen convention so all endpoints consistently show both request and response examples.docs/ev-abci/modules/staking-wrapper.md (1)
31-35: Repeated "normally" in three consecutive bullets degrades readability.The static analysis flag is valid here.
✏️ Suggested rewrite
-Before migration is triggered, the wrapper behaves identically to the standard staking module: +Before migration is triggered, the wrapper behaves identically to the standard staking module. +All standard operations continue without change: -- Delegations work normally -- Validator operations work normally -- Rewards distribution works normally +- Delegations and undelegations +- Validator creation and modification +- Rewards distribution🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ev-abci/modules/staking-wrapper.md` around lines 31 - 35, The three bullet points under the pre-migration behavior repeat the word "normally," hurting readability; update the list in staking-wrapper.md so each bullet uses distinct phrasing (e.g., "Delegations operate as usual", "Validator operations remain unchanged", "Rewards are distributed as expected") or consolidate into a single sentence like "Before migration is triggered, the wrapper behaves identically to the standard staking module: delegations, validator operations, and rewards distribution continue as before." Reference the bullets in the pre-migration behavior section to apply the wording change.
| Key metrics to watch: | ||
|
|
||
| - `evolve_block_height` - Current block height | ||
| - `evolve_da_submission_total` - DA submissions count | ||
| - `evolve_da_submission_failures` - Failed DA submissions |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for the documented metric names and Prometheus registration patterns
rg -n "evolve_block_height|evolve_da_submission_total|evolve_da_submission_failures|prometheus\.MustRegister|promauto\.NewCounter|promauto\.NewGauge" --type=go -A2Repository: evstack/ev-node
Length of output: 41
🏁 Script executed:
#!/bin/bash
# Explore repository structure
git ls-files | head -30
echo "---"
# Look for metrics-related files
find . -type f -name "*metric*" -o -name "*prometheus*" 2>/dev/null | head -20
echo "---"
# Check file types present
file $(git ls-files | head -10)Repository: evstack/ev-node
Length of output: 1286
🏁 Script executed:
#!/bin/bash
# Search for aggregator-related files
find . -type f -name "*aggregator*" 2>/dev/null | head -20
echo "---"
# Search for the specific metric names in all Go files
rg "evolve_block_height|evolve_da_submission_total|evolve_da_submission_failures" --type=goRepository: evstack/ev-node
Length of output: 161
🏁 Script executed:
#!/bin/bash
# Examine the metrics.go files
echo "=== block/internal/common/metrics.go ==="
cat -n ./block/internal/common/metrics.go | head -100
echo ""
echo "=== pkg/p2p/metrics.go ==="
cat -n ./pkg/p2p/metrics.go | head -100Repository: evstack/ev-node
Length of output: 9572
🏁 Script executed:
#!/bin/bash
# Search for "evolve" anywhere in the codebase
rg "evolve" --type=go --type=md 2>/dev/null | head -20
echo "---"
# Get the complete metrics.go file to see all DA metrics
cat ./block/internal/common/metrics.go | grep -n "DA\|Gauge\|Counter" | head -40Repository: evstack/ev-node
Length of output: 4731
🏁 Script executed:
#!/bin/bash
# Get the rest of metrics.go to see metric registrations
tail -n +100 ./block/internal/common/metrics.go | head -200Repository: evstack/ev-node
Length of output: 6504
Fix incorrect Prometheus metric names in documentation.
The documented metric names do not match the actual registered names in the codebase:
evolve_block_height→ Should be<namespace>_sequencer_latest_block_heightevolve_da_submission_total→ No such metric exists (did you meanda_submitter_pending_blobsfor pending count?)evolve_da_submission_failures→ Should be<namespace>_sequencer_da_submitter_failures_total
The "evolve" prefix is incorrect; metrics use the "sequencer" subsystem. Review the intended metrics and provide accurate names that match the implementation in block/internal/common/metrics.go.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/running-nodes/aggregator.md` around lines 144 - 148, The docs
list incorrect Prometheus metric names; update
docs/guides/running-nodes/aggregator.md to use the actual metric names defined
in block/internal/common/metrics.go: replace the incorrect "evolve_block_height"
with "<namespace>_sequencer_latest_block_height", change
"evolve_da_submission_total" to the intended pending metric
"da_submitter_pending_blobs" (if you meant pending count), and replace
"evolve_da_submission_failures" with
"<namespace>_sequencer_da_submitter_failures_total"; ensure the docs use the
"sequencer" subsystem prefix consistent with the metrics.go definitions.
There was a problem hiding this comment.
Actionable comments posted: 13
♻️ Duplicate comments (1)
docs/guides/operations/troubleshooting.md (1)
22-31: View Logs section now covers all three common runtimes.Including systemd, foreground, and Docker variants is a solid improvement.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/operations/troubleshooting.md` around lines 22 - 31, The docs contain a duplicated approval/comment line around the "View Logs" section; remove the duplicate so the explanatory sentence appears only once and keep the log examples intact (the code block containing "journalctl -u evnode -f", "./evnode start ... 2>&1 | tee evnode.log", and "docker logs -f <container_name>" should remain unchanged). Ensure there are no repeated approval markers like "[approve_code_changes]" or repeated sentences describing the three runtimes.
🧹 Nitpick comments (3)
docs/getting-started/choose-your-path.md (1)
41-66: Use relative links for internal docs references.Internal links currently use absolute paths (e.g.,
/getting-started/...). The docs guideline requires relative links in markdown files. Please switch to relative paths from this file’s location.
As per coding guidelines: “Use relative links for internal documentation references in markdown files.”♻️ Example fix
-**→ [EVM Quickstart](/getting-started/evm/quickstart)** +**→ [EVM Quickstart](./evm/quickstart)** ... -**→ [Cosmos SDK Quickstart](/getting-started/cosmos/quickstart)** +**→ [Cosmos SDK Quickstart](./cosmos/quickstart)** ... -**→ [Custom Executor Quickstart](/getting-started/custom/quickstart)** +**→ [Custom Executor Quickstart](./custom/quickstart)**Also applies to: 92-92
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/choose-your-path.md` around lines 41 - 66, Replace absolute internal links in this markdown (e.g., the link targets for "EVM Quickstart" and "Cosmos SDK Quickstart") with relative paths from this file's location; search for links that start with "/getting-started/..." and update them to the correct relative paths (for example "../evm/quickstart" or "../cosmos/quickstart" as appropriate), and apply the same fix to the other occurrence noted around line 92; update the link targets only, leaving the link text and surrounding headings unchanged.docs/guides/operations/deployment.md (1)
5-60: Restructure as step‑by‑step to meet guides requirement.This page is an index, but docs/guides/** should be step-by-step. Consider adding a short numbered flow (pick scale → follow guide → run checklist → proceed to next steps), or move the index to a non‑guide section.
As per coding guidelines: "docs/guides/**/*.md: Structure guides with clear step-by-step instructions".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/operations/deployment.md` around lines 5 - 60, This page is currently an index; restructure it into a clear step-by-step guide by turning the existing sections ("🏗️ Deployment Scales", "📚 Available Deployment Guides", "✅ Before You Deploy") into a numbered flow: 1) Pick your deployment scale (local/testnet/mainnet) with a one‑line decision hint, 2) Follow the corresponding linked guide (replace the bulleted "Available Deployment Guides" list with a single step linking each guide), 3) Run the pre-deploy checklist (promote the "✅ Before You Deploy" items into concrete checklist steps to execute), and 4) Proceed to "Next Steps" for production hardening; alternatively, if you want to keep an index, move this file out of docs/guides/ to a non-guide section and add a short step-by-step guide here instead.docs/guides/advanced/forced-inclusion.md (1)
1-129: Consider relocating or adding step-by-step structure.This is comprehensive technical documentation but sits under docs/guides/advanced, which requires step-by-step guidance. Consider moving it to docs/learn (and linking from guides), or add a concise step-by-step “How to use forced inclusion” section.
Based on learnings: "Applies to docs/learn//*.md : Place comprehensive technical documentation in the
docs/learn/directory, including sequencing concepts and technical specifications".
As per coding guidelines: "docs/guides//*.md: Structure guides with clear step-by-step instructions".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/advanced/forced-inclusion.md` around lines 1 - 129, This doc is comprehensive technical content but lives under docs/guides/advanced (which expects step-by-step guides); either move the page to docs/learn (keeping the "Forced Inclusion" title and all technical sections including references to DAEpochForcedInclusion and MaxBytes) and add a short guide link from docs/guides, or keep it here but add a concise "How to use forced inclusion" step-by-step section at the top (3–6 numbered steps showing: how to submit to DA, when sequencer retrieves forced txs, and inclusion deadlines) and retain the existing detailed sections below; also add a cross-link to Based Sequencing (./based.md) and ensure the new step-by-step references DAEpochForcedInclusion and MaxBytes so readers can find the technical specifics.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/concepts/block-lifecycle.md`:
- Around line 682-685: Update the wording for the soft confirmation field:
change the description for the symbol soft_confirmed_height from "Height of last
soft confirmed block" to "Height of last soft-confirmed block" so the compound
adjective is hyphenated; leave the other entries (sync_height,
da_included_height, header_store_height) unchanged.
In `@docs/concepts/data-availability.md`:
- Around line 70-72: Update the three internal markdown links so they are
relative rather than absolute: replace "[Local DA
Guide](/guides/da-layers/local-da)", "[Celestia
Guide](/guides/da-layers/celestia)", and "[DA Interface
Reference](/reference/interfaces/da)" with relative paths from this document
(e.g. "../guides/da-layers/local-da", "../guides/da-layers/celestia", and
"../reference/interfaces/da"), ensuring all internal docs follow the
docs/**/*.md relative-link guideline.
- Around line 33-50: The fenced ASCII diagram block is missing a language tag
which triggers MD040; update the fenced code block shown (the block starting
with the ASCII "Block Produced" diagram) to include a language identifier (use
`text`) after the opening triple backticks so the diagram is ```text ... ```;
keep the diagram content unchanged other than adding the language tag.
In `@docs/getting-started/choose-your-path.md`:
- Around line 96-112: The fenced decision-tree code block that starts with the
triple backticks above "Do you have an existing Cosmos SDK chain?" is missing a
language tag; update that opening fence from ``` to a tagged fence such as
```text (or ```console) so markdownlint passes and the docs remain consistent.
In `@docs/guides/da-layers/celestia.md`:
- Around line 207-229: The markdown uses absolute internal links (e.g., the link
text "Troubleshooting Guide" with target /guides/operations/troubleshooting,
"Local DA Guide" /guides/da-layers/local-da, "Troubleshooting"
/guides/operations/troubleshooting, and "Configuration Reference"
/reference/configuration/ev-node-config); change each absolute path to a
relative path consistent with docs guidelines (for example replace
/guides/operations/troubleshooting with ../operations/troubleshooting or the
appropriate relative path from docs/guides/da-layers/celestia.md) so all
internal references are relative links.
In `@docs/guides/operations/troubleshooting.md`:
- Around line 66-68: Add a language identifier "log" to the fenced code blocks
that contain the DA layer error lines so they satisfy MD040; specifically update
the code fences that wrap the text "ERR DA layer submission failed
error=\"connection refused\"" and the one that wraps "ERR DA layer submission
failed error=\"Codespace: 'sdk', Code: 19, Message: \"" by changing the opening
``` to ```log and ensuring each block ends with ``` so the blocks are fenced as
```log ... ```.
- Around line 197-206: The current step uses the glob "rm -rf ~/.evnode/data/*"
which skips hidden files; change the instructions to remove the entire data
directory and recreate it instead: replace the rm -rf ~/.evnode/data/* step with
a directory-level removal of ~/.evnode/data followed by recreating the directory
(so all hidden files like .lock or .db are removed), and keep the surrounding
systemctl stop evnode and systemctl start evnode steps unchanged.
- Line 293: Update the "Discord" bullet in the Troubleshooting section by either
adding the missing URL (replace the standalone "Discord" bullet with "Discord —
<insert URL>" or markdown link format [Discord](https://...) ) or remove the
bullet entirely until a valid link is available; look for the bullet labeled
"Discord" in the docs/guides/operations/troubleshooting.md content and make the
change so the entry is actionable.
- Line 110: Replace absolute internal markdown links with relative paths in the
troubleshooting doc: find occurrences of '/guides/restart-chain' and replace
with '../restart-chain', '/guides/reset-state' replace with '../reset-state',
and '/guides/operations/monitoring' replace with './monitoring' so all internal
references use relative links (update each instance noted in the review).
In `@docs/guides/running-nodes/full-node.md`:
- Line 5: Fix two minor grammar issues: replace the phrase "a Evolve-based
blockchain network" with "an Evolve-based blockchain network" (update the
article before "Evolve-based"), and change any instances of "lets call it" to
the contraction "let's call it" (add the apostrophe). Search for the exact
strings "a Evolve-based blockchain network" and "lets call it" in the content
and update them accordingly.
In `@docs/overview/what-is-evolve.md`:
- Around line 89-92: Replace the time-relative phrases in the two sentences:
change "As of today, Evolve provides..." to a concrete snapshot like "As of
2026-02-24, Evolve provides..." (or to a specific release/version), and reword
"We're currently working on implementing many new and exciting features such as
light nodes and state fraud proofs." to a date-scoped or version-scoped
statement such as "Planned features (as of 2026-02-24) include light nodes and
state fraud proofs." so the document remains unambiguous and does not become
stale; update the two quoted sentence strings accordingly.
- Around line 15-18: Run the VitePress link validator and fix any broken links:
run make testlink and address any failures for the newly added links in this
file (the external GitHub URL https://github.com/evstack/ev-node and the
internal Execution interface link
https://github.com/evstack/ev-node/blob/main/core/execution/execution.go and the
mention of ev-node); update the URLs or markdown link targets in
what-is-evolve.md (and the same changes around lines referenced 79-85) so that
make testlink passes without errors.
In `@docs/reference/interfaces/da.md`:
- Around line 191-195: Update the "See Also" section: replace the three absolute
internal links "/concepts/data-availability", "/guides/da-layers/celestia", and
"/guides/da-layers/local-da" with relative Markdown links (e.g.,
../concepts/data-availability or appropriate relative paths) so internal
references in the "See Also" section resolve correctly; modify the links in the
docs reference for the Data Availability interface (the "See Also" heading and
the three listed link items) to use relative paths.
---
Duplicate comments:
In `@docs/guides/operations/troubleshooting.md`:
- Around line 22-31: The docs contain a duplicated approval/comment line around
the "View Logs" section; remove the duplicate so the explanatory sentence
appears only once and keep the log examples intact (the code block containing
"journalctl -u evnode -f", "./evnode start ... 2>&1 | tee evnode.log", and
"docker logs -f <container_name>" should remain unchanged). Ensure there are no
repeated approval markers like "[approve_code_changes]" or repeated sentences
describing the three runtimes.
---
Nitpick comments:
In `@docs/getting-started/choose-your-path.md`:
- Around line 41-66: Replace absolute internal links in this markdown (e.g., the
link targets for "EVM Quickstart" and "Cosmos SDK Quickstart") with relative
paths from this file's location; search for links that start with
"/getting-started/..." and update them to the correct relative paths (for
example "../evm/quickstart" or "../cosmos/quickstart" as appropriate), and apply
the same fix to the other occurrence noted around line 92; update the link
targets only, leaving the link text and surrounding headings unchanged.
In `@docs/guides/advanced/forced-inclusion.md`:
- Around line 1-129: This doc is comprehensive technical content but lives under
docs/guides/advanced (which expects step-by-step guides); either move the page
to docs/learn (keeping the "Forced Inclusion" title and all technical sections
including references to DAEpochForcedInclusion and MaxBytes) and add a short
guide link from docs/guides, or keep it here but add a concise "How to use
forced inclusion" step-by-step section at the top (3–6 numbered steps showing:
how to submit to DA, when sequencer retrieves forced txs, and inclusion
deadlines) and retain the existing detailed sections below; also add a
cross-link to Based Sequencing (./based.md) and ensure the new step-by-step
references DAEpochForcedInclusion and MaxBytes so readers can find the technical
specifics.
In `@docs/guides/operations/deployment.md`:
- Around line 5-60: This page is currently an index; restructure it into a clear
step-by-step guide by turning the existing sections ("🏗️ Deployment Scales",
"📚 Available Deployment Guides", "✅ Before You Deploy") into a numbered flow:
1) Pick your deployment scale (local/testnet/mainnet) with a one‑line decision
hint, 2) Follow the corresponding linked guide (replace the bulleted "Available
Deployment Guides" list with a single step linking each guide), 3) Run the
pre-deploy checklist (promote the "✅ Before You Deploy" items into concrete
checklist steps to execute), and 4) Proceed to "Next Steps" for production
hardening; alternatively, if you want to keep an index, move this file out of
docs/guides/ to a non-guide section and add a short step-by-step guide here
instead.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
docs/concepts/block-lifecycle.mddocs/concepts/data-availability.mddocs/getting-started/choose-your-path.mddocs/getting-started/custom/quickstart.mddocs/guides/advanced/forced-inclusion.mddocs/guides/da-layers/celestia.mddocs/guides/operations/deployment.mddocs/guides/operations/troubleshooting.mddocs/guides/running-nodes/full-node.mddocs/overview/what-is-evolve.mddocs/reference/interfaces/da.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/getting-started/custom/quickstart.md
| - `sync_height`: Current sync height | ||
| - `da_included_height`: Height of last DA-included block | ||
| - `soft_confirmed_height`: Height of last soft confirmed block | ||
| - `header_store_height`: Current header store height |
There was a problem hiding this comment.
Minor grammar: hyphenate compound adjective.
"soft confirmed" reads better as "soft-confirmed".
✅ Suggested fix
-- `soft_confirmed_height`: Height of last soft confirmed block
+- `soft_confirmed_height`: Height of last soft-confirmed block📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `sync_height`: Current sync height | |
| - `da_included_height`: Height of last DA-included block | |
| - `soft_confirmed_height`: Height of last soft confirmed block | |
| - `header_store_height`: Current header store height | |
| - `sync_height`: Current sync height | |
| - `da_included_height`: Height of last DA-included block | |
| - `soft_confirmed_height`: Height of last soft-confirmed block | |
| - `header_store_height`: Current header store height |
🧰 Tools
🪛 LanguageTool
[grammar] ~684-~684: Use a hyphen to join words.
Context: ...t_confirmed_height: Height of last soft confirmed block - header_store_height`:...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/concepts/block-lifecycle.md` around lines 682 - 685, Update the wording
for the soft confirmation field: change the description for the symbol
soft_confirmed_height from "Height of last soft confirmed block" to "Height of
last soft-confirmed block" so the compound adjective is hyphenated; leave the
other entries (sync_height, da_included_height, header_store_height) unchanged.
| ``` | ||
| Block Produced | ||
| │ | ||
| ▼ | ||
| ┌─────────────────┐ | ||
| │ Submitter │ Queues block for DA | ||
| └────────┬────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────┐ | ||
| │ DA Layer │ Stores and orders data | ||
| └────────┬────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────┐ | ||
| │ Full Nodes │ Retrieve and verify | ||
| └─────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
Add a language to the fenced block.
MD040 requires a language tag; use text for the ASCII flow diagram.
✅ Suggested fix
-```
+```text
Block Produced
│
▼
┌─────────────────┐
│ Submitter │ Queues block for DA
└────────┬────────┘
│
▼
┌─────────────────┐
│ DA Layer │ Stores and orders data
└────────┬────────┘
│
▼
┌─────────────────┐
│ Full Nodes │ Retrieve and verify
└─────────────────┘
</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 33-33: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/concepts/data-availability.md around lines 33 - 50, The fenced ASCII
diagram block is missing a language tag which triggers MD040; update the fenced
code block shown (the block starting with the ASCII "Block Produced" diagram) to
include a language identifier (use text) after the opening triple backticks so
the diagram is text ... ; keep the diagram content unchanged other than
adding the language tag.
</details>
<!-- fingerprinting:phantom:triton:eagle -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - [Local DA Guide](/guides/da-layers/local-da) | ||
| - [Celestia Guide](/guides/da-layers/celestia) | ||
| - [DA Interface Reference](/reference/interfaces/da) |
There was a problem hiding this comment.
Use relative links for internal docs.
Internal references should be relative to satisfy docs/**/*.md guidelines.
✅ Suggested fix
-- [Local DA Guide](/guides/da-layers/local-da)
-- [Celestia Guide](/guides/da-layers/celestia)
-- [DA Interface Reference](/reference/interfaces/da)
+- [Local DA Guide](../guides/da-layers/local-da.md)
+- [Celestia Guide](../guides/da-layers/celestia.md)
+- [DA Interface Reference](../reference/interfaces/da.md)As per coding guidelines: "docs/**/*.md: Use relative links for internal documentation references in markdown files".
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [Local DA Guide](/guides/da-layers/local-da) | |
| - [Celestia Guide](/guides/da-layers/celestia) | |
| - [DA Interface Reference](/reference/interfaces/da) | |
| - [Local DA Guide](../guides/da-layers/local-da.md) | |
| - [Celestia Guide](../guides/da-layers/celestia.md) | |
| - [DA Interface Reference](../reference/interfaces/da.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/concepts/data-availability.md` around lines 70 - 72, Update the three
internal markdown links so they are relative rather than absolute: replace
"[Local DA Guide](/guides/da-layers/local-da)", "[Celestia
Guide](/guides/da-layers/celestia)", and "[DA Interface
Reference](/reference/interfaces/da)" with relative paths from this document
(e.g. "../guides/da-layers/local-da", "../guides/da-layers/celestia", and
"../reference/interfaces/da"), ensuring all internal docs follow the
docs/**/*.md relative-link guideline.
| ``` | ||
| Do you have an existing Cosmos SDK chain? | ||
| ├── Yes → Cosmos SDK (ev-abci) | ||
| └── No | ||
| │ | ||
| Do you need a custom VM or non-standard execution? | ||
| ├── Yes → Custom Executor | ||
| └── No | ||
| │ | ||
| Do you want maximum wallet/tooling support? | ||
| ├── Yes → EVM (ev-reth) | ||
| └── No | ||
| │ | ||
| Do you prefer Go over Solidity? | ||
| ├── Yes → Cosmos SDK (ev-abci) | ||
| └── No → EVM (ev-reth) | ||
| ``` |
There was a problem hiding this comment.
Specify a fenced code language.
The decision tree fence lacks a language tag. Add a language (e.g., text) to satisfy markdownlint and keep the docs consistent.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 96-96: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/getting-started/choose-your-path.md` around lines 96 - 112, The fenced
decision-tree code block that starts with the triple backticks above "Do you
have an existing Cosmos SDK chain?" is missing a language tag; update that
opening fence from ``` to a tagged fence such as ```text (or ```console) so
markdownlint passes and the docs remain consistent.
| See [Troubleshooting Guide](/guides/operations/troubleshooting) for details. | ||
|
|
||
| ### Connection Refused | ||
|
|
||
| Verify your Celestia node is running: | ||
|
|
||
| ```bash | ||
| curl http://localhost:26658/header/sync_state | ||
| ``` | ||
|
|
||
| ### Token Expired | ||
|
|
||
| Regenerate your auth token: | ||
|
|
||
| ```bash | ||
| celestia light auth write --p2p.network <network> | ||
| ``` | ||
|
|
||
| ## See Also | ||
|
|
||
| - [Local DA Guide](/guides/da-layers/local-da) - Development setup | ||
| - [Troubleshooting](/guides/operations/troubleshooting) - Common issues | ||
| - [Configuration Reference](/reference/configuration/ev-node-config) - All DA options |
There was a problem hiding this comment.
Use relative links for internal docs.
Absolute internal paths violate the docs link guideline.
✅ Suggested fix
-See [Troubleshooting Guide](/guides/operations/troubleshooting) for details.
+See [Troubleshooting Guide](../operations/troubleshooting.md) for details.
...
-- [Local DA Guide](/guides/da-layers/local-da) - Development setup
-- [Troubleshooting](/guides/operations/troubleshooting) - Common issues
-- [Configuration Reference](/reference/configuration/ev-node-config) - All DA options
+- [Local DA Guide](./local-da.md) - Development setup
+- [Troubleshooting](../operations/troubleshooting.md) - Common issues
+- [Configuration Reference](../../reference/configuration/ev-node-config.md) - All DA optionsAs per coding guidelines: "docs/**/*.md: Use relative links for internal documentation references in markdown files".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/da-layers/celestia.md` around lines 207 - 229, The markdown uses
absolute internal links (e.g., the link text "Troubleshooting Guide" with target
/guides/operations/troubleshooting, "Local DA Guide" /guides/da-layers/local-da,
"Troubleshooting" /guides/operations/troubleshooting, and "Configuration
Reference" /reference/configuration/ev-node-config); change each absolute path
to a relative path consistent with docs guidelines (for example replace
/guides/operations/troubleshooting with ../operations/troubleshooting or the
appropriate relative path from docs/guides/da-layers/celestia.md) so all
internal references are relative links.
| 1. Check logs for specific error messages | ||
| 2. Search [GitHub Issues](https://github.com/evstack/ev-node/issues) | ||
| 3. Join the community Discord for support | ||
|
|
There was a problem hiding this comment.
Discord reference is missing a URL.
The entry is non-actionable without a link. Either add the URL or remove the bullet until the link is available.
✏️ Proposed fix
-3. Join the community Discord for support
+3. Join the [community Discord](https://discord.gg/<invite>) for support🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/operations/troubleshooting.md` at line 293, Update the "Discord"
bullet in the Troubleshooting section by either adding the missing URL (replace
the standalone "Discord" bullet with "Discord — <insert URL>" or markdown link
format [Discord](https://...) ) or remove the bullet entirely until a valid link
is available; look for the bullet labeled "Discord" in the
docs/guides/operations/troubleshooting.md content and make the change so the
entry is actionable.
|
|
||
| ## Introduction | ||
|
|
||
| This guide covers how to set up a full node to run alongside a sequencer node in a Evolve-based blockchain network. A full node maintains a complete copy of the blockchain and helps validate transactions, improving the network's decentralization and security. |
There was a problem hiding this comment.
Minor grammar fixes.
- Use “an Evolve-based”
- Use “let’s call it”
✅ Suggested fix
-This guide covers how to set up a full node to run alongside a sequencer node in a Evolve-based blockchain network.
+This guide covers how to set up a full node to run alongside a sequencer node in an Evolve-based blockchain network.
...
-Initialize the chain config for the full node, lets call it `FullNode` and set the chain ID to your chain ID:
+Initialize the chain config for the full node, let's call it `FullNode`, and set the chain ID to your chain ID:Also applies to: 28-28
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/running-nodes/full-node.md` at line 5, Fix two minor grammar
issues: replace the phrase "a Evolve-based blockchain network" with "an
Evolve-based blockchain network" (update the article before "Evolve-based"), and
change any instances of "lets call it" to the contraction "let's call it" (add
the apostrophe). Search for the exact strings "a Evolve-based blockchain
network" and "lets call it" in the content and update them accordingly.
| Evolve is [open-source](https://github.com/evstack/ev-node), production-ready, and fully composable. | ||
|
|
||
| At its core is \`ev-node\`, a modular node that exposes an [Execution interface](https://github.com/evstack/ev-node/blob/main/core/execution/execution.go), — letting you bring any VM or execution logic, including Cosmos SDK or custom-built runtimes. | ||
|
|
There was a problem hiding this comment.
Validate new links with make testlink.
New external and internal links were added here; please run make testlink to ensure they all resolve in the VitePress site.
Also applies to: 79-85
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/overview/what-is-evolve.md` around lines 15 - 18, Run the VitePress link
validator and fix any broken links: run make testlink and address any failures
for the newly added links in this file (the external GitHub URL
https://github.com/evstack/ev-node and the internal Execution interface link
https://github.com/evstack/ev-node/blob/main/core/execution/execution.go and the
mention of ev-node); update the URLs or markdown link targets in
what-is-evolve.md (and the same changes around lines referenced 79-85) so that
make testlink passes without errors.
| As of today, Evolve provides a single sequencer, an execution interface (Engine API or ABCI), and a connection to Celestia. | ||
|
|
||
| We're currently working on implementing many new and exciting features such as light nodes and state fraud proofs. | ||
|
|
There was a problem hiding this comment.
Replace time-relative phrasing with a concrete date or version.
“As of today” / “We’re currently working…” will go stale quickly. Use a specific date (e.g., “As of 2026‑02‑24”) or a release/version to keep the doc unambiguous and durable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/overview/what-is-evolve.md` around lines 89 - 92, Replace the
time-relative phrases in the two sentences: change "As of today, Evolve
provides..." to a concrete snapshot like "As of 2026-02-24, Evolve provides..."
(or to a specific release/version), and reword "We're currently working on
implementing many new and exciting features such as light nodes and state fraud
proofs." to a date-scoped or version-scoped statement such as "Planned features
(as of 2026-02-24) include light nodes and state fraud proofs." so the document
remains unambiguous and does not become stale; update the two quoted sentence
strings accordingly.
| ## See Also | ||
|
|
||
| - [Data Availability Concepts](/concepts/data-availability) | ||
| - [Celestia Guide](/guides/da-layers/celestia) | ||
| - [Local DA Guide](/guides/da-layers/local-da) |
There was a problem hiding this comment.
Use relative links for internal docs.
Absolute internal links should be relative in docs/**/*.md.
✅ Suggested fix
-- [Data Availability Concepts](/concepts/data-availability)
-- [Celestia Guide](/guides/da-layers/celestia)
-- [Local DA Guide](/guides/da-layers/local-da)
+- [Data Availability Concepts](../../concepts/data-availability.md)
+- [Celestia Guide](../../guides/da-layers/celestia.md)
+- [Local DA Guide](../../guides/da-layers/local-da.md)As per coding guidelines: "docs/**/*.md: Use relative links for internal documentation references in markdown files".
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## See Also | |
| - [Data Availability Concepts](/concepts/data-availability) | |
| - [Celestia Guide](/guides/da-layers/celestia) | |
| - [Local DA Guide](/guides/da-layers/local-da) | |
| ## See Also | |
| - [Data Availability Concepts](../../concepts/data-availability.md) | |
| - [Celestia Guide](../../guides/da-layers/celestia.md) | |
| - [Local DA Guide](../../guides/da-layers/local-da.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/reference/interfaces/da.md` around lines 191 - 195, Update the "See
Also" section: replace the three absolute internal links
"/concepts/data-availability", "/guides/da-layers/celestia", and
"/guides/da-layers/local-da" with relative Markdown links (e.g.,
../concepts/data-availability or appropriate relative paths) so internal
references in the "See Also" section resolve correctly; modify the links in the
docs reference for the Data Availability interface (the "See Also" heading and
the three listed link items) to use relative paths.
| @@ -0,0 +1,136 @@ | |||
| # RPC Compatibility | |||
3 participants
Overview
This pr restructures the docs and writes new sections in order to be better suited for users
Summary by CodeRabbit
Documentation
Chores