docs(leios-testnet): add tutorial-style README

[scarmuega]

What

Adds a tutorial-style README.md for the leios-testnet example, which had no docs.

The README walks a reader from zero to running:

• What is Leios? — the EB overlay on top of Praos, with a notify→fetch flow diagram and a leios-notify (push) vs leios-fetch (pull) comparison.
• Running it — RUST_LOG=info cargo run -p leios-testnet.
• Reading the output — an annotated sample log transcript mapped to the events the example handles.
• How it works — a code walkthrough keyed to src/main.rs: the handshake version swap that "turns Leios on", the tokio::select! event loop, Praos chain-sync underneath, the handle_notification notify→fetch logic, and the {tx_hash => size} body decoding that sizes the tx bitmap.
• Configuration / Troubleshooting / Going further — the tunable constants, common failure modes (the devnet resets often), and links to CIP-0164 and the Leios testnet docs.

Also refreshes the chain intersection point in src/main.rs to a current point (the Musashi Dojo testnet resets periodically, so the old point had aged out).

Scope

This PR is scoped to examples/leios-testnet/ only. The separate leios-tui example (and its Cargo.toml workspace entry) is intentionally left out.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added a comprehensive guide for the leios-testnet example, including setup steps, run commands, expected output, verification checkpoints, troubleshooting tips, and extension notes.

• Bug Fixes

  • Updated the example’s starting sync position so it follows the testnet from a more current point, improving how the demo connects and runs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a 225-line README to the leios-testnet example covering the Leios overlay protocol, mini-protocols, run instructions, internal event-loop flow, configuration constants, troubleshooting, and extension guidance. Updates the hardcoded INTERSECT_SLOT and INTERSECT_HASH values in src/main.rs to a new testnet tip.

Changes

Leios Testnet Documentation and Config

Layer / File(s)	Summary
README and intersection update examples/leios-testnet/README.md, examples/leios-testnet/src/main.rs	New README documents the protocol overview, notify/fetch mini-protocols, run instructions with expected log output, internal event-loop and handle_notification flow, CBOR EB body decoding, configuration constants, troubleshooting, and extension pointers. INTERSECT_SLOT and INTERSECT_HASH are replaced with new values.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 Hippity-hop, a README appears,
Explaining Leios to calm all our fears!
Notify, fetch, and a handshake so neat,
New intersection point — the chain stays complete.
Docs and a constant, all tidy and bright,
This rabbit hops onward into the night! 🌙

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a tutorial-style README for leios-testnet.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/leios-testnet-readme

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

examples/leios-testnet/README.md (2)

37-45: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add language specifier to fenced code block for lint compliance.

The ASCII diagram block starting at Line 37 lacks a language tag, triggering markdownlint-cli2 MD040. Add text to silence the warning and keep the document consistent.

-```
+```text
 relay ──leios-notify──▶  BlockOffer(eb)        "I have EB e"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/leios-testnet/README.md` around lines 37 - 45, The fenced ASCII
diagram in README is missing a language specifier, which triggers markdown lint
MD040. Update the fenced block around the leios testnet protocol diagram to use
a text language tag so the Markdown stays lint-compliant and consistent with
other code fences.

Source: Linters/SAST tools

---

81-91: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add language specifier to log output block.

The log sample block starting at Line 81 lacks a language tag, triggering markdownlint-cli2 MD040. Add text to silence the warning.

-```
+```text
 INFO connecting to Leios testnet relay="leios-node.play.dev.cardano.org:3001" magic=164

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/leios-testnet/README.md` around lines 81 - 91, The log sample block
in the README is missing a fenced code language tag and should be marked as
plain text to satisfy markdownlint MD040. Update the fenced block containing the
Leios testnet log sample so it uses a text specifier, keeping the existing
sample content unchanged; this applies to the code block near the README’s log
example and should be easy to locate by the INFO log lines.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@examples/leios-testnet/README.md`:
- Around line 37-45: The fenced ASCII diagram in README is missing a language
specifier, which triggers markdown lint MD040. Update the fenced block around
the leios testnet protocol diagram to use a text language tag so the Markdown
stays lint-compliant and consistent with other code fences.
- Around line 81-91: The log sample block in the README is missing a fenced code
language tag and should be marked as plain text to satisfy markdownlint MD040.
Update the fenced block containing the Leios testnet log sample so it uses a
text specifier, keeping the existing sample content unchanged; this applies to
the code block near the README’s log example and should be easy to locate by the
INFO log lines.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6dcf8852-f7cf-436a-95c4-256e8077b856

📥 Commits

Reviewing files that changed from the base of the PR and between 1038c66 and b682d9d.

📒 Files selected for processing (2)

• examples/leios-testnet/README.md
• examples/leios-testnet/src/main.rs