Merge pull request #6380 from ethereum-optimism/refcell/faucet-styling

fix(ctb): Port Faucet Periphery Contracts to Triple Slash Natspec Styling

packages/contracts-bedrock/.gas-snapshot

-AdminFaucetAuthModuleTest:test_adminProof_verify_succeeds() (gas: 57577)
+AdminFaucetAuthModuleTest:test_adminProof_verify_succeeds() (gas: 57573)
 AdminFaucetAuthModuleTest:test_nonAdminProof_verify_succeeds() (gas: 59050)
 AdminFaucetAuthModuleTest:test_proofWithWrongId_verify_succeeds() (gas: 60673)
 AssetReceiverTest:test_constructor_succeeds() (gas: 9696)
@@ -70,14 +70,14 @@ Drippie_Test:test_status_unauthorized_reverts() (gas: 167344)
 Drippie_Test:test_trigger_oneFunction_succeeds() (gas: 338143)
 Drippie_Test:test_trigger_twoFunctions_succeeds() (gas: 491870)
 Drippie_Test:test_twice_inOneInterval_reverts() (gas: 303767)
-FaucetTest:test_authAdmin_drip_succeeds() (gas: 366111)
-FaucetTest:test_drip_afterTimeout_succeeds() (gas: 447899)
-FaucetTest:test_drip_beforeTimeout_reverts() (gas: 378888)
-FaucetTest:test_drip_disabledModule_reverts() (gas: 352405)
-FaucetTest:test_drip_emitsEvent_succeeds() (gas: 369165)
-FaucetTest:test_drip_githubSendsCorrectAmount_succeeds() (gas: 366611)
-FaucetTest:test_drip_optimistNftSendsCorrectAmount_succeeds() (gas: 366555)
-FaucetTest:test_drip_preventsReplayAttacks_succeeds() (gas: 369218)
+FaucetTest:test_authAdmin_drip_succeeds() (gas: 366107)
+FaucetTest:test_drip_afterTimeout_succeeds() (gas: 447891)
+FaucetTest:test_drip_beforeTimeout_reverts() (gas: 378884)
+FaucetTest:test_drip_disabledModule_reverts() (gas: 352401)
+FaucetTest:test_drip_emitsEvent_succeeds() (gas: 369161)
+FaucetTest:test_drip_githubSendsCorrectAmount_succeeds() (gas: 366607)
+FaucetTest:test_drip_optimistNftSendsCorrectAmount_succeeds() (gas: 366551)
+FaucetTest:test_drip_preventsReplayAttacks_succeeds() (gas: 369214)
 FaucetTest:test_initialize_succeeds() (gas: 7626)
 FaucetTest:test_nonAdmin_drip_fails() (gas: 262520)
 FaucetTest:test_receive_succeeds() (gas: 17401)

packages/contracts-bedrock/contracts/periphery/faucet/Faucet.sol

@@ -3,32 +3,23 @@ pragma solidity 0.8.15;
 
 import { IFaucetAuthModule } from "./authmodules/IFaucetAuthModule.sol";
 
-/**
- * @title  SafeSend
- * @notice Sends ETH to a recipient account without triggering any code.
- */
+/// @title  SafeSend
+/// @notice Sends ETH to a recipient account without triggering any code.
 contract SafeSend {
-    /**
-     * @param _recipient Account to send ETH to.
-     */
+    /// @param _recipient Account to send ETH to.
     constructor(address payable _recipient) payable {
         selfdestruct(_recipient);
     }
 }
 
-/**
- * @title  Faucet
- * @notice Faucet contract that drips ETH to users.
- */
+/// @title  Faucet
+/// @notice Faucet contract that drips ETH to users.
 contract Faucet {
-    /**
-     * @notice Emitted on each drip.
-     *
-     * @param authModule The type of authentication that was used for verifying the drip.
-     * @param userId     The id of the user that requested the drip.
-     * @param amount     The amount of funds sent.
-     * @param recipient  The recipient of the drip.
-     */
+    /// @notice Emitted on each drip.
+    /// @param authModule The type of authentication that was used for verifying the drip.
+    /// @param userId     The id of the user that requested the drip.
+    /// @param amount     The amount of funds sent.
+    /// @param recipient  The recipient of the drip.
     event Drip(
         string indexed authModule,
         bytes32 indexed userId,
@@ -36,26 +27,20 @@ contract Faucet {
         address indexed recipient
     );
 
-    /**
-     * @notice Parameters for a drip.
-     */
+    /// @notice Parameters for a drip.
     struct DripParameters {
         address payable recipient;
         bytes32 nonce;
     }
 
-    /**
-     * @notice Parameters for authentication.
-     */
+    /// @notice Parameters for authentication.
     struct AuthParameters {
         IFaucetAuthModule module;
         bytes32 id;
         bytes proof;
     }
 
-    /**
-     * @notice Configuration for an authentication module.
-     */
+    /// @notice Configuration for an authentication module.
     struct ModuleConfig {
         string name;
         bool enabled;
@@ -63,74 +48,51 @@ contract Faucet {
         uint256 amount;
     }
 
-    /**
-     * @notice Admin address that can configure the faucet.
-     */
+    /// @notice Admin address that can configure the faucet.
     address public immutable ADMIN;
 
-    /**
-     * @notice Mapping of authentication modules to their configurations.
-     */
+    /// @notice Mapping of authentication modules to their configurations.
     mapping(IFaucetAuthModule => ModuleConfig) public modules;
 
-    /**
-     * @notice Mapping of authentication IDs to the next timestamp at which they can be used.
-     */
+    /// @notice Mapping of authentication IDs to the next timestamp at which they can be used.
     mapping(IFaucetAuthModule => mapping(bytes32 => uint256)) public timeouts;
 
-    /**
-     * @notice Maps from id to nonces to whether or not they have been used.
-     */
+    /// @notice Maps from id to nonces to whether or not they have been used.
     mapping(bytes32 => mapping(bytes32 => bool)) public nonces;
 
-    /**
-     * @notice Modifier that makes a function admin priviledged.
-     */
+    /// @notice Modifier that makes a function admin priviledged.
     modifier priviledged() {
         require(msg.sender == ADMIN, "Faucet: function can only be called by admin");
         _;
     }
 
-    /**
-     * @param _admin Admin address that can configure the faucet.
-     */
+    /// @param _admin Admin address that can configure the faucet.
     constructor(address _admin) {
         ADMIN = _admin;
     }
 
-    /**
-     * @notice Allows users to donate ETH to this contract.
-     */
+    /// @notice Allows users to donate ETH to this contract.
     receive() external payable {
         // Thank you!
     }
 
-    /**
-     * @notice Allows the admin to withdraw funds.
-     *
-     * @param _recipient Address to receive the funds.
-     * @param _amount    Amount of ETH in wei to withdraw.
-     */
+    /// @notice Allows the admin to withdraw funds.
+    /// @param _recipient Address to receive the funds.
+    /// @param _amount    Amount of ETH in wei to withdraw.
     function withdraw(address payable _recipient, uint256 _amount) public priviledged {
         new SafeSend{ value: _amount }(_recipient);
     }
 
-    /**
-     * @notice Allows the admin to configure an authentication module.
-     *
-     * @param _module Authentication module to configure.
-     * @param _config Configuration to set for the module.
-     */
+    /// @notice Allows the admin to configure an authentication module.
+    /// @param _module Authentication module to configure.
+    /// @param _config Configuration to set for the module.
     function configure(IFaucetAuthModule _module, ModuleConfig memory _config) public priviledged {
         modules[_module] = _config;
     }
 
-    /**
-     * @notice Drips ETH to a recipient account.
-     *
-     * @param _params Drip parameters.
-     * @param _auth   Authentication parameters.
-     */
+    /// @notice Drips ETH to a recipient account.
+    /// @param _params Drip parameters.
+    /// @param _auth   Authentication parameters.
     function drip(DripParameters memory _params, AuthParameters memory _auth) public {
         // Grab the module config once.
         ModuleConfig memory config = modules[_auth.module];

packages/contracts-bedrock/contracts/periphery/faucet/authmodules/AdminFaucetAuthModule.sol

@@ -6,41 +6,30 @@ import { SignatureChecker } from "@openzeppelin/contracts/utils/cryptography/Sig
 import { IFaucetAuthModule } from "./IFaucetAuthModule.sol";
 import { Faucet } from "../Faucet.sol";
 
-/**
- * @title  AdminFaucetAuthModule
- * @notice FaucetAuthModule that allows an admin to sign off on a given faucet drip. Takes an admin
- *         as the constructor argument.
- */
+/// @title  AdminFaucetAuthModule
+/// @notice FaucetAuthModule that allows an admin to sign off on a given faucet drip. Takes an admin
+///         as the constructor argument.
 contract AdminFaucetAuthModule is IFaucetAuthModule, EIP712 {
-    /**
-     * @notice Admin address that can sign off on drips.
-     */
+    /// @notice Admin address that can sign off on drips.
     address public immutable ADMIN;
 
-    /**
-     * @notice EIP712 typehash for the Proof type.
-     */
+    /// @notice EIP712 typehash for the Proof type.
     bytes32 public constant PROOF_TYPEHASH =
         keccak256("Proof(address recipient,bytes32 nonce,bytes32 id)");
 
-    /**
-     * @notice Struct that represents a proof that verifies the admin.
-     *
-     * @custom:field recipient Address that will be receiving the faucet funds.
-     * @custom:field nonce     Pseudorandom nonce to prevent replay attacks.
-     * @custom:field id        id for the user requesting the faucet funds.
-     */
+    /// @notice Struct that represents a proof that verifies the admin.
+    /// @custom:field recipient Address that will be receiving the faucet funds.
+    /// @custom:field nonce     Pseudorandom nonce to prevent replay attacks.
+    /// @custom:field id        id for the user requesting the faucet funds.
     struct Proof {
         address recipient;
         bytes32 nonce;
         bytes32 id;
     }
 
-    /**
-     * @param _admin   Admin address that can sign off on drips.
-     * @param _name    Contract name.
-     * @param _version The current major version of the signing domain.
-     */
+    /// @param _admin   Admin address that can sign off on drips.
+    /// @param _name    Contract name.
+    /// @param _version The current major version of the signing domain.
     constructor(
         address _admin,
         string memory _name,
@@ -49,22 +38,19 @@ contract AdminFaucetAuthModule is IFaucetAuthModule, EIP712 {
         ADMIN = _admin;
     }
 
-    /**
-     * @inheritdoc IFaucetAuthModule
-     */
+    /// @inheritdoc IFaucetAuthModule
     function verify(
         Faucet.DripParameters memory _params,
         bytes32 _id,
         bytes memory _proof
-    ) external view returns (bool) {
+    ) external view returns (bool valid_) {
         // Generate a EIP712 typed data hash to compare against the proof.
-        return
-            SignatureChecker.isValidSignatureNow(
-                ADMIN,
-                _hashTypedDataV4(
-                    keccak256(abi.encode(PROOF_TYPEHASH, _params.recipient, _params.nonce, _id))
-                ),
-                _proof
-            );
+        valid_ = SignatureChecker.isValidSignatureNow(
+            ADMIN,
+            _hashTypedDataV4(
+                keccak256(abi.encode(PROOF_TYPEHASH, _params.recipient, _params.nonce, _id))
+            ),
+            _proof
+        );
     }
 }

packages/contracts-bedrock/contracts/periphery/faucet/authmodules/IFaucetAuthModule.sol

@@ -3,18 +3,14 @@ pragma solidity 0.8.15;
 
 import { Faucet } from "../Faucet.sol";
 
-/**
- * @title  IFaucetAuthModule
- * @notice Interface for faucet authentication modules.
- */
+/// @title  IFaucetAuthModule
+/// @notice Interface for faucet authentication modules.
 interface IFaucetAuthModule {
-    /**
-     * @notice Verifies that the given drip parameters are valid.
-     *
-     * @param _params Drip parameters to verify.
-     * @param _id     Authentication ID to verify.
-     * @param _proof  Authentication proof to verify.
-     */
+    /// @notice Verifies that the given drip parameters are valid.
+    /// @param _params Drip parameters to verify.
+    /// @param _id     Authentication ID to verify.
+    /// @param _proof  Authentication proof to verify.
+    /// @return valid_ True if the drip parameters are valid.
     function verify(
         Faucet.DripParameters memory _params,
         bytes32 _id,