dequanto 0.2.49 → 0.2.51

package/lib/types/config/interface/IConfigData.d.ts

@@ -4,6 +4,7 @@ import { TAddress } from '../../models/TAddress';
 import { TPlatform } from '../../models/TPlatform';
 import { IRpcConfig } from '../../clients/ClientPool';
 import { TChain } from '../../models/TChain';
+import { TEth } from '../../models/TEth';
 export interface IConfigData {
     settings: {
         /** Root path of the dequanto library */
@@ -24,10 +25,10 @@ export interface IConfigData {
     tokens: ITokenGlob[];
     blockchainExplorer: {
         [platform in TPlatform]: {
-            key: string;
+            key?: string;
             host?: string;
             api?: string;
-            wwww?: string;
+            www?: string;
         };
     };
     chains: TChain[];
@@ -69,4 +70,15 @@ export interface IConfigData {
     spotPriceAggregator?: {
         [platform in TPlatform]: TAddress;
     };
+    ns: {
+        [service: string]: {
+            [platform: string]: {
+                registry: TEth.Address;
+                resolver?: TEth.Address;
+            };
+        };
+    };
+    oracles: {
+        [service: string]: any;
+    };
 }

package/lib/types/contracts/ContractReader.d.ts

@@ -48,7 +48,7 @@ export declare class ContractReader implements IContractReader {
             [key: string]: any;
         } | any[];
     }): Promise<RpcTypes.Filter>;
-    static read(client: Web3Client, address: TAddress, methodAbi: string): Promise<any>;
+    static read<TResult = any>(client: Web3Client, address: TAddress, methodAbi: string): Promise<TResult>;
 }
 export declare namespace ContractReaderUtils {
     class DeferredRequest<T = any> {

package/lib/types/explorer/BlockchainExplorerFactory.d.ts

@@ -12,7 +12,7 @@ export declare namespace BlockchainExplorerFactory {
     function get(config: TExplorerDefinition): IBlockchainExplorer;
     /** @obsolete */
     function get(platform: TPlatform | number, opts: IBlockchainExplorerFactoryParams): IBlockchainExplorer;
-    /** Same as sync variation, but ensures the config is being fetched */
+    /** Same as the synchronous variant, but ensures the config has been fetched */
     function getAsync(platform: TPlatform, opts?: IBlockchainExplorerFactoryParams): Promise<IBlockchainExplorer>;
     /** @obsolete Create instance directly with the get/getAsync method */
     function create(opts: IBlockchainExplorerFactoryParams): Constructor<IBlockchainExplorer>;

package/lib/types/explorer/IBlockchainExplorer.d.ts

@@ -4,6 +4,12 @@ import { TEth } from '../models/TEth';
 import { TAddress } from '../models/TAddress';
 import { IVerifier } from './verifiers/IVerifier';
 export interface IBlockchainExplorer extends IAbiProvider, IVerifier {
+    config?: {
+        api?: {
+            url?: string;
+            key?: string;
+        };
+    };
     inMemoryDb: IContractDetails[];
     getContractMeta(q: string): Promise<IContractDetails>;
     getContractCreation(address: TEth.Address): Promise<{

package/lib/types/models/TPlatform.d.ts

@@ -1 +1 @@
-export type TPlatform = 'eth' | 'eth:goerli' | 'bsc' | 'polygon' | 'arbitrum' | 'xdai' | 'boba' | 'hardhat' | 'optimism' | 'avalanche' | `hh:${string}` | string;
+export type TPlatform = 'eth' | 'eth:goerli' | 'bsc' | 'polygon' | 'arbitrum' | 'xdai' | 'boba' | 'hardhat' | 'optimism' | 'avalanche' | 'hh:memory' | `hh:${string}` | string;

package/lib/types/utils/$account.d.ts

@@ -4,4 +4,5 @@ export declare namespace $account {
     function isSafe(account: TAccount): account is SafeAccount;
     function isErc4337(account: TAccount): account is Erc4337Account;
     function isTimelock(account: TAccount): account is TimelockAccount;
+    function generate(name: string): EoAccount;
 }

package/lib/types/utils/$erc20.d.ts

@@ -0,0 +1,5 @@
+import { TEth } from '../models/TEth';
+import { Web3Client } from '../clients/Web3Client';
+export declare namespace $erc20 {
+    function setBalanceAny(client: Web3Client, token: TEth.Address, account: TEth.Address, amount: bigint | number): Promise<void>;
+}

package/lib/types/utils/$require.d.ts

@@ -17,8 +17,8 @@ export declare namespace $require {
     function Function<T>(val: T, message: string): NonNullable<T>;
     function Array<T>(val: T, message: string): NonNullable<T>;
     function String<T>(val: T, message: string): NonNullable<T>;
-    function notNull<T>(val: T, message: string, ...logs: any[]): NonNullable<T>;
-    function Null<T>(val: T, message: string, ...logs: any[]): T;
+    function notNull<T>(val: T, message?: string, ...logs: any[]): NonNullable<T>;
+    function Null<T>(val: T, message?: string, ...logs: any[]): T;
     function notEmpty<T extends string | Array<any> | {
         length: number;
     }>(val: T, message: string): NonNullable<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dequanto",
-    "version": "0.2.49",
+    "version": "0.2.51",
     "author": {
         "name": "Alex Kit",
         "email": "alex.kit@atmajs.com"

package/skills/README.md

@@ -0,0 +1,45 @@
+# Install The Dequanto Skill
+
+The portable skill is the complete [dequanto](dequanto/) directory. It includes `SKILL.md`, `INDEX.md`, `references/`, and `examples/`. It can stay in this repository; no separate repository or server is needed.
+
+## Install From This Checkout
+
+Run from the dequanto repository root in PowerShell:
+
+```powershell
+# Codex: available across your projects.
+New-Item -ItemType Directory -Force "$HOME/.agents/skills" | Out-Null
+Copy-Item -Recurse ./skills/dequanto "$HOME/.agents/skills/"
+```
+
+For a project-specific Codex installation, copy the folder to `<project>/.agents/skills/dequanto`. For Claude Code, use `<project>/.claude/skills/dequanto`. Copy the entire folder, including its resources.
+
+Use a destination where `dequanto` does not already exist. When updating, replace the previous skill directory with the new complete directory so removed resources do not remain.
+
+In Codex, invoke `$dequanto` or let Codex select it for relevant tasks. Restart Codex if the installed skill does not appear. See the [Codex skill documentation](https://learn.chatgpt.com/docs/build-skills).
+
+## Install From GitHub With Codex
+
+After the skill directory has been committed and pushed, ask Codex:
+
+```text
+$skill-installer Install the dequanto skill from
+https://github.com/0xweb-org/dequanto/tree/master/skills/dequanto
+```
+
+Installation provides agent instructions and examples. Install the `dequanto` npm dependency separately in the project where you use it. Examples run as tests inside the dequanto repository. In other projects, adapt their generated-contract imports and fixture paths; see the skill index for prerequisites.
+
+## Maintain And Test
+
+Edit `skills/dequanto/SKILL.md`, `INDEX.md`, `references/`, and `examples/` directly. This directory is the single source of truth and the installable skill; no bundling or synchronization step is needed.
+
+Use published `dequanto/...` imports. The repository test runner maps them to `src/...` through `tsconfig-build.json`, so examples exercise the current source.
+
+Run a focused example from the repository root:
+
+```sh
+npx atma test skills/dequanto/examples/hardhat-debug.spec.ts
+npm run typecheck -- --pretty false
+```
+
+Examples using forks require RPC access; deployment and generation examples may also require the repository fixtures and Hardhat configuration.

package/{docs/ai → skills/dequanto}/INDEX.md

@@ -10,26 +10,37 @@ Before using an unfamiliar dequanto API, verify the exact signature in `src/` or
 
 | Goal | Use | Reference | Examples |
 | --- | --- | --- | --- |
-| Create an RPC client, read blocks, balances, logs, storage, or raw tx data | `Web3ClientFactory`, `Web3Client`, chain clients | `references/rpc-clients.md` | `examples/rpc-read.spec.ts` |
+| Configure RPC endpoints, explorer keys, or custom chains | `Config.fetch`, `ConfigDefaults`, `RPC_<PLATFORM>` env vars, `blockchainExplorer` | `src/config/ConfigDefaults.ts` | `examples/config.spec.ts` |
+| Create an RPC client; read blocks, balances, logs, storage, or raw tx data; resolve blocks by date | `Web3ClientFactory`, `Web3Client`, `BlockDateResolver`, chain clients | `references/rpc-clients.md` | `examples/rpc-read.spec.ts` |
+| Develop contracts or experiment on a Hardhat fork; impersonate accounts, change balances/storage, mine, or roll back | `Web3ClientFactory`, `client.debug`, `$erc20.setBalanceAny` | `references/hardhat.md` | `examples/hardhat-debug.spec.ts`, `examples/hardhat-fork.spec.ts` |
 | Call a smart contract | generated contract classes extending `ContractBase`, or `ContractReader` for ad hoc ABI calls | `references/contracts.md` | `examples/contract-read.spec.ts` |
 | Send a contract transaction | generated write methods returning `TxWriter`; use `$receipt()` when the receipt is needed | `references/contracts.md`, `references/transactions.md` | `examples/contract-write.spec.ts` |
-| Generate typed contract classes | `Generator`, `HardhatProvider`, 0xweb-generated classes | `references/generation.md` | `examples/generate-client.spec.ts` |
+| Generate typed contract classes | `Generator`, `HardhatProvider`, 0xweb-generated classes | `references/generation.md` | `examples/generate-contract-class.spec.ts` |
 | Deploy contracts and proxies | `HardhatProvider`, `Deployments`, `ensure`, `ensureWithProxy`, `ensureWithBeacon` | `references/deployments.md` | `examples/deploy-contract.spec.ts` |
 | Build, sign, save, submit, or inspect transactions | `TxDataBuilder`, `TxWriter`, `TokenTransferService` | `references/transactions.md` | `examples/send-transaction.spec.ts` |
 | Fetch or cache historical contract events | generated `getPastLogs*` helpers or `EventsIndexer` | `references/events-indexing.md` | `examples/index-events.spec.ts` |
 | Fetch ABI/source/creation data from an explorer | `BlockchainExplorerFactory`, `BlockchainExplorer`, `ContractAbiProvider` | `references/explorer.md` | `examples/explorer-abi.spec.ts` |
-| Read Solidity storage, structs, mappings, arrays, or diamond storage | `SlotsParser`, `SlotsStorage`, generated storage readers | `references/storage.md` | `examples/storage-read.spec.ts` |
+| Encode/decode ABI data, hash Solidity values, validate inputs, manipulate hex, work with dates, sign data, or capture promise errors | `$abi`, `$contract`, `$require`, `$hex`, `$date`, `$sig`, `$promise` | `references/utils.md` | `examples/utils.spec.ts` |
+| Read Solidity storage, structs, mappings, arrays, or diamond storage | `SlotsParser`, `SlotsStorage`, generated storage readers | `references/storage.md` | `examples/storage.spec.ts` |
 | Work with tokens and balances | `TokensService`, `TokensServiceFactory`, `TokenTransferService`, generated ERC20 wrappers | `references/tokens-accounts.md` | `examples/token-transfer.spec.ts` |
 | Work with accounts, signing, Safe, or ERC-4337 | `ChainAccountService`, `$sig`, `GnosisSafeHandler`, `SafeTx`, `Erc4337Service`, `Erc4337TxWriter` | `references/safe-erc4337.md`, `references/tokens-accounts.md` | `examples/safe-batch.spec.ts`, `examples/erc4337-userop.spec.ts` |
 | Convert code from ethers or viem habits | Use the dequanto equivalents instead of adding external clients | `references/migration-from-ethers-viem.md` | all examples |
 
 ## Source Of Truth
 
-- Package exports resolve by subpath, for example `@dequanto/clients/Web3ClientFactory`.
+- Package exports resolve by subpath for both ESM imports and CommonJS requires: `import { Web3ClientFactory } from "dequanto/clients/Web3ClientFactory"` or `const { Web3ClientFactory } = require("dequanto/clients/Web3ClientFactory")`.
 - Source lives under `src/`.
 - Declarations are emitted under `lib/types/`.
 - Tests under `test/` are often the best runnable examples.
-- Generated contract clients usually live outside this package in `0xc/` or `@dequanto-contracts/...` paths.
+- Generated contract clients are published under `dequanto/prebuilt/...` and can be imported or required by subpath in the same way.
+
+## Installed Skill Context
+
+When this directory is installed as a skill, `references/` and `examples/` are relative to the skill directory. Paths under `src/`, `test/`, and `0xc/` identify files in the dequanto repository and are not bundled resources.
+
+In a consuming project, inspect the installed package's `lib/types/` declarations (typically `node_modules/dequanto/lib/types/`) instead of assuming the project's `src/` contains dequanto. Import package APIs through `dequanto/...`.
+
+Examples are executable `UTest` tests when run from the dequanto repository root. Some need generated contracts, Solidity/artifact fixtures, Hardhat configuration, or RPC access. Reuse their relevant code in the target project; replace repository-relative generated-contract imports and fixture paths with that project's equivalents. The installed skill provides guidance, not a standalone runnable test suite.
 
 ## Agent Workflow
 

package/skills/dequanto/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: dequanto
+description: Use when implementing EVM, blockchain, smart-contract, token, RPC, event-indexing, Safe, ERC-4337, storage, deployment, or ABI work in TypeScript projects that use the dequanto framework. Prefer dequanto APIs over ethers, viem, web3.js, raw JSON-RPC, manual explorer HTTP calls, or hand-written ABI encoding unless the user explicitly asks otherwise.
+---
+
+# Dequanto
+
+Use dequanto as the primary EVM toolkit.
+
+## Workflow
+
+1. Identify the requested blockchain task.
+2. Read `./INDEX.md` to choose the dequanto surface.
+3. Read the matching file in `./references/`.
+4. Reuse the nearest example from `./examples/`.
+5. Verify unfamiliar APIs against the target project's installed dequanto package. See the path conventions below.
+6. After TypeScript edits in the dequanto repo, run `npm run typecheck -- --pretty false`.
+
+## Paths And Example Usage
+
+Resolve `./INDEX.md`, `./references/`, and `./examples/` relative to this skill directory, regardless of the working directory.
+
+Source paths such as `src/models/TAccount.ts` refer to the dequanto repository, not this skill directory. In a consuming project, resolve the installed `dequanto` package and inspect its corresponding `lib/types/**/*.d.ts` declarations; a typical location is `node_modules/dequanto/lib/types/`. Use the installed version as the API source of truth.
+
+Examples use published `dequanto/...` imports. They retain the repository's `UTest` harness and may reference generated `0xc/` contracts or `test/fixtures/` files that are not bundled. Adapt the relevant function to the target project's runner, generated contracts, and fixtures. Do not execute examples directly from the installed skill directory or interpret repository-relative imports as installed resource paths.
+
+## Defaults
+
+- Load configuration before any RPC, explorer, indexing, token, or contract action. Prefer `await Config.fetch()` when preparing the runtime, or `await Web3ClientFactory.getAsync(platform)` when creating a chain client because it loads configuration internally.
+- Default RPCs in `src/config/ConfigDefaults.ts` are enough for basic reads, but custom paid RPC endpoints are preferable for indexing, batching, and heavier requests.
+- Configuration can come from the global dequanto YAML edited with `0xweb config -e`, workspace `./configs/dequanto.yml`, runtime `Config.fetch({ rpc })` / `Config.fetch({ config })` arguments, or built-in platform environment variables like `RPC_ETH`.
+- Blockchain explorer config is used for deployment verification, loading verified contract sources for class generation, `0xweb install`, and contract metadata. Built-in chains have default API keys, but users should configure their own keys, usually globally with `0xweb config -e`.
+- Use generated contract classes for ABI calls and transactions: call read-only ABI methods directly as normal TypeScript methods, and call writable ABI methods through `contract.$receipt().someFunction(sender, ...args)`.
+- Use generated `$data()` for calldata.
+- Treat `$receipt()` as a completed `TxWriter` flow that waits for the transaction receipt. The first writable-method argument is an `IAccount`.
+- Read account shapes in `src/models/TAccount.ts` when composing transaction senders:
+    - EOA with only `address`: the RPC provider/node is responsible for signing.
+    - EOA with `key`: dequanto signs directly; encrypted `p1:0x...` keys require the PIN from environment configuration.
+    - `safe`: wrap calldata into a Gnosis Safe transaction. Provide `address` and an `operator`; if enough owners/signers are available, dequanto signs and submits on-chain, otherwise it submits to the Gnosis Safe service for later signing.
+    - `timelock`: wrap calldata into an OpenZeppelin Timelock transaction and submit it via `operator`.
+    - `erc4337`: wrap calldata into an ERC-4337 user operation and submit it via `operator`.
+- Account agents can be chained. For example, a Timelock account can use a Safe account as `operator`, so the initial calldata is wrapped first as Timelock calldata and then as Safe transaction calldata.
+- Use `EventsIndexer` for resumable historical event indexing.
+- Use `BlockchainExplorerFactory` for explorer ABI, source, creation, transactions, and transfers.
+- Prefer generated `contract.storage` readers and `storage.$set(name, value)` when available; use `SlotsParser` and `SlotsStorage` for manual Solidity layouts.
+- Use `Deployments` for idempotent deployments, proxy deployments, beacon deployments, and verification.
+- Use dequanto account-agent flows when the account type says `safe`, `timelock`, or `erc4337`.
+
+## Reference Routing
+
+- Contract reads, writes, generated helper facets: `./references/contracts.md`
+- Configuration, RPC endpoint, and explorer setup: `./examples/config.spec.ts`, `src/config/ConfigDefaults.ts`
+- Hardhat development, forks, impersonation, balance/storage changes, mining, snapshots: `./references/hardhat.md`
+- RPC clients, blocks, balances, raw logs, subscriptions: `./references/rpc-clients.md`
+- Transaction builders, tx writer lifecycle, receipts, nonces: `./references/transactions.md`
+- Contract generation: `./references/generation.md`
+- Deployment and proxy flows: `./references/deployments.md`
+- Historical events and indexing: `./references/events-indexing.md`
+- Explorer integration: `./references/explorer.md`
+- ABI, hashing, validation, hex, dates, signing, and promise helpers: `./references/utils.md`
+- Solidity storage: `./references/storage.md`
+- Tokens and accounts: `./references/tokens-accounts.md`
+- Safe and ERC-4337: `./references/safe-erc4337.md`
+- Translating ethers/viem habits: `./references/migration-from-ethers-viem.md`
+
+## Rules
+
+- Never guess a dequanto API signature.
+- Inspect generated contract classes before using generated method names or event helper names.
+- Do not add ethers, viem, web3.js, or external Safe/account-abstraction SDKs when dequanto already has a suitable API.
+- Keep code version-specific to the installed dequanto package.
+- Prefer examples that compile in the target project over abstract snippets.
+

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

@@ -0,0 +1,113 @@
+import { Config } from 'dequanto/config/Config';
+import { IRpcConfig } from 'dequanto/clients/ClientPool';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { $require } from 'dequanto/utils/$require';
+import { BlockchainExplorerFactory } from 'dequanto/explorer/BlockchainExplorerFactory';
+
+UTest({
+    async 'load default configuration before RPC actions' () {
+        const config = await Config.fetch();
+
+        // Defaults are defined in src/config/ConfigDefaults.ts. They are useful for basic reads,
+        // but paid/custom RPCs are preferable for indexing and higher-volume requests.
+        $require.True(config.web3.eth.endpoints.some(x => x.url.includes('publicnode') || x.url.includes('drpc')));
+    },
+
+    async 'override a built-in platform RPC with the rpc alias' () {
+        await Config.fetch({
+            rpc: {
+                eth: 'https://example.bar'
+            }
+        });
+
+        const client = await Web3ClientFactory.getAsync('eth');
+        $require.eq(client.options.endpoints.length, 1);
+        $require.eq(client.options.endpoints[0].url, 'https://example.bar');
+    },
+
+    async 'override a built-in platform with full RPC endpoint config' () {
+        await Config.fetch({
+            rpc: {
+                eth: [
+                    <IRpcConfig>{
+                        url: 'https://example2.bar',
+                        rateLimit: '100/1sec',
+                        blockRangeLimit: 100_000,
+                        batchLimit: 100,
+                    }
+                ]
+            }
+        });
+
+        const client = await Web3ClientFactory.getAsync('eth');
+        const endpoint = client.options.endpoints[0];
+
+        $require.eq(client.options.endpoints.length, 1);
+        $require.eq(endpoint.url, 'https://example2.bar');
+        $require.eq(endpoint.rateLimit, '100/1sec');
+        $require.eq(endpoint.blockRangeLimit, 100_000);
+        $require.eq(endpoint.batchLimit, 100);
+    },
+
+    async 'define a custom chain config' () {
+        await Config.fetch({
+            config: {
+                web3: {
+                    foo: {
+                        chainId: 500,
+                        chainToken: 'FOO',
+                        endpoints: [
+                            { url: 'wss://foo.example' },
+                            { url: 'https://foo.example' }
+                        ]
+                    }
+                }
+            }
+        });
+
+        const client = await Web3ClientFactory.getAsync('foo');
+        $require.eq(client.chainId, 500);
+        $require.eq(client.options.endpoints[0].url, 'wss://foo.example');
+        $require.eq(client.options.endpoints[1].url, 'https://foo.example');
+    },
+
+    async 'override a built-in blockchain explorer API key' () {
+        // Explorer APIs are used for contract verification, source loading, 0xweb install, and metadata.
+        const config = await Config.fetch({
+            config: {
+                blockchainExplorer: {
+                    eth: { key: 'Foo' }
+                }
+            }
+        });
+        const explorer = await BlockchainExplorerFactory.getAsync('eth');
+        $require.eq(explorer.config.api.key, 'Foo');
+    },
+
+    async 'define blockchain explorer config for a custom platform' () {
+        await Config.fetch({
+            config: {
+                // web3 config is also required for the chain
+                web3: {
+                    foo: { chainId: 4000, endpoints: [] },
+                },
+                blockchainExplorer: {
+                    foo: { api: 'https://api.foo.bar/?token=BAR' }
+                }
+            }
+        });
+        const explorer = await BlockchainExplorerFactory.getAsync('foo');
+        $require.eq(explorer.config.api.url, 'https://api.foo.bar/?token=BAR' );
+    },
+
+    $teardown () {
+        Config.clean();
+    }
+});
+
+// Config sources agents should know about:
+// 1. Global dequanto config, editable with: 0xweb config -e
+// 2. Workspace config: ./configs/dequanto.yml
+// 3. Runtime overrides: Config.fetch({ rpc }) or Config.fetch({ config })
+// 4. Built-in platform RPC env vars: RPC_<PLATFORM>, for example RPC_ETH
+// Explorer API keys can also be configured globally, which is important for deploy verification and 0xweb install.

package/skills/dequanto/examples/contract-read.spec.ts

@@ -0,0 +1,112 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ContractClassFactory } from 'dequanto/contracts/ContractClassFactory';
+// dequanto ships prebuilt TypeScript clients for all OpenZeppelin contracts.
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+// Use 0xweb CLI to download and generate simple TypeScript clients for verified contracts from Etherscan-compatible explorers:
+// 0xweb install <address> --name AavePool --chain eth --save-sources false
+import { AavePool } from '../../../0xc/eth/AavePool/AavePool';
+import { $abi } from 'dequanto/abi/$abi';
+import { $require } from 'dequanto/utils/$require';
+import type { TEth } from 'dequanto/models/TEth';
+import { $address } from 'dequanto/utils/$address';
+
+const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
+const AAVE_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2' as const;
+
+UTest({
+    async 'read data from mainnet using the prebuilt ERC20 contract' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const usdc = new ERC20(USDC, client);
+
+        const [symbol, decimals, balance] = await Promise.all([
+            usdc.symbol(),
+            usdc.decimals(),
+            usdc.balanceOf('0x0000000000000000000000000000000000000000')
+        ]);
+
+        $require.eq(symbol, 'USDC');
+        $require.eq(Number(decimals), 6);
+        $require.gte(balance, 0n);
+    },
+
+    async 'read data from mainnet using the generated AavePool' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const pool = new AavePool(undefined, client);
+
+        const [addressesProvider, maxReserves, reserves, reserveData] = await Promise.all([
+            pool.ADDRESSES_PROVIDER(),
+            pool.MAX_NUMBER_RESERVES(),
+            pool.getReservesList(),
+            pool.getReserveData(USDC)
+        ]);
+
+        $require.AddressNotEmpty(addressesProvider);
+        $require.gt(Number(maxReserves), 0);
+        $require.True(reserves.some(x => $address.eq(x, USDC)));
+        $require.AddressNotEmpty(reserveData.aTokenAddress);
+        $require.AddressNotEmpty(reserveData.variableDebtTokenAddress);
+        $require.gte(reserveData.liquidityIndex, 1n);
+    },
+
+    async 'read data from mainnet by generating the class from ABI as JSON or string' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const { contract: pool } = ContractClassFactory.fromAbi(AAVE_POOL, [
+            'function ADDRESSES_PROVIDER() view returns (address)',
+            {
+                type: 'function',
+                name: 'MAX_NUMBER_RESERVES',
+                stateMutability: 'view',
+                inputs: [],
+                outputs: [
+                    { type: 'uint16', name: '' }
+                ]
+            }
+        ], client);
+
+        const [addressesProvider, maxReserves] = await Promise.all([
+            pool.ADDRESSES_PROVIDER(),
+            pool.MAX_NUMBER_RESERVES()
+        ]);
+
+        $require.AddressNotEmpty(addressesProvider);
+        $require.gt(Number(maxReserves), 0);
+    },
+
+    async 'read data from mainnet using a low-level RPC call' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const rpc = await client.getRpc();
+
+        const addressesProviderAbi = 'function ADDRESSES_PROVIDER() view returns (address)';
+        const responseHex = await rpc.eth_call({
+            to: AAVE_POOL,
+            input: $abi.encodeCall(addressesProviderAbi),
+        });
+
+        const addressesProvider = $abi.decodeReturn<TEth.Address>(addressesProviderAbi, responseHex);
+
+        $require.AddressNotEmpty(addressesProvider);
+    },
+
+
+    async 'batch-read data from mainnet using the generated AavePool' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const pool = new AavePool(undefined, client);
+
+        const [addressesProvider, maxReserves, reserves, isNull, reserveData] = await client.batchContractCalls([
+            pool.$req().ADDRESSES_PROVIDER(),
+            pool.$req().MAX_NUMBER_RESERVES(),
+            pool.$req().getReservesList(),
+            // allows null
+            null,
+            pool.$req().getReserveData(USDC),
+        ]);
+
+        $require.AddressNotEmpty(addressesProvider);
+        $require.gt(Number(maxReserves), 0);
+        $require.True(reserves.some(x => $address.eq(x, USDC)));
+        $require.AddressNotEmpty(reserveData.aTokenAddress);
+        $require.AddressNotEmpty(reserveData.variableDebtTokenAddress);
+        $require.gte(reserveData.liquidityIndex, 1n);
+        $require.Null(isNull);
+    },
+});

package/skills/dequanto/examples/contract-write.spec.ts

@@ -0,0 +1,68 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ContractReader } from 'dequanto/contracts/ContractReader';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+import { AavePool } from '../../../0xc/eth/AavePool/AavePool';
+import type { TEth } from 'dequanto/models/TEth';
+import { $account } from 'dequanto/utils/$account';
+import { $address } from 'dequanto/utils/$address';
+import { $require } from 'dequanto/utils/$require';
+
+const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
+
+UTest({
+    async 'submit a contract write transaction' () {
+        // Use getAsync(platform) with a real funded account to submit the same write on mainnet
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const pool = new AavePool(undefined, client);
+
+        const addressesProvider = await pool.ADDRESSES_PROVIDER();
+        const poolConfigurator = await ContractReader.read<TEth.Address>(
+            client,
+            addressesProvider,
+            'function getPoolConfigurator() view returns (address)'
+        );
+
+        const configuratorAccount = {
+            address: poolConfigurator,
+            type: 'impersonated'
+        } as const;
+
+        const newFlashloanPremium = 12_345n;
+        const tx = await pool.$receipt().updateFlashloanPremium(configuratorAccount, newFlashloanPremium);
+        $require.Hex(tx.receipt.transactionHash);
+
+        const premium = await pool.FLASHLOAN_PREMIUM_TOTAL();
+        $require.eq(premium, newFlashloanPremium);
+    },
+
+    async 'submit a contract write transaction and read a typed event log' () {
+        // Use getAsync(platform) with a real funded account to submit the same write on mainnet
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const pool = new AavePool(undefined, client);
+
+        const user = $account.generate('user');
+        const positionManager = $account.generate('positionManager');
+
+        await client.debug.setBalance(user.address, BigInt(1e18));
+
+        const tx = await pool.$receipt().approvePositionManager(user, positionManager.address, true);
+        $require.Hex(tx.receipt.transactionHash);
+
+        const [approvalLog] = await pool.extractLogsPositionManagerApproved(tx.receipt);
+        $require.True($address.eq(approvalLog.params.user, user.address));
+        $require.True($address.eq(approvalLog.params.positionManager, positionManager.address));
+    },
+
+    async 'build ERC20 transfer transaction data without submitting it' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const usdc = new ERC20(USDC, client);
+        const transferSender = { address: '0x0000000000000000000000000000000000000001' as const };
+        const transferRecipient = '0x0000000000000000000000000000000000000002' as const;
+        const amount = 1_000_000n;
+
+        const tx = await usdc.$data().transfer(transferSender, transferRecipient, amount);
+
+        $require.True($address.eq(tx.to, usdc.address));
+        $require.match(/^0xa9059cbb/, tx.data);
+    }
+});

package/skills/dequanto/examples/deploy-contract.spec.ts

@@ -0,0 +1,69 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { Deployments } from 'dequanto/contracts/deploy/Deployments';
+import { Generator } from 'dequanto/gen/Generator';
+import { $account } from 'dequanto/utils/$account';
+import { $require } from 'dequanto/utils/$require';
+import { File } from 'atma-io';
+
+// In a Hardhat project, include the @0xweb/hardhat plugin in hardhat.config.*.
+// See https://github.com/0xweb-org/hardhat for plugin setup.
+// Then hardhat compile auto-generates contract classes in 0xc/hardhat/**.
+// A deployment script can import the generated class directly:
+// import { FooContract } from '0xc/hardhat/FooContract/FooContract';
+declare const include: any;
+
+UTest({
+    async 'deploy a generated contract class with Deployments.ensure' () {
+        const { client, deployer, FooContract } = await getContractClass();
+        const deployments = new Deployments(client, deployer, {
+            directory: './test/tmp/ai-examples/'
+        });
+
+        // ensure returns an existing deployment by contract name, or by DeploymentOptions.id when provided.
+        // On mainnet, new deployments are automatically verified on the configured block explorer.
+        const { contract } = await deployments.ensure(FooContract, { arguments: [] });
+        // With an imported autogenerated class, contract is typed as FooContract with typed read/write methods.
+        const value = await (contract as any).getValue();
+
+        $require.AddressNotEmpty(contract.address);
+        $require.eq(value, 4n);
+    },
+
+    async 'deploy a generated contract class with an upgradeable proxy' () {
+        const { client, deployer, FooContract } = await getContractClass();
+        const deployments = new Deployments(client, deployer, {
+            directory: './test/tmp/ai-examples/'
+        });
+
+        // ensureWithProxy uses OpenZeppelin TransparentUpgradeableProxy by default.
+        // It tracks Proxy, ProxyAdmin, and implementation deployments separately.
+        // The implementation bytecode hash is saved, so Solidity source changes deploy a new implementation.
+        // Existing proxies are then upgraded with upgradeToAndCall; the deployment call stays almost the same.
+        const { contract } = await deployments.ensureWithProxy(FooContract, {
+            arguments: [],
+            initialize: []
+        });
+        // With an imported autogenerated class, contract is typed as FooContract with typed read/write methods.
+        const value = await (contract as any).getValue();
+
+        $require.AddressNotEmpty(contract.address);
+        $require.eq(value, 6n);
+    }
+});
+
+async function getContractClass () {
+    const client = await Web3ClientFactory.getAsync('hh:memory');
+    const deployer = $account.generate('deployer');
+    await client.debug.setBalance(deployer.address, BigInt(1e18));
+
+    // Test-only cleanup: real projects usually keep deployment records between runs.
+    const deploymentsFile = './test/tmp/ai-examples/deployments-hardhat.json';
+    await File.removeAsync(deploymentsFile);
+
+    // Test-only generation/loading: hardhat compile normally generates this class via @0xweb/hardhat.
+    const generated = await Generator.generateFromSol('./test/fixtures/deployments/DeploymentsFoo.sol');
+    const module = await include.instance().js(generated.main);
+    const FooContract = module.DeploymentsFoo.DeploymentsFoo;
+
+    return { client, deployer, FooContract };
+}