From 376566117a8891fd8bccbd90a9ad470760b17ce0 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Tue, 19 May 2026 11:07:46 +0530 Subject: [PATCH 1/5] docs(nitrolite): YNU-864 reconcile learn and protocol --- .../core-concepts/challenge-response.mdx | 158 ++--- .../core-concepts/state-channels-vs-l1-l2.mdx | 133 ++--- docs/nitrolite/learn/glossary.mdx | 76 +++ docs/nitrolite/learn/index.mdx | 10 +- .../introduction/architecture-at-a-glance.mdx | 2 +- docs/nitrolite/learn/migrating-from-0.5.3.mdx | 65 +++ .../protocol-flows/app-session-deposit.mdx | 33 +- .../learn/protocol-flows/escrow-deposit.mdx | 544 +----------------- .../protocol-flows/escrow-withdrawal.mdx | 519 +---------------- .../protocol-flows/home-channel-creation.mdx | 21 +- .../protocol-flows/home-channel-deposit.mdx | 21 +- .../home-channel-withdraw-on-create.mdx | 12 +- .../home-channel-withdrawal.mdx | 21 +- .../learn/protocol-flows/transfer-flow.mdx | 30 +- .../protocol/cross-chain-and-assets.mdx | 41 +- .../protocol/enforcement-and-settlement.mdx | 23 +- docs/nitrolite/protocol/interaction-model.mdx | 6 +- .../protocol/security-and-limitations.mdx | 8 +- .../protocol/state-and-ledger-model.mdx | 28 +- docs/nitrolite/protocol/terminology.mdx | 2 +- sidebars-nitrolite.ts | 2 + 21 files changed, 435 insertions(+), 1320 deletions(-) create mode 100644 docs/nitrolite/learn/glossary.mdx create mode 100644 docs/nitrolite/learn/migrating-from-0.5.3.mdx diff --git a/docs/nitrolite/learn/core-concepts/challenge-response.mdx b/docs/nitrolite/learn/core-concepts/challenge-response.mdx index b227c6b..7e1c2de 100644 --- a/docs/nitrolite/learn/core-concepts/challenge-response.mdx +++ b/docs/nitrolite/learn/core-concepts/challenge-response.mdx @@ -1,155 +1,119 @@ --- sidebar_position: 4 title: Challenge-Response & Disputes -description: How Yellow Network handles disputes and ensures fund safety +description: How Yellow Network handles disputes and keeps channel funds recoverable keywords: [challenge, dispute, security, settlement, fund recovery] --- import Tooltip from '@site/src/components/Tooltip'; import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions'; -:::warning[Work in Progress] -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. -::: - # Challenge-Response & Disputes -In this guide, you will learn how Yellow Network resolves disputes and ensures your funds are always recoverable. +Challenge-response is the on-chain fallback that lets a participant enforce the latest valid channel state if the counterparty stops cooperating. -**Goal**: Understand the security guarantees that make off-chain transactions safe. +**Goal**: understand why off-chain updates remain recoverable even when Nitronode is unavailable. --- ## Why Challenge-Response Matters -In any off-chain system, a critical question arises: **What if someone tries to cheat?** +In any off-chain system, a critical question arises: what if someone tries to settle an old state? -State channels solve this with a challenge-response mechanism: +State channels answer this with versioned, signed states: -1. Anyone can submit a state to the blockchain -2. Counterparties have time to respond with a newer state -3. The newest valid state always wins -4. Funds are distributed according to that state - ---- +1. A participant submits a signed state on-chain. +2. The counterparty has a challenge window to respond with a newer valid state. +3. The newest valid state wins. +4. Funds are released according to the final accepted state. -## The Trust Model +## Trust Model -State channels are **trustless** because: - -| Guarantee | How It's Achieved | -|-----------|-------------------| -| **Fund custody** | Smart contract holds funds, not Clearnode | -| **State validity** | Only signed states are accepted | -| **Dispute resolution** | On-chain fallback if disagreement | -| **Recovery** | You can always get your funds back | - ---- +| Guarantee | How it is achieved | +| --- | --- | +| **Fund custody** | ChannelHub holds channel funds on-chain, not Nitronode. | +| **State validity** | Only valid signed states can advance the channel. | +| **Dispute resolution** | A participant can force the latest valid state on-chain. | +| **Recovery** | Funds are recoverable from the latest enforceable state. | -## Channel Dispute Flow +## Channel Challenge Flow -### Scenario: Clearnode Becomes Unresponsive +### Scenario: Nitronode becomes unresponsive -You have a channel with 100 USDC. The Clearnode stops responding. +You have a channel with 100 USDC. Nitronode stops responding. -**Your options:** +Your options: -1. Wait for Clearnode to recover -2. Force settlement on-chain via challenge +1. Wait for Nitronode to recover. +2. Submit the latest mutually signed state on-chain and start the challenge path. -### The Process +### Process -1. **Initiate Challenge**: Submit your latest signed state to the blockchain -2. **Challenge Period**: Contract sets a timer (e.g., 24 hours) -3. **Response Window**: Counterparty can submit a newer state -4. **Resolution**: After timeout, challenged state becomes final +1. **Initiate challenge**: submit the latest signed state to ChannelHub. +2. **Challenge period**: ChannelHub sets the response deadline. +3. **Response window**: a counterparty can submit a newer valid state. +4. **Resolution**: after timeout, the latest accepted state can be closed. ```mermaid stateDiagram-v2 - [*] --> ACTIVE - ACTIVE --> DISPUTE: challenge() - DISPUTE --> ACTIVE: checkpoint() with newer state - DISPUTE --> FINAL: Timeout expires - FINAL --> [*] - - note right of DISPUTE: Anyone can submit
newer valid state -``` + [*] --> open + open --> challenged: challenge + challenged --> open: checkpoint newer state + challenged --> closed: close after timeout + closed --> [*] ---- + note right of challenged: A newer valid state
can defeat the challenge +``` ## Why This Works -### States Are Ordered +### States are ordered -Every state has a version number. A newer (higher version) state always supersedes older states. +Every channel state has a version number. A higher version supersedes a lower version when both states are valid. -### States Are Signed +### States are signed -With the default SimpleConsensus adjudicator, both parties must sign every state. If someone signed a state, they can't later claim they didn't agree. +The default v1 channel path requires both user and node signatures for enforceable states. A party that signed a state cannot later deny that signature. -:::note Other Adjudicators -Different adjudicators may have different signing requirements. For example, a Remittance adjudicator may only require the sender's signature. The signing rules are defined by the channel's adjudicator contract. -::: - -### Challenge Period Provides Fairness +### Challenge period provides fairness -The waiting window ensures honest parties have time to respond. Network delays don't cause losses. +The waiting window gives honest parties time to respond. Network delays should not cause immediate loss of funds. -### On-Chain Contract is Neutral +### ChannelHub is neutral -The smart contract accepts any valid signed state, picks the highest version, and distributes funds exactly as specified. - ---- - -## Challenge Period Selection - -| Duration | Trade-offs | -|----------|------------| -| **1 hour** | Fast resolution, tight response window | -| **24 hours** | Balanced (recommended) | -| **7 days** | Maximum safety, slow settlement | - -The Custody Contract enforces a minimum of 1 hour. - ---- +ChannelHub validates signatures, state version, status, and ledger invariants. It does not rely on Nitronode cooperation once a valid state is submitted. ## Checkpoint vs Challenge -| Operation | Purpose | Channel Status | -|-----------|---------|----------------| -| `checkpoint()` | Record state without dispute | Stays ACTIVE | -| `challenge()` | Force dispute resolution | Changes to DISPUTE | +| Operation | Purpose | Channel status | +| --- | --- | --- | +| `checkpoint()` | Record a valid state without forcing closure. | Stays `open`. | +| `challenge()` | Start the on-chain dispute path. | Changes to `challenged`. | -Use checkpoint for safety snapshots. Use challenge when you need to force settlement. - ---- +Use checkpoint for safety snapshots. Use challenge when you need to force settlement because a counterparty is not cooperating. ## What Happens If... | Scenario | Outcome | -|----------|---------| -| **Clearnode goes offline** | Challenge with latest state, withdraw after timeout | -| **You lose state history** | Challenge with old state; counterparty submits newer if they have it | -| **Counterparty submits wrong state** | Submit your newer state via checkpoint | -| **Block reorg occurs** | Replay events from last confirmed block | - ---- +| --- | --- | +| **Nitronode goes offline** | Challenge with the latest signed state, then close after timeout. | +| **You lose state history** | An older state can be defeated by a newer valid state if the counterparty has it. | +| **Counterparty submits a stale state** | Submit a newer valid state during the challenge window. | +| **Block reorg occurs** | Replay confirmed chain state from the last trusted block. | ## Key Takeaways | Concept | Remember | -|---------|----------| -| **Challenge** | Force on-chain dispute resolution | -| **Response** | Submit newer state to defeat challenge | -| **Timeout** | After period, challenged state becomes final | -| **Checkpoint** | Record state without dispute | - -:::success Security Guarantee -You can **always** recover your funds according to the latest mutually signed state, regardless of counterparty behavior. +| --- | --- | +| **Challenge** | Starts on-chain dispute resolution. | +| **Response** | A newer valid state defeats an older challenged state. | +| **Timeout** | After expiry, the accepted state can be closed. | +| **Checkpoint** | Records state without starting the close path. | + +:::success Security guarantee +You can recover funds according to the latest enforceable state even if the off-chain counterparty stops cooperating. ::: ---- - ## Deep Dive -For protocol details, see the [App Layer](/nitrolite/protocol/introduction) section. +For protocol details, see [Enforcement and Settlement](/nitrolite/protocol/enforcement-and-settlement). diff --git a/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx b/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx index 466045b..902e158 100644 --- a/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx +++ b/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx @@ -2,142 +2,113 @@ sidebar_position: 1 title: State Channels vs L1/L2 description: Compare state channels with Layer 1 and Layer 2 scaling solutions -keywords: [state channels, L1, L2, scaling, comparison, rollups, VirtualApp] +keywords: [state channels, L1, L2, scaling, comparison, rollups] --- import Tooltip from '@site/src/components/Tooltip'; import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions'; -:::warning[Work in Progress] -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. -::: - # State Channels vs L1/L2 -In this guide, you will learn how state channels compare to Layer 1 and Layer 2 solutions, and when each approach is the right choice. +State channels are a scaling pattern for repeated interactions between known parties. Yellow Network uses channels, Nitronode coordination, and ChannelHub enforcement to make high-frequency asset movement fast while preserving an on-chain fallback. -**Goal**: Understand where state channels fit in the blockchain scaling landscape. +**Goal**: understand where state channels fit beside Layer 1 chains and Layer 2 rollups. --- ## Solution Comparison -| Solution | Throughput | Latency | Cost per Op | Best For | -|----------|------------|---------|-------------|----------| -| **Layer 1** | 15-65K TPS | 1-15 sec | $0.001-$50 | Settlement, contracts | -| **Layer 2** | 2,000-4,000 TPS | 1-10 sec | $0.01-$0.50 | General dApps | -| **State Channels** | **Unlimited*** | **< 1 sec** | **$0** | High-frequency, known parties | - -*\*Theoretically unlimited—no consensus bottleneck. Real-world throughput depends on signature generation, network latency, and application logic. Benchmarking documentation coming soon.* - ---- +| Solution | Throughput | Latency | Cost per operation | Best for | +| --- | --- | --- | --- | --- | +| **Layer 1** | Chain-limited | Block time | Native gas cost | Settlement, contracts, global ordering | +| **Layer 2** | Rollup or sequencer-limited | Sequencer plus settlement latency | L2 fees | General applications with many unknown users | +| **State channels** | Limited by signing, networking, and app logic | Sub-second off-chain path | No gas for ordinary off-chain updates | Repeated interactions between identified parties | ## How State Channels Work -State channels operate on a simple principle: - -1. **Lock funds** in a smart contract (on-chain) -2. **Exchange signed states** directly between participants (off-chain) -3. **Settle** when done or if there's a dispute (on-chain) +State channels operate on a simple pattern: -The key insight: most interactions between parties don't need immediate on-chain settlement. +1. **Lock funds** in ChannelHub on-chain. +2. **Exchange signed states** off-chain. +3. **Checkpoint, challenge, or close** on-chain when needed. ---- +Most interactions do not need immediate on-chain settlement. The chain is used for funding, checkpoints, disputes, and exits. ## State Channel Advantages -### Instant Finality +### Low-latency updates -Unlike L2 solutions that still have block times, state channels provide sub-second finality: +| Solution | Transaction flow | +| --- | --- | +| L1 | Transaction -> mempool -> block -> confirmation | +| L2 | Transaction -> sequencer -> L2 block -> L1 data path | +| Channels | Signature -> validation -> accepted state | -| Solution | Transaction Flow | -|----------|------------------| -| L1 | Transaction → Mempool → Block → Confirmation | -| L2 | Transaction → Sequencer → L2 Block → L1 Data | -| Channels | Signature → Validation → Done | +### No gas for ordinary off-chain operations -### Zero Operational Cost +Once the channel is funded, transfers and app-session updates are signed off-chain. Gas is paid only for on-chain funding, checkpointing, disputes, and exits. -| Operation | L1 Cost | L2 Cost | State Channel | -|-----------|---------|---------|---------------| -| 100 transfers | $500-5000 | $10-50 | **$0** | -| 1000 transfers | $5000-50000 | $100-500 | **$0** | +### Enforceable settlement -### Privacy - -Off-chain transactions are only visible to participants. Only opening and final states appear on-chain. - ---- +If cooperation fails, the latest enforceable state can be submitted to ChannelHub. The on-chain path validates signatures, versions, and ledger invariants. ## State Channel Limitations -### Known Participants +### Identified counterparties -Channels work between specific participants. Yellow Network addresses this through Clearnodes—off-chain service providers that coordinate channels and provide a unified balance across multiple users and chains. +Channels work between defined participants. Yellow Network uses Nitronode as an off-chain coordinator so applications can work with channel balances without each app directly managing every counterparty path. -### Liquidity Requirements +### Liquidity requirements -Funds must be locked upfront. You can't spend more than what's locked in the channel. +Funds must be locked before they can be spent. A user cannot spend more than the balance available in the relevant channel or app session. -### Liveness Requirements +### Liveness requirements -Participants must respond to challenges within the challenge period. Users should ensure they can monitor for challenges or use services that provide this functionality. +Participants need a way to monitor and respond during challenge periods. Users can enforce the latest signed state, but they must retain state data and react before a challenge expires. ---- +### Cross-chain trust + +Cross-chain behavior currently relies on Nitronode liquidity and relay behavior. Trustless cross-chain enforcement is not the default public builder path yet. ## When to Use Each | Choose | When | -|--------|------| -| **L1** | Deploying contracts, one-time large transfers, final settlement | -| **L2** | General dApps, many unknown users, complex smart contracts | -| **State Channels** | Known parties, real-time speed, high frequency, zero gas needed | - ---- +| --- | --- | +| **L1** | You need global settlement, contract deployment, or one-time high-value operations. | +| **L2** | You need general smart-contract execution for many unknown users. | +| **State channels** | You need fast repeated interactions between identified parties with an on-chain fallback. | ## Decision Framework ```mermaid flowchart TD - A[Transaction] --> B{Known counterparty?} - B -->|No| C[Use L1/L2] - B -->|Yes| D{High frequency?} - D -->|Yes| E[Use State Channel] - D -->|No| F{Large value?} + A[Interaction] --> B{Known participants?} + B -->|No| C[Use L1 or L2] + B -->|Yes| D{Repeated updates?} + D -->|Yes| E[Use state channels] + D -->|No| F{Needs custom global contract logic?} F -->|Yes| C F -->|No| E - + style E fill:#9999ff,stroke:#333,color:#111 style C fill:#99ff99,stroke:#333,color:#111 ``` ---- - ## How Yellow Network Addresses Limitations -| Limitation | Solution | -|------------|----------| -| Known participants | Clearnode coordination layer | -| Liquidity | Unified balance across chains | -| Liveness | Always-on Clearnode monitoring | - ---- +| Limitation | Yellow Network approach | +| --- | --- | +| Identified counterparties | Nitronode coordinates off-chain channel state advancement. | +| Liquidity | Home-channel balances and app sessions keep app funds available off-chain. | +| Enforcement | ChannelHub provides checkpoint, challenge, and close paths. | +| Developer ergonomics | SDKs build signed requests and typed app-session updates. | ## Key Takeaways -State channels shine when you have identified participants who will interact frequently—like players in a game, counterparties in a trade, or parties in a payment relationship. - -:::success State Channel Sweet Spot -- Real-time interactions between known parties -- High transaction volumes -- Zero gas costs required -- Instant finality needed -::: - ---- +State channels work best for real-time applications where the same participants update state repeatedly. They are not a replacement for every L1 or L2 use case, but they are a strong fit for payments, trading, gaming, checkout, and app-session workflows that benefit from signed off-chain updates. ## Deep Dive -For technical details on channel implementation: - -- **[App Layer](/nitrolite/protocol/introduction)** — System design and fund flows +- [Protocol Overview](/nitrolite/protocol/introduction) +- [State and Ledger Model](/nitrolite/protocol/state-and-ledger-model) +- [Enforcement and Settlement](/nitrolite/protocol/enforcement-and-settlement) diff --git a/docs/nitrolite/learn/glossary.mdx b/docs/nitrolite/learn/glossary.mdx new file mode 100644 index 0000000..199b650 --- /dev/null +++ b/docs/nitrolite/learn/glossary.mdx @@ -0,0 +1,76 @@ +--- +title: Glossary +description: Core Nitrolite v1 terms for builders and protocol readers. +sidebar_position: 5 +--- + +# Glossary + +This page defines the terms used across the Nitrolite v1 Learn, Build, Protocol, and API Reference docs. + +## Core Terms + +| Term | Meaning | +| --- | --- | +| **App session** | An off-chain application-specific state funded from a channel through `commit` transitions and settled back through `release` transitions. | +| **Asset** | A configured token symbol and decimal model that Nitronode recognizes across supported chains. | +| **Channel** | A user-node relationship for one asset, with signed state updates and an on-chain enforcement path. | +| **Channel state** | The signed record of channel version, transition, ledgers, and participant signatures. | +| **ChannelHub** | The v1 on-chain entrypoint for channel creation, deposits, withdrawals, checkpoints, challenges, and close operations. | +| **Checkpoint** | An on-chain submission that records a valid signed state without necessarily closing the channel. | +| **Challenge** | An on-chain dispute path where a participant submits a signed state and gives the counterparty time to respond with a newer valid state. | +| **Home channel** | The user's primary channel for a configured asset. | +| **Home ledger** | The authoritative ledger for the channel's current enforcement chain. | +| **Nitronode** | The open-source off-chain coordinator that validates state transitions, signs states, and serves v1 RPC. | +| **Non-home ledger** | The secondary ledger used when a cross-chain operation is in progress. It is empty during ordinary same-chain operation. | +| **Pending state** | A Node-issued state with only the Node signature. It becomes enforceable only after the user acknowledges it. | +| **Quorum** | The signature threshold required by an app session before an app-state update is accepted. | +| **Session key** | A scoped signing key an application can use for app-session updates without asking the wallet to sign every step. | +| **Vault** | Node-controlled liquidity used by enforcement and cross-chain accounting paths. | + +## Channel Statuses + +The v1 RPC status surface uses: + +| Status | Meaning | +| --- | --- | +| `void` | No channel exists yet. | +| `open` | The channel exists and can accept normal state updates. | +| `challenged` | A challenge is active and the response window is running. | +| `closing` | The channel is in the close path after a final state or expired challenge. | +| `closed` | Funds have been released and the channel lifecycle is complete. | + +## Transition Literals + +These are the current `transition_type` literals from the v1 API schema. + +| Literal | Meaning | +| --- | --- | +| `transfer_send` | Sender-side off-chain transfer. | +| `transfer_receive` | Receiver-side off-chain transfer. | +| `release` | Return funds from an app session or extension to the channel. | +| `commit` | Move funds from the channel into an app session or extension. | +| `home_deposit` | Same-chain home-channel deposit. | +| `home_withdrawal` | Same-chain home-channel withdrawal. | +| `mutual_lock` | Escrow deposit initiate. | +| `escrow_deposit` | Escrow deposit finalize or complete. | +| `escrow_lock` | Escrow withdrawal initiate. | +| `escrow_withdraw` | Escrow withdrawal finalize or complete. | +| `migrate` | Home-chain migration initiate. | +| `finalize` | Finalize and close the channel state. | + +## Amount Units + +Use the SDK method signature as the source of truth for amount shape: + +| Surface | Typical amount shape | +| --- | --- | +| Native TypeScript SDK | `Decimal` for app-facing method calls. | +| Compat TypeScript SDK | Raw asset-unit strings for transfer-style methods and raw base units for on-chain-style methods. | +| API Reference | Wire payload shape from `docs/api.yaml`. | + +## Related Pages + +- [Architecture at a Glance](./introduction/architecture-at-a-glance) +- [State and Ledger Model](/nitrolite/protocol/state-and-ledger-model) +- [Key Terms](/nitrolite/build/getting-started/key-terms) diff --git a/docs/nitrolite/learn/index.mdx b/docs/nitrolite/learn/index.mdx index d5b3062..34ff5ad 100644 --- a/docs/nitrolite/learn/index.mdx +++ b/docs/nitrolite/learn/index.mdx @@ -15,7 +15,7 @@ Welcome to the Yellow Network learning path. This section builds your understand Yellow Network is decentralized clearing and settlement infrastructure that operates as a Layer 3 overlay on existing blockchains. It lets businesses, exchanges, and application developers move digital assets through signed channel states. Independent node operators run open-source Nitronode software supplied by Layer3 Fintech Ltd. The SDK and developer tools are open-source and free. :::info What changed in v1 -The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and app sessions. If you are coming from `@erc7824/nitrolite@0.5.3`, start with the [TypeScript compat migration path](/nitrolite/build/sdk/typescript-compat/overview). +The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and app sessions. If you are coming from `@erc7824/nitrolite@0.5.3`, start with [Migrating from 0.5.3](./migrating-from-0.5.3). ::: ## Introduction @@ -32,6 +32,8 @@ The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and ap **[YELLOW Token](./core-concepts/yellow-token.mdx)**: The utility token powering network services, node operator collateral, and dispute resolution. +**[Glossary](./glossary.mdx)**: Core v1 terms, statuses, transition literals, and amount-unit reminders. + ## Protocol Flows **[Protocol Architecture](./protocol-flows/architecture.mdx)**: The Petal Diagram: home chain, cross-chain, transfers, and app sessions. @@ -42,6 +44,10 @@ The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and ap **[App Session Deposit](./protocol-flows/app-session-deposit.mdx)**: Depositing funds into app sessions. +## Migration + +**[Migrating from 0.5.3](./migrating-from-0.5.3.mdx)**: Choose the compat-first or native v1 migration path from `@erc7824/nitrolite@0.5.3`. + ## Next Steps After completing the Learn section, continue to: @@ -61,5 +67,7 @@ After completing the Learn section, continue to: | [State Channels vs L1/L2](./core-concepts/state-channels-vs-l1-l2) | 12 min | Intermediate | | [Challenge-Response](./core-concepts/challenge-response) | 6 min | Intermediate | | [YELLOW Token](./core-concepts/yellow-token) | 8 min | Intermediate | +| [Glossary](./glossary) | 5 min | Beginner | +| [Migrating from 0.5.3](./migrating-from-0.5.3) | 10 min | Intermediate | | [Protocol Architecture](./protocol-flows/architecture) | 10 min | Intermediate | | [Transfer Flow](./protocol-flows/transfer-flow) | 12 min | Advanced | diff --git a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx index 7bfa222..a7c76b6 100644 --- a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx +++ b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx @@ -123,7 +123,7 @@ stateDiagram-v2 note right of OPEN: Normal operation happens here ``` -`CHALLENGED` means a participant has submitted a disputed state on-chain and the challenge duration is running. During that window, another participant may respond with a higher-version mutually signed state. If no higher-version response is accepted before expiry, a separate close call is still required before funds are released according to that enforced state. See [Channel Lifecycle](/nitrolite/protocol/channel-lifecycle) and [Enforcement and Settlement](/nitrolite/protocol/enforcement-and-settlement) for the formal rules. +`CHALLENGED` means a participant has submitted a candidate state on-chain and the challenge duration is running. During that window, another participant may respond with a higher-version mutually signed state. If no higher-version response is accepted before expiry, a separate close call is still required before funds are released according to that enforced state. See [Channel Lifecycle](/nitrolite/protocol/channel-lifecycle) and [Enforcement and Settlement](/nitrolite/protocol/enforcement-and-settlement) for the formal rules. ### Typical Flow diff --git a/docs/nitrolite/learn/migrating-from-0.5.3.mdx b/docs/nitrolite/learn/migrating-from-0.5.3.mdx new file mode 100644 index 0000000..9b6e3f4 --- /dev/null +++ b/docs/nitrolite/learn/migrating-from-0.5.3.mdx @@ -0,0 +1,65 @@ +--- +title: Migrating from 0.5.3 +description: Migration paths from @erc7824/nitrolite 0.5.3 to the Yellow v1 SDKs. +sidebar_position: 6 +--- + +# Migrating from 0.5.3 + +If your application uses `@erc7824/nitrolite@0.5.3`, choose one of two migration paths: + +| Path | Use when | +| --- | --- | +| **Compat first** | You need the smallest migration and want familiar helper shapes while moving to the v1 package family. | +| **Native v1** | You are building new flows or can afford to adopt the v1 SDK model directly. | + +## Path 1: Compat First + +Use `@yellow-org/sdk-compat` when you need to move existing 0.5.3 code with minimal application churn. + +Start here: + +- [Compat overview](/nitrolite/build/sdk/typescript-compat/overview) +- [Migration overview](/nitrolite/build/sdk/typescript-compat/migration-overview) +- [Off-chain migration](/nitrolite/build/sdk/typescript-compat/migration-offchain) +- [On-chain migration](/nitrolite/build/sdk/typescript-compat/migration-onchain) +- [Errors and recovery](/nitrolite/build/sdk/typescript-compat/errors) + +Compat does not preserve every old behavior. In particular, fail-fast calls, amount units, polling, and server-push assumptions need deliberate review. Follow the migration pages before changing production code. + +## Path 2: Native v1 + +Use `@yellow-org/sdk` for new applications and for migrations that can adopt the v1 lifecycle directly. + +Start here: + +- [Quickstart](/nitrolite/build/getting-started/quickstart) +- [Prerequisites](/nitrolite/build/getting-started/prerequisites) +- [Native TypeScript SDK](/nitrolite/build/sdk/typescript/getting-started) +- [Lifecycle example source](/nitrolite/build/getting-started/quickstart#step-7-run-it) + +Native v1 is the default long-term path. It exposes the current channel and app-session lifecycle directly instead of preserving the 0.5.3 helper vocabulary. + +## Terminology Map + +| 0.5.3 term | v1 term | +| --- | --- | +| `@erc7824/nitrolite` | `@yellow-org/sdk` or `@yellow-org/sdk-compat` | +| Clearnode | Nitronode | +| Custody | ChannelHub | +| Adjudicator | Channel engine and signature validators | +| Virtual app | App session | + +## Migration Checklist + +1. Pick compat-first or native v1. +2. Replace package imports. +3. Review amount units for every transfer, deposit, withdrawal, and app-session call. +4. Replace server-push assumptions with explicit queries or the supported polling helper. +5. Run the updated flow against a disposable test wallet before updating docs or production examples. + +## Related Pages + +- [Glossary](./glossary) +- [API Reference](/nitrolite/api-reference/) +- [Protocol Overview](/nitrolite/protocol/introduction) diff --git a/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx b/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx index c74e615..9f99416 100644 --- a/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx @@ -15,7 +15,7 @@ This document provides a comprehensive breakdown of the **App Session Deposit** ```mermaid graph LR U["User"] --> SC["SenderClient"] - SC <--> N["Node (Clearnode)"] + SC <--> N["Nitronode"] style U stroke:#333 style SC stroke:#333 @@ -26,7 +26,7 @@ graph LR | --- | --- | | **User** | The human user initiating the deposit | | **SenderClient** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates and coordinates both app session and channel states | +| **Node** | The Nitronode that validates and coordinates both app session and channel states | --- @@ -39,6 +39,10 @@ Before the deposit flow begins: 3. An **App Session** already exists (created via `create_app_session`). 4. User is a **participant** in the target App Session. +:::info Application signature collection +The application is responsible for collecting the app-session quorum signatures before it submits an app-state update. Nitronode validates the quorum, but it does not gather participant signatures for the app. +::: + --- ## Key Data Structures @@ -213,7 +217,7 @@ From the on-chain protocol: --- -## Phase 5: Notifications and Completion +## Phase 5: Confirmation and Completion ```mermaid sequenceDiagram @@ -221,16 +225,17 @@ sequenceDiagram actor SenderClient actor User - Node->>SenderClient: Sends AppSessionUpdate Node->>SenderClient: Return node signature - SenderClient->>User: Returns success and tx hash + SenderClient->>Node: Query latest app session if needed + Node->>SenderClient: Returns latest app session state + SenderClient->>User: Returns success ``` ### What Gets Returned -1. **AppSessionUpdate** -- Notification of the updated app session state. -2. **Node signature** -- Confirms the Node has accepted both states. -3. **Success and tx hash** -- User-facing confirmation. +1. **Node signature** -- Confirms Nitronode has accepted both states. +2. **Latest app session state** -- Retrieved by query if the application wants a fresh read after submission. +3. **Success** -- User-facing confirmation. --- @@ -269,8 +274,10 @@ sequenceDiagram rect rgb(0, 0, 230) Note over Node,User: Phase 5: Complete - Node->>SenderClient: AppSessionUpdate + node signature - SenderClient->>User: Returns success and tx hash + Node->>SenderClient: Return node signature + SenderClient->>Node: Query latest app session if needed + Node->>SenderClient: Returns latest app session state + SenderClient->>User: Returns success end ``` @@ -302,12 +309,6 @@ This is solved by: 2. **Verifiable accounting** -- Channel state tracks fund flows, app session tracks allocations. 3. **Linked validation** -- `EnsureSameDepositAssetAmount` validates that both states reflect the same deposit amount before either is stored. -:::info Note on Quorum -The `quorum_sigs` parameter must be assembled by the **application itself**. This means the application is responsible for collecting signatures from each participant (based on their signature weights) to meet the quorum threshold before submitting the deposit state to the Node. -::: - ---- - ## Related Flows - [Transfer Communication Flow](./transfer-flow) diff --git a/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx b/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx index a4b8f8c..8b82f6f 100644 --- a/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx @@ -1,542 +1,48 @@ --- title: "Escrow Channel Deposit Flow" -description: "A comprehensive breakdown of the Escrow Channel Deposit flow for cross-chain deposits via short-lived escrow channels in the Nitrolite v1.0 protocol." +description: "Current documentation status for non-home-chain escrow deposits in Nitrolite v1." sidebar_position: 8 --- # Escrow Channel Deposit Flow -This document provides a comprehensive breakdown of the **Escrow Channel Deposit** flow as defined in the Nitrolite v1.0 protocol. This operation allows a user to deposit funds from a **Non-Home Chain** (a blockchain different from where their home channel exists) into their unified balance through a **short-lived Escrow Channel**. +Escrow deposits are the protocol path for bringing funds from a non-home chain into a user's home-channel balance. The mechanism can be supported by Nitrolite, but docs.yellow.org does not yet document escrow deposits as a builder-facing workflow. -This is a **cross-chain bridging operation** that uses a two-phase approach (Preparation + Execution) to move liquidity across blockchains without requiring atomic cross-chain verification. - -:::caution Cross-Chain Status -Cross-chain functionality is not yet fully implemented. While channels can be created on any chain with a Nitro deployment, cross-chain operations like escrow deposit and withdrawal are planned for shortly after launch. +:::caution Not documented as an app workflow yet +Escrow operation mechanics are intentionally deferred until the Nitronode automation and product surface are ready for public builder docs. Use the home-channel deposit and app-session lifecycle docs for the current v1 builder path. ::: ---- - -## Actors in the Flow - -```mermaid -graph LR - U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] - N <--> HC["HomeChain"] - N <--> EC["EscrowChain"] - - style U stroke:#333 - style C stroke:#333 - style N stroke:#333 - style HC stroke:#4CAF50 - style EC stroke:#FF9800 -``` - -| Actor | Role | -| --- | --- | -| **User** | The human user initiating the cross-chain deposit | -| **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates, coordinates, and bridges state transitions | -| **HomeChain** | The blockchain where the user's home channel exists | -| **EscrowChain** | The non-home blockchain where the user is depositing funds from | - ---- - -## Prerequisites - -Before the escrow deposit flow begins: - -1. **User already has a home channel** on the HomeChain. -2. **Node** contains the user's state with Home Channel information. -3. **Client** is connected to the Node via WebSocket. - -This flow handles the "Another Chain" petal from the Nitrolite architecture diagram. When a user wants to deposit from a chain that is NOT their home chain, they cannot directly deposit -- instead, they use an escrow mechanism. - ---- - -## Key Concepts - -### What is an Escrow Entity? - -An **Escrow Entity** is a short-lived channel created on a non-home chain specifically for cross-chain deposits. It acts as a bridge (note: "entity" is used instead of "channel" to avoid confusion with the channel concept and lifecycle): - -- User locks funds on the **Escrow Chain** (non-home). -- Node provides equivalent liquidity on the **Home Chain**. -- **Happy case**: The escrow is finalized once User and Node sign the execution phase state and submit it on-chain. -- **Unhappy case**: Either party challenges the escrow if the opposite party decides not to continue cooperating. After challenge, escrow funds are distributed back. - -### Two-Phase Cross-Chain Operations - -Since one chain cannot directly observe or verify another chain's state, cross-chain actions are **two-phase** and **optimistic**: - -| Phase | Purpose | -| --- | --- | -| **Preparation Phase** | Lock liquidity on both chains, create escrow object | -| **Execution Phase** | Update allocations and net flows, finalize the operation | - -### Transition Types Used - -| Transition | Description | -| --- | --- | -| `mutual_lock` | Initial lock of funds preparing for cross-chain movement | -| `escrow_deposit` | Finalizes the escrow deposit, updating allocations | - ---- - -## Phase 1: Deposit Initiation - -```mermaid -sequenceDiagram - actor User - actor Client - - User->>Client: async deposit(blockchainId, asset, amount) - Note over Client: User initiates cross-chain deposit -``` - -The **User** calls the `deposit` function on the **Client** SDK with three parameters: - -| Parameter | Description | Example | -| --- | --- | --- | -| `blockchainId` | The blockchain ID where funds are coming FROM (non-home chain) | `59144` (Linea) | -| `asset` | The asset symbol to deposit | `usdc` | -| `amount` | The amount to deposit | `100.0` | - ---- - -## Phase 2: Fetching Current State - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: GetLastState(UserWallet, asset) - Note right of Node: GetLastState(userWallet, asset) - Node->>Client: Returns state -``` - -1. **Client** requests the **latest state** from the Node. -2. The Node looks up the state using `UserWallet` and `asset`. -3. The Node returns the current **state** object containing the **Home Channel** information. - ---- - -## Phase 3: Building the Preparation State (Mutual Lock) - -```mermaid -sequenceDiagram - actor Client - - Note over Client: createNextState(currentState) returns state - Note over Client: state.setID(CalculateStateID(state.userWallet,
state.asset, state.cycleId, state.version)) - Note over Client: GetTokenAddress(blockchainId, asset) - Note over Client: state.setEscrowToken(blockchainId, tokenAddress) - Note over Client: GetEscrowChannelID(homeChannelDef, state.version) - Note over Client: NewTransition(mutualLockT, state.ID(),
homeChannelID, amount) - Note over Client: state.applyTransitions(transitions) returns true - Note over Client: signState(state) returns userSig -``` - -### 3.1 Create Next State - -``` -createNextState(currentState) -> state -``` - -The Client creates a new state object based on the current state with an incremented version. - -### 3.2 Calculate State ID - -``` -state.setID(CalculateStateID(state.userWallet, state.asset, state.cycleId, state.version)) -``` - -The **State ID** is a deterministic hash computed from user wallet, asset, cycle, and version. +## What is stable -### 3.3 Get Token Address for Escrow Chain +The conceptual model is still useful when reading protocol material: -``` -GetTokenAddress(blockchainId, asset) -> tokenAddress -``` +- A user has one home chain for a given asset. +- A non-home-chain deposit needs a temporary escrow path because one chain cannot directly verify another chain's latest channel state. +- Nitronode coordinates signed off-chain state updates and on-chain settlement paths. +- The home ledger remains the user's canonical app balance for that asset. -The Client resolves the token contract address for the specified asset on the escrow (non-home) chain. +## Transition names -### 3.4 Set Escrow Token +The current schema names the two escrow-deposit transitions as: -``` -state.setEscrowToken(blockchainId, tokenAddress) -``` - -The state is updated to include the escrow chain's token information in the `escrow_ledger`. - -### 3.5 Get Escrow Channel ID - -``` -GetEscrowChannelID(homeChannelDef, state.version) -> escrowChannelID -``` - -A deterministic escrow channel ID is computed based on the home channel definition and current version. - -### 3.6 Create Mutual Lock Transition - -``` -NewTransition(mutual_lock, state.ID(), homeChannelID, amount) -``` - -The **mutual_lock** transition prepares funds for cross-chain movement: - -| Field | Value | +| Transition | Meaning | | --- | --- | -| `type` | `mutual_lock` | -| `tx_hash` | State ID reference | -| `account_id` | Home Channel ID | -| `amount` | Amount to lock | - -### 3.7 Apply and Sign - -``` -state.applyTransitions(transitions) -> true -signState(state) -> userSig -``` - -The transition is applied to the state and the user signs it. - ---- - -## Phase 4: Node Validates and Stores Escrow Channel - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: SubmitState(state, userSig) - Note right of Node: GetLastState(userWallet, asset) returns currentState - Note right of Node: EnsureNoOngoingTransitions() - Note right of Node: ValidateStateTransition(currentState, state) - Note right of Node: StoreEscrowChannel(escrow_channel) - Note right of Node: StoreState(state) - Node->>Client: Return node signature -``` - -### Node Validation Steps - -| Step | Operation | Purpose | -| --- | --- | --- | -| 1 | `GetLastState(...)` | Fetch current user state | -| 2 | `EnsureNoOngoingTransitions()` | Block other operations during escrow | -| 3 | `ValidateStateTransition(...)` | Verify version, signatures, balances | -| 4 | `StoreEscrowChannel(...)` | Create escrow channel record | -| 5 | `StoreState(state)` | Persist the new state | - -:::warning Atomic Operations -Once an escrow deposit starts with `mutual_lock`, **the Node stops issuing new states** until `escrow_deposit` finalizes. This ensures atomicity of cross-chain operations. -::: - ---- - -## Phase 5: On-Chain Escrow Initiation - -```mermaid -sequenceDiagram - actor Client - actor EscrowChain - actor Node - - Note over Client: PackChannelDefinition(channelDef) - Note over Client: PackState(channelId, state) - Client->>EscrowChain: initiateEscrowDeposit(packedChannelDef, packedState) - EscrowChain->>Client: Return Tx Hash - EscrowChain-->>Node: Emits EscrowDepositInitiated Event - Note right of Node: HandleEscrowDepositInitiated() - Note right of Node: UpdateEscrowChannel(escrow_channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate -``` - -### 5.1 Pack Channel Definition and State - -``` -PackChannelDefinition(channelDef) -> packedChannelDef -PackState(channelId, state) -> packedState -``` - -The Client serializes the channel definition and state for on-chain submission. - -### 5.2 On-Chain Transaction - -``` -initiateEscrowDeposit(packedChannelDef, packedState) -``` +| `mutual_lock` | Escrow deposit initiate. The parties prepare the locked state needed for the cross-chain deposit path. | +| `escrow_deposit` | Escrow deposit finalize. The deposit is completed into the home-ledger accounting model. | -The Client submits a transaction to the **EscrowChain** smart contract, which: +These names are included so readers can recognize them in protocol and API reference material. They are not instructions to assemble escrow deposit states by hand. -- Locks the user's funds on the escrow chain -- Creates an escrow object with a timeout -- Emits `EscrowDepositInitiated` event +## Current builder guidance -### 5.3 Node Event Handling +For applications today: -The Node listens for blockchain events and: +- Use home-channel deposit for same-chain funding. +- Use app-session deposit to move available home-channel funds into an app session. +- Treat escrow deposit automation as a future product path until the public Nitronode workflow is documented. -1. **HandleEscrowDepositInitiated** -- Processes the event. -2. **UpdateEscrowChannel** -- Updates the escrow channel status. -3. Sends **ChannelUpdate** and **BalanceUpdate** notifications to the Client. +## Related pages ---- - -## Phase 6: Home Chain Escrow Initiation - -```mermaid -sequenceDiagram - actor Node - actor HomeChain - actor Client - - Node->>HomeChain: initiateEscrowDeposit(homeChannelId, packedState) - HomeChain-->>Node: Emits EscrowDepositInitiatedOnHome Event - Node-->>Node: HandleEscrowDepositInitiatedOnHome() - Node-->>Client: Sends ChannelUpdate and BalanceUpdate -``` - -The **Node** initiates escrow deposit on the **Home Chain**: - -1. Submits `initiateEscrowDeposit(homeChannelId, packedState)` to Home Chain contract. -2. Home Chain emits `EscrowDepositInitiatedOnHome` event. -3. Node handles the event internally. -4. Sends updated notifications to Client. - -The initiation on the home chain ensures that the Node's liquidity commitment is recorded on-chain, providing security guarantees for the cross-chain operation. - ---- - -## Phase 7: Building the Execution State (Escrow Deposit) - -This phase starts when the Client sees the `EscrowDepositInitiatedOnHome` event on the Home Chain. - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: GetLastState(UserWallet, asset) - Note right of Node: GetLastState(userWallet, asset) - Node->>Client: Returns state - Note over Client: createNextState(currentState) returns state - Note over Client: state.setID(CalculateStateID(state.userWallet,
state.asset, state.cycleId, state.version)) - Note over Client: NewTransition(escrow_depositT, state.ID(),
homeChannelID, amount) - Note over Client: state.applyTransitions(transitions) returns true - Note over Client: signState(state) returns userSig -``` - -### 7.1 Fetch Updated State - -The Client fetches the latest state which now reflects the escrowed funds. - -### 7.2 Create Escrow Deposit Transition - -``` -NewTransition(escrow_deposit, state.ID(), homeChannelID, amount) -``` - -The **escrow_deposit** transition finalizes the cross-chain deposit: - -| Field | Value | -| --- | --- | -| `type` | `escrow_deposit` | -| `tx_hash` | State ID reference | -| `account_id` | Home Channel ID | -| `amount` | Deposited amount | - ---- - -## Phase 8: Submitting Execution State - -```mermaid -sequenceDiagram - actor Client - actor Node - actor User - - Client->>Node: SubmitState(state, userSig) - Note right of Node: GetLastState(userWallet, asset) returns currentState - Note right of Node: EnsureNoOngoingTransitions() - Note right of Node: ValidateStateTransition(currentState, state) - Note right of Node: StoreState(state) - Node->>Client: Return node signature - - Client-->>User: Returns success -``` - -1. Client submits the execution state with `escrow_deposit` transition. -2. Node validates and stores the state. -3. Client returns success to the User. - -At this point, the user's unified balance is updated to reflect the deposited funds. The escrow mechanism has effectively "bridged" the funds from the non-home chain. - ---- - -## Phase 9: Escrow Finalization (Automatic or Fast Unlock) - -```mermaid -sequenceDiagram - actor Node - actor EscrowChain - actor Client - - Note over Node: PackState(channelId, state) - Node->>EscrowChain: finalizeEscrowDeposit(escrowChannelId, packedState) - EscrowChain->>Node: Return Tx Hash - EscrowChain-->>Node: Emits EscrowDepositFinalized Event - Note right of Node: HandleEscrowDepositFinalized() - Note right of Node: UpdateEscrowChannel(escrow_channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate -``` - -### Two Unlock Options - -These are **Node funds** that require an unlock: - -| Option | Description | -| --- | --- | -| **Automatic Release** | Escrowed funds are released after the lock period expires | -| **Fast Unlock** | Node calls `FinalizeEscrowDeposit` on escrow chain to release funds immediately | - -:::warning -"Automatic" unlock means the funds **will be released eventually after the `unlockAt` timestamp is reached**, not exactly when the timestamp is reached. Each on-chain action checks whether Node's funds can be unlocked, and if so, the unlock is performed. There is also a manual method `purgeEscrowDeposits(maxToPurge)` for explicit cleanup. -::: - -### Finalization Steps - -1. **PackState** -- Node prepares the final state. -2. **FinalizeEscrowDeposit** -- Submits to Escrow Chain contract. -3. **EscrowDepositFinalized** event emitted. -4. Node updates internal state and notifies Client. - ---- - -## Complete Flow Diagram - -```mermaid -sequenceDiagram - actor User - actor Client - actor Node - actor HomeChain - actor EscrowChain - - rect rgb(40, 40, 100) - Note over User,Client: Phase 1: Initiation - User->>Client: async deposit(blockchainId, asset, amount) - end - - rect rgb(40, 100, 40) - Note over Client,Node: Phase 2-4: State Preparation - Client->>Node: GetLastState(UserWallet, asset) - Node->>Client: Returns state - Note over Client: Build mutual_lock state - Client->>Node: SubmitState(state, userSig) - Node->>Client: Return node signature - end - - rect rgb(150, 100, 40) - Note over Client,EscrowChain: Phase 5: On-Chain Escrow - Client->>EscrowChain: initiateEscrowDeposit(...) - EscrowChain-->>Node: EscrowDepositInitiated Event - end - - rect rgb(40, 100, 100) - Note over Node,HomeChain: Phase 6: Home Chain Checkpoint - Node->>HomeChain: initiateEscrowDeposit(homeChannelId, packedState) - HomeChain-->>Node: EscrowDepositInitiatedOnHome Event - end - - rect rgb(100, 40, 100) - Note over Client,Node: Phase 7-8: Execution State - Client->>Node: GetLastState(UserWallet, asset) - Node->>Client: Returns state - Note over Client: Build escrow_deposit state - Client->>Node: SubmitState(state, userSig) - Node->>Client: Return node signature - Client-->>User: Returns success - end - - rect rgb(100, 100, 40) - Note over Node,EscrowChain: Phase 9: Finalization - Node->>EscrowChain: finalizeEscrowDeposit(...) - EscrowChain-->>Node: EscrowDepositFinalized Event - Node-->>Client: ChannelUpdate and BalanceUpdate - end -``` - ---- - -## Key Concepts Summary - -### State Transitions Overview - -```mermaid -flowchart LR - subgraph Preparation["Preparation Phase"] - A["Current State"] --> B["mutual_lock Transition"] - B --> C["Escrowed State"] - end - subgraph Execution["Execution Phase"] - C --> D["escrow_deposit Transition"] - D --> E["Final State"] - end - - style Preparation fill:#1a1a2e,stroke:#16213e - style Execution fill:#0f3460,stroke:#16213e -``` - -### On-Chain vs Off-Chain Actions - -| Action | Chain | Purpose | -| --- | --- | --- | -| `SubmitState` (mutual_lock) | Off-chain (Node) | Prepare escrow | -| `initiateEscrowDeposit` | **On-chain (Escrow)** | Lock funds on non-home chain | -| `initiateEscrowDeposit` | **On-chain (Home)** | Record state on home chain | -| `SubmitState` (escrow_deposit) | Off-chain (Node) | Execute escrow | -| `finalizeEscrowDeposit` | **On-chain (Escrow)** | Release locked funds | - -### Security Guarantees - -From the on-chain protocol: - -- **Preparation phase**: User locks funds on the non-home chain. Node locks equal liquidity on the home chain. An escrow object with timeouts is created. -- **Execution phase**: A signed execution state updates allocations and net flows. -- **Recoverability**: Every escrow phase must be completable or revertible via timeout and challenge on at least one chain. - ---- - -## Error Recovery - -### What if the process stalls? - -| Scenario | Recovery | -| --- | --- | -| Node doesn't respond | User can challenge with the last signed state | -| On-chain transaction fails | Retry or wait for timeout to revert | -| Network issues | Escrowed funds released automatically after lock period | - -### Challenge Mechanism - -If an escrow process is challenged and the challenge period expires without resolution, the finalize function: - -1. Does not invoke the channel engine. -2. Manually unlocks the locked funds to the Node. -3. Sets status to `FINALIZED`. - -:::warning -If an escrow was challenged, then the on-chain channel **must also be challenged and closed**. It is not possible to continue operating a channel after any related escrow was challenged. -::: - ---- - -## Related Flows - -- [Transfer Communication Flow](./transfer-flow) -- [App Session Deposit Flow](./app-session-deposit) +- [Architecture at a Glance](../introduction/architecture-at-a-glance) - [Home Channel Deposit Flow](./home-channel-deposit) -- [Escrow Channel Withdrawal Flow](./escrow-withdrawal) +- [App Session Deposit Flow](./app-session-deposit) +- [Cross-chain and Assets](/nitrolite/protocol/cross-chain-and-assets) diff --git a/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx b/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx index e740011..82e7271 100644 --- a/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx +++ b/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx @@ -1,517 +1,48 @@ --- title: "Escrow Channel Withdrawal Flow" -description: "A comprehensive breakdown of the Escrow Channel Withdrawal flow for cross-chain withdrawals via short-lived escrow channels in the Nitrolite v1.0 protocol." +description: "Current documentation status for non-home-chain escrow withdrawals in Nitrolite v1." sidebar_position: 9 --- # Escrow Channel Withdrawal Flow -This document provides a comprehensive breakdown of the **Escrow Channel Withdrawal** flow as defined in the Nitrolite v1.0 protocol. This operation allows a user to withdraw funds from their **unified balance** to a **Non-Home Chain** (a blockchain different from where their home channel exists) through a **short-lived Escrow Channel**. +Escrow withdrawals are the protocol path for moving value from a user's home-channel balance to a non-home chain. The mechanism can be supported by Nitrolite, but docs.yellow.org does not yet document escrow withdrawals as a builder-facing workflow. -This is the reverse operation of Escrow Channel Deposit -- it's a **cross-chain bridging out** operation that uses a two-phase approach (Preparation + Execution) to move liquidity from the home chain to a different blockchain. - -:::caution Cross-Chain Status -Cross-chain functionality is not yet fully implemented. While channels can be created on any chain with a Nitro deployment, cross-chain operations like escrow deposit and withdrawal are planned for shortly after launch. +:::caution Not documented as an app workflow yet +Escrow operation mechanics are intentionally deferred until the Nitronode automation and product surface are ready for public builder docs. Use the home-channel withdrawal and app-session lifecycle docs for the current v1 builder path. ::: ---- - -## Actors in the Flow - -```mermaid -graph LR - U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] - N <--> HC["HomeChain"] - N <--> EC["EscrowChain"] - - style U stroke:#333 - style C stroke:#333 - style N stroke:#333 - style HC stroke:#4CAF50 - style EC stroke:#FF9800 -``` +## What is stable -| Actor | Role | -| --- | --- | -| **User** | The human user initiating the cross-chain withdrawal | -| **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates, coordinates, and bridges state transitions | -| **HomeChain** | The blockchain where the user's home channel exists (funds originate here) | -| **EscrowChain** | The non-home blockchain where the user wants to receive funds | - ---- +The conceptual model is still useful when reading protocol material: -## Prerequisites +- A user's home ledger remains the canonical balance for an asset. +- A withdrawal to a non-home chain needs an escrow path because the target chain cannot directly verify the home chain's latest channel state. +- Nitronode coordinates signed off-chain state updates and on-chain settlement paths. +- Applications should not ask users to run escrow withdrawal state construction manually. -Before the escrow withdrawal flow begins: +## Transition names -1. **User already has a home channel** on the HomeChain. -2. **Node** contains the user's state with Home Channel information. -3. **Client** is connected to the Node via WebSocket. -4. **User has sufficient balance** in their unified balance to withdraw. +The current schema names the two escrow-withdrawal transitions as: -This flow handles the "bridging out" scenario. When a user wants to receive funds on a chain that is NOT their home chain, they use the escrow withdrawal mechanism where the Node locks liquidity on the target chain. - ---- - -## Key Concepts - -### Escrow Withdrawal vs Escrow Deposit - -| Operation | Direction | User Action | Node Action | -| --- | --- | --- | --- | -| **Escrow Deposit** | Non-Home to Home | User locks funds on escrow chain | Node provides liquidity on home chain | -| **Escrow Withdrawal** | Home to Non-Home | User locks funds on home chain | Node provides liquidity on escrow chain | - -### Transition Types Used - -| Transition | Description | +| Transition | Meaning | | --- | --- | -| `escrow_lock` | Lock funds from unified balance, preparing for withdrawal | -| `escrow_withdraw` | Finalize the withdrawal, releasing funds on escrow chain | - ---- - -## Phase 1: Withdrawal Initiation - -```mermaid -sequenceDiagram - actor User - actor Client - - User->>Client: async withdraw(blockchainId, asset, amount) - Note over Client: User initiates cross-chain withdrawal -``` - -The **User** calls the `withdraw` function on the **Client** SDK with three parameters: - -| Parameter | Description | Example | -| --- | --- | --- | -| `blockchainId` | The blockchain ID where funds should be received (non-home chain) | `59144` (Linea) | -| `asset` | The asset symbol to withdraw | `usdc` | -| `amount` | The amount to withdraw | `100.0` | - ---- - -## Phase 2: Fetching Current State - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: GetLastState(UserWallet, asset) - Note right of Node: GetLastState(userWallet, asset) - Node->>Client: Returns state -``` - -1. **Client** requests the **latest state** from the Node. -2. The Node looks up the state using `UserWallet` and `asset`. -3. The Node returns the current **state** object containing the **Home Channel** information. - ---- - -## Phase 3: Building the Preparation State (Escrow Lock) - -```mermaid -sequenceDiagram - actor Client - - Note over Client: createNextState(currentState) returns state - Note over Client: state.setID(CalculateStateID(state.userWallet,
state.asset, state.cycleId, state.version)) - Note over Client: GetTokenAddress(blockchainId, asset) - Note over Client: state.setEscrowToken(blockchainId, tokenAddress) - Note over Client: GetEscrowChannelID(homeChannelDef, state.version) - Note over Client: NewTransition(escrowLockT, state.ID(),
escrowChannelID, amount) - Note over Client: state.applyTransitions(transitions) returns true - Note over Client: signState(state) returns userSig -``` - -### 3.1 Create Next State - -``` -createNextState(currentState) -> state -``` - -The Client creates a new state object based on the current state with an incremented version. - -### 3.2 Calculate State ID - -``` -state.setID(CalculateStateID(state.userWallet, state.asset, state.cycleId, state.version)) -``` +| `escrow_lock` | Escrow withdrawal initiate. Funds are prepared for the cross-chain withdrawal path. | +| `escrow_withdraw` | Escrow withdrawal finalize. The withdrawal is completed toward the non-home-chain destination. | -The **State ID** is a deterministic hash computed from user wallet, asset, cycle, and version. +These names are included so readers can recognize them in protocol and API reference material. They are not instructions to assemble escrow withdrawal states by hand. -### 3.3 Get Token Address for Escrow Chain +## Current builder guidance -``` -GetTokenAddress(blockchainId, asset) -> tokenAddress -``` +For applications today: -The Client resolves the token contract address for the specified asset on the escrow (non-home) chain. - -### 3.4 Set Escrow Token - -``` -state.setEscrowToken(blockchainId, tokenAddress) -``` - -The state is updated to include the escrow chain's token information in the `escrow_ledger`. - -### 3.5 Get Escrow Channel ID - -``` -GetEscrowChannelID(homeChannelDef, state.version) -> escrowChannelID -``` - -A deterministic escrow channel ID is computed based on the home channel definition and current version. - -### 3.6 Create Escrow Lock Transition - -``` -NewTransition(escrow_lock, state.ID(), escrowChannelID, amount) -``` - -The **escrow_lock** transition locks funds from the user's unified balance: - -| Field | Value | -| --- | --- | -| `type` | `escrow_lock` | -| `tx_hash` | State ID reference | -| `account_id` | Escrow Channel ID | -| `amount` | Amount to lock | - -### 3.7 Apply and Sign - -``` -state.applyTransitions(transitions) -> true -signState(state) -> userSig -``` - -The transition is applied to the state and the user signs it. - ---- - -## Phase 4: Node Validates and Stores Escrow Channel - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: SubmitState(state, userSig) - Note right of Node: GetLastState(userWallet, asset) returns currentState - Note right of Node: EnsureNoOngoingTransitions() - Note right of Node: ValidateStateTransition(currentState, state) - Note right of Node: StoreEscrowChannel(escrow_channel) - Note right of Node: StoreState(state) - Node->>Client: Return node signature -``` - -### Node Validation Steps - -| Step | Operation | Purpose | -| --- | --- | --- | -| 1 | `GetLastState(...)` | Fetch current user state | -| 2 | `EnsureNoOngoingTransitions()` | Block other operations during escrow | -| 3 | `ValidateStateTransition(...)` | Verify version, signatures, balances | -| 4 | `StoreEscrowChannel(...)` | Create escrow channel record | -| 5 | `StoreState(state)` | Persist the new state | - -:::warning Atomic Operations -Once an escrow withdrawal starts with `escrow_lock`, **the Node stops issuing new states** until `escrow_withdraw` finalizes. This ensures atomicity of cross-chain operations. -::: - ---- - -## Phase 5: On-Chain Escrow Initiation - -```mermaid -sequenceDiagram - actor Client - actor Node - actor EscrowChain - - Note over Client: PackChannelDefinition(channelDef) - Note over Client: PackState(channelId, state) - Client->>EscrowChain: initiateEscrowWithdrawal(packedChannelDef, packedState) - EscrowChain->>Client: Return Tx Hash - EscrowChain-->>Node: Emits EscrowWithdrawalInitiated Event - Note right of Node: HandleEscrowWithdrawalInitiated() - Note right of Node: UpdateEscrowChannel(escrow_channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate -``` - -### 5.1 Pack Channel Definition and State - -``` -PackChannelDefinition(channelDef) -> packedChannelDef -PackState(channelId, state) -> packedState -``` - -The Client serializes the channel definition and state for on-chain submission. - -### 5.2 Client On-Chain Transaction - -``` -initiateEscrowWithdrawal(packedChannelDef, packedState) -``` - -The **Client** submits a transaction to the **EscrowChain** smart contract, which: - -- Locks the Node's liquidity on the escrow chain -- Creates an escrow object with timeouts -- Emits `EscrowWithdrawalInitiated` event - -:::warning Security Measure -In cross-chain operations (escrow deposit, escrow withdrawal, channel migration), the **first on-chain transaction is always submitted by the User/Client**. This guards against DOS attacks where a user would initiate an action, the Node would need to perform a transaction, and the user disappears. -::: +- Use home-channel withdrawal for same-chain exits. +- Use app-session withdrawal to return app-session funds to the user's home channel. +- Treat escrow withdrawal automation as a future product path until the public Nitronode workflow is documented. -### 5.3 Node Event Handling +## Related pages -The Node listens for blockchain events and: - -1. **HandleEscrowWithdrawalInitiated** -- Processes the event. -2. **UpdateEscrowChannel** -- Updates the escrow channel status. -3. Sends **ChannelUpdate** and **BalanceUpdate** notifications to the Client. - ---- - -## Phase 6: Building the Execution State (Escrow Withdrawal) - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: GetLastState(UserWallet, asset) - Note right of Node: GetLastState(userWallet, asset) - Node->>Client: Returns state - Note over Client: createNextState(currentState) returns state - Note over Client: state.setID(CalculateStateID(state.userWallet,
state.asset, state.cycleId, state.version)) - Note over Client: NewTransition(escrow_withdrawalT, state.ID(),
escrowChannelID, amount) - Note over Client: state.applyTransitions(transitions) returns true - Note over Client: signState(state) returns userSig -``` - -### 6.1 Fetch Updated State - -The Client fetches the latest state which now reflects the locked funds. - -### 6.2 Create Escrow Withdrawal Transition - -``` -NewTransition(escrow_withdraw, state.ID(), escrowChannelID, amount) -``` - -The **escrow_withdraw** transition finalizes the cross-chain withdrawal: - -| Field | Value | -| --- | --- | -| `type` | `escrow_withdraw` | -| `tx_hash` | State ID reference | -| `account_id` | Escrow Channel ID | -| `amount` | Withdrawn amount | - ---- - -## Phase 7: Submitting Execution State - -```mermaid -sequenceDiagram - actor Client - actor Node - - Client->>Node: SubmitState(state, userSig) - Note right of Node: GetLastState(userWallet, asset) returns currentState - Note right of Node: ValidateStateTransition(currentState, state) - Note right of Node: StoreState(state) - Node->>Client: Return node signature -``` - -1. Client submits the execution state with `escrow_withdraw` transition. -2. Node validates and stores the state. -3. Node returns its signature confirming acceptance. - ---- - -## Phase 8: Escrow Finalization - -```mermaid -sequenceDiagram - actor Client - actor Node - actor EscrowChain - - Note over Node: PackState(channelId, state) - Client->>EscrowChain: finalizeEscrowWithdrawal(escrowChannelId, packedState) - EscrowChain->>Client: Return Tx Hash - EscrowChain-->>Node: Emits EscrowWithdrawalFinalized Event - Note right of Node: HandleEscrowWithdrawalFinalized() - Note right of Node: UpdateEscrowChannel(escrow_channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate -``` - -### 8.1 Pack Final State - -``` -PackState(channelId, state) -> packedState -``` - -The Node prepares the final state for on-chain submission. - -### 8.2 Client Finalizes On-Chain - -``` -finalizeEscrowWithdrawal(escrowChannelId, packedState) -``` - -The **Client** submits a transaction to finalize the withdrawal: - -- Releases the Node's locked funds to the User on the escrow chain. -- User receives funds on the non-home chain. -- Emits `EscrowWithdrawalFinalized` event. - -At this point, the user's wallet on the EscrowChain receives the withdrawn funds. - -### 8.3 Node Event Handling - -The Node: - -1. **HandleEscrowWithdrawalFinalized** -- Processes the event. -2. **UpdateEscrowChannel** -- Marks escrow as completed. -3. Sends final **ChannelUpdate** and **BalanceUpdate** notifications. - ---- - -## Complete Flow Diagram - -```mermaid -sequenceDiagram - actor User - actor Client - actor Node - actor HomeChain - actor EscrowChain - - rect rgb(40, 40, 100) - Note over User,Client: Phase 1: Initiation - User->>Client: async withdraw(blockchainId, asset, amount) - end - - rect rgb(40, 100, 40) - Note over Client,Node: Phase 2-4: State Preparation - Client->>Node: GetLastState(UserWallet, asset) - Node->>Client: Returns state - Note over Client: Build escrow_lock state - Client->>Node: SubmitState(state, userSig) - Node->>Client: Return node signature - end - - rect rgb(150, 100, 40) - Note over Client,EscrowChain: Phase 5: On-Chain Escrow - Client->>EscrowChain: initiateEscrowWithdrawal(...) - EscrowChain-->>Node: EscrowWithdrawalInitiated Event - Node-->>Client: ChannelUpdate and BalanceUpdate - end - - rect rgb(100, 40, 100) - Note over Client,Node: Phase 6-7: Execution State - Client->>Node: GetLastState(UserWallet, asset) - Node->>Client: Returns state - Note over Client: Build escrow_withdraw state - Client->>Node: SubmitState(state, userSig) - Node->>Client: Return node signature - end - - rect rgb(100, 100, 40) - Note over Client,EscrowChain: Phase 8: Finalization - Client->>EscrowChain: finalizeEscrowWithdrawal(...) - EscrowChain-->>Node: EscrowWithdrawalFinalized Event - Node-->>Client: ChannelUpdate and BalanceUpdate - end -``` - ---- - -## Key Concepts Summary - -### State Transitions Overview - -```mermaid -flowchart LR - subgraph Preparation["Preparation Phase"] - A["Current State"] --> B["escrow_lock Transition"] - B --> C["Locked State"] - end - subgraph Execution["Execution Phase"] - C --> D["escrow_withdraw Transition"] - D --> E["Final State"] - end - - style Preparation fill:#1a1a2e,stroke:#16213e - style Execution fill:#0f3460,stroke:#16213e -``` - -### Comparison: Escrow Deposit vs Withdrawal - -| Aspect | Escrow Deposit | Escrow Withdrawal | -| --- | --- | --- | -| **Direction** | Non-Home to Home | Home to Non-Home | -| **Preparation Transition** | `mutual_lock` | `escrow_lock` | -| **Execution Transition** | `escrow_deposit` | `escrow_withdraw` | -| **Who initiates on-chain?** | Client (initiateEscrowDeposit) | Client (initiateEscrowWithdrawal) | -| **Who finalizes on-chain?** | Node (finalizeEscrowDeposit) | Client (finalizeEscrowWithdrawal) | -| **Who provides liquidity?** | Node on home chain | Node on escrow chain | - -### On-Chain vs Off-Chain Actions - -| Action | Chain | Who | Purpose | -| --- | --- | --- | --- | -| `SubmitState` (escrow_lock) | Off-chain (Node) | Client | Lock funds in preparation | -| `initiateEscrowWithdrawal` | **On-chain (Escrow)** | Client | Lock Node's liquidity | -| `SubmitState` (escrow_withdraw) | Off-chain (Node) | Client | Execute withdrawal | -| `finalizeEscrowWithdrawal` | **On-chain (Escrow)** | Client | Release funds to User | - -### Security Guarantees - -From the on-chain protocol: - -- **Preparation phase**: Node locks withdrawal liquidity on the non-home chain. -- **Execution phase**: Signed state updates allocations and net flows so that User receives funds on the non-home chain. -- If enforcement stalls, challenges and timeouts guarantee completion or reversion. - ---- - -## Error Recovery - -### What if the process stalls? - -| Scenario | Recovery | -| --- | --- | -| Node doesn't respond | User can challenge with the last signed state | -| On-chain transaction fails | Retry or wait for timeout to revert | -| Network issues | User can challenge or wait for timeout-based recovery | - -### Challenge Resolution - -If an escrow process is challenged and the challenge period expires without resolution: - -1. The finalize function handles this explicitly. -2. Manually unlocks the locked funds to the Node. -3. Sets status to `FINALIZED`. - -:::warning -If an escrow was challenged, then the on-chain channel **must also be challenged and closed**. It is not possible to continue operating a channel after any related escrow was challenged. -::: - ---- - -## Related Flows - -- [Transfer Communication Flow](./transfer-flow) -- [App Session Deposit Flow](./app-session-deposit) -- [Escrow Channel Deposit Flow](./escrow-deposit) +- [Architecture at a Glance](../introduction/architecture-at-a-glance) - [Home Channel Withdrawal Flow](./home-channel-withdrawal) +- [App Session Deposit Flow](./app-session-deposit) +- [Cross-chain and Assets](/nitrolite/protocol/cross-chain-and-assets) diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-creation.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-creation.mdx index bfcde3c..f1936b3 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-creation.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-creation.mdx @@ -17,7 +17,7 @@ This flow is triggered when a user attempts to deposit for the first time and ha ```mermaid graph LR U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] + C <--> N["Nitronode"] C --> HC["HomeChain"] HC -.-> N @@ -31,7 +31,7 @@ graph LR | --- | --- | | **User** | The human user initiating their first deposit | | **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates, stores, and coordinates state transitions | +| **Node** | The Nitronode that validates, stores, and coordinates state transitions | | **HomeChain** | The blockchain where the user's home channel will be created | --- @@ -318,7 +318,7 @@ The **Client** submits a transaction to the **HomeChain** smart contract, which: --- -## Phase 6: Event Handling and Completion +## Phase 6: Confirmation and Completion ```mermaid sequenceDiagram @@ -328,20 +328,16 @@ sequenceDiagram Note right of Node: HandleChannelCreated() Note right of Node: UpdateChannel(channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success ``` -The Node listens for blockchain events and: +Nitronode listens for blockchain events internally and updates its stored view: 1. **HandleChannelCreated()** -- Processes the creation event. 2. **UpdateChannel(channel)** -- Updates channel status to reflect on-chain state. -| Event | Description | -| --- | --- | -| `ChannelUpdate` | Notifies client of new channel status | -| `BalanceUpdate` | Notifies client of new balance | - The Client returns success to the User, confirming: - Home channel created successfully @@ -392,7 +388,8 @@ sequenceDiagram rect rgb(40, 100, 100) Note over Node,User: Phase 6: Completion - Node-->>Client: ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success end ``` @@ -439,7 +436,7 @@ flowchart LR The Nitrolite architecture improves upon the previous version by **skipping the custody ledger step**. Users transfer funds directly from their ERC-20 token balance via approvals, saving one transaction compared to the old protocol. This means: -1. User approves the Custody contract. +1. User approves the ChannelHub. 2. Channel creation pulls funds directly. 3. No intermediate custody step required. diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx index 71b528b..933ad56 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx @@ -21,7 +21,7 @@ This flow is for **subsequent deposits** to an existing channel. For the initial ```mermaid graph LR U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] + C <--> N["Nitronode"] C --> HC["HomeChain"] HC -.-> N @@ -35,7 +35,7 @@ graph LR | --- | --- | | **User** | The human user initiating the deposit | | **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates and stores state transitions | +| **Node** | The Nitronode that validates and stores state transitions | | **HomeChain** | The blockchain where the user's home channel exists | --- @@ -48,7 +48,7 @@ Before the home channel deposit flow begins: 2. **User already has a home channel** on the HomeChain. 3. **Node** contains the user's state with Home Channel information. 4. **User has funds** on the HomeChain to deposit (ERC-20 tokens). -5. **No ongoing operation** exists for this channel (the Clearnode will deny the request otherwise). +5. **No ongoing operation** exists for this channel (the Nitronode will deny the request otherwise). :::note The "no ongoing operation" requirement applies to ALL operations except `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. @@ -248,7 +248,7 @@ The **Client** submits a transaction to the **HomeChain** smart contract, which: --- -## Phase 6: Event Handling and Completion +## Phase 6: Confirmation and Completion ```mermaid sequenceDiagram @@ -258,20 +258,16 @@ sequenceDiagram Note right of Node: HandleChannelDeposited() Note right of Node: UpdateChannel(channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success ``` -The Node listens for blockchain events and: +Nitronode listens for blockchain events internally and updates its stored view: 1. **HandleChannelDeposited()** -- Processes the deposit event. 2. **UpdateChannel(channel)** -- Updates the channel's on-chain state version and locked funds. -| Event | Description | -| --- | --- | -| `ChannelUpdate` | Notifies client of new channel state | -| `BalanceUpdate` | Notifies client of new balance | - --- ## Complete Flow Diagram @@ -316,7 +312,8 @@ sequenceDiagram rect rgb(100, 40, 40) Note over Node,User: Phase 6: Completion - Node-->>Client: ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success end ``` diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-withdraw-on-create.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-withdraw-on-create.mdx index 5187395..5ea0284 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-withdraw-on-create.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-withdraw-on-create.mdx @@ -17,7 +17,7 @@ This scenario commonly occurs when a user receives a transfer before ever deposi ```mermaid graph LR U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] + C <--> N["Nitronode"] C --> HC["HomeChain"] HC -.-> N @@ -31,7 +31,7 @@ graph LR | --- | --- | | **User** | The human user initiating the withdrawal | | **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that contains the user's pending state | +| **Node** | The Nitronode that contains the user's pending state | | **HomeChain** | The blockchain where the channel will be created | --- @@ -280,7 +280,7 @@ Since this is a withdrawal without deposit: --- -## Phase 6: Event Handling and Completion +## Phase 6: Confirmation and Completion ```mermaid sequenceDiagram @@ -290,7 +290,8 @@ sequenceDiagram Note right of Node: HandleChannelCreated() Note right of Node: UpdateChannel(channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success ``` @@ -344,7 +345,8 @@ sequenceDiagram rect rgb(40, 100, 100) Note over Node,User: Phase 6: Completion - Node-->>Client: ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success end ``` diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx index 3b5d455..ebecc16 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx @@ -21,7 +21,7 @@ The Home Chain may differ from where the channel was originally created, as user ```mermaid graph LR U["User"] --> C["Client"] - C <--> N["Node (Clearnode)"] + C <--> N["Nitronode"] C --> HC["HomeChain"] HC -.-> N @@ -35,7 +35,7 @@ graph LR | --- | --- | | **User** | The human user initiating the withdrawal | | **Client** | SDK/Application managing states on behalf of the user | -| **Node** | The Clearnode that validates and stores state transitions | +| **Node** | The Nitronode that validates and stores state transitions | | **HomeChain** | The blockchain where the user's home channel exists | --- @@ -48,7 +48,7 @@ Before the home channel withdrawal flow begins: 2. **User already has a home channel** on the HomeChain. 3. **Node** contains the user's state with Home Channel information. 4. **User has sufficient balance** in their unified balance to withdraw. -5. **No ongoing operation** exists for this channel (the Clearnode will deny the request otherwise). +5. **No ongoing operation** exists for this channel (the Nitronode will deny the request otherwise). :::note The "no ongoing operation" requirement applies to ALL operations except `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. @@ -258,7 +258,7 @@ The **Client** submits a transaction to the **HomeChain** smart contract, which: --- -## Phase 6: Event Handling and Completion +## Phase 6: Confirmation and Completion ```mermaid sequenceDiagram @@ -268,20 +268,16 @@ sequenceDiagram Note right of Node: HandleChannelWithdrawn() Note right of Node: UpdateChannel(channel) - Node-->>Client: Sends ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success ``` -The Node listens for blockchain events and: +Nitronode listens for blockchain events internally and updates its stored view: 1. **HandleChannelWithdrawn()** -- Processes the withdrawal event. 2. **UpdateChannel(channel)** -- Updates the channel's on-chain state version. -| Event | Description | -| --- | --- | -| `ChannelUpdate` | Notifies client of new channel state | -| `BalanceUpdate` | Notifies client of new balance | - --- ## Complete Flow Diagram @@ -326,7 +322,8 @@ sequenceDiagram rect rgb(100, 40, 40) Note over Node,User: Phase 6: Completion - Node-->>Client: ChannelUpdate and BalanceUpdate + Client->>Node: Query latest channel and balance + Node-->>Client: Returns latest channel state and balance Client-->>User: Returns success end ``` diff --git a/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx b/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx index 94201d8..c6a5bfa 100644 --- a/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx +++ b/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx @@ -6,7 +6,7 @@ sidebar_position: 2 # Transfer Communication Flow -This document provides a comprehensive breakdown of the **off-chain transfer flow** as defined in the Nitrolite v1.0 protocol. The transfer operation moves funds between users instantly without blockchain transactions, leveraging **state transitions** managed through the **Clearnode** (Node). +This document provides a comprehensive breakdown of the **off-chain transfer flow** as defined in the Nitrolite v1.0 protocol. The transfer operation moves funds between users instantly without blockchain transactions, leveraging **state transitions** managed through the **Nitronode** (Node). --- @@ -15,7 +15,7 @@ This document provides a comprehensive breakdown of the **off-chain transfer flo ```mermaid graph LR SU["SenderUser"] --> SC["SenderClient"] - SC <--> N["Node (Clearnode)"] + SC <--> N["Nitronode"] N <--> RC["ReceiverClient"] style SU stroke:#333 @@ -28,8 +28,8 @@ graph LR | --- | --- | | **SenderUser** | The human user initiating the transfer | | **SenderClient** | SDK/Application that manages states on behalf of the sender | -| **Node** | The Clearnode that validates, stores, and coordinates state transitions | -| **ReceiverClient** | SDK/Application that receives notifications for the recipient | +| **Node** | The Nitronode that validates, stores, and coordinates state transitions | +| **ReceiverClient** | SDK/Application that can query the recipient's latest state | --- @@ -204,9 +204,9 @@ EnsureNoOngoingTransitions() The Node checks that there are no pending/incomplete transitions for this user. This prevents race conditions and ensures state consistency. :::warning -If there's an ongoing transition, the Clearnode will return a relevant error and the submission is rejected. +If there's an ongoing transition, the Nitronode will return a relevant error and the submission is rejected. -**Atomic Operations**: `escrow_deposit`, `escrow_withdrawal`, and `home-chain migration` operations are considered as one atomic operation. This means that if, for example, an escrow deposit was started with `initiate_escrow_deposit` transition, then no other states will be issued apart from `finalize_escrow_deposit`. Only after finalization can a `transfer` (or other non-`finalize_escrow_deposit` transition) be accepted by the Node. +**Serialized operations**: Nitronode does not accept a transfer while another state transition is still pending for the same user and asset. Escrow and migration transitions are not documented as builder-facing workflows yet, but they follow the same rule: finish or acknowledge the pending state before submitting a normal transfer. ::: :::info @@ -219,7 +219,7 @@ Even in case of `home_deposit`, the Node won't accept a new state until it knows ValidateAdvancement(currentState, proposedState) ``` -State advancement validation is done by applying effects from the proposed state to the current one. If there is any difference between the proposed state and the one built by the Clearnode, it will return a relevant error (e.g., `version should be X`, `asset shouldn't change`, etc.). +State advancement validation is done by applying effects from the proposed state to the current one. If there is any difference between the proposed state and the one built by the Nitronode, it will return a relevant error (e.g., `version should be X`, `asset shouldn't change`, etc.). The Node validates: @@ -244,7 +244,7 @@ StoreState(state) ``` :::info 2-Signature Rule -The Node also signs the sender's state. In v1, only a 2-signature state (both User and Node signatures) can be valid. After signing, the Node stores the state locally and sends it as a notification to subscribers. +The Node also signs the sender's state. In v1, only a 2-signature state (both User and Node signatures) can be valid. After signing, Nitronode stores the state locally and returns the signature in the transfer response. ::: The validated and dual-signed state is stored in the Node's database. At this point, the sender's side of the transfer is complete. @@ -324,9 +324,9 @@ The Node supports receiving funds by users who don't have a channel or are not o --- -## Phase 6: Notifications and Completion +## Phase 6: Confirmation and Completion -After the receiver state is created, the Node sends notifications to both the sender and receiver clients. +After the receiver state is created, Nitronode returns the sender-side signature. Applications that need fresh balances should query the latest channel or balance state after the transfer response. --- @@ -367,11 +367,13 @@ sequenceDiagram end rect rgb(0, 0, 0) - Note over Node,ReceiverClient: Phase 6: Notify - Node->>SenderClient: ChannelUpdate and BalanceUpdate - Node->>ReceiverClient: ChannelUpdate and BalanceUpdate + Note over Node,ReceiverClient: Phase 6: Confirm and query Node->>SenderClient: Return node signature - SenderClient->>SenderUser: Returns success and tx hash + SenderClient->>Node: Query latest state if needed + ReceiverClient->>Node: Query latest state if online + Node->>SenderClient: Returns latest state + Node->>ReceiverClient: Returns latest state + SenderClient->>SenderUser: Returns success end ``` diff --git a/docs/nitrolite/protocol/cross-chain-and-assets.mdx b/docs/nitrolite/protocol/cross-chain-and-assets.mdx index c162a26..3ba4ca4 100644 --- a/docs/nitrolite/protocol/cross-chain-and-assets.mdx +++ b/docs/nitrolite/protocol/cross-chain-and-assets.mdx @@ -76,46 +76,39 @@ Each escrow is identified by an escrow channel identifier derived deterministica An escrow is not a separate protocol entity with its own state. It is an on-chain record derived from a channel state transition. -## Cross-Chain Deposit +:::caution Builder workflow not documented yet +Escrow and migration mechanics can be supported by the protocol, but docs.yellow.org does not yet document them as public app-builder workflows. The sections below define the semantic model only. +::: -Cross-chain deposit uses a two-phase escrow process: +## Cross-Chain Deposit -1. **Initiate**: participants sign an Escrow Deposit Initiate state. On the home chain, the Node allocation increases to reserve funds. On the non-home chain, the User deposit is locked in escrow with an unlock delay. -2. **Finalize**: participants sign an Escrow Deposit Finalize state. On the home chain, the User allocation increases by the deposited amount. On the non-home chain, escrowed funds are released to the Node's vault. +Cross-chain deposit is represented as a two-phase escrow family: -If escrow is not finalized within the unlock delay, escrowed funds on the non-home chain are automatically unlocked to the Node. Either participant MAY challenge escrow during the challenge period. It is NOT possible to challenge a deposit escrow after the unlock delay has passed. +| Phase | Transition literal | Meaning | +| --- | --- | --- | +| Initiate | `mutual_lock` | Escrow deposit initiate. | +| Finalize | `escrow_deposit` | Escrow deposit finalize or complete. | Cross-chain amounts are validated using WAD normalization. ## Cross-Chain Withdrawal -Cross-chain withdrawal uses a similar two-phase escrow process: - -1. **Initiate**: participants sign an Escrow Withdrawal Initiate state. On the non-home chain, the Node locks funds from its vault into escrow. -2. **Finalize**: participants sign an Escrow Withdrawal Finalize state. On the home chain, the User allocation decreases. On the non-home chain, escrowed funds are released to the User. +Cross-chain withdrawal is represented as a two-phase escrow family: -If escrow is not finalized cooperatively, either participant MAY challenge the escrow. +| Phase | Transition literal | Meaning | +| --- | --- | --- | +| Initiate | `escrow_lock` | Escrow withdrawal initiate. | +| Finalize | `escrow_withdraw` | Escrow withdrawal finalize or complete. | ## Home Chain Migration -The home chain MAY change through two-phase migration: - -1. **Initiate**: participants sign a Migration Initiate state. On the current home chain, the state records target-chain allocation. On the target chain, a new channel record is created with migrating-in status and the Node locks funds equal to User allocation, validated by WAD normalization. -2. **Finalize**: participants sign a Migration Finalize state. On the new home chain, the channel transitions to operating status. On the old home chain, locked funds are released to the Node and the channel is marked as migrated out. - -After migration: +The home chain may change through migration states, represented by the `migrate` transition family. Migration is not a public builder workflow today. Conceptually, after migration: - home chain identifier updates. - home token address updates. -- former non-home ledger becomes the home ledger. -- former home ledger becomes the non-home ledger and is zeroed out on finalization. +- the new home ledger becomes the authoritative ledger. - subsequent enforcement operations execute against the new home chain. -- User allocation is preserved, normalized by decimal precision. -- Node allocation is recalculated for the new chain. - -:::note Migration version note -Migration transitions are functional but may be refined in future protocol versions. -::: +- user allocation is preserved, normalized by decimal precision. ## Cross-Chain Replay Protection diff --git a/docs/nitrolite/protocol/enforcement-and-settlement.mdx b/docs/nitrolite/protocol/enforcement-and-settlement.mdx index f339414..400e787 100644 --- a/docs/nitrolite/protocol/enforcement-and-settlement.mdx +++ b/docs/nitrolite/protocol/enforcement-and-settlement.mdx @@ -86,14 +86,14 @@ The challenger signature is distinct from state signatures. It is produced by si Challenge process: 1. The challenger submits a candidate state, state signatures, challenger signature, and challenger participant index. -2. The channel MUST NOT be in `DISPUTE`, `MIGRATED_OUT`, or `CLOSED` status. +2. The channel MUST NOT already be `challenged` or `closed`. 3. The candidate version MUST be greater than or equal to the current on-chain version. 4. If the candidate version is strictly greater, the blockchain layer validates and applies the new state. -5. The channel status becomes `DISPUTED`, and challenge expiry is set to current time plus challenge duration. +5. The channel status becomes `challenged`, and challenge expiry is set to current time plus challenge duration. -During the challenge period, any participant MAY respond with a valid state whose version is strictly greater than the disputed state. It is NOT possible to file another challenge while a channel is already disputed. +During the challenge period, any participant MAY respond with a valid state whose version is strictly greater than the challenged state. It is NOT possible to file another challenge while a channel is already challenged. -After the challenge period expires without resolution, the disputed state becomes final. A separate close call is still required to release locked funds. +After the challenge period expires without resolution, the challenged state becomes final. A separate close call is still required to release locked funds. ## Close Operation @@ -104,7 +104,7 @@ Two close paths exist: | Cooperative close | A participant submits a state with the `CLOSE` intent, signed by all participants. | | Unilateral close | After challenge expiry, any party MAY call close without additional signatures. Funds are released according to the last enforced state's allocations. | -It is not possible to close an already `CLOSED` or `MIGRATED_OUT` channel. In both close paths, locked funds are set to zero and the channel lifecycle ends. +It is not possible to close an already `closed` channel. In both close paths, locked funds are set to zero and the channel lifecycle ends. ## Enforcement Validation @@ -122,14 +122,13 @@ The blockchain layer applies common validation rules when processing enforcement ## Escrow and Migration Enforcement -| Operation | On-chain effect | +Escrow and migration transitions are part of the protocol model, but their public app-builder workflow is not documented yet. Treat the enforcement details as protocol reference material, not as instructions for constructing escrow or migration states by hand. + +| Operation family | Enforcement note | | --- | --- | -| Escrow Deposit Initiate | On home chain: state updated, Node funds adjusted. On non-home chain: escrow record created, User funds locked. | -| Escrow Deposit Finalize | On home chain: state updated, User allocation increased. On non-home chain: escrowed funds released to the Node's vault. | -| Escrow Withdrawal Initiate | On home chain: state updated. On non-home chain: escrow record created, Node funds locked from vault. | -| Escrow Withdrawal Finalize | On home chain: state updated, User allocation decreased. On non-home chain: escrowed funds released to User. | -| Migration Initiate | On old home chain: state updated. On new home chain: channel created with migrating-in status, Node funds locked. | -| Migration Finalize | On new home chain: channel transitions to operating. On old home chain: all locked funds released, channel marked as migrated out. | +| Escrow deposit | Initiate and finalize states coordinate home-ledger accounting with a non-home-chain escrow record. | +| Escrow withdrawal | Initiate and finalize states coordinate home-ledger accounting with non-home-chain release. | +| Migration | Initiate and finalize states move the home-chain enforcement target while preserving normalized user allocation. | ## Failure Conditions diff --git a/docs/nitrolite/protocol/interaction-model.mdx b/docs/nitrolite/protocol/interaction-model.mdx index 41aa59a..f074696 100644 --- a/docs/nitrolite/protocol/interaction-model.mdx +++ b/docs/nitrolite/protocol/interaction-model.mdx @@ -1,6 +1,6 @@ --- title: "Interaction Model" -description: "Transport-independent message envelope, core operations, event messages, correlation, error handling, and ordering." +description: "Transport-independent message envelope, core operations, response correlation, error handling, and ordering." --- # Interaction Model @@ -45,7 +45,7 @@ Messages are encoded as compact ordered arrays: | --- | | Request | | Successful response | -| Event notification | +| Reserved event notification | | Error response | :::note Events @@ -110,6 +110,6 @@ Rules: Message ordering requirements MAY depend on implementation. These protocol-level constraints apply: - `RequestId` values MUST NOT be reused within a single connection. -- Events MAY arrive at any time and MUST NOT block request processing. +- Future event notifications, once specified, MUST NOT block request processing. State update ordering is governed by channel state versioning and advancement rules, not by the message transport layer. diff --git a/docs/nitrolite/protocol/security-and-limitations.mdx b/docs/nitrolite/protocol/security-and-limitations.mdx index cd90f72..5225ffa 100644 --- a/docs/nitrolite/protocol/security-and-limitations.mdx +++ b/docs/nitrolite/protocol/security-and-limitations.mdx @@ -48,7 +48,7 @@ The blockchain layer provides: ## Node Liquidity and Cross-Chain Trust -Each User channel is opened with a Node. To maintain cross-chain functionality, the Node MUST hold sufficient liquidity on each supported blockchain to satisfy off-chain state allocations. +Each User channel is opened with a Node. Cross-chain functionality depends on the Node operator maintaining enough liquidity on each supported blockchain to satisfy off-chain state allocations. When a User with home chain A transfers assets to a User with home chain B, the Node receives the amount on chain A and allocates from its own balance to the recipient on chain B. If the recipient later enforces state on chain B and the Node lacks sufficient liquidity there, on-chain enforcement will fail. @@ -58,10 +58,10 @@ In the current protocol version, users rely on the Node operator to maintain ade ## Current Trust Assumptions -Participants MUST trust Nodes for: +Participants currently rely on Nodes for: -- **Liveness**: Nodes MUST be online to facilitate off-chain state advancement. -- **Cross-chain liquidity**: Nodes MUST maintain sufficient funds on each supported chain to honor off-chain allocations. +- **Liveness**: Nodes need to be online to facilitate off-chain state advancement. +- **Cross-chain liquidity**: Node operators need sufficient funds on each supported chain to honor off-chain allocations. - **Cross-chain relay**: Nodes relay cross-chain state updates; trustless cross-chain enforcement is not yet implemented. - **Timely enforcement**: Nodes are expected to submit checkpoints when requested. diff --git a/docs/nitrolite/protocol/state-and-ledger-model.mdx b/docs/nitrolite/protocol/state-and-ledger-model.mdx index 3020e97..4e791f9 100644 --- a/docs/nitrolite/protocol/state-and-ledger-model.mdx +++ b/docs/nitrolite/protocol/state-and-ledger-model.mdx @@ -117,21 +117,25 @@ Because this mapping is deterministic, signatures over off-chain state are valid ## Intent Mapping -| On-chain intent | Transition | -| --- | --- | -| `OPERATE` | TransferSend, TransferReceive, Commit, Release, Acknowledgement | -| `CLOSE` | Finalize | -| `DEPOSIT` | Home Deposit | -| `WITHDRAW` | Home Withdrawal | -| `INITIATE_ESCROW_DEPOSIT` | Escrow Deposit Initiate | -| `FINALIZE_ESCROW_DEPOSIT` | Escrow Deposit Finalize | -| `INITIATE_ESCROW_WITHDRAWAL` | Escrow Withdrawal Initiate | -| `FINALIZE_ESCROW_WITHDRAWAL` | Escrow Withdrawal Finalize | -| `INITIATE_MIGRATION` | Migration Initiate | -| `FINALIZE_MIGRATION` | Migration Finalize | +| On-chain intent | Transition literal | Meaning | +| --- | --- | --- | +| `OPERATE` | `transfer_send` | Sender-side off-chain transfer. | +| `OPERATE` | `transfer_receive` | Receiver-side off-chain transfer. | +| `OPERATE` | `commit` | Move channel funds into an app session or extension. | +| `OPERATE` | `release` | Return app-session or extension funds to the channel. | +| `CLOSE` | `finalize` | Finalize and close the channel. | +| `DEPOSIT` | `home_deposit` | Deposit on the home chain. | +| `WITHDRAW` | `home_withdrawal` | Withdraw on the home chain. | +| `INITIATE_ESCROW_DEPOSIT` | `mutual_lock` | Escrow deposit initiate. | +| `FINALIZE_ESCROW_DEPOSIT` | `escrow_deposit` | Escrow deposit finalize or complete. | +| `INITIATE_ESCROW_WITHDRAWAL` | `escrow_lock` | Escrow withdrawal initiate. | +| `FINALIZE_ESCROW_WITHDRAWAL` | `escrow_withdraw` | Escrow withdrawal finalize or complete. | +| `INITIATE_MIGRATION` | `migrate` | Home-chain migration initiate. | Transitions that map to `OPERATE` do not require on-chain checkpointing under normal operation. +Escrow and migration transition names are included for protocol accuracy. Their public app-builder workflow is not documented yet. + ## Transition Field Each state update includes a transition describing the operation that produced the new state. diff --git a/docs/nitrolite/protocol/terminology.mdx b/docs/nitrolite/protocol/terminology.mdx index 8af1552..2390b3c 100644 --- a/docs/nitrolite/protocol/terminology.mdx +++ b/docs/nitrolite/protocol/terminology.mdx @@ -73,7 +73,7 @@ Each unified asset defines a canonical decimal precision used during protocol in | --- | --- | | Mutually Signed State | A state that carries valid signatures from both the User and the Node. Only mutually signed states are enforceable on-chain. | | Node-Issued Pending State | A state produced by the Node that carries only the Node's signature. A pending state is NOT enforceable on-chain and becomes mutually signed only after the User acknowledges it. | -| Channel Status | A specific on-chain channel data configuration throughout the lifecycle, including operating, disputed, migrating-in, and migrated-out statuses. | +| Channel Status | A specific on-chain channel data configuration throughout the lifecycle, including open, challenged, closing, and closed states. | | Escrow Channel Identifier | A 32-byte hash derived deterministically from the home channel identifier and state version. It uniquely identifies each escrow operation. | ## Protocol Operations diff --git a/sidebars-nitrolite.ts b/sidebars-nitrolite.ts index d895ee5..dc44592 100644 --- a/sidebars-nitrolite.ts +++ b/sidebars-nitrolite.ts @@ -20,6 +20,7 @@ const sidebars: SidebarsConfig = { id: 'learn/index', label: 'Learn', }, + 'learn/migrating-from-0.5.3', { type: 'category', label: 'Introduction', @@ -37,6 +38,7 @@ const sidebars: SidebarsConfig = { 'learn/core-concepts/state-channels-vs-l1-l2', 'learn/core-concepts/challenge-response', 'learn/core-concepts/yellow-token', + 'learn/glossary', ], collapsed: false, }, From 9b1dcc861a98c22e3bd1d83d59ef1a5a178c86d4 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Wed, 20 May 2026 08:00:38 +0530 Subject: [PATCH 2/5] docs(nitrolite): add v053 mental model guide --- docs/nitrolite/learn/index.mdx | 7 +- docs/nitrolite/learn/whats-new-from-0.5.3.mdx | 115 ++++++++++++++++++ sidebars-nitrolite.ts | 1 + 3 files changed, 121 insertions(+), 2 deletions(-) create mode 100644 docs/nitrolite/learn/whats-new-from-0.5.3.mdx diff --git a/docs/nitrolite/learn/index.mdx b/docs/nitrolite/learn/index.mdx index 34ff5ad..61779bb 100644 --- a/docs/nitrolite/learn/index.mdx +++ b/docs/nitrolite/learn/index.mdx @@ -15,7 +15,7 @@ Welcome to the Yellow Network learning path. This section builds your understand Yellow Network is decentralized clearing and settlement infrastructure that operates as a Layer 3 overlay on existing blockchains. It lets businesses, exchanges, and application developers move digital assets through signed channel states. Independent node operators run open-source Nitronode software supplied by Layer3 Fintech Ltd. The SDK and developer tools are open-source and free. :::info What changed in v1 -The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and app sessions. If you are coming from `@erc7824/nitrolite@0.5.3`, start with [Migrating from 0.5.3](./migrating-from-0.5.3). +The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and app sessions. If you are coming from `@erc7824/nitrolite@0.5.3`, start with [What Changed Since 0.5.3](./whats-new-from-0.5.3) before opening the code migration guide. ::: ## Introduction @@ -46,7 +46,9 @@ The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and ap ## Migration -**[Migrating from 0.5.3](./migrating-from-0.5.3.mdx)**: Choose the compat-first or native v1 migration path from `@erc7824/nitrolite@0.5.3`. +**[What Changed Since 0.5.3](./whats-new-from-0.5.3.mdx)**: Learn the v1 mental model before changing code: Clearnode is now Nitronode, ChannelHub replaces Custody, and app sessions sit on top of home channels. + +**[Migrating from 0.5.3](./migrating-from-0.5.3.mdx)**: Choose the compat-first or native v1 code migration path from `@erc7824/nitrolite@0.5.3`. ## Next Steps @@ -68,6 +70,7 @@ After completing the Learn section, continue to: | [Challenge-Response](./core-concepts/challenge-response) | 6 min | Intermediate | | [YELLOW Token](./core-concepts/yellow-token) | 8 min | Intermediate | | [Glossary](./glossary) | 5 min | Beginner | +| [What Changed Since 0.5.3](./whats-new-from-0.5.3) | 8 min | Beginner | | [Migrating from 0.5.3](./migrating-from-0.5.3) | 10 min | Intermediate | | [Protocol Architecture](./protocol-flows/architecture) | 10 min | Intermediate | | [Transfer Flow](./protocol-flows/transfer-flow) | 12 min | Advanced | diff --git a/docs/nitrolite/learn/whats-new-from-0.5.3.mdx b/docs/nitrolite/learn/whats-new-from-0.5.3.mdx new file mode 100644 index 0000000..546d2ca --- /dev/null +++ b/docs/nitrolite/learn/whats-new-from-0.5.3.mdx @@ -0,0 +1,115 @@ +--- +title: What Changed Since 0.5.3 +description: Mental model changes for builders moving from @erc7824/nitrolite 0.5.3 to Nitrolite v1. +sidebar_position: 5 +--- + +# What Changed Since 0.5.3 + +If you built with `@erc7824/nitrolite@0.5.3`, v1 can feel like a lot changed at once. The important shift is not that the old model was wrong. v1 moves responsibilities into clearer layers so app code can work closer to the channel and app-session lifecycle. + +This page is a no-code orientation. Read it before the code migration guide if you want the new vocabulary and product shape to feel familiar first. + +## You are still building the same kind of app + +The goal is the same: move value through fast off-chain updates while keeping an on-chain recovery path. Your users should not wait for a blockchain transaction for every app action, and the latest mutually signed state should still be enforceable if cooperation fails. + +In 0.5.3, many apps learned this through Clearnode, unified balances, explicit auth helpers, channel resize flows, and WebSocket notifications. In v1, the same safety goal is expressed through Nitronode, home channels, app sessions, signed state advancement, and ChannelHub enforcement. + +## Names changed, roles got clearer + +| 0.5.3 term | v1 term | How to think about it | +| --- | --- | --- | +| Clearnode | Nitronode | The off-chain coordinator your SDK connects to. It serves v1 RPC, validates transitions, co-signs valid states, and coordinates app sessions. | +| Custody | ChannelHub | The on-chain enforcement entrypoint for channel create, deposit, withdraw, checkpoint, challenge, and close operations. | +| Adjudicator | ChannelHub validators and engine logic | Validation moved into the v1 engine and signature-validator model instead of app code naming an adjudicator contract directly. | +| Virtual app | App session | The app-specific off-chain state extension funded from channel balances. | +| NitroRPC 0.4 helper methods | v1 RPC namespaces | Wire methods are grouped as `channels.v1.*`, `app_sessions.v1.*`, `apps.v1.*`, `user.v1.*`, and `node.v1.*`. Most builders should call them through an SDK. | + +The biggest practical rename is Clearnode to Nitronode. If old docs said "connect to Clearnode", the v1 equivalent is "connect to Nitronode". + +## What moved into the SDK + +In many 0.5.3 integrations, app code owned the whole pipeline: open a WebSocket, build a helper message, sign it, send it, parse the response, and listen for pushed updates. + +In v1, the SDK owns more of that plumbing: + +- connection setup and request correlation +- envelope framing and method names +- state signing and transaction signing +- Nitronode config and asset metadata lookup +- amount conversion for high-level calls +- typed errors and safer recovery paths + +That means app code can focus on business intent: prepare a home channel, commit funds into an app session, operate, withdraw, close, and query final state. + +## Authentication did not disappear + +The old front door was explicit: `auth_request`, `auth_challenge`, `auth_verify`, JWT reuse, and a session key that signed later RPC requests. That flow still matters for legacy and compat migrations, but it is not the native v1 app front door. + +Native v1 treats authorization as part of signed protocol state. A channel update is accepted because the right participant signed the right state. Session keys still exist, but they are expressed as signed key-state and signature-validation mode, not as a separate auth handshake every app must implement before it can call the SDK. + +The user-facing result should be better: fewer application-owned security decisions, less copied auth code, and clearer boundaries between wallet authority, delegated signing, Nitronode validation, and on-chain enforcement. + +## Home channels come before app sessions + +In 0.5.3, it was natural to think in terms of unified balance plus app-level helper workflows. In v1, start with the channel state: + +| Concept | Role | +| --- | --- | +| Home channel | The user and Nitronode channel for one asset. Deposits, transfers, acknowledgements, checkpoints, and withdrawals update this state. | +| Home ledger | The ledger tied to the chain where the channel state is enforced. | +| App session | An extension that receives committed channel funds and tracks app-specific allocations. | +| Commit and release | The movements between channel funds and app-session funds. | + +An app session does not replace the home channel. It sits on top of channel funds. That is why the native lifecycle first prepares the home channel, then creates and funds an app session. + +## State first, settlement when needed + +v1 separates state advancement from blockchain settlement. A high-level SDK operation can produce a state that both the user and Nitronode have signed. That signed state is useful before it is posted on-chain. + +`checkpoint` is the moment you ask ChannelHub to enforce the latest signed state. For routine app activity, most updates stay off-chain. You checkpoint when the lifecycle requires on-chain enforcement, recovery, or settlement. + +This is the mental model to keep: first agree on state, then settle only when needed. + +## Events become refresh policy + +0.5.3 docs talked about pushed balance, channel, transfer, and app-session updates. In current v1 docs, asynchronous events are reserved for a future protocol revision. Do not build a new v1 app around server-push assumptions. + +Use explicit queries for the state your UI needs. If you are migrating through compat and your old app expects event-shaped callbacks, use the compat polling helper as a bridge while you decide your final refresh policy. + +## Amounts are a boundary + +v1 makes amount boundaries more explicit. Native SDK calls use exact decimal values for builder-facing amounts. RPC payloads use strings. Compat preserves some 0.5.3 amount shapes so older code can move in stages. + +That is intentional. Treat every amount conversion as a boundary between layers, not a formatting detail. During migration, review deposits, withdrawals, transfers, app-session allocations, and security-token calls separately. + +## Compat is scaffolding + +`@yellow-org/sdk-compat` is useful when you need a smaller first step from `@erc7824/nitrolite@0.5.3`. It preserves selected app-facing shapes and routes them through the v1 runtime. + +Compat is not meant to preserve every old behavior forever. Some helper workflows fail fast because there is no honest one-to-one mapping to v1. That is a safety rail: it points you to the place where the app needs a real lifecycle decision. + +Use compat to reduce migration risk. Use native `@yellow-org/sdk` when you are ready to align the app with the v1 model directly. + +## What not to carry forward + +Avoid carrying these assumptions into new v1 code: + +- hard-coded Clearnode, Custody, or Adjudicator addresses in app config +- app-owned WebSocket helper chains as the primary integration model +- server-push updates as the only way to keep UI state fresh +- one global amount format across every method family +- escrow or migration operation guides as current builder flows + +Escrow and migration are protocol concepts, and contract support exists in lower layers. They are not documented as app-builder how-to flows on docs.yellow.org yet. + +## Ready to migrate your code? + +Start with the code migration page when the mental model is clear: + +- [Migrating from 0.5.3](./migrating-from-0.5.3) - choose compat-first or native v1. +- [TypeScript compat SDK](/nitrolite/build/sdk/typescript-compat/overview) - staged migration for existing 0.5.3 apps. +- [Native TypeScript SDK](/nitrolite/build/sdk/typescript/getting-started) - the long-term SDK path for new v1 flows. +- [Quickstart](/nitrolite/build/getting-started/quickstart) - run the tested channel and app-session lifecycle. +- [Key Terms & Mental Models](/nitrolite/build/getting-started/key-terms) - quick vocabulary reference for the v1 SDK docs. diff --git a/sidebars-nitrolite.ts b/sidebars-nitrolite.ts index dc44592..119df4a 100644 --- a/sidebars-nitrolite.ts +++ b/sidebars-nitrolite.ts @@ -20,6 +20,7 @@ const sidebars: SidebarsConfig = { id: 'learn/index', label: 'Learn', }, + 'learn/whats-new-from-0.5.3', 'learn/migrating-from-0.5.3', { type: 'category', From 5d2508ebd628a06b7840f9c67747dfef81092c3c Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 21 May 2026 17:26:40 +0530 Subject: [PATCH 3/5] docs: address PR158 learn protocol review --- .../core-concepts/challenge-response.mdx | 49 ++++++++++--------- .../core-concepts/state-channels-vs-l1-l2.mdx | 8 +-- docs/nitrolite/learn/glossary.mdx | 23 ++++----- docs/nitrolite/learn/index.mdx | 16 +++--- .../introduction/architecture-at-a-glance.mdx | 21 ++++---- .../learn/introduction/what-yellow-solves.mdx | 8 +-- docs/nitrolite/learn/migrating-from-0.5.3.mdx | 6 +-- .../protocol-flows/app-session-deposit.mdx | 2 +- .../learn/protocol-flows/escrow-deposit.mdx | 11 +---- .../protocol-flows/escrow-withdrawal.mdx | 11 +---- .../protocol-flows/home-channel-deposit.mdx | 3 +- .../home-channel-withdrawal.mdx | 15 +++--- .../learn/protocol-flows/transfer-flow.mdx | 5 +- docs/nitrolite/learn/whats-new-from-0.5.3.mdx | 6 +-- docs/nitrolite/protocol/channel-lifecycle.mdx | 26 +++++----- .../protocol/cross-chain-and-assets.mdx | 20 ++++---- .../protocol/enforcement-and-settlement.mdx | 8 +-- docs/nitrolite/protocol/introduction.mdx | 2 +- .../protocol/security-and-limitations.mdx | 5 +- .../protocol/state-and-ledger-model.mdx | 18 ++++--- docs/nitrolite/protocol/terminology.mdx | 4 +- 21 files changed, 126 insertions(+), 141 deletions(-) diff --git a/docs/nitrolite/learn/core-concepts/challenge-response.mdx b/docs/nitrolite/learn/core-concepts/challenge-response.mdx index 7e1c2de..93ad486 100644 --- a/docs/nitrolite/learn/core-concepts/challenge-response.mdx +++ b/docs/nitrolite/learn/core-concepts/challenge-response.mdx @@ -1,38 +1,38 @@ --- sidebar_position: 4 -title: Challenge-Response & Disputes -description: How Yellow Network handles disputes and keeps channel funds recoverable +title: Challenge & Recovery +description: How Yellow Network lets participants recover funds when a counterparty stops cooperating keywords: [challenge, dispute, security, settlement, fund recovery] --- import Tooltip from '@site/src/components/Tooltip'; import { tooltipDefinitions } from '@site/src/constants/tooltipDefinitions'; -# Challenge-Response & Disputes +# Challenge & Recovery -Challenge-response is the on-chain fallback that lets a participant enforce the latest valid channel state if the counterparty stops cooperating. +A challenge is the on-chain fallback that lets a participant recover from an unresponsive or broken counterparty. **Goal**: understand why off-chain updates remain recoverable even when Nitronode is unavailable. --- -## Why Challenge-Response Matters +## Why Challenges Matter -In any off-chain system, a critical question arises: what if someone tries to settle an old state? +In any off-chain system, a critical question arises: what if the counterparty stops signing, stops responding, or tries to use an on-chain state you disagree with? State channels answer this with versioned, signed states: -1. A participant submits a signed state on-chain. -2. The counterparty has a challenge window to respond with a newer valid state. -3. The newest valid state wins. -4. Funds are released according to the final accepted state. +1. Old states cannot replace newer states because versions must increase. +2. A participant can enforce a signed state on-chain when cooperation fails. +3. If a challenge is active, the counterparty has a response window to enforce a newer valid state. +4. If no newer state is accepted before the window expires, the challenged state can be closed. ## Trust Model | Guarantee | How it is achieved | | --- | --- | | **Fund custody** | ChannelHub holds channel funds on-chain, not Nitronode. | -| **State validity** | Only valid signed states can advance the channel. | +| **State validity** | Only states signed by the required participants, with a greater version and correct intent, can advance the channel. | | **Dispute resolution** | A participant can force the latest valid state on-chain. | | **Recovery** | Funds are recoverable from the latest enforceable state. | @@ -49,16 +49,16 @@ Your options: ### Process -1. **Initiate challenge**: submit the latest signed state to ChannelHub. +1. **Initiate challenge**: submit a mutually signed state to ChannelHub with a challenger signature. 2. **Challenge period**: ChannelHub sets the response deadline. -3. **Response window**: a counterparty can submit a newer valid state. -4. **Resolution**: after timeout, the latest accepted state can be closed. +3. **Response window**: a counterparty can enforce a newer mutually signed state. +4. **Resolution**: a newer state returns the channel to `open`; after timeout, the challenged state can be closed. ```mermaid stateDiagram-v2 [*] --> open open --> challenged: challenge - challenged --> open: checkpoint newer state + challenged --> open: enforce newer state challenged --> closed: close after timeout closed --> [*] @@ -69,7 +69,7 @@ stateDiagram-v2 ### States are ordered -Every channel state has a version number. A higher version supersedes a lower version when both states are valid. +Every channel state has a version number. ChannelHub rejects stale submissions that do not advance the version beyond the state already recorded on-chain. ### States are signed @@ -83,14 +83,14 @@ The waiting window gives honest parties time to respond. Network delays should n ChannelHub validates signatures, state version, status, and ledger invariants. It does not rely on Nitronode cooperation once a valid state is submitted. -## Checkpoint vs Challenge +## Enforcement vs Challenge | Operation | Purpose | Channel status | | --- | --- | --- | -| `checkpoint()` | Record a valid state without forcing closure. | Stays `open`. | +| Enforce a signed state | Record a valid state without starting the dispute path. | Stays `open`. | | `challenge()` | Start the on-chain dispute path. | Changes to `challenged`. | -Use checkpoint for safety snapshots. Use challenge when you need to force settlement because a counterparty is not cooperating. +Use ordinary state enforcement when you only need the chain to record a newer state. Use challenge when you need to force recovery because a counterparty is not cooperating. ## What Happens If... @@ -98,17 +98,18 @@ Use checkpoint for safety snapshots. Use challenge when you need to force settle | --- | --- | | **Nitronode goes offline** | Challenge with the latest signed state, then close after timeout. | | **You lose state history** | An older state can be defeated by a newer valid state if the counterparty has it. | -| **Counterparty submits a stale state** | Submit a newer valid state during the challenge window. | -| **Block reorg occurs** | Replay confirmed chain state from the last trusted block. | +| **Counterparty submits a stale state** | ChannelHub rejects it if it does not have a higher version than the current on-chain state. | +| **Counterparty challenges with a stale state** | Enforce a newer valid state during the challenge window to resolve the challenge. | +| **Block reorg occurs** | Wait for the transaction to be included in the canonical chain again. No special challenge action is required only because of a reorg. | ## Key Takeaways | Concept | Remember | | --- | --- | | **Challenge** | Starts on-chain dispute resolution. | -| **Response** | A newer valid state defeats an older challenged state. | -| **Timeout** | After expiry, the accepted state can be closed. | -| **Checkpoint** | Records state without starting the close path. | +| **Response** | A newer mutually signed state resolves an older challenged state. | +| **Timeout** | The time window during which a challenge can be resolved. After expiry, the challenged state can be closed. | +| **Enforcement** | Records state without starting the dispute path. | :::success Security guarantee You can recover funds according to the latest enforceable state even if the off-chain counterparty stops cooperating. diff --git a/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx b/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx index 902e158..dfed213 100644 --- a/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx +++ b/docs/nitrolite/learn/core-concepts/state-channels-vs-l1-l2.mdx @@ -30,9 +30,9 @@ State channels operate on a simple pattern: 1. **Lock funds** in ChannelHub on-chain. 2. **Exchange signed states** off-chain. -3. **Checkpoint, challenge, or close** on-chain when needed. +3. **Enforce, challenge, or close** on-chain when needed. -Most interactions do not need immediate on-chain settlement. The chain is used for funding, checkpoints, disputes, and exits. +Most interactions do not need immediate on-chain settlement. The chain is used for funding, state enforcement, disputes, and exits. ## State Channel Advantages @@ -46,7 +46,7 @@ Most interactions do not need immediate on-chain settlement. The chain is used f ### No gas for ordinary off-chain operations -Once the channel is funded, transfers and app-session updates are signed off-chain. Gas is paid only for on-chain funding, checkpointing, disputes, and exits. +Once the channel is funded, transfers and app-session updates are signed off-chain. Gas is paid only for on-chain funding, state enforcement, disputes, and exits. ### Enforceable settlement @@ -100,7 +100,7 @@ flowchart TD | --- | --- | | Identified counterparties | Nitronode coordinates off-chain channel state advancement. | | Liquidity | Home-channel balances and app sessions keep app funds available off-chain. | -| Enforcement | ChannelHub provides checkpoint, challenge, and close paths. | +| Enforcement | ChannelHub provides state enforcement, challenge, and close paths. | | Developer ergonomics | SDKs build signed requests and typed app-session updates. | ## Key Takeaways diff --git a/docs/nitrolite/learn/glossary.mdx b/docs/nitrolite/learn/glossary.mdx index 199b650..90bd89d 100644 --- a/docs/nitrolite/learn/glossary.mdx +++ b/docs/nitrolite/learn/glossary.mdx @@ -12,20 +12,21 @@ This page defines the terms used across the Nitrolite v1 Learn, Build, Protocol, | Term | Meaning | | --- | --- | -| **App session** | An off-chain application-specific state funded from a channel through `commit` transitions and settled back through `release` transitions. | -| **Asset** | A configured token symbol and decimal model that Nitronode recognizes across supported chains. | +| **App session** | An app-specific off-chain state where users can commit channel funds, exchange app-state signatures, and later release balances back to their home channels. | +| **Asset** | A unified value unit that Nitronode configures across supported chains, such as one canonical `usdc` asset spanning chain-specific USDC tokens. | | **Channel** | A user-node relationship for one asset, with signed state updates and an on-chain enforcement path. | | **Channel state** | The signed record of channel version, transition, ledgers, and participant signatures. | -| **ChannelHub** | The v1 on-chain entrypoint for channel creation, deposits, withdrawals, checkpoints, challenges, and close operations. | -| **Checkpoint** | An on-chain submission that records a valid signed state without necessarily closing the channel. | +| **ChannelHub** | The v1 on-chain enforcement layer for channel creation, deposits, withdrawals, state enforcement, challenges, and close operations. | +| **Checkpoint / enforcement** | An on-chain submission that records a valid signed state without necessarily closing the channel. `checkpoint()` is an SDK or contract entry point for specific enforcement paths. | | **Challenge** | An on-chain dispute path where a participant submits a signed state and gives the counterparty time to respond with a newer valid state. | | **Home channel** | The user's primary channel for a configured asset. | | **Home ledger** | The authoritative ledger for the channel's current enforcement chain. | -| **Nitronode** | The open-source off-chain coordinator that validates state transitions, signs states, and serves v1 RPC. | +| **Nitronode** | The open-source off-chain entrypoint that validates state transitions, signs states, and serves v1 RPC. | | **Non-home ledger** | The secondary ledger used when a cross-chain operation is in progress. It is empty during ordinary same-chain operation. | -| **Pending state** | A Node-issued state with only the Node signature. It becomes enforceable only after the user acknowledges it. | +| **Pending state** | A proposed state that is not enforceable yet because it does not have every required signature. Node-issued pending states commonly wait for user acknowledgement. | | **Quorum** | The signature threshold required by an app session before an app-state update is accepted. | -| **Session key** | A scoped signing key an application can use for app-session updates without asking the wallet to sign every step. | +| **Session key** | A scoped signing key authorized by a participant. It can apply to channel state or app-session state, depending on its signature-validation scope. | +| **Token** | A chain-specific contract or native token instance. A single asset can map to different tokens on different supported chains. | | **Vault** | Node-controlled liquidity used by enforcement and cross-chain accounting paths. | ## Channel Statuses @@ -37,7 +38,6 @@ The v1 RPC status surface uses: | `void` | No channel exists yet. | | `open` | The channel exists and can accept normal state updates. | | `challenged` | A challenge is active and the response window is running. | -| `closing` | The channel is in the close path after a final state or expired challenge. | | `closed` | Funds have been released and the channel lifecycle is complete. | ## Transition Literals @@ -52,13 +52,10 @@ These are the current `transition_type` literals from the v1 API schema. | `commit` | Move funds from the channel into an app session or extension. | | `home_deposit` | Same-chain home-channel deposit. | | `home_withdrawal` | Same-chain home-channel withdrawal. | -| `mutual_lock` | Escrow deposit initiate. | -| `escrow_deposit` | Escrow deposit finalize or complete. | -| `escrow_lock` | Escrow withdrawal initiate. | -| `escrow_withdraw` | Escrow withdrawal finalize or complete. | -| `migrate` | Home-chain migration initiate. | | `finalize` | Finalize and close the channel state. | +Escrow and migration operation names are documented in the Protocol section because they are protocol-level concepts, not current app-builder how-to flows. + ## Amount Units Use the SDK method signature as the source of truth for amount shape: diff --git a/docs/nitrolite/learn/index.mdx b/docs/nitrolite/learn/index.mdx index 61779bb..983dac0 100644 --- a/docs/nitrolite/learn/index.mdx +++ b/docs/nitrolite/learn/index.mdx @@ -28,12 +28,18 @@ The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and ap **[State Channels vs L1/L2](./core-concepts/state-channels-vs-l1-l2.mdx)**: Compare state channels with Layer 1 and Layer 2 solutions. Understand when each approach is the right choice. -**[Challenge-Response & Disputes](./core-concepts/challenge-response.mdx)**: How Yellow Network handles disputes and ensures your funds are recoverable through the latest mutually signed state. +**[Challenge & Recovery](./core-concepts/challenge-response.mdx)**: How Yellow Network handles disputes and ensures your funds are recoverable through the latest mutually signed state. **[YELLOW Token](./core-concepts/yellow-token.mdx)**: The utility token powering network services, node operator collateral, and dispute resolution. **[Glossary](./glossary.mdx)**: Core v1 terms, statuses, transition literals, and amount-unit reminders. +## Migration + +**[What Changed Since 0.5.3](./whats-new-from-0.5.3.mdx)**: Learn the v1 mental model before changing code: Clearnode is now Nitronode, ChannelHub replaces Custody, and app sessions sit on top of home channels. + +**[Migrating from 0.5.3](./migrating-from-0.5.3.mdx)**: Choose the compat-first or native v1 code migration path from `@erc7824/nitrolite@0.5.3`. + ## Protocol Flows **[Protocol Architecture](./protocol-flows/architecture.mdx)**: The Petal Diagram: home chain, cross-chain, transfers, and app sessions. @@ -44,12 +50,6 @@ The v1 protocol uses ChannelHub, Nitronode, channel states, home ledgers, and ap **[App Session Deposit](./protocol-flows/app-session-deposit.mdx)**: Depositing funds into app sessions. -## Migration - -**[What Changed Since 0.5.3](./whats-new-from-0.5.3.mdx)**: Learn the v1 mental model before changing code: Clearnode is now Nitronode, ChannelHub replaces Custody, and app sessions sit on top of home channels. - -**[Migrating from 0.5.3](./migrating-from-0.5.3.mdx)**: Choose the compat-first or native v1 code migration path from `@erc7824/nitrolite@0.5.3`. - ## Next Steps After completing the Learn section, continue to: @@ -67,7 +67,7 @@ After completing the Learn section, continue to: | [What Yellow Solves](./introduction/what-yellow-solves) | 5 min | Beginner | | [Architecture at a Glance](./introduction/architecture-at-a-glance) | 8 min | Beginner | | [State Channels vs L1/L2](./core-concepts/state-channels-vs-l1-l2) | 12 min | Intermediate | -| [Challenge-Response](./core-concepts/challenge-response) | 6 min | Intermediate | +| [Challenge & Recovery](./core-concepts/challenge-response) | 6 min | Intermediate | | [YELLOW Token](./core-concepts/yellow-token) | 8 min | Intermediate | | [Glossary](./glossary) | 5 min | Beginner | | [What Changed Since 0.5.3](./whats-new-from-0.5.3) | 8 min | Beginner | diff --git a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx index a7c76b6..b24d2f2 100644 --- a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx +++ b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx @@ -22,8 +22,8 @@ flowchart TB app --> sdk sdk <-->|"v1 RPC over WebSocket"| node - sdk -->|"deposit, checkpoint, challenge, close"| chain - node -->|"checkpoint and escrow coordination"| chain + sdk -->|"deposit, enforce, challenge, close"| chain + node -->|"state enforcement coordination"| chain chain -->|"events and enforced state"| node ``` @@ -38,7 +38,7 @@ flowchart TB ## ChannelHub -ChannelHub is the v1 on-chain entrypoint for channel enforcement. It works with ChannelEngine, EscrowDepositEngine, EscrowWithdrawalEngine, and signature validators. Builders interact with ChannelHub as the contract that creates channels, processes deposits and withdrawals, checkpoints signed states, accepts challenges, and closes channels. +ChannelHub is the v1 on-chain enforcement layer. It works with ChannelEngine, EscrowDepositEngine, EscrowWithdrawalEngine, and signature validators. Builders interact with ChannelHub as the contract that creates channels, processes deposits and withdrawals, enforces signed states, accepts challenges, and closes channels. ChannelHub validates: @@ -49,7 +49,7 @@ ChannelHub validates: - locked-funds accounting - challenge and close status transitions -Routine transfers and app-session updates are signed off-chain. The blockchain is used for create, deposit, withdraw, checkpoint, challenge, close, escrow, and migration operations. +Routine transfers and app-session updates are signed off-chain. The blockchain is used for create, deposit, withdraw, state enforcement, challenge, close, escrow, and migration operations. --- @@ -64,7 +64,7 @@ Nitronode is operated by an independent node operator using open-source software - validates v1 channel transitions - signs mutually agreed channel states - issues pending receive and release states for user acknowledgement -- coordinates cross-chain escrow and app-session flows +- coordinates app-session flows and, where supported, cross-chain escrow flows - serves v1 RPC methods over WebSocket ### v1 RPC @@ -105,19 +105,18 @@ flowchart TB ## Channel Lifecycle -The v1 RPC currently exposes channel status as `void`, `open`, `challenged`, `closing`, and `closed`. +The v1 RPC currently exposes channel status as `void`, `open`, `challenged`, and `closed`. After a challenge expires, a separate close call can move the channel to `closed`; there is no separate `closing` status in the RPC schema. ```mermaid stateDiagram-v2 [*] --> VOID VOID --> OPEN: create or deposit OPEN --> OPEN: signed off-chain updates - OPEN --> OPEN: checkpoint higher-version state + OPEN --> OPEN: enforce higher-version state OPEN --> CHALLENGED: challenge CHALLENGED --> OPEN: higher-version response - CHALLENGED --> CLOSING: challenge expires; close required - OPEN --> CLOSING: cooperative close - CLOSING --> CLOSED: close transaction releases funds + CHALLENGED --> CLOSED: close after timeout + OPEN --> CLOSED: cooperative close CLOSED --> [*] note right of OPEN: Normal operation happens here @@ -129,7 +128,7 @@ stateDiagram-v2 1. **Create or deposit**: The user and Node sign an initial channel state; a deposit state may be submitted to ChannelHub to lock funds. 2. **Operate**: The user and Node exchange signed states off-chain for transfers, acknowledgements, commits, releases, and other valid transitions. -3. **Checkpoint or challenge**: Any party may enforce the latest mutually signed state if needed. +3. **Enforce or challenge**: Any party may enforce the latest mutually signed state if needed. 4. **Close**: A final signed state or expired challenge releases funds according to the enforced allocation. ## Key Takeaways diff --git a/docs/nitrolite/learn/introduction/what-yellow-solves.mdx b/docs/nitrolite/learn/introduction/what-yellow-solves.mdx index 137d164..7950309 100644 --- a/docs/nitrolite/learn/introduction/what-yellow-solves.mdx +++ b/docs/nitrolite/learn/introduction/what-yellow-solves.mdx @@ -41,7 +41,7 @@ Most interactions between parties do not need immediate on-chain settlement. Con | On-chain moves | Every move requires a transaction. A 40-move game becomes 40+ transactions and repeated gas fees. | | State channel moves | Players lock funds once, sign moves off-chain, and settle the final allocation through one enforceable state. | -State channels let applications execute many signed off-chain operations between occasional on-chain checkpoints. +State channels let applications execute many signed off-chain operations between occasional on-chain enforcement actions. ### What You Get @@ -72,8 +72,8 @@ Typical flow: 1. **Create or deposit into a home channel.** The user approves the ChannelHub spender and submits a signed deposit state. ChannelHub locks the deposited ERC-20 or native ETH amount for that channel. 2. **Transact off-chain.** The user and Nitronode exchange signed channel states for transfers, acknowledgements, commits, releases, and other v1 transitions. -3. **Move across chains through escrow.** Cross-chain deposits and withdrawals use two-phase escrow states that coordinate the home ledger and non-home ledger. -4. **Settle when needed.** Any party may checkpoint, challenge, or close with an enforceable mutually signed state. +3. **Move across chains through escrow where supported.** The protocol defines two-phase escrow states that coordinate the home ledger and non-home ledger, but public builder workflows for escrow are not documented yet. +4. **Settle when needed.** Any party may enforce, challenge, or close with an enforceable mutually signed state. ```mermaid flowchart LR @@ -97,7 +97,7 @@ flowchart LR - **Payments:** Micropayments, streaming payments, P2P transfers, API billing, and content monetization. - **Gaming:** Turn-based wagers, tournament payouts, and in-game economies with instant updates. -- **DeFi:** High-frequency trading, prediction markets, and escrow flows with enforceable settlement. +- **DeFi:** High-frequency trading, prediction markets, and escrow-backed flows once the public builder workflow is available. --- diff --git a/docs/nitrolite/learn/migrating-from-0.5.3.mdx b/docs/nitrolite/learn/migrating-from-0.5.3.mdx index 9b6e3f4..f09ba25 100644 --- a/docs/nitrolite/learn/migrating-from-0.5.3.mdx +++ b/docs/nitrolite/learn/migrating-from-0.5.3.mdx @@ -10,7 +10,7 @@ If your application uses `@erc7824/nitrolite@0.5.3`, choose one of two migration | Path | Use when | | --- | --- | -| **Compat first** | You need the smallest migration and want familiar helper shapes while moving to the v1 package family. | +| **Compat first** | You need the smallest migration and want familiar helper shapes while moving to the v1 package family. Treat it as a bridge, not the long-term endpoint. | | **Native v1** | You are building new flows or can afford to adopt the v1 SDK model directly. | ## Path 1: Compat First @@ -25,7 +25,7 @@ Start here: - [On-chain migration](/nitrolite/build/sdk/typescript-compat/migration-onchain) - [Errors and recovery](/nitrolite/build/sdk/typescript-compat/errors) -Compat does not preserve every old behavior. In particular, fail-fast calls, amount units, polling, and server-push assumptions need deliberate review. Follow the migration pages before changing production code. +Compat does not preserve every old behavior. In particular, fail-fast calls, polling, and server-push assumptions need deliberate review. It formats known compat surfaces for v1, but you should still review every amount boundary where your app crosses between compat calls, native SDK calls, RPC payloads, and UI display. Follow the migration pages before changing production code. ## Path 2: Native v1 @@ -52,7 +52,7 @@ Native v1 is the default long-term path. It exposes the current channel and app- ## Migration Checklist -1. Pick compat-first or native v1. +1. Pick compat-first or native v1. Prefer native v1 as the final model once the staged migration is stable. 2. Replace package imports. 3. Review amount units for every transfer, deposit, withdrawal, and app-session call. 4. Replace server-push assumptions with explicit queries or the supported polling helper. diff --git a/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx b/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx index 9f99416..6ccff0b 100644 --- a/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/app-session-deposit.mdx @@ -297,7 +297,7 @@ sequenceDiagram | Transition | From / To | Purpose | | --- | --- | --- | | `commit` | Unified Balance to App Session | Lock funds for deposit | -| `release` | App Session to Unified Balance | Unlock funds on withdraw | +| `release` | App Session to Unified Balance | Return funds on withdraw | ### Why Two States? diff --git a/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx b/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx index 8b82f6f..63cdaa4 100644 --- a/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/escrow-deposit.mdx @@ -21,16 +21,9 @@ The conceptual model is still useful when reading protocol material: - Nitronode coordinates signed off-chain state updates and on-chain settlement paths. - The home ledger remains the user's canonical app balance for that asset. -## Transition names +## Protocol reference -The current schema names the two escrow-deposit transitions as: - -| Transition | Meaning | -| --- | --- | -| `mutual_lock` | Escrow deposit initiate. The parties prepare the locked state needed for the cross-chain deposit path. | -| `escrow_deposit` | Escrow deposit finalize. The deposit is completed into the home-ledger accounting model. | - -These names are included so readers can recognize them in protocol and API reference material. They are not instructions to assemble escrow deposit states by hand. +Protocol-level operation names and invariants live in [Cross-chain and Assets](/nitrolite/protocol/cross-chain-and-assets). This Learn page intentionally avoids escrow state construction steps until the public Nitronode workflow is documented. ## Current builder guidance diff --git a/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx b/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx index 82e7271..3ac4d73 100644 --- a/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx +++ b/docs/nitrolite/learn/protocol-flows/escrow-withdrawal.mdx @@ -21,16 +21,9 @@ The conceptual model is still useful when reading protocol material: - Nitronode coordinates signed off-chain state updates and on-chain settlement paths. - Applications should not ask users to run escrow withdrawal state construction manually. -## Transition names +## Protocol reference -The current schema names the two escrow-withdrawal transitions as: - -| Transition | Meaning | -| --- | --- | -| `escrow_lock` | Escrow withdrawal initiate. Funds are prepared for the cross-chain withdrawal path. | -| `escrow_withdraw` | Escrow withdrawal finalize. The withdrawal is completed toward the non-home-chain destination. | - -These names are included so readers can recognize them in protocol and API reference material. They are not instructions to assemble escrow withdrawal states by hand. +Protocol-level operation names and invariants live in [Cross-chain and Assets](/nitrolite/protocol/cross-chain-and-assets). This Learn page intentionally avoids escrow state construction steps until the public Nitronode workflow is documented. ## Current builder guidance diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx index 933ad56..6890a2c 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-deposit.mdx @@ -51,7 +51,7 @@ Before the home channel deposit flow begins: 5. **No ongoing operation** exists for this channel (the Nitronode will deny the request otherwise). :::note -The "no ongoing operation" requirement applies to ALL operations except `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. +The "no ongoing operation" requirement applies to ALL operations except the RPC operation names `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. Those names describe protocol/RPC surfaces, not current app-builder escrow or migration how-to steps. ::: --- @@ -64,7 +64,6 @@ The "no ongoing operation" requirement applies to ALL operations except `finaliz | --- | --- | --- | | **home_deposit** | External to Channel | `createChannel` (first deposit) or `depositToChannel` | | **home_withdrawal** | Channel to External | `withdrawFromChannel` (can also be done with `createChannel`) | -| **escrow_withdraw** | Channel to Non-Home Chain | `initiateEscrowWithdrawal` | ### The depositToChannel Mechanism diff --git a/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx b/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx index ebecc16..480c0dd 100644 --- a/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx +++ b/docs/nitrolite/learn/protocol-flows/home-channel-withdrawal.mdx @@ -8,7 +8,7 @@ sidebar_position: 6 This document provides a comprehensive breakdown of the **Home Channel Withdrawal** flow as defined in the Nitrolite v1.0 protocol. This operation allows a user to withdraw funds from their **unified balance** back to their wallet on the **Home Chain** -- the blockchain where their channel currently exists. -This is a **single-chain operation** that updates the state and checkpoints it on-chain to release funds. +This is a **single-chain operation** that updates the state and enforces it on-chain to release funds. :::note The Home Chain may differ from where the channel was originally created, as users can migrate their Home Chain explicitly. @@ -51,7 +51,7 @@ Before the home channel withdrawal flow begins: 5. **No ongoing operation** exists for this channel (the Nitronode will deny the request otherwise). :::note -The "no ongoing operation" requirement applies to ALL operations except `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. +The "no ongoing operation" requirement applies to ALL operations except the RPC operation names `finalize_escrow_deposit`, `finalize_escrow_withdrawal`, and `finalize_migration`. Those names describe protocol/RPC surfaces, not current app-builder escrow or migration how-to steps. ::: --- @@ -64,7 +64,6 @@ The "no ongoing operation" requirement applies to ALL operations except `finaliz | --- | --- | --- | | **home_deposit** | External to Channel | `createChannel` (first deposit) or `depositToChannel` | | **home_withdrawal** | Channel to External | `withdrawFromChannel` (can also be done with `createChannel`) | -| **escrow_withdraw** | Channel to Non-Home Chain | `finalizeEscrowWithdrawal` or `initiateEscrowWithdrawal` | ### The withdrawFromChannel Mechanism @@ -211,7 +210,7 @@ A state with intent `WITHDRAW` must include a negative user net-flow delta and m --- -## Phase 5: On-Chain Checkpoint +## Phase 5: On-Chain Enforcement ```mermaid sequenceDiagram @@ -338,14 +337,14 @@ sequenceDiagram flowchart LR A["Current State
(balance: 100)"] --> B["home_withdrawal
Transition (50)"] B --> C["New State
(balance: 50)"] - C --> D["Checkpoint
On-Chain"] + C --> D["Enforce
On-Chain"] D --> E["Funds Released
to User Wallet"] style A fill:#4caf50 style E fill:#2196f3 ``` -### Withdrawal vs Checkpoint +### Withdrawal vs Enforcement | Aspect | Description | | --- | --- | @@ -376,7 +375,7 @@ Without the on-chain withdrawal call, the withdrawal is only recorded off-chain. ### What Protects the User? 1. **Dual signatures** -- Both User and Node must agree to the state. -2. **On-chain enforcement** -- Checkpoint validates all signatures. +2. **On-chain enforcement** -- ChannelHub validates all signatures. 3. **Challenge mechanism** -- User can challenge if Node misbehaves. --- @@ -389,7 +388,7 @@ Without the on-chain withdrawal call, the withdrawal is only recorded off-chain. | **Ongoing transition** | Atomic operation in progress | Wait for completion | | **Invalid signature** | Corrupted or wrong key | Regenerate signature | | **Stale version** | Race condition | Refetch state and retry | -| **Checkpoint revert** | On-chain validation failure | Check state validity | +| **Enforcement revert** | On-chain validation failure | Check state validity | --- diff --git a/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx b/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx index c6a5bfa..753082b 100644 --- a/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx +++ b/docs/nitrolite/learn/protocol-flows/transfer-flow.mdx @@ -206,7 +206,7 @@ The Node checks that there are no pending/incomplete transitions for this user. :::warning If there's an ongoing transition, the Nitronode will return a relevant error and the submission is rejected. -**Serialized operations**: Nitronode does not accept a transfer while another state transition is still pending for the same user and asset. Escrow and migration transitions are not documented as builder-facing workflows yet, but they follow the same rule: finish or acknowledge the pending state before submitting a normal transfer. +**Serialized operations**: Nitronode advances one state at a time for the same user and asset. It rejects a transfer if an earlier state transition is still pending, because accepting both would make the final version order ambiguous. Escrow and migration are protocol-defined but not current builder-facing workflows; the same sequencing rule applies when those paths are enabled. ::: :::info @@ -413,8 +413,7 @@ sequenceDiagram | `commit` | Commit funds to lock | | `home_deposit` | Deposit to home channel | | `home_withdrawal` | Withdraw from home channel | -| `escrow_deposit/lock/withdraw` | Escrow channel operations | -| `migrate` | Cross-chain migration | +| Escrow and migration operations | Protocol-defined, not current builder-facing workflows | --- diff --git a/docs/nitrolite/learn/whats-new-from-0.5.3.mdx b/docs/nitrolite/learn/whats-new-from-0.5.3.mdx index 546d2ca..b176b4a 100644 --- a/docs/nitrolite/learn/whats-new-from-0.5.3.mdx +++ b/docs/nitrolite/learn/whats-new-from-0.5.3.mdx @@ -21,7 +21,7 @@ In 0.5.3, many apps learned this through Clearnode, unified balances, explicit a | 0.5.3 term | v1 term | How to think about it | | --- | --- | --- | | Clearnode | Nitronode | The off-chain coordinator your SDK connects to. It serves v1 RPC, validates transitions, co-signs valid states, and coordinates app sessions. | -| Custody | ChannelHub | The on-chain enforcement entrypoint for channel create, deposit, withdraw, checkpoint, challenge, and close operations. | +| Custody | ChannelHub | The on-chain enforcement layer for channel create, deposit, withdraw, state enforcement, challenge, and close operations. | | Adjudicator | ChannelHub validators and engine logic | Validation moved into the v1 engine and signature-validator model instead of app code naming an adjudicator contract directly. | | Virtual app | App session | The app-specific off-chain state extension funded from channel balances. | | NitroRPC 0.4 helper methods | v1 RPC namespaces | Wire methods are grouped as `channels.v1.*`, `app_sessions.v1.*`, `apps.v1.*`, `user.v1.*`, and `node.v1.*`. Most builders should call them through an SDK. | @@ -57,7 +57,7 @@ In 0.5.3, it was natural to think in terms of unified balance plus app-level hel | Concept | Role | | --- | --- | -| Home channel | The user and Nitronode channel for one asset. Deposits, transfers, acknowledgements, checkpoints, and withdrawals update this state. | +| Home channel | The user and Nitronode channel for one asset. Deposits, transfers, acknowledgements, enforcement submissions, and withdrawals update this state. | | Home ledger | The ledger tied to the chain where the channel state is enforced. | | App session | An extension that receives committed channel funds and tracks app-specific allocations. | | Commit and release | The movements between channel funds and app-session funds. | @@ -68,7 +68,7 @@ An app session does not replace the home channel. It sits on top of channel fund v1 separates state advancement from blockchain settlement. A high-level SDK operation can produce a state that both the user and Nitronode have signed. That signed state is useful before it is posted on-chain. -`checkpoint` is the moment you ask ChannelHub to enforce the latest signed state. For routine app activity, most updates stay off-chain. You checkpoint when the lifecycle requires on-chain enforcement, recovery, or settlement. +State enforcement is the moment you ask ChannelHub to record the latest signed state on-chain. For routine app activity, most updates stay off-chain. You enforce a state when the lifecycle requires on-chain recovery or settlement. SDK and contract surfaces may still call a specific enforcement path `checkpoint()`. This is the mental model to keep: first agree on state, then settle only when needed. diff --git a/docs/nitrolite/protocol/channel-lifecycle.mdx b/docs/nitrolite/protocol/channel-lifecycle.mdx index 753269b..85b1891 100644 --- a/docs/nitrolite/protocol/channel-lifecycle.mdx +++ b/docs/nitrolite/protocol/channel-lifecycle.mdx @@ -1,6 +1,6 @@ --- title: "Channel Lifecycle" -description: "Channel definition, identifiers, lifecycle actions, signing categories, transition families, and checkpoint-relevant transitions." +description: "Channel definition, identifiers, lifecycle actions, signing categories, transition families, and enforcement-relevant transitions." --- # Channel Lifecycle @@ -38,20 +38,20 @@ This ensures that each channel definition produces a unique identifier, that the ```mermaid stateDiagram-v2 [*] --> Create - Create --> Checkpoint: enforce signed state + Create --> Enforced: enforce signed state Create --> Close: cooperative close - Checkpoint --> Checkpoint: higher-version state - Checkpoint --> Challenge: participant dispute - Challenge --> Checkpoint: higher-version response + Enforced --> Enforced: higher-version state + Enforced --> Challenge: participant dispute + Challenge --> Enforced: higher-version response Challenge --> Close: challenge expires - Checkpoint --> Close: final signed state + Enforced --> Close: final signed state Close --> [*] ``` | Action | Context | Rule | | --- | --- | --- | | Create | Off-chain, then optionally on-chain | The Node validates and stores the channel definition. An initial state is constructed and signed by all participants. The initial state, or any later higher-version state, MAY be submitted for on-chain enforcement. | -| Checkpoint | Off-chain, then optionally on-chain | The Node validates and stores a new state off-chain. Depending on transition type or participant initiative, the state MAY also be submitted to the blockchain layer. | +| State enforcement | Off-chain, then optionally on-chain | The Node validates and stores a new state off-chain. Depending on transition type or participant initiative, the state MAY also be submitted to the blockchain layer. | | Challenge | On-chain only | A participant submits a signed state plus challenger signature. The challenge duration begins, and other participants MAY respond with a higher-version state. | | Close | Off-chain for cooperative agreement, on-chain for execution | A close finalizes the channel and releases funds according to final state allocations. | @@ -95,8 +95,8 @@ For all transitions that do not modify the non-home ledger, the non-home ledger | Transition | Core rule | | --- | --- | | Acknowledgement | Allows the User to acknowledge a pending Node-issued state. Valid only when the current state has no User signature. | -| Home Deposit | Records an asset deposit from the home chain. `AccountId` MUST reference the home channel identifier. Requires an on-chain checkpoint to lock deposited assets. | -| Home Withdrawal | Records an asset withdrawal to the home chain. `AccountId` MUST reference the home channel identifier. Requires an on-chain checkpoint to release withdrawn assets. | +| Home Deposit | Records an asset deposit from the home chain. `AccountId` MUST reference the home channel identifier. Requires on-chain enforcement to lock deposited assets. | +| Home Withdrawal | Records an asset withdrawal to the home chain. `AccountId` MUST reference the home channel identifier. Requires on-chain enforcement to release withdrawn assets. | | TransferSend | Transfers assets from the User to a counterparty through the Node. `TxId` correlates with the receiver's TransferReceive. | | TransferReceive | Records inbound transfer from a counterparty through the Node. Amount and `TxId` MUST match the sender's TransferSend. It is a Node-issued pending state. | | Commit | Moves assets from the channel into an extension. `AccountId` MUST reference the extension object identifier. | @@ -121,11 +121,11 @@ Certain transitions produce side effects that create or modify states in other c - **Release**: when an extension releases assets, the Node MUST atomically create the Release state on the User's channel. - **Cross-chain escrow transitions**: escrow initiate and finalize operations MAY trigger on-chain actions that MUST be coordinated with the off-chain state change. -## Checkpoint-Relevant Transitions +## Enforcement-Relevant Transitions -These transitions require or MAY trigger a checkpoint because their intent does not map to `OPERATE`: +These transitions require or MAY trigger on-chain enforcement because their intent does not map to `OPERATE`: -| Transition | Intent | Checkpoint behavior | +| Transition | Intent | Enforcement behavior | | --- | --- | --- | | Home Deposit | `DEPOSIT` | Required to lock deposited assets. | | Home Withdrawal | `WITHDRAW` | Required to release withdrawn assets. | @@ -137,4 +137,4 @@ These transitions require or MAY trigger a checkpoint because their intent does | Migration Finalize | `FINALIZE_MIGRATION` | Required to complete chain migration. | | Finalize | `CLOSE` | Required to settle and release funds. | -Any transition MAY also be checkpointed at a participant's discretion to enforce the current state on-chain. Any party MAY independently submit a validly signed state to the blockchain layer. +Any transition MAY also be enforced at a participant's discretion to record the current state on-chain. Any party MAY independently submit a validly signed state to the blockchain layer. diff --git a/docs/nitrolite/protocol/cross-chain-and-assets.mdx b/docs/nitrolite/protocol/cross-chain-and-assets.mdx index 3ba4ca4..a842871 100644 --- a/docs/nitrolite/protocol/cross-chain-and-assets.mdx +++ b/docs/nitrolite/protocol/cross-chain-and-assets.mdx @@ -55,7 +55,7 @@ The home chain MAY change through a migration operation. After migration, the ne | Ledger | Responsibilities | | --- | --- | -| Home Ledger | Tracks authoritative asset allocations, receives checkpoints for enforcement, and holds deposited assets in the enforcement contract. | +| Home Ledger | Tracks authoritative asset allocations, receives state enforcement submissions, and holds deposited assets in the enforcement contract. | | Non-Home Ledger | Tracks assets involved in cross-chain escrow operations, reflects cross-chain deposit and withdrawal allocations, and coordinates with the home ledger. | When no cross-chain operation is in progress, the non-home ledger MUST be empty. @@ -71,23 +71,23 @@ Each escrow is identified by an escrow channel identifier derived deterministica | Identifier | 32-byte hash derived from home channel identifier and state version. | | Hosting chain | Non-home chain. For deposits, this is where User funds are locked. For withdrawals, this is where Node funds are locked. | | Tracked amount | Amount locked in escrow, corresponding to non-home ledger allocations. | -| Unlock delay | Deposit escrows include an unlock delay after which funds are automatically unlocked to the Node if not challenged. | +| Release delay | Deposit escrows include a release delay after which funds are automatically returned to the Node if not challenged. | | Challenge duration | Period after challenge initiation that allows resolution. If no finalization state is supplied, the initiate state is finalized and funds are returned. | An escrow is not a separate protocol entity with its own state. It is an on-chain record derived from a channel state transition. :::caution Builder workflow not documented yet -Escrow and migration mechanics can be supported by the protocol, but docs.yellow.org does not yet document them as public app-builder workflows. The sections below define the semantic model only. +Escrow and migration are defined by the protocol, but the current Nitronode public app-builder workflow does not implement them yet. The sections below define the semantic model only. ::: ## Cross-Chain Deposit Cross-chain deposit is represented as a two-phase escrow family: -| Phase | Transition literal | Meaning | +| Phase | Protocol operation | Meaning | | --- | --- | --- | -| Initiate | `mutual_lock` | Escrow deposit initiate. | -| Finalize | `escrow_deposit` | Escrow deposit finalize or complete. | +| Initiate | `initiate_escrow_deposit` | Escrow deposit initiate. | +| Finalize | `finalize_escrow_deposit` | Escrow deposit finalize or complete. | Cross-chain amounts are validated using WAD normalization. @@ -95,14 +95,14 @@ Cross-chain amounts are validated using WAD normalization. Cross-chain withdrawal is represented as a two-phase escrow family: -| Phase | Transition literal | Meaning | +| Phase | Protocol operation | Meaning | | --- | --- | --- | -| Initiate | `escrow_lock` | Escrow withdrawal initiate. | -| Finalize | `escrow_withdraw` | Escrow withdrawal finalize or complete. | +| Initiate | `initiate_escrow_withdrawal` | Escrow withdrawal initiate. | +| Finalize | `finalize_escrow_withdrawal` | Escrow withdrawal finalize or complete. | ## Home Chain Migration -The home chain may change through migration states, represented by the `migrate` transition family. Migration is not a public builder workflow today. Conceptually, after migration: +The home chain may change through migration states, represented by the `initiate_migration` and `finalize_migration` operation family. Migration is not implemented as a public builder workflow today. Conceptually, after migration: - home chain identifier updates. - home token address updates. diff --git a/docs/nitrolite/protocol/enforcement-and-settlement.mdx b/docs/nitrolite/protocol/enforcement-and-settlement.mdx index 400e787..7e47dff 100644 --- a/docs/nitrolite/protocol/enforcement-and-settlement.mdx +++ b/docs/nitrolite/protocol/enforcement-and-settlement.mdx @@ -1,6 +1,6 @@ --- title: "Enforcement and Settlement" -description: "On-chain enforceability, checkpointing, challenges, close paths, validation rules, and failure conditions." +description: "On-chain enforceability, state submissions, challenges, close paths, validation rules, and failure conditions." --- # Enforcement and Settlement @@ -27,7 +27,7 @@ Node-issued pending states carry only the Node's signature. They are NOT enforce - Participants advance state off-chain through signed updates. - At any time, any party MAY submit the latest mutually signed state to the blockchain layer. - The blockchain layer validates the submitted state and updates its record. -- On-chain state always reflects the latest successfully checkpointed state. +- On-chain state always reflects the latest successfully enforced state. The on-chain state MAY lag behind the off-chain state during normal operation for transitions with the `OPERATE` intent. @@ -60,7 +60,7 @@ The state submitted for channel creation MAY carry a `DEPOSIT`, `WITHDRAW`, or ` ## State Submission -State submission covers checkpoint, deposit, and withdrawal operations: +State submission covers state enforcement, deposit, and withdrawal operations: 1. A participant constructs the enforcement representation of a signed state. 2. The participant submits the enforcement representation with all required signatures. @@ -122,7 +122,7 @@ The blockchain layer applies common validation rules when processing enforcement ## Escrow and Migration Enforcement -Escrow and migration transitions are part of the protocol model, but their public app-builder workflow is not documented yet. Treat the enforcement details as protocol reference material, not as instructions for constructing escrow or migration states by hand. +Escrow and migration operations are part of the protocol model, but the current Nitronode public app-builder workflow does not implement them yet. Treat the enforcement details as protocol reference material, not as instructions for constructing escrow or migration states by hand. | Operation family | Enforcement note | | --- | --- | diff --git a/docs/nitrolite/protocol/introduction.mdx b/docs/nitrolite/protocol/introduction.mdx index d87c0d8..ae43168 100644 --- a/docs/nitrolite/protocol/introduction.mdx +++ b/docs/nitrolite/protocol/introduction.mdx @@ -69,7 +69,7 @@ flowchart TB | --- | --- | | Core Protocol | Channels, states, state advancement rules, and enforcement mechanisms. | | Extension Layer | Additional functionality that interacts with the core protocol through defined interfaces. | -| Blockchain Layer | Channel creation, deposits, checkpoints, escrow operations, and fund release. | +| Blockchain Layer | Channel creation, deposits, state enforcement, escrow operations, and fund release. | ## Version Scope diff --git a/docs/nitrolite/protocol/security-and-limitations.mdx b/docs/nitrolite/protocol/security-and-limitations.mdx index 5225ffa..10e1ff6 100644 --- a/docs/nitrolite/protocol/security-and-limitations.mdx +++ b/docs/nitrolite/protocol/security-and-limitations.mdx @@ -52,6 +52,8 @@ Each User channel is opened with a Node. Cross-chain functionality depends on th When a User with home chain A transfers assets to a User with home chain B, the Node receives the amount on chain A and allocates from its own balance to the recipient on chain B. If the recipient later enforces state on chain B and the Node lacks sufficient liquidity there, on-chain enforcement will fail. +Single-chain operation can also depend on timing. During an off-chain transfer, the sender's funds are not returned to the Node's available vault immediately. They become available to the Node only after the sender's latest state is enforced on-chain, so temporary liquidity gaps can exist even when both users operate on the same chain. + :::caution Cross-chain liquidity trust In the current protocol version, users rely on the Node operator to maintain adequate liquidity across supported chains. Users cannot independently verify that this condition holds at all times. ::: @@ -63,7 +65,8 @@ Participants currently rely on Nodes for: - **Liveness**: Nodes need to be online to facilitate off-chain state advancement. - **Cross-chain liquidity**: Node operators need sufficient funds on each supported chain to honor off-chain allocations. - **Cross-chain relay**: Nodes relay cross-chain state updates; trustless cross-chain enforcement is not yet implemented. -- **Timely enforcement**: Nodes are expected to submit checkpoints when requested. +- **Timely enforcement**: Nodes are expected to submit state enforcement transactions when requested. +- **Off-chain funds integrity**: Current off-chain validation depends on Node behavior to prevent unsupported state advancement before every path is enforced on-chain. Participants do not need to trust Nodes for: diff --git a/docs/nitrolite/protocol/state-and-ledger-model.mdx b/docs/nitrolite/protocol/state-and-ledger-model.mdx index 4e791f9..ff911f1 100644 --- a/docs/nitrolite/protocol/state-and-ledger-model.mdx +++ b/docs/nitrolite/protocol/state-and-ledger-model.mdx @@ -117,24 +117,26 @@ Because this mapping is deterministic, signatures over off-chain state are valid ## Intent Mapping -| On-chain intent | Transition literal | Meaning | +| On-chain intent | Protocol operation | Meaning | | --- | --- | --- | | `OPERATE` | `transfer_send` | Sender-side off-chain transfer. | | `OPERATE` | `transfer_receive` | Receiver-side off-chain transfer. | | `OPERATE` | `commit` | Move channel funds into an app session or extension. | | `OPERATE` | `release` | Return app-session or extension funds to the channel. | +| `OPERATE` | acknowledgement | Acknowledge a Node-issued pending state. | | `CLOSE` | `finalize` | Finalize and close the channel. | | `DEPOSIT` | `home_deposit` | Deposit on the home chain. | | `WITHDRAW` | `home_withdrawal` | Withdraw on the home chain. | -| `INITIATE_ESCROW_DEPOSIT` | `mutual_lock` | Escrow deposit initiate. | -| `FINALIZE_ESCROW_DEPOSIT` | `escrow_deposit` | Escrow deposit finalize or complete. | -| `INITIATE_ESCROW_WITHDRAWAL` | `escrow_lock` | Escrow withdrawal initiate. | -| `FINALIZE_ESCROW_WITHDRAWAL` | `escrow_withdraw` | Escrow withdrawal finalize or complete. | -| `INITIATE_MIGRATION` | `migrate` | Home-chain migration initiate. | +| `INITIATE_ESCROW_DEPOSIT` | `initiate_escrow_deposit` | Escrow deposit initiate. | +| `FINALIZE_ESCROW_DEPOSIT` | `finalize_escrow_deposit` | Escrow deposit finalize or complete. | +| `INITIATE_ESCROW_WITHDRAWAL` | `initiate_escrow_withdrawal` | Escrow withdrawal initiate. | +| `FINALIZE_ESCROW_WITHDRAWAL` | `finalize_escrow_withdrawal` | Escrow withdrawal finalize or complete. | +| `INITIATE_MIGRATION` | `initiate_migration` | Home-chain migration initiate. | +| `FINALIZE_MIGRATION` | `finalize_migration` | Home-chain migration finalize. | -Transitions that map to `OPERATE` do not require on-chain checkpointing under normal operation. +Transitions that map to `OPERATE` do not require on-chain enforcement under normal operation. -Escrow and migration transition names are included for protocol accuracy. Their public app-builder workflow is not documented yet. +Escrow and migration operations are included for protocol accuracy. The protocol defines them, but the current Nitronode public app-builder workflow does not implement them yet. ## Transition Field diff --git a/docs/nitrolite/protocol/terminology.mdx b/docs/nitrolite/protocol/terminology.mdx index 2390b3c..55f59d8 100644 --- a/docs/nitrolite/protocol/terminology.mdx +++ b/docs/nitrolite/protocol/terminology.mdx @@ -73,14 +73,14 @@ Each unified asset defines a canonical decimal precision used during protocol in | --- | --- | | Mutually Signed State | A state that carries valid signatures from both the User and the Node. Only mutually signed states are enforceable on-chain. | | Node-Issued Pending State | A state produced by the Node that carries only the Node's signature. A pending state is NOT enforceable on-chain and becomes mutually signed only after the User acknowledges it. | -| Channel Status | A specific on-chain channel data configuration throughout the lifecycle, including open, challenged, closing, and closed states. | +| Channel Status | A specific on-chain channel data configuration throughout the lifecycle. The current RPC status surface is `void`, `open`, `challenged`, and `closed`. | | Escrow Channel Identifier | A 32-byte hash derived deterministically from the home channel identifier and state version. It uniquely identifies each escrow operation. | ## Protocol Operations | Operation | Definition | | --- | --- | -| Checkpoint | Submitting a signed state to the blockchain layer so the latest agreed state is recorded on-chain. | +| State Enforcement | Submitting a signed state to the blockchain layer so the latest agreed state is recorded on-chain. SDK or contract surfaces may expose a narrower `checkpoint` entry point for specific enforcement paths. | | Challenge | An on-chain operation where a participant disputes the current enforced state by submitting a signed state and challenger signature. | | Commit | Moving assets from a channel into an extension, such as an application session. | | Release | Returning assets from an extension back to channel allocations. | From 4ebed00e6375a96c65ca9bcdb6f1aa9f32454c10 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 21 May 2026 20:45:15 +0530 Subject: [PATCH 4/5] docs: clarify off-chain funds integrity assumption --- docs/nitrolite/protocol/security-and-limitations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nitrolite/protocol/security-and-limitations.mdx b/docs/nitrolite/protocol/security-and-limitations.mdx index 10e1ff6..bc692d9 100644 --- a/docs/nitrolite/protocol/security-and-limitations.mdx +++ b/docs/nitrolite/protocol/security-and-limitations.mdx @@ -66,7 +66,7 @@ Participants currently rely on Nodes for: - **Cross-chain liquidity**: Node operators need sufficient funds on each supported chain to honor off-chain allocations. - **Cross-chain relay**: Nodes relay cross-chain state updates; trustless cross-chain enforcement is not yet implemented. - **Timely enforcement**: Nodes are expected to submit state enforcement transactions when requested. -- **Off-chain funds integrity**: Current off-chain validation depends on Node behavior to prevent unsupported state advancement before every path is enforced on-chain. +- **Off-chain funds integrity**: Until every state path is independently enforceable on-chain, participants trust the Node not to advance unsupported off-chain balances that do not correspond to locked funds. Participants do not need to trust Nodes for: From a90c2b578eff9679da88b438d88d8af9cf98e517 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Thu, 21 May 2026 22:21:48 +0530 Subject: [PATCH 5/5] docs: restore closing channel status wording --- docs/nitrolite/learn/glossary.mdx | 1 + docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx | 2 +- docs/nitrolite/protocol/terminology.mdx | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/nitrolite/learn/glossary.mdx b/docs/nitrolite/learn/glossary.mdx index 90bd89d..c5f3ab6 100644 --- a/docs/nitrolite/learn/glossary.mdx +++ b/docs/nitrolite/learn/glossary.mdx @@ -38,6 +38,7 @@ The v1 RPC status surface uses: | `void` | No channel exists yet. | | `open` | The channel exists and can accept normal state updates. | | `challenged` | A challenge is active and the response window is running. | +| `closing` | The Node has issued the finalization state; the channel is in the close path. | | `closed` | Funds have been released and the channel lifecycle is complete. | ## Transition Literals diff --git a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx index b24d2f2..d351636 100644 --- a/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx +++ b/docs/nitrolite/learn/introduction/architecture-at-a-glance.mdx @@ -105,7 +105,7 @@ flowchart TB ## Channel Lifecycle -The v1 RPC currently exposes channel status as `void`, `open`, `challenged`, and `closed`. After a challenge expires, a separate close call can move the channel to `closed`; there is no separate `closing` status in the RPC schema. +The v1 RPC exposes channel status as `void`, `open`, `challenged`, `closing`, and `closed`. `closing` appears when the Node has issued the finalization state and the channel is in the close path. After a challenge expires, a separate close call can move the channel to `closed`. ```mermaid stateDiagram-v2 diff --git a/docs/nitrolite/protocol/terminology.mdx b/docs/nitrolite/protocol/terminology.mdx index 55f59d8..dd1bff0 100644 --- a/docs/nitrolite/protocol/terminology.mdx +++ b/docs/nitrolite/protocol/terminology.mdx @@ -73,7 +73,7 @@ Each unified asset defines a canonical decimal precision used during protocol in | --- | --- | | Mutually Signed State | A state that carries valid signatures from both the User and the Node. Only mutually signed states are enforceable on-chain. | | Node-Issued Pending State | A state produced by the Node that carries only the Node's signature. A pending state is NOT enforceable on-chain and becomes mutually signed only after the User acknowledges it. | -| Channel Status | A specific on-chain channel data configuration throughout the lifecycle. The current RPC status surface is `void`, `open`, `challenged`, and `closed`. | +| Channel Status | A specific on-chain channel data configuration throughout the lifecycle. The current RPC status surface is `void`, `open`, `challenged`, `closing`, and `closed`; `closing` means the Node has issued the finalization state and the channel is in the close path. | | Escrow Channel Identifier | A 32-byte hash derived deterministically from the home channel identifier and state version. It uniquely identifies each escrow operation. | ## Protocol Operations