ERC-7878 Bequeathable Contract (Bequeathable Contracts)
Final · Tokens · created 2025-02-01
A standard interface that lets a token owner set up a will in advance, so that after the owner's death an executor can transfer the tokens to an inheritor following a set waiting period.
Why it is needed
Crypto tokens, NFTs (non-fungible tokens) in particular, have begun to be used to tokenize real-world assets. For mainstream finance to accept such tokens, there must be a way to pass them on after the owner dies, but today there is no standardized method for transferring digital assets when a token holder dies. The inheritance process can also give rise to disputes, so a safeguard is needed that lets someone step in and halt the process before the actual transfer occurs. This standard models the real-world process of writing and executing a will. It defines a common interface in which the owner writes a Will in advance and designates an executor, so that after death the tokens pass to the inheritor safely and transparently after a set waiting period.
What to implement
event ObituaryStarted(address indexed owner, address indexed inheritor);: Signals that the owner's tokens are scheduled to be inherited. It is emitted when announceObit is called and contains the original owner and inheritor addresses.event ObituaryCancelled(address indexed owner, address indexed cancelledBy);: Signals that an in-progress obituary and its waiting period have been cancelled. It also contains the address of whoever cancelled it.function setWill(address[] memory executors, uint256 moratoriumTTL) external;: The token owner sets a will. It registers the list of executor addresses and the time in seconds that must pass between the obituary and the transfer, and calling it again overwrites the existing will.function getWill(address owner) external view returns (address[] memory executors, uint256 moratoriumTTL);: Looks up the contents of a given owner's will. It returns the executor list and the waiting time so the owner can verify the settings.function announceObit(address owner, address inheritor) external;: Starts the obituary process. It declares the owner and the address of the inheritor who will receive the tokens.function cancelObit(address owner) external;: Cancels an obituary that has already been announced. Any executor, or the owner themselves, can call it.function getObit(address owner) external view returns (address inheritor, int256 moratoriumTTL);: Looks up the designated inheritor and how much of the waiting time remains. A negative value means the waiting time has passed and the transfer is possible.function bequeath(address owner) external;: After the waiting period ends, actually transfers the tokens to the inheritor address declared at the time of the obituary.
In depth
Mandatory implementation of the Bequeathable interface
A contract that follows this standard MUST implement the Bequeathable interface. The interface consists of 6 functions and 2 events. The functions are setWill (set or update the will), getWill (look up the will), announceObit (announce the obituary to start the inheritance process), cancelObit (cancel the obituary), getObit (look up the obituary status), and bequeath (transfer the tokens to the inheritor). The events are ObituaryStarted, emitted when an obituary is announced, and ObituaryCancelled, emitted when an obituary is cancelled. Per the header, it requires ERC-20, ERC-165, ERC-721, and ERC-1155.
setWill and getWill: setting and checking the will
setWill is the function by which the token owner registers an array of executor addresses (executors) and a waiting time (moratoriumTTL, in seconds). Multiple executors can be designated, such as legal counsel, a spouse, or children, but only one of them is needed to start the process and carry out the transfer. Calling this function again must overwrite the existing will. moratoriumTTL is the time that must pass from when the obituary is announced until the actual inheritance transfer becomes possible, and it serves as a safety buffer that allows intervention before the transfer. getWill takes an owner address and returns the executor list and moratoriumTTL, and is used to check that the owner has set the will correctly.
announceObit and cancelObit: starting and cancelling the process
announceObit takes the owner address and the inheritor address, starts the obituary process, and emits an ObituaryStarted event containing the original owner and the inheritor. cancelObit is the function that cancels an in-progress obituary. Any executor can call it, and if the owner is alive, the owner can call it too. On cancellation, an ObituaryCancelled event is emitted and who cancelled it (cancelledBy) is recorded. According to the Rationale, letting any executor cancel is a design for handling disputes. If a dispute arises, it is settled in court, and once the matter is resolved the obituary process can be started again.
getObit and bequeath: status lookup and executing the transfer
getObit takes an owner address and returns the inheritor designated at the time of the obituary and the time remaining until moratoriumTTL. The returned remaining time is of type int256, and a negative value means the waiting time has already passed and the tokens can be passed on. bequeath is the function that actually transfers the tokens to the inheritor, and the transfer must go to the inheritor address designated when announceObit was called. According to the Rationale, to keep the interface simple, all tokens are transferred to a single address, and any further distribution afterward is the responsibility of whoever receives that address.
A design modeled on real-world will execution
This standard follows the process by which a will is prepared and executed in the real world. The owner writes a will and names an executor, the executor announces the obituary upon death, the will is read and the inheritor is identified, and the transfer of ownership is carried out according to the will. However, reality is not always smooth and disputes often arise, so while keeping the interface simple, the standard includes a mechanism that lets any executor cancel the obituary.
Compatibility with existing token standards
This standard is compatible with existing token standards such as ERC-20, ERC-721, and ERC-1155. It can be implemented alongside them without affecting their core functionality. In other words, it adds inheritance functionality on top of token formats already in use. A test case (Bequeath.test.js) and a reference implementation (Bequeathable.sol) are provided as source assets. The status of this proposal is Final, a finalized standard.
Things to watch out for
- Design access control carefully: Access control must be designed carefully so that the will-related functions can be executed only by authorized parties.
- Set the waiting time long enough: moratoriumTTL must be set to a reasonable length so that disputes or corrections are possible. For high-value tokens in particular, at least 30 days is recommended. It also reduces the damage if an attacker who has taken over an executor's wallet starts an obituary process without authorization.