Merge pull request #5595 from ethereum-optimism/harry/faucet-contracts

feat(contracts-periphery): create Faucet contract

packages/contracts-periphery/contracts/foundry-tests/AdminFaucetAuthModule.t.sol

+//SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import { Test } from "forge-std/Test.sol";
+import { AdminFaucetAuthModule } from "../universal/faucet/authmodules/AdminFaucetAuthModule.sol";
+import { Faucet } from "../universal/faucet/Faucet.sol";
+import { FaucetHelper } from "../testing/helpers/FaucetHelper.sol";
+
+/**
+ * @title  AdminFaucetAuthModuleTest
+ * @notice Tests the AdminFaucetAuthModule contract.
+ */
+contract AdminFaucetAuthModuleTest is Test {
+    /**
+     * @notice The admin of the `AdminFaucetAuthModule` contract.
+     */
+    address internal admin;
+    /**
+     * @notice Private key of the `admin`.
+     */
+    uint256 internal adminKey;
+    /**
+     * @notice Not an admin of the `AdminFaucetAuthModule` contract.
+     */
+    address internal nonAdmin;
+    /**
+     * @notice Private key of the `nonAdmin`.
+     */
+    uint256 internal nonAdminKey;
+    /**
+     * @notice An instance of the `AdminFaucetAuthModule` contract.
+     */
+    AdminFaucetAuthModule internal adminFam;
+    /**
+     * @notice An instance of the `FaucetHelper` contract.
+     */
+    FaucetHelper internal faucetHelper;
+    string internal adminFamName = "AdminFAM";
+    string internal adminFamVersion = "1";
+
+    /**
+     * @notice Deploy the `AdminFaucetAuthModule` contract.
+     */
+    function setUp() external {
+        adminKey = 0xB0B0B0B0;
+        admin = vm.addr(adminKey);
+
+        nonAdminKey = 0xC0C0C0C0;
+        nonAdmin = vm.addr(nonAdminKey);
+
+        adminFam = new AdminFaucetAuthModule(admin, adminFamName, adminFamVersion);
+
+        faucetHelper = new FaucetHelper();
+    }
+
+    /**
+     * @notice Get signature as a bytes blob.
+     *
+     */
+    function _getSignature(uint256 _signingPrivateKey, bytes32 _digest)
+        internal
+        pure
+        returns (bytes memory)
+    {
+        (uint8 v, bytes32 r, bytes32 s) = vm.sign(_signingPrivateKey, _digest);
+
+        bytes memory signature = abi.encodePacked(r, s, v);
+        return signature;
+    }
+
+    /**
+     * @notice Signs a proof with the given private key and returns the signature using
+     *         the given EIP712 domain separator. This assumes that the issuer's address is the
+     *         corresponding public key to _issuerPrivateKey.
+     */
+    function issueProofWithEIP712Domain(
+        uint256 _issuerPrivateKey,
+        bytes memory _eip712Name,
+        bytes memory _contractVersion,
+        uint256 _eip712Chainid,
+        address _eip712VerifyingContract,
+        address recipient,
+        bytes memory id,
+        bytes32 nonce
+    ) internal view returns (bytes memory) {
+        AdminFaucetAuthModule.Proof memory proof = AdminFaucetAuthModule.Proof(
+            recipient,
+            nonce,
+            id
+        );
+        return
+            _getSignature(
+                _issuerPrivateKey,
+                faucetHelper.getDigestWithEIP712Domain(
+                    proof,
+                    _eip712Name,
+                    _contractVersion,
+                    _eip712Chainid,
+                    _eip712VerifyingContract
+                )
+            );
+    }
+
+    /**
+     * @notice assert that verify returns true for valid proofs signed by admins.
+     */
+    function test_adminProof_verify_returnsTrue() external {
+        bytes32 nonce = faucetHelper.consumeNonce();
+        address fundsReceiver = makeAddr("fundsReceiver");
+        bytes memory proof = issueProofWithEIP712Domain(
+            adminKey,
+            bytes(adminFamName),
+            bytes(adminFamVersion),
+            block.chainid,
+            address(adminFam),
+            fundsReceiver,
+            abi.encodePacked(fundsReceiver),
+            nonce
+        );
+
+        vm.prank(nonAdmin);
+        assertEq(
+            adminFam.verify(
+                Faucet.DripParameters(payable(fundsReceiver), nonce),
+                abi.encodePacked(fundsReceiver),
+                proof
+            ),
+            true
+        );
+    }
+
+    /**
+     * @notice assert that verify returns false for proofs signed by nonadmins.
+     */
+    function test_nonAdminProof_verify_returnsFalse() external {
+        bytes32 nonce = faucetHelper.consumeNonce();
+        address fundsReceiver = makeAddr("fundsReceiver");
+        bytes memory proof = issueProofWithEIP712Domain(
+            nonAdminKey,
+            bytes(adminFamName),
+            bytes(adminFamVersion),
+            block.chainid,
+            address(adminFam),
+            fundsReceiver,
+            abi.encodePacked(fundsReceiver),
+            nonce
+        );
+
+        vm.prank(admin);
+        assertEq(
+            adminFam.verify(
+                Faucet.DripParameters(payable(fundsReceiver), nonce),
+                abi.encodePacked(fundsReceiver),
+                proof
+            ),
+            false
+        );
+    }
+
+    /**
+     * @notice assert that verify returns false for proofs where the id in the proof is different
+     * than the id in the call to verify.
+     */
+    function test_proofWithWrongId_verify_returnsFalse() external {
+        bytes32 nonce = faucetHelper.consumeNonce();
+        address fundsReceiver = makeAddr("fundsReceiver");
+        address randomAddress = makeAddr("randomAddress");
+        bytes memory proof = issueProofWithEIP712Domain(
+            adminKey,
+            bytes(adminFamName),
+            bytes(adminFamVersion),
+            block.chainid,
+            address(adminFam),
+            fundsReceiver,
+            abi.encodePacked(fundsReceiver),
+            nonce
+        );
+
+        vm.prank(admin);
+        assertEq(
+            adminFam.verify(
+                Faucet.DripParameters(payable(fundsReceiver), nonce),
+                abi.encodePacked(randomAddress),
+                proof
+            ),
+            false
+        );
+    }
+}

packages/contracts-periphery/contracts/testing/helpers/FaucetHelper.sol

+//SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import {
+    AdminFaucetAuthModule
+} from "../../universal/faucet/authmodules/AdminFaucetAuthModule.sol";
+import {
+    ECDSAUpgradeable
+} from "@openzeppelin/contracts-upgradeable/utils/cryptography/ECDSAUpgradeable.sol";
+
+/**
+ * Simple helper contract that helps with testing the Faucet contract.
+ */
+contract FaucetHelper {
+    /**
+     * @notice EIP712 typehash for the Proof type.
+     */
+    bytes32 public constant PROOF_TYPEHASH =
+        keccak256("Proof(address recipient,bytes32 nonce,bytes id)");
+
+    /**
+     * @notice EIP712 typehash for the EIP712Domain type that is included as part of the signature.
+     */
+    bytes32 public constant EIP712_DOMAIN_TYPEHASH =
+        keccak256(
+            "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+        );
+
+    /**
+     * @notice Keeps track of current nonce to generate new nonces for each drip.
+     */
+    uint256 public currentNonce;
+
+    /**
+     * @notice Returns a bytes32 nonce that should change everytime. In practice, people should use
+     *         pseudorandom nonces.
+     *
+     * @return Nonce that should be used as part of drip parameters.
+     */
+    function consumeNonce() public returns (bytes32) {
+        return bytes32(keccak256(abi.encode(currentNonce++)));
+    }
+
+    /**
+     * @notice Returns the hash of the struct Proof.
+     *
+     * @param _proof Proof struct to hash.
+     *
+     * @return EIP-712 typed struct hash.
+     */
+    function getProofStructHash(AdminFaucetAuthModule.Proof memory _proof)
+        public
+        pure
+        returns (bytes32)
+    {
+        return keccak256(abi.encode(PROOF_TYPEHASH, _proof.recipient, _proof.nonce, _proof.id));
+    }
+
+    /**
+     * @notice Computes the EIP712 digest with the given domain parameters.
+     *         Used for testing that different domain parameters fail.
+     *
+     * @param _proof             Proof struct to hash.
+     * @param _name              Contract name to use in the EIP712 domain.
+     * @param _version           Contract version to use in the EIP712 domain.
+     * @param _chainid           Chain ID to use in the EIP712 domain.
+     * @param _verifyingContract Address to use in the EIP712 domain.
+     * @param _verifyingContract Address to use in the EIP712 domain.
+     * @param _verifyingContract Address to use in the EIP712 domain.
+     *
+     * @return EIP-712 compatible digest.
+     */
+    function getDigestWithEIP712Domain(
+        AdminFaucetAuthModule.Proof memory _proof,
+        bytes memory _name,
+        bytes memory _version,
+        uint256 _chainid,
+        address _verifyingContract
+    ) public pure returns (bytes32) {
+        bytes32 domainSeparator = keccak256(
+            abi.encode(
+                EIP712_DOMAIN_TYPEHASH,
+                keccak256(_name),
+                keccak256(_version),
+                _chainid,
+                _verifyingContract
+            )
+        );
+        return ECDSAUpgradeable.toTypedDataHash(domainSeparator, getProofStructHash(_proof));
+    }
+}

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

+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import { IFaucetAuthModule } from "./authmodules/IFaucetAuthModule.sol";
+
+/**
+ * @title  SafeSend
+ * @notice Sends ETH to a recipient account without triggering any code.
+ */
+contract SafeSend {
+    /**
+     * @param _recipient Account to send ETH to.
+     */
+    constructor(address payable _recipient) payable {
+        selfdestruct(_recipient);
+    }
+}
+
+/**
+ * @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.
+     */
+    event Drip(
+        string indexed authModule,
+        bytes indexed userId,
+        uint256 amount,
+        address indexed recipient
+    );
+
+    /**
+     * @notice Parameters for a drip.
+     */
+    struct DripParameters {
+        address payable recipient;
+        bytes32 nonce;
+    }
+
+    /**
+     * @notice Parameters for authentication.
+     */
+    struct AuthParameters {
+        IFaucetAuthModule module;
+        bytes id;
+        bytes proof;
+    }
+
+    /**
+     * @notice Configuration for an authentication module.
+     */
+    struct ModuleConfig {
+        string name;
+        bool enabled;
+        uint256 ttl;
+        uint256 amount;
+    }
+
+    /**
+     * @notice Admin address that can configure the faucet.
+     */
+    address public immutable ADMIN;
+
+    /**
+     * @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.
+     */
+    mapping(IFaucetAuthModule => mapping(bytes => uint256)) public timeouts;
+
+    /**
+     * @notice Maps from id to nonces to whether or not they have been used.
+     */
+    mapping(bytes => mapping(bytes32 => bool)) public nonces;
+
+    /**
+     * @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.
+     */
+    constructor(address _admin) {
+        ADMIN = _admin;
+    }
+
+    /**
+     * @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.
+     */
+    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.
+     */
+    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.
+     */
+    function drip(DripParameters memory _params, AuthParameters memory _auth) public {
+        // Grab the module config once.
+        ModuleConfig memory config = modules[_auth.module];
+
+        // Make sure we're using a supported security module.
+        require(config.enabled, "Faucet: provided auth module is not supported by this faucet");
+
+        // The issuer's signature commits to a nonce to prevent replay attacks.
+        // This checks that the nonce has not been used for this issuer before. The nonces are
+        // scoped to the issuer address, so the same nonce can be used by different issuers without
+        // clashing.
+        require(nonces[_auth.id][_params.nonce] == false, "Faucet: nonce has already been used");
+
+        // Make sure the timeout has elapsed.
+        require(
+            timeouts[_auth.module][_auth.id] < block.timestamp,
+            "Faucet: auth cannot be used yet because timeout has not elapsed"
+        );
+
+        // Verify the proof.
+        require(
+            _auth.module.verify(_params, _auth.id, _auth.proof),
+            "Faucet: drip parameters could not be verified by security module"
+        );
+
+        // Set the next timestamp at which this auth id can be used.
+        timeouts[_auth.module][_auth.id] = block.timestamp + config.ttl;
+
+        // Mark the nonce as used.
+        nonces[_auth.id][_params.nonce] = true;
+
+        // Execute a safe transfer of ETH to the recipient account.
+        new SafeSend{ value: config.amount }(_params.recipient);
+
+        emit Drip(config.name, _auth.id, config.amount, _params.recipient);
+    }
+}

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

+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import { EIP712 } from "@openzeppelin/contracts/utils/cryptography/draft-EIP712.sol";
+import { SignatureChecker } from "@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol";
+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.
+ */
+contract AdminFaucetAuthModule is IFaucetAuthModule, EIP712 {
+    /**
+     * @notice Admin address that can sign off on drips.
+     */
+    address public immutable ADMIN;
+
+    /**
+     * @notice EIP712 typehash for the Proof type.
+     */
+    bytes32 public constant PROOF_TYPEHASH =
+        keccak256("Proof(address recipient,bytes32 nonce,bytes 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.
+     */
+    struct Proof {
+        address recipient;
+        bytes32 nonce;
+        bytes 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.
+     */
+    constructor(
+        address _admin,
+        string memory _name,
+        string memory _version
+    ) EIP712(_name, _version) {
+        ADMIN = _admin;
+    }
+
+    /**
+     * @inheritdoc IFaucetAuthModule
+     */
+    function verify(
+        Faucet.DripParameters memory _params,
+        bytes memory _id,
+        bytes memory _proof
+    ) external view returns (bool) {
+        // 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
+            );
+    }
+}

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

+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.15;
+
+import { Faucet } from "../Faucet.sol";
+
+/**
+ * @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.
+     */
+    function verify(
+        Faucet.DripParameters memory _params,
+        bytes memory _id,
+        bytes memory _proof
+    ) external view returns (bool);
+}