Merge pull request #63 from MetaMask/refactor/improve-delegation-devex

Improve declarative delegation interface

Author: hanzel98

packages/delegation-toolkit/src/caveatBuilder/resolveCaveats.ts

@@ -10,7 +10,7 @@ export type Caveats = CaveatBuilder | (Caveat | CoreCaveatConfiguration)[];
  * @param config - The configuration for the caveat builder.
  * @param config.environment - The environment to be used for the caveat builder.
  * @param config.scope - The scope to be used for the caveat builder.
- * @param config.caveats - The caveats to be resolved, which can be either a CaveatBuilder or an array of Caveat or CaveatConfiguration.
+ * @param config.caveats - The caveats to be resolved, which can be either a CaveatBuilder or an array of Caveat or CaveatConfiguration. Optional - if not provided, only scope caveats will be used.
  * @returns The resolved array of caveats.
  */
 export const resolveCaveats = ({
@@ -20,27 +20,29 @@ export const resolveCaveats = ({
 }: {
   environment: DeleGatorEnvironment;
   scope: ScopeConfig;
-  caveats: Caveats;
+  caveats?: Caveats;
 }) => {
   const scopeCaveatBuilder = createCaveatBuilderFromScope(environment, scope);
 
-  if ('build' in caveats && typeof caveats.build === 'function') {
-    (caveats as CaveatBuilder).build().forEach((caveat) => {
-      scopeCaveatBuilder.addCaveat(caveat);
-    });
-  } else if (Array.isArray(caveats)) {
-    caveats.forEach((caveat) => {
-      try {
-        if ('type' in caveat) {
-          const { type, ...config } = caveat;
-          scopeCaveatBuilder.addCaveat(type, config);
-        } else {
-          scopeCaveatBuilder.addCaveat(caveat);
+  if (caveats) {
+    if ('build' in caveats && typeof caveats.build === 'function') {
+      (caveats as CaveatBuilder).build().forEach((caveat) => {
+        scopeCaveatBuilder.addCaveat(caveat);
+      });
+    } else if (Array.isArray(caveats)) {
+      caveats.forEach((caveat) => {
+        try {
+          if ('type' in caveat) {
+            const { type, ...config } = caveat;
+            scopeCaveatBuilder.addCaveat(type, config);
+          } else {
+            scopeCaveatBuilder.addCaveat(caveat);
+          }
+        } catch (error) {
+          throw new Error(`Invalid caveat: ${(error as Error).message}`);
         }
-      } catch (error) {
-        throw new Error(`Invalid caveat: ${(error as Error).message}`);
-      }
-    });
+      });
+    }
   }
 
   return scopeCaveatBuilder.build();

packages/delegation-toolkit/src/caveatBuilder/scope/functionCallScope.ts

@@ -31,6 +31,7 @@ const isFunctionCallConfig = (
  * @param config - Configuration object containing allowed targets, methods, and optionally calldata.
  * @returns A configured caveat builder with the specified caveats.
  * @throws Error if any of the required parameters are invalid.
+ * @throws Error if both allowedCalldata and exactCalldata are provided simultaneously.
  */
 export function createFunctionCallCaveatBuilder(
   environment: DeleGatorEnvironment,
@@ -42,16 +43,21 @@ export function createFunctionCallCaveatBuilder(
     throw new Error('Invalid Function Call configuration');
   }
 
+  if (allowedCalldata && allowedCalldata.length > 0 && exactCalldata) {
+    throw new Error(
+      'Cannot specify both allowedCalldata and exactCalldata. Please use only one calldata restriction type.',
+    );
+  }
+
   const caveatBuilder = createCaveatBuilder(environment)
     .addCaveat('allowedTargets', { targets })
     .addCaveat('allowedMethods', { selectors });
 
-  if (allowedCalldata) {
+  if (allowedCalldata && allowedCalldata.length > 0) {
     allowedCalldata.forEach((calldataConfig) => {
       caveatBuilder.addCaveat('allowedCalldata', calldataConfig);
     });
-  }
-  if (exactCalldata) {
+  } else if (exactCalldata) {
     caveatBuilder.addCaveat('exactCalldata', exactCalldata);
   }
 

packages/delegation-toolkit/src/caveatBuilder/scope/nativeTokenPeriodicScope.ts

@@ -1,13 +1,17 @@
 import type { DeleGatorEnvironment } from '../../types';
+import type { AllowedCalldataBuilderConfig } from '../allowedCalldataBuilder';
 import { createCaveatBuilder } from '../coreCaveatBuilder';
 import type { CoreCaveatBuilder } from '../coreCaveatBuilder';
+import type { ExactCalldataBuilderConfig } from '../exactCalldataBuilder';
 import type {
   nativeTokenPeriodTransfer,
   NativeTokenPeriodTransferBuilderConfig,
 } from '../nativeTokenPeriodTransferBuilder';
 
 export type NativeTokenPeriodicScopeConfig = {
   type: typeof nativeTokenPeriodTransfer;
+  allowedCalldata?: AllowedCalldataBuilderConfig[];
+  exactCalldata?: ExactCalldataBuilderConfig;
 } & NativeTokenPeriodTransferBuilderConfig;
 
 /**
@@ -17,19 +21,49 @@ export type NativeTokenPeriodicScopeConfig = {
  * @param config - Configuration object containing native token periodic transfer parameters.
  * @returns A configured caveat builder with native token period transfer and exact calldata caveats.
  * @throws Error if any of the native token periodic transfer parameters are invalid.
+ * @throws Error if both allowedCalldata and exactCalldata are provided simultaneously.
  * @throws Error if the environment is not properly configured.
  */
 export function createNativeTokenPeriodicCaveatBuilder(
   environment: DeleGatorEnvironment,
   config: NativeTokenPeriodicScopeConfig,
 ): CoreCaveatBuilder {
-  return createCaveatBuilder(environment)
-    .addCaveat('exactCalldata', {
+  const {
+    periodAmount,
+    periodDuration,
+    startDate,
+    allowedCalldata,
+    exactCalldata,
+  } = config;
+
+  if (allowedCalldata && allowedCalldata.length > 0 && exactCalldata) {
+    throw new Error(
+      'Cannot specify both allowedCalldata and exactCalldata. Please use only one calldata restriction type.',
+    );
+  }
+
+  const caveatBuilder = createCaveatBuilder(environment);
+
+  // Add calldata restrictions
+  if (allowedCalldata && allowedCalldata.length > 0) {
+    allowedCalldata.forEach((calldataConfig) => {
+      caveatBuilder.addCaveat('allowedCalldata', calldataConfig);
+    });
+  } else if (exactCalldata) {
+    caveatBuilder.addCaveat('exactCalldata', exactCalldata);
+  } else {
+    // Default behavior: only allow empty calldata
+    caveatBuilder.addCaveat('exactCalldata', {
       calldata: '0x',
-    })
-    .addCaveat('nativeTokenPeriodTransfer', {
-      periodAmount: config.periodAmount,
-      periodDuration: config.periodDuration,
-      startDate: config.startDate,
     });
+  }
+
+  // Add native token period transfer restriction
+  caveatBuilder.addCaveat('nativeTokenPeriodTransfer', {
+    periodAmount,
+    periodDuration,
+    startDate,
+  });
+
+  return caveatBuilder;
 }

packages/delegation-toolkit/src/caveatBuilder/scope/nativeTokenStreamingScope.ts

@@ -1,13 +1,17 @@
 import type { DeleGatorEnvironment } from '../../types';
+import type { AllowedCalldataBuilderConfig } from '../allowedCalldataBuilder';
 import { createCaveatBuilder } from '../coreCaveatBuilder';
 import type { CoreCaveatBuilder } from '../coreCaveatBuilder';
+import type { ExactCalldataBuilderConfig } from '../exactCalldataBuilder';
 import type {
   nativeTokenStreaming,
   NativeTokenStreamingBuilderConfig,
 } from '../nativeTokenStreamingBuilder';
 
 export type NativeTokenStreamingScopeConfig = {
   type: typeof nativeTokenStreaming;
+  allowedCalldata?: AllowedCalldataBuilderConfig[];
+  exactCalldata?: ExactCalldataBuilderConfig;
 } & NativeTokenStreamingBuilderConfig;
 
 /**
@@ -17,20 +21,51 @@ export type NativeTokenStreamingScopeConfig = {
  * @param config - Configuration object containing native token streaming parameters.
  * @returns A configured caveat builder with native token streaming and exact calldata caveats.
  * @throws Error if any of the native token streaming parameters are invalid.
+ * @throws Error if both allowedCalldata and exactCalldata are provided simultaneously.
  * @throws Error if the environment is not properly configured.
  */
 export function createNativeTokenStreamingCaveatBuilder(
   environment: DeleGatorEnvironment,
   config: NativeTokenStreamingScopeConfig,
 ): CoreCaveatBuilder {
-  return createCaveatBuilder(environment)
-    .addCaveat('exactCalldata', {
+  const {
+    initialAmount,
+    maxAmount,
+    amountPerSecond,
+    startTime,
+    allowedCalldata,
+    exactCalldata,
+  } = config;
+
+  if (allowedCalldata && allowedCalldata.length > 0 && exactCalldata) {
+    throw new Error(
+      'Cannot specify both allowedCalldata and exactCalldata. Please use only one calldata restriction type.',
+    );
+  }
+
+  const caveatBuilder = createCaveatBuilder(environment);
+
+  // Add calldata restrictions
+  if (allowedCalldata && allowedCalldata.length > 0) {
+    allowedCalldata.forEach((calldataConfig) => {
+      caveatBuilder.addCaveat('allowedCalldata', calldataConfig);
+    });
+  } else if (exactCalldata) {
+    caveatBuilder.addCaveat('exactCalldata', exactCalldata);
+  } else {
+    // Default behavior: only allow empty calldata
+    caveatBuilder.addCaveat('exactCalldata', {
       calldata: '0x',
-    })
-    .addCaveat('nativeTokenStreaming', {
-      initialAmount: config.initialAmount,
-      maxAmount: config.maxAmount,
-      amountPerSecond: config.amountPerSecond,
-      startTime: config.startTime,
     });
+  }
+
+  // Add native token streaming restriction
+  caveatBuilder.addCaveat('nativeTokenStreaming', {
+    initialAmount,
+    maxAmount,
+    amountPerSecond,
+    startTime,
+  });
+
+  return caveatBuilder;
 }

packages/delegation-toolkit/src/caveatBuilder/scope/nativeTokenTransferScope.ts

@@ -1,13 +1,17 @@
 import type { DeleGatorEnvironment } from '../../types';
+import type { AllowedCalldataBuilderConfig } from '../allowedCalldataBuilder';
 import { createCaveatBuilder } from '../coreCaveatBuilder';
 import type { CoreCaveatBuilder } from '../coreCaveatBuilder';
+import type { ExactCalldataBuilderConfig } from '../exactCalldataBuilder';
 import type {
   nativeTokenTransferAmount,
   NativeTokenTransferAmountBuilderConfig,
 } from '../nativeTokenTransferAmountBuilder';
 
 export type NativeTokenTransferScopeConfig = {
   type: typeof nativeTokenTransferAmount;
+  allowedCalldata?: AllowedCalldataBuilderConfig[];
+  exactCalldata?: ExactCalldataBuilderConfig;
 } & NativeTokenTransferAmountBuilderConfig;
 
 /**
@@ -17,17 +21,41 @@ export type NativeTokenTransferScopeConfig = {
  * @param config - Configuration object containing native token transfer parameters.
  * @returns A configured caveat builder with native token transfer amount and exact calldata caveats.
  * @throws Error if any of the native token transfer parameters are invalid.
+ * @throws Error if both allowedCalldata and exactCalldata are provided simultaneously.
  * @throws Error if the environment is not properly configured.
  */
 export function createNativeTokenTransferCaveatBuilder(
   environment: DeleGatorEnvironment,
   config: NativeTokenTransferScopeConfig,
 ): CoreCaveatBuilder {
-  return createCaveatBuilder(environment)
-    .addCaveat('exactCalldata', {
+  const { maxAmount, allowedCalldata, exactCalldata } = config;
+
+  if (allowedCalldata && allowedCalldata.length > 0 && exactCalldata) {
+    throw new Error(
+      'Cannot specify both allowedCalldata and exactCalldata. Please use only one calldata restriction type.',
+    );
+  }
+
+  const caveatBuilder = createCaveatBuilder(environment);
+
+  // Add calldata restrictions
+  if (allowedCalldata && allowedCalldata.length > 0) {
+    allowedCalldata.forEach((calldataConfig) => {
+      caveatBuilder.addCaveat('allowedCalldata', calldataConfig);
+    });
+  } else if (exactCalldata) {
+    caveatBuilder.addCaveat('exactCalldata', exactCalldata);
+  } else {
+    // Default behavior: only allow empty calldata
+    caveatBuilder.addCaveat('exactCalldata', {
       calldata: '0x',
-    })
-    .addCaveat('nativeTokenTransferAmount', {
-      maxAmount: config.maxAmount,
     });
+  }
+
+  // Add native token transfer amount restriction
+  caveatBuilder.addCaveat('nativeTokenTransferAmount', {
+    maxAmount,
+  });
+
+  return caveatBuilder;
 }

packages/delegation-toolkit/src/delegation.ts

@@ -185,10 +185,9 @@ type BaseCreateDelegationOptions = {
   environment: DeleGatorEnvironment;
   scope: ScopeConfig;
   from: Hex;
-  caveats: Caveats;
+  caveats?: Caveats;
   parentDelegation?: Delegation | Hex;
   salt?: Hex;
-  allowInsecureUnrestrictedDelegation?: boolean;
 };
 
 /**

packages/delegation-toolkit/test/DelegationFramework/DelegationManager/delegationManagement.test.ts

@@ -91,7 +91,6 @@ describe('DelegationManager - Delegation Management', () => {
           targets: [alice.address],
           selectors: ['0x00000000'],
         },
-        caveats: [],
       });
 
       const encodedData = DelegationManager.encode.disableDelegation({
@@ -117,7 +116,6 @@ describe('DelegationManager - Delegation Management', () => {
           targets: [alice.address],
           selectors: ['0x00000000'],
         },
-        caveats: [],
       });
 
       const encodedData = DelegationManager.encode.enableDelegation({
@@ -143,7 +141,6 @@ describe('DelegationManager - Delegation Management', () => {
           targets: [alice.address],
           selectors: ['0x00000000'],
         },
-        caveats: [],
       });
 
       const execution = createExecution({

packages/delegation-toolkit/test/caveatBuilder/scope/nativeTokenPeriodicScope.test.ts

@@ -10,6 +10,7 @@ describe('createNativeTokenPeriodicCaveatBuilder', () => {
   const environment = {
     caveatEnforcers: {
       ExactCalldataEnforcer: randomAddress(),
+      AllowedCalldataEnforcer: randomAddress(),
       NativeTokenPeriodTransferEnforcer: randomAddress(),
     },
   } as unknown as DeleGatorEnvironment;
@@ -46,4 +47,38 @@ describe('createNativeTokenPeriodicCaveatBuilder', () => {
       },
     ]);
   });
+
+  it('creates a native token periodic transfer CaveatBuilder with empty allowedCalldata array (should fall back to default)', () => {
+    const config: NativeTokenPeriodicScopeConfig = {
+      type: 'nativeTokenPeriodTransfer',
+      periodAmount: 1000n,
+      periodDuration: 1000,
+      startDate: Math.floor(Date.now() / 1000),
+      allowedCalldata: [], // Empty array should trigger fallback to default exactCalldata
+    };
+
+    const caveatBuilder = createNativeTokenPeriodicCaveatBuilder(
+      environment,
+      config,
+    );
+
+    const caveats = caveatBuilder.build();
+
+    expect(caveats).to.deep.equal([
+      {
+        enforcer: environment.caveatEnforcers.ExactCalldataEnforcer,
+        args: '0x',
+        terms: '0x',
+      },
+      {
+        enforcer: environment.caveatEnforcers.NativeTokenPeriodTransferEnforcer,
+        args: '0x',
+        terms: concat([
+          toHex(config.periodAmount, { size: 32 }),
+          toHex(config.periodDuration, { size: 32 }),
+          toHex(config.startDate, { size: 32 }),
+        ]),
+      },
+    ]);
+  });
 });