Truffle Encoder

This module provides an interface for recognizing JavaScript user input of Solidity values, encoding those values for use in a transaction, and performing overload resolution based on those values to determine which Solidity method to encode for.

The interface is split into three classes: The project encoder, the contract encoder, and the contract instance encoder. The project encoder is associated to the project as a whole; it can recognize user input, encode transactions, and resolve overloads, although the interface for the latter two is somewhat inconvenient. The contract encoder is associated to a specific contract class. It is similar to the project encoder, but presents an easier-to-use interface for transaction encoding and overload resolution, so long as one is dealing with methods of the specified class. The contract instance encoder is associated to a specific contract instance; it is like the contract encoder, but is associated to a specific address, allowing the to option in transactions to be populated automatically.

Usage

Initialization

Create a encoder with one of the various constructor functions.

For a project encoder, use the [[forProject|forProject]] function.

For a contract encoder, use the [[forArtifact|forArtifact]] or [[forContract|forContract]] function.

For a contract instance encoder, use one of the following:

• [[forDeployedArtifact|forDeployedArtifact]]
• [[forDeployedContract|forDeployedContract]]
• [[forArtifactAt|forArtifactAt]]
• [[forContractAt|forContractAt]]
• [[forContractInstance|forContractInstance]]

See the documentation of these functions for details, or below for usage examples.

All of these functions take a final argument in which information about the project is specified; currently only a few methods for specifying project information are allowed, but more are planned.

One can also spawn encoders from other encoders by supplying additional information. See the documentation for the individual encoder classes for a method listing.

Encoder methods

See the documentation for the individual encoder classes for a method listing.

Wrapped format information

When using the various "wrap" functions, values will be wrapped in machine-readable [[Format.Values.Value]] objects containing individual wrapped values. (This is the same format that @truffle/decoder produces output in.) See the [[Format|format documentation]] for an overview and complete module listing.

Use of project information and encoding of enums

The encoder can do purely ABI-based encoding, like other encoders; however it has the capability to use project information to do more.

The most significant use of this is that if further project information is present, this allows for enums to be entered as strings with the name of the option, rather than having to be entered via the underlying number. See the documentation of [[ProjectEncoder.wrap]] for more.

Similarly, if project information is present, the encoder will also throw an error if you attempt to put an out-of-range value into an enum type, and refuse to consider overloads that would result in this during overload resolution. If project information is absent, the encoder will be unable to recognize any error in these situations.

ENS resolution

The encoder supports ENS resolution for address and contract types if initialized to support such. See the documentation of the [[EncoderSettings]] and [[EnsSettings]] types for more.

Basic usage examples

These usage examples are for a project with two contracts, Contract1 and Contract2. Let's suppose these look like the following:

pragma solidity ^0.8.0;

contract Contract1 {
 function enumExample(Contract2.Ternary x) public payable {
 }

 function overloaded(uint x) public payable {
 }

 function overloaded(string x) public payable {
 }
}

contract Contract2 {
 enum Ternary { No, Yes, Maybe }
}
Copy

Encoding a transaction

import { forContract } from "@truffle/encoder";
const contract1 = artifacts.require("Contract1");
const contract2 = artifacts.require("Contract2");
const encoder = await Encoder.forContract(Contract1, [Contract1, Contract2]);
const abi = Contract1.abi.find(abiEntry => abiEntry.name === "enumExample");
const tx = await encoder.encodeTransaction(
 abi,
 ["Maybe", { value: 1 }],
 { allowOptions: true }
);
Copy

Performing overload resolution

import { forContract } from "@truffle/encoder";
const contract1 = artifacts.require("Contract1");
const contract2 = artifacts.require("Contract2");
const encoder = await Encoder.forContract(Contract1, [Contract1, Contract2]);
const abis = Contract1.abi.filter(abiEntry => abiEntry.name === "overloaded");
const { tx, abi } = await encoder.encodeTransaction(
 abis,
 ["hello", { value: 1 }],
 { allowOptions: true }
);
Copy