feat: catchain overview

[Shvandre]

Closes #986

Summary by CodeRabbit

• Documentation
  • Added "Catchain overview" page detailing the Catchain message-dependency protocol, causality preservation, Byzantine handling, and node state/synchronization.
  • Updated "Catchain 1.0 and BCP visualizer" with clarified title/description and expanded, clearer simulation notes.
  • Updated site navigation to include the new Catchain overview page.
• Chores
  • Added spell-check entries (CRDT, irreflexive/irreflexivity, Mersenne).

[github-actions]

No documentation issues detected.

[fakela]

@fakela nice animation! Is it possible to make the resolution higher? Gif looks a little blurry

Yes, definitely I can do that 👌

[fakela]

@fakela nice animation! Is it possible to make the resolution higher? Gif looks a little blurry

I have updated the gifs and added dark mode as well

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e9aa6ca-980a-455f-97f9-96ebc2aab31a

📥 Commits

Reviewing files that changed from the base of the PR and between dc31058 and 599543f.

📒 Files selected for processing (1)

• foundations/consensus/catchain-overview.mdx

✅ Files skipped from review due to trivial changes (1)

• foundations/consensus/catchain-overview.mdx

---

📝 Walkthrough

Walkthrough

Adds a new Catchain overview documentation page, inserts it into the Consensus navigation before the visualizer, refines the Catchain visualizer metadata and simulation notes, and extends the custom dictionary with protocol-specific terms.

Changes

Catchain Documentation Updates

Layer / File(s)	Summary
Catchain Overview page and navigation docs.json, foundations/consensus/catchain-overview.mdx	New 105-line documentation page introducing Catchain as a message-dependency protocol supporting consensus via causality-preserving dependencies. Covers problem statement, protocol capabilities (CRDT-based eventual consistency, Byzantine tolerance), neighbor selection, message identification and dependencies, Byzantine-node handling with fork detection, node state vectors, dependency retrieval and synchronization, and ADNL-based encryption. Navigation entry added to display the overview before the visualizer.
Catchain Visualizer clarification and expansion foundations/consensus/catchain-visualizer.mdx	Page title and description updated from "Catchain & BCP visualizer" to "Catchain 1.0 and BCP visualizer." Introductory text refined; simulation notes expanded into explicit bullets clarifying timing approximation, dependency handling without vector-time sync, equal-weight quorums, priority-window scheduling differences, null candidate assumption, and simplified VoteFor/slow-mode behavior.
Spell-check dictionary updates resources/dictionaries/custom.txt	Dictionary extended with three new entries: CRDT (line 182), irreflexive/irreflexivity (lines 357–358), and Mersenne (line 440), supporting spell-check validation of protocol terminology in the documentation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

3p

Poem

🐰 In docs I nibble lines so neat and spry,
A catchain tale beneath the page's sky,
Visuals polished, glossary grown wide,
Messages, dependencies—side by side,
Knowledge hops forward, with a joyful sigh.

🚥 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 and concisely reflects the main change: adding a new catchain overview documentation page.
Linked Issues check	✅ Passed	The PR fulfills issue #986's requirement to describe what a catchain is and what it is useful for through the new comprehensive documentation page.
Out of Scope Changes check	✅ Passed	All changes are scoped to the catchain overview documentation: new overview page, supporting dictionary updates, visualization page metadata updates, and documentation configuration—all directly related to issue #986.
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
• Commit unit tests in branch catchain-overview

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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 and usage tips.}

[github-actions]

Thanks for the improvements to the catchain docs; I have several suggestions in foundations/consensus/catchain-overview.mdx and foundations/consensus/catchain-visualizer.mdx, so please apply the inline suggestions.

[novusnota]

@Shvandre take a look, please

Outdated

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@foundations/consensus/catchain-overview.mdx`:
- Line 48: Update the sentence that currently states the `seqno` is incremented
"after each round" to say it is incremented "after each sent message" so it
matches the earlier definition that `seqno` counts messages sent by a node;
update the text in the Catchain overview where `seqno` is described and ensure
any adjacent reference (e.g., the "Handling Byzantine nodes" link) remains
correct and consistent with the per-message increment semantics.
- Around line 82-83: The sentence describing fork handling contains a duplicated
trailing word ("messages") which makes it hard to parse; update the sentence
that currently reads "...as well as all messages that depend on `(A, j) where j
>= i` messages." by removing the extra "messages" so it ends "...as well as all
messages that depend on `(A, j) where j >= i`." and ensure spacing and
punctuation around `(A, j)` remain correct; refer to the fork example using the
identifier `(A; i)` to locate the sentence.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 79ec8649-7a0c-4c7e-a38b-aaca5cad30ff

📥 Commits

Reviewing files that changed from the base of the PR and between 8edf7c3 and dc31058.

⛔ Files ignored due to path filters (2)

• resources/images/foundations/catchain-dark.gif is excluded by !**/*.gif
• resources/images/foundations/catchain-light.gif is excluded by !**/*.gif

📒 Files selected for processing (4)

• docs.json
• foundations/consensus/catchain-overview.mdx
• foundations/consensus/catchain-visualizer.mdx
• resources/dictionaries/custom.txt

[novusnota]

I'll tentatively approve and merge this. Everyone, thanks for the work done on this pull request! ❤️

If any issues are spotted later, let's resolve them in another PR.