@openzeppelin/upgrades-core 1.25.0 → 1.26.0

package/src/deployment.ts

@@ -22,6 +22,13 @@ export interface Deployment {
   txHash?: string;
 }
 
+export interface RemoteDeploymentId {
+  remoteDeploymentId?: string;
+}
+
+/**
+ * Options for deploying an implementation contract, proxy admin contract, or remote deployment.
+ */
 export interface DeployOpts {
   /**
    * Timeout in milliseconds to wait for the transaction confirmation when deploying an implementation contract or proxy admin contract. Use `0` to wait indefinitely.
@@ -50,6 +57,7 @@ export interface DeployOpts {
  *   If not provided, invalid deployments will not be deleted in a dev network (which is not a problem if merge is false,
  *   since it will be overwritten with the new deployment).
  * @param merge whether the cached deployment is intended to be merged with the new deployment. Defaults to false.
+ * @param getRemoteDeployment a function to get the remote deployment status by id. If the deployment id is not found, returns undefined.
  * @returns the cached deployment if it should be used, otherwise the new deployment from the deploy function
  * @throws {InvalidDeployment} if the cached deployment is invalid and we are not on a dev network
  */
@@ -61,8 +69,9 @@ export async function resumeOrDeploy<T extends Deployment, U extends T = T>(
   opts?: DeployOpts,
   deployment?: ManifestField<T>,
   merge?: boolean,
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
 ): Promise<T | U> {
-  const validated = await validateCached(cached, provider, type, opts, deployment, merge);
+  const validated = await validateCached(cached, provider, type, opts, deployment, merge, getRemoteDeployment);
   if (validated === undefined || merge) {
     const deployment = await deploy();
     debug('initiated deployment', 'transaction hash:', deployment.txHash, 'merge:', merge);
@@ -79,10 +88,11 @@ async function validateCached<T extends Deployment>(
   opts?: DeployOpts,
   deployment?: ManifestField<T>,
   merge?: boolean,
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
 ): Promise<T | undefined> {
   if (cached !== undefined) {
     try {
-      await validateStoredDeployment(cached, provider, type, opts, merge);
+      return await validateStoredDeployment(cached, provider, type, opts, merge, getRemoteDeployment);
     } catch (e) {
       if (e instanceof InvalidDeployment && (await isDevelopmentNetwork(provider))) {
         debug('ignoring invalid deployment in development network', e.deployment.address);
@@ -94,50 +104,79 @@ async function validateCached<T extends Deployment>(
         throw e;
       }
     }
+  } else {
+    return undefined;
   }
-  return cached;
 }
 
-async function validateStoredDeployment<T extends Deployment>(
+async function validateStoredDeployment<T extends Deployment & RemoteDeploymentId>(
   stored: T,
   provider: EthereumProvider,
   type?: string,
   opts?: DeployOpts,
   merge?: boolean,
-) {
-  const { txHash } = stored;
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
+): Promise<T> {
+  const { txHash, remoteDeploymentId } = stored;
+  let deployment = stored;
+
   if (txHash !== undefined) {
     // If there is a deployment with txHash stored, we look its transaction up. If the
     // transaction is found, the deployment is reused.
     debug('found previous deployment', txHash);
     const tx = await getTransactionByHash(provider, txHash);
+    let foundDeployment = undefined;
     if (tx !== null) {
-      debug('resuming previous deployment', txHash);
+      foundDeployment = txHash;
+    } else if (remoteDeploymentId !== undefined && getRemoteDeployment !== undefined) {
+      // If the transaction is not found, try checking the deployment id since the transaction may have been replaced
+      const response = await getRemoteDeployment(remoteDeploymentId);
+      if (response !== undefined) {
+        foundDeployment = remoteDeploymentId;
+
+        // update the stored tx hash
+        deployment = { ...stored, txHash: response.txHash };
+        debug('updating previous deployment to tx hash ', response.txHash);
+      }
+    }
+
+    if (foundDeployment) {
+      debug('resuming previous deployment', foundDeployment);
       if (merge) {
         // If merging, wait for the existing deployment to be mined
-        waitAndValidateDeployment(provider, stored, type, opts);
+        waitAndValidateDeployment(provider, deployment, type, opts, getRemoteDeployment);
       }
     } else {
       // If the transaction is not found we throw an error, except if we're in
       // a development network then we simply silently redeploy.
       // This error should be caught by the caller to determine if we're in a dev network.
-      throw new InvalidDeployment(stored);
+      throw new InvalidDeployment(deployment);
     }
   } else {
-    const existingBytecode = await getCode(provider, stored.address);
+    const existingBytecode = await getCode(provider, deployment.address);
     if (isEmpty(existingBytecode)) {
-      throw new InvalidDeployment(stored);
+      throw new InvalidDeployment(deployment);
     }
   }
+  return deployment;
+}
+
+/**
+ * A deployment that is performed remotely, which has a status and transaction hash.
+ */
+export interface RemoteDeployment {
+  status: 'completed' | 'failed' | 'submitted';
+  txHash: string;
 }
 
 export async function waitAndValidateDeployment(
   provider: EthereumProvider,
-  deployment: Deployment,
+  deployment: Deployment & RemoteDeploymentId,
   type?: string,
   opts?: DeployOpts,
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
 ): Promise<void> {
-  const { txHash, address } = deployment;
+  const { txHash, address, remoteDeploymentId } = deployment;
 
   // Poll for 60 seconds with a 5 second poll interval by default.
   const pollTimeout = opts?.timeout ?? 60e3;
@@ -145,7 +184,38 @@ export async function waitAndValidateDeployment(
 
   debug('polling timeout', pollTimeout, 'polling interval', pollInterval);
 
-  if (txHash !== undefined) {
+  let foundCode = false;
+
+  if (remoteDeploymentId !== undefined && getRemoteDeployment !== undefined) {
+    const startTime = Date.now();
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      if (await hasCode(provider, address)) {
+        debug('code in target address found', address);
+        foundCode = true;
+        break;
+      }
+
+      const completed = await isDeploymentCompleted(
+        address,
+        remoteDeploymentId,
+        await getRemoteDeployment(remoteDeploymentId),
+      );
+      if (completed) {
+        break;
+      } else {
+        await sleep(pollInterval);
+      }
+      if (pollTimeout != 0) {
+        const elapsedTime = Date.now() - startTime;
+        if (elapsedTime >= pollTimeout) {
+          // A timeout is NOT an InvalidDeployment
+          throw new TransactionMinedTimeout(deployment, type, !!opts);
+        }
+      }
+    }
+  } else if (txHash !== undefined) {
     const startTime = Date.now();
 
     // eslint-disable-next-line no-constant-condition
@@ -172,24 +242,28 @@ export async function waitAndValidateDeployment(
     }
   }
 
-  debug('verifying code in target address', address);
-  const startTime = Date.now();
-  while (!(await hasCode(provider, address))) {
-    const elapsedTime = Date.now() - startTime;
-    if (elapsedTime >= pollTimeout || txHash === undefined) {
-      throw new InvalidDeployment(deployment);
+  if (!foundCode) {
+    debug('verifying code in target address', address);
+    const startTime = Date.now();
+    while (!(await hasCode(provider, address))) {
+      const elapsedTime = Date.now() - startTime;
+      if (elapsedTime >= pollTimeout || txHash === undefined) {
+        throw new InvalidDeployment(deployment);
+      }
+      await sleep(pollInterval);
     }
-    await sleep(pollInterval);
+    debug('code in target address found', address);
   }
-  debug('code in target address found', address);
 }
 
 export class TransactionMinedTimeout extends UpgradesError {
-  constructor(readonly deployment: Deployment, type?: string, configurableTimeout?: boolean) {
+  constructor(readonly deployment: Deployment & RemoteDeploymentId, type?: string, configurableTimeout?: boolean) {
     super(
-      `Timed out waiting for ${type ? type + ' ' : ''}contract deployment to address ${
-        deployment.address
-      } with transaction ${deployment.txHash}`,
+      `Timed out waiting for ${type ? type + ' ' : ''}contract deployment to address ${deployment.address} with ${
+        deployment.remoteDeploymentId
+          ? `deployment id ${deployment.remoteDeploymentId}`
+          : `transaction ${deployment.txHash}`
+      }`,
       () =>
         'Run the function again to continue waiting for the transaction confirmation.' +
         (configurableTimeout
@@ -217,3 +291,37 @@ export class InvalidDeployment extends Error {
     return msg;
   }
 }
+
+/**
+ * Checks if the deployment id is completed.
+ *
+ * @param address The expected address of the deployment.
+ * @param remoteDeploymentId The deployment id.
+ * @param remoteDeploymentResponse The remote deployment response corresponding to the given id.
+ * @returns true if the deployment id is completed, false otherwise.
+ * @throws {InvalidDeployment} if the deployment id failed.
+ */
+export async function isDeploymentCompleted(
+  address: string,
+  remoteDeploymentId: string,
+  remoteDeploymentResponse: RemoteDeployment | undefined,
+): Promise<boolean> {
+  debug('verifying deployment id', remoteDeploymentId);
+  if (remoteDeploymentResponse === undefined) {
+    throw new Error(`Could not find remote deployment with id ${remoteDeploymentId}`);
+  }
+
+  const status = remoteDeploymentResponse.status;
+  if (status === 'completed') {
+    debug('succeeded verifying deployment id completed', remoteDeploymentId);
+    return true;
+  } else if (status === 'failed') {
+    debug(`deployment id ${remoteDeploymentId} failed with tx hash ${remoteDeploymentResponse.txHash}`);
+    throw new InvalidDeployment({ address, txHash: remoteDeploymentResponse.txHash });
+  } else if (status === 'submitted') {
+    debug('waiting for deployment id to be completed', remoteDeploymentId);
+    return false;
+  } else {
+    throw new Error(`Broken invariant: Unrecognized status ${status} for deployment id ${remoteDeploymentId}`);
+  }
+}

package/src/impl-store.test.ts

@@ -5,8 +5,9 @@ import rimrafAsync from 'rimraf';
 import util from 'util';
 import path from 'path';
 import os from 'os';
+import sinon from 'sinon';
 
-import { fetchOrDeploy, mergeAddresses } from './impl-store';
+import { fetchOrDeploy, fetchOrDeployGetDeployment, mergeAddresses } from './impl-store';
 import { getVersion } from './version';
 import { stubProvider } from './stub-provider';
 import { ImplDeployment } from './manifest';
@@ -89,3 +90,53 @@ test('merge all addresses', async t => {
 function unorderedEqual(arr1: string[], arr2: string[]) {
   return arr1.every(i => arr2.includes(i)) && arr2.every(i => arr1.includes(i));
 }
+
+test('platform - replace tx hash for deployment', async t => {
+  const provider = stubProvider();
+
+  // create a pending deployment with id
+  const fakeDeploy = await provider.deployPending();
+  provider.removeContract(fakeDeploy.address);
+  async function fakeDeployWithId() {
+    return {
+      ...fakeDeploy,
+      txHash: '0x1',
+      remoteDeploymentId: 'abc',
+    };
+  }
+
+  const getDeploymentResponse1 = sinon.stub().returns({
+    status: 'submitted',
+    txHash: '0x1',
+  });
+  // let it timeout
+  await t.throwsAsync(
+    fetchOrDeployGetDeployment(
+      version1,
+      provider,
+      fakeDeployWithId,
+      { timeout: 1, pollingInterval: 0 },
+      undefined,
+      getDeploymentResponse1,
+    ),
+  );
+
+  // make the contract code exist
+  provider.addContract(fakeDeploy.address);
+
+  // simulate a changed tx hash
+  const getDeploymentResponse2 = sinon.stub().returns({
+    status: 'completed',
+    txHash: '0x2',
+  });
+  const deployment = await fetchOrDeployGetDeployment(
+    version1,
+    provider,
+    fakeDeployWithId,
+    { timeout: 1, pollingInterval: 0 },
+    undefined,
+    getDeploymentResponse2,
+  );
+  t.is(deployment.address, fakeDeploy.address);
+  t.is(deployment.txHash, '0x2');
+});

package/src/impl-store.ts

@@ -1,7 +1,14 @@
 import debug from './utils/debug';
 import { Manifest, ManifestData, ImplDeployment } from './manifest';
 import { EthereumProvider, isDevelopmentNetwork } from './provider';
-import { Deployment, InvalidDeployment, resumeOrDeploy, waitAndValidateDeployment } from './deployment';
+import {
+  Deployment,
+  RemoteDeploymentId,
+  RemoteDeployment,
+  InvalidDeployment,
+  resumeOrDeploy,
+  waitAndValidateDeployment,
+} from './deployment';
 import { Version } from './version';
 import assert from 'assert';
 import { DeployOpts } from '.';
@@ -26,6 +33,7 @@ export interface ManifestField<T> {
  * @param deploy the deploy function
  * @param opts options containing the timeout and pollingInterval parameters. If undefined, assumes the timeout is not configurable and will not mention those parameters in the error message for TransactionMinedTimeout.
  * @param merge if true, adds a deployment to existing deployment by merging their addresses. Defaults to false.
+ * @param getRemoteDeployment a function to get the remote deployment status by id. If the deployment id is not found, returns undefined.
  * @returns the deployment
  * @throws {InvalidDeployment} if the deployment is invalid
  * @throws {TransactionMinedTimeout} if the transaction was not confirmed within the timeout period
@@ -36,6 +44,7 @@ async function fetchOrDeployGeneric<T extends Deployment, U extends T = T>(
   deploy: () => Promise<U>,
   opts?: DeployOpts,
   merge?: boolean,
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
 ): Promise<U | Deployment> {
   const manifest = await Manifest.forNetwork(provider);
 
@@ -51,7 +60,16 @@ async function fetchOrDeployGeneric<T extends Deployment, U extends T = T>(
       }
 
       const stored = deployment.get();
-      const updated = await resumeOrDeploy(provider, stored, deploy, lens.type, opts, deployment, merge);
+      const updated = await resumeOrDeploy(
+        provider,
+        stored,
+        deploy,
+        lens.type,
+        opts,
+        deployment,
+        merge,
+        getRemoteDeployment,
+      );
       if (updated !== stored) {
         if (merge && deployment.merge) {
           // only check primary addresses for clashes, since the address could already exist in an allAddresses field
@@ -67,7 +85,7 @@ async function fetchOrDeployGeneric<T extends Deployment, U extends T = T>(
       return updated;
     });
 
-    await waitAndValidateDeployment(provider, deployment, lens.type, opts);
+    await waitAndValidateDeployment(provider, deployment, lens.type, opts, getRemoteDeployment);
 
     return deployment;
   } catch (e) {
@@ -98,6 +116,18 @@ export function deleteDeployment(deployment: ManifestField<Deployment>) {
   deployment.set(undefined);
 }
 
+/**
+ * Fetches the deployment address from the manifest, or deploys it if not found and returns the address.
+ *
+ * @param version the contract version
+ * @param provider the Ethereum provider
+ * @param deploy the deploy function
+ * @param opts options containing the timeout and pollingInterval parameters. If undefined, assumes the timeout is not configurable and will not mention those parameters in the error message for TransactionMinedTimeout.
+ * @param merge if true, adds a deployment to existing deployment by merging their addresses. Defaults to false.
+ * @returns the deployment address
+ * @throws {InvalidDeployment} if the deployment is invalid
+ * @throws {TransactionMinedTimeout} if the transaction was not confirmed within the timeout period
+ */
 export async function fetchOrDeploy(
   version: Version,
   provider: EthereumProvider,
@@ -108,14 +138,35 @@ export async function fetchOrDeploy(
   return (await fetchOrDeployGeneric(implLens(version.linkedWithoutMetadata), provider, deploy, opts, merge)).address;
 }
 
+/**
+ * Fetches the deployment from the manifest, or deploys it if not found and returns the deployment.
+ *
+ * @param version the contract version
+ * @param provider the Ethereum provider
+ * @param deploy the deploy function
+ * @param opts options containing the timeout and pollingInterval parameters. If undefined, assumes the timeout is not configurable and will not mention those parameters in the error message for TransactionMinedTimeout.
+ * @param merge if true, adds a deployment to existing deployment by merging their addresses. Defaults to false.
+ * @param getRemoteDeployment a function to get the remote deployment status by id. If the deployment id is not found, returns undefined.
+ * @returns the deployment
+ * @throws {InvalidDeployment} if the deployment is invalid
+ * @throws {TransactionMinedTimeout} if the transaction was not confirmed within the timeout period
+ */
 export async function fetchOrDeployGetDeployment<T extends ImplDeployment>(
   version: Version,
   provider: EthereumProvider,
   deploy: () => Promise<T>,
   opts?: DeployOpts,
   merge?: boolean,
+  getRemoteDeployment?: (remoteDeploymentId: string) => Promise<RemoteDeployment | undefined>,
 ): Promise<T | Deployment> {
-  return fetchOrDeployGeneric(implLens(version.linkedWithoutMetadata), provider, deploy, opts, merge);
+  return fetchOrDeployGeneric(
+    implLens(version.linkedWithoutMetadata),
+    provider,
+    deploy,
+    opts,
+    merge,
+    getRemoteDeployment,
+  );
 }
 
 const implLens = (versionWithoutMetadata: string) =>
@@ -171,7 +222,7 @@ function lens<T>(description: string, type: string, fn: (data: ManifestData) =>
 async function checkForAddressClash(
   provider: EthereumProvider,
   data: ManifestData,
-  updated: Deployment,
+  updated: Deployment & RemoteDeploymentId,
   checkAllAddresses: boolean,
 ): Promise<void> {
   const clash = lookupDeployment(data, updated.address, checkAllAddresses);
@@ -180,11 +231,18 @@ async function checkForAddressClash(
       debug('deleting a previous deployment at address', updated.address);
       clash.set(undefined);
     } else {
-      throw new Error(
-        `The following deployment clashes with an existing one at ${updated.address}\n\n` +
-          JSON.stringify(updated, null, 2) +
-          `\n\n`,
-      );
+      const existing = clash.get();
+      // it's a clash if there is no deployment id or if deployment ids don't match
+      if (
+        existing !== undefined &&
+        (existing.remoteDeploymentId === undefined || existing.remoteDeploymentId !== updated.remoteDeploymentId)
+      ) {
+        throw new Error(
+          `The following deployment clashes with an existing one at ${updated.address}\n\n` +
+            JSON.stringify(updated, null, 2) +
+            `\n\n`,
+        );
+      }
     }
   }
 }
@@ -193,7 +251,7 @@ function lookupDeployment(
   data: ManifestData,
   address: string,
   checkAllAddresses: boolean,
-): ManifestField<Deployment> | undefined {
+): ManifestField<Deployment & RemoteDeploymentId> | undefined {
   if (data.admin?.address === address) {
     return adminLens(data);
   }

package/src/manifest.test.ts

@@ -434,6 +434,7 @@ test('normalize manifest', t => {
   const deployment = {
     address: '0x1234',
     txHash: '0x1234',
+    remoteDeploymentId: 'abc',
     kind: 'uups' as const,
     layout: { solcVersion: '0.8.9', types: {}, storage: [] },
     deployTransaction: {},

package/src/manifest.ts

@@ -5,7 +5,7 @@ import { EthereumProvider, getChainId, getHardhatMetadata, networkNames } from '
 import lockfile from 'proper-lockfile';
 import { compare as compareVersions } from 'compare-versions';
 
-import type { Deployment } from './deployment';
+import type { Deployment, RemoteDeploymentId } from './deployment';
 import type { StorageLayout } from './storage';
 import { pick } from './utils/pick';
 import { mapValues } from './utils/map-values';
@@ -18,9 +18,9 @@ const currentManifestVersion = '3.2';
 export interface ManifestData {
   manifestVersion: string;
   impls: {
-    [version in string]?: ImplDeployment;
+    [version in string]?: ImplDeployment & RemoteDeploymentId;
   };
-  proxies: ProxyDeployment[];
+  proxies: (ProxyDeployment & RemoteDeploymentId)[];
   admin?: Deployment;
 }
 
@@ -318,11 +318,14 @@ export function normalizeManifestData(input: ManifestData): ManifestData {
   };
 }
 
-function normalizeDeployment<D extends Deployment>(input: D): Deployment;
-function normalizeDeployment<D extends Deployment, K extends keyof D>(input: D, include: K[]): Deployment & Pick<D, K>;
-function normalizeDeployment<D extends Deployment, K extends keyof D>(
+function normalizeDeployment<D extends Deployment & RemoteDeploymentId>(input: D): Deployment & RemoteDeploymentId;
+function normalizeDeployment<D extends Deployment & RemoteDeploymentId, K extends keyof D>(
+  input: D,
+  include: K[],
+): Deployment & RemoteDeploymentId & Pick<D, K>;
+function normalizeDeployment<D extends Deployment & RemoteDeploymentId, K extends keyof D>(
   input: D,
   include: K[] = [],
-): Deployment & Pick<D, K> {
-  return pick(input, ['address', 'txHash', ...include]);
+): Deployment & RemoteDeploymentId & Pick<D, K> {
+  return pick(input, ['address', 'txHash', 'remoteDeploymentId', ...include]);
 }

package/src/validate/error.ts

@@ -9,3 +9,9 @@ export class ValidationErrors extends UpgradesError {
     );
   }
 }
+
+export class ContractSourceNotFoundError extends UpgradesError {
+  constructor() {
+    super('The requested contract was not found. Make sure the source code is available for compilation');
+  }
+}

package/src/validate/index.ts

@@ -1,6 +1,6 @@
 export { validate, ValidationRunData, ContractValidation } from './run';
 export { ProxyKindOption, StandaloneValidationOptions, ValidationOptions, withValidationDefaults } from './overrides';
-export { ValidationErrors } from './error';
+export { ValidationErrors, ContractSourceNotFoundError } from './error';
 export { RunValidation, ValidationLog, Validation, ValidationResult } from './compat';
 export { ValidationData, ValidationDataCurrent, isCurrentValidationData, concatRunData } from './data';
 export {

package/src/validate/query.ts

@@ -3,7 +3,7 @@ import { ValidationRunData, ValidationError, isOpcodeError } from './run';
 import { StorageLayout } from '../storage/layout';
 import { unlinkBytecode } from '../link-refs';
 import { ValidationOptions, processExceptions } from './overrides';
-import { ValidationErrors } from './error';
+import { ContractSourceNotFoundError, ValidationErrors } from './error';
 import { ValidationData, normalizeValidationData } from './data';
 import { ProxyDeployment } from '../manifest';
 
@@ -72,7 +72,7 @@ export function getContractNameAndRunValidation(data: ValidationData, version: V
   }
 
   if (fullContractName === undefined || runValidation === undefined) {
-    throw new Error('The requested contract was not found. Make sure the source code is available for compilation');
+    throw new ContractSourceNotFoundError();
   }
 
   return [fullContractName, runValidation];