Skip to main content
Version: 1.x

TypeScript Compat SDK

@yellow-org/sdk-compat is a migration layer for apps already built on the published @erc7824/[email protected] API. It keeps selected app-facing calls available while routing them through the native v1 @yellow-org/sdk runtime.

:::note Package naming The published npm package audited for this migration path is @erc7824/[email protected]. Some older internal docs refer to the same 0.5.3 codebase as @layer-3/nitrolite. :::

Already integrated with @erc7824/nitrolite?

Speed up the migration with the yellow-sdk-codemod repository:

# Clone the codemod and install its dependencies
git clone https://github.com/layer-3/yellow-sdk-codemod.git
cd yellow-sdk-codemod
npm install
npm run build

# Scan your codebase for migrate-able patterns (no files modified)
node dist/cli.js scan --path /path/to/your-app/src

# Apply transforms (and update package.json deps)
node dist/cli.js run --path /path/to/your-app --update-deps

After running, search for TODO [codemod] in your codebase and resolve them manually. The codemod surfaces every place a chained create*Message + sendRequest + parse*Response pattern needs context. See node dist/cli.js list for the full transform list.

:::tip MCP-assisted migration Yellow SDK MCP is available as @yellow-org/sdk-mcp. Connect it to your AI coding tool when you want help reviewing unresolved codemod markers, uncertain imports, old RPC helper chains, and direct v1 SDK replacements. See the migration overview for the workflow. :::

Why Use Compat​

Use compat when a live app needs to move off the 0.5.3 package without rewriting every transport, auth, event, and amount-handling call at once. New apps should start with the native @yellow-org/sdk instead.

Compat is a bridge, not full package parity. The underlying v1 client is available as client.innerClient for flows that the migration surface cannot model honestly.

Installation​

npm install @yellow-org/sdk-compat
# peer dependencies
npm install @yellow-org/sdk viem

:::info Public Nitronode endpoints Use the sandbox endpoint in the wsURL field below while testing a migration. Use production/mainnet only when you intentionally connect to live assets.

  • Sandbox: wss://nitronode-sandbox.yellow.org/v1/ws
  • Production/mainnet: wss://nitronode.yellow.org/v1/ws :::

Quick Start​

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

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

await client.deposit(tokenAddress, 11_000_000n);

const channels = await client.getChannels();
const balances = await client.getBalances();
const sessions = await client.getAppSessionsList();

// 5 USDC (6 decimals) as raw asset-unit string:
await client.transfer(recipientAddress, [{ asset: 'usdc', amount: '5000000' }]);

await client.close();

TransferAllocation.amount is a raw asset-unit string using the asset's canonical decimals; the compat layer divides by decimals before delegating to the v1 SDK.

Amount Units​

Method areaAmount formatExample
deposit, withdrawal, token allowance helpersraw token-unit bigint11_000_000n
transfer allocationsraw asset-unit string'5000000'
App-session allocationshuman-readable decimal string'5.0'
Direct @yellow-org/sdk channel and app amountsDecimalnew Decimal(5)

Method Cheat Sheet​

AreaCovered surface
Channel operationsdeposit, depositAndCreateChannel, withdrawal, closeChannel, resizeChannel, challengeChannel, acknowledge
Query methodsgetChannels, getChannelData, getBalances, getLedgerEntries, getAppSessionsList, getAssetsList, getAccountInfo, getConfig, getBlockchains, getActionAllowances
On-chain helpersgetOpenChannels, approveTokens, getTokenAllowance, getTokenBalance
Transferstransfer(destination, allocations) with raw asset-unit strings
App sessionscreateAppSession, closeAppSession, submitAppState, getAppDefinition, registerApp, getApps
App-session signingpackCreateAppSessionHash, packSubmitAppStateHash, toWalletQuorumSignature, toSessionKeyQuorumSignature
Auth helperscreateAuthRequestMessage, createAuthVerifyMessage, createAuthVerifyMessageWithJWT, createEIP712AuthMessageSigner
Event pollingEventPoller polls getChannels(), getBalances(), and getAssetsList() and emits legacy-shaped callbacks

checkpointChannel(...) is exported as a fail-fast migration shim; use client.innerClient.checkpoint(asset) instead.

See EventPoller for the cookbook.

Lifecycle helpers include ping(), close(), waitForClose(), and refreshAssets().

What Compat Does Not Preserve​

:::warning Compat is curated, not a drop-in @yellow-org/sdk-compat preserves selected @erc7824/[email protected] app-facing APIs. It does not preserve:

  • the legacy server-push event model; use EventPoller
  • checkpointChannel(...); it is a fail-fast stub, use client.innerClient.checkpoint(asset)
  • get_session_keys directory-style APIs
  • get_rpc_history
  • full root-export parity with @erc7824/[email protected]

If your code touches these surfaces, run the codemod first, then use the migration guides below to finish the manual changes. :::

Configuration​

interface NitroliteClientConfig {
  wsURL: string;                           // Nitronode WebSocket URL
  walletClient: WalletClient;              // viem WalletClient with account
  chainId: number;                         // Chain ID, for example 11155111
  blockchainRPCs?: Record<number, string>; // Chain ID -> RPC URL map
  channelSessionKeySigner?: {
    sessionKeyPrivateKey: Hex;
    walletAddress: Address;
    metadataHash: Hex;
    authSig: Hex;
  };
}

blockchainRPCsFromEnv() reads from NEXT_PUBLIC_BLOCKCHAIN_RPCS:

NEXT_PUBLIC_BLOCKCHAIN_RPCS=11155111:https://rpc.sepolia.io,1:https://mainnet.infura.io/v3/KEY

Accessing the v1 SDK​

Client is not re-exported from @yellow-org/sdk-compat for SSR safety. Import SDK classes directly from @yellow-org/sdk, or use the wrapped instance exposed on the compat client:

const v1Client = client.innerClient;
await v1Client.getHomeChannel(wallet, 'usdc');
await v1Client.checkpoint('usdc');
await v1Client.approveToken(chainId, 'usdc', amount);

Error Handling​

The compat package exports typed errors plus getUserFacingMessage(error) for UI-safe messages. See Errors and recovery for the cookbook.

Migration Guides​