@openzeppelin/wizard 0.1.0

package/src/governor.ts

@@ -0,0 +1,445 @@
+import { supportsInterface } from "./common-functions";
+import { CommonOptions, withCommonDefaults, defaults as commonDefaults } from "./common-options";
+import { ContractBuilder, Contract } from "./contract";
+import { OptionsError } from "./error";
+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";
+
+export const defaults: Required<GovernorOptions> = {
+  name: 'MyGovernor',
+  delay: '1 block',
+  period: '1 week',
+
+  votes: 'erc20votes',
+  timelock: 'openzeppelin',
+  blockTime: 13.2,
+  decimals: 18,
+  proposalThreshold: '0',
+  quorumMode: 'percent',
+  quorumPercent: 4,
+  quorumAbsolute: '',
+  bravo: false,
+  settings: true,
+  
+  access: commonDefaults.access,
+  upgradeable: commonDefaults.upgradeable,
+  info: commonDefaults.info
+} as const;
+
+export const votesOptions = ['erc20votes', 'erc721votes', 'comp'] as const;
+export type VotesOptions = typeof votesOptions[number];
+
+export const timelockOptions = [false, 'openzeppelin', 'compound'] as const;
+export type TimelockOptions = typeof timelockOptions[number];
+
+export function printGovernor(opts: GovernorOptions = defaults): string {
+  return printContract(buildGovernor(opts));
+}
+
+export interface GovernorOptions extends CommonOptions {
+  name: string;
+  delay: string;
+  period: string;
+  blockTime?: number;
+  proposalThreshold?: string;
+  decimals?: number;
+  quorumMode?: 'percent' | 'absolute';
+  quorumPercent?: number;
+  quorumAbsolute?: string;
+  votes?: VotesOptions;
+  timelock?: TimelockOptions;
+  bravo?: boolean;
+  settings?: boolean;
+}
+
+function withDefaults(opts: GovernorOptions): Required<GovernorOptions> {
+  return {
+    ...opts,
+    ...withCommonDefaults(opts),
+    decimals: opts.decimals ?? defaults.decimals,
+    blockTime: opts.blockTime || defaults.blockTime,
+    quorumPercent: opts.quorumPercent ?? defaults.quorumPercent,
+    quorumAbsolute: opts.quorumAbsolute ?? defaults.quorumAbsolute,
+    proposalThreshold: opts.proposalThreshold || defaults.proposalThreshold,
+    settings: opts.settings ?? defaults.settings,
+    bravo: opts.bravo ?? defaults.bravo,
+    quorumMode: opts.quorumMode ?? defaults.quorumMode,
+    votes: opts.votes ?? defaults.votes,
+    timelock: opts.timelock ?? defaults.timelock
+  };
+}
+
+export function buildGovernor(opts: GovernorOptions): Contract {
+  const allOpts = withDefaults(opts);
+
+  const c = new ContractBuilder(allOpts.name);
+
+  validateDecimals(allOpts.decimals);
+
+  addBase(c, allOpts);
+  addSettings(c, allOpts);
+  addCounting(c, allOpts);
+  addBravo(c, allOpts);
+  addVotes(c, allOpts);
+  addQuorum(c, allOpts);
+  addTimelock(c, allOpts);
+
+  setUpgradeable(c, allOpts.upgradeable, allOpts.access);
+
+  setInfo(c, allOpts.info);
+
+  return c;
+}
+
+function addBase(c: ContractBuilder, { name }: GovernorOptions) {
+  c.addParent(
+    {
+      name: 'Governor',
+      path: '@openzeppelin/contracts/governance/Governor.sol',
+    },
+    [name],
+  );
+  c.addOverride('IGovernor', functions.votingDelay);
+  c.addOverride('IGovernor', functions.votingPeriod);
+  c.addOverride('IGovernor', functions.quorum);
+  c.addOverride('Governor', functions.state);
+  c.addOverride('Governor', functions.propose);
+  c.addOverride('Governor', functions.proposalThreshold);
+  c.addOverride('Governor', functions._execute);
+  c.addOverride('Governor', functions._cancel);
+  c.addOverride('Governor', functions._executor);
+  c.addOverride('Governor', supportsInterface);
+}
+
+function addSettings(c: ContractBuilder, allOpts: Required<GovernorOptions>) {
+  if (allOpts.settings) {
+    c.addParent(
+      {
+        name: 'GovernorSettings',
+        path: '@openzeppelin/contracts/governance/extensions/GovernorSettings.sol',
+      },
+      [
+        { value: getVotingDelay(allOpts), note: allOpts.delay },
+        { value: getVotingPeriod(allOpts), note: allOpts.period },
+        { lit: getProposalThreshold(allOpts) },
+      ],
+    );
+    c.addOverride('GovernorSettings', functions.votingDelay, 'view');
+    c.addOverride('GovernorSettings', functions.votingPeriod, 'view');
+    c.addOverride('GovernorSettings', functions.proposalThreshold, 'view');
+  } else {
+    setVotingParameters(c, allOpts);
+    setProposalThreshold(c, allOpts);
+  }
+}
+
+function getVotingDelay(opts: Required<GovernorOptions>): number {
+  try {
+    return durationToBlocks(opts.delay, opts.blockTime);
+  } catch (e) {
+    if (e instanceof Error) {
+      throw new OptionsError({
+        delay: e.message,
+      });
+    } else {
+      throw e;
+    }
+  }
+}
+
+function getVotingPeriod(opts: Required<GovernorOptions>): number {
+  try {
+    return durationToBlocks(opts.period, opts.blockTime);
+  } catch (e) {
+    if (e instanceof Error) {
+      throw new OptionsError({
+        period: e.message,
+      });
+    } else {
+      throw e;
+    }
+  }
+}
+
+function validateDecimals(decimals: number) {
+  if (!/^\d+$/.test(decimals.toString())) {
+    throw new OptionsError({
+      decimals: 'Not a valid number',
+    });
+  }
+}
+
+function getProposalThreshold({ proposalThreshold, decimals, votes }: Required<GovernorOptions>): string {
+  if (!/^\d+$/.test(proposalThreshold)) {
+    throw new OptionsError({
+      proposalThreshold: 'Not a valid number',
+    });
+  }
+
+  if (/^0+$/.test(proposalThreshold) || decimals === 0 || votes === 'erc721votes') {
+    return proposalThreshold;
+  } else {
+    return `${proposalThreshold}e${decimals}`;
+  }
+}
+
+function setVotingParameters(c: ContractBuilder, opts: Required<GovernorOptions>) {
+  const delayBlocks = getVotingDelay(opts);
+  c.setFunctionBody([`return ${delayBlocks}; // ${opts.delay}`], functions.votingDelay);
+
+  const periodBlocks = getVotingPeriod(opts);
+  c.setFunctionBody([`return ${periodBlocks}; // ${opts.period}`], functions.votingPeriod);
+}
+
+function setProposalThreshold(c: ContractBuilder, opts: Required<GovernorOptions>) {
+  const threshold = getProposalThreshold(opts);
+  const nonZeroThreshold = parseInt(threshold) !== 0;
+
+  if (nonZeroThreshold) {
+    c.setFunctionBody([`return ${threshold};`], functions.proposalThreshold);
+  }
+}
+
+function addCounting(c: ContractBuilder, { bravo }: GovernorOptions) {
+  if (!bravo) {
+    c.addParent({
+      name: 'GovernorCountingSimple',
+      path: '@openzeppelin/contracts/governance/extensions/GovernorCountingSimple.sol',
+    });
+  }
+}
+
+const votesModules = {
+  erc20votes: {
+    tokenType: 'IVotes',
+    parentName: 'GovernorVotes',
+  },
+  erc721votes: {
+    tokenType: 'IVotes',
+    parentName: 'GovernorVotes',
+  },
+  comp: {
+    tokenType: 'ERC20VotesComp',
+    parentName: 'GovernorVotesComp',
+  },
+} as const;
+
+function addVotes(c: ContractBuilder, { votes }: Required<GovernorOptions>) {
+  const tokenArg = '_token';
+  const { tokenType, parentName } = votesModules[votes];
+
+  c.addConstructorArgument({
+    type: tokenType,
+    name: tokenArg,
+  });
+
+  c.addParent({
+    name: parentName,
+    path: `@openzeppelin/contracts/governance/extensions/${parentName}.sol`,
+  }, [{ lit: tokenArg }]);
+}
+
+export const numberPattern = /^(?!$)(\d*)(?:\.(\d+))?(?:e(\d+))?$/;
+
+function addQuorum(c: ContractBuilder, opts: Required<GovernorOptions>) {
+  if (opts.quorumMode === 'percent') {
+    if (opts.votes !== 'erc20votes' && opts.votes !== 'erc721votes') {
+      throw new OptionsError({
+        quorumPercent: 'Percent-based quorum is only available for ERC20Votes or ERC721Votes',
+      });
+    }
+
+    if (opts.quorumPercent > 100) {
+      throw new OptionsError({
+        quorumPercent: 'Invalid percentage',
+      });
+    }
+
+    let { quorumFractionNumerator, quorumFractionDenominator } = getQuorumFractionComponents(opts.quorumPercent);
+
+    if (quorumFractionDenominator !== undefined) {
+      c.addOverride('GovernorVotesQuorumFraction', functions.quorumDenominator);
+      c.setFunctionBody([
+        `return ${quorumFractionDenominator};`
+      ], functions.quorumDenominator, 'pure');
+    }
+
+    c.addParent({
+      name: 'GovernorVotesQuorumFraction',
+      path: '@openzeppelin/contracts/governance/extensions/GovernorVotesQuorumFraction.sol',
+    }, [quorumFractionNumerator]);
+    c.addOverride('GovernorVotesQuorumFraction', functions.quorum);
+  }
+
+  else if (opts.quorumMode === 'absolute') {
+    if (!numberPattern.test(opts.quorumAbsolute)) {
+      throw new OptionsError({
+        quorumAbsolute: 'Not a valid number',
+      });
+    }
+
+    let returnStatement = (opts.decimals === 0 || opts.votes === 'erc721votes') ? 
+      `return ${opts.quorumAbsolute};` :
+      `return ${opts.quorumAbsolute}e${opts.decimals};`;
+
+    c.setFunctionBody([
+      returnStatement,
+    ], functions.quorum, 'pure');
+  }
+}
+
+const timelockModules = {
+  openzeppelin: {
+    timelockType: 'TimelockController',
+    parentName: 'GovernorTimelockControl',
+  },
+  compound: {
+    timelockType: 'ICompoundTimelock',
+    parentName: 'GovernorTimelockCompound',
+  },
+} as const;
+
+function getQuorumFractionComponents(quorumPercent: number): {quorumFractionNumerator: number, quorumFractionDenominator: string | undefined} {
+  let quorumFractionNumerator = quorumPercent;
+  let quorumFractionDenominator = undefined;
+
+  const quorumPercentSegments = quorumPercent.toString().split(".");
+  if (quorumPercentSegments.length > 2) {
+    throw new OptionsError({
+      quorumPercent: 'Invalid percentage',
+    });
+  } else if (quorumPercentSegments.length == 2 && quorumPercentSegments[0] !== undefined && quorumPercentSegments[1] !== undefined) {
+    quorumFractionNumerator = parseInt(quorumPercentSegments[0].concat(quorumPercentSegments[1]));
+    const decimals = quorumPercentSegments[1].length;
+    quorumFractionDenominator = '100';
+    while (quorumFractionDenominator.length < decimals + 3) {
+      quorumFractionDenominator += '0';
+    }
+  }
+  return { quorumFractionNumerator, quorumFractionDenominator };
+}
+
+function addTimelock(c: ContractBuilder, { timelock }: Required<GovernorOptions>) {
+  if (timelock === false) {
+    return;
+  }
+
+  const timelockArg = '_timelock';
+  const { timelockType, parentName } = timelockModules[timelock];
+
+  c.addConstructorArgument({
+    type: timelockType,
+    name: timelockArg,
+  });
+
+  c.addParent({
+    name: parentName,
+    path: `@openzeppelin/contracts/governance/extensions/${parentName}.sol`,
+  }, [{ lit: timelockArg }]);
+  c.addOverride('IGovernor', functions.propose);
+  c.addOverride(parentName, functions._execute);
+  c.addOverride(parentName, functions._cancel);
+  c.addOverride(parentName, functions._executor);
+  c.addOverride(parentName, functions.state);
+  c.addOverride(parentName, supportsInterface);
+}
+
+function addBravo(c: ContractBuilder, { bravo, timelock }: GovernorOptions) {
+  if (bravo) {
+    if (timelock === false) {
+      throw new OptionsError({
+        timelock: 'GovernorBravo compatibility requires a timelock',
+      });
+    }
+
+    c.addParent({
+      name: 'GovernorCompatibilityBravo',
+      path: '@openzeppelin/contracts/governance/compatibility/GovernorCompatibilityBravo.sol',
+    });
+    c.addOverride('IGovernor', functions.state);
+    c.addOverride('GovernorCompatibilityBravo', functions.propose);
+    c.addOverride('IERC165', supportsInterface);
+  }
+}
+
+const functions = defineFunctions({
+  votingDelay: {
+    args: [],
+    returns: ['uint256'],
+    kind: 'public',
+    mutability: 'pure',
+  },
+  votingPeriod: {
+    args: [],
+    returns: ['uint256'],
+    kind: 'public',
+    mutability: 'pure',
+  },
+  proposalThreshold: {
+    args: [],
+    returns: ['uint256'],
+    kind: 'public',
+    mutability: 'pure',
+  },
+  quorum: {
+    args: [
+      { name: 'blockNumber', type: 'uint256' },
+    ],
+    returns: ['uint256'],
+    kind: 'public',
+    mutability: 'view',
+  },
+  quorumDenominator: {
+    args: [],
+    returns: ['uint256'],
+    kind: 'public',
+    mutability: 'view',
+  },
+  propose: {
+    args: [
+      { name: 'targets', type: 'address[] memory' },
+      { name: 'values', type: 'uint256[] memory' },
+      { name: 'calldatas', type: 'bytes[] memory' },
+      { name: 'description', type: 'string memory' },
+    ],
+    returns: ['uint256'],
+    kind: 'public',
+  },
+  _execute: {
+    args: [
+      { name: 'proposalId', type: 'uint256' },
+      { name: 'targets', type: 'address[] memory' },
+      { name: 'values', type: 'uint256[] memory' },
+      { name: 'calldatas', type: 'bytes[] memory' },
+      { name: 'descriptionHash', type: 'bytes32' },
+    ],
+    kind: 'internal',
+  },
+  _cancel: {
+    args: [
+      { name: 'targets', type: 'address[] memory' },
+      { name: 'values', type: 'uint256[] memory' },
+      { name: 'calldatas', type: 'bytes[] memory' },
+      { name: 'descriptionHash', type: 'bytes32' },
+    ],
+    returns: ['uint256'],
+    kind: 'internal',
+  },
+  state: {
+    args: [
+      { name: 'proposalId', type: 'uint256' },
+    ],
+    returns: ['ProposalState'],
+    kind: 'public',
+    mutability: 'view',
+  },
+  _executor: {
+    args: [],
+    returns: ['address'],
+    kind: 'internal',
+    mutability: 'view',
+  },
+});

package/src/index.ts

@@ -0,0 +1,23 @@
+export type { GenericOptions, KindedOptions } from './build-generic';
+export { buildGeneric } from './build-generic';
+
+export type { Contract } from './contract';
+export { ContractBuilder } from './contract';
+
+export { printContract } from './print';
+export { printContractVersioned } from './print-versioned';
+
+export type { Access } from './set-access-control';
+export type { Upgradeable } from './set-upgradeable';
+export type { Info } from './set-info';
+
+export { premintPattern } from './erc20';
+export { defaults as infoDefaults } from './set-info';
+
+export type { OptionsErrorMessages } from './error';
+export { OptionsError } from './error';
+
+export type { Kind } from './kind';
+export { sanitizeKind } from './kind';
+
+export { erc20, erc721, erc1155, governor } from './api';

package/src/kind.ts

@@ -0,0 +1,30 @@
+import type { GenericOptions } from './build-generic';
+
+export type Kind = GenericOptions['kind'];
+
+export function sanitizeKind(kind: unknown): Kind {
+  if (typeof kind === 'string') {
+    const sanitized = kind.replace(/^(ERC|.)/i, c => c.toUpperCase());
+    if (isKind(sanitized)) {
+      return sanitized;
+    }
+  }
+  return 'ERC20';
+}
+
+function isKind<T>(value: Kind | T): value is Kind {
+  switch (value) {
+    case 'ERC20':
+    case 'ERC1155':
+    case 'ERC721':
+    case 'Governor':
+      return true;
+
+    default: {
+      // Static assert that we've checked all kinds.
+      const _: T = value;
+      return false;
+    }
+  }
+}
+

package/src/options.ts

@@ -0,0 +1,45 @@
+import path from 'path';
+
+import type { Contract } from './contract';
+
+const upgradeableName = (n: string) => {
+  if (n === 'Initializable') {
+    return n;
+  } else {
+    return n.replace(/(Upgradeable)?(?=\.|$)/, 'Upgradeable');
+  }
+}
+
+const upgradeableImport = (p: string) => {
+  const { dir, ext, name } = path.parse(p);
+  // Use path.posix to get forward slashes
+  return path.posix.format({
+    ext,
+    dir: dir.replace(/^@openzeppelin\/contracts/, '@openzeppelin/contracts-upgradeable'),
+    name: upgradeableName(name),
+  });
+};
+
+export interface Options {
+  transformImport?: (path: string) => string;
+}
+
+export interface Helpers extends Required<Options> {
+  upgradeable: boolean;
+  transformName: (name: string) => string;
+  transformVariable: (code: string) => string;
+}
+
+export function withHelpers(contract: Contract, opts: Options = {}): Helpers {
+  const upgradeable = contract.upgradeable;
+  const transformName = (n: string) => upgradeable ? upgradeableName(n) : n;
+  return {
+    upgradeable,
+    transformName,
+    transformImport: p1 => {
+      const p2 = upgradeable ? upgradeableImport(p1) : p1;
+      return opts.transformImport?.(p2) ?? p2;
+    },
+    transformVariable: v => v.replace(/[A-Z]\w*(?=\.|$)/, transformName),
+  };
+}

package/src/print-versioned.ts

@@ -0,0 +1,12 @@
+import { version as contractsVersion } from "@openzeppelin/contracts/package.json";
+import type { Contract } from "./contract";
+import { printContract } from "./print";
+
+export function printContractVersioned(contract: Contract): string {
+  return printContract(contract, {
+    transformImport: p =>
+      p.replace(/^@openzeppelin\/contracts(-upgradeable)?/, `$&@${contractsVersion}`),
+  });
+}
+
+