@openzeppelin/upgrades-core 1.11.0 → 1.13.0

package/src/index.ts

@@ -1,9 +1,16 @@
 export * from './validate';
-export * from './impl-store';
+export { fetchOrDeploy, fetchOrDeployAdmin } from './impl-store';
 export * from './version';
-export * from './manifest';
 export * from './storage';
-export * from './eip-1967';
+export {
+  EIP1967BeaconNotFound,
+  EIP1967ImplementationNotFound,
+  getAdminAddress,
+  getBeaconAddress,
+  getImplementationAddress,
+  toEip1967Hash,
+  toFallbackEip1967Hash,
+} from './eip-1967';
 export * from './provider';
 export * from './src-decoder';
 export * from './solc-api';
@@ -11,18 +18,28 @@ export * from './deployment';
 export * from './link-refs';
 export * from './error';
 
+export {
+  ManifestData,
+  ImplDeployment,
+  ProxyDeployment,
+  Manifest,
+  migrateManifest,
+  DeploymentNotFound,
+} from './manifest';
+
 export { getStorageLayoutForAddress } from './manifest-storage-layout';
 
 export * from './scripts/migrate-oz-cli-project';
 
 export { logWarning } from './utils/log';
-export { setProxyKind, processProxyKind } from './proxy-kind';
+export { setProxyKind, processProxyKind, detectProxyKind } 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 { addProxyToManifest } from './add-proxy-to-manifest';
 
 export {
   BeaconProxyUnsupportedError,
@@ -31,5 +48,6 @@ export {
   DeployBeaconProxyUnsupportedError,
   DeployBeaconProxyImplUnknownError,
   DeployBeaconProxyKindError,
+  ForceImportUnsupportedError,
   assertNotProxy,
 } from './usage-error';

package/src/manifest-storage-layout.test.ts

@@ -1,4 +1,4 @@
-import _test, { TestInterface } from 'ava';
+import _test, { TestFn } from 'ava';
 import assert from 'assert';
 
 import { artifacts } from 'hardhat';
@@ -17,7 +17,7 @@ interface Context {
   validationData: ValidationData;
 }
 
-const test = _test as TestInterface<Context>;
+const test = _test as TestFn<Context>;
 
 test.before(async t => {
   const buildInfo = await artifacts.getBuildInfo('contracts/test/ManifestMigrate.sol:ManifestMigrateUnique');
@@ -44,6 +44,7 @@ test('getStorageLayoutForAddress - update layout', async t => {
     },
     proxies: [],
   });
+
   const layout = await getStorageLayoutForAddress(manifest, t.context.validationData, address);
   t.deepEqual(layout, updatedLayout);
   t.like(manifest.data, {

package/src/manifest-storage-layout.ts

@@ -5,6 +5,7 @@ import { ValidationData } from './validate/data';
 import { findVersionWithoutMetadataMatches, unfoldStorageLayout } from './validate/query';
 import { stabilizeTypeIdentifier } from './utils/type-id';
 import { DeepArray, deepEqual } from './utils/deep-array';
+import { UpgradesError } from './error';
 
 export async function getStorageLayoutForAddress(
   manifest: Manifest,
@@ -12,13 +13,17 @@ export async function getStorageLayoutForAddress(
   implAddress: string,
 ): Promise<StorageLayout> {
   const data = await manifest.read();
-  const versionWithoutMetadata = Object.keys(data.impls).find(v => data.impls[v]?.address === implAddress);
+  const versionWithoutMetadata = Object.keys(data.impls).find(
+    v => data.impls[v]?.address === implAddress || data.impls[v]?.allAddresses?.includes(implAddress),
+  );
   if (versionWithoutMetadata === undefined) {
-    throw new Error(`Deployment at address ${implAddress} is not registered`);
+    throw new UpgradesError(
+      `Deployment at address ${implAddress} is not registered`,
+      () => 'To register a previously deployed proxy for upgrading, use the forceImport function.',
+    );
   }
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   const { layout } = data.impls[versionWithoutMetadata]!;
-
   if (isCurrentLayoutVersion(layout)) {
     return layout;
   } else {

package/src/manifest.test.ts

@@ -1,5 +1,5 @@
 import test from 'ava';
-import { Manifest } from './manifest';
+import { Manifest, ManifestData, normalizeManifestData } from './manifest';
 
 test('manifest name for a known network', t => {
   const manifest = new Manifest(1);
@@ -11,3 +11,36 @@ test('manifest name for an unknown network', t => {
   const manifest = new Manifest(id);
   t.is(manifest.file, `.openzeppelin/unknown-${id}.json`);
 });
+
+test('normalize manifest', t => {
+  const deployment = {
+    address: '0x1234',
+    txHash: '0x1234',
+    kind: 'uups' as const,
+    layout: { types: {}, storage: [] },
+    deployTransaction: {},
+  };
+  const input: ManifestData = {
+    manifestVersion: '3.0',
+    admin: deployment,
+    impls: { a: deployment },
+    proxies: [deployment],
+  };
+  const norm = normalizeManifestData(input);
+  t.like(norm.admin, {
+    ...deployment,
+    kind: undefined,
+    layout: undefined,
+    deployTransaction: undefined,
+  });
+  t.like(norm.impls.a, {
+    ...deployment,
+    kind: undefined,
+    deployTransaction: undefined,
+  });
+  t.like(norm.proxies[0], {
+    ...deployment,
+    layout: undefined,
+    deployTransaction: undefined,
+  });
+});

package/src/manifest.ts

@@ -22,6 +22,7 @@ export interface ManifestData {
 
 export interface ImplDeployment extends Deployment {
   layout: StorageLayout;
+  allAddresses?: string[];
 }
 
 export interface ProxyDeployment extends Deployment {
@@ -57,7 +58,10 @@ export class Manifest {
 
   async getDeploymentFromAddress(address: string): Promise<ImplDeployment> {
     const data = await this.read();
-    const deployment = Object.values(data.impls).find(d => d?.address === address);
+    const deployment = Object.values(data.impls).find(
+      d => d?.address === address || d?.allAddresses?.includes(address),
+    );
+
     if (deployment === undefined) {
       throw new DeploymentNotFound(`Deployment at address ${address} is not registered`);
     }
@@ -160,11 +164,12 @@ export function migrateManifest(data: ManifestData): ManifestData {
 
 export class DeploymentNotFound extends Error {}
 
-function normalizeManifestData(input: ManifestData): ManifestData {
+export function normalizeManifestData(input: ManifestData): ManifestData {
   return {
-    ...pick(input, ['manifestVersion', 'admin']),
+    manifestVersion: input.manifestVersion,
+    admin: input.admin && normalizeDeployment(input.admin),
     proxies: input.proxies.map(p => normalizeDeployment(p, ['kind'])),
-    impls: mapValues(input.impls, i => i && normalizeDeployment(i, ['layout'])),
+    impls: mapValues(input.impls, i => i && normalizeDeployment(i, ['layout', 'allAddresses'])),
   };
 }
 

package/src/provider.ts

@@ -71,7 +71,11 @@ export async function call(
 
 export async function hasCode(provider: EthereumProvider, address: string, block?: string): Promise<boolean> {
   const code = await getCode(provider, address, block);
-  return code !== '0x';
+  return !isEmpty(code);
+}
+
+export function isEmpty(code: string) {
+  return code.replace(/^0x/, '') === '';
 }
 
 export async function getTransactionByHash(

package/src/proxy-kind.ts

@@ -1,9 +1,10 @@
 import { EthereumProvider } from './provider';
 import { inferProxyKind, ValidationData, ValidationOptions } from './validate';
 import { Manifest, DeploymentNotFound, ProxyDeployment } from './manifest';
-import { isBeaconProxy } from './eip-1967-type';
+import { isBeaconProxy, isTransparentOrUUPSProxy, isTransparentProxy } from './eip-1967-type';
 import { Version } from './version';
 import { BeaconProxyUnsupportedError } from './usage-error';
+import { UpgradesError } from '.';
 
 export async function setProxyKind(
   provider: EthereumProvider,
@@ -57,3 +58,25 @@ export async function processProxyKind(
     throw new BeaconProxyUnsupportedError();
   }
 }
+
+/**
+ * Detects the kind of proxy at an address by reading its ERC 1967 storage slots.
+ *
+ * @param provider the Ethereum provider
+ * @param proxyAddress the proxy address
+ * @returns the proxy kind
+ * @throws {UpgradesError} if the contract at address does not look like an ERC 1967 proxy
+ */
+export async function detectProxyKind(provider: EthereumProvider, proxyAddress: string) {
+  let importKind: ProxyDeployment['kind'];
+  if (await isTransparentProxy(provider, proxyAddress)) {
+    importKind = 'transparent';
+  } else if (await isTransparentOrUUPSProxy(provider, proxyAddress)) {
+    importKind = 'uups';
+  } else if (await isBeaconProxy(provider, proxyAddress)) {
+    importKind = 'beacon';
+  } else {
+    throw new UpgradesError(`Contract at ${proxyAddress} doesn't look like an ERC 1967 proxy`);
+  }
+  return importKind;
+}

package/src/scripts/migrate-oz-cli-project.test.ts

@@ -50,7 +50,7 @@ test('produces network export data', async t => {
 
 test('deletes project file', async t => {
   const error = await t.throwsAsync(() => fs.access(PROJECT_FILE));
-  t.is(error.message, `ENOENT: no such file or directory, access '${PROJECT_FILE}'`);
+  t.is(error?.message, `ENOENT: no such file or directory, access '${PROJECT_FILE}'`);
 });
 
 test('export file contains networks and compiler data', async t => {

package/src/solc-api.ts

@@ -1,4 +1,5 @@
 import type { SourceUnit } from 'solidity-ast';
+import { StorageItem, TypeItem } from './storage';
 
 export interface SolcOutput {
   contracts: {
@@ -8,6 +9,10 @@ export interface SolcOutput {
           bytecode: SolcBytecode;
           methodIdentifiers?: Record<string, string>;
         };
+        storageLayout?: {
+          storage: StorageItem[];
+          types: Record<string, TypeItem>;
+        };
       };
     };
   };

package/src/standalone.test.ts

@@ -1,4 +1,4 @@
-import _test, { TestInterface } from 'ava';
+import _test, { TestFn } from 'ava';
 import { artifacts } from 'hardhat';
 
 import { SolcInput, SolcOutput } from './solc-api';
@@ -9,7 +9,7 @@ interface Context {
   solcOutput: SolcOutput;
 }
 
-const test = _test as TestInterface<Context>;
+const test = _test as TestFn<Context>;
 
 test.before(async t => {
   const buildInfo = await artifacts.getBuildInfo('contracts/test/Standalone.sol:StandaloneV1');

package/src/storage/extract.ts

@@ -1,11 +1,18 @@
 import assert from 'assert';
-import { ContractDefinition, StructDefinition, EnumDefinition, TypeDescriptions } from 'solidity-ast';
+import {
+  ContractDefinition,
+  StructDefinition,
+  EnumDefinition,
+  TypeDescriptions,
+  VariableDeclaration,
+} from 'solidity-ast';
 import { isNodeType, findAll } from 'solidity-ast/utils';
-
 import { StorageLayout, TypeItem } from './layout';
 import { normalizeTypeIdentifier } from '../utils/type-id';
 import { SrcDecoder } from '../src-decoder';
 import { ASTDereferencer } from '../ast-dereferencer';
+import { mapValues } from '../utils/map-values';
+import { pick } from '../utils/pick';
 
 const currentLayoutVersion = '1.1';
 
@@ -17,62 +24,48 @@ export function extractStorageLayout(
   contractDef: ContractDefinition,
   decodeSrc: SrcDecoder,
   deref: ASTDereferencer,
+  storageLayout?: StorageLayout | undefined,
 ): StorageLayout {
-  const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion };
-
-  // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
-  const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition']);
+  const layout: StorageLayout = { storage: [], types: {}, layoutVersion: currentLayoutVersion, flat: false };
+  if (storageLayout !== undefined) {
+    layout.types = mapValues(storageLayout.types, m => {
+      return {
+        label: m.label,
+        members: m.members?.map(m => (typeof m === 'string' ? m : pick(m, ['label', 'type']))) as TypeItem['members'],
+      };
+    });
 
-  for (const varDecl of contractDef.nodes) {
-    if (isNodeType('VariableDeclaration', varDecl)) {
-      if (!varDecl.constant && varDecl.mutability !== 'immutable') {
-        const type = normalizeTypeIdentifier(typeDescriptions(varDecl).typeIdentifier);
-
-        layout.storage.push({
-          contract: contractDef.name,
-          label: varDecl.name,
-          type,
-          src: decodeSrc(varDecl),
-        });
-
-        assert(varDecl.typeName != null);
-
-        // We will recursively look for all types involved in this variable declaration in order to store their type
-        // information. We iterate over a Map that is indexed by typeIdentifier to ensure we visit each type only once.
-        // Note that there can be recursive types.
-        const typeNames = new Map(
-          [...findTypeNames(varDecl.typeName)].map(n => [typeDescriptions(n).typeIdentifier, n]),
-        );
-
-        for (const typeName of typeNames.values()) {
-          const { typeIdentifier, typeString: label } = typeDescriptions(typeName);
-
-          const type = normalizeTypeIdentifier(typeIdentifier);
-
-          if (type in layout.types) {
-            continue;
-          }
-
-          let members;
-
-          if ('referencedDeclaration' in typeName && !/^t_contract\b/.test(type)) {
-            const typeDef = derefUserDefinedType(typeName.referencedDeclaration);
-            members = getTypeMembers(typeDef);
-            // Recursively look for the types referenced in this definition and add them to the queue.
-            for (const typeName of findTypeNames(typeDef)) {
-              const { typeIdentifier } = typeDescriptions(typeName);
-              if (!typeNames.has(typeIdentifier)) {
-                typeNames.set(typeIdentifier, typeName);
-              }
-            }
-          }
-
-          layout.types[type] = { label, members };
+    for (const storage of storageLayout.storage) {
+      const origin = getOriginContract(contractDef, storage.astId, deref);
+
+      if (origin) {
+        const [varDecl, contract] = origin;
+        // Solc layout doesn't bring members for enums so we get them using the ast method
+        loadLayoutType(varDecl, layout, deref);
+        const { label, offset, slot, type } = storage;
+        const src = decodeSrc(varDecl);
+        layout.storage.push({ label, offset, slot, type, contract, src });
+        layout.flat = true;
+      }
+    }
+  } else {
+    for (const varDecl of contractDef.nodes) {
+      if (isNodeType('VariableDeclaration', varDecl)) {
+        if (!varDecl.constant && varDecl.mutability !== 'immutable') {
+          const type = normalizeTypeIdentifier(typeDescriptions(varDecl).typeIdentifier);
+
+          layout.storage.push({
+            contract: contractDef.name,
+            label: varDecl.name,
+            type,
+            src: decodeSrc(varDecl),
+          });
+
+          loadLayoutType(varDecl, layout, deref);
         }
       }
     }
   }
-
   return layout;
 }
 
@@ -108,3 +101,56 @@ function getTypeMembers(typeDef: StructDefinition | EnumDefinition): TypeItem['m
     return typeDef.members.map(m => m.name);
   }
 }
+
+function getOriginContract(
+  contract: ContractDefinition,
+  astId: number | undefined,
+  deref: ASTDereferencer,
+): undefined | [VariableDeclaration, string] {
+  for (const id of contract.linearizedBaseContracts.reverse()) {
+    const parentContract = deref(['ContractDefinition'], id);
+
+    const varDecl = parentContract.nodes.find(n => n.id == astId);
+    if (varDecl && isNodeType('VariableDeclaration', varDecl)) {
+      return [varDecl, parentContract.name];
+    }
+  }
+}
+
+function loadLayoutType(varDecl: VariableDeclaration, layout: StorageLayout, deref: ASTDereferencer) {
+  // Note: A UserDefinedTypeName can also refer to a ContractDefinition but we won't care about those.
+  const derefUserDefinedType = deref(['StructDefinition', 'EnumDefinition']);
+
+  assert(varDecl.typeName != null);
+
+  // We will recursively look for all types involved in this variable declaration in order to store their type
+  // information. We iterate over a Map that is indexed by typeIdentifier to ensure we visit each type only once.
+  // Note that there can be recursive types.
+  const typeNames = new Map([...findTypeNames(varDecl.typeName)].map(n => [typeDescriptions(n).typeIdentifier, n]));
+
+  for (const typeName of typeNames.values()) {
+    const { typeIdentifier, typeString: label } = typeDescriptions(typeName);
+
+    const type = normalizeTypeIdentifier(typeIdentifier);
+    const hasMembers = /^t_(enum|struct)\b/.test(type);
+    if (type in layout.types && (!hasMembers || layout.types[type].members !== undefined)) {
+      continue;
+    }
+
+    let members;
+
+    if ('referencedDeclaration' in typeName && !/^t_contract\b/.test(type)) {
+      const typeDef = derefUserDefinedType(typeName.referencedDeclaration);
+      members = getTypeMembers(typeDef);
+      // Recursively look for the types referenced in this definition and add them to the queue.
+      for (const typeName of findTypeNames(typeDef)) {
+        const { typeIdentifier } = typeDescriptions(typeName);
+        if (!typeNames.has(typeIdentifier)) {
+          typeNames.set(typeIdentifier, typeName);
+        }
+      }
+    }
+
+    layout.types[type] = { label, members };
+  }
+}

package/src/storage/layout.ts

@@ -9,13 +9,17 @@ export interface StorageLayout {
   layoutVersion?: string;
   storage: StorageItem[];
   types: Record<string, TypeItem>;
+  flat?: boolean;
 }
 
 export interface StorageItem<Type = string> {
+  astId?: number;
   contract: string;
   label: string;
   type: Type;
   src: string;
+  offset?: number;
+  slot?: string;
 }
 
 export interface TypeItem<Type = string> {

package/src/storage/report.test.ts

@@ -1,4 +1,4 @@
-import _test, { TestInterface } from 'ava';
+import _test, { TestFn } from 'ava';
 import { ContractDefinition } from 'solidity-ast';
 import { findAll } from 'solidity-ast/utils';
 import { artifacts } from 'hardhat';
@@ -13,7 +13,7 @@ interface Context {
   extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
 }
 
-const test = _test as TestInterface<Context>;
+const test = _test as TestFn<Context>;
 
 const dummyDecodeSrc = () => 'file.sol:1';
 

package/src/storage.test.ts

@@ -1,4 +1,4 @@
-import _test, { TestInterface } from 'ava';
+import _test, { TestFn } from 'ava';
 import { ContractDefinition } from 'solidity-ast';
 import { findAll } from 'solidity-ast/utils';
 import { artifacts } from 'hardhat';
@@ -14,7 +14,7 @@ interface Context {
   extractStorageLayout: (contract: string) => ReturnType<typeof extractStorageLayout>;
 }
 
-const test = _test as TestInterface<Context>;
+const test = _test as TestFn<Context>;
 
 test.before(async t => {
   const buildInfo = await artifacts.getBuildInfo('contracts/test/Storage.sol:Storage1');
@@ -344,7 +344,7 @@ test('storage upgrade with recursive type', t => {
   const v1 = t.context.extractStorageLayout('StorageUpgrade_Recursive_V1');
   const v2 = t.context.extractStorageLayout('StorageUpgrade_Recursive_V2');
   const e = t.throws(() => getStorageUpgradeErrors(v1, v2));
-  t.true(e.message.includes('Recursion found'));
+  t.true(e?.message.includes('Recursion found'));
 });
 
 test('storage upgrade with contract type', t => {

package/src/usage-error.ts

@@ -51,6 +51,15 @@ export class PrepareUpgradeUnsupportedError extends UpgradesError {
   }
 }
 
+export class ForceImportUnsupportedError 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 forceImport() function.`,
+    );
+  }
+}
+
 export async function assertNotProxy(provider: EthereumProvider, address: string) {
   if (await isTransparentOrUUPSProxy(provider, address)) {
     throw new UpgradesError(