sol2uml 2.1.3 → 2.1.6

package/README.md

@@ -58,8 +58,8 @@ Options:
   -f, --outputFormat <value>                   output file format. (choices: "svg", "png", "dot", "all", default: "svg")
   -o, --outputFileName <value>                 output file name
   -i, --ignoreFilesOrFolders <filesOrFolders>  comma separated list of files or folders to ignore
-  -n, --network <network>                      Ethereum network (choices: "mainnet", "polygon", "bsc", "arbitrum", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", default: "mainnet")
-  -k, --apiKey <key>                           Etherscan, Polygonscan or BscScan API key
+  -n, --network <network>                      Ethereum network (choices: "mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic", default: "mainnet", env: ETH_NETWORK)
+  -k, --apiKey <key>                           Blockchain explorer API key. eg Etherscan, Arbiscan, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key (env: SCAN_API_KEY)
   -v, --verbose                                run with debugging statements (default: false)
   -h, --help                                   display help for command
 
@@ -77,9 +77,9 @@ Usage: sol2uml class <fileFolderAddress> [options]
 
 Generates UML diagrams from Solidity source code.
 
-If no file, folder or address is passes as the first argument, the working folder is used.
+If no file, folder or address is passed as the first argument, the working folder is used.
 When a folder is used, all *.sol files are found in that folder and all sub folders.
-A comma separated list of files and folders can also used. For example
+A comma separated list of files and folders can also be used. For example
     sol2uml contracts,node_modules/openzeppelin-solidity
 
 If an Ethereum address with a 0x prefix is passed, the verified source code from Etherscan will be used. For example
@@ -119,12 +119,13 @@ Arguments:
   fileFolderAddress        file name, base folder or contract address
 
 Options:
-  -c, --contract <name>    Contract name in local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.
-  -d, --data               Gets the values in the storage slots from an Ethereum node. (default: false)
-  -s, --storage <address>  The address of the contract with the storage values. This will be different from the contract with the code if a proxy contract is used. This is not needed if `fileFolderAddress` is an address and the contract is not proxied.
-  -u, --url <url>          URL of the Ethereum node to get storage values if the `data` option is used. (default: "http://localhost:8545", env: NODE_URL)
-  -bn, --block <number>    Block number to get the contract storage values from. (default: "latest")
-  -h, --help               display help for command
+  -c, --contract <name>           Contract name in the local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.
+  -cf, --contractFile <filename>  Filename the contract is located in. This can include the relative path to the desired file.
+  -d, --data                      Gets the values in the storage slots from an Ethereum node. (default: false)
+  -s, --storage <address>         The address of the contract with the storage values. This will be different from the contract with the code if a proxy contract is used. This is not needed if `fileFolderAddress` is an address and the contract is not proxied.
+  -u, --url <url>                 URL of the Ethereum node to get storage values if the `data` option is used. (default: "http://localhost:8545", env: NODE_URL)
+  -bn, --block <number>           Block number to get the contract storage values from. (default: "latest")
+  -h, --help                      display help for command
 ```
 
 ### Flatten usage

package/lib/converterAST2Classes.js

@@ -25,6 +25,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertAST2UmlClasses = void 0;
 const path = __importStar(require("path"));
+const path_1 = require("path");
 const umlClass_1 = require("./umlClass");
 const typeGuards_1 = require("./typeGuards");
 const debug = require('debug')('sol2uml');
@@ -35,7 +36,6 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
     if (node.type === 'SourceUnit') {
         node.children.forEach((childNode) => {
             if (childNode.type === 'ContractDefinition') {
-                debug(`Adding contract ${childNode.name}`);
                 let umlClass = new umlClass_1.UmlClass({
                     name: childNode.name,
                     absolutePath: filesystem
@@ -44,6 +44,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     relativePath,
                 });
                 umlClass = parseContractDefinition(umlClass, childNode);
+                debug(`Added contract ${childNode.name}`);
                 umlClasses.push(umlClass);
             }
             else if (childNode.type === 'StructDefinition') {
@@ -57,6 +58,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                     relativePath,
                 });
                 umlClass = parseStructDefinition(umlClass, childNode);
+                debug(`Added struct ${umlClass.name}`);
                 umlClasses.push(umlClass);
             }
             else if (childNode.type === 'EnumDefinition') {
@@ -69,6 +71,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         : relativePath,
                     relativePath,
                 });
+                debug(`Added enum ${umlClass.name}`);
                 umlClass = parseEnumDefinition(umlClass, childNode);
                 umlClasses.push(umlClass);
             }
@@ -80,7 +83,7 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                         const importPath = require.resolve(childNode.path, {
                             paths: [codeFolder],
                         });
-                        imports.push({
+                        const newImport = {
                             absolutePath: importPath,
                             classNames: childNode.symbolAliases
                                 ? childNode.symbolAliases.map((alias) => {
@@ -90,7 +93,9 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                                     };
                                 })
                                 : [],
-                        });
+                        };
+                        debug(`Added filesystem import ${newImport.absolutePath} with class names ${newImport.classNames}`);
+                        imports.push(newImport);
                     }
                     catch (err) {
                         debug(`Failed to resolve import ${childNode.path} from file ${relativePath}`);
@@ -98,10 +103,12 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                 }
                 else {
                     // this has come from Etherscan
-                    const importPath = childNode.path[0] === '@'
-                        ? childNode.path
-                        : path.join(codeFolder, childNode.path);
-                    imports.push({
+                    const importPath = childNode.path[0] === '.'
+                        ? // Use Linux paths, not Windows paths, to resolve Etherscan files
+                            path_1.posix.join(codeFolder.toString(), childNode.path)
+                        : childNode.path;
+                    debug(`codeFolder ${codeFolder} childNode.path ${childNode.path}`);
+                    const newImport = {
                         absolutePath: importPath,
                         classNames: childNode.symbolAliases
                             ? childNode.symbolAliases.map((alias) => {
@@ -111,9 +118,12 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                                 };
                             })
                             : [],
-                    });
+                    };
+                    debug(`Added Etherscan import ${newImport.absolutePath} with class names: ${newImport.classNames}`);
+                    imports.push(newImport);
                 }
             }
+            // TODO add file level constants
         });
     }
     else {

package/lib/converterClasses2Storage.d.ts

@@ -36,7 +36,7 @@ export interface Storage {
  * @param storage is mutated with the storage values
  */
 export declare const addStorageValues: (url: string, contractAddress: string, storage: Storage, blockTag: string) => Promise<void>;
-export declare const convertClasses2Storages: (contractName: string, umlClasses: UmlClass[]) => Storage[];
+export declare const convertClasses2Storages: (contractName: string, umlClasses: UmlClass[], contractFilename?: string) => Storage[];
 export declare const parseReferenceStorage: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[], storages: Storage[]) => Storage | undefined;
 export declare const calcStorageByteSize: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[]) => {
     size: number;

package/lib/converterClasses2Storage.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findDimensionLength = exports.offsetStorageSlots = exports.calcSlotKey = exports.isElementary = exports.calcStorageByteSize = exports.parseReferenceStorage = exports.convertClasses2Storages = exports.addStorageValues = exports.StorageType = void 0;
 const umlClass_1 = require("./umlClass");
@@ -6,6 +9,8 @@ const associations_1 = require("./associations");
 const slotValues_1 = require("./slotValues");
 const utils_1 = require("ethers/lib/utils");
 const ethers_1 = require("ethers");
+const path_1 = __importDefault(require("path"));
+const debug = require('debug')('sol2uml');
 var StorageType;
 (function (StorageType) {
     StorageType["Contract"] = "Contract";
@@ -29,14 +34,24 @@ const addStorageValues = async (url, contractAddress, storage, blockTag) => {
     });
 };
 exports.addStorageValues = addStorageValues;
-const convertClasses2Storages = (contractName, umlClasses) => {
+const convertClasses2Storages = (contractName, umlClasses, contractFilename) => {
     // Find the base UML Class from the base contract name
-    const umlClass = umlClasses.find(({ name }) => {
-        return name === contractName;
+    const umlClass = umlClasses.find(({ name, relativePath }) => {
+        if (!contractFilename) {
+            return name === contractName;
+        }
+        return (name === contractName &&
+            (relativePath == path_1.default.normalize(contractFilename) ||
+                path_1.default.basename(relativePath) ===
+                    path_1.default.normalize(contractFilename)));
     });
     if (!umlClass) {
-        throw Error(`Failed to find contract with name "${contractName}"`);
+        const contractFilenameError = contractFilename
+            ? ` in filename "${contractFilename}"`
+            : '';
+        throw Error(`Failed to find contract with name "${contractName}"${contractFilenameError}`);
     }
+    debug(`Found contract "${contractName}" in ${umlClass.absolutePath}`);
     const storages = [];
     const variables = parseVariables(umlClass, umlClasses, [], storages, []);
     storages.unshift({

package/lib/parserEtherscan.d.ts

@@ -1,6 +1,6 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
-declare const networks: readonly ["mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "bsc", "arbitrum"];
+export declare const networks: readonly ["mainnet", "ropsten", "kovan", "rinkeby", "goerli", "sepolia", "polygon", "testnet.polygon", "arbitrum", "testnet.arbitrum", "avalanche", "testnet.avalanche", "bsc", "testnet.bsc", "crono", "fantom", "testnet.fantom", "moonbeam", "optimistic", "kovan-optimistic"];
 declare type Network = typeof networks[number];
 export declare class EtherscanParser {
     protected apikey: string;

package/lib/parserEtherscan.js

@@ -3,13 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EtherscanParser = void 0;
+exports.EtherscanParser = exports.networks = void 0;
 const axios_1 = __importDefault(require("axios"));
 const parser_1 = require("@solidity-parser/parser");
 const converterAST2Classes_1 = require("./converterAST2Classes");
 const filterClasses_1 = require("./filterClasses");
 const debug = require('debug')('sol2uml');
-const networks = [
+exports.networks = [
     'mainnet',
     'ropsten',
     'kovan',
@@ -17,15 +17,26 @@ const networks = [
     'goerli',
     'sepolia',
     'polygon',
-    'bsc',
+    'testnet.polygon',
     'arbitrum',
+    'testnet.arbitrum',
+    'avalanche',
+    'testnet.avalanche',
+    'bsc',
+    'testnet.bsc',
+    'crono',
+    'fantom',
+    'testnet.fantom',
+    'moonbeam',
+    'optimistic',
+    'kovan-optimistic',
 ];
 class EtherscanParser {
     constructor(apikey = 'ZAD4UI2RCXCQTP38EXS3UY2MPHFU5H9KB1', network = 'mainnet') {
         this.apikey = apikey;
         this.network = network;
-        if (!networks.includes(network)) {
-            throw new Error(`Invalid network "${network}". Must be one of ${networks}`);
+        if (!exports.networks.includes(network)) {
+            throw new Error(`Invalid network "${network}". Must be one of ${exports.networks}`);
         }
         else if (network === 'mainnet') {
             this.url = 'https://api.etherscan.io/api';
@@ -34,12 +45,52 @@ class EtherscanParser {
             this.url = 'https://api.polygonscan.com/api';
             this.apikey = 'AMHGNTV5A7XYGX2M781JB3RC1DZFVRWQEB';
         }
+        else if (network === 'testnet.polygon') {
+            this.url = 'https://api-testnet.polygonscan.com/api';
+            this.apikey = 'AMHGNTV5A7XYGX2M781JB3RC1DZFVRWQEB';
+        }
+        else if (network === 'arbitrum') {
+            this.url = 'https://api.arbiscan.io/api';
+            this.apikey = 'ZGTK2TAGWMAB6IAC12BMK8YYPNCPIM8VDQ';
+        }
+        else if (network === 'testnet.arbitrum') {
+            this.url = 'https://api-testnet.arbiscan.io/api';
+            this.apikey = 'ZGTK2TAGWMAB6IAC12BMK8YYPNCPIM8VDQ';
+        }
+        else if (network === 'avalanche') {
+            this.url = 'https://api.snowtrace.io/api';
+            this.apikey = 'U5FAN98S5XNH5VI83TI4H35R9I4TDCKEJY';
+        }
+        else if (network === 'testnet.avalanche') {
+            this.url = 'https://api-testnet.snowtrace.io/api';
+            this.apikey = 'U5FAN98S5XNH5VI83TI4H35R9I4TDCKEJY';
+        }
         else if (network === 'bsc') {
             this.url = 'https://api.bscscan.com/api';
+        }
+        else if (network === 'testnet.bsc') {
+            this.url = 'https://api-testnet.bscscan.com/api';
+        }
+        else if (network === 'crono') {
+            this.url = 'https://api.cronoscan.com/api';
+            this.apikey = '76A3RG5WHTPMMR66E9SFI2EIDT6MP976W2';
             this.apikey = 'APYH49FXVY9UA3KTDI6F4WP3KPIC86NITN';
         }
-        else if (network === 'arbitrum') {
-            this.url = 'https://api.arbiscan.io/api';
+        else if (network === 'fantom') {
+            this.url = 'https://api.ftmscan.com/api';
+            this.apikey = '71KRX13XPZMGR3D1Q85W78G2DSZ4JPMAEX';
+        }
+        else if (network === 'testnet.fantom') {
+            this.url = 'https://api-testnet.ftmscan.com/api';
+            this.apikey = '71KRX13XPZMGR3D1Q85W78G2DSZ4JPMAEX';
+        }
+        else if (network === 'optimistic' || network === 'kovan-optimistic') {
+            this.url = `https://api-${network}.etherscan.io/api`;
+            this.apikey = 'FEXS1HXVA4Y2RNTMEA8V1UTK21S4JWHH9U';
+        }
+        else if (network === 'moonbeam') {
+            this.url = 'https://api-moonbeam.moonscan.io/api';
+            this.apikey = '5EUFXW6TDC16VERF3D9SCWRRU6AEMTBHNJ';
         }
         else {
             this.url = `https://api-${network}.etherscan.io/api`;
@@ -54,6 +105,7 @@ class EtherscanParser {
         const { files, contractName } = await this.getSourceCode(contractAddress);
         let umlClasses = [];
         for (const file of files) {
+            debug(`Parsing source file ${file.filename}`);
             const node = await this.parseSourceCode(file.code);
             const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename);
             umlClasses = umlClasses.concat(umlClass);

package/lib/sol2uml.js

@@ -10,8 +10,12 @@ const converterClasses2Storage_1 = require("./converterClasses2Storage");
 const converterStorage2Dot_1 = require("./converterStorage2Dot");
 const regEx_1 = require("./utils/regEx");
 const writerFiles_1 = require("./writerFiles");
+const path_1 = require("path");
 const program = new commander_1.Command();
-program.version(require('../package.json').version);
+const version = (0, path_1.basename)(__dirname) === 'lib'
+    ? require('../package.json').version // used when run from compile js in /lib
+    : require('../../package.json').version; // used when run from TypeScript source files under src/ts via ts-node
+program.version(version);
 const debugControl = require('debug');
 const debug = require('debug')('sol2uml');
 program
@@ -30,20 +34,10 @@ The Solidity code can be pulled from verified source code on Blockchain explorer
     .option('-o, --outputFileName <value>', 'output file name')
     .option('-i, --ignoreFilesOrFolders <filesOrFolders>', 'comma separated list of files or folders to ignore')
     .addOption(new commander_1.Option('-n, --network <network>', 'Ethereum network')
-    .choices([
-    'mainnet',
-    'polygon',
-    'bsc',
-    'arbitrum',
-    'ropsten',
-    'kovan',
-    'rinkeby',
-    'goerli',
-    'sepolia',
-])
+    .choices(parserEtherscan_1.networks)
     .default('mainnet')
     .env('ETH_NETWORK'))
-    .addOption(new commander_1.Option('-k, --apiKey <key>', 'Etherscan, Polygonscan, BscScan or Arbiscan API key').env('SCAN_API_KEY'))
+    .addOption(new commander_1.Option('-k, --apiKey <key>', 'Blockchain explorer API key. eg Etherscan, Arbiscan, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key').env('SCAN_API_KEY'))
     .option('-v, --verbose', 'run with debugging statements', false);
 program
     .command('class', { isDefault: true })
@@ -52,9 +46,9 @@ program
 
 Generates UML diagrams from Solidity source code.
 
-If no file, folder or address is passes as the first argument, the working folder is used.
+If no file, folder or address is passed as the first argument, the working folder is used.
 When a folder is used, all *.sol files are found in that folder and all sub folders.
-A comma separated list of files and folders can also used. For example
+A comma separated list of files and folders can also be used. For example
     sol2uml contracts,node_modules/openzeppelin-solidity
 
 If an Ethereum address with a 0x prefix is passed, the verified source code from Etherscan will be used. For example
@@ -90,7 +84,8 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
         debug(`Finished generating UML`);
     }
     catch (err) {
-        console.error(`Failed to generate UML diagram\n${err.stack}`);
+        console.error(err);
+        process.exit(2);
     }
 });
 program
@@ -100,7 +95,8 @@ program
 
 WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A known example is fixed-sized arrays declared with an expression will fail to be sized.`)
     .argument('<fileFolderAddress>', 'file name, base folder or contract address')
-    .option('-c, --contract <name>', 'Contract name in local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.')
+    .option('-c, --contract <name>', 'Contract name in the local Solidity files. Not needed when using an address as the first argument as the contract name can be derived from Etherscan.')
+    .option('-cf, --contractFile <filename>', 'Filename the contract is located in. This can include the relative path to the desired file.')
     .option('-d, --data', 'Gets the values in the storage slots from an Ethereum node.', false)
     .option('-s, --storage <address>', 'The address of the contract with the storage values. This will be different from the contract with the code if a proxy contract is used. This is not needed if `fileFolderAddress` is an address and the contract is not proxied.')
     .addOption(new commander_1.Option('-u, --url <url>', 'URL of the Ethereum node to get storage values if the `data` option is used.')
@@ -115,7 +111,7 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
         };
         let { umlClasses, contractName } = await (0, parserGeneral_1.parserUmlClasses)(fileFolderAddress, combinedOptions);
         contractName = combinedOptions.contract || contractName;
-        const storages = (0, converterClasses2Storage_1.convertClasses2Storages)(contractName, umlClasses);
+        const storages = (0, converterClasses2Storage_1.convertClasses2Storages)(contractName, umlClasses, combinedOptions.contractFile);
         if ((0, regEx_1.isAddress)(fileFolderAddress)) {
             // The first storage is the contract
             storages[0].address = fileFolderAddress;
@@ -130,7 +126,7 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
             }
             else {
                 if (!(0, regEx_1.isAddress)(fileFolderAddress)) {
-                    throw Error(`Can not get storage slot values if first param is not an address and the \`address\` option is not used.`);
+                    throw Error(`Can not get storage slot values if first param is not an address and the \`--storage\` option is not used.`);
                 }
                 storageAddress = fileFolderAddress;
             }
@@ -143,7 +139,8 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
         await (0, writerFiles_1.writeOutputFiles)(dotString, fileFolderAddress, contractName || 'storageDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
     }
     catch (err) {
-        console.error(`Failed to generate storage diagram.\n${err.stack}`);
+        console.error(err.stack);
+        process.exit(2);
     }
 });
 program
@@ -170,7 +167,8 @@ In order for the merged code to compile, the following is done:
         await (0, writerFiles_1.writeSolidity)(solidityCode, outputFilename);
     }
     catch (err) {
-        console.error(`Failed to flatten files.\n${err.stack}`);
+        console.error(err);
+        process.exit(2);
     }
 });
 program.on('option:verbose', () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sol2uml",
-  "version": "2.1.3",
-  "description": "Unified Modeling Language (UML) class diagram generator for Solidity contracts",
+  "version": "2.1.6",
+  "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "scripts": {
@@ -54,14 +54,15 @@
     "UML",
     "Solidity",
     "Ethereum",
-    "Class diagram",
-    "Class",
     "diagram",
-    "Contract",
-    "Interface",
-    "Relationship",
-    "SVG",
+    "class",
+    "diagram",
+    "contract",
     "Blockchain",
-    "Model"
+    "storage",
+    "flatten",
+    "visual",
+    "tool",
+    "cli"
   ]
 }