**BREAKING**: Update name lookup API

packages/examples/packages/name-lookup/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snaps.git"
   },
   "source": {
-    "shasum": "Sbu/MyQ6Mrxr6/4DDjd6SVjESJ2jrWASZSHc5JukBBo=",
+    "shasum": "mnFLBYHzMpTmIdjvtO3JHGmecaqtcb4g/Tnz7VI7zV8=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",
@@ -17,9 +17,11 @@
     }
   },
   "initialPermissions": {
-    "endowment:name-lookup": [
-      "eip155:1"
-    ]
+    "endowment:name-lookup": {
+      "chains": [
+        "eip155:1"
+      ]
+    }
   },
   "manifestVersion": "0.1"
 }

packages/examples/packages/name-lookup/src/index.test.ts

@@ -15,7 +15,12 @@ describe('onNameLookup', () => {
     };
 
     expect(await onNameLookup(request)).toStrictEqual({
-      resolvedAddress: '0xc0ffee254729296a45a3885639AC7E10F9d54979',
+      resolvedAddresses: [
+        {
+          resolvedAddress: '0xc0ffee254729296a45a3885639AC7E10F9d54979',
+          protocol: 'test protocol',
+        },
+      ],
     });
   });
 
@@ -26,7 +31,9 @@ describe('onNameLookup', () => {
     };
 
     expect(await onNameLookup(request)).toStrictEqual({
-      resolvedDomain: 'c0f.1.test.domain',
+      resolvedDomains: [
+        { resolvedDomain: 'c0f.1.test.domain', protocol: 'test protocol' },
+      ],
     });
   });
 
@@ -38,7 +45,9 @@ describe('onNameLookup', () => {
     } as any;
 
     expect(await onNameLookup(request)).toStrictEqual({
-      resolvedDomain: 'c0f.1.test.domain',
+      resolvedDomains: [
+        { resolvedDomain: 'c0f.1.test.domain', protocol: 'test protocol' },
+      ],
     });
   });
 

packages/examples/packages/name-lookup/src/index.ts

@@ -17,12 +17,14 @@ export const onNameLookup: OnNameLookupHandler = async (request) => {
     const shortAddress = address.substring(2, 5);
     const chainIdDecimal = parseInt(chainId.split(':')[1], 10);
     const resolvedDomain = `${shortAddress}.${chainIdDecimal}.test.domain`;
-    return { resolvedDomain };
+    return { resolvedDomains: [{ resolvedDomain, protocol: 'test protocol' }] };
   }
 
   if (domain) {
     const resolvedAddress = '0xc0ffee254729296a45a3885639AC7E10F9d54979';
-    return { resolvedAddress };
+    return {
+      resolvedAddresses: [{ resolvedAddress, protocol: 'test protocol' }],
+    };
   }
 
   return null;

packages/snaps-controllers/coverage.json

@@ -1,6 +1,6 @@
 {
-  "branches": 90.87,
-  "functions": 96.7,
-  "lines": 97.86,
-  "statements": 97.57
+  "branches": 89.7,
+  "functions": 96.73,
+  "lines": 97.67,
+  "statements": 97.38
 }

packages/snaps-controllers/src/snaps/SnapController.ts

@@ -74,6 +74,7 @@
   getValidatedLocalizationFiles,
   VirtualFile,
   NpmSnapFileNames,
+  OnNameLookupResponseStruct,
 } from '@metamask/snaps-utils';
 import type { Json, NonEmptyArray, SemVerRange } from '@metamask/utils';
 import {
@@ -2926,6 +2927,9 @@
           this.#checkPhishingList.bind(this),
         );
         break;
+      case HandlerType.OnNameLookup:
+        assertStruct(result, OnNameLookupResponseStruct);
+        break;
       default:
         break;
     }

packages/snaps-controllers/src/snaps/endowments/index.ts

@@ -94,5 +94,5 @@ export * from './enum';
 export { getRpcCaveatOrigins } from './rpc';
 export { getSignatureOriginCaveat } from './signature-insight';
 export { getTransactionOriginCaveat } from './transaction-insight';
-export { getChainIdsCaveat } from './name-lookup';
+export { getChainIdsCaveat, getLookupMatchersCaveat } from './name-lookup';
 export { getKeyringCaveatOrigins } from './keyring';

packages/snaps-controllers/src/snaps/endowments/name-lookup.test.ts

@@ -6,6 +6,7 @@ import { SnapEndowments } from '.';
 import {
   nameLookupEndowmentBuilder,
   getChainIdsCaveat,
+  getLookupMatchersCaveat,
   getNameLookupCaveatMapper,
   nameLookupCaveatSpecifications,
 } from './name-lookup';
@@ -17,7 +18,7 @@ describe('endowment:name-lookup', () => {
       permissionType: PermissionType.Endowment,
       targetName: SnapEndowments.NameLookup,
       endowmentGetter: expect.any(Function),
-      allowedCaveats: [SnapCaveatType.ChainIds],
+      allowedCaveats: [SnapCaveatType.ChainIds, SnapCaveatType.LookupMatchers],
       subjectTypes: [SubjectType.Snap],
       validator: expect.any(Function),
     });
@@ -30,16 +31,20 @@ describe('endowment:name-lookup', () => {
       expect(() =>
         // @ts-expect-error Missing required permission types.
         specification.validator({}),
-      ).toThrow('Expected a single "chainIds" caveat.');
+      ).toThrow(
+        'Expected the following caveats: "chainIds", "lookupMatchers".',
+      );
     });
 
-    it('throws if the caveat is not a single "chainIds"', () => {
+    it('throws if the caveats are not one or both of "chainIds" and "lookupMatchers".', () => {
       expect(() =>
         // @ts-expect-error Missing other required permission types.
         specification.validator({
           caveats: [{ type: 'foo', value: 'bar' }],
         }),
-      ).toThrow('Expected a single "chainIds" caveat.');
+      ).toThrow(
+        'Expected the following caveats: "chainIds", "lookupMatchers", received "foo".',
+      );
 
       expect(() =>
         // @ts-expect-error Missing other required permission types.
@@ -49,7 +54,7 @@ describe('endowment:name-lookup', () => {
             { type: 'chainIds', value: ['bar'] },
           ],
         }),
-      ).toThrow('Expected a single "chainIds" caveat.');
+      ).toThrow('Duplicate caveats are not allowed.');
     });
   });
 });
@@ -87,28 +92,60 @@ describe('getChainIdsCaveat', () => {
     expect(getChainIdsCaveat(permission)).toBeNull();
   });
 
-  it('throws if the permission does not have exactly one caveat', () => {
+  it('throws if there is not a "chainIds" caveat', () => {
     const permission: PermissionConstraint = {
       date: 0,
       parentCapability: 'foo',
       invoker: 'bar',
       id: 'baz',
       caveats: [
         {
-          type: SnapCaveatType.ChainIds,
-          value: ['eip155:1'],
+          type: SnapCaveatType.PermittedCoinTypes,
+          value: 'foo',
         },
+      ],
+    };
+
+    expect(() => getChainIdsCaveat(permission)).toThrow('Assertion failed');
+  });
+});
+
+describe('getLookupMatchersCaveat', () => {
+  it('returns the value from a name-lookup permission', () => {
+    const permission: PermissionConstraint = {
+      date: 0,
+      parentCapability: 'foo',
+      invoker: 'bar',
+      id: 'baz',
+      caveats: [
         {
-          type: SnapCaveatType.ChainIds,
-          value: ['eip155:2'],
+          type: SnapCaveatType.LookupMatchers,
+          value: { tlds: ['lens'] },
         },
       ],
     };
+    expect(getLookupMatchersCaveat(permission)).toStrictEqual({
+      tlds: ['lens'],
+    });
+  });
 
-    expect(() => getChainIdsCaveat(permission)).toThrow('Assertion failed');
+  it('returns null if the input is undefined', () => {
+    expect(getLookupMatchersCaveat(undefined)).toBeNull();
   });
 
-  it('throws if the first caveat is not a "chainIds" caveat', () => {
+  it('returns null if the permission does not have caveats', () => {
+    const permission: PermissionConstraint = {
+      date: 0,
+      parentCapability: 'foo',
+      invoker: 'bar',
+      id: 'baz',
+      caveats: null,
+    };
+
+    expect(getLookupMatchersCaveat(permission)).toBeNull();
+  });
+
+  it('throws if there is not a "matchers" caveat', () => {
     const permission: PermissionConstraint = {
       date: 0,
       parentCapability: 'foo',
@@ -122,20 +159,46 @@ describe('getChainIdsCaveat', () => {
       ],
     };
 
-    expect(() => getChainIdsCaveat(permission)).toThrow('Assertion failed');
+    expect(() => getLookupMatchersCaveat(permission)).toThrow(
+      'Assertion failed',
+    );
   });
 });
 
 describe('getNameLookupCaveatMapper', () => {
   it('maps input to a caveat', () => {
-    expect(getNameLookupCaveatMapper(['eip155:1'])).toStrictEqual({
+    expect(getNameLookupCaveatMapper({ chains: ['eip155:1'] })).toStrictEqual({
       caveats: [
         {
           type: 'chainIds',
           value: ['eip155:1'],
         },
       ],
     });
+
+    expect(
+      getNameLookupCaveatMapper({ matchers: { tlds: ['lens'] } }),
+    ).toStrictEqual({
+      caveats: [
+        {
+          type: 'lookupMatchers',
+          value: { tlds: ['lens'] },
+        },
+      ],
+    });
+
+    expect(
+      getNameLookupCaveatMapper({
+        matchers: { tlds: ['lens'], schemes: ['fio'] },
+      }),
+    ).toStrictEqual({
+      caveats: [
+        {
+          type: 'lookupMatchers',
+          value: { tlds: ['lens'], schemes: ['fio'] },
+        },
+      ],
+    });
   });
 
   it('does not include caveat if input is empty array', () => {
@@ -158,21 +221,81 @@ describe('nameLookupCaveatSpecifications', () => {
       ).toThrow('Expected a plain object.');
     });
 
-    it.each([
-      {
-        type: SnapCaveatType.ChainIds,
-        value: ['eip155'],
-      },
-      {
-        type: SnapCaveatType.ChainIds,
-        value: undefined,
-      },
-    ])('throws if the caveat values are invalid types', (val) => {
+    it('throws if the caveat values are invalid for the "chainIds" caveat', () => {
       expect(() =>
-        nameLookupCaveatSpecifications[SnapCaveatType.ChainIds].validator?.(
-          val,
-        ),
-      ).toThrow('Expected caveat value to have type "string array"');
+        nameLookupCaveatSpecifications[SnapCaveatType.ChainIds].validator?.({
+          type: SnapCaveatType.ChainIds,
+          value: ['eip155'],
+        }),
+      ).toThrow(
+        'Assertion failed: At path: 0 -- Expected a Chain ID matching `/^(?<namespace>[-a-z0-9]{3,8}):(?<reference>[-a-zA-Z0-9]{1,32})$/` but received "eip155".',
+      );
+
+      expect(() =>
+        nameLookupCaveatSpecifications[SnapCaveatType.ChainIds].validator?.({
+          type: SnapCaveatType.ChainIds,
+          value: undefined,
+        }),
+      ).toThrow(
+        'Assertion failed: Expected an array value, but received: undefined.',
+      );
+    });
+
+    it('throws if the caveat values are invalid for the "matchers" caveat', () => {
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: undefined,
+        }),
+      ).toThrow(
+        'Assertion failed: Expected an object, but received: undefined.',
+      );
+
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: { foo: 'bar', tlds: ['lens'], schemes: ['fio'] },
+        }),
+      ).toThrow(
+        'Assertion failed: At path: foo -- Expected a value of type `never`, but received: `"bar"`.',
+      );
+
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: { foo: 'bar' },
+        }),
+      ).toThrow(
+        'Assertion failed: At path: foo -- Expected a value of type `never`, but received: `"bar"`.',
+      );
+
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: { tlds: ['lens'], schemes: [1, 2] },
+        }),
+      ).toThrow(
+        'Assertion failed: At path: schemes.0 -- Expected a string, but received: 1.',
+      );
+
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: { tlds: [1, 2], schemes: ['fio'] },
+        }),
+      ).toThrow(
+        'Assertion failed: At path: tlds.0 -- Expected a string, but received: 1.',
+      );
     });
 
     it('will not throw with a valid caveat value', () => {
@@ -182,6 +305,15 @@ describe('nameLookupCaveatSpecifications', () => {
           value: ['eip155:1'],
         }),
       ).not.toThrow();
+
+      expect(() =>
+        nameLookupCaveatSpecifications[
+          SnapCaveatType.LookupMatchers
+        ].validator?.({
+          type: SnapCaveatType.LookupMatchers,
+          value: { tlds: ['lens'], schemes: ['fio'] },
+        }),
+      ).not.toThrow();
     });
   });
 });