Release v5.1 updates

.changeset/tricky-bats-pretend.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`ERC1363Utils`: Add helper similar to the existing `ERC721Utils` and `ERC1155Utils`

.solcover.js

@@ -10,4 +10,12 @@ module.exports = {
     fgrep: '[skip-on-coverage]',
     invert: true,
   },
+  // Work around stack too deep for coverage
+  configureYulOptimizer: true,
+  solcOptimizerDetails: {
+    yul: true,
+    yulDetails: {
+      optimizerSteps: '',
+    },
+  },
 };

contracts/access/manager/AccessManager.sol

@@ -97,7 +97,15 @@ contract AccessManager is Context, Multicall, IAccessManager {
         uint32 nonce;
     }
 
+    /**
+     * @dev The identifier of the admin role. Required to perform most configuration operations including
+     * other roles' management and target restrictions.
+     */
     uint64 public constant ADMIN_ROLE = type(uint64).min; // 0
+
+    /**
+     * @dev The identifier of the public role. Automatically granted to all addresses with no delay.
+     */
     uint64 public constant PUBLIC_ROLE = type(uint64).max; // 2**64-1
 
     mapping(address target => TargetConfig mode) private _targets;
@@ -687,7 +695,7 @@ contract AccessManager is Context, Multicall, IAccessManager {
 
         (bool adminRestricted, uint64 roleId, uint32 operationDelay) = _getAdminRestrictions(data);
 
-        // isTragetClosed apply to non-admin-restricted function
+        // isTargetClosed apply to non-admin-restricted function
         if (!adminRestricted && isTargetClosed(address(this))) {
             return (false, 0);
         }

contracts/access/manager/IAccessManager.sol

@@ -3,7 +3,6 @@
 
 pragma solidity ^0.8.20;
 
-import {IAccessManaged} from "./IAccessManaged.sol";
 import {Time} from "../../utils/types/Time.sol";
 
 interface IAccessManager {

contracts/finance/VestingWallet.sol

@@ -37,8 +37,8 @@ contract VestingWallet is Context, Ownable {
     uint64 private immutable _duration;
 
     /**
-     * @dev Sets the sender as the initial owner, the beneficiary as the pending owner, the start timestamp and the
-     * vesting duration of the vesting wallet.
+     * @dev Sets the beneficiary (owner), the start timestamp and the vesting duration (in seconds) of the vesting
+     * wallet.
      */
     constructor(address beneficiary, uint64 startTimestamp, uint64 durationSeconds) payable Ownable(beneficiary) {
         _start = startTimestamp;

contracts/finance/VestingWalletCliff.sol

@@ -7,6 +7,8 @@ import {VestingWallet} from "./VestingWallet.sol";
 
 /**
  * @dev Extension of {VestingWallet} that adds a cliff to the vesting schedule.
+ *
+ * _Available since v5.1._
  */
 abstract contract VestingWalletCliff is VestingWallet {
     using SafeCast for *;
@@ -17,8 +19,8 @@ abstract contract VestingWalletCliff is VestingWallet {
     error InvalidCliffDuration(uint64 cliffSeconds, uint64 durationSeconds);
 
     /**
-     * @dev Sets the sender as the initial owner, the beneficiary as the pending owner, the start timestamp, the
-     * vesting duration and the duration of the cliff of the vesting wallet.
+     * @dev Set the duration of the cliff, in seconds. The cliff starts vesting schedule (see {VestingWallet}'s
+     * constructor) and ends `cliffSeconds` later.
      */
     constructor(uint64 cliffSeconds) {
         if (cliffSeconds > duration()) {

contracts/governance/Governor.sol

@@ -802,7 +802,7 @@ abstract contract Governor is Context, ERC165, EIP712, Nonces, IGovernor, IERC72
      * @dev Try to parse a character from a string as a hex value. Returns `(true, value)` if the char is in
      * `[0-9a-fA-F]` and `(false, 0)` otherwise. Value is guaranteed to be in the range `0 <= value < 16`
      */
-    function _tryHexToUint(bytes1 char) private pure returns (bool, uint8) {
+    function _tryHexToUint(bytes1 char) private pure returns (bool isHex, uint8 value) {
         uint8 c = uint8(char);
         unchecked {
             // Case 0-9

contracts/governance/IGovernor.sol

@@ -8,6 +8,9 @@ import {IERC6372} from "../interfaces/IERC6372.sol";
 
 /**
  * @dev Interface of the {Governor} core.
+ *
+ * NOTE: Event parameters lack the `indexed` keyword for compatibility with GovernorBravo events.
+ * Making event parameters `indexed` affects how events are decoded, potentially breaking existing indexers.
  */
 interface IGovernor is IERC165, IERC6372 {
     enum ProposalState {

contracts/governance/extensions/GovernorCountingFractional.sol

@@ -27,6 +27,8 @@ import {Math} from "../../utils/math/Math.sol";
  * * Voting privately from a shielded pool using zero knowledge proofs.
  *
  * Based on ScopeLift's GovernorCountingFractional[https://github.com/ScopeLift/flexible-voting/blob/e5de2efd1368387b840931f19f3c184c85842761/src/GovernorCountingFractional.sol]
+ *
+ * _Available since v5.1._
  */
 abstract contract GovernorCountingFractional is Governor {
     using Math for *;
@@ -43,7 +45,7 @@ abstract contract GovernorCountingFractional is Governor {
     /**
      * @dev Mapping from proposal ID to vote tallies for that proposal.
      */
-    mapping(uint256 => ProposalVote) private _proposalVotes;
+    mapping(uint256 proposalId => ProposalVote) private _proposalVotes;
 
     /**
      * @dev A fractional vote params uses more votes than are available for that user.
@@ -145,7 +147,7 @@ abstract contract GovernorCountingFractional is Governor {
         uint256 againstVotes = 0;
         uint256 forVotes = 0;
         uint256 abstainVotes = 0;
-        uint256 usedWeight;
+        uint256 usedWeight = 0;
 
         // For clarity of event indexing, fractional voting must be clearly advertised in the "support" field.
         //

contracts/governance/extensions/GovernorStorage.sol

@@ -88,7 +88,12 @@ abstract contract GovernorStorage is Governor {
      */
     function proposalDetails(
         uint256 proposalId
-    ) public view virtual returns (address[] memory, uint256[] memory, bytes[] memory, bytes32) {
+    )
+        public
+        view
+        virtual
+        returns (address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash)
+    {
         // here, using memory is more efficient than storage
         ProposalDetails memory details = _proposalDetails[proposalId];
         if (details.descriptionHash == 0) {
@@ -102,14 +107,19 @@ abstract contract GovernorStorage is Governor {
      */
     function proposalDetailsAt(
         uint256 index
-    ) public view virtual returns (uint256, address[] memory, uint256[] memory, bytes[] memory, bytes32) {
-        uint256 proposalId = _proposalIds[index];
-        (
+    )
+        public
+        view
+        virtual
+        returns (
+            uint256 proposalId,
             address[] memory targets,
             uint256[] memory values,
             bytes[] memory calldatas,
             bytes32 descriptionHash
-        ) = proposalDetails(proposalId);
-        return (proposalId, targets, values, calldatas, descriptionHash);
+        )
+    {
+        proposalId = _proposalIds[index];
+        (targets, values, calldatas, descriptionHash) = proposalDetails(proposalId);
     }
 }

contracts/governance/utils/Votes.sol

@@ -232,7 +232,7 @@ abstract contract Votes is Context, EIP712, Nonces, IERC5805 {
         Checkpoints.Trace208 storage store,
         function(uint208, uint208) view returns (uint208) op,
         uint208 delta
-    ) private returns (uint208, uint208) {
+    ) private returns (uint208 oldValue, uint208 newValue) {
         return store.push(clock(), op(store.latest(), delta));
     }
 

contracts/interfaces/IERC1363Receiver.sol

@@ -18,7 +18,7 @@ interface IERC1363Receiver {
      * (i.e. 0x88a7ca5c, or its own function selector).
      *
      * @param operator The address which called `transferAndCall` or `transferFromAndCall` function.
-     * @param from The address which are tokens transferred from.
+     * @param from The address which the tokens are transferred from.
      * @param value The amount of tokens transferred.
      * @param data Additional data with no specified format.
      * @return `bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))` if transfer is allowed unless throwing.

contracts/interfaces/IERC1363Spender.sol

@@ -4,7 +4,7 @@
 pragma solidity ^0.8.20;
 
 /**
- * @title ERC1363Spender
+ * @title IERC1363Spender
  * @dev Interface for any contract that wants to support `approveAndCall`
  * from ERC-1363 token contracts.
  */

contracts/interfaces/IERC2981.sol

@@ -15,6 +15,9 @@ interface IERC2981 is IERC165 {
     /**
      * @dev Returns how much royalty is owed and to whom, based on a sale price that may be denominated in any unit of
      * exchange. The royalty amount is denominated and should be paid in that same unit of exchange.
+     *
+     * NOTE: ERC-2981 allows setting the royalty to 100% of the price. In that case all the price would be sent to the
+     * royalty receiver and 0 tokens to the seller. Contracts dealing with royalty should consider empty transfers.
      */
     function royaltyInfo(
         uint256 tokenId,

contracts/metatx/ERC2771Forwarder.sol

@@ -218,7 +218,7 @@ contract ERC2771Forwarder is EIP712, Nonces {
      */
     function _recoverForwardRequestSigner(
         ForwardRequestData calldata request
-    ) internal view virtual returns (bool, address) {
+    ) internal view virtual returns (bool isValid, address signer) {
         (address recovered, ECDSA.RecoverError err, ) = _hashTypedDataV4(
             keccak256(
                 abi.encode(
@@ -309,8 +309,7 @@ contract ERC2771Forwarder is EIP712, Nonces {
         bool success;
         uint256 returnSize;
         uint256 returnValue;
-        /// @solidity memory-safe-assembly
-        assembly {
+        assembly ("memory-safe") {
             // Perform the staticcall and save the result in the scratch space.
             // | Location  | Content  | Content (Hex)                                                      |
             // |-----------|----------|--------------------------------------------------------------------|
@@ -362,8 +361,7 @@ contract ERC2771Forwarder is EIP712, Nonces {
             // We explicitly trigger invalid opcode to consume all gas and bubble-up the effects, since
             // neither revert or assert consume all gas since Solidity 0.8.20
             // https://docs.soliditylang.org/en/v0.8.20/control-structures.html#panic-via-assert-and-error-via-require
-            /// @solidity memory-safe-assembly
-            assembly {
+            assembly ("memory-safe") {
                 invalid()
             }
         }

contracts/proxy/Clones.sol

@@ -37,8 +37,7 @@ library Clones {
         if (address(this).balance < value) {
             revert Errors.InsufficientBalance(address(this).balance, value);
         }
-        /// @solidity memory-safe-assembly
-        assembly {
+        assembly ("memory-safe") {
             // Cleans the upper 96 bits of the `implementation` word, then packs the first 3 bytes
             // of the `implementation` address with the bytecode before the address.
             mstore(0x00, or(shr(0xe8, shl(0x60, implementation)), 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000))
@@ -77,8 +76,7 @@ library Clones {
         if (address(this).balance < value) {
             revert Errors.InsufficientBalance(address(this).balance, value);
         }
-        /// @solidity memory-safe-assembly
-        assembly {
+        assembly ("memory-safe") {
             // Cleans the upper 96 bits of the `implementation` word, then packs the first 3 bytes
             // of the `implementation` address with the bytecode before the address.
             mstore(0x00, or(shr(0xe8, shl(0x60, implementation)), 0x3d602d80600a3d3981f3363d3d373d3d3d363d73000000))
@@ -99,8 +97,7 @@ library Clones {
         bytes32 salt,
         address deployer
     ) internal pure returns (address predicted) {
-        /// @solidity memory-safe-assembly
-        assembly {
+        assembly ("memory-safe") {
             let ptr := mload(0x40)
             mstore(add(ptr, 0x38), deployer)
             mstore(add(ptr, 0x24), 0x5af43d82803e903d91602b57fd5bf3ff)

contracts/proxy/ERC1967/ERC1967Utils.sol

@@ -9,7 +9,7 @@ import {Address} from "../../utils/Address.sol";
 import {StorageSlot} from "../../utils/StorageSlot.sol";
 
 /**
- * @dev This abstract contract provides getters and event emitting update functions for
+ * @dev This library provides getters and event emitting update functions for
  * https://eips.ethereum.org/EIPS/eip-1967[ERC-1967] slots.
  */
 library ERC1967Utils {

contracts/proxy/transparent/TransparentUpgradeableProxy.sol

@@ -15,7 +15,8 @@ import {ProxyAdmin} from "./ProxyAdmin.sol";
  * include them in the ABI so this interface must be used to interact with it.
  */
 interface ITransparentUpgradeableProxy is IERC1967 {
-    function upgradeToAndCall(address, bytes calldata) external payable;
+    /// @dev See {UUPSUpgradeable-upgradeToAndCall}
+    function upgradeToAndCall(address newImplementation, bytes calldata data) external payable;
 }
 
 /**

contracts/token/ERC1155/ERC1155.sol

@@ -381,8 +381,7 @@ abstract contract ERC1155 is Context, ERC165, IERC1155, IERC1155MetadataURI, IER
         uint256 element1,
         uint256 element2
     ) private pure returns (uint256[] memory array1, uint256[] memory array2) {
-        /// @solidity memory-safe-assembly
-        assembly {
+        assembly ("memory-safe") {
             // Load the free memory pointer
             array1 := mload(0x40)
             // Set array length to 1

contracts/token/ERC1155/README.adoc

@@ -39,3 +39,5 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 == Utilities
 
 {{ERC1155Holder}}
+
+{{ERC1155Utils}}

contracts/token/ERC1155/utils/ERC1155Utils.sol

@@ -9,13 +9,15 @@ import {IERC1155Errors} from "../../../interfaces/draft-IERC6093.sol";
  * @dev Library that provide common ERC-1155 utility functions.
  *
  * See https://eips.ethereum.org/EIPS/eip-1155[ERC-1155].
+ *
+ * _Available since v5.1._
  */
 library ERC1155Utils {
     /**
      * @dev Performs an acceptance check for the provided `operator` by calling {IERC1155-onERC1155Received}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
-     * The acceptance call is not executed and treated as a no-op if the target address is doesn't contain code (i.e. an EOA).
+     * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
      * Otherwise, the recipient must implement {IERC1155Receiver-onERC1155Received} and return the acceptance magic value to accept
      * the transfer.
      */
@@ -38,8 +40,7 @@ library ERC1155Utils {
                     // non-IERC1155Receiver implementer
                     revert IERC1155Errors.ERC1155InvalidReceiver(to);
                 } else {
-                    /// @solidity memory-safe-assembly
-                    assembly {
+                    assembly ("memory-safe") {
                         revert(add(32, reason), mload(reason))
                     }
                 }
@@ -51,7 +52,7 @@ library ERC1155Utils {
      * @dev Performs a batch acceptance check for the provided `operator` by calling {IERC1155-onERC1155BatchReceived}
      * on the `to` address. The `operator` is generally the address that initiated the token transfer (i.e. `msg.sender`).
      *
-     * The acceptance call is not executed and treated as a no-op if the target address is doesn't contain code (i.e. an EOA).
+     * The acceptance call is not executed and treated as a no-op if the target address doesn't contain code (i.e. an EOA).
      * Otherwise, the recipient must implement {IERC1155Receiver-onERC1155Received} and return the acceptance magic value to accept
      * the transfer.
      */
@@ -76,8 +77,7 @@ library ERC1155Utils {
                     // non-IERC1155Receiver implementer
                     revert IERC1155Errors.ERC1155InvalidReceiver(to);
                 } else {
-                    /// @solidity memory-safe-assembly
-                    assembly {
+                    assembly ("memory-safe") {
                         revert(add(32, reason), mload(reason))
                     }
                 }

contracts/token/ERC20/README.adoc

@@ -71,3 +71,5 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 == Utilities
 
 {{SafeERC20}}
+
+{{ERC1363Utils}}