@openzeppelin/wizard 0.4.1 → 0.4.3

package/src/environments/hardhat/upgradeable/package.json

@@ -11,8 +11,8 @@
   "devDependencies": {
     "@openzeppelin/contracts": "^5.0.0",
     "@openzeppelin/contracts-upgradeable": "^5.0.0",
-    "@openzeppelin/hardhat-upgrades": "^2.0.0",
-    "@nomicfoundation/hardhat-toolbox": "^3.0.0",
+    "@openzeppelin/hardhat-upgrades": "^3.0.0",
+    "@nomicfoundation/hardhat-toolbox": "^5.0.0",
     "hardhat": "^2.16.1"
   }
 }

package/src/erc20.ts

@@ -6,6 +6,7 @@ import { CommonOptions, withCommonDefaults, defaults as commonDefaults } from '.
 import { setUpgradeable } from './set-upgradeable';
 import { setInfo } from './set-info';
 import { printContract } from './print';
+import { ClockMode, clockModeDefault, setClockMode } from './set-clock-mode';
 
 export interface ERC20Options extends CommonOptions {
   name: string;
@@ -15,7 +16,11 @@ export interface ERC20Options extends CommonOptions {
   premint?: string;
   mintable?: boolean;
   permit?: boolean;
-  votes?: boolean;
+  /**
+   * Whether to keep track of historical balances for voting in on-chain governance, and optionally specify the clock mode.
+   * Setting `true` is equivalent to 'blocknumber'. Setting a clock mode implies voting is enabled.
+   */
+  votes?: boolean | ClockMode;
   flashmint?: boolean;
 }
 
@@ -87,7 +92,8 @@ export function buildERC20(opts: ERC20Options): Contract {
   }
 
   if (allOpts.votes) {
-    addVotes(c);
+    const clockMode = allOpts.votes === true ? clockModeDefault : allOpts.votes;
+    addVotes(c, clockMode);
   }
 
   if (allOpts.flashmint) {
@@ -166,7 +172,7 @@ function addPermit(c: ContractBuilder, name: string) {
 
 }
 
-function addVotes(c: ContractBuilder) {
+function addVotes(c: ContractBuilder, clockMode: ClockMode) {
   if (!c.parents.some(p => p.contract.name === 'ERC20Permit')) {
     throw new Error('Missing ERC20Permit requirement for ERC20Votes');
   }
@@ -180,6 +186,8 @@ function addVotes(c: ContractBuilder) {
   c.addOverride({
     name: 'Nonces',
   }, functions.nonces);
+
+  setClockMode(c, ERC20Votes, clockMode);
 }
 
 function addFlashMint(c: ContractBuilder) {

package/src/erc721.ts

@@ -7,6 +7,7 @@ import { CommonOptions, withCommonDefaults, defaults as commonDefaults } from '.
 import { setUpgradeable } from './set-upgradeable';
 import { setInfo } from './set-info';
 import { printContract } from './print';
+import { ClockMode, clockModeDefault, setClockMode } from './set-clock-mode';
 
 export interface ERC721Options extends CommonOptions {
   name: string;
@@ -18,7 +19,11 @@ export interface ERC721Options extends CommonOptions {
   pausable?: boolean;
   mintable?: boolean;
   incremental?: boolean;
-  votes?: boolean;
+  /**
+   * Whether to keep track of individual units for voting in on-chain governance, and optionally specify the clock mode.
+   * Setting `true` is equivalent to 'blocknumber'. Setting a clock mode implies voting is enabled.
+   */
+  votes?: boolean | ClockMode;
 }
 
 export const defaults: Required<ERC721Options> = {
@@ -34,7 +39,7 @@ export const defaults: Required<ERC721Options> = {
   votes: false,
   access: commonDefaults.access,
   upgradeable: commonDefaults.upgradeable,
-  info: commonDefaults.info
+  info: commonDefaults.info,
 } as const;
 
 function withDefaults(opts: ERC721Options): Required<ERC721Options> {
@@ -94,7 +99,8 @@ export function buildERC721(opts: ERC721Options): Contract {
   }
 
   if (allOpts.votes) {
-    addVotes(c, allOpts.name);
+    const clockMode = allOpts.votes === true ? clockModeDefault : allOpts.votes;
+    addVotes(c, allOpts.name, clockMode);
   }
 
   setAccessControl(c, access);
@@ -181,7 +187,7 @@ function addMintable(c: ContractBuilder, access: Access, incremental = false, ur
   }
 }
 
-function addVotes(c: ContractBuilder, name: string) {
+function addVotes(c: ContractBuilder, name: string, clockMode: ClockMode) {
   const EIP712 = {
     name: 'EIP712',
     path: '@openzeppelin/contracts/utils/cryptography/EIP712.sol',
@@ -196,6 +202,8 @@ function addVotes(c: ContractBuilder, name: string) {
 
   c.addOverride(ERC721Votes, functions._update);
   c.addOverride(ERC721Votes, functions._increaseBalance);
+
+  setClockMode(c, ERC721Votes, clockMode);
 }
 
 const functions = defineFunctions({

package/src/generate/erc20.ts

@@ -1,5 +1,6 @@
 import type { ERC20Options } from '../erc20';
 import { accessOptions } from '../set-access-control';
+import { clockModeOptions } from '../set-clock-mode';
 import { infoOptions } from '../set-info';
 import { upgradeableOptions } from '../set-upgradeable';
 import { generateAlternatives } from './alternatives';
@@ -13,7 +14,7 @@ const blueprint = {
   pausable: booleans,
   mintable: booleans,
   permit: booleans,
-  votes: booleans,
+  votes: [ ...booleans, ...clockModeOptions ] as const,
   flashmint: booleans,
   premint: ['1'],
   access: accessOptions,

package/src/generate/erc721.ts

@@ -1,5 +1,6 @@
 import type { ERC721Options } from '../erc721';
 import { accessOptions } from '../set-access-control';
+import { clockModeOptions } from '../set-clock-mode';
 import { infoOptions } from '../set-info';
 import { upgradeableOptions } from '../set-upgradeable';
 import { generateAlternatives } from './alternatives';
@@ -19,7 +20,7 @@ const blueprint = {
   access: accessOptions,
   upgradeable: upgradeableOptions,
   info: infoOptions,
-  votes: booleans,
+  votes: [ ...booleans, ...clockModeOptions ] as const,
 };
 
 export function* generateERC721Options(): Generator<Required<ERC721Options>> {

package/src/generate/governor.ts

@@ -1,5 +1,6 @@
 import { defaults, GovernorOptions, timelockOptions, votesOptions } from '../governor';
 import { accessOptions } from '../set-access-control';
+import { clockModeOptions } from '../set-clock-mode';
 import { infoOptions } from '../set-info';
 import { upgradeableOptions } from '../set-upgradeable';
 import { generateAlternatives } from './alternatives';
@@ -17,6 +18,7 @@ const blueprint = {
   quorumPercent: [4],
   quorumAbsolute: ['1000'],
   votes: votesOptions,
+  clockMode: clockModeOptions,
   timelock: timelockOptions,
   storage: booleans,
   settings: booleans,

package/src/generate/sources.ts

@@ -7,7 +7,7 @@ import { generateERC721Options } from './erc721';
 import { generateERC1155Options } from './erc1155';
 import { generateGovernorOptions } from './governor';
 import { generateCustomOptions } from './custom';
-import { buildGeneric, GenericOptions } from '../build-generic';
+import { buildGeneric, GenericOptions, KindedOptions } from '../build-generic';
 import { printContract } from '../print';
 import { OptionsError } from '../error';
 import { findCover } from '../utils/find-cover';
@@ -15,25 +15,37 @@ import type { Contract } from '../contract';
 
 type Subset = 'all' | 'minimal-cover';
 
-export function* generateOptions(): Generator<GenericOptions> {
-  for (const kindOpts of generateERC20Options()) {
-    yield { kind: 'ERC20', ...kindOpts };
+type Kind = keyof KindedOptions;
+
+export function* generateOptions(kind?: Kind): Generator<GenericOptions> {
+  if (!kind || kind === 'ERC20') {
+    for (const kindOpts of generateERC20Options()) {
+      yield { kind: 'ERC20', ...kindOpts };
+    }
   }
 
-  for (const kindOpts of generateERC721Options()) {
-    yield { kind: 'ERC721', ...kindOpts };
+  if (!kind || kind === 'ERC721') {
+    for (const kindOpts of generateERC721Options()) {
+      yield { kind: 'ERC721', ...kindOpts };
+    }
   }
 
-  for (const kindOpts of generateERC1155Options()) {
-    yield { kind: 'ERC1155', ...kindOpts };
+  if (!kind || kind === 'ERC1155') {
+    for (const kindOpts of generateERC1155Options()) {
+      yield { kind: 'ERC1155', ...kindOpts };
+    }
   }
 
-  for (const kindOpts of generateGovernorOptions()) {
-    yield { kind: 'Governor', ...kindOpts };
+  if (!kind || kind === 'Governor') {
+    for (const kindOpts of generateGovernorOptions()) {
+      yield { kind: 'Governor', ...kindOpts };
+    }
   }
 
-  for (const kindOpts of generateCustomOptions()) {
-    yield { kind: 'Custom', ...kindOpts };
+  if (!kind || kind === 'Custom') {
+    for (const kindOpts of generateCustomOptions()) {
+      yield { kind: 'Custom', ...kindOpts };
+    }
   }
 }
 
@@ -47,10 +59,10 @@ interface GeneratedSource extends GeneratedContract {
   source: string;
 }
 
-function generateContractSubset(subset: Subset): GeneratedContract[] {
+function generateContractSubset(subset: Subset, kind?: Kind): GeneratedContract[] {
   const contracts = [];
 
-  for (const options of generateOptions()) {
+  for (const options of generateOptions(kind)) {
     const id = crypto
       .createHash('sha1')
       .update(JSON.stringify(options))
@@ -80,17 +92,17 @@ function generateContractSubset(subset: Subset): GeneratedContract[] {
   }
 }
 
-export function* generateSources(subset: Subset): Generator<GeneratedSource> {
-  for (const c of generateContractSubset(subset)) {
+export function* generateSources(subset: Subset, kind?: Kind): Generator<GeneratedSource> {
+  for (const c of generateContractSubset(subset, kind)) {
     const source = printContract(c.contract);
     yield { ...c, source };
   }
 }
 
-export async function writeGeneratedSources(dir: string, subset: Subset): Promise<void> {
+export async function writeGeneratedSources(dir: string, subset: Subset, kind?: Kind): Promise<void> {
   await fs.mkdir(dir, { recursive: true });
 
-  for (const { id, source } of generateSources(subset)) {
+  for (const { id, source } of generateSources(subset, kind)) {
     await fs.writeFile(path.format({ dir, name: id, ext: '.sol' }), source);
   }
 }

package/src/governor.ts

@@ -1,13 +1,14 @@
 import { supportsInterface } from "./common-functions";
 import { CommonOptions, withCommonDefaults, defaults as commonDefaults } from "./common-options";
-import { ContractBuilder, Contract } from "./contract";
+import { ContractBuilder, Contract, Value } from "./contract";
 import { OptionsError } from "./error";
 import { setAccessControl } from "./set-access-control";
 import { printContract } from "./print";
 import { setInfo } from "./set-info";
 import { setUpgradeable } from "./set-upgradeable";
 import { defineFunctions } from './utils/define-functions';
-import { durationToBlocks } from "./utils/duration";
+import { durationToBlocks, durationToTimestamp } from "./utils/duration";
+import { clockModeDefault, type ClockMode } from "./set-clock-mode";
 
 export const defaults: Required<GovernorOptions> = {
   name: 'MyGovernor',
@@ -15,6 +16,7 @@ export const defaults: Required<GovernorOptions> = {
   period: '1 week',
 
   votes: 'erc20votes',
+  clockMode: clockModeDefault,
   timelock: 'openzeppelin',
   blockTime: 12,
   decimals: 18,
@@ -51,6 +53,7 @@ export interface GovernorOptions extends CommonOptions {
   quorumPercent?: number;
   quorumAbsolute?: string;
   votes?: VotesOptions;
+  clockMode?: ClockMode;
   timelock?: TimelockOptions;
   storage?: boolean;
   settings?: boolean;
@@ -73,6 +76,7 @@ function withDefaults(opts: GovernorOptions): Required<GovernorOptions> {
     storage: opts.storage ?? defaults.storage,
     quorumMode: opts.quorumMode ?? defaults.quorumMode,
     votes: opts.votes ?? defaults.votes,
+    clockMode: opts.clockMode ?? defaults.clockMode,
     timelock: opts.timelock ?? defaults.timelock
   };
 }
@@ -129,8 +133,8 @@ function addSettings(c: ContractBuilder, allOpts: Required<GovernorOptions>) {
     c.addParent(
       GovernorSettings,
       [
-        { value: getVotingDelay(allOpts), note: allOpts.delay },
-        { value: getVotingPeriod(allOpts), note: allOpts.period },
+        getVotingDelay(allOpts),
+        getVotingPeriod(allOpts),
         { lit: getProposalThreshold(allOpts) },
       ],
     );
@@ -143,9 +147,18 @@ function addSettings(c: ContractBuilder, allOpts: Required<GovernorOptions>) {
   }
 }
 
-function getVotingDelay(opts: Required<GovernorOptions>): number {
+function getVotingDelay(opts: Required<GovernorOptions>): { lit: string } | { note: string, value: number } {
   try {
-    return durationToBlocks(opts.delay, opts.blockTime);
+    if (opts.clockMode === 'timestamp') {
+      return {
+        lit: durationToTimestamp(opts.delay),
+      };
+    } else {
+      return {
+        value: durationToBlocks(opts.delay, opts.blockTime),
+        note: opts.delay
+      };
+    }
   } catch (e) {
     if (e instanceof Error) {
       throw new OptionsError({
@@ -157,9 +170,18 @@ function getVotingDelay(opts: Required<GovernorOptions>): number {
   }
 }
 
-function getVotingPeriod(opts: Required<GovernorOptions>): number {
+function getVotingPeriod(opts: Required<GovernorOptions>): { lit: string } | { note: string, value: number } {
   try {
-    return durationToBlocks(opts.period, opts.blockTime);
+    if (opts.clockMode === 'timestamp') {
+      return {
+        lit: durationToTimestamp(opts.period),
+      };
+    } else {
+      return {
+        value: durationToBlocks(opts.period, opts.blockTime),
+        note: opts.period
+      };
+    }
   } catch (e) {
     if (e instanceof Error) {
       throw new OptionsError({
@@ -195,10 +217,18 @@ function getProposalThreshold({ proposalThreshold, decimals, votes }: Required<G
 
 function setVotingParameters(c: ContractBuilder, opts: Required<GovernorOptions>) {
   const delayBlocks = getVotingDelay(opts);
-  c.setFunctionBody([`return ${delayBlocks}; // ${opts.delay}`], functions.votingDelay);
+  if ('lit' in delayBlocks) {
+    c.setFunctionBody([`return ${delayBlocks.lit};`], functions.votingDelay);
+  } else {
+    c.setFunctionBody([`return ${delayBlocks.value}; // ${delayBlocks.note}`], functions.votingDelay);
+  }
 
   const periodBlocks = getVotingPeriod(opts);
-  c.setFunctionBody([`return ${periodBlocks}; // ${opts.period}`], functions.votingPeriod);
+  if ('lit' in periodBlocks) {
+    c.setFunctionBody([`return ${periodBlocks.lit};`], functions.votingPeriod);
+  } else {
+    c.setFunctionBody([`return ${periodBlocks.value}; // ${periodBlocks.note}`], functions.votingPeriod);
+  }
 }
 
 function setProposalThreshold(c: ContractBuilder, opts: Required<GovernorOptions>) {

package/src/index.ts

@@ -19,4 +19,6 @@ export { OptionsError } from './error';
 export type { Kind } from './kind';
 export { sanitizeKind } from './kind';
 
-export { erc20, erc721, erc1155, governor, custom } from './api';
+export { erc20, erc721, erc1155, governor, custom } from './api';
+
+export { compatibleContractsSemver } from './utils/version';

package/src/print.ts

@@ -7,6 +7,7 @@ import { formatLines, spaceBetween, Lines } from './utils/format-lines';
 import { mapValues } from './utils/map-values';
 import SOLIDITY_VERSION from './solidity-version.json';
 import { inferTranspiled } from './infer-transpiled';
+import { compatibleContractsSemver } from './utils/version';
 
 export function printContract(contract: Contract, opts?: Options): string {
   const helpers = withHelpers(contract, opts);
@@ -22,6 +23,7 @@ export function printContract(contract: Contract, opts?: Options): string {
     ...spaceBetween(
       [
         `// SPDX-License-Identifier: ${contract.license}`,
+        `// Compatible with OpenZeppelin Contracts ${compatibleContractsSemver}`,
         `pragma solidity ^${SOLIDITY_VERSION};`,
       ],
 
@@ -71,6 +73,7 @@ function printConstructor(contract: Contract, helpers: Helpers): Lines[] {
       : contract.constructorCode;
     const head = helpers.upgradeable ? 'function initialize' : 'constructor';
     const constructor = printFunction2(
+      [],
       head,
       args,
       modifiers,
@@ -191,6 +194,7 @@ function printFunction(fn: ContractFunction, helpers: Helpers): Lines[] {
 
   if (modifiers.length + fn.code.length > 1) {
     return printFunction2(
+      fn.comments,
       'function ' + fn.name,
       fn.args.map(a => printArgument(a, helpers)),
       modifiers,
@@ -203,8 +207,8 @@ function printFunction(fn: ContractFunction, helpers: Helpers): Lines[] {
 
 // generic for functions and constructors
 // kindedName = 'function foo' or 'constructor'
-function printFunction2(kindedName: string, args: string[], modifiers: string[], code: Lines[]): Lines[] {
-  const fn = [];
+function printFunction2(comments: string[], kindedName: string, args: string[], modifiers: string[], code: Lines[]): Lines[] {
+  const fn: Lines[] = [ ...comments ];
 
   const headingLength = [kindedName, ...args, ...modifiers]
     .map(s => s.length)

package/src/set-clock-mode.ts

@@ -0,0 +1,33 @@
+import type { ContractBuilder, ReferencedContract } from "./contract";
+import { defineFunctions } from "./utils/define-functions";
+
+export const clockModeOptions = ['blocknumber', 'timestamp'] as const;
+export const clockModeDefault = 'blocknumber' as const;
+export type ClockMode = typeof clockModeOptions[number];
+
+const functions = defineFunctions({
+  clock: {
+    kind: 'public' as const,
+    args: [],
+    returns: ['uint48'],
+    mutability: 'view' as const,
+  },
+
+  CLOCK_MODE: {
+    kind: 'public' as const,
+    args: [],
+    returns: ['string memory'],
+    mutability: 'pure' as const,
+  }
+});
+
+export function setClockMode(c: ContractBuilder, parent: ReferencedContract, votes: ClockMode) {
+  if (votes === 'timestamp') {
+    c.addOverride(parent, functions.clock);
+    c.setFunctionBody(['return uint48(block.timestamp);'], functions.clock);
+
+    c.setFunctionComments(['// solhint-disable-next-line func-name-mixedcase'], functions.CLOCK_MODE);
+    c.addOverride(parent, functions.CLOCK_MODE);
+    c.setFunctionBody(['return "mode=timestamp";'], functions.CLOCK_MODE);
+  }
+}

package/src/test.ts

@@ -1,14 +1,42 @@
-import test from 'ava';
+import { promises as fs } from 'fs';
+import _test, { TestFn, ExecutionContext } from 'ava';
 import hre from 'hardhat';
 import path from 'path';
 
 import { generateSources, writeGeneratedSources } from './generate/sources';
-import type { GenericOptions } from './build-generic';
+import type { GenericOptions, KindedOptions } from './build-generic';
 import { custom, erc1155, erc20, erc721, governor } from './api';
 
-test('result compiles', async t => {
-  const generatedSourcesPath = path.join(hre.config.paths.sources, 'generated');
-  await writeGeneratedSources(generatedSourcesPath, 'all');
+interface Context {
+  generatedSourcesPath: string
+}
+
+const test = _test as TestFn<Context>;
+
+test.serial('erc20 result compiles', async t => {
+  await testCompile(t, 'ERC20');
+});
+
+test.serial('erc721 result compiles', async t => {
+  await testCompile(t, 'ERC721');
+});
+
+test.serial('erc1155 result compiles', async t => {
+  await testCompile(t, 'ERC1155');
+});
+
+test.serial('governor result compiles', async t => {
+  await testCompile(t, 'Governor');
+});
+
+test.serial('custom result compiles', async t => {
+  await testCompile(t, 'Custom');
+});
+
+async function testCompile(t: ExecutionContext<Context>, kind: keyof KindedOptions) {
+  const generatedSourcesPath = path.join(hre.config.paths.sources, `generated`);
+  await fs.rm(generatedSourcesPath, { force: true, recursive: true });
+  await writeGeneratedSources(generatedSourcesPath, 'all', kind);
 
   // We only want to check that contracts compile and we don't care about any
   // of the outputs. Setting empty outputSelection causes compilation to go a
@@ -19,7 +47,7 @@ test('result compiles', async t => {
 
   await hre.run('compile');
   t.pass();
-});
+}
 
 function isAccessControlRequired(opts: GenericOptions) {
   switch(opts.kind) {

package/src/utils/duration.ts

@@ -32,3 +32,21 @@ export function durationToBlocks(duration: string, blockTime: number): number {
   const durationSeconds = value * secondsForUnit[unit];
   return Math.round(durationSeconds / blockTime);
 }
+
+export function durationToTimestamp(duration: string): string {
+  const match = duration.trim().match(durationPattern);
+
+  if (!match) {
+    throw new Error('Bad duration format');
+  }
+
+  const value = match[1]!;
+  const unit = match[2]! as DurationUnit;
+
+  // unit must be a Solidity supported time unit
+  if (unit === 'block' || unit === 'month' || unit === 'year') {
+    throw new Error('Invalid unit for timestamp');
+  }
+
+  return `${value} ${unit}s`;
+}

package/src/utils/version.ts

@@ -0,0 +1,4 @@
+/**
+ * Semantic version string representing of the minimum compatible version of Contracts to display in output.
+ */
+export const compatibleContractsSemver = '^5.0.0';