@openzeppelin/wizard 0.1.0

package/src/print.ts

@@ -0,0 +1,236 @@
+import 'array.prototype.flatmap/auto';
+
+import type { Contract, Parent, ContractFunction, FunctionArgument, Value, NatspecTag } from './contract';
+import { Options, Helpers, withHelpers } from './options';
+
+import { formatLines, spaceBetween, Lines } from './utils/format-lines';
+import { mapValues } from './utils/map-values';
+
+const SOLIDITY_VERSION = '0.8.4';
+
+export function printContract(contract: Contract, opts?: Options): string {
+  const helpers = withHelpers(contract, opts);
+
+  const fns = mapValues(
+    sortedFunctions(contract),
+    fns => fns.map(fn => printFunction(fn, helpers)),
+  );
+
+  const hasOverrides = fns.override.some(l => l.length > 0);
+
+  return formatLines(
+    ...spaceBetween(
+      [
+        `// SPDX-License-Identifier: ${contract.license}`,
+        `pragma solidity ^${SOLIDITY_VERSION};`,
+      ],
+
+      contract.imports.map(p => `import "${helpers.transformImport(p)}";`),
+
+      [
+        ...printNatspecTags(contract.natspecTags),
+        [`contract ${contract.name}`, ...printInheritance(contract, helpers), '{'].join(' '),
+
+        spaceBetween(
+          printUsingFor(contract, helpers),
+          contract.variables.map(helpers.transformVariable),
+          printConstructor(contract, helpers),
+          ...fns.code,
+          ...fns.modifiers,
+          hasOverrides ? [`// The following functions are overrides required by Solidity.`] : [],
+          ...fns.override,
+        ),
+
+        `}`,
+      ],
+    ),
+  );
+}
+
+function printInheritance(contract: Contract, { transformName }: Helpers): [] | [string] {
+  if (contract.parents.length > 0) {
+    return ['is ' + contract.parents.map(p => transformName(p.contract.name)).join(', ')];
+  } else {
+    return [];
+  }
+}
+
+function printUsingFor(contract: Contract, { transformName }: Helpers): string[] {
+  return contract.using.map(
+    u => `using ${transformName(u.library.name)} for ${transformName(u.usingFor)};`,
+  );
+}
+
+function printConstructor(contract: Contract, helpers: Helpers): Lines[] {
+  const hasParentParams = contract.parents.some(p => p.params.length > 0);
+  const hasConstructorCode = contract.constructorCode.length > 0;
+  if (hasParentParams || hasConstructorCode) {
+    const parents = contract.parents
+      .filter(hasInitializer)
+      .flatMap(p => printParentConstructor(p, helpers));
+    const modifiers = helpers.upgradeable ? ['initializer public'] : parents;
+    const args = contract.constructorArgs.map(a =>  printArgument(a, helpers));
+    const body = helpers.upgradeable
+      ? spaceBetween(
+        parents.map(p => p + ';'),
+        contract.constructorCode,
+      )
+      : contract.constructorCode;
+    const head = helpers.upgradeable ? 'function initialize' : 'constructor';
+    const constructor = printFunction2(
+      head,
+      args,
+      modifiers,
+      body,
+    );
+    if (!helpers.upgradeable) {
+      return constructor;
+    } else {
+      return spaceBetween(
+        [
+          '/// @custom:oz-upgrades-unsafe-allow constructor',
+          'constructor() {',
+          [
+            '_disableInitializers();'
+          ],
+          '}'
+        ],
+        constructor,
+      );
+    }
+  } else {
+    return [];
+  }
+}
+
+function hasInitializer(parent: Parent) {
+  // CAUTION
+  // This list is validated by compilation of SafetyCheck.sol.
+  // Always keep this list and that file in sync.
+  return !['Initializable'].includes(parent.contract.name);
+}
+
+type SortedFunctions = Record<'code' | 'modifiers' | 'override', ContractFunction[]>;
+
+// Functions with code first, then those with modifiers, then the rest
+function sortedFunctions(contract: Contract): SortedFunctions {
+  const fns: SortedFunctions = { code: [], modifiers: [], override: [] };
+
+  for (const fn of contract.functions) {
+    if (fn.code.length > 0) {
+      fns.code.push(fn);
+    } else if (fn.modifiers.length > 0) {
+      fns.modifiers.push(fn);
+    } else {
+      fns.override.push(fn);
+    }
+  }
+
+  return fns;
+}
+
+function printParentConstructor({ contract, params }: Parent, helpers: Helpers): [] | [string] {
+  const fn = helpers.upgradeable ? `__${contract.name}_init` : contract.name;
+  if (helpers.upgradeable || params.length > 0) {
+    return [
+      fn + '(' + params.map(printValue).join(', ') + ')',
+    ];
+  } else {
+    return [];
+  }
+}
+
+export function printValue(value: Value): string {
+  if (typeof value === 'object') {
+    if ('lit' in value) {
+      return value.lit;
+    } else if ('note' in value) {
+      return `${printValue(value.value)} /* ${value.note} */`;
+    } else {
+      throw Error('Unknown value type');
+    }
+  } else if (typeof value === 'number') {
+    if (Number.isSafeInteger(value)) {
+      return value.toFixed(0);
+    } else {
+      throw new Error(`Number not representable (${value})`);
+    }
+  } else {
+    return JSON.stringify(value);
+  }
+}
+
+function printFunction(fn: ContractFunction, helpers: Helpers): Lines[] {
+  const { transformName } = helpers;
+
+  if (fn.override.size <= 1 && fn.modifiers.length === 0 && fn.code.length === 0 && !fn.final) {
+    return []
+  }
+
+  const modifiers: string[] = [fn.kind, ...fn.modifiers];
+
+  if (fn.mutability !== 'nonpayable') {
+    modifiers.splice(1, 0, fn.mutability);
+  }
+
+  if (fn.override.size === 1) {
+    modifiers.push(`override`);
+  } else if (fn.override.size > 1) {
+    modifiers.push(`override(${[...fn.override].map(transformName).join(', ')})`);
+  }
+
+  if (fn.returns?.length) {
+    modifiers.push(`returns (${fn.returns.join(', ')})`);
+  }
+
+  const code = [...fn.code];
+
+  if (fn.override.size > 0 && !fn.final) {
+    const superCall = `super.${fn.name}(${fn.args.map(a => a.name).join(', ')});`;
+    code.push(fn.returns?.length ? 'return ' + superCall : superCall);
+  }
+
+  if (modifiers.length + fn.code.length > 1) {
+    return printFunction2(
+      'function ' + fn.name,
+      fn.args.map(a => printArgument(a, helpers)),
+      modifiers,
+      code,
+    );
+  } else {
+    return [];
+  }
+}
+
+// generic for functions and constructors
+// kindedName = 'function foo' or 'constructor'
+function printFunction2(kindedName: string, args: string[], modifiers: string[], code: Lines[]): Lines[] {
+  const fn = [];
+
+  const headingLength = [kindedName, ...args, ...modifiers]
+    .map(s => s.length)
+    .reduce((a, b) => a + b);
+
+  const braces = code.length > 0 ? '{' : '{}';
+
+  if (headingLength <= 72) {
+    fn.push([`${kindedName}(${args.join(', ')})`, ...modifiers, braces].join(' '));
+  } else {
+    fn.push(`${kindedName}(${args.join(', ')})`, modifiers, braces);
+  }
+
+  if (code.length > 0) {
+    fn.push(code, '}');
+  }
+
+  return fn;
+}
+
+function printArgument(arg: FunctionArgument, { transformName }: Helpers): string {
+  const type = /^[A-Z]/.test(arg.type) ? transformName(arg.type) : arg.type;
+  return [type, arg.name].join(' ');
+}
+
+function printNatspecTags(tags: NatspecTag[]): string[] {
+  return tags.map(({ key, value }) => `/// ${key} ${value}`);
+}

package/src/scripts/prepare.ts

@@ -0,0 +1,60 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import hre from 'hardhat';
+import type { BuildInfo } from 'hardhat/types';
+import type { SourceUnit } from 'solidity-ast';
+import { findAll } from 'solidity-ast/utils';
+import _rimraf from 'rimraf';
+import { promisify } from 'util';
+import { version } from "@openzeppelin/contracts/package.json";
+
+const rimraf = promisify(_rimraf);
+
+import type { OpenZeppelinContracts } from '../../openzeppelin-contracts';
+import { writeGeneratedSources } from '../generate/sources';
+import { mapValues } from '../utils/map-values';
+import { transitiveClosure } from '../utils/transitive-closure';
+
+async function main() {
+  const generatedSourcesPath = path.join(hre.config.paths.sources, 'generated');
+  await rimraf(generatedSourcesPath);
+  await writeGeneratedSources(generatedSourcesPath, 'minimal-cover');
+  await hre.run('compile');
+
+  const dependencies: Record<string, Set<string>> = {};
+  const sources: Record<string, string> = {};
+
+  for (const buildInfoPath of await hre.artifacts.getBuildInfoPaths()) {
+    const buildInfo: BuildInfo = JSON.parse(
+      await fs.readFile(buildInfoPath, 'utf8'),
+    );
+
+    for (const [sourceFile, { ast }] of Object.entries(buildInfo.output.sources)) {
+      if (sourceFile.startsWith('@openzeppelin/contracts')) {
+        const sourceDependencies = (dependencies[sourceFile] ??= new Set());
+        for (const imp of findAll('ImportDirective', ast)) {
+          sourceDependencies.add(imp.absolutePath);
+        }
+      }
+    }
+
+    for (const [sourceFile, { content }] of Object.entries(buildInfo.input.sources)) {
+      if (sourceFile.startsWith('@openzeppelin/contracts')) {
+        sources[sourceFile] = content;
+      }
+    }
+  }
+
+  const contracts: OpenZeppelinContracts = {
+    version,
+    sources,
+    dependencies: mapValues(transitiveClosure(dependencies), d => Array.from(d)),
+  };
+
+  await fs.writeFile('openzeppelin-contracts.json', JSON.stringify(contracts, null, 2));
+}
+
+main().catch(e => {
+  console.error(e);
+  process.exit(1);
+});

package/src/set-access-control.ts

@@ -0,0 +1,39 @@
+import type { ContractBuilder, BaseFunction } from './contract';
+import { supportsInterface } from './common-functions';
+
+export const accessOptions = ['ownable', 'roles'] as const;
+
+export type Access = typeof accessOptions[number];
+
+export function setAccessControl(c: ContractBuilder, fn: BaseFunction, access: Access, role: string) {
+  switch (access) {
+    case 'ownable': {
+      c.addParent(parents.Ownable);
+      c.addModifier('onlyOwner', fn);
+      break;
+    }
+    case 'roles': {
+      const roleId = role + '_ROLE';
+      if (c.addParent(parents.AccessControl)) {
+        c.addConstructorCode('_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);');
+      }
+      c.addOverride(parents.AccessControl.name, supportsInterface);
+      if (c.addVariable(`bytes32 public constant ${roleId} = keccak256("${roleId}");`)) {
+        c.addConstructorCode(`_grantRole(${roleId}, msg.sender);`);
+      }
+      c.addModifier(`onlyRole(${roleId})`, fn);
+      break;
+    }
+  }
+}
+
+const parents = {
+  Ownable: {
+    name: 'Ownable',
+    path: '@openzeppelin/contracts/access/Ownable.sol',
+  },
+  AccessControl: {
+    name: 'AccessControl',
+    path: '@openzeppelin/contracts/access/AccessControl.sol',
+  },
+};

package/src/set-info.ts

@@ -0,0 +1,24 @@
+import type { ContractBuilder } from "./contract";
+
+export const TAG_SECURITY_CONTACT = `@custom:security-contact`;
+
+export const infoOptions = [{}, { securityContact: 'security@example.com', license: 'WTFPL' }] as const;
+
+export const defaults: Info = { license: 'MIT' };
+
+export type Info = {
+  securityContact?: string;
+  license?: string;
+}
+
+export function setInfo(c: ContractBuilder, info: Info) {
+  const { securityContact, license } = info;
+  
+  if (securityContact) {
+    c.addNatspecTag(TAG_SECURITY_CONTACT, securityContact);
+  }
+
+  if (license) {
+    c.license = license;
+  }
+}

package/src/set-upgradeable.ts

@@ -0,0 +1,49 @@
+import type { ContractBuilder } from './contract';
+import { Access, setAccessControl } from './set-access-control';
+import { defineFunctions } from './utils/define-functions';
+
+export const upgradeableOptions = [false, 'transparent', 'uups'] as const;
+
+export type Upgradeable = typeof upgradeableOptions[number];
+
+export function setUpgradeable(c: ContractBuilder, upgradeable: Upgradeable, access: Access) {
+  if (upgradeable === false) {
+    return;
+  }
+
+  c.upgradeable = true;
+
+  c.addParent({
+    name: 'Initializable',
+    path: '@openzeppelin/contracts/proxy/utils/Initializable.sol',
+  });
+
+  switch (upgradeable) {
+    case 'transparent': break;
+
+    case 'uups': {
+      setAccessControl(c, functions._authorizeUpgrade, access, 'UPGRADER');
+      c.addParent({
+        name: 'UUPSUpgradeable',
+        path: '@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol',
+      });
+      c.addOverride('UUPSUpgradeable', functions._authorizeUpgrade);
+      c.setFunctionBody([], functions._authorizeUpgrade);
+      break;
+    }
+
+    default: {
+      const _: never = upgradeable;
+      throw new Error('Unknown value for `upgradeable`');
+    }
+  }
+}
+
+const functions = defineFunctions({
+  _authorizeUpgrade: {
+    args: [
+      { name: 'newImplementation', type: 'address' },
+    ],
+    kind: 'internal',
+  },
+});

package/src/test.ts

@@ -0,0 +1,21 @@
+import test from 'ava';
+import hre from 'hardhat';
+import { promisify } from 'util';
+import path from 'path';
+
+import { writeGeneratedSources } from './generate/sources';
+
+test('result compiles', async t => {
+  const generatedSourcesPath = path.join(hre.config.paths.sources, 'generated');
+  await writeGeneratedSources(generatedSourcesPath, 'all');
+
+  // 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
+  // lot faster and not run out of memory.
+  for (const { settings } of hre.config.solidity.compilers) {
+    settings.outputSelection = {};
+  }
+
+  await hre.run('compile');
+  t.pass();
+});

package/src/utils/define-functions.ts

@@ -0,0 +1,18 @@
+import type { BaseFunction } from '../contract';
+
+type ImplicitNameFunction = Omit<BaseFunction, 'name'>;
+
+export function defineFunctions<F extends string>(
+  fns: Record<F, ImplicitNameFunction>,
+): Record<F, BaseFunction>;
+
+export function defineFunctions(
+  fns: Record<string, ImplicitNameFunction>,
+): Record<string, BaseFunction> {
+  return Object.fromEntries(
+    Object.entries(fns).map(([name, fn]) => [
+      name,
+      Object.assign({ name }, fn),
+    ]),
+  );
+}

package/src/utils/duration.ts

@@ -0,0 +1,34 @@
+const durationUnits = ['block', 'second', 'minute', 'hour', 'day', 'week', 'month', 'year'] as const;
+type DurationUnit = typeof durationUnits[number];
+export const durationPattern = new RegExp(`^(\\d+(?:\\.\\d+)?) +(${durationUnits.join('|')})s?$`);
+
+const second = 1;
+const minute = 60 * second;
+const hour = 60 * minute;
+const day = 24 * hour;
+const week = 7 * day;
+const month = 30 * day;
+const year = 365 * day;
+const secondsForUnit = { second, minute, hour, day, week, month, year };
+
+export function durationToBlocks(duration: string, blockTime: number): number {
+  const match = duration.trim().match(durationPattern);
+
+  if (!match) {
+    throw new Error('Bad duration format');
+  }
+
+  const value = parseFloat(match[1]!);
+  const unit = match[2]! as DurationUnit;
+
+  if (unit === 'block') {
+    if (!Number.isInteger(value)) {
+      throw new Error('Invalid number of blocks');
+    }
+
+    return value;
+  }
+
+  const durationSeconds = value * secondsForUnit[unit];
+  return Math.round(durationSeconds / blockTime);
+}

package/src/utils/find-cover.ts

@@ -0,0 +1,26 @@
+import { sortedBy } from './sorted-by';
+
+// Greedy approximation of minimum set cover.
+
+export function findCover<T extends object>(sets: T[], getElements: (set: T) => unknown[]): T[] {
+  const sortedSets = sortedBy(
+    sets.map(set => ({ set, elems: getElements(set) })),
+    s => -s.elems.length,
+  );
+
+  const seen = new Set<unknown>();
+  const res = [];
+
+  for (const { set, elems } of sortedSets) {
+    let included = false;
+    for (const e of elems) {
+      if (!included && !seen.has(e)) {
+        res.push(set);
+        included = true;
+      }
+      seen.add(e);
+    }
+  }
+
+  return res;
+}

package/src/utils/format-lines.ts

@@ -0,0 +1,31 @@
+import 'array.prototype.flatmap/auto';
+
+export type Lines = string | typeof whitespace | Lines[];
+
+const whitespace = Symbol('whitespace');
+
+export function formatLines(...lines: Lines[]): string {
+  return [...indentEach(0, lines)].join('\n') + '\n';
+}
+
+function* indentEach(
+  indent: number,
+  lines: Lines[],
+): Generator<string | typeof whitespace> {
+  for (const line of lines) {
+    if (line === whitespace) {
+      yield '';
+    } else if (Array.isArray(line)) {
+      yield* indentEach(indent + 1, line);
+    } else {
+      yield '    '.repeat(indent) + line;
+    }
+  }
+}
+
+export function spaceBetween(...lines: Lines[][]): Lines[] {
+  return lines
+    .filter(l => l.length > 0)
+    .flatMap<Lines>(l => [whitespace, ...l])
+    .slice(1);
+}

package/src/utils/map-values.ts

@@ -0,0 +1,10 @@
+export function mapValues<K extends keyof any, V, W>(
+  obj: Record<K, V>,
+  fn: (val: V) => W,
+): Record<K, W> {
+  const res = {} as Record<K, W>;
+  for (const key in obj) {
+    res[key] = fn(obj[key]);
+  }
+  return res;
+}

package/src/utils/sorted-by.ts

@@ -0,0 +1,3 @@
+export function sortedBy<T>(xs: Iterable<T>, fn: (x: T) => number): T[] {
+  return Array.from(xs).sort((a, b) => fn(a) - fn(b));
+}

package/src/utils/to-identifier.test.ts

@@ -0,0 +1,20 @@
+import test from 'ava';
+
+import { toIdentifier } from './to-identifier';
+
+test('unmodified', t => {
+  t.is(toIdentifier('abc'), 'abc');
+});
+
+test('remove leading specials', t => {
+  t.is(toIdentifier('--abc'), 'abc');
+});
+
+test('remove specials and upcase next char', t => {
+  t.is(toIdentifier('abc-def'), 'abcDef');
+  t.is(toIdentifier('abc--def'), 'abcDef');
+});
+
+test('capitalize', t => {
+  t.is(toIdentifier('abc', true), 'Abc');
+});

package/src/utils/to-identifier.ts

@@ -0,0 +1,7 @@
+export function toIdentifier(str: string, capitalize = false): string {
+  return str
+    .normalize('NFD').replace(/[\u0300-\u036f]/g, '') // remove accents
+    .replace(/^[^a-zA-Z$_]+/, '')
+    .replace(/^(.)/, c => capitalize ? c.toUpperCase() : c)
+    .replace(/[^\w$]+(.?)/g, (_, c) => c.toUpperCase());
+}

package/src/utils/transitive-closure.ts

@@ -0,0 +1,27 @@
+type T = string;
+
+export function transitiveClosure(obj: Record<T, Iterable<T>>): Record<T, Set<T>> {
+  const closure = {} as Record<T, Set<T>>;
+
+  for (const key in obj) {
+    closure[key] = reachable(obj, key);
+  }
+
+  return closure;
+}
+
+export function reachable(obj: Record<T, Iterable<T>>, key: T): Set<T> {
+  let prevSize = 0;
+  const res = new Set(obj[key]);
+
+  while (prevSize < res.size) {
+    prevSize = res.size;
+    for (const k of res) {
+      for (const v of obj[k] ?? []) {
+        res.add(v);
+      }
+    }
+  }
+
+  return res;
+}

package/src/zip.test.ts

@@ -0,0 +1,35 @@
+import test from 'ava';
+
+import { zipContract } from './zip';
+import { buildERC20 } from './erc20';
+import { generateSources } from './generate/sources';
+import { buildGeneric } from './build-generic';
+
+test('erc20 basic', t => {
+  const c = buildERC20({ name: 'MyToken', symbol: 'MTK' });
+  const zip = zipContract(c);
+  const files = Object.values(zip.files).map(f => f.name).sort();
+
+  t.deepEqual(files, [
+    '@openzeppelin/',
+    '@openzeppelin/contracts/',
+    '@openzeppelin/contracts/README.md',
+    '@openzeppelin/contracts/token/',
+    '@openzeppelin/contracts/token/ERC20/',
+    '@openzeppelin/contracts/token/ERC20/ERC20.sol',
+    '@openzeppelin/contracts/token/ERC20/IERC20.sol',
+    '@openzeppelin/contracts/token/ERC20/extensions/',
+    '@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol',
+    '@openzeppelin/contracts/utils/',
+    '@openzeppelin/contracts/utils/Context.sol',
+    'MyToken.sol',
+  ]);
+});
+
+test('can zip all combinations', t => {
+  for (const { options } of generateSources('all')) {
+    const c = buildGeneric(options);
+    zipContract(c);
+  }
+  t.pass();
+});