dequanto 0.2.50 → 0.2.51

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

@@ -22,6 +22,8 @@ Useful tests:
 
 ## TxWriter Lifecycle
 
+For transactions from any address on a Hardhat development network or fork, pass `{ address, type: 'impersonated' }` as the account. The writer enables impersonation automatically. See [Hardhat development and forking](hardhat.md#impersonate-an-account) for a complete ERC20 transfer example.
+
 Generated write methods return a `TxWriter`.
 
 ```ts
@@ -45,7 +47,7 @@ const receipt = await tx.wait();
 Use `BatchAgent` when a script should run its full transaction flow without immediately submitting transactions on-chain. `BatchAgent` plugs into `TxWriter.DEFAULTS.agent`, intercepts write calls, returns completed mock writers/receipts to the script, and caches the transactions for later review or execution.
 
 ```ts
-import { BatchAgent } from '@dequanto/txs/agents/BatchAgent';
+import { BatchAgent } from 'dequanto/txs/agents/BatchAgent';
 
 const batch = new BatchAgent().enable();
 
@@ -76,7 +78,7 @@ Important behavior:
 ## Build And Sign Raw Tx
 
 ```ts
-import { TxDataBuilder } from '@dequanto/txs/TxDataBuilder';
+import { TxDataBuilder } from 'dequanto/txs/TxDataBuilder';
 
 const builder = new TxDataBuilder(client, sender, {
     to: receiver
@@ -93,7 +95,7 @@ const receipt = await client.sendSignedTransaction(signed);
 ## Send Existing Tx Data
 
 ```ts
-import { TxWriter } from '@dequanto/txs/TxWriter';
+import { TxWriter } from 'dequanto/txs/TxWriter';
 
 const tx = await TxWriter.writeTxData(client, {
     to: receiver,
@@ -133,7 +135,7 @@ const service = new TokenTransferService(client).$config({ nonce });
 Use `TxLogParser` for receipts when no generated contract parser is available.
 
 ```ts
-import { TxLogParser } from '@dequanto/txs/receipt/TxLogParser';
+import { TxLogParser } from 'dequanto/txs/receipt/TxLogParser';
 
 const parser = new TxLogParser();
 const logs = await parser.parse(receipt, { abi });

package/skills/dequanto/references/utils.md

@@ -0,0 +1,131 @@
+# Utility Helpers
+
+Dequanto includes helpers for common EVM and TypeScript operations. Prefer them when they make contract code shorter and more consistent. Verify unfamiliar helpers in the installed declarations.
+
+Key source files:
+
+- `src/abi/$abi.ts`
+- `src/utils/$contract.ts`
+- `src/utils/$require.ts`
+- `src/utils/$hex.ts`
+- `src/utils/$date.ts`
+- `src/utils/$sig.ts`
+- `src/utils/$promise.ts`
+
+Runnable example: [utility helpers](../examples/utils.spec.ts).
+
+## ABI Encoding And Decoding
+
+Import `$abi` from `dequanto/abi/$abi`. Use it instead of another ABI coder or manually constructed calldata.
+
+```ts
+import { $abi } from 'dequanto/abi/$abi';
+
+const encoded = $abi.encode(['address', 'uint256'], [account, 5n]);
+const [decodedAccount, decodedAmount] = $abi.decode(['address', 'uint256'], encoded);
+const calldata = $abi.encodeCall(
+    'function transfer(address to, uint256 amount)',
+    [account, 5n]
+);
+const totalSupply = $abi.decodeReturn<bigint>(
+    'function totalSupply() view returns (uint256)',
+    responseHex
+);
+```
+
+- `encode` and `decode` accept one type/value or arrays of types/values.
+- `encodeCall` accepts a Solidity function declaration or JSON ABI item.
+- `decodeReturn` accepts a function declaration, JSON ABI item, or output definitions. Multiple named outputs are returned as an object.
+
+## Solidity-Compatible Keccak-256
+
+Use `$contract.keccak256(...)` for the same Keccak-256 operation used by Solidity:
+
+```ts
+import { $contract } from 'dequanto/utils/$contract';
+
+const topic = $contract.keccak256('Transfer(address,address,uint256)');
+const bytes = $contract.keccak256('0x1234', 'buffer');
+```
+
+A string beginning with `0x` is hashed as bytes; other strings are UTF-8 encoded. The default output is hex. Pass `'buffer'` for a `Uint8Array`.
+
+## Runtime Requirements
+
+`$require` provides compact runtime validation similar in purpose to Solidity's `require`:
+
+```ts
+import { $require } from 'dequanto/utils/$require';
+
+const address = $require.AddressNotEmpty(inputAddress, 'Recipient is required');
+$require.BigInt(amount, 'Amount must be bigint', { min: 1n });
+$require.gte(balance, amount, 'Insufficient balance');
+$require.Hex(calldata, 'Invalid calldata');
+$require.notNull(receipt, 'Receipt was not returned');
+```
+
+Useful checks include `True`, `notNull`, `Null`, `notEmpty`, `eq`, `notEq`, `gt`, `gte`, `lt`, `lte`, `match`, `has`, `oneOf`, `Address`, `AddressNotEmpty`, `AddressChecked`, `TxHash`, `Hex`, `Number`, `BigInt`, and `Numeric`. Most value validators return the validated value.
+
+## Hex Manipulation
+
+Use `$hex` for `0x` normalization, conversion, padding, concatenation, slicing, and byte counts:
+
+```ts
+import { $hex } from 'dequanto/utils/$hex';
+
+const value = $hex.ensure('1234');             // 0x1234
+const word = $hex.padBytes(value, 32);          // left-pad to 32 bytes
+const payload = $hex.concat([value, '0xabcd']);
+const firstTwoBytes = $hex.getBytes(payload, 0, 2);
+const byteLength = $hex.getBytesLength(payload);
+```
+
+`toHex('hello')` encodes a normal string as UTF-8. `toHexBuffer(...)` also ensures an even number of hex digits. `padBytes` takes a byte count and pads left by default; pass `{ padEnd: true }` to pad right.
+
+## Date And Time
+
+Use `$date` for time spans, Unix timestamps, formatting, date boundaries, and arithmetic:
+
+```ts
+import { $date } from 'dequanto/utils/$date';
+
+const timeoutMs = $date.parseTimespan('5min');
+const timeoutSeconds = $date.parseTimespan('5min', { get: 's' });
+const deadline = $date.tool().add('5min').toUnixTimestamp();
+const date = $date.fromUnixTimestamp(deadline);
+```
+
+`parseTimespan` returns milliseconds by default. Request seconds explicitly when passing time to a contract or RPC API.
+
+## Signing
+
+Use `$sig` for account creation, message and typed-data signatures, transaction signing, and signer recovery:
+
+```ts
+import { $sig } from 'dequanto/utils/$sig';
+
+const account = $sig.$account.generate();
+const signature = await $sig.signMessage('Approve operation', account);
+const signer = $sig.recoverMessage('Approve operation', signature);
+```
+
+Use `signMessage`/`recoverMessage` for EIP-191 messages, `signTypedData` for typed data, and `signTx`/`recoverTx` for transactions. Account helpers include `generate`, `fromMnemonic`, and `fromKey`.
+
+## Promise Results Without Try/Catch
+
+`$promise.caught(...)` converts a rejection into a result object:
+
+```ts
+import { $promise } from 'dequanto/utils/$promise';
+
+const { result, error } = await $promise.caught(loadValue());
+if (error) {
+    console.error(error.message);
+} else {
+    console.log(result);
+}
+```
+
+It accepts a promise or a function returning a promise and returns `{ result }` on success or `{ error }` on failure. Other helpers cover delays, timeouts, events, callbacks, and polling.
+
+The remaining files under `src/utils/` mostly support organization, conversion, formatting, and readability. Use them when relevant, but verify current signatures in `lib/types/utils/` rather than guessing.

package/src/explorer/BlockchainExplorer.ts

@@ -175,10 +175,10 @@ export class BlockchainExplorer implements IBlockchainExplorer {
         try {
             abi = await this.client.get(url);
         } catch (err) {
-            $logger.log(`Blockchain explorer request filed "${url}": ${err.message}`);
+            $logger.log(`Blockchain explorer request failed for "${url}": ${err.message}`);
             let addressByByteCode = await this.getSimilarContract(address);
             if (addressByByteCode != null) {
-                $logger.log(`Found similar byte code address: ${addressByByteCode}`);
+                $logger.log(`Found similar bytecode address: ${addressByByteCode}`);
                 return this.getContractAbi(addressByByteCode);
             }
             throw err;
@@ -195,7 +195,7 @@ export class BlockchainExplorer implements IBlockchainExplorer {
                 let hex = $address.fromBytes32(uin256Hex);
                 return this.getContractAbi(hex)
             }
-            throw new Error(`Implement ${params.implementation} support`);
+            throw new Error(`Implementation lookup is not supported for ${params.implementation}`);
         }
         if (isOpenZeppelinProxy(abiJson) || mightBeProxy(abiJson)) {
             let web3 = this.getWeb3(this.platform);
@@ -384,12 +384,12 @@ export class BlockchainExplorer implements IBlockchainExplorer {
             try {
                 return JSON.parse(str)
             } catch (error) {
-                // etherscan returns code wrapped into {{}}
+                // Etherscan can return source code wrapped in {{...}}
             }
             str = str
                 .replace(/^\s*\{\{/g, '{')
                 .replace(/\}\}\s*$/g, '}');
-            // @TODO check etherscan serialized jsons. Does it always has "{{...}}" wrappings
+            // @TODO Check Etherscan serialized JSON. Does it always use "{{...}}" wrapping?
 
             return JSON.parse(str)
         }
@@ -555,7 +555,7 @@ function hasMethod(abi: TAbiItem[], name: string) {
 function ensureDefaults(opts: TExplorerDefinition) {
 
     let platform = opts.platform;
-    $require.notNull(platform, `Generic Blockchain Explorer Config should contain platform name`);
+    $require.notNull(platform, `Generic blockchain explorer config must include a platform name`);
 
     opts.ABI_CACHE ??= `./cache/${$platform.toPath(platform)}/abis.json`
     opts.CONTRACTS ??= [];
@@ -594,7 +594,7 @@ class HttpClient {
     async getHtml(url: string) {
         let resp = await $http.get(url);
         if (resp.status !== 200) {
-            throw new Error(`${url} not loaded with status ${resp.status}.`);
+            throw new Error(`${url} failed to load with status ${resp.status}.`);
         }
         return resp.data;
     }
@@ -644,7 +644,7 @@ class HttpClient {
             throw error;
         }
         if (data.result == null) {
-            $logger.warn(`Blockchain "${url}" explorer returned empty result`, data);
+            $logger.warn(`Blockchain explorer "${url}" returned an empty result`, data);
         }
         return data.result as TOut;
     }
@@ -669,7 +669,7 @@ class HttpClient {
             throw new Error(str);
         }
         if (data.result == null) {
-            $logger.warn(`Blockchain "${url}" explorer returned empty result`, data);
+            $logger.warn(`Blockchain explorer "${url}" returned an empty result`, data);
         }
         return data.result;
     }

package/src/explorer/BlockchainExplorerFactory.ts

@@ -50,7 +50,7 @@ export namespace BlockchainExplorerFactory {
         return new BlockchainExplorer(params);
     }
 
-    /** Same as sync variation, but ensures the config is being fetched */
+    /** Same as the synchronous variant, but ensures the config has been fetched */
     export async function getAsync (platform: TPlatform, opts?: IBlockchainExplorerFactoryParams): Promise<IBlockchainExplorer> {
         await Config.get();
         return get(platform, opts);

package/src/explorer/BlockchainExplorerProvider.ts

@@ -26,7 +26,7 @@ export namespace BlockchainExplorerProvider {
                 if (cfg != null) {
                     return new BlockchainExplorer({ platform, ...cfg });
                 }
-                throw new Error(`Unsupported platform ${platform} for block chain explorer`);
+                throw new Error(`Unsupported platform ${platform} for blockchain explorer`);
         }
     }
 

package/src/explorer/BlockchainExplorerStorage.ts

@@ -82,7 +82,7 @@ export class BlockchainExplorerStorage implements IBlockchainExplorer {
         let $address = opts?.implementation ?? address;
         let $contract = this.contracts[$address.toLowerCase()];
         $require.notNull($contract, `Contract "${$address}" not found`);
-        // @TODO: L1: return abi as json (means in *scan providers we must serialize it earlier)
+        // @TODO: L1: Return ABI as JSON. *scan providers should serialize it earlier.
         return {
             implementation: $address,
             abi: JSON.stringify($contract.abi)
@@ -92,7 +92,7 @@ export class BlockchainExplorerStorage implements IBlockchainExplorer {
         let _address = address;
         let _contract = this.contracts[_address.toLowerCase()];
         $require.notNull(_contract, `Contract "${_address}" not found`);
-        // @TODO: L1: return abi as json (means in *scan providers we must serialize it earlier)
+        // @TODO: L1: Return ABI as JSON. *scan providers should serialize it earlier.
         return {
             SourceCode: {
                 contractName: _contract.name,

package/src/explorer/ContractVerifier.ts

@@ -42,7 +42,7 @@ export class ContractVerifier {
     }
 
     async ensure (Ctor: TContractInfo, opts: TSubmissionOptions = {}): Promise<void>  {
-        this.logger.log(`Submit sources for ${typeof Ctor === 'string' ? Ctor : Ctor.name}`);
+        this.logger.log(`Submitting sources for ${typeof Ctor === 'string' ? Ctor : Ctor.name}`);
 
         let status = await this.submit(Ctor, opts);
         await this.waitForVerification(status, opts);
@@ -66,7 +66,7 @@ export class ContractVerifier {
             } catch (e) {
                 let message = e.message;
                 if (/verified/i.test(message)) {
-                    // was already verified
+                    // Already verified.
                     return true;
                 }
                 if (/(pending|queue)/i.test(message)) {
@@ -100,13 +100,13 @@ export class ContractVerifier {
         }
 
         try {
-            this.logger.log(`Checking if already verified ${address}`);
+            this.logger.log(`Checking whether contract ${address} is already verified`);
             let currentSources = await this.explorer.getContractSource(address);
             if ($is.notEmpty(currentSources?.ContractName)) {
                 return { status:'verified' };
             }
         } catch (error) {
-            // ignore any pre-check error and continue with the verification
+            // Ignore pre-check errors and continue with verification.
         }
 
         let deployedBytecode = await client.getCode(address);
@@ -140,7 +140,7 @@ export class ContractVerifier {
         }
 
         let jsonMetaPath = info.ctx.source.path;
-        $require.notEmpty(jsonMetaPath, `Deployment should return a path to compilation JSON`);
+        $require.notEmpty(jsonMetaPath, `Deployment should return a path to the compilation JSON`);
         $require.True(await File.existsAsync(jsonMetaPath) , `${jsonMetaPath} does not exist`);
 
         let jsonMeta = await File.readAsync<{ sourceName: string, contractName: string }>(jsonMetaPath);
@@ -150,7 +150,7 @@ export class ContractVerifier {
         let jsonMetaDbg = await File.readAsync<{ buildInfo: string }>(jsonMetaDbgPath);
 
         let jsonMetaBuildInfoPath = jsonMetaDbg.buildInfo;
-        $require.notEmpty(jsonMetaPath, `${jsonMetaDbgPath} should contain the path to the buildInfo json file`);
+        $require.notEmpty(jsonMetaPath, `${jsonMetaDbgPath} should contain the path to the build info JSON file`);
 
         let buildInfoPath = new class_Uri(new class_Uri(jsonMetaPath).toDir()).combine(jsonMetaBuildInfoPath).toString();
         $require.True(await File.existsAsync(buildInfoPath) , `${buildInfoPath} does not exist`);
@@ -170,7 +170,7 @@ export class ContractVerifier {
         }
         let buildInfo = await File.readAsync<TBuildInfo>(buildInfoPath);
 
-        $require.notNull(buildInfo.solcLongVersion, `${buildInfoPath} should contain the "solcLongVersion" information`);
+        $require.notNull(buildInfo.solcLongVersion, `${buildInfoPath} should contain the "solcLongVersion" value`);
 
         let sources = await this.getSources(jsonMeta.sourceName);
         let sourcesSerialized = JSON.stringify({
@@ -181,7 +181,7 @@ export class ContractVerifier {
 
         let sourcesSerializedWrapped = `${sourcesSerialized}`;
 
-        this.logger.log(`Submit ${jsonMeta.sourceName}:${jsonMeta.contractName} and dependencies to verify ${address} contract`);
+        this.logger.log(`Submitting ${jsonMeta.sourceName}:${jsonMeta.contractName} and dependencies to verify contract ${address}`);
 
         try {
             let guid = await this.explorer.submitContractVerification({
@@ -243,7 +243,7 @@ export class ContractVerifier {
 
         await crawlSourceFile(new SourceFile(main));
 
-        this.logger.log(`Found ${Object.keys(sources).length} source files: `, Object.keys(sources));
+        this.logger.log(`Found ${Object.keys(sources).length} source files:`, Object.keys(sources));
         return sources;
     }
 
@@ -284,7 +284,7 @@ export class ContractVerifier {
             } catch (e) {
                 let message = e.message;
                 if (/verified|success/i.test(message)) {
-                    // was already verified
+                    // Already verified.
                     return true;
                 }
                 if (/(pending|queue)/i.test(message)) {

package/src/explorer/verifiers/FsHtmlVerifier.ts

@@ -115,7 +115,7 @@ export class FsHtmlVerifier implements IVerifier {
 
 
         if (contractData.contractName.includes('Utils/Proxy')) {
-            // fix Proxy, rename contract duplicates
+            // Rename duplicate Proxy contracts before writing the verification form.
             html = html.replaceAll('contracts/Utils/Proxy.sol:Proxy', 'contracts/Utils/TUProxy.sol:TUProxy');
             html = html.replace('Utils/Proxy.sol":', 'Utils/TUProxy.sol":');
             html = html.replace('contract Proxy is ', 'contract TUProxy is ');

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
     "exclude": [
-        "exports/core.lib.ts"
+        "exports/core.lib.ts",
+        "ts-temp"
     ],
     "compilerOptions": {
         "baseUrl": "./",

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

@@ -1,35 +0,0 @@
-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';
-
-// This is the low-level path for creating a storage reader directly from Solidity source.
-// Classes generated from source with 0xweb install or @0xweb/hardhat expose storage on the instance: foo.storage.get('count').
-UTest({
-    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/references/storage.md

@@ -1,93 +0,0 @@
-# Solidity Storage
-
-Use `SlotsParser` to derive layout and `SlotsStorage` to read or write slots. Do not decode raw storage words as ABI payloads.
-
-Key source files:
-
-- `src/solidity/SlotsParser.ts`
-- `src/solidity/SlotsStorage.ts`
-- `src/solidity/storage/handlers/SlotStructHandler.ts`
-- `src/solidity/storage/handlers/SlotMappingHandler.ts`
-- `src/solidity/storage/handlers/SlotDynamicArrayHandler.ts`
-- `src/solidity/storage/SlotsStorageTransport.ts`
-- `src/gen/GeneratorStorageReader.ts`
-
-Useful tests:
-
-- `test/solidity/SlotsReader.spec.ts`
-- `test/solidity/Storage.spec.ts`
-- `test/solidity/SlotsParser.spec.ts`
-- `test/generate/slotreader.spec.ts`
-
-## Parse Slots From Solidity
-
-```ts
-import { SlotsParser } from '@dequanto/solidity/SlotsParser';
-
-const slots = await SlotsParser.slots({
-    path: './contracts/Vault.sol'
-}, 'Vault');
-```
-
-For inline code:
-
-```ts
-const slots = await SlotsParser.slots({ path: '', code }, 'Foo');
-```
-
-## Parse Slots From ABI Inputs
-
-Use this for standalone struct or tuple ABI data:
-
-```ts
-const slots = await SlotsParser.slotsFromAbi(
-    '(uint256 foo, address owner, bool enabled)'
-);
-```
-
-## Read Contract Storage
-
-```ts
-import { SlotsStorage } from '@dequanto/solidity/SlotsStorage';
-
-const storage = SlotsStorage.createWithClient(client, contract.address, slots);
-
-const owner = await storage.get('owner');
-const user = await storage.get('users[0]');
-const balance = await storage.get(`balances["${account}"]`);
-```
-
-Supported path forms include:
-
-- `field`
-- `struct.field`
-- `array[0]`
-- `mapping["0x..."]`
-- `mapping["0x..."].field`
-- `nested[0].balances[1]`
-- breadcrumb arrays such as `['users', account, 'balance']`
-
-## Read Diamond Or Offset Storage
-
-For library-selected storage roots:
-
-```ts
-const storage = SlotsStorage.createWithClient(client, contract.address, slots, {
-    storageOffset: $contract.keccak256('diamond.app.storage')
-});
-```
-
-## Write Storage In Tests
-
-`SlotsStorage.set(...)` exists and is useful in Hardhat/debug contexts:
-
-```ts
-await storage.set('user.balance', 1000n);
-```
-
-Do not use storage writes in production code unless the transport explicitly supports it and the task requires test/debug mutation.
-
-## Raw Slot Reads
-
-Use `client.getStorageAt(address, slot)` or `client.getStorageAtBatched(address, slots)` only when raw words are needed.
-