Skip to main content
Version: 1.x
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.

The Three Layers​

Yellow Network consists of three interconnected layers, each with a specific responsibility:

LayerPurposeSpeedCost
ApplicationYour business logic and user interface——
Off-ChainInstant state updates via Nitro RPC< 1 secondZero gas
On-ChainFund custody, disputes, final settlementBlock timeGas 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​

Adjudicators validate state transitions according to application-specific rules:

  • SimpleConsensus: Both participants must sign (default for payment channels)
  • Custom Adjudicators: Application-specific validation logic
On-Chain Operations

You only touch the blockchain for:

  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)

Off-Chain Layer: Speed and Efficiency​

The off-chain layer handles high-frequency operations without blockchain transactions.

Clearnode​

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:

  • 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

Nitro RPC Protocol​

Nitro RPC is a lightweight protocol optimized for state channel communication:

  • 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
// Compact Nitro RPC format
[requestId, method, params, timestamp]

// Example: Transfer 50 USDC
[42, "transfer", {"destination": "0x...", "amount": "50.0", "asset": "usdc"}, 1699123456789]

How Funds Flow​

This diagram shows how your tokens move through the system:

Fund States​

StateLocationWhat It Means
User WalletYour EOAFull control, on-chain
Available BalanceCustody ContractDeposited, ready for channels
Channel-LockedCustody ContractCommitted to a specific channel
Unified BalanceClearnodeAvailable for off-chain operations
App SessionApplicationLocked in a specific app session

Channel Lifecycle​

A payment channel progresses through distinct states:

Legacy Flow

The diagram above shows the recommended flow where both participants sign the initial state, creating the channel directly in ACTIVE status. A legacy flow also exists where only the creator signs initially (status becomes INITIAL), and other participants call join() separately. See Channel Lifecycle for details.

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​

Off-Chain Transfer​

Key Takeaways​

ConceptWhat to Remember
On-ChainOnly for opening, closing, disputes—security layer
Off-ChainWhere all the action happens—speed layer
ClearnodeYour gateway to the network—coordination layer
State ChannelsLock once, transact unlimited times, settle once
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.

Next Steps​

Ready to start building? Continue to: