Merge remote-tracking branch 'upstream' into refactor/erc721-update-fnPointer

contracts/metatx/ERC2771Forwarder.sol

@@ -20,6 +20,25 @@ import {Address} from "../utils/Address.sol";
  * * `nonce`: A unique transaction ordering identifier to avoid replayability and request invalidation.
  * * `deadline`: A timestamp after which the request is not executable anymore.
  * * `data`: Encoded `msg.data` to send with the requested call.
+ *
+ * Relayers are able to submit batches if they are processing a high volume of requests. With high
+ * throughput, relayers may run into limitations of the chain such as limits on the number of
+ * transactions in the mempool. In these cases the recommendation is to distribute the load among
+ * multiple accounts.
+ *
+ * ==== Security Considerations
+ *
+ * If a relayer submits a forward request, it should be willing to pay up to 100% of the gas amount
+ * specified in the request. This contract does not implement any kind of retribution for this gas,
+ * and it is assumed that there is an out of band incentive for relayers to pay for execution on
+ * behalf of signers. Often, the relayer is operated by a project that will consider it a user
+ * acquisition cost.
+ *
+ * By offering to pay for gas, relayers are at risk of having that gas used by an attacker toward
+ * some other purpose that is not aligned with the expected out of band incentives. If you operate a
+ * relayer, consider whitelisting target contracts and function selectors. When relaying ERC-721 or
+ * ERC-1155 transfers specifically, consider rejecting the use of the `data` field, since it can be
+ * used to execute arbitrary code.
  */
 contract ERC2771Forwarder is EIP712, Nonces {
     using ECDSA for bytes32;

contracts/token/ERC20/utils/SafeERC20.sol

@@ -70,8 +70,8 @@ library SafeERC20 {
 
     /**
      * @dev Set the calling contract's allowance toward `spender` to `value`. If `token` returns no value,
-     * non-reverting calls are assumed to be successful. Compatible with tokens that require the approval to be set to
-     * 0 before setting it to a non-zero value.
+     * non-reverting calls are assumed to be successful. Meant to be used with tokens that require the approval
+     * to be set to zero before setting it to a non-zero value, such as USDT.
      */
     function forceApprove(IERC20 token, address spender, uint256 value) internal {
         bytes memory approvalCall = abi.encodeCall(token.approve, (spender, value));

contracts/utils/structs/BitMaps.sol

@@ -3,8 +3,17 @@
 pragma solidity ^0.8.19;
 
 /**
- * @dev Library for managing uint256 to bool mapping in a compact and efficient way, providing the keys are sequential.
+ * @dev Library for managing uint256 to bool mapping in a compact and efficient way, provided the keys are sequential.
  * Largely inspired by Uniswap's https://github.com/Uniswap/merkle-distributor/blob/master/contracts/MerkleDistributor.sol[merkle-distributor].
+ *
+ * BitMaps pack 256 booleans across each bit of a single 256-bit slot of `uint256` type.
+ * Hence booleans corresponding to 256 _sequential_ indices would only consume a single slot,
+ * unlike the regular `bool` which would consume an entire slot for a single value.
+ *
+ * This results in gas savings in two ways:
+ *
+ * - Setting a zero value to non-zero only once every 256 times
+ * - Accessing the same warm slot for every 256 _sequential_ indices
  */
 library BitMaps {
     struct BitMap {