ENSIP-16: Metadata Event Discovery

Abstract

This ENSIP specifies APIs for querying metadata directly on the resolver for EIP-3668 (CCIP Read: Secure offchain data retrieval) enabled names. EIP-3668 will power many domains in the future, however since the retrieval mechanism uses wildcard + offchain resolver, there is no standardised way to retrieve important metadata information such as which L2/offchain database the records are stored on and where JSON RPC endpoint is to find event log information.

Motivation

With EIP-3668 subdomains already starting to see wide adoption, it is important that there is a standardised way for different stakeholders to discover and access metadata about offchain names.

This ENSIP addresses two critical use cases:

Data Indexers: Third-party indexing services can use the MetadataChanged event to automatically discover which chain and smart contract address will emit metadata events. This allows indexers to dynamically discover new data sources and begin indexing them without manual configuration, enabling comprehensive coverage of the ENS ecosystem.

Name Owners with Custom Storage: For name owners who store records in traditional databases (RDBMS) or non-EVM compatible chains, this ENSIP provides a way to expose metadata with a common JSON RPC interface. This allows these systems to present metadata in the same format as EVM-based event logs, allowing data indexers to index records on non-EVM compatible chains.

Specification

Resolver implements the following Solidity interface:

// To be included in
// https://github.com/ensdomains/ens-contracts/blob/staging/contracts/resolvers/Resolver.sol
interface IOffchainResolverMetadataProvider {

    /**
     * @dev Returns metadata for discovering the location of offchain name data
     * @param name DNS-encoded name to query
     * @return rpcURLs The JSON RPC endpoint for querying offchain data
     * @return chainId The chain ID where the data is stored (optional)
     * @return baseRegistry The base registry address on the target chain that emits events.
     */
    function metadata(bytes calldata name)
        external
        view
        returns (
            string[] memory rpcURLs,
            uint256 chainId,
            address baseRegistry
        );

    event MetadataChanged(
        bytes name,              // DNS-encoded name
        string[] rpcURLs,        // JSON RPC endpoint
        uint256 chainId,         // Chain identifier (optional)
        address baseRegistry     // Base registry address
    );
}

metadata function

The metadata function allows resolvers to dynamically provide information about where offchain data for a given name can be queried. This function returns the same information as would be emitted in a MetadataChanged event: the JSON RPC endpoint URLs, the chain ID where the data resides, and the base registry address on the target chain.

Requirements:

At least one of chainId OR rpcURLs MUST be provided
If both chainId and rpcURLs are provided, indexers and applications MAY choose to use the provided RPC URL(s) or their own RPC endpoint for that chain
chainId SHOULD be set to 0 for non-EVM sources or entirely offchain implementations
For EVM-compatible chains, chainId SHOULD match the chain's EIP-155 identifier

MetadataChanged Event

The MetadataChanged event allows resolvers to signal where offchain metadata can be queried. When the data is stored on other EVM compatible chains, it can specify chain id and its base registry address so that indexers can dynamically discover the new source and start indexing.

Event Schema Standardization

All L2 registry and resolver implementations MUST emit events matching the schema defined below to ensure compatibility with general-purpose indexing infrastructure. This event schema is designed to match the one used by ENS v2 on L1 and Namechain, enabling indexers to use consistent logic across all chains.

For entirely offchain name providers, synthetic JSON-RPC endpoints MUST return events in this same format, allowing indexers to reconstruct metadata without requiring chain-specific integration.

JSON RPC Events

JSON RPC endpoint must implement the following Solidity events. The endpoints must encode these events following EIP-1474 eth_getLogs standard.

Key Terminology:

registry = A contract that manages name ownership and hierarchical relationships for a set of subnames. The base registry manages top-level domains (also known as root registry within the v2 contract), while subregistries manage names under a specific parent
subregistry = A registry contract that manages subnames under a parent name. Linked from a parent registry via SubregistryUpdate events
registry id/tokenId = The unique identifier for a name NFT, derived from the labelhash and version id that increments every time the permission of the name changes effectively invalidating any permissions or approvals tied to the old token ID.

Registry Events

// Emitted when a new subname is registered. a subname without expiration should set type(uint256).max
event NameRegistered(uint256 indexed tokenId, string label, uint64 expiration, address registeredBy);
// Emitted when a new token id is generated
event TokenRegenerated(uint256 oldTokenId, uint256 newTokenId);

// Standard ERC1155 transfer event for name ownership changes
event TransferSingle(
    address indexed operator,
    address indexed from,
    address indexed to,
    uint256 id,
    uint256 value // must always be 1
);

// Standard ERC1155 transfer event for multiple name ownership changes
event TransferBatch(
  address indexed operator,
  address indexed from,
  address indexed to,
  uint256[] ids,
  uint256[] values
);

// Standard ERC721 transfer event for name ownership changes
event Transfer(
  address indexed from,
  address indexed to,
  uint256 tokenId
);

// Emitted when subregistry is updated
event SubregistryUpdate(
    uint256 indexed id,
    address subregistry
);

// Emitted when resolver is updated
event ResolverUpdate(
    uint256 indexed id,
    address resolver
);

TODO: Add events to keep track of expiry of all names (expiry on subnames are optional).

NOTE: Even though ENS v2 registry contract is ERC1155 (TransferSingle, TransferBatch), ERC721 events(Transfer) are also accepted if name owner choose to build their own registry with an NFT capability.

Resolver Events

event AddressChanged(
    bytes32 indexed node,
    uint256 coinType,
    bytes newAddress
);

event AddrChanged(
  bytes32 indexed node,
  address a
);

event TextChanged(
    bytes32 indexed node,
    string indexed indexedKey,
    string key,
    string value
);

event ContenthashChanged(
  bytes32 indexed node,
  bytes hash
);

NOTE: In ENS v1, a resolver has a node property which is derived by the hash of subname and node of its parent name using namehash algorithm. In ENS v2 system, a resolver is used by a single registry which may have multiple parent registries. For example, a registry has a label called foo that has parent registry of eth and xyz, providing name for both foo.eth and foo.xyz. For a resolver to represent records for multiple names, the node of the v2 resolver is kept as 0x indicating that the node needs to be derived by combining the label information of the registry traversing from the subname all the way to the base/root registry. If a name owner choose to use their own contract with single registry and resolver, the node can be the namehash of the name as in v1.

Indexer API Representation

This ENSIP specifies how to discover and index event data for ENS names across different chains and storage systems. However, it does not dictate the specific API format that indexers must use to expose their indexed data to applications.