Skip to content

YNU-864: Learn introduction rewrite (v1 mental model) #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ihsraham wants to merge 1 commit into
base: docs/reorg-for-v1
Choose a base branch
from
Open

YNU-864: Learn introduction rewrite (v1 mental model) #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 16 additions & 25 deletions docs/nitrolite/learn/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,52 +12,43 @@ import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions';

Welcome to the Yellow Network learning path. This section builds your understanding from fundamentals to advanced concepts.

Yellow Network is a decentralized clearing and settlement infrastructure that operates as a Layer 3 overlay on top of existing blockchains. It enables businesses — brokers, exchanges, and application developers — to move digital assets across multiple blockchain networks through a unified peer-to-peer ledger, without relying on a centralized intermediary. The network is formed by independent node operators who run open-source clearnode software supplied by Layer3 Fintech Ltd. on their own infrastructure. The YELLOW token provides access to network services including clearing, SDK and developer tools, node operation, the AppRegistry, and dispute resolution.
Yellow Network is decentralized clearing and settlement infrastructure that operates as a Layer 3 overlay on existing blockchains. It lets businesses, exchanges, and application developers move digital assets through signed channel states. Independent node operators run open-source Nitronode software supplied by Layer3 Fintech Ltd. The YELLOW token enables clearing/staking and dispute resolution; the SDK and developer tools are open-source and free.
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

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

I think it is best to not mention "YELLOW clearing / staking" for now.


---
:::info What changed in v1
The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and app sessions. If you are coming from `@erc7824/nitrolite@0.5.3`, PR7 will add the migration guide at `learn/migrating-from-0.5.3.mdx`.
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

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

What is the "PR7"?

:::

## Introduction

Start here to understand what Yellow Network solves and how it works.

**[What Yellow Solves](./introduction/what-yellow-solves.mdx)** — Understand the core problems: scaling, cost, and speed. Learn why <Tooltip content={tooltipDefinitions.channel}>state channels</Tooltip> are the answer for high-frequency applications.
**[What Yellow Solves](./introduction/what-yellow-solves.mdx)**: Understand the core problems: scaling, cost, and speed. Learn why <Tooltip content={tooltipDefinitions.channel}>state channels</Tooltip> are the answer for high-frequency applications.

**[Architecture at a Glance](./introduction/architecture-at-a-glance.mdx)** — See how the three protocol layers (on-chain, off-chain, application) work together to enable fast, secure transactions.

---
**[Architecture at a Glance](./introduction/architecture-at-a-glance.mdx)**: See how the protocol, off-chain, and blockchain layers work together to enable fast channel updates with enforceable settlement.

## Core Concepts

Deep dive into the technology powering Yellow Network.

**[State Channels vs L1/L2](./core-concepts/state-channels-vs-l1-l2.mdx)** — Compare state channels with Layer 1 and Layer 2 solutions. Understand when each approach is the right choice.
**[State Channels vs L1/L2](./core-concepts/state-channels-vs-l1-l2.mdx)**: Compare state channels with Layer 1 and Layer 2 solutions. Understand when each approach is the right choice.

**[Challenge-Response & Disputes](./core-concepts/challenge-response.mdx)** — How Yellow Network handles disputes and ensures your funds are always recoverable.
**[Challenge-Response & Disputes](./core-concepts/challenge-response.mdx)**: How Yellow Network handles disputes and ensures your funds are recoverable through the latest mutually signed state.

**[YELLOW Token](./core-concepts/yellow-token.mdx)** — The utility token powering network services, node operator collateral, and dispute resolution.

---
**[YELLOW Token](./core-concepts/yellow-token.mdx)**: The utility token powering network services, node operator collateral, and dispute resolution.

## Protocol Flows

Detailed v1 protocol flow documentation for deposits, withdrawals, transfers, and app sessions.

**[Protocol Architecture](./protocol-flows/architecture.mdx)** — The Petal Diagram: Home Chain, Cross-Chain, Transfers, and App Sessions.
**[Protocol Architecture](./protocol-flows/architecture.mdx)**: The Petal Diagram: home chain, cross-chain, transfers, and app sessions.

**[Transfer Flow](./protocol-flows/transfer-flow.mdx)** — Off-chain transfers between users via the Clearnode.
**[Transfer Flow](./protocol-flows/transfer-flow.mdx)**: Off-chain transfers between users via Nitronode.

**[Home Channel Flows](./protocol-flows/home-channel-creation.mdx)** — Channel creation, deposits, and withdrawals on the home chain.
**[Home Channel Flows](./protocol-flows/home-channel-creation.mdx)**: Channel creation, deposits, and withdrawals on the home chain.

**[App Session Deposit](./protocol-flows/app-session-deposit.mdx)** — Depositing funds into app sessions.

---
**[App Session Deposit](./protocol-flows/app-session-deposit.mdx)**: Depositing funds into app sessions.

## Next Steps

After completing the Learn section, continue to:

- **[Build](/nitrolite/build/quick-start)** — Implement complete Yellow Applications
- **[Protocol](/nitrolite/protocol/introduction)** — Authoritative protocol specification
- **[Build](/nitrolite/build/quick-start)**: Implement complete Yellow applications.
- **[Protocol](/nitrolite/protocol/introduction)**: Read the authoritative protocol specification.
- **MCP tools**: PR8 will add `build/sdk/mcp.mdx` for agent-assisted protocol and SDK lookup.
Copy link
Copy Markdown
Contributor

@nksazonov nksazonov May 14, 2026

Choose a reason for hiding this comment

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

"PR8 will add build/sdk/mcp.mdx" exposes an internal PR number to readers. If the page ships or the PR is re-numbered, this entry silently misleads.

Suggestion: Either remove this bullet until the page exists, or write it as "MCP tools documentation coming soon at build/sdk/mcp.mdx" without the PR reference.


---

Expand Down
Loading
Loading