Options
Public
  • Public
  • Public/Protected
  • All
Menu

External module @truffle/decoder

Truffle Decoder

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 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.

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 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 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 decodings = 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 { 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.

Index

Decoder Classes

Exception Classes

Inputs Interfaces

Results Interfaces

Inputs Type aliases

Provider-based Constructor Functions

Truffle Contract-based Constructor Functions

Inputs Type aliases

BlockSpecifier

BlockSpecifier: number | "genesis" | "latest" | "pending"

Specifies a block. Can be given by number, or can be given via the special strings "genesis", "latest", or "pending".

Intended to work like Web3's BlockType.

Warning: Using "pending", while allowed, is not advised, as it may lead to internally inconsistent results. Use of "latest" is safe and will not lead to inconsistent results from a single decoder call due to the decoder's caching system, but pending blocks cannot be cached under this system, which may cause inconsistencies.

Provider-based Constructor Functions

forAddress

  • This function is asynchronous.

    Constructs a contract instance decoder for a given instance of a contract in this project. Unlike the other functions, this method doesn't require giving an artifact for the address itself; however, the address had better correspond to a contract of a type given in the project info, or you'll get an exception.

    Parameters

    • address: string

      The address of the contract instance to decode. If an invalid address is provided, this method will throw an exception.

    • provider: Provider

      The Web3 provider object to use.

    • projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. See the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forProject for more detail.

    Returns Promise<ContractInstanceDecoder>

forArtifact

  • This function is asynchronous.

    Constructs a contract decoder for a given contract artifact.

    Parameters

    • artifact: Artifact

      The artifact for the contract.

      A contract constructor object may be substituted for the artifact, so if you're not sure which you're dealing with, it's OK.

    • provider: Provider

      The Web3 provider object to use.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms; see the ProjectInfo documentation for more information.

      Alternatively, instead of a ProjectInfo, one may simply pass a list of artifacts. Contract constructor objects may be substituted for artifacts, so if you're not sure which you're dealing with, it's OK.

      If this latter option is used, one may omit artifact itself from the list of artifacts and only include the other relevant artifacts; note that omission this is not allowed when passing a ProjectInfo.

      If this parameter is omitted, it's treated as if one had passed [].

    Returns Promise<ContractDecoder>

forArtifactAt

  • This function is asynchronous.

    Constructs a contract instance decoder for a contract instance at a given address.

    Parameters

    • artifact: Artifact

      The artifact corresponding to the type of the contract.

      A contract constructor object may be substituted for the artifact, so if you're not sure which you're dealing with, it's OK.

    • provider: Provider

      The Web3 provider object to use.

    • address: string

      The address of the contract instance to decode.

      Address must either be checksummed, or in all one case to circumvent the checksum. Mixed-case with bad checksum will cause this function to throw an exception.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. see the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractInstanceDecoder>

forDeployedArtifact

  • This function is asynchronous.

    Constructs a contract instance decoder for a deployed contract instance.

    Parameters

    • artifact: Artifact

      The artifact corresponding to the type of the contract.

      A contract constructor object may be substituted for the artifact, so if you're not sure which you're dealing with, it's OK.

    • provider: Provider

      The Web3 provider object to use.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. see the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractInstanceDecoder>

forProject

  • This function is asynchronous.

    Constructs a wire decoder for the project.

    Parameters

    • provider: Provider

      The Web3 provider object to use.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project or contracts being decoded. This may come in several forms; see the ProjectInfo documentation for more information.

      Alternatively, instead of a ProjectInfo, one may simply pass a list of artifacts. Contract constructor objects may be substituted for artifacts, so if you're not sure which you're dealing with, it's OK. If this parameter is omitted, it's treated as if one had passed [].

    Returns Promise<WireDecoder>

infoToCompilations

Truffle Contract-based Constructor Functions

forContract

  • This function is asynchronous.

    Constructs a contract decoder for a given contract.

    Parameters

    • contract: ContractConstructorObject

      The contract constructor object corresponding to the type of the contract.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. See the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractDecoder>

forContractAt

  • This function is asynchronous.

    Constructs a contract instance decoder for a contract instance at a given address.

    Parameters

    • contract: ContractConstructorObject

      The contract constructor object corresponding to the type of the contract.

    • address: string

      The address of the contract instance to decode.

      Address must either be checksummed, or in all one case to circumvent the checksum. Mixed-case with bad checksum will cause this function to throw an exception.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. see the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractInstanceDecoder>

forContractInstance

  • This function is asynchronous.

    Constructs a contract instance decoder for a given contract instance.

    Parameters

    • contract: ContractInstanceObject

      The contract abstraction object corresponding to the contract instance.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. see the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractInstanceDecoder>

forDeployedContract

  • This function is asynchronous.

    Constructs a contract instance decoder for a deployed contract instance.

    Parameters

    • contract: ContractConstructorObject

      The contract constructor object corresponding to the type of the contract.

    • Optional projectInfo: ProjectInfo | Artifact[]

      Information about the project being decoded, or just the contracts relevant to the contract being decoded (e.g., by providing struct or enum definitions, or even just appearing as a contract type). This may come in several forms. see the ProjectInfo documentation for more information. See the projectInfo parameter documentation on forArtifact for more detail.

    Returns Promise<ContractInstanceDecoder>

Generated using TypeDoc