✅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:

  1. Uses the same philosophy as Ether in that tokens are sent with send(dest, value, data).

  2. Both contracts and regular addresses can control and reject which token they send by registering a tokensToSend hook. (Rejection is done by reverting in the hook function.)

  3. Both contracts and regular addresses can control and reject which token they receive by registering a tokensReceived hook. (Rejection is done by reverting in the hook function.)

  4. 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.

  5. 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.

  6. Every token transaction contains data and operatorData bytes fields to be used freely to pass data from the holder and the operator, respectively.

  7. It is backward compatible with wallets that do not contain the tokensReceived hook function by deploying a proxy contract implementing the tokensReceived 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.

My comment Callbacks are potentially vulnerable to reentrancy attacks, be careful.

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:

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.

PreviousOpenZeppelin SafeERC20NextOpenZeppelin ERC-1155

Last updated