Skip to main content
Version: 1.x

Migrating from v0.5.3 to Compat

Use this guide when an existing app depends on @erc7824/[email protected] and needs a staged path onto the v1 runtime. Compat preserves the supported app-facing surface, but it does not promise full 0.5.3 package parity.

Start With the Codemod​

Run the codemod before hand-editing. It rewrites imports, migrates client constructors, renames auth fields, updates dependencies, and leaves TODO [codemod] comments where a human needs to collapse a workflow.

git clone https://github.com/layer-3/yellow-sdk-codemod.git
cd yellow-sdk-codemod
npm install
npm run build

node dist/cli.js scan --path /path/to/your-app/src
node dist/cli.js run --path /path/to/your-app --update-deps

Then search for the manual markers:

rg "TODO \\[codemod\\]" /path/to/your-app

See the overview for the command sequence and node dist/cli.js list for available transforms.

MCP-Assisted Migration​

:::tip Available now Yellow SDK MCP is available from npm as @yellow-org/sdk-mcp. Connect it to your AI coding tool when you want a second pass on migration leftovers. :::

After the codemod, use the MCP server as a second review pass:

  1. Set up Yellow SDK MCP in Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, or another MCP-compatible tool.
  2. Ask it to walk through changed files and unresolved TODO [codemod] markers.
  3. Ask it to check whether uncertain imports belong to @yellow-org/sdk-compat or native @yellow-org/sdk.
  4. Ask it to map old create*Message + sendRequest + parse*Response flows onto v1 SDK calls where possible.
  5. Ask it to verify direct v1 SDK replacements before reaching for client.innerClient.

MCP assistance does not replace the manual checklist below. Treat it as a practical review partner that can keep the SDK, RPC catalogue, examples, and migration guidance in the same conversation.

Install Compat​

npm install @yellow-org/sdk-compat
npm install @yellow-org/sdk viem

Client Construction​

Before: app-owned WebSocket plus helper calls.

const msg = await createGetChannelsMessage(signer.sign, address);
const raw = await sendRequest(msg);
const parsed = parseGetChannelsResponse(raw);

After: one compat client backed by the v1 SDK.

import { NitroliteClient, blockchainRPCsFromEnv } from '@yellow-org/sdk-compat';

const client = await NitroliteClient.create({
  wsURL: 'wss://nitronode-sandbox.yellow.org/v1/ws',
  walletClient,
  chainId: 11155111,
  blockchainRPCs: blockchainRPCsFromEnv(),
});

const channels = await client.getChannels();

:::info Public Nitronode endpoints Use wss://nitronode-sandbox.yellow.org/v1/ws for migration tests with sandbox assets. Use wss://nitronode.yellow.org/v1/ws only when you intentionally connect migrated code to production/mainnet assets. :::

Migration Matrix​

Legacy useCompat statusDirect v1 replacement
Auth helpersAvailable: createAuthRequestMessage, createAuthVerifyMessage, createAuthVerifyMessageWithJWT, createEIP712AuthMessageSignerSDK client auth flow
Channel create or resize helpersUnsupported or fail-fast where no honest v1 mapping existsNative client.innerClient.deposit(...), client.innerClient.checkpoint(asset), lifecycle methods
TransferAvailable with raw-amount caveatClient.transfer(recipient, asset, Decimal)
App sessionsAvailable with v1 remappingNative app-session methods on Client

Amount Rules​

Do not flatten all amounts into one convention. Compat intentionally keeps separate units for separate method families.

  • deposit, withdrawal, and token allowance helpers use raw token-unit bigint.
  • transfer uses raw asset-unit strings, for example { asset: 'usdc', amount: '5000000' } for 5 USDC with 6 decimals.
  • App-session allocations use human-readable decimal strings, for example '5.0'.
  • Direct native v1 calls use Decimal.

See the canonical amount-units table.

What Changes​

Concernv0.5.3 habitCompat behavior
WebSocket ownershipApp creates and manages WebSocketNitroliteClient manages the connection
SigningApp passes signer.sign into each helperClient methods sign internally with walletClient
Contract addressesApp hard-codes custody and adjudicator addressesCompat reads current node config and asset metadata
Channel creationApp calls createChannel()First deposit() creates the home channel when needed
Server-push eventsApp handles pushed channel and balance eventsUse EventPoller
ErrorsApp matches raw stringsUse typed errors and Errors and recovery

Manual Review Checklist​

After the codemod runs, review each changed area before shipping:

AreaWhat to check
Imports@erc7824/nitrolite, @layer-3/nitrolite, and vendored tarballs are gone from app source
Client setupnew NitroliteClient(...) and createNitroliteClient(...) are replaced with NitroliteClient.create({ wsURL, walletClient, chainId, blockchainRPCs })
Authapp_name, expire, participant, and challenge are migrated to application, expires_at, session_key, scope, and allowances
RPC chainscreate*Message + sendRequest + parse*Response call chains are replaced with client methods or consciously kept as transitional helpers
Channel operationscreateChannel, depositToChannel, and old approveToken wrappers are replaced with deposit, withdrawal, approveTokens, or a direct innerClient call
EventsWebSocket push handlers are replaced with EventPoller or app-owned polling
Contract configcustody, adjudicator, CUSTODIES, and ADJUDICATORS constants are removed; config comes from Nitronode
AmountsTransfer amounts are raw asset-unit strings; app-session allocations are human-readable decimal strings
ErrorsRaw string matching is replaced with NitroliteClient.classifyError() and getUserFacingMessage()
SSRDo not import Client from @yellow-org/sdk-compat; import SDK classes directly from @yellow-org/sdk

Unsupported Surfaces​

The following names can still appear in migrated code, but they are not full live replacements:

  • checkpointChannel(...) fails fast; use client.innerClient.checkpoint(asset).
  • Workflow-only create*Message helpers such as createTransferMessage, createCreateChannelMessage, createCloseChannelMessage, and createResizeChannelMessage fail fast with migration guidance.
  • parse*Response helpers normalize known v1 payloads into 0.5.x-shaped responses, but they are not a replacement for an app-owned RPC transport.
  • get_session_keys directory-style APIs and get_rpc_history are not preserved.

Next Steps​