fix: re-introduce resolveAccountAddress on v2 KeyringSnapRpc (#585)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Medium Risk**
> Touches signing-request routing contracts across API, client, and Snap
handler; incorrect behavior could mis-route dapp signing, though changes
are additive and optional for Snaps.
> 
> **Overview**
> Restores **`keyring_resolveAccountAddress`** on the v2 snap keyring
stack so MetaMask can ask a Snap which account address should handle a
signing request for a given CAIP-2 scope and JSON-RPC call.
> 
> **keyring-api (v2)** adds the RPC method constant, request/response
structs (nullable `ResolvedAccountAddress`), the optional
`resolveAccountAddress` on `KeyringSnapRpc`, and a
**`snap.resolveAccountAddress`** capability flag.
> 
> **keyring-snap-client** and **keyring-snap-sdk** wire the method
through: the client sends validated RPC calls; the SDK handler
dispatches to `keyring.resolveAccountAddress` or throws if unsupported.
Tests cover success, `null` responses, and missing implementation.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5951828. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: ccharly

packages/keyring-api/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `resolveAccountAddress` to `KeyringSnapRpc` (v2) ([#585](https://github.com/MetaMask/accounts/pull/585))
+  - Add `snap.resolveAccountAddress` boolean flag to `KeyringCapabilities` to declare support for this method.
+
 ## [23.4.0]
 
 ### Added

packages/keyring-api/src/v2/api/keyring-capabilities.ts

@@ -108,6 +108,11 @@ export const KeyringCapabilitiesStruct = object({
        * (`keyring_setSelectedAccounts`).
        */
       selectedAccounts: exactOptional(boolean()),
+      /**
+       * Whether the keyring supports resolving the account address to use for
+       * routing a signing request (`keyring_resolveAccountAddress`).
+       */
+      resolveAccountAddress: exactOptional(boolean()),
     }),
   ),
 });

packages/keyring-api/src/v2/api/keyring-snap-rpc.ts

@@ -1,20 +1,31 @@
-import type { AccountId } from '@metamask/keyring-utils';
-import { UuidStruct } from '@metamask/keyring-utils';
+import type { AccountId, JsonRpcRequest } from '@metamask/keyring-utils';
+import { UuidStruct, JsonRpcRequestStruct } from '@metamask/keyring-utils';
 import type { Infer } from '@metamask/superstruct';
 import {
   array,
   literal,
+  nullable,
   number,
   object,
   record,
   string,
   union,
 } from '@metamask/superstruct';
 
+import { ResolvedAccountAddressStruct } from '../../api/address';
+import type { ResolvedAccountAddress } from '../../api/address';
 import { BalanceStruct } from '../../api/balance';
 import type { Balance } from '../../api/balance';
-import { CaipAssetTypeOrIdStruct, CaipAssetTypeStruct } from '../../api/caip';
-import type { CaipAssetType, CaipAssetTypeOrId } from '../../api/caip';
+import {
+  CaipAssetTypeOrIdStruct,
+  CaipAssetTypeStruct,
+  CaipChainIdStruct,
+} from '../../api/caip';
+import type {
+  CaipAssetType,
+  CaipAssetTypeOrId,
+  CaipChainId,
+} from '../../api/caip';
 import { PaginationStruct } from '../../api/pagination';
 import type { Pagination } from '../../api/pagination';
 import { TransactionsPageStruct } from '../../api/transaction';
@@ -32,6 +43,7 @@ export const KeyringSnapRpcMethod = {
   GetAccountTransactions: 'keyring_getAccountTransactions',
   GetAccountAssets: 'keyring_getAccountAssets',
   GetAccountBalances: 'keyring_getAccountBalances',
+  ResolveAccountAddress: 'keyring_resolveAccountAddress',
 } as const;
 
 /**
@@ -150,6 +162,30 @@ export type GetAccountBalancesResponse = Infer<
   typeof GetAccountBalancesResponseStruct
 >;
 
+// ----------------------------------------------------------------------------
+// Resolve account address
+
+export const ResolveAccountAddressRequestStruct = object({
+  ...CommonHeader,
+  method: literal(`${KeyringSnapRpcMethod.ResolveAccountAddress}`),
+  params: object({
+    scope: CaipChainIdStruct,
+    request: JsonRpcRequestStruct,
+  }),
+});
+
+export type ResolveAccountAddressRequest = Infer<
+  typeof ResolveAccountAddressRequestStruct
+>;
+
+export const ResolveAccountAddressResponseStruct = nullable(
+  ResolvedAccountAddressStruct,
+);
+
+export type ResolveAccountAddressResponse = Infer<
+  typeof ResolveAccountAddressResponseStruct
+>;
+
 // ----------------------------------------------------------------------------
 
 /**
@@ -161,7 +197,8 @@ export type KeyringSnapRpcRequests =
   | SetSelectedAccountsRequest
   | GetAccountTransactionsRequest
   | GetAccountAssetsRequest
-  | GetAccountBalancesRequest;
+  | GetAccountBalancesRequest
+  | ResolveAccountAddressRequest;
 
 /**
  * Extract the proper request type for a given {@link KeyringSnapRpcMethod}.
@@ -205,4 +242,13 @@ export type KeyringSnapRpc = KeyringRpc & {
     id: AccountId,
     assets: CaipAssetType[],
   ) => Promise<Record<CaipAssetType, Balance>>;
+
+  /**
+   * Resolve the account address to use for routing a signing request.
+   * Maps to `keyring_resolveAccountAddress`.
+   */
+  resolveAccountAddress?: (
+    scope: CaipChainId,
+    request: JsonRpcRequest,
+  ) => Promise<ResolvedAccountAddress | null>;
 };

packages/keyring-snap-client/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `resolveAccountAddress` to v2 `KeyringClient` ([#585](https://github.com/MetaMask/accounts/pull/585))
+
 ## [9.1.0]
 
 ### Added

packages/keyring-snap-client/src/v2/KeyringClient.test.ts

@@ -272,5 +272,45 @@ describe('KeyringClient', () => {
         expect(response).toStrictEqual(expectedResponse);
       });
     });
+
+    describe('resolveAccountAddress', () => {
+      it('sends a request to resolve an account address and returns the response', async () => {
+        const scope = 'bip122:000000000019d6689c085ae165831e93';
+        const request = {
+          jsonrpc: '2.0' as const,
+          id: '1',
+          method: 'signPsbt',
+          params: {},
+        };
+        const expectedResponse = {
+          address:
+            'bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf',
+        };
+
+        mockSender.send.mockResolvedValue(expectedResponse);
+        const response = await client.resolveAccountAddress(scope, request);
+        expect(mockSender.send).toHaveBeenCalledWith({
+          jsonrpc: '2.0',
+          id: expect.any(String),
+          method: `${KeyringSnapRpcMethod.ResolveAccountAddress}`,
+          params: { scope, request },
+        });
+        expect(response).toStrictEqual(expectedResponse);
+      });
+
+      it('returns null when the snap cannot resolve an address', async () => {
+        const scope = 'bip122:000000000019d6689c085ae165831e93';
+        const request = {
+          jsonrpc: '2.0' as const,
+          id: '1',
+          method: 'signPsbt',
+          params: {},
+        };
+
+        mockSender.send.mockResolvedValue(null);
+        const response = await client.resolveAccountAddress(scope, request);
+        expect(response).toBeNull();
+      });
+    });
   });
 });

packages/keyring-snap-client/src/v2/KeyringClient.ts

@@ -1,4 +1,9 @@
-import type { KeyringAccount, KeyringRequest } from '@metamask/keyring-api';
+import type {
+  CaipChainId,
+  KeyringAccount,
+  KeyringRequest,
+  ResolvedAccountAddress,
+} from '@metamask/keyring-api';
 import type {
   Balance,
   CaipAssetType,
@@ -19,6 +24,7 @@ import {
   GetAccountTransactionsResponseStruct,
   GetAccountAssetsResponseStruct,
   GetAccountBalancesResponseStruct,
+  ResolveAccountAddressResponseStruct,
 } from '@metamask/keyring-api/v2';
 import type {
   CreateAccountOptions,
@@ -27,6 +33,7 @@ import type {
   KeyringSnapRpc,
   KeyringRpcRequest,
 } from '@metamask/keyring-api/v2';
+import type { JsonRpcRequest } from '@metamask/keyring-utils';
 import type { AccountId } from '@metamask/keyring-utils';
 import { strictMask } from '@metamask/keyring-utils';
 import { assert } from '@metamask/superstruct';
@@ -252,4 +259,27 @@ export class KeyringClient implements KeyringSnapRpc {
       GetAccountBalancesResponseStruct,
     );
   }
+
+  /**
+   * Resolves the account address to use for routing a signing request.
+   *
+   * @param scope - CAIP-2 chain ID of the signing request.
+   * @param request - The signing JSON-RPC request.
+   * @returns A promise that resolves to the resolved address, or `null` if
+   * the Snap cannot determine an address for this request.
+   */
+  async resolveAccountAddress(
+    scope: CaipChainId,
+    request: JsonRpcRequest,
+  ): Promise<ResolvedAccountAddress | null> {
+    return strictMask(
+      await this.#sender.send({
+        jsonrpc: '2.0',
+        id: uuid(),
+        method: KeyringSnapRpcMethod.ResolveAccountAddress,
+        params: { scope, request },
+      }),
+      ResolveAccountAddressResponseStruct,
+    );
+  }
 }

packages/keyring-snap-sdk/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `keyring_resolveAccountAddress` dispatch to v2 `handleKeyringRequest` ([#585](https://github.com/MetaMask/accounts/pull/585))
+
 ## [9.1.0]
 
 ### Added

packages/keyring-snap-sdk/src/v2/rpc-handler.test.ts

@@ -19,6 +19,7 @@ import type {
   GetAccountTransactionsRequest,
   GetAccountAssetsRequest,
   GetAccountBalancesRequest,
+  ResolveAccountAddressRequest,
   KeyringRpc,
   KeyringSnapRpc,
 } from '@metamask/keyring-api/v2';
@@ -38,6 +39,7 @@ describe('handleKeyringRequest', () => {
     getAccountTransactions: jest.fn(),
     getAccountAssets: jest.fn(),
     getAccountBalances: jest.fn(),
+    resolveAccountAddress: jest.fn(),
   };
 
   afterEach(() => {
@@ -472,6 +474,60 @@ describe('handleKeyringRequest', () => {
     );
   });
 
+  it('calls `keyring_resolveAccountAddress`', async () => {
+    const request: ResolveAccountAddressRequest = {
+      jsonrpc: '2.0',
+      id: '7c507ff0-365f-4de0-8cd5-eb83c30ebda4',
+      method: `${KeyringSnapRpcMethod.ResolveAccountAddress}`,
+      params: {
+        scope: 'bip122:000000000019d6689c085ae165831e93',
+        request: {
+          jsonrpc: '2.0',
+          id: '1',
+          method: 'signPsbt',
+          params: {},
+        },
+      },
+    };
+
+    const mockedResult = {
+      address:
+        'bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf',
+    };
+    keyring.resolveAccountAddress.mockResolvedValue(mockedResult);
+    const result = await handleKeyringRequest(keyring, request);
+
+    expect(keyring.resolveAccountAddress).toHaveBeenCalledWith(
+      request.params.scope,
+      request.params.request,
+    );
+    expect(result).toStrictEqual(mockedResult);
+  });
+
+  it('throws an error if `keyring_resolveAccountAddress` is not implemented', async () => {
+    const request: ResolveAccountAddressRequest = {
+      jsonrpc: '2.0',
+      id: '7c507ff0-365f-4de0-8cd5-eb83c30ebda4',
+      method: `${KeyringSnapRpcMethod.ResolveAccountAddress}`,
+      params: {
+        scope: 'bip122:000000000019d6689c085ae165831e93',
+        request: {
+          jsonrpc: '2.0',
+          id: '1',
+          method: 'signPsbt',
+          params: {},
+        },
+      },
+    };
+
+    const partialKeyring: KeyringSnapRpc = { ...keyring };
+    delete partialKeyring.resolveAccountAddress;
+
+    await expect(handleKeyringRequest(partialKeyring, request)).rejects.toThrow(
+      `Method not supported: ${KeyringSnapRpcMethod.ResolveAccountAddress}`,
+    );
+  });
+
   it('throws an error if an unknown method is called', async () => {
     const request: JsonRpcRequest = {
       jsonrpc: '2.0',

packages/keyring-snap-sdk/src/v2/rpc-handler.ts

@@ -16,6 +16,7 @@ import {
   GetAccountTransactionsRequestStruct,
   GetAccountAssetsRequestStruct,
   GetAccountBalancesRequestStruct,
+  ResolveAccountAddressRequestStruct,
 } from '@metamask/keyring-api/v2';
 import type { KeyringSnapRpc } from '@metamask/keyring-api/v2';
 import type { JsonRpcRequest } from '@metamask/keyring-utils';
@@ -138,6 +139,17 @@ async function dispatchKeyringRequest(
       );
     }
 
+    case `${KeyringSnapRpcMethod.ResolveAccountAddress}`: {
+      if (keyring.resolveAccountAddress === undefined) {
+        throw new MethodNotSupportedError(request.method);
+      }
+      assert(request, ResolveAccountAddressRequestStruct);
+      return keyring.resolveAccountAddress(
+        request.params.scope,
+        request.params.request,
+      );
+    }
+
     default: {
       throw new MethodNotSupportedError(request.method);
     }