Merging protocol docs

[mod]

Summary by CodeRabbit

• Documentation

  • Added comprehensive contract API reference and deployment guides.
  • Added protocol architecture documentation for Decentralized and App Layers.
  • Added SDK documentation with getting-started guides, examples, and API references.
  • Added integration guides for dApp UI specifications and event handling.
  • Updated protocol terminology and branding throughout documentation.

• Chores

  • Added documentation synchronization script and updated build configuration.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 605e3f32-21f9-4413-80bd-b4fffdc85c77

📥 Commits

Reviewing files that changed from the base of the PR and between 0bbcf3c and 86f0c0e.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (85)

• .gitmodules
• docs/api-reference/index.md
• docs/build/quick-start/index.md
• docs/contracts/addresses.md
• docs/contracts/api-reference/_category_.json
• docs/contracts/api-reference/app-registry.md
• docs/contracts/api-reference/faucet.md
• docs/contracts/api-reference/interfaces/_category_.json
• docs/contracts/api-reference/interfaces/ilock.md
• docs/contracts/api-reference/interfaces/islash.md
• docs/contracts/api-reference/locker.md
• docs/contracts/api-reference/node-registry.md
• docs/contracts/api-reference/treasury.md
• docs/contracts/api-reference/yellow-governor.md
• docs/contracts/api-reference/yellow-token.md
• docs/contracts/faq.md
• docs/contracts/index.md
• docs/contracts/integration/_category_.json
• docs/contracts/integration/deployment.md
• docs/contracts/integration/events.md
• docs/contracts/integration/ui-spec.md
• docs/contracts/protocol/_category_.json
• docs/contracts/protocol/governance.md
• docs/contracts/protocol/overview.md
• docs/contracts/protocol/slashing.md
• docs/contracts/protocol/staking.md
• docs/contracts/protocol/treasury.md
• docs/contracts/sdk/_category_.json
• docs/contracts/sdk/api-reference.md
• docs/contracts/sdk/examples.md
• docs/contracts/sdk/getting-started.md
• docs/guides/index.md
• docs/guides/migration-guide.md
• docs/guides/multi-party-app-sessions.mdx
• docs/learn/advanced/managing-session-keys.mdx
• docs/learn/core-concepts/app-sessions.mdx
• docs/learn/core-concepts/challenge-response.mdx
• docs/learn/core-concepts/message-envelope.mdx
• docs/learn/core-concepts/session-keys.mdx
• docs/learn/core-concepts/state-channels-vs-l1-l2.mdx
• docs/learn/getting-started/key-terms.mdx
• docs/learn/getting-started/prerequisites.mdx
• docs/learn/getting-started/quickstart.mdx
• docs/learn/index.mdx
• docs/learn/introduction/architecture-at-a-glance.mdx
• docs/learn/introduction/what-yellow-solves.mdx
• docs/manuals/request-asset-support.md
• docs/manuals/request-blockchain-support.md
• docs/manuals/running-clearnode-locally.md
• docs/protocol/app-layer/_category_.json
• docs/protocol/app-layer/off-chain/_category_.json
• docs/protocol/app-layer/off-chain/app-sessions.mdx
• docs/protocol/app-layer/off-chain/authentication.mdx
• docs/protocol/app-layer/off-chain/channel-methods.mdx
• docs/protocol/app-layer/off-chain/message-format.mdx
• docs/protocol/app-layer/off-chain/overview.mdx
• docs/protocol/app-layer/off-chain/queries.mdx
• docs/protocol/app-layer/off-chain/transfers.mdx
• docs/protocol/app-layer/on-chain/_category_.json
• docs/protocol/app-layer/on-chain/channel-lifecycle.mdx
• docs/protocol/app-layer/on-chain/data-structures.mdx
• docs/protocol/app-layer/on-chain/overview.mdx
• docs/protocol/app-layer/on-chain/security.mdx
• docs/protocol/app-layer/on-chain/signature-formats.mdx
• docs/protocol/architecture.mdx
• docs/protocol/communication-flows.mdx
• docs/protocol/decentralized-layer/_category_.json
• docs/protocol/decentralized-layer/cluster-lifecycle.mdx
• docs/protocol/decentralized-layer/elastic-security.mdx
• docs/protocol/decentralized-layer/liquidity-layer.mdx
• docs/protocol/decentralized-layer/overview.mdx
• docs/protocol/decentralized-layer/protocol-lifecycle.mdx
• docs/protocol/decentralized-layer/security.mdx
• docs/protocol/glossary.mdx
• docs/protocol/implementation-checklist.mdx
• docs/protocol/introduction.mdx
• docs/protocol/protocol-reference.mdx
• docs/protocol/terminology.mdx
• docusaurus.config.ts
• package.json
• scripts/sync-contracts-docs.js
• sidebars.ts
• src/constants/tooltipDefinitions.ts
• src/pages/whitepaper.md
• vendors/yellow

---

📝 Walkthrough

Walkthrough

This PR introduces a major documentation restructuring and rebranding effort. It adds the vendors/yellow submodule, systematically renames Nitrolite to VirtualApp throughout documentation, reorganizes protocol documentation into Decentralized Layer and App Layer structures, and adds comprehensive Yellow Network smart contract documentation including API references, guides, integration examples, and deployment instructions. The changes also update internal navigation paths, add a contract documentation synchronization script, and update configuration files.

Changes

Cohort / File(s)	Summary
Submodule & Configuration .gitmodules, package.json, docusaurus.config.ts, sidebars.ts	Added vendors/yellow submodule, new sync script, pinned Docusaurus theme dependencies, added Contracts navbar entry and sidebar generation.
Nitrolite → VirtualApp Rebranding docs/api-reference/*, docs/build/*, docs/guides/*, docs/learn/*, docs/manuals/*, docs/protocol/app-layer/*, src/constants/tooltipDefinitions.ts, src/pages/whitepaper.md	Systematic renaming of Nitrolite protocol references to VirtualApp protocol; updated related tooltips, descriptions, and links across 40+ documentation files.
Protocol Architecture Reorganization docs/protocol/architecture.mdx, docs/protocol/introduction.mdx, docs/protocol/terminology.mdx, docs/protocol/glossary.mdx, docs/protocol/implementation-checklist.mdx, docs/protocol/protocol-reference.mdx, docs/protocol/communication-flows.mdx	Restructured protocol documentation from single-layer Nitrolite model to multi-layer Yellow Protocol (Decentralized Layer + App Layer); updated architecture diagrams, design goals, and cross-references.
Decentralized Layer Documentation docs/protocol/decentralized-layer/_category_.json, docs/protocol/decentralized-layer/overview.mdx, docs/protocol/decentralized-layer/cluster-lifecycle.mdx, docs/protocol/decentralized-layer/elastic-security.mdx, docs/protocol/decentralized-layer/liquidity-layer.mdx, docs/protocol/decentralized-layer/protocol-lifecycle.mdx, docs/protocol/decentralized-layer/security.mdx	Added comprehensive documentation for DL components including cluster topology, BLS signatures, elastic security model, liquidity layer, asset flows, and threat model analysis.
Smart Contract Documentation docs/contracts/index.md, docs/contracts/addresses.md, docs/contracts/faq.md, docs/contracts/api-reference/*, docs/contracts/protocol/*, docs/contracts/integration/*, docs/contracts/sdk/*	Added extensive contract documentation covering API references (YellowToken, NodeRegistry, AppRegistry, Treasury, YellowGovernor, Faucet, Locker), protocol mechanics (staking, slashing, governance, treasury), integration guides (deployment, events, UI specs), and SDK usage (getting started, examples, API reference).
Documentation Sync Script scripts/sync-contracts-docs.js	Added build-time script to synchronize and transform contract documentation from vendors/yellow into docs/contracts with Docusaurus-compatible frontmatter and category metadata; includes vendor path validation and directory rebuilding.
App Layer Path Restructuring docs/protocol/app-layer/_category_.json, docs/protocol/app-layer/off-chain/*, docs/protocol/app-layer/on-chain/*	Reorganized app-layer documentation structure; updated internal cross-references across protocol docs to use new app-layer paths (e.g., /docs/protocol/app-layer/on-chain/... instead of /docs/protocol/on-chain/...).
Updated Internal Links docs/learn/core-concepts/*	Updated documentation hyperlinks to point to new app-layer paths for architecture, channel lifecycle, security, authentication, and off-chain features.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Updating docs #116: Updates to tooltipDefinitions.ts keys (clearnode, custodyContract, and protocol-related tooltips) affecting the same constant definitions modified in this PR.

Suggested reviewers

• dpatsora

Poem

🐰 Hops through docs with floppy ears,
VirtualApp now replaces Nitrolite's years,
Layers dance—decentralized and app,
Contracts documented, no knowledge gap!
Submodules synced with script so swift,
This docsite's gotten quite the lift! 🌟

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/wpx

---

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

[alessio]

@mod The current state of the documentation is inconsistent, as it seems like that the new section Contracts brings about another Introduction. The team would like to these changes before merging them. Thanks!