dequanto 0.2.49 → 0.2.50

package/contracts/oz/Proxy.sol

@@ -0,0 +1 @@
+import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";

package/docs/ai/INDEX.md

@@ -10,10 +10,11 @@ Before using an unfamiliar dequanto API, verify the exact signature in `src/` or
 
 | Goal | Use | Reference | Examples |
 | --- | --- | --- | --- |
+| 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 | `Web3ClientFactory`, `Web3Client`, chain clients | `references/rpc-clients.md` | `examples/rpc-read.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` |
@@ -25,11 +26,11 @@ Before using an unfamiliar dequanto API, verify the exact signature in `src/` or
 
 ## 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.
 
 ## Agent Workflow
 

package/docs/ai/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/docs/ai/examples/contract-read.spec.ts

@@ -1,14 +1,20 @@
 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 stable USDC metadata from live Ethereum RPC' () {
+    async 'read data from mainnet using the prebuilt ERC20 contract' () {
         const client = await Web3ClientFactory.getAsync('eth');
         const usdc = new ERC20(USDC, client);
 
@@ -18,12 +24,12 @@ UTest({
             usdc.balanceOf('0x0000000000000000000000000000000000000000')
         ]);
 
-        eq_(symbol, 'USDC');
-        eq_(Number(decimals), 6);
-        gte_(balance, 0n);
+        $require.eq(symbol, 'USDC');
+        $require.eq(Number(decimals), 6);
+        $require.gte(balance, 0n);
     },
 
-    async 'read generated Aave Pool data from live Ethereum RPC' () {
+    async 'read data from mainnet using the generated AavePool' () {
         const client = await Web3ClientFactory.getAsync('eth');
         const pool = new AavePool(undefined, client);
 
@@ -34,11 +40,73 @@ UTest({
             pool.getReserveData(USDC)
         ]);
 
-        has_(addressesProvider, /^0x[a-fA-F0-9]{40}$/);
-        gt_(Number(maxReserves), 0);
-        eq_(reserves.some(x => x.toLowerCase() === USDC.toLowerCase()), true);
-        has_(reserveData.aTokenAddress, /^0x[a-fA-F0-9]{40}$/);
-        has_(reserveData.variableDebtTokenAddress, /^0x[a-fA-F0-9]{40}$/);
-        gte_(reserveData.liquidityIndex, 1n);
-    }
-});
+        $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/docs/ai/examples/contract-write.spec.ts

@@ -1,16 +1,68 @@
 import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { ERC20 } from '@dequanto-contracts/openzeppelin/ERC20';
+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 'build ERC20 transfer tx data without submitting' () {
+    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('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
-        const sender = { address: '0x0000000000000000000000000000000000000001' as const };
-        const receiver = '0x0000000000000000000000000000000000000002' as const;
+        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(sender, receiver, 1_000_000n);
+        const tx = await usdc.$data().transfer(transferSender, transferRecipient, amount);
 
-        eq_(tx.to.toLowerCase(), usdc.address.toLowerCase());
-        has_(tx.data, /^0xa9059cbb/);
+        $require.True($address.eq(tx.to, usdc.address));
+        $require.match(/^0xa9059cbb/, tx.data);
     }
-});
+});

package/docs/ai/examples/deploy-contract.spec.ts

@@ -1,32 +1,69 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
 import { Deployments } from '@dequanto/contracts/deploy/Deployments';
 import { Generator } from '@dequanto/gen/Generator';
-import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
+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 with Deployments.ensure' () {
-        const hh = new HardhatProvider();
-        const client = hh.client();
-        const deployer = hh.deployer(0);
-        const deploymentsFile = './test/tmp/ai-examples/deployments-hardhat.json';
+    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/'
+        });
 
-        await File.removeAsync(deploymentsFile);
+        // 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();
 
-        const generated = await Generator.generateFromSol('./test/fixtures/deployments/DeploymentsFoo.sol');
-        const module = await include.instance().js(generated.main);
-        const Ctor = module.DeploymentsFoo.DeploymentsFoo;
+        $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/',
-            verification: false
+            directory: './test/tmp/ai-examples/'
         });
 
-        const { contract } = await deployments.ensure(Ctor, { arguments: [] });
+        // 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();
 
-        has_(contract.address, /^0x[a-fA-F0-9]{40}$/);
-        eq_(value, 4n);
+        $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 };
+}

package/docs/ai/examples/erc4337-userop.spec.ts

@@ -4,6 +4,7 @@ import { Erc4337Service } from '@dequanto/erc4337/Erc4337Service';
 import { UserOperation } from '@dequanto/erc4337/models/UserOperation';
 import { $address } from '@dequanto/utils/$address';
 import { $erc4337 } from '@dequanto/erc4337/utils/$erc4337';
+import { $require } from '@dequanto/utils/$require';
 
 UTest({
     async 'hash a UserOperation and create an ERC-4337 service' () {
@@ -28,10 +29,11 @@ UTest({
             paymasterAndData: '0x',
             signature: '0x'
         };
+        const entryPointAddress = '0xc6e7df5e7b4f2a278906862b61205850344d4e7d';
+        const chainId = 1;
+        const hash = $erc4337.hash(op,entryPointAddress , chainId);
 
-        const hash = $erc4337.hash(op, '0xc6e7df5e7b4f2a278906862b61205850344d4e7d', 1);
-
-        has_(hash, /^0x[a-fA-F0-9]{64}$/);
-        notEq_(service, null);
+        $require.match(/^0x[a-fA-F0-9]{64}$/, hash);
+        $require.notNull(service);
     }
-});
+});

package/docs/ai/examples/explorer-abi.spec.ts

@@ -1,4 +1,6 @@
 import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
+import { $address } from '@dequanto/utils/$address';
+import { $require } from '@dequanto/utils/$require';
 
 UTest({
     async 'fetch stable USDC ABI and source from configured Ethereum explorer' () {
@@ -9,10 +11,11 @@ UTest({
         const source = await explorer.getContractSource(implementation);
         const creation = await explorer.getContractCreation(address);
 
-        eq_(implementation.toLowerCase(), address);
-        gt_(JSON.parse(abi).length, 0);
-        has_(source.ContractName, /FiatToken|Proxy|USDC/i);
-        has_(creation.creator, /^0x[a-fA-F0-9]{40}$/);
-        has_(creation.txHash, /^0x[a-fA-F0-9]{64}$/);
+        $require.AddressNotEmpty(implementation);
+        $require.True($address.eq(implementation, address) === false, `USDC is Proxy: ${implementation} != ${address}`);
+        $require.gt(JSON.parse(abi).length, 0);
+        $require.match(/FiatToken|Proxy|USDC/i, source.ContractName);
+        $require.AddressNotEmpty(creation.creator);
+        $require.TxHash(creation.txHash);
     }
-});
+});

package/docs/ai/examples/{generate-client.spec.ts → generate-contract-class.spec.ts}

@@ -1,8 +1,11 @@
 import { Generator } from '@dequanto/gen/Generator';
+import { $require } from '@dequanto/utils/$require';
 import { File } from 'atma-io';
 
+// Generator is the low-level API for creating contract classes programmatically.
+// Prefer 0xweb install for third-party contracts and @0xweb/hardhat for local Hardhat contracts.
 UTest({
-    async 'generate a typed contract client from a fixture artifact' () {
+    async 'generate a typed contract class from a fixture artifact' () {
         const output = './test/tmp/ai-examples/hardhat/';
         const gen = new Generator({
             name: 'AnyERC20',
@@ -16,7 +19,7 @@ UTest({
         const result = await gen.generate();
         const source = await File.readAsync<string>(result.main, { skipHooks: true });
 
-        has_(source, 'class AnyERC20');
-        has_(source, 'ContractBase');
+        $require.has('class AnyERC20', source);
+        $require.has('ContractBase', source);
     }
 });

package/docs/ai/examples/index-events.spec.ts

@@ -1,12 +1,14 @@
 import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
 import { EventsIndexer } from '@dequanto/indexer/EventsIndexer';
-import { ERC20 } from '@dequanto-contracts/openzeppelin/ERC20';
+import { ERC20 } from '@dequanto/prebuilt/openzeppelin/ERC20';
+import { $require } from '@dequanto/utils/$require';
 
 UTest({
     async 'index stable USDC Transfer logs from live Ethereum RPC' () {
         const client = await Web3ClientFactory.getAsync('eth');
         const usdc = new ERC20('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
 
+        // EventsIndexer stores fetched logs in the local cache directory, so later runs can reuse cached ranges.
         const indexer = new EventsIndexer(usdc, {
             name: 'USDCTransfersAiExample',
             fs: {
@@ -19,9 +21,9 @@ UTest({
             toBlock: 18_000_010
         });
 
-        gt_(logs.length, 0);
-        gte_(infos.fetched + infos.cached, logs.length);
-        eq_(logs[0].event, 'Transfer');
-        has_(logs[0].transactionHash, /^0x[a-fA-F0-9]{64}$/);
+        $require.gt(logs.length, 0);
+        $require.gte(infos.fetched + infos.cached, logs.length);
+        $require.eq(logs[0].event, 'Transfer');
+        $require.TxHash(logs[0].transactionHash);
     }
-});
+});

package/docs/ai/examples/rpc-read.spec.ts

@@ -1,15 +1,42 @@
 import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { Config } from '@dequanto/config/Config';
+import { $require } from '@dequanto/utils/$require';
 
 UTest({
-    async 'read latest block and zero-address balance from live Ethereum RPC' () {
+    async '!read common RPC data via Web3Client directly' () {
+        const cfg = await Config.fetch();
+
         const client = await Web3ClientFactory.getAsync('eth');
 
+        const chainId = await client.getChainId();
         const latest = await client.getBlockNumber();
         const block = await client.getBlock('latest');
         const balance = await client.getBalance('0x0000000000000000000000000000000000000000');
 
-        gt_(Number(latest), 0);
-        gt_(Number(block.timestamp), 0);
-        gte_(balance, 0n);
+        $require.eq(chainId, 1);
+        $require.gt(Number(latest), 0);
+        $require.gt(Number(block.timestamp), 0);
+        $require.gte(balance, 0n);
+    },
+
+    async 'call low-level RPC methods from the generated Rpc client' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        // getRpc exposes the full generated RPC method list from OpenRPC specs, including eth, core-geth, MetaMask, and Flashbots methods.
+        const rpc = await client.getRpc();
+
+        const latest = await rpc.eth_blockNumber();
+        const block = await rpc.eth_getBlockByNumber('latest', false);
+        const balance = await rpc.eth_getBalance('0x0000000000000000000000000000000000000000', 'latest');
+
+        $require.gt(Number(latest), 0);
+        $require.gt(Number(block.timestamp), 0);
+        $require.gte(balance, 0n);
+
+        // Use rpc.request for custom or not-yet-generated RPC methods.
+        const response = await rpc.request({
+            method: 'eth_blockNumber',
+            params: []
+        });
+        $require.gt(Number(response), 0);
     }
-});
+});

package/docs/ai/examples/safe-batch.spec.ts

@@ -2,6 +2,7 @@ import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
 import { InMemoryServiceTransport } from '@dequanto/safe/transport/InMemoryServiceTransport';
 import { SafeTx } from '@dequanto/safe/SafeTx';
 import { $address } from '@dequanto/utils/$address';
+import { $require } from '@dequanto/utils/$require';
 import { SafeAccount } from '@dequanto/models/TAccount';
 
 UTest({
@@ -45,11 +46,11 @@ UTest({
             await token.$data().transfer(safeAccount, owner2.address, 50n)
         ];
 
-        eq_(txs.length, 2);
+        $require.eq(txs.length, 2);
         txs.forEach(tx => {
-            eq_(tx.to, token.address);
-            has_(tx.data, /^0x[a-fA-F0-9]+$/);
+            $require.True($address.eq(tx.to, token.address));
+            $require.match(/^0x[a-fA-F0-9]+$/, tx.data);
         });
-        notEq_(safeTx, null);
+        $require.notNull(safeTx);
     }
 });