Aeternity data serialization

Aeternity contract calldata encoding and results decoding library

Installation

This package is not published to NPM registry yet.

npm install -P @aeternity/aepp-calldata

Quick Start

There is single module Encoder that should be imported and instanciated. The constructor takes a single argument - Sophia ACI as string.

The encode method is used to encode calldata taking the contract name as first argument, then function name and list of contract call arguments as last argument.

The decode method is used to decode contract call results while the first two arguments are the same as the encoding method the last one is the actuall result to be decoded.

NodeJS example:

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

const encoder = new Encoder(ACI)

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

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

Expected output:

Encoded data: cb_KxHwzCuVGyl3aG9vbHltb2x5zwMSnw==
Decoded data: whoolymoly

Serialization

The encode and decode methods of the Encoder accept and return contract byte arrays (a cb_ prefixed string with base64check encoded binary data).

The library also provides serialization and deserialization methods to work with binary data, i.e.:

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

const encoder = new Encoder(ACI)

const encodedBin = encoder.serialize(CONTRACT, 'test_string', ["whoolymoly"])
console.log(encodedBin)

const binData = new Uint8Array([0x29, 0x77, 0x68, 0x6f, 0x6f, 0x6c, 0x79, 0x6d, 0x6f, 0x6c, 0x79])
const decodedBin = encoder.deserialize(CONTRACT, 'test_string', binData)
console.log(decodedBin)

Expected output:

Uint8Array(18) [
   43,  17, 240, 204,  43, 149,
   27,  41, 119, 104, 111, 111,
  108, 121, 109, 111, 108, 121
]
FateString { name: 'string', _value: 'whoolymoly' }

The serialize method return a byte array while the deserialize method returns a wrapper object of the corresponding Sophia type.

Wrapper objects are not backward compatible guaranteed interface. Each data type wrapper implements valueOf Javascript method that should be used to unbox the primitive (Javascript) type.

Data types

Using the library involves data types and their mappings from Sophia to JavaScript and vice versa.

• note the fixed structure of variant object with keys variant which denotes variant constructor and values as it's arguments.
• while Javascript Number and primitive int types can be used as well when BigInt type is expected it's not recommended because of it's Number.MAX_SAFE_INTEGER limitation.

Versioning

This project follows the semantic versioning guidelines. Refer to the CHANGELOG for more information about releases.

Development

Install

npm install

Tests

make tests

Verify browser compatibility with:

make browser-tests

To see the test coverage run:

make coverage