SIP-12: Domain Resolution

Abstract

This SIP proposes a new endowment, endowment:name-lookup, that enables a way for snaps to resolve a domain and address to their respective counterparts.

Motivation

Currently, the MetaMask wallet allows for ENS domain resolution. The implementation is hardcoded and limited to just the ENS protocol. In an effort to increasingly modularize the wallet and allow for resolution beyond ENS, we decided to open up domain/address resolution to snaps. A snap would be able to provide resolution based on a domain or address provided with a chain ID. The address resolution is in essence “reverse resolution”. The functionality provided by this API is also beneficial as a base layer for a petname system (see definition). With plans to bring petnames to MetaMask, resolutions would be fed into the petname system and used as a means for cache invalidation.

Specification

Formal specifications are written in Typescript. Usage of CAIP-N specifications, where N is a number, are references to Chain Agnostic Improvement Proposals.

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” written in uppercase in this document are to be interpreted as described in RFC 2119

Definitions

This section is non-normative, and merely recapitulates some definitions from CAIP-2.

• ChainId - a CAIP-2 string. It identifies a specific chain among all blockchains recognized by the CAIP standards.
  • ChainId consists of a Namespace and a Reference
    • Namespace - a class of similar blockchains. For example EVM-based blockchains.
    • Reference - a way to identify a concrete chain inside a Namespace. For example Ethereum Mainnet or one of its test networks.

• AccountAddress - The account address portion of a CAIP-10 ID.

• Petname system - A naming system that finds balance between global, collision-free and memorable names. Please see this article on this topic.

Snap Manifest

This SIP specifies a permission named endowment:name-lookup. The permission grants a snap the ability to expose an onNameLookup export that receives an object with chainId and domain OR address fields.

This permission is specified as follows in snap.manifest.json files:

{
  "initialPermissions": {
    "endowment:name-lookup": {
        "chains": ["eip155:1", "bip122:000000000019d6689c085ae165831e93"],
    }
  }
}

chains - An array of CAIP-2 chain IDs that the snap supports. This field is useful for a client in order to avoid unnecessary overhead.

Snap Implementation

Please see below for an example implementation of the API:

import { OnNameLookupHandler } from "@metamask/snap-types";

export const onNameLookup: OnNameLookupHandler = async ({
  chainId,
  domain,
  address
}) => {
  if (domain) {
    return { resolvedAddress: /* Get domain resolution */ }
  } 
  
  if (address) {
    return { resolvedDomain: /* Get address resolution */ };
  }

  return null;
};

The type for an onNameLookup handler function’s arguments is:

type OnNameLookupBaseArgs = { 
  chainId: ChainId
}

type DomainLookupArgs = OnNameLookUpBaseArgs & { domain: string; address?: never };
type AddressLookupArgs = OnNameLookUpBaseArgs & { address: string; domain?: never };

type OnNameLookupArgs = DomainLookupArgs | AddressLookupArgs;

chainId - This is a CAIP-2 chainId string. The snap is expected to parse and utilize this string as needed.

domain - This is a human-readable address. If the domain property is defined, the request is looking for resolution to an address.

address - This is a non-readable address, this should be the native address format of the currently selected chain/protocol. If the address property is defined, the request is looking for resolution to a domain.

The interface for the return value of an onNameLookup export is:

type OnNameLookupResponse =
  | {
      resolvedAddress: AccountAddress;
      resolvedDomain?: never;
    }
  | { resolvedDomain: string; resolvedAddress?: never }
  | null;

Note: resolvedDomain and resolvedAddress MUST be the keys that the resolved address/domain being queried is indexed by in the protocol that the snap is resolving for. These returned values are un-opinionated at the API layer to allow the client to use them as they see fit.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Hassan Malik, "SIP-12: Domain Resolution [DRAFT]," Snaps Improvement Proposals, no. 12, July 2023. [Online serial]. Available: https://github.com/MetaMask/SIPs/blob/master/SIPS/sip-12.md