nitrolite-codemod

Automated migration tool for upgrading from @erc7824/nitrolite (v0.4–0.5.3) to @yellow-org/sdk-compat.

Installation

cd codemod
npm install

Important

The scan command requires ripgrep (rg) to be installed and available in your PATH. On macOS, install it with brew install ripgrep. On Linux, use your package manager (e.g. apt install ripgrep). The run command (jscodeshift transforms) does not require ripgrep.

Commands

scan — Detect old patterns without modifying files

npx tsx src/cli.ts scan --path ../my-app

Scans your codebase and prints a summary of every old Nitrolite pattern found, grouped by category with file-level counts. Useful for estimating migration scope before running any transforms.

run — Apply transforms

# Run all transforms
npx tsx src/cli.ts run --path ../my-app/src

# Dry run (preview changes, no writes)
npx tsx src/cli.ts run --path ../my-app/src --dry-run

# Run specific transforms only
npx tsx src/cli.ts run --path ../my-app/src --transforms import-rewriter,client-constructor

# Also update package.json dependencies
npx tsx src/cli.ts run --path ../my-app --update-deps

list — Show available transforms

npx tsx src/cli.ts list

Transforms

Transform	What it does
import-rewriter	Rewrites @erc7824/nitrolite and @layer-3/nitrolite imports to @yellow-org/sdk-compat. Splits imports that moved to @yellow-org/sdk into a separate declaration. Renames changed exports (e.g. RPCData → NitroliteRPCRequest).
client-constructor	Migrates new NitroliteClient(...) and createNitroliteClient(...) constructor patterns to NitroliteClient.create({ wsURL, walletClient, chainId, blockchainRPCs }).
auth-params	Renames auth request fields (app_name → application, expire → expires_at, participant → session_key), removes deprecated challenge field, adds missing allowances and scope.
rpc-collapse	Flags the create*Message() + sendRequest() + parse*Response() pattern with TODO comments pointing to the equivalent NitroliteClient method. Also flags NitroliteRPC.createRequest (old array format) and NitroliteRPC.signRequestMessage.
channel-ops	Flags deprecated createChannel(), depositToChannel(), and approveToken() calls with TODO comments suggesting client.deposit() instead.
ws-events	Flags manual new WebSocket() connections to clearnode endpoints and push-based ws.onmessage event handlers, suggesting EventPoller as the replacement.
config-cleanup	Flags deprecated manual contract address configs (custody, adjudicator, CUSTODIES, ADJUDICATORS), old Signature structs { v, r, s }, manual formatUnits/parseUnits calls, and manual error string matching patterns.

Scan patterns detected

The scan command checks for these patterns:

• @erc7824/nitrolite and @layer-3/nitrolite import paths
• Vendored tarball references (erc7824-nitrolite-*.tgz)
• createNitroliteClient() factory calls
• new NitroliteClient( constructor calls
• create*Message() RPC builder calls
• parse*Response() RPC parser calls
• NitroliteRPC.createRequest and NitroliteRPC.signRequestMessage
• Manual contract addresses (custody, adjudicator)
• Old auth fields (app_name)
• Deprecated createChannel() calls
• Manual WebSocket connections to clearnode
• approveToken() and depositToChannel() calls

How it works

The codemod uses jscodeshift to parse source files into an AST and apply safe, targeted transformations.

Automatic changes (applied directly):

• Import path rewrites
• Named import renames
• Client constructor migration
• Auth field renames

Flagged for manual review (inserts // TODO [codemod] comments):

• RPC create-sign-send-parse pattern collapse
• Deprecated channel operations
• Manual WebSocket removal
• Contract address cleanup
• Error handling migration

After running, search your codebase for TODO [codemod] to find all spots that need manual attention.

Options

Flag	Description
--path <dir>	(required) Path to the source directory to transform
--transforms <names>	Comma-separated list of transforms (default: all)
--dry-run	Preview changes without writing files
--update-deps	Also update package.json (remove old deps, add new ones)
--extensions <exts>	File extensions to process (default: ts,tsx,js,jsx,mjs)

Migration mapping reference

Package names

Old	New
@erc7824/nitrolite	@yellow-org/sdk-compat
@layer-3/nitrolite	@yellow-org/sdk-compat
@erc7824/nitrolite-compat	@yellow-org/sdk-compat
file:./vendor/erc7824-nitrolite-*.tgz	@yellow-org/sdk-compat

RPC pattern collapse

Old (create → sign → send → parse)	New (single client call)
createGetChannelsMessage + parseGetChannelsResponse	client.getChannels()
createGetLedgerBalancesMessage + parseGetLedgerBalancesResponse	client.getBalances()
createAppSessionMessage + parseCreateAppSessionResponse	client.createAppSession(def, alloc)
createCloseAppSessionMessage + parseCloseAppSessionResponse	client.closeAppSession(id, alloc)
createSubmitAppStateMessage + parseSubmitAppStateResponse	client.submitAppState(params)
createTransferMessage	client.transfer(dest, alloc)
createCreateChannelMessage + parseCreateChannelResponse	client.deposit(token, amount)
createCloseChannelMessage + parseCloseChannelResponse	client.closeChannel()
createPingMessage	client.ping()

Auth fields

Old	New
app_name	application
expire (string)	expires_at (BigInt, seconds since epoch)
participant	session_key
challenge	Removed
—	allowances: [] (new, required)
—	scope: 'app.create' (new, required)