Jsonrpc

ensips/16.md

@@ -1,185 +1,178 @@
 ---
-description: Allows metadata to be queried on EIP-3668 enabled names
+description: Provides a discovery mechanism for metadata for names resolved via EIP-3668
 contributors:
   - jefflau
-  - makoto
+  - matoken.eth
 ensip:
   status: draft
   created: 2022-09-22
+  updated: 2025-10-06
 ignoredRules: ["heading:implementation", "heading:open-items"]
 ---
 
-# ENSIP-16: Offchain Metadata
+# 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 of the 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 the owner (who can change the records), or which L2/offchain database the records are stored on.
+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 way for frontend interfaces to get important metadata to allow a smooth user experience. For instance a UI needs to be able to check if the currently connected user has the right to update an EIP-3668 name.
+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 this by adding a way of important metadata to be gathered on the offchain resolver, which would likely revert and be also resolved offchain, however there is an option for it to be also left onchain if there value was static and wouldn't need to be changed often.
+This ENSIP addresses two critical use cases:
 
-## Specification
-
-The metadata should include 2 different types of info
-
-- Offchain data storage location related info: `graphqlUrl` includes the URL to fetch the metadata.
-
-- Ownership related info: `owner`, `isApprovedForAll` defines who can own or update the given record.
-
-### Context
-
-An optional field "context" is introduced by utilizing an arbitrary bytes string to define the namespace to which a record belongs.
-
-For example, this "context" can refer to the address of the entity that has set a particular record. By associating records with specific addresses, users can confidently manage their records in a trustless manner on Layer 2 without direct access to the ENS Registry contract on the Ethereum mainnet. Please refer to [ENS-Bedrock-Resolver](https://github.com/corpus-io/ENS-Bedrock-Resolver#context) for the reference integration
-
-### Dynamic Metadata
+**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.
 
-Metadata serves a crucial role in providing valuable insights about a node owner and their specific resolver. In certain scenarios, resolvers may choose to adopt diverse approaches to resolve data based on the node. An example of this would be handling subdomains of a particular node differently. For instance, we could resolve "optimism.foo.eth" using a contract on optimism and "gnosis.foo.eth" using a contract on gnosis.
-By passing the name through metadata, we empower the resolution process, enabling CcipResolve flows to become remarkably flexible and scalable. This level of adaptability ensures that our system can accommodate a wide array of use cases, making it more user-friendly and accommodating for a diverse range of scenarios.
+**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.
 
-## Implementation
+## Specification
 
-### L1
+Resolver implements the following Solidity interface:
 
 ```solidity
 // To be included in
 // https://github.com/ensdomains/ens-contracts/blob/staging/contracts/resolvers/Resolver.sol
-interface IOffChainResolver {
-    /** @dev Returns the owner of the resolver on L2
-     * @param node
-     * @return owner in bytes32 instead of address to cater for non EVM based owner information
-     */
-    owner(bytes32 node) returns (bytes owner);
+interface IOffchainResolverMetadataProvider {
 
-    // optional.
-    // this returns data via l2 with EIP-3668 so that non EVM chains can also return information of which address can update the record
-    // The same function name exists on L2 where delegate returns address instead of bytes
-    function isApprovedFor(bytes context, bytes32 node, bytes delegate) returns (bool);
-
-    /** @dev Returns the metadata of the resolver on L2
-     * @return graphqlUrl url of graphql endpoint that provides additional information about the offchain name and its subdomains
+    /**
+     * @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)
-    {
-        return (graphqlUrl);
-    }
+        returns (
+            string[] memory rpcURLs,
+            uint256 chainId,
+            address baseRegistry
+        );
 
-    // Optional. If context is dynamic, the event won't be emitted.
     event MetadataChanged(
-        string name,
-        string graphqlUrl,
+        bytes name,              // DNS-encoded name
+        string[] rpcURLs,        // JSON RPC endpoint
+        uint256 chainId,         // Chain identifier (optional)
+        address baseRegistry     // Base registry address
     );
 }
 ```
 
-### L2 (EVM compatible chain only)
+### metadata function
 
-```solidity
-// To be included in the contract returned by `metadata` function `storageLocation`
-interface IL2Resolver {
-    /**
-     * @dev Check to see if the delegate has been approved by the context for the node.
-     *
-     * @param context = an arbitrary bytes string to define the namespace to which a record belongs such as the name owner.
-     * @param node
-     * @param delegate = an address that is allowed to update record under context
-     */
-    function isApprovedFor(bytes context,bytes32 node,address delegate) returns (bool);
+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.
 
-    event Approved(
-        bytes context,
-        bytes32 indexed node,
-        address indexed delegate,
-        bool indexed approved
-    );
-}
-```
+**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
 
-```javascript
-const node = namehash('ccipreadsub.example.eth')
-const resolver = await ens.resolver(node)
-const owner = await resolver.owner(node)
-// 0x123...
-const dataLocation = await.resolver.graphqlUrl()
-// {
-//   url: 'http://example.com/ens/graphql',
-// }
-```
 
-#### GraphQL schema
+### MetadataChanged Event
 
-[GraphQL](https://graphql.org) is a query language for APIs and a runtime for fulfilling those queries with onchain event data. You can use the hosted/decentralised indexing service such as [The Graph](https://thegraph.com), [Goldsky](https://docs.goldsky.com/introduction), [QuickNode](https://marketplace.quicknode.com/add-on/subgraph-hosting) or host your own using The Graph, or [ponder](https://ponder.sh)
+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.
 
-#### L1
+### Event Schema Standardization
 
-`Metadata` is an optional schema that indexes `MetadataChanged` event.
+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.
 
-```graphql
+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.
 
-type Domain @entity{
-  id
-  metadata: Metadata
-}
+### JSON RPC Events
 
-type Metadata @entity {
-  "l1 resolver address"
-  id: ID!
-  "Name of the Chain"
-  name: String
-  "url of the graphql endpoint"
-  graphqlUrl: String
-}
+JSON RPC endpoint must implement the following Solidity events. The endpoints must encode these events following [EIP-1474 eth_getLogs](https://eips.ethereum.org/EIPS/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.
 
-#### L2
-
-L2 graphql URL is discoverable via `metadata` function `graphqlUrl` field.
-Because the canonical ownership of the name exists on L1, some L2/offchain storage may choose to allow multiple entities to update the same node namespaced by `context`. When querying the domain data, the query should be filtered by `context` that is returned by `metadata`function `context` field
-
-```graphql
-type Domain {
-  id: ID! # concatenation of context and namehash delimited by `-`
-  context: Bytes
-  name: String
-  namehash: Bytes
-  labelName: String
-  labelhash: Bytes
-  resolvedAddress: Bytes
-  parent: Domain
-  subdomains: [Domain]
-  subdomainCount: Int!
-  resolver: Resolver!
-  expiryDate: BigInt
-}
+#### Registry Events
 
-type Resolver @entity {
-  id: ID! # concatenation of node, resolver address and context delimited by `-`
-  node: Bytes
-  context: Bytes
-  address: Bytes
-  domain: Domain
-  addr: Bytes
-  contentHash: Bytes
-  texts: [String!]
-  coinTypes: [BigInt!]
-}
+```solidity
+// Emitted when a new subname is registered
+event NewSubname(bytes32 indexed tokenId, string label);
+// 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
+);
 ```
 
-## Backwards Compatibility
+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
+
+```solidity
+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
+);
+```
 
-None
+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.
 
-## Open Items
+### Indexer API Representation
 
-- Should `owner` and `isApprovedForAll` be within graphql or should be own metadata function?
+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.
 
 ## Copyright
 
-Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).