@openzeppelin/wizard 0.1.0

package/src/erc721.ts

@@ -0,0 +1,250 @@
+import { Contract, ContractBuilder } from './contract';
+import { Access, setAccessControl } from './set-access-control';
+import { addPausable } from './add-pausable';
+import { supportsInterface } from './common-functions';
+import { defineFunctions } from './utils/define-functions';
+import { CommonOptions, withCommonDefaults, defaults as commonDefaults } from './common-options';
+import { setUpgradeable } from './set-upgradeable';
+import { setInfo } from './set-info';
+import { printContract } from './print';
+
+export interface ERC721Options extends CommonOptions {
+  name: string;
+  symbol: string;
+  baseUri?: string;
+  enumerable?: boolean;
+  uriStorage?: boolean;
+  burnable?: boolean;
+  pausable?: boolean;
+  mintable?: boolean;
+  incremental?: boolean;
+  votes?: boolean;
+}
+
+export const defaults: Required<ERC721Options> = {
+  name: 'MyToken',
+  symbol: 'MTK',
+  baseUri: '',
+  enumerable: false,
+  uriStorage: false,
+  burnable: false,
+  pausable: false,
+  mintable: false,
+  incremental: false,
+  votes: false,
+  access: commonDefaults.access,
+  upgradeable: commonDefaults.upgradeable,
+  info: commonDefaults.info
+} as const;
+
+function withDefaults(opts: ERC721Options): Required<ERC721Options> {
+  return {
+    ...opts,
+    ...withCommonDefaults(opts),
+    baseUri: opts.baseUri ?? defaults.baseUri,
+    enumerable: opts.enumerable ?? defaults.enumerable,
+    uriStorage: opts.uriStorage ?? defaults.uriStorage,
+    burnable: opts.burnable ?? defaults.burnable,
+    pausable: opts.pausable ?? defaults.pausable,
+    mintable: opts.mintable ?? defaults.mintable,
+    incremental: opts.incremental ?? defaults.incremental,
+    votes: opts.votes ?? defaults.votes,
+  };
+}
+
+export function printERC721(opts: ERC721Options = defaults): string {
+  return printContract(buildERC721(opts));
+}
+
+export function buildERC721(opts: ERC721Options): Contract {
+  const allOpts = withDefaults(opts);
+
+  const c = new ContractBuilder(allOpts.name);
+
+  const { access, upgradeable, info } = allOpts;
+
+  addBase(c, allOpts.name, allOpts.symbol);
+
+  if (allOpts.baseUri) {
+    addBaseURI(c, allOpts.baseUri);
+  }
+
+  if (allOpts.enumerable) {
+    addEnumerable(c);
+  }
+
+  if (allOpts.uriStorage) {
+    addURIStorage(c);
+  }
+
+  if (allOpts.pausable) {
+    addPausable(c, access, [functions._beforeTokenTransfer]);
+  }
+
+  if (allOpts.burnable) {
+    addBurnable(c);
+  }
+
+  if (allOpts.mintable) {
+    addMintable(c, access, allOpts.incremental, allOpts.uriStorage);
+  }
+
+  if (allOpts.votes) {
+    addVotes(c, allOpts.name);
+  }
+
+  setUpgradeable(c, upgradeable, access);
+
+  setInfo(c, info);
+
+  return c;
+}
+
+function addBase(c: ContractBuilder, name: string, symbol: string) {
+  c.addParent(
+    {
+      name: 'ERC721',
+      path: '@openzeppelin/contracts/token/ERC721/ERC721.sol',
+    },
+    [name, symbol],
+  );
+
+  c.addOverride('ERC721', functions._beforeTokenTransfer);
+  c.addOverride('ERC721', functions._afterTokenTransfer);
+  c.addOverride('ERC721', functions._burn);
+  c.addOverride('ERC721', functions.tokenURI);
+  c.addOverride('ERC721', supportsInterface);
+}
+
+function addBaseURI(c: ContractBuilder, baseUri: string) {
+  c.addOverride('ERC721', functions._baseURI);
+  c.setFunctionBody([`return ${JSON.stringify(baseUri)};`], functions._baseURI);
+}
+
+function addEnumerable(c: ContractBuilder) {
+  c.addParent({
+    name: 'ERC721Enumerable',
+    path: '@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol',
+  });
+
+  c.addOverride('ERC721Enumerable', functions._beforeTokenTransfer);
+  c.addOverride('ERC721Enumerable', supportsInterface);
+}
+
+function addURIStorage(c: ContractBuilder) {
+  c.addParent({
+    name: 'ERC721URIStorage',
+    path: '@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol',
+  });
+
+  c.addOverride('ERC721URIStorage', functions._burn);
+  c.addOverride('ERC721URIStorage', functions.tokenURI);
+}
+
+function addBurnable(c: ContractBuilder) {
+  c.addParent({
+    name: 'ERC721Burnable',
+    path: '@openzeppelin/contracts/token/ERC721/extensions/ERC721Burnable.sol',
+  });
+}
+
+function addMintable(c: ContractBuilder, access: Access, incremental = false, uriStorage = false) {
+  const fn = getMintFunction(incremental, uriStorage);
+  setAccessControl(c, fn, access, 'MINTER');
+
+  if (incremental) {
+    c.addUsing({
+      name: 'Counters',
+      path: '@openzeppelin/contracts/utils/Counters.sol',
+    }, 'Counters.Counter');
+    c.addVariable('Counters.Counter private _tokenIdCounter;');
+    c.addFunctionCode('uint256 tokenId = _tokenIdCounter.current();', fn);
+    c.addFunctionCode('_tokenIdCounter.increment();', fn);
+    c.addFunctionCode('_safeMint(to, tokenId);', fn);
+  } else {
+    c.addFunctionCode('_safeMint(to, tokenId);', fn);
+  }
+
+  if (uriStorage) {
+    c.addFunctionCode('_setTokenURI(tokenId, uri);', fn);
+  }
+}
+
+function addVotes(c: ContractBuilder, name: string) {
+  c.addParent(
+    {
+      name: 'EIP712',
+      path: '@openzeppelin/contracts/utils/cryptography/draft-EIP712.sol',
+    },
+    [name, "1"]
+  );
+  c.addParent(
+    {
+      name: 'ERC721Votes',
+      path: '@openzeppelin/contracts/token/ERC721/extensions/draft-ERC721Votes.sol',
+    });
+  c.addOverride('ERC721Votes', functions._afterTokenTransfer);
+}
+
+const functions = defineFunctions({
+  _beforeTokenTransfer: {
+    kind: 'internal' as const,
+    args: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'tokenId', type: 'uint256' },
+    ],
+  },
+
+  _afterTokenTransfer: {
+    kind: 'internal' as const,
+    args: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'tokenId', type: 'uint256' },
+    ],
+  },
+
+  _burn: {
+    kind: 'internal' as const,
+    args: [
+      { name: 'tokenId', type: 'uint256' },
+    ],
+  },
+
+  tokenURI: {
+    kind: 'public' as const,
+    args: [
+      { name: 'tokenId', type: 'uint256' },
+    ],
+    returns: ['string memory'],
+    mutability: 'view' as const,
+  },
+
+  _baseURI: {
+    kind: 'internal' as const,
+    args: [],
+    returns: ['string memory'],
+    mutability: 'pure' as const,
+  },
+});
+
+function getMintFunction(incremental: boolean, uriStorage: boolean) {
+  const fn = {
+    name: 'safeMint',
+    kind: 'public' as const,
+    args: [
+      { name: 'to', type: 'address' },
+    ],
+  };
+
+  if (!incremental) {
+    fn.args.push({ name: 'tokenId', type: 'uint256' });
+  }
+
+  if (uriStorage) {
+    fn.args.push({ name: 'uri', type: 'string memory' });
+  }
+
+  return fn;
+}

package/src/error.ts

@@ -0,0 +1,7 @@
+export type OptionsErrorMessages = { [prop in string]?: string };
+
+export class OptionsError extends Error {
+  constructor(readonly messages: OptionsErrorMessages) {
+    super("Invalid options for Governor");
+  }
+}

package/src/generate/alternatives.ts

@@ -0,0 +1,38 @@
+import { mapValues } from "../utils/map-values";
+
+type Blueprint = Record<string, readonly unknown[]>;
+
+type Alternatives<B extends Blueprint> = {
+  [k in keyof B]: B[k][number];
+};
+
+export function* generateAlternatives<B extends Blueprint>(
+  blueprint: B,
+): Generator<Alternatives<B>> {
+  const entries = Object.entries(blueprint).map(([key, values]) => ({
+    key,
+    values,
+    current: 0,
+    limit: values.length,
+  }));
+
+  for (; !done(); advance()) {
+    yield Object.fromEntries(
+      entries.map(e => [e.key, e.values[e.current % e.limit]]),
+    ) as Alternatives<B>;
+  }
+
+  function done() {
+    const last = entries[entries.length - 1];
+    return last?.current === last?.limit;
+  }
+
+  function advance() {
+    for (const e of entries) {
+      e.current = (e.current % e.limit) + 1;
+      if (e.current < e.limit) {
+        break;
+      }
+    }
+  }
+}

package/src/generate/erc1155.ts

@@ -0,0 +1,23 @@
+import type { ERC1155Options } from '../erc1155';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { upgradeableOptions } from '../set-upgradeable';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyToken'],
+  uri: ['https://example.com/'],
+  burnable: booleans,
+  pausable: booleans,
+  mintable: booleans,
+  supply: booleans,
+  access: accessOptions,
+  upgradeable: upgradeableOptions,
+  info: infoOptions,
+};
+
+export function* generateERC1155Options(): Generator<Required<ERC1155Options>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/erc20.ts

@@ -0,0 +1,27 @@
+import type { ERC20Options } from '../erc20';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { upgradeableOptions } from '../set-upgradeable';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyToken'],
+  symbol: ['MTK'],
+  burnable: booleans,
+  snapshots: booleans,
+  pausable: booleans,
+  mintable: booleans,
+  permit: booleans,
+  votes: booleans,
+  flashmint: booleans,
+  premint: ['1'],
+  access: accessOptions,
+  upgradeable: upgradeableOptions,
+  info: infoOptions,
+};
+
+export function* generateERC20Options(): Generator<Required<ERC20Options>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/erc721.ts

@@ -0,0 +1,27 @@
+import type { ERC721Options } from '../erc721';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { upgradeableOptions } from '../set-upgradeable';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyToken'],
+  symbol: ['MTK'],
+  baseUri: ['https://example.com/'],
+  enumerable: booleans,
+  uriStorage: booleans,
+  burnable: booleans,
+  pausable: booleans,
+  mintable: booleans,
+  incremental: booleans,
+  access: accessOptions,
+  upgradeable: upgradeableOptions,
+  info: infoOptions,
+  votes: booleans,
+};
+
+export function* generateERC721Options(): Generator<Required<ERC721Options>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/governor.ts

@@ -0,0 +1,30 @@
+import { defaults, GovernorOptions, timelockOptions, votesOptions } from '../governor';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { upgradeableOptions } from '../set-upgradeable';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyGovernor'],
+  delay: ['1 week'],
+  period: ['1 week'],
+  blockTime: [defaults.blockTime],
+  proposalThreshold: ['0', '1000'],
+  decimals: [18],
+  quorumMode: ['percent', 'absolute'] as const,
+  quorumPercent: [4],
+  quorumAbsolute: ['1000'],
+  votes: votesOptions,
+  timelock: timelockOptions,
+  bravo: booleans,
+  settings: booleans,
+  upgradeable: upgradeableOptions,
+  access: accessOptions,
+  info: infoOptions,
+};
+
+export function* generateGovernorOptions(): Generator<Required<GovernorOptions>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/sources.ts

@@ -0,0 +1,91 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+import { generateERC20Options } from './erc20';
+import { generateERC721Options } from './erc721';
+import { generateERC1155Options } from './erc1155';
+import { buildGeneric, GenericOptions } from '../build-generic';
+import { printContract } from '../print';
+import { generateGovernorOptions } from './governor';
+import { OptionsError } from '../error';
+import { findCover } from '../utils/find-cover';
+import type { Contract } from '../contract';
+
+type Subset = 'all' | 'minimal-cover';
+
+export function* generateOptions(): Generator<GenericOptions> {
+  for (const kindOpts of generateERC20Options()) {
+    yield { kind: 'ERC20', ...kindOpts };
+  }
+
+  for (const kindOpts of generateERC721Options()) {
+    yield { kind: 'ERC721', ...kindOpts };
+  }
+
+  for (const kindOpts of generateERC1155Options()) {
+    yield { kind: 'ERC1155', ...kindOpts };
+  }
+
+  for (const kindOpts of generateGovernorOptions()) {
+    yield { kind: 'Governor', ...kindOpts };
+  }
+}
+
+interface GeneratedContract {
+  id: string;
+  options: GenericOptions;
+  contract: Contract;
+}
+
+interface GeneratedSource extends GeneratedContract {
+  source: string;
+}
+
+function generateContractSubset(subset: Subset): GeneratedContract[] {
+  const contracts = [];
+
+  for (const options of generateOptions()) {
+    const id = crypto
+      .createHash('sha1')
+      .update(JSON.stringify(options))
+      .digest()
+      .toString('hex');
+
+    try {
+      const contract = buildGeneric(options);
+      contracts.push({ id, options, contract });
+    } catch (e: unknown) {
+      if (e instanceof OptionsError) {
+        continue;
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  if (subset === 'all') {
+    return contracts;
+  } else {
+    const getParents = (c: GeneratedContract) => c.contract.parents.map(p => p.contract.path);
+    return [
+      ...findCover(contracts.filter(c => c.options.upgradeable), getParents),
+      ...findCover(contracts.filter(c => !c.options.upgradeable), getParents),
+    ];
+  }
+}
+
+export function* generateSources(subset: Subset): Generator<GeneratedSource> {
+  for (const c of generateContractSubset(subset)) {
+    const source = printContract(c.contract);
+    yield { ...c, source };
+  }
+}
+
+export async function writeGeneratedSources(dir: string, subset: Subset): Promise<void> {
+  await fs.mkdir(dir, { recursive: true });
+
+  for (const { id, source } of generateSources(subset)) {
+    await fs.writeFile(path.format({ dir, name: id, ext: '.sol' }), source);
+  }
+}

package/src/governor.test.ts

@@ -0,0 +1,120 @@
+import test from 'ava';
+import { governor } from '.';
+
+import { buildGovernor, GovernorOptions } from './governor';
+import { printContract } from './print';
+
+function testGovernor(title: string, opts: Partial<GovernorOptions>) {
+  test(title, t => {
+    const c = buildGovernor({
+      name: 'MyGovernor',
+      delay: '1 week',
+      period: '1 week',
+      settings: false,
+      ...opts,
+    });
+    t.snapshot(printContract(c));
+  });
+}
+
+/**
+ * Tests external API for equivalence with internal API
+ */
+ function testAPIEquivalence(title: string, opts?: GovernorOptions) {
+  test(title, t => {
+    t.is(governor.print(opts), printContract(buildGovernor({
+      name: 'MyGovernor',
+      delay: '1 block',
+      period: '1 week',
+      ...opts,
+    })));
+  });
+}
+
+testGovernor('governor with proposal threshold', {
+  proposalThreshold: '1',
+});
+
+testGovernor('governor with custom block time', {
+  blockTime: 6,
+});
+
+testGovernor('governor with custom decimals', {
+  decimals: 6,
+  proposalThreshold: '1',
+  quorumMode: 'absolute',
+  quorumAbsolute: '1',
+});
+
+testGovernor('governor with 0 decimals', {
+  decimals: 0,
+  proposalThreshold: '1',
+  quorumMode: 'absolute',
+  quorumAbsolute: '1',
+});
+
+testGovernor('governor with settings', {
+  settings: true,
+  proposalThreshold: '1',
+});
+
+testGovernor('governor with bravo', {
+  bravo: true,
+});
+
+testGovernor('governor with erc20votes', {
+  votes: 'erc20votes',
+});
+
+testGovernor('governor with erc721votes', {
+  votes: 'erc721votes',
+});
+
+testGovernor('governor with erc721votes omit decimals', {
+  votes: 'erc721votes',
+  decimals: 6,
+  proposalThreshold: '1',
+  quorumMode: 'absolute',
+  quorumAbsolute: '5',
+});
+
+testGovernor('governor with erc721votes settings omit decimals', {
+  votes: 'erc721votes',
+  decimals: 6,
+  proposalThreshold: '10',
+  settings: true,
+});
+
+testGovernor('governor with comp', {
+  votes: 'comp',
+  quorumMode: 'absolute',
+  quorumAbsolute: '1',
+});
+
+testGovernor('governor with percent quorum', {
+  quorumMode: 'percent',
+  quorumPercent: 6,
+});
+
+testGovernor('governor with fractional percent quorum', {
+  quorumMode: 'percent',
+  quorumPercent: 0.5,
+});
+
+testGovernor('governor with openzeppelin timelock', {
+  timelock: 'openzeppelin',
+});
+
+testGovernor('governor with compound timelock', {
+  timelock: 'compound',
+});
+
+testAPIEquivalence('API default');
+
+testAPIEquivalence('API basic', { name: 'CustomGovernor', delay: '2 weeks', period: '2 week' });
+
+testAPIEquivalence('API basic upgradeable', { name: 'CustomGovernor', delay: '2 weeks', period: '2 week', upgradeable: 'uups' });
+
+test('API assert defaults', async t => {
+  t.is(governor.print(governor.defaults), governor.print());
+});