# Module decoder/lib

# 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 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|`forProject`]] function.

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

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

- [[forDeployedArtifact|`forDeployedArtifact`]]
- [[forDeployedContract|`forDeployedContract`]]
- [[forArtifactAt|`forArtifactAt`]]
- [[forContractAt|`forContractAt`]]
- [[forContractInstance|`forContractInstance`]]
- [[forAddress|`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|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 [[ProjectDecoder.decodeTransaction|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 [[forDeployedContract|`forContractInstance`]] to perform both of these in one step. If we wanted to do this with a specified address, we could use [[forContractAt|`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 [[ContractInstanceDecoder.variable|`variable`]] and [[ContractInstanceDecoder.watchMappingKey|`watchMappingKey`]] at the documentation for these individual functions. * *

- Defined in decoder/lib/index.ts:1

#####
Index

### References

ExtrasAllowed
StateVariable

### Classes - Decoder

ContractDecoder
ContractInstanceDecoder
ProjectDecoder

### Classes - Exception

ContractAllocationFailedError
ContractBeingDecodedHasNoNodeError
ContractNotFoundError
InvalidAddressError
VariableNotFoundError

### Classes - Other

NoProviderError

### Interfaces - Inputs

DecodeLogOptions
EventOptions
Log
ReturnOptions
Transaction

### Interfaces - Results

ContractState
DecodedLog

### Interfaces - Other

DecoderSettings
EnsSettings

### Type Aliases

ProjectInfo

### Functions - Provider-based Constructor

forAddress
forArtifact
forArtifactAt
forDeployedArtifact
forProject

### Functions - Truffle Contract-based Constructor

forContract
forContractAt
forContractInstance
forDeployedContract

## References

### ExtrasAllowed

Re-exports ExtrasAllowed

### StateVariable

Re-exports StateVariable

Generated using TypeDoc