Add onNameLookup export

packages/snaps-controllers/coverage.json

@@ -1,6 +1,6 @@
 {
   "branches": 89.8,
-  "functions": 95.28,
-  "lines": 96.53,
-  "statements": 96.17
+  "functions": 95.31,
+  "lines": 96.54,
+  "statements": 96.19
 }

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

@@ -2523,7 +2523,7 @@ describe('SnapController', () => {
           [MOCK_SNAP_ID]: {},
         }),
       ).rejects.toThrow(
-        'A snap must request at least one of the following permissions: endowment:rpc, endowment:keyring, endowment:transaction-insight, endowment:cronjob.',
+        'A snap must request at least one of the following permissions: endowment:rpc, endowment:keyring, endowment:transaction-insight, endowment:cronjob, endowment:name-lookup.',
       );
 
       controller.destroy();

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

@@ -7,4 +7,5 @@ export enum SnapEndowments {
   EthereumProvider = 'endowment:ethereum-provider',
   Rpc = 'endowment:rpc',
   WebAssemblyAccess = 'endowment:webassembly',
+  NameLookup = 'endowment:name-lookup',
 }

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

@@ -14,6 +14,7 @@ import {
   getKeyringCaveatMapper,
 } from './keyring';
 import { longRunningEndowmentBuilder } from './long-running';
+import { nameLookupEndowmentBuilder } from './name-lookup';
 import { networkAccessEndowmentBuilder } from './network-access';
 import {
   getRpcCaveatMapper,
@@ -38,6 +39,7 @@ export const endowmentPermissionBuilders = {
     ethereumProviderEndowmentBuilder,
   [rpcEndowmentBuilder.targetName]: rpcEndowmentBuilder,
   [webAssemblyEndowmentBuilder.targetName]: webAssemblyEndowmentBuilder,
+  [nameLookupEndowmentBuilder.targetName]: nameLookupEndowmentBuilder,
 } as const;
 
 export const endowmentCaveatSpecifications = {
@@ -63,6 +65,7 @@ export const handlerEndowments: Record<HandlerType, string> = {
   [HandlerType.SnapKeyring]: keyringEndowmentBuilder.targetName,
   [HandlerType.OnTransaction]: transactionInsightEndowmentBuilder.targetName,
   [HandlerType.OnCronjob]: cronjobEndowmentBuilder.targetName,
+  [HandlerType.OnNameLookup]: nameLookupEndowmentBuilder.targetName,
 };
 
 export * from './enum';

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

@@ -0,0 +1,19 @@
+import { PermissionType, SubjectType } from '@metamask/permission-controller';
+
+import { SnapEndowments } from '.';
+import { nameLookupEndowmentBuilder } from './name-lookup';
+
+describe('endowment:name-lookup', () => {
+  const specification = nameLookupEndowmentBuilder.specificationBuilder({});
+  it('builds the expected permission specification', () => {
+    expect(specification).toStrictEqual({
+      permissionType: PermissionType.Endowment,
+      targetName: SnapEndowments.NameLookup,
+      endowmentGetter: expect.any(Function),
+      allowedCaveats: null,
+      subjectTypes: [SubjectType.Snap],
+    });
+
+    expect(specification.endowmentGetter()).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,45 @@
+import {
+  EndowmentGetterParams,
+  PermissionType,
+  PermissionSpecificationBuilder,
+  ValidPermissionSpecification,
+  SubjectType,
+} from '@metamask/permission-controller';
+import { NonEmptyArray } from '@metamask/utils';
+
+import { SnapEndowments } from './enum';
+
+const permissionName = SnapEndowments.NameLookup;
+
+type NameLookupEndowmentSpecification = ValidPermissionSpecification<{
+  permissionType: PermissionType.Endowment;
+  targetName: typeof permissionName;
+  endowmentGetter: (_options?: EndowmentGetterParams) => undefined;
+  allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+}>;
+
+/**
+ * `endowment:name-lookup` returns nothing; it is intended to be used as a flag
+ * by the extension to detect whether the snap has the capability to resolve content entered into the send screen.
+ *
+ * @param _builderOptions - Optional specification builder options.
+ * @returns The specification for the name-lookup endowment.
+ */
+const specificationBuilder: PermissionSpecificationBuilder<
+  PermissionType.Endowment,
+  any,
+  NameLookupEndowmentSpecification
+> = (_builderOptions?: unknown) => {
+  return {
+    permissionType: PermissionType.Endowment,
+    targetName: permissionName,
+    allowedCaveats: null,
+    endowmentGetter: (_getterOptions?: EndowmentGetterParams) => undefined,
+    subjectTypes: [SubjectType.Snap],
+  };
+};
+
+export const nameLookupEndowmentBuilder = Object.freeze({
+  targetName: permissionName,
+  specificationBuilder,
+} as const);

packages/snaps-controllers/src/snaps/permission.test.ts

@@ -49,6 +49,15 @@ describe('buildSnapEndowmentSpecifications', () => {
           ],
           "targetName": "endowment:long-running",
         },
+        "endowment:name-lookup": {
+          "allowedCaveats": null,
+          "endowmentGetter": [Function],
+          "permissionType": "Endowment",
+          "subjectTypes": [
+            "snap",
+          ],
+          "targetName": "endowment:name-lookup",
+        },
         "endowment:network-access": {
           "allowedCaveats": null,
           "endowmentGetter": [Function],

packages/snaps-execution-environments/coverage.json

@@ -1,6 +1,6 @@
 {
-  "branches": 79.31,
-  "functions": 92.14,
-  "lines": 91.17,
-  "statements": 91.03
+  "branches": 79.45,
+  "functions": 91.48,
+  "lines": 90.93,
+  "statements": 90.66
 }

packages/snaps-execution-environments/src/common/BaseSnapExecutor.test.browser.ts

@@ -1244,6 +1244,41 @@ describe('BaseSnapExecutor', () => {
     });
   });
 
+  it('supports onNameLookup export', async () => {
+    const CODE = `module.exports.onNameLookup = ({ id, content }) => content`;
+
+    const executor = new TestSnapExecutor();
+    await executor.executeSnap(1, MOCK_SNAP_ID, CODE, []);
+
+    expect(await executor.readCommand()).toStrictEqual({
+      jsonrpc: '2.0',
+      id: 1,
+      result: 'OK',
+    });
+
+    await executor.writeCommand({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'snapRpc',
+      params: [
+        MOCK_SNAP_ID,
+        HandlerType.OnNameLookup,
+        MOCK_ORIGIN,
+        {
+          jsonrpc: '2.0',
+          method: 'foo',
+          params: { id: 'eip155:1', content: 'foo.lens' },
+        },
+      ],
+    });
+
+    expect(await executor.readCommand()).toStrictEqual({
+      id: 2,
+      jsonrpc: '2.0',
+      result: 'foo.lens',
+    });
+  });
+
   it('blocks snaps from escaping confinement by using unbound this', async () => {
     const consoleSpy = spy(console, 'log');
 

packages/snaps-execution-environments/src/common/commands.ts

@@ -4,6 +4,7 @@ import { assertExhaustive } from '@metamask/utils';
 import { InvokeSnap, InvokeSnapArgs } from './BaseSnapExecutor';
 import {
   assertIsOnTransactionRequestArguments,
+  assertIsOnNameLookupRequestArguments,
   ExecuteSnap,
   JsonRpcRequestWithoutId,
   Ping,
@@ -44,7 +45,14 @@ export function getHandlerArguments(
         transactionOrigin,
       };
     }
-
+    case HandlerType.OnNameLookup: {
+      assertIsOnNameLookupRequestArguments(request.params);
+      const { id, content } = request.params;
+      return {
+        id,
+        content,
+      };
+    }
     case HandlerType.OnRpcRequest:
     case HandlerType.SnapKeyring:
       return { origin, request };

packages/snaps-execution-environments/src/common/validation.ts

@@ -30,6 +30,7 @@ const VALIDATION_FUNCTIONS = {
   [HandlerType.OnTransaction]: validateFunctionExport,
   [HandlerType.SnapKeyring]: validateKeyringExport,
   [HandlerType.OnCronjob]: validateFunctionExport,
+  [HandlerType.OnNameLookup]: validateFunctionExport,
 };
 
 /**
@@ -178,6 +179,33 @@ export function assertIsOnTransactionRequestArguments(
   );
 }
 
+export const OnNameLookupRequestArgumentsStruct = object({
+  id: ChainIdStruct,
+  content: string(),
+});
+
+export type OnNameLookupRequestArguments = Infer<
+  typeof OnNameLookupRequestArgumentsStruct
+>;
+
+/**
+ * Asserts that the given value is a valid {@link OnNameLookupRequestArguments}
+ * object.
+ *
+ * @param value - The value to validate.
+ * @throws If the value is not a valid {@link OnNameLookupRequestArguments}
+ * object.
+ */
+export function assertIsOnNameLookupRequestArguments(
+  value: unknown,
+): asserts value is OnNameLookupRequestArguments {
+  assertStruct(
+    value,
+    OnNameLookupRequestArgumentsStruct,
+    'Invalid request params',
+  );
+}
+
 const OkResponseStruct = assign(
   JsonRpcSuccessStruct,
   object({

packages/snaps-utils/coverage.json

@@ -1,6 +1,6 @@
 {
   "branches": 94.14,
   "functions": 100,
-  "lines": 98.5,
-  "statements": 94.64
+  "lines": 98.51,
+  "statements": 94.41
 }

packages/snaps-utils/src/handlers.ts

@@ -1,7 +1,13 @@
 import { Component } from '@metamask/snaps-ui';
 import { Json, JsonRpcRequest } from '@metamask/utils';
 
-import { AccountId, ChainId, RequestArguments } from './namespace';
+import {
+  AccountId,
+  AccountAddress,
+  ChainId,
+  Caip2ChainId,
+  RequestArguments,
+} from './namespace';
 
 /**
  * The `onRpcRequest` handler. This is called whenever a JSON-RPC request is
@@ -68,6 +74,32 @@ export type OnCronjobHandler<
     | undefined,
 > = (args: { request: JsonRpcRequest<Params> }) => Promise<unknown>;
 
+/**
+ * The response from a snap's `onNameLookup` handler.
+ *
+ * @property protocolName - This refers to the protocol that was used for the address lookup.
+ *
+ * If the snap has no resolved addresses from its lookup, this should be `null`.
+ */
+export type OnNameLookupResponse = {
+  resolvedAccount: AccountAddress;
+} | null;
+
+/**
+ * The `onNameLookup` handler. This is called whenever content is entered
+ * into the send to field for sending assets to an EOA address.
+ *
+ * @param args - The request arguments.
+ * @param args.content - The human-readable address that is to be resolved.
+ * @param args.id - The CAIP-2 chain ID of the network the transaction is
+ * being submitted to.
+ * @returns Resolved address(es) from the content lookup. See {@link OnNameLookupResponse}.
+ */
+export type OnNameLookupHandler = (args: {
+  id: Caip2ChainId;
+  content: string;
+}) => Promise<OnNameLookupResponse>;
+
 /**
  * A request sent to the `handleRequest` handler of a snap keyring.
  *
@@ -115,6 +147,7 @@ export type SnapFunctionExports = {
   onRpcRequest?: OnRpcRequestHandler;
   onTransaction?: OnTransactionHandler;
   onCronjob?: OnCronjobHandler;
+  onNameLookup?: OnNameLookupHandler;
 };
 
 /**

packages/snaps-utils/src/manifest/validation.ts

@@ -172,6 +172,7 @@ export const PermissionsStruct = type({
     }),
   ),
   wallet_snap: optional(SnapIdsStruct),
+  'endowment:name-lookup': optional(object({})),
 });
 /* eslint-enable @typescript-eslint/naming-convention */
 

packages/snaps-utils/src/namespace.ts

@@ -25,6 +25,8 @@ export const CHAIN_ID_REGEX =
 export const ACCOUNT_ID_REGEX =
   /^(?<chainId>(?<namespace>[-a-z0-9]{3,8}):(?<reference>[-a-zA-Z0-9]{1,32})):(?<accountAddress>[a-zA-Z0-9]{1,64})$/u;
 
+export const ACCOUNT_ADDRESS_REGEX = /^(?<accountAddress>[a-zA-Z0-9]{1,64})$/u;
+
 /**
  * Parse a chain ID string to an object containing the namespace and reference.
  * This validates the chain ID before parsing it.
@@ -85,11 +87,14 @@ export const LimitedString = size(string(), 1, 40);
  */
 export const ChainIdStruct = pattern(string(), CHAIN_ID_REGEX);
 export type ChainId = `${string}:${string}`;
+export type Caip2ChainId = Infer<typeof ChainIdStruct>;
 
 export const AccountIdStruct = pattern(string(), ACCOUNT_ID_REGEX);
 export type AccountId = `${ChainId}:${string}`;
 
 export const AccountIdArrayStruct = array(AccountIdStruct);
+export const AccountAddressStruct = pattern(string(), ACCOUNT_ADDRESS_REGEX);
+export type AccountAddress = Infer<typeof AccountAddressStruct>;
 
 /**
  * A chain descriptor.

packages/snaps-utils/src/types.ts

@@ -135,6 +135,7 @@ export enum HandlerType {
   OnTransaction = 'onTransaction',
   SnapKeyring = 'keyring',
   OnCronjob = 'onCronjob',
+  OnNameLookup = 'onNameLookup',
 }
 
 export const SNAP_EXPORT_NAMES = Object.values(HandlerType);