[Chore] - Match contract docs locally (#493)

* add docgen for solidity changes to husky

* add solidity docs

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

* Update .husky/pre-commit.js

Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>

---------

Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com>
Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>

.husky/pre-commit.js

@@ -43,12 +43,17 @@ const FILE_EXTENSION_FILTERS = {
     [FILE_EXTENSION.SOLIDITY]: "\.sol$",
 };
 
-// File extension => script in package.json to run
+// File extension => script in package.json to run for linting
 const FILE_EXTENSION_LINTING_COMMAND = {
     [FILE_EXTENSION.TYPESCRIPT]: "pnpm run lint:ts:fix",
     [FILE_EXTENSION.SOLIDITY]: "pnpm run lint:sol:fix",
 };
 
+// File extension => script in package.json to run for documentation generation
+const FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND = {
+    [FILE_EXTENSION.SOLIDITY]: "pnpm run solidity:docgen",
+};
+
 // Project => Path in monorepo
 const FOLDER_PATH = {
     [FOLDER.BRIDGEUI]: "bridge-ui/",
@@ -95,7 +100,8 @@ function main() {
             process.exit(1);
         }
         const changedFileExtensions = getChangedFileExtensions(folder);
-        executeLinting(folder, changedFileExtensions);
+        executeCommand(folder, changedFileExtensions, FILE_EXTENSION_LINTING_COMMAND);
+        executeCommand(folder, changedFileExtensions, FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND);
     }
 
     updateGitIndex();
@@ -180,14 +186,15 @@ function getChangedFileExtensions(_folder) {
 }
 
 /**
- * Execute linting command
+ * Execute command based on file extension
- * @param {FOLDER, FILE_EXTENSION[]}
+ * @param {FOLDER, FILE_EXTENSION[], FILE_EXTENSION_LINTING_COMMAND | FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND}
  */
-function executeLinting(_folder, _changedFileExtensions) {
+function executeCommand(_folder, _changedFileExtensions, _command) {
     for (const fileExtension of _changedFileExtensions) {
         const path = FOLDER_PATH[_folder];
-        const cmd = FILE_EXTENSION_LINTING_COMMAND[fileExtension];
+        const cmd = _command[fileExtension];
-        console.log(`${fileExtension} change found in ${path}, linting...`);
+        if (!cmd) return;
+        console.log(`${fileExtension} change found in ${path}, executing command ${cmd}`);
         try {
             // Execute command synchronously and stream output directly to the current stdout
             execSync(`

contracts/docs/api/LineaRollup.mdx

@@ -24,14 +24,6 @@ bytes32 VERIFIER_UNSETTER_ROLE
 
 The role required to set/remove  proof verifiers by type.
 
-### GENESIS_SHNARF
-
-```solidity
-bytes32 GENESIS_SHNARF
-```
-
-The default genesis shnarf using empty/default hashes and a default state.
-
 ### SHNARF_EXISTS_DEFAULT_VALUE
 
 ```solidity

contracts/docs/api/interfaces/IPauseManager.mdx

@@ -70,6 +70,22 @@ Emitted when a pause type and its associated role are set in the `_pauseTypeRole
 | pauseType | enum IPauseManager.PauseType | The indexed type of pause. |
 | role | bytes32 | The indexed role associated with the pause type. |
 
+### PauseTypeRoleUpdated
+
+```solidity
+event PauseTypeRoleUpdated(enum IPauseManager.PauseType pauseType, bytes32 role, bytes32 previousRole)
+```
+
+Emitted when a pause type and its associated role are updated in the `_PauseTypeRoles` mapping.
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| pauseType | enum IPauseManager.PauseType | The indexed type of pause. |
+| role | bytes32 | The indexed role associated with the pause type. |
+| previousRole | bytes32 | The indexed previously found role associated with the pause type. |
+
 ### UnPauseTypeRoleSet
 
 ```solidity
@@ -85,6 +101,22 @@ Emitted when an unpause type and its associated role are set in the `_unPauseTyp
 | unPauseType | enum IPauseManager.PauseType | The indexed type of unpause. |
 | role | bytes32 | The indexed role associated with the unpause type. |
 
+### UnPauseTypeRoleUpdated
+
+```solidity
+event UnPauseTypeRoleUpdated(enum IPauseManager.PauseType unPauseType, bytes32 role, bytes32 previousRole)
+```
+
+Emitted when an unpause type and its associated role are updated in the `_unPauseTypeRoles` mapping.
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| unPauseType | enum IPauseManager.PauseType | The indexed type of unpause. |
+| role | bytes32 | The indexed role associated with the unpause type. |
+| previousRole | bytes32 | The indexed previously found role associated with the unpause type. |
+
 ### IsPaused
 
 ```solidity
@@ -101,6 +133,22 @@ error IsNotPaused(enum IPauseManager.PauseType pauseType)
 
 _Thrown when a specific pause type is not paused and expected to be._
 
+### PauseTypeNotUsed
+
+```solidity
+error PauseTypeNotUsed()
+```
+
+_Thrown when the unused paused type is used._
+
+### RolesNotDifferent
+
+```solidity
+error RolesNotDifferent()
+```
+
+_Thrown when trying to update a pause/unpause type role mapping to the existing role._
+
 ### pauseByType
 
 ```solidity
@@ -109,7 +157,8 @@ function pauseByType(enum IPauseManager.PauseType _pauseType) external
 
 Pauses functionality by specific type.
 
-_Requires the role mapped in pauseTypeRoles for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in pauseTypeRoles for the pauseType._
 
 #### Parameters
 
@@ -125,7 +174,8 @@ function unPauseByType(enum IPauseManager.PauseType _pauseType) external
 
 Unpauses functionality by specific type.
 
-_Requires the role mapped in unPauseTypeRoles for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in unPauseTypeRoles for the pauseType._
 
 #### Parameters
 
@@ -153,3 +203,41 @@ Check if a pause type is enabled.
 | ---- | ---- | ----------- |
 | pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. |
 
+### updatePauseTypeRole
+
+```solidity
+function updatePauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the pause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+PAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
+### updateUnpauseTypeRole
+
+```solidity
+function updateUnpauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the unpause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+UNPAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+

contracts/docs/api/interfaces/l1/ILineaRollup.mdx

@@ -308,14 +308,6 @@ error FinalizationStateIncorrect(bytes32 expected, bytes32 value)
 
 _Thrown when finalization state does not match._
 
-### FinalBlockNumberLessThanOrEqualToLastFinalizedBlock
-
-```solidity
-error FinalBlockNumberLessThanOrEqualToLastFinalizedBlock(uint256 finalBlockNumber, uint256 lastFinalizedBlock)
-```
-
-_Thrown when the final block number in finalization data is less than or equal to the last finalized block during finalization._
-
 ### FinalBlockStateEqualsZeroHash
 
 ```solidity

contracts/docs/api/lib/CallForwardingProxy.mdx

@@ -1,9 +1,9 @@
 # `CallForwardingProxy`
 
-### target
+### TARGET
 
 ```solidity
-address target
+address TARGET
 ```
 
 The underlying target address that is called.
@@ -22,3 +22,9 @@ fallback() external payable
 
 Defaults to, and forwards all calls to the target address.
 
+### receive
+
+```solidity
+receive() external payable
+```
+

contracts/docs/api/lib/PauseManager.mdx

@@ -22,6 +22,20 @@ This is used to unpause all unpausable functions.
 mapping(bytes32 => bool) pauseTypeStatuses
 ```
 
+### onlyUsedPausedTypes
+
+```solidity
+modifier onlyUsedPausedTypes(enum IPauseManager.PauseType _pauseType)
+```
+
+_Modifier to prevent usage of unused PauseType._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The PauseType value being checked. Requirements: - The type must not be UNUSED. |
+
 ### whenTypeAndGeneralNotPaused
 
 ```solidity
@@ -105,7 +119,8 @@ function pauseByType(enum IPauseManager.PauseType _pauseType) external
 
 Pauses functionality by specific type.
 
-_Requires the role mapped in `_pauseTypeRoles` for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in `_pauseTypeRoles` for the pauseType._
 
 #### Parameters
 
@@ -121,7 +136,8 @@ function unPauseByType(enum IPauseManager.PauseType _pauseType) external
 
 Unpauses functionality by specific type.
 
-_Requires the role mapped in `_unPauseTypeRoles` for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in `_unPauseTypeRoles` for the pauseType._
 
 #### Parameters
 
@@ -149,3 +165,41 @@ Check if a pause type is enabled.
 | ---- | ---- | ----------- |
 | pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. |
 
+### updatePauseTypeRole
+
+```solidity
+function updatePauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the pause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+PAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
+### updateUnpauseTypeRole
+
+```solidity
+function updateUnpauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the unpause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+UNPAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+

contracts/docs/scripts/updateSidebar.js

@@ -1,10 +1,10 @@
 /* eslint-disable */
 // This script is meant to be executed in the root directory of https://github.com/Consensys/doc.linea, which has different linting rules
-// The purpose of this script is to modify the sidebars.js file to correctly include the autogenerated smart contract documentation 
+// The purpose of this script is to modify the sidebars.js file to correctly include the autogenerated smart contract documentation
 
 /**
  * PURPOSE
- * 
+ *
  * Modifies sidebars.js in the root directory of https://github.com/Consensys/doc.linea to correctly include smart contract documentation pages.
  * The sidebars.js file configures the sidebar for the documentation website @ https://docs.linea.build/
  */
@@ -70,7 +70,9 @@ function main() {
  */
 function removeExistingSmartContractSidebar(sidebarObject) {
   if (sidebarObject?.apiSidebar) {
-    sidebarObject.apiSidebar = sidebarObject?.apiSidebar.filter(sidebarSection => sidebarSection?.label !== SMART_CONTRACT_SIDEBAR_LABEL);
+    sidebarObject.apiSidebar = sidebarObject?.apiSidebar.filter(
+      (sidebarSection) => sidebarSection?.label !== SMART_CONTRACT_SIDEBAR_LABEL,
+    );
   }
 }
 
@@ -80,12 +82,7 @@ function removeExistingSmartContractSidebar(sidebarObject) {
  */
 function getSmartContractSidebar() {
   // Create and populate smart contract sidebar
-  const smartContractsPath = path.join(
+  const smartContractsPath = path.join(__dirname, "docs", "api", "linea-smart-contracts");
-    __dirname,
-    "docs",
-    "api",
-    "linea-smart-contracts",
-  );
 
   let smartContractSidebar = new FolderSidebar(
     SMART_CONTRACT_SIDEBAR_LABEL,
@@ -93,11 +90,7 @@ function getSmartContractSidebar() {
     false,
   );
 
-  populateFolderSidebar(
+  populateFolderSidebar(smartContractSidebar, smartContractsPath, ".mdx");
-    smartContractSidebar,
-    smartContractsPath,
-    ".mdx",
-  );
 
   return smartContractSidebar;
 }
@@ -120,10 +113,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {
 
     // Base case => *.mdx file => Add relative path to sidebar
     if (fileMetadata.isFile() && fileNode.endsWith(fileExtension)) {
-      const relativePath = path.relative(
+      const relativePath = path.relative(path.join(__dirname, "docs"), filePath.split(fileExtension)[0]);
-        path.join(__dirname, "docs"),
-        filePath.split(fileExtension)[0],
-      );
       folderSidebar?.items.push(relativePath);
     }
   }
@@ -137,7 +127,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {
     if (fileMetadata.isDirectory()) {
       let newFolderNode = new FolderSidebar(fileNode);
       populateFolderSidebar(newFolderNode, filePath, fileExtension);
-      // Add populated child FolderSidebar to current sidebar section 
+      // Add populated child FolderSidebar to current sidebar section
       folderSidebar?.items.push(newFolderNode);
     }
   }
@@ -153,8 +143,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {
  */
 function createNewSidebarFile(sidebarObject) {
   // Create new sidebars.js file content
-  const sidebarFileLine1 =
+  const sidebarFileLine1 = "/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */";
-    "/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */";
   const sidebarFileLine2 = "const sidebars =";
   const sidebarFileLineFinal = "module.exports = sidebars;";
   const newSidebarFileContent = `${sidebarFileLine1}\n${sidebarFileLine2}\n${JSON.stringify(sidebarObject, null, 2)}\n\n${sidebarFileLineFinal}`;

contracts/package.json

@@ -19,7 +19,8 @@
     "lint:ts:fix": "npx eslint --fix '**/*.{js,ts}'",
     "lint": "pnpm run lint:sol && npm run lint:ts && npm run prettier",
     "lint:fix": "pnpm run lint:sol:fix && npm run lint:ts:fix && npm run prettier:fix",
-    "clean": "rimraf .openzeppelin build cache node_modules typechain-types coverage coverage.json"
+    "clean": "rimraf .openzeppelin build cache node_modules typechain-types coverage coverage.json",
+    "solidity:docgen": "npx hardhat docgen"
   },
   "devDependencies": {
     "@ethereumjs/util": "9.0.3",