This module provides an interface for decoding contract state, transaction calldata, events, and return values and revert strings. It's an interface to the same low-level decoding functionality that Truffle Debugger uses. However, it has additional functionality that the debugger does not need, and the debugger has additional functionality that this decoder does not need.

The interface is split into three classes: The project decoder, the contract decoder, and the contract instance decoder. The project decoder is associated to the project as a whole and decodes transaction calldata and events. The contract decoder is associated to a specific contract class. It has all the capabilities of the project decoder, but it can also decode return values from calls made by the given contract class. The contract instance decoder is associated to a specific contract instance; it again has all the capabilities of the project decoder and contract decoder, but it can also decode the state variables for the specific instance. (In addition, in the case that the contract does not include a deployedBytecode field in its artifact, which can hinder decoding certain things, the contract instance decoder can sometimes work around this where the other decoders cannot.)

This documentation describes the current state of the decoder, but further improvements are planned.

Usage

Initialization

Create a decoder with one of the various constructor functions.

For a project decoder, use the forProject function.

For a contract decoder, use the forArtifact or forContract function.

For a contract instance decoder, use one of the following: forDeployedArtifact forDeployedContract forArtifactAt forContractAt forContractInstance forAddress

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 decoders from other decoders by supplying additional information. See the documentation for the individual decoder classes for a method listing.

Decoder methods

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

Output format information

The decoder outputs lossless, machine-readable Format.Values.Result objects containing individual decoded values. See the format documentation for an overview and complete module listing.

Decoding modes, abification, and caveats

The decoder runs in either of two modes: full mode or ABI mode. Full mode requires some additional constraints but returns substantially more detailed information. Please see the notes on decoding modes for more about this distinction.

See also the notes about decoding state variables for additional caveats about what may or may not be fully decodable.

Basic usage examples

Decoding a log with the project decoder

This usage example is for a project with two contracts, Contract1 and Contract2.

import { forProject } from "@truffle/decoder";
const contract1 = artifacts.require("Contract1");
const contract2 = artifacts.require("Contract2");
const provider = web3.currentProvider;
const decoder = await Decoder.forProject(provider, [contract1, contract2]);
const decodings = await decoder.decodeLog(log);

The usage of decodeTransaction is similar.

For getting already-decoded logs meeting appropriate conditions, see ProjectDecoder.events.

Decoding state variables with the contract instance decoder

This usage example is for decoding the state variables of a contract Contract in a project that also contains a contract OtherContract.

import { forContract } from "@truffle/decoder";
const contract = artifacts.require("Contract");
const otherContract = artifacts.require("OtherContract");
const decoder = await Decoder.forContract(contract, [otherContract]);
const instanceDecoder = await decoder.forInstance();
const variables = await instanceDecoder.variables();

In this example, we use the deployed version of Contract. If we wanted an instance at a different address, we could pass the address to forInstance.

In addition, rather than using forContract and then forInstance, we could also use forContractInstance to perform both of these in one step. If we wanted to do this with a specified address, we could use forContractAt.

Yet another way would be:

import { forContractInstance } from "@truffle/decoder";
const contract = artifacts.require("Contract");
const otherContract = artifacts.require("OtherContract");
const deployedContract = await contract.deployed();
const instanceDecoder = await Decoder.forContractInstance(deployedContract, [otherContract]);
const variables = await instanceDecoder.variables();

These examples are not exhaustive.

One can find more advanced decoding examples with variable and watchMappingKey at the documentation for these individual functions.