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​

:::info Coming soon The Yellow SDK MCP server is proposed for npm publication as @yellow-org/sdk-mcp. Until that package is published, treat this as a preview of the assisted workflow, not a command that should work today. :::

After publication, connect the MCP server to your MCP-compatible client and use it as a second review pass after the codemod:

  1. Run server_info to confirm the MCP content version matches the SDK version you are migrating to.
  2. Use the migrate-from-v053 prompt to walk through changed files and unresolved TODO [codemod] markers.
  3. Use validate_import when you are unsure whether a symbol belongs to @yellow-org/sdk-compat or native @yellow-org/sdk.
  4. Use get_rpc_method to map old create*Message + sendRequest + parse*Response flows onto the v1 wire method.
  5. Use lookup_method, lookup_type, or search_api to verify direct v1 SDK replacements before reaching for client.innerClient.

MCP assistance does not replace the manual checklist below. Tool-specific setup belongs with the package publish so the documented commands are runnable on the day they appear here.

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: '<sandbox-url-coming-soon>',
  walletClient,
  chainId: 11155111,
  blockchainRPCs: blockchainRPCsFromEnv(),
});

const channels = await client.getChannels();

:::info Sandbox URL - coming soon Use the same Nitronode URL placeholder pattern as the native v1 quickstart. Replace <sandbox-url-coming-soon> only when the canonical sandbox host is pinned. :::

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​