From dbf8db97635e4fa7c1808c55e62c20f5e987935d Mon Sep 17 00:00:00 2001 From: dave | d1onys1us <13951458+d1onys1us@users.noreply.github.com> Date: Tue, 3 Jan 2023 22:03:35 -0500 Subject: [PATCH] feat(docs): autocommit changes to solidity docs and omit private state vars and functions (#490) --- .github/workflows/solidity.yml | 6 + packages/protocol/hardhat.config.ts | 1 + packages/protocol/package.json | 4 +- .../solidity-docgen/templates/common.hbs | 5 +- .../docs/smart-contracts/L1/LibData.md | 105 ++++++++++++++++++ .../docs/smart-contracts/L1/TkoToken.md | 1 - .../docs/smart-contracts/L2/TaikoL2.md | 12 -- .../docs/smart-contracts/bridge/Bridge.md | 6 - .../docs/smart-contracts/bridge/EtherVault.md | 12 -- .../docs/smart-contracts/bridge/IBridge.md | 2 - .../docs/smart-contracts/bridge/TokenVault.md | 19 ---- .../smart-contracts/common/AddressResolver.md | 12 -- .../smart-contracts/common/ConfigManager.md | 6 - pnpm-lock.yaml | 8 +- 14 files changed, 121 insertions(+), 78 deletions(-) create mode 100644 packages/website/docs/smart-contracts/L1/LibData.md diff --git a/.github/workflows/solidity.yml b/.github/workflows/solidity.yml index 2f6b3ea8018..55f0321d18e 100644 --- a/.github/workflows/solidity.yml +++ b/.github/workflows/solidity.yml @@ -68,6 +68,12 @@ jobs: working-directory: ./packages/protocol run: pnpm export:docs + - uses: stefanzweifel/git-auto-commit-action@v4 + name: protocol - Auto Commit Solidity Docs + if: github.ref != 'refs/heads/main' + with: + commit_message: "chore(docs): auto commit solidity docs" + - name: protocol - Deploy L1 Contracts working-directory: ./packages/protocol run: pnpm deploy:hardhat diff --git a/packages/protocol/hardhat.config.ts b/packages/protocol/hardhat.config.ts index 01cfec2b7b1..d1bc8c40ac7 100644 --- a/packages/protocol/hardhat.config.ts +++ b/packages/protocol/hardhat.config.ts @@ -22,6 +22,7 @@ const config: HardhatUserConfig = { "thirdparty/", "common/EssentialContract.sol", ], + outputDir: "../website/docs/smart-contracts/", pages: "files", templates: "./solidity-docgen/templates", }, diff --git a/packages/protocol/package.json b/packages/protocol/package.json index bb4b7ff2b00..8cf7dfcd672 100644 --- a/packages/protocol/package.json +++ b/packages/protocol/package.json @@ -5,7 +5,7 @@ "scripts": { "compile": "pnpm hardhat preprocess && pnpm hardhat compile", "export:abi": "pnpm hardhat clear-abi && pnpm hardhat export-abi", - "export:docs": "pnpm hardhat docgen && pnpm prettier --write ./docs/**/*.md", + "export:docs": "pnpm hardhat docgen && pnpm prettier --write ../website/docs/smart-contracts/**/*.md", "clean": "rm -rf abis cache && pnpm hardhat clean", "lint:sol": "pnpm prettier '**/*.sol' --write && pnpm solhint 'contracts/**/*.sol' --fix", "eslint": "pnpm exec eslint --ignore-path .eslintignore --ext .js,.ts .", @@ -71,7 +71,7 @@ "rlp": "^3.0.0", "solhint": "^3.3.7", "solidity-coverage": "^0.8.2", - "solidity-docgen": "^0.6.0-beta.29", + "solidity-docgen": "^0.6.0-beta.34", "ts-node": "^10.5.0", "typechain": "^5.2.0", "typescript": "^4.5.5" diff --git a/packages/protocol/solidity-docgen/templates/common.hbs b/packages/protocol/solidity-docgen/templates/common.hbs index b2a3b2a5a2a..2a723215fe8 100644 --- a/packages/protocol/solidity-docgen/templates/common.hbs +++ b/packages/protocol/solidity-docgen/templates/common.hbs @@ -9,7 +9,9 @@ {{{natspec.notice}}} {{#if natspec.dev}} +{{#unless (eq visibility "internal")}} _{{{natspec.dev}}}_ +{{/unless}} {{/if}} {{#if natspec.params}} @@ -30,5 +32,4 @@ _{{{natspec.dev}}}_ {{#each returns}} | {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} | {{/each}} -{{/if}} - +{{/if}} \ No newline at end of file diff --git a/packages/website/docs/smart-contracts/L1/LibData.md b/packages/website/docs/smart-contracts/L1/LibData.md new file mode 100644 index 00000000000..03dcd6c5dac --- /dev/null +++ b/packages/website/docs/smart-contracts/L1/LibData.md @@ -0,0 +1,105 @@ +## LibData + +### BlockMetadata + +```solidity +struct BlockMetadata { + uint256 id; + uint256 l1Height; + bytes32 l1Hash; + address beneficiary; + bytes32 txListHash; + bytes32 mixHash; + bytes extraData; + uint64 gasLimit; + uint64 timestamp; + uint64 commitHeight; + uint64 commitSlot; +} +``` + +### ProposedBlock + +```solidity +struct ProposedBlock { + bytes32 metaHash; + address proposer; + uint64 proposedAt; +} +``` + +### ForkChoice + +```solidity +struct ForkChoice { + bytes32 blockHash; + uint64 provenAt; + address[] provers; +} +``` + +### State + +```solidity +struct State { + mapping(uint256 => bytes32) l2Hashes; + mapping(uint256 => struct LibData.ProposedBlock) proposedBlocks; + mapping(uint256 => mapping(bytes32 => struct LibData.ForkChoice)) forkChoices; + mapping(address => mapping(uint256 => bytes32)) commits; + uint64 genesisHeight; + uint64 genesisTimestamp; + uint64 __reservedA1; + uint64 statusBits; + uint64 nextBlockId; + uint64 lastProposedAt; + uint64 avgBlockTime; + uint64 __avgGasLimit; + uint64 latestVerifiedHeight; + uint64 latestVerifiedId; + uint64 avgProofTime; + uint64 __reservedC1; + uint256[42] __gap; +} +``` + +### TentativeState + +```solidity +struct TentativeState { + mapping(address => bool) proposers; + mapping(address => bool) provers; + bool whitelistProposers; + bool whitelistProvers; + uint256[46] __gap; +} +``` + +### saveProposedBlock + +```solidity +function saveProposedBlock(struct LibData.State state, uint256 id, struct LibData.ProposedBlock blk) internal +``` + +### getProposedBlock + +```solidity +function getProposedBlock(struct LibData.State state, uint256 id) internal view returns (struct LibData.ProposedBlock) +``` + +### getL2BlockHash + +```solidity +function getL2BlockHash(struct LibData.State state, uint256 number) internal view returns (bytes32) +``` + +### getStateVariables + +```solidity +function getStateVariables(struct LibData.State state) internal view returns (uint64 genesisHeight, uint64 latestVerifiedHeight, uint64 latestVerifiedId, uint64 nextBlockId) +``` + +### hashMetadata + +```solidity +function hashMetadata(struct LibData.BlockMetadata meta) internal pure returns (bytes32) +``` diff --git a/packages/website/docs/smart-contracts/L1/TkoToken.md b/packages/website/docs/smart-contracts/L1/TkoToken.md index 147dcf27b1d..7909d2887f5 100644 --- a/packages/website/docs/smart-contracts/L1/TkoToken.md +++ b/packages/website/docs/smart-contracts/L1/TkoToken.md @@ -2,7 +2,6 @@ _This is Taiko's governance and fee token._ - ### Mint ```solidity diff --git a/packages/website/docs/smart-contracts/L2/TaikoL2.md b/packages/website/docs/smart-contracts/L2/TaikoL2.md index da9d73373af..a25186c80ba 100644 --- a/packages/website/docs/smart-contracts/L2/TaikoL2.md +++ b/packages/website/docs/smart-contracts/L2/TaikoL2.md @@ -1,17 +1,5 @@ ## TaikoL2 -### l2Hashes - -```solidity -mapping(uint256 => bytes32) l2Hashes -``` - -### l1Hashes - -```solidity -mapping(uint256 => bytes32) l1Hashes -``` - ### publicInputHash ```solidity diff --git a/packages/website/docs/smart-contracts/bridge/Bridge.md b/packages/website/docs/smart-contracts/bridge/Bridge.md index 21277f48c92..448f41941f8 100644 --- a/packages/website/docs/smart-contracts/bridge/Bridge.md +++ b/packages/website/docs/smart-contracts/bridge/Bridge.md @@ -5,12 +5,6 @@ which calls the library implementations. See {IBridge} for more details. _The code hash for the same address on L1 and L2 may be different._ -### state - -```solidity -struct LibBridgeData.State state -``` - ### MessageStatusChanged ```solidity diff --git a/packages/website/docs/smart-contracts/bridge/EtherVault.md b/packages/website/docs/smart-contracts/bridge/EtherVault.md index b6696ec7798..d3624157100 100644 --- a/packages/website/docs/smart-contracts/bridge/EtherVault.md +++ b/packages/website/docs/smart-contracts/bridge/EtherVault.md @@ -2,18 +2,6 @@ Vault that holds Ether. -### authorizedAddrs - -```solidity -mapping(address => bool) authorizedAddrs -``` - -### \_\_gap - -```solidity -uint256[49] __gap -``` - ### Authorized ```solidity diff --git a/packages/website/docs/smart-contracts/bridge/IBridge.md b/packages/website/docs/smart-contracts/bridge/IBridge.md index a1a9788f19b..5997fc2ddb3 100644 --- a/packages/website/docs/smart-contracts/bridge/IBridge.md +++ b/packages/website/docs/smart-contracts/bridge/IBridge.md @@ -22,7 +22,6 @@ struct Message { bytes data; string memo; } - ``` ### Context @@ -33,7 +32,6 @@ struct Context { address sender; uint256 srcChainId; } - ``` ### SignalSent diff --git a/packages/website/docs/smart-contracts/bridge/TokenVault.md b/packages/website/docs/smart-contracts/bridge/TokenVault.md index 8841d2e771e..0fd52b87721 100644 --- a/packages/website/docs/smart-contracts/bridge/TokenVault.md +++ b/packages/website/docs/smart-contracts/bridge/TokenVault.md @@ -14,7 +14,6 @@ struct CanonicalERC20 { string symbol; string name; } - ``` ### isBridgedToken @@ -35,12 +34,6 @@ mapping(address => struct TokenVault.CanonicalERC20) bridgedToCanonical mapping(uint256 => mapping(address => address)) canonicalToBridged ``` -### \_\_gap - -```solidity -uint256[47] __gap -``` - ### BridgedERC20Deployed ```solidity @@ -140,15 +133,3 @@ invoking a message call._ | from | address | The source address. | | to | address | The destination address. | | amount | uint256 | The amount of tokens to be sent. 0 is a valid value. | - -### \_getOrDeployBridgedToken - -```solidity -function _getOrDeployBridgedToken(struct TokenVault.CanonicalERC20 canonicalToken) private returns (address) -``` - -### \_deployBridgedToken - -```solidity -function _deployBridgedToken(struct TokenVault.CanonicalERC20 canonicalToken) private returns (address bridgedToken) -``` diff --git a/packages/website/docs/smart-contracts/common/AddressResolver.md b/packages/website/docs/smart-contracts/common/AddressResolver.md index 1d84900aa87..e6e81c7cc72 100644 --- a/packages/website/docs/smart-contracts/common/AddressResolver.md +++ b/packages/website/docs/smart-contracts/common/AddressResolver.md @@ -9,12 +9,6 @@ it uses an AddressManager to manage the name-to-address mapping. contract IAddressManager _addressManager ``` -### \_\_gap - -```solidity -uint256[49] __gap -``` - ### onlyFromNamed ```solidity @@ -91,9 +85,3 @@ Returns the AddressManager's address. ```solidity function _init(address addressManager_) internal virtual ``` - -### \_resolve - -```solidity -function _resolve(uint256 chainId, string name) private view returns (address payable) -``` diff --git a/packages/website/docs/smart-contracts/common/ConfigManager.md b/packages/website/docs/smart-contracts/common/ConfigManager.md index da0a49d19d2..4c3d2ddb171 100644 --- a/packages/website/docs/smart-contracts/common/ConfigManager.md +++ b/packages/website/docs/smart-contracts/common/ConfigManager.md @@ -1,11 +1,5 @@ ## ConfigManager -### kv - -```solidity -mapping(bytes32 => bytes) kv -``` - ### Updated ```solidity diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e56ae85a5fe..a1044844ed7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -157,7 +157,7 @@ importers: rlp: ^3.0.0 solhint: ^3.3.7 solidity-coverage: ^0.8.2 - solidity-docgen: ^0.6.0-beta.29 + solidity-docgen: ^0.6.0-beta.34 ts-node: ^10.5.0 typechain: ^5.2.0 typescript: ^4.5.5 @@ -203,7 +203,7 @@ importers: rlp: 3.0.0 solhint: 3.3.7 solidity-coverage: 0.8.2_hardhat@2.12.2 - solidity-docgen: 0.6.0-beta.30_hardhat@2.12.2 + solidity-docgen: 0.6.0-beta.34_hardhat@2.12.2 ts-node: 10.9.1_vw4thnff6td543szquzqpxymti typechain: 5.2.0_typescript@4.9.3 typescript: 4.9.3 @@ -18185,8 +18185,8 @@ packages: - supports-color dev: true - /solidity-docgen/0.6.0-beta.30_hardhat@2.12.2: - resolution: {integrity: sha512-CfwhhM/hQIWm0LHyUIJse4Lz4kR+VahBfns5Z0l7l+2V3Emv8LNIG8a6aM1+r0k49iOVfO1xyFaJyXFS1UD8cA==} + /solidity-docgen/0.6.0-beta.34_hardhat@2.12.2: + resolution: {integrity: sha512-igdGrkg8gT1jn+B2NwzjEtSf+7NTrSi/jz88zO7MZWgETmcWbXaxgAsQP4BQeC4YFeH0Pie1NsLP7+9qDgvFtA==} peerDependencies: hardhat: ^2.8.0 dependencies: