What Changed Since 0.5.3
If you built with @erc7824/[email protected], 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 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. |
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, 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. |
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.
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.
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/[email protected]. 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 - choose compat-first or native v1.
- TypeScript compat SDK - staged migration for existing 0.5.3 apps.
- Native TypeScript SDK - the long-term SDK path for new v1 flows.
- Quickstart - run the tested channel and app-session lifecycle.
- Key Terms & Mental Models - quick vocabulary reference for the v1 SDK docs.