ERC-820: Pseudo-introspection Registry Contract


Metadata
Status: FinalStandards Track: ERCCreated: 2018-01-05
Authors
Jordi Baylina (jordi@baylina.cat), Jacques Dafflon (jacques@dafflon.tech)
Requires

:information_source: ERC-1820 has superseded ERC-820. :information_source:
ERC-1820 fixes the incompatibility in the ERC-165 logic which was introduced by the Solidty 0.5 update.
Have a look at the official announcement, and the comments about the bug and the fix.
Apart from this fix, ERC-1820 is functionally equivalent to ERC-820.

:warning: ERC-1820 MUST be used in lieu of ERC-820. :warning:

Simple Summary


This standard defines a universal registry smart contract where any address (contract or regular account) can register which interface it supports and which smart contract is responsible for its implementation.

This standard keeps backward compatibility with ERC-165.

Abstract


This standard defines a registry where smart contracts and regular accounts can publish which functionalities they implement---either directly or through a proxy contract.

Anyone can query this registry to ask if a specific address implements a given interface and which smart contract handles its implementation.

This registry MAY be deployed on any chain and shares the same address on all chains.

Interfaces with zeroes (0) as the last 28 bytes are considered ERC-165 interfaces, and this registry SHALL forward the call to the contract to see if it implements the interface.

This contract also acts as an ERC-165 cache to reduce gas consumption.

Motivation


There have been different approaches to define pseudo-introspection in Ethereum. The first is ERC-165 which has the limitation that it cannot be used by regular accounts. The second attempt is ERC-672 which uses reverse ENS. Using reverse ENS has two issues. First, it is unnecessarily complicated, and second, ENS is still a centralized contract controlled by a multisig. This multisig theoretically would be able to modify the system.

This standard is much simpler than ERC-672, and it is fully decentralized.

This standard also provides a unique address for all chains. Thus solving the problem of resolving the correct registry address for different chains.

Specification


ERC-820 Registry Smart Contract

This is an exact copy of the code of the ERC820 registry smart contract.


Deployment Transaction

Below is the raw transaction which MUST be used to deploy the smart contract on any chain.


The strings of 820's at the end of the transaction are the r and s of the signature. From this deterministic pattern (generated by a human), anyone can deduce that no one knows the private key for the deployment account.

Deployment Method

This contract is going to be deployed using the keyless deployment method---also known as Nick's method---which relies on a single-use address. (See Nick's article for more details). This method works as follows:

  1. Generate a transaction which deploys the contract from a new random account.
  • This transaction MUST NOT use EIP-155 in order to work on any chain.
  • This transaction MUST have a relatively high gas price to be deployed on any chain. In this case, it is going to be 100 Gwei.
  1. Set the v, r, s of the transaction signature to the following values:

    
    

    Those r and s values---made of a repeating pattern of 820's---are predictable "random numbers" generated deterministically by a human.

    The values of r and s must be 32 bytes long each---or 64 characters in hexadecimal. Since 820 is 3 characters long and 3 is not a divisor of 64, but it is a divisor of 63, the r and s values are padded with one extra character.
    The s value is prefixed with a single zero (0). The 0 prefix also guarantees that s < secp256k1n ÷ 2 + 1.
    The r value, cannot be prefixed with a zero, as the transaction becomes invalid. Instead it is suffixed with a zero (0) which still respects the condition s < secp256k1n.

  2. We recover the sender of this transaction, i.e., the single-use deployment account.

    Thus we obtain an account that can broadcast that transaction, but we also have the warranty that nobody knows the private key of that account.

  3. Send exactly 0.08 ethers to this single-use deployment account.

  4. Broadcast the deployment transaction.

This operation can be done on any chain, guaranteeing that the contract address is always the same and nobody can use that address with a different contract.

Single-use Registry Deployment Account


This account is generated by reverse engineering it from its signature for the transaction. This way no one knows the private key, but it is known that it is the valid signer of the deployment transaction.

To deploy the registry, 0.08 ethers MUST be sent to this account first.

Registry Contract Address


The contract has the address above for every chain on which it is deployed.

Raw metadata of ./contracts/ERC820Registry.sol

Interface Name

Any interface name is hashed using keccak256 and sent to getInterfaceImplementer().

If the interface is part of a standard, it is best practice to explicitly state the interface name and link to this published ERC-820 such that other people don't have to come here to look up these rules.

For convenience, the registry provides a function to compute the hash on-chain:


Compute the keccak256 hash of an interface given its name.

identifier: 65ba36c1
parameters
_interfaceName: Name of the interface.
returns: The keccak256 hash of an interface name.

Approved ERCs

If the interface is part of an approved ERC, it MUST be named ERC###XXXXX where ### is the number of the ERC and XXXXX should be the name of the interface in CamelCase. The meaning of this interface SHOULD be defined in the specified ERC.

Examples:

  • keccak256("ERC20Token")
  • keccak256("ERC777Token")
  • keccak256("ERC777TokensSender")
  • keccak256("ERC777TokensRecipient")

ERC-165 Compatible Interfaces

The compatibility with ERC-165, including the ERC165 Cache, has been designed and developed with William Entriken.

Any interface where the last 28 bytes are zeroes (0) SHALL be considered an ERC-165 interface.

ERC-165 Lookup

Anyone can explicitly check if a contract implements an ERC-165 interface using the registry by calling one of the two functions below:


Checks whether a contract implements an ERC-165 interface or not.

NOTE: The result is cached. If the cache is out of date, it MUST be updated by calling updateERC165Cache. (See ERC165 Cache for more details.)

identifier: f712f3e8
parameters
_contract: Address of the contract to check.
_interfaceId: ERC-165 interface to check.
returns: true if _contract implements _interfaceId, false otherwise.


Checks whether a contract implements an ERC-165 interface or not without using nor updating the cache.

identifier: b7056765
parameters
_contract: Address of the contract to check.
_interfaceId: ERC-165 interface to check.
returns: true if _contract implements _interfaceId, false otherwise.

ERC-165 Cache

Whether a contract implements an ERC-165 interface or not can be cached manually to save gas.

If a contract dynamically changes its interface and relies on the ERC-165 cache of the ERC-820 registry, the cache MUST be updated manually---there is no automatic cache invalidation or cache update. Ideally the contract SHOULD automatically update the cache when changing its interface. However anyone MAY update the cache on the contract's behalf.

The cache update MUST be done using the updateERC165Cache function:


identifier: a41e7d51
parameters
_contract: Address of the contract for which to update the cache.
_interfaceId: ERC-165 interface for which to update the cache.

Private User-defined Interfaces

This scheme is extensible. You MAY make up your own interface name and raise awareness to get other people to implement it and then check for those implementations. Have fun but please, you MUST not conflict with the reserved designations above.

Set An Interface For An Address

For any address to set a contract as the interface implementation, it must call the following function of the ERC-820 registry:


Sets the contract which implements a specific interface for an address.

Only the manager defined for that address can set it. (Each address is the manager for itself, see the manager section for more details.)

NOTE: If _addr and _implementer are two different addresses, then:

  • The _implementer MUST implement the ERC820ImplementerInterface (detailed below).
  • Calling canImplementInterfaceForAddress on _implementer with the given _addr and _interfaceHash MUST return the ERC820_ACCEPT_MAGIC value.

NOTE: The _interfaceHash MUST NOT be an ERC-165 interface---it MUST NOT end with 28 zeroes (0).

NOTE: The _addr MAY be 0, then msg.sender is assumed. This default value simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.

identifier: 29965a1d
parameters
_addr: Address to define the interface for (if _addr == 0 them msg.sender: is assumed)
_interfaceHash: keccak256 hash of the name of the interface as a string, for example web3.utils.keccak256('ERC777TokensRecipient') for the ERC777TokensRecipient interface.
_implementer: Contract implementing _interfaceHash for _addr.

Get An Implementation Of An Interface For An Address

Anyone MAY query the ERC-820 Registry to obtain the address of a contract implementing an interface on behalf of some address using the getInterfaceImplementer function.


Query if an address implements an interface and through which contract.

NOTE: If the last 28 bytes of the _interfaceHash are zeroes (0), then the first 4 bytes are considered an ERC-165 interface and the registry SHALL forward the call to the contract at _addr to see if it implements the ERC-165 interface (the first 4 bytes of _interfaceHash). The registry SHALL also cache ERC-165 queries to reduce gas consumption. Anyone MAY call the erc165UpdateCache function to update whether a contract implements an interface or not.

NOTE: The _addr MAY be 0, then msg.sender is assumed. This default value is consistent with the behavior of the setInterfaceImplementer function and simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.

identifier: aabbb8ca
parameters
_addr: Address being queried for the implementer of an interface. (If _addr == 0 them msg.sender is assumed.)
_interfaceHash: keccak256 hash of the name of the interface as a string. E.g. web3.utils.keccak256('ERC777Token')
returns: The address of the contract which implements the interface _interfaceHash for _addr or 0x0 if _addr did not register an implementer for this interface.

Interface Implementation (ERC820ImplementerInterface)


Any contract being registered as the implementation of an interface for a given address MUST implement said interface. In addition if it implements an interface on behalf of a different address, the contract MUST implement the ERC820ImplementerInterface shown above.


Indicates whether a contract implements an interface (interfaceHash) for a given address (addr).

If a contract implements the interface (interfaceHash) for a given address (addr), it MUST return ERC820_ACCEPT_MAGIC when called with the addr and the interfaceHash. If it does not implement the interfaceHash for a given address (addr), it MUST NOT return ERC820_ACCEPT_MAGIC.

identifier: f0083250
parameters
interfaceHash: Hash of the interface which is implemented
addr: Address for which the interface is implemented
returns: ERC820_ACCEPT_MAGIC only if the contract implements ìnterfaceHash for the address addr.

The special value ERC820_ACCEPT_MAGIC is defined as the keccka256 hash of the string "ERC820_ACCEPT_MAGIC".


The reason to return ERC820_ACCEPT_MAGIC instead of a boolean is to prevent cases where a contract fails to implement the canImplementInterfaceForAddress but implements a fallback function which does not throw. In this case, since canImplementInterfaceForAddress does not exist, the fallback function is called instead, executed without throwing and returns 1. Thus making it appear as if canImplementInterfaceForAddress returned true.

Manager

The manager of an address (regular account or a contract) is the only entity allowed to register implementations of interfaces for the address. By default, any address is its own manager.

The manager can transfer its role to another address by calling setManager on the registry contract with the address for which to transfer the manager and the address of the new manager.

setManager Function


Sets the _newManager as manager for the _addr address.

The new manager will be able to call setInterfaceImplementer for _addr.

If _newManager is 0x0, the manager is reset to _addr itself as the manager.

identifier: 5df8122f
parameters
_addr: Address for which to set the new manager.
_newManager: The address of the new manager for _addr. (Pass 0x0 to reset the manager to _addr.)

getManager Function


Get the manager of an address.

identifier: 3d584063
parameters
_addr: Address for which to return the manager.
returns: Address of the manager for a given address.

Rationale


This standards offers a way for any type of address (externally owned and contracts) to implement an interface and potentially delegate the implementation of the interface to a proxy contract. This delegation to a proxy contract is necessary for externally owned accounts and useful to avoid redeploying existing contracts such as multisigs and DAOs.

The registry can also act as a ERC-165 cache in order to save gas when looking up if a contract implements a specific ERC-165 interface. This cache is intentionally kept simple, without automatic cache update or invalidation. Anyone can easily and safely update the cache for any interface and any contract by calling the updateERC165Cache function.

The registry is deployed using a keyless deployment method relying on a single-use deployment address to ensure no one controls the registry, thereby ensuring trust.

Backward Compatibility


This standard is backward compatible with ERC-165, as both methods MAY be implemented without conflicting with each other.

Test Cases


Please check the jbaylina/ERC820 repository for the full test suite.

Implementation


The implementation is available in the repo: jbaylina/ERC820.

Copyright


Copyright and related rights waived via CC0.