From 643110c6964c3b63f4a811639325b9f781e9db9f Mon Sep 17 00:00:00 2001 From: The Dark Jester Date: Mon, 6 Jan 2025 14:12:38 +0000 Subject: [PATCH] [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 * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester --------- Signed-off-by: The Dark Jester Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> --- .husky/pre-commit.js | 21 +++-- contracts/docs/api/LineaRollup.mdx | 8 -- .../docs/api/interfaces/IPauseManager.mdx | 92 ++++++++++++++++++- .../docs/api/interfaces/l1/ILineaRollup.mdx | 8 -- .../docs/api/lib/CallForwardingProxy.mdx | 10 +- contracts/docs/api/lib/PauseManager.mdx | 58 +++++++++++- contracts/docs/scripts/updateSidebar.js | 31 ++----- contracts/package.json | 3 +- 8 files changed, 180 insertions(+), 51 deletions(-) diff --git a/.husky/pre-commit.js b/.husky/pre-commit.js index 86d60c09..0c1728a1 100644 --- a/.husky/pre-commit.js +++ b/.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 - * @param {FOLDER, FILE_EXTENSION[]} + * Execute command based on 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]; - console.log(`${fileExtension} change found in ${path}, linting...`); + const cmd = _command[fileExtension]; + 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(` diff --git a/contracts/docs/api/LineaRollup.mdx b/contracts/docs/api/LineaRollup.mdx index 96990127..9604dfa5 100644 --- a/contracts/docs/api/LineaRollup.mdx +++ b/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 diff --git a/contracts/docs/api/interfaces/IPauseManager.mdx b/contracts/docs/api/interfaces/IPauseManager.mdx index d09f221c..e8dbf612 100644 --- a/contracts/docs/api/interfaces/IPauseManager.mdx +++ b/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. | + diff --git a/contracts/docs/api/interfaces/l1/ILineaRollup.mdx b/contracts/docs/api/interfaces/l1/ILineaRollup.mdx index 62e8e394..5e53f2a6 100644 --- a/contracts/docs/api/interfaces/l1/ILineaRollup.mdx +++ b/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 diff --git a/contracts/docs/api/lib/CallForwardingProxy.mdx b/contracts/docs/api/lib/CallForwardingProxy.mdx index 0464089f..1b008bce 100644 --- a/contracts/docs/api/lib/CallForwardingProxy.mdx +++ b/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 +``` + diff --git a/contracts/docs/api/lib/PauseManager.mdx b/contracts/docs/api/lib/PauseManager.mdx index 8b85b7d9..470c720b 100644 --- a/contracts/docs/api/lib/PauseManager.mdx +++ b/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. | + diff --git a/contracts/docs/scripts/updateSidebar.js b/contracts/docs/scripts/updateSidebar.js index ccfda338..a362f861 100644 --- a/contracts/docs/scripts/updateSidebar.js +++ b/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( - __dirname, - "docs", - "api", - "linea-smart-contracts", - ); + const smartContractsPath = path.join(__dirname, "docs", "api", "linea-smart-contracts"); let smartContractSidebar = new FolderSidebar( SMART_CONTRACT_SIDEBAR_LABEL, @@ -93,11 +90,7 @@ function getSmartContractSidebar() { false, ); - populateFolderSidebar( - smartContractSidebar, - smartContractsPath, - ".mdx", - ); + populateFolderSidebar(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( - path.join(__dirname, "docs"), - filePath.split(fileExtension)[0], - ); + const relativePath = path.relative(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 = - "/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */"; + const sidebarFileLine1 = "/** @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}`; diff --git a/contracts/package.json b/contracts/package.json index 1669baf1..3169fe78 100644 --- a/contracts/package.json +++ b/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",