dequanto 0.2.50 → 0.2.51

package/{docs/ai → skills/dequanto}/examples/send-transaction.spec.ts

@@ -1,10 +1,10 @@
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { TxDataBuilder } from '@dequanto/txs/TxDataBuilder';
-import { TxWriter } from '@dequanto/txs/TxWriter';
-import { $account } from '@dequanto/utils/$account';
-import { $address } from '@dequanto/utils/$address';
-import { $number } from '@dequanto/utils/$number';
-import { $require } from '@dequanto/utils/$require';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { TxDataBuilder } from 'dequanto/txs/TxDataBuilder';
+import { TxWriter } from 'dequanto/txs/TxWriter';
+import { $account } from 'dequanto/utils/$account';
+import { $address } from 'dequanto/utils/$address';
+import { $number } from 'dequanto/utils/$number';
+import { $require } from 'dequanto/utils/$require';
 
 UTest({
     async 'build native transfer tx data with gas fields' () {

package/skills/dequanto/examples/storage.spec.ts

@@ -0,0 +1,58 @@
+import { AavePool } from '../../../0xc/eth/AavePool/AavePool';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { HardhatProvider } from 'dequanto/hardhat/HardhatProvider';
+import { SlotsParser } from 'dequanto/solidity/SlotsParser';
+import { SlotsStorage } from 'dequanto/solidity/SlotsStorage';
+import { $require } from 'dequanto/utils/$require';
+
+// Generated classes include the storage layout: use instance.storage.$set(name, value).
+// SlotsParser and SlotsStorage provide the low-level alternative for Solidity source.
+UTest({
+    async 'read and set AavePool storage by variable name on an Ethereum fork' () {
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const pool = new AavePool(undefined, client);
+        const premiumBefore = await pool.FLASHLOAN_PREMIUM_TOTAL();
+        const packedNeighborBefore = await pool.storage.__DEPRECATED_flashLoanPremiumToProtocol();
+        const id = await client.debug.snapshot();
+
+        try {
+            const premium = premiumBefore + 1n;
+            await pool.storage.$set('_flashLoanPremium', premium);
+
+            $require.eq(await pool.storage._flashLoanPremium(), premium);
+            $require.eq(await pool.FLASHLOAN_PREMIUM_TOTAL(), premium);
+            // Both uint128 fields share slot 58; preserve the neighboring field.
+            $require.eq(await pool.storage.__DEPRECATED_flashLoanPremiumToProtocol(), packedNeighborBefore);
+        } finally {
+            await client.debug.revert(id);
+        }
+
+        $require.eq(await pool.FLASHLOAN_PREMIUM_TOTAL(), premiumBefore);
+    },
+
+    async 'read and write Solidity storage with SlotsParser and SlotsStorage' () {
+        const code = `
+            contract Vault {
+                uint256 public count = 123;
+                mapping(address => uint256) balances;
+
+                constructor () {
+                    balances[address(0x1000000000000000000000000000000000000001)] = 7;
+                }
+            }
+        `;
+        const hh = new HardhatProvider();
+        const client = await Web3ClientFactory.getAsync('hh:memory');
+        const { contract } = await hh.deployCode(code, { client });
+
+        const slots = await SlotsParser.slots({ path: '', code }, 'Vault');
+        const storage = SlotsStorage.createWithClient(client, contract.address, slots);
+
+        $require.eq(await storage.get('count'), 123n);
+        $require.eq(await storage.get('balances["0x1000000000000000000000000000000000000001"]'), 7n);
+
+        // Direct storage writes require a debug network such as Hardhat.
+        await storage.set('count', 500n);
+        $require.eq(await storage.get('count'), 500n);
+    }
+});

package/{docs/ai → skills/dequanto}/examples/token-transfer.spec.ts

@@ -1,8 +1,8 @@
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { ERC20 } from '@dequanto/prebuilt/openzeppelin/ERC20';
-import { $account } from '@dequanto/utils/$account';
-import { $erc20 } from '@dequanto/utils/$erc20';
-import { $require } from '@dequanto/utils/$require';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+import { $account } from 'dequanto/utils/$account';
+import { $erc20 } from 'dequanto/utils/$erc20';
+import { $require } from 'dequanto/utils/$require';
 
 const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
 const INITIAL_SENDER_BALANCE = 100_000_000n;

package/skills/dequanto/examples/utils.spec.ts

@@ -0,0 +1,63 @@
+import { $abi } from 'dequanto/abi/$abi';
+import { $contract } from 'dequanto/utils/$contract';
+import { $date } from 'dequanto/utils/$date';
+import { $hex } from 'dequanto/utils/$hex';
+import { $promise } from 'dequanto/utils/$promise';
+import { $require } from 'dequanto/utils/$require';
+import { $sig } from 'dequanto/utils/$sig';
+
+const ACCOUNT = '0x0000000000000000000000000000000000000002';
+
+UTest({
+    'encode and decode ABI values and calldata' () {
+        const encoded = $abi.encode(['address', 'uint256'], [ACCOUNT, 5n]);
+        const [account, amount] = $abi.decode(['address', 'uint256'], encoded);
+        const calldata = $abi.encodeCall(
+            'function transfer(address to, uint256 amount)',
+            [ACCOUNT, 5n]
+        );
+
+        $require.eq(account, ACCOUNT);
+        $require.eq(amount, 5n);
+        $require.eq(
+            calldata,
+            '0xa9059cbb00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000005'
+        );
+        $require.eq(
+            $abi.decodeReturn<bigint>(
+                'function totalSupply() view returns (uint256)',
+                $abi.encode('uint256', 10n)
+            ),
+            10n
+        );
+    },
+
+    'hash Solidity values and manipulate hex' () {
+        const topic = $contract.keccak256('Transfer(address,address,uint256)');
+        const payload = $hex.concat([$hex.ensure('1234'), $hex.toHexBuffer(5)]);
+
+        $require.eq(topic, '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef');
+        $require.eq(payload, '0x123405');
+        $require.eq($hex.padBytes('0x2a', 4), '0x0000002a');
+        $require.eq($hex.getBytes(payload, 0, 2), '0x1234');
+        $require.eq($hex.getBytesLength(payload), 3);
+    },
+
+    async 'validate values, dates, signatures, and promise results' () {
+        $require.eq($date.parseTimespan('5days', { get: 's' }), 432_000);
+        $require.AddressNotEmpty(ACCOUNT);
+        $require.BigInt(5n, 'Expected an amount', { min: 1n });
+
+        const signer = $sig.$account.generate();
+        const signature = await $sig.signMessage('Hello dequanto', signer);
+        $require.eq($sig.recoverMessage('Hello dequanto', signature), signer.address);
+
+        const success = await $promise.caught(Promise.resolve(42));
+        const failure = await $promise.caught(Promise.reject(new Error('Expected failure')));
+
+        $require.eq(success.result, 42);
+        $require.Null(success.error);
+        $require.notNull(failure.error);
+        $require.eq(failure.error.message, 'Expected failure');
+    }
+});

package/{docs/ai → skills/dequanto}/references/contracts.md

@@ -48,7 +48,7 @@ const balance = await token.balanceOf(account);
 For ad hoc reads without a generated class:
 
 ```ts
-import { ContractReader } from '@dequanto/contracts/ContractReader';
+import { ContractReader } from 'dequanto/contracts/ContractReader';
 
 const reader = new ContractReader(client);
 const symbol = await reader.readAsync<string>(

package/{docs/ai → skills/dequanto}/references/deployments.md

@@ -2,6 +2,8 @@
 
 Use `HardhatProvider` for compile/deploy helper flows and `Deployments` for idempotent deployments, deployment storage, bytecode checks, proxy upgrades, beacon proxies, and verification.
 
+See [Hardhat development and forking](hardhat.md) for creating development networks and live-contract forks, impersonating accounts, changing balances/storage, and restoring snapshots.
+
 Key source files:
 
 - `src/hardhat/HardhatProvider.ts`
@@ -21,7 +23,7 @@ Useful tests:
 ## HardhatProvider
 
 ```ts
-import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
+import { HardhatProvider } from 'dequanto/hardhat/HardhatProvider';
 
 const hh = new HardhatProvider();
 const client = hh.client();
@@ -43,7 +45,7 @@ Common methods:
 ## Idempotent Deployments
 
 ```ts
-import { Deployments } from '@dequanto/contracts/deploy/Deployments';
+import { Deployments } from 'dequanto/contracts/deploy/Deployments';
 
 const deployments = new Deployments(client, deployer, {
     directory: './deployments/',

package/{docs/ai → skills/dequanto}/references/events-indexing.md

@@ -34,7 +34,7 @@ Use `'*'` for all events, or an event-name array for multiple events.
 ## EventsIndexer
 
 ```ts
-import { EventsIndexer } from '@dequanto/indexer/EventsIndexer';
+import { EventsIndexer } from 'dequanto/indexer/EventsIndexer';
 
 const indexer = new EventsIndexer(contract, {
     name: 'TokenTransfers',

package/{docs/ai → skills/dequanto}/references/explorer.md

@@ -19,7 +19,7 @@ Useful tests:
 ## Create Explorer
 
 ```ts
-import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
+import { BlockchainExplorerFactory } from 'dequanto/explorer/BlockchainExplorerFactory';
 
 const explorer = BlockchainExplorerFactory.get('eth');
 ```

package/{docs/ai → skills/dequanto}/references/generation.md

@@ -2,13 +2,13 @@
 
 TypeScript class generation is a core dequanto workflow. Prefer generated contract classes over raw ABI calls: generated classes let application code call contracts as ordinary TypeScript classes, with no direct web3-specific ABI encoding, decoding, or JSON-RPC plumbing.
 
-Before generating a contract, check whether dequanto already ships a prebuilt class. The package includes OpenZeppelin contract classes under `dequanto/prebuilt/**` / `@dequanto/prebuilt/openzeppelin/**`. Class names match the OpenZeppelin contract names, for example `ERC20`, `ERC721`, `Ownable`, or `TimelockController`.
+Before generating a contract, check whether dequanto already ships a prebuilt class. The package includes OpenZeppelin contract classes under `dequanto/prebuilt/**` / `dequanto/prebuilt/openzeppelin/**`. Class names match the OpenZeppelin contract names, for example `ERC20`, `ERC721`, `Ownable`, or `TimelockController`.
 
 For standard OpenZeppelin contracts, do not generate a new class. Import the prebuilt class and pass the target contract address plus a chain client loaded by platform/chain abbreviation:
 
 ```ts
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { ERC20 } from '@dequanto/prebuilt/openzeppelin/ERC20';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
 
 const platform = 'eth';
 const address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
@@ -71,7 +71,7 @@ By default, `0xweb install` saves the downloaded Solidity sources next to the ge
 The generated class can then be imported and used like a normal TypeScript class:
 
 ```ts
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
 import { USDC } from './0xc/eth/USDC/USDC';
 
 const client = await Web3ClientFactory.getAsync('eth');
@@ -121,7 +121,7 @@ Use `Generator` directly only for custom generation tasks, test fixtures, non-Ha
 ### Generate From Compiled Artifact
 
 ```ts
-import { Generator } from '@dequanto/gen/Generator';
+import { Generator } from 'dequanto/gen/Generator';
 
 const gen = new Generator({
     name: 'AnyERC20',
@@ -180,7 +180,7 @@ When a contract is generated from verified on-chain source, such as with `0xweb
 Use `GeneratorStorageReader` when the task needs generated storage accessors without generating the full contract class.
 
 ```ts
-import { GeneratorStorageReader } from '@dequanto/gen/GeneratorStorageReader';
+import { GeneratorStorageReader } from 'dequanto/gen/GeneratorStorageReader';
 
 const gen = new GeneratorStorageReader();
 const result = await gen.generate({

package/skills/dequanto/references/hardhat.md

@@ -0,0 +1,113 @@
+# Hardhat Development And Forking
+
+Dequanto integrates Hardhat as a development and forking network for contract development and experimenting with live contracts on a local fork. Use `client.debug` to mine blocks, change balances and storage, impersonate accounts, and restore snapshots. These changes affect the local network only.
+
+Key source files:
+
+- `src/clients/Web3ClientFactory.ts`
+- `src/hardhat/HardhatProvider.ts`
+- `src/hardhat/HardhatWeb3Client.ts`
+- `src/clients/debug/ClientDebugMethods.ts`
+- `src/utils/$erc20.ts`
+- `src/txs/TxWriter.ts`
+
+Runnable examples: [Hardhat debug operations](../examples/hardhat-debug.spec.ts) and [forked ERC20 transfers](../examples/hardhat-fork.spec.ts). The fork example requires an accessible Ethereum RPC.
+
+## Create A Network Or Fork
+
+Use a project with Hardhat installed and a `hardhat.config.*` file.
+
+```ts
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+
+// Initialize an in-memory Ethereum fork using the platform's default/configured RPCs.
+const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+```
+
+Replace `eth` with the platform to fork. Optionally pass `{ block: 20_000_000, url: 'https://...' }` as the second argument to select a block and override the source RPC. Initializing an in-memory fork resets the shared Hardhat network; create it before taking snapshots or changing state.
+
+To use a separately running local Hardhat node, start it with Ethereum forking configured through Hardhat's normal node setup, then connect:
+
+```ts
+const client = await Web3ClientFactory.getAsync('hh:eth');
+```
+
+This connects to the local node (by default `127.0.0.1:8545`) and associates it with Ethereum. It does not start the node or configure its fork.
+
+For an in-memory development network without a fork, use `hh:memory`. Use `hardhat` to connect to a separately running local development node. See [deployments](deployments.md) for compiling and deploying contracts.
+
+## Impersonate An Account
+
+On Hardhat, submit transactions from any address, including a contract address, by passing an account with `type: 'impersonated'`. No private key is required. The transaction writer enables impersonation automatically.
+
+```ts
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+import { $erc20 } from 'dequanto/utils/$erc20';
+
+const usdc = new ERC20('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
+const account = {
+    address: '0x0000000000000000000000000000000000001234',
+    type: 'impersonated'
+} as const;
+const to = '0x0000000000000000000000000000000000005678';
+const amount = 1_000_000n; // 1 USDC in its smallest units.
+
+await client.debug.setBalance(account.address, 10n ** 18n);
+await $erc20.setBalanceAny(client, usdc.address, account.address, amount);
+const writer = await usdc.$receipt().transfer(account, to, amount);
+console.log(writer.receipt.transactionHash);
+```
+
+Contract checks still apply, including sufficient token balances and allowances. For explicit control, use `client.debug.impersonateAccount(address)` and `client.debug.stopImpersonatingAccount(address)`.
+
+## Advance The Network
+
+```ts
+await client.debug.mine('5days');
+await client.debug.mine(10); // Mine 10 blocks.
+```
+
+Time strings are converted to seconds and used as the block count, with a default interval of one second per block. `mine('5days')` therefore mines `432_000` blocks, advancing network time by approximately five days. The optional second argument sets the interval in seconds.
+
+## Set Native And ERC20 Balances
+
+Set the native balance of any account or contract in wei:
+
+```ts
+await client.debug.setBalance(account.address, 10n ** 18n); // 1 ETH.
+```
+
+Use `$erc20.setBalanceAny` to set an ERC20 balance without knowing its storage slot:
+
+```ts
+await $erc20.setBalanceAny(client, usdc.address, account.address, 1_000_000n);
+// A number is interpreted in whole-token units instead:
+await $erc20.setBalanceAny(client, usdc.address, account.address, 1);
+```
+
+The helper traces `balanceOf(account)` with `debug_traceCall`, examines accessed storage for the returned balance, and writes the matching slot. A `bigint` amount is in the token's smallest units; a `number` is converted using the token's decimals. This changes balance storage directly without minting tokens or updating total supply. Tokens whose balances are computed rather than stored directly may not be supported.
+
+## Set Contract Storage
+
+For a known storage slot, use:
+
+```ts
+await client.debug.setStorageAt(contractAddress, slot, '0x2a');
+```
+
+The value is padded to 32 bytes. For named variables, mappings, and packed fields, use a resolved storage layout with `SlotsStorage.set(...)`; see [Solidity storage](storage.md#write-storage-in-tests).
+
+## Snapshots And Rollbacks
+
+```ts
+const id = await client.debug.snapshot();
+try {
+    await client.debug.mine('5days');
+    await client.debug.setBalance(account.address, 10n ** 18n);
+    // Run transactions or assertions against the modified state.
+} finally {
+    await client.debug.revert(id);
+}
+```
+
+Take the snapshot before modifying state. Create a fresh snapshot for each independent scenario.

package/{docs/ai → skills/dequanto}/references/rpc-clients.md

@@ -8,6 +8,7 @@ Key source files:
 - `src/clients/Web3Client.ts`
 - `src/clients/EvmWeb3Client.ts`
 - `src/clients/ClientPool.ts`
+- `src/blocks/BlockDateResolver.ts`
 - `src/rpc/Rpc.ts`
 - `src/rpc/RpcBase.ts`
 
@@ -21,27 +22,29 @@ Useful tests:
 ## Client Creation
 
 ```ts
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
 
 const client = await Web3ClientFactory.getAsync('eth');
 ```
 
-For Hardhat:
+For an in-memory Hardhat fork using the platform's default/configured RPCs:
 
 ```ts
-const client = await Web3ClientFactory.getAsync('hardhat');
+const client = await Web3ClientFactory.getAsync('hh:memory:eth');
 ```
 
-For a fork-like platform string:
+To connect to an already running local Hardhat node configured as an Ethereum fork:
 
 ```ts
 const client = await Web3ClientFactory.getAsync('hh:eth');
 ```
 
+Use `hh:memory` for an in-memory development network without a fork, or `hardhat` for a separately running local development node. See [Hardhat development and forking](hardhat.md) for setup, impersonation, balance/storage changes, mining, and snapshots.
+
 For direct endpoints:
 
 ```ts
-import { EvmWeb3Client } from '@dequanto/clients/EvmWeb3Client';
+import { EvmWeb3Client } from 'dequanto/clients/EvmWeb3Client';
 
 const client = new EvmWeb3Client({
     platform: 'eth',
@@ -80,6 +83,23 @@ const result = await client.readContract({
 });
 ```
 
+## Resolve Blocks By Date
+
+Use `BlockDateResolver` to find the block nearest to a date, or to resolve a block number back to its date:
+
+```ts
+import { BlockDateResolver } from 'dequanto/blocks/BlockDateResolver';
+
+const resolver = new BlockDateResolver(client);
+const date = new Date('2024-03-03T10:20:00Z');
+
+const blockNumber = await resolver.getBlockNumberFor(date);
+const { block, timestamp } = await resolver.getBlockInfoFor(date);
+const blockDate = await resolver.getDate(blockNumber);
+```
+
+`getBlockNumberFor(date)` returns the nearest block number. `getBlockInfoFor(date)` also returns that block's Unix timestamp. The resolver estimates from the chain's average block time and refines the estimate by loading blocks, so the result can be immediately before or after the requested time. Compare the returned timestamp when an exact time boundary matters. Dates before the chain was active throw a `Date out of range` error.
+
 ## Logs
 
 Use `getPastLogs(filter, options?)` for raw log queries. It handles block-range pagination and node range limits.

package/{docs/ai → skills/dequanto}/references/safe-erc4337.md

@@ -51,8 +51,8 @@ const tx = await token
 ## Manual Safe Flow
 
 ```ts
-import { GnosisSafeHandler } from '@dequanto/safe/GnosisSafeHandler';
-import { ContractWriter } from '@dequanto/contracts/ContractWriter';
+import { GnosisSafeHandler } from 'dequanto/safe/GnosisSafeHandler';
+import { ContractWriter } from 'dequanto/contracts/ContractWriter';
 
 const writer = new ContractWriter(target.address, client);
 const txWriter = await writer.writeAsync(safeAccount, 'airdrop()', [], {

package/skills/dequanto/references/storage.md

@@ -0,0 +1,122 @@
+# Solidity Storage
+
+Prefer the storage reader included in generated contract classes. For manual layouts, use `SlotsParser` to derive layout and `SlotsStorage` to read or write slots. Do not decode raw storage words as ABI payloads.
+
+Key source files:
+
+- `src/solidity/SlotsParser.ts`
+- `src/solidity/SlotsStorage.ts`
+- `src/solidity/storage/handlers/SlotStructHandler.ts`
+- `src/solidity/storage/handlers/SlotMappingHandler.ts`
+- `src/solidity/storage/handlers/SlotDynamicArrayHandler.ts`
+- `src/solidity/storage/SlotsStorageTransport.ts`
+- `src/gen/GeneratorStorageReader.ts`
+
+Useful tests:
+
+- `test/solidity/SlotsReader.spec.ts`
+- `test/solidity/Storage.spec.ts`
+- `test/solidity/SlotsParser.spec.ts`
+- `test/generate/slotreader.spec.ts`
+
+## Generated Contract Storage Readers
+
+Contract classes installed from a blockchain explorer with `0xweb install`, or generated from Solidity sources with `@0xweb/hardhat`, include a storage reader on `contractInstance.storage`. It contains the storage layout derived from the source, including slot positions and packed fields, so you can access storage by variable name without manually resolving slots.
+
+On a Hardhat development network or fork, write a variable with `await contractInstance.storage.$set('someVar', value)`. The generated reader exposes `$set` and `$get`; `set` and `get` are methods on the underlying `SlotsStorage`.
+
+For example, using the generated AavePool class:
+
+```ts
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { AavePool } from '../../../0xc/eth/AavePool/AavePool';
+
+const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+const pool = new AavePool(undefined, client);
+const id = await client.debug.snapshot();
+
+try {
+    await pool.storage.$set('_flashLoanPremium', 12_345n);
+    const premium = await pool.storage._flashLoanPremium();
+    const publicPremium = await pool.FLASHLOAN_PREMIUM_TOTAL();
+} finally {
+    await client.debug.revert(id);
+}
+```
+
+The AavePool import points to this repository's generated class; use your project's generated path. Keep generated storage layouts in sync with the deployed implementation, especially after proxy upgrades. See the [storage example](../examples/storage.spec.ts) for assertions and rollback verification.
+
+## Parse Slots From Solidity
+
+```ts
+import { SlotsParser } from 'dequanto/solidity/SlotsParser';
+
+const slots = await SlotsParser.slots({
+    path: './contracts/Vault.sol'
+}, 'Vault');
+```
+
+For inline code:
+
+```ts
+const slots = await SlotsParser.slots({ path: '', code }, 'Foo');
+```
+
+## Parse Slots From ABI Inputs
+
+Use this for standalone struct or tuple ABI data:
+
+```ts
+const slots = await SlotsParser.slotsFromAbi(
+    '(uint256 foo, address owner, bool enabled)'
+);
+```
+
+## Read Contract Storage
+
+```ts
+import { SlotsStorage } from 'dequanto/solidity/SlotsStorage';
+
+const storage = SlotsStorage.createWithClient(client, contract.address, slots);
+
+const owner = await storage.get('owner');
+const user = await storage.get('users[0]');
+const balance = await storage.get(`balances["${account}"]`);
+```
+
+Supported path forms include:
+
+- `field`
+- `struct.field`
+- `array[0]`
+- `mapping["0x..."]`
+- `mapping["0x..."].field`
+- `nested[0].balances[1]`
+- breadcrumb arrays such as `['users', account, 'balance']`
+
+## Read Diamond Or Offset Storage
+
+For library-selected storage roots:
+
+```ts
+const storage = SlotsStorage.createWithClient(client, contract.address, slots, {
+    storageOffset: $contract.keccak256('diamond.app.storage')
+});
+```
+
+## Write Storage In Tests
+
+`SlotsStorage.set(...)` exists and is useful in Hardhat/debug contexts:
+
+```ts
+await storage.set('user.balance', 1000n);
+```
+
+For a known raw slot on Hardhat, use `await client.debug.setStorageAt(contractAddress, slot, '0x2a')`; the value is padded to 32 bytes. To set an ERC20 balance without resolving its layout manually, use `$erc20.setBalanceAny(client, tokenAddress, accountAddress, amount)`. See [Hardhat development and forking](hardhat.md) for examples and snapshot/rollback handling.
+
+Do not use storage writes in production code unless the transport explicitly supports it and the task requires test/debug mutation.
+
+## Raw Slot Reads
+
+Use `client.getStorageAt(address, slot)` or `client.getStorageAtBatched(address, slots)` only when raw words are needed.
+

package/{docs/ai → skills/dequanto}/references/tokens-accounts.md

@@ -21,7 +21,7 @@ Useful tests:
 ## Token Metadata
 
 ```ts
-import { TokensService } from '@dequanto/tokens/TokensService';
+import { TokensService } from 'dequanto/tokens/TokensService';
 
 const tokens = new TokensService('eth');
 const usdc = await tokens.getKnownToken('USDC');
@@ -30,7 +30,7 @@ const usdc = await tokens.getKnownToken('USDC');
 For forked Hardhat platform strings:
 
 ```ts
-import { TokensServiceFactory } from '@dequanto/tokens/TokensServiceFactory';
+import { TokensServiceFactory } from 'dequanto/tokens/TokensServiceFactory';
 
 const tokens = await TokensServiceFactory.getAsync('hh:eth');
 ```
@@ -38,7 +38,7 @@ const tokens = await TokensServiceFactory.getAsync('hh:eth');
 ## Token Transfer Service
 
 ```ts
-import { TokenTransferService } from '@dequanto/tokens/TokenTransferService';
+import { TokenTransferService } from 'dequanto/tokens/TokenTransferService';
 
 const service = new TokenTransferService(client);
 const tx = await service.transfer(sender, receiver, 'USDC', 10);
@@ -69,7 +69,7 @@ const tx = await service.transferAllWithRemainder(sender, receiver, 'USDC', 1);
 Generate or derive EOA accounts:
 
 ```ts
-import { $sig } from '@dequanto/utils/$sig';
+import { $sig } from 'dequanto/utils/$sig';
 
 const account = $sig.$account.generate();
 const fromMnemonic = await $sig.$account.fromMnemonic(mnemonic, 0);
@@ -79,7 +79,7 @@ const fromKey = await $sig.$account.fromKey(privateKey);
 Use `ChainAccountService` for named encrypted account storage:
 
 ```ts
-import { ChainAccountService } from '@dequanto/ChainAccountService';
+import { ChainAccountService } from 'dequanto/ChainAccountService';
 
 const service = new ChainAccountService();
 const account = await service.get('deployer');
@@ -91,9 +91,15 @@ Transaction APIs accept several account shapes:
 
 - EOA account: `{ address, key }`
 - named account: string resolved through `ChainAccountService`
-- impersonated account in Hardhat
+- impersonated account in Hardhat: `{ type: 'impersonated', address }` (no private key required)
 - Safe account: `{ type: 'safe', address, operator, owners? }`
 - ERC-4337 account: `{ type: 'erc4337', address, operator }`
 
 Inspect `src/models/TAccount.ts` before adding a new account shape.
 
+## Balances And Impersonation On Hardhat
+
+Use `client.debug.setBalance(address, 10n ** 18n)` to set a native balance to 1 ETH. Use `$erc20.setBalanceAny(client, tokenAddress, accountAddress, amount)` to resolve and overwrite an ERC20 balance slot: `bigint` amounts are raw smallest units, while `number` amounts are converted using token decimals.
+
+Pass an impersonated account to generated write methods, for example `await usdc.$receipt().transfer({ address, type: 'impersonated' }, to, amount)`. See [Hardhat development and forking](hardhat.md) and the [fork example](../examples/hardhat-fork.spec.ts).
+