sol2uml 2.1.2 → 2.1.5

package/README.md

@@ -53,12 +53,13 @@ The three subcommands:
 The Solidity code can be pulled from verified source code on Blockchain explorers like Etherscan or from local Solidity files.
 
 Options:
+  -V, --version                                output the version number
   -sf, --subfolders <value>                    number of subfolders that will be recursively searched for Solidity files. (default: all)
   -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
 
@@ -118,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/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,23 @@ 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 == contractFilename ||
+                path_1.default.basename(relativePath) === 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,12 +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 networks = [
+const debug = require('debug')('sol2uml');
+exports.networks = [
     'mainnet',
     'ropsten',
     'kovan',
@@ -16,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';
@@ -33,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`;
@@ -130,6 +182,7 @@ class EtherscanParser {
     async getSourceCode(contractAddress) {
         const description = `get verified source code for address ${contractAddress} from Etherscan API.`;
         try {
+            debug(`About to get Solidity source code for ${contractAddress} from ${this.url}`);
             const response = await axios_1.default.get(this.url, {
                 params: {
                     module: 'contract',

package/lib/sol2uml.js

@@ -10,7 +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();
+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
@@ -29,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 })
@@ -89,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
@@ -99,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.')
@@ -114,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;
@@ -129,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;
             }
@@ -142,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
@@ -169,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.2",
-  "description": "Unified Modeling Language (UML) class diagram generator for Solidity contracts",
+  "version": "2.1.5",
+  "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"
   ]
 }