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.
App Sessions
App sessions are off-chain channels built on top of the unified balance that enable multi-party applications with custom governance rules.
Goal: Understand how app sessions work for building multi-party applications.
What is an App Session?
An app session is a temporary shared account where multiple participants can:
- Lock funds from their unified balance
- Execute application-specific logic (games, escrow, predictions)
- Redistribute funds based on outcomes
- Close and release funds back to unified balances
Think of it as a programmable escrow with custom voting rules.
App Session vs Payment Channel
| Feature | Payment Channel | App Session |
|---|---|---|
| Participants | Always 2 | 2 or more |
| Governance | Both must sign | Quorum-based |
| Fund source | On-chain deposit | Unified balance |
| Mid-session changes | Via resize (on-chain) | Via intent (off-chain) |
| Use case | Transfers | Applications |
App Session Definition
Every app session starts with a definition that specifies the rules:
| Field | Description |
|---|---|
protocol | Version (NitroRPC/0.4 recommended) |
participants | Wallet addresses (order matters for signatures) |
weights | Voting power per participant |
quorum | Minimum weight required for state updates |
challenge | Dispute window in seconds |
nonce | Unique identifier (typically timestamp) |
The app_session_id is computed deterministically from the definition using keccak256(JSON.stringify(definition)).
Governance with Quorum
The quorum system enables flexible governance patterns.
How It Works
- Each participant has a weight (voting power)
- State updates require signatures with total weight ≥ quorum
- Not everyone needs to sign—just enough to meet quorum
Common Patterns
| Pattern | Setup | Use Case |
|---|---|---|
| Unanimous | weights: [50, 50], quorum: 100 | Both must agree |
| Trusted Judge | weights: [0, 0, 100], quorum: 100 | App determines outcome |
| 2-of-3 Escrow | weights: [40, 40, 50], quorum: 80 | Any two can proceed |
| Weighted Voting | weights: [20, 25, 30, 25], quorum: 51 | Majority by weight |
Session Lifecycle
1. Creation
- Funds locked from participants' unified balances
- All participants with non-zero allocations must sign
- Status becomes
open, version starts at1
2. State Updates
- Redistribute funds with
submit_app_state - Version must increment by exactly 1
- Quorum of signatures required
3. Closure
- Final allocations distributed to unified balances
- Session becomes
closed(cannot reopen) - Quorum of signatures required
Intent System (NitroRPC/0.4)
The intent system enables dynamic fund management during active sessions:
| Intent | Purpose | Rule |
|---|---|---|
| OPERATE | Redistribute existing funds | Sum unchanged |
| DEPOSIT | Add funds from unified balance | Sum increases |
| WITHDRAW | Remove funds to unified balance | Sum decreases |
Allocations always represent the final state, not the delta. The Clearnode computes deltas internally.
Fund Flow
Protocol Versions
| Version | Status | Key Features |
|---|---|---|
| NitroRPC/0.2 | Legacy | Basic state updates only |
| NitroRPC/0.4 | Current | Intent system (OPERATE, DEPOSIT, WITHDRAW) |
Always use NitroRPC/0.4 for new applications. Protocol version is set at creation and cannot be changed.
Best Practices
- Set appropriate challenge periods: 1 hour minimum, 24 hours recommended
- Include commission participants: Apps often have a judge that takes a small fee
- Plan for disputes: Design allocations that can be verified by third parties
- Version carefully: Each state update must be exactly
current + 1
Deep Dive
For complete method specifications and implementation details:
- App Session Methods — Complete method specifications
- Communication Flows — Sequence diagrams
- Implementation Checklist — Building app session support