@anomsci/resolution v1.1.0

Resolution

@anomsci/resolution | A simple resolution library for Ethereum Name Service (ENS) domains.

Getting Started

This library supports the resolution of Ethereum Name Service (ENS) names and subnames. The resolver contracts used to resolve names are auto-detected via calls to the ENS Registry contract. Resolution results include a name's records, token data, and parent name data in the case of subnames. To get started, install the library:

npm install @anomsci/resolution

Dependencies: The @adraffy/ens-normalize library is used for ENS name normalization, content-hash for EIP 1577 contenthash decoding, dotenv for the RPC provider environment variable, eth-fetch for Ethereum smart contract calls & provider instance, js-yaml for parsing the YAML config, and keccak for keccak256 hashing.

Usage

A resolve object is exported by the library, which contains two methods for resolution: default, and noParent. Both methods require a name parameter be provided, which is expected to be an ENS name, and also contain optional useMulticall and withFallback parameters, both expecting a true/false value.

// Default Resolution
resolve.default(ensName, useMulticall = true, withFallback = false);

// No Parent Resolution
resolve.noParent(ensName, useMulticall = true, withFallback = false);

Under the default resolution method, the provided name will have its token data, records, and in the case of subnames, parent name data resolved. The noParent resolution method provides the same, except with the exclusion of the parent data resolution. The useMulticall parameter determines if a multicall will be used instead of separate calls to the resolver contract to resolve the name's address, content, and text records. When true, a multicall will be used, and if false, resolution will default to the fallback option (separate calls). The withFallback parameter determines if the fallback option should be attempted in the case of a failed multicall. When true, the fallback will be attempted, and when false no fallback will be attempted after a failed multicall. A cause for a failed multicall may include the resolver contract not supporting multicall functionality. No fallback can be attempted when a multicall is not used.

Example Use

In this example use, resolve is imported from @anomsci/resolution, and the default method is used to resolve the name ethereum.eth. A multicall is used for the resolver calls by setting useMulticall to true, and the fallback option is disabled by setting withFallback to false.

const resolve = require('@anomsci/resolution');

resolve.default('ethereum.eth', true, true)
    .then(console.log);

// Sample Output:
// {"owner":"0x899FcB1437DE65DC6315f5a69C017dd3F2837557","manager":"0xAd2e180019FCa9e55CADe76E4487F126Fd08DA34","text":{"avatar":"https://euc.li/ethereum.eth"},"tokenId":"38024433996008673239128445693334039761881177377983244511636310112901938893141","status":"unwrapped"}

Resolution Results

The resolution results for any name will contain information about the name ownership/management, the name's records (address, content, text), tokenId, wrapper status, and parent name information for subnames. Resolution results are returned as a JSON object. When the noParent method of resolve is used, parent name resolution is not completed, and the parent object is not returned in the resolution results for subnames.

{
    "owner": "OWNER_ADDRESS",
    "manager": "MANAGER_ADDRESS",
    "address": "ADDRESS_RECORD",
    "content": {
        "type": "ipfs",
        "name": "IPFS_CID"
    },
    "text": {
        "avatar": "AVATAR_URL",
        "url": "URL"
    },
    "tokenId": "TOKEN_ID",
    "status": "WRAPPER_STATUS",
    "parent": {
        "owner": "PARENT_OWNER",
        "manager": "PARENT_MANAGER",
        "tokenId": "PARENT_TOKEN_ID",
        "status": "PARENT_WRAPPER_STATUS"
    }
}

• owner: Token holder address returned via an ownerOf() call to the ENS Name Wrapper or Registrar contract with the name's tokenId.
• manager: Owner address returned via an owner() call to the ENS registry.
• address: Address record returned via an addr() call to the name's resolver.*
• content: The decoded content hash returned via a contenthash() call to the name's resolver.*
• text: Text records based on the textKeys in the config returned via a getText() call to the name's resolver.*
• tokenId: The calculated tokenId based on the namehash or labelhash of the name.
• status: Name Wrapper status. Either wrapped or unwrapped.
• parent: In cases of subname resolution, this corresponds to the token data of the parent name (e.g.. for the subname sub.example.eth, the parent is example.eth). The returned token data includes the owner, manager, tokenId, and status of the parent name.

*These calls are combined into a multicall, when useMulticall is true.

Config

To use the resolve function, an Ethereum Mainnet connection is required. This is set through the RPC_URL variable in the .env, where you can specify your HTTP JSON-RPC provider URL.

# URL for your Ethereum Mainnet JSON RPC Interface
RPC_URL=<YOUR_RPC_URL>

The library can be configured from the config.yaml. This contains the ABI for the calls used to different contracts in the resolution process, contract addresses, the textKeys used for resolving text records, and name of the .env variable for the provider URL. By default, the config contains the ABI for the owner(), addr(), contenthash(), and ownerOf() calls, contract addresses for the ENS registry, name wrapper, and registrar, and text keys corresponding to the Global Keys specified under ERC-634: Storage of text records in ENS. The default .env variable name for the provider URL is RPC_URL.

Default config.yaml:

abi:
  registry:
    - "function resolver(bytes32 node) public view returns (address)"
    - "function owner(bytes32 node) external view returns (address)"
  resolver:
    - "function multicall(bytes[] calldata data) external returns(bytes[] memory results)"
    - "function addr(bytes32) view returns (address)"
    - "function contenthash(bytes32) view returns (bytes)"
    - "function text(bytes32,string) view returns (string)"
  name_wrapper:
    - "function ownerOf(uint256 id) view returns (address owner)"
  registrar:
    - "function ownerOf(uint256 tokenId) view returns (address)"

contracts:
  registry: "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e"
  name_wrapper: "0xD4416b13d2b3a9aBae7AcD5D6C2BbDBE25686401"
  registrar: "0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85"

textKeys:
  - "avatar"
  - "description"
  - "display"
  - "email"
  - "keywords"
  - "mail"
  - "notice"
  - "location"
  - "phone"
  - "url"

providerConfig:
  rpcEnv: "RPC_URL"