refactor(evm-wallet-experiment): split coordinator-vat into home/away (#939)

Splits the monolithic 3,275-line `coordinator-vat` into four focused
components — home coordinator, away coordinator, delegator vat, and
redeemer vat — and replaces raw caveat bytes with a discriminated union
of decoded semantic grant types.

**Architecture before:**
```
coordinator-vat (3,275 lines)   — home and away concerns mixed together
delegation-vat  (211 lines)     — limited grant handling
delegation-grant.ts             — builds grants from raw CaveatSpec arrays
```

**Architecture after:**
```
home-coordinator (2,388 lines)  — keyring, signing, delegation building, peer-relay relay
delegator-vat    (245 lines)    — caveat encoding, unsigned grant construction
away-coordinator (1,999 lines)  — grant reception, typed delegation routing
redeemer-vat     (57 lines)     — away-side grant storage
delegation-twin                 — semantic execution wrapper per grant
```

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> Large refactor touching core wallet execution/routing and delegation
redemption paths (UserOps, direct tx submission, spend limits), with
significant behavioral surface area and risk of regressions across
home/away flows.
> 
> **Overview**
> Splits the wallet subcluster’s coordinator responsibilities by
introducing role-based clustering: `makeWalletClusterConfig` now selects
`home-coordinator` vs `away-coordinator` bundles and swaps the auxiliary
vat to `delegator` (home) or `redeemer` (away), with updated tests and
build bundling.
> 
> Replaces the prior raw `DelegationGrant`/`CaveatSpec`-driven twin flow
with **semantic, discriminated grant types** (`TransferNativeGrant`,
`TransferFungibleGrant`) and a simplified `METHOD_CATALOG`; removes the
`delegation-grant` builder module and rewrites `makeDelegationTwin` to
enforce per-grant interface guards plus local spend/limit tracking.
> 
> Adds an `away-coordinator` vat implementing away-side routing, grant
receipt/storage integration, and redemption execution paths (incl.
ERC-4337/UserOp vs direct 7702 submission) plus new shared `tx-utils`
helpers for gas/result validation.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
088e26c. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

packages/evm-wallet-experiment/package.json

@@ -29,7 +29,7 @@
     "dist/"
   ],
   "scripts": {
-    "build": "ocap bundle src/vats/coordinator-vat.ts src/vats/keyring-vat.ts src/vats/provider-vat.ts src/vats/delegation-vat.ts",
+    "build": "ocap bundle src/vats/home-coordinator.ts src/vats/away-coordinator.ts src/vats/keyring-vat.ts src/vats/provider-vat.ts src/vats/delegator-vat.ts src/vats/redeemer-vat.ts",
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @ocap/evm-wallet-experiment",
     "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./dist ./.turbo ./logs",

packages/evm-wallet-experiment/src/cluster-config.test.ts

@@ -1,13 +1,12 @@
 import { describe, it, expect } from 'vitest';
 
 import { makeWalletClusterConfig } from './cluster-config.ts';
-import type { Address } from './types.ts';
 
 const BUNDLE_BASE_URL = 'http://localhost:3000';
 
 describe('cluster-config', () => {
   describe('makeWalletClusterConfig', () => {
-    it('creates a valid ClusterConfig', () => {
+    it('defaults to home role', () => {
       const config = makeWalletClusterConfig({
         bundleBaseUrl: BUNDLE_BASE_URL,
       });
@@ -17,7 +16,34 @@ describe('cluster-config', () => {
       expect(config.vats).toHaveProperty('coordinator');
       expect(config.vats).toHaveProperty('keyring');
       expect(config.vats).toHaveProperty('provider');
-      expect(config.vats).toHaveProperty('delegation');
+      expect(config.vats).toHaveProperty('delegator');
+      expect(config.vats).not.toHaveProperty('redeemer');
+    });
+
+    it('uses home-coordinator.bundle for home role', () => {
+      const config = makeWalletClusterConfig({
+        bundleBaseUrl: BUNDLE_BASE_URL,
+        role: 'home',
+      });
+
+      const coordConfig = config.vats.coordinator as { bundleSpec: string };
+      expect(coordConfig.bundleSpec).toBe(
+        `${BUNDLE_BASE_URL}/home-coordinator.bundle`,
+      );
+    });
+
+    it('uses away-coordinator.bundle for away role', () => {
+      const config = makeWalletClusterConfig({
+        bundleBaseUrl: BUNDLE_BASE_URL,
+        role: 'away',
+      });
+
+      const coordConfig = config.vats.coordinator as { bundleSpec: string };
+      expect(coordConfig.bundleSpec).toBe(
+        `${BUNDLE_BASE_URL}/away-coordinator.bundle`,
+      );
+      expect(config.vats).toHaveProperty('redeemer');
+      expect(config.vats).not.toHaveProperty('delegator');
     });
 
     it('includes OCAP URL services by default', () => {
@@ -40,40 +66,34 @@ describe('cluster-config', () => {
       expect(config.services).toStrictEqual(['customService']);
     });
 
-    it('sets delegation manager address as parameter', () => {
-      const address = '0xcccccccccccccccccccccccccccccccccccccccc' as Address;
+    it('has four vats for home role', () => {
       const config = makeWalletClusterConfig({
         bundleBaseUrl: BUNDLE_BASE_URL,
-        delegationManagerAddress: address,
+        role: 'home',
       });
+      const vatNames = Object.keys(config.vats);
 
-      expect(config.vats.delegation).toHaveProperty('parameters');
-      expect(
-        (config.vats.delegation as { parameters: Record<string, unknown> })
-          .parameters.delegationManagerAddress,
-      ).toBe(address);
+      expect(vatNames).toStrictEqual([
+        'coordinator',
+        'keyring',
+        'provider',
+        'delegator',
+      ]);
     });
 
-    it('has four vats with bundleSpec', () => {
+    it('has four vats for away role', () => {
       const config = makeWalletClusterConfig({
         bundleBaseUrl: BUNDLE_BASE_URL,
+        role: 'away',
       });
       const vatNames = Object.keys(config.vats);
 
       expect(vatNames).toStrictEqual([
         'coordinator',
         'keyring',
         'provider',
-        'delegation',
+        'redeemer',
       ]);
-
-      for (const vatName of vatNames) {
-        const vatConfig = config.vats[vatName] as { bundleSpec: string };
-        expect(vatConfig).toHaveProperty('bundleSpec');
-        expect(vatConfig.bundleSpec).toBe(
-          `${BUNDLE_BASE_URL}/${vatName}-vat.bundle`,
-        );
-      }
     });
 
     it('requests required globals for all vats', () => {
@@ -82,12 +102,11 @@ describe('cluster-config', () => {
       });
 
       const baseGlobals = ['TextEncoder', 'TextDecoder'];
-      for (const vatName of ['keyring', 'provider', 'delegation']) {
+      for (const vatName of ['keyring', 'provider', 'delegator']) {
         const vatConfig = config.vats[vatName] as { globals?: string[] };
         expect(vatConfig.globals).toStrictEqual(baseGlobals);
       }
 
-      // Coordinator additionally needs Date and setTimeout
       const coordConfig = config.vats.coordinator as { globals?: string[] };
       expect(coordConfig.globals).toStrictEqual([
         'TextEncoder',

packages/evm-wallet-experiment/src/cluster-config.ts

@@ -1,14 +1,11 @@
 import type { ClusterConfig } from '@metamask/ocap-kernel';
 
-import type { Address } from './types.ts';
-
 /**
  * Options for creating a wallet cluster configuration.
  */
 export type WalletClusterConfigOptions = {
   bundleBaseUrl: string;
-  delegationManagerAddress?: Address;
-  chainId?: number;
+  role?: 'home' | 'away';
   forceReset?: boolean;
   services?: string[];
   allowedHosts?: string[];
@@ -25,18 +22,38 @@ export function makeWalletClusterConfig(
 ): ClusterConfig {
   const {
     bundleBaseUrl,
-    delegationManagerAddress,
+    role = 'home',
     services = ['ocapURLIssuerService', 'ocapURLRedemptionService'],
     allowedHosts,
   } = options;
 
+  const coordinatorBundle =
+    role === 'home'
+      ? `${bundleBaseUrl}/home-coordinator.bundle`
+      : `${bundleBaseUrl}/away-coordinator.bundle`;
+
+  const auxiliaryVat =
+    role === 'home'
+      ? {
+          delegator: {
+            bundleSpec: `${bundleBaseUrl}/delegator-vat.bundle`,
+            globals: ['TextEncoder', 'TextDecoder'],
+          },
+        }
+      : {
+          redeemer: {
+            bundleSpec: `${bundleBaseUrl}/redeemer-vat.bundle`,
+            globals: ['TextEncoder', 'TextDecoder'],
+          },
+        };
+
   return {
     bootstrap: 'coordinator',
     forceReset: options.forceReset ?? false,
     services,
     vats: {
       coordinator: {
-        bundleSpec: `${bundleBaseUrl}/coordinator-vat.bundle`,
+        bundleSpec: coordinatorBundle,
         globals: ['TextEncoder', 'TextDecoder', 'Date', 'setTimeout'],
       },
       keyring: {
@@ -50,13 +67,7 @@ export function makeWalletClusterConfig(
           fetch: allowedHosts ? { allowedHosts } : {},
         },
       },
-      delegation: {
-        bundleSpec: `${bundleBaseUrl}/delegation-vat.bundle`,
-        globals: ['TextEncoder', 'TextDecoder'],
-        ...(delegationManagerAddress
-          ? { parameters: { delegationManagerAddress } }
-          : {}),
-      },
+      ...auxiliaryVat,
     },
   };
 }

packages/evm-wallet-experiment/src/index.ts

@@ -27,7 +27,6 @@ export type {
   Address,
   Action,
   Caveat,
-  CaveatSpec,
   CaveatType,
   ChainConfig,
   CreateDelegationOptions,
@@ -44,13 +43,14 @@ export type {
   SwapQuote,
   SwapResult,
   TransactionRequest,
+  TransferFungibleGrant,
+  TransferNativeGrant,
   UserOperation,
   WalletCapabilities,
 } from './types.ts';
 
 export {
   ActionStruct,
-  CaveatSpecStruct,
   CaveatStruct,
   CaveatTypeValues,
   ChainConfigStruct,
@@ -66,6 +66,8 @@ export {
   SmartAccountConfigStruct,
   SwapQuoteStruct,
   TransactionRequestStruct,
+  TransferFungibleGrantStruct,
+  TransferNativeGrantStruct,
   UserOperationStruct,
   WalletCapabilitiesStruct,
 } from './types.ts';
@@ -182,11 +184,5 @@ export type {
 export { METHOD_CATALOG } from './lib/method-catalog.ts';
 export type { CatalogMethodName } from './lib/method-catalog.ts';
 
-// Grant builder
-export {
-  buildDelegationGrant,
-  makeDelegationGrantBuilder,
-} from './lib/delegation-grant.ts';
-
 // Twin factory
 export { makeDelegationTwin } from './lib/delegation-twin.ts';