Terminology
Core Concepts
Channel: A secure communication pathway between participants that locks funds in an on-chain smart contract while enabling off-chain state updates.
State: A snapshot of the channel at any point in time, including fund allocations and application-specific data.
Participant: An entity (identified by a wallet address) that is part of a channel.
Clearnode: A node operated by independent operators using open-source software developed by Layer3 Fintech Ltd. It provides a unified ledger (through the Nitro RPC protocol), coordinates state channels (through VirtualApp), and enables chain abstraction for developers and users.
Creator: The participant at index 0 in a channel who initiates channel creation.
App Sessions: Off-chain channels built on top of payment channels, intended to be used by app developers to enable application-specific interactions and transactions without touching the blockchain.
Unified Balance: An abstraction that aggregates users' funds across multiple blockchain networks, managed by a clearnode.
Session Key: A temporary cryptographic key delegated by a user's main wallet that provides a flexible way for the user to manage security of their funds by giving specific permissions and allowances for specific apps.
Identifiers
channelId: A unique identifier for a channel, computed as the hash of the channel configuration, formatted as a 0x-prefixed hex string (32 bytes).
packedState: A specific encoding of a channelId, state.intent, state.version, state.data, state.allocations, used for signing and signature verification.
requestId: A unique identifier for an RPC request, used for correlating requests and responses formatted as a 0x-prefixed hex string (32 bytes).
appSessionId: A unique identifier for an app session, formatted as a 0x-prefixed hex string (32 bytes). Used for all subsequent operations on that specific app session.
accountId: An identifier for an account or app session within the unified ledger. Can be either a 0x-prefixed hex string or a wallet address.
chainId: A blockchain network identifier (uint64). Examples: 1 (Ethereum Mainnet), 137 (Polygon), 8453 (Base), 42161 (Arbitrum One), 10 (Optimism).
assetSymbol: A lowercase string identifier for a supported asset. Asset symbols are consistent across chains.
walletAddress: A user's blockchain address (0x-prefixed hex string, 20 bytes) that identifies their account and owns funds. Used to identify participants in channels and app sessions.
userId: Identifies a user after authentication to the Clearnode. Currently, this is always equivalent to the user's walletAddress.
On-Chain Contracts
Custody Contract: The main on-chain contract implementing the VirtualApp protocol. It provides the functionality to lock and unlock funds; create, close and challenge a channel; track channel state, and coordinate with adjudicators to validate state transitions on state updates.
Adjudicator: A smart contract that defines the rules for validating state transitions during all channel lifecycle operations. The adjudicator's adjudicate(...) function is called by the Custody contract to verify whether a new state is valid based on previous states and application-specific logic. Examples include SimpleConsensus (requires both signatures) and Remittance (only sender must sign).
Protocol Layers
Decentralized Layer (YNP): The peer-to-peer overlay network — Kademlia DHT, BLS threshold clusters, elastic security, and the liquidity layer. Manages account state, cross-shard transfers, and settlement.
App Layer (VirtualApp): The state channel protocol (also known as YApps) — on-chain custody and adjudicator contracts, plus the off-chain Nitro RPC protocol for fast state updates.
Nitro RPC: The off-chain communication protocol used by the App Layer for channel operations, transfers, and app sessions.
Decentralized Layer Terms
NodeID: A 256-bit identity derived from on-chain randomness at registration. Each NodeID requires collateral.
Signing Cluster (C_sign): The set of k nodes closest to an account's key in the DHT, responsible for BLS threshold signing.
Replication Set (C_watch): A larger ring of r nodes that independently verify signing cluster state. Always a superset of the signing cluster.
Certificate: The protocol's universal primitive for state change — a cluster-attested operation carrying a BLS threshold signature.
Escrow Certificate: A certificate authorizing a withdrawal from the network to L1.
Dispute Certificate: A certificate produced by the replication set to override a fraudulent withdrawal.
These terms are used throughout the protocol specification. Bookmark this page for easy reference while reading other sections.