viem-deal

library2.0.4jsnpmunverified

viem-deal is a utility library, currently at stable version 2.0.4 (released October 2024), designed to extend viem clients with powerful capabilities for manipulating ERC20 token balances on development and test networks. It enables developers to "deal" arbitrary amounts of any ERC20 token to any account on `setStorageAt`-compatible environments like Anvil, Hardhat, or Tevm-based forks. This functionality mirrors Foundry's `deal` cheat code, achieving balance manipulation by dynamically identifying the correct storage slot for an account's balance using `eth_createAccessList` and then overriding that storage slot's value with `setStorageAt`. The library provides a rapid and efficient method for setting up test scenarios with precise token balances without actual on-chain minting or transfers. The project shows a frequent release cadence, with multiple patch and minor releases in October 2024. A key differentiator is its reliance on RPC cheat codes, which streamlines test setup compared to transactional interactions. The package ships with TypeScript types, ensuring a type-safe development experience.

testing database web-framework

npm install viem-deal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VIEM-DEAL

viem-deal

testingjavascriptv2.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dealActions

✓ import { dealActions } from 'viem-deal';

✗ const { dealActions } = require('viem-deal');

The library primarily uses ESM imports. While v2.0.3 briefly converted to CJS, v2.0.4 fixed module resolution, making ESM the intended and commonly used module system for modern Node.js environments.

createTestClient

✓ import { createTestClient, http } from 'viem';

✗ import { createClient } from 'viem';

When using `viem-deal` with local testing environments like Anvil, `createTestClient` is typically preferred over `createClient` for its specific test-oriented functionalities, often combined with an `anvil` mode transport.

foundry

✓ import { foundry } from 'viem/chains';

✗ import { anvil } from 'viem/chains';

`foundry` is often used to refer to the chain configuration for test environments compatible with Foundry's cheat codes, like Anvil, even though Anvil itself is also a test RPC. Using the correct chain import for the desired test environment is crucial.

This quickstart demonstrates how to set up a viem test client, extend it with `dealActions`, and then use the `deal` function to transfer 100 USDC to a specified test address on an Anvil-based local blockchain. It showcases the primary usage pattern for modifying ERC20 balances in a test environment.

import { createTestClient, http, parseUnits } from 'viem'; import { foundry } from 'viem/chains'; import { dealActions } from 'viem-deal'; const client = createTestClient({ mode: 'anvil', chain: foundry, transport: http(), }).extend(dealActions); async function runDealExample() { const erc20Address = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"; // Example USDC address const recipientAddress = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"; // Example test address const amount = parseUnits("100", 6); // 100 USDC (6 decimals) console.log(`Dealing ${amount} units of ERC20 ${erc20Address} to ${recipientAddress}...`); await client.deal({ erc20: erc20Address, account: recipientAddress, amount: amount, }); console.log('Deal successful. Check recipient balance.'); } runDealExample().catch(console.error);

Debug

Known issues

breakingIn `viem-deal` v2.0.0, the `recipient` parameter of the `deal` function was renamed to `account`. Additionally, the `account` parameter is now optional; if not provided, the default account of the client will be used.

fix

Update calls to the `deal` function to use `account` instead of `recipient`. For example, change `recipient: '0x...'` to `account: '0x...'`. If no account is provided, ensure the client is configured with a default account.

affects: >=2.0.0

gotchaThe package is known to have unexpected side effects when used to 'deal' dust (very small amounts) of stETH (staked Ether). This can lead to unpredictable behavior in tests or simulations.

fix

Avoid using `viem-deal` for very small amounts or 'dust' of stETH. If stETH balance manipulation is necessary, consider using larger, more substantial amounts or explore alternative methods specific to stETH's underlying mechanics.

affects: >=1.0.0

gotchaBetween `v2.0.3` and `v2.0.4`, there were changes related to module format and `.js` extensions. `v2.0.3` converted the package to CommonJS, while `v2.0.4` removed `.js` extensions from imports. This can lead to module resolution issues, especially when mixing ESM and CJS or with specific TypeScript `moduleResolution` settings.

fix

For projects using modern Node.js and TypeScript, ensure your `tsconfig.json` and `package.json` are configured for ESM (e.g., `"type": "module"`, `"module": "nodenext"` or `"bundler"` in `tsconfig.json`). If encountering `ERR_MODULE_NOT_FOUND`, verify import paths and consider updating to the latest patch version which might have stabilized module exports.

affects: 2.0.3 - 2.0.4

Errors

Common errors & fixes

TypeError: client.deal is not a function

The `dealActions` extension was not correctly applied to the viem client. The `deal` function is provided by `dealActions` and must be explicitly extended onto a client.

fix

Ensure your viem client is extended with `dealActions`: `const client = createTestClient(...).extend(dealActions);`

Argument of type '{ recipient: Address; erc20: Address; amount: bigint; }' is not assignable to parameter of type 'DealParameters'. Object literal may only specify known properties, and 'recipient' does not exist in type 'DealParameters'.

This error occurs in `viem-deal` v2.0.0 and later because the `recipient` parameter of the `deal` function was renamed to `account` in a breaking change.

fix

Rename the `recipient` parameter to `account` in your `deal` function calls: `await client.deal({ erc20: '0x...', account: '0x...', amount: parseUnits('100', 6) });`

ERR_MODULE_NOT_FOUND: Cannot find package 'viem-deal' imported from ...

This error typically indicates an issue with module resolution, often related to incorrect import paths, missing package installation, or mismatches between CommonJS and ES Modules environments, particularly after the module format changes in v2.0.3/v2.0.4.

fix

First, ensure `viem-deal` is installed (`npm install viem-deal`). Verify that your `import` statements are correct (e.g., `import { dealActions } from 'viem-deal';`). If using TypeScript or a bundler, confirm that your `tsconfig.json` (`"module"`, `"moduleResolution"`, `"type"`) and `package.json` (`"type"`) are configured correctly for ESM. Consider clearing `node_modules` and reinstalling.

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

viemrequiredCore client library that viem-deal extends with additional actions. viem is a TypeScript interface for Ethereum providing low-level stateless primitives for interaction.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Rubilmax/viem-deal ↗

packagehttps://www.npmjs.com/package/viem-deal ↗

homepagehttps://viem-deal.vercel.app ↗