# @dfinity/rosetta-client 中文文档

规范地址：https://npmcn.com/package/%40dfinity/rosetta-client/

版本：0\.6\.2
npm 元数据更新时间：2025-07-23T12:10:54.551Z
中文译文更新时间：2026-11-14T11:46:17.230Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dfinity/rosetta-client
原文对照：https://npmcn.com/package/%40dfinity/rosetta-client/?lang=original
项目主页：https://github.com/dfinity/rosetta-client
源码仓库：https://github.com/dfinity/rosetta-client

弃用说明：This package is deprecated and no longer maintained\.

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

- 包体积（解压后）：369 kB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：10 个
- 首次发布：2021-02-19T18:51:56.818Z
- 最新版本发布：2022-01-24T22:03:43.792Z
- 近 30 天下载量：2058（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

[![GitHub Actions](https://github.com/dfinity/rosetta-client/workflows/integration-test/badge.svg?branch=master)](https://github.com/dfinity/rosetta-client/actions?query=branch%3Amaster)

## 安装

```sh
npm install @dfinity/rosetta-client
```

也可以使用：`pnpm add @dfinity/rosetta-client`、`yarn add @dfinity/rosetta-client`、`bun add @dfinity/rosetta-client`

## README

# `@dfinity/rosetta-client`

[![GitHub Actions](https://github.com/dfinity/rosetta-client/workflows/integration-test/badge.svg?branch=master)](https://github.com/dfinity/rosetta-client/actions?query=branch%3Amaster)

一个叫 Rosetta API 的 JavaScript 软件包, 附加辅助功能到 获取证书并进行转让.

\* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \*\* \* \* \* \* \* 址、执行转账。

## 使用量

### 使用 ED25519 键工作

```javascript
let { randomBytes } = require("crypto");
let { key_new, key_to_pub_key, seed_from_pem } = require("@dfinity/rosetta-client");

// Derive an ED25519 private key from a system random seed. The private key's
// type is Buffer.
//
// 从系统生成的随机种子生成一个 ED25519 私钥。私钥类型为 Buffer。
let privateKey = key_new();

// Derive an ED25519 private key from a user-specified 32-byte random seed.
//
// 从用户指定的 32 字节随机数种子生成一个 ED25519 私钥。
let seed = randomBytes(32);
privateKey = key_new(seed);

// You can also load the seed from the identity PEM file generated by dfx, and
// use that to generate the private key for this library. This is the preferred
// way of generating private keys, since you can also use dfx to perform
// transfers and other operations on the command line given the identity PEM
// file.
//
// 您也可以从 dfx 生成的 PEM 文件中读取种子，并用其生成本库的私钥。我们推荐使用
// 本方式生成私钥，因为 dfx 可以读取证书文件并在命令行下进行转账等操作。
seed = seed_from_pem(
  readFileSync("/home/username/.config/dfx/identity/default/identity.pem")
);
privateKey = key_new(seed);

// Use key_to_pub_key() to derive a public key from a private key. The public
// key's type is Buffer.
//
// 调用 key_to_pub_key() 函数，从私钥生成公钥。公钥类型是 Buffer。
let publicKey = key_to_pub_key(privateKey);
```

### 处理账户地址

```javascript
let {
  pub_key_to_address,
  address_from_hex,
  address_to_hex,
} = require("@dfinity/rosetta-client");

// pub_key_to_address() derives an address from a public key. The address type
// is Buffer.
//
// pub_key_to_address() 函数从公钥生成账户地址。地址类型是Buffer。
let address = pub_key_to_address(publicKey);

// address_from_hex() & address_to_hex() converts between the address Buffer and
// the hex address string used in Rosetta API requests. This is not a simple
// base16 encoding, since the hex string will also contain a CRC32 checksum.
// address_from_hex() will throw if the checksum doesn't match.
//
// address_from_hex() 和 address_to_hex() 函数用于在地址的 Buffer 和用于 Rosetta
// API 请求中的十六进制字符串之间进行转换。转换过程并非简单的 base16 编码，因为
// 十六进制字符串中还会包含一个 CRC32 校验码。address_from_hex() 在校验码错误时
// 会抛出异常。
address = address_from_hex(address_to_hex(address));
```

### 呼叫罗塞塔API并进行转账

```javascript
let { Session } = require("@dfinity/rosetta-client");

// A Session implements the interface of RosettaClient as specified in
// https://www.npmjs.com/package/@lunarhq/rosetta-ts-client, and you can use
// methods of RosettaClient to invoke the Rosetta API.
//
// Session 实现了 https://www.npmjs.com/package/@lunarhq/rosetta-ts-client 描述
// 的 RosettaClient 类接口，可以调用 RosettaClient 的方法使用 Rosetta API。
let session = new Session({ baseUrl: "http://127.0.0.1:8080" });

// The network_identifier value used in requests.
//
// 请求中的 network_identifier 一栏所用的值。
console.log(await session.network_identifier);

// The currency value used in requests.
//
// 请求中的 currency 一栏所用的值。
console.log(await session.currency);

// A BigInt value representing the transaction fee. At the moment, despite the
// name "suggested_fee", the fee is mandatory.
//
// 代表交易费用的 BigInt 值。尽管 Rosetta API 中将其称为“建议费用”，该费用目前是
// 强制的。
console.log(await session.suggested_fee);

// Given the source account private key as a Buffer, the destination account as
// a Buffer, the transfer amount as a BigInt, perform a transfer and return the
// result of the /construction/submit call.
//
// The destination account will receive the specified amount. An additional fee
// will be charged from the source account.
//
// 给定划出账户私钥的 Buffer 对象、划入账户地址的 Buffer 对象和划转金额的 BigInt
// 值，发起一次转账，并返回 /construction/submit 调用的结果。
//
// 划入账户将收到指定金额，划出账户则将额外扣除交易费用。
let submit_result = await session.transfer(src_private_key, dest_addr, 123n);
console.log(submit_result);
```

### 查询给交易散列的交易

```javascript
// Call the /search/transactions endpoint and search for an on-chain transaction
// given its hash. Other query conditions of /search/transactions are not
// implemented yet.
//
// 调用 /search/transactions 接口，通过事务 hash 值检索其是否上链。
// /search/transactions 接口的其他检索条件目前暂未实现。
let transactions_result = await session.transactions({
  network_identifier: await session.network_identifier,
  transaction_identifier: submit_result.transaction_identifier,
});

console.log(transactions_result.transactions[0]);
```

### 在将私人钥匙保存在孤立环境中的同时进行转账

```javascript
let { transfer_combine } = require("@dfinity/rosetta-client");

// Due to security concerns, you may wish to avoid calling transfer() which
// consumes the private key and performs network calls. We support using the
// private key only in a fully isolated environment while performing a transfer,
// here's an example.
//
// 出于安全考虑，您也许希望避免调用 transfer() 方法，因为它需要传入私钥参数，并
// 且会执行网络调用。我们支持在转账时，仅在完全隔离的环境中使用私钥，用例如下。
let payloads_result = await session.transfer_pre_combine(
  src_public_key,
  dest_addr,
  123n
);

// This step can be executed in a fully isolated environment. The result is the
// same of calling /construction/combine with session.combine().
//
// 该步骤可在完全隔离的环境中执行。与通过 session.combine() 调用 /construction/combine 的结果相同。
let combine_result = transfer_combine(src_private_key, payloads_result);

submit_result = await session.transfer_post_combine(combine_result);
```

### 在可配置的时间内提交交易

```javascript
// The transfer()/transfer_pre_combine() functions take two extra optional
// parameters. One is max_fee, another is an object for additional metadata in
// the /construction/payloads request.
//
// It's possible to specify ingress_start/ingress_end in the metadata, so that
// you can generate and sign a transaction earlier, but postpone the submission
// later. The submission period must be within the next 24 hours.
// ingress_start/ingress_end are BigInt values specifying nanoseconds since unix
// epoch, and you can specify only single one of it.
//
// transfer()/transfer_pre_combine() 函数还有两个可选参数，一个是 max_fee，另一
// 个是作为 /construction/payloads 请求的额外 metadata 的对象。
//
// 可以在 metadata 中指定 ingress_start/ingress_end，从而提前生成并签名一条事
// 务，但将事务的提交推迟到之后的时间。提交时间必须不晚于事务生成后的 24 小时。
// ingress_start/ingress_end 是纳秒单位 Unix 时间戳的 BigInt 值，可以全部指定也
// 可以只指定一个。

payloads_result = await session.transfer_pre_combine(
  src_public_key,
  dest_addr,
  123n,
  undefined,
  { ingress_start, ingress_end }
);
```

### 解码已签名的交易

```javascript
const { signed_transaction_decode } = require("@dfinity/rosetta-client");

// You may wish to decode a signed transaction and verify the content before
// actually submitting it. Here's how.
//
// 您也许想要在提交已签名的事务前，先将其反序列化并校验其内容。示例如下。

// The signed_transaction field is a hex-encoded string. Pass it directly to
// signed_transaction_decode().
//
// signed_transaction 是十六进制编码的字符串。直接将其传给
// signed_transaction_decode() 即可。
const tx = signed_transaction_decode(combine_result.signed_transaction);

// The source account as a Buffer.
//
// 转出账户的 Buffer 值。
console.log(address_to_hex(tx.from));

// The destination account as a Buffer.
//
// 转入账户的 Buffer 值。
console.log(address_to_hex(tx.to));

// The transfer amount as a BigInt.
//
// 转账金额的 BigInt 值。
console.log(tx.amount);

// The additional transaction fee as a BigInt.
//
// 额外的交易费用的 BigInt 值。
console.log(tx.fee);

// The source account's public key as a Buffer.
//
// 转出账户公钥的 Buffer 值。
console.log(tx.sender_pubkey);
```

### 使用 JS 捆绑创建( U)

您可以将这个软件包及其依赖性捆绑在一个 JS 文件中,并使用 作为常规的普通JS模块.

JS , 普通JS。

```sh
$ npm install
$ npm run-script build
$ node --eval "console.log(require('./dist/main.js'))"
```

捆绑的联署材料也可作为以下文件提供: `dist` 中情局的艺术品.

联合来文1 `dist` 文件直接下载。

## 支持的 Node.js 版本

本包以最新版本的Node.js v10/v12/v13/v14/v15/v16进行测试.

## 常见陷阱和陷阱

### 与 BigInt 合作

因为 JavaScript 数字类型 [限制](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) 以整数表示 精度,我们用 `BigInt`s 各地(金额、费用、时间戳等) 表示整数。 使用时需要注意 `BigInt`用这个 软件包 :

\* JavaScript \* \* \*[页:1](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)时 是涉及整数的部分均使用 `BigInt` 类型(如转账金额、交易费用、时间戳等)。使用 `BigInt` 时需要留意的要点:

```javascript
// Don't do this! Precision loss!
// 不要这样，会有精度损失！
let timestamp = BigInt(Date.now() * 1000000);

// Do this instead!
// 这样才对！
let timestamp = BigInt(Date.now()) * 1000000n;
```

另外,JavaScript的内置 `JSON` 编码器/解码器与 此软件包的输入/输出数据。 我们用 [`json-bigint`](https://www.npmjs.com/package/json-bigint) 给 JSON 的 这个包中的编码/解码, 如果你需要与JSON合作,你也 还需要 `json-bigint`。 。 。 .

\*\*\*,贾瓦脚本 `JSON` 页:1 [`json-bigint`](https://www.npmjs.com/package/json-bigint) JSON,JSON {{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{}{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{}{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{{ 也应当使用 `json-bigint`。 。 。 .

```javascript
const JSONbig = require("json-bigint")({ strict: true, useNativeBigInt: true });
JSONbig.parse(); // Use this instead of JSON.parse()
JSONbig.stringify(); // Use this instead of JSON.stringify()
```

## 常见问题

### 如何安装 @dfinity/rosetta-client？

在项目目录运行 npm install @dfinity/rosetta-client，或使用 pnpm add / yarn add / bun add。

### @dfinity/rosetta-client 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dfinity\_\_rosetta-client 是否存在。

### @dfinity/rosetta-client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dfinity/rosetta-client 可以商用吗？

@dfinity/rosetta-client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dfinity/rosetta-client 的下载量有多少？

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

### @dfinity/rosetta-client 还在维护吗？

最新版本 0\.6\.2 发布于 2022/01/25（4 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/02/20。作者已将其标记为弃用，新项目建议寻找替代方案。