# @fireblocks/ncw-js-sdk 中文文档

规范地址：https://npmcn.com/package/%40fireblocks/ncw-js-sdk/

版本：12\.5\.6
npm 元数据更新时间：2026-08-13T14:44:23.612Z
中文译文更新时间：2026-11-14T19:29:07.567Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fireblocks/ncw-js-sdk
原文对照：https://npmcn.com/package/%40fireblocks/ncw-js-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.8 MB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：3 个
- 首次发布：2023-07-30T09:09:31.611Z
- 最新版本发布：2025-04-20T09:19:04.465Z
- 近 30 天下载量：5368（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：139（近 12 个月 0 个）

## 中文简介

JavaScript 中的防火块签名器

## 安装

```sh
npm install @fireblocks/ncw-js-sdk
```

也可以使用：`pnpm add @fireblocks/ncw-js-sdk`、`yarn add @fireblocks/ncw-js-sdk`、`bun add @fireblocks/ncw-js-sdk`

## README

# 全国妇女理事会

Fireblocks 非海关钱包的官方 Javascript & Typescript SDK

## 快速启动

### 初始化

```typescript
import {
  FireblocksNCWFactory,
  IEventsHandler,
  IFireblocksNCW,
  IMessagesHandler,
  TEvent,
  InMemorySecureStorageProvider,
} from "@fireblocks/ncw-js-sdk";

// Example Device ID
const deviceId = "f16e05e0-1869-4a6b-9678-17a1c14ed482";

// Initiate secure storage to hold generated data during SDK usage.
const secureStorageProvider = new InMemorySecureStorageProvider();

// Register a message handler to process outgoing message to your API
const messagesHandler: IMessagesHandler = {
  handleOutgoingMessage: (message: string) => {
    // Send the message to your API service
    return {} as any;
  },
};

// Register an events handler to handle on various events that the SDK emitts
const eventsHandler: IEventsHandler = {
  handleEvent: (event: TEvent) => {
    if (
      event.type === "key_descriptor_changed" ||
      event.type === "key_takeover_changed" ||
      event.type === "transaction_signature_changed" ||
      event.type === "join_wallet_descriptor"
    ) {
      // Do something when the event is fired.
      console.log(event);
    }
  },
};

// Initialize Fireblocks NCW SDK
const fireblocksNCW = await FireblocksNCWFactory({
  deviceId,
  messagesHandler,
  eventsHandler,
  secureStorageProvider,
});
```

### 生成 MPC 密钥

```typescript
import { IKeyDescriptor, TMPCAlgorithm } from "@fireblocks/ncw-js-sdk";

// Generate MPC Keys
const algorithms: Set<TMPCAlgorithm> = new Set(["MPC_CMP_ECDSA_SECP256K1"]);
const keyDescriptor: Set<IKeyDescriptor> = await fireblocksNCW.generateMPCKeys(algorithms);
```

生成 MPC 密钥进程将释放 `IKeyTakeoverChangedEvent` 事件.

### 签名交易

```typescript
import { ITransactionSignature } from "@fireblocks/ncw-js-sdk";

// Sign transaction
const result: ITransactionSignature = await fireblocksNCW.signTransaction("SOME_TX_UUID");
console.log(
  `txId: ${result.txId}`,
  `status: ${result.transactionSignatureStatus}`, // "PENDING" | "STARTED" | "COMPLETED" | "TIMEOUT" | "ERROR"
);
```

标志进程会发出 `ITransactionSignatureChangedEvent` 事件.

### 安全存储

以下示例使用自定义的安全存储.

```typescript
const secureStorageProvider = new PasswordEncryptedLocalStorage(deviceId, () => {
  const password = prompt("Enter password", "");
  if (password === null) {
    return Promise.reject(new Error("Rejected by user"));
  }
  return Promise.resolve(password || "");
});

// Initialize Fireblocks NCW SDK with your custom secure storage
const fireblocksNCW = await FireblocksNCW.initialize(deviceId, messagesHandler, eventsHandler, secureStorageProvider);
```

基于用户密码的安全存储的一个实例.

```typescript
import {
  BrowserLocalStorageProvider,
  ISecureStorageProvider,
  TReleaseSecureStorageCallback,
  decryptAesGCM,
  encryptAesGCM,
} from "@fireblocks/ncw-js-sdk";
import { md } from "node-forge";

export type GetUserPasswordFunc = () => Promise<string>;

/// This secure storage implementations creates an encryption key on-demand based on a user password

export class PasswordEncryptedLocalStorage extends BrowserLocalStorageProvider implements ISecureStorageProvider {
  private encKey: string | null = null;

  constructor(
    private _salt: string,
    private getPassword: GetUserPasswordFunc,
  ) {
    super();
  }

  public async getAccess(): Promise<TReleaseSecureStorageCallback> {
    this.encKey = await this._generateEncryptionKey();
    return async () => {
      await this._release();
    };
  }

  private async _release(): Promise<void> {
    this.encKey = null;
  }

  public async get(key: string): Promise<string | null> {
    if (!this.encKey) {
      throw new Error("Storage locked");
    }

    const encryptedData = await super.get(key);
    if (!encryptedData) {
      return null;
    }

    return decryptAesGCM(encryptedData, this.encKey, this._salt);
  }

  public async set(key: string, data: string): Promise<void> {
    if (!this.encKey) {
      throw new Error("Storage locked");
    }

    const encryptedData = await encryptAesGCM(data, this.encKey, this._salt);
    await super.set(key, encryptedData);
  }

  private async _generateEncryptionKey(): Promise<string> {
    let key = await this.getPassword();
    const md5 = md.md5.create();

    for (let i = 0; i < 1000; ++i) {
      md5.update(key);
      key = md5.digest().toHex();
    }

    return key;
  }
}
```

## 发展

1.  清除仓库
2.  安装依赖关系 `yarn`
3.  以 `yarn build`
4.  运行测试 `yarn test`

## 技术

-   [字体](https://www.npmjs.com/package/typescript)
-   [维特](https://www.npmjs.com/package/vite)
-   [欢乐](https://www.npmjs.com/package/jest)
-   [ESLint 语录](https://www.npmjs.com/package/eslint)
-   [高级](https://www.npmjs.com/package/prettier)

## 常见问题

### @fireblocks/ncw-js-sdk 是什么？

JavaScript 中的防火块签名器

### 如何安装 @fireblocks/ncw-js-sdk？

在项目目录运行 npm install @fireblocks/ncw-js-sdk，或使用 pnpm add / yarn add / bun add。

### @fireblocks/ncw-js-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fireblocks/ncw-js-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fireblocks/ncw-js-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fireblocks/ncw-js-sdk 可以商用吗？

@fireblocks/ncw-js-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fireblocks/ncw-js-sdk 的下载量有多少？

根据 npm 官方下载统计，@fireblocks/ncw-js-sdk 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,368 次，日均约 179 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fireblocks/ncw-js-sdk 还在维护吗？

最新版本 12\.5\.6 发布于 2025/04/20（1\.6 年前）；至今共发布 139 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/07/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。