@1inch/solidity-utils 2.0.6 → 2.0.9

package/README.md

@@ -1,6 +1,7 @@
-<p align="center">
-  <img src="https://app.1inch.io/assets/images/logo.svg" width="200" alt="1inch network" />
-</p>
+<div align="center">
+    <img src="https://github.com/1inch/farming/blob/master/.github/1inch_github_w.svg#gh-light-mode-only">
+    <img src="https://github.com/1inch/farming/blob/master/.github/1inch_github_b.svg#gh-dark-mode-only">
+</div>
 
 # Utils library for contracts and tests
 
@@ -44,4 +45,22 @@ This repository contains frequently used smart contracts, libraries and interfac
 
 ### UTILS
 
+#### Docify
+
+Generates documentation in markdown format from natspec docs
+
+##### Usage
+Add to `package.json` file solidity compiler version and shortcut to run command
+
+`devDependencies` section
+
+```
+"solc": "0.8.12",
+```
+
+`scripts` section
+```
+"docify": "npx solidity-utils-docify"
+```
+
 ...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1inch/solidity-utils",
-  "version": "2.0.6",
+  "version": "2.0.9",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "repository": {
@@ -25,13 +25,14 @@
     "typechain": "hardhat typechain"
   },
   "dependencies": {
-    "@metamask/eth-sig-util": "^4.0.0",
+    "@metamask/eth-sig-util": "4.0.0",
     "@openzeppelin/contracts": "4.5.0",
     "@openzeppelin/test-helpers": "0.5.15",
+    "bn.js": "5.2.0",
     "chai": "4.3.6",
     "chai-as-promised": "7.1.1",
-    "ethereumjs-wallet": "1.0.2",
-    "hardhat": "2.8.4",
+    "chai-bn": "0.3.1",
+    "ethereumjs-util": "7.1.4",
     "web3-utils": "1.7.0"
   },
   "devDependencies": {
@@ -46,7 +47,6 @@
     "@types/node": "17.0.18",
     "@typescript-eslint/eslint-plugin": "5.12.0",
     "@typescript-eslint/parser": "5.12.0",
-    "chai-bn": "0.3.1",
     "create-ts-index": "^1.14.0",
     "cross-spawn": "7.0.3",
     "dotenv": "16.0.0",
@@ -57,6 +57,7 @@
     "eslint-plugin-promise": "6.0.0",
     "eslint-plugin-standard": "5.0.0",
     "eslint-plugin-typescript": "0.14.0",
+    "hardhat": "2.8.4",
     "hardhat-deploy": "0.10.5",
     "hardhat-gas-reporter": "1.0.8",
     "rimraf": "3.0.2",
@@ -80,6 +81,7 @@
   "files": [
     "./dist",
     "./*.MD",
+    "./utils",
     "contracts/*.sol",
     "contracts/interfaces",
     "contracts/libraries"

package/utils/contract.hbs

@@ -0,0 +1,69 @@
+# {{{name}}}
+
+
+{{{natspec.title}}}
+{{{natspec.userdoc}}}
+{{{natspec.devdoc}}}
+
+{{#if (withoutFirstElement inheritance)}}
+## Derives
+{{/if}}
+{{#each (withoutFirstElement inheritance)}}
+{{#if (getRelativeDocPath name source.contractsDir source.solcOutput.sources)}}
+- [{{name}}]({{getRelativeDocPath name source.contractsDir source.solcOutput.sources}})
+{{else}}
+- {{name}}
+{{/if}}
+{{/each}}
+
+{{#if ownFunctions}}
+## Functions
+{{/if}}
+{{#ownFunctions}}
+### {{name}}
+```solidity
+function {{name}}(
+  {{#args}}
+  {{type}} {{name}}{{#if @last}}{{else}},{{/if}}
+  {{/args}}
+) {{visibility}}{{#if outputs}} returns ({{outputs}}){{/if}}
+```
+{{#if natspec.userdoc}}{{natspec.userdoc}}{{/if}}
+{{#if natspec.devdoc}}{{natspec.devdoc}}{{/if}}
+{{#if args}}
+#### Parameters:
+| Name | Type | Description                                                          |
+| :--- | :--- | :------------------------------------------------------------------- |
+{{#args}}
+|`{{name}}` | {{type}} | {{#with (lookup ../natspec.params @index)~}} {{ removeNewlines description }} {{/with}}
+{{/args}}{{/if}}
+{{#if natspec.returns}}
+#### Return Values:
+| Name                           | Type          | Description                                                                  |
+| :----------------------------- | :------------ | :--------------------------------------------------------------------------- |
+{{#natspec.returns}}
+|`{{param}}`| {{#lookup ../outputs.types @index}}{{/lookup}} | {{{removeNewlines description}}}
+{{/natspec.returns}}{{/if}}
+{{/ownFunctions}}
+{{#if ownEvents}}
+## Events
+{{/if}}
+{{#ownEvents}}
+### {{name}}
+```solidity
+event {{name}}(
+  {{#args}}
+  {{type}} {{name}}{{#if @last}}{{else}},{{/if}}
+  {{/args}}
+)
+```
+{{#if natspec.userdoc}}{{natspec.userdoc}}{{/if}}
+{{#if natspec.devdoc}}{{natspec.devdoc}}{{/if}}
+{{#if args}}
+#### Parameters:
+| Name | Type | Description                                                          |
+| :--- | :--- | :------------------------------------------------------------------- |
+{{#args}}
+|`{{name}}` | {{type}} | {{#with (lookup ../natspec.params @index)~}} {{ removeNewlines description }} {{/with}}
+{{/args}}{{/if}}
+{{/ownEvents}}

package/utils/docify.utils.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+const SOLC_NPM_NAME = 'solc';
+const BASE_DIR = 'docgen';
+const SCRIPT_DIR = __dirname;
+const INPUT_DIR = 'contracts';
+const OUTPUT_DIR = `${BASE_DIR}/docs`;
+const HELPERS_PATH = `${SCRIPT_DIR}/solidity-docgen-helpers.js`;
+
+const fs = require('fs');
+const path = require('path');
+const spawn = require('cross-spawn');
+
+function getFileNameWithoutExtension (fileName) {
+    return fileName.substr(0, fileName.lastIndexOf('.'));
+}
+
+function runProcess (name, args) {
+    console.log(`running ${name} with args ${JSON.stringify(args)}`);
+    const result = spawn.sync(name, args, { stdio: ['inherit', 'inherit', 'pipe'] });
+    if (result.stderr.length > 0) {
+        throw new Error(result.stderr);
+    }
+}
+
+function getReadmes (targetPath) {
+    let result = [];
+    const readmePath = path.join(targetPath, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+        const content = `# ${path.basename(targetPath)}\n`;
+        result.push({ path: readmePath, content });
+    }
+    const childDirs = fs.readdirSync(targetPath, { withFileTypes: true }).filter(item => item.isDirectory());
+    for (const dir of childDirs) {
+        result = result.concat(getReadmes(path.join(targetPath, dir.name)));
+    }
+    return result;
+}
+
+function generateReadmes (readmes) {
+    for (const readme of readmes) {
+        fs.writeFileSync(readme.path, readme.content);
+    }
+}
+
+function getSummary (targetPath) {
+    function getSummaryRoot (summaryTargetPath, indentation) {
+        function specialCaseRoot (item) {
+            if (item.indentation >= 0) {
+                return item;
+            }
+            return ({
+                name: 'Main Readme',
+                path: item.path,
+                indentation: 0,
+            });
+        }
+
+        const items = fs.readdirSync(summaryTargetPath, { withFileTypes: true });
+        let result = [specialCaseRoot({
+            name: path.basename(summaryTargetPath),
+            path: path.relative(targetPath, path.join(summaryTargetPath, 'README.md')).replaceAll('\\', '/'),
+            indentation: indentation - 1,
+        })];
+        for (const dir of items.filter(item => item.isDirectory())) {
+            result = result.concat(getSummaryRoot(path.join(summaryTargetPath, dir.name), indentation + 1));
+        }
+        result = result
+            .concat(items
+                .filter(item => !item.isDirectory() &&
+                    !item.name.endsWith('README.md') &&
+                    !item.name.endsWith('SUMMARY.md'))
+                .map(file => ({
+                    name: getFileNameWithoutExtension(file.name),
+                    path: path.relative(targetPath, path.join(summaryTargetPath, file.name)).replaceAll('\\', '/'),
+                    indentation,
+                })));
+        return result;
+    }
+
+    function generateContent (summaryTree) {
+        const lines = summaryTree.map(x => `${'\t'.repeat(x.indentation)}* [${x.name}](${x.path})`).join('\n');
+        return `# Table of contents\n\n${lines}`;
+    }
+
+    return generateContent(getSummaryRoot(targetPath, 0));
+}
+
+function generateSummary (targetPath, summary) {
+    fs.writeFileSync(path.join(targetPath, 'SUMMARY.md'), summary);
+}
+
+function generateGitbookFiles () {
+    if (fs.existsSync(path.join(BASE_DIR, 'README.md'))){
+        fs.copyFileSync(path.join(BASE_DIR, 'README.md'), path.join(OUTPUT_DIR, 'README.md'));
+    }
+    
+    const readmesToGenerate = getReadmes(OUTPUT_DIR);
+    const summary = getSummary(OUTPUT_DIR);
+
+    generateReadmes(readmesToGenerate);
+    generateSummary(OUTPUT_DIR, summary);
+}
+
+function removeUnwantedDocs () {
+    const unwantedDirs = ['mocks', 'tests'];
+    for (const unwantedDir of unwantedDirs) {
+        fs.rmSync(path.join(OUTPUT_DIR, unwantedDir), { force: true, recursive: true });
+    }
+}
+
+const solidityDocgenArgs = [
+    'solidity-docgen',
+    '-i',
+    INPUT_DIR,
+    '-o',
+    OUTPUT_DIR,
+    '--solc-module',
+    SOLC_NPM_NAME,
+    '--solc-settings',
+    JSON.stringify({ optimizer: { enabled: false } }),
+    '--templates',
+    SCRIPT_DIR,
+    '--helpers',
+    HELPERS_PATH,
+];
+
+fs.rmSync(OUTPUT_DIR, { force: true, recursive: true });
+runProcess('npx', solidityDocgenArgs);
+generateGitbookFiles();
+removeUnwantedDocs();

package/utils/solidity-docgen-helpers.js

@@ -0,0 +1,31 @@
+module.exports = {
+    removeNewlines (str) {
+        return str.replace(/\r?\n/g, ' ');
+    },
+    withoutFirstElement (arr) {
+        return arr.splice(1);
+    },
+    getRelativeDocPath (contractName, contractsDir, sources) {
+        function getRelativePath (contractPath) {
+            if (contractPath){
+                if (contractPath.startsWith(contractsDir)) {
+                    return contractPath.substr(contractsDir.length + 1).replace('.sol', '.md');
+                }
+                if (contractPath.startsWith('@openzeppelin')) {
+                    const regexMatch = contractPath.match(/@openzeppelin\/contracts\/(.+)\/([^/]+)\.sol/);
+                    return `https://docs.openzeppelin.com/contracts/3.x/api/${regexMatch[1]}#${regexMatch[2]}`;
+                }
+            }
+            return null;
+        }
+
+        const sourcesKeys = Object.keys(sources);
+        const contractPath = sourcesKeys.find(x => x.includes(contractName));
+
+        if (!contractPath){
+            console.log('WARNING: file ' + contractName + '.sol not found in source files.');
+        }
+        
+        return getRelativePath(contractPath);
+    },
+};