Add Solidity Wizard API function to get versioned remappings (#724)

Co-authored-by: Eric Lau <ericglau@outlook.com>

Author: typicalHuman

.changeset/long-trams-tease.md

@@ -0,0 +1,5 @@
+---
+'@openzeppelin/wizard': patch
+---
+
+Add API function to get versioned remappings.

packages/core/solidity/README.md

@@ -24,81 +24,42 @@ The following contract types are supported:
 
 Note that `stablecoin` and `realWorldAsset` are experimental and may be subject to change.
 
-Each contract type has functions/constants as defined below.
-
 ### Functions
 
+Each contract type implements a common API with methods that take contract-specific options (e.g., `ERC20Options` for `erc20`, `ERC721Options` for `erc721`, etc.). This ensures type safety and allows for contract-specific features.
+
 #### `print`
 ```js
-function print(opts?: ERC20Options): string
-```
-```js
-function print(opts?: ERC721Options): string
-```
-```js
-function print(opts?: ERC1155Options): string
-```
-```js
-function print(opts?: StablecoinOptions): string
-```
-```js
-function print(opts?: AccountOptions): string
-```
-```js
-function print(opts?: GovernorOptions): string
-```
-```js
-function print(opts?: CustomOptions): string
+function print(opts?: Options): string
 ```
 Returns a string representation of a contract generated using the provided options. If `opts` is not provided, uses [`defaults`](#defaults).
 
-#### `defaults`
-```js
-const defaults: Required<ERC20Options>
-```
-```js
-const defaults: Required<ERC721Options>
-```
-```js
-const defaults: Required<ERC1155Options>
-```
-```js
-const defaults: Required<StablecoinOptions>
-```
+#### `getVersionedRemappings`
 ```js
-const defaults: Required<AccountOptions>
+function getVersionedRemappings(opts?: Options): string[]
 ```
+Returns an array of remappings that map unversioned import prefixes to versioned import prefixes. For example:
 ```js
-const defaults: Required<GovernorOptions>
+[
+  "@openzeppelin/contracts/=@openzeppelin/contracts@5.5.0/",
+  "@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@5.5.0/"
+]
 ```
+If the contract options include upgradeability, the upgradeable remapping is included. If `opts` is not provided, uses [`defaults`](#defaults).
+
+#### `defaults`
 ```js
-const defaults: Required<CustomOptions>
+const defaults: Required<Options>
 ```
-The default options that are used for [`print`](#print).
+The default options that are used for [`print`](#print) and [`getVersionedRemappings`](#getVersionedRemappings).
 
 #### `isAccessControlRequired`
 ```js
-function isAccessControlRequired(opts: Partial<ERC20Options>): boolean
-```
-```js
-function isAccessControlRequired(opts: Partial<ERC721Options>): boolean
-```
-```js
-function isAccessControlRequired(opts: Partial<ERC1155Options>): boolean
-```
-```js
-function isAccessControlRequired(opts: Partial<StablecoinOptions>): boolean
-```
-```js
-function isAccessControlRequired(opts: Partial<GovernorOptions>): boolean
-```
-```js
-function isAccessControlRequired(opts: Partial<CustomOptions>): boolean
+function isAccessControlRequired(opts: Partial<Options>): boolean
 ```
 Whether any of the provided options require access control to be enabled. If this returns `true`, then calling `print` with the same options would cause the `access` option to default to `'ownable'` if it was `undefined` or `false`.
 
-> Note that contracts such as `account`, have its own way of handling permissions and do not support the `access` option.
-Thus, that type does not include `isAccessControlRequired`.
+> Note that contracts such as `account` have their own way of handling permissions and do not support the `access` option. Thus, that type does not include `isAccessControlRequired`.
 
 ### Examples
 
@@ -129,4 +90,3 @@ const contract = erc20.print({
   ...erc20.defaults,
   upgradeable: 'uups',
 });
-```

packages/core/solidity/src/api.ts

@@ -37,13 +37,26 @@ import {
   defaults as customDefaults,
   isAccessControlRequired as customIsAccessControlRequired,
 } from './custom';
+import { getVersionedRemappings } from './get-versioned-remappings';
 
 export interface WizardContractAPI<Options extends CommonOptions> {
   /**
    * Returns a string representation of a contract generated using the provided options. If opts is not provided, uses `defaults`.
    */
   print: (opts?: Options) => string;
 
+  /**
+   * Returns remappings that map unversioned import prefixes to versioned import prefixes.
+   * @example
+   * ```ts
+   * [
+   *   "@openzeppelin/contracts/=@openzeppelin/contracts@5.5.0/",
+   *   "@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@5.5.0/"
+   * ]
+   * ```
+   */
+  getVersionedRemappings: (opts?: Options) => string[];
+
   /**
    * The default options that are used for `print`.
    */
@@ -69,40 +82,48 @@ export type Custom = WizardContractAPI<CustomOptions> & AccessControlAPI<CustomO
 
 export const erc20: ERC20 = {
   print: printERC20,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: erc20defaults,
   isAccessControlRequired: erc20IsAccessControlRequired,
 };
 export const erc721: ERC721 = {
   print: printERC721,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: erc721defaults,
   isAccessControlRequired: erc721IsAccessControlRequired,
 };
 export const erc1155: ERC1155 = {
   print: printERC1155,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: erc1155defaults,
   isAccessControlRequired: erc1155IsAccessControlRequired,
 };
 export const stablecoin: Stablecoin = {
   print: printStablecoin,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: stablecoinDefaults,
   isAccessControlRequired: stablecoinIsAccessControlRequired,
 };
 export const account: Account = {
   print: printAccount,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: accountDefaults,
 };
 export const realWorldAsset: RealWorldAsset = {
   print: printStablecoin,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: stablecoinDefaults,
   isAccessControlRequired: stablecoinIsAccessControlRequired,
 };
 export const governor: Governor = {
   print: printGovernor,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: governorDefaults,
   isAccessControlRequired: governorIsAccessControlRequired,
 };
 export const custom: Custom = {
   print: printCustom,
+  getVersionedRemappings: getVersionedRemappings,
   defaults: customDefaults,
   isAccessControlRequired: customIsAccessControlRequired,
 };

packages/core/solidity/src/get-versioned-remappings.test.ts

@@ -0,0 +1,26 @@
+import test from 'ava';
+import { getVersionedRemappings } from './get-versioned-remappings';
+import contracts from '../openzeppelin-contracts';
+
+test('getVersionedRemappings not upgradeable', t => {
+  const remappings = getVersionedRemappings({});
+  t.is(remappings.length, 1);
+  t.is(remappings[0], `@openzeppelin/contracts/=@openzeppelin/contracts@${contracts.version}/`);
+  t.snapshot(remappings);
+});
+
+test('getVersionedRemappings upgradeable uups', t => {
+  const remappings = getVersionedRemappings({ upgradeable: 'uups' });
+  t.is(remappings.length, 2);
+  t.is(remappings[0], `@openzeppelin/contracts/=@openzeppelin/contracts@${contracts.version}/`);
+  t.is(remappings[1], `@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@${contracts.version}/`);
+  t.snapshot(remappings);
+});
+
+test('getVersionedRemappings upgradeable transparent', t => {
+  const remappings = getVersionedRemappings({ upgradeable: 'transparent' });
+  t.is(remappings.length, 2);
+  t.is(remappings[0], `@openzeppelin/contracts/=@openzeppelin/contracts@${contracts.version}/`);
+  t.is(remappings[1], `@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@${contracts.version}/`);
+  t.snapshot(remappings);
+});

packages/core/solidity/src/get-versioned-remappings.test.ts.md

@@ -0,0 +1,31 @@
+# Snapshot report for `src/get-versioned-remappings.test.ts`
+
+The actual snapshot is saved in `get-versioned-remappings.test.ts.snap`.
+
+Generated by [AVA](https://avajs.dev).
+
+## getVersionedRemappings not upgradeable
+
+> Snapshot 1
+
+    [
+      '@openzeppelin/contracts/=@openzeppelin/contracts@5.5.0/',
+    ]
+
+## getVersionedRemappings upgradeable uups
+
+> Snapshot 1
+
+    [
+      '@openzeppelin/contracts/=@openzeppelin/contracts@5.5.0/',
+      '@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@5.5.0/',
+    ]
+
+## getVersionedRemappings upgradeable transparent
+
+> Snapshot 1
+
+    [
+      '@openzeppelin/contracts/=@openzeppelin/contracts@5.5.0/',
+      '@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@5.5.0/',
+    ]

packages/core/solidity/src/get-versioned-remappings.test.ts.snap

@@ -0,0 +1,10 @@
+import type { CommonOptions } from './common-options';
+import contracts from '../openzeppelin-contracts';
+
+export function getVersionedRemappings(opts?: CommonOptions): string[] {
+  const remappings = [`@openzeppelin/contracts/=@openzeppelin/contracts@${contracts.version}/`];
+  if (opts?.upgradeable) {
+    remappings.push(`@openzeppelin/contracts-upgradeable/=@openzeppelin/contracts-upgradeable@${contracts.version}/`);
+  }
+  return remappings;
+}