refactor(evm-wallet-experiment): deduplicate FIRST_ARG_OFFSET and ERC-20 grant builders

- Export FIRST_ARG_OFFSET from erc20.ts; remove local copies in
  delegation-grant.ts and delegation-twin.ts
- Extract buildErc20Grant helper from the near-identical
  buildTransferGrant/buildApproveGrant (~90 lines removed)
- Strengthen delegation twin method guards: M.any() -> M.string() for
  Hex returns, M.bigint() for getBalance
- Clarify cast: as keyof typeof METHOD_CATALOG -> as CatalogMethodName

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

packages/evm-wallet-experiment/src/lib/delegation-grant.ts

@@ -8,7 +8,11 @@ import {
   makeCaveat,
 } from './caveats.ts';
 import { makeDelegation } from './delegation.ts';
-import { ERC20_APPROVE_SELECTOR, ERC20_TRANSFER_SELECTOR } from './erc20.ts';
+import {
+  ERC20_APPROVE_SELECTOR,
+  ERC20_TRANSFER_SELECTOR,
+  FIRST_ARG_OFFSET,
+} from './erc20.ts';
 import type {
   Address,
   Caveat,
@@ -19,12 +23,6 @@ import type {
 
 const harden = globalThis.harden ?? (<T>(value: T): T => value);
 
-/**
- * Byte offset of the first argument in ABI-encoded calldata (after the
- * 4-byte function selector).
- */
-const FIRST_ARG_OFFSET = 4;
-
 /**
  * Encode an address as a 32-byte ABI-encoded word (left-padded with zeros).
  *
@@ -102,23 +100,47 @@ export function buildDelegationGrant(
   }
 }
 
+type Erc20GrantOptions = {
+  methodName: 'transfer' | 'approve';
+  selector: Hex;
+  delegator: Address;
+  delegate: Address;
+  token: Address;
+  max: bigint;
+  chainId: number;
+  validUntil?: number;
+  restrictedAddress?: Address;
+  entropy?: Hex;
+};
+
 /**
- * Build a transfer delegation grant.
+ * Build a delegation grant for an ERC-20 method (transfer or approve).
  *
- * @param options - Transfer grant options.
- * @returns An unsigned DelegationGrant for ERC-20 transfers.
+ * @param options - ERC-20 grant options.
+ * @param options.methodName - The catalog method name ('transfer' or 'approve').
+ * @param options.selector - The ERC-20 function selector.
+ * @param options.delegator - The delegating account address.
+ * @param options.delegate - The delegate account address.
+ * @param options.token - The ERC-20 token contract address.
+ * @param options.max - The maximum token amount allowed.
+ * @param options.chainId - The chain ID.
+ * @param options.validUntil - Optional Unix timestamp after which the delegation expires.
+ * @param options.restrictedAddress - Optional address to lock the first argument to.
+ * @param options.entropy - Optional entropy for delegation salt.
+ * @returns An unsigned DelegationGrant for the given ERC-20 method.
  */
-function buildTransferGrant(options: TransferOptions): DelegationGrant {
-  const {
-    delegator,
-    delegate,
-    token,
-    max,
-    chainId,
-    validUntil,
-    recipient,
-    entropy,
-  } = options;
+function buildErc20Grant({
+  methodName,
+  selector,
+  delegator,
+  delegate,
+  token,
+  max,
+  chainId,
+  validUntil,
+  restrictedAddress,
+  entropy,
+}: Erc20GrantOptions): DelegationGrant {
   const caveats: Caveat[] = [
     makeCaveat({
       type: 'allowedTargets',
@@ -127,7 +149,7 @@ function buildTransferGrant(options: TransferOptions): DelegationGrant {
     }),
     makeCaveat({
       type: 'allowedMethods',
-      terms: encodeAllowedMethods([ERC20_TRANSFER_SELECTOR]),
+      terms: encodeAllowedMethods([selector]),
       chainId,
     }),
     makeCaveat({
@@ -139,8 +161,8 @@ function buildTransferGrant(options: TransferOptions): DelegationGrant {
 
   const caveatSpecs: CaveatSpec[] = [{ type: 'cumulativeSpend', token, max }];
 
-  if (recipient !== undefined) {
-    const value = abiEncodeAddress(recipient);
+  if (restrictedAddress !== undefined) {
+    const value = abiEncodeAddress(restrictedAddress);
     caveats.push(
       makeCaveat({
         type: 'allowedCalldata',
@@ -178,7 +200,22 @@ function buildTransferGrant(options: TransferOptions): DelegationGrant {
     entropy,
   });
 
-  return harden({ delegation, methodName: 'transfer', caveatSpecs, token });
+  return harden({ delegation, methodName, caveatSpecs, token });
+}
+
+/**
+ * Build a transfer delegation grant.
+ *
+ * @param options - Transfer grant options.
+ * @returns An unsigned DelegationGrant for ERC-20 transfers.
+ */
+function buildTransferGrant(options: TransferOptions): DelegationGrant {
+  return buildErc20Grant({
+    ...options,
+    methodName: 'transfer',
+    selector: ERC20_TRANSFER_SELECTOR,
+    restrictedAddress: options.recipient,
+  });
 }
 
 /**
@@ -188,76 +225,12 @@ function buildTransferGrant(options: TransferOptions): DelegationGrant {
  * @returns An unsigned DelegationGrant for ERC-20 approvals.
  */
 function buildApproveGrant(options: ApproveOptions): DelegationGrant {
-  const {
-    delegator,
-    delegate,
-    token,
-    max,
-    chainId,
-    validUntil,
-    spender,
-    entropy,
-  } = options;
-  const caveats: Caveat[] = [
-    makeCaveat({
-      type: 'allowedTargets',
-      terms: encodeAllowedTargets([token]),
-      chainId,
-    }),
-    makeCaveat({
-      type: 'allowedMethods',
-      terms: encodeAllowedMethods([ERC20_APPROVE_SELECTOR]),
-      chainId,
-    }),
-    makeCaveat({
-      type: 'erc20TransferAmount',
-      terms: encodeErc20TransferAmount({ token, amount: max }),
-      chainId,
-    }),
-  ];
-
-  const caveatSpecs: CaveatSpec[] = [{ type: 'cumulativeSpend', token, max }];
-
-  if (spender !== undefined) {
-    const value = abiEncodeAddress(spender);
-    caveats.push(
-      makeCaveat({
-        type: 'allowedCalldata',
-        terms: encodeAllowedCalldata({ dataStart: FIRST_ARG_OFFSET, value }),
-        chainId,
-      }),
-    );
-    caveatSpecs.push({
-      type: 'allowedCalldata',
-      dataStart: FIRST_ARG_OFFSET,
-      value,
-    });
-  }
-
-  if (validUntil !== undefined) {
-    caveats.push(
-      makeCaveat({
-        type: 'timestamp',
-        terms: encodeTimestamp({ after: 0, before: validUntil }),
-        chainId,
-      }),
-    );
-    caveatSpecs.push({
-      type: 'blockWindow',
-      after: 0n,
-      before: BigInt(validUntil),
-    });
-  }
-
-  const delegation = makeDelegation({
-    delegator,
-    delegate,
-    caveats,
-    chainId,
-    entropy,
+  return buildErc20Grant({
+    ...options,
+    methodName: 'approve',
+    selector: ERC20_APPROVE_SELECTOR,
+    restrictedAddress: options.spender,
   });
-
-  return harden({ delegation, methodName: 'approve', caveatSpecs, token });
 }
 
 /**

packages/evm-wallet-experiment/src/lib/delegation-twin.ts

@@ -2,7 +2,11 @@ import { M } from '@endo/patterns';
 import type { MethodSchema } from '@metamask/kernel-utils';
 import { makeDiscoverableExo } from '@metamask/kernel-utils/discoverable';
 
-import { decodeBalanceOfResult, encodeBalanceOf } from './erc20.ts';
+import {
+  decodeBalanceOfResult,
+  encodeBalanceOf,
+  FIRST_ARG_OFFSET,
+} from './erc20.ts';
 import { GET_BALANCE_SCHEMA, METHOD_CATALOG } from './method-catalog.ts';
 import type { CatalogMethodName } from './method-catalog.ts';
 import type {
@@ -13,13 +17,6 @@ import type {
   Hex,
 } from '../types.ts';
 
-/**
- * Byte offset of the first argument in ABI-encoded calldata (after the
- * 4-byte function selector). An `allowedCalldata` caveat spec at this offset
- * pins the address argument for transfer/approve.
- */
-const FIRST_ARG_OFFSET = 4;
-
 const METHODS_WITH_ADDRESS_ARG: ReadonlySet<string> = new Set([
   'transfer',
   'approve',
@@ -64,9 +61,9 @@ function buildMethodGuard(
   switch (methodName) {
     case 'transfer':
     case 'approve':
-      return M.callWhen(addrGuard, M.scalar()).returns(M.any());
+      return M.callWhen(addrGuard, M.scalar()).returns(M.string());
     case 'call':
-      return M.callWhen(M.string(), M.scalar(), M.string()).returns(M.any());
+      return M.callWhen(M.string(), M.scalar(), M.string()).returns(M.string());
     default:
       throw new Error(`Unknown catalog method: ${String(methodName)}`);
   }
@@ -140,7 +137,7 @@ export function makeDelegationTwin(
   const { grant, redeemFn, readFn } = options;
   const { methodName, caveatSpecs, delegation } = grant;
 
-  const entry = METHOD_CATALOG[methodName as keyof typeof METHOD_CATALOG];
+  const entry = METHOD_CATALOG[methodName as CatalogMethodName];
   if (!entry) {
     throw new Error(`Unknown method in grant: ${methodName}`);
   }
@@ -219,7 +216,7 @@ export function makeDelegationTwin(
       return decodeBalanceOfResult(result);
     };
     schema.getBalance = GET_BALANCE_SCHEMA;
-    methodGuards.getBalance = M.callWhen().returns(M.any());
+    methodGuards.getBalance = M.callWhen().returns(M.bigint());
   }
 
   const interfaceGuard = M.interface(

packages/evm-wallet-experiment/src/lib/erc20.ts

@@ -12,6 +12,11 @@ const harden = globalThis.harden ?? (<T>(value: T): T => value);
 // Constants
 // ---------------------------------------------------------------------------
 
+/**
+ * Byte offset of the first argument in ABI-encoded calldata (after the 4-byte selector).
+ */
+export const FIRST_ARG_OFFSET = 4;
+
 /**
  * Function selector for ERC-20 `transfer(address,uint256)`.
  */