lumos-patches

Apply CCC patches to Lumos to add JoyID, Nostr, and Portal wallet support.

@ckb-ccc/lumos-patches bridges Lumos and CCC. If you already use Lumos to compose CKB transactions but want your users to sign with JoyID, Nostr, or Portal wallets, apply these patches before using any Lumos APIs.

You do not need this package if you are building a new application. Use @ckb-ccc/connector-react or @ckb-ccc/shell instead for full CCC support.

Who needs it

Install @ckb-ccc/lumos-patches if you have an existing Lumos-based codebase and want to:

• Sign transactions with JoyID (no @ckb-lumos/joyid required).
• Sign transactions with Nostr wallets.
• Sign transactions with Portal wallet.

Installation

npm

npm install @ckb-ccc/lumos-patches

yarn

yarn add @ckb-ccc/lumos-patches

pnpm

pnpm add @ckb-ccc/lumos-patches

Applying the patches

Call generateDefaultScriptInfos() and pass the result to Lumos’ registerCustomLockScriptInfos before you use any Lumos transaction-building functions.

import { generateDefaultScriptInfos } from "@ckb-ccc/lumos-patches";
import { registerCustomLockScriptInfos } from "@ckb-lumos/common-scripts/lib/common";

// Apply once at app startup, before using Lumos
registerCustomLockScriptInfos(generateDefaultScriptInfos());

Call registerCustomLockScriptInfos before your first Lumos transaction. Registering after transaction building has started may cause scripts to be missing from the cell deps.

generateDefaultScriptInfos

Returns an array of LockScriptInfo objects that teach Lumos how to collect cells and prepare witnesses for JoyID, Nostr, and PWLock scripts on both mainnet and testnet.

function generateDefaultScriptInfos(): LockScriptInfo[]

The returned array includes script infos for:

Script	CKB known script
JoyID	ccc.KnownScript.JoyId
Nostr Lock	ccc.KnownScript.NostrLock
PWLock	ccc.KnownScript.PWLock

Each script info covers both mainnet and testnet code hashes, so the same call works for both networks.

generateScriptInfo

If you need to patch in a custom lock script beyond the defaults, use the lower-level generateScriptInfo function:

function generateScriptInfo(
  codeHash: string,
  cellDeps: ccc.CellDepInfoLike[],
  dummyLockLength: number,
): LockScriptInfo

Parameter	Description
codeHash	The code hash of the custom lock script (hex string).
cellDeps	Cell dependencies required by the script.
dummyLockLength	Byte length of the placeholder witness lock field used during fee estimation.

Full example

import { generateDefaultScriptInfos } from "@ckb-ccc/lumos-patches";
import { registerCustomLockScriptInfos } from "@ckb-lumos/common-scripts/lib/common";
import { initializeConfig, predefined } from "@ckb-lumos/config-manager";

// 1. Initialize Lumos config as usual
initializeConfig(predefined.AGGRON4); // testnet

// 2. Apply CCC patches — must happen before building transactions
registerCustomLockScriptInfos(generateDefaultScriptInfos());

// 3. Use Lumos normally — JoyID, Nostr, and Portal locks now work