Tracer

A class that encapsulates the storage access tracing functionality in an object-oriented interface, allowing for reusable tracers with consistent configuration.

Signature

import type { Abi, ContractFunctionName } from "tevm";
import type { TraceStateBaseOptions, TraceStateTxParams, TraceStateResult } from "@polareth/evmstate";
 
class Tracer {
  // @ts-expect-error - Constructor implementation is missing
  constructor(options: TraceStateBaseOptions);
  // @ts-expect-error - Function implementation is missing
  traceState<
    TAbi extends Abi | readonly unknown[] = Abi,
    TFunctionName extends ContractFunctionName<TAbi> = ContractFunctionName<TAbi>,
  >(txOptions: TraceStateTxParams<TAbi, TFunctionName>): Promise<TraceStateResult>;
}

Constructor

import type { TraceStateBaseOptions } from "@polareth/evmstate";
 
class Tracer {
  // @ts-expect-error - Constructor implementation is missing
  constructor(options: TraceStateBaseOptions);
}

Creates a new Tracer instance with shared configuration.

Parameters

Property	Type	Description
`rpcUrl`	`string \| undefined`	Ethereum RPC endpoint URL
`client`	`MemoryClient \| undefined`	Optional Tevm client instance
`explorers`	`Record<string, Explorer> \| undefined`	Optional contract explorers configuration

You must provide either rpcUrl or client.

Methods

traceState

import type { Abi, ContractFunctionName } from "tevm";
import type { TraceStateTxParams, TraceStateResult } from "@polareth/evmstate";
 
class Tracer {
  // @ts-expect-error - Function implementation is missing
  traceState<
    TAbi extends Abi | readonly unknown[] = Abi,
    TFunctionName extends ContractFunctionName<TAbi> = ContractFunctionName<TAbi>,
  >(txOptions: TraceStateTxParams<TAbi, TFunctionName>): Promise<TraceStateResult>;
}

Traces the storage access patterns for a transaction, using the shared configuration from the constructor.

Parameters

Property	Type	Description
`from`	`Address`	The sender address
`to`	`Address \| undefined`	The recipient address
`data`	`Hex \| undefined`	The transaction calldata
`value`	`bigint \| undefined`	Optional ETH amount to send
`abi`	`TAbi \| undefined`	Optional contract ABI
`functionName`	`TFunctionName \| undefined`	Optional function name
`args`	`unknown[] \| undefined`	Optional function arguments

Just like the standalone traceState function, the Tracer.traceState method either takes encoded calldata or an ABI function call.

Return value

Returns a promise that resolves to a record mapping account addresses to their state changes:

import type { TraceStateResult } from "@polareth/evmstate";
 
type ReturnType = TraceStateResult;

See the output format reference for details on the structure.

Examples

Basic usage

import { Tracer } from "@polareth/evmstate";
 
// Create tracer with shared configuration
const tracer = new Tracer({
  rpcUrl: "https://1.rpc.thirdweb.com",
});
 
// Trace multiple transactions
const trace1 = await tracer.traceState({
  from: "0xSenderAddress",
  to: "0xContractAddress",
  data: "0xCalldata1",
});
 
const trace2 = await tracer.traceState({
  from: "0xSenderAddress",
  to: "0xContractAddress",
  data: "0xCalldata2",
});

With custom Tevm client

import { createMemoryClient, http } from "tevm";
import { mainnet } from "tevm/common";
import { Tracer } from "@polareth/evmstate";
 
// Create custom Tevm client
const client = createMemoryClient({
  common: mainnet,
  fork: {
    transport: http("https://1.rpc.thirdweb.com"),
    blockTag: "latest",
  },
});
 
// Create tracer with custom client
const tracer = new Tracer({ client });
 
// Trace a transaction
const trace = await tracer.traceState({
  from: "0xSenderAddress",
  to: "0xContractAddress",
  data: "0xCalldata",
  value: 1000000000000000000n, // 1 ETH
});

With contract ABI

example.ts

import { Tracer } from "@polareth/evmstate";
 
// Create tracer
const tracer = new Tracer({
  rpcUrl: "https://1.rpc.thirdweb.com",
});
 
// Trace an ERC-20 transfer
const transferTrace = await tracer.traceState({
  from: "0xSenderAddress",
  to: "0xTokenAddress",
  abi: erc20Abi,
  functionName: "transfer",
  args: ["0xRecipient", 1000000000000000000n], // recipient, amount
});

Tracing an existing transaction

import { Tracer } from "@polareth/evmstate";
 
const tracer = new Tracer({
  rpcUrl: "https://1.rpc.thirdweb.com",
});
 
const trace = await tracer.traceState({
  txHash: "0x1234567890abcdef...",
});