Trivia Royale Guide

A practical guide for building state channel applications with the Yellow SDK. This documentation is built from real-world experience implementing Trivia Royale, a multiplayer trivia game that demonstrates core state channel concepts through working code.

Core Concepts

Before building with state channels, you need to understand three fundamental concepts:

The Balance Model

State channels use a 4-layer balance system where funds flow through distinct layers:

• Wallet Balance - Your on-chain ETH (starting point)
• Custody Balance - Funds deposited to Yellow's smart contract
• Channel Balance - Your capacity in a payment channel
• Ledger Balance - Allocated funds within application sessions (can be negative)

Understanding this model is critical because different operations require funds in different layers, and withdrawals must traverse all layers in reverse.

Application Sessions

Sessions are isolated instances where participants interact with instant, gasless transactions. Each session defines:

• Who can participate
• How much each participant stakes
• How funds are distributed when the interaction completes

Sessions enable typed, broadcast messaging between participants and handle fund distribution automatically.

Message Flow

Clients communicate asynchronously through the ClearNode broker. The architecture:

• ClearNode broadcasts messages to all session participants
• You must handle broadcasting your own messages
• Message ordering and timing affect application behavior
• Typed schemas enable auto-joining and state synchronization

Building Blocks

Practical patterns you'll use in every application:

When to Use Each

ClearNode Communication - Understanding the low-level infrastructure:

• Debugging WebSocket connection issues
• Building custom RPC operations
• Understanding state transitions
• Managing session keys across restarts

Fund Management - Moving value in or out of the system:

• Initial user onboarding (deposit funds)
• Cashing out winnings (withdraw funds)
• Rebalancing channel capacity
• Peer-to-peer payments

Distributed Sessions - Creating multi-party applications:

• Multiplayer games requiring coordination
• Multi-party contracts and agreements
• Collaborative applications
• Tournament brackets

Session Lifecycle - Managing application state:

• Tracking active games and sessions
• Cleaning up after completion
• Handling disconnections gracefully
• Managing UI state

Patterns & Examples

Complete implementations you can adapt:

Prerequisites

This guide assumes you're a TypeScript developer with:

• Basic understanding of Web3 concepts (wallets, addresses, signatures)
• Familiarity with async/await patterns
• Experience with event-driven architecture
• Node.js or browser environment setup

You do not need deep blockchain knowledge or state channel theory - we'll explain everything as we go.

Quick Reference