sol2uml 2.4.3 → 2.5.0

package/README.md

@@ -14,7 +14,7 @@ See more contract diagrams [here](./examples/README.md).
 Storage layout diagram of USDC's [verified source code](https://etherscan.io/address/0xa2327a938febf5fec13bacfb16ae10ecbc4cbdcf#code) on Etherscan.
 ![USDC](./examples/storage/usdcData.svg)
 
-See more contract storage diagram examples [here](./examples/storage/README.md).
+See an explanation of how storage diagrams work with lots of examples [here](./examples/storage/README.md).
 
 # Install
 
@@ -54,14 +54,19 @@ 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", "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", "gnosisscan", 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)
+  -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", "gnosisscan", default: "mainnet", env: ETH_NETWORK)
+  -k, --apiKey <key>                           Blockchain explorer API key. eg Etherscan, Arbiscan, Optimism, BscScan, CronoScan, FTMScan, PolygonScan or SnowTrace API key (env: SCAN_API_KEY)
+  -bc, --backColor <color>                     Canvas background color. "none" will use a transparent canvas. (default: "white")
+  -sc, --shapeColor <color>                    Basic drawing color for graphics, not text (default: "black")
+  -fc, --fillColor <color>                     Color used to fill the background of a node (default: "gray95")
+  -tc, --textColor <color>                     Color used for text (default: "black")
   -v, --verbose                                run with debugging statements (default: false)
+  -V, --version                                output the version number
   -h, --help                                   display help for command
 
 Commands:
@@ -131,6 +136,7 @@ Options:
   -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")
+  -a, --array <number>            Number of slots to display at the start and end of arrays. (default: "2")
   -h, --help                      display help for command
 ```
 
@@ -272,6 +278,20 @@ Heads/Tails:
 
 See more storage slot diagrams [here](./examples/storage/README.md).
 
+# Styling Colors
+
+The colors use by the diagrams can be configured using the `backColor`, `shapeColor`, `fillColor` and `textColor` options.
+sol2uml uses the [X11 color scheme](https://graphviz.org/doc/info/colors.html#x11) for named colors.
+Other color formats like Red-Green-Blue (RGB) can also be used. For example, #ffffff for white and #000000 for black.
+See [Graphviz color](https://graphviz.org/docs/attr-types/color/) documentation for more details.
+
+Here's an example using the color options
+```
+sol2uml storage -sc deeppink -tc #ffffff -fc dimgrey -bc black 0xfCc00A1e250644d89AF0df661bC6f04891E21585
+```
+
+![Aave V3 Pool](./examples/storage/AaveV3PoolStorageColor.svg )
+
 # Version 2.x changes
 
 The biggest change with 2.x is the introduction of subcommands as sol2uml can now draw contract storage diagrams.

package/lib/SlotValueCache.d.ts

@@ -0,0 +1,31 @@
+import { BigNumberish } from '@ethersproject/bignumber';
+/**
+ * Singleton that caches a mapping of slot keys to values.
+ * Assumes all data is read from the same block and contract
+ */
+export declare class SlotValueCache {
+    private static slotCache;
+    /**
+     * @param slotKeys array of slot numbers or slot keys in hexadecimal format
+     * @return cachedValues array of the slot values that are in the cache.
+     * @return missingKeys array of the slot keys that are not cached in hexadecimal format.
+     */
+    static readSlotValues(slotKeys: readonly BigNumberish[]): {
+        cachedValues: string[];
+        missingKeys: string[];
+    };
+    /**
+     * Adds the missing slot values to the cache and then returns all slot values from
+     * the cache for each of the `slotKeys`.
+     * @param slotKeys array of slot numbers or keys in hexadecimal format.
+     * @param missingKeys array of the slot keys that are not cached in hexadecimal format.
+     * @param missingValues array of slot values in hexadecimal format.
+     * @return values array of slot values for each of the `slotKeys`.
+     */
+    static addSlotValues(slotKeys: readonly BigNumberish[], missingKeys: readonly string[], missingValues: readonly string[]): string[];
+    /**
+     * Used for testing purposes to clear the cache.
+     * This allows tests to run against different contracts and blockTags
+     */
+    static clear(): void;
+}

package/lib/SlotValueCache.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlotValueCache = void 0;
+const bignumber_1 = require("@ethersproject/bignumber");
+const debug = require('debug')('sol2uml');
+/**
+ * Singleton that caches a mapping of slot keys to values.
+ * Assumes all data is read from the same block and contract
+ */
+class SlotValueCache {
+    /**
+     * @param slotKeys array of slot numbers or slot keys in hexadecimal format
+     * @return cachedValues array of the slot values that are in the cache.
+     * @return missingKeys array of the slot keys that are not cached in hexadecimal format.
+     */
+    static readSlotValues(slotKeys) {
+        const cachedValues = [];
+        const missingKeys = [];
+        slotKeys.forEach((slotKey, i) => {
+            const key = bignumber_1.BigNumber.from(slotKey).toHexString();
+            if (this.slotCache[key]) {
+                cachedValues.push(this.slotCache[key]);
+            }
+            else {
+                missingKeys.push(key);
+            }
+        });
+        return { cachedValues, missingKeys };
+    }
+    /**
+     * Adds the missing slot values to the cache and then returns all slot values from
+     * the cache for each of the `slotKeys`.
+     * @param slotKeys array of slot numbers or keys in hexadecimal format.
+     * @param missingKeys array of the slot keys that are not cached in hexadecimal format.
+     * @param missingValues array of slot values in hexadecimal format.
+     * @return values array of slot values for each of the `slotKeys`.
+     */
+    static addSlotValues(slotKeys, missingKeys, missingValues) {
+        if (missingKeys?.length !== missingValues?.length) {
+            throw Error(`${missingKeys?.length} keys does not match ${missingValues?.length} values`);
+        }
+        missingKeys.forEach((key, i) => {
+            if (!this.slotCache[key]) {
+                debug(`cached slot ${key} with ${missingValues[i]}`);
+                this.slotCache[key] = missingValues[i];
+            }
+        });
+        return slotKeys.map((slotKey) => {
+            const key = bignumber_1.BigNumber.from(slotKey).toHexString();
+            // it should find the slot value in the cache. if not it'll return undefined
+            return this.slotCache[key];
+        });
+    }
+    /**
+     * Used for testing purposes to clear the cache.
+     * This allows tests to run against different contracts and blockTags
+     */
+    static clear() {
+        this.slotCache = {};
+    }
+}
+exports.SlotValueCache = SlotValueCache;
+// Singleton of cached slot keys mapped to values
+SlotValueCache.slotCache = {};
+//# sourceMappingURL=SlotValueCache.js.map

package/lib/associations.d.ts

@@ -1,2 +1,2 @@
 import { Association, UmlClass } from './umlClass';
-export declare const findAssociatedClass: (association: Association, sourceUmlClass: UmlClass, umlClasses: UmlClass[], searchedAbsolutePaths?: string[]) => UmlClass | undefined;
+export declare const findAssociatedClass: (association: Association, sourceUmlClass: UmlClass, umlClasses: readonly UmlClass[], searchedAbsolutePaths?: string[]) => UmlClass | undefined;

package/lib/associations.js

@@ -1,29 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findAssociatedClass = void 0;
-const umlClass_1 = require("./umlClass");
 // Find the UML class linked to the association
 const findAssociatedClass = (association, sourceUmlClass, umlClasses, searchedAbsolutePaths = []) => {
-    let umlClass = umlClasses.find((targetUmlClass) => {
-        // is the source class link via the association to the target class?
-        if (isAssociated(association, sourceUmlClass, targetUmlClass))
-            return true;
-        // Not linked so now try linking to target under the node_modules folder.
-        // eg remove node_modules from node_modules/@openzeppelin/contracts-upgradeable/proxy/Initializable.sol
-        // is the target class under node_modules?
-        if (targetUmlClass.relativePath.match(/^node_modules\//)) {
-            // clone the target and updated absolutePath and relativePath so it's no longer under node_modules
-            const clonedTargetClass = new umlClass_1.UmlClass(targetUmlClass);
-            clonedTargetClass.absolutePath =
-                targetUmlClass.absolutePath.replace(/^node_modules\//, '');
-            clonedTargetClass.relativePath =
-                targetUmlClass.relativePath.replace(/^node_modules\//, '');
-            // is the source class link via the association to the target class?
-            return isAssociated(association, sourceUmlClass, clonedTargetClass);
-        }
-        // could not find a link from the source to target via the association
-        return false;
-    });
+    const umlClass = umlClasses.find((targetUmlClass) => isAssociated(association, sourceUmlClass, targetUmlClass));
     // If a link was found
     if (umlClass)
         return umlClass;

package/lib/converterAST2Classes.d.ts

@@ -1,10 +1,21 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
+import { Remapping } from './parserEtherscan';
 /**
  * Convert solidity parser output of type `ASTNode` to UML classes of type `UMLClass`
  * @param node output of Solidity parser of type `ASTNode`
  * @param relativePath relative path from the working directory to the Solidity source file
+ * @param remappings used to rename relative paths
  * @param filesystem flag if Solidity source code was parsed from the filesystem or Etherscan
  * @return umlClasses array of UML class definitions of type `UmlClass`
  */
-export declare function convertAST2UmlClasses(node: ASTNode, relativePath: string, filesystem?: boolean): UmlClass[];
+export declare function convertAST2UmlClasses(node: ASTNode, relativePath: string, remappings: Remapping[], filesystem?: boolean): UmlClass[];
+/**
+ * Used to rename import file names. For example
+ * @openzeppelin/contracts/token/ERC721/IERC721Receiver.sol
+ * to
+ * lib/openzeppelin-contracts/@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol
+ * @param fileName file name in the Solidity code
+ * @param mappings an array of remappings from Etherscan's settings
+ */
+export declare const renameFile: (fileName: string, mappings: Remapping[]) => string;

package/lib/converterAST2Classes.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertAST2UmlClasses = void 0;
+exports.renameFile = exports.convertAST2UmlClasses = void 0;
 const path = __importStar(require("path"));
 const path_1 = require("path");
 const umlClass_1 = require("./umlClass");
@@ -34,10 +34,11 @@ let umlClasses;
  * Convert solidity parser output of type `ASTNode` to UML classes of type `UMLClass`
  * @param node output of Solidity parser of type `ASTNode`
  * @param relativePath relative path from the working directory to the Solidity source file
+ * @param remappings used to rename relative paths
  * @param filesystem flag if Solidity source code was parsed from the filesystem or Etherscan
  * @return umlClasses array of UML class definitions of type `UmlClass`
  */
-function convertAST2UmlClasses(node, relativePath, filesystem = false) {
+function convertAST2UmlClasses(node, relativePath, remappings, filesystem = false) {
     const imports = [];
     umlClasses = [];
     if (node.type === 'SourceUnit') {
@@ -110,11 +111,12 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                 }
                 else {
                     // this has come from Etherscan
-                    const importPath = childNode.path[0] === '.'
+                    const remappedFile = (0, exports.renameFile)(childNode.path, remappings);
+                    const importPath = remappedFile[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}`);
+                            path_1.posix.join(codeFolder.toString(), remappedFile)
+                        : remappedFile;
+                    debug(`codeFolder ${codeFolder} childNode.path ${childNode.path} remapped to ${remappedFile}`);
                     const newImport = {
                         absolutePath: importPath,
                         classNames: childNode.symbolAliases
@@ -126,7 +128,10 @@ function convertAST2UmlClasses(node, relativePath, filesystem = false) {
                             })
                             : [],
                     };
-                    debug(`Added Etherscan import ${newImport.absolutePath} with class names: ${newImport.classNames}`);
+                    debug(`Added Etherscan import ${newImport.absolutePath} with:`);
+                    newImport.classNames.forEach((className) => {
+                        debug(`\t alias ${className.className}, name ${className.className}`);
+                    });
                     imports.push(newImport);
                 }
             }
@@ -671,4 +676,25 @@ function parseContractKind(kind) {
             throw Error(`Invalid kind ${kind}`);
     }
 }
+/**
+ * Used to rename import file names. For example
+ * @openzeppelin/contracts/token/ERC721/IERC721Receiver.sol
+ * to
+ * lib/openzeppelin-contracts/@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol
+ * @param fileName file name in the Solidity code
+ * @param mappings an array of remappings from Etherscan's settings
+ */
+const renameFile = (fileName, mappings) => {
+    let renamedFile = fileName;
+    for (const mapping of mappings) {
+        if (renamedFile.match(mapping.from)) {
+            const beforeFileName = renamedFile;
+            renamedFile = renamedFile.replace(mapping.from, mapping.to);
+            debug(`remapping ${beforeFileName} to ${renamedFile}`);
+            break;
+        }
+    }
+    return renamedFile;
+};
+exports.renameFile = renameFile;
 //# sourceMappingURL=converterAST2Classes.js.map

package/lib/converterClass2Dot.d.ts

@@ -13,5 +13,9 @@ export interface ClassOptions {
     hideAbstracts?: boolean;
     hideFilename?: boolean;
     hideSourceContract?: boolean;
+    backColor?: string;
+    shapeColor?: string;
+    fillColor?: string;
+    textColor?: string;
 }
 export declare const convertClass2Dot: (umlClass: UmlClass, options?: ClassOptions) => string;

package/lib/converterClasses2Dot.js

@@ -18,9 +18,10 @@ function convertUmlClasses2Dot(umlClasses, clusterFolders = false, classOptions
     let dotString = `
 digraph UmlClassDiagram {
 rankdir=BT
-color=black
 arrowhead=open
-node [shape=record, style=filled, fillcolor=gray95]`;
+bgcolor="${classOptions.backColor}"
+edge [color="${classOptions.shapeColor}"]
+node [shape=record, style=filled, color="${classOptions.shapeColor}", fillcolor="${classOptions.fillColor}", fontcolor="${classOptions.textColor}"]`;
     // Sort UML Classes by folder of source file
     const umlClassesSortedByCodePath = sortUmlClassesByCodePath(umlClasses);
     let currentCodeFolder = '';

package/lib/converterClasses2Storage.d.ts

@@ -1,9 +1,11 @@
-import { Attribute, UmlClass } from './umlClass';
+import { Attribute, AttributeType, UmlClass } from './umlClass';
 import { BigNumberish } from '@ethersproject/bignumber';
-export declare enum StorageType {
+export declare enum StorageSectionType {
     Contract = "Contract",
     Struct = "Struct",
-    Array = "Array"
+    Array = "Array",
+    Bytes = "Bytes",
+    String = "String"
 }
 export interface Variable {
     id: number;
@@ -12,47 +14,67 @@ export interface Variable {
     byteSize: number;
     byteOffset: number;
     type: string;
+    attributeType: AttributeType;
     dynamic: boolean;
-    variable?: string;
+    name?: string;
     contractName?: string;
-    noValue: boolean;
-    value?: string;
-    referenceStorageId?: number;
-    enumId?: number;
+    displayValue: boolean;
+    getValue?: boolean;
+    slotValue?: string;
+    parsedValue?: string;
+    referenceSectionId?: number;
+    enumValues?: string[];
 }
-export interface Storage {
+export interface StorageSection {
     id: number;
     name: string;
     address?: string;
-    slotKey?: string;
-    type: StorageType;
+    offset?: string;
+    type: StorageSectionType;
     arrayLength?: number;
     arrayDynamic?: boolean;
+    mapping: boolean;
     variables: Variable[];
 }
-/**
- *
- * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
- * @param contractAddress Contract address to get the storage slot values from.
- * If proxied, use proxy and not the implementation contract.
- * @param storage is mutated with the storage values
- * @param blockTag block number or `latest`
- */
-export declare const addStorageValues: (url: string, contractAddress: string, storage: Storage, blockTag?: BigNumberish | 'latest') => Promise<void>;
 /**
  *
  * @param contractName name of the contract to get storage layout.
  * @param umlClasses array of UML classes of type `UMLClass`
+ * @param arrayItems the number of items to display at the start and end of an array
  * @param contractFilename relative path of the contract in the file system
- * @return array of storage objects with consecutive slots
+ * @return storageSections array of storageSection objects
+ */
+export declare const convertClasses2StorageSections: (contractName: string, umlClasses: UmlClass[], arrayItems: number, contractFilename?: string) => StorageSection[];
+/**
+ * Recursively adds new storage sections under a class attribute.
+ * also returns the allowed enum values
+ * @param attribute the attribute that is referencing a storage section
+ * @param umlClass contract or file level struct
+ * @param otherClasses array of all the UML Classes
+ * @param storageSections mutable array of storageSection objects
+ * @param mapping flags that the storage section is under a mapping
+ * @param arrayItems the number of items to display at the start and end of an array
+ * @return storageSection new storage section that was added or undefined if none was added.
+ * @return enumValues array of allowed enum values. undefined if attribute is not an enum
  */
-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[]) => {
+export declare const parseStorageSectionFromAttribute: (attribute: Attribute, umlClass: UmlClass, otherClasses: readonly UmlClass[], storageSections: StorageSection[], mapping: boolean, arrayItems: number) => {
+    storageSection: StorageSection;
+    enumValues?: string[];
+};
+export declare const calcStorageByteSize: (attribute: Attribute, umlClass: UmlClass, otherClasses: readonly UmlClass[]) => {
     size: number;
     dynamic: boolean;
 };
 export declare const isElementary: (type: string) => boolean;
-export declare const calcSlotKey: (variable: Variable) => string | undefined;
-export declare const offsetStorageSlots: (storage: Storage, slots: number, storages: Storage[]) => void;
-export declare const findDimensionLength: (umlClass: UmlClass, dimension: string) => number;
+export declare const calcSectionOffset: (variable: Variable, sectionOffset?: string) => string;
+export declare const findDimensionLength: (umlClass: UmlClass, dimension: string, otherClasses: readonly UmlClass[]) => number;
+/**
+ * Recursively adds variables for dynamic string, bytes or arrays
+ * @param storageSection
+ * @param storageSections
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * @param arrayItems the number of items to display at the start and end of an array
+ * @param blockTag block number or `latest`
+ */
+export declare const addDynamicVariables: (storageSection: StorageSection, storageSections: StorageSection[], url: string, contractAddress: string, arrayItems: number, blockTag: BigNumberish) => Promise<void>;