diff --git a/docs/nitrolite/learn/index.mdx b/docs/nitrolite/learn/index.mdx index 0de7b5f..8778a2d 100644 --- a/docs/nitrolite/learn/index.mdx +++ b/docs/nitrolite/learn/index.mdx @@ -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. ---- +:::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`. +::: ## 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 state channels 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 state channels 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. --- diff --git a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx index 2fa0f0d..6521610 100644 --- a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx +++ b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx @@ -1,253 +1,148 @@ --- sidebar_position: 2 title: Architecture at a Glance -description: High-level overview of Yellow Network's three-layer architecture -keywords: [architecture, state channels, VirtualApp, Clearnode, smart contracts] +description: High-level overview of Yellow Network's v1 architecture +keywords: [architecture, state channels, Nitrolite, Nitronode, ChannelHub, smart contracts] --- -import Tooltip from '@site/src/components/Tooltip'; -import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions'; - -:::warning[Work in Progress] -This page was carried over from the v0.5.x documentation and has not yet been fully updated for v1.x. Some terminology, code examples, and API references may be outdated. An update is in progress. -::: - # Architecture at a Glance -In this guide, you will learn how Yellow Network's three protocol layers work together to enable fast, secure, off-chain transactions. +Yellow Network v1 combines application code, SDK clients, Nitronode coordination, and ChannelHub enforcement so most updates happen off-chain while the latest mutually signed state remains enforceable on-chain. --- -## The Three Layers - -Yellow Network consists of three interconnected layers, each with a specific responsibility: +## The Four Surfaces ```mermaid -graph TB - subgraph Application["Application Layer"] - direction TB - APP["Your Application
Games, Payments, DeFi"] - end - - subgraph OffChain["Off-Chain Layer"] - direction LR - CLIENT["Client SDK"] - BROKER["Clearnode"] - end - - subgraph OnChain["On-Chain Layer"] - direction TB - CONTRACTS["Custody & Adjudicator Contracts"] - end - - subgraph Blockchain["Blockchain Layer"] - direction TB - CHAIN["Ethereum, Polygon, Base, etc."] - end - - APP --> CLIENT - CLIENT <-->|"Nitro RPC Protocol"| BROKER - CLIENT -.->|"On-chain operations"| CONTRACTS - BROKER -.->|"Monitors events"| CONTRACTS - CONTRACTS --> CHAIN - - style Application fill:#e1f5ff,stroke:#9ad7ff,color:#111 - style OffChain fill:#fff4e1,stroke:#ffd497,color:#111 - style OnChain fill:#ffe1f5,stroke:#ffbde6,color:#111 - style Blockchain fill:#f0f0f0,stroke:#c9c9c9,color:#111 +flowchart TB + app["Application
Games, payments, exchanges"] + sdk["Client SDK + v1 RPC
typed calls and signed envelopes"] + node["Nitronode
state validation and coordination"] + chain["Blockchain layer
ChannelHub + engines"] + + app --> sdk + sdk <-->|"v1 RPC over WebSocket"| node + sdk -->|"deposit, checkpoint, challenge, close"| chain + node -->|"checkpoint and escrow coordination"| chain + chain -->|"events and enforced state"| node ``` -| Layer | Purpose | Speed | Cost | -|-------|---------|-------|------| -| **Application** | Your business logic and user interface | — | — | -| **Off-Chain** | Instant state updates via Nitro RPC | < 1 second | Zero gas | -| **On-Chain** | Fund custody, disputes, final settlement | Block time | Gas fees | +| Surface | Purpose | Typical speed | Cost | +|-------|---------|---------------|------| +| **Application** | Business logic, user interface, app-session rules | User interaction speed | App-defined | +| **Client SDK + v1 RPC** | Builds signed envelopes and calls Nitronode methods | Network round trip | No gas | +| **Nitronode** | Validates transitions, signs channel states, coordinates off-chain updates | Sub-second in normal operation | No gas | +| **Blockchain layer** | ChannelHub state enforcement, locked funds, challenge and close paths | Block time | Gas fees | --- -## On-Chain Layer: Security Foundation - -The on-chain layer provides cryptographic guarantees through smart contracts: - -### Custody Contract - -The **Custody Contract** is the core of VirtualApp's on-chain implementation. It handles: - -- **Channel Creation**: Lock funds and establish participant relationships -- **Dispute Resolution**: Process challenges and validate states -- **Final Settlement**: Distribute funds according to signed final state -- **Fund Management**: Deposit and withdrawal operations - -### Adjudicator Contracts +## ChannelHub -**Adjudicators** validate state transitions according to application-specific rules: +ChannelHub is the v1 on-chain entrypoint for channel enforcement. It works with ChannelEngine, EscrowDepositEngine, EscrowWithdrawalEngine, and signature validators. Builders interact with ChannelHub as the contract that creates channels, processes deposits and withdrawals, checkpoints signed states, accepts challenges, and closes channels. -- **SimpleConsensus**: Both participants must sign (default for payment channels) -- **Custom Adjudicators**: Application-specific validation logic +ChannelHub validates: -:::info On-Chain Operations -You only touch the blockchain for: +- channel definitions and channel identifiers +- approved signature validation modes +- state versions and intents +- home-ledger and non-home-ledger invariants +- locked-funds accounting +- challenge and close status transitions -1. Opening a channel (lock funds) -2. Resizing a channel (add or remove funds) -3. Closing a channel (unlock and distribute funds) -4. Disputing a state (if counterparty is uncooperative) - -::: +Routine transfers and app-session updates are signed off-chain. The blockchain is used for create, deposit, withdraw, checkpoint, challenge, close, escrow, and migration operations. --- -## Off-Chain Layer: Speed and Efficiency - -The off-chain layer handles high-frequency operations without blockchain transactions. +## Off-chain layer -### Clearnode +The off-chain layer handles frequent state advancement without blockchain transactions. -A **Clearnode** is operated by independent node operators using open-source software developed and maintained by Layer3 Fintech Ltd. It is the off-chain service that: +### Nitronode -- Manages the Nitro RPC protocol for state channel operations -- Provides a unified balance across multiple chains -- Coordinates payment channels between users -- Hosts app sessions for multi-party applications +Nitronode is operated by independent node operators using open-source software developed and maintained by Layer3 Fintech Ltd. It: -### Nitro RPC Protocol +- validates v1 channel transitions +- signs mutually agreed channel states +- issues pending receive and release states for user acknowledgement +- coordinates cross-chain escrow and app-session flows +- serves v1 RPC methods over WebSocket -**Nitro RPC** is a lightweight protocol optimized for state channel communication: +### v1 RPC -- **Compact format**: JSON array structure reduces message size by ~30% -- **Signed messages**: Every request and response is cryptographically signed -- **Real-time updates**: Bidirectional communication via WebSocket - -```javascript -// Compact Nitro RPC format -[requestId, method, params, timestamp] - -// Example: Transfer 50 USDC -[42, "transfer", {"destination": "0x...", "amount": "50.0", "asset": "usdc"}, 1699123456789] -``` +v1 RPC is the wire surface used by SDKs and low-level clients. Builders should prefer the SDK unless they are implementing an SDK, proxy, debugger, or language integration. --- ## How Funds Flow -This diagram shows how your tokens move through the system: +Funds are represented by channel states with a home ledger and, when needed, a non-home ledger. ```mermaid -graph TB - A["User Wallet
(ERC-20)"] -->|"1. deposit"| B["Available Balance
(Custody Contract)"] - B -->|"2. resize"| C["Channel-Locked
(Custody Contract)"] - C <-->|"3. resize"| D["Unified Balance
(Clearnode)"] - D -->|"4. open session"| E["App Sessions
(Applications)"] - E -->|"5. close session"| D - D -->|"6. resize/close"| B - B -->|"7. withdraw"| A - - style A fill:#90EE90,stroke:#333,color:#111 - style B fill:#87CEEB,stroke:#333,color:#111 - style C fill:#FFD700,stroke:#333,color:#111 - style D fill:#DDA0DD,stroke:#333,color:#111 - style E fill:#FFA07A,stroke:#333,color:#111 +flowchart TB + wallet["User wallet"] + hub["ChannelHub"] + home["Home channel
home ledger"] + nonhome["Non-home ledger
escrow in progress"] + session["App session
extension state"] + + wallet -->|"approve + home deposit"| hub + hub -->|"locked funds"| home + home <-->|"transfer / acknowledge"| home + home -->|"commit"| session + session -->|"release"| home + home <-->|"escrow initiate / finalize"| nonhome + home -->|"home withdrawal / close"| wallet ``` -### Fund States - -| State | Location | What It Means | -|-------|----------|---------------| -| **User Wallet** | Your EOA | Full control, on-chain | -| **Available Balance** | Custody Contract | Deposited, ready for channels | -| **Channel-Locked** | Custody Contract | Committed to a specific channel | -| **Unified Balance** | Clearnode | Available for off-chain operations | -| **App Session** | Application | Locked in a specific app session | +| Concept | What it means | +|-------|---------------| +| **Home channel** | The user and Node channel for a unified asset. | +| **Home ledger** | The authoritative ledger for the enforcement chain. | +| **Non-home ledger** | A temporary ledger for cross-chain escrow, withdrawal, or migration. | +| **App session** | An extension state funded by commit transitions and settled by release transitions. | --- ## Channel Lifecycle -A payment channel progresses through distinct states: +The v1 RPC exposes channel status as `void`, `open`, `challenged`, and `closed`. ```mermaid stateDiagram-v2 [*] --> VOID - VOID --> ACTIVE: create() with both signatures - ACTIVE --> ACTIVE: Off-chain updates (zero gas) - ACTIVE --> ACTIVE: resize() (add/remove funds) - ACTIVE --> FINAL: close() (cooperative) - ACTIVE --> DISPUTE: challenge() (if disagreement) - DISPUTE --> ACTIVE: checkpoint() (newer state) - DISPUTE --> FINAL: Timeout expires - FINAL --> [*] - - note right of ACTIVE: This is where
99% of activity happens + VOID --> OPEN: create or deposit + OPEN --> OPEN: signed off-chain updates + OPEN --> OPEN: checkpoint higher-version state + OPEN --> CHALLENGED: challenge + CHALLENGED --> OPEN: higher-version response + CHALLENGED --> CLOSED: challenge expires and close executes + OPEN --> CLOSED: cooperative close + CLOSED --> [*] + + note right of OPEN: Normal operation happens here ``` -:::info Legacy Flow -The diagram above shows the flow where both participants sign the initial state, creating the channel directly in ACTIVE status. See the [Channel Lifecycle](/nitrolite/protocol/channel-lifecycle) section for details. -::: +`CHALLENGED` means a participant has submitted a disputed state on-chain and the challenge duration is running. During that window, another participant may respond with a higher-version mutually signed state. If no higher-version response is accepted before expiry, the challenged state can be closed and funds are released according to that enforced state. See [Channel Lifecycle](/nitrolite/protocol/channel-lifecycle) and [Enforcement and Settlement](/nitrolite/protocol/enforcement-and-settlement) for the formal rules. ### Typical Flow -1. **Create**: Both parties sign initial state → channel becomes ACTIVE -2. **Operate**: Exchange signed states off-chain (unlimited, zero gas) -3. **Close**: Both sign final state → funds distributed - -### Dispute Path (Rare) - -If your counterparty becomes unresponsive: - -1. **Challenge**: Submit your latest signed state on-chain -2. **Wait**: Challenge period (typically 24 hours) allows counterparty to respond -3. **Finalize**: If no newer state is submitted, your state becomes final - ---- - -## Communication Patterns - -### Opening a Channel - -```mermaid -sequenceDiagram - participant Client - participant Clearnode - participant Blockchain - - Client->>Clearnode: create_channel request - Clearnode->>Client: channel config + Clearnode signature - Client->>Client: Sign state - Client->>Blockchain: create() with BOTH signatures - Blockchain->>Blockchain: Verify, lock funds, emit event - Blockchain-->>Clearnode: Event detected - Clearnode->>Client: Channel now ACTIVE -``` - -### Off-Chain Transfer - -```mermaid -sequenceDiagram - participant Sender - participant Clearnode - participant Receiver - - Sender->>Clearnode: transfer(destination, amount) - Clearnode->>Clearnode: Validate, update ledger - Clearnode->>Sender: Confirmed ✓ - Clearnode->>Receiver: balance_update notification - - Note over Sender,Receiver: Complete in < 1 second, zero gas -``` - ---- +1. **Create or deposit**: The user and Node sign an initial channel state; a deposit state may be submitted to ChannelHub to lock funds. +2. **Operate**: The user and Node exchange signed states off-chain for transfers, acknowledgements, commits, releases, and other valid transitions. +3. **Checkpoint or challenge**: Any party may enforce the latest mutually signed state if needed. +4. **Close**: A final signed state or expired challenge releases funds according to the enforced allocation. ## Key Takeaways | Concept | What to Remember | |---------|------------------| -| **On-Chain** | Only for opening, closing, disputes—security layer | -| **Off-Chain** | Where all the action happens—speed layer | -| **Clearnode** | Your gateway to the network—coordination layer | -| **State Channels** | Lock once, transact unlimited times, settle once | +| **ChannelHub** | The v1 contract entrypoint for enforcement and locked funds. | +| **Nitronode** | The off-chain coordinator for state advancement and v1 RPC. | +| **Channel state** | The signed record of allocations, version, transition, and ledgers. | +| **Home ledger** | The enforceable ledger for the channel's current home chain. | +| **App session** | An extension funded by commit transitions and settled through release transitions. | :::success Security Guarantee -At every stage, funds remain cryptographically secured. You can always recover your funds according to the latest valid signed state, even if a Clearnode becomes unresponsive. +For the home chain, assets can be recovered through ChannelHub with the latest mutually signed state even if Nitronode becomes unresponsive. ::: --- @@ -256,6 +151,6 @@ At every stage, funds remain cryptographically secured. You can always recover y Ready to start building? Continue to: -- **[Quickstart](/nitrolite/build/getting-started/quickstart)** — Create your first channel in minutes -- **[Prerequisites](/nitrolite/build/getting-started/prerequisites)** — Set up your development environment -- **[Core Concepts](../core-concepts/state-channels-vs-l1-l2.mdx)** — Deep dive into state channels +- **[Quickstart](/nitrolite/build/getting-started/quickstart)**: Create your first channel in minutes. +- **[Prerequisites](/nitrolite/build/getting-started/prerequisites)**: Set up your development environment. +- **[Core Concepts](../core-concepts/state-channels-vs-l1-l2.mdx)**: Deep dive into state channels. diff --git a/docs/nitrolite/learn/introduction/supported-chains.mdx b/docs/nitrolite/learn/introduction/supported-chains.mdx index 877cee7..e0acaf7 100644 --- a/docs/nitrolite/learn/introduction/supported-chains.mdx +++ b/docs/nitrolite/learn/introduction/supported-chains.mdx @@ -1,298 +1,81 @@ --- sidebar_position: 3 title: Supported Chains & Assets -description: Complete list of supported blockchains and assets on Yellow Network -keywords: [supported chains, blockchains, assets, tokens, USDC, Base, Polygon, Ethereum, sandbox, production] +description: Discover supported blockchains, assets, and ChannelHub addresses at runtime +keywords: [supported chains, blockchains, assets, tokens, ChannelHub, Ethereum Sepolia, Polygon Amoy, Base Sepolia] --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -:::warning[Work in Progress] -This page was carried over from the v0.5.x documentation and has not yet been fully updated for v1.x. Some terminology, code examples, and API references may be outdated. An update is in progress. -::: - # Supported Chains & Assets -This page lists all blockchains and assets currently supported on Yellow Network. - ---- - -## Environments - -Yellow Network operates two separate environments: - -| Environment | Purpose | URL | -|-------------|---------|-----| -| **Sandbox** | Development and testing | `wss://clearnet-sandbox.yellow.com/ws` | -| **Production** | Live operations with real assets | `wss://clearnet.yellow.com/ws` | - -:::info Environment Separation -- Sandbox uses **testnet** blockchains and test tokens (e.g., `ytest.usd`) -- Production uses **mainnet** blockchains and real assets (e.g., `usdc`) -- Assets and blockchains from one environment cannot be used in the other -::: +Yellow Network nodes advertise their supported blockchains, ChannelHub addresses, and assets through v1 RPC. Treat runtime discovery as the source of truth. --- -## Supported Blockchains - - - - -| Blockchain | Chain ID | Status | -|------------|----------|--------| -| Base Sepolia | 84532 | ✅ Active | -| Polygon Amoy | 80002 | ✅ Active | -| Ethereum Sepolia | 11155111 | ✅ Active | - - - - -| Blockchain | Chain ID | Status | -|------------|----------|--------| -| Ethereum | 1 | ✅ Active | -| BNB Smart Chain | 56 | ✅ Active | -| Polygon | 137 | ✅ Active | -| World Chain | 480 | ✅ Active | -| Base | 8453 | ✅ Active | -| Linea | 59144 | ✅ Active | -| XRPL EVM Sidechain | 1440000 | ✅ Active | - - - - ---- - -## Supported Assets - - - - -| Asset | Symbol | Description | -|-------|--------|-------------| -| Yellow Test USD | `ytest.usd` | Test stablecoin for sandbox development | - -:::tip Getting Test Tokens -Use the Yellow Network faucet to receive `ytest.usd` tokens for testing in the Sandbox environment. -::: - - - - -| Asset | Symbol | Blockchains | Decimals | -|-------|--------|-------------|----------| -| USD Coin | `usdc` | Ethereum, BNB Smart Chain, Polygon, World Chain, Base, Linea, XRPL EVM | 6 | -| Tether USD | `usdt` | BNB Smart Chain, Base, Linea | 6 | -| Ethereum | `eth` | Base, Linea | 18 | -| Wrapped Ether | `weth` | BNB Smart Chain, Polygon | 18 | -| BNB | `bnb` | BNB Smart Chain | 18 | -| Chainlink | `link` | BNB Smart Chain | 18 | -| XRP | `xrp` | XRPL EVM Sidechain | 18 | -| Beatwav | `beatwav` | Ethereum, Polygon | 18 | - - - - ---- - -## Assets by Blockchain - - - - -### Base Sepolia (84532) - -| Asset | Symbol | -|-------|--------| -| Yellow Test USD | `ytest.usd` | - -### Polygon Amoy (80002) - -| Asset | Symbol | -|-------|--------| -| Yellow Test USD | `ytest.usd` | - - - - -### Ethereum (1) - -| Asset | Symbol | -|-------|--------| -| USD Coin | `usdc` | -| Beatwav | `beatwav` | - -### BNB Smart Chain (56) - -| Asset | Symbol | -|-------|--------| -| BNB | `bnb` | -| USD Coin | `usdc` | -| Tether USD | `usdt` | -| Wrapped Ether | `weth` | -| Chainlink | `link` | - -### Polygon (137) - -| Asset | Symbol | -|-------|--------| -| USD Coin | `usdc` | -| Wrapped Ether | `weth` | -| Beatwav | `beatwav` | +## Runtime Discovery -### World Chain (480) +Do not hardcode v1 contract addresses in application docs or app configuration. The active Nitronode returns current network and asset configuration: -| Asset | Symbol | -|-------|--------| -| USD Coin | `usdc` | +- `client.getConfig()` wraps `node.v1.get_config` and returns the node address, node version, supported signature validators, supported blockchains, and each blockchain's ChannelHub address. +- `client.getAssets()` wraps `node.v1.get_assets` and returns asset symbols, decimals, suggested blockchain IDs, token addresses, and token chain IDs. -### Base (8453) - -| Asset | Symbol | -|-------|--------| -| Ethereum | `eth` | -| USD Coin | `usdc` | -| Tether USD | `usdt` | - -### Linea (59144) - -| Asset | Symbol | -|-------|--------| -| Ethereum | `eth` | -| USD Coin | `usdc` | -| Tether USD | `usdt` | - -### XRPL EVM Sidechain (1440000) - -| Asset | Symbol | -|-------|--------| -| USD Coin | `usdc` | -| XRP | `xrp` | +```typescript +import { Client, createSigners, withBlockchainRPC } from '@yellow-org/sdk'; + +const wsUrl = process.env.NITRONODE_WS_URL!; +const rpcUrl = process.env.RPC_URL!; +const chainId = BigInt(process.env.CHAIN_ID!); +const privateKey = process.env.PRIVATE_KEY as `0x${string}`; + +const { stateSigner, txSigner } = createSigners(privateKey); +const client = await Client.create( + wsUrl, + stateSigner, + txSigner, + withBlockchainRPC(chainId, rpcUrl), +); + +const config = await client.getConfig(); +const assets = await client.getAssets(); + +for (const chain of config.blockchains) { + console.log(`${chain.name} (${chain.id}) ChannelHub=${chain.channelHubAddress}`); +} + +for (const asset of assets) { + console.log(`${asset.symbol} decimals=${asset.decimals}`); + for (const token of asset.tokens) { + console.log(` chain=${token.blockchainId} token=${token.address}`); + } +} +``` - - +Raw RPC clients can call `node.v1.get_config` for blockchain and ChannelHub data and `node.v1.get_assets` for asset and token data. --- -## Contract Addresses - -Contract addresses vary by blockchain. See the [deployment repository](https://github.com/erc7824/nitrolite/tree/main/contract/deployments) for the latest addresses. - - - - -### Base Sepolia (84532) - -| Contract | Address | -|----------|---------| -| Custody | `0x019B65A265EB3363822f2752141b3dF16131b262` | -| Adjudicator | `0x7c7ccbc98469190849BCC6c926307794fDfB11F2` | - -### Polygon Amoy (80002) - -| Contract | Address | -|----------|---------| -| Custody | `0x019B65A265EB3363822f2752141b3dF16131b262` | -| Adjudicator | `0x7c7ccbc98469190849BCC6c926307794fDfB11F2` | - - - - -### Ethereum (1) - -| Contract | Address | -|----------|---------| -| Custody | `0x6F71a38d919ad713D0AfE0eB712b95064Fc2616f` | -| Adjudicator | `0x14980dF216722f14c42CA7357b06dEa7eB408b10` | - -### BNB Smart Chain (56) - -| Contract | Address | -|----------|---------| -| Custody | `0x6F71a38d919ad713D0AfE0eB712b95064Fc2616f` | -| Adjudicator | `0x14980dF216722f14c42CA7357b06dEa7eB408b10` | - -### Polygon (137) +## Deployed v1 Contract Folders -| Contract | Address | -|----------|---------| -| Custody | `0x490fb189DdE3a01B00be9BA5F41e3447FbC838b6` | -| Adjudicator | `0x7de4A0736Cf5740fD3Ca2F2e9cc85c9AC223eF0C` | +The Nitrolite repository currently contains v1 deployment artifacts under [`contracts/deployments`](https://github.com/layer-3/nitrolite/tree/main/contracts/deployments). -### World Chain (480) +| Chain ID | Deployment folder | +| ---: | --- | +| `11155111` | `contracts/deployments/11155111/` | +| `80002` | `contracts/deployments/80002/` | +| `84532` | `contracts/deployments/84532/` | -| Contract | Address | -|----------|---------| -| Custody | `0x6F71a38d919ad713D0AfE0eB712b95064Fc2616f` | -| Adjudicator | `0x14980dF216722f14c42CA7357b06dEa7eB408b10` | - -### Base (8453) - -| Contract | Address | -|----------|---------| -| Custody | `0x490fb189DdE3a01B00be9BA5F41e3447FbC838b6` | -| Adjudicator | `0x7de4A0736Cf5740fD3Ca2F2e9cc85c9AC223eF0C` | - -### Linea (59144) - -| Contract | Address | -|----------|---------| -| Custody | `0x6F71a38d919ad713D0AfE0eB712b95064Fc2616f` | -| Adjudicator | `0x14980dF216722f14c42CA7357b06dEa7eB408b10` | - -### XRPL EVM Sidechain (1440000) - -| Contract | Address | -|----------|---------| -| Custody | `0x6F71a38d919ad713D0AfE0eB712b95064Fc2616f` | -| Adjudicator | `0x14980dF216722f14c42CA7357b06dEa7eB408b10` | - - - - ---- +Each folder contains ChannelHub, ChannelEngine, escrow engine, signature validator, and test token deployment records for that chain. Use the runtime RPC response for the active endpoint you are connected to, because a node may support only a subset of deployed chains. --- -## Quick Code Reference +## Asset Symbols -### Connecting to the Right Environment +Asset symbols are node configuration, not protocol constants. The current v1 sandbox examples use symbols such as `yusd` and `yellow`, but applications should discover the available list through `client.getAssets()` or `node.v1.get_assets`. -```typescript -import { Client } from "yellow-ts"; - -// Sandbox (for testing with ytest.usd) -const sandboxClient = new Client({ - url: 'wss://clearnet-sandbox.yellow.com/ws', -}); - -// Production (for real assets like usdc) -const productionClient = new Client({ - url: 'wss://clearnet.yellow.com/ws', -}); -``` - -### Using the Correct Asset - -```typescript -// Sandbox environment -const sandboxAllocations = [ - { participant: address1, asset: 'ytest.usd', amount: '100.0' }, - { participant: address2, asset: 'ytest.usd', amount: '0.0' } -]; - -// Production environment -const productionAllocations = [ - { participant: address1, asset: 'usdc', amount: '100.0' }, - { participant: address2, asset: 'usdc', amount: '0.0' } -]; -``` +When the canonical sandbox URL and faucet are finalized, verify symbols against the live endpoint before publishing copy-paste funding instructions. --- ## See Also -- [Quick Start Guide](/nitrolite/build/quick-start) — Get started building with Yellow SDK -- [Multi-Party App Sessions](/nitrolite/build/sdk/multi-party-app-sessions) — Create multi-party application sessions -- [API Reference](/nitrolite/api-reference) — Complete SDK documentation +- [Quick Start Guide](/nitrolite/build/getting-started/quickstart): Create a v1 channel with the SDK. +- [API Reference](/nitrolite/api-reference): Inspect the raw `node.v1.get_config` and `node.v1.get_assets` methods. diff --git a/docs/nitrolite/learn/introduction/what-yellow-solves.mdx b/docs/nitrolite/learn/introduction/what-yellow-solves.mdx index 87f7c93..b663b2b 100644 --- a/docs/nitrolite/learn/introduction/what-yellow-solves.mdx +++ b/docs/nitrolite/learn/introduction/what-yellow-solves.mdx @@ -1,20 +1,16 @@ --- sidebar_position: 1 title: What Yellow Solves -description: Understand the core problems Yellow Network addresses - scaling, cost, and speed +description: "Understand the core problems Yellow Network addresses: scaling, cost, and speed" keywords: [Yellow Network, state channels, blockchain scaling, off-chain, Web3] --- import Tooltip from '@site/src/components/Tooltip'; import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions'; -:::warning[Work in Progress] -This page was carried over from the v0.5.x documentation and has not yet been fully updated for v1.x. Some terminology, code examples, and API references may be outdated. An update is in progress. -::: - # What Yellow Solves -In this guide, you will learn why Yellow Network exists, what problems it addresses, and how it provides a faster, cheaper way to build Web3 applications. Yellow Network is developed and maintained by Layer3 Fintech Ltd. and operated by independent node operators running the issuer's open-source software. +Yellow Network lets applications move high-frequency asset updates off-chain while keeping the latest mutually signed state enforceable on-chain. --- @@ -28,122 +24,100 @@ Every blockchain transaction requires global consensus. While this guarantees se | **High Costs** | Gas fees spike during network congestion, making microtransactions impractical | | **Limited Throughput** | Networks like Ethereum process ~15-30 transactions per second | -For applications requiring real-time interactions—gaming, trading, micropayments—these constraints make traditional blockchain unusable as a backend. +For applications requiring real-time interactions, such as gaming, trading, and micropayments, these constraints make traditional blockchain execution a poor backend for every user action. --- ## How Yellow Network Solves This -Yellow Network uses **state channels** to move high-frequency operations off-chain while preserving blockchain-level security guarantees. +Yellow Network uses **state channels** to move frequent operations off-chain while preserving blockchain-level enforcement for the latest mutually signed state. ### The Core Insight -Most interactions between parties don't need immediate on-chain settlement. Consider a chess game with a 10 USDC wager: +Most interactions between parties do not need immediate on-chain settlement. Consider a chess game with a `new Decimal("10")` USDC wager: -- **On-chain approach**: Every move requires a transaction → 40+ transactions → $100s in fees -- **State channel approach**: Lock funds once, play off-chain, settle once → 2 transactions → minimal fees +| Approach | Result | +| --- | --- | +| On-chain moves | Every move requires a transaction. A 40-move game becomes 40+ transactions and repeated gas fees. | +| State channel moves | Players lock funds once, sign moves off-chain, and settle the final allocation through one enforceable state. | -State channels let you execute unlimited off-chain operations between on-chain checkpoints. +State channels let applications execute many signed off-chain operations between occasional on-chain checkpoints. ### What You Get -| Feature | Benefit | -|---------|---------| -| **Instant Transactions** | Sub-second finality (< 1 second typical) | -| **Zero Gas Costs** | Off-chain operations incur no blockchain fees | -| **Unlimited Throughput*** | No consensus bottleneck limiting operations | -| **Blockchain Security** | Funds are always recoverable via on-chain contracts | - -*\*Theoretically unlimited—state channels have no blockchain consensus overhead. Real-world performance depends on signature generation speed, network latency between participants, and application complexity. We'll be publishing detailed benchmarks soon.* - ---- - -## The VirtualApp Protocol - -Yellow Network is built on **VirtualApp**, a state channel protocol designed for EVM-compatible chains. VirtualApp provides: - -- **Fund Custody**: Smart contracts that securely lock and release assets -- **Dispute Resolution**: Challenge-response mechanism ensuring fair outcomes -- **Final Settlement**: Cryptographic guarantees that final allocations are honored +- **Fast updates:** Users exchange signed states without waiting for block confirmation. +- **No gas per off-chain update:** Routine channel operations do not send a transaction. +- **High throughput:** Throughput is bounded by signing, networking, and application logic rather than global chain consensus. +- **On-chain enforcement:** A participant can submit the latest mutually signed state to ChannelHub if cooperation fails. :::tip When to Use Yellow Network Choose Yellow Network when your application needs: - Real-time interactions between users - Microtransactions or streaming payments -- High transaction volumes without gas costs -- Multi-party coordination with instant settlement +- High transaction volume without gas per update +- Multi-party coordination with enforceable settlement ::: --- -## Chain Abstraction with Clearnode +## Chain Abstraction with Nitronode -A **Clearnode** is operated by independent node operators using the issuer's open-source software. It serves as your entry point to Yellow Network. When you connect to a Clearnode: +A **Nitronode** is operated by an independent node operator using open-source software. It coordinates v1 RPC, validates state transitions, signs channel updates, and tracks the channel state each user shares with the Node. -1. **Deposit** tokens into the Custody Contract on any supported chain -2. **Resize** your channel to move funds to your unified balance -3. **Transact** instantly with any other user on the network -4. **Withdraw** back through the Custody Contract to any supported chain +In v1, the user's main balance lives in a **home channel**. The home channel has a **home ledger** tied to the chain where the latest state is enforceable. When cross-chain movement is needed, a **non-home ledger** tracks the temporary escrow state until the operation is finalized. -:::note Fund Flow -Funds flow through the Custody Contract (on-chain) before reaching your unified balance (off-chain). The `resize` operation moves funds between your on-chain available balance and your off-chain unified balance. See [Architecture](./architecture-at-a-glance#how-funds-flow) for the complete flow. -::: +Typical flow: -For example, deposit 50 USDC on Polygon and 50 USDC on Base—after resizing, your unified balance shows 100 USDC. You can then withdraw all 100 USDC to Arbitrum if you choose. +1. **Create or deposit into a home channel.** The user approves the ChannelHub spender and submits a signed deposit state. ChannelHub locks the deposited ERC-20 or native ETH amount for that channel. +2. **Transact off-chain.** The user and Nitronode exchange signed channel states for transfers, acknowledgements, commits, releases, and other v1 transitions. +3. **Move across chains through escrow.** Cross-chain deposits and withdrawals use two-phase escrow states that coordinate the home ledger and non-home ledger. +4. **Settle when needed.** Any party may checkpoint, challenge, or close with an enforceable mutually signed state. ```mermaid -graph LR - A["Deposit on Polygon
50 USDC"] --> C["Unified Balance
100 USDC"] - B["Deposit on Base
50 USDC"] --> C - C --> D["Withdraw to Arbitrum
100 USDC"] - - style C fill:#90EE90,stroke:#333,color:#111 +flowchart LR + wallet["User wallet"] + hub["ChannelHub"] + home["Home channel state"] + escrow["Escrow state
(when cross-chain)"] + app["App session"] + + wallet -->|"approve + deposit"| hub + hub --> home + home <-->|"signed updates"| home + home -->|"commit"| app + app -->|"release"| home + home <-->|"escrow initiate/finalize"| escrow ``` --- ## Real-World Applications -### Payment Applications - -- **Micropayments**: Pay-per-article, API usage billing, content monetization -- **Streaming payments**: Subscription services, hourly billing, real-time payroll -- **P2P transfers**: Instant remittances without intermediaries - -### Gaming Applications - -- **Turn-based games**: Chess, poker, strategy games with wagers -- **Real-time multiplayer**: In-game economies with instant transactions -- **Tournaments**: Prize pools and automated payouts - -### DeFi Applications - -- **High-frequency trading**: Execute trades without MEV concerns -- **Prediction markets**: Real-time betting with instant settlement -- **Escrow services**: Multi-party coordination with dispute resolution +- **Payments:** Micropayments, streaming payments, P2P transfers, API billing, and content monetization. +- **Gaming:** Turn-based wagers, tournament payouts, and in-game economies with instant updates. +- **DeFi:** High-frequency trading, prediction markets, and escrow flows with enforceable settlement. --- ## Security Model -Yellow Network maintains blockchain-level security despite operating off-chain: +Yellow Network maintains blockchain-level enforcement despite operating off-chain: -| Guarantee | How It's Achieved | -|-----------|-------------------| -| **Fund Safety** | All funds locked in audited smart contracts | -| **Dispute Resolution** | Challenge period allows contesting incorrect states | -| **Cryptographic Proof** | Every state transition is signed by participants | -| **Recovery Guarantee** | Users can always recover funds via on-chain contracts | +| Guarantee | How It Works | +|-----------|--------------| +| **Fund safety** | Participants cannot lose assets without signing a state that authorizes the change. | +| **Dispute resolution** | A challenge period lets participants respond with a higher-version state. | +| **Cryptographic proof** | Every enforceable channel state is signed by the required participants. | +| **Recovery path** | Home-chain assets can be recovered through ChannelHub using the latest mutually signed state. | -If a Clearnode becomes unresponsive or malicious, you can submit your latest signed state to the blockchain and recover your funds after a challenge period. +The current protocol still has trust assumptions around Node liveness, cross-chain liquidity, and cross-chain relay. Read [Security and Limitations](/nitrolite/protocol/security-and-limitations) for the formal boundary. --- -## Next Steps - -Now that you understand what Yellow solves, continue to: +## Where to next -- **[Architecture at a Glance](./architecture-at-a-glance.mdx)** — See how the protocol layers work together -- **[Quickstart](/nitrolite/build/getting-started/quickstart)** — Create your first state channel in minutes +- **[Architecture at a Glance](./architecture-at-a-glance.mdx)**: See the v1 layers, state model, and lifecycle. +- **[Supported Chains & Assets](./supported-chains.mdx)**: Learn how to discover supported chains, assets, and contract addresses at runtime. +- **[Protocol terminology](/nitrolite/protocol/terminology)**: Use the formal v1 term definitions until the Learn glossary lands. diff --git a/docs/nitrolite/learn/protocol-flows/architecture.mdx b/docs/nitrolite/learn/protocol-flows/architecture.mdx index c21c1ed..cf6ce90 100644 --- a/docs/nitrolite/learn/protocol-flows/architecture.mdx +++ b/docs/nitrolite/learn/protocol-flows/architecture.mdx @@ -6,7 +6,7 @@ sidebar_position: 1 # Protocol Architecture (Petal Diagram) -The **Petal Diagram** is the central architectural reference for the Nitrolite Protocol. It maps how different actions -- Deposits, Withdrawals, Transfers, and App Sessions -- interact with various blockchains, all centered on a user's channel ("My Channel"). +The **Petal Diagram** is the central architectural reference for the Nitrolite Protocol. It maps how deposits, withdrawals, transfers, and app sessions interact with blockchains, all centered on a user's channel. Nitrolite Protocol Petal Diagram @@ -18,88 +18,52 @@ The **Petal Diagram** is the central architectural reference for the Nitrolite P ### Petal 1: My Home Chain (Deposits and Withdrawals) -The **Home Chain** is the blockchain chosen by the user when they first create their channel or deposit a specific token. +The **Home Chain** is the blockchain where the user's channel state is enforced for a specific asset. :::info Important Choice -When selecting your Home Chain, consider that this is the blockchain where your funds will be **enforced on-chain**. If you are unable to agree with the Node on a next state (e.g., in a dispute scenario), you can withdraw your funds on this specific blockchain. Choose a chain where you have easy access and are comfortable transacting. +When selecting your Home Chain, choose the blockchain where you are comfortable enforcing and withdrawing funds if cooperation with the Node fails. ::: -**The Flow:** - -- **Deposit:** When a user deposits for the first time, that specific chain (e.g., Polygon) becomes the "Home Chain" for that token. -- **Optimization:** This process improves upon the previous version by **skipping the custody ledger step**, reducing one step and improving UX. -- **Mechanism:** Users transfer funds directly from their ERC-20 token balance via approvals, saving one transaction compared to the old protocol. -- **Withdrawal:** The withdrawal process follows the exact same direct logic as the deposit. - -**Key Benefit:** Direct fund transfers without intermediate custody steps result in reduced gas costs and improved UX. +**The Flow:** The user approves the ChannelHub spender, submits a signed home-deposit state, and ChannelHub pulls ERC-20 tokens or native ETH into the home channel. A home-withdrawal state releases funds from ChannelHub back to the user. --- ### Petal 2: Another Chain (Cross-Chain Support) -When a user already has a Home Chain (e.g., Polygon) with funds and wants to deposit funds from a *different* chain (e.g., Linea or Base), the protocol uses a specialized bridge mechanism. - -**The Challenge:** Since the user's Home Chain is already defined, the protocol needs a different mechanism to handle deposits from a non-home chain. +When a user already has a Home Chain with funds and wants to deposit from a different chain, the protocol uses a two-phase escrow mechanism. -**The Solution -- The Bridge:** +**The Challenge:** The home ledger is authoritative for enforcement, but the user's funds may start on a non-home chain. -- The protocol implements a specialized bridge solution. -- Cross-chain deposits work similarly to cross-chain transfers, but with **atomic properties** -- ensuring the action either fully completes or doesn't happen at all. -- Atomicity is achieved not via smart contract infrastructure alone, but with the help of the participants. Both the User and the Node can see whether the process is failing on one chain and can cancel the process on another chain. +**The Solution:** A signed escrow-deposit initiate state creates a non-home escrow record, and a signed finalize state completes the deposit and updates the home ledger. Cross-chain withdrawals mirror this flow. WAD normalization validates cross-chain amounts when token decimals differ. -**Key Property:** Atomic execution guarantees -- no partial states or stuck funds. +**Key Property:** Escrow coordinates the home ledger and non-home ledger so cross-chain operations can be challenged or finalized according to the protocol rules. --- ### Petal 3: Transfers (Sender and Receiver State) -Unlike state changes within a single channel, transfers between *two different users* are not strictly "atomic" because the two users have **unrelated states**. You cannot update the receiver's state on-chain immediately when the sender initiates the transfer. +Transfers update two unrelated user channels. The sender signs a `transfer_send` state. The receiver later acknowledges a Node-issued `transfer_receive` state. -**The Solution -- Aggregated State Updates:** +**The Solution:** The sender signs a new state showing funds sent through the Node. Nitronode prepares a receive state for the receiver's channel. The receiver signs an acknowledgement to make the pending state mutually signed and enforceable. -- **Sender Action:** The sender submits their new state (showing funds sent). -- **Verification:** If the Clearnode accepts this state as valid, it prepares a "pending state" for the Receiver. -- **Receiver Action (Aggregation):** If a receiver gets multiple transfers from different people, they do **not** need to sign a state update for every single transfer. -- **Efficiency:** The "receive" updates are **aggregated**. Only the Node signs the aggregated states; the Receiver doesn't need to. However, when such states may be aggregated with a "send", "lock", or "withdraw", then the Receiver needs to sign these new states. -- It is in the Receiver's security interest to own the latest state (to be able to challenge with it if the network goes down). The main challenge for the Receiver is to obtain the "receive" state signed by the Node if they are offline or not connected to the Node. -- In v1.0, not only the receiver but anyone can subscribe for state updates, enabling users to hire **User Watchtowers** that listen to "receive" state updates and store such states for the User. - -**Key Optimization:** Batch processing reduces signature overhead and improves throughput. +**Key Efficiency:** Receive states can be batched before acknowledgement, reducing signature overhead while preserving the enforceable-state boundary. --- -### Petal 4: App Sessions (The "Virtual Layer") - -App Sessions function as a **Virtual Layer** within the protocol. +### Petal 4: App Sessions -**The Node Mechanism:** +App sessions are extension states funded by commit transitions from the user's home channel. -- When a user enters an App Session (locks funds), those funds move to the Node. -- These funds are technically locked on the Node's wallet and are **not directly enforced by the State Channel** during the session. +**The Mechanism:** A `commit` transition moves assets from the user's home channel ledger into the app session extension. The app session tracks its own state and participant allocations. A `release` transition returns assets from the app session back into the user's channel ledger. **Security and Risk:** -- If the Node misbehaves, the user can currently only recover funds that are *not* locked in an active session. +- Home-channel assets outside app sessions remain recoverable through the latest mutually signed channel state. +- In-session app funds depend on the app-session participants and current extension-layer trust assumptions. +- The protocol roadmap includes stronger extension-layer enforcement and watchtower support. -:::note -This is a limitation in the current version of the protocol. Future work to improve App Session security through Node Watchtowers and cryptographic proofs is planned. +:::note Current trust boundary +Do not describe app-session funds as fully on-chain enforced in the current protocol version. The core channel layer is enforceable through ChannelHub; extension-layer security is still improving. ::: -- To simplify security, the protocol restricts App Sessions to **one participant deposit of one token per session update**. - -**Future Validation -- Node Watchtowers:** - -- **Third-Party Node Observers (Node Watchtowers)** will validate actions on the Virtual Layer. -- If they detect misbehavior by the Node, they can intervene or slash, ensuring the system remains trustless. - -**UX Philosophy:** The Virtual Layer stays flexible (allowing flexible app sessions, settlements, and swaps), while the **Fundamental Layer** (Deposits/Withdrawals/Transfers) remains strictly enforced on-chain. - ---- - -## Protocol Layers - -| Layer | Description | Security Level | -| --- | --- | --- | -| **Fundamental Layer** | Deposits/Withdrawals (on-chain) and Transfers (off-chain) | Strictly enforced on-chain (High Security) | -| **Virtual Layer** | App Sessions and internal movements | Broker/Watchtower model (High Flexibility) | -| **Cross-Chain** | Managed via specialized bridge | Atomic swap properties | +**UX Philosophy:** Core deposits, withdrawals, transfers, and challenges stay tied to channel-state enforcement, while app sessions provide flexible application logic through the extension layer.