How to use @truffle/decoder outside truffle project?

[TheStarBoys]

I want to decode state variables by using truffle decoder, but am stuck for construction of decoder.
In the documentation, it shows I must use artifacts to import contract artifacts.

"artifacts" seems to be a global value injected by truffle runtime. Is there a way to get artifacts without truffle runtime? Or, where is "artifacts" available besides in migration and testing scripts?

I need help please.

[gnidan]

Hey! Thanks for reaching out about this!

Two things:

1. Firstly, what's your use case? I'm guessing you have some Hardhat or Foundry project and you want to import your contract source information from that project into @truffle/decoder?
2. In the meantime, I just reworked an old demo to hopefully get you started. It uses @truffle/fetch-and-compile to instantiate @truffle/decoder using verified contracts from Etherscan and/or Sourcify. Note: the demo shows how to decode transactions, not variables like you're asking about... hopefully this is at least a good starting point for you.

Apologies about not having good documentation for using @truffle/decoder outside of Truffle contexts... we will certainly have to remedy this soon (and maybe even build handy Hardhat/Foundry shims!), but until then, perhaps this can be a starting point for you.

But first, a direct answer: @truffle/decoder needs a ProjectInfo object with a list of Compilation objects passed as commonCompilations. It's probably not much help, but in theory you could follow those type specifications and shim whatever source information you have into the format @truffle/decoder expects... (please let me know if you're going that route! happy to help answer questions!)

Example transaction decoding with @truffle/fetch-and-compile

The following demonstrates how to decode transactions (calldata and events) for verified contracts on public networks. I'll split things up into helper functions + one main decode() interface, but ℹ️ see this gist for everything put together.

Take a look to see what this will give you (approximately):

🖼️ Screenshot of this example decoding a complex transaction.

Anyway, I'll start with the entrypoint and then list the helper functions:

Entrypoint (decode() function)

decode()

export async function decode(options: {
  transactionHash: string;
  showLogs?: boolean;
  raw?: boolean;
}) {
  const {
    transactionHash,
    showLogs,
    raw
  } = options;

  // initialize provider from environment variables
  const { provider, etherscanKey } = getEnvironment();

  // read transaction and receipt
  const { transaction, logs, relatedAddresses } = await getTransactionInfo({
    transactionHash,
    provider
  });

  // uses @truffle/fetch-and-compile for verified contract source
  const projectInfo = await getProjectInfo({
    addresses: relatedAddresses,
    provider,
    etherscanKey
  });

  // initialize decoder
  const decoder = await Decoder.forProject({
    provider,
    projectInfo
  });

  // decode calldata
  const calldataDecoding = await decoder.decodeTransaction(transaction);

  // decode logs
  const logDecodings = showLogs
    ? await Promise.all(
        logs.map(async (log) => {
          const possibleDecodings = await decoder.decodeLog(log);
          return possibleDecodings[0];
        })
      )
    : [];

  showDecodings({
    calldataDecoding,
    logDecodings,
    raw
  });
}

^ This function reads verified contracts from Etherscan and/or Sourcify, using the source information to decode transaction calldata and emitted events. Decoded results are printed to console.

As implemented, this accepts two flags: options.showLogs turns on event decoding (off by default), and options.raw disables pretty-printing.

Helper functions

getEnvironment() - reads environment variables for JSON RPC URL and Etherscan API key

export function getEnvironment(): {
  provider: Provider;
  etherscanKey: string;
} {
  const rpcUrl = process.env.MAINNET_URL || "";
  const etherscanKey = process.env.ETHERSCAN_KEY || "";

  const web3 = new Web3(rpcUrl);
  const provider = web3.currentProvider as any;

  return { provider, etherscanKey };
}

getTransactionInfo() - gets relevant transaction info from the blockchain

export async function getTransactionInfo(options: {
  provider: Provider;
  transactionHash: string;
}): Promise<{
  transaction: Decoder.Transaction;
  logs: Decoder.Log[];
  relatedAddresses: string[];
}> {
  const {
    transactionHash,
    provider
  } = options;

  const web3 = new Web3(provider);

  const {
    to,
    blockNumber,
    from,
    input
  } = await web3.eth.getTransaction(transactionHash);

  const {
    contractAddress,
    logs
  } = await web3.eth.getTransactionReceipt(transactionHash);

  const relatedAddresses = Array.from(new Set([
    to,
    contractAddress,
    ...logs.map(({ address }) => address)
  ])).filter(
    (address: string | undefined | null): address is string => !!address
  );

  return {
    transaction: {
      to,
      from,
      input,
      blockNumber
    },
    logs,
    relatedAddresses
  };
}

getProjectInfo() - invokes @truffle/fetch-and-compile and returns decoder input

export async function getProjectInfo(options: {
  provider: Provider;
  addresses: string[];
  etherscanKey: string;
}): Promise<Decoder.ProjectInfo> {
  const {
    addresses,
    provider,
    etherscanKey
  } = options;

  const web3 = new Web3(provider);
  const networkId = await web3.eth.net.getId();

  const { results } = await fetchAndCompileMultiple(
    addresses,
    {
      network: {
        networkId
      },
      fetcherOptions: {
        etherscan: {
          apiKey: etherscanKey
        }
      },
      compile: {
        docker: true
      }
    }
  );

  const commonCompilations = Object.values(results)
    .map(({ compileResult }) => compileResult.compilations)
    .reduce((a, b) => ([...a, ...b]), []);

  return { commonCompilations };
};

showDecodings() - print calldata and optionally print event decodings (pass options.raw to turn off custom pretty-printing)

export function showDecodings(options: {
  calldataDecoding: Codec.CalldataDecoding;
  logDecodings?: (Codec.LogDecoding | undefined)[];
  raw?: boolean;
}): void {
  const {
    calldataDecoding,
    logDecodings = [],
    raw = false,
  } = options;

  // print output
  console.group(chalk.bold("Transaction"));
  if (raw) {
    console.log(
      util.inspect(calldataDecoding, { colors: true, depth: null })
    );
  } else {
    console.log(
      new Codec.Export.CalldataDecodingInspector(calldataDecoding)
    );
  }
  console.groupEnd();

  if (logDecodings.length > 0) {
    console.log("");
    console.group(chalk.bold("Logs"));
    for (const logDecoding of logDecodings) {
      if (logDecoding) {
        if (raw) {
          console.log(
            util.inspect(logDecoding, { colors: true, depth: null })
          );
        } else {
          console.log(
            new Codec.Export.LogDecodingInspector(logDecoding)
          );
        }
      } else {
        console.log("- <could not decode event>");
      }
    }
    console.groupEnd();
  }
}

That's about it! I didn't bother including a package.json or any kind of CLI wrapper, so you'll need to install the dependencies and call decode() yourself somewhere.

Make sense? (🔍 In case you need it, here's that link to the full example code again. 😄)

[TheStarBoys]

It's very helpful for me. It's straightforward to make me understand how to use @truffle/decoder to decode calldata and logs. I can base on this example code to achieve my own functionality. I really need this to parsing information about the smart contracts for analyzing some potential security issues of on-chain them. Sometimes, you know, some state variables is private, solidity doesn't generate public getter for these variables. It's helpful that there is an easy way to decode these information. Thanks for your help. And thanks truffle team providing these convenient libraries!

[gnidan]

awesome! glad this helps! please reach out again if you have more questions

[TheStarBoys]

No problem! Thanks for your kind! I will keep up research on this.