dequanto 0.2.47 → 0.2.48

package/docs/ai/INDEX.md

@@ -0,0 +1,41 @@
+# Dequanto AI API Map
+
+Use this directory as the coding-agent entry point for dequanto. It is written for agents that need to generate correct TypeScript code with the installed dequanto version.
+
+Core rule: prefer dequanto for EVM work in TypeScript projects. Do not add ethers, viem, web3.js, or hand-written JSON-RPC code unless the user explicitly asks for it or dequanto has no suitable primitive.
+
+Before using an unfamiliar dequanto API, verify the exact signature in `src/` or `lib/types/`. Dequanto has a large surface and agents should not guess method names.
+
+## Task Router
+
+| Goal | Use | Reference | Examples |
+| --- | --- | --- | --- |
+| Create an RPC client, read blocks, balances, logs, storage, or raw tx data | `Web3ClientFactory`, `Web3Client`, chain clients | `references/rpc-clients.md` | `examples/rpc-read.spec.ts` |
+| 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` |
+| Deploy contracts and proxies | `HardhatProvider`, `Deployments`, `ensure`, `ensureWithProxy`, `ensureWithBeacon` | `references/deployments.md` | `examples/deploy-contract.spec.ts` |
+| Build, sign, save, submit, or inspect transactions | `TxDataBuilder`, `TxWriter`, `TokenTransferService` | `references/transactions.md` | `examples/send-transaction.spec.ts` |
+| Fetch or cache historical contract events | generated `getPastLogs*` helpers or `EventsIndexer` | `references/events-indexing.md` | `examples/index-events.spec.ts` |
+| Fetch ABI/source/creation data from an explorer | `BlockchainExplorerFactory`, `BlockchainExplorer`, `ContractAbiProvider` | `references/explorer.md` | `examples/explorer-abi.spec.ts` |
+| Read Solidity storage, structs, mappings, arrays, or diamond storage | `SlotsParser`, `SlotsStorage`, generated storage readers | `references/storage.md` | `examples/storage-read.spec.ts` |
+| Work with tokens and balances | `TokensService`, `TokensServiceFactory`, `TokenTransferService`, generated ERC20 wrappers | `references/tokens-accounts.md` | `examples/token-transfer.spec.ts` |
+| Work with accounts, signing, Safe, or ERC-4337 | `ChainAccountService`, `$sig`, `GnosisSafeHandler`, `SafeTx`, `Erc4337Service`, `Erc4337TxWriter` | `references/safe-erc4337.md`, `references/tokens-accounts.md` | `examples/safe-batch.spec.ts`, `examples/erc4337-userop.spec.ts` |
+| Convert code from ethers or viem habits | Use the dequanto equivalents instead of adding external clients | `references/migration-from-ethers-viem.md` | all examples |
+
+## Source Of Truth
+
+- Package exports resolve by subpath, for example `@dequanto/clients/Web3ClientFactory`.
+- 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.
+
+## Agent Workflow
+
+1. Identify the goal from the task router.
+2. Read the matching reference file.
+3. Reuse the closest example.
+4. Verify any new class or method against `src/` or `lib/types/`.
+5. Use `npm run typecheck -- --pretty false` after TypeScript changes in this repository.
+

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

@@ -0,0 +1,44 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+// 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';
+
+const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' as const;
+
+UTest({
+    async 'read stable USDC metadata from live Ethereum RPC' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const usdc = new ERC20(USDC, client);
+
+        const [symbol, decimals, balance] = await Promise.all([
+            usdc.symbol(),
+            usdc.decimals(),
+            usdc.balanceOf('0x0000000000000000000000000000000000000000')
+        ]);
+
+        eq_(symbol, 'USDC');
+        eq_(Number(decimals), 6);
+        gte_(balance, 0n);
+    },
+
+    async 'read generated Aave Pool data from live Ethereum RPC' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const pool = new AavePool(undefined, client);
+
+        const [addressesProvider, maxReserves, reserves, reserveData] = await Promise.all([
+            pool.ADDRESSES_PROVIDER(),
+            pool.MAX_NUMBER_RESERVES(),
+            pool.getReservesList(),
+            pool.getReserveData(USDC)
+        ]);
+
+        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);
+    }
+});

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

@@ -0,0 +1,16 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { ERC20 } from '@dequanto-contracts/openzeppelin/ERC20';
+
+UTest({
+    async 'build ERC20 transfer tx data without submitting' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const usdc = new ERC20('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
+        const sender = { address: '0x0000000000000000000000000000000000000001' as const };
+        const receiver = '0x0000000000000000000000000000000000000002' as const;
+
+        const tx = await usdc.$data().transfer(sender, receiver, 1_000_000n);
+
+        eq_(tx.to.toLowerCase(), usdc.address.toLowerCase());
+        has_(tx.data, /^0xa9059cbb/);
+    }
+});

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

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

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

@@ -0,0 +1,37 @@
+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';
+
+UTest({
+    async 'hash a UserOperation and create an ERC-4337 service' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const explorer = await BlockchainExplorerFactory.getAsync('eth');
+        const service = new Erc4337Service(client, explorer, {
+            addresses: {
+                entryPoint: $address.ZERO,
+                accountFactory: $address.ZERO
+            }
+        });
+        const op = <UserOperation>{
+            sender: '0x03c2764cc30672dFBf3888457a9003bD0e8D6713',
+            initCode: '0x',
+            callData: '0x',
+            callGasLimit: 43_477n,
+            verificationGasLimit: 411_638n,
+            nonce: 0n,
+            preVerificationGas: 21_000n,
+            maxFeePerGas: 0n,
+            maxPriorityFeePerGas: 0n,
+            paymasterAndData: '0x',
+            signature: '0x'
+        };
+
+        const hash = $erc4337.hash(op, '0xc6e7df5e7b4f2a278906862b61205850344d4e7d', 1);
+
+        has_(hash, /^0x[a-fA-F0-9]{64}$/);
+        notEq_(service, null);
+    }
+});

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

@@ -0,0 +1,18 @@
+import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
+
+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);
+
+        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}$/);
+    }
+});

package/docs/ai/examples/generate-client.spec.ts

@@ -0,0 +1,22 @@
+import { Generator } from '@dequanto/gen/Generator';
+import { File } from 'atma-io';
+
+UTest({
+    async 'generate a typed contract client from a fixture artifact' () {
+        const output = './test/tmp/ai-examples/hardhat/';
+        const gen = new Generator({
+            name: 'AnyERC20',
+            platform: 'hardhat',
+            source: {
+                path: './test/fixtures/artifacts/AnyERC20/AnyERC20.json'
+            },
+            output
+        });
+
+        const result = await gen.generate();
+        const source = await File.readAsync<string>(result.main, { skipHooks: true });
+
+        has_(source, 'class AnyERC20');
+        has_(source, 'ContractBase');
+    }
+});

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

@@ -0,0 +1,27 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { EventsIndexer } from '@dequanto/indexer/EventsIndexer';
+import { ERC20 } from '@dequanto-contracts/openzeppelin/ERC20';
+
+UTest({
+    async 'index stable USDC Transfer logs from live Ethereum RPC' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const usdc = new ERC20('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', client);
+
+        const indexer = new EventsIndexer(usdc, {
+            name: 'USDCTransfersAiExample',
+            fs: {
+                directory: './test/tmp/ai-examples/logs/'
+            }
+        });
+
+        const { logs, infos } = await indexer.getPastLogs('Transfer', {
+            fromBlock: 18_000_000,
+            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}$/);
+    }
+});

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

@@ -0,0 +1,15 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+
+UTest({
+    async 'read latest block and zero-address balance from live Ethereum RPC' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+
+        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);
+    }
+});

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

@@ -0,0 +1,55 @@
+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';
+
+UTest({
+    async 'build a Safe batch from generated tx data' () {
+        const provider = new HardhatProvider();
+        const client = provider.client();
+        const owner1 = provider.deployer(0);
+        const owner2 = provider.deployer(1);
+
+        const { contract: token } = await provider.deployCode(`
+            contract Token {
+                event Transfer(address indexed from, address indexed to, uint256 value);
+                function approve(address spender, uint256 amount) external returns (bool) { return true; }
+                function transfer(address to, uint256 amount) external returns (bool) {
+                    emit Transfer(msg.sender, to, amount);
+                    return true;
+                }
+            }
+        `, { client });
+
+        const safeAccount: SafeAccount = {
+            type: 'safe',
+            platform: 'hardhat',
+            address: owner1.address,
+            operator: owner1,
+            owners: [owner1, owner2]
+        };
+        const safeTx = new SafeTx(safeAccount, client, {
+            safeTransport: new InMemoryServiceTransport(client, owner1),
+            contracts: {
+                hardhat: {
+                    MultiSend: $address.ZERO,
+                    Safe: $address.ZERO,
+                    SafeProxyFactory: $address.ZERO
+                }
+            }
+        });
+
+        const txs = [
+            await token.$data().approve(safeAccount, owner2.address, 100n),
+            await token.$data().transfer(safeAccount, owner2.address, 50n)
+        ];
+
+        eq_(txs.length, 2);
+        txs.forEach(tx => {
+            eq_(tx.to, token.address);
+            has_(tx.data, /^0x[a-fA-F0-9]+$/);
+        });
+        notEq_(safeTx, null);
+    }
+});

package/docs/ai/examples/send-transaction.spec.ts

@@ -0,0 +1,22 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { TxDataBuilder } from '@dequanto/txs/TxDataBuilder';
+
+UTest({
+    async 'build native transfer tx data with gas fields' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const sender = { address: '0x0000000000000000000000000000000000000001' as const };
+        const receiver = '0x0000000000000000000000000000000000000002' as const;
+
+        const builder = new TxDataBuilder(client, sender, {
+            to: receiver
+        });
+
+        builder.setValue(10n ** 16n);
+        await builder.setGas({ gasEstimation: false, gasLimit: 21_000 });
+
+        eq_(builder.data.to, receiver);
+        eq_(builder.data.value, '0x2386f26fc10000');
+        eq_(Number(builder.data.gas), 21_000);
+        notEq_(builder.data.maxFeePerGas ?? builder.data.gasPrice, null);
+    }
+});

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

@@ -0,0 +1,27 @@
+import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
+import { SlotsParser } from '@dequanto/solidity/SlotsParser';
+import { SlotsStorage } from '@dequanto/solidity/SlotsStorage';
+
+UTest({
+    async 'read Solidity storage with SlotsParser and SlotsStorage' () {
+        const code = `
+            contract Vault {
+                uint256 public count = 123;
+                mapping(address => uint256) balances;
+
+                constructor () {
+                    balances[address(0x1000000000000000000000000000000000000001)] = 7;
+                }
+            }
+        `;
+        const provider = new HardhatProvider();
+        const client = provider.client();
+        const { contract } = await provider.deployCode(code, { client });
+
+        const slots = await SlotsParser.slots({ path: '', code }, 'Vault');
+        const storage = SlotsStorage.createWithClient(client, contract.address, slots);
+
+        eq_(await storage.get('count'), 123n);
+        eq_(await storage.get('balances["0x1000000000000000000000000000000000000001"]'), 7n);
+    }
+});

package/docs/ai/examples/token-transfer.spec.ts

@@ -0,0 +1,22 @@
+import { Web3ClientFactory } from '@dequanto/clients/Web3ClientFactory';
+import { TokenTransferService } from '@dequanto/tokens/TokenTransferService';
+import { TokensService } from '@dequanto/tokens/TokensService';
+
+UTest({
+    async 'load known token metadata and read a live token balance' () {
+        const client = await Web3ClientFactory.getAsync('eth');
+        const tokens = new TokensService('eth');
+        const usdc = await tokens.getKnownToken('USDC');
+        const service = new TokenTransferService(client);
+
+        const balance = await service.getBalance(
+            '0x0000000000000000000000000000000000000000',
+            usdc
+        );
+
+        eq_(usdc.symbol, 'USDC');
+        eq_(usdc.decimals, 6);
+        eq_(usdc.address.toLowerCase(), '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48');
+        gte_(balance, 0n);
+    }
+});

package/docs/ai/references/contracts.md

@@ -0,0 +1,111 @@
+# Contracts
+
+Use generated contract clients whenever an ABI, artifact, Solidity source, or verified explorer source is available. Generated clients extend `ContractBase` and expose typed read/write methods.
+
+Key source files:
+
+- `src/contracts/ContractBase.ts`
+- `src/contracts/ContractReader.ts`
+- `src/contracts/ContractWriter.ts`
+- `src/contracts/ContractClassFactory.ts`
+- `src/contracts/utils/ContractBaseUtils.ts`
+- `src/txs/TxWriter.ts`
+
+Useful tests:
+
+- `test/generate/gen.spec.ts`
+- `test/hardhat/deployments/deployments.spec.ts`
+- `test/receipt.spec.ts`
+
+## Generated Contract Shape
+
+Generated read methods call `this.$read(...)` and return decoded values.
+
+Generated write methods call `this.$write(...)` and return a `Promise<TxWriter>`.
+
+Common generated-client helpers from `ContractBase`:
+
+- `$address(address)` creates the same contract wrapper for another address.
+- `$config(builderConfig, writerConfig)` returns a configured wrapper clone.
+- `$receipt()` wraps write methods so they wait for mining.
+- `$data()` creates tx data instead of sending it.
+- `$gas()` estimates write-method gas.
+- `$call()` simulates write methods with `eth_call`.
+- `$req()` creates deferred read requests for batching.
+- `$signed()` creates methods for signed flows.
+- `forBlock(numberOrDate)` reads at a block number or date.
+- `getPastLogs(event, options)` and generated event helpers read parsed logs.
+
+## Reads
+
+Prefer:
+
+```ts
+const token = new ERC20(tokenAddress, client);
+const balance = await token.balanceOf(account);
+```
+
+For ad hoc reads without a generated class:
+
+```ts
+import { ContractReader } from '@dequanto/contracts/ContractReader';
+
+const reader = new ContractReader(client);
+const symbol = await reader.readAsync<string>(
+    tokenAddress,
+    'function symbol() returns string'
+);
+```
+
+For batching generated reads, prefer deferred requests from `$req()` and execute through `$executeBatch(...)` when available.
+
+## Writes
+
+Generated write methods return `TxWriter`.
+
+```ts
+const tx = await token.transfer(sender, receiver, amount);
+const receipt = await tx.wait();
+```
+
+If the caller needs a receipt directly:
+
+```ts
+const tx = await token.$receipt().transfer(sender, receiver, amount);
+const receipt = tx.receipt;
+```
+
+If the caller needs calldata but should not submit:
+
+```ts
+const data = await token.$data().transfer(sender, receiver, amount);
+```
+
+For manual send mode:
+
+```ts
+const tx = await token
+    .$config({ send: 'manual', gasEstimation: false })
+    .transfer(sender, receiver, amount);
+```
+
+## Events
+
+For generated contracts, prefer generated log helpers when present. Otherwise use:
+
+```ts
+const logs = await token.getPastLogs('Transfer', {
+    fromBlock,
+    toBlock,
+    params: { from: owner }
+});
+```
+
+`ContractBase` converts raw logs to `ITxLogItem` with `event`, `params`, `arguments`, `blockNumber`, `transactionHash`, and address data.
+
+## Avoid
+
+- Do not instantiate `ethers.Contract` or `viem.getContract` in consumer code that already uses dequanto.
+- Do not manually encode ABI calldata when generated `$data()` or `$abiUtils.serializeMethodCallData(...)` is available.
+- Do not guess generated method names for overloaded Solidity functions; inspect the generated class.
+

package/docs/ai/references/deployments.md

@@ -0,0 +1,98 @@
+# Deployments
+
+Use `HardhatProvider` for compile/deploy helper flows and `Deployments` for idempotent deployments, deployment storage, bytecode checks, proxy upgrades, beacon proxies, and verification.
+
+Key source files:
+
+- `src/hardhat/HardhatProvider.ts`
+- `src/contracts/deploy/Deployments.ts`
+- `src/contracts/deploy/proxy/ProxyDeployment.ts`
+- `src/contracts/deploy/storage/DeploymentsStorage.ts`
+- `src/contracts/deploy/ContractDeployer.ts`
+
+Useful tests:
+
+- `test/hardhat/deployments/deployments.spec.ts`
+- `test/hardhat/deploy.spec.ts`
+- `test/hardhat/compile.spec.ts`
+- `test/hardhat/forked.spec.ts`
+- `test/hardhat/snaps.spec.ts`
+
+## HardhatProvider
+
+```ts
+import { HardhatProvider } from '@dequanto/hardhat/HardhatProvider';
+
+const hh = new HardhatProvider();
+const client = hh.client();
+const deployer = hh.deployer(0);
+```
+
+Common methods:
+
+- `client('hardhat' | 'localhost')`
+- `forked({ platform, url, block })`
+- `deployer(index)`
+- `compileSol(path, options?)`
+- `compileCode(code, options?)`
+- `deploySol(path, options?)`
+- `deployCode(code, options?)`
+- `deployClass(Ctor, options?)`
+- `getContractFromSolPath(path, options?)`
+
+## Idempotent Deployments
+
+```ts
+import { Deployments } from '@dequanto/contracts/deploy/Deployments';
+
+const deployments = new Deployments(client, deployer, {
+    directory: './deployments/',
+    verification: false
+});
+
+const { contract, deployment } = await deployments.ensure(MyContract, {
+    arguments: ['Name', 'SYM', 1_000n]
+});
+```
+
+`ensure` reuses saved deployments when possible. With `latest: true`, it checks local bytecode against deployed bytecode and redeploys when required unless options say otherwise.
+
+## Transparent Proxy
+
+```ts
+const { contract, contractImplementation, contractProxy, deployment } =
+    await deployments.ensureWithProxy(MyUpgradeableContract, {
+        id: 'MyUpgradeableContract',
+        initialize: [owner]
+    });
+```
+
+Initializer params are passed by method name:
+
+- `initialize`
+- `initializeV2`
+- `initializeV3`
+
+`ensureWithProxy` serializes initializer and latest migration calldata from the generated contract ABI.
+
+## Beacon Proxy
+
+```ts
+const result = await deployments.ensureWithBeacon(MyUpgradeableContract, {
+    id: 'Pool/A',
+    initialize: [owner]
+});
+```
+
+Beacon deployment ids can use paths. The first path segment is treated as the implementation id.
+
+## Storage Layout
+
+Proxy and beacon upgrades validate generated storage layout data when available. For upgrade-sensitive work, inspect generated `$slots` and deployment layout output before assuming compatibility.
+
+## Avoid
+
+- Do not deploy a contract twice manually when `Deployments.ensure(...)` should own the deployment record.
+- Do not skip `id` for multiple proxy or beacon instances of the same implementation.
+- Do not assume proxy upgrade safety from TypeScript compile success alone.
+