โ OpenZeppelin ERC-777
EIP-777
Simple Summary
This EIP defines standard interfaces and behaviors for token contracts.
Abstract
This standard defines a new way to interact with a token contract while remaining backward compatible with ERC-20.
It defines advanced features to interact with tokens. Namely, operators to send tokens on behalf of another addressโcontract or regular accountโand send/receive hooks to offer token holders more control over their tokens.
It takes advantage of ERC-1820 to find out whether and where to notify contracts and regular addresses when they receive tokens as well as to allow compatibility with already-deployed contracts.
Motivation
This standard tries to improve upon the widely used ERC-20 token standard. The main advantages of this standard are:
Uses the same philosophy as Ether in that tokens are sent with
send(dest, value, data)
.Both contracts and regular addresses can control and reject which token they send by registering a
tokensToSend
hook. (Rejection is done byrevert
ing in the hook function.)Both contracts and regular addresses can control and reject which token they receive by registering a
tokensReceived
hook. (Rejection is done byrevert
ing in the hook function.)The
tokensReceived
hook allows to send tokens to a contract and notify it in a single transaction, unlike ERC-20 which requires a double call (approve
/transferFrom
) to achieve this.The holder can โauthorizeโ and โrevokeโ operators which can send tokens on their behalf. These operators are intended to be verified contracts such as an exchange, a cheque processor or an automatic charging system.
Every token transaction contains
data
andoperatorData
bytes fields to be used freely to pass data from the holder and the operator, respectively.It is backward compatible with wallets that do not contain the
tokensReceived
hook function by deploying a proxy contract implementing thetokensReceived
hook for the wallet.
OpenZeppelin ERC777 Doc
Like ERC20, ERC777 is a standard for fungible tokens, and is focused around allowing more complex interactions when trading tokens. More generally, it brings tokens and Ether closer together by providing the equivalent of a msg.value
field, but for tokens.
The standard also brings multiple quality-of-life improvements, such as getting rid of the confusion around decimals
, minting and burning with proper events, among others, but its killer feature is receive hooks. A hook is simply a function in a contract that is called when tokens are sent to it, meaning accounts and contracts can react to receiving tokens.
This enables a lot of interesting use cases, including atomic purchases using tokens (no need to do approve
and transferFrom
in two separate transactions), rejecting reception of tokens (by reverting on the hook call), redirecting the received tokens to other addresses (similarly to how PaymentSplitter
does it), among many others.
Furthermore, since contracts are required to implement these hooks in order to receive tokens, no tokens can get stuck in a contract that is unaware of the ERC777 protocol, as has happened countless times when using ERC20s.
What If I Already Use ERC20?
The standard has you covered! The ERC777 standard is backwards compatible with ERC20, meaning you can interact with these tokens as if they were ERC20, using the standard functions, while still getting all of the niceties, including send hooks. See the EIPโs Backwards Compatibility section to learn more.
Constructing an ERC777 Token Contract
We will replicate the GLD
example of the ERC20 guide, this time using ERC777. As always, check out the API reference
to learn more about the details of each function.
// contracts/GLDToken.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.6.0;
import "@openzeppelin/contracts/token/ERC777/ERC777.sol";
contract GLDToken is ERC777 {
constructor(uint256 initialSupply, address[] memory defaultOperators)
public
ERC777("Gold", "GLD", defaultOperators)
{
_mint(msg.sender, initialSupply, "", "");
}
}
In this case, weโll be extending from the ERC777
contract, which provides an implementation with compatibility support for ERC20. The API is quite similar to that of ERC777
, and weโll once again make use of _mint
to assign the initialSupply
to the deployer account. Unlike ERC20โs _mint
, this one includes some extra parameters, but you can safely ignore those for now.
Youโll notice both name
and symbol
are assigned, but not decimals
. The ERC777 specification makes it mandatory to include support for these functions (unlike ERC20, where it is optional and we had to include ERC20Detailed
), but also mandates that decimals
always returns a fixed value of 18
, so thereโs no need to set it ourselves. For a review of decimals
's role and importance, refer back to our ERC20 guide.
Finally, weโll need to set the defaultOperators
: special accounts (usually other smart contracts) that will be able to transfer tokens on behalf of their holders. If youโre not planning on using operators in your token, you can simply pass an empty array. Stay tuned for an upcoming in-depth guide on ERC777 operators!
Thatโs it for a basic token contract! We can now deploy it, and use the same balanceOf
method to query the deployerโs balance:
> GLDToken.balanceOf(deployerAddress)
1000
To move tokens from one account to another, we can use both ERC20
's transfer
method, or the new ERC777
's send
, which fulfills a very similar role, but adds an optional data
field:
> GLDToken.transfer(otherAddress, 300)
> GLDToken.send(otherAddress, 300, "")
> GLDToken.balanceOf(otherAddress)
600
> GLDToken.balanceOf(deployerAddress)
400
Sending Tokens to Contracts
A key difference when using send
is that token transfers to other contracts may revert with the following message:
ERC777: token recipient contract has no implementer for ERC777TokensRecipient
This is a good thing! It means that the recipient contract has not registered itself as aware of the ERC777 protocol, so transfers to it are disabled to prevent tokens from being locked forever. As an example, the Golem contract currently holds over 350k GNT
tokens, worth multiple tens of thousands of dollars, and lacks methods to get them out of there. This has happened to virtually every ERC20-backed project, usually due to user error.
An upcoming guide will cover how a contract can register itself as a recipient, send and receive hooks, and other advanced features of ERC777!
How to Set Implementer
Interface of the ERC777Token standard as defined in the EIP.
This contract uses the ERC1820 registry standard to let token holders and recipients react to token movements by using setting implementers for the associated interfaces in said registry. See IERC1820Registry
and ERC1820Implementer
.
The implementer setter function can be found in IERC1820Registry:
Function definition:
setInterfaceImplementer(address account, bytes32 _interfaceHash, address implementer)
Description:
Sets the implementer
contract as account
's implementer for interfaceHash
.
account
being the zero address is an alias for the callerโs address. The zero address can also be used in implementer
to remove an old one.
See interfaceHash
to learn how these are created.
Emits an InterfaceImplementerSet
event.
Requirements:
the caller must be the current manager for
account
.interfaceHash
must not be anIERC165
interface id (i.e. it must not end in 28 zeroes).implementer
must implementIERC1820Implementer
and return true when queried for support, unlessimplementer
is the caller. SeeIERC1820Implementer.canImplementInterfaceForAddress
.
OpenZeppelin Implementation
We are going to discover the "new" functions that ERC20 does not have.
send()
The send()
method is similar to transfer()
but with an additional function parameter data
. If we send()
to a contract, the recipient contract MUST implment the tokensReceived()
callback, otherwise the transaction would revert. This design makes sure that the recipient contract is aware of the ERC777 protocol.
Diving into the code, send()
will invoke the _callTokensToSend()
and _callTokensReceived()
callbacks:
function send(address recipient, uint256 amount, bytes memory data) public virtual override {
_send(_msgSender(), recipient, amount, data, "", true);
}
function _send(
address from,
address to,
uint256 amount,
bytes memory userData,
bytes memory operatorData,
bool requireReceptionAck
) internal virtual {
require(from != address(0), "ERC777: transfer from the zero address");
require(to != address(0), "ERC777: transfer to the zero address");
address operator = _msgSender();
_callTokensToSend(operator, from, to, amount, userData, operatorData);
_move(operator, from, to, amount, userData, operatorData);
_callTokensReceived(operator, from, to, amount, userData, operatorData, requireReceptionAck);
}
Callbacks
_callTokensToSend()
function _callTokensToSend(
address operator,
address from,
address to,
uint256 amount,
bytes memory userData,
bytes memory operatorData
) private {
address implementer = _ERC1820_REGISTRY.getInterfaceImplementer(from, _TOKENS_SENDER_INTERFACE_HASH);
if (implementer != address(0)) {
IERC777Sender(implementer).tokensToSend(operator, from, to, amount, userData, operatorData);
}
}
_callTokensReceived()
function _callTokensReceived(
address operator,
address from,
address to,
uint256 amount,
bytes memory userData,
bytes memory operatorData,
bool requireReceptionAck
) private {
address implementer = _ERC1820_REGISTRY.getInterfaceImplementer(to, _TOKENS_RECIPIENT_INTERFACE_HASH);
if (implementer != address(0)) {
IERC777Recipient(implementer).tokensReceived(operator, from, to, amount, userData, operatorData);
} else if (requireReceptionAck) {
require(!to.isContract(), "ERC777: token recipient contract has no implementer for ERC777TokensRecipient");
}
}
implementer
must be registered in ERC1820 registry in order to use these two callbacks.
Last updated
Was this helpful?