Add ERC-20 Encumber Extension (ERC-7246)

contracts/interfaces/README.adoc

@@ -46,6 +46,7 @@ are useful to interact with third party contracts that implement them.
 - {IERC6909ContentURI}
 - {IERC6909Metadata}
 - {IERC6909TokenSupply}
+- {IERC7246}
 - {IERC7579Module}
 - {IERC7579Validator}
 - {IERC7579Hook}
@@ -113,6 +114,8 @@ are useful to interact with third party contracts that implement them.
 
 {{IERC6909TokenSupply}}
 
+{{IERC7246}}
+
 {{IERC7579Module}}
 
 {{IERC7579Validator}}

contracts/interfaces/draft-IERC7246.sol

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity >=0.6.2;
+
+import {IERC20} from "./IERC20.sol";
+
+interface IERC7246 is IERC20 {
+    /// @dev Emitted when `amount` tokens are encumbered from `owner` to `spender`.
+    event Encumber(address indexed owner, address indexed spender, uint256 amount);
+
+    /// @dev Emitted when the encumbrance of a `spender` to an `owner` is reduced by `amount`.
+    event Release(address indexed owner, address indexed spender, uint256 amount);
+
+    /**
+     * @dev Returns the total amount of tokens owned by `owner` that are currently encumbered.
+     *
+     * - MUST never exceed `balanceOf(owner)`
+     * - Any function which would reduce `balanceOf(owner)` below `encumberedBalanceOf(owner)` MUST revert
+     */
+    function encumberedBalanceOf(address owner) external view returns (uint256);
+
+    /**
+     * @dev Convenience function for reading the unencumbered balance of an address.
+     * Trivially implemented as `balanceOf(owner) - encumberedBalanceOf(owner)`
+     */
+    function availableBalanceOf(address owner) external view returns (uint256);
+
+    /**
+     * @dev Returns the number of tokens that `owner` has encumbered to `spender`.
+     *
+     * - This value increases when {encumber} or {encumberFrom} are called by the `owner` or by another permitted account.
+     * - This value decreases when {release} or {transferFrom} are called by `spender`.
+     */
+    function encumbrances(address owner, address spender) external view returns (uint256);
+
+    /**
+     * @dev Increases the amount of tokens that the caller has encumbered to `spender` by `amount`.
+     * Grants `spender` a guaranteed right to transfer `amount` from the caller's by using `transferFrom`.
+     *
+     * - MUST revert if caller does not have `amount` tokens available
+     *  (e.g. if `balanceOf(caller) - encumberedBalanceOf(caller) < amount`).
+     * - Emits an {IERC7246-Encumber} event.
+     */
+    function encumber(address spender, uint256 amount) external;
+
+    /**
+     * @dev Increases the amount of tokens that `owner` has encumbered to `spender` by `amount`.
+     * Grants `spender` a guaranteed right to transfer `amount` from `owner` using transferFrom.
+     *
+     * - The function SHOULD revert unless the owner account has deliberately authorized the sender of the message via some mechanism.
+     * - MUST revert if `owner` does not have `amount` tokens available
+     *  (e.g. if `balanceOf(owner) - encumberedBalanceOf(owner) < amount`).
+     * - Emits an {IERC7246-Encumber} event.
+     */
+    function encumberFrom(address owner, address spender, uint256 amount) external;
+
+    /**
+     * @dev Reduces amount of tokens encumbered from `owner` to caller by `amount`
+     *
+     * - Emits a {IERC7246-Release} event.
+     */
+    function release(address owner, uint256 amount) external;
+}

contracts/token/ERC20/ERC20.sol

@@ -152,7 +152,7 @@ abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
      * This internal function is equivalent to {transfer}, and can be used to
      * e.g. implement automatic token fees, slashing mechanisms, etc.
      *
-     * Emits a {Transfer} event.
+     * Emits a {Transfer-address-address-uint256} event.
      *
      * NOTE: This function is not virtual, {_update} should be overridden instead.
      */
@@ -171,7 +171,7 @@ abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
      * (or `to`) is the zero address. All customizations to transfers, mints, and burns should be done by overriding
      * this function.
      *
-     * Emits a {Transfer} event.
+     * Emits a {IERC20-Transfer} event.
      */
     function _update(address from, address to, uint256 value) internal virtual {
         if (from == address(0)) {
@@ -207,7 +207,7 @@ abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
      * @dev Creates a `value` amount of tokens and assigns them to `account`, by transferring it from address(0).
      * Relies on the `_update` mechanism
      *
-     * Emits a {Transfer} event with `from` set to the zero address.
+     * Emits a {IERC20-Transfer} event with `from` set to the zero address.
      *
      * NOTE: This function is not virtual, {_update} should be overridden instead.
      */
@@ -239,7 +239,7 @@ abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
      * This internal function is equivalent to `approve`, and can be used to
      * e.g. set automatic allowances for certain subsystems, etc.
      *
-     * Emits an {Approval} event.
+     * Emits an {IERC20-Approval} event.
      *
      * Requirements:
      *

contracts/token/ERC20/README.adoc

@@ -27,6 +27,7 @@ Additionally there are multiple custom extensions, including:
 * {ERC20TemporaryApproval}: support for approvals lasting for only one transaction, as defined in ERC-7674.
 * {ERC1363}: support for calling the target of a transfer or approval, enabling code execution on the receiver within a single transaction.
 * {ERC4626}: tokenized vault that manages shares (represented as ERC-20) that are backed by assets (another ERC-20).
+* {ERC7246}
 
 Finally, there are some utilities to interact with ERC-20 contracts in various ways:
 
@@ -74,6 +75,8 @@ NOTE: This core set of contracts is designed to be unopinionated, allowing devel
 
 {{ERC4626}}
 
+{{ERC7246}}
+
 == Utilities
 
 {{SafeERC20}}

contracts/token/ERC20/extensions/draft-ERC7246.sol

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.26;
+
+import {ERC20} from "../ERC20.sol";
+import {IERC7246} from "../../../interfaces/draft-IERC7246.sol";
+import {Math} from "../../../utils/math/Math.sol";
+
+/**
+ * @title ERC7246
+ * @dev An extension of {ERC20} that adds support for encumbrances of token balances. Encumbrances are a
+ * stronger version of allowances: they grant the `spender` an exclusive right to transfer tokens from the
+ * `owner`'s balance without reducing the `owner`'s balance until the tokens are transferred or the
+ * encumbrance is released.
+ */
+abstract contract ERC7246 is ERC20, IERC7246 {
+    /// @dev Thrown when the result of an {_update} or {_encumber} call would result in negative {availableBalanceOf}.
+    error ERC7246InsufficientAvailableBalance(uint256 available, uint256 required);
+
+    /// @dev Thrown when an account tries to release more encumbered tokens than it has.
+    error ERC7246InsufficientEncumbrance(uint256 encumbered, uint256 required);
+
+    /// @dev Thrown when an account tries to encumber tokens to itself.
+    error ERC7246SelfEncumbrance();
+
+    mapping(address owner => mapping(address spender => uint256)) private _encumbrances;
+    mapping(address owner => uint256) private _encumberedBalances;
+
+    /// @inheritdoc IERC7246
+    function encumberedBalanceOf(address owner) public view virtual returns (uint256) {
+        return _encumberedBalances[owner];
+    }
+
+    /// @inheritdoc IERC7246
+    function availableBalanceOf(address owner) public view virtual returns (uint256) {
+        return balanceOf(owner) - encumberedBalanceOf(owner);
+    }
+
+    /// @inheritdoc IERC7246
+    function encumbrances(address owner, address spender) public view virtual returns (uint256) {
+        return _encumbrances[owner][spender];
+    }
+
+    /// @inheritdoc IERC7246
+    function encumber(address spender, uint256 amount) public virtual {
+        _encumber(msg.sender, spender, amount);
+    }
+
+    /// @inheritdoc IERC7246
+    function encumberFrom(address owner, address spender, uint256 amount) public virtual {
+        _spendAllowance(owner, msg.sender, amount);
+        _encumber(owner, spender, amount);
+    }
+
+    /// @inheritdoc IERC7246
+    function release(address owner, uint256 amount) public virtual {
+        _releaseEncumbrance(owner, msg.sender, amount);
+    }
+
+    /**
+     * @dev Encumber `amount` of tokens from `owner` to `spender`. Encumbering tokens grants an exclusive right
+     * to transfer the tokens without removing them from `owner`'s balance. Release the tokens by calling
+     * {release} or transfer them by calling {transferFrom}.
+     */
+    function _encumber(address owner, address spender, uint256 amount) internal virtual {
+        require(owner != spender, ERC7246SelfEncumbrance());
+        uint256 availableBalance = availableBalanceOf(owner);
+        require(availableBalance >= amount, ERC7246InsufficientAvailableBalance(availableBalance, amount));
+
+        // Given that the `availableBalanceOf` is `balanceOf(owner) - encumberedBalanceOf(owner)`,
+        // we know that the new `_encumberedBalances[owner] <= balanceOf(owner)` and thus no overflow is possible.
+        // `_encumberedBalances[owner] >= _encumbrances[owner][spender]`, so no overflow is possible there either.
+        unchecked {
+            _encumbrances[owner][spender] += amount;
+            _encumberedBalances[owner] += amount;
+        }
+
+        emit Encumber(owner, spender, amount);
+    }
+
+    /**
+     * @dev Release `amount` of encumbered tokens from `owner` to `spender`.
+     *
+     * - Will revert if there are insufficient encumbered tokens.
+     * - Emits the {IERC7246-Release} event.
+     */
+    function _releaseEncumbrance(address owner, address spender, uint256 amount) internal virtual {
+        uint256 encumbered = encumbrances(owner, spender);
+        require(encumbered >= amount, ERC7246InsufficientEncumbrance(encumbered, amount));
+
+        unchecked {
+            _encumbrances[owner][spender] -= amount;
+            _encumberedBalances[owner] -= amount;
+        }
+
+        emit Release(owner, spender, amount);
+    }
+
+    /**
+     * @dev See {ERC20-_spendAllowance}. Encumbrances are consumed first, then the remaining amount
+     * is passed to `super._spendAllowance`.
+     */
+    function _spendAllowance(address owner, address spender, uint256 amount) internal virtual override {
+        uint256 amountEncumbered = encumbrances(owner, spender);
+        uint256 remainingAllowance = amount;
+
+        if (amountEncumbered != 0) {
+            uint256 encumberedToUse = Math.min(amount, amountEncumbered);
+            _releaseEncumbrance(owner, spender, encumberedToUse);
+            unchecked {
+                remainingAllowance -= encumberedToUse;
+            }
+        }
+
+        super._spendAllowance(owner, spender, remainingAllowance);
+    }
+
+    /// @dev See {ERC20-_update}. Ensures that `from` has sufficient {availableBalanceOf} to cover the `amount` being transferred.
+    function _update(address from, address to, uint256 amount) internal virtual override {
+        super._update(from, to, amount);
+        if (from != address(0)) {
+            uint256 balanceOfFrom = balanceOf(from);
+            uint256 encumberedBalanceOfFrom = encumberedBalanceOf(from);
+            require(
+                balanceOfFrom >= encumberedBalanceOfFrom,
+                ERC7246InsufficientAvailableBalance(balanceOfFrom + amount - encumberedBalanceOfFrom, amount)
+            );
+        }
+    }
+}

package.json

@@ -61,7 +61,7 @@
     "@nomicfoundation/hardhat-chai-matchers": "^2.0.6",
     "@nomicfoundation/hardhat-ethers": "^3.0.9",
     "@nomicfoundation/hardhat-network-helpers": "^1.0.13",
-    "@openzeppelin/docs-utils": "^0.1.5",
+    "@openzeppelin/docs-utils": "^0.1.6",
     "@openzeppelin/merkle-tree": "^1.0.7",
     "@openzeppelin/upgrade-safe-transpiler": "^0.4.1",
     "@openzeppelin/upgrades-core": "^1.20.6",