uups-checker 1.0.0

package/lib/openzeppelin-contracts/docs/templates/contract.hbs

@@ -0,0 +1,111 @@
+{{#each items}}
+:{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]]
+{{/each}}
+
+[.contract]
+[[{{anchor}}]]
+=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link]
+
+[.hljs-theme-light.nopadding]
+```solidity
+import "@openzeppelin/{{__item_context.file.absolutePath}}";
+```
+
+{{{natspec.dev}}}
+
+{{#if modifiers}}
+[.contract-index]
+.Modifiers
+--
+{{#each modifiers}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+--
+{{/if}}
+
+{{#if has-functions}}
+[.contract-index]
+.Functions
+--
+{{#each inherited-functions}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{contract.name}}
+{{/unless}}
+{{#each functions}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
+{{#if has-events}}
+[.contract-index]
+.Events
+--
+{{#each inheritance}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{name}}
+{{/unless}}
+{{#each events}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
+{{#if has-errors}}
+[.contract-index]
+.Errors
+--
+{{#each inheritance}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{name}}
+{{/unless}}
+{{#each errors}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
+{{#each modifiers}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#modifier#
+
+{{{natspec.dev}}}
+
+{{/each}}
+
+{{#each functions}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}}){{#if returns2}} → {{typed-params returns2}}{{/if}}++` [.item-kind]#{{visibility}}#
+
+{{{natspec.dev}}}
+
+{{/each}}
+
+{{#each events}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#event#
+
+{{{natspec.dev}}}
+
+{{/each}}
+
+{{#each errors}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#error#
+
+{{{natspec.dev}}}
+
+{{/each}}

package/lib/openzeppelin-contracts/docs/templates/helpers.js

@@ -0,0 +1,46 @@
+const { version } = require('../../package.json');
+
+module.exports['oz-version'] = () => version;
+
+module.exports['readme-path'] = opts => {
+  return 'contracts/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc';
+};
+
+module.exports.names = params => params?.map(p => p.name).join(', ');
+
+module.exports['typed-params'] = params => {
+  return params?.map(p => `${p.type}${p.indexed ? ' indexed' : ''}${p.name ? ' ' + p.name : ''}`).join(', ');
+};
+
+const slug = (module.exports.slug = str => {
+  if (str === undefined) {
+    throw new Error('Missing argument');
+  }
+  return str.replace(/\W/g, '-');
+});
+
+const linksCache = new WeakMap();
+
+function getAllLinks(items) {
+  if (linksCache.has(items)) {
+    return linksCache.get(items);
+  }
+  const res = {};
+  linksCache.set(items, res);
+  for (const item of items) {
+    res[`xref-${item.anchor}`] = `xref:${item.__item_context.page}#${item.anchor}`;
+    res[slug(item.fullName)] = `pass:normal[xref:${item.__item_context.page}#${item.anchor}[\`${item.fullName}\`]]`;
+  }
+  return res;
+}
+
+module.exports['with-prelude'] = opts => {
+  const links = getAllLinks(opts.data.site.items);
+  const contents = opts.fn();
+  const neededLinks = contents
+    .match(/\{[-._a-z0-9]+\}/gi)
+    .map(m => m.replace(/^\{(.+)\}$/, '$1'))
+    .filter(k => k in links);
+  const prelude = neededLinks.map(k => `:${k}: ${links[k]}`).join('\n');
+  return prelude + '\n' + contents;
+};

package/lib/openzeppelin-contracts/docs/templates/page.hbs

@@ -0,0 +1,4 @@
+:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]
+{{#with-prelude}}
+{{readme (readme-path)}}
+{{/with-prelude}}

package/lib/openzeppelin-contracts/docs/templates/properties.js

@@ -0,0 +1,64 @@
+const { isNodeType, findAll } = require('solidity-ast/utils');
+const { slug } = require('./helpers');
+
+module.exports.anchor = function anchor({ item, contract }) {
+  let res = '';
+  if (contract) {
+    res += contract.name + '-';
+  }
+  res += item.name;
+  if ('parameters' in item) {
+    const signature = item.parameters.parameters.map(v => v.typeName.typeDescriptions.typeString).join(',');
+    res += slug('(' + signature + ')');
+  }
+  if (isNodeType('VariableDeclaration', item)) {
+    res += '-' + slug(item.typeName.typeDescriptions.typeString);
+  }
+  return res;
+};
+
+module.exports.inheritance = function ({ item, build }) {
+  if (!isNodeType('ContractDefinition', item)) {
+    throw new Error('used inherited-items on non-contract');
+  }
+
+  return item.linearizedBaseContracts
+    .map(id => build.deref('ContractDefinition', id))
+    .filter((c, i) => c.name !== 'Context' || i === 0);
+};
+
+module.exports['has-functions'] = function ({ item }) {
+  return item.inheritance.some(c => c.functions.length > 0);
+};
+
+module.exports['has-events'] = function ({ item }) {
+  return item.inheritance.some(c => c.events.length > 0);
+};
+
+module.exports['has-errors'] = function ({ item }) {
+  return item.inheritance.some(c => c.errors.length > 0);
+};
+
+module.exports.functions = function ({ item }) {
+  return [
+    ...[...findAll('FunctionDefinition', item)].filter(f => f.visibility !== 'private'),
+    ...[...findAll('VariableDeclaration', item)].filter(f => f.visibility === 'public'),
+  ];
+};
+
+module.exports.returns2 = function ({ item }) {
+  if (isNodeType('VariableDeclaration', item)) {
+    return [{ type: item.typeDescriptions.typeString }];
+  } else {
+    return item.returns;
+  }
+};
+
+module.exports['inherited-functions'] = function ({ item }) {
+  const { inheritance } = item;
+  const baseFunctions = new Set(inheritance.flatMap(c => c.functions.flatMap(f => f.baseFunctions ?? [])));
+  return inheritance.map((contract, i) => ({
+    contract,
+    functions: contract.functions.filter(f => !baseFunctions.has(f.id) && (f.name !== 'constructor' || i === 0)),
+  }));
+};

package/lib/openzeppelin-contracts/hardhat/env-artifacts.js

@@ -0,0 +1,24 @@
+const { HardhatError } = require('hardhat/internal/core/errors');
+
+// Modifies `artifacts.require(X)` so that instead of X it loads the XUpgradeable contract.
+// This allows us to run the same test suite on both the original and the transpiled and renamed Upgradeable contracts.
+
+extendEnvironment(env => {
+  const artifactsRequire = env.artifacts.require;
+
+  env.artifacts.require = name => {
+    for (const suffix of ['UpgradeableWithInit', 'Upgradeable', '']) {
+      try {
+        return artifactsRequire(name + suffix);
+      } catch (e) {
+        // HH700: Artifact not found - from https://hardhat.org/hardhat-runner/docs/errors#HH700
+        if (HardhatError.isHardhatError(e) && e.number === 700 && suffix !== '') {
+          continue;
+        } else {
+          throw e;
+        }
+      }
+    }
+    throw new Error('Unreachable');
+  };
+});

package/lib/openzeppelin-contracts/hardhat/env-contract.js

@@ -0,0 +1,25 @@
+extendEnvironment(env => {
+  const { contract } = env;
+
+  env.contract = function (name, body) {
+    const { takeSnapshot } = require('@nomicfoundation/hardhat-network-helpers');
+
+    contract(name, accounts => {
+      // reset the state of the chain in between contract test suites
+      let snapshot;
+
+      before(async function () {
+        snapshot = await takeSnapshot();
+      });
+
+      after(async function () {
+        await snapshot.restore();
+      });
+
+      // remove the default account from the accounts list used in tests, in order
+      // to protect tests against accidentally passing due to the contract
+      // deployer being used subsequently as function caller
+      body(accounts.slice(1));
+    });
+  };
+});

package/lib/openzeppelin-contracts/hardhat/ignore-unreachable-warnings.js

@@ -0,0 +1,45 @@
+// Warnings about unreachable code are emitted with a source location that corresponds to the unreachable code.
+// We have some testing contracts that purposely cause unreachable code, but said code is in the library contracts, and
+// with hardhat-ignore-warnings we are not able to selectively ignore them without potentially ignoring relevant
+// warnings that we don't want to miss.
+// Thus, we need to handle these warnings separately. We force Hardhat to compile them in a separate compilation job and
+// then ignore the warnings about unreachable code that come from that compilation job.
+
+const { task } = require('hardhat/config');
+const {
+  TASK_COMPILE_SOLIDITY_GET_COMPILATION_JOB_FOR_FILE,
+  TASK_COMPILE_SOLIDITY_COMPILE,
+} = require('hardhat/builtin-tasks/task-names');
+
+const marker = Symbol('unreachable');
+const markedCache = new WeakMap();
+
+task(TASK_COMPILE_SOLIDITY_GET_COMPILATION_JOB_FOR_FILE, async (params, _, runSuper) => {
+  const job = await runSuper(params);
+  // If the file is in the unreachable directory, we make a copy of the config and mark it, which will cause it to get
+  // compiled separately (along with the other marked files).
+  if (params.file.sourceName.startsWith('contracts/mocks/') && /\bunreachable\b/.test(params.file.sourceName)) {
+    const originalConfig = job.solidityConfig;
+    let markedConfig = markedCache.get(originalConfig);
+    if (markedConfig === undefined) {
+      markedConfig = { ...originalConfig, [marker]: true };
+      markedCache.set(originalConfig, markedConfig);
+    }
+    job.solidityConfig = markedConfig;
+  }
+  return job;
+});
+
+const W_UNREACHABLE_CODE = '5740';
+
+task(TASK_COMPILE_SOLIDITY_COMPILE, async (params, _, runSuper) => {
+  const marked = params.compilationJob.solidityConfig[marker];
+  const result = await runSuper(params);
+  if (marked) {
+    result.output = {
+      ...result.output,
+      errors: result.output.errors?.filter(e => e.severity !== 'warning' || e.errorCode !== W_UNREACHABLE_CODE),
+    };
+  }
+  return result;
+});

package/lib/openzeppelin-contracts/hardhat/skip-foundry-tests.js

@@ -0,0 +1,6 @@
+const { subtask } = require('hardhat/config');
+const { TASK_COMPILE_SOLIDITY_GET_SOURCE_PATHS } = require('hardhat/builtin-tasks/task-names');
+
+subtask(TASK_COMPILE_SOLIDITY_GET_SOURCE_PATHS).setAction(async (_, __, runSuper) =>
+  (await runSuper()).filter(path => !path.endsWith('.t.sol')),
+);

package/lib/openzeppelin-contracts/hardhat/task-test-get-files.js

@@ -0,0 +1,25 @@
+const { internalTask } = require('hardhat/config');
+const { TASK_TEST_GET_TEST_FILES } = require('hardhat/builtin-tasks/task-names');
+
+// Modifies `hardhat test` to skip the proxy tests after proxies are removed by the transpiler for upgradeability.
+
+internalTask(TASK_TEST_GET_TEST_FILES).setAction(async (args, hre, runSuper) => {
+  const path = require('path');
+  const { promises: fs } = require('fs');
+
+  const hasProxies = await fs
+    .access(path.join(hre.config.paths.sources, 'proxy/Proxy.sol'))
+    .then(() => true)
+    .catch(() => false);
+
+  const ignoredIfProxy = [
+    'proxy/beacon/BeaconProxy.test.js',
+    'proxy/beacon/UpgradeableBeacon.test.js',
+    'proxy/ERC1967/ERC1967Proxy.test.js',
+    'proxy/transparent/ProxyAdmin.test.js',
+    'proxy/transparent/TransparentUpgradeableProxy.test.js',
+    'proxy/utils/UUPSUpgradeable.test.js',
+  ].map(p => path.join(hre.config.paths.tests, p));
+
+  return (await runSuper(args)).filter(file => hasProxies || !ignoredIfProxy.includes(file));
+});

package/lib/openzeppelin-contracts/hardhat.config.js

@@ -0,0 +1,131 @@
+/// ENVVAR
+// - CI:                output gas report to file instead of stdout
+// - COVERAGE:          enable coverage report
+// - ENABLE_GAS_REPORT: enable gas report
+// - COMPILE_MODE:      production modes enables optimizations (default: development)
+// - COMPILE_VERSION:   compiler version (default: 0.8.20)
+// - COINMARKETCAP:     coinmarkercat api key for USD value in gas report
+
+const fs = require('fs');
+const path = require('path');
+const proc = require('child_process');
+
+const argv = require('yargs/yargs')()
+  .env('')
+  .options({
+    coverage: {
+      type: 'boolean',
+      default: false,
+    },
+    gas: {
+      alias: 'enableGasReport',
+      type: 'boolean',
+      default: false,
+    },
+    gasReport: {
+      alias: 'enableGasReportPath',
+      type: 'string',
+      implies: 'gas',
+      default: undefined,
+    },
+    mode: {
+      alias: 'compileMode',
+      type: 'string',
+      choices: ['production', 'development'],
+      default: 'development',
+    },
+    ir: {
+      alias: 'enableIR',
+      type: 'boolean',
+      default: false,
+    },
+    foundry: {
+      alias: 'hasFoundry',
+      type: 'boolean',
+      default: hasFoundry(),
+    },
+    compiler: {
+      alias: 'compileVersion',
+      type: 'string',
+      default: '0.8.20',
+    },
+    coinmarketcap: {
+      alias: 'coinmarketcapApiKey',
+      type: 'string',
+    },
+  }).argv;
+
+require('@nomiclabs/hardhat-truffle5');
+require('hardhat-ignore-warnings');
+require('hardhat-exposed');
+require('solidity-docgen');
+argv.foundry && require('@nomicfoundation/hardhat-foundry');
+
+if (argv.foundry && argv.coverage) {
+  throw Error('Coverage analysis is incompatible with Foundry. Disable with `FOUNDRY=false` in the environment');
+}
+
+for (const f of fs.readdirSync(path.join(__dirname, 'hardhat'))) {
+  require(path.join(__dirname, 'hardhat', f));
+}
+
+const withOptimizations = argv.gas || argv.compileMode === 'production';
+
+/**
+ * @type import('hardhat/config').HardhatUserConfig
+ */
+module.exports = {
+  solidity: {
+    version: argv.compiler,
+    settings: {
+      optimizer: {
+        enabled: withOptimizations,
+        runs: 200,
+      },
+      viaIR: withOptimizations && argv.ir,
+      outputSelection: { '*': { '*': ['storageLayout'] } },
+    },
+  },
+  warnings: {
+    'contracts-exposed/**/*': {
+      'code-size': 'off',
+      'initcode-size': 'off',
+    },
+    '*': {
+      'code-size': withOptimizations,
+      'unused-param': !argv.coverage, // coverage causes unused-param warnings
+      default: 'error',
+    },
+  },
+  networks: {
+    hardhat: {
+      blockGasLimit: 10000000,
+      allowUnlimitedContractSize: !withOptimizations,
+    },
+  },
+  exposed: {
+    imports: true,
+    initializers: true,
+    exclude: ['vendor/**/*'],
+  },
+  docgen: require('./docs/config'),
+};
+
+if (argv.gas) {
+  require('hardhat-gas-reporter');
+  module.exports.gasReporter = {
+    showMethodSig: true,
+    currency: 'USD',
+    outputFile: argv.gasReport,
+    coinmarketcap: argv.coinmarketcap,
+  };
+}
+
+if (argv.coverage) {
+  require('solidity-coverage');
+  module.exports.networks.hardhat.initialBaseFeePerGas = 0;
+}
+
+function hasFoundry() {
+  return proc.spawnSync('forge', ['-V'], { stdio: 'ignore' }).error === undefined;
+}