Key Terms & Mental Models
Nitrolite uses one shared vocabulary across the SDK, protocol docs, and on-chain contracts. Learn these terms first and the rest of the docs become much easier to scan.
:::info Canonical source The protocol source of truth is Protocol Terminology. Use this page as the builder-facing quick reference for the SDK docs. :::
Core mental model
Nitrolite lets a user and Nitronode exchange signed channel states off-chain, then enforce the latest mutually signed state on-chain when needed. The user experience is fast because most updates are signatures, not blockchain transactions. The safety model still has an on-chain exit through ChannelHub.
Essential vocabulary
| Term | What it means | Builder cue |
|---|---|---|
| Channel | A state container shared by a user and Nitronode for one unified asset. | The thing your deposits, transfers, withdrawals, and checkpoints update. |
| Home Channel (for a specific Asset) | The default user-Nitronode channel whose home ledger for the Asset is enforced on its home chain. | Most apps start here. deposit(), transfer(), and checkpoint() act on the home channel for an asset. |
| Escrow Channel | A temporary cross-chain channel derived from a home channel for escrow operations. | You meet this when funds move between chains. |
| Channel State | The current agreed channel configuration: ledgers, version, and transition data. | SDK state operations return a state before you decide whether to checkpoint it. |
| Channel Definition | The immutable channel parameters: user, node, asset, nonce, challenge duration, and signature validators. | Fixed at channel creation. Do not model it as app-level mutable config. |
| Ledger | A record of asset allocations and net flows for a specific blockchain inside a channel state. | Ledger math must balance exactly. |
| Home Ledger | The ledger tied to the chain where the current channel state is enforced. | This is the authoritative ledger for checkpoint and challenge flows. |
| Non-Home Ledger | A secondary ledger for a blockchain other than the home chain. | Used by escrow and migration flows, not as a synonym for home channel. |
| (Node) Vault | Nitronode's per-chain pool of available funds used to cover required locking during transitions. | Cross-chain availability depends on node liquidity in the right vault. |
| Asset | A logical value unit, such as USDC, with a symbol and decimal precision independent of any one chain. | The SDK takes asset symbols like 'usdc', not token addresses, for high-level channel operations. |
| Token | The per-blockchain contract representation of an Asset. | Nitronode asset config maps an asset symbol to the token address used on each supported chain. |
| Decimal | An exact decimal amount represented with decimal.js. | Use new Decimal(5), not JavaScript floating-point numbers, for SDK amounts. |
| App Session | An application extension that commits channel funds into a multi-party off-chain session. | Games, matching, escrow, and other multi-party flows live here. |
| Quorum | The minimum weighted approval needed for an app session state update. | If weights are [40, 40, 50] and quorum is 80, two participants may be enough. |
| Session Key | A delegated signing key authorized by a participant's primary key for a scoped time window. | Useful for repeated app signatures without prompting the primary wallet every time. |
| Challenge | An on-chain dispute where a participant submits a signed state and opens the challenge window. | Lets an honest party enforce a newer valid state before timeout. |
| Checkpoint | The operation of submitting a signed state to the blockchain layer for enforcement. | client.checkpoint('usdc') settles the latest agreed state for that asset. |
| Nitronode | The v1 off-chain coordinator that serves RPC, co-signs valid states, tracks channels, and coordinates app sessions. | This is the node your SDK client connects to over WebSocket. |
| ChannelHub | The v1 on-chain entrypoint for channel create, deposit, withdraw, checkpoint, challenge, and close operations. | The SDK hides most contract calls, but this is the contract enforcing the state. |
| Migration | A transition that moves the home-chain channel of a specific Asset to another blockchain. | Treat it as protocol state enforcement configuration, not a package upgrade. |
| Transition | A typed operation explaining why the channel state changed. | Every state advancement carries one transition type. |
Channel lifecycle statuses
Channel.status uses these v1 values:
| Status | Meaning |
|---|---|
void | No channel exists yet. |
open | The channel is active. |
challenged | A challenge is active on-chain. |
closed | The channel has been finalized. |
Transition types
These are the v1 transition_type literals from docs/api.yaml:
| Literal | Meaning |
|---|---|
transfer_receive | Receive side of an off-chain transfer. |
transfer_send | Send side of an off-chain transfer. |
release | Return funds from an extension back to the channel. |
commit | Move funds from the channel into an extension. |
home_deposit | Add funds to the home channel. |
home_withdrawal | Remove funds from the home channel. |
mutual_lock | Lock funds through mutual agreement. |
escrow_deposit | Start or advance cross-chain escrow deposit flow. |
escrow_lock | Lock escrow funds while a cross-chain flow is pending. |
escrow_withdraw | Withdraw through an escrow flow. |
migrate | Move the channel home-chain relationship. |
finalize | Finalize and close the channel state. |
Mental models that prevent bugs
States first, settlement second
High-level SDK calls such as deposit(), withdraw(), and transfer() prepare signed state updates. checkpoint() is the separate step that submits a state on-chain.
Amounts are decimals, ledgers are exact
The builder-facing SDK uses Decimal values. The protocol then preserves exact ledger accounting using the asset's configured precision. This avoids rounding bugs when the same logical asset exists on multiple chains.
App sessions spend committed channel funds
An app session does not replace a channel. It is an extension that receives funds through commit transitions and returns funds through release transitions.
Challenges are the escape hatch
If cooperation fails, a participant can use a challenge to force the latest valid state into the on-chain flow. The challenge window gives the counterparty time to respond with a newer valid state.
v0.5.x -> v1 term map
| v0.5.x term | v1 term to use now |
|---|---|
| Clearnode | Nitronode |
| VirtualApp | App Session, or the specific SDK/client API you are using |
| Custody Contract | ChannelHub |
| Adjudicator | ChannelHub validators and engine logic |
| NitroRPC/0.4 | v1 RPC |