wormhole-foundation · VolodymyrBg · May 19, 2025 · May 19, 2025 · May 19, 2025 · May 19, 2025
@@ -6,51 +6,103 @@ pragma solidity ^0.8.0;
 import "./State.sol";
 
 contract Getters is State {
+    /**
+     * @notice Returns the GuardianSet for a given index.
+     * @param index The index of the GuardianSet.
+     * @return The GuardianSet struct.
+     */
     function getGuardianSet(uint32 index) public view returns (Structs.GuardianSet memory) {
         return _state.guardianSets[index];
     }
 
+    /**
+     * @notice Returns the current GuardianSet index.
+     * @return The current GuardianSet index.
+     */
     function getCurrentGuardianSetIndex() public view returns (uint32) {
         return _state.guardianSetIndex;
     }
 
+    /**
+     * @notice Returns the expiry time for the current GuardianSet.
+     * @return The expiry timestamp (in seconds since epoch).
+     */
     function getGuardianSetExpiry() public view returns (uint32) {
         return _state.guardianSetExpiry;
     }
 
+    /**
+     * @notice Checks if a governance action has already been consumed.
+     * @param hash The hash of the governance action.
+     * @return True if the action has been consumed, false otherwise.
+     */
     function governanceActionIsConsumed(bytes32 hash) public view returns (bool) {
         return _state.consumedGovernanceActions[hash];
     }
 
+    /**
+     * @notice Checks if an implementation address has been initialized.
+     * @param impl The implementation address.
+     * @return True if initialized, false otherwise.
+     */
     function isInitialized(address impl) public view returns (bool) {
         return _state.initializedImplementations[impl];
     }
 
+    /**
+     * @notice Returns the Wormhole chain ID.
+     * @return The chain ID.
+     */
     function chainId() public view returns (uint16) {
         return _state.provider.chainId;
     }
 
+    /**
+     * @notice Returns the EVM chain ID.
+     * @return The EVM chain ID.
+     */
     function evmChainId() public view returns (uint256) {
         return _state.evmChainId;
     }
 
+    /**
+     * @notice Returns true if the contract is running on a forked chain.
+     * @return True if on a fork, false otherwise.
+     */
     function isFork() public view returns (bool) {
         return evmChainId() != block.chainid;
     }
 
+    /**
+     * @notice Returns the governance chain ID.
+     * @return The governance chain ID.
+     */
     function governanceChainId() public view returns (uint16){
         return _state.provider.governanceChainId;
     }
 
+    /**
+     * @notice Returns the governance contract address.
+     * @return The governance contract address (bytes32).
+     */
     function governanceContract() public view returns (bytes32){
         return _state.provider.governanceContract;
     }
 
+    /**
+     * @notice Returns the current message fee.
+     * @return The message fee in wei.
+     */
     function messageFee() public view returns (uint256) {
         return _state.messageFee;
     }
 
+    /**
+     * @notice Returns the next sequence number for a given emitter address.
+     * @param emitter The emitter address.
+     * @return The next sequence number.
+     */
     function nextSequence(address emitter) public view returns (uint64) {
         return _state.sequences[emitter];
     }
-}
+}
@@ -22,7 +22,9 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
     bytes32 constant module = 0x00000000000000000000000000000000000000000000000000000000436f7265;
 
     /**
-     * @dev Upgrades a contract via Governance VAA/VM
+     * @notice Submits a contract upgrade via Governance VAA/VM.
+     * @dev Only callable if not on a fork. Upgrades the implementation to a new contract.
+     * @param _vm The encoded Governance VAA/VM.
      */
     function submitContractUpgrade(bytes memory _vm) public {
         require(!isFork(), "invalid fork");
@@ -49,7 +51,9 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
     }
 
     /**
-     * @dev Sets a `messageFee` via Governance VAA/VM
+     * @notice Sets the message fee via Governance VAA/VM.
+     * @dev Updates the message fee for the contract.
+     * @param _vm The encoded Governance VAA/VM.
      */
     function submitSetMessageFee(bytes memory _vm) public {
         Structs.VM memory vm = parseVM(_vm);
@@ -74,7 +78,9 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
     }
 
     /**
-     * @dev Deploys a new `guardianSet` via Governance VAA/VM
+     * @notice Deploys a new GuardianSet via Governance VAA/VM.
+     * @dev Adds a new GuardianSet and updates the index.
+     * @param _vm The encoded Governance VAA/VM.
      */
     function submitNewGuardianSet(bytes memory _vm) public {
         Structs.VM memory vm = parseVM(_vm);
@@ -112,7 +118,9 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
     }
 
     /**
-     * @dev Submits transfer fees to the recipient via Governance VAA/VM
+     * @notice Submits transfer fees to the recipient via Governance VAA/VM.
+     * @dev Transfers the specified amount to the recipient address.
+     * @param _vm The encoded Governance VAA/VM.
      */
     function submitTransferFees(bytes memory _vm) public {
         Structs.VM memory vm = parseVM(_vm);
@@ -141,8 +149,10 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
     }
 
     /**
-    * @dev Updates the `chainId` and `evmChainId` on a forked chain via Governance VAA/VM
-    */
+     * @notice Updates the chainId and evmChainId on a forked chain via Governance VAA/VM.
+     * @dev Only callable on a fork. Updates the chain IDs.
+     * @param _vm The encoded Governance VAA/VM.
+     */
     function submitRecoverChainId(bytes memory _vm) public {
         require(isFork(), "not a fork");
 
@@ -218,4 +228,4 @@ abstract contract Governance is GovernanceStructs, Messages, Setters, ERC1967Upg
         // Confirm the governance VAA/VM is valid
         return (true, "");
     }
-}
+}
@@ -19,45 +19,40 @@ contract GovernanceStructs {
     }
 
     struct ContractUpgrade {
-        bytes32 module;
-        uint8 action;
-        uint16 chain;
-
-        address newContract;
+        bytes32 module; ///< The module identifier.
+        uint8 action; ///< The action type (should be 1 for ContractUpgrade).
+        uint16 chain; ///< The chain ID for which the upgrade is intended.
+        address newContract; ///< The address of the new contract implementation.
     }
 
     struct GuardianSetUpgrade {
-            bytes32 module;
-        uint8 action;
-        uint16 chain;
-
-        Structs.GuardianSet newGuardianSet;
-        uint32 newGuardianSetIndex;
+        bytes32 module; ///< The module identifier.
+        uint8 action; ///< The action type (should be 2 for GuardianSetUpgrade).
+        uint16 chain; ///< The chain ID for which the upgrade is intended.
+        Structs.GuardianSet newGuardianSet; ///< The new GuardianSet to be added.
+        uint32 newGuardianSetIndex; ///< The index of the new GuardianSet.
     }
 
     struct SetMessageFee {
-        bytes32 module;
-        uint8 action;
-        uint16 chain;
-
-        uint256 messageFee;
+        bytes32 module; ///< The module identifier.
+        uint8 action; ///< The action type (should be 3 for SetMessageFee).
+        uint16 chain; ///< The chain ID for which the fee is set.
+        uint256 messageFee; ///< The new message fee value.
     }
 
     struct TransferFees {
-        bytes32 module;
-        uint8 action;
-        uint16 chain;
-
-        uint256 amount;
-        bytes32 recipient;
+        bytes32 module; ///< The module identifier.
+        uint8 action; ///< The action type (should be 4 for TransferFees).
+        uint16 chain; ///< The chain ID for which the transfer is intended.
+        uint256 amount; ///< The amount of fees to transfer.
+        bytes32 recipient; ///< The recipient address (as bytes32).
     }
 
     struct RecoverChainId {
-        bytes32 module;
-        uint8 action;
-
-        uint256 evmChainId;
-        uint16 newChainId;
+        bytes32 module; ///< The module identifier.
+        uint8 action; ///< The action type (should be 5 for RecoverChainId).
+        uint256 evmChainId; ///< The new EVM chain ID.
+        uint16 newChainId; ///< The new Wormhole chain ID.
     }
 
     /// @dev Parse a contract upgrade (action 1) with minimal validation
@@ -180,4 +175,4 @@ contract GovernanceStructs {
 
         require(encodedRecoverChainId.length == index, "invalid RecoverChainId");
     }
-}
+}
@@ -11,7 +11,14 @@ import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Upgrade.sol";
 contract Implementation is Governance {
     event LogMessagePublished(address indexed sender, uint64 sequence, uint32 nonce, bytes payload, uint8 consistencyLevel);
 
-    // Publish a message to be attested by the Wormhole network
+    /**
+     * @notice Publishes a message to be attested by the Wormhole network.
+     * @dev Emits a LogMessagePublished event. Requires a fee equal to messageFee().
+     * @param nonce A user-supplied nonce for replay protection.
+     * @param payload The message payload to publish.
+     * @param consistencyLevel The desired consistency level for the message.
+     * @return sequence The sequence number of the published message.
+     */
     function publishMessage(
         uint32 nonce,
         bytes memory payload,
@@ -30,6 +37,11 @@ contract Implementation is Governance {
         setNextSequence(emitter, sequence + 1);
     }
 
+    /**
+     * @notice Initializes the contract after an upgrade.
+     * @dev This function must 
F438
be called after an upgrade to set the EVM chain ID if not already set.
+     * Can only be called once per implementation.
+     */
     function initialize() initializer public virtual {
         // this function needs to be exposed for an upgrade to pass
         if (evmChainId() == 0) {
@@ -61,6 +73,9 @@ contract Implementation is Governance {
         }
     }
 
+    /**
+     * @dev Modifier to ensure the contract is only initialized once per implementation.
+     */
     modifier initializer() {
         address implementation = ERC1967Upgrade._getImplementation();
 
@@ -74,7 +89,13 @@ contract Implementation is Governance {
         _;
     }
 
+    /**
+     * @notice Fallback function. Always reverts as this contract does not support fallback calls.
+     */
     fallback() external payable {revert("unsupported");}
 
+    /**
+     * @notice Receive function. Always reverts as this contract does not accept assets.
+     */
     receive() external payable {revert("the Wormhole contract does not accept assets");}
 }
@@ -12,20 +12,26 @@ import "./libraries/external/BytesLib.sol";
 contract Messages is Getters {
     using BytesLib for bytes;
 
-    /// @dev parseAndVerifyVM serves to parse an encodedVM and wholy validate it for consumption
+    /**
+     * @notice Parses and verifies an encoded VM (Validator Message).
+     * @dev Parses the encoded VM and validates it against the current Guardian set.
+     * @param encodedVM The encoded VM bytes.
+     * @return vm The parsed VM struct.
+     * @return valid True if the VM is valid, false otherwise.
+     * @return reason The reason for failure if not valid.
+     */
     function parseAndVerifyVM(bytes calldata encodedVM) public view returns (Structs.VM memory vm, bool valid, string memory reason) {
         vm = parseVM(encodedVM);
         /// setting checkHash to false as we can trust the hash field in this case given that parseVM computes and then sets the hash field above
         (valid, reason) = verifyVMInternal(vm, false);
     }
 
    /**
-    * @dev `verifyVM` serves to validate an arbitrary vm against a valid Guardian set
-    *  - it aims to make sure the VM is for a known guardianSet
-    *  - it aims to ensure the guardianSet is not expired
-    *  - it aims to ensure the VM has reached quorum
-    *  - it aims to verify the signatures provided against the guardianSet
-    *  - it aims to verify the hash field provided against the contents of the vm
+    * @notice Verifies a VM against the current Guardian set.
+    * @dev Checks signatures, quorum, and expiration.
+    * @param vm The VM struct to verify.
+    * @return valid True if the VM is valid, false otherwise.
+    * @return reason The reason for failure if not valid.
     */
     function verifyVM(Structs.VM memory vm) public view returns (bool valid, string memory reason) {
         (valid, reason) = verifyVMInternal(vm, true);    
@@ -103,10 +109,13 @@ contract Messages is Getters {
 
 
     /**
-     * @dev verifySignatures serves to validate arbitrary sigatures against an arbitrary guardianSet
-     *  - it intentionally does not solve for expectations within guardianSet (you should use verifyVM if you need these protections)
-     *  - it intentioanlly does not solve for quorum (you should use verifyVM if you need these protections)
-     *  - it intentionally returns true when signatures is an empty set (you should use verifyVM if you need these protections)
+     * @notice Verifies a set of signatures against a Guardian set.
+     * @dev Does not check quorum or expectations within the Guardian set.
+     * @param hash The hash that was signed.
+     * @param signatures The array of signatures.
+     * @param guardianSet The Guardian set to check against.
+     * @return valid True if all signatures are valid, false otherwise.
+     * @return reason The reason for failure if not valid.
      */
     function verifySignatures(bytes32 hash, Structs.Signature[] memory signatures, Structs.GuardianSet memory guardianSet) public pure returns (bool valid, string memory reason) {
         uint8 lastIndex = 0;
@@ -141,8 +150,10 @@ contract Messages is Getters {
     }
 
     /**
-     * @dev parseVM serves to parse an encodedVM into a vm struct
-     *  - it intentionally performs no validation functions, it simply parses raw into a struct
+     * @notice Parses an encoded VM into a VM struct.
+     * @dev Performs no validation, only parsing.
+     * @param encodedVM The encoded VM bytes.
+     * @return vm The parsed VM struct.
      */
     function parseVM(bytes memory encodedVM) public pure virtual returns (Structs.VM memory vm) {
         uint index = 0;
@@ -208,7 +219,9 @@ contract Messages is Getters {
     }
 
     /**
-     * @dev quorum serves solely to determine the number of signatures required to acheive quorum
+     * @notice Calculates the number of signatures required for quorum.
+     * @param numGuardians The number of guardians in the set.
+     * @return numSignaturesRequiredForQuorum The number of signatures required for quorum.
      */
     function quorum(uint numGuardians) public pure virtual returns (uint numSignaturesRequiredForQuorum) {
         // The max number of guardians is 255