ERC-7695 ERC-721 ownership delegation and context (Ownership Delegation and Context for ERC-721)
Draft · NFTs & multi-token · created 2024-04-02
An ERC-721 extension standard that lets an NFT be lent out or locked by attaching it to a purpose-specific context without transferring it elsewhere, and that lets the right to exercise ownership be delegated to another account for a fixed period.
Why it is needed
The existing ERC-721 has only a single role, Owner. So to stake, pledge as collateral, or lend an NFT, the token itself has to be transferred to and locked in that contract. But many apps grant benefits like airdrops or tier-based rewards using the fact that a token sits in a wallet as proof of holding. Once a token is locked in a contract, the original owner loses access to those benefits, and reward systems can only fix this by individually supporting as many locking contracts as possible. There has also been no standard way to express use cases like lending or delegation, where the owner stays the same but the user changes, which has always made it hard to build such services on top of ERC-721. This standard tries to solve the problem by dividing use cases into contexts handled by controllers, and by adding ownership delegation to the standard, which separates the owner from the right to exercise ownership.
What to implement
event ContextUpdated(bytes32 indexed ctxHash, address indexed controller, uint64 detachingDuration);: Fired when a context is created or when its controller or detaching wait time changes.event ContextAttached(bytes32 indexed ctxHash, uint256 indexed tokenId);: Fired when a token is attached to a context.event ContextDetachmentRequested(bytes32 indexed ctxHash, uint256 indexed tokenId);: Fired when detachment of a token from a context is requested.event ContextDetached(bytes32 indexed ctxHash, uint256 indexed tokenId);: Fired when a token is detached from a context.event ContextUserAssigned(bytes32 indexed ctxHash, uint256 indexed tokenId, address indexed user);: Fired when a user is assigned to use a token within a context.event ContextLockUpdated(bytes32 indexed ctxHash, uint256 indexed tokenId, bool locked);: Fired when a token is locked or unlocked within a context.event OwnershipDelegationStarted(uint256 indexed tokenId, address indexed delegatee, uint64 until);: Fired when ownership delegation is started (proposed).event OwnershipDelegationAccepted(uint256 indexed tokenId, address indexed delegatee, uint64 until);: Fired when the delegate accepts the ownership delegation.event OwnershipDelegationStopped(uint256 indexed tokenId, address indexed delegatee);: Fired when ownership delegation is stopped before expiry.function maxDetachingDuration() external view returns (uint64);: Queries the maximum wait time a context detachment can take.function getContext(bytes32 ctxHash) external view returns (address controller, uint64 detachingDuration);: Queries the controller address and detaching wait time of a context. Reverts if the context does not exist.function createContext(address controller, uint64 detachingDuration, bytes calldata ctxMsg) external returns (bytes32 ctxHash);: Creates a new context and returns its hash. Reverts if the controller is the zero address or the wait time exceeds the maximum.function updateContext(bytes32 ctxHash, address newController, uint64 newDetachingDuration) external;: Changes the controller and detaching wait time of an existing context. Only the current controller can call this.function isAttachedWithContext(bytes32 ctxHash, uint256 tokenId) external view returns (bool);: Queries whether a token is attached to a given context.function attachContext(bytes32 ctxHash, uint256 tokenId, bytes calldata data) external;: Attaches a token to a context. If the controller is a contract, the onAttached callback is called, and the attachment is rejected on failure.function requestDetachContext(bytes32 ctxHash, uint256 tokenId, bytes calldata data) external;: Requests detachment from a context. An unlocked token is detached immediately, while a locked token enters a requested state.function execDetachContext(bytes32 ctxHash, uint256 tokenId, bytes calldata data) external;: Executes detachment for a token once the wait time has passed after a detach request.function getContextUser(bytes32 ctxHash, uint256 tokenId) external view returns (address user);: Queries the user assigned to use a token within a given context.function setContextUser(bytes32 ctxHash, uint256 tokenId, address user) external;: Assigns a user for a context. Only the controller can call this, and the token must be attached to that context.function isTokenContextLocked(bytes32 ctxHash, uint256 tokenId) external view returns (bool);: Queries whether a token is locked within a given context.function setContextLock(bytes32 ctxHash, uint256 tokenId, bool lock) external;: Locks or unlocks a token within a context. Only the controller can call this.function getOwnershipManager(uint256 tokenId) external view returns(address manager);: Queries the account currently holding the right to exercise ownership (the owner if there is no delegation in effect, or the delegate if there is).function getOwnershipDelegatee(uint256 tokenId) external view returns (address delegatee, uint64 until);: Queries the currently valid ownership delegate and expiration time. Reverts if there is no delegation or it has expired.function pendingOwnershipDelegatee(uint256 tokenId) external view returns (address delegatee, uint64 until);: Queries the pending, not-yet-accepted delegate and expiration time.function startDelegateOwnership(uint256 tokenId, address delegatee, uint64 until) external;: Starts the process of delegating ownership until a specified time. Any prior pending proposal is replaced.function acceptOwnershipDelegation(uint256 tokenId) external;: The delegate accepts the delegation proposal. Once accepted, the delegate becomes the ownership manager until expiration.function stopOwnershipDelegation(uint256 tokenId) external;: The delegate stops the delegation before expiry and returns the right to exercise ownership to the owner.function getContext(uint256 index) external view returns(bytes32 ctxHash);: Returns the context hash at the given index in the optional enumeration extension.function getContextCount() external view returns(uint256);: Returns the number of contexts created on the contract.function getAttachedContext(uint256 tokenId, uint256 index) external view returns(bytes32 ctxHash);: Returns the hash at the given index among the contexts attached to a token.function getAttachedContextCount(uint256 tokenId) external view returns(uint256);: Returns the number of contexts attached to a token.function onAttached(bytes32 ctxHash, uint256 tokenId, address operator, bytes calldata data) external;: A callback invoked on the controller side when a token is attached to a context. Reverting it rejects the attachment.function onDetachRequested(bytes32 ctxHash, uint256 tokenId, address operator, bytes calldata data) external;: A callback invoked when detachment is requested. The result is ignored, so it cannot block detachment.function onExecDetachContext(bytes32 ctxHash, uint256 tokenId, address user, address operator, bytes calldata data) external;: A callback invoked when detachment is executed. The result is ignored, so it cannot block detachment.
In depth
Context and role structure
A context is a unit representing a specific use of a token, and each token-context pair has exactly one controller and one user. The controller can transfer the controller role, assign the user, and lock or unlock the token, while the user has the right to use the token within that context. Ownership Rights are defined as three things: token transfer, context attachment, and context detachment. The Ownership Manager is the party that actually exercises ownership rights, referring to the owner when there is no delegation and to the delegate when delegation is active. For a single token there is exactly one owner, one delegate, and one ownership manager, while up to n context roles can be attached.
Two-step ownership delegation
startDelegateOwnership is called by the owner, their operator, or an approved address. It must revert if there is already an accepted delegation, the expiration time must be in the future, and it reverts if the delegate is the owner themselves or the zero address. Any prior pending proposal is replaced. It only takes effect once the delegate (or their operator) calls acceptOwnershipDelegation, after which the delegate is recorded as the ownership manager until expiration. stopOwnershipDelegation can only be called by the delegate side for an accepted delegation, and on success the owner becomes the ownership manager again. Unlike approve or setApprovalForAll, which only add permissions while the owner keeps their status, delegation transfers the owner's rights themselves to the delegate and reverts automatically on expiration. This design is meant to prevent abuse where an owner keeps hold of the rights, takes collateral, and then siphons the token off to another account, and the two-step process (propose and accept) is meant to prevent mistakes in designating the delegate.
Lock and detach rules
setContextLock can only be called by the controller, and it cannot be called on a token for which detachment has already been requested. Detachment branches two ways. For an unlocked token, or when the controller itself requests it, a single call to requestDetachContext detaches it immediately and fires ContextDetached. For a locked token, the request fires ContextDetachRequested, and execDetachContext must be called after the detaching wait time (detachingDuration) has passed for detachment to occur. Eligibility to call both functions is limited to the ownership manager, their operator, and, when not under delegation, an approved address. The onDetachRequested and onExecDetachContext callbacks in the detachment process are called but their results are specified to be ignored, so the controller cannot block detachment. In contrast, onAttached on attachment reverts the entire operation on failure, allowing the controller to reject an unwanted attachment. This is designed so that the owner can free the token themselves even if the controller loses control.
Automatic cleanup on transfer
Transfers can only be performed by the ownership manager, their operator, or, when not under delegation, an approved address. When a transfer occurs, any ongoing ownership delegation must be stopped and all attached contexts must be detached. If there are locked contexts, detachment must first be requested and the wait time must have passed before the transfer can proceed. During detachment, if the controller is a contract, onExecDetachContext is called with an empty data argument, but the result is ignored. For gas efficiency, the OwnershipDelegationStopped and ContextDetached events are intentionally not fired during this process.
ERC-165 identifiers and optional extensions
A contract implementing this standard must implement all functions of IERC7695, and supportsInterface must return true for 0x486b6fba. The optional Enumerable extension, which allows querying the list of contexts, has the identifier 0xcebf44b7. It is recommended that the controller be a contract implementing the callback interface (IERC7695ContextCallback) that receives attachment and detachment requests, and the identifier for this interface is 0xad0491f1.
Proposal in Draft status
This proposal is in Draft status, created in April 2024. Since it is not yet a finalized standard, the interface and rules may still change, and the latest source text should be checked before implementation.
Things to watch out for
- Setting the detaching wait time: The deployer should set an appropriate upper bound on the detachment delay via maxDetachingDuration, and whoever creates a context should set a period suited to the use case that does not exceed that cap. This is a safeguard against abuse where an owner lists something for a very short time and then hands the token off to another owner in rapid succession.
- Duplicate token use: When creating a new context, the controller must track the other contexts for the same NFT contract. For example, if a game locks a token in a lending context while a separate delegation context is also created, the token could end up being used for two different purposes within the same game at once. Approaches to consider include using a shared context that combines lending and delegation, or imposing reuse restrictions on new contexts.
- Buffer time for delegation requests: Systems that rely on ownership delegation must add a buffer of at least maxDetachingDuration seconds when requesting a delegation. For example, if the maximum detaching wait time is 7 days but a collateral contract only needs a 3 day delegation period, without a buffer the owner could withdraw funds and then lock the token in another context to block detachment and transfer.
- Callback caller verification: When implementing IERC7695ContextCallback, you must verify that the callback's msg.sender is the expected contract address (usually the token contract or a designated controller contract). This is necessary to prevent unauthorized actions by a malicious party impersonating a legitimate contract.
- Phishing and risk of ownership loss: If an owner is deceived into designating a malicious account as delegate via startDelegateOwnership, that account can even transfer the tokens. This risk should be regarded at the same level as approve or setApprovalForAll. When delegating to a contract such as collateral, you should also check that the delegation period is not excessively long and that there is a clause releasing the delegation once conditions are met, and be aware that if the contract owner or its operator is compromised, token ownership can change hands.