Manifest Call Encoder

The Manifest Call Encoder module enables the encoding and decoding of data according to the MOI Manifest specification. This specification defines the structure of routines, classes, methods, and state within logic object, allowing for seamless interaction with their properties.

Through this module, developers can encode data in compliance with the expected format specified by the logic Manifest. This is particularly valuable when preparing data for invoking routines on logic object. By correctly encoding routine parameters according to the logic Manifest, developers can generate accurate input data that aligns with the logic objects’s expectations.

In addition, this facilitates the decoding of data received from the blockchain or logic objects. Developers can decode routine call results, and other Manifest-encoded data structures, enabling them to extract meaningful information. This capability greatly aids in the efficient processing and interpretation of data obtained from the MOI network.

Types

LogicManifest

The LogicManifest module defines the schema for a logic manifest.

EngineConfig

The EngineConfig interface defines the configuration for the logic engine. It has two properties:

kind - string: The type of logic engine.

flags - string[]: A list of flags.

TypeField

The TypeField interface defines a field type. It has three properties:

slot - number: The slot number of the field.

label - string: The label or name of the field.

type - string: The type of the field.

MethodField

The MethodField interface defines a method field. It has two properties:

ptr - number | bigint: The pointer value of the field.

code - number | bigint: The code value of the field.

Class

The Class interface defines a class within the logic manifest. It has three properties:

name - string: The name of the class.

fields - TypeField[] | null: An optional array of fields within the class.

methods - MethodField[] | null: An optional array of methods within the class.

State

The State interface defines the state within the logic manifest. It has two properties:

kind - string: The kind or type of the state.

fields - TypeField[]: An array of fields within the state.

Constant

The Constant interface defines a constant within the logic manifest. It has two properties:

type - string: The type of the constant.

value - string: The value of the constant.

Instructions

The Instructions interface defines the instructions within the logic manifest. It has three optional properties:

bin - number[] | null: An optional array of binary values.

hex - string: A hexadecimal representation of the instructions (optional).

asm - string[] | null: An optional array of assembly instructions.

Routine

The Routine interface defines a routine within the logic manifest. It has five properties:

name - string: The name of the routine.

kind - string: The kind or type of the routine.

accepts - TypeField[] | null: An optional array of input fields that the routine accepts.

returns - TypeField[] | null: An optional array of output fields that the routine returns.

executes - Instructions: The instructions executed by the routine.

catches - string[] | null: An optional array of exceptions caught by the routine.

Method

The Method interface defines a method within a class in the logic manifest. It has six properties:

name - string: The name of the method.

class - string: The name of the class the method belongs to.

accepts - TypeField[] | null: An optional array of input fields that the method accepts.

returns - TypeField[] | null: An optional array of output fields that the method returns.

executes - Instructions: The instructions executed by the method.

catches - string[] | null: An optional array of exceptions caught by the method.

TypeDef

The TypeDef represents a string type definition.

Element

The Element interface represents an element within the logic manifest. It has four properties:

ptr - number: The pointer value of the element.

kind - string: The kind or type of the element.

deps - number[] | null: An optional array of dependencies for the element.

data - State | Constant | TypeDef | Routine | Class | Method: The data associated with the element.

Manifest

The Manifest interface represents the overall logic manifest. It has three properties:

syntax - string: The syntax used in the manifest.

engine - EngineConfig: The configuration of the logic engine.

elements - Element[]: An array of elements within the manifest.

Exception

The Exception interface defines an exception. It has three properties:

class - string: The exception class.
data - string: The exception message.
trace - string[]: The stack trace of the exception.
revert - boolean: Represents the interaction revert status.

PoloSchema

The PoloSchema interface defines a schema used by polo of serialization and deserialization. It has two properties:

kind - string: The type or kind of the schema.
fields - Record<string, any>: The fields within the schema. It is a dictionary-like structure where keys are strings and values are object (optional).

ManifestCoder

ManifestCoder is a class that provides encoding and decoding functionality for Manifest Call Encoder. It allows encoding manifests and arguments, as well as decoding output, exceptions and logic states based on both predefined and runtime schema.

// Example
import { ManifestCoder } from "js-moi-sdk";

const manifest = { ... }
const manifestCoder = new ManifestCoder(manifest);

Methods

static encodeManifest(manifest)

Encodes a manifest into a hexadecimal string.

This function supports encoding both JSON and YAML manifest formats. If the input manifest is an object, it is assumed to be a JSON manifest and is encoded using the JsonManifestCoder. If the input manifest is a string, it is assumed to be a YAML manifest and is encoded using the YamlManifestCoder.

Arguments:

manifest – The manifest to encode. It can be either a string (YAML) or an object (JSON).

Throws:

Will throw an error if the manifest type is unsupported.

Returns:

The encoded manifest as a hexadecimal string prefixed with “0x”.

// Example
const encodedManifest = ManifestCoder.encodeManifest(manifest)
console.log(encodedManifest)

>> "0x0e4f065...50000"

static decodeManifest(manifest, format)

Decodes a given manifest in either JSON or YAML format.

Arguments:

manifest (string|Uint8Array) – The manifest data to decode, provided as a string or Uint8Array.
format (ManifestCoderFormat) – The format of the manifest, either JSON or YAML.

Throws:

Error –

Throws an error if the format is unsupported.

Returns:

LogicManifest.Manifest|string – - Returns a LogicManifest.Manifest object if JSON format is used or a string representation if YAML format is used.

// Example
const decodedManifest = ManifestCoder.decodeManifest(encodedManifest, ManifestFormat.JSON);
console.log(decodedManifest)

>> { syntax: 1, engine: { kind: "PISA", flags: [] }, elements: [...] }

encodeArguments(routine, ...args)

Encodes the arguments for a specified routine into a hexadecimal string.

Arguments:

routine – The name of the routine for which the arguments are being encoded.
args – The arguments to be encoded, passed as a variadic parameter.

Returns:

A hexadecimal string representing the encoded arguments.

// Example
const calldata = manifestCoder.encodeArguments("Seeder", "MOI", 100_000_000);

console.log(calldata)

>> "0x0d6f0665...d4f49"

decodeArguments(routine, calldata)

Decodes the provided calldata into the expected arguments for a given routine.

Arguments:

routine (string) – The name of the routine whose arguments are to be decoded.
calldata (string) – The calldata to decode.

Returns:

T|null – - The decoded arguments as an object of type T, or null if the routine accepts no arguments.

decodeOutput(routine, output)

Decodes the output of a routine.

Arguments:

routine (string) – The name of the routine whose output is to be decoded.
output (string) – The output string to decode.

Returns:

T|null – - The decoded output as type T, or null if the output is invalid or the routine has no return schema.

// Example
const callsite = "BalanceOf";
const output = "0x0e1f0305f5e100";
const args = manifestCoder.decodeOutput(callsite, output);

console.log(decodedOutput);

>> { balance: 100000000 }

static decodeException(error)

Decodes an exception thrown by a logic routine call. The exception data is decoded using the predefined exception schema. Returns the decoded exception object, or null if the error is empty.

Arguments:

error (string) – The error data to decode, represented as a hexadecimal string prefixed with “0x”.

Returns:

Exception|null – The decoded exception object, or null if the error is empty.

// Example
const error = "0x0e6f0666d104de04737472696e67696e73756666696369656e742062616c616e636520666f722073656e6465723f06e60172756e74696d652e726f6f742829726f7574696e652e5472616e736665722829205b3078635d202e2e2e205b307831623a205448524f57203078355d";

const exception = ManifestCoder.decodeException(error);

console.log(exception)

>> {
        class: "string",
        error: "insufficient balance for sender",
        revert: false,
        trace: [
            "runtime.root()",
            "routine.Transfer() [0xc] ... [0x1b: THROW 0x5]"
        ],
    }

decodeEventOutput(event, logData)

Decodes a log data from an event emitted in a logic.

Arguments:

event (string) – The name of the event.
logData (string) – The POLO encoded log data to be decoded.

Returns:

T|null – The decoded event log data, or null if the log data is empty.

Schema

Schema is a class that provides schema parsing functionality for encoding and decoding manifest, arguments, logic states and other data based on a predefined schema. It supports parsing fields and generating a schema for decoding purposes.

// Example
const manifest = { ... }
const elements = new Map();
const classDefs = new Map();

manifest.elements.forEach(element => {
    elements.set(element.ptr, element);

    if(element.kind === "class") {
        classDefs.set(element.data.name, element.ptr);
    }
})

const schema = new Schema(elements, classDefs);

Methods

parseFields(fields)

Parses an array of fields and generates the schema based on the fields.

Arguments:

fields (Array.<LogicManifest.TypeField>) – The array of fields.

Throws:

Error – If the fields are invalid or contain unsupported data types.

Returns:

PoloSchema – The generated schema based on the fields.

// Example
const routine = manifest.elements.find(element =>
    // BalanceOf is the name of a routine which is available in the manifest
    element.data.name === "BalanceOf"
)
const fields = routine.data.accepts ? routine.data.accepts : [];
const routineSchema = schema.parseFields(fields)

console.log(routineSchema)

>> { kind: "struct", fields: { addr: { kind: "bytes" } } }