Merge branch 'develop' into bedrock-go-versions

.changeset/empty-eels-move.md

+---
+'@eth-optimism/contracts-governance': patch
+---
+
+Clean up the hardhat config

.changeset/lucky-parents-deliver.md

+---
+'@eth-optimism/contracts-bedrock': patch
+---
+
+Add comments to RLP libraries

.changeset/rare-trees-whisper.md

+---
+'@eth-optimism/contracts-periphery': patch
+---
+
+Cleaned up natspec for Drippie and its dependencies

packages/contracts-bedrock/contracts/libraries/rlp/RLPReader.sol

@@ -2,41 +2,42 @@
 pragma solidity ^0.8.9;
 
 /**
+ * @custom:attribution https://github.com/hamdiallam/Solidity-RLP
  * @title RLPReader
- * @dev Adapted from "RLPReader" by Hamdi Allam (hamdi.allam97@gmail.com).
+ * @notice RLPReader is a library for parsing RLP-encoded byte arrays into Solidity types. Adapted
+ *         from Solidity-RLP (https://github.com/hamdiallam/Solidity-RLP) by Hamdi Allam with
+ *         various tweaks to improve readability.
  */
 library RLPReader {
-    /*************
-     * Constants *
-     *************/
-
+    /**
+     * @notice Max list length that this library will accept.
+     */
     uint256 internal constant MAX_LIST_LENGTH = 32;
 
-    /*********
-     * Enums *
-     *********/
-
+    /**
+     * @notice RLP item types.
+     *
+     * @custom:value DATA_ITEM Represents an RLP data item (NOT a list).
+     * @custom:value LIST_ITEM Represents an RLP list item.
+     */
     enum RLPItemType {
         DATA_ITEM,
         LIST_ITEM
     }
 
-    /***********
-     * Structs *
-     ***********/
-
+    /**
+     * @notice Struct representing an RLP item.
+     */
     struct RLPItem {
         uint256 length;
         uint256 ptr;
     }
 
-    /**********************
-     * Internal Functions *
-     **********************/
-
     /**
-     * Converts bytes to a reference to memory position and length.
+     * @notice Converts bytes to a reference to memory position and length.
+     *
      * @param _in Input bytes to convert.
+     *
      * @return Output memory reference.
      */
     function toRLPItem(bytes memory _in) internal pure returns (RLPItem memory) {
@@ -49,8 +50,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP list value into a list of RLP items.
+     * @notice Reads an RLP list value into a list of RLP items.
+     *
      * @param _in RLP list value.
+     *
      * @return Decoded RLP list items.
      */
     function readList(RLPItem memory _in) internal pure returns (RLPItem[] memory) {
@@ -88,8 +91,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP list value into a list of RLP items.
+     * @notice Reads an RLP list value into a list of RLP items.
+     *
      * @param _in RLP list value.
+     *
      * @return Decoded RLP list items.
      */
     function readList(bytes memory _in) internal pure returns (RLPItem[] memory) {
@@ -97,8 +102,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes value into bytes.
+     * @notice Reads an RLP bytes value into bytes.
+     *
      * @param _in RLP bytes value.
+     *
      * @return Decoded bytes.
      */
     function readBytes(RLPItem memory _in) internal pure returns (bytes memory) {
@@ -110,8 +117,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes value into bytes.
+     * @notice Reads an RLP bytes value into bytes.
+     *
      * @param _in RLP bytes value.
+     *
      * @return Decoded bytes.
      */
     function readBytes(bytes memory _in) internal pure returns (bytes memory) {
@@ -119,8 +128,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP string value into a string.
+     * @notice Reads an RLP string value into a string.
+     *
      * @param _in RLP string value.
+     *
      * @return Decoded string.
      */
     function readString(RLPItem memory _in) internal pure returns (string memory) {
@@ -128,8 +139,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP string value into a string.
+     * @notice Reads an RLP string value into a string.
+     *
      * @param _in RLP string value.
+     *
      * @return Decoded string.
      */
     function readString(bytes memory _in) internal pure returns (string memory) {
@@ -137,8 +150,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes32 value into a bytes32.
+     * @notice Reads an RLP bytes32 value into a bytes32.
+     *
      * @param _in RLP bytes32 value.
+     *
      * @return Decoded bytes32.
      */
     function readBytes32(RLPItem memory _in) internal pure returns (bytes32) {
@@ -163,8 +178,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bytes32 value into a bytes32.
+     * @notice Reads an RLP bytes32 value into a bytes32.
+     *
      * @param _in RLP bytes32 value.
+     *
      * @return Decoded bytes32.
      */
     function readBytes32(bytes memory _in) internal pure returns (bytes32) {
@@ -172,8 +189,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP uint256 value into a uint256.
+     * @notice Reads an RLP uint256 value into a uint256.
+     *
      * @param _in RLP uint256 value.
+     *
      * @return Decoded uint256.
      */
     function readUint256(RLPItem memory _in) internal pure returns (uint256) {
@@ -181,8 +200,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP uint256 value into a uint256.
+     * @notice Reads an RLP uint256 value into a uint256.
+     *
      * @param _in RLP uint256 value.
+     *
      * @return Decoded uint256.
      */
     function readUint256(bytes memory _in) internal pure returns (uint256) {
@@ -190,8 +211,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bool value into a bool.
+     * @notice Reads an RLP bool value into a bool.
+     *
      * @param _in RLP bool value.
+     *
      * @return Decoded bool.
      */
     function readBool(RLPItem memory _in) internal pure returns (bool) {
@@ -209,8 +232,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP bool value into a bool.
+     * @notice Reads an RLP bool value into a bool.
+     *
      * @param _in RLP bool value.
+     *
      * @return Decoded bool.
      */
     function readBool(bytes memory _in) internal pure returns (bool) {
@@ -218,8 +243,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP address value into a address.
+     * @notice Reads an RLP address value into a address.
+     *
      * @param _in RLP address value.
+     *
      * @return Decoded address.
      */
     function readAddress(RLPItem memory _in) internal pure returns (address) {
@@ -233,8 +260,10 @@ library RLPReader {
     }
 
     /**
-     * Reads an RLP address value into a address.
+     * @notice Reads an RLP address value into a address.
+     *
      * @param _in RLP address value.
+     *
      * @return Decoded address.
      */
     function readAddress(bytes memory _in) internal pure returns (address) {
@@ -242,8 +271,10 @@ library RLPReader {
     }
 
     /**
-     * Reads the raw bytes of an RLP item.
+     * @notice Reads the raw bytes of an RLP item.
+     *
      * @param _in RLP item to read.
+     *
      * @return Raw RLP bytes.
      */
     function readRawBytes(RLPItem memory _in) internal pure returns (bytes memory) {
@@ -255,8 +286,10 @@ library RLPReader {
      *********************/
 
     /**
-     * Decodes the length of an RLP item.
+     * @notice Decodes the length of an RLP item.
+     *
      * @param _in RLP item to decode.
+     *
      * @return Offset of the encoded data.
      * @return Length of the encoded data.
      * @return RLP item type (LIST_ITEM or DATA_ITEM).
@@ -333,10 +366,12 @@ library RLPReader {
     }
 
     /**
-     * Copies the bytes from a memory location.
+     * @notice Copies the bytes from a memory location.
+     *
      * @param _src    Pointer to the location to read from.
      * @param _offset Offset to start reading from.
      * @param _length Number of bytes to read.
+     *
      * @return Copied bytes.
      */
     function _copy(
@@ -378,8 +413,10 @@ library RLPReader {
     }
 
     /**
-     * Copies an RLP item into bytes.
+     * @notice Copies an RLP item into bytes.
+     *
      * @param _in RLP item to copy.
+     *
      * @return Copied bytes.
      */
     function _copy(RLPItem memory _in) private pure returns (bytes memory) {

packages/contracts-bedrock/contracts/libraries/rlp/RLPWriter.sol

@@ -2,17 +2,18 @@
 pragma solidity ^0.8.9;
 
 /**
+ * @custom:attribution https://github.com/bakaoh/solidity-rlp-encode
  * @title RLPWriter
- * @author Bakaoh (with modifications)
+ * @author RLPWriter is a library for encoding Solidity types to RLP bytes. Adapted from Bakaoh's
+ *         RLPEncode library (https://github.com/bakaoh/solidity-rlp-encode) with minor
+ *         modifications to improve legibility.
  */
 library RLPWriter {
-    /**********************
-     * Internal Functions *
-     **********************/
-
     /**
-     * RLP encodes a byte string.
+     * @notice RLP encodes a byte string.
+     *
      * @param _in The byte string to encode.
+     *
      * @return The RLP encoded string in bytes.
      */
     function writeBytes(bytes memory _in) internal pure returns (bytes memory) {
@@ -28,8 +29,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a list of RLP encoded byte byte strings.
+     * @notice RLP encodes a list of RLP encoded byte byte strings.
+     *
      * @param _in The list of RLP encoded byte strings.
+     *
      * @return The RLP encoded list of items in bytes.
      */
     function writeList(bytes[] memory _in) internal pure returns (bytes memory) {
@@ -38,8 +41,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a string.
+     * @notice RLP encodes a string.
+     *
      * @param _in The string to encode.
+     *
      * @return The RLP encoded string in bytes.
      */
     function writeString(string memory _in) internal pure returns (bytes memory) {
@@ -47,8 +52,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes an address.
+     * @notice RLP encodes an address.
+     *
      * @param _in The address to encode.
+     *
      * @return The RLP encoded address in bytes.
      */
     function writeAddress(address _in) internal pure returns (bytes memory) {
@@ -56,8 +63,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a uint.
+     * @notice RLP encodes a uint.
+     *
      * @param _in The uint256 to encode.
+     *
      * @return The RLP encoded uint256 in bytes.
      */
     function writeUint(uint256 _in) internal pure returns (bytes memory) {
@@ -65,8 +74,10 @@ library RLPWriter {
     }
 
     /**
-     * RLP encodes a bool.
+     * @notice RLP encodes a bool.
+     *
      * @param _in The bool to encode.
+     *
      * @return The RLP encoded bool in bytes.
      */
     function writeBool(bool _in) internal pure returns (bytes memory) {
@@ -75,14 +86,12 @@ library RLPWriter {
         return encoded;
     }
 
-    /*********************
-     * Private Functions *
-     *********************/
-
     /**
-     * Encode the first byte, followed by the `len` in binary form if `length` is more than 55.
+     * @notice Encode the first byte and then the `len` in binary form if `length` is more than 55.
+     *
      * @param _len    The length of the string or the payload.
      * @param _offset 128 if item is string, 192 if item is list.
+     *
      * @return RLP encoded bytes.
      */
     function _writeLength(uint256 _len, uint256 _offset) private pure returns (bytes memory) {
@@ -110,9 +119,10 @@ library RLPWriter {
     }
 
     /**
-     * Encode integer in big endian binary form with no leading zeroes.
-     * @notice TODO: This should be optimized with assembly to save gas costs.
+     * @notice Encode integer in big endian binary form with no leading zeroes.
+     *
      * @param _x The integer to encode.
+     *
      * @return RLP encoded bytes.
      */
     function _toBinary(uint256 _x) private pure returns (bytes memory) {
@@ -134,8 +144,9 @@ library RLPWriter {
     }
 
     /**
-     * Copies a piece of memory to another location.
-     * @notice From: https://github.com/Arachnid/solidity-stringutils/blob/master/src/strings.sol.
+     * @custom:attribution https://github.com/Arachnid/solidity-stringutils
+     * @notice Copies a piece of memory to another location.
+     *
      * @param _dest Destination location.
      * @param _src  Source location.
      * @param _len  Length of memory to copy.
@@ -169,9 +180,11 @@ library RLPWriter {
     }
 
     /**
-     * Flattens a list of byte strings into one byte string.
-     * @notice From: https://github.com/sammayo/solidity-rlp-encoder/blob/master/RLPEncode.sol.
+     * @custom:attribution https://github.com/sammayo/solidity-rlp-encoder
+     * @notice Flattens a list of byte strings into one byte string.
+     *
      * @param _list List of byte strings to flatten.
+     *
      * @return The flattened byte string.
      */
     function _flatten(bytes[] memory _list) private pure returns (bytes memory) {

packages/contracts-governance/hardhat.config.ts

 import dotenv from 'dotenv'
+import { HardhatUserConfig } from 'hardhat/config'
 import '@nomiclabs/hardhat-ethers'
 import '@nomiclabs/hardhat-etherscan'
 import '@nomiclabs/hardhat-waffle'
 import 'hardhat-gas-reporter'
 import 'solidity-coverage'
-import { task, types } from 'hardhat/config'
-import { providers, utils, Wallet } from 'ethers'
-import { CrossChainMessenger } from '@eth-optimism/sdk'
-import { getChainId } from '@eth-optimism/core-utils'
 
 import './scripts/deploy-token'
 import './scripts/multi-send'
@@ -17,66 +14,13 @@ import './scripts/create-airdrop-json'
 import './scripts/deploy-distributor'
 import './scripts/test-claims'
 import './scripts/create-distributor-json'
+import './scripts/deposit'
 
 dotenv.config()
 
-task('accounts', 'Prints the list of accounts').setAction(async (args, hre) => {
-  const accounts = await hre.ethers.getSigners()
-
-  for (const account of accounts) {
-    console.log(account.address)
-  }
-})
-
-task('deposit', 'Deposits funds onto Optimism.')
-  .addParam('to', 'Recipient address.', null, types.string)
-  .addParam('amountEth', 'Amount in ETH to send.', null, types.string)
-  .addParam('l1ProviderUrl', '', process.env.L1_PROVIDER_URL, types.string)
-  .addParam('l2ProviderUrl', '', process.env.L2_PROVIDER_URL, types.string)
-  .addParam('privateKey', '', process.env.PRIVATE_KEY, types.string)
-  .setAction(async (args) => {
-    const { to, amountEth, l1ProviderUrl, l2ProviderUrl, privateKey } = args
-    if (!l1ProviderUrl || !l2ProviderUrl || !privateKey) {
-      throw new Error(
-        'You must define --l1-provider-url, --l2-provider-url, --private-key in your environment.'
-      )
-    }
-
-    const l1Provider = new providers.JsonRpcProvider(l1ProviderUrl)
-    const l2Provider = new providers.JsonRpcProvider(l2ProviderUrl)
-    const l1Wallet = new Wallet(privateKey, l1Provider)
-    const messenger = new CrossChainMessenger({
-      l1SignerOrProvider: l1Wallet,
-      l2SignerOrProvider: l2Provider,
-      l1ChainId: await getChainId(l1Provider),
-      l2ChainId: await getChainId(l2Provider),
-    })
-
-    const amountWei = utils.parseEther(amountEth)
-    console.log(`Depositing ${amountEth} ETH to ${to}...`)
-    const tx = await messenger.depositETH(amountWei, {
-      recipient: to,
-    })
-    console.log(`Got TX hash ${tx.hash}. Waiting...`)
-    await tx.wait()
-
-    const l1WalletOnL2 = new Wallet(privateKey, l2Provider)
-    await l1WalletOnL2.sendTransaction({
-      to,
-      value: utils.parseEther(amountEth),
-    })
-
-    const balance = await l2Provider.getBalance(to)
-    console.log('Funded account balance', balance.toString())
-    console.log('Done.')
-  })
-
 const privKey = process.env.PRIVATE_KEY || '0x' + '11'.repeat(32)
 
-/**
- * @type import("hardhat/config").HardhatUserConfig
- */
-module.exports = {
+const config: HardhatUserConfig = {
   solidity: {
     version: '0.8.12',
     settings: {
@@ -91,17 +35,20 @@ module.exports = {
     optimism: {
       chainId: 17,
       url: 'http://localhost:8545',
-      saveDeployments: false,
     },
     'optimism-kovan': {
       chainId: 69,
       url: 'https://kovan.optimism.io',
       accounts: [privKey],
     },
+    'optimism-goerli': {
+      chainId: 420,
+      url: 'https://goerli.optimism.io',
+      accounts: [privKey],
+    },
     'optimism-nightly': {
       chainId: 421,
       url: 'https://goerli-nightly-us-central1-a-sequencer.optimism.io',
-      saveDeployments: true,
       accounts: [privKey],
     },
     'optimism-mainnet': {
@@ -110,8 +57,7 @@ module.exports = {
       accounts: [privKey],
     },
     'hardhat-node': {
-      url: 'http://localhost:9545',
-      saveDeployments: false,
+      url: 'http://localhost:8545',
     },
   },
   gasReporter: {
@@ -122,3 +68,5 @@ module.exports = {
     apiKey: process.env.ETHERSCAN_API_KEY,
   },
 }
+
+export default config

packages/contracts-governance/scripts/deploy-token.ts

@@ -93,6 +93,10 @@ task('deploy-token', 'Deploy governance token and its mint manager contracts')
         console.log(`Got ${tokenReceipt.contractAddress}`)
         throw new Error(`Fatal error! Mismatch of governance token address`)
       }
+    } else if (nonceTokenDeployer !== 0 && governanceTokenCode === '0x') {
+      throw new Error(
+        `Nonce is ${nonceTokenDeployer} without governance token deployed`
+      )
     } else {
       console.log(
         `GovernanceToken already deployed at ${addresses.governanceToken}, skipping`

packages/contracts-governance/scripts/deposit.ts

+import { task, types } from 'hardhat/config'
+import { providers, utils, Wallet } from 'ethers'
+import { CrossChainMessenger } from '@eth-optimism/sdk'
+import { getChainId } from '@eth-optimism/core-utils'
+
+task('deposit', 'Deposits funds onto Optimism.')
+  .addParam('to', 'Recipient address.', null, types.string)
+  .addParam('amountEth', 'Amount in ETH to send.', null, types.string)
+  .addParam('l1ProviderUrl', '', process.env.L1_PROVIDER_URL, types.string)
+  .addParam('l2ProviderUrl', '', process.env.L2_PROVIDER_URL, types.string)
+  .addParam('privateKey', '', process.env.PRIVATE_KEY, types.string)
+  .setAction(async (args) => {
+    const { to, amountEth, l1ProviderUrl, l2ProviderUrl, privateKey } = args
+    if (!l1ProviderUrl || !l2ProviderUrl || !privateKey) {
+      throw new Error(
+        'You must define --l1-provider-url, --l2-provider-url, --private-key in your environment.'
+      )
+    }
+
+    const l1Provider = new providers.JsonRpcProvider(l1ProviderUrl)
+    const l2Provider = new providers.JsonRpcProvider(l2ProviderUrl)
+    const l1Wallet = new Wallet(privateKey, l1Provider)
+    const messenger = new CrossChainMessenger({
+      l1SignerOrProvider: l1Wallet,
+      l2SignerOrProvider: l2Provider,
+      l1ChainId: await getChainId(l1Provider),
+      l2ChainId: await getChainId(l2Provider),
+    })
+
+    const amountWei = utils.parseEther(amountEth)
+    console.log(`Depositing ${amountEth} ETH to ${to}...`)
+    const tx = await messenger.depositETH(amountWei, {
+      recipient: to,
+    })
+    console.log(`Got TX hash ${tx.hash}. Waiting...`)
+    await tx.wait()
+
+    const l1WalletOnL2 = new Wallet(privateKey, l2Provider)
+    await l1WalletOnL2.sendTransaction({
+      to,
+      value: utils.parseEther(amountEth),
+    })
+
+    const balance = await l2Provider.getBalance(to)
+    console.log('Funded account balance', balance.toString())
+    console.log('Done.')
+  })

packages/contracts-periphery/contracts/universal/AssetReceiver.sol

@@ -12,17 +12,28 @@ import { Transactor } from "./Transactor.sol";
  */
 contract AssetReceiver is Transactor {
     /**
-     * Emitted when ETH is received by this address.
+     * @notice Emitted when ETH is received by this address.
+     *
+     * @param from Address that sent ETH to this contract.
      */
     event ReceivedETH(address indexed from, uint256 amount);
 
     /**
-     * Emitted when ETH is withdrawn from this address.
+     * @notice Emitted when ETH is withdrawn from this address.
+     *
+     * @param withdrawer Address that triggered the withdrawal.
+     * @param recipient  Address that received the withdrawal.
+     * @param amount     ETH amount withdrawn.
      */
     event WithdrewETH(address indexed withdrawer, address indexed recipient, uint256 amount);
 
     /**
-     * Emitted when ERC20 tokens are withdrawn from this address.
+     * @notice Emitted when ERC20 tokens are withdrawn from this address.
+     *
+     * @param withdrawer Address that triggered the withdrawal.
+     * @param recipient  Address that received the withdrawal.
+     * @param asset      Address of the token being withdrawn.
+     * @param amount     ERC20 amount withdrawn.
      */
     event WithdrewERC20(
         address indexed withdrawer,
@@ -32,7 +43,12 @@ contract AssetReceiver is Transactor {
     );
 
     /**
-     * Emitted when ERC721 tokens are withdrawn from this address.
+     * @notice Emitted when ERC20 tokens are withdrawn from this address.
+     *
+     * @param withdrawer Address that triggered the withdrawal.
+     * @param recipient  Address that received the withdrawal.
+     * @param asset      Address of the token being withdrawn.
+     * @param id         Token ID being withdrawn.
      */
     event WithdrewERC721(
         address indexed withdrawer,
@@ -47,14 +63,14 @@ contract AssetReceiver is Transactor {
     constructor(address _owner) Transactor(_owner) {}
 
     /**
-     * Make sure we can receive ETH.
+     * @notice Make sure we can receive ETH.
      */
     receive() external payable {
         emit ReceivedETH(msg.sender, msg.value);
     }
 
     /**
-     * Withdraws full ETH balance to the recipient.
+     * @notice Withdraws full ETH balance to the recipient.
      *
      * @param _to Address to receive the ETH balance.
      */
@@ -63,7 +79,7 @@ contract AssetReceiver is Transactor {
     }
 
     /**
-     * Withdraws partial ETH balance to the recipient.
+     * @notice Withdraws partial ETH balance to the recipient.
      *
      * @param _to     Address to receive the ETH balance.
      * @param _amount Amount of ETH to withdraw.
@@ -75,7 +91,7 @@ contract AssetReceiver is Transactor {
     }
 
     /**
-     * Withdraws full ERC20 balance to the recipient.
+     * @notice Withdraws full ERC20 balance to the recipient.
      *
      * @param _asset ERC20 token to withdraw.
      * @param _to    Address to receive the ERC20 balance.
@@ -85,7 +101,7 @@ contract AssetReceiver is Transactor {
     }
 
     /**
-     * Withdraws partial ERC20 balance to the recipient.
+     * @notice Withdraws partial ERC20 balance to the recipient.
      *
      * @param _asset  ERC20 token to withdraw.
      * @param _to     Address to receive the ERC20 balance.
@@ -103,7 +119,7 @@ contract AssetReceiver is Transactor {
     }
 
     /**
-     * Withdraws ERC721 token to the recipient.
+     * @notice Withdraws ERC721 token to the recipient.
      *
      * @param _asset ERC721 token to withdraw.
      * @param _to    Address to receive the ERC721 token.

packages/contracts-periphery/contracts/universal/Transactor.sol

@@ -20,6 +20,7 @@ contract Transactor is Owned {
      * @param _data   Data to send with the call.
      * @param _gas    Amount of gas to send with the call.
      * @param _value  ETH value to send with the call.
+     *
      * @return Boolean success value.
      * @return Bytes data returned by the call.
      */
@@ -38,6 +39,7 @@ contract Transactor is Owned {
      * @param _target Address to call.
      * @param _data   Data to send with the call.
      * @param _gas    Amount of gas to send with the call.
+     *
      * @return Boolean success value.
      * @return Bytes data returned by the call.
      */

packages/contracts-periphery/contracts/universal/drippie/Drippie.sol

@@ -7,17 +7,23 @@ import { IDripCheck } from "./IDripCheck.sol";
 /**
  * @title Drippie
  * @notice Drippie is a system for managing automated contract interactions. A specific interaction
- * is called a "drip" and can be executed according to some condition (called a dripcheck) and an
- * execution interval. Drips cannot be executed faster than the execution interval. Drips can
- * trigger arbitrary contract calls where the calling contract is this contract address. Drips can
- * also send ETH value, which makes them ideal for keeping addresses sufficiently funded with ETH.
- * Drippie is designed to be connected with smart contract automation services so that drips can be
- * executed automatically. However, Drippie is specifically designed to be separated from these
- * services so that trust assumptions are better compartmentalized.
+ *         is called a "drip" and can be executed according to some condition (called a dripcheck)
+ *         and an execution interval. Drips cannot be executed faster than the execution interval.
+ *         Drips can trigger arbitrary contract calls where the calling contract is this contract
+ *         address. Drips can also send ETH value, which makes them ideal for keeping addresses
+ *         sufficiently funded with ETH. Drippie is designed to be connected with smart contract
+ *         automation services so that drips can be executed automatically. However, Drippie is
+ *         specifically designed to be separated from these services so that trust assumptions are
+ *         better compartmentalized.
  */
 contract Drippie is AssetReceiver {
     /**
-     * Enum representing different status options for a given drip.
+     * @notice Enum representing different status options for a given drip.
+     *
+     * @custom:value NONE     Drip does not exist.
+     * @custom:value ACTIVE   Drip is active and can be executed.
+     * @custom:value PAUSED   Drip is paused and cannot be executed until reactivated.
+     * @custom:value ARCHIVED Drip is archived and can no longer be executed or reactivated.
      */
     enum DripStatus {
         NONE,
@@ -27,7 +33,7 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Represents a drip action.
+     * @notice Represents a drip action.
      */
     struct DripAction {
         address payable target;
@@ -36,7 +42,7 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Represents the configuration for a given drip.
+     * @notice Represents the configuration for a given drip.
      */
     struct DripConfig {
         uint256 interval;
@@ -46,7 +52,7 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Represents the state of an active drip.
+     * @notice Represents the state of an active drip.
      */
     struct DripState {
         DripStatus status;
@@ -56,7 +62,11 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Emitted when a new drip is created.
+     * @notice Emitted when a new drip is created.
+     *
+     * @param nameref Indexed name parameter (hashed).
+     * @param name    Unindexed name parameter (unhashed).
+     * @param config  Config for the created drip.
      */
     event DripCreated(
         // Emit name twice because indexed version is hashed.
@@ -66,7 +76,11 @@ contract Drippie is AssetReceiver {
     );
 
     /**
-     * Emitted when a drip status is updated.
+     * @notice Emitted when a drip status is updated.
+     *
+     * @param nameref Indexed name parameter (hashed).
+     * @param name    Unindexed name parameter (unhashed).
+     * @param status  New drip status.
      */
     event DripStatusUpdated(
         // Emit name twice because indexed version is hashed.
@@ -76,7 +90,12 @@ contract Drippie is AssetReceiver {
     );
 
     /**
-     * Emitted when a drip is executed.
+     * @notice Emitted when a drip is executed.
+     *
+     * @param nameref   Indexed name parameter (hashed).
+     * @param name      Unindexed name parameter (unhashed).
+     * @param executor  Address that executed the drip.
+     * @param timestamp Time when the drip was executed.
      */
     event DripExecuted(
         // Emit name twice because indexed version is hashed.
@@ -87,7 +106,7 @@ contract Drippie is AssetReceiver {
     );
 
     /**
-     * Maps from drip names to drip states.
+     * @notice Maps from drip names to drip states.
      */
     mapping(string => DripState) public drips;
 
@@ -97,9 +116,9 @@ contract Drippie is AssetReceiver {
     constructor(address _owner) AssetReceiver(_owner) {}
 
     /**
-     * Creates a new drip with the given name and configuration. Once created, drips cannot be
-     * modified in any way (this is a security measure). If you want to update a drip, simply pause
-     * (and potentially archive) the existing drip and create a new one.
+     * @notice Creates a new drip with the given name and configuration. Once created, drips cannot
+     *         be modified in any way (this is a security measure). If you want to update a drip,
+     *         simply pause (and potentially archive) the existing drip and create a new one.
      *
      * @param _name   Name of the drip.
      * @param _config Configuration for the drip.
@@ -130,9 +149,10 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Sets the status for a given drip. The behavior of this function depends on the status that
-     * the user is trying to set. A drip can always move between ACTIVE and PAUSED, but it can
-     * never move back to NONE and once ARCHIVED, it can never move back to ACTIVE or PAUSED.
+     * @notice Sets the status for a given drip. The behavior of this function depends on the
+     *         status that the user is trying to set. A drip can always move between ACTIVE and
+     *         PAUSED, but it can never move back to NONE and once ARCHIVED, it can never move back
+     *         to ACTIVE or PAUSED.
      *
      * @param _name   Name of the drip to update.
      * @param _status New drip status.
@@ -184,9 +204,10 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Checks if a given drip is executable.
+     * @notice Checks if a given drip is executable.
      *
      * @param _name Drip to check.
+     *
      * @return True if the drip is executable, false otherwise.
      */
     function executable(string memory _name) public view returns (bool) {
@@ -219,12 +240,12 @@ contract Drippie is AssetReceiver {
     }
 
     /**
-     * Triggers a drip. This function is deliberately left as a public function because the
-     * assumption being made here is that setting the drip to ACTIVE is an affirmative signal that
-     * the drip should be executable according to the drip parameters, drip check, and drip
-     * interval. Note that drip parameters are read entirely from the state and are not supplied as
-     * user input, so there should not be any way for a non-authorized user to influence the
-     * behavior of the drip.
+     * @notice Triggers a drip. This function is deliberately left as a public function because the
+     *         assumption being made here is that setting the drip to ACTIVE is an affirmative
+     *         signal that the drip should be executable according to the drip parameters, drip
+     *         check, and drip interval. Note that drip parameters are read entirely from the state
+     *         and are not supplied as user input, so there should not be any way for a
+     *         non-authorized user to influence the behavior of the drip.
      *
      * @param _name Name of the drip to trigger.
      */