Implement EIP-6963

.eslintrc.js

@@ -26,12 +26,32 @@ module.exports = {
     },
 
     {
-      files: ['*.test.ts', '*.test.js'],
+      files: ['*.test.ts', '*.test.js', 'jest.setup*.js'],
       extends: [
         '@metamask/eslint-config-jest',
         '@metamask/eslint-config-nodejs',
       ],
     },
+
+    {
+      files: ['EIP6963.test.ts', 'jest.setup.browser.js'],
+      rules: {
+        // We're mixing Node and browser environments in these files.
+        'no-restricted-globals': 'off',
+      },
+    },
+
+    {
+      files: ['jest.setup.browser.js'],
+      env: { browser: true },
+      // This file contains copypasta and we're not going to bother fixing these.
+      rules: {
+        'jest/require-top-level-describe': 'off',
+        'jsdoc/require-description': 'off',
+        'jsdoc/require-param-description': 'off',
+        'jsdoc/require-param-type': 'off',
+      },
+    },
   ],
 
   ignorePatterns: [

jest.config.js

@@ -45,10 +45,10 @@ const baseConfig = {
   // An object that configures minimum threshold enforcement for coverage results
   coverageThreshold: {
     global: {
-      branches: 61.29,
-      functions: 60.24,
-      lines: 63.82,
-      statements: 63.97,
+      branches: 64.25,
+      functions: 64.89,
+      lines: 66.35,
+      statements: 66.43,
     },
   },
 
@@ -222,8 +222,12 @@ const browserConfig = {
   ...baseConfig,
   displayName: 'Browser Providers',
   testEnvironment: 'jsdom',
-  testMatch: ['**/*InpageProvider.test.ts', '**/*ExtensionProvider.test.ts'],
-  setupFilesAfterEnv: ['./jest.setup.js'],
+  testMatch: [
+    '**/*InpageProvider.test.ts',
+    '**/*ExtensionProvider.test.ts',
+    '**/EIP6963.test.ts',
+  ],
+  setupFilesAfterEnv: ['./jest.setup.browser.js'],
 };
 
 module.exports = {

jest.setup.browser.js

@@ -0,0 +1,87 @@
+Object.assign(global, require('jest-chrome'));
+
+// Clean up jsdom between tests.
+// Courtesy @jhildenbiddle
+// https://github.com/jestjs/jest/issues/1224#issuecomment-716075260
+const sideEffects = {
+  document: {
+    addEventListener: {
+      fn: document.addEventListener,
+      refs: [],
+    },
+    keys: Object.keys(document),
+  },
+  window: {
+    addEventListener: {
+      fn: window.addEventListener,
+      refs: [],
+    },
+    keys: Object.keys(window),
+  },
+};
+
+// Lifecycle Hooks
+// -----------------------------------------------------------------------------
+beforeAll(async () => {
+  // Spy addEventListener
+  ['document', 'window'].forEach((obj) => {
+    const { fn, refs } = sideEffects[obj].addEventListener;
+
+    /**
+     *
+     * @param type
+     * @param listener
+     * @param options
+     */
+    function addEventListenerSpy(type, listener, options) {
+      // Store listener reference so it can be removed during reset
+      refs.push({ type, listener, options });
+      // Call original window.addEventListener
+      fn(type, listener, options);
+    }
+
+    // Add to default key array to prevent removal during reset
+    sideEffects[obj].keys.push('addEventListener');
+
+    // Replace addEventListener with mock
+    global[obj].addEventListener = addEventListenerSpy;
+  });
+});
+
+// Reset JSDOM. This attempts to remove side effects from tests, however it does
+// not reset all changes made to globals like the window and document
+// objects. Tests requiring a full JSDOM reset should be stored in separate
+// files, which is only way to do a complete JSDOM reset with Jest.
+beforeEach(async () => {
+  const rootElm = document.documentElement;
+
+  // Remove attributes on root element
+  [...rootElm.attributes].forEach((attr) => rootElm.removeAttribute(attr.name));
+
+  // Remove elements (faster than setting innerHTML)
+  while (rootElm.firstChild) {
+    rootElm.removeChild(rootElm.firstChild);
+  }
+
+  // Remove global listeners and keys
+  ['document', 'window'].forEach((obj) => {
+    const { refs } = sideEffects[obj].addEventListener;
+
+    // Listeners
+    while (refs.length) {
+      const { type, listener, options } = refs.pop();
+      global[obj].removeEventListener(type, listener, options);
+    }
+
+    // This breaks coverage.
+    // // Keys
+    // Object.keys(global[obj])
+    //   .filter((key) => !sideEffects[obj].keys.includes(key))
+    //   .forEach((key) => {
+    //     delete global[obj][key];
+    //   });
+  });
+
+  // Restore base elements
+  rootElm.innerHTML = '<head></head><body></body>';
+});

package.json

@@ -39,6 +39,7 @@
   "dependencies": {
     "@metamask/object-multiplex": "^1.1.0",
     "@metamask/safe-event-emitter": "^3.0.0",
+    "@metamask/utils": "^5.0.2",
     "detect-browser": "^5.2.0",
     "eth-rpc-errors": "^4.0.2",
     "extension-port-stream": "^2.0.1",
@@ -61,6 +62,7 @@
     "@types/node": "^17.0.23",
     "@types/pump": "^1.1.0",
     "@types/readable-stream": "^2.3.15",
+    "@types/uuid": "^9.0.1",
     "@types/webextension-polyfill": "^0.10.0",
     "@typescript-eslint/eslint-plugin": "^5.43.0",
     "@typescript-eslint/parser": "^5.43.0",

src/EIP6963.test.ts

@@ -0,0 +1,195 @@
+import { announceProvider, requestProvider } from './EIP6963';
+
+const getProviderInfo = () => ({
+  name: 'test',
+  icon: 'https://wallet.io/icon.svg',
+  uuid: '1449211e-5560-4235-9ab1-582cbe2b165f',
+});
+
+const providerInfoValidationError = () =>
+  new Error(
+    'Invalid EIP-6963 ProviderDetail object. See https://eips.ethereum.org/EIPS/eip-6963 for requirements.',
+  );
+
+describe('EIP6963', () => {
+  describe('announceProvider', () => {
+    describe('provider info validation', () => {
+      it('throws if the provider info is not a plain object', () => {
+        [null, undefined, Symbol('bar'), []].forEach((invalidInfo) => {
+          expect(() => announceProvider(invalidInfo as any)).toThrow(
+            providerInfoValidationError(),
+          );
+        });
+      });
+
+      it('throws if the `icon` field is invalid', () => {
+        [null, undefined, '', 'not-a-url', Symbol('bar')].forEach(
+          (invalidIcon) => {
+            const provider: any = { name: 'test' };
+            const providerDetail = { info: getProviderInfo(), provider };
+            providerDetail.info.icon = invalidIcon as any;
+
+            expect(() => announceProvider(providerDetail)).toThrow(
+              providerInfoValidationError(),
+            );
+          },
+        );
+      });
+
+      it('throws if the `name` field is invalid', () => {
+        [null, undefined, '', {}, [], Symbol('bar')].forEach((invalidName) => {
+          const provider: any = { name: 'test' };
+          const providerDetail = { info: getProviderInfo(), provider };
+          providerDetail.info.name = invalidName as any;
+
+          expect(() => announceProvider(providerDetail)).toThrow(
+            providerInfoValidationError(),
+          );
+        });
+      });
+
+      it('throws if the `uuid` field is invalid', () => {
+        [null, undefined, '', 'foo', Symbol('bar')].forEach((invalidUuid) => {
+          const provider: any = { name: 'test' };
+          const providerDetail = { info: getProviderInfo(), provider };
+          providerDetail.info.uuid = invalidUuid as any;
+
+          expect(() => announceProvider(providerDetail)).toThrow(
+            providerInfoValidationError(),
+          );
+        });
+      });
+    });
+
+    describe('provider validation', () => {
+      it('throws if the provider is not a plain object', () => {
+        [null, undefined, Symbol('bar'), []].forEach((invalidProvider) => {
+          const provider: any = invalidProvider;
+          const providerDetail = { info: getProviderInfo(), provider };
+
+          expect(() => announceProvider(providerDetail)).toThrow(
+            providerInfoValidationError(),
+          );
+        });
+      });
+    });
+
+    it('should announce a provider', () => {
+      const provider: any = { name: 'test' };
+      const providerDetail = { info: getProviderInfo(), provider };
+      const dispatchEvent = jest.spyOn(window, 'dispatchEvent');
+      const addEventListener = jest.spyOn(window, 'addEventListener');
+
+      announceProvider(providerDetail);
+
+      expect(dispatchEvent).toHaveBeenCalledTimes(1);
+      expect(dispatchEvent).toHaveBeenCalledWith(
+        new CustomEvent('eip6963:announceProvider', {
+          detail: {
+            info: getProviderInfo(),
+            provider,
+          },
+        }),
+      );
+      expect(addEventListener).toHaveBeenCalledTimes(1);
+      expect(addEventListener).toHaveBeenCalledWith(
+        'eip6963:requestProvider',
+        expect.any(Function),
+      );
+    });
+  });
+
+  describe('requestProvider', () => {
+    it('should receive an announced provider (called before announceProvider)', async () => {
+      const provider: any = { name: 'test' };
+      const providerDetail = { info: getProviderInfo(), provider };
+      const handleProvider = jest.fn();
+      const dispatchEvent = jest.spyOn(window, 'dispatchEvent');
+      const addEventListener = jest.spyOn(window, 'addEventListener');
+
+      requestProvider(handleProvider);
+      announceProvider(providerDetail);
+      await delay();
+
+      expect(dispatchEvent).toHaveBeenCalledTimes(2);
+      expect(dispatchEvent).toHaveBeenNthCalledWith(
+        1,
+        new Event('eip6963:requestProvider'),
+      );
+      expect(dispatchEvent).toHaveBeenNthCalledWith(
+        2,
+        new CustomEvent('eip6963:announceProvider'),
+      );
+
+      expect(addEventListener).toHaveBeenCalledTimes(2);
+      expect(addEventListener).toHaveBeenCalledWith(
+        'eip6963:announceProvider',
+        expect.any(Function),
+      );
+      expect(addEventListener).toHaveBeenCalledWith(
+        'eip6963:requestProvider',
+        expect.any(Function),
+      );
+
+      expect(handleProvider).toHaveBeenCalledTimes(1);
+      expect(handleProvider).toHaveBeenCalledWith({
+        info: getProviderInfo(),
+        provider,
+      });
+    });
+
+    it('should receive an announced provider (called after announceProvider)', async () => {
+      const provider: any = { name: 'test' };
+      const providerDetail = { info: getProviderInfo(), provider };
+      const handleProvider = jest.fn();
+      const dispatchEvent = jest.spyOn(window, 'dispatchEvent');
+      const addEventListener = jest.spyOn(window, 'addEventListener');
+
+      announceProvider(providerDetail);
+      requestProvider(handleProvider);
+      await delay();
+
+      // Notice that 3 events are dispatched in total when requestProvider is
+      // called after announceProvider.
+      expect(dispatchEvent).toHaveBeenCalledTimes(3);
+      expect(dispatchEvent).toHaveBeenNthCalledWith(
+        1,
+        new CustomEvent('eip6963:announceProvider'),
+      );
+      expect(dispatchEvent).toHaveBeenNthCalledWith(
+        2,
+        new Event('eip6963:requestProvider'),
+      );
+      expect(dispatchEvent).toHaveBeenNthCalledWith(
+        3,
+        new CustomEvent('eip6963:announceProvider'),
+      );
+
+      expect(addEventListener).toHaveBeenCalledTimes(2);
+      expect(addEventListener).toHaveBeenCalledWith(
+        'eip6963:announceProvider',
+        expect.any(Function),
+      );
+      expect(addEventListener).toHaveBeenCalledWith(
+        'eip6963:requestProvider',
+        expect.any(Function),
+      );
+
+      expect(handleProvider).toHaveBeenCalledTimes(1);
+      expect(handleProvider).toHaveBeenCalledWith({
+        info: getProviderInfo(),
+        provider,
+      });
+    });
+  });
+});
+
+/**
+ * Delay for a number of milliseconds by awaiting a promise
+ * resolved after the specified number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to delay for.
+ */
+async function delay(ms = 1) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}