Skip to main content

Glossary

Complete alphabetical reference of all protocol terms and concepts.

Quick Reference

This glossary provides concise definitions of all Nitrolite protocol terms. For detailed explanations with examples and diagrams, see the respective sections in the documentation.

A​

Adjudicator​

Smart contract that validates state transitions according to application-specific rules. Each channel specifies an adjudicator that determines which state updates are valid.

Examples: SimpleConsensus, RemittanceAdjudicator

Related: Data Structures, Security Considerations

Allocation​

Specification of how funds are distributed, containing destination, token, and amount. Allocations define where funds should be sent when a channel closes or how they're distributed within an app session.

Structure:

{
  destination: address,  // Recipient wallet address
  token: address,        // ERC-20 token contract
  amount: uint256        // Amount in smallest unit
}

Related: Data Structures

App Session​

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. Previously known as Virtual Ledger Channels (VLC).

Features:

  • Multi-party participation
  • Custom governance rules (quorum, weights)
  • Fund locking from unified balance
  • Application-specific state management

Related: App Sessions Methods, Communication Flows

C​

Challenge Period​

Duration (in seconds) that parties have to respond to a dispute. When a channel is challenged, all participants have this amount of time to submit a newer state before the challenged state becomes final.

Typical Values:

  • Default: 86400 seconds (24 hours)
  • Minimum recommended: 3600 seconds (1 hour)
  • Maximum recommended: 604800 seconds (7 days)

Related: Channel Lifecycle

Channel​

A secure communication pathway between participants that locks funds in an on-chain smart contract while enabling off-chain state updates. Channels are the foundation of the Nitrolite protocol.

Lifecycle: VOID → INITIAL → ACTIVE → (DISPUTE) → FINAL

Related: On-Chain Protocol, Data Structures

channelId​

A unique identifier for a channel, formatted as a 0x-prefixed hex string (32 bytes). Computed deterministically from the channel configuration.

Computation:

channelId = keccak256(abi.encode(
  channel.participants,
  channel.adjudicator,
  channel.challenge,
  channel.nonce
))

Related: Data Structures

Checkpoint​

Recording a state on-chain without entering dispute mode. Checkpointing creates an on-chain record of the current state but keeps the channel in ACTIVE status.

Benefits:

  • Shortens effective challenge history
  • Provides on-chain proof of state
  • Doesn't start challenge period

Related: Channel Lifecycle

Clearnode​

A virtual ledger layer that provides a unified ledger (through Nitro RPC) and coordinates state channels (through Nitrolite), providing chain abstraction for developers and users.

Responsibilities:

  • Manage off-chain RPC protocol
  • Provide unified balance
  • Join payment channels
  • Coordinate app sessions

Related: Architecture, Off-Chain RPC Protocol

Creator​

The participant at index 0 in a channel who initiates channel creation. The Creator constructs the channel configuration, prepares the initial funding state, signs it (signature at position 0), and calls the on-chain create() function to lock their funds and establish the channel.

Typically: A user or light client opening a payment channel with a clearnode.

Related: Channel Lifecycle, Protocol Reference

Custody Contract​

The main on-chain contract implementing channel creation, joining, closure, and resizing. It is an implementation of the Nitrolite protocol.

Interfaces Implemented:

  • IChannel - Core channel operations
  • IDeposit - Fund management
  • IChannelReader - State queries

Related: On-Chain Overview, Data Structures

I​

Intent​

In NitroRPC/0.4, specifies the type of app session state update. The intent system enables dynamic fund management within active sessions.

Types:

  • OPERATE: Redistribute existing funds (sum unchanged)
  • DEPOSIT: Add funds to session from unified balance
  • WITHDRAW: Remove funds from session to unified balance

Related: App Sessions

L​

Ledger Entry​

Double-entry bookkeeping record of a debit or credit. Every financial operation in a clearnode creates two ledger entries to maintain accounting accuracy.

Fields:

  • account_id
  • asset
  • credit (incoming)
  • debit (outgoing)
  • created_at

Related: Transfers, Query Methods

Ledger Transaction​

User-facing transaction record showing transfers, deposits, withdrawals, and app session operations. Provides a simplified view of financial activity.

Types:

  • transfer - Direct transfer between users
  • deposit - Funds deposited to unified balance
  • withdrawal - Funds withdrawn from unified balance
  • app_deposit - Funds locked in app session
  • app_withdrawal - Funds released from app session

Related: Query Methods

M​

Magic Number​

Constant in state.data signaling special states. Magic numbers enable smart contracts to identify the type of state without complex parsing.

Values:

  • CHANOPEN = 7877 (0x1EC5) - Initial funding state
  • CHANCLOSE = 7879 (0x1EC7) - Final closing state

Related: Protocol Reference, Data Structures

N​

Nonce​

Unique number ensuring channel identifier uniqueness. Even with identical participants and configuration, different nonces create different channel IDs.

Typical Value: Timestamp in milliseconds

Related: Data Structures, Channel Creation

Nitro RPC​

The off-chain communication protocol for state channel operations. A lightweight, RPC-based RPC protocol with compact message format and signature-based authentication.

Versions:

  • NitroRPC/0.2: Legacy (basic state updates)
  • NitroRPC/0.4: Current (intent system)

Related: Off-Chain RPC Protocol, Message Format

Nitrolite​

The on-chain smart contract protocol for state channels. Defines the structure of channels, states, and the rules for creation, updates, and closure.

Version: 0.5.0 (Mainnet deployments live; not production yet)

Related: On-Chain Protocol, Protocol Reference

P​

Participant​

An entity (identified by a wallet address) that is part of a channel. Typically includes a Creator (user) and a Clearnode or Clearnode Operator.

In Payment Channels:

  • Index 0: Creator (user)
  • Index 1: Clearnode

Related: Data Structures, Protocol Reference

Q​

Quorum​

Minimum total weight of signatures required to approve app session state updates. The quorum defines the governance threshold for multi-party applications.

Example:

participants: [Alice, Bob, Judge]
weights: [40, 40, 50]
quorum: 80

// Valid signature combinations:
// - Alice + Bob (40 + 40 = 80) ✓
// - Alice + Judge (40 + 50 = 90) ✓
// - Bob + Judge (40 + 50 = 90) ✓
// - Alice alone (40 < 80) ✗

Related: App Sessions, Governance Examples

R​

requestId​

A unique identifier for an RPC request, used for correlating requests and responses. Generated by the client for each request.

Type: uint64

Related: Message Format

S​

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.

Features:

  • Spending limits (allowances)
  • Operation scope restrictions
  • Expiration time
  • Gasless signing (no wallet prompts)

Related: Authentication, Communication Flows

State​

A snapshot of the channel at a point in time, including fund allocations and application-specific data. States are signed by participants to authorize transitions.

Components:

  • intent - Purpose of the state (INITIALIZE, OPERATE, RESIZE, FINALIZE)
  • version - Incremental version number for comparison
  • data - Application-specific data or magic number
  • allocations - Fund distribution
  • sigs - Participant signatures

Related: Data Structures

packedState​

A specific encoding of a channelId, state.intent, state.version, state.data, state.allocations, used for signing and signature verification.

Computation:

packedState = abi.encode(
  channelId,
  state.intent,
  state.version,
  state.data,
  state.allocations
)

Related: Data Structures

U​

Unified Balance​

An abstraction that aggregates a user's funds across multiple blockchain networks, managed by a clearnode. The unified balance provides a single view of all assets regardless of which chain they're locked on.

Benefits:

  • Chain abstraction
  • Simplified fund management
  • Cross-chain transfers without bridges
  • Single balance for all operations

Related: Architecture, Transfers

W​

Weight​

Voting power assigned to a participant in an app session. Weights determine how much influence each participant has in governance decisions.

Usage: Sum of signer weights must meet quorum for state updates to be valid.

Related: App Sessions

Additional Terms​

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.

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 (e.g., "usdc", "eth", "weth", "usdt", "dai", "wbtc"). 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.

Cross-References​

For detailed explanations of these terms with examples, diagrams, and use cases, refer to:

Using This Glossary

Press Ctrl+F (or Cmd+F on Mac) to search for specific terms. Most terms also appear as tooltips throughout the documentation for quick reference.