On-Chain Migration Guide

This page covers deposits, withdrawals, channel operations, amount handling, and contract-address migration for apps moving from @erc7824/[email protected] to @yellow-org/sdk-compat.

Deposits

In v1, home-channel creation is implicit on first deposit. Apps should stop sending a separate createChannel workflow.

Before: manual approve, deposit, and channel creation.

await approveToken(custody, tokenAddress, amount);
await sendRequest(createDepositMessage(signer.sign, { token: tokenAddress, amount }));
await sendRequest(createCreateChannelMessage(signer.sign, { token: tokenAddress, amount }));

After: one compat call with raw token units.

const amount = 11_000_000n; // 11 USDC when the token has 6 decimals
await client.deposit(tokenAddress, amount);

deposit() resolves the token to a v1 asset, sets the home blockchain, calls the native deposit path, and checkpoints. If token allowance is missing, the compat client retries after approval through the v1 SDK.

Withdrawals

Before: close or resize workflow plus a manual withdrawal request.

const closeMsg = await createCloseChannelMessage(signer.sign, channelId, destination);
await sendRequest(closeMsg);
await sendRequest(createWithdrawMessage(signer.sign, { token, amount }));

After: one compat call with raw token units.

const amount = 5_000_000n; // 5 USDC
await client.withdrawal(tokenAddress, amount);

Channel Operations

Operation	v0.5.3 habit	Compat behavior
Create	createChannel()	Unsupported as a standalone flow; first deposit() creates the home channel when needed
Close	createCloseChannelMessage + send + parse	client.closeChannel() or client.closeChannel({ tokenAddress })
Resize	createResizeChannelMessage + send + parse	client.resizeChannel({ allocate_amount, token }), implemented through deposit
Checkpoint	checkpointChannel(...)	Fail-fast stub; use client.innerClient.checkpoint(asset)
Challenge	challengeChannel({ state })	Delegates to the v1 challenge path

Amount Handling

Compat does not accept one universal amount shape. Use the canonical amount-units table before changing production amounts.

// Raw token-unit bigint for deposit and withdrawal.
await client.deposit(usdcTokenAddress, 11_000_000n);
await client.withdrawal(usdcTokenAddress, 5_000_000n);

// Helpers for display conversion.
const formatted = client.formatAmount(usdcTokenAddress, 11_000_000n); // "11"
const parsed = client.parseAmount(usdcTokenAddress, '11.0');          // 11_000_000n

Transfers are different. A transfer allocation uses a raw asset-unit string:

await client.transfer(recipientAddress, [
  { asset: 'usdc', amount: '5000000' },
]);

App-session allocations are different again: they use human-readable decimal strings. Keep these three cases separate during review.

Contract Addresses

Before: apps often carried manual contract maps.

const addresses = { custody: '0x...', adjudicator: '0x...' };

After: contract and asset metadata comes from Nitronode config and asset discovery. The addresses config field is deprecated and ignored.

const config = await client.getConfig();
const assets = await client.getAssetsList();

If an on-chain helper needs an RPC URL for a chain, pass blockchainRPCs when creating NitroliteClient or use blockchainRPCsFromEnv().

const client = await NitroliteClient.create({
  wsURL: '<sandbox-url-coming-soon>',
  walletClient,
  chainId: 11155111,
  blockchainRPCs: {
    11155111: process.env.SEPOLIA_RPC_URL!,
  },
});

Approval Helpers

Compat exposes allowance helpers for migration code that still thinks in raw token units:

const allowance = await client.getTokenAllowance(tokenAddress);

if (allowance < 11_000_000n) {
  await client.approveTokens(tokenAddress, 11_000_000n);
}

For native v1-only flows, use client.innerClient.approveToken(chainId, asset, amount) with Decimal.