Add ERC: Encumber - Splitting Ownership & Guarantees

Merged by EIP-Bot.

ERCS/erc-7246.md

@@ -0,0 +1,227 @@
+---
+eip: 7246
+title: Encumber - Splitting Ownership & Guarantees
+description: A token interface to allow pledging tokens without transferring ownership.
+author: Coburn Berry (@coburncoburn), Mykel Pereira (@mykelp), Scott Silver (@scott-silver)
+discussions-to: https://ethereum-magicians.org/t/encumber-extending-the-erc-20-token-standard-to-allow-pledging-tokens-without-giving-up-ownership/14849
+status: Draft
+type: Standards Track
+category: ERC
+created: 2023-06-27
+requires: 20
+---
+
+## Abstract
+
+This ERC proposes an extension to the [ERC-20](./eip-20.md) token standard by adding Encumber—the ability for an account to grant another account exclusive right to move some portion of their balance. Encumber is a stronger version of [ERC-20](./eip-20.md) allowances. While [ERC-20](./eip-20.md) approve grants another account the permission to transfer a specified token amount, encumber grants the same permission while ensuring that the tokens will be available when needed.
+
+## Motivation
+
+This extension adds flexibility to the [ERC-20](./eip-20.md) token standard and caters to use cases where token locking is required, but it is preferential to maintain actual ownership of tokens. This interface can also be adapted to other token standards, such as [ERC-721](./eip-721.md), in a straightforward manner
+
+Token holders commonly transfer their tokens to smart contracts which will return the tokens under specific conditions. In some cases, smart contracts do not actually need to hold the tokens, but need to guarantee they will be available if necessary. Since allowances do not provide a strong enough guarantee, the only way to do guarantee token availability presently is to transfer the token to the smart contract. Locking tokens without moving them gives more clear indication of the rights and ownership of the tokens. This allows for airdrops and other ancillary benefits of ownership to reach the true owner. It also adds another layer of safety, where draining a pool of [ERC-20](./eip-20.md) tokens can be done in a single transfer, iterating accounts to transfer encumbered tokens would be significantly more prohibitive in gas usage.
+
+## Specification
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
+
+A compliant token MUST implement the following interface
+
+```solidity
+/**
+ * @dev Interface of the ERC-7246 standard.
+ */
+interface IERC7246{
+    /**
+     * @dev Emitted when `amount` tokens are encumbered from `owner` to `taker`.
+     */
+    event Encumber(address indexed owner, address indexed taker, uint amount);
+
+    /**
+     * @dev Emitted when the encumbrance of a `taker` to an `owner` is reduced by `amount`.
+     */
+    event Release(address indexed owner, address indexed taker, uint 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 returns (uint);
+
+    /**
+     * @dev Returns the number of tokens that `owner` has encumbered to `taker`.
+     *
+     * This value increases when {encumber} or {encumberFrom} are called by the `owner` or by another permitted account.
+     * This value decreases when {release} and {transferFrom} are called by `taker`.
+     */
+    function encumbrances(address owner, address taker) external returns (uint);
+
+    /**
+     * @dev Increases the amount of tokens that the caller has encumbered to `taker` by `amount`.
+     * Grants to `taker` a guaranteed right to transfer `amount` from the caller's balance by using `transferFrom`.
+     *
+     * MUST revert if caller does not have `amount` tokens available
+     * (e.g. if `balanceOf(caller) - encumbrances(caller) < amount`).
+     *
+     * Emits an {Encumber} event.
+     */
+    function encumber(address taker, uint amount) external;
+
+    /**
+     * @dev Increases the amount of tokens that `owner` has encumbered to `taker` by `amount`.
+     * Grants to `taker` 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) - encumbrances(owner) < amount`).
+     *
+     * Emits an {Encumber} event.
+     */
+    function encumberFrom(address owner, address taker, uint amount) external;
+
+    /**
+     * @dev Reduces amount of tokens encumbered from `owner` to caller by `amount`
+     *
+     * Emits a {Release} event.
+     */
+    function release(address owner, uint amount) external;
+
+
+    /**
+     * @dev Convenience function for reading the unencumbered balance of an address.
+     * Trivially implemented as `balanceOf(owner) - encumberedBalanceOf(owner)`
+     */
+    function availableBalanceOf(address owner) public view returns (uint);
+}
+```
+
+## Rationale
+The specification was designed to complement and mirror the ERC-20 specification to ease adoption and understanding. The specification is intentionally minimally proscriptive of this joining, where the only true requirement is that an owner cannot transfer encumbered tokens. However, the example implementation includes some decisions about where to connect with ERC-20 functions worth noting. It was designed for minimal invasiveness of standard ERC-20 definitions.
+    - The example has a dependency on `approve` to facilitate `encumberFrom`. This proposal allows for an implementer to define another mechanism, such as an `approveEncumber` which would mirror ERC-20 allowances, if desired.
+    - `transferFrom(src, dst, amount)` is written to first reduce the `encumbrances(src, amount)`, and then subsequently spend from `allowance(src, msg.sender)`. Alternatively, `transferFrom` could be implemented to spend from allowance simultaneously to spending encumbrances. This would require `approve` to check that the approved balance does not decrease beneath the amount required by encumbered balances, and also make creating the approval a prerequisite to calling `encumber`.
+
+It is possible to stretch the Encumber interface to cover ERC-721 tokens by using the `tokenId` in place of `amount` param since they are both `uint`. The interface opts for clarity with the most likely use case (ERC-20), even if it is compatible with other formats.
+
+
+
+## Backwards Compatibility
+
+This EIP is backwards compatible with the existing [ERC-20](./eip-20.md) standard. Implementations must add the functionality to block transfer of tokens that are encumbered to another account.
+
+
+## Reference Implementation
+
+This can be implemented as an extension of any base [ERC-20](./eip-20.md) contract by modifying the transfer function to block the transfer of encumbered tokens and to release encumbrances when spent via transferFrom.
+
+
+``` solidity
+// An erc-20 token that implements the encumber interface by blocking transfers.
+
+pragma solidity ^0.8.0;
+import {ERC20} from "../lib/openzeppelin-contracts/contracts/token/ERC20/ERC20.sol";
+import { IERC7246 } from "./IERC7246.sol";
+
+contract EncumberableERC20 is ERC20, IERC7246 {
+    // Owner -> Taker -> Amount that can be taken
+    mapping (address => mapping (address => uint)) public encumbrances;
+
+    // The encumbered balance of the token owner. encumberedBalance must not exceed balanceOf for a user
+    // Note this means rebasing tokens pose a risk of diminishing and violating this prototocol
+    mapping (address => uint) public encumberedBalanceOf;
+
+    address public minter;
+
+    constructor(string memory name, string memory symbol) ERC20(name, symbol) {
+        minter = msg.sender;
+    }
+
+    function mint(address recipient, uint amount) public {
+        require(msg.sender == minter, "only minter");
+        _mint(recipient, amount);
+    }
+
+    function encumber(address taker, uint amount) external {
+        _encumber(msg.sender, taker, amount);
+    }
+
+    function encumberFrom(address owner, address taker, uint amount) external {
+        require(allowance(owner, msg.sender) >= amount);
+       _encumber(owner, taker, amount);
+    }
+
+    function release(address owner, uint amount) external {
+        _release(owner, msg.sender, amount);
+    }
+
+    // If bringing balance and encumbrances closer to equal, must check
+    function availableBalanceOf(address a) public view returns (uint) {
+        return (balanceOf(a) - encumberedBalanceOf[a]);
+    }
+
+    function _encumber(address owner, address taker, uint amount) private {
+        require(availableBalanceOf(owner) >= amount, "insufficient balance");
+        encumbrances[owner][taker] += amount;
+        encumberedBalanceOf[owner] += amount;
+        emit Encumber(owner, taker, amount);
+    }
+
+    function _release(address owner, address taker, uint amount) private {
+        if (encumbrances[owner][taker] < amount) {
+          amount = encumbrances[owner][taker];
+        }
+        encumbrances[owner][taker] -= amount;
+        encumberedBalanceOf[owner] -= amount;
+        emit Release(owner, taker, amount);
+    }
+
+    function transfer(address dst, uint amount) public override returns (bool) {
+        // check but dont spend encumbrance
+        require(availableBalanceOf(msg.sender) >= amount, "insufficient balance");
+        _transfer(msg.sender, dst, amount);
+        return true;
+    }
+
+    function transferFrom(address src, address dst, uint amount) public override returns (bool) {
+        uint encumberedToTaker = encumbrances[src][msg.sender];
+        bool exceedsEncumbrance = amount > encumberedToTaker;
+        if (exceedsEncumbrance)  {
+            uint excessAmount = amount - encumberedToTaker;
+
+            // check that enough enencumbered tokens exist to spend from allowance
+           require(availableBalanceOf(src) >= excessAmount, "insufficient balance");
+
+           // Exceeds Encumbrance , so spend all of it
+            _spendEncumbrance(src, msg.sender, encumberedToTaker);
+
+            _spendAllowance(src, dst, excessAmount);
+        } else {
+            _spendEncumbrance(src, msg.sender, amount);
+        }
+
+        _transfer(src, dst, amount);
+        return true;
+    }
+
+    function _spendEncumbrance(address owner, address taker, uint256 amount) internal virtual {
+        uint256 currentEncumbrance = encumbrances[owner][taker];
+        require(currentEncumbrance >= amount, "insufficient encumbrance");
+        uint newEncumbrance = currentEncumbrance - amount;
+        encumbrances[owner][taker] = newEncumbrance;
+        encumberedBalanceOf[owner] -= amount;
+    }
+}
+```
+
+
+## Security Considerations
+
+Parties relying on `balanceOf` to determine the amount of tokens available for transfer should instead rely on `balanceOf(account) - encumberedBalance(account)`, or, if implemented, `availableBalanceOf(account)`.
+
+The property that encumbered balances are always backed by a token balance can be accomplished in a straightforward manner by altering `transfer` and `transferFrom` to block . If there are other functions that can alter user balances, such as a rebasing token or an admin burn function, additional guards must be added by the implementer to likewise ensure those functions prevent reducing `balanceOf(account)` below `encumberedBalanceOf(account)` for any given account.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).