Migrating from 0.5.3
If your application uses @erc7824/[email protected], 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. 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
Use @yellow-org/sdk-compat when you need to move existing 0.5.3 code with minimal application churn.
Start here:
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
Use @yellow-org/sdk for new applications and for migrations that can adopt the v1 lifecycle directly.
Start here:
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
- Pick compat-first or native v1. Prefer native v1 as the final model once the staged migration is stable.
- Replace package imports.
- Review amount units for every transfer, deposit, withdrawal, and app-session call.
- Replace server-push assumptions with explicit queries or the supported polling helper.
- Run the updated flow against a disposable test wallet before updating docs or production examples.