This module provides an interface for decoding contract state, transaction calldata, and events. 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 interface either does not need or cannot currently replicated. In the future, this interface will also decode return values and revert strings.

The interface is split into three classes: The wire decoder, the contract decoder, and the contract instance decoder. The wire 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 wire decoder, but in addition it acts as a factory for contract instance decoders. The contract instance decoder is associated to a specific contract instance; it too has all the capabilities of the wire 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 you should expect to see improvements soon. Note that most of the documentation is not found in this README, but rather in this package's API documentation. However, this README describes the overall approach.

Usage

Initialization

Create a decoder with one of the various constructor functions.

For a wire 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 [[forContractAbstraction|forContractAbstraction]]

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

All of these functions presently require a final argument containing all artifacts that could potentially be relevant. It's intended that this argument will be optional in the future.

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 and abification

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

Basic usage examples

Decoding a log with the wire 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 decodedLog = await decoder.decodeLog(log);

The usage of decodeTransaction is similar.

For getting already-decoded logs meeting appropriate conditions, see WireDecoder.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 { forContractAbstraction } from "@truffle/decoder";
const contract = artifacts.require("Contract");
const otherContract = artifacts.require("OtherContract");
const deployedContract = await contract.deployed();
const instanceDecoder = await Decoder.forContractAbstraction(deployedContract, [otherContract]);
const variables = await instanceDecoder.variables();

These examples are not exhaustive.

See the API documentation for more advanced decoding examples with variable or watchMappingKey.