feat: create merger and factory for the Caip25Permission

eslint-warning-thresholds.json

@@ -374,12 +374,6 @@
     "@typescript-eslint/no-unsafe-enum-comparison": 4,
     "jsdoc/tag-lines": 4
   },
-  "packages/multichain/src/scope/transform.ts": {
-    "jsdoc/tag-lines": 3
-  },
-  "packages/multichain/src/scope/types.ts": {
-    "jsdoc/tag-lines": 1
-  },
   "packages/multichain/src/scope/validation.ts": {
     "jsdoc/tag-lines": 2
   },

packages/multichain/src/adapters/caip-permission-adapter-session-scopes.ts

@@ -7,7 +7,7 @@ import {
   KnownWalletNamespaceRpcMethods,
   KnownWalletRpcMethods,
 } from '../scope/constants';
-import { mergeScopes } from '../scope/transform';
+import { mergeNormalizedScopes } from '../scope/transform';
 import type {
   InternalScopesObject,
   NonWalletKnownCaipNamespace,
@@ -94,7 +94,7 @@ export const getSessionScopes = (
     'requiredScopes' | 'optionalScopes'
   >,
 ) => {
-  return mergeScopes(
+  return mergeNormalizedScopes(
     getNormalizedScopesObject(caip25CaveatValue.requiredScopes),
     getNormalizedScopesObject(caip25CaveatValue.optionalScopes),
   );

packages/multichain/src/caip25Permission.test.ts

@@ -20,6 +20,11 @@ jest.mock('./scope/supported', () => ({
 }));
 const MockScopeSupported = jest.mocked(ScopeSupported);
 
+jest.mock('@metamask/permission-controller', () => ({
+  ...jest.requireActual('@metamask/permission-controller'),
+  constructPermission: jest.fn(),
+}));
+
 const { removeAccount, removeScope } = Caip25CaveatMutators[Caip25CaveatType];
 
 describe('caip25EndowmentBuilder', () => {
@@ -475,7 +480,7 @@ describe('caip25EndowmentBuilder', () => {
 describe('caip25CaveatBuilder', () => {
   const findNetworkClientIdByChainId = jest.fn();
   const listAccounts = jest.fn();
-  const { validator } = caip25CaveatBuilder({
+  const { validator, merger } = caip25CaveatBuilder({
     findNetworkClientIdByChainId,
     listAccounts,
   });
@@ -698,4 +703,209 @@ describe('caip25CaveatBuilder', () => {
       }),
     ).toBeUndefined();
   });
+
+  describe('permission merger', () => {
+    const initLeftValue: Caip25CaveatValue = {
+      optionalScopes: {
+        'eip155:1': {
+          accounts: ['eip155:1:0xdead'],
+        },
+      },
+      requiredScopes: {},
+      isMultichainOrigin: false,
+    };
+
+    it.each<{
+      rightValue: Caip25CaveatValue;
+      expectedMergedValue: Caip25CaveatValue;
+      expectedDiff: Caip25CaveatValue;
+    }>([
+      {
+        rightValue: {
+          optionalScopes: {
+            'eip155:1': {
+              accounts: ['eip155:1:0xbeef'],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedMergedValue: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xdead', 'eip155:1:0xbeef'] },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedDiff: {
+          optionalScopes: {
+            'eip155:1': {
+              accounts: ['eip155:1:0xbeef'],
+            },
+          },
+          isMultichainOrigin: false,
+          requiredScopes: {},
+        },
+      },
+      {
+        rightValue: {
+          optionalScopes: {
+            'eip155:10': {
+              accounts: [],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedMergedValue: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xdead'] },
+            'eip155:10': {
+              accounts: [],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedDiff: {
+          optionalScopes: {
+            'eip155:10': {
+              accounts: [],
+            },
+          },
+          isMultichainOrigin: false,
+          requiredScopes: {},
+        },
+      },
+      {
+        rightValue: {
+          optionalScopes: {
+            'eip155:10': {
+              accounts: ['eip155:10:0xbeef'],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedMergedValue: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xdead'] },
+            'eip155:10': { accounts: ['eip155:10:0xbeef'] },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedDiff: {
+          optionalScopes: {
+            'eip155:10': {
+              accounts: ['eip155:10:0xbeef'],
+            },
+          },
+          isMultichainOrigin: false,
+          requiredScopes: {},
+        },
+      },
+      {
+        rightValue: {
+          optionalScopes: {
+            'eip155:1': {
+              accounts: ['eip155:1:0xdead', 'eip155:1:0xbeef'],
+            },
+            'eip155:10': {
+              accounts: ['eip155:10:0xdead', 'eip155:10:0xbeef'],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedMergedValue: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xdead', 'eip155:1:0xbeef'] },
+            'eip155:10': {
+              accounts: ['eip155:10:0xdead', 'eip155:10:0xbeef'],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedDiff: {
+          optionalScopes: {
+            'eip155:1': {
+              accounts: ['eip155:1:0xbeef'],
+            },
+            'eip155:10': {
+              accounts: ['eip155:10:0xdead', 'eip155:10:0xbeef'],
+            },
+          },
+          isMultichainOrigin: false,
+          requiredScopes: {},
+        },
+      },
+      {
+        rightValue: {
+          optionalScopes: {
+            'eip155:1': {
+              accounts: ['eip155:1:0xdead', 'eip155:1:0xbadd'],
+            },
+            'eip155:10': {
+              accounts: ['eip155:10:0xbeef', 'eip155:10:0xbadd'],
+            },
+            'eip155:426161': {
+              accounts: [
+                'eip155:426161:0xdead',
+                'eip155:426161:0xbeef',
+                'eip155:426161:0xbadd',
+              ],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedMergedValue: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xdead', 'eip155:1:0xbadd'] },
+            'eip155:10': {
+              accounts: ['eip155:10:0xbeef', 'eip155:10:0xbadd'],
+            },
+            'eip155:426161': {
+              accounts: [
+                'eip155:426161:0xdead',
+                'eip155:426161:0xbeef',
+                'eip155:426161:0xbadd',
+              ],
+            },
+          },
+          requiredScopes: {},
+          isMultichainOrigin: false,
+        },
+        expectedDiff: {
+          optionalScopes: {
+            'eip155:1': { accounts: ['eip155:1:0xbadd'] },
+            'eip155:10': {
+              accounts: ['eip155:10:0xbeef', 'eip155:10:0xbadd'],
+            },
+            'eip155:426161': {
+              accounts: [
+                'eip155:426161:0xdead',
+                'eip155:426161:0xbeef',
+                'eip155:426161:0xbadd',
+              ],
+            },
+          },
+          isMultichainOrigin: false,
+          requiredScopes: {},
+        },
+      },
+    ])(
+      'should return the expected merged value $expectedMergedValue and expected diff $expectedDiff',
+      async ({ rightValue, expectedMergedValue, expectedDiff }) => {
+        const [newValue, diff] = merger(initLeftValue, rightValue);
+
+        expect(newValue).toStrictEqual(
+          expect.objectContaining(expectedMergedValue),
+        );
+        expect(diff).toStrictEqual(expect.objectContaining(expectedDiff));
+      },
+    );
+  });
 });

packages/multichain/src/caip25Permission.ts

@@ -24,8 +24,10 @@ import { cloneDeep, isEqual } from 'lodash';
 import { getEthAccounts } from './adapters/caip-permission-adapter-eth-accounts';
 import { assertIsInternalScopesObject } from './scope/assert';
 import { isSupportedScopeString } from './scope/supported';
+import { mergeInternalScopes } from './scope/transform';
 import {
   parseScopeString,
+  type InternalScopeString,
   type ExternalScopeString,
   type InternalScopeObject,
   type InternalScopesObject,
@@ -83,7 +85,9 @@ export const caip25CaveatBuilder = ({
   findNetworkClientIdByChainId,
   listAccounts,
 }: Caip25EndowmentCaveatSpecificationBuilderOptions): EndowmentCaveatSpecificationConstraint &
-  Required<Pick<EndowmentCaveatSpecificationConstraint, 'validator'>> => {
+  Required<
+    Pick<EndowmentCaveatSpecificationConstraint, 'validator' | 'merger'>
+  > => {
   return {
     type: Caip25CaveatType,
     validator: (
@@ -150,6 +154,39 @@ export const caip25CaveatBuilder = ({
         );
       }
     },
+    merger: (
+      leftValue: Caip25CaveatValue,
+      rightValue: Caip25CaveatValue,
+    ): [Caip25CaveatValue, Caip25CaveatValue] => {
+      const mergedRequiredScopes = mergeInternalScopes(
+        leftValue.requiredScopes,
+        rightValue.requiredScopes,
+      );
+      const mergedOptionalScopes = mergeInternalScopes(
+        leftValue.optionalScopes,
+        rightValue.optionalScopes,
+      );
+
+      const mergedValue: Caip25CaveatValue = {
+        requiredScopes: mergedRequiredScopes,
+        optionalScopes: mergedOptionalScopes,
+        isMultichainOrigin: leftValue.isMultichainOrigin,
+      };
+
+      const partialDiff = diffScopesForCaip25CaveatValue(
+        leftValue,
+        mergedValue,
+        'requiredScopes',
+      );
+
+      const diff = diffScopesForCaip25CaveatValue(
+        partialDiff,
+        mergedValue,
+        'optionalScopes',
+      );
+
+      return [mergedValue, diff];
+    },
   };
 };
 
@@ -347,3 +384,48 @@ function removeScope(
     operation: CaveatMutatorOperation.RevokePermission,
   };
 }
+
+/**
+ *
+ * @param originalValue - The existing CAIP-25 permission caveat value.
+ * @param mergedValue - The result from merging existing and incoming CAIP-25 permission caveat values.
+ * @param scopeToMerge - The required or optional scopes from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request.
+ * @returns The differential between original and merged CAIP-25 permission caveat values.
+ */
+function diffScopesForCaip25CaveatValue(
+  originalValue: Caip25CaveatValue,
+  mergedValue: Caip25CaveatValue,
+  scopeToMerge: keyof Pick<
+    Caip25CaveatValue,
+    'optionalScopes' | 'requiredScopes'
+  >,
+): Caip25CaveatValue {
+  const diff = cloneDeep(originalValue);
+
+  for (const [scopeString, mergedScopeObject] of Object.entries(
+    mergedValue[scopeToMerge],
+  )) {
+    const internalScopeString = scopeString as InternalScopeString;
+    const originalScopeObject = diff[scopeToMerge][internalScopeString];
+
+    if (originalScopeObject) {
+      const newAccounts = mergedScopeObject.accounts.filter(
+        (account) =>
+          !diff[scopeToMerge][
+            scopeString as InternalScopeString
+          ]?.accounts.includes(account),
+      );
+      if (newAccounts.length > 0) {
+        diff[scopeToMerge][internalScopeString] = {
+          accounts: newAccounts,
+        };
+        continue;
+      }
+      delete diff[scopeToMerge][internalScopeString];
+    } else {
+      diff[scopeToMerge][internalScopeString] = mergedScopeObject;
+    }
+  }
+
+  return diff;
+}

packages/multichain/src/index.test.ts

@@ -28,7 +28,8 @@ describe('@metamask/multichain', () => {
         "parseScopeString",
         "normalizeScope",
         "mergeScopeObject",
-        "mergeScopes",
+        "mergeNormalizedScopes",
+        "mergeInternalScopes",
         "normalizeAndMergeScopes",
         "caip25CaveatBuilder",
         "Caip25CaveatType",

packages/multichain/src/index.ts

@@ -49,7 +49,8 @@ export { parseScopeString } from './scope/types';
 export {
   normalizeScope,
   mergeScopeObject,
-  mergeScopes,
+  mergeNormalizedScopes,
+  mergeInternalScopes,
   normalizeAndMergeScopes,
 } from './scope/transform';