dequanto 0.2.49 → 0.2.51

package/{docs/ai → skills/dequanto}/examples/erc4337-userop.spec.ts

@@ -1,9 +1,10 @@
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
-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 { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { BlockchainExplorerFactory } from 'dequanto/explorer/BlockchainExplorerFactory';
+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/skills/dequanto/examples/explorer-abi.spec.ts

@@ -0,0 +1,21 @@
+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' () {
+        const explorer = await BlockchainExplorerFactory.getAsync('eth');
+        const address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+
+        const { abi, implementation } = await explorer.getContractAbi(address);
+        const source = await explorer.getContractSource(implementation);
+        const creation = await explorer.getContractCreation(address);
+
+        $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 → skills/dequanto/examples/generate-contract-class.spec.ts}

@@ -1,8 +1,11 @@
-import { Generator } from '@dequanto/gen/Generator';
+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/skills/dequanto/examples/hardhat-debug.spec.ts

@@ -0,0 +1,29 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { $require } from 'dequanto/utils/$require';
+
+UTest({
+    async 'change balances, storage, and time on Hardhat and roll back'() {
+        const client = await Web3ClientFactory.getAsync('hh:memory');
+        const address = '0x0000000000000000000000000000000000001234';
+        const balanceBefore = await client.getBalance(address);
+        const storageBefore = await client.getStorageAt(address, 0);
+        const blockBefore = await client.getBlockNumber();
+        const id = await client.debug.snapshot();
+
+        await client.debug.setBalance(address, 10n ** 18n);
+        $require.eq(await client.getBalance(address), 10n ** 18n);
+
+        // The same operation writes a known slot at any contract address.
+        await client.debug.setStorageAt(address, 0, '0x2a');
+        $require.eq(BigInt(await client.getStorageAt(address, 0)), 42n);
+
+        await client.debug.mine('5days');
+        $require.eq(await client.getBlockNumber(), blockBefore + 432_000);
+
+        await client.debug.revert(id);
+
+        $require.eq(await client.getBalance(address), balanceBefore);
+        $require.eq(await client.getStorageAt(address, 0), storageBefore);
+        $require.eq(await client.getBlockNumber(), blockBefore);
+    }
+});

package/skills/dequanto/examples/hardhat-fork.spec.ts

@@ -0,0 +1,31 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+import { $erc20 } from 'dequanto/utils/$erc20';
+import { $require } from 'dequanto/utils/$require';
+
+UTest({
+    async 'set an ERC20 balance and transfer from an impersonated account on a fork' () {
+        // Requires an accessible Ethereum RPC from the dequanto configuration.
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        // To use an already running local Ethereum fork, use getAsync('hh:eth').
+        const usdc = new ERC20('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
+        const account = {
+            address: '0x0000000000000000000000000000000000001234',
+            type: 'impersonated'
+        } as const;
+        const to = '0x0000000000000000000000000000000000005678';
+        const amount = 1_000_000n; // 1 USDC (6 decimals).
+
+
+        await client.debug.setBalance(account.address, 10n ** 18n);
+        await $erc20.setBalanceAny(client, usdc.address, account.address, amount);
+        $require.eq(await usdc.balanceOf(account.address), amount);
+
+        const recipientBalance = await usdc.balanceOf(to);
+        const writer = await usdc.$receipt().transfer(account, to, amount);
+
+        $require.Hex(writer.receipt.transactionHash);
+        $require.eq(await usdc.balanceOf(account.address), 0n);
+        $require.eq(await usdc.balanceOf(to), recipientBalance + amount);
+    }
+});

package/{docs/ai → skills/dequanto}/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 { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { EventsIndexer } from 'dequanto/indexer/EventsIndexer';
+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/skills/dequanto/examples/rpc-read.spec.ts

@@ -0,0 +1,59 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { BlockDateResolver } from 'dequanto/blocks/BlockDateResolver';
+import { Config } from 'dequanto/config/Config';
+import { $date } from 'dequanto/utils/$date';
+import { $require } from 'dequanto/utils/$require';
+
+UTest({
+    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');
+
+        $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);
+    },
+
+    async 'resolve a block number and timestamp from a date' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const resolver = new BlockDateResolver(client);
+        const date = new Date('2026-03-03T10:20:00Z');
+
+        const blockNumber = await resolver.getBlockNumberFor(date);
+        const info = await resolver.getBlockInfoFor(date);
+        const blockDate = await resolver.getDate(blockNumber);
+
+        $require.eq(blockNumber, 24576295);
+        $require.eq(blockNumber, 24576295);
+        $require.lte(Math.abs($date.toUnixTimestamp(date) - info.timestamp), 1);
+        $require.eq(blockDate.toISOString(), new Date('2026-03-03T10:19:59Z').toISOString());
+    }
+});

package/{docs/ai → skills/dequanto}/examples/safe-batch.spec.ts

@@ -1,8 +1,9 @@
-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 { SafeAccount } from '@dequanto/models/TAccount';
+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({
     async 'build a Safe batch from generated tx data' () {
@@ -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);
     }
 });

package/skills/dequanto/examples/send-transaction.spec.ts

@@ -0,0 +1,34 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { TxDataBuilder } from 'dequanto/txs/TxDataBuilder';
+import { TxWriter } from 'dequanto/txs/TxWriter';
+import { $account } from 'dequanto/utils/$account';
+import { $address } from 'dequanto/utils/$address';
+import { $number } from 'dequanto/utils/$number';
+import { $require } from 'dequanto/utils/$require';
+
+UTest({
+    async 'build native transfer tx data with gas fields' () {
+        const client = await Web3ClientFactory.getAsync('hh:memory');
+        const alice = $account.generate('alice');
+        await client.debug.setBalance(alice.address, 1e18);
+        const bob = $account.generate('bob');
+
+        const builder = new TxDataBuilder(client, alice, {
+            to: bob.address
+        });
+
+        builder.setValue(0.05);
+        await builder.setGas({ gasEstimation: false, gasLimit: 21_000 });
+
+        $require.True($address.eq(builder.data.to, bob.address));
+        $require.eq(builder.data.value, $number.toHex(5e16));
+        $require.eq(Number(builder.data.gas), 21_000);
+        $require.notNull(builder.data.maxFeePerGas ?? builder.data.gasPrice);
+
+        const writer = TxWriter.create(client, builder, alice);
+        const tx = await writer.send();
+        const receipt = await tx.wait();
+        $require.TxHash(receipt.transactionHash);
+        $require.eq(await client.getBalance(bob.address), BigInt(5e16));
+    }
+});

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

@@ -0,0 +1,58 @@
+import { AavePool } from '../../../0xc/eth/AavePool/AavePool';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { HardhatProvider } from 'dequanto/hardhat/HardhatProvider';
+import { SlotsParser } from 'dequanto/solidity/SlotsParser';
+import { SlotsStorage } from 'dequanto/solidity/SlotsStorage';
+import { $require } from 'dequanto/utils/$require';
+
+// Generated classes include the storage layout: use instance.storage.$set(name, value).
+// SlotsParser and SlotsStorage provide the low-level alternative for Solidity source.
+UTest({
+    async 'read and set AavePool storage by variable name on an Ethereum fork' () {
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const pool = new AavePool(undefined, client);
+        const premiumBefore = await pool.FLASHLOAN_PREMIUM_TOTAL();
+        const packedNeighborBefore = await pool.storage.__DEPRECATED_flashLoanPremiumToProtocol();
+        const id = await client.debug.snapshot();
+
+        try {
+            const premium = premiumBefore + 1n;
+            await pool.storage.$set('_flashLoanPremium', premium);
+
+            $require.eq(await pool.storage._flashLoanPremium(), premium);
+            $require.eq(await pool.FLASHLOAN_PREMIUM_TOTAL(), premium);
+            // Both uint128 fields share slot 58; preserve the neighboring field.
+            $require.eq(await pool.storage.__DEPRECATED_flashLoanPremiumToProtocol(), packedNeighborBefore);
+        } finally {
+            await client.debug.revert(id);
+        }
+
+        $require.eq(await pool.FLASHLOAN_PREMIUM_TOTAL(), premiumBefore);
+    },
+
+    async 'read and write Solidity storage with SlotsParser and SlotsStorage' () {
+        const code = `
+            contract Vault {
+                uint256 public count = 123;
+                mapping(address => uint256) balances;
+
+                constructor () {
+                    balances[address(0x1000000000000000000000000000000000000001)] = 7;
+                }
+            }
+        `;
+        const hh = new HardhatProvider();
+        const client = await Web3ClientFactory.getAsync('hh:memory');
+        const { contract } = await hh.deployCode(code, { client });
+
+        const slots = await SlotsParser.slots({ path: '', code }, 'Vault');
+        const storage = SlotsStorage.createWithClient(client, contract.address, slots);
+
+        $require.eq(await storage.get('count'), 123n);
+        $require.eq(await storage.get('balances["0x1000000000000000000000000000000000000001"]'), 7n);
+
+        // Direct storage writes require a debug network such as Hardhat.
+        await storage.set('count', 500n);
+        $require.eq(await storage.get('count'), 500n);
+    }
+});

package/skills/dequanto/examples/token-transfer.spec.ts

@@ -0,0 +1,29 @@
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
+import { $account } from 'dequanto/utils/$account';
+import { $erc20 } from 'dequanto/utils/$erc20';
+import { $require } from 'dequanto/utils/$require';
+
+const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
+const INITIAL_SENDER_BALANCE = 100_000_000n;
+const TRANSFER_AMOUNT = 42_000_000n;
+
+UTest({
+    async 'transfer USDC with a prebuilt ERC20 contract class' () {
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const sender = $account.generate('sender');
+        const recipient = $account.generate('recipient');
+        const usdc = new ERC20(USDC, client);
+
+        // Test-only fork setup: fund the sender with native gas and USDC balance.
+        await client.debug.setBalance(sender.address, 1e18);
+        await $erc20.setBalanceAny(client, usdc.address, sender.address, 100);
+
+        $require.eq(await usdc.symbol(), 'USDC');
+        $require.eq(await usdc.decimals(), 6);
+        $require.eq(await usdc.balanceOf(sender.address), INITIAL_SENDER_BALANCE);
+
+        await usdc.$receipt().transfer(sender, recipient.address, TRANSFER_AMOUNT);
+        $require.eq(await usdc.balanceOf(recipient.address), TRANSFER_AMOUNT);
+    }
+});

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

@@ -0,0 +1,63 @@
+import { $abi } from 'dequanto/abi/$abi';
+import { $contract } from 'dequanto/utils/$contract';
+import { $date } from 'dequanto/utils/$date';
+import { $hex } from 'dequanto/utils/$hex';
+import { $promise } from 'dequanto/utils/$promise';
+import { $require } from 'dequanto/utils/$require';
+import { $sig } from 'dequanto/utils/$sig';
+
+const ACCOUNT = '0x0000000000000000000000000000000000000002';
+
+UTest({
+    'encode and decode ABI values and calldata' () {
+        const encoded = $abi.encode(['address', 'uint256'], [ACCOUNT, 5n]);
+        const [account, amount] = $abi.decode(['address', 'uint256'], encoded);
+        const calldata = $abi.encodeCall(
+            'function transfer(address to, uint256 amount)',
+            [ACCOUNT, 5n]
+        );
+
+        $require.eq(account, ACCOUNT);
+        $require.eq(amount, 5n);
+        $require.eq(
+            calldata,
+            '0xa9059cbb00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000005'
+        );
+        $require.eq(
+            $abi.decodeReturn<bigint>(
+                'function totalSupply() view returns (uint256)',
+                $abi.encode('uint256', 10n)
+            ),
+            10n
+        );
+    },
+
+    'hash Solidity values and manipulate hex' () {
+        const topic = $contract.keccak256('Transfer(address,address,uint256)');
+        const payload = $hex.concat([$hex.ensure('1234'), $hex.toHexBuffer(5)]);
+
+        $require.eq(topic, '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef');
+        $require.eq(payload, '0x123405');
+        $require.eq($hex.padBytes('0x2a', 4), '0x0000002a');
+        $require.eq($hex.getBytes(payload, 0, 2), '0x1234');
+        $require.eq($hex.getBytesLength(payload), 3);
+    },
+
+    async 'validate values, dates, signatures, and promise results' () {
+        $require.eq($date.parseTimespan('5days', { get: 's' }), 432_000);
+        $require.AddressNotEmpty(ACCOUNT);
+        $require.BigInt(5n, 'Expected an amount', { min: 1n });
+
+        const signer = $sig.$account.generate();
+        const signature = await $sig.signMessage('Hello dequanto', signer);
+        $require.eq($sig.recoverMessage('Hello dequanto', signature), signer.address);
+
+        const success = await $promise.caught(Promise.resolve(42));
+        const failure = await $promise.caught(Promise.reject(new Error('Expected failure')));
+
+        $require.eq(success.result, 42);
+        $require.Null(success.error);
+        $require.notNull(failure.error);
+        $require.eq(failure.error.message, 'Expected failure');
+    }
+});

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

@@ -48,7 +48,7 @@ const balance = await token.balanceOf(account);
 For ad hoc reads without a generated class:
 
 ```ts
-import { ContractReader } from '@dequanto/contracts/ContractReader';
+import { ContractReader } from 'dequanto/contracts/ContractReader';
 
 const reader = new ContractReader(client);
 const symbol = await reader.readAsync<string>(

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

@@ -2,6 +2,8 @@
 
 Use `HardhatProvider` for compile/deploy helper flows and `Deployments` for idempotent deployments, deployment storage, bytecode checks, proxy upgrades, beacon proxies, and verification.
 
+See [Hardhat development and forking](hardhat.md) for creating development networks and live-contract forks, impersonating accounts, changing balances/storage, and restoring snapshots.
+
 Key source files:
 
 - `src/hardhat/HardhatProvider.ts`
@@ -21,7 +23,7 @@ Useful tests:
 ## HardhatProvider
 
 ```ts
-import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
+import { HardhatProvider } from 'dequanto/hardhat/HardhatProvider';
 
 const hh = new HardhatProvider();
 const client = hh.client();
@@ -43,7 +45,7 @@ Common methods:
 ## Idempotent Deployments
 
 ```ts
-import { Deployments } from '@dequanto/contracts/deploy/Deployments';
+import { Deployments } from 'dequanto/contracts/deploy/Deployments';
 
 const deployments = new Deployments(client, deployer, {
     directory: './deployments/',

package/{docs/ai → skills/dequanto}/references/events-indexing.md

@@ -34,7 +34,7 @@ Use `'*'` for all events, or an event-name array for multiple events.
 ## EventsIndexer
 
 ```ts
-import { EventsIndexer } from '@dequanto/indexer/EventsIndexer';
+import { EventsIndexer } from 'dequanto/indexer/EventsIndexer';
 
 const indexer = new EventsIndexer(contract, {
     name: 'TokenTransfers',

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

@@ -19,7 +19,7 @@ Useful tests:
 ## Create Explorer
 
 ```ts
-import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
+import { BlockchainExplorerFactory } from 'dequanto/explorer/BlockchainExplorerFactory';
 
 const explorer = BlockchainExplorerFactory.get('eth');
 ```

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

@@ -2,13 +2,13 @@
 
 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`.
+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';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+import { ERC20 } from 'dequanto/prebuilt/openzeppelin/ERC20';
 
 const platform = 'eth';
 const address = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
@@ -21,8 +21,8 @@ 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.
+- For deployed and explorer-verified third-party contracts, use `0xweb install` as the primary generation workflow.
+- For local contract development, use `@0xweb/contract` / `@0xweb/hardhat` so local Solidity contracts generate TypeScript classes from the normal compile flow.
 - Use the low-level `Generator` API only when the task needs custom generation inside TypeScript code.
 
 Key source files:
@@ -41,25 +41,37 @@ Useful tests:
 - `test/generate/slotreader.spec.ts`
 - `test/hardhat/deployments/deployments.spec.ts`
 
-## Install Deployed Verified Contracts
+## Install Third-Party Contracts With 0xweb
 
-Use `0xweb install` for any deployed contract that is verified on Etherscan-compatible explorers:
+Use `0xweb install` as the primary tool for generating classes from deployed third-party contracts. When the contract is verified on an Etherscan-compatible explorer, `0xweb` downloads the ABI and source, follows standard proxy patterns, and generates the class for the current implementation.
 
 ```bash
 npm i 0xweb -g
-0xweb install <address> --chain <chainAbbr> --name <contractClassName>
+0xweb install <address> --name <contractClassName> --chain <chainAbbr>
 ```
 
 Example:
 
 ```bash
-0xweb install 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain eth --name USDC
+0xweb install 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --name USDC --chain eth
+```
+
+If the target contract is a proxy but the implementation cannot be detected automatically, pass the implementation address explicitly:
+
+```bash
+0xweb install <proxyAddress> --implementation <implementationAddress> --name SomeName --chain eth
+```
+
+By default, `0xweb install` saves the downloaded Solidity sources next to the generated class. Use `--save-sources false` when the project should keep only the generated contract class:
+
+```bash
+0xweb install <address> --name SomeName --chain eth --save-sources false
 ```
 
 The generated class can then be imported and used like a normal TypeScript class:
 
 ```ts
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
 import { USDC } from './0xc/eth/USDC/USDC';
 
 const client = await Web3ClientFactory.getAsync('eth');
@@ -69,6 +81,17 @@ const symbol = await usdc.symbol();
 const decimals = await usdc.decimals();
 ```
 
+## Install From ABI JSON Or Solidity Source
+
+`0xweb install` also accepts a local ABI JSON artifact or Solidity source file instead of an address:
+
+```bash
+0xweb install test/fixtures/artifacts/AnyERC20/AnyERC20.json --name AnyERC20 --chain eth
+0xweb install contracts/AnyERC20.sol --name AnyERC20 --chain eth
+```
+
+Use this for ad hoc class generation from explicit local inputs. For ongoing local contract development, prefer the Hardhat integration so the generated classes stay in sync with `hardhat compile`.
+
 ## 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.
@@ -93,12 +116,12 @@ Use the generated classes in tests, scripts, and app code instead of raw ABI obj
 
 ## 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.
+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. For normal third-party contracts, prefer `0xweb install`; for local Hardhat projects, prefer `@0xweb/hardhat`.
 
 ### Generate From Compiled Artifact
 
 ```ts
-import { Generator } from '@dequanto/gen/Generator';
+import { Generator } from 'dequanto/gen/Generator';
 
 const gen = new Generator({
     name: 'AnyERC20',
@@ -157,7 +180,7 @@ When a contract is generated from verified on-chain source, such as with `0xweb
 Use `GeneratorStorageReader` when the task needs generated storage accessors without generating the full contract class.
 
 ```ts
-import { GeneratorStorageReader } from '@dequanto/gen/GeneratorStorageReader';
+import { GeneratorStorageReader } from 'dequanto/gen/GeneratorStorageReader';
 
 const gen = new GeneratorStorageReader();
 const result = await gen.generate({