@openzeppelin/upgrades-core 1.9.2 → 1.12.0

package/src/impl-store.ts

@@ -4,9 +4,11 @@ import { EthereumProvider, isDevelopmentNetwork } from './provider';
 import { Deployment, InvalidDeployment, resumeOrDeploy, waitAndValidateDeployment } from './deployment';
 import type { Version } from './version';
 import assert from 'assert';
+import { DeployOpts } from '.';
 
 interface ManifestLens<T> {
   description: string;
+  type: string;
   (data: ManifestData): ManifestField<T>;
 }
 
@@ -15,10 +17,22 @@ interface ManifestField<T> {
   set(value: T | undefined): void;
 }
 
+/**
+ * Fetches the deployment from the manifest, or deploys it if not found.
+ *
+ * @param lens the manifest lens
+ * @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.
+ * @returns the deployment address
+ * @throws {InvalidDeployment} if the deployment is invalid
+ * @throws {TransactionMinedTimeout} if the transaction was not confirmed within the timeout period
+ */
 async function fetchOrDeployGeneric<T extends Deployment>(
   lens: ManifestLens<T>,
   provider: EthereumProvider,
   deploy: () => Promise<T>,
+  opts?: DeployOpts,
 ): Promise<string> {
   const manifest = await Manifest.forNetwork(provider);
 
@@ -40,7 +54,7 @@ async function fetchOrDeployGeneric<T extends Deployment>(
       return updated;
     });
 
-    await waitAndValidateDeployment(provider, deployment);
+    await waitAndValidateDeployment(provider, deployment, lens.type, opts);
 
     return deployment.address;
   } catch (e) {
@@ -67,12 +81,13 @@ export async function fetchOrDeploy(
   version: Version,
   provider: EthereumProvider,
   deploy: () => Promise<ImplDeployment>,
+  opts?: DeployOpts,
 ): Promise<string> {
-  return fetchOrDeployGeneric(implLens(version.linkedWithoutMetadata), provider, deploy);
+  return fetchOrDeployGeneric(implLens(version.linkedWithoutMetadata), provider, deploy, opts);
 }
 
 const implLens = (versionWithoutMetadata: string) =>
-  lens(`implementation ${versionWithoutMetadata}`, data => ({
+  lens(`implementation ${versionWithoutMetadata}`, 'implementation', data => ({
     get: () => data.impls[versionWithoutMetadata],
     set: (value?: ImplDeployment) => (data.impls[versionWithoutMetadata] = value),
   }));
@@ -80,17 +95,18 @@ const implLens = (versionWithoutMetadata: string) =>
 export async function fetchOrDeployAdmin(
   provider: EthereumProvider,
   deploy: () => Promise<Deployment>,
+  opts?: DeployOpts,
 ): Promise<string> {
-  return fetchOrDeployGeneric(adminLens, provider, deploy);
+  return fetchOrDeployGeneric(adminLens, provider, deploy, opts);
 }
 
-const adminLens = lens('proxy admin', data => ({
+const adminLens = lens('proxy admin', 'proxy admin', data => ({
   get: () => data.admin,
   set: (value?: Deployment) => (data.admin = value),
 }));
 
-function lens<T>(description: string, fn: (data: ManifestData) => ManifestField<T>): ManifestLens<T> {
-  return Object.assign(fn, { description });
+function lens<T>(description: string, type: string, fn: (data: ManifestData) => ManifestField<T>): ManifestLens<T> {
+  return Object.assign(fn, { description, type });
 }
 
 async function checkForAddressClash(

package/src/index.ts

@@ -9,10 +9,27 @@ export * from './src-decoder';
 export * from './solc-api';
 export * from './deployment';
 export * from './link-refs';
+export * from './error';
 
 export { getStorageLayoutForAddress } from './manifest-storage-layout';
 
 export * from './scripts/migrate-oz-cli-project';
 
 export { logWarning } from './utils/log';
-export { setProxyKind } from './set-proxy-kind';
+export { setProxyKind, processProxyKind } from './proxy-kind';
+
+export { UpgradeableContract } from './standalone';
+
+export { isTransparentOrUUPSProxy, isBeaconProxy } from './eip-1967-type';
+export { getImplementationAddressFromBeacon, getImplementationAddressFromProxy } from './impl-address';
+export { isBeacon } from './beacon';
+
+export {
+  BeaconProxyUnsupportedError,
+  LoadProxyUnsupportedError,
+  PrepareUpgradeUnsupportedError,
+  DeployBeaconProxyUnsupportedError,
+  DeployBeaconProxyImplUnknownError,
+  DeployBeaconProxyKindError,
+  assertNotProxy,
+} from './usage-error';

package/src/manifest.ts

@@ -25,7 +25,7 @@ export interface ImplDeployment extends Deployment {
 }
 
 export interface ProxyDeployment extends Deployment {
-  kind: 'uups' | 'transparent';
+  kind: 'uups' | 'transparent' | 'beacon';
 }
 
 function defaultManifest(): ManifestData {

package/src/provider.ts

@@ -5,6 +5,7 @@ export interface EthereumProvider {
   send(method: 'net_version', params: []): Promise<string>;
   send(method: 'eth_chainId', params: []): Promise<string>;
   send(method: 'eth_getCode', params: [string, string]): Promise<string>;
+  send(method: 'eth_call', params: unknown[]): Promise<string>;
   send(method: 'eth_getStorageAt', params: [string, string, string]): Promise<string>;
   send(method: 'eth_getTransactionByHash', params: [string]): Promise<null | EthereumTransaction>;
   send(method: 'eth_getTransactionReceipt', params: [string]): Promise<null | EthereumTransactionReceipt>;
@@ -53,6 +54,21 @@ export async function getCode(provider: EthereumProvider, address: string, block
   return provider.send('eth_getCode', [address, block]);
 }
 
+export async function call(
+  provider: EthereumProvider,
+  address: string,
+  data: string,
+  block = 'latest',
+): Promise<string> {
+  return provider.send('eth_call', [
+    {
+      to: address,
+      data: data,
+    },
+    block,
+  ]);
+}
+
 export async function hasCode(provider: EthereumProvider, address: string, block?: string): Promise<boolean> {
   const code = await getCode(provider, address, block);
   return code !== '0x';

package/src/proxy-kind.ts

@@ -0,0 +1,59 @@
+import { EthereumProvider } from './provider';
+import { inferProxyKind, ValidationData, ValidationOptions } from './validate';
+import { Manifest, DeploymentNotFound, ProxyDeployment } from './manifest';
+import { isBeaconProxy } from './eip-1967-type';
+import { Version } from './version';
+import { BeaconProxyUnsupportedError } from './usage-error';
+
+export async function setProxyKind(
+  provider: EthereumProvider,
+  proxyAddress: string,
+  opts: ValidationOptions,
+): Promise<ProxyDeployment['kind']> {
+  const manifest = await Manifest.forNetwork(provider);
+
+  const manifestDeployment = await manifest.getProxyFromAddress(proxyAddress).catch(e => {
+    if (e instanceof DeploymentNotFound) {
+      return undefined;
+    } else {
+      throw e;
+    }
+  });
+
+  if (opts.kind === undefined) {
+    opts.kind = manifestDeployment?.kind ?? 'transparent';
+  } else if (manifestDeployment && opts.kind !== manifestDeployment.kind) {
+    throw new Error(`Requested an upgrade of kind ${opts.kind} but proxy is ${manifestDeployment.kind}`);
+  }
+
+  return opts.kind;
+}
+
+/**
+ * Processes opts.kind when deploying the implementation for a UUPS or Transparent proxy.
+ *
+ * @throws {BeaconProxyUnsupportedError} If this function is called for a Beacon proxy.
+ */
+export async function processProxyKind(
+  provider: EthereumProvider,
+  proxyAddress: string | undefined,
+  opts: ValidationOptions,
+  data: ValidationData,
+  version: Version,
+) {
+  if (opts.kind === undefined) {
+    if (proxyAddress !== undefined && (await isBeaconProxy(provider, proxyAddress))) {
+      opts.kind = 'beacon';
+    } else {
+      opts.kind = inferProxyKind(data, version);
+    }
+  }
+
+  if (proxyAddress !== undefined) {
+    await setProxyKind(provider, proxyAddress, opts);
+  }
+
+  if (opts.kind === 'beacon') {
+    throw new BeaconProxyUnsupportedError();
+  }
+}

package/src/standalone.test.ts

@@ -0,0 +1,40 @@
+import _test, { TestInterface } from 'ava';
+import { artifacts } from 'hardhat';
+
+import { SolcInput, SolcOutput } from './solc-api';
+import { UpgradeableContract } from './standalone';
+
+interface Context {
+  solcInput: SolcInput;
+  solcOutput: SolcOutput;
+}
+
+const test = _test as TestInterface<Context>;
+
+test.before(async t => {
+  const buildInfo = await artifacts.getBuildInfo('contracts/test/Standalone.sol:StandaloneV1');
+  if (buildInfo === undefined) {
+    throw new Error('Build info not found');
+  }
+  t.context.solcInput = buildInfo.input;
+  t.context.solcOutput = buildInfo.output;
+});
+
+test('reports unsafe operation', t => {
+  const impl = new UpgradeableContract('StandaloneV1', t.context.solcInput, t.context.solcOutput);
+  const report = impl.getErrorReport();
+  t.false(report.ok);
+  t.true(report.errors[0].kind === 'delegatecall');
+});
+
+test('reports storage upgrade errors', t => {
+  const v1 = new UpgradeableContract('StandaloneV1', t.context.solcInput, t.context.solcOutput);
+
+  const v2Good = new UpgradeableContract('StandaloneV2Good', t.context.solcInput, t.context.solcOutput);
+  const goodReport = v1.getStorageUpgradeReport(v2Good);
+  t.true(goodReport.ok);
+
+  const v2Bad = new UpgradeableContract('StandaloneV2Bad', t.context.solcInput, t.context.solcOutput);
+  const badReport = v1.getStorageUpgradeReport(v2Bad);
+  t.false(badReport.ok);
+});

package/src/standalone.ts

@@ -0,0 +1,41 @@
+import { SolcOutput, SolcInput } from './solc-api';
+import { solcInputOutputDecoder } from './src-decoder';
+import {
+  getContractVersion,
+  getErrors,
+  getStorageLayout,
+  UpgradeableContractErrorReport,
+  validate,
+  ValidationOptions,
+  withValidationDefaults,
+} from './validate';
+import { getStorageUpgradeReport, StorageLayout } from './storage';
+import { Version } from './version';
+import { ValidationError } from './validate/run';
+
+export interface Report {
+  ok: boolean;
+  explain(color?: boolean): string;
+}
+
+export class UpgradeableContract {
+  readonly version: Version;
+  readonly errors: ValidationError[];
+  readonly layout: StorageLayout;
+
+  constructor(readonly name: string, solcInput: SolcInput, solcOutput: SolcOutput, opts: ValidationOptions = {}) {
+    const decodeSrc = solcInputOutputDecoder(solcInput, solcOutput);
+    const validation = validate(solcOutput, decodeSrc);
+    this.version = getContractVersion(validation, name);
+    this.errors = getErrors(validation, this.version, opts);
+    this.layout = getStorageLayout(validation, this.version);
+  }
+
+  getErrorReport() {
+    return new UpgradeableContractErrorReport(this.errors);
+  }
+
+  getStorageUpgradeReport(newVersion: UpgradeableContract, opts: ValidationOptions = {}) {
+    return getStorageUpgradeReport(this.layout, newVersion.layout, withValidationDefaults(opts));
+  }
+}

package/src/storage/index.ts

@@ -29,6 +29,18 @@ export function assertStorageUpgradeSafe(
     opts = withValidationDefaults({ unsafeAllowCustomTypes });
   }
 
+  const report = getStorageUpgradeReport(original, updated, opts);
+
+  if (!report.pass) {
+    throw new StorageUpgradeErrors(report);
+  }
+}
+
+export function getStorageUpgradeReport(
+  original: StorageLayout,
+  updated: StorageLayout,
+  opts: Required<ValidationOptions>,
+): LayoutCompatibilityReport {
   const originalDetailed = getDetailedLayout(original);
   const updatedDetailed = getDetailedLayout(updated);
   const comparator = new StorageLayoutComparator(opts.unsafeAllowCustomTypes, opts.unsafeAllowRenames);
@@ -43,12 +55,10 @@ export function assertStorageUpgradeSafe(
     logNote(`\`unsafeAllowCustomTypes\` is no longer necessary. Structs are enums are automatically checked.\n`);
   }
 
-  if (!report.pass) {
-    throw new StorageUpgradeErrors(report);
-  }
+  return report;
 }
 
-class StorageUpgradeErrors extends UpgradesError {
+export class StorageUpgradeErrors extends UpgradesError {
   constructor(readonly report: LayoutCompatibilityReport) {
     super(`New storage layout is incompatible`, () => report.explain());
   }

package/src/storage/report.ts

@@ -1,4 +1,4 @@
-import chalk from 'chalk';
+import _chalk from 'chalk';
 
 import type { BasicOperation } from '../levenshtein';
 import type { ParsedTypeDetailed } from './layout';
@@ -8,13 +8,18 @@ import { indent } from '../utils/indent';
 import { assert } from '../utils/assert';
 
 export class LayoutCompatibilityReport {
-  readonly pass: boolean;
+  constructor(readonly ops: StorageOperation<StorageItem>[]) {}
 
-  constructor(readonly ops: StorageOperation<StorageItem>[]) {
-    this.pass = ops.length === 0;
+  get ok(): boolean {
+    return this.pass;
   }
 
-  explain(): string {
+  get pass(): boolean {
+    return this.ops.length === 0;
+  }
+
+  explain(color = true): string {
+    const chalk = new _chalk.Instance({ level: color && _chalk.supportsColor ? _chalk.supportsColor.level : 0 });
     const res = [];
 
     for (const op of this.ops) {

package/src/usage-error.ts

@@ -0,0 +1,68 @@
+import { EthereumProvider, getBeaconAddress, isBeaconProxy, isTransparentOrUUPSProxy, UpgradesError } from '.';
+
+export class BeaconProxyUnsupportedError extends UpgradesError {
+  constructor() {
+    super(
+      'Beacon proxies are not supported with the current function.',
+      () => 'Use deployBeacon(), deployBeaconProxy(), or upgradeBeacon() instead.',
+    );
+  }
+}
+
+export class DeployBeaconProxyKindError extends UpgradesError {
+  constructor(kind: string) {
+    super(
+      `Unsupported proxy kind '${kind}'`,
+      () => `deployBeaconProxy() is only supported with proxy kind undefined or 'beacon'`,
+    );
+  }
+}
+
+export class DeployBeaconProxyUnsupportedError extends UpgradesError {
+  constructor(beaconAddress: string) {
+    super(`Contract at ${beaconAddress} doesn't look like a beacon`, () => 'Deploy a beacon using deployBeacon().');
+  }
+}
+
+export class DeployBeaconProxyImplUnknownError extends UpgradesError {
+  constructor(implAddress: string) {
+    super(
+      `Beacon's current implementation at ${implAddress} is unknown`,
+      () => `Call deployBeaconProxy() with the implementation option providing the beacon's current implementation.`,
+    );
+  }
+}
+
+export class LoadProxyUnsupportedError extends UpgradesError {
+  constructor(proxyAddress: string) {
+    super(
+      `Contract at ${proxyAddress} doesn't look like a supported proxy`,
+      () => 'Only transparent, UUPS, or beacon proxies can be loaded with the loadProxy() function.',
+    );
+  }
+}
+
+export class PrepareUpgradeUnsupportedError extends UpgradesError {
+  constructor(proxyOrBeaconAddress: string) {
+    super(
+      `Contract at address ${proxyOrBeaconAddress} doesn't look like a supported proxy or beacon`,
+      () => `Only transparent, UUPS, or beacon proxies or beacons can be used with the prepareUpgrade() function.`,
+    );
+  }
+}
+
+export async function assertNotProxy(provider: EthereumProvider, address: string) {
+  if (await isTransparentOrUUPSProxy(provider, address)) {
+    throw new UpgradesError(
+      'Address is a transparent or UUPS proxy which cannot be upgraded using upgradeBeacon().',
+      () => 'Use upgradeProxy() instead.',
+    );
+  } else if (await isBeaconProxy(provider, address)) {
+    const beaconAddress = await getBeaconAddress(provider, address);
+    throw new UpgradesError(
+      'Address is a beacon proxy which cannot be upgraded directly.',
+      () =>
+        `upgradeBeacon() must be called with a beacon address, not a beacon proxy address. Call upgradeBeacon() on the beacon address ${beaconAddress} instead.`,
+    );
+  }
+}

package/src/utils/address.ts

@@ -0,0 +1,16 @@
+import { toChecksumAddress } from 'ethereumjs-util';
+
+/**
+ * Parses an address from a hex string which may come from storage or a returned address via eth_call.
+ *
+ * @param addressString The address hex string.
+ * @returns The parsed checksum address, or undefined if the input string is not an address.
+ */
+export function parseAddress(addressString: string): string | undefined {
+  const buf = Buffer.from(addressString.replace(/^0x/, ''), 'hex');
+  if (!buf.slice(0, 12).equals(Buffer.alloc(12, 0))) {
+    return undefined;
+  }
+  const address = '0x' + buf.toString('hex', 12, 32); // grab the last 20 bytes
+  return toChecksumAddress(address);
+}

package/src/utils/make-non-enumerable.ts

@@ -1,3 +1,3 @@
-export function makeNonEnumerable<O extends any>(obj: O, key: keyof O): void {
+export function makeNonEnumerable<O>(obj: O, key: keyof O): void {
   Object.defineProperty(obj, key, { enumerable: false });
 }

package/src/validate/error.ts

@@ -1,73 +1,11 @@
-import chalk from 'chalk';
-
 import { ValidationError } from './run';
-import { UpgradesError, ErrorDescriptions } from '../error';
+import { UpgradesError } from '../error';
+import { UpgradeableContractErrorReport } from './report';
 
 export class ValidationErrors extends UpgradesError {
   constructor(contractName: string, readonly errors: ValidationError[]) {
-    super(`Contract \`${contractName}\` is not upgrade safe`, () => {
-      return errors.map(describeError).join('\n\n');
-    });
-  }
-}
-
-const errorInfo: ErrorDescriptions<ValidationError> = {
-  constructor: {
-    msg: e => `Contract \`${e.contract}\` has a constructor`,
-    hint: () => 'Define an initializer instead',
-    link: 'https://zpl.in/upgrades/error-001',
-  },
-  delegatecall: {
-    msg: () => `Use of delegatecall is not allowed`,
-    link: 'https://zpl.in/upgrades/error-002',
-  },
-  selfdestruct: {
-    msg: () => `Use of selfdestruct is not allowed`,
-    link: 'https://zpl.in/upgrades/error-003',
-  },
-  'state-variable-assignment': {
-    msg: e => `Variable \`${e.name}\` is assigned an initial value`,
-    hint: () => 'Move the assignment to the initializer',
-    link: 'https://zpl.in/upgrades/error-004',
-  },
-  'state-variable-immutable': {
-    msg: e => `Variable \`${e.name}\` is immutable`,
-    hint: () => `Use a constant or mutable variable instead`,
-    link: 'https://zpl.in/upgrades/error-005',
-  },
-  'external-library-linking': {
-    msg: e => `Linking external libraries like \`${e.name}\` is not yet supported`,
-    hint: () =>
-      `Use libraries with internal functions only, or skip this check with the \`unsafeAllowLinkedLibraries\` flag \n` +
-      `    if you have manually checked that the libraries are upgrade safe`,
-    link: 'https://zpl.in/upgrades/error-006',
-  },
-  'struct-definition': {
-    msg: e => `Structs like \`${e.name}\` are supported in the latest version of the plugin`,
-    hint: () => `Update your dependency and run again`,
-  },
-  'enum-definition': {
-    msg: e => `Enums like \`${e.name}\` are supported in the latest version of the plugin`,
-    hint: () => `Update your dependency and run again`,
-  },
-  'missing-public-upgradeto': {
-    msg: () => `Implementation is missing a public \`upgradeTo(address)\` function`,
-    hint: () =>
-      `Inherit UUPSUpgradeable to include this function in your contract\n` +
-      `    @openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol`,
-    link: 'https://zpl.in/upgrades/error-008',
-  },
-};
-
-function describeError(e: ValidationError): string {
-  const info = errorInfo[e.kind];
-  const log = [chalk.bold(e.src) + ': ' + info.msg(e as any)];
-  const hint = info.hint?.(e as any);
-  if (hint) {
-    log.push(hint);
-  }
-  if (info.link) {
-    log.push(chalk.dim(info.link));
+    super(`Contract \`${contractName}\` is not upgrade safe`, () =>
+      new UpgradeableContractErrorReport(errors).explain(),
+    );
   }
-  return log.join('\n    ');
 }

package/src/validate/index.ts

@@ -11,7 +11,9 @@ export {
   getUnlinkedBytecode,
   getErrors,
   isUpgradeSafe,
+  inferProxyKind,
 } from './query';
+export { UpgradeableContractErrorReport } from './report';
 
 // Backwards compatibility
 export { silenceWarnings } from '../utils/log';

package/src/validate/overrides.ts

@@ -69,7 +69,7 @@ export function processExceptions(
 ): ValidationError[] {
   const { unsafeAllow } = withValidationDefaults(opts);
 
-  if (opts.kind === 'transparent') {
+  if (opts.kind === 'transparent' || opts.kind === 'beacon') {
     errors = errors.filter(error => error.kind !== 'missing-public-upgradeto');
   }
 

package/src/validate/query.ts

@@ -5,13 +5,15 @@ import { unlinkBytecode } from '../link-refs';
 import { ValidationOptions, processExceptions } from './overrides';
 import { ValidationErrors } from './error';
 import { ValidationData, normalizeValidationData } from './data';
+import { ProxyDeployment } from '../manifest';
+
+const upgradeToSignature = 'upgradeTo(address)';
 
 export function assertUpgradeSafe(data: ValidationData, version: Version, opts: ValidationOptions): void {
   const dataV3 = normalizeValidationData(data);
   const [contractName] = getContractNameAndRunValidation(dataV3, version);
 
-  let errors = getErrors(dataV3, version);
-  errors = processExceptions(contractName, errors, opts);
+  const errors = getErrors(dataV3, version, opts);
 
   if (errors.length > 0) {
     throw new ValidationErrors(contractName, errors);
@@ -100,23 +102,28 @@ export function getUnlinkedBytecode(data: ValidationData, bytecode: string): str
   return bytecode;
 }
 
-export function getErrors(data: ValidationData, version: Version): ValidationError[] {
+export function getErrors(data: ValidationData, version: Version, opts: ValidationOptions = {}): ValidationError[] {
   const dataV3 = normalizeValidationData(data);
   const [contractName, runValidation] = getContractNameAndRunValidation(dataV3, version);
   const c = runValidation[contractName];
 
   const errors = getUsedContractsAndLibraries(contractName, runValidation).flatMap(name => runValidation[name].errors);
 
-  const selfAndInheritedMethods = c.methods.concat(...c.inherit.map(name => runValidation[name].methods));
+  const selfAndInheritedMethods = getAllMethods(runValidation, contractName);
 
-  if (!selfAndInheritedMethods.includes('upgradeTo(address)')) {
+  if (!selfAndInheritedMethods.includes(upgradeToSignature)) {
     errors.push({
       src: c.src,
       kind: 'missing-public-upgradeto',
     });
   }
 
-  return errors;
+  return processExceptions(contractName, errors, opts);
+}
+
+function getAllMethods(runValidation: ValidationRunData, contractName: string): string[] {
+  const c = runValidation[contractName];
+  return c.methods.concat(...c.inherit.map(name => runValidation[name].methods));
 }
 
 function getUsedContractsAndLibraries(contractName: string, runValidation: ValidationRunData) {
@@ -136,3 +143,14 @@ export function isUpgradeSafe(data: ValidationData, version: Version): boolean {
   const dataV3 = normalizeValidationData(data);
   return getErrors(dataV3, version).length == 0;
 }
+
+export function inferProxyKind(data: ValidationData, version: Version): ProxyDeployment['kind'] {
+  const dataV3 = normalizeValidationData(data);
+  const [contractName, runValidation] = getContractNameAndRunValidation(dataV3, version);
+  const methods = getAllMethods(runValidation, contractName);
+  if (methods.includes(upgradeToSignature)) {
+    return 'uups';
+  } else {
+    return 'transparent';
+  }
+}