Conversation
|
The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).
|
|
Claude finished @tac0turtle's task in 5m 2s —— View job Documentation PR ReviewTasks:
This is a substantial documentation effort — 63 new files covering concepts, guides, and reference specs. The structure is well thought out and the writing is generally clear. Below is a detailed review of issues found, grouped by severity. Critical Issues1. Wrong CLI flags in The recovery command uses incorrect flag prefixes: # Current (WRONG):
./evnode start --node.aggregator --node.based_sequencer
# Correct (from pkg/config/config.go):
./evnode start --evnode.node.aggregator --evnode.node.based_sequencerConfirmed against Significant Issues2. Near-complete duplication: Both files are ~744–759 lines and cover essentially the same material (Executor, Reaper, Submitter, Syncer, Cache Manager, retry strategy, metrics). The only difference is that 3. Backoff cap inconsistency in
These use different terms. The spec ( 4. Placeholder files included in the PR Several files have only stub content with no actionable information for users. These should either be completed or removed before merging a "docs rewrite":
5. Duplicate content between As noted by @pthmas: Minor / Style Issues6. Broken internal link in The file links to 7. Broken reference in Line 15 links to 8. Broken reference in Links to 9. The node types table lists "Attester" as a current option, but 10. Double space typo in "Every node" has two spaces. Fix this → 11. Gas price description in The automatic gas price detection paragraph could mislead readers into thinking they must configure it manually. The Celestia guide correctly notes "By default, ev-node uses automatic gas price detection" — the block-lifecycle conceptual doc should align. Positive Observations
SummaryThe two highest-priority items before merge are: (1) fix the wrong CLI flags in |
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.90% -0.08%
==========================================
Files 113 113
Lines 11617 11617
==========================================
- Hits 7084 7075 -9
- Misses 3734 3743 +9
Partials 799 799
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?
| - **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?
📝 WalkthroughWalkthroughComprehensive documentation expansion covering Evolve's architecture, core concepts, configuration, deployment, and API reference. Adds guides for EV-ABCI migration, EV-RETH setup, quickstarts for EVM and Cosmos chains, operational procedures, and detailed specification references. Includes minor makefile adjustment for markdown linting. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 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.
| ### Recovery from Malicious Sequencer | ||
|
|
||
| When a malicious sequencer is detected (censoring forced inclusion transactions): | ||
|
|
||
| **All nodes must restart the chain in based sequencing mode:** | ||
|
|
||
| ```bash | ||
| # Restart with based sequencing enabled | ||
| ./evnode start --node.aggregator --node.based_sequencer | ||
| ``` | ||
|
|
||
| **In based sequencing mode:** | ||
|
|
||
| - No single sequencer controls transaction ordering | ||
| - Every full node derives blocks independently from the DA layer | ||
| - Forced inclusion becomes the primary (and only) transaction submission method | ||
| - Censorship becomes impossible as ordering comes from the DA layer | ||
|
|
||
| **Important considerations:** | ||
|
|
||
| - All full nodes should coordinate the switch to based mode | ||
| - The chain continues from the last valid state | ||
| - Users submit transactions directly to the DA layer going forward | ||
| - This is a one-way transition - moving back to single sequencer requires social consensus | ||
|
|
||
| See [Based Sequencing documentation](./based.md) for details on operating in this mode. |
There was a problem hiding this comment.
Clarify the “must restart in based sequencing mode” requirement.
This reads as a hard requirement, but recovery from censorship likely depends on governance/coordination and may allow alternative mitigations. Please soften this language (e.g., “may require coordinated restart”) and describe prerequisites or conditions.
🤖 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 90 - 115, Update the
"Recovery from Malicious Sequencer" section to soften the hard requirement:
change wording from "All nodes must restart the chain in based sequencing mode"
to language like "Nodes may require a coordinated restart into based sequencing
mode" and add brief prerequisites/conditions such as the need for governance or
operator coordination, a consensus decision or emergency governance action,
verification of the last valid state before restart, and an
announcement/rollback plan; keep the example CLI (./evnode start
--node.aggregator --node.based_sequencer) but label it as one possible
coordinated action rather than the only remedy, and link to the Based Sequencing
docs for operational steps and governance considerations.
| ```bash | ||
| # Install celestia-node | ||
| curl -sL https://docs.celestia.org/install.sh | bash | ||
|
|
||
| # Initialize (choose your network) | ||
| celestia light init --p2p.network mocha | ||
|
|
||
| # Start the node | ||
| celestia light start --p2p.network mocha | ||
| ``` |
There was a problem hiding this comment.
Add a safety warning for curl | bash install.
The quick-start pipes a remote script directly into shell, which is a common supply-chain risk. Please add a short warning and recommend verifying the script/checksums before executing.
🤖 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 20 - 29, Add a safety warning
before the "curl -sL https://docs.celestia.org/install.sh | bash" install step
explaining the supply-chain risk of piping remote scripts to shell, instruct
users to review the script and verify checksums/signatures (or fetch and inspect
the script manually) before running, and provide a short alternative command
sequence (download, verify, then execute) as a safer option so readers know how
to validate the installer instead of running it directly.
| 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.
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