> ## Documentation Index
> Fetch the complete documentation index at: https://ckbfans.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# lumos-patches

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

`@ckb-ccc/lumos-patches` bridges [Lumos](https://github.com/ckb-js/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.

<Info>
  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.
</Info>

## 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

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @ckb-ccc/lumos-patches
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @ckb-ccc/lumos-patches
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @ckb-ccc/lumos-patches
    ```
  </Tab>
</Tabs>

## Applying the patches

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

```typescript theme={null}
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());
```

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

## 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.

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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
```