Minor refactor of redeemer address resolution, and clarity improvements to error messages.

Author: jeffsmale90

packages/smart-accounts-kit/src/experimental/x402DelegationProviderUtils.ts

@@ -34,6 +34,7 @@ type EnsureRedeemerSufficientlyConstrainedParams = {
   redeemerEnforcer: Hex;
   caveats: Caveat[];
   existingDelegations: Delegation[];
+  facilitatorAddresses: Address[] | undefined;
   redeemerAddresses: Address[] | undefined;
   requireRedeemers: boolean;
 };
@@ -61,10 +62,10 @@ type EnsureExpirySufficientlyConstrainedParams = {
 /**
  * Inputs for resolving allowed redeemer addresses.
  */
-type ResolveRedeemerAddressesParams = {
-  facilitatorAddresses?: Address[];
-  redeemerAddresses?: Address[];
-};
+type ResolveRedeemerAddressesParams = Pick<
+  EnsureRedeemerSufficientlyConstrainedParams,
+  'facilitatorAddresses' | 'redeemerAddresses'
+>;
 
 /**
  * Resolved context required to build and sign an x402 delegation.
@@ -245,13 +246,16 @@ export const ensureExpirySufficientlyConstrained = ({
 };
 
 /**
- * Resolves the allowed redeemer addresses from the union of facilitator specified and caller specified redeemer addresses.
- * If either are undefined, the other is returned.
+ * Resolves allowed redeemer addresses from facilitator and configured redeemer inputs.
+ *
+ * If both inputs are provided, returns their intersection.
+ * If only one input is provided, returns that input.
+ * If neither input is provided, returns undefined.
  *
  * @param options - Redeemer address inputs.
  * @param options.facilitatorAddresses - Optional facilitator addresses from the PaymentRequirements.
  * @param options.redeemerAddresses - Optional redeemer addresses from the RedeemersConfig.
- * @returns The allowed redeemer addresses, or undefined if none are specified.
+ * @returns Resolved allowed redeemer addresses, or undefined when no input is provided.
  */
 const resolveRedeemerAddresses = ({
   facilitatorAddresses,
@@ -288,40 +292,44 @@ const resolveRedeemerAddresses = ({
  * Returns the caveat list unchanged when an existing redeemer caveat is already
  * strict enough, or appends a new redeemer caveat scoped to facilitator addresses.
  *
- * @param options0 - Redeemer constraint evaluation inputs.
- * @param options0.redeemerEnforcer - Address of the redeemer enforcer caveat contract.
- * @param options0.caveats - Currently resolved caveats for the delegation being created.
- * @param options0.existingDelegations - Existing parent-chain delegations to inspect for inherited constraints.
- * @param options0.redeemerAddresses - Optional addresses to which redemption should be constrained.
- * @param options0.requireRedeemers - Whether at least one redeemer constraint must exist when no redeemer addresses are supplied.
+ * @param config - Redeemer constraint evaluation inputs.
+ * @param config.redeemerEnforcer - Address of the redeemer enforcer caveat contract.
+ * @param config.caveats - Currently resolved caveats for the delegation being created.
+ * @param config.existingDelegations - Existing parent-chain delegations to inspect for inherited constraints.
+ * @param config.redeemerAddresses - Optional addresses to which redemption should be constrained.
+ * @param config.requireRedeemers - Whether at least one redeemer constraint must exist.
  * @returns The original caveats when sufficiently constrained, otherwise caveats with a redeemer caveat appended.
- * @throws If no facilitator addresses are provided and no redeemer constraint exists.
+ * @throws If either facilitatorAddresses and/or redeemerAddresses are provided, but the intersection is empty.
+ * @throws If requireRedeemers is true, but no valid redeemer addresses are provided, and no existing redeemer caveat is found in the existingDelegations.
  */
-export const ensureRedeemerSufficientlyConstrained = ({
-  redeemerEnforcer,
-  caveats,
-  existingDelegations,
-  redeemerAddresses,
-  requireRedeemers,
-}: EnsureRedeemerSufficientlyConstrainedParams): Caveat[] => {
-  const redeemerEnforcerNormalized = normalizeAddress(redeemerEnforcer);
-
+export const ensureRedeemerSufficientlyConstrained = (
+  config: EnsureRedeemerSufficientlyConstrainedParams,
+): Caveat[] => {
+  // `redeemerAddresses` is the intersection of `facilitatorAddresses` and `redeemerAddresses`.
+  // If either is undefined, it implies no constraint is specified by that value, and the other is returned.
+  // If both are undefined, it implies that no constraint is specified overall.
+  const redeemerAddresses = resolveRedeemerAddresses(config);
+
+  // If the result is defined, but zero-length, it implies no redeemers are allowed, which is a non-satisfiable constraint, so an error is thrown.
   if (redeemerAddresses?.length === 0) {
     throw new Error(
-      'No valid redeemer addresses were resolved. The intersection of `redeemers.addresses` and `extra.facilitatorAddresses` must be non-empty.',
+      'No valid redeemer addresses were resolved. If both `redeemers.addresses` and `extra.facilitatorAddresses` are provided, they must overlap. If only one is provided, it must include at least one address.',
     );
   }
 
+  const redeemerEnforcer = normalizeAddress(config.redeemerEnforcer);
+
+  const { caveats, existingDelegations } = config;
+
   if (!redeemerAddresses) {
-    if (!requireRedeemers) {
+    if (!config.requireRedeemers) {
       return caveats;
     }
 
     const hasExistingRedeemerCaveat = hasMatchingCaveats(
       caveats,
       existingDelegations,
-      ({ enforcer }) =>
-        normalizeAddress(enforcer) === redeemerEnforcerNormalized,
+      ({ enforcer }) => normalizeAddress(enforcer) === redeemerEnforcer,
     );
 
     if (!hasExistingRedeemerCaveat) {
@@ -333,22 +341,21 @@ export const ensureRedeemerSufficientlyConstrained = ({
     return caveats;
   }
 
-  const redeemerAddressesNormalized = redeemerAddresses.map(normalizeAddress);
-  const redeemerAddressesSet = new Set(redeemerAddressesNormalized);
+  const redeemerAddressesSet = new Set(redeemerAddresses.map(normalizeAddress));
 
   const hasSupersedingRedeemerCaveat = hasMatchingCaveats(
     caveats,
     existingDelegations,
     (caveat) => {
-      if (normalizeAddress(caveat.enforcer) !== redeemerEnforcerNormalized) {
+      if (normalizeAddress(caveat.enforcer) !== redeemerEnforcer) {
         return false;
       }
 
       const allowedRedeemerAddresses = decodeRedeemerTerms(
         caveat.terms,
       ).redeemers.map(normalizeAddress);
 
-      // If this redeemer caveat only allows facilitator addresses, it is sufficiently constrained.
+      // If this redeemer caveat only allows redeemer addresses, it is sufficiently constrained.
       return allowedRedeemerAddresses.every((item) =>
         redeemerAddressesSet.has(item),
       );
@@ -472,16 +479,12 @@ export const resolvex402DelegationCaveats = ({
     isScopeOptional: true,
   });
 
-  const resolvedRedeemerAddresses = resolveRedeemerAddresses({
-    facilitatorAddresses,
-    redeemerAddresses,
-  });
-
   const caveatsWithRedeemer = ensureRedeemerSufficientlyConstrained({
     redeemerEnforcer,
+    facilitatorAddresses,
+    redeemerAddresses,
     caveats: initialCaveats,
     existingDelegations,
-    redeemerAddresses: resolvedRedeemerAddresses,
     requireRedeemers,
   });
 

packages/smart-accounts-kit/test/experimental/x402DelegationProviderUtils.test.ts

@@ -83,12 +83,11 @@ describe('x402DelegationProviderUtils', () => {
           redeemerEnforcer,
           caveats: [],
           existingDelegations: [],
+          facilitatorAddresses: undefined,
           redeemerAddresses: [],
           requireRedeemers: false,
         }),
-      ).toThrow(
-        'No valid redeemer addresses were resolved. The intersection of `redeemers.addresses` and `extra.facilitatorAddresses` must be non-empty.',
-      );
+      ).toThrow('No valid redeemer addresses were resolved.');
     });
 
     it('throws when redeemer addresses are empty and redeemers are required', () => {
@@ -97,12 +96,11 @@ describe('x402DelegationProviderUtils', () => {
           redeemerEnforcer,
           caveats: [],
           existingDelegations: [],
+          facilitatorAddresses: undefined,
           redeemerAddresses: [],
           requireRedeemers: true,
         }),
-      ).toThrow(
-        'No valid redeemer addresses were resolved. The intersection of `redeemers.addresses` and `extra.facilitatorAddresses` must be non-empty.',
-      );
+      ).toThrow('No valid redeemer addresses were resolved.');
     });
 
     it('returns caveats unchanged when redeemer addresses are missing and redeemers are optional', () => {
@@ -112,6 +110,7 @@ describe('x402DelegationProviderUtils', () => {
         redeemerEnforcer,
         caveats: initialCaveats,
         existingDelegations: [],
+        facilitatorAddresses: undefined,
         redeemerAddresses: undefined,
         requireRedeemers: false,
       });
@@ -125,6 +124,7 @@ describe('x402DelegationProviderUtils', () => {
           redeemerEnforcer,
           caveats: [],
           existingDelegations: [],
+          facilitatorAddresses: undefined,
           redeemerAddresses: undefined,
           requireRedeemers: true,
         }),
@@ -152,6 +152,7 @@ describe('x402DelegationProviderUtils', () => {
             },
           ]),
         ],
+        facilitatorAddresses: undefined,
         redeemerAddresses: undefined,
         requireRedeemers: true,
       });
@@ -172,6 +173,7 @@ describe('x402DelegationProviderUtils', () => {
         redeemerEnforcer,
         caveats: initialCaveats,
         existingDelegations: [],
+        facilitatorAddresses: undefined,
         redeemerAddresses: [facilitatorA, facilitatorB],
         requireRedeemers: true,
       });
@@ -196,6 +198,7 @@ describe('x402DelegationProviderUtils', () => {
             },
           ]),
         ],
+        facilitatorAddresses: undefined,
         redeemerAddresses: [facilitatorA, facilitatorB],
         requireRedeemers: true,
       });