@metamask/ens-controller 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0]
+### Added
+- Initial release
+  - As a result of converting our shared controllers repo into a monorepo ([#831](https://github.com/MetaMask/controllers/pull/831)), we've created this package from select parts of [`@metamask/controllers` v33.0.0](https://github.com/MetaMask/controllers/tree/v33.0.0), namely:
+    - `src/third-party/EnsController.ts`
+    - `src/third-party/EnsController.test.ts`
+
+    All changes listed after this point were applied to this package following the monorepo conversion.
+
+[Unreleased]: https://github.com/MetaMask/controllers/compare/@metamask/ens-controller@1.0.0...HEAD
+[1.0.0]: https://github.com/MetaMask/controllers/releases/tag/@metamask/ens-controller@1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2018 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

package/README.md

@@ -0,0 +1,15 @@
+# `@metamask/ens-controller`
+
+Maps ENS names to their resolved addresses by chain id.
+
+## Installation
+
+`yarn add @metamask/ens-controller`
+
+or
+
+`npm install @metamask/ens-controller`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/controllers#readme).

package/dist/EnsController.d.ts

@@ -0,0 +1,76 @@
+import { BaseController, BaseConfig, BaseState } from '@metamask/base-controller';
+/**
+ * @type EnsEntry
+ *
+ * ENS entry representation
+ * @property chainId - Id of the associated chain
+ * @property ensName - The ENS name
+ * @property address - Hex address with the ENS name, or null
+ */
+export interface EnsEntry {
+    chainId: string;
+    ensName: string;
+    address: string | null;
+}
+/**
+ * @type EnsState
+ *
+ * ENS controller state
+ * @property ensEntries - Object of ENS entry objects
+ */
+export interface EnsState extends BaseState {
+    ensEntries: {
+        [chainId: string]: {
+            [ensName: string]: EnsEntry;
+        };
+    };
+}
+/**
+ * Controller that manages a list ENS names and their resolved addresses
+ * by chainId. A null address indicates an unresolved ENS name.
+ */
+export declare class EnsController extends BaseController<BaseConfig, EnsState> {
+    /**
+     * Name of this controller used during composition
+     */
+    name: string;
+    /**
+     * Creates an EnsController instance.
+     *
+     * @param config - Initial options used to configure this controller.
+     * @param state - Initial state to set on this controller.
+     */
+    constructor(config?: Partial<BaseConfig>, state?: Partial<EnsState>);
+    /**
+     * Remove all chain Ids and ENS entries from state.
+     */
+    clear(): void;
+    /**
+     * Delete an ENS entry.
+     *
+     * @param chainId - Parent chain of the ENS entry to delete.
+     * @param ensName - Name of the ENS entry to delete.
+     * @returns Boolean indicating if the entry was deleted.
+     */
+    delete(chainId: string, ensName: string): boolean;
+    /**
+     * Retrieve a DNS entry.
+     *
+     * @param chainId - Parent chain of the ENS entry to retrieve.
+     * @param ensName - Name of the ENS entry to retrieve.
+     * @returns The EnsEntry or null if it does not exist.
+     */
+    get(chainId: string, ensName: string): EnsEntry | null;
+    /**
+     * Add or update an ENS entry by chainId and ensName.
+     *
+     * A null address indicates that the ENS name does not resolve.
+     *
+     * @param chainId - Id of the associated chain.
+     * @param ensName - The ENS name.
+     * @param address - Associated address (or null) to add or update.
+     * @returns Boolean indicating if the entry was set.
+     */
+    set(chainId: string, ensName: string, address: string | null): boolean;
+}
+export default EnsController;

package/dist/EnsController.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsController = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+const controller_utils_1 = require("@metamask/controller-utils");
+/**
+ * Controller that manages a list ENS names and their resolved addresses
+ * by chainId. A null address indicates an unresolved ENS name.
+ */
+class EnsController extends base_controller_1.BaseController {
+    /**
+     * Creates an EnsController instance.
+     *
+     * @param config - Initial options used to configure this controller.
+     * @param state - Initial state to set on this controller.
+     */
+    constructor(config, state) {
+        super(config, state);
+        /**
+         * Name of this controller used during composition
+         */
+        this.name = 'EnsController';
+        this.defaultState = { ensEntries: {} };
+        this.initialize();
+    }
+    /**
+     * Remove all chain Ids and ENS entries from state.
+     */
+    clear() {
+        this.update({ ensEntries: {} });
+    }
+    /**
+     * Delete an ENS entry.
+     *
+     * @param chainId - Parent chain of the ENS entry to delete.
+     * @param ensName - Name of the ENS entry to delete.
+     * @returns Boolean indicating if the entry was deleted.
+     */
+    delete(chainId, ensName) {
+        const normalizedEnsName = (0, controller_utils_1.normalizeEnsName)(ensName);
+        if (!normalizedEnsName ||
+            !this.state.ensEntries[chainId] ||
+            !this.state.ensEntries[chainId][normalizedEnsName]) {
+            return false;
+        }
+        const ensEntries = Object.assign({}, this.state.ensEntries);
+        delete ensEntries[chainId][normalizedEnsName];
+        if (Object.keys(ensEntries[chainId]).length === 0) {
+            delete ensEntries[chainId];
+        }
+        this.update({ ensEntries });
+        return true;
+    }
+    /**
+     * Retrieve a DNS entry.
+     *
+     * @param chainId - Parent chain of the ENS entry to retrieve.
+     * @param ensName - Name of the ENS entry to retrieve.
+     * @returns The EnsEntry or null if it does not exist.
+     */
+    get(chainId, ensName) {
+        const normalizedEnsName = (0, controller_utils_1.normalizeEnsName)(ensName);
+        // TODO Explicitly handle the case where `normalizedEnsName` is `null`
+        // eslint-disable-next-line no-implicit-coercion
+        return !!normalizedEnsName && this.state.ensEntries[chainId]
+            ? this.state.ensEntries[chainId][normalizedEnsName] || null
+            : null;
+    }
+    /**
+     * Add or update an ENS entry by chainId and ensName.
+     *
+     * A null address indicates that the ENS name does not resolve.
+     *
+     * @param chainId - Id of the associated chain.
+     * @param ensName - The ENS name.
+     * @param address - Associated address (or null) to add or update.
+     * @returns Boolean indicating if the entry was set.
+     */
+    set(chainId, ensName, address) {
+        if (!Number.isInteger(Number.parseInt(chainId, 10)) ||
+            !ensName ||
+            typeof ensName !== 'string' ||
+            (address && !(0, controller_utils_1.isValidHexAddress)(address))) {
+            throw new Error(`Invalid ENS entry: { chainId:${chainId}, ensName:${ensName}, address:${address}}`);
+        }
+        const normalizedEnsName = (0, controller_utils_1.normalizeEnsName)(ensName);
+        if (!normalizedEnsName) {
+            throw new Error(`Invalid ENS name: ${ensName}`);
+        }
+        const normalizedAddress = address ? (0, controller_utils_1.toChecksumHexAddress)(address) : null;
+        const subState = this.state.ensEntries[chainId];
+        if ((subState === null || subState === void 0 ? void 0 : subState[normalizedEnsName]) &&
+            subState[normalizedEnsName].address === normalizedAddress) {
+            return false;
+        }
+        this.update({
+            ensEntries: Object.assign(Object.assign({}, this.state.ensEntries), { [chainId]: Object.assign(Object.assign({}, this.state.ensEntries[chainId]), { [normalizedEnsName]: {
+                        address: normalizedAddress,
+                        chainId,
+                        ensName: normalizedEnsName,
+                    } }) }),
+        });
+        return true;
+    }
+}
+exports.EnsController = EnsController;
+exports.default = EnsController;
+//# sourceMappingURL=EnsController.js.map

package/dist/EnsController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnsController.js","sourceRoot":"","sources":["../src/EnsController.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BaseController,\n  BaseConfig,\n  BaseState,\n} from '@metamask/base-controller';\nimport {\n  normalizeEnsName,\n  isValidHexAddress,\n  toChecksumHexAddress,\n} from '@metamask/controller-utils';\n\n/**\n * @type EnsEntry\n *\n * ENS entry representation\n * @property chainId - Id of the associated chain\n * @property ensName - The ENS name\n * @property address - Hex address with the ENS name, or null\n */\nexport interface EnsEntry {\n  chainId: string;\n  ensName: string;\n  address: string | null;\n}\n\n/**\n * @type EnsState\n *\n * ENS controller state\n * @property ensEntries - Object of ENS entry objects\n */\nexport interface EnsState extends BaseState {\n  ensEntries: { [chainId: string]: { [ensName: string]: EnsEntry } };\n}\n\n/**\n * Controller that manages a list ENS names and their resolved addresses\n * by chainId. A null address indicates an unresolved ENS name.\n */\nexport class EnsController extends BaseController<BaseConfig, EnsState> {\n  /**\n   * Name of this controller used during composition\n   */\n  override name = 'EnsController';\n\n  /**\n   * Creates an EnsController instance.\n   *\n   * @param config - Initial options used to configure this controller.\n   * @param state - Initial state to set on this controller.\n   */\n  constructor(config?: Partial<BaseConfig>, state?: Partial<EnsState>) {\n    super(config, state);\n\n    this.defaultState = { ensEntries: {} };\n\n    this.initialize();\n  }\n\n  /**\n   * Remove all chain Ids and ENS entries from state.\n   */\n  clear() {\n    this.update({ ensEntries: {} });\n  }\n\n  /**\n   * Delete an ENS entry.\n   *\n   * @param chainId - Parent chain of the ENS entry to delete.\n   * @param ensName - Name of the ENS entry to delete.\n   * @returns Boolean indicating if the entry was deleted.\n   */\n  delete(chainId: string, ensName: string): boolean {\n    const normalizedEnsName = normalizeEnsName(ensName);\n    if (\n      !normalizedEnsName ||\n      !this.state.ensEntries[chainId] ||\n      !this.state.ensEntries[chainId][normalizedEnsName]\n    ) {\n      return false;\n    }\n\n    const ensEntries = Object.assign({}, this.state.ensEntries);\n    delete ensEntries[chainId][normalizedEnsName];\n\n    if (Object.keys(ensEntries[chainId]).length === 0) {\n      delete ensEntries[chainId];\n    }\n\n    this.update({ ensEntries });\n    return true;\n  }\n\n  /**\n   * Retrieve a DNS entry.\n   *\n   * @param chainId - Parent chain of the ENS entry to retrieve.\n   * @param ensName - Name of the ENS entry to retrieve.\n   * @returns The EnsEntry or null if it does not exist.\n   */\n  get(chainId: string, ensName: string): EnsEntry | null {\n    const normalizedEnsName = normalizeEnsName(ensName);\n\n    // TODO Explicitly handle the case where `normalizedEnsName` is `null`\n    // eslint-disable-next-line no-implicit-coercion\n    return !!normalizedEnsName && this.state.ensEntries[chainId]\n      ? this.state.ensEntries[chainId][normalizedEnsName] || null\n      : null;\n  }\n\n  /**\n   * Add or update an ENS entry by chainId and ensName.\n   *\n   * A null address indicates that the ENS name does not resolve.\n   *\n   * @param chainId - Id of the associated chain.\n   * @param ensName - The ENS name.\n   * @param address - Associated address (or null) to add or update.\n   * @returns Boolean indicating if the entry was set.\n   */\n  set(chainId: string, ensName: string, address: string | null): boolean {\n    if (\n      !Number.isInteger(Number.parseInt(chainId, 10)) ||\n      !ensName ||\n      typeof ensName !== 'string' ||\n      (address && !isValidHexAddress(address))\n    ) {\n      throw new Error(\n        `Invalid ENS entry: { chainId:${chainId}, ensName:${ensName}, address:${address}}`,\n      );\n    }\n\n    const normalizedEnsName = normalizeEnsName(ensName);\n    if (!normalizedEnsName) {\n      throw new Error(`Invalid ENS name: ${ensName}`);\n    }\n\n    const normalizedAddress = address ? toChecksumHexAddress(address) : null;\n    const subState = this.state.ensEntries[chainId];\n\n    if (\n      subState?.[normalizedEnsName] &&\n      subState[normalizedEnsName].address === normalizedAddress\n    ) {\n      return false;\n    }\n\n    this.update({\n      ensEntries: {\n        ...this.state.ensEntries,\n        [chainId]: {\n          ...this.state.ensEntries[chainId],\n          [normalizedEnsName]: {\n            address: normalizedAddress,\n            chainId,\n            ensName: normalizedEnsName,\n          },\n        },\n      },\n    });\n    return true;\n  }\n}\n\nexport default EnsController;\n"]}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './EnsController';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./EnsController"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC","sourcesContent":["export * from './EnsController';\n"]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@metamask/ens-controller",
+  "version": "1.0.0",
+  "description": "Maps ENS names to their resolved addresses by chain id",
+  "keywords": [
+    "MetaMask",
+    "Ethereum"
+  ],
+  "homepage": "https://github.com/MetaMask/controllers/tree/main/packages/ens-controller#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/controllers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/controllers.git"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/ens-controller",
+    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@metamask/base-controller": "~1.0.0",
+    "@metamask/controller-utils": "~1.0.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^3.1.0",
+    "@types/jest": "^26.0.22",
+    "deepmerge": "^4.2.2",
+    "jest": "^26.4.2",
+    "ts-jest": "^26.5.2",
+    "typedoc": "^0.22.15",
+    "typedoc-plugin-missing-exports": "^0.22.6",
+    "typescript": "~4.6.3"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}