dequanto 0.2.37 → 0.2.40

package/src/contracts/ContractWriter.ts

@@ -53,9 +53,9 @@ export class ContractWriter implements IContractWriter {
     }
 
     /**
-    * We split Tx sending in two awaitable steps
-    * 1. This method prepares(gas, nonce, etc) - and sends the Tx
-    * 2. With returned writer you can subscribe to events and/or wait for Tx to be mined
+    * We split transaction sending into two awaitable steps:
+    * 1. This method prepares gas, nonce, etc., and sends the transaction.
+    * 2. With the returned writer, you can subscribe to events and/or wait for the transaction to be mined.
     * @param account
     * @param interfaceAbi
     * @param params
@@ -74,7 +74,7 @@ export class ContractWriter implements IContractWriter {
     ): Promise<TxWriter> {
 
         $require.notNull(account, 'Account parameter is undefined.');
-        $require.True(typeof account === 'object' || typeof account === 'string', `ContractWriter expect Account as the first parameter, got: ${ typeof account }`)
+        $require.True(typeof account === 'object' || typeof account === 'string', `ContractWriter expects Account as the first parameter, got: ${ typeof account }`)
 
         let value = typeof account !== 'string'
             ? account.value

package/src/contracts/deploy/ContractDeployer.ts

@@ -87,10 +87,10 @@ export class ContractDeployer {
         let artifacts = ctx.artifacts ?? './artifacts/';
         let files = await $require.resolved(
             Directory.readFilesAsync(artifacts, '**.json'),
-            `Artifact files not found for ${ctx.name}`
+            `Artifact files were not found for ${ctx.name}`
         );
         let file = files.find(x => x.uri.file === `${ctx.name}.json`);
-        $require.notNull(file, `File for the contract ${ctx.name} not found within: \n ${ files.map(x => x.uri.toString()).join('\n') }`);
+        $require.notNull(file, `File for contract ${ctx.name} was not found in: \n ${ files.map(x => x.uri.toString()).join('\n') }`);
 
         return this.fromMetaFile ({
             ...ctx,
@@ -129,7 +129,7 @@ export class ContractDeployer {
     }
 
     private async fromMetaJson (ctx: TDeploymentByMetaJson) {
-        $require.notNull(ctx.json?.bytecode, 'Contract bytecode is expected in json');
+        $require.notNull(ctx.json?.bytecode, 'Contract bytecode is expected in JSON');
         return this.fromBytecode({
             ...ctx,
             bytecode: ctx.json.bytecode,
@@ -139,7 +139,7 @@ export class ContractDeployer {
     }
 
     private async fromBytecode (ctx: TDeploymentWithBytecode) {
-        $require.True($is.Hex(ctx.bytecode), `bytecode must be a hex string: ${ctx.bytecode}`);
+        $require.True($is.Hex(ctx.bytecode), `Bytecode must be a hex string: ${ctx.bytecode}`);
 
         let deployment = new ContractDeployment({
             client: this.client,

package/src/contracts/deploy/ContractDeployment.ts

@@ -19,7 +19,7 @@ export class ContractDeployment {
         abi?: TAbiItem[]
         params?: any[]
         source?: {
-            // JSON meta file
+            // JSON metadata file.
             path: string
         }
     }) {

package/src/contracts/deploy/Deployments.ts

@@ -7,8 +7,7 @@ import { TEth } from '@dequanto/models/TEth';
 import { $abiUtils } from '@dequanto/utils/$abiUtils';
 import { $contract } from '@dequanto/utils/$contract';
 import { $require } from '@dequanto/utils/$require';
-import { ParametersFromSecond } from '@dequanto/utils/types';
-import { Constructor } from '@dequanto/utils/types';
+import { Constructor, ParametersFromSecond } from '@dequanto/utils/types';
 
 import { BlockchainExplorerFactory } from '@dequanto/explorer/BlockchainExplorerFactory';
 import { ContractVerifier } from '@dequanto/explorer/ContractVerifier';
@@ -16,40 +15,45 @@ import { HardhatWeb3Client } from '@dequanto/hardhat/HardhatWeb3Client';
 import { LoggerService } from '@dequanto/loggers/LoggerService';
 import { $is } from '@dequanto/utils/$is';
 
-import { IBeacon, IBeaconProxy, IProxy, IProxyAdmin, ProxyDeployment } from './proxy/ProxyDeployment';
-import { DeploymentsStorage, IDeployment } from './storage/DeploymentsStorage';
+import { $bytecode } from '@dequanto/evm/utils/$bytecode';
 import { TAddress } from '@dequanto/models/TAddress';
-import { $promise } from '@dequanto/utils/$promise';
 import { l } from '@dequanto/utils/$logger';
-import { $bytecode } from '@dequanto/evm/utils/$bytecode';
-import { THex } from '@dequanto/models/THex';
+import { $promise } from '@dequanto/utils/$promise';
+import { IBeacon, IBeaconProxy, IProxy, IProxyAdmin, ProxyDeployment } from './proxy/ProxyDeployment';
+import { DeploymentsStorage, IDeployment } from './storage/DeploymentsStorage';
 
 
 
 type TDeploymentOptions = {
     id?: string
 
-    /** Will deploy the contract */
+    // For proxy deployments: redeploys the implementation if the bytecode has not changed but the immutable arguments have changed.
+    immutablesKey?: string
+
+    // Older deployments did not have immutablesKey, so any proxy implementation with immutable variables would trigger redeployment.
+    checkImmutables?: boolean
+
+    /** Deploys the contract. */
     force?: boolean
-    /** Will check if local bytecode has changed and will deploy */
+    /** Checks whether the local bytecode has changed and deploys if needed. */
     latest?: boolean
 
     verification?: boolean | 'silent'
 
-    // Will be used for verification process
+    // Used for the verification process.
     proxyFor?: TAddress
 
     deployment?: {
-        // Pending deployment transaction will be re-checked
+        // Pending deployment transaction will be rechecked.
         tx?: TEth.Hex
-        // When false, the implementation won't be updated in proxy
+        // When false, the implementation will not be updated in the proxy.
         upgradeProxy?: boolean
-        // Owner, if differes from deployer
+        // Owner, if different from the deployer.
         owner?: TEth.IAccount
     }
 }
 type TVerificationOptions = TDeploymentOptions & {
-    // otherwise will be fetched from the deployment TX
+    // Otherwise, this will be fetched from the deployment transaction.
     constructorParams?: any[]
 }
 
@@ -81,7 +85,7 @@ export class Deployments {
         Proxy?: Constructor<ContractBase>,
         ProxyAdmin?: Constructor<IProxyAdmin>
         directory?: string
-        // Will be part of the deployments filename
+        // Part of the deployments filename.
         name?: string
         // TPlatform of a forked network
         fork?: string
@@ -136,7 +140,7 @@ export class Deployments {
     }): Promise<T> {
         let contract = await this.getOrNull(Ctor, opts);
         if (contract == null) {
-            throw new Error(`Deployment ${Ctor.name} ${opts?.id ?? ''} not found in ${this.client.platform} [${this.store.opts?.name ?? this.store.opts?.directory ?? ''}]`);
+            throw new Error(`Deployment ${Ctor.name} ${opts?.id ?? ''} was not found in ${this.client.platform} [${this.store.opts?.name ?? this.store.opts?.directory ?? ''}]`);
         }
         return contract;
     }
@@ -162,7 +166,7 @@ export class Deployments {
     }
 
     /**
-     * Get the deployment for Ctor, but returns the CtorWrapped instance. Useful for proxies, etc.
+     * Gets the deployment for Ctor, but returns the CtorWrapped instance. Useful for proxies, etc.
      * e.g. deployments.getAs(SomeProxy, SomeImplementation);
      */
     async getAs<TDeployed extends ContractBase, TWrapped extends ContractBase>(Ctor: Constructor<TDeployed>, CtorWrapped: Constructor<TWrapped>, opts?: {
@@ -183,7 +187,7 @@ export class Deployments {
         let deployment = await this.store.getDeploymentInfo('', {
             id: params.id
         });
-        $require.notNull(deployment, `Deployment for ${params.id} not found`);
+        $require.notNull(deployment, `Deployment for ${params.id} was not found`);
         await this.ensureVerification(params.Ctor, deployment, {
             id: params.id,
             constructorParams: params.constructorParams,
@@ -217,8 +221,14 @@ export class Deployments {
                 ? (this.client.platform === 'hardhat' || this.opts?.checkBytecode !== false)
                 : (opts.latest);
 
-            if (opts.force !== true && requireLatest !== true) {
-                // return already deployed contract
+            /** For backward compatibility:
+             *  For older deployments, the deployer should set this if immutablesKey is not present in the deployed state. */
+            let hasNewImmutables = opts.checkImmutables === true
+                ? Boolean(currentDeployment.immutablesKey != opts.immutablesKey)
+                : Boolean(currentDeployment.immutablesKey && currentDeployment.immutablesKey != opts.immutablesKey);
+
+            if (opts.force !== true && requireLatest !== true && hasNewImmutables !== true) {
+                // Return the already deployed contract.
                 $contract.store.register(contract as any);
                 return {
                     contract,
@@ -226,9 +236,9 @@ export class Deployments {
                 };
             }
             if (requireLatest === true && opts.force !== true) {
-                // was already deployed. Check new bytecode hash
+                // The contract was already deployed. Check the new bytecode hash.
                 let isSame = await this.isSameBytecode(Ctor, currentDeployment);
-                if (isSame) {
+                if (isSame && hasNewImmutables !== true) {
                     $contract.store.register(contract as any);
                     return {
                         contract,
@@ -252,7 +262,7 @@ export class Deployments {
 
 
 
-        // Lets deploy the contract, new, forced, or latest
+        // Deploy the contract: new, forced, or latest.
 
         let constructorArgs = opts.arguments ?? [];
         let id = opts.id ?? Ctor.name;
@@ -272,6 +282,7 @@ export class Deployments {
         let deployment = await this.store.saveDeployment(deployedContract, {
             id,
             name: Ctor.name,
+            immutablesKey: opts.immutablesKey,
             bytecodeHash: this.getBytecodeHash(deployedBytecode)
         }, receipt);
 
@@ -287,16 +298,11 @@ export class Deployments {
         };
     }
 
-    async ensureWithProxy<
-        T extends (TContract & { initialize?: TInit }),
-        TInit extends TInitializer
-    >(
+    async ensureWithProxy<T extends TContract>(
         CtorImpl: Constructor<T>,
-        opts?: TConstructorArgs<T> & TDeploymentOptions & {
-            initialize?: ParametersFromSecond<T['initialize']>
-        }
+        opts?: TConstructorArgs<T> & TDeploymentOptions & TInitializerParams<T>
     ): Promise<{
-        // the Implementation Contract with the address set to Proxy
+        // The implementation contract with the address set to the proxy.
         contract: T
         contractReceipt?: TEth.TxReceipt
         contractProxy: IProxy,
@@ -308,6 +314,7 @@ export class Deployments {
 
         let id = opts?.id ?? getImplementationId(CtorImpl);
         let proxyId = `${id}Proxy`;
+        let immutablesKey = getImmutablesKey(opts?.arguments);
 
         let {
             contract: contractImpl,
@@ -316,13 +323,15 @@ export class Deployments {
         } = await this.ensure(CtorImpl, {
             arguments: opts?.arguments as any,
             id: id,
+            immutablesKey,
             force: opts?.force,
             latest: this.opts?.checkBytecode !== false,
             verification: opts?.verification,
             deployment: opts?.deployment
         });
 
-        let data = serializeInitData(id, contractImpl, opts.initialize);
+        let initData = serializeInitData(id, contractImpl, opts.initialize);
+        let { migrationData, migrationV } = serializeMigrationData(id, contractImpl, opts);
         let implementationAddress = contractImplDeployment.implementation ?? contractImplDeployment.address;
 
         let {
@@ -337,13 +346,15 @@ export class Deployments {
             deployments: this,
             implementation: {
                 address: implementationAddress,
-                initData: data
+                initData,
+                migrationData,
+                migrationV,
             },
             upgradeImplementation: opts.deployment?.upgradeProxy ?? this.opts?.whenUpgradeRequired !== 'ignore'
         })
 
         if (contractImplDeployment.implementation == null) {
-            // Set the Proxy contract as the main Address
+            // Set the proxy contract as the main address.
             contractImplDeployment.implementation = contractImplDeployment.address;
             contractImplDeployment.address = contractProxy.address;
 
@@ -365,12 +376,12 @@ export class Deployments {
     }
 
     /**
-     * Deploys the Beacon contract. Implementation is the target contract (can be a proxy or normal contract)
+     * Deploys the Beacon contract. The implementation is the target contract (can be a proxy or normal contract).
      * https://docs.openzeppelin.com/contracts/5.x/api/proxy#beacon
      **/
     async ensureWithBeacon<
         T extends (TContract & { initialize?: TInit }),
-        TInit extends TInitializer
+        TInit extends TFunction
     >(
         CtorImpl: Constructor<T>,
         opts: TConstructorArgs<T> & TDeploymentOptions & {
@@ -379,7 +390,7 @@ export class Deployments {
             initialize?: ParametersFromSecond<T['initialize']>
         }
     ): Promise<{
-        // the Implementation Contract with the address set to Beacon Proxy
+        // The implementation contract with the address set to the Beacon proxy.
         contract: T
         contractReceipt?: TEth.TxReceipt
         contractDeployment: IDeployment
@@ -390,7 +401,7 @@ export class Deployments {
         contractBeaconProxyDeployment: IDeployment
     }> {
 
-        $require.notEmpty(opts?.id, `ID is required for Beacon deployment, as Implementation apparently will get multiple Beacons`);
+        $require.notEmpty(opts?.id, `ID is required for Beacon deployment, as the implementation can have multiple Beacons`);
 
         let beaconProxyId = opts.id;
         let implId = beaconProxyId.includes('/')
@@ -426,7 +437,9 @@ export class Deployments {
             deployments: this,
             implementation: {
                 address: implementationAddress,
-                initData: data
+                initData: data,
+                // @TODO Implement migrations for Beacons.
+                migrationData: null
             }
         });
 
@@ -461,7 +474,7 @@ export class Deployments {
             return true;
         }
 
-        // recheck v1
+        // Recheck v1.
         if (deployment.bytecodeHash != null) {
             let address = deployment.implementation ?? deployment.address;
             let bytecode = await this.client.getCode(address);
@@ -479,8 +492,8 @@ export class Deployments {
                 let [ localDiff, onchainDiff ] = Str.getDifference(bytecodeLocal, bytecodeOnchain);
                 if (localDiff === '' || /^0+$/.test(localDiff)) {
                     this._logger.log(`${deployment.id} bytecode has only immutable data diff, assume unchanged`);
-                    // Local deployedBytecode doesn't contain the immutable data
-                    // instead the solc generates the bytecode with 0 as the placeholder
+                    // Local deployedBytecode does not contain immutable data.
+                    // Instead, solc generates bytecode with 0 as the placeholder.
                     return true;
                 }
             }
@@ -557,19 +570,19 @@ export class Deployments {
 
 
     /**
-     * A simple method to configure the contracts state
+     * A simple method to configure contract state.
      */
     public async configure<T extends TContract, TValue>(Ctor: Constructor<T> | T, opts: {
         id?: string;
 
-        // Latest value, if differs from current, the updater will be executed
+        // Latest value. If it differs from current, the updater will be executed.
         value?: TValue
         // Current value.
         current?: TValue | Promise<TValue> | ((x: T) => Promise<TValue>);
         shouldUpdate?: boolean | (() => boolean | Promise<boolean>)
         updater: (x: T, value: TValue) => Promise<any>
 
-        // Will be logged with old and new value
+        // Logged with the old and new values.
         title?: string
     }) {
         let x: T;
@@ -611,9 +624,19 @@ export class Deployments {
     }
 }
 
-
-type TInitializer = (...args: any[]) => any
-
+type TFunction = (...args: any[]) => any;
+type TInitializerName = 'initialize' | `initializeV${number}`;
+type TInitializerParams<T> = {
+    initialize?: T extends { initialize: infer TInit }
+        ? TInit extends TFunction
+            ? ParametersFromSecond<TInit>
+            : never
+        : any[];
+} & {
+    [K in Extract<keyof T, TInitializerName>]?: T[K] extends TFunction
+        ? ParametersFromSecond<T[K]>
+        : never;
+};
 
 type TContract = ContractBase & { $constructor?: (...args: any[]) => any }
 type TConstructorArgs<T extends TContract> = T['$constructor'] extends Function ? {
@@ -639,7 +662,7 @@ function isEqual(a, b) {
         // Not strictly equal
         return a == b;
     }
-    // check arrays
+    // Check arrays.
     if (Array.isArray(a) || Array.isArray(b)) {
         if (a.length !== b.length) {
             return false;
@@ -648,7 +671,7 @@ function isEqual(a, b) {
             return isEqual(x, b[i]);
         });
     }
-    // check objects
+    // Check objects.
     for (let key in a) {
         let aValue = a[key];
         let bValue = b[key];
@@ -658,7 +681,7 @@ function isEqual(a, b) {
     }
     for (let key in b) {
         if (key in a === false && b[key] != null) {
-            // value present in b, but was not in a
+            // Value is present in b, but not in a.
             return false;
         }
     }
@@ -678,9 +701,34 @@ function serializeInitData(id: string, contract: ContractBase, initializeParams:
 }
 
 
+function serializeMigrationData(id: string, contract: ContractBase, opts: any) {
+    let rgx = /^initializeV(?<version>[\d+])$/;
+    let migrations = contract
+        .abi
+        .map(x => rgx.exec(x.name))
+        .filter(x => x != null)
+        .map(match => Number(match.groups.version))
+        ;
+    if (migrations.length === 0) {
+        return { migrationData: null, migrationV: 1 };
+    }
+    let v = alot(migrations).max(x => x);
+    let key = `initializeV${v}`;
+    let migrationAbi = contract.abi.find(x => x.name === key);
+    let migrationParams = opts?.[key] ?? [];
+    if (migrationParams?.length !== migrationAbi.inputs.length) {
+        throw new Error(`Wrong number of arguments (${migrationParams?.length}) for initializer method (${migrationAbi.inputs.length}) in ${id}.`);
+    }
+    return {
+        migrationData: $abiUtils.serializeMethodCallData(migrationAbi, migrationParams ?? []),
+        migrationV: v
+    };
+}
+
+
 /**
- * Normalize the contract name by removing any versions from name
- * "FooV1" is actually the "Foo" contract
+ * Normalizes the contract name by removing any version suffix from the name.
+ * "FooV1" is actually the "Foo" contract.
  */
 function getImplementationId (Ctor: Constructor<TContract>) {
     let id = Ctor.name;
@@ -691,6 +739,15 @@ function getImplementationId (Ctor: Constructor<TContract>) {
     return id;
 }
 
+
+function getImmutablesKey (args: any[]) {
+    if (args == null || args.length === 0) {
+        return null;
+    }
+    let key = args.map(arg => `${arg?.toString()}`).join('-');
+    return key;
+}
+
 namespace Str {
     export function getDifference (a: TEth.Hex, b: TEth.Hex) {
         if (a === b) {

package/src/contracts/deploy/proxy/$proxyDeploy.ts

@@ -20,7 +20,7 @@ export namespace $proxyDeploy {
                 variable: result.newVar,
                 path: serializePath(result.newPath, result.newVar),
                 conflicts: result.conflicts,
-                message: `${result.type}: Variable ${serializePath(result.newPath, result.newVar)}(${result.newVar.type}) at slot ${result.newVar.slot} conflicts ${conflicts}`
+                message: `${result.type}: Variable ${serializePath(result.newPath, result.newVar)}(${result.newVar.type}) at slot ${result.newVar.slot} conflicts with ${conflicts}`
             };
         }
         return null;
@@ -34,15 +34,15 @@ export namespace $proxyDeploy {
 
         ctx ??= {};
 
-        // When resolving state variables
-        // we append '$' char(s) to the overriden variables to avoid name conflicts, so here we check also for __gap with possible $ sfx.
+        // When resolving state variables, we append '$' characters to overridden variables to avoid name conflicts.
+        // Also check for __gap with a possible '$' suffix.
         let rgxGap = /^_+gap\$*$/;
         let oldMemory = oldVars.map(getMemoryPosition);
         let oldLastSlot = alot(oldVars).max(x => x.slot);
         for (let i = 0; i < newVars.length; i++) {
             let newVar = newVars[i];
             if (newVar.slot > oldLastSlot) {
-                // New variable was added after the last slot in current deployment
+                // A new variable was added after the last slot in the current deployment.
                 if (ctx.isExtendableMemory === false) {
                     return new BaseError(
                         ELayoutError.MEMORY_OVERFLOW,
@@ -52,8 +52,8 @@ export namespace $proxyDeploy {
                     );
                 }
 
-                // Find the new variable name in old storage
-                // Exclude those with the same position, as they might be pushed logically down by __gap pattern
+                // Find the new variable name in old storage.
+                // Exclude variables at the same position, as they might be pushed logically down by the __gap pattern.
                 let oldVarWithName = oldVars.find(x => x.name === newVar.name);
                 if (oldVarWithName != null && !Variables.eqLocation(oldVarWithName, newVar) && !rgxGap.test(newVar.name)) {
                     return new BaseError(
@@ -69,7 +69,7 @@ export namespace $proxyDeploy {
             let oldVarAtSamePos = oldVars.find(x => x.slot === newVar.slot && x.position === newVar.position);
             if (oldVarAtSamePos != null) {
                 if (oldVarAtSamePos.type === newVar.type) {
-                    // New variable is the same
+                    // The new variable is the same.
                     if (oldVarAtSamePos.name !== newVar.name) {
                         let oldVarWithName = oldVars.find(x => x.name === newVar.name);
                         if (oldVarWithName != null) {
@@ -229,7 +229,7 @@ export namespace $proxyDeploy {
         newPath?: string
         oldPath?: string
 
-        // root storage is extendable, but if we compare base array types, or structs, the memory is limited due to outer next variable slots
+        // Root storage is extendable, but when comparing base array types or structs, memory is limited by outer next-variable slots.
         isExtendableMemory?: boolean
 
         isLastVariable?: boolean
@@ -239,13 +239,13 @@ export namespace $proxyDeploy {
         TYPE_MISMATCH = 'TYPE_MISMATCH',
         TYPE_COLLISION = 'TYPE_COLLISION',
 
-        /** throws error if memory is not extendable */
+        /** Throws an error if memory is not extendable. */
         ARRAY_LENGTH_MISMATCH = 'ARRAY_LENGTH_MISMATCH',
 
-        /** in arrays the memory for a single item is not extendable, but in contract's root storage or mapping values is */
+        /** In arrays, memory for a single item is not extendable, but it is extendable in contract root storage or mapping values. */
         MEMORY_OVERFLOW = 'MEMORY_OVERFLOW',
 
-        /** Variables on same slot with different names (rename possible) but additionally the some variable exists in old layout on different slot */
+        /** Variables on the same slot with different names (rename possible), while the same variable also exists in the old layout on a different slot. */
         NAME_MISMATCH = 'NAME_MISMATCH'
     }
     class BaseError {
@@ -274,7 +274,7 @@ export namespace $proxyDeploy {
 
     function getMemoryPosition ($var: ISlotVarDefinition) {
         if (isDynamicVariable($var)) {
-            // dynamic variables occupy the single slot
+            // Dynamic variables occupy a single slot.
             return {
                 variable: $var,
                 offset: $var.slot * 256,
@@ -300,12 +300,12 @@ export namespace $proxyDeploy {
     function requireBoth (a: ISlotVarDefinition, b: ISlotVarDefinition, aCheck: boolean, bCheck: boolean) {
         if (!aCheck) {
             return {
-                error: `Current variable is not dynamic ${a.name}(${a.type}) but the new one is: ${b.name}(${b.type})`
+                error: `Current variable ${a.name}(${a.type}) is not dynamic, but the new one is: ${b.name}(${b.type})`
             };
         }
         if (!bCheck) {
             return {
-                error: `Current variable is dynamic ${a.name}(${a.type}) but the new one is not: ${b.name}(${b.type})`
+                error: `Current variable ${a.name}(${a.type}) is dynamic, but the new one is not: ${b.name}(${b.type})`
             };
         }
     }