dequanto 0.2.49 → 0.2.51

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

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,7 +135,7 @@ 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 });

package/skills/dequanto/references/utils.md

@@ -0,0 +1,131 @@
+# Utility Helpers
+
+Dequanto includes helpers for common EVM and TypeScript operations. Prefer them when they make contract code shorter and more consistent. Verify unfamiliar helpers in the installed declarations.
+
+Key source files:
+
+- `src/abi/$abi.ts`
+- `src/utils/$contract.ts`
+- `src/utils/$require.ts`
+- `src/utils/$hex.ts`
+- `src/utils/$date.ts`
+- `src/utils/$sig.ts`
+- `src/utils/$promise.ts`
+
+Runnable example: [utility helpers](../examples/utils.spec.ts).
+
+## ABI Encoding And Decoding
+
+Import `$abi` from `dequanto/abi/$abi`. Use it instead of another ABI coder or manually constructed calldata.
+
+```ts
+import { $abi } from 'dequanto/abi/$abi';
+
+const encoded = $abi.encode(['address', 'uint256'], [account, 5n]);
+const [decodedAccount, decodedAmount] = $abi.decode(['address', 'uint256'], encoded);
+const calldata = $abi.encodeCall(
+    'function transfer(address to, uint256 amount)',
+    [account, 5n]
+);
+const totalSupply = $abi.decodeReturn<bigint>(
+    'function totalSupply() view returns (uint256)',
+    responseHex
+);
+```
+
+- `encode` and `decode` accept one type/value or arrays of types/values.
+- `encodeCall` accepts a Solidity function declaration or JSON ABI item.
+- `decodeReturn` accepts a function declaration, JSON ABI item, or output definitions. Multiple named outputs are returned as an object.
+
+## Solidity-Compatible Keccak-256
+
+Use `$contract.keccak256(...)` for the same Keccak-256 operation used by Solidity:
+
+```ts
+import { $contract } from 'dequanto/utils/$contract';
+
+const topic = $contract.keccak256('Transfer(address,address,uint256)');
+const bytes = $contract.keccak256('0x1234', 'buffer');
+```
+
+A string beginning with `0x` is hashed as bytes; other strings are UTF-8 encoded. The default output is hex. Pass `'buffer'` for a `Uint8Array`.
+
+## Runtime Requirements
+
+`$require` provides compact runtime validation similar in purpose to Solidity's `require`:
+
+```ts
+import { $require } from 'dequanto/utils/$require';
+
+const address = $require.AddressNotEmpty(inputAddress, 'Recipient is required');
+$require.BigInt(amount, 'Amount must be bigint', { min: 1n });
+$require.gte(balance, amount, 'Insufficient balance');
+$require.Hex(calldata, 'Invalid calldata');
+$require.notNull(receipt, 'Receipt was not returned');
+```
+
+Useful checks include `True`, `notNull`, `Null`, `notEmpty`, `eq`, `notEq`, `gt`, `gte`, `lt`, `lte`, `match`, `has`, `oneOf`, `Address`, `AddressNotEmpty`, `AddressChecked`, `TxHash`, `Hex`, `Number`, `BigInt`, and `Numeric`. Most value validators return the validated value.
+
+## Hex Manipulation
+
+Use `$hex` for `0x` normalization, conversion, padding, concatenation, slicing, and byte counts:
+
+```ts
+import { $hex } from 'dequanto/utils/$hex';
+
+const value = $hex.ensure('1234');             // 0x1234
+const word = $hex.padBytes(value, 32);          // left-pad to 32 bytes
+const payload = $hex.concat([value, '0xabcd']);
+const firstTwoBytes = $hex.getBytes(payload, 0, 2);
+const byteLength = $hex.getBytesLength(payload);
+```
+
+`toHex('hello')` encodes a normal string as UTF-8. `toHexBuffer(...)` also ensures an even number of hex digits. `padBytes` takes a byte count and pads left by default; pass `{ padEnd: true }` to pad right.
+
+## Date And Time
+
+Use `$date` for time spans, Unix timestamps, formatting, date boundaries, and arithmetic:
+
+```ts
+import { $date } from 'dequanto/utils/$date';
+
+const timeoutMs = $date.parseTimespan('5min');
+const timeoutSeconds = $date.parseTimespan('5min', { get: 's' });
+const deadline = $date.tool().add('5min').toUnixTimestamp();
+const date = $date.fromUnixTimestamp(deadline);
+```
+
+`parseTimespan` returns milliseconds by default. Request seconds explicitly when passing time to a contract or RPC API.
+
+## Signing
+
+Use `$sig` for account creation, message and typed-data signatures, transaction signing, and signer recovery:
+
+```ts
+import { $sig } from 'dequanto/utils/$sig';
+
+const account = $sig.$account.generate();
+const signature = await $sig.signMessage('Approve operation', account);
+const signer = $sig.recoverMessage('Approve operation', signature);
+```
+
+Use `signMessage`/`recoverMessage` for EIP-191 messages, `signTypedData` for typed data, and `signTx`/`recoverTx` for transactions. Account helpers include `generate`, `fromMnemonic`, and `fromKey`.
+
+## Promise Results Without Try/Catch
+
+`$promise.caught(...)` converts a rejection into a result object:
+
+```ts
+import { $promise } from 'dequanto/utils/$promise';
+
+const { result, error } = await $promise.caught(loadValue());
+if (error) {
+    console.error(error.message);
+} else {
+    console.log(result);
+}
+```
+
+It accepts a promise or a function returning a promise and returns `{ result }` on success or `{ error }` on failure. Other helpers cover delays, timeouts, events, callbacks, and polling.
+
+The remaining files under `src/utils/` mostly support organization, conversion, formatting, and readability. Use them when relevant, but verify current signatures in `lib/types/utils/` rather than guessing.

package/src/abi/$abi.ts

@@ -1,7 +1,9 @@
-import { TAbiInput } from '@dequanto/types/TAbi';
+import { TAbiInput, TAbiItem, TAbiOutput } from '@dequanto/types/TAbi';
 import { ParamType } from './fragments';
 import { TEth } from '@dequanto/models/TEth';
 import { $abiCoder } from './$abiCoder';
+import { $abiUtils } from '@dequanto/utils/$abiUtils';
+import { $abiParser } from '@dequanto/utils/$abiParser';
 
 export namespace $abi {
     type TAbiType = string | ParamType | TAbiInput;
@@ -29,6 +31,37 @@ export namespace $abi {
         return isSingle ? result[0] : result;
     }
 
+    export function encodeCall(abi: string | TAbiItem, params?: any[]): TEth.Hex {
+        return $abiUtils.serializeMethodCallData(abi, params);
+    }
+
+    export function decodeReturn<T = any>(abi: string | TAbiItem | TAbiOutput[], hex: string): T {
+        let outputs = typeof abi === 'string'
+            ? ($abiParser.parseMethod(abi).outputs ?? [])
+            : (Array.isArray(abi) ? abi : abi.outputs ?? []);
+        let returnAbi = outputs;
+        let isDynamic: boolean = null;
+        if (outputs.length > 1) {
+            let isNamedTuple = outputs.every(x => x.name != null && x.name !== '');
+            if (isNamedTuple) {
+                returnAbi = [{ type: 'tuple', components: outputs, name: null }];
+                isDynamic = false;
+            }
+        }
+
+        try {
+            let arr = $abiCoder.decode(returnAbi as any, hex, {
+                dynamic: isDynamic
+            });
+            return returnAbi.length === 1 ? arr[0] : arr;
+        } catch (error) {
+            if (outputs.length === 1 && returnAbi.length === 1) {
+                return $abiCoder.decodeSingle(returnAbi[0], hex);
+            }
+            throw error;
+        }
+    }
+
     function ensureTypes (types: TAbiType | TAbiType[]): TAbiType[] {
         let arr = Array.isArray(types) ? types : [ types ];
         return arr.map($abiCoder.normalizeType);

package/src/blocks/BlockDateResolver.ts

@@ -1,9 +1,9 @@
 import alot from 'alot';
 import memd from 'memd';
-import { Web3Client } from '@dequanto/clients/Web3Client';
 import { TEth } from '@dequanto/models/TEth';
 import { $block } from '@dequanto/utils/$block';
 import { $date } from '@dequanto/utils/$date';
+import type { Web3Client } from '@dequanto/clients/Web3Client';
 
 export class BlockDateResolver {
     private AVG_INITIAL = {

package/src/clients/Web3Client.ts

@@ -32,6 +32,8 @@ import { DataLike } from '@dequanto/utils/types';
 import { ErrorCode } from './ClientPoolStats';
 import { $date } from '@dequanto/utils/$date';
 import { WalletClient } from './WalletClient';
+import alot from 'alot';
+import { $abiParser } from '@dequanto/utils/$abiParser';
 
 export abstract class Web3Client implements IWeb3Client {
 
@@ -108,12 +110,55 @@ export abstract class Web3Client implements IWeb3Client {
     }
 
     // Submit contract calls in a batch and decode the responses.
-    async batchContractCalls(requests: TRpcContractCall[], options?: {
+    async batchContractCalls(requests: TRpcContractCall[] | Promise<TRpcContractCall>[], options?: {
         allowErrors?: boolean
     }) {
         let reader = new RpcContract(this);
-        let result = await reader.batch(requests, options);
-        return result;
+
+        let requestsArrRaw = await Promise.all(requests);
+        let requestsArr = await alot(requestsArrRaw).mapAsync(async request => {
+            if (request == null) {
+                return null;
+            }
+            let abi = typeof request.abi === 'string'
+                ? [ $abiParser.parseMethod(request.abi) ]
+                : (Array.isArray(request.abi) ? request.abi : [ request.abi ])
+
+            let blockNumber = request.blockNumber;
+            if (blockNumber instanceof Date) {
+                let resolver = di.resolve(BlockDateResolver, this);
+                blockNumber = await resolver.getBlockNumberFor(blockNumber);
+            }
+            let method = request.method;
+            if (method == null) {
+                $require.eq(abi.length, 1, `No function method is provided, the single ABI item expected`);
+                method = abi[0].name;
+            }
+            return {
+                address: request.address,
+                abi: abi,
+                method: method,
+                params: request.params,
+                blockNumber: blockNumber,
+                options: options
+            } as TRpcContractCall;
+        }).toArrayAsync();
+
+        // Skip NULL request: mirror later as the NULL result
+        let mapped = [];
+        let rpcRequestsNotEmpty = [];
+        for (let i = 0; i < requestsArr.length; i++) {
+            if (requestsArr[i] == null) {
+                continue;
+            }
+            let idx = rpcRequestsNotEmpty.push(requestsArr[i]) - 1;
+            mapped[i] = idx;
+        }
+
+        let outputs = await reader.batch(rpcRequestsNotEmpty, options);
+        return requestsArr.map((_, i) => {
+            return outputs[mapped[i]] ?? null;
+        });
     }
 
     getEventStream(address: TEth.Address, abi: TAbiItem[], event: string) {