ERC-7246 Locking tokens while preserving ownership (Encumber - Splitting Ownership & Guarantees)
Review · Tokens · created 2023-06-27
An ERC-20 extension that guarantees a specific account can reliably take a portion of your balance without the tokens actually being moved elsewhere. It is a stronger commitment than approve, since locked tokens cannot be freely spent by the owner.
Why it is needed
To use tokens as collateral or to lock them until a certain condition ends, most systems today require actually transferring the tokens into a smart contract. ERC-20's approve only permits another account to move a certain amount, so if the owner sends the tokens elsewhere in the meantime, the promise is broken. To guarantee availability, the contract must physically hold the tokens, but doing so transfers ownership to the contract, so owner benefits like airdrops no longer reach the real owner. Also, when tokens are pooled in a single contract, a single transfer can drain them all, increasing the potential damage. The source explains that locking tokens without moving them makes rights and ownership relationships clearer, and that extracting locked tokens requires going through accounts one by one, which is far more expensive in gas.
What to implement
event Encumber(address indexed owner, address indexed taker, uint amount);: An event emitted when an amount of owner's tokens is locked (encumbered) to taker.event Release(address indexed owner, address indexed taker, uint amount);: An event emitted when the amount of owner's tokens locked to taker decreases by amount.function encumberedBalanceOf(address owner) external returns (uint);: Returns the total amount of owner's tokens that are currently locked. This value must never exceed balanceOf(owner).function encumbrances(address owner, address taker) external returns (uint);: Returns the amount of tokens owner has locked to a specific taker.function encumber(address taker, uint amount) external;: The caller locks amount of their own balance to taker. Taker is guaranteed the right to take that amount via transferFrom.function encumberFrom(address owner, address taker, uint amount) external;: With owner's prior permission, a third party locks amount of owner's tokens to taker.function release(address owner, uint amount) external;: The caller (taker) releases amount from the locked amount they held against owner.function availableBalanceOf(address owner) public view returns (uint);: A convenience function for reading the balance that is not locked and can be freely spent. It is simply implemented as balanceOf(owner) - encumberedBalanceOf(owner).
In depth
Core invariant: the locked balance is always backed by the actual balance
encumberedBalanceOf(owner) MUST never exceed balanceOf(owner). Additionally, any function that would drop balanceOf(owner) below encumberedBalanceOf(owner) MUST revert. These two conditions are the decisive difference from allowance. They are what guarantees that locked tokens will actually be there when needed. The source Rationale states that the standard deliberately specifies only the bare minimum, and the only real requirement is that the owner cannot transfer locked tokens.
Call conditions for encumber and encumberFrom
encumber(taker, amount) MUST fail if the caller's available balance is insufficient, i.e. if balanceOf(caller) - encumberedBalanceOf(caller) < amount. encumberFrom(owner, taker, amount), which lets a third party lock owner's tokens, SHOULD fail if owner has not intentionally permitted the caller in some way, and MUST fail if owner's available balance is insufficient. Both functions emit an Encumber event on success. The reference implementation reuses ERC-20's allowance as the permission mechanism for encumberFrom, but the source allows defining a separate mechanism such as approveEncumber instead.
Changes in the locked amount and events
The value of encumbrances(owner, taker) increases when owner or a permitted account calls encumber or encumberFrom, and decreases when taker calls release or transferFrom. An Encumber(owner, taker, amount) event is emitted when the lock increases, and a Release(owner, taker, amount) event is emitted when it decreases. release(owner, amount) is a function by which the caller, acting as taker, voluntarily reduces the lock. The reference implementation handles the case where the requested amount exceeds the actual locked amount by releasing only the full locked amount.
Order of consumption in transferFrom: lock first, then allowance
The reference implementation's transferFrom(src, dst, amount) first consumes encumbrances(src, msg.sender), and if the requested amount exceeds the locked amount, spends the excess from allowance(src, msg.sender). This excess can only be drawn from the available balance (availableBalanceOf). The source Rationale mentions that an alternative implementation could consume the lock and the allowance simultaneously, but in that case approve would need to check that the allowance balance does not fall below what the locked balance requires, and permission would become a precondition before calling encumber. A regular transfer does not consume the lock and only checks the available balance.
ERC-20 compatibility and implementation approach
This standard is backwards compatible with existing ERC-20. Implementers only need to add functionality that blocks the transfer of tokens locked to another account. The reference implementation inherits OpenZeppelin's ERC-20 and shows that it can be attached as an extension to any ERC-20 by overriding transfer to check the available balance and transferFrom to consume the lock. The specification is designed to complement and closely mirror the ERC-20 specification, making it easy to adopt and understand.
Extension to other standards such as ERC-721
Since both amount and tokenId are uint, this interface can also be extended to ERC-721 tokens by placing tokenId in the amount slot. However, the source states that the interface itself was designed for clarity around its most likely use case, ERC-20. The Motivation section also mentions that this interface can be simply applied to other token standards such as ERC-721.
Proposal status: Review
This proposal is currently in the Review stage. Since it has not yet been finalized, keep in mind that the interface or requirements may change.
Things to watch out for
- Checking balance by available balance: When determining the amount of tokens that can be transferred, you must not rely on balanceOf. Instead, use balanceOf(account) - encumberedBalance(account), or availableBalanceOf(account) if it is implemented.
- Additional guards needed for other functions that change balance: The property that the locked balance is always backed by the actual balance can be achieved simply by blocking transfer and transferFrom. However, if there are other functions that change balances, such as rebasing tokens or admin burn functions, implementers must add separate guards to those functions as well to ensure balanceOf(account) never drops below encumberedBalanceOf(account).