绝对数据序列化

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

这是 Javascript 中指定的数据序列化 永久性协议。 。 。 .

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

安装

npm install -P @aeternity/aepp-calldata

快速启动

根据ACI提供的类型信息与合同电话合作 AciContractCallEncoder 应使用类。 建筑师只用一个参数 索菲娅 ACI 作为字符串.

节点JS实例 :

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

const encoder = new AciContractCallEncoder(ACI)

编码调用数据

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

示例

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

预期产出:

Encoded data: cb_KxHwzCuVGyl3aG9vbHltb2x5zwMSnw==

解码调用结果

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

示例

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 方法接受与结果类型的参数.

示例

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

活动

示例

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

预期产出:

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

字节阵列

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

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

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

示例

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 }

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

示例

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 小时
• 签名
• 承诺
• 字节

示例

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

字符串示例 :

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

合同编码器

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

示例

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的绘图,反之亦然.

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

版本

本项目遵循 语义版本 准则. 参见 变化 关于释放的更多信息.

公共 API

用语义化版本表示的后向兼容承诺 上文 实值 仅限 申请到该图书馆的公共API, 这只是模块导出和 数据类型 以上列出.

公共API包括以下类别:

• 合同编码器
• 字节编码合同编码器
• ContractByte 箭头编码器
• FateApi 编码器
• 合同编码器
• 类型解析器

公共API也定义于 类型脚本解密文件。 。 。 .

错误

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

发展

请确保你熟悉 贡献准则 先说.

安装

npm install

测试

单位测试可使用:

make tests

综合测试:

make integration-tests

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

make benchmark-tests

校验浏览器的兼容性 :

make browser-tests

检查范围:

make coverage