210 lines
9.2 KiB
Markdown
210 lines
9.2 KiB
Markdown
---
|
|
eip: 181
|
|
title: ENS support for reverse resolution of Ethereum addresses
|
|
author: Nick Johnson <arachnid@notdot.net>
|
|
status: Final
|
|
type: Standards Track
|
|
category: ERC
|
|
created: 2016-12-01
|
|
---
|
|
|
|
# Abstract
|
|
This EIP specifies a TLD, registrar, and resolver interface for reverse resolution of Ethereum addresses using ENS. This permits associating a human-readable name with any Ethereum blockchain address. Resolvers can be certain that the reverse record was published by the owner of the Ethereum address in question.
|
|
|
|
# Motivation
|
|
While name services are mostly used for forward resolution - going from human-readable identifiers to machine-readable ones - there are many use-cases in which reverse resolution is useful as well:
|
|
|
|
- Applications that allow users to monitor accounts benefit from showing the name of an account instead of its address, even if it was originally added by address.
|
|
- Attaching metadata such as descriptive information to an address allows retrieving this information regardless of how the address was originally discovered.
|
|
- Anyone can configure a name to resolve to an address, regardless of ownership of that address. Reverse records allow the owner of an address to claim a name as authoritative for that address.
|
|
|
|
# Specification
|
|
Reverse ENS records are stored in the ENS hierarchy in the same fashion as regular records, under a reserved domain, `addr.reverse`. To generate the ENS name for a given account's reverse records, convert the account to hexadecimal representation in lower-case, and append `addr.reverse`. For instance, the ENS registry's address at `0x112234455c3a32fd11230c42e7bccd4a84e02010` has any reverse records stored at `112234455c3a32fd11230c42e7bccd4a84e02010.addr.reverse`.
|
|
|
|
Note that this means that contracts wanting to do dynamic reverse resolution of addresses will need to perform hex encoding in the contract.
|
|
|
|
## Registrar
|
|
The owner of the `addr.reverse` domain will be a registrar that permits the caller to take ownership of
|
|
the reverse record for their own address. It provides the following methods:
|
|
|
|
### function claim(address owner) returns (bytes32 node)
|
|
|
|
When called by account `x`, instructs the ENS registry to transfer ownership of the name `hex(x) + '.addr.reverse'` to the provided address, and return the namehash of the ENS record thus transferred.
|
|
|
|
Allowing the caller to specify an owner other than themselves for the relevant node facilitates contracts that need accurate reverse ENS entries delegating this to their creators with a minimum of code inside their constructor:
|
|
|
|
reverseRegistrar.claim(msg.sender)
|
|
|
|
### function claimWithResolver(address owner, address resolver) returns (bytes32 node)
|
|
|
|
When called by account `x`, instructs the ENS registry to set the resolver of the name `hex(x) + '.addr.reverse'` to the specified resolver, then transfer ownership of the name to the provided address, and return the namehash of the ENS record thus transferred. This method facilitates setting up a custom resolver and owner in fewer transactions than would be required if calling `claim`.
|
|
|
|
### function setName(string name) returns (bytes32 node)
|
|
|
|
When called by account `x`, sets the resolver for the name `hex(x) + '.addr.reverse'` to a default resolver, and sets the name record on that name to the specified name. This method facilitates setting up simple reverse records for users in a single transaction.
|
|
|
|
## Resolver interface
|
|
A new resolver interface is defined, consisting of the following method:
|
|
|
|
function name(bytes32 node) constant returns (string);
|
|
|
|
Resolvers that implement this interface must return a valid ENS name for the requested node, or the empty string if no name is defined for the requested node.
|
|
|
|
The interface ID of this interface is 0x691f3431.
|
|
|
|
Future EIPs may specify more record types appropriate to reverse ENS records.
|
|
|
|
# Appendix 1: Registrar implementation
|
|
|
|
This registrar, written in Solidity, implements the specifications outlined above.
|
|
|
|
pragma solidity ^0.4.10;
|
|
|
|
import "./AbstractENS.sol";
|
|
|
|
contract Resolver {
|
|
function setName(bytes32 node, string name) public;
|
|
}
|
|
|
|
/**
|
|
* @dev Provides a default implementation of a resolver for reverse records,
|
|
* which permits only the owner to update it.
|
|
*/
|
|
contract DefaultReverseResolver is Resolver {
|
|
AbstractENS public ens;
|
|
mapping(bytes32=>string) public name;
|
|
|
|
/**
|
|
* @dev Constructor
|
|
* @param ensAddr The address of the ENS registry.
|
|
*/
|
|
function DefaultReverseResolver(AbstractENS ensAddr) {
|
|
ens = ensAddr;
|
|
}
|
|
|
|
/**
|
|
* @dev Only permits calls by the reverse registrar.
|
|
* @param node The node permission is required for.
|
|
*/
|
|
modifier owner_only(bytes32 node) {
|
|
require(msg.sender == ens.owner(node));
|
|
_;
|
|
}
|
|
|
|
/**
|
|
* @dev Sets the name for a node.
|
|
* @param node The node to update.
|
|
* @param _name The name to set.
|
|
*/
|
|
function setName(bytes32 node, string _name) public owner_only(node) {
|
|
name[node] = _name;
|
|
}
|
|
}
|
|
|
|
contract ReverseRegistrar {
|
|
// namehash('addr.reverse')
|
|
bytes32 constant ADDR_REVERSE_NODE = 0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2;
|
|
|
|
AbstractENS public ens;
|
|
Resolver public defaultResolver;
|
|
|
|
/**
|
|
* @dev Constructor
|
|
* @param ensAddr The address of the ENS registry.
|
|
* @param resolverAddr The address of the default reverse resolver.
|
|
*/
|
|
function ReverseRegistrar(AbstractENS ensAddr, Resolver resolverAddr) {
|
|
ens = ensAddr;
|
|
defaultResolver = resolverAddr;
|
|
}
|
|
|
|
/**
|
|
* @dev Transfers ownership of the reverse ENS record associated with the
|
|
* calling account.
|
|
* @param owner The address to set as the owner of the reverse record in ENS.
|
|
* @return The ENS node hash of the reverse record.
|
|
*/
|
|
function claim(address owner) returns (bytes32 node) {
|
|
return claimWithResolver(owner, 0);
|
|
}
|
|
|
|
/**
|
|
* @dev Transfers ownership of the reverse ENS record associated with the
|
|
* calling account.
|
|
* @param owner The address to set as the owner of the reverse record in ENS.
|
|
* @param resolver The address of the resolver to set; 0 to leave unchanged.
|
|
* @return The ENS node hash of the reverse record.
|
|
*/
|
|
function claimWithResolver(address owner, address resolver) returns (bytes32 node) {
|
|
var label = sha3HexAddress(msg.sender);
|
|
node = sha3(ADDR_REVERSE_NODE, label);
|
|
var currentOwner = ens.owner(node);
|
|
|
|
// Update the resolver if required
|
|
if(resolver != 0 && resolver != ens.resolver(node)) {
|
|
// Transfer the name to us first if it's not already
|
|
if(currentOwner != address(this)) {
|
|
ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, this);
|
|
currentOwner = address(this);
|
|
}
|
|
ens.setResolver(node, resolver);
|
|
}
|
|
|
|
// Update the owner if required
|
|
if(currentOwner != owner) {
|
|
ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, owner);
|
|
}
|
|
|
|
return node;
|
|
}
|
|
|
|
/**
|
|
* @dev Sets the `name()` record for the reverse ENS record associated with
|
|
* the calling account. First updates the resolver to the default reverse
|
|
* resolver if necessary.
|
|
* @param name The name to set for this address.
|
|
* @return The ENS node hash of the reverse record.
|
|
*/
|
|
function setName(string name) returns (bytes32 node) {
|
|
node = claimWithResolver(this, defaultResolver);
|
|
defaultResolver.setName(node, name);
|
|
return node;
|
|
}
|
|
|
|
/**
|
|
* @dev Returns the node hash for a given account's reverse records.
|
|
* @param addr The address to hash
|
|
* @return The ENS node hash.
|
|
*/
|
|
function node(address addr) constant returns (bytes32 ret) {
|
|
return sha3(ADDR_REVERSE_NODE, sha3HexAddress(addr));
|
|
}
|
|
|
|
/**
|
|
* @dev An optimised function to compute the sha3 of the lower-case
|
|
* hexadecimal representation of an Ethereum address.
|
|
* @param addr The address to hash
|
|
* @return The SHA3 hash of the lower-case hexadecimal encoding of the
|
|
* input address.
|
|
*/
|
|
function sha3HexAddress(address addr) private returns (bytes32 ret) {
|
|
addr; ret; // Stop warning us about unused variables
|
|
assembly {
|
|
let lookup := 0x3031323334353637383961626364656600000000000000000000000000000000
|
|
let i := 40
|
|
loop:
|
|
i := sub(i, 1)
|
|
mstore8(i, byte(and(addr, 0xf), lookup))
|
|
addr := div(addr, 0x10)
|
|
i := sub(i, 1)
|
|
mstore8(i, byte(and(addr, 0xf), lookup))
|
|
addr := div(addr, 0x10)
|
|
jumpi(loop, i)
|
|
ret := sha3(0, 40)
|
|
}
|
|
}
|
|
}
|
|
|
|
## Copyright
|
|
Copyright and related rights waived via [CC0](../LICENSE.md).
|