dequanto 0.2.38 → 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

@@ -27,27 +27,33 @@ 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[]
 }
 
@@ -79,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
@@ -134,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;
     }
@@ -160,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?: {
@@ -181,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,
@@ -215,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,
@@ -224,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,
@@ -250,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;
@@ -270,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);
 
@@ -285,14 +298,11 @@ export class Deployments {
         };
     }
 
-    async ensureWithProxy<
-        T extends (TContract & TInitializers<TInit>),
-        TInit extends TFunction
-    >(
+    async ensureWithProxy<T extends TContract>(
         CtorImpl: Constructor<T>,
         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,
@@ -304,6 +314,7 @@ export class Deployments {
 
         let id = opts?.id ?? getImplementationId(CtorImpl);
         let proxyId = `${id}Proxy`;
+        let immutablesKey = getImmutablesKey(opts?.arguments);
 
         let {
             contract: contractImpl,
@@ -312,6 +323,7 @@ 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,
@@ -342,7 +354,7 @@ export class Deployments {
         })
 
         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;
 
@@ -364,7 +376,7 @@ 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<
@@ -378,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
@@ -389,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 +438,7 @@ export class Deployments {
             implementation: {
                 address: implementationAddress,
                 initData: data,
-                // @TODO implement migrations for Beacons
+                // @TODO Implement migrations for Beacons.
                 migrationData: null
             }
         });
@@ -462,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);
@@ -480,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;
                 }
             }
@@ -558,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;
@@ -612,27 +624,19 @@ export class Deployments {
     }
 }
 
-
-type TFunction = (...args: any[]) => any
-type TInitializerName = 'initialize' | `initializeV${number}`
-type TInitializers<TInit extends TFunction> = {
-    [K in TInitializerName]?: TInit
-}
-type TInitializerParams<T extends TInitializers<TFunction>> = {
-    initialize?: T['initialize'] extends TFunction
-        ? ParametersFromSecond<T['initialize']>
-        : never
-    initializeV2?: T['initializeV2'] extends TFunction
-        ? ParametersFromSecond<T['initializeV2']>
-        : never
-    initializeV3?: T['initializeV3'] extends TFunction
-        ? ParametersFromSecond<T['initializeV3']>
-        : never
+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, `initializeV${number}`>]?: T[K] extends TFunction
+    [K in Extract<keyof T, TInitializerName>]?: T[K] extends TFunction
         ? ParametersFromSecond<T[K]>
-        : any
-}
+        : never;
+};
 
 type TContract = ContractBase & { $constructor?: (...args: any[]) => any }
 type TConstructorArgs<T extends TContract> = T['$constructor'] extends Function ? {
@@ -658,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;
@@ -667,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];
@@ -677,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;
         }
     }
@@ -723,8 +727,8 @@ function serializeMigrationData(id: string, contract: ContractBase, opts: any) {
 
 
 /**
- * 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;
@@ -735,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})`
             };
         }
     }