{"id":14230,"library":"viem-deal","title":"Viem Deal Helper","description":"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.","status":"active","version":"2.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/Rubilmax/viem-deal","tags":["javascript","viem","deal","hardhat","anvil","test","cheat","rpc","erc20","typescript"],"install":[{"cmd":"npm install viem-deal","lang":"bash","label":"npm"},{"cmd":"yarn add viem-deal","lang":"bash","label":"yarn"},{"cmd":"pnpm add viem-deal","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core client library that viem-deal extends with additional actions. viem is a TypeScript interface for Ethereum providing low-level stateless primitives for interaction.","package":"viem","optional":false}],"imports":[{"note":"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.","wrong":"const { dealActions } = require('viem-deal');","symbol":"dealActions","correct":"import { dealActions } from 'viem-deal';"},{"note":"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.","wrong":"import { createClient } from 'viem';","symbol":"createTestClient","correct":"import { createTestClient, http } from 'viem';"},{"note":"`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.","wrong":"import { anvil } from 'viem/chains';","symbol":"foundry","correct":"import { foundry } from 'viem/chains';"}],"quickstart":{"code":"import { createTestClient, http, parseUnits } from 'viem';\nimport { foundry } from 'viem/chains';\nimport { dealActions } from 'viem-deal';\n\nconst client = createTestClient({\n  mode: 'anvil',\n  chain: foundry,\n  transport: http(),\n}).extend(dealActions);\n\nasync function runDealExample() {\n  const erc20Address = \"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"; // Example USDC address\n  const recipientAddress = \"0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266\"; // Example test address\n  const amount = parseUnits(\"100\", 6); // 100 USDC (6 decimals)\n\n  console.log(`Dealing ${amount} units of ERC20 ${erc20Address} to ${recipientAddress}...`);\n\n  await client.deal({\n    erc20: erc20Address,\n    account: recipientAddress,\n    amount: amount,\n  });\n\n  console.log('Deal successful. Check recipient balance.');\n}\n\nrunDealExample().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"In `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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Between `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.","severity":"gotcha","affected_versions":"2.0.3 - 2.0.4"}],"env_vars":null,"search_vec":"'2.0.4':15 '2024':18,139 'account':50,83 'achiev':71 'actual':117 'amount':43 'anvil':56,175 'arbitrari':42 'balanc':31,72,85,115 'base':61 'cadenc':130 'capabl':26 'chain':120 'cheat':69,148,177 'client':23 'code':70,149 'compar':154 'compat':53 'correct':78 'createaccesslist':88 'current':11 'deal':2,6,41,68,173 'design':19 'develop':33,39,169 'differenti':142 'dynam':75 'effici':105 'enabl':38 'ensur':164 'environ':54 'erc20':29,46,179 'eth':87 'experi':170 'extend':21 'fork':62 'foundri':66 'frequent':128 'function':64 'hardhat':57,174 'helper':3 'identifi':76 'interact':157 'javascript':171 'key':141 'librari':10,100 'like':55 'manipul':28,73 'method':106 'minor':135 'mint':121 'mirror':65 'multipl':132 'network':36 'octob':17,138 'on-chain':118 'overrid':91 'packag':159 'patch':133 'power':25 'precis':113 'project':125 'provid':101 'rapid':103 'releas':16,129,136 'relianc':145 'rpc':147,178 'safe':168 'scenario':111 'set':108 'setstorageat':52,98 'setup':153 'ship':160 'show':126 'slot':80,94 'stabl':13 'storag':79,93 'streamlin':151 'test':35,110,152,176 'tevm':60 'tevm-bas':59 'token':30,47,114 'transact':156 'transfer':123 'type':163,167 'type-saf':166 'typescript':162,180 'use':86 'util':9 'valu':96 'version':14 'viem':1,5,22,172 'viem-deal':4 'without':116","created_at":"2026-04-20T01:58:36.723508+00:00","updated_at":"2026-04-20T01:58:36.723508+00:00","problems":[{"fix":"Ensure your viem client is extended with `dealActions`: `const client = createTestClient(...).extend(dealActions);`","cause":"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.","error":"TypeError: client.deal is not a function"},{"fix":"Rename the `recipient` parameter to `account` in your `deal` function calls: `await client.deal({ erc20: '0x...', account: '0x...', amount: parseUnits('100', 6) });`","cause":"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.","error":"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'."},{"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.","cause":"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.","error":"ERR_MODULE_NOT_FOUND: Cannot find package 'viem-deal' imported from ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://viem-deal.vercel.app","github":"https://github.com/Rubilmax/viem-deal","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/viem-deal","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","database","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}