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

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

Original ERC · ← ERCs