# @aeternity/aepp-calldata 中文文档

规范地址：https://npmcn.com/package/%40aeternity/aepp-calldata/

版本：1\.10\.0
npm 元数据更新时间：2026-10-26T23:56:53.867Z
中文译文更新时间：2026-11-06T03:32:34.015Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40aeternity/aepp-calldata
原文对照：https://npmcn.com/package/%40aeternity/aepp-calldata/?lang=original
项目主页：https://github.com/aeternity/aepp-calldata-js#readme
源码仓库：https://github.com/aeternity/aepp-calldata-js

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

- 包体积（解压后）：432 kB，232 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2021-08-04T13:16:42.773Z
- 最新版本发布：2026-10-26T23:56:53.484Z
- 近 30 天下载量：5532（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 1 个）

## 中文简介

Atenity 数据序列化库

## 安装

```sh
npm install @aeternity/aepp-calldata
```

也可以使用：`pnpm add @aeternity/aepp-calldata`、`yarn add @aeternity/aepp-calldata`、`bun add @aeternity/aepp-calldata`

## README

# 绝对数据序列化

永久合同调用数据编码和结果解码 **独立** 图书馆.

这是 Javascript 中指定的数据序列化 [永久性协议](https://github.com/aeternity/protocol/blob/master/serializations.md#data)。 。 。 .

虽然本作编写时图书馆的唯一目的只是分别提供合同调用数据的编码和解码,并返回数据,但图书馆可能会演变为完整的协议规格序列化图书馆.

## 安装

```bash
npm install -P @aeternity/aepp-calldata
```

## 快速启动

根据ACI提供的类型信息与合同电话合作 `AciContractCallEncoder` 应使用类。 建筑师只用一个参数 [索菲娅 ACI](https://github.com/aeternity/aesophia/blob/master/docs/aeso_aci.md) 作为字符串.

节点JS实例 :

```javascript
const {AciContractCallEncoder} = require('@aeternity/aepp-calldata')
const ACI = require('./Test.json')
const CONTRACT = 'Test'

const encoder = new AciContractCallEncoder(ACI)
```

### 编码调用数据

这个 `encodeCall` 方法用于编码以合同名称为第一参数的 calldata,然后以函数名称和合同呼叫参数列表为最后参数.

示例

```javascript
const encoded = encoder.encodeCall(CONTRACT, 'test_string', ["whoolymoly"])
console.log(`Encoded data: ${encoded}`)
```

预期产出:

```
Encoded data: cb_KxHwzCuVGyl3aG9vbHltb2x5zwMSnw==
```

### 解码调用结果

这个 `decodeResult` 方法用于根据它的类型解码合同调用结果. 虽然前两个参数与编码方法相同,但第三个是被解码的实际结果,最后一个是默认为"ok"的结果类型.

示例

```javascript
const decoded = encoder.decodeResult(CONTRACT, 'test_string', 'cb_KXdob29seW1vbHlGazSE')
console.log(`Decoded data: ${decoded}`)
```

预期产出:

```
Encoded data: cb_KxHwzCuVGyl3aG9vbHltb2x5zwMSnw==
Decoded data: whoolymoly
```

### 合同呼叫错误

FATE合同调用错误信息作为编码合同字典(`cb_` 前缀字符串). 然而,返回消息是FATE字符串编码的,所以 `decodeResult` 方法接受与结果类型的参数.

示例

```javascript
// error message
const error = encoder.decodeResult(
    CONTRACT,
    'test_string',
    'cb_VHlwZSBlcnJvciBvbiBjYWxsOiBbe2J5dGVzLDw8MjQwLDIsLi4uPj59XSBpcyBub3Qgb2YgdHlwZSBbe2J5dGVzLDMyfV3EtJjU',
    'error'
)
console.log('Error: ' + error)

// revert message
const revert = encoder.decodeResult(CONTRACT, 'test_string', 'cb_OXJlcXVpcmUgZmFpbGVkarP9mg==', 'revert')
console.log('Revert: ' + revert)
```

预期产出:

```
Error: Type error on call: [{bytes,<<240,2,...>>}] is not of type [{bytes,32}]
Revert: require failed
```

### 活动

示例

```javascript
const data = encoder.decodeEvent('Test', 'cb_dHJpZ2dlcmVk1FYuYA==', [
    34853523142692495808479485503424878684430196596020091237715106250497712463899n,
    17n
])
console.log(data)
```

预期产出:

```
{EventTwo: [17n, 'triggered']}
```

## 字节阵列

任何合同字节都可以使用 `ContractByteArrayEncoder` 课.

FATE没有随数据携带某种信息格式的节点:

-   记录密钥丢失
-   变量名称丢失
-   任何用户类型的信息都丢失
-   STL 类型信息丢失:即链条, AENS, Set, BLS12 381

示例

```javascript
const {ContractByteArrayEncoder} = require('@aeternity/aepp-calldata')

const decodedString = encoder.decode('cb_KXdob29seW1vbHlGazSE')
console.log(`Decoded string: ${decodedString}`)

const decodedMap = encoder.decode('cb_LwEOfzGit9U')
console.log('Decoded map:', decodedMap)

```

预期产出:

```
Decoded string: whoolymoly
Decoded map: Map(1) { 7n => false }
```

编码器还可以使用明确类型的信息:

示例

```javascript
const {ContractByteArrayEncoder, TypeResolver} = require('@aeternity/aepp-calldata')

const encoder = new ContractByteArrayEncoder()
const resolver = new TypeResolver()

const decodedString = encoder.decodeWithType('cb_KXdob29seW1vbHlGazSE', resolver.resolveType('string'))
console.log(`Decoded string: ${decodedString}`)

const type = resolver.resolveType({map: ['int', 'bool']})
const encodedMap = encoder.encodeWithType(new Map([[7n, false]]), type)
console.log('Encoded map:', encodedMap)

```

预期产出:

```
Decoded string: whoolymoly
Decoded map: Map(1) { 7n => false }
```

## FATE API 编码器

下列任何一种FATE API数据类型都可以被编码并解码:

-   键 block hash
-   微块 hash
-   块( p)
-   块( tx hash)
-   块( state hash)
-   合同字节
-   合同( p)
-   账户 pubkey
-   账户 seckey
-   频道
-   甲骨文 pubkey
-   甲骨文 query id
-   端点( p)
-   名称
-   tx 小时
-   签名
-   承诺
-   字节

示例

```javascript
const {FateApiEncoder} = require('@aeternity/aepp-calldata')
const encoder = new FateApiEncoder()

const encoded = encoder.encode('contract_bytearray', new Uint8Array())
console.log(`Encoded: ${encoded}`)

const decoded = encoder.decode('cb_Xfbg4g==')
console.log('Decoded:', decoded)
```

预期产出:

```
Encoded: cb_Xfbg4g==
Decoded: Uint8Array(0) []
```

注意编码器使用二进制数据,所以字符串必须编码为 `Uint8Array`。 。 。 .

字符串示例 :

```javascript
const textEncoder = new TextEncoder()
const textDecoder = new TextDecoder()

const encoded = encoder.encode('contract_bytearray', textEncoder.encode('whoolymoly'))
console.log(`Encoded: ${encoded}`)

const decoded = textDecoder.decode(encoder.decode('cb_d2hvb2x5bW9seeO2SW0='))
console.log('Decoded:', decoded)
```

例外输出 :

```
Encoded: cb_d2hvb2x5bW9seeO2SW0=
Decoded: whoolymoly
```

## 合同编码器

解码合同元数据,包括字节码.

示例

```javascript
const {ContractEncoder} = require('@aeternity/aepp-calldata')
const encoder = new ContractEncoder()

const testContract = fs.readFileSync(path.resolve(__dirname, '../build/contracts/Test.aeb'))
const contract = encoder.decode(testContract.toString())

console.log('Contract:', contract)
```

预期产出( 已调整) :

```
{
  tag: 70n,
  vsn: 3n,
  source_hash: 'e50758c624dcacd485db1f9e76208c5858dd968f6218637d055fd4a3b2850baa',
  aevmTypeInfo: [],
  compilerVersion: '6.1.0',
  payable: false,
  bytecode: {
    functions: [
      {
        id: '077a0e02',
        name: 'test_nested_list',
        attributes: [],
        args: {
          name: 'tuple',
          valueTypes: [
            {
              name: 'list',
              valuesType: { name: 'list', valuesType: { name: 'int' } }
            }
          ]
        },
        returnType: {
          name: 'list',
          valuesType: { name: 'list', valuesType: { name: 'int' } }
        },
        instructions: [
          [
            { mnemonic: 'RETURNR', args: [ { mod: 'arg', arg: 0n } ] }
          ]
        ]
      },
      .....
    ],
    symbols: {
      '67419061': 'test_unit',
      ....
    },
    annotations: Map(0) {}
  }
}
```

**请注意,字节代码是用于调试/打印目的的,其结构WON't保持后相容性**

## 数据类型

使用库涉及数据类型及其从索菲亚到JavaScript的绘图,反之亦然.

| 索菲亚类型 | 索菲亚实例 | Javascript 类型 | Javascript 示例 |
| --- | --- | --- | --- |
| 单位 | `63`, (中文(简体) ), `-63` | 大点 | `63n`, (中文(简体) ), `-63n` |
| 嘘 | `true`, (中文(简体) ), `false` | 布尔 | `true`, (中文(简体) ), `false` |
| 字符串 | `"whoolymoly"` | 字符串 | `"whoolymoly"` |
| 字节 | `#beef` | 大点 | `BigInt("0xbeef")` |
| 列表 | `[1, 2, 3, 5, 8, 13, 21]` | 阵列 | `[1,2,3,5,8,13,21]` |
| 二联 | `(true, false)` | 阵列 | `[true, false]` |
| 地图 | `{[7] = false}` | 地图、 对象、 阵列 | `new Map([[7, false]])`, (中文(简体) ), `{7: false}`, (中文(简体) ), `[[7, false]]` |
| 记录 | `{x = 0, y = 0}` | 对象( POJO) | `{x: 0, y: 0}` |
| 变体 | `Some(404)`, (中文(简体) ), `None` | 对象( POJO) | `{'Some': [404]}`, (中文(简体) ), `{'None': []}`, (中文(简体) ), `404`, (中文(简体) ), `undefined` |
| 位数 | `Bits.none`, (中文(简体) ), `Bits.all` `Bits.set(Bits.none, 0)` | 大点 | `0b0n`, (中文(简体) ), `-1n`, (中文(简体) ), `0b00000001n` |
| 散列轴 | `#001234d` | 大点 | `BigInt("0x001234d")` |
| 签名 | `#001234d` | 大点 | `BigInt("0x001234d")` |
| 地址 | `ak_2gx9MEFxKvY9vMG5YnqnXWv1hCsX7rgnfvBLJS4aQurustR1rt` | 字符串 | `ak_2gx9MEFxKvY9vMG5YnqnXWv1hCsX7rgnfvBLJS4aQurustR1rt` |
| 设置. 设置 | `Set.from_list([1, 2, 3])` | 设定, 阵列 | `new Set([1,2,3])`, (中文(简体) ),`[1,2,3]` |
| BLS12 381.fr (英语) | `BLS12_381.int_to_fr(3735928559)` | 大点 | `3735928559n` |
| BLS12 381.fp (英语) | `BLS12_381.int_to_fp(3735928559)` | 大点 | `3735928559n` |

-   注意单键的变异对象的固定结构——变异构造器(即:. `Some`)和以它为值的多变参数.
-   当 Javascript 数字和原始 `int` 类型也可以在 `BigInt` 类型预计不会被推荐,因为它是 `Number.MAX_SAFE_INTEGER` 限制.

## 版本

本项目遵循 [语义版本](https://semver.org/spec/v2.0.0) 准则. 参见 [变化](https://npmcn.com/package/%40aeternity/aepp-calldata/CHANGELOG.md) 关于释放的更多信息.

## 公共 API

用语义化版本表示的后向兼容承诺 [上文](https://npmcn.com/package/%40aeternity/aepp-calldata/#readme-versioning) 实值 **仅限** 申请到该图书馆的公共API, 这只是模块导出和 [数据类型](https://npmcn.com/package/%40aeternity/aepp-calldata/#readme-data-types) 以上列出.

公共API包括以下类别:

-   [合同编码器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/AciContractCallEncoder.js)
-   [字节编码合同编码器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/BytecodeContractCallEncoder.js)
-   [ContractByte 箭头编码器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/ContractByteArrayEncoder.js)
-   [FateApi 编码器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/FateApiEncoder.js)
-   [合同编码器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/ContractEncoder.js)
-   [类型解析器](https://npmcn.com/package/%40aeternity/aepp-calldata/api/TypeResolver.js)

公共API也定义于 [类型脚本解密文件](https://npmcn.com/package/%40aeternity/aepp-calldata/main.d.ts)。 。 。 .

### 错误

出错名称也是公共API的一部分,并且保证在相容版本之间获得相同的出错名称. 由于错误类不导出为公共 API, 库用户应该依赖 **仅限** 打开 `Error.name` 属性处理例外. 另请注意: **错误消息不是公共 API 的一部分** 并且可以不经通知而更改版本之间的任何时间.

## 发展

请确保你熟悉 [贡献准则](https://npmcn.com/package/%40aeternity/aepp-calldata/CONTRIBUTING.md) 先说.

### 安装

```bash
npm install
```

### 测试

单位测试可使用:

```bash
make tests
```

综合测试:

```bash
make integration-tests
```

人们可以利用这些基准对某一变化的业绩进行比较:

```bash
make benchmark-tests
```

校验浏览器的兼容性 :

```bash
make browser-tests
```

检查范围:

```bash
make coverage
```

## 常见问题

### @aeternity/aepp-calldata 是什么？

Atenity 数据序列化库

### 如何安装 @aeternity/aepp-calldata？

在项目目录运行 npm install @aeternity/aepp-calldata，或使用 pnpm add / yarn add / bun add。

### @aeternity/aepp-calldata 支持 TypeScript 吗？

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

### @aeternity/aepp-calldata 支持 ESM 还是 CommonJS？

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

### @aeternity/aepp-calldata 可以商用吗？

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

### @aeternity/aepp-calldata 的下载量有多少？

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

### @aeternity/aepp-calldata 还在维护吗？

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