Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
traceActions
✓ import { traceActions } from 'viem-tracer';
✗ const { traceActions } = require('viem-tracer');
Used to extend a Viem client with the `client.traceCall` action for programmatic tracing.
traced
✓ import { traced } from 'viem-tracer';
✗ import traced from 'viem-tracer';
A higher-order function that wraps a Viem transport to enable automatic tracing for failed or all transactions. It is a named export, not a default.
TracerConfig
✓ import { type TracerConfig } from 'viem-tracer';
TypeScript type for configuring the tracer behavior, specifying when to trace (all, next, failed transactions).
This quickstart demonstrates how to integrate `viem-tracer` with a Viem client, showing both programmatic `client.traceCall` usage and automatic tracing for failed transactions with detailed output.
import { createTestClient, http, parseEther } from 'viem';
import { foundry, goerli } from 'viem/chains';
import { traceActions, traced } from 'viem-tracer';
import { erc20Abi } from 'viem/abis';
// For demonstration, use a local test client (Anvil/Foundry) or a testnet client with debug_traceCall support.
// Replace 'YOUR_QUICKNODE_RPC_URL' with an actual RPC endpoint supporting debug_traceCall.
const client = createTestClient({
mode: "anvil", // or "hardhat"
chain: foundry,
transport: traced(
http(process.env.RPC_URL ?? ''),
{ failed: true } // Trace only failed transactions by default
),
}).extend(traceActions);
async function runTraceExample() {
try {
// Example 1: Programmatic traceCall
console.log('--- Programmatic traceCall Example ---');
const traceResult = await client.traceCall({
account: "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e", // From address
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // To address
value: parseEther("1"),
data: '0x', // No specific function call, just sending ETH
// tracer: "callTracer", // Defaults to "callTracer"
});
console.log('Trace Result for ETH transfer:', traceResult);
// Example 2: Automatic tracing for a failing transaction
console.log('\n--- Automatic Trace on Failed Transaction Example ---');
// This transaction is designed to fail due to insufficient balance
await client.writeContract({
abi: erc20Abi,
address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Mainnet, likely wrong for Foundry
functionName: "transfer",
args: ["0xA0Cf798816D4b9b9866b5330EEa46a18382f251e", 100_000000n],
account: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" // Example account from Foundry
});
} catch (error) {
console.error('Caught an error:', error.message); // Should include trace
}
}
runTraceExample();
Debug
Known issues
gotchaViem-tracer relies on the underlying RPC provider supporting `debug_traceCall` or similar tracing APIs. Not all public RPC endpoints support this, especially for mainnet. Local development environments like Anvil or Hardhat (configured via `foundry` or `hardhat` chains in Viem) are typically required for full functionality.fixEnsure your `viem` client is connected to a compatible RPC endpoint (e.g., Anvil, Hardhat, or a QuickNode/Alchemy endpoint with `debug_traceCall` enabled). For local testing, use `createTestClient` with `mode: 'anvil'` or `mode: 'hardhat'`.
affects: >=1.0.0
gotchaThe `viem-tracer` library decorates the Viem `transport` and extends the `client` object. It's crucial to set up the `traced` transport wrapper *before* extending the client with `traceActions` to ensure proper integration and access to tracing capabilities on the client object.fixWrap your `http()` or other transport with `traced()` first, then call `.extend(traceActions)` on the `createClient` or `createTestClient` result, as shown in the quickstart example.
affects: >=1.0.0
breakingThe peer dependency `viem` has specific version requirements. As of `viem-tracer@1.8.0`, it requires `viem@^2.21.0`. Using an older or incompatible version of `viem` may lead to type errors, runtime issues, or unexpected behavior.fixEnsure your `viem` package version matches the peer dependency requirement specified in `viem-tracer`'s `package.json`. Upgrade `viem` if necessary: `npm install viem@^2.21.0` or `yarn add viem@^2.21.0`.
affects: >=1.0.0 (check `package.json` for exact peer dep)
Errors
Common errors & fixes
TypeError: client.traceCall is not a function
The `traceActions` extension was not applied to the Viem client, or it was applied incorrectly.
fixMake sure you are calling `.extend(traceActions)` on your `createClient` or `createTestClient` instance, for example: `createTestClient(...).extend(traceActions);`
ProviderError: Method debug_traceCall not found
The connected RPC endpoint does not support the `debug_traceCall` method, which is required by `viem-tracer` for detailed transaction tracing.
fixSwitch to an RPC provider that supports `debug_traceCall`. This typically includes local development environments like Anvil or Hardhat, or specialized RPC services (e.g., QuickNode, Alchemy) that explicitly enable debug APIs. Update your `http()` transport to point to a compatible URL.
Error: ERC20: transfer amount exceeds balance
This error message (or similar revert reasons) is automatically augmented by `viem-tracer` to include a decoded call trace, indicating a transaction failure.
fixThis is often the *output* of `viem-tracer` doing its job, not a problem with the tracer itself. The fix is to debug the underlying smart contract logic or transaction parameters (e.g., ensure sufficient balance, correct allowances, or valid inputs) using the provided trace.
Audit
Dependencies
viemrequiredCore Ethereum client library that viem-tracer extends and integrates with.