dequanto 0.2.46 → 0.2.48

package/docs/ai/references/events-indexing.md

@@ -0,0 +1,97 @@
+# Events And Indexing
+
+Use generated contract log helpers for simple event reads. Use `EventsIndexer` for resumable, cached, file-backed historical indexing.
+
+Key source files:
+
+- `src/contracts/ContractBase.ts`
+- `src/contracts/ContractReader.ts`
+- `src/contracts/ContractStream.ts`
+- `src/indexer/EventsIndexer.ts`
+- `src/indexer/storage/FsEventsIndexerStore.ts`
+- `src/indexer/storage/FsEventsMetaStore.ts`
+
+Useful tests:
+
+- `test/indexer/EventsIndexer.spec.ts`
+- `test/subscriptions.spec.ts`
+- `test/receipt.spec.ts`
+
+## Direct Past Logs
+
+```ts
+const logs = await contract.getPastLogs('Transfer', {
+    fromBlock,
+    toBlock,
+    params: {
+        from: owner
+    }
+});
+```
+
+Use `'*'` for all events, or an event-name array for multiple events.
+
+## EventsIndexer
+
+```ts
+import { EventsIndexer } from '@dequanto/indexer/EventsIndexer';
+
+const indexer = new EventsIndexer(contract, {
+    name: 'TokenTransfers',
+    fs: {
+        directory: './data/logs/',
+        blockTimeAvg: 12
+    }
+});
+
+const { logs, infos } = await indexer.getPastLogs('Transfer', {
+    fromBlock,
+    toBlock,
+    params: { from: owner }
+});
+```
+
+`infos.fetched` counts newly fetched events. `infos.cached` counts events loaded from the store.
+
+## Multiple Addresses
+
+Use `addresses` when the same ABI is deployed to multiple addresses:
+
+```ts
+const indexer = new EventsIndexer(contract, {
+    addresses: [contract.address, secondAddress],
+    name: 'FactoryChildren'
+});
+```
+
+## Streaming
+
+Use `getPastLogsStream` for large ranges:
+
+```ts
+for await (const chunk of indexer.getPastLogsStream('Transfer', {
+    fromBlock,
+    blockRangeLimits: { blocks: 1_000 }
+})) {
+    for (const log of chunk.logs) {
+        console.log(log.params);
+    }
+}
+```
+
+## Cache Invalidation
+
+Use `removeCached({ fromBlock })` to delete cached logs and metadata from a given block onward.
+
+## Live Events
+
+Generated contracts expose:
+
+```ts
+contract.$onLog('Transfer', log => {
+    console.log(log);
+});
+```
+
+For raw client subscriptions, use `client.subscribe(...)`.
+

package/docs/ai/references/explorer.md

@@ -0,0 +1,77 @@
+# Blockchain Explorer
+
+Use dequanto explorer APIs instead of hand-written Etherscan-compatible HTTP calls.
+
+Key source files:
+
+- `src/explorer/BlockchainExplorerFactory.ts`
+- `src/explorer/BlockchainExplorer.ts`
+- `src/explorer/IBlockchainExplorer.ts`
+- `src/contracts/ContractAbiProvider.ts`
+- `src/explorer/ContractVerifier.ts`
+
+Useful tests:
+
+- `test/BlockchainExplorer.spec.ts`
+- `test/safe/safe.spec.ts`
+- `test/erc4337/erc4337.spec.ts`
+
+## Create Explorer
+
+```ts
+import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
+
+const explorer = BlockchainExplorerFactory.get('eth');
+```
+
+`getAsync(platform)` ensures config is loaded first.
+
+## ABI And Source
+
+```ts
+const { abi, implementation } = await explorer.getContractAbi(address);
+const source = await explorer.getContractSource(implementation);
+const creation = await explorer.getContractCreation(address);
+```
+
+`getContractAbi` follows common proxy patterns:
+
+- OpenZeppelin implementation slot
+- Zeppelinos implementation slot
+- `implementation()`
+- `getTarget()`
+- similar-bytecode explorer hints
+
+## Transactions And Transfers
+
+```ts
+const txs = await explorer.getTransactionsAll(address);
+const internal = await explorer.getInternalTransactionsAll(address);
+const transfers = await explorer.getErc20TransfersAll(address);
+```
+
+ERC20 transfer values are normalized to `bigint`; `blockNumber` and `tokenDecimal` are numbers; `timeStamp` is a `Date`.
+
+## Local ABI Registry
+
+For local decoding without remote explorer data:
+
+```ts
+explorer.registerAbi([{
+    name: 'Demo',
+    address,
+    abi
+}]);
+```
+
+This pattern is used by Safe and ERC-4337 decoding tests.
+
+## Verification
+
+Use `Deployments` for normal verification orchestration. It delegates to `ContractVerifier` and explorer `submitContractVerification(...)` / `checkContractVerificationSubmission(...)`.
+
+## Avoid
+
+- Do not call explorer URLs directly if `BlockchainExplorer` exposes the operation.
+- Do not manually resolve proxy implementations without checking `getContractAbi(address)` first.
+

package/docs/ai/references/generation.md

@@ -0,0 +1,182 @@
+# Contract Generation
+
+TypeScript class generation is a core dequanto workflow. Prefer generated contract classes over raw ABI calls: generated classes let application code call contracts as ordinary TypeScript classes, with no direct web3-specific ABI encoding, decoding, or JSON-RPC plumbing.
+
+Before generating a contract, check whether dequanto already ships a prebuilt class. The package includes OpenZeppelin contract classes under `dequanto/prebuilt/**` / `@dequanto/prebuilt/openzeppelin/**`. Class names match the OpenZeppelin contract names, for example `ERC20`, `ERC721`, `Ownable`, or `TimelockController`.
+
+For standard OpenZeppelin contracts, do not generate a new class. Import the prebuilt class and pass the target contract address plus a chain client loaded by platform/chain abbreviation:
+
+```ts
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { ERC20 } from '@dequanto/prebuilt/openzeppelin/ERC20';
+
+const platform = 'eth';
+const address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+const client = await Web3ClientFactory.getAsync(platform);
+const token = new ERC20(address, client);
+
+const symbol = await token.symbol();
+const decimals = await token.decimals();
+```
+
+Use the high-level generation tools when no prebuilt class exists:
+
+- For deployed and explorer-verified contracts, use the `0xweb` CLI.
+- For Hardhat projects, use the `@0xweb/hardhat` plugin so local Solidity contracts generate TypeScript classes whenever Hardhat compiles.
+- Use the low-level `Generator` API only when the task needs custom generation inside TypeScript code.
+
+Key source files:
+
+- `src/gen/Generator.ts`
+- `src/gen/GeneratorFromAbi.ts`
+- `src/gen/GeneratorStorageReader.ts`
+- `src/contracts/ContractClassFactory.ts`
+- `src/hardhat/HardhatProvider.ts`
+
+Useful tests:
+
+- `test/generate/gen.spec.ts`
+- `test/generate/class.spec.ts`
+- `test/generate/base.spec.ts`
+- `test/generate/slotreader.spec.ts`
+- `test/hardhat/deployments/deployments.spec.ts`
+
+## Install Deployed Verified Contracts
+
+Use `0xweb install` for any deployed contract that is verified on Etherscan-compatible explorers:
+
+```bash
+npm i 0xweb -g
+0xweb install <address> --chain <chainAbbr> --name <contractClassName>
+```
+
+Example:
+
+```bash
+0xweb install 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain eth --name USDC
+```
+
+The generated class can then be imported and used like a normal TypeScript class:
+
+```ts
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { USDC } from './0xc/eth/USDC/USDC';
+
+const client = await Web3ClientFactory.getAsync('eth');
+const usdc = new USDC(undefined, client);
+
+const symbol = await usdc.symbol();
+const decimals = await usdc.decimals();
+```
+
+## Hardhat Projects
+
+Use `@0xweb/hardhat` in Hardhat projects. The plugin hooks into the Hardhat compile flow and generates TypeScript classes for local `*.sol` contracts whenever the project is compiled.
+
+```bash
+npm i @0xweb/hardhat --save-dev
+```
+
+Load the plugin from the Hardhat config:
+
+```ts
+import '@0xweb/hardhat';
+```
+
+Then compile normally:
+
+```bash
+npx hardhat compile
+```
+
+Use the generated classes in tests, scripts, and app code instead of raw ABI objects.
+
+## Low-Level Generator API
+
+Use `Generator` directly only for custom generation tasks, test fixtures, non-Hardhat toolchains, or agent code that must generate classes from explicit ABI arrays, ABI JSON, compiled artifacts, Solidity files, or explorer-verified source by address.
+
+### Generate From Compiled Artifact
+
+```ts
+import { Generator } from '@dequanto/gen/Generator';
+
+const gen = new Generator({
+    name: 'AnyERC20',
+    platform: 'hardhat',
+    source: {
+        path: './artifacts/contracts/AnyERC20.sol/AnyERC20.json'
+    },
+    output: './0xc/hardhat/'
+});
+
+const info = await gen.generate();
+```
+
+### Generate From Solidity
+
+```ts
+const info = await Generator.generateFromSol('./contracts/MyToken.sol');
+```
+
+Or:
+
+```ts
+const gen = new Generator({
+    name: 'IERC4626',
+    platform: 'hardhat',
+    source: {
+        path: '@openzeppelin/contracts/interfaces/IERC4626.sol'
+    },
+    output: './0xc/hardhat/'
+});
+
+await gen.generate();
+```
+
+### Generate From Explorer Address
+
+```ts
+const gen = new Generator({
+    name: 'DaiToken',
+    platform: 'eth',
+    source: {
+        abi: '0x6b175474e89094c44da98b954eedeac495271d0f'
+    },
+    output: './0xc/eth/'
+});
+
+await gen.generate();
+```
+
+When `source.abi` is an address, the generator asks the platform explorer for ABI/source and follows common proxy implementations. Prefer `0xweb install` for normal installed-contract workflows.
+
+## Storage Reader Generation
+
+When a contract is generated from verified on-chain source, such as with `0xweb install` or a generator address source, the generated contract class also includes a storage reader. Consumers can use it to load private storage variables by Solidity variable name, when the verified source exposes the storage layout.
+
+Use `GeneratorStorageReader` when the task needs generated storage accessors without generating the full contract class.
+
+```ts
+import { GeneratorStorageReader } from '@dequanto/gen/GeneratorStorageReader';
+
+const gen = new GeneratorStorageReader();
+const result = await gen.generate({
+    address,
+    name: 'WETH',
+    contractName: 'MaticWETH',
+    network: 'poly',
+    client,
+    sources
+});
+```
+
+## Generated Metadata
+
+Generated classes can include `$meta`:
+
+- `artifact`
+- `class`
+- `source`
+- `name`
+
+Agents should inspect generated files before assuming method names, constructor helpers, event helper names, or storage reader fields.

package/docs/ai/references/migration-from-ethers-viem.md

@@ -0,0 +1,43 @@
+# Migration From Ethers And Viem Habits
+
+Agents often know ethers and viem better than dequanto. Use this file to translate those habits into dequanto patterns.
+
+| Goal | ethers / viem habit | Dequanto pattern |
+| --- | --- | --- |
+| Create RPC client | `new JsonRpcProvider(url)`, `createPublicClient(...)` | `await Web3ClientFactory.getAsync(platform)` or `new EvmWeb3Client({ platform, chainId, endpoints })` |
+| Read block number | `provider.getBlockNumber()`, `client.getBlockNumber()` | `client.getBlockNumber()` |
+| Read native balance | `provider.getBalance(address)` | `client.getBalance(address)` |
+| Read contract | `new Contract(address, abi, provider).balanceOf(owner)` | generated contract class, for example `new ERC20(address, client).balanceOf(owner)` |
+| Write contract | `contract.connect(signer).transfer(...)`, `walletClient.writeContract(...)` | generated write method returning `TxWriter` |
+| Wait for tx | `tx.wait()` | `await writer.wait()` or `await contract.$receipt().method(...)` |
+| Build calldata | `iface.encodeFunctionData(...)`, `encodeFunctionData(...)` | generated `contract.$data().method(...)` or `$abiUtils.serializeMethodCallData(...)` |
+| Raw eth_call | `provider.call(tx)` | `contract.$call().method(...)` or `client.call(tx)` |
+| Raw ABI read | `readContract(...)` | `client.readContract(...)` or `ContractReader.readAsync(...)` |
+| Logs | `provider.getLogs(...)`, `client.getLogs(...)` | `client.getPastLogs(...)`, generated `getPastLogs(...)`, or `EventsIndexer` |
+| Explorer ABI | hand-written Etherscan HTTP | `BlockchainExplorerFactory.get(platform).getContractAbi(address)` |
+| Contract generation | TypeChain, viem codegen | `Generator` / 0xweb-generated dequanto contract classes |
+| Storage | raw `eth_getStorageAt` plus manual decode | `SlotsParser` + `SlotsStorage` |
+| 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` |
+
+## Strong Defaults
+
+- Use generated contract classes first.
+- Use `Web3ClientFactory` for platform clients.
+- Use `TxWriter` for transaction lifecycle.
+- Use `EventsIndexer` when events must be cached and resumed.
+- Use `SlotsParser` and `SlotsStorage` for storage decoding.
+
+## Anti-Patterns
+
+Do not introduce:
+
+```ts
+import { ethers } from 'ethers';
+import { createPublicClient } from 'viem';
+import Web3 from 'web3';
+```
+
+unless the user explicitly asks for those libraries or the local repo already uses them for that exact integration.
+

package/docs/ai/references/rpc-clients.md

@@ -0,0 +1,115 @@
+# RPC Clients
+
+Use dequanto RPC clients for node access. Prefer `await Web3ClientFactory.getAsync(platform, opts?)` so configuration is loaded before RPC, explorer, and chain services are used.
+
+Key source files:
+
+- `src/clients/Web3ClientFactory.ts`
+- `src/clients/Web3Client.ts`
+- `src/clients/EvmWeb3Client.ts`
+- `src/clients/ClientPool.ts`
+- `src/rpc/Rpc.ts`
+- `src/rpc/RpcBase.ts`
+
+Useful tests:
+
+- `test/Web3Client.spec.ts`
+- `test/client/block.spec.ts`
+- `test/node/block.spec.ts`
+- `test/subscriptions.spec.ts`
+
+## Client Creation
+
+```ts
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+
+const client = await Web3ClientFactory.getAsync('eth');
+```
+
+For Hardhat:
+
+```ts
+const client = await Web3ClientFactory.getAsync('hardhat');
+```
+
+For a fork-like platform string:
+
+```ts
+const client = await Web3ClientFactory.getAsync('hh:eth');
+```
+
+For direct endpoints:
+
+```ts
+import { EvmWeb3Client } from '@dequanto/clients/EvmWeb3Client';
+
+const client = new EvmWeb3Client({
+    platform: 'eth',
+    chainId: 1,
+    endpoints: [{ url: process.env.RPC_URL_ETH }]
+});
+```
+
+## Common Reads
+
+```ts
+const blockNumber = await client.getBlockNumber();
+const block = await client.getBlock('latest');
+const balance = await client.getBalance(address);
+const tx = await client.getTransaction(hash);
+const receipt = await client.getTransactionReceipt(hash);
+const code = await client.getCode(contractAddress);
+const chainId = await client.getChainId();
+```
+
+Storage:
+
+```ts
+const slot0 = await client.getStorageAt(contractAddress, 0);
+const slots = await client.getStorageAtBatched(contractAddress, [0, 1, 2]);
+```
+
+Raw contract call:
+
+```ts
+const result = await client.readContract({
+    address: tokenAddress,
+    abi,
+    method: 'balanceOf',
+    params: [owner]
+});
+```
+
+## Logs
+
+Use `getPastLogs(filter, options?)` for raw log queries. It handles block-range pagination and node range limits.
+
+```ts
+const logs = await client.getPastLogs({
+    address: tokenAddress,
+    fromBlock,
+    toBlock,
+    topics: [transferTopic]
+});
+```
+
+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?)`.
+
+## Avoid
+
+- Do not use raw `fetch`/HTTP for Ethereum JSON-RPC when `Web3Client` or `client.getRpc()` can do it.
+- Do not call `getWeb3()` on `Web3Client`; the base class throws and points to the compatibility layer.
+

package/docs/ai/references/safe-erc4337.md

@@ -0,0 +1,134 @@
+# Safe And ERC-4337
+
+Use dequanto account-agent flows for Gnosis Safe and ERC-4337 instead of wiring external SDK calls directly.
+
+Key source files:
+
+- `src/safe/GnosisSafeHandler.ts`
+- `src/safe/GnosisSafeFactory.ts`
+- `src/safe/GnosisSafeService.ts`
+- `src/safe/SafeTx.ts`
+- `src/safe/transport/InMemoryServiceTransport.ts`
+- `src/safe/transport/FileServiceTransport.ts`
+- `src/safe/transport/SafeServiceTransport.ts`
+- `src/erc4337/Erc4337Service.ts`
+- `src/erc4337/Erc4337TxWriter.ts`
+- `src/txs/agents/SafeAgent.ts`
+- `src/txs/agents/Erc4337Agent.ts`
+- `src/txs/agents/BatchAgent.ts`
+
+Useful tests:
+
+- `test/safe/safe.spec.ts`
+- `test/erc4337/erc4337.spec.ts`
+
+## Safe Account Transaction
+
+Use a `SafeAccount` with generated contract write methods:
+
+```ts
+const safeAccount = {
+    type: 'safe',
+    address: safeAddress,
+    operator: owner1,
+    owners: [owner1, owner2]
+} as const;
+
+const tx = await token.transfer(safeAccount, receiver, amount);
+await tx.wait();
+```
+
+Pass a Safe transport through writer config when needed:
+
+```ts
+const tx = await token
+    .$config(null, {
+        safeTransport: new InMemoryServiceTransport(client, owner1)
+    })
+    .transfer(safeAccount, receiver, amount);
+```
+
+## Manual Safe Flow
+
+```ts
+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()', [], {
+    builderConfig: {
+        send: 'manual',
+        gasEstimation: false
+    }
+});
+
+const safe = new GnosisSafeHandler({
+    safeAddress,
+    owners: [owner1],
+    client,
+    transport
+});
+
+const { safeTxHash } = await safe.createTransaction(txWriter, 0n);
+await safe.confirmTx(safeTxHash, owner2);
+const submitTx = await safe.submitTransaction(safeTxHash);
+await submitTx.wait();
+```
+
+## Safe Batch
+
+Use `SafeTx.executeBatch(...)` with generated `$data()` calls when manually composing a Safe batch:
+
+```ts
+const safeTx = new SafeTx(safeAccount, client, {
+    safeTransport,
+    contracts
+});
+
+const tx = await safeTx.executeBatch(
+    await token.$data().approve(safeAccount, spender, amount),
+    await token.$data().transfer(safeAccount, receiver, amount)
+);
+
+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.
+
+## Safe Decoding
+
+Use `GnosisSafeService.decodeSafeTx(data, { decodeContractCall: true })`. Register ABIs on the explorer when decoding local or unknown contracts.
+
+## ERC-4337
+
+Use `Erc4337TxWriter` for the higher-level flow:
+
+```ts
+const erc4337 = new Erc4337TxWriter(client, explorer, {
+    addresses: {
+        entryPoint,
+        accountFactory
+    }
+});
+
+const account = await erc4337.getAccount(owner);
+const txData = await token.$data().transfer(account, receiver, amount);
+
+const { writer } = await erc4337.submitUserOpViaEntryPointWithOwner({
+    tx: txData,
+    owner,
+    submitter
+});
+
+await writer.wait();
+```
+
+Use `Erc4337Service` for low-level operation creation, signing, decoding, and `handleOps` submission.
+
+## Avoid
+
+- Do not manually assemble Safe `execTransaction` signatures unless the task is explicitly low-level.
+- Do not bypass dequanto `TxWriter` account agents for Safe or ERC-4337 when generated contract writes can use account types.
+