dequanto 0.2.50 → 0.2.52

package/skills/dequanto/examples/live-events.spec.ts

@@ -0,0 +1,125 @@
+import { TEth } from 'dequanto/models/TEth';
+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 { $promise } from 'dequanto/utils/$promise';
+import { $require } from 'dequanto/utils/$require';
+
+const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
+const TRANSFER_AMOUNT = 1_000_000n; // 1 USDC (6 decimals).
+
+UTest({
+    $config: {
+        timeout: 60_000
+    },
+
+    async 'subscribe to contract events with a generated contract class' () {
+        const client = await Web3ClientFactory.getAsync('hh:memory:eth');
+        const usdc = new ERC20(USDC, client);
+
+        let eventFromTypedCallback = null;
+        let eventFromTypedStream = null;
+        let eventFromNamedCallback = null;
+
+        // Prefer the generated, event-specific method for typed callback arguments.
+        usdc.onTransfer(event => {
+            eventFromTypedCallback = event;
+        });
+
+        // The same method returns a stream when the callback is omitted.
+        const transferStream = usdc.onTransfer();
+        const listener = transferStream.subscribe(
+            event => {
+                eventFromTypedStream = event;
+            },
+            error => {
+                throw error;
+            }
+        );
+
+        // Subscribe by event name when the name is selected dynamically.
+        usdc.onLog('Transfer', event => {
+            eventFromNamedCallback = event;
+        });
+
+        const sender = $account.generate('sender');
+        const receiver = $account.generate('receiver');
+
+        // Test-only fork setup: fund the sender with native gas and USDC balance.
+        await client.debug.setBalance(sender.address, 10n ** 18n);
+        await $erc20.setBalanceAny(
+            client,
+            usdc.address,
+            sender.address,
+            TRANSFER_AMOUNT
+        );
+
+        try {
+            const writer = await usdc
+                .$receipt()
+                .transfer(sender, receiver.address, TRANSFER_AMOUNT);
+
+            for (const event of [
+                eventFromTypedCallback,
+                eventFromTypedStream,
+                eventFromNamedCallback
+            ]) {
+                const receivedEvent = $require.notNull(event);
+                $require.eq(receivedEvent.name, 'Transfer');
+                $require.eq(receivedEvent.event.address, usdc.address);
+                $require.eq(
+                    receivedEvent.event.transactionHash,
+                    writer.receipt.transactionHash
+                );
+            }
+        } finally {
+            listener.unsubscribe();
+        }
+    },
+
+    async 'subscribe to new block headers with Web3Client' () {
+        const client = Web3ClientFactory.get('hh:memory');
+        const previousBlockNumber = await client.getBlockNumber();
+        const subscription = await client.subscribe('newHeads');
+
+        try {
+            const nextBlock = $promise.timeout(
+                new Promise<TEth.Block>((resolve, reject) => {
+                    subscription.subscribe(resolve, reject, true);
+                }),
+                5_000,
+                'Waiting for the next block'
+            );
+            await client.debug.mine(1);
+
+            const block = await nextBlock;
+            $require.eq(block.number, previousBlockNumber + 1);
+        } finally {
+            await subscription.unsubscribe();
+        }
+    },
+
+    async 'subscribe to new block headers with the low-level Rpc client' () {
+        const client = Web3ClientFactory.get('hh:memory');
+        const previousBlockNumber = await client.getBlockNumber();
+        const rpc = await client.getRpc({ ws: true });
+        const subscription = await rpc.eth_subscribe('newHeads');
+
+        try {
+            const nextBlock = $promise.timeout(
+                new Promise<TEth.Block>((resolve, reject) => {
+                    subscription.subscribe(resolve, reject, true);
+                }),
+                5_000,
+                'Waiting for the next block'
+            );
+            await client.debug.mine(1);
+
+            const block = await nextBlock;
+            $require.eq(block.number, previousBlockNumber + 1);
+        } finally {
+            await subscription.unsubscribe();
+        }
+    }
+});

package/skills/dequanto/examples/revert-error.spec.ts

@@ -0,0 +1,82 @@
+import { HardhatProvider } from 'dequanto/hardhat/HardhatProvider';
+import { $account } from 'dequanto/utils/$account';
+import { $promise } from 'dequanto/utils/$promise';
+import { $require } from 'dequanto/utils/$require';
+
+// No manual pre-flight simulation is necessary: TxWriter and generated contract write methods
+// automatically estimate gas before submitting. Gas estimation simulates the transaction;
+// if it reverts, dequanto catches the revert, decodes any custom error bytecode using the ABI,
+// captures execution traces, and throws a standard JavaScript Error.
+// If gas estimation succeeds but the transaction reverts on-chain later, the error flow is identical.
+UTest({
+    async 'catch automatic revert and decode custom error without manual simulation' () {
+        const hh = new HardhatProvider();
+        const client = hh.client();
+        const deployer = hh.deployer(0);
+
+        const { contract } = await hh.deployCode(`
+            contract Vault {
+                error InsufficientBalance(uint256 available, uint256 requested);
+                uint256 public total;
+
+                function withdraw(uint256 amount) external {
+                    uint256 available = 50;
+                    if (amount > available) {
+                        revert InsufficientBalance(available, amount);
+                    }
+                    total += amount;
+                }
+            }
+        `, { client });
+
+        const user = $account.generate('user');
+        await client.debug.setBalance(user.address, 1e18);
+
+        // Calling $receipt() directly attempts execution; dequanto simulates via gas estimation.
+        // It throws a normal Error with decoded custom error details and method context.
+        const { error } = await $promise.caught(
+            contract.$receipt().withdraw(user, 100n)
+        );
+
+        $require.notNull(error, 'Expected transaction to throw on revert');
+        $require.has('InsufficientBalance', error.message);
+        $require.has('50', error.message);
+        $require.has('100', error.message);
+    },
+
+    async 'decode custom error when transaction reverts on-chain' () {
+        const hh = new HardhatProvider();
+        const client = hh.client();
+
+        const { contract } = await hh.deployCode(`
+            contract Counter {
+                error LimitReached(uint256 max);
+                uint256 public count;
+
+                function increment() external {
+                    if (count >= 1) {
+                        revert LimitReached(1);
+                    }
+                    count++;
+                }
+            }
+        `, { client });
+
+        const user = $account.generate('user');
+        await client.debug.setBalance(user.address, 1e18);
+
+        // First call succeeds and mines
+        await contract.$receipt().increment(user);
+
+        // Bypass pre-flight gas estimation so transaction is mined on-chain and reverts there
+        const writer = await contract
+            .$config({ gasEstimation: false, gasLimit: 100_000 })
+            .increment(user);
+
+        const { error } = await $promise.caught(writer.wait());
+
+        $require.notNull(error, 'Expected on-chain revert to throw');
+        $require.has('LimitReached', error.message);
+        $require.has('1', error.message);
+    }
+});

package/{docs/ai → skills/dequanto}/examples/rpc-read.spec.ts

@@ -1,9 +1,11 @@
-import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
-import { Config } from '@dequanto/config/Config';
-import { $require } from '@dequanto/utils/$require';
+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' () {
+    async 'read common RPC data via Web3Client directly' () {
         const cfg = await Config.fetch();
 
         const client = await Web3ClientFactory.getAsync('eth');
@@ -38,5 +40,20 @@ UTest({
             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,9 +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 { $require } from '@dequanto/utils/$require';
-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' () {

package/{docs/ai → skills/dequanto}/examples/send-transaction.spec.ts

@@ -1,10 +1,10 @@
-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';
+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' () {

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/{docs/ai → skills/dequanto}/examples/token-transfer.spec.ts

@@ -1,8 +1,8 @@
-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';
+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;

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/skills/dequanto/references/browser.md

@@ -0,0 +1,43 @@
+# Browser and dApp Integration
+
+Dequanto works in browser applications (Vite, Webpack, Next.js, vanilla web). In the browser, transactions and signatures are delegated to connected Web3 wallets (MetaMask, Rabby, Coinbase Wallet, etc.) via EIP-6963 and EIP-1193.
+
+Key source files:
+
+- `src/clients/WalletClient.ts`
+- `src/wallets/EIP6963ProviderFactory.ts`
+- `src/clients/Web3Client.ts`
+- `src/txs/TxWriter.ts`
+
+Runnable example: [browser wallet connection and transfer](../examples/browser-wallet.spec.ts).
+
+## Accessing the Wallet
+
+```ts
+import { Web3ClientFactory } from 'dequanto/clients/Web3ClientFactory';
+
+const client = await Web3ClientFactory.getAsync('eth');
+
+// 1. Discover available injected wallets (EIP-6963)
+const providers = await client.wallet.getProviders();
+
+// 2. Connect (prompts user wallet)
+const [account] = await client.wallet.connect();
+
+// 3. Listen to wallet events
+client.wallet.factory.on('onAccountsChanged', (detail, accounts) => {
+    console.log('Account switched:', accounts[0]);
+});
+client.wallet.factory.on('onChainChanged', (detail, chainId) => {
+    console.log('Network switched:', chainId);
+});
+```
+
+## Sending Transactions from Browser
+
+Pass the user's address as an EOA account with no `key`. Because `client.wallet.isConnected(account.address)` is true, `TxWriter` delegates signing and submission to the browser wallet:
+
+```ts
+const tx = await token.$receipt().transfer({ address: account }, recipient, 100n);
+console.log('Mined tx:', tx.receipt.transactionHash);
+```

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>(
@@ -89,6 +89,14 @@ const tx = await token
     .transfer(sender, receiver, amount);
 ```
 
+### Automatic Simulation And Error Handling
+
+Do not perform manual pre-flight simulations before submitting. When calling write methods such as `contract.$receipt().method(sender, ...args)`:
+- Dequanto automatically estimates gas, which simulates the transaction on the node.
+- If it reverts, dequanto decodes custom error bytecode using the contract ABI, attaches call traces, and throws a standard JavaScript `Error`.
+- If gas estimation succeeds but the transaction reverts on-chain later, the error flow is identical: `wait()` throws a standard `Error` with decoded custom error details.
+- Catch reverts with normal JavaScript `try / catch`.
+
 ## Events
 
 For generated contracts, prefer generated log helpers when present. Otherwise use:

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',
@@ -93,5 +93,5 @@ contract.$onLog('Transfer', log => {
 });
 ```
 
-For raw client subscriptions, use `client.subscribe(...)`.
+For new logs after a live connection is established, see [WebSocket and live logs](live-events.md).
 

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';
@@ -71,7 +71,7 @@ By default, `0xweb install` saves the downloaded Solidity sources next to the ge
 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');
@@ -92,6 +92,70 @@ const decimals = await usdc.decimals();
 
 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`.
 
+## Project Workflow And Version Control
+
+`0xweb install` is the primary contract-class generation workflow for project codebases. The `0xc/` folder it produces should be committed to version control, not gitignored. Committing the generated classes enables:
+
+- Tracking which implementation is installed behind a proxy (each upgrade lands as a diff).
+- Using installed contracts without re-downloading from an explorer on every clone.
+- Keeping application code pinned to a known interface even when the explorer ABI changes.
+
+**Recommended `.gitignore` approach:**
+
+```gitignore
+# Commit all installed contract classes
+# 0xc/
+
+# Only ignore Hardhat-compiled local contract classes (regenerated by "npx hardhat compile")
+0xc/hardhat/
+```
+
+Gitignoring `0xc/hardhat/` is safe only when the project uses the `@0xweb/hardhat` plugin, because those classes are regenerated automatically by the Hardhat compile step.
+
+**Restoring installed contracts on a fresh clone:**
+
+`0xweb install` records each installed contract in `0xweb.json` at the project root. When cloning a project that already has `0xweb.json`, run:
+
+```bash
+0xweb restore
+```
+
+This re-downloads and regenerates every contract that was previously installed, so the `0xc/` folder matches what was recorded without manual re-installation of each contract.
+
+**Global configuration (`0xweb config -e`):**
+
+`0xweb config -e` opens the global dequanto configuration file in the system editor. Use it to add or update:
+
+- RPC endpoints for any chain
+- Blockchain explorer API keys (Etherscan, Polygonscan, etc.)
+- Custom chain definitions
+
+dequanto loads configuration from multiple sources in order: the default global config, the default local project config, any paths the developer provides explicitly, and inline config objects passed in code. The global config persists across projects on the same machine, so a developer who sets up RPCs and API keys once via `0xweb config -e` makes those available to every project without repeating the setup.
+
+**Account management (`0xweb accounts add / new`):**
+
+```bash
+0xweb accounts add   # import an existing account by name and private key
+0xweb accounts new   # generate a new account
+```
+
+Accounts added this way are stored in an encrypted global store protected by a combination of local machine keys and a user-supplied PIN. Because the store is global, a named account configured once (for example `deployer`) is available in every project on that machine. Application code can reference the account by name through the dequanto config without embedding private keys in the repository.
+
+**Ad-hoc network queries:**
+
+The following commands are useful for interactive investigation and one-off queries, but are not part of the project's TypeScript codebase integration:
+
+```bash
+0xweb contract read  <address> <method> --chain <chain>
+0xweb contract write <address> <method> --chain <chain>
+0xweb contract calldata <address> <method>
+0xweb contract dump   <address> --chain <chain>
+0xweb contract slot   <address> <slot>  --chain <chain>
+0xweb token   price   <address>         --chain <chain>
+```
+
+These commands operate directly on the network and do not generate any files consumed by project source code. Do not suggest them as a substitute for generated contract classes inside application code.
+
 ## 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.
@@ -121,7 +185,7 @@ Use `Generator` directly only for custom generation tasks, test fixtures, non-Ha
 ### Generate From Compiled Artifact
 
 ```ts
-import { Generator } from '@dequanto/gen/Generator';
+import { Generator } from 'dequanto/gen/Generator';
 
 const gen = new Generator({
     name: 'AnyERC20',
@@ -180,7 +244,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({
@@ -202,4 +266,4 @@ Generated classes can include `$meta`:
 - `source`
 - `name`
 
-Agents should inspect generated files before assuming method names, constructor helpers, event helper names, or storage reader fields.
+Agents should inspect generated files before assuming method names, constructor helpers, event helper names, or storage reader fields.