dequanto 0.2.50 → 0.2.52

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/skills/dequanto/references/live-events.md

@@ -0,0 +1,126 @@
+# WebSocket And Live Logs
+
+For URL-based clients, live subscriptions require at least one WebSocket endpoint in the chain's RPC endpoint list. Add a `wss://...` URL alongside any HTTP endpoints:
+
+```yaml
+web3:
+  eth:
+    endpoints:
+      - url: wss://ethereum.example
+      - url: https://ethereum.example
+```
+
+When a subscription requests a live connection, dequanto automatically selects a WebSocket endpoint from the client pool. A WebSocket endpoint can also serve normal RPC calls. HTTP endpoints remain useful for ordinary request traffic and as additional pool endpoints.
+
+An EIP-1193 provider can deliver subscriptions through its `message` event and does not need a separate WebSocket URL. This includes the in-memory Hardhat provider.
+
+You can provide the same configuration through `Config.fetch({ config: ... })`, workspace or global dequanto configuration, or the platform RPC environment configuration. See [RPC clients](rpc-clients.md) and [the configuration example](../examples/config.spec.ts).
+
+Key source files:
+
+- `src/clients/Web3Client.ts`
+- `src/clients/ClientEventsStream.ts`
+- `src/contracts/ContractBase.ts`
+- `src/contracts/ContractStream.ts`
+- `src/rpc/Rpc.ts`
+- `src/rpc/RpcSubscription.ts`
+- generated contract classes such as `src/prebuilt/openzeppelin/ERC20.ts`
+
+Useful tests:
+
+- `test/subscriptions.spec.ts`
+- `test/rpc/rpc.spec.ts`
+
+Runnable example: [live event subscriptions](../examples/live-events.spec.ts). It uses an in-memory Hardhat Ethereum fork and mines the required activity itself. The fork needs a configured Ethereum HTTP RPC, but it does not require a WebSocket endpoint or live network activity.
+
+## Generated Contract Event Subscriptions
+
+Prefer generated contract classes for contract logs. They expose a typed method for every event:
+
+```ts
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+
+const token = new ERC20(tokenAddress, client);
+
+token.onTransfer(event => {
+    // The generated callback carries typed Transfer arguments.
+    console.log(event.arguments);
+});
+
+token.onApproval(event => {
+    console.log(event.arguments);
+});
+```
+
+Generated classes also expose `onLog(eventName, callback?)` when the event name is selected dynamically:
+
+```ts
+token.onLog('Transfer', event => {
+    console.log(event.name, event.arguments);
+});
+```
+
+Both forms return a `ClientEventsStream`, even when a callback is provided. Omit the callback to compose or subscribe to the stream yourself:
+
+```ts
+const transfers = token.onTransfer();
+const listener = transfers.subscribe(
+    event => console.log(event.arguments),
+    error => console.error(error)
+);
+
+// Removes this callback from the client-side stream.
+listener.unsubscribe();
+```
+
+Use the generated `on<EventName>` method when the event is known at development time because its callback is event-specific. Use `onLog(name)` when the event name is chosen dynamically.
+
+Live streams only receive new logs after the subscription connects. Use generated `getPastLogs<EventName>` methods or `EventsIndexer` for historical ranges.
+
+## Client-Level Subscriptions
+
+Use `client.subscribe` for low-level live logs, new block headers, or pending transactions. It automatically requests a WebSocket connection from the configured pool:
+
+```ts
+const subscription = await client.subscribe('newHeads', (error, block) => {
+    if (error) {
+        console.error(error);
+        return;
+    }
+    console.log(block.number);
+});
+
+// Ends the remote RPC subscription.
+await subscription.unsubscribe();
+```
+
+Supported overloads include:
+
+```ts
+await client.subscribe('logs', {
+    address: tokenAddress,
+    topics: [transferTopic]
+}, callback);
+
+await client.subscribe('newPendingTransactions', callback);
+```
+
+## Raw RPC Subscriptions
+
+Use the generated RPC client when you need the low-level `eth_subscribe` lifecycle directly:
+
+```ts
+import { Rpc } from 'dequanto/rpc/Rpc';
+
+const rpc = new Rpc('wss://ethereum.example');
+const subscription = await rpc.eth_subscribe('newHeads');
+
+subscription.subscribe(
+    block => console.log(block.number),
+    error => console.error(error)
+);
+
+await subscription.unsubscribe();
+```
+
+`RpcSubscription.subscribe` accepts data and error callbacks. Always call `unsubscribe()` when a low-level subscription is no longer needed.

package/{docs/ai → skills/dequanto}/references/migration-from-ethers-viem.md

@@ -20,6 +20,7 @@ Agents often know ethers and viem better than dequanto. Use this file to transla
 | Bigint formatting | `parseUnits`, `formatUnits` | `bigint` js type is supported natively, additionally `$bigint` helpers and token decimals through dequanto token services |
 | Safe tx | Safe SDK | `SafeAccount`, `GnosisSafeHandler`, `SafeTx`, Safe transports |
 | ERC-4337 | external bundler/account SDK | `Erc4337Service`, `Erc4337TxWriter`, `Erc4337Account` |
+| Browser wallet / dApp | wagmi, RainbowKit, `window.ethereum` | `client.wallet`, `EIP6963ProviderFactory` |
 
 ## Strong Defaults
 

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.
@@ -97,16 +117,7 @@ For large ranges, use `streamed: true` and `onProgress`.
 
 ## Subscriptions
 
-Use `subscribe(...)` for websocket subscriptions:
-
-```ts
-const sub = await client.subscribe('newHeads', (error, block) => {
-    if (error) throw error;
-    console.log(block.number);
-});
-```
-
-For contract events, generated contracts expose `$onLog(event, cb?)`.
+Add a `wss://...` endpoint to the chain RPC list, then use generated contract event methods, `client.subscribe(...)`, or `Rpc.eth_subscribe(...)`. Dequanto automatically selects a WebSocket endpoint for live connections; that endpoint can also serve ordinary RPC calls. See [WebSocket and live logs](live-events.md).
 
 ## Avoid
 

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()', [], {
@@ -95,7 +95,7 @@ await tx.wait();
 
 For scripts, prefer `BatchAgent` when the code should call generated write methods normally and review or submit the collected transactions at the end. If the submitting account is a Safe, `batch.execute()` converts the collected single transactions into one Safe batch/multicall transaction. If the submitting account is a Timelock, `batch.execute()` converts them into one Timelock batch/scheduleBatch flow.
 
-See `../../references/transactions.md` for the full `BatchAgent` script pattern.
+See `./transactions.md` for the full `BatchAgent` script pattern.
 
 ## Safe Decoding
 

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).
+

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

@@ -22,6 +22,8 @@ Useful tests:
 
 ## TxWriter Lifecycle
 
+For transactions from any address on a Hardhat development network or fork, pass `{ address, type: 'impersonated' }` as the account. The writer enables impersonation automatically. See [Hardhat development and forking](hardhat.md#impersonate-an-account) for a complete ERC20 transfer example.
+
 Generated write methods return a `TxWriter`.
 
 ```ts
@@ -45,7 +47,7 @@ const receipt = await tx.wait();
 Use `BatchAgent` when a script should run its full transaction flow without immediately submitting transactions on-chain. `BatchAgent` plugs into `TxWriter.DEFAULTS.agent`, intercepts write calls, returns completed mock writers/receipts to the script, and caches the transactions for later review or execution.
 
 ```ts
-import { BatchAgent } from '@dequanto/txs/agents/BatchAgent';
+import { BatchAgent } from 'dequanto/txs/agents/BatchAgent';
 
 const batch = new BatchAgent().enable();
 
@@ -76,7 +78,7 @@ Important behavior:
 ## Build And Sign Raw Tx
 
 ```ts
-import { TxDataBuilder } from '@dequanto/txs/TxDataBuilder';
+import { TxDataBuilder } from 'dequanto/txs/TxDataBuilder';
 
 const builder = new TxDataBuilder(client, sender, {
     to: receiver
@@ -93,7 +95,7 @@ const receipt = await client.sendSignedTransaction(signed);
 ## Send Existing Tx Data
 
 ```ts
-import { TxWriter } from '@dequanto/txs/TxWriter';
+import { TxWriter } from 'dequanto/txs/TxWriter';
 
 const tx = await TxWriter.writeTxData(client, {
     to: receiver,
@@ -133,14 +135,35 @@ const service = new TokenTransferService(client).$config({ nonce });
 Use `TxLogParser` for receipts when no generated contract parser is available.
 
 ```ts
-import { TxLogParser } from '@dequanto/txs/receipt/TxLogParser';
+import { TxLogParser } from 'dequanto/txs/receipt/TxLogParser';
 
 const parser = new TxLogParser();
 const logs = await parser.parse(receipt, { abi });
 ```
 
+## Reverts And Error Handling
+
+Developers do not need to perform manual pre-flight simulations (e.g. via `contract.$call()` or `contract.$gas()`). When sending a transaction via `TxWriter` or generated methods like `contract.$receipt().method(account, ...)`:
+
+1. **Automatic Simulation via Gas Estimation:** Dequanto automatically estimates gas before submitting. Estimating gas inherently simulates the transaction on the node.
+2. **Custom Error Decoding:** If the call reverts during estimation, dequanto catches the revert, automatically decodes the custom error bytecode using the contract ABI, formats the call arguments, attaches execution traces (when running on Hardhat/debug nodes), and throws a standard JavaScript `Error`.
+3. **On-Chain Reverts:** If gas estimation succeeded (or was disabled) but the transaction subsequently reverts on-chain, the flow is identical: `await writer.wait()` rejects with a standard JavaScript `Error` containing the decoded custom error name and arguments.
+
+```ts
+try {
+    await vault.$receipt().withdraw(user, 100n);
+} catch (error) {
+    // error.message includes the decoded custom error name, parameters, method, and traces:
+    // e.g., "VM Exception: reverted with custom error 'InsufficientBalance(50, 100)'"
+    console.error(error.message);
+}
+```
+
+See the [revert and custom error example](../examples/revert-error.spec.ts) for runnable demonstrations.
+
 ## Avoid
 
+- Do not perform manual simulations with `$call()` or `$gas()` solely to catch reverts before sending; `TxWriter` automatically simulates via gas estimation, decodes custom errors, and throws standard JavaScript errors.
 - Do not manually manage gas and nonce unless the task needs it.
 - Do not use external wallet clients when a dequanto `TAccount`, `SafeAccount`, or `Erc4337Account` flow is available.