Skip to content

docs: rewrite README#98

Merged
wcatz merged 3 commits intomasterfrom
chore/readme-rewrite
Mar 9, 2026
Merged

docs: rewrite README#98
wcatz merged 3 commits intomasterfrom
chore/readme-rewrite

Conversation

@wcatz
Copy link
Copy Markdown
Owner

@wcatz wcatz commented Mar 9, 2026

Summary

  • Lead with quickstart, then technical how-it-works
  • Remove marketing language and performance claims
  • Correct TICKN description: epochNonce(E) = BLAKE2b-256(η_c(E-1) || η_ph(E-2)) with one-epoch lag on labNonce
  • Remove adder from dependency list (pending replacement)
  • Drop "replaces external tools" framing

Test plan

  • No code changes

Summary by CodeRabbit

  • Documentation
    • Reorganized README into a concise Quick Start / Run-focused workflow, removing lengthy historical and per-mode descriptions.
    • Consolidated setup, prerequisites, environment and configuration guidance with updated examples and socket/variable notes.
    • Streamlined feature and command narratives into unified runtime capabilities (notifications, leader scheduling, nonces, stake queries, leaderlog).
    • Updated network/build/Helm references and applied formatting and terminology consistency across docs.

Remove marketing language and performance claims. Lead with
quickstart, then technical details on CPraos, TICKN nonce
evolution, sync pipeline, and architecture. Remove adder
references from dependency list (pending replacement).
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 9, 2026

Warning

Rate limit exceeded

@wcatz has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 11 minutes and 51 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0a197911-2847-4fcf-9de6-cb74e2cea076

📥 Commits

Reviewing files that changed from the base of the PR and between bbd4861 and 3e15b9b.

📒 Files selected for processing (1)
  • README.md
📝 Walkthrough

Walkthrough

README.md was rewritten: content condensed into a Run/Quick Start-focused flow, prerequisites and configuration consolidated, feature descriptions rephrased (CPraos leader schedule, epoch nonce evolution), and commands/architecture sections streamlined.

Changes

Cohort / File(s) Summary
Documentation Rewrite
README.md
Complete rewrite of documentation: consolidated Quick Start/Run flow, moved and simplified prerequisites and configuration, replaced granular feature blocks with a unified runtime narrative (notifications, CPraos leader scheduling, epoch nonce evolution, stake queries, leaderlog), updated commands and build/run guidance, and applied formatting/terminology harmonization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 I hopped through words and lines,
Readme trimmed to lean designs,
Quick Start beats the old routine,
Clearer paths where devs convene,
A joyful nibble—docs are clean! 🎉

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: rewrite README' directly and accurately describes the main change in the pull request, which is a comprehensive restructuring of the README documentation.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch chore/readme-rewrite

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (4)
README.md (4)

15-15: Consider clarifying the privacy implications.

The instruction to add RawDataBot to get the chat ID is a common pattern, but users should be aware that bots may log messages while present. Consider adding a brief note like "remove it promptly" or "RawDataBot will see messages while in the group."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 15, Update the Telegram group/channel ID instruction to
warn about privacy: edit the line mentioning adding `@RawDataBot` to explicitly
state that bots can read messages while present and advise users to remove the
bot promptly after obtaining the chat ID (e.g., append "Note: RawDataBot can see
messages while in the group, so remove it promptly after retrieving the chat
ID"). Ensure the new wording replaces the original single-sentence instruction
so readers are clearly warned about message visibility.

104-110: Add language specifier to code block.

The code block is missing a language specifier, which affects rendering and accessibility.

📝 Proposed fix
-```
+```text
 1. vrfInput    = BLAKE2b-256(slot[8B BE] || epochNonce[32B])
 2. _, output   = vrf.Prove(vrfSkey[:32], vrfInput)
 3. leaderValue = BLAKE2b-256(0x4C || output)
 4. threshold   = 2^256 * (1 - (1-f)^σ)          // f=0.05, σ=poolStake/totalStake
 5. isLeader    = leaderValue < threshold

Based on static analysis hints (markdownlint MD040).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 104 - 110, The fenced code block containing the
VRF/leader-election pseudo-code lacks a language specifier; update the block
delimiting backticks to include a language (e.g., "text") so markdown renderers
and linters recognize it—locate the block with the lines referencing vrfInput,
vrf.Prove, leaderValue, threshold and isLeader and change the opening fence from
``` to ```text (or another appropriate language) to satisfy markdownlint MD040.

152-154: Add language specifier to code block.

The pipeline diagram would render better with a language specifier such as text.

📝 Proposed fix
-```
+```text
 sync.go (NtN ChainSync) → blockCh [10,000 buf] → batch writer → InsertBlockBatch (CopyFrom) → ProcessBatch (nonce)

Based on static analysis hints (markdownlint MD040).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 152 - 154, Add a language specifier to the fenced
code block containing the pipeline diagram so Markdown renders it as plain text;
update the block that currently contains "sync.go (NtN ChainSync) → blockCh
[10,000 buf] → batch writer → InsertBlockBatch (CopyFrom) → ProcessBatch
(nonce)" to use a language tag such as text (e.g., ```text) at the opening fence
to satisfy markdownlint MD040 and improve rendering.

129-131: Add language specifier to code block.

The code block is missing a language specifier. Consider using text or python for pseudocode.

📝 Proposed fix
-```
+```text
 epochNonce(E) = BLAKE2b-256(η_c(E-1) || η_ph(E-2))

Based on static analysis hints (markdownlint MD040).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 129 - 131, The code block containing the formula
"epochNonce(E) = BLAKE2b-256(η_c(E-1) || η_ph(E-2))" lacks a language specifier;
update the fenced code block from ``` to ```text (or another appropriate
specifier like ```python) so the block is tagged (e.g., change the opening fence
to ```text) to satisfy markdownlint MD040.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Line 15: Update the Telegram group/channel ID instruction to warn about
privacy: edit the line mentioning adding `@RawDataBot` to explicitly state that
bots can read messages while present and advise users to remove the bot promptly
after obtaining the chat ID (e.g., append "Note: RawDataBot can see messages
while in the group, so remove it promptly after retrieving the chat ID"). Ensure
the new wording replaces the original single-sentence instruction so readers are
clearly warned about message visibility.
- Around line 104-110: The fenced code block containing the VRF/leader-election
pseudo-code lacks a language specifier; update the block delimiting backticks to
include a language (e.g., "text") so markdown renderers and linters recognize
it—locate the block with the lines referencing vrfInput, vrf.Prove, leaderValue,
threshold and isLeader and change the opening fence from ``` to ```text (or
another appropriate language) to satisfy markdownlint MD040.
- Around line 152-154: Add a language specifier to the fenced code block
containing the pipeline diagram so Markdown renders it as plain text; update the
block that currently contains "sync.go (NtN ChainSync) → blockCh [10,000 buf] →
batch writer → InsertBlockBatch (CopyFrom) → ProcessBatch (nonce)" to use a
language tag such as text (e.g., ```text) at the opening fence to satisfy
markdownlint MD040 and improve rendering.
- Around line 129-131: The code block containing the formula "epochNonce(E) =
BLAKE2b-256(η_c(E-1) || η_ph(E-2))" lacks a language specifier; update the
fenced code block from ``` to ```text (or another appropriate specifier like
```python) so the block is tagged (e.g., change the opening fence to ```text) to
satisfy markdownlint MD040.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 75386e64-2e83-4fb6-a042-8192e9f61bd6

📥 Commits

Reviewing files that changed from the base of the PR and between 51e6f93 and 3181c6c.

📒 Files selected for processing (1)
  • README.md

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (3)
README.md (3)

131-133: Add language identifier to fenced code block.

The code block should specify a language for proper syntax highlighting and markdown compliance.

📝 Proposed fix
-```
+```text
 epochNonce(E) = BLAKE2b-256(η_c(E-1) || η_ph(E-2))
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @README.md around lines 131 - 133, The fenced code block containing the
formula for epochNonce should include a language identifier for proper syntax
highlighting and markdown compliance; update the block that shows "epochNonce(E)
= BLAKE2b-256(η_c(E-1) || η_ph(E-2))" to use a language tag such as "text" (or
another appropriate lexer) after the opening backticks so the formula is
rendered correctly.


</details>

---

`106-112`: **Add language identifier to fenced code block.**

The CPraos leader election pseudocode should specify a language for proper syntax highlighting.


<details>
<summary>📝 Proposed fix</summary>

```diff
-```
+```text
 1. vrfInput    = BLAKE2b-256(slot[8B BE] || epochNonce[32B])
 2. _, output   = vrf.Prove(vrfSkey[:32], vrfInput)
 3. leaderValue = BLAKE2b-256(0x4C || output)
 4. threshold   = 2^256 * (1 - (1-f)^σ)          // f=0.05, σ=poolStake/totalStake
 5. isLeader    = leaderValue < threshold
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @README.md around lines 106 - 112, Add a language identifier to the fenced
code block that contains the CPraos pseudocode (the block with vrfInput,
vrf.Prove, leaderValue, threshold, isLeader) so it gets proper syntax
highlighting; update the opening triple-backtick to include an appropriate
identifier such as "text" or "pseudo" (e.g., ```text) and keep the pseudocode
content unchanged.


</details>

---

`154-156`: **Add language identifier to fenced code block.**

The pipeline diagram code block should specify a language for proper syntax highlighting.


<details>
<summary>📝 Proposed fix</summary>

```diff
-```
+```text
 sync.go (NtN ChainSync) → blockCh [10,000 buf] → batch writer → InsertBlockBatch (CopyFrom) → ProcessBatch (nonce)
 ```
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @README.md around lines 154 - 156, The fenced code block containing the
pipeline diagram (showing "sync.go (NtN ChainSync) → blockCh [10,000 buf] →
batch writer → InsertBlockBatch (CopyFrom) → ProcessBatch (nonce)") lacks a
language identifier, so update that triple-backtick fence to include a language
(e.g., "text") to enable proper syntax highlighting; locate the block in
README.md and change totext without altering the diagram content.


</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @README.md:

  • Around line 131-133: The fenced code block containing the formula for
    epochNonce should include a language identifier for proper syntax highlighting
    and markdown compliance; update the block that shows "epochNonce(E) =
    BLAKE2b-256(η_c(E-1) || η_ph(E-2))" to use a language tag such as "text" (or
    another appropriate lexer) after the opening backticks so the formula is
    rendered correctly.
  • Around line 106-112: Add a language identifier to the fenced code block that
    contains the CPraos pseudocode (the block with vrfInput, vrf.Prove, leaderValue,
    threshold, isLeader) so it gets proper syntax highlighting; update the opening
    triple-backtick to include an appropriate identifier such as "text" or "pseudo"
    (e.g., ```text) and keep the pseudocode content unchanged.
  • Around line 154-156: The fenced code block containing the pipeline diagram
    (showing "sync.go (NtN ChainSync) → blockCh [10,000 buf] → batch writer →
    InsertBlockBatch (CopyFrom) → ProcessBatch (nonce)") lacks a language
    identifier, so update that triple-backtick fence to include a language (e.g.,
    "text") to enable proper syntax highlighting; locate the block in README.md and
    change totext without altering the diagram content.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `741ab6b7-92ba-4362-b7ab-91f550316898`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 3181c6ce25d10a2ae40523aec24e97a0a1bab965 and bbd486152e0b8a2a5bb10709343b9c40eed606f9.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `README.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

@wcatz wcatz merged commit f05d4da into master Mar 9, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant