Release v5.0.1 (#4785)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+
+## 5.0.1 (2023-12-07)
+
+- `ERC2771Context` and `Context`: Introduce a `_contextPrefixLength()` getter, used to trim extra information appended to `msg.data`.
+- `Multicall`: Make aware of non-canonical context (i.e. `msg.sender` is not `_msgSender()`), allowing compatibility with `ERC2771Context`.
+
 ## 5.0.0 (2023-10-05)
 
 ### Additions Summary
@@ -7,9 +13,9 @@
 The following contracts and libraries were added:
 
 - `AccessManager`: A consolidated system for managing access control in complex systems.
-	- `AccessManaged`: A module for connecting a contract to an authority in charge of its access control.
-	- `GovernorTimelockAccess`:  An adapter for time-locking governance proposals using an `AccessManager`.
-	- `AuthorityUtils`: A library of utilities for interacting with authority contracts.
+  - `AccessManaged`: A module for connecting a contract to an authority in charge of its access control.
+  - `GovernorTimelockAccess`: An adapter for time-locking governance proposals using an `AccessManager`.
+  - `AuthorityUtils`: A library of utilities for interacting with authority contracts.
 - `GovernorStorage`: A Governor module that stores proposal details in storage.
 - `ERC2771Forwarder`: An ERC2771 forwarder for meta transactions.
 - `ERC1967Utils`: A library with ERC1967 events, errors and getters.
@@ -127,7 +133,7 @@ These removals were implemented in the following PRs: [#3637](https://github.com
 - `ERC1155`: Removed check for address zero in `balanceOf`. ([#4263](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4263))
 - `ERC1155`: Optimized array accesses by skipping bounds checking when unnecessary. ([#4300](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4300))
 - `ERC1155`: Bubble errors triggered in the `onERC1155Received` and `onERC1155BatchReceived` hooks. ([#4314](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4314))
-- `ERC1155Supply`: Added a `totalSupply()` function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2**256-1 . ([#3962](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3962))
+- `ERC1155Supply`: Added a `totalSupply()` function that returns the total amount of token circulating, this change will restrict the total tokens minted across all ids to 2\*\*256-1 . ([#3962](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3962))
 - `ERC1155Receiver`: Removed in favor of `ERC1155Holder`. ([#4450](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/4450))
 
 #### Utils
@@ -180,6 +186,10 @@ In this logic of removing hidden SLOADs, the `_isApprovedOrOwner` function was r
 
 The `_exists` function was removed. Calls to this function can be replaced by `_ownerOf(tokenId) != address(0)`.
 
+#### More about ERC1155
+
+Batch transfers will now emit `TransferSingle` if the batch consists of a single token, while in previous versions the `TransferBatch` event would be used for all transfers initiated through `safeBatchTransferFrom`. Both behaviors are compliant with the ERC-1155 specification.
+
 #### ERC165Storage
 
 Users that were registering EIP-165 interfaces with `_registerInterface` from `ERC165Storage` should instead do so so by overriding the `supportsInterface` function as seen below:
@@ -190,6 +200,27 @@ function supportsInterface(bytes4 interfaceId) public view virtual override retu
 }
 ```
 
+#### SafeMath
+
+Methods in SafeMath superseded by native overflow checks in Solidity 0.8.0 were removed along with operations providing an interface for revert strings. The remaining methods were moved to `utils/Math.sol`.
+
+```diff
+- import "@openzeppelin/contracts/utils/math/SafeMath.sol";
++ import "@openzeppelin/contracts/utils/math/Math.sol";
+
+ function tryOperations(uint256 x, uint256 y) external view {
+-  (bool overflowsAdd, uint256 resultAdd) = SafeMath.tryAdd(x, y);
++  (bool overflowsAdd, uint256 resultAdd) = Math.tryAdd(x, y);
+-  (bool overflowsSub, uint256 resultSub) = SafeMath.trySub(x, y);
++  (bool overflowsSub, uint256 resultSub) = Math.trySub(x, y);
+-  (bool overflowsMul, uint256 resultMul) = SafeMath.tryMul(x, y);
++  (bool overflowsMul, uint256 resultMul) = Math.tryMul(x, y);
+-  (bool overflowsDiv, uint256 resultDiv) = SafeMath.tryDiv(x, y);
++  (bool overflowsDiv, uint256 resultDiv) = Math.tryDiv(x, y);
+   // ...
+ }
+```
+
 #### Adapting Governor modules
 
 Custom Governor modules that override internal functions may require modifications if migrated to v5. In particular, the new internal functions `_queueOperations` and `_executeOperations` may need to be used. If assistance with this migration is needed reach out via the [OpenZeppelin Support Forum](https://forum.openzeppelin.com/c/support/contracts/18).

contracts/metatx/ERC2771Context.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Contracts (last updated v5.0.0) (metatx/ERC2771Context.sol)
+// OpenZeppelin Contracts (last updated v5.0.1) (metatx/ERC2771Context.sol)
 
 pragma solidity ^0.8.20;
 
@@ -13,6 +13,10 @@ import {Context} from "../utils/Context.sol";
  * specification adding the address size in bytes (20) to the calldata size. An example of an unexpected
  * behavior could be an unintended fallback (or another function) invocation while trying to invoke the `receive`
  * function only accessible if `msg.data.length == 0`.
+ *
+ * WARNING: The usage of `delegatecall` in this contract is dangerous and may result in context corruption.
+ * Any forwarded request to this contract triggering a `delegatecall` to itself will result in an invalid {_msgSender}
+ * recovery.
  */
 abstract contract ERC2771Context is Context {
     /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
@@ -48,13 +52,11 @@ abstract contract ERC2771Context is Context {
      * a call is not performed by the trusted forwarder or the calldata length is less than
      * 20 bytes (an address length).
      */
-    function _msgSender() internal view virtual override returns (address sender) {
-        if (isTrustedForwarder(msg.sender) && msg.data.length >= 20) {
-            // The assembly code is more direct than the Solidity version using `abi.decode`.
-            /// @solidity memory-safe-assembly
-            assembly {
-                sender := shr(96, calldataload(sub(calldatasize(), 20)))
-            }
+    function _msgSender() internal view virtual override returns (address) {
+        uint256 calldataLength = msg.data.length;
+        uint256 contextSuffixLength = _contextSuffixLength();
+        if (isTrustedForwarder(msg.sender) && calldataLength >= contextSuffixLength) {
+            return address(bytes20(msg.data[calldataLength - contextSuffixLength:]));
         } else {
             return super._msgSender();
         }
@@ -66,10 +68,19 @@ abstract contract ERC2771Context is Context {
      * 20 bytes (an address length).
      */
     function _msgData() internal view virtual override returns (bytes calldata) {
-        if (isTrustedForwarder(msg.sender) && msg.data.length >= 20) {
-            return msg.data[:msg.data.length - 20];
+        uint256 calldataLength = msg.data.length;
+        uint256 contextSuffixLength = _contextSuffixLength();
+        if (isTrustedForwarder(msg.sender) && calldataLength >= contextSuffixLength) {
+            return msg.data[:calldataLength - contextSuffixLength];
         } else {
             return super._msgData();
         }
     }
+
+    /**
+     * @dev ERC-2771 specifies the context as being a single address (20 bytes).
+     */
+    function _contextSuffixLength() internal view virtual override returns (uint256) {
+        return 20;
+    }
 }

contracts/mocks/ERC2771ContextMock.sol

@@ -4,10 +4,11 @@ pragma solidity ^0.8.20;
 
 import {ContextMock} from "./ContextMock.sol";
 import {Context} from "../utils/Context.sol";
+import {Multicall} from "../utils/Multicall.sol";
 import {ERC2771Context} from "../metatx/ERC2771Context.sol";
 
 // By inheriting from ERC2771Context, Context's internal functions are overridden automatically
-contract ERC2771ContextMock is ContextMock, ERC2771Context {
+contract ERC2771ContextMock is ContextMock, ERC2771Context, Multicall {
     /// @custom:oz-upgrades-unsafe-allow constructor
     constructor(address trustedForwarder) ERC2771Context(trustedForwarder) {
         emit Sender(_msgSender()); // _msgSender() should be accessible during construction
@@ -20,4 +21,8 @@ contract ERC2771ContextMock is ContextMock, ERC2771Context {
     function _msgData() internal view override(Context, ERC2771Context) returns (bytes calldata) {
         return ERC2771Context._msgData();
     }
+
+    function _contextSuffixLength() internal view override(Context, ERC2771Context) returns (uint256) {
+        return ERC2771Context._contextSuffixLength();
+    }
 }

contracts/mocks/docs/access-control/AccessControlERC20MintBase.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControl} from "../../../access/AccessControl.sol";
+import {ERC20} from "../../../token/ERC20/ERC20.sol";
+
+contract AccessControlERC20MintBase is ERC20, AccessControl {
+    // Create a new role identifier for the minter role
+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+
+    error CallerNotMinter(address caller);
+
+    constructor(address minter) ERC20("MyToken", "TKN") {
+        // Grant the minter role to a specified account
+        _grantRole(MINTER_ROLE, minter);
+    }
+
+    function mint(address to, uint256 amount) public {
+        // Check that the calling account has the minter role
+        if (!hasRole(MINTER_ROLE, msg.sender)) {
+            revert CallerNotMinter(msg.sender);
+        }
+        _mint(to, amount);
+    }
+}

contracts/mocks/docs/access-control/AccessControlERC20MintMissing.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControl} from "../../../access/AccessControl.sol";
+import {ERC20} from "../../../token/ERC20/ERC20.sol";
+
+contract AccessControlERC20MintMissing is ERC20, AccessControl {
+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
+
+    constructor() ERC20("MyToken", "TKN") {
+        // Grant the contract deployer the default admin role: it will be able
+        // to grant and revoke any roles
+        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
+    }
+
+    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
+        _mint(to, amount);
+    }
+
+    function burn(address from, uint256 amount) public onlyRole(BURNER_ROLE) {
+        _burn(from, amount);
+    }
+}

contracts/mocks/docs/access-control/AccessControlERC20MintOnlyRole.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessControl} from "../../../access/AccessControl.sol";
+import {ERC20} from "../../../token/ERC20/ERC20.sol";
+
+contract AccessControlERC20Mint is ERC20, AccessControl {
+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
+
+    constructor(address minter, address burner) ERC20("MyToken", "TKN") {
+        _grantRole(MINTER_ROLE, minter);
+        _grantRole(BURNER_ROLE, burner);
+    }
+
+    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
+        _mint(to, amount);
+    }
+
+    function burn(address from, uint256 amount) public onlyRole(BURNER_ROLE) {
+        _burn(from, amount);
+    }
+}

contracts/mocks/docs/access-control/AccessManagedERC20MintBase.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {AccessManaged} from "../../../access/manager/AccessManaged.sol";
+import {ERC20} from "../../../token/ERC20/ERC20.sol";
+
+contract AccessManagedERC20Mint is ERC20, AccessManaged {
+    constructor(address manager) ERC20("MyToken", "TKN") AccessManaged(manager) {}
+
+    // Minting is restricted according to the manager rules for this function.
+    // The function is identified by its selector: 0x40c10f19.
+    // Calculated with bytes4(keccak256('mint(address,uint256)'))
+    function mint(address to, uint256 amount) public restricted {
+        _mint(to, amount);
+    }
+}

contracts/mocks/docs/access-control/MyContractOwnable.sol

@@ -2,7 +2,7 @@
 
 pragma solidity ^0.8.20;
 
-import {Ownable} from "../../access/Ownable.sol";
+import {Ownable} from "../../../access/Ownable.sol";
 
 contract MyContract is Ownable {
     constructor(address initialOwner) Ownable(initialOwner) {}

contracts/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openzeppelin/contracts",
   "description": "Secure Smart Contract library for Solidity",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "files": [
     "**/*.sol",
     "/build/contracts/*.json",

contracts/token/ERC1155/IERC1155.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Contracts (last updated v5.0.0) (token/ERC1155/IERC1155.sol)
+// OpenZeppelin Contracts (last updated v5.0.1) (token/ERC1155/IERC1155.sol)
 
 pragma solidity ^0.8.20;
 
@@ -104,13 +104,12 @@ interface IERC1155 is IERC165 {
     /**
      * @dev xref:ROOT:erc1155.adoc#batch-operations[Batched] version of {safeTransferFrom}.
      *
-     *
      * WARNING: This function can potentially allow a reentrancy attack when transferring tokens
      * to an untrusted contract, when invoking {onERC1155BatchReceived} on the receiver.
      * Ensure to follow the checks-effects-interactions pattern and consider employing
      * reentrancy guards when interacting with untrusted contracts.
      *
-     * Emits a {TransferBatch} event.
+     * Emits either a {TransferSingle} or a {TransferBatch} event, depending on the length of the array arguments.
      *
      * Requirements:
      *

contracts/utils/Context.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Contracts (last updated v5.0.0) (utils/Context.sol)
+// OpenZeppelin Contracts (last updated v5.0.1) (utils/Context.sol)
 
 pragma solidity ^0.8.20;
 
@@ -21,4 +21,8 @@ abstract contract Context {
     function _msgData() internal view virtual returns (bytes calldata) {
         return msg.data;
     }
+
+    function _contextSuffixLength() internal view virtual returns (uint256) {
+        return 0;
+    }
 }

contracts/utils/Multicall.sol

@@ -1,22 +1,36 @@
 // SPDX-License-Identifier: MIT
-// OpenZeppelin Contracts (last updated v5.0.0) (utils/Multicall.sol)
+// OpenZeppelin Contracts (last updated v5.0.1) (utils/Multicall.sol)
 
 pragma solidity ^0.8.20;
 
 import {Address} from "./Address.sol";
+import {Context} from "./Context.sol";
 
 /**
  * @dev Provides a function to batch together multiple calls in a single external call.
+ *
+ * Consider any assumption about calldata validation performed by the sender may be violated if it's not especially
+ * careful about sending transactions invoking {multicall}. For example, a relay address that filters function
+ * selectors won't filter calls nested within a {multicall} operation.
+ *
+ * NOTE: Since 5.0.1 and 4.9.4, this contract identifies non-canonical contexts (i.e. `msg.sender` is not {_msgSender}).
+ * If a non-canonical context is identified, the following self `delegatecall` appends the last bytes of `msg.data`
+ * to the subcall. This makes it safe to use with {ERC2771Context}. Contexts that don't affect the resolution of
+ * {_msgSender} are not propagated to subcalls.
  */
-abstract contract Multicall {
+abstract contract Multicall is Context {
     /**
      * @dev Receives and executes a batch of function calls on this contract.
      * @custom:oz-upgrades-unsafe-allow-reachable delegatecall
      */
     function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results) {
+        bytes memory context = msg.sender == _msgSender()
+            ? new bytes(0)
+            : msg.data[msg.data.length - _contextSuffixLength():];
+
         results = new bytes[](data.length);
         for (uint256 i = 0; i < data.length; i++) {
-            results[i] = Address.functionDelegateCall(address(this), data[i]);
+            results[i] = Address.functionDelegateCall(address(this), bytes.concat(data[i], context));
         }
         return results;
     }

docs/modules/ROOT/pages/access-control.adoc

@@ -10,10 +10,10 @@ The most common and basic form of access control is the concept of _ownership_:
 OpenZeppelin Contracts provides xref:api:access.adoc#Ownable[`Ownable`] for implementing ownership in your contracts.
 
 ```solidity
-include::api:example$MyContractOwnable.sol[]
+include::api:example$access-control/MyContractOwnable.sol[]
 ```
 
-By default, the xref:api:access.adoc#Ownable-owner--[`owner`] of an `Ownable` contract is the account that deployed it, which is usually exactly what you want.
+At deployment, the xref:api:access.adoc#Ownable-owner--[`owner`] of an `Ownable` contract is set to the provided `initialOwner` parameter.
 
 Ownable also lets you:
 
@@ -41,32 +41,11 @@ Most software uses access control systems that are role-based: some users are re
 OpenZeppelin Contracts provides xref:api:access.adoc#AccessControl[`AccessControl`] for implementing role-based access control. Its usage is straightforward: for each role that you want to define,
 you will create a new _role identifier_ that is used to grant, revoke, and check if an account has that role.
 
-Here's a simple example of using `AccessControl` in an xref:tokens.adoc#ERC20[`ERC20` token] to define a 'minter' role, which allows accounts that have it create new tokens:
+Here's a simple example of using `AccessControl` in an xref:erc20.adoc[`ERC20` token] to define a 'minter' role, which allows accounts that have it create new tokens:
 
 [source,solidity]
 ----
-// contracts/MyToken.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.20;
-
-import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
-import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-
-contract MyToken is ERC20, AccessControl {
-    // Create a new role identifier for the minter role
-    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
-
-    constructor(address minter) ERC20("MyToken", "TKN") {
-        // Grant the minter role to a specified account
-        _grantRole(MINTER_ROLE, minter);
-    }
-
-    function mint(address to, uint256 amount) public {
-        // Check that the calling account has the minter role
-        require(hasRole(MINTER_ROLE, msg.sender), "Caller is not a minter");
-        _mint(to, amount);
-    }
-}
+include::api:example$access-control/AccessControlERC20MintBase.sol[]
 ----
 
 NOTE: Make sure you fully understand how xref:api:access.adoc#AccessControl[`AccessControl`] works before using it on your system, or copy-pasting the examples from this guide.
@@ -77,30 +56,7 @@ Let's augment our ERC20 token example by also defining a 'burner' role, which le
 
 [source,solidity]
 ----
-// contracts/MyToken.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.20;
-
-import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
-import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-
-contract MyToken is ERC20, AccessControl {
-    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
-    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
-
-    constructor(address minter, address burner) ERC20("MyToken", "TKN") {
-        _grantRole(MINTER_ROLE, minter);
-        _grantRole(BURNER_ROLE, burner);
-    }
-
-    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
-        _mint(to, amount);
-    }
-
-    function burn(address from, uint256 amount) public onlyRole(BURNER_ROLE) {
-        _burn(from, amount);
-    }
-}
+include::api:example$access-control/AccessControlERC20MintOnlyRole.sol[]
 ----
 
 So clean! By splitting concerns this way, more granular levels of permission may be implemented than were possible with the simpler _ownership_ approach to access control. Limiting what each component of a system is able to do is known as the https://en.wikipedia.org/wiki/Principle_of_least_privilege[principle of least privilege], and is a good security practice. Note that each account may still have more than one role, if so desired.
@@ -122,31 +78,7 @@ Let's take a look at the ERC20 token example, this time taking advantage of the
 
 [source,solidity]
 ----
-// contracts/MyToken.sol
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.20;
-
-import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
-import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
-
-contract MyToken is ERC20, AccessControl {
-    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
-    bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE");
-
-    constructor() ERC20("MyToken", "TKN") {
-        // Grant the contract deployer the default admin role: it will be able
-        // to grant and revoke any roles
-        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
-    }
-
-    function mint(address to, uint256 amount) public onlyRole(MINTER_ROLE) {
-        _mint(to, amount);
-    }
-
-    function burn(address from, uint256 amount) public onlyRole(BURNER_ROLE) {
-        _burn(from, amount);
-    }
-}
+include::api:example$access-control/AccessControlERC20MintMissing.sol[]
 ----
 
 Note that, unlike the previous examples, no accounts are granted the 'minter' or 'burner' roles. However, because those roles' admin role is the default admin role, and _that_ role was granted to `msg.sender`, that same account can call `grantRole` to give minting or burning permission, and `revokeRole` to remove it.
@@ -202,3 +134,153 @@ TIP: A recommended configuration is to grant both roles to a secure governance c
 Operations executed by the xref:api:governance.adoc#TimelockController[`TimelockController`] are not subject to a fixed delay but rather a minimum delay. Some major updates might call for a longer delay. For example, if a delay of just a few days might be sufficient for users to audit a minting operation, it makes sense to use a delay of a few weeks, or even a few months, when scheduling a smart contract upgrade.
 
 The minimum delay (accessible through the xref:api:governance.adoc#TimelockController-getMinDelay--[`getMinDelay`] method) can be updated by calling the xref:api:governance.adoc#TimelockController-updateDelay-uint256-[`updateDelay`] function. Bear in mind that access to this function is only accessible by the timelock itself, meaning this maintenance operation has to go through the timelock itself.
+
+[[access-management]]
+== Access Management
+
+For a system of contracts, better integrated role management can be achieved with an xref:api:access.adoc#AccessManager[`AccessManager`] instance. Instead of managing each contract's permission separately, AccessManager stores all the permissions in a single contract, making your protocol easier to audit and maintain.
+
+Although xref:api:access.adoc#AccessControl[`AccessControl`] offers a more dynamic solution for adding permissions to your contracts than Ownable, decentralized protocols tend to become more complex after integrating new contract instances and requires you to keep track of permissions separately in each contract. This increases the complexity of permissions management and monitoring across the system.
+
+image::access-control-multiple.svg[Access Control multiple]
+
+Protocols managing permissions in production systems often require more integrated alternatives to fragmented permissions through multiple `AccessControl` instances.
+
+image::access-manager.svg[AccessManager]
+
+The AccessManager is designed around the concept of role and target functions:
+
+* Roles are granted to accounts (addresses) following a many-to-many approach for flexibility. This means that each user can have one or multiple roles and multiple users can have the same role.
+* Access to a restricted target function is limited to one role. A target function is defined by one https://docs.soliditylang.org/en/v0.8.20/abi-spec.html#function-selector[function selector] on one contract (called target). 
+
+For a call to be authorized, the caller must bear the role that is assigned to the current target function (contract address + function selector).
+
+image::access-manager-functions.svg[AccessManager functions]
+
+=== Using `AccessManager`
+
+OpenZeppelin Contracts provides xref:api:access.adoc#AccessManager[`AccessManager`] for managing roles across any number of contracts. The `AccessManager` itself is a contract that can be deployed and used out of the box. It sets an initial admin in the constructor who will be allowed to perform management operations.
+
+In order to restrict access to some functions of your contract, you should inherit from the xref:api:access.adoc#AccessManaged[`AccessManaged`] contract provided along with the manager. This provides the `restricted` modifier that can be used to protect any externally facing function. Note that you will have to specify the address of the AccessManager instance (xref:api:access.adoc#AccessManaged-constructor-address-[`initialAuthority`]) in the constructor so the `restricted` modifier knows which manager to use for checking permissions.
+
+Here's a simple example of an xref:tokens.adoc#ERC20[`ERC20` token] that defines a `mint` function that is restricted by an xref:api:access.adoc#AccessManager[`AccessManager`]:
+
+```solidity
+include::api:example$access-control/AccessManagedERC20MintBase.sol[]
+```
+
+NOTE: Make sure you fully understand how xref:api:access.adoc#AccessManager[`AccessManager`] works before using it or copy-pasting the examples from this guide.
+
+Once the managed contract has been deployed, it is now under the manager's control. The initial admin can then assign the minter role to an address and also allow the role to call the `mint` function. For example, this is demonstrated in the following Javascript code using Ethers.js:
+
+```javascript
+// const target = ...;
+// const user = ...;
+const MINTER = 42n; // Roles are uint64 (0 is reserved for the ADMIN_ROLE)
+
+// Grant the minter role with no execution delay
+await manager.grantRole(MINTER, user, 0);
+
+// Allow the minter role to call the function selector
+// corresponding to the mint function
+await manager.setTargetFunctionRole(
+    target,
+    ['0x40c10f19'], // bytes4(keccak256('mint(address,uint256)'))
+    MINTER
+);
+```
+
+Even though each role has its own list of function permissions, each role member (`address`) has an execution delay that will dictate how long the account should wait to execute a function that requires its role. Delayed operations must have the xref:api:access.adoc#AccessManager-schedule-address-bytes-uint48-[`schedule`] function called on them first in the AccessManager before they can be executed, either by calling to the target function or using the AccessManager's xref:api:access.adoc#AccessManager-execute-address-bytes-[`execute`] function.
+
+Additionally, roles can have a granting delay that prevents adding members immediately. The AccessManager admins can set this grant delay as follows:
+
+```javascript
+const HOUR = 60 * 60;
+
+const GRANT_DELAY = 24 * HOUR;
+const EXECUTION_DELAY = 5 * HOUR;
+const ACCOUNT = "0x...";
+    
+await manager.connect(initialAdmin).setGrantDelay(MINTER, GRANT_DELAY);
+
+// The role will go into effect after the GRANT_DELAY passes
+await manager.connect(initialAdmin).grantRole(MINTER, ACCOUNT, EXECUTION_DELAY); 
+```
+
+Note that roles do not define a name. As opposed to the xref:api:access.adoc#AccessControl[`AccessControl`] case, roles are identified as numeric values instead of being hardcoded in the contract as `bytes32` values. It is still possible to allow for tooling discovery (e.g. for role exploration) using role labeling with the xref:api:access.adoc#AccessManager-labelRole-uint64-string-[`labelRole`] function.
+
+```javascript
+await manager.labelRole(MINTER, "MINTER");
+```
+
+Given the admins of the `AccessManaged` can modify all of its permissions, it's recommended to keep only a single admin address secured under a multisig or governance layer. To achieve this, it is possible for the initial admin to set up all the required permissions, targets, and functions, assign a new admin, and finally renounce its admin role.
+
+For improved incident response coordination, the manager includes a mode where administrators can completely close a target contract. When closed, all calls to restricted target functions in a target contract will revert.
+
+Closing and opening contracts don't alter any of their settings, neither permissions nor delays. Particularly, the roles required for calling specific target functions are not modified.
+
+This mode is useful for incident response operations that require temporarily shutting down a contract in order to evaluate emergencies and reconfigure permissions.
+
+```javascript
+const target = await myToken.getAddress();
+
+// Token's `restricted` functions closed
+await manager.setTargetClosed(target, true);
+
+// Token's `restricted` functions open
+await manager.setTargetClosed(target, false);
+```
+
+WARNING: Even if an `AccessManager` defines permissions for a target function, these won't be applied if the managed contract instance is not using the xref:api:access.adoc#AccessManaged-restricted--[`restricted`] modifier for that function, or if its manager is a different one.
+
+=== Role Admins and Guardians
+
+An important aspect of the AccessControl contract is that roles aren't granted nor revoked by role members. Instead, it relies on the concept of a role admin for granting and revoking.
+
+In the case of the `AccessManager`, the same rule applies and only the role's admins are able to call xref:api:access.adoc#AccessManager-grantRole-uint64-address-uint32-[grant] and xref:api:access.adoc#AccessManager-revokeRole-uint64-address-[revoke] functions. Note that calling these functions will be subject to the execution delay that the executing role admin has.
+
+Additionally, the `AccessManager` stores a _guardian_ as an extra protection for each role. This guardian has the ability to cancel operations that have been scheduled by any role member with an execution delay. Consider that a role will have its initial admin and guardian default to the `ADMIN_ROLE` (`0`).
+
+IMPORTANT: Be careful with the members of `ADMIN_ROLE`, since it acts as the default admin and guardian for every role. A misbehaved guardian can cancel operations at will, affecting the AccessManager's operation.
+
+=== Manager configuration
+
+The `AccessManager` provides a built-in interface for configuring permission settings that can be accessed by its `ADMIN_ROLE` members.
+
+This configuration interface includes the following functions:
+
+* Add a label to a role using the xref:api:access.adoc#AccessManager-labelRole-uint64-string-[`labelRole`] function.
+* Assign the admin and guardian of a role with xref:api:access.adoc#AccessManager-setRoleAdmin-uint64-uint64-[`setRoleAdmin`] and xref:api:access.adoc#AccessManager-setRoleGuardian-uint64-uint64-[`setRoleGuardian`].
+* Set each role's grant delay via xref:api:access.adoc#AccessManager-setGrantDelay-uint64-uint32-[`setGrantDelay`].
+
+As an admin, some actions will require a delay. Similar to each member's execution delay, some admin operations require waiting for execution and should follow the xref:api:access.adoc#AccessManager-schedule-address-bytes-uint48-[`schedule`] and xref:api:access.adoc#AccessManager-execute-address-bytes-[`execute`] workflow.
+
+More specifically, these delayed functions are those for configuring the settings of a specific target contract. The delay applied to these functions can be adjusted by the manager admins with xref:api:access.adoc#AccessManager-setTargetAdminDelay-address-uint32-[`setTargetAdminDelay`].
+
+The delayed admin actions are:
+
+* Updating an `AccessManaged` contract xref:api:access.adoc#AccessManaged-authority--[authority] using xref:api:access.adoc#AccessManager-updateAuthority-address-address-[`updateAuthority`].
+* Closing or opening a target via xref:api:access.adoc#AccessManager-setTargetClosed-address-bool-[`setTargetClosed`].
+* Changing permissions of whether a role can call a target function with xref:api:access.adoc#AccessManager-setTargetFunctionRole-address-bytes4---uint64-[`setTargetFunctionRole`].
+
+=== Using with Ownable
+
+Contracts already inheriting from xref:api:access.adoc#Ownable[`Ownable`] can migrate to AccessManager by transferring ownership to the manager. After that, all calls to functions with the `onlyOwner` modifier should be called through the manager's xref:api:access.adoc#AccessManager-execute-address-bytes-[`execute`] function, even if the caller doesn't require a delay.
+
+```javascript
+await ownable.connect(owner).transferOwnership(accessManager);
+```
+
+=== Using with AccessControl
+
+For systems already using xref:api:access.adoc#AccessControl[`AccessControl`], the `DEFAULT_ADMIN_ROLE` can be granted to the `AccessManager` after revoking every other role. Subsequent calls should be made through the manager's xref:api:access.adoc#AccessManager-execute-address-bytes-[`execute`] method, similar to the Ownable case.
+
+```javascript
+// Revoke old roles
+await accessControl.connect(admin).revokeRoke(MINTER_ROLE, account);
+
+// Grant the admin role to the access manager
+await accessControl.connect(admin).grantRole(DEFAULT_ADMIN_ROLE, accessManager);
+
+await accessControl.connect(admin).renounceRole(DEFAULT_ADMIN_ROLE, admin);
+```

docs/modules/ROOT/pages/utilities.adoc

@@ -71,29 +71,45 @@ contract MyContract {
 [[math]]
 == Math
 
-The most popular math related library OpenZeppelin Contracts provides is xref:api:utils.adoc#SafeMath[`SafeMath`], which provides mathematical functions that protect your contract from overflows and underflows.
+Although Solidity already provides math operators (i.e. `+`, `-`, etc.), Contracts includes xref:api:utils.adoc#Math[`Math`]; a set of utilities for dealing with mathematical operators, with support for extra operations (eg. xref:api:utils.adoc#Math-average-uint256-uint256-[`average`]) and xref:api:utils.adoc#SignedMath[`SignedMath`]; a library specialized in signed math operations.
 
-Include the contract with `using SafeMath for uint256;` and then call the functions:
+Include these contracts with `using Math for uint256` or `using SignedMath for int256` and then use their functions in your code:
 
-* `myNumber.add(otherNumber)`
-* `myNumber.sub(otherNumber)`
-* `myNumber.div(otherNumber)`
-* `myNumber.mul(otherNumber)`
-* `myNumber.mod(otherNumber)`
+[source,solidity]
+----
+contract MyContract {
+    using Math for uint256;
+    using SignedMath for int256;
+
+    function tryOperations(uint256 a, uint256 b) internal pure {
+        (bool overflowsAdd, uint256 resultAdd) = x.tryAdd(y);
+        (bool overflowsSub, uint256 resultSub) = x.trySub(y);
+        (bool overflowsMul, uint256 resultMul) = x.tryMul(y);
+        (bool overflowsDiv, uint256 resultDiv) = x.tryDiv(y);
+        // ...
+    }
+
+    function unsignedAverage(int256 a, int256 b) {
+        int256 avg = a.average(b);
+        // ...
+    }
+}
+----
 
 Easy!
 
-[[payment]]
-== Payment
+[[structures]]
+== Structures
 
-Want to split some payments between multiple people? Maybe you have an app that sends 30% of art purchases to the original creator and 70% of the profits to the current owner; you can build that with xref:api:finance.adoc#PaymentSplitter[`PaymentSplitter`]!
+Some use cases require more powerful data structures than arrays and mappings offered natively in Solidity. Contracts provides these libraries for enhanced data structure management:
 
-In Solidity, there are some security concerns with blindly sending money to accounts, since it allows them to execute arbitrary code. You can read up on these security concerns in the https://consensys.github.io/smart-contract-best-practices/[Ethereum Smart Contract Best Practices] website.
+- xref:api:utils.adoc#BitMaps[`BitMaps`]: Store packed booleans in storage.
+- xref:api:utils.adoc#Checkpoints[`Checkpoints`]: Checkpoint values with built-in lookups.
+- xref:api:utils.adoc#DoubleEndedQueue[`DoubleEndedQueue`]: Store items in a queue with `pop()` and `queue()` constant time operations.
+- xref:api:utils.adoc#EnumerableSet[`EnumerableSet`]: A https://en.wikipedia.org/wiki/Set_(abstract_data_type)[set] with enumeration capabilities.
+- xref:api:utils.adoc#EnumerableMap[`EnumerableMap`]: A `mapping` variant with enumeration capabilities.
 
-[[collections]]
-== Collections
-
-If you need support for more powerful collections than Solidity's native arrays and mappings, take a look at xref:api:utils.adoc#EnumerableSet[`EnumerableSet`] and xref:api:utils.adoc#EnumerableMap[`EnumerableMap`]. They are similar to mappings in that they store and remove elements in constant time and don't allow for repeated entries, but they also support _enumeration_, which means you can easily query all stored entries both on and off-chain.
+The `Enumerable*` structures are similar to mappings in that they store and remove elements in constant time and don't allow for repeated entries, but they also support _enumeration_, which means you can easily query all stored entries both on and off-chain.
 
 [[misc]]
 == Misc

package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzeppelin-solidity",
   "description": "Secure Smart Contract library for Solidity",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "private": true,
   "files": [
     "/contracts/**/*.sol",

test/metatx/ERC2771Context.test.js

@@ -13,7 +13,7 @@ const ContextMockCaller = artifacts.require('ContextMockCaller');
 const { shouldBehaveLikeRegularContext } = require('../utils/Context.behavior');
 
 contract('ERC2771Context', function (accounts) {
-  const [, trustedForwarder] = accounts;
+  const [, trustedForwarder, other] = accounts;
 
   beforeEach(async function () {
     this.forwarder = await ERC2771Forwarder.new('ERC2771Forwarder');
@@ -131,4 +131,58 @@ contract('ERC2771Context', function (accounts) {
       await expectEvent(receipt, 'DataShort', { data });
     });
   });
+
+  it('multicall poison attack', async function () {
+    const attacker = Wallet.generate();
+    const attackerAddress = attacker.getChecksumAddressString();
+    const nonce = await this.forwarder.nonces(attackerAddress);
+
+    const msgSenderCall = web3.eth.abi.encodeFunctionCall(
+      {
+        name: 'msgSender',
+        type: 'function',
+        inputs: [],
+      },
+      [],
+    );
+
+    const data = web3.eth.abi.encodeFunctionCall(
+      {
+        name: 'multicall',
+        type: 'function',
+        inputs: [
+          {
+            internalType: 'bytes[]',
+            name: 'data',
+            type: 'bytes[]',
+          },
+        ],
+      },
+      [[web3.utils.encodePacked({ value: msgSenderCall, type: 'bytes' }, { value: other, type: 'address' })]],
+    );
+
+    const req = {
+      from: attackerAddress,
+      to: this.recipient.address,
+      value: '0',
+      gas: '100000',
+      data,
+      nonce: Number(nonce),
+      deadline: MAX_UINT48,
+    };
+
+    req.signature = await ethSigUtil.signTypedMessage(attacker.getPrivateKey(), {
+      data: {
+        types: this.types,
+        domain: this.domain,
+        primaryType: 'ForwardRequest',
+        message: req,
+      },
+    });
+
+    expect(await this.forwarder.verify(req)).to.equal(true);
+
+    const receipt = await this.forwarder.execute(req);
+    await expectEvent.inTransaction(receipt.tx, ERC2771ContextMock, 'Sender', { sender: attackerAddress });
+  });
 });