Skip to main content
Version: 1.x

Off-Chain Migration Guide

This page covers authentication, app sessions, transfers, ledger queries, and event polling when moving 0.5.3 app code to @yellow-org/sdk-compat.

Authentication​

Native NitroliteClient usage handles connection authentication inside the client. Legacy auth helper imports are split into three buckets.

Available and Functional​

These helpers are exported and implemented for migration code that still owns a WebSocket auth flow:

import {
  createAuthRequestMessage,
  createAuthVerifyMessage,
  createAuthVerifyMessageWithJWT,
  createEIP712AuthMessageSigner,
} from '@yellow-org/sdk-compat';

The v1 auth request fields are application, expires_at, session_key, scope, and allowances. The codemod flags older app_name, expire, participant, and challenge usage for review.

Exported but Fail Fast​

Workflow helpers that cannot map honestly to a single live v1 RPC remain exported so old imports compile, but throw with migration guidance:

createTransferMessage;
createCreateChannelMessage;
createCloseChannelMessage;
createResizeChannelMessage;

Use NitroliteClient methods instead.

Parse v1 Payloads Into 0.5.x Shapes​

The parse*Response helpers normalize known v1 response payloads into the older app-facing response shape:

parseGetChannelsResponse;
parseGetLedgerBalancesResponse;
parseGetLedgerEntriesResponse;
parseGetAppSessionsResponse;
parseCreateAppSessionResponse;
parseCloseAppSessionResponse;
parseSubmitAppStateResponse;
parseGetAppDefinitionResponse;
parseAnyRPCResponse;

These are migration aids, not a reason to keep an app-owned RPC transport indefinitely.

App Sessions​

List​

Before: createGetAppSessionsMessage + sendRequest + parseGetAppSessionsResponse.

After:

const sessions = await client.getAppSessionsList();

Create​

App-session allocation strings remain human-readable decimal strings:

const appAmount = '5.0'; // human-readable app-session decimal string

await client.createAppSession(definition, [
  { participant: userAddress, asset: 'usdc', amount: appAmount },
], quorumSigs);

Submit State​

import { RPCAppStateIntent } from '@yellow-org/sdk-compat';

await client.submitAppState({
  app_session_id: appSessionId,
  intent: RPCAppStateIntent.Operate,
  version,
  allocations,
  quorum_sigs: quorumSigs,
});

Close​

await client.closeAppSession(appSessionId, allocations, quorumSigs);

Transfers​

Transfer allocations are raw asset-unit strings, not human-readable decimal strings.

Before: helper workflow.

const msg = await createTransferMessage(signer.sign, { destination, allocations });
await sendRequest(msg);

After: compat method.

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

That example means 5 USDC when the asset has 6 decimals. See the amount-units table.

Ledger Queries​

Before: create, send, parse.

const msg = await createGetLedgerBalancesMessage(signer.sign, accountId);
const raw = await sendRequest(msg);
const balances = parseGetLedgerBalancesResponse(raw).params.ledgerBalances;

After: direct client calls.

const balances = await client.getBalances();
const entries = await client.getLedgerEntries();
const channels = await client.getChannels();

Event Polling​

0.5.3 apps often listened for pushed channel and balance updates. Compat replaces that with EventPoller, which polls the same query methods your app can call directly.

import { EventPoller } from '@yellow-org/sdk-compat';

const poller = new EventPoller(client, {
  onChannelUpdate: (channels) => updateChannels(channels),
  onBalanceUpdate: (balances) => updateBalances(balances),
  onAssetsUpdate: (assets) => updateAssets(assets),
  onError: (err) => reportError(err),
}, 5000);

poller.start();

See the EventPoller cookbook for lifecycle, interval, and cleanup guidance.

Error Handling​

Wrap migrated calls with typed error handling instead of string-matching raw wallet or RPC errors:

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

try {
  await client.transfer(destination, [{ asset: 'usdc', amount: '5000000' }]);
} catch (err) {
  const typed = NitroliteClient.classifyError(err);
  showToast(getUserFacingMessage(typed));
}

See Errors and recovery for recovery recipes.