sol2uml 2.4.2 → 2.5.0

package/lib/converterStorage2Dot.d.ts

@@ -1,7 +1,11 @@
-import { Storage } from './converterClasses2Storage';
-export declare const convertStorages2Dot: (storages: Storage[], options: {
+import { StorageSection } from './converterClasses2Storage';
+export declare const convertStorages2Dot: (storageSections: readonly StorageSection[], options: {
     data: boolean;
+    backColor: string;
+    shapeColor: string;
+    fillColor: string;
+    textColor: string;
 }) => string;
-export declare function convertStorage2Dot(storage: Storage, dotString: string, options: {
+export declare function convertStorage2Dot(storageSection: StorageSection, dotString: string, options: {
     data: boolean;
 }): string;

package/lib/converterStorage2Dot.js

@@ -2,23 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertStorage2Dot = exports.convertStorages2Dot = void 0;
 const converterClasses2Storage_1 = require("./converterClasses2Storage");
+const umlClass_1 = require("./umlClass");
 const debug = require('debug')('sol2uml');
-const convertStorages2Dot = (storages, options) => {
+const convertStorages2Dot = (storageSections, options) => {
     let dotString = `
 digraph StorageDiagram {
 rankdir=LR
-color=black
 arrowhead=open
-node [shape=record, style=filled, fillcolor=gray95 fontname="Courier New"]`;
+bgcolor="${options.backColor}"
+edge [color="${options.shapeColor}"]
+node [shape=record, style=filled, color="${options.shapeColor}", fillcolor="${options.fillColor}", fontcolor="${options.textColor}", fontname="Courier New"]`;
     // process contract and the struct storages
-    storages.forEach((storage) => {
+    storageSections.forEach((storage) => {
         dotString = convertStorage2Dot(storage, dotString, options);
     });
     // link contract and structs to structs
-    storages.forEach((slot) => {
+    storageSections.forEach((slot) => {
         slot.variables.forEach((storage) => {
-            if (storage.referenceStorageId) {
-                dotString += `\n ${slot.id}:${storage.id} -> ${storage.referenceStorageId}`;
+            if (storage.referenceSectionId) {
+                dotString += `\n ${slot.id}:${storage.id} -> ${storage.referenceSectionId}`;
             }
         });
     });
@@ -28,34 +30,50 @@ node [shape=record, style=filled, fillcolor=gray95 fontname="Courier New"]`;
     return dotString;
 };
 exports.convertStorages2Dot = convertStorages2Dot;
-function convertStorage2Dot(storage, dotString, options) {
+function convertStorage2Dot(storageSection, dotString, options) {
     // write storage header with name and optional address
-    dotString += `\n${storage.id} [label="${storage.name} \\<\\<${storage.type}\\>\\>\\n${storage.address || storage.slotKey || ''}`;
+    dotString += `\n${storageSection.id} [label="${storageSection.name} \\<\\<${storageSection.type}\\>\\>\\n${storageSection.address || storageSection.offset || ''}`;
     dotString += ' | {';
-    const startingVariables = storage.variables.filter((s) => s.byteOffset === 0);
+    const startingVariables = storageSection.variables.filter((s) => s.byteOffset === 0);
+    // for each slot displayed, does is have any variables with parsed data?
+    const displayData = startingVariables.map((startVar) => storageSection.variables.some((variable) => variable.fromSlot === startVar.fromSlot && variable.parsedValue));
+    const linePad = '\\n\\ ';
     // write slot numbers
-    dotString += '{ slot';
+    const dataLine = options.data ? linePad : '';
+    dotString +=
+        storageSection.offset || storageSection.mapping
+            ? `{ offset${dataLine}`
+            : `{ slot${dataLine}`;
     startingVariables.forEach((variable, i) => {
+        const dataLine = options.data && displayData[i] ? linePad : '';
         if (variable.fromSlot === variable.toSlot) {
-            dotString += `| ${variable.fromSlot} `;
+            dotString += ` | ${variable.fromSlot}${dataLine}`;
         }
         else {
-            dotString += `| ${variable.fromSlot}-${variable.toSlot} `;
+            dotString += ` | ${variable.fromSlot}-${variable.toSlot}${dataLine}`;
         }
     });
     // write slot values if available
     if (options.data) {
-        dotString += '} | {value';
+        dotString += `} | {value${dataLine}`;
         startingVariables.forEach((variable, i) => {
-            dotString += ` | ${variable.value || ''}`;
+            if (displayData[i]) {
+                dotString += ` | ${variable.slotValue || ''}${linePad}`;
+            }
+            else {
+                dotString += ` | `;
+            }
         });
     }
-    const contractVariablePrefix = storage.type === converterClasses2Storage_1.StorageType.Contract ? '\\<inherited contract\\>.' : '';
-    dotString += `} | { type: ${contractVariablePrefix}variable (bytes)`;
+    const contractVariablePrefix = storageSection.type === converterClasses2Storage_1.StorageSectionType.Contract
+        ? '\\<inherited contract\\>.'
+        : '';
+    const dataLine2 = options.data ? `\\ndecoded data` : '';
+    dotString += `} | { type: ${contractVariablePrefix}variable (bytes)${dataLine2}`;
     // For each slot
     startingVariables.forEach((variable) => {
         // Get all the storage variables in this slot
-        const slotVariables = storage.variables.filter((s) => s.fromSlot === variable.fromSlot);
+        const slotVariables = storageSection.variables.filter((s) => s.fromSlot === variable.fromSlot);
         const usedBytes = slotVariables.reduce((acc, s) => acc + s.byteSize, 0);
         if (usedBytes < 32) {
             // Create an unallocated variable for display purposes
@@ -66,20 +84,22 @@ function convertStorage2Dot(storage, dotString, options) {
                 byteSize: 32 - usedBytes,
                 byteOffset: usedBytes,
                 type: 'unallocated',
+                attributeType: umlClass_1.AttributeType.UserDefined,
                 dynamic: false,
-                noValue: true,
+                displayValue: false,
+                getValue: false,
                 contractName: variable.contractName,
-                variable: '',
+                name: '',
             });
         }
         const slotVariablesReversed = slotVariables.reverse();
         // For each variable in the slot
         slotVariablesReversed.forEach((variable, i) => {
             if (i === 0) {
-                dotString += ` | { ${dotVariable(variable, storage.name)} `;
+                dotString += ` | { ${dotVariable(variable, storageSection.name)} `;
             }
             else {
-                dotString += ` | ${dotVariable(variable, storage.name)} `;
+                dotString += ` | ${dotVariable(variable, storageSection.name)} `;
             }
         });
         dotString += '}';
@@ -89,12 +109,17 @@ function convertStorage2Dot(storage, dotString, options) {
     return dotString;
 }
 exports.convertStorage2Dot = convertStorage2Dot;
-const dotVariable = (storage, contractName) => {
-    const port = storage.referenceStorageId !== undefined ? `<${storage.id}>` : '';
-    const contractNamePrefix = storage.contractName !== contractName ? `${storage.contractName}.` : '';
-    const variable = storage.variable
-        ? `: ${contractNamePrefix}${storage.variable}`
+const dotVariable = (variable, contractName) => {
+    const port = variable.referenceSectionId !== undefined ? `<${variable.id}>` : '';
+    const contractNamePrefix = variable.contractName !== contractName
+        ? `${variable.contractName}.`
+        : '';
+    const variableValue = variable.parsedValue
+        ? `\\n\\ ${variable.parsedValue}`
+        : '';
+    const variableName = variable.name
+        ? `: ${contractNamePrefix}${variable.name}`
         : '';
-    return `${port} ${storage.type}${variable} (${storage.byteSize})`;
+    return `${port} ${variable.type}${variableName} (${variable.byteSize})${variableValue}`;
 };
 //# sourceMappingURL=converterStorage2Dot.js.map

package/lib/filterClasses.d.ts

@@ -7,7 +7,7 @@ import { ClassOptions } from './converterClass2Dot';
  * @param options sol2uml class options
  * @return umlClasses filtered list of UML classes of type `UMLClass`
  */
-export declare const filterHiddenClasses: (umlClasses: UmlClass[], options: ClassOptions) => UmlClass[];
+export declare const filterHiddenClasses: (umlClasses: readonly UmlClass[], options: ClassOptions) => UmlClass[];
 /**
  * Finds all the UML classes that have an association with a list of base contract names.
  * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
@@ -16,7 +16,7 @@ export declare const filterHiddenClasses: (umlClasses: UmlClass[], options: Clas
  * @param depth limit the number of associations from the base contract.
  * @return filteredUmlClasses list of UML classes of type `UMLClass`
  */
-export declare const classesConnectedToBaseContracts: (umlClasses: UmlClass[], baseContractNames: string[], depth?: number) => UmlClass[];
+export declare const classesConnectedToBaseContracts: (umlClasses: readonly UmlClass[], baseContractNames: readonly string[], depth?: number) => UmlClass[];
 /**
  * Finds all the UML classes that have an association with a base contract name.
  * The associated classes can be contracts, abstract contracts, interfaces, libraries, enums, structs or constants.
@@ -26,7 +26,7 @@ export declare const classesConnectedToBaseContracts: (umlClasses: UmlClass[], b
  * @param depth limit the number of associations from the base contract.
  * @return filteredUmlClasses list of UML classes of type `UMLClass`
  */
-export declare const classesConnectedToBaseContract: (umlClasses: UmlClass[], baseContractName: string, weightedDirectedGraph: WeightedDiGraph, depth?: number) => {
+export declare const classesConnectedToBaseContract: (umlClasses: readonly UmlClass[], baseContractName: string, weightedDirectedGraph: WeightedDiGraph, depth?: number) => {
     [contractName: string]: UmlClass;
 };
-export declare const topologicalSortClasses: (umlClasses: UmlClass[]) => UmlClass[];
+export declare const topologicalSortClasses: (umlClasses: readonly UmlClass[]) => UmlClass[];

package/lib/filterClasses.js

@@ -4,6 +4,7 @@ exports.topologicalSortClasses = exports.classesConnectedToBaseContract = export
 const js_graph_algorithms_1 = require("js-graph-algorithms");
 const umlClass_1 = require("./umlClass");
 const associations_1 = require("./associations");
+const debug = require('debug')('sol2uml');
 /**
  * Filter out any UML Class types that are to be hidden.
  * @param umlClasses array of UML classes of type `UMLClass`
@@ -85,7 +86,7 @@ function loadWeightedDirectedGraph(umlClasses) {
                 continue;
             }
             const isTarget = umlClasses.find((u) => u.id === targetUmlClass.id);
-            console.log(`isTarget ${isTarget} Adding edge from ${sourceUmlClass.name} with id ${sourceUmlClass.id} to ${targetUmlClass.name} with id ${targetUmlClass.id} and type ${targetUmlClass.stereotype}`);
+            debug(`isTarget ${isTarget} Adding edge from ${sourceUmlClass.name} with id ${sourceUmlClass.id} to ${targetUmlClass.name} with id ${targetUmlClass.id} and type ${targetUmlClass.stereotype}`);
             weightedDirectedGraph.addEdge(new js_graph_algorithms_1.Edge(sourceUmlClass.id, targetUmlClass.id, 1));
         }
     }

package/lib/parserEtherscan.d.ts

@@ -1,7 +1,11 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
+export interface Remapping {
+    from: RegExp;
+    to: string;
+}
 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", "gnosisscan"];
-export type Network = typeof networks[number];
+export type Network = (typeof networks)[number];
 export declare class EtherscanParser {
     protected apikey: string;
     network: Network;
@@ -37,11 +41,25 @@ export declare class EtherscanParser {
      * @param contractAddress Ethereum contract address with a 0x prefix
      */
     getSourceCode(contractAddress: string): Promise<{
-        files: {
+        files: readonly {
             code: string;
             filename: string;
         }[];
         contractName: string;
         compilerVersion: string;
+        remappings: Remapping[];
     }>;
 }
+/**
+ * Parses Ethersan's remappings config in its API response
+ * @param rawMappings
+ */
+export declare const parseRemappings: (rawMappings: string[]) => Remapping[];
+/**
+ * Parses a single mapping. For example
+ * "@openzeppelin/=lib/openzeppelin-contracts/"
+ * This is from Uniswap's UniversalRouter in the Settings section after the source files
+ * https://etherscan.io/address/0xEf1c6E67703c7BD7107eed8303Fbe6EC2554BF6B#code
+ * @param mapping
+ */
+export declare const parseRemapping: (mapping: string) => Remapping;

package/lib/parserEtherscan.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EtherscanParser = exports.networks = void 0;
+exports.parseRemapping = exports.parseRemappings = exports.EtherscanParser = exports.networks = void 0;
 const axios_1 = __importDefault(require("axios"));
 const parser_1 = require("@solidity-parser/parser");
 const converterAST2Classes_1 = require("./converterAST2Classes");
@@ -110,12 +110,12 @@ class EtherscanParser {
      * @return Promise with an array of UmlClass objects
      */
     async getUmlClasses(contractAddress) {
-        const { files, contractName } = await this.getSourceCode(contractAddress);
+        const { files, contractName, remappings } = 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);
+            const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename, remappings);
             umlClasses = umlClasses.concat(umlClass);
         }
         return {
@@ -130,12 +130,12 @@ class EtherscanParser {
      * @return Promise string of Solidity code
      */
     async getSolidityCode(contractAddress) {
-        const { files, contractName, compilerVersion } = await this.getSourceCode(contractAddress);
+        const { files, contractName, compilerVersion, remappings } = await this.getSourceCode(contractAddress);
         // Parse the UmlClasses from the Solidity code in each file
         let umlClasses = [];
         for (const file of files) {
             const node = await this.parseSourceCode(file.code);
-            const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename);
+            const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, file.filename, remappings);
             umlClasses = umlClasses.concat(umlClass);
         }
         // Sort the classes so dependent code is first
@@ -209,6 +209,7 @@ class EtherscanParser {
             if (!Array.isArray(response?.data?.result)) {
                 throw new Error(`Failed to ${description}. No result array in HTTP data: ${JSON.stringify(response?.data)}`);
             }
+            let remappings;
             const results = response.data.result.map((result) => {
                 if (!result.SourceCode) {
                     throw new Error(`Failed to ${description}. Most likely the contract has not been verified on Etherscan.`);
@@ -223,6 +224,8 @@ class EtherscanParser {
                             parableResultString = result.SourceCode.slice(1, -1);
                         }
                         const sourceCodeObject = JSON.parse(parableResultString);
+                        // Get any remapping of filenames from the settings
+                        remappings = (0, exports.parseRemappings)(sourceCodeObject.settings?.remappings);
                         // The getsource response from Etherscan is inconsistent so we need to handle both shapes
                         const sourceFiles = sourceCodeObject.sources
                             ? Object.entries(sourceCodeObject.sources)
@@ -239,6 +242,8 @@ class EtherscanParser {
                 // if multiple Solidity source files with no Etherscan bug in the SourceCode field
                 if (result?.SourceCode?.sources) {
                     const sourceFiles = Object.values(result.SourceCode.sources);
+                    // Get any remapping of filenames from the settings
+                    remappings = (0, exports.parseRemappings)(result.SourceCode.settings?.remappings);
                     return sourceFiles.map(([filename, code]) => ({
                         code: code.content,
                         filename,
@@ -254,6 +259,7 @@ class EtherscanParser {
                 files: results.flat(1),
                 contractName: response.data.result[0].ContractName,
                 compilerVersion: response.data.result[0].CompilerVersion,
+                remappings,
             };
         }
         catch (err) {
@@ -268,4 +274,31 @@ class EtherscanParser {
     }
 }
 exports.EtherscanParser = EtherscanParser;
+/**
+ * Parses Ethersan's remappings config in its API response
+ * @param rawMappings
+ */
+const parseRemappings = (rawMappings) => {
+    if (!rawMappings)
+        return [];
+    return rawMappings.map((mapping) => (0, exports.parseRemapping)(mapping));
+};
+exports.parseRemappings = parseRemappings;
+/**
+ * Parses a single mapping. For example
+ * "@openzeppelin/=lib/openzeppelin-contracts/"
+ * This is from Uniswap's UniversalRouter in the Settings section after the source files
+ * https://etherscan.io/address/0xEf1c6E67703c7BD7107eed8303Fbe6EC2554BF6B#code
+ * @param mapping
+ */
+const parseRemapping = (mapping) => {
+    const equalIndex = mapping.indexOf('=');
+    const from = mapping.slice(0, equalIndex);
+    const to = mapping.slice(equalIndex + 1);
+    return {
+        from: new RegExp('^' + from),
+        to,
+    };
+};
+exports.parseRemapping = parseRemapping;
 //# sourceMappingURL=parserEtherscan.js.map

package/lib/parserFiles.d.ts

@@ -1,6 +1,6 @@
 import { ASTNode } from '@solidity-parser/parser/dist/src/ast-types';
 import { UmlClass } from './umlClass';
-export declare const parseUmlClassesFromFiles: (filesOrFolders: string[], ignoreFilesOrFolders: string[], subfolders?: number) => Promise<UmlClass[]>;
-export declare function getSolidityFilesFromFolderOrFiles(folderOrFilePaths: string[], ignoreFilesOrFolders: string[], subfolders?: number): Promise<string[]>;
-export declare function getSolidityFilesFromFolderOrFile(folderOrFilePath: string, ignoreFilesOrFolders?: string[], depthLimit?: number): Promise<string[]>;
+export declare const parseUmlClassesFromFiles: (filesOrFolders: readonly string[], ignoreFilesOrFolders: readonly string[], subfolders?: number) => Promise<UmlClass[]>;
+export declare function getSolidityFilesFromFolderOrFiles(folderOrFilePaths: readonly string[], ignoreFilesOrFolders: readonly string[], subfolders?: number): Promise<string[]>;
+export declare function getSolidityFilesFromFolderOrFile(folderOrFilePath: string, ignoreFilesOrFolders?: readonly string[], depthLimit?: number): Promise<string[]>;
 export declare function parseSolidityFile(fileName: string): ASTNode;

package/lib/parserFiles.js

@@ -16,7 +16,7 @@ const parseUmlClassesFromFiles = async (filesOrFolders, ignoreFilesOrFolders, su
     for (const file of files) {
         const node = await parseSolidityFile(file);
         const relativePath = (0, path_1.relative)(process.cwd(), file);
-        const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, relativePath, true);
+        const umlClass = (0, converterAST2Classes_1.convertAST2UmlClasses)(node, relativePath, [], true);
         umlClasses = umlClasses.concat(umlClass);
     }
     return umlClasses;
@@ -82,7 +82,7 @@ function getSolidityFilesFromFolderOrFile(folderOrFilePath, ignoreFilesOrFolders
             else {
                 error = new Error(`Failed to get Solidity files under folder or file ${folderOrFilePath}`, { cause: err });
             }
-            console.error(error.stack);
+            console.error(error);
             reject(error);
         }
     });

package/lib/slotValues.d.ts

@@ -1,3 +1,49 @@
 import { BigNumberish } from '@ethersproject/bignumber';
-export declare const getStorageValue: (url: string, contractAddress: string, slot: BigNumberish, blockTag?: BigNumberish | 'latest') => Promise<string>;
-export declare const getStorageValues: (url: string, contractAddress: string, slots: BigNumberish[], blockTag?: BigNumberish | 'latest') => Promise<string[]>;
+import { StorageSection, Variable } from './converterClasses2Storage';
+/**
+ * Adds the slot values to the variables in the storage section.
+ * This can be rerun for a section as it will only get if the slot value
+ * does not exist.
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If contract is proxied, use proxy and not the implementation contract.
+ * @param storageSection is mutated with the slot values added to the variables
+ * @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 addSlotValues: (url: string, contractAddress: string, storageSection: StorageSection, arrayItems: number, blockTag: BigNumberish) => Promise<void>;
+export declare const parseValue: (variable: Variable) => string;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @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 slotKeys array of 32 byte slot keys as BigNumbers.
+ * @param blockTag block number or `latest`
+ * @return slotValues array of 32 byte slot values as hexadecimal strings
+ */
+export declare const getSlotValues: (url: string, contractAddress: string, slotKeys: readonly BigNumberish[], blockTag?: BigNumberish | 'latest') => Promise<string[]>;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @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 slotKey 32 byte slot key as a BigNumber.
+ * @param blockTag block number or `latest`
+ * @return slotValue 32 byte slot value as hexadecimal string
+ */
+export declare const getSlotValue: (url: string, contractAddress: string, slotKey: BigNumberish, blockTag: BigNumberish | 'latest') => Promise<string>;
+/**
+ * Calculates the number of string characters or bytes of a string or bytes type.
+ * See the following for how string and bytes are stored in storage slots
+ * https://docs.soliditylang.org/en/v0.8.17/internals/layout_in_storage.html#bytes-and-string
+ * @param variable the variable with the slotValue that is being sized
+ * @return bytes the number of bytes of the dynamic slot. If static, zero is return.
+ */
+export declare const dynamicSlotSize: (variable: {
+    name?: string;
+    type?: string;
+    slotValue?: string;
+}) => number;
+export declare const convert2String: (bytes: string) => string;
+export declare const escapeString: (text: string) => string;