@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/src/network.ts

@@ -0,0 +1,302 @@
+import {
+  findNetwork,
+  MetrikClient,
+  networkDeployments,
+  type MetrikNetworkDeployment,
+  getNetwork,
+  listNetworks,
+  networkForCaip2,
+  networkForChainId,
+  type MetrikNetwork,
+} from "@absol-labs/sdk";
+import { defineChain, isAddress, isAddressEqual, type Chain } from "viem";
+
+/**
+ * The agent layer's ONE view of where Metrik is deployed.
+ *
+ * Every chain id, CAIP-2 id, contract address, deploy block, default RPC, gas
+ * token and oracle origin this package uses comes from the `@absol-labs/sdk`
+ * network registry through this module. Nothing under `src/` may hardcode them
+ * (`test/no-hardcoded-chain.test.ts` fails the build if anything does), so a new
+ * deployment — the V3 escrow and factory included — is a registry/config change,
+ * not a code change here.
+ *
+ * What the agent adds on top of the registry is only what the registry does not
+ * describe: which network is the DEFAULT for a surface that is given none, and
+ * where a test wallet gets funded (a faucet is an off-chain courtesy, not a
+ * deployment fact).
+ */
+
+/**
+ * The registry id every surface defaults to when no network is selected. An
+ * id, not a chain id: the registry resolves it to the chain, addresses and RPC.
+ */
+export const DEFAULT_METRIK_NETWORK_ID = "baseSepolia";
+
+/** Environment variable that selects the network by id, chain id or CAIP-2 id. */
+export const METRIK_NETWORK_ENV = "METRIK_NETWORK";
+
+/** What a surface is allowed to settle on, beyond "the registry knows it". */
+export interface NetworkPolicy {
+  /**
+   * Refuse a registered network that is not a testnet. The CLI and the agent
+   * frameworks sign with keys read from the environment, so they keep the
+   * testnet-only rule; the registry's `testnet` flag is the source of truth.
+   */
+  readonly testnetOnly?: boolean;
+}
+
+/** A network the registry does not know, or one the build does not allow. */
+export class UnsupportedNetworkError extends Error {
+  readonly selector: string;
+
+  constructor(selector: string, message: string) {
+    super(message);
+    this.name = "UnsupportedNetworkError";
+    this.selector = selector;
+  }
+}
+
+/** The network a surface uses when none is selected. */
+export function defaultNetwork(): MetrikNetwork {
+  return getNetwork(DEFAULT_METRIK_NETWORK_ID);
+}
+
+/** Every registered network the policy allows, in registry order. */
+export function allowedNetworks(policy: NetworkPolicy = {}): MetrikNetwork[] {
+  return listNetworks().filter(
+    (network) => policy.testnetOnly !== true || network.testnet,
+  );
+}
+
+/** `"<chainId> (<name>)"` for every allowed network, for error messages. */
+export function describeAllowedNetworks(policy: NetworkPolicy = {}): string {
+  const allowed = allowedNetworks(policy);
+  if (allowed.length === 0) return "(none registered)";
+  return allowed
+    .map((network) => `${network.chain.id} (${network.name}, "${network.id}")`)
+    .join(", ");
+}
+
+/**
+ * Resolve a network selector — a registry id (e.g. the default
+ * {@link DEFAULT_METRIK_NETWORK_ID}), an EVM chain id (as a number or a decimal
+ * string), or a CAIP-2 id (`eip155:<chainId>`) — to a registered
+ * network the policy allows. `undefined` (or empty) selects the default.
+ *
+ * Fail closed: an unknown selector, or a known network the policy forbids, is an
+ * {@link UnsupportedNetworkError}, never a silent fallback to the default.
+ */
+export function resolveAgentNetwork(
+  selector: string | number | undefined,
+  policy: NetworkPolicy = {},
+): MetrikNetwork {
+  const raw =
+    typeof selector === "number" ? String(selector) : selector?.trim();
+  const network =
+    raw === undefined || raw.length === 0
+      ? defaultNetwork()
+      : lookupNetwork(raw);
+  if (network === undefined) {
+    throw new UnsupportedNetworkError(
+      raw ?? "",
+      `unknown Metrik network "${raw}": the SDK network registry knows ${describeAllowedNetworks()}`,
+    );
+  }
+  assertNetworkAllowed(network, policy, raw ?? network.id);
+  return network;
+}
+
+/** The registered network on `chainId` the policy allows; throws otherwise. */
+export function requireNetworkForChainId(
+  chainId: number,
+  policy: NetworkPolicy = {},
+  source = "the configured chain id",
+): MetrikNetwork {
+  const network = networkForChainId(chainId);
+  if (network === undefined) {
+    throw new UnsupportedNetworkError(
+      String(chainId),
+      `${source} ${chainId} is not a network the Metrik registry knows (registered: ${describeAllowedNetworks()})`,
+    );
+  }
+  assertNetworkAllowed(network, policy, source);
+  return network;
+}
+
+/** The registered network with this CAIP-2 id the policy allows; throws otherwise. */
+export function requireNetworkForCaip2(
+  caip2: string,
+  policy: NetworkPolicy = {},
+  source = "the configured network",
+): MetrikNetwork {
+  const network = networkForCaip2(caip2);
+  if (network === undefined) {
+    throw new UnsupportedNetworkError(
+      caip2,
+      `${source} ${caip2} is not a network the Metrik registry knows (registered: ${describeAllowedNetworks()})`,
+    );
+  }
+  assertNetworkAllowed(network, policy, source);
+  return network;
+}
+
+function lookupNetwork(raw: string): MetrikNetwork | undefined {
+  if (/^\d+$/.test(raw)) return networkForChainId(Number(raw));
+  if (raw.startsWith("eip155:")) return networkForCaip2(raw);
+  return findNetwork(raw);
+}
+
+function assertNetworkAllowed(
+  network: MetrikNetwork,
+  policy: NetworkPolicy,
+  source: string,
+): void {
+  if (policy.testnetOnly === true && !network.testnet) {
+    throw new UnsupportedNetworkError(
+      source,
+      `refusing ${network.name} (chain ${network.chain.id}): this surface is testnet-only. Allowed: ${describeAllowedNetworks(policy)}`,
+    );
+  }
+}
+
+/**
+ * The network's registered deployment (the CURRENT one, or a `legacy` one that
+ * still holds streams) whose escrow is `escrow`, or `undefined`.
+ */
+export function registeredDeployment(
+  network: MetrikNetwork,
+  escrow: string,
+): (MetrikNetworkDeployment & { readonly legacy: boolean }) | undefined {
+  if (!isAddress(escrow)) return undefined;
+  const deployments = networkDeployments(network);
+  const index = deployments.findIndex((entry) =>
+    isAddressEqual(entry.escrow.address, escrow),
+  );
+  return index < 0
+    ? undefined
+    : { ...(deployments[index] as MetrikNetworkDeployment), legacy: index > 0 };
+}
+
+/**
+ * Whether `escrow` is one of the network's registered escrows — the current
+ * one or a legacy one (whose streams can still be read, closed and
+ * reclaimed; the SDK refuses NEW opens on it unless explicitly opted in).
+ */
+export function isRegisteredEscrow(
+  network: MetrikNetwork,
+  escrow: string,
+): boolean {
+  return registeredDeployment(network, escrow) !== undefined;
+}
+
+/**
+ * The viem chain for a chain id: the registered network's chain when there is
+ * one, otherwise a minimal chain definition around the given RPC (so a custom,
+ * explicitly configured deployment still signs with the right chain id).
+ */
+export function chainForChainId(chainId: number, rpcUrl: string): Chain {
+  const registered = networkForChainId(chainId);
+  if (registered !== undefined) return registered.chain;
+  return defineChain({
+    id: chainId,
+    name: `eip155:${String(chainId)}`,
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: { default: { http: [rpcUrl] } },
+  });
+}
+
+/**
+ * A read-only `MetrikClient` for one escrow on a REGISTERED network (default:
+ * the registry's default network). The chain, the default USDC and oracle, and
+ * opener-factory detection all come from the registry; the escrow and RPC are
+ * the caller's. A chain id the registry does not know is refused — register the
+ * network with the SDK's `registerNetwork()` first.
+ */
+export function readOnlyMetrikClient(options: {
+  readonly escrowAddress: `0x${string}`;
+  readonly rpcUrl: string;
+  readonly chainId?: number;
+  /**
+   * Only for an escrow the registry does NOT record (a deliberate private
+   * deployment): its declared generation. The SDK then skips its code-hash
+   * pin. Ignored for a registered escrow, whose generation is the registry's.
+   */
+  readonly unregisteredEscrowGeneration?: "v2" | "v3";
+}): MetrikClient {
+  const network =
+    options.chainId === undefined
+      ? defaultNetwork()
+      : requireNetworkForChainId(options.chainId);
+  const registered = registeredDeployment(network, options.escrowAddress);
+  return MetrikClient.forNetwork(network, {
+    escrow: options.escrowAddress,
+    rpcUrl: options.rpcUrl,
+    ...(registered === undefined &&
+    options.unregisteredEscrowGeneration !== undefined
+      ? {
+          allowUnregisteredEscrow: true,
+          generation: options.unregisteredEscrowGeneration,
+        }
+      : {}),
+  });
+}
+
+// ── Funding hints ────────────────────────────────────────────────────────────
+
+/**
+ * Where a test wallet on a network gets its gas and its USDC. Off-chain
+ * courtesy data the registry does not carry; keyed by registry id, never by
+ * chain id.
+ */
+export interface NetworkFunding {
+  /** A faucet for the network's GAS token, or `null` if none is known. */
+  readonly gasFaucetUrl: string | null;
+  /** A faucet for the network's settlement USDC, or `null` if none is known. */
+  readonly usdcFaucetUrl: string | null;
+  /** The Coinbase CDP faucet's name for this network, or `null` if CDP has none. */
+  readonly cdpNetwork: string | null;
+}
+
+const NETWORK_FUNDING: Readonly<Record<string, NetworkFunding>> = {
+  baseSepolia: {
+    gasFaucetUrl: "https://www.alchemy.com/faucets/base-sepolia",
+    usdcFaucetUrl: "https://faucet.circle.com",
+    cdpNetwork: "base-sepolia",
+  },
+};
+
+/** Funding hints for a network; all `null` for a network with none known. */
+export function networkFunding(network: MetrikNetwork): NetworkFunding {
+  return (
+    NETWORK_FUNDING[network.id] ?? {
+      gasFaucetUrl: null,
+      usdcFaucetUrl: null,
+      cdpNetwork: null,
+    }
+  );
+}
+
+/**
+ * One sentence telling a user how to fund GAS on this network, read from the
+ * network's gas-token metadata. Where gas is the settlement token (USDC), the
+ * USDC faucet is the gas faucet.
+ */
+export function gasFundingHint(network: MetrikNetwork): string {
+  const funding = networkFunding(network);
+  const symbol = network.gasToken.symbol;
+  const url = network.gasToken.isSettlementToken
+    ? funding.usdcFaucetUrl
+    : funding.gasFaucetUrl;
+  return url === null
+    ? `acquire ${symbol} on ${network.name}`
+    : `fund it with ${symbol} at ${url}`;
+}
+
+/** One sentence telling a user how to fund the settlement USDC on this network. */
+export function usdcFundingHint(network: MetrikNetwork): string {
+  const url = networkFunding(network).usdcFaucetUrl;
+  return url === null
+    ? `acquire USDC on ${network.name}`
+    : `fund it with USDC at ${url} (${network.name})`;
+}

package/src/sdk/client.ts

@@ -87,6 +87,11 @@ export interface AgentSdkClient {
   claimable(streamId: `0x${string}`): Promise<bigint>;
   reclaimable(streamId: `0x${string}`): Promise<bigint>;
   claim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  /**
+   * StreamEscrowV3 only: redeem the on-chain proven high-water without a proof.
+   * Optional so an existing custom SDK client keeps compiling.
+   */
+  claimProven?(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   close(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   reclaim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   /**
@@ -192,6 +197,26 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
     return await this.sdkClient.claim(input.streamId);
   }
 
+  /**
+   * Operator-only, StreamEscrowV3 only: redeem the stream's on-chain proven
+   * high-water (`claimProven`) without a fresh proof. Authorized exactly like
+   * {@link claimStream} — it pays the same party from the same escrow, only an
+   * amount already proven against a signed checkpoint root and recorded
+   * on-chain, so it can never pay more than a proof claim could have.
+   */
+  async claimProvenStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    const claimProven = this.sdkClient.claimProven?.bind(this.sdkClient);
+    if (claimProven === undefined) {
+      throw new Error(
+        "this SDK client cannot send claimProven (StreamEscrowV3 only)",
+      );
+    }
+    await this.authorizeExistingStreamAction(input);
+    return await claimProven(input.streamId);
+  }
+
   async closeStream(
     input: MandateAuthorizedStreamActionInput,
   ): Promise<StreamProofTransactionResult> {

package/src/sdk/invoke.ts

@@ -6,7 +6,6 @@ import {
   signedServiceDescriptorSchema,
   type DeliveryReceiptDomainInput,
 } from "@absol-labs/shared";
-import { MetrikClient } from "@absol-labs/sdk";
 import type { Address, Hex, LocalAccount } from "viem";
 
 import type { ServiceListing } from "../discovery/registry.js";
@@ -30,6 +29,7 @@ import {
   type SignedInvocationCapability,
   DEFAULT_CAPABILITY_TTL_SECONDS,
 } from "../capability/invocation-capability.js";
+import { readOnlyMetrikClient } from "../network.js";
 
 /**
  * Buyer half of the pay -> use loop (metrik-agent#64, impl of #62 part 2/2).
@@ -57,11 +57,12 @@ export interface InvokeStreamReader {
 export function createSdkInvokeStreamReader(options: {
   readonly escrowAddress: Address;
   readonly rpcUrl: string;
+  /** Chain of the escrow; must be a registered network. Default: the registry default. */
+  readonly chainId?: number;
+  /** See `readOnlyMetrikClient`: only for an escrow the registry does not record. */
+  readonly unregisteredEscrowGeneration?: "v2" | "v3";
 }): InvokeStreamReader {
-  const metrik = MetrikClient.baseSepolia({
-    escrow: options.escrowAddress,
-    rpcUrl: options.rpcUrl,
-  });
+  const metrik = readOnlyMetrikClient(options);
   return {
     async getStreamV2(streamId) {
       const stream = await metrik.getStreamV2(streamId);

package/src/wallet/autonomous-wallet-broker.ts

@@ -4,7 +4,6 @@ import {
   formatRequestForAuthorizationSignature,
   type PrivyClient,
 } from "@privy-io/node";
-import { streamEscrowV2Abi } from "@absol-labs/shared";
 import {
   decodeFunctionData,
   getAddress,
@@ -16,6 +15,7 @@ import { z } from "zod";
 
 import {
   autonomousProofBytes,
+  AUTONOMOUS_WALLET_CAIP2,
   AUTONOMOUS_WALLET_CHAIN_ID,
   AUTONOMOUS_WALLET_VERSION,
   type AutonomousWalletBroker as AutonomousWalletClientBroker,
@@ -35,6 +35,14 @@ import {
   PRIVY_BROKER_USDC,
   type BrokerStreamReader,
 } from "./privy-session-broker.js";
+import {
+  BROKER_EXIT_METHODS,
+  brokerEscrowPolicy,
+  decodeEscrowCall,
+  escrowRole,
+  type BrokerEscrowPolicy,
+} from "./broker-escrows.js";
+import { defaultNetwork } from "../network.js";
 
 const transactionSchema = z.object({
   from: z.string().refine(isAddress),
@@ -137,6 +145,8 @@ export interface AutonomousWalletBrokerOptions {
   readonly requestTtlSeconds?: number;
   /** Must match the base URL used by the Privy client, without a trailing slash. */
   readonly privyApiBaseUrl?: string;
+  /** Current + legacy escrows. Default: from the registries (see `./broker-escrows.ts`). */
+  readonly escrows?: BrokerEscrowPolicy;
 }
 
 /**
@@ -288,6 +298,7 @@ export class AutonomousWalletBroker implements AutonomousWalletClientBroker {
       provision.address,
       this.options.streamReader,
       this.nowSeconds(),
+      this.options.escrows ?? brokerEscrowPolicy(defaultNetwork()),
     );
     const requestExpiryMs = (this.nowSeconds() + this.requestTtl) * 1_000;
     const idempotencyKey = randomUUID();
@@ -558,6 +569,7 @@ async function buildRpcBody(
   address: Address,
   streamReader: BrokerStreamReader,
   now: number,
+  escrows: BrokerEscrowPolicy,
 ): Promise<Record<string, unknown>> {
   if (method === "eth_sendTransaction") {
     const tx = transactionSchema.parse(params[0]);
@@ -568,11 +580,19 @@ async function buildRpcBody(
       );
     assertChain(tx.chainId);
     assertZeroValue(tx.value);
-    const target = getAddress(tx.to).toLowerCase();
-    if (target === PRIVY_BROKER_USDC.toLowerCase()) {
-      assertUsdcApproval(tx.data as Hex);
-    } else if (target === PRIVY_BROKER_ESCROW.toLowerCase()) {
-      await assertEscrowMethod(tx.data as Hex, address, streamReader);
+    const target = getAddress(tx.to);
+    const role = escrowRole(escrows, target);
+    if (target.toLowerCase() === PRIVY_BROKER_USDC.toLowerCase()) {
+      // The approval spender must be the CURRENT escrow, never a legacy one.
+      assertUsdcApproval(tx.data as Hex, escrows.current);
+    } else if (role !== null) {
+      await assertEscrowMethod(
+        tx.data as Hex,
+        address,
+        streamReader,
+        target,
+        role,
+      );
     } else {
       throw new AutonomousWalletBrokerError(
         "policy-denied",
@@ -583,7 +603,7 @@ async function buildRpcBody(
     return {
       method,
       chain_type: "ethereum",
-      caip2: "eip155:84532",
+      caip2: AUTONOMOUS_WALLET_CAIP2,
       params: { transaction: normalizeJson(transaction) },
     };
   }
@@ -613,7 +633,7 @@ async function buildRpcBody(
     parsed.domain.name !== invocationCapabilityDomainName ||
     parsed.domain.version !== invocationCapabilityDomainVersion ||
     parsed.domain.verifyingContract.toLowerCase() !==
-      PRIVY_BROKER_ESCROW.toLowerCase()
+      escrows.current.toLowerCase()
   )
     throw new AutonomousWalletBrokerError(
       "policy-denied",
@@ -655,7 +675,7 @@ async function buildRpcBody(
   return {
     method,
     chain_type: "ethereum",
-    caip2: "eip155:84532",
+    caip2: AUTONOMOUS_WALLET_CAIP2,
     params: {
       typed_data: normalizeJson({
         ...wireTypedData,
@@ -704,7 +724,7 @@ function assertZeroValue(value: string | number | bigint | undefined): void {
   }
 }
 
-function assertUsdcApproval(data: Hex): void {
+function assertUsdcApproval(data: Hex, currentEscrow: Address): void {
   try {
     const decoded = decodeFunctionData({
       abi: [
@@ -723,7 +743,7 @@ function assertUsdcApproval(data: Hex): void {
     });
     const [spender, amount] = decoded.args;
     if (
-      spender.toLowerCase() !== PRIVY_BROKER_ESCROW.toLowerCase() ||
+      spender.toLowerCase() !== currentEscrow.toLowerCase() ||
       amount > 1_000_000n
     )
       throw new Error("approval outside Metrik policy");
@@ -740,10 +760,13 @@ async function assertEscrowMethod(
   data: Hex,
   address: Address,
   streamReader: BrokerStreamReader,
+  escrow: Address,
+  role: "current" | "legacy",
 ): Promise<void> {
   try {
-    const decoded = decodeFunctionData({ abi: streamEscrowV2Abi, data });
-    if (decoded.functionName === "openStream") {
+    const decoded = decodeEscrowCall(data);
+    // A legacy escrow is exit-only: openStream there falls through and fails.
+    if (decoded.functionName === "openStream" && role === "current") {
       const [, , deposit, rate, duration] = decoded.args;
       if (
         deposit > PRIVY_POLICY_MAX_TOTAL_USDC ||
@@ -754,14 +777,17 @@ async function assertEscrowMethod(
       }
       return;
     }
-    if (
-      decoded.functionName !== "close" &&
-      decoded.functionName !== "reclaim" &&
-      decoded.functionName !== "reclaimUnverified"
-    ) {
-      throw new Error("escrow method is not allowlisted");
+    if (!BROKER_EXIT_METHODS.has(decoded.functionName)) {
+      throw new Error(
+        role === "legacy"
+          ? "only close, reclaim and reclaimUnverified are allowed on a legacy escrow"
+          : "escrow method is not allowlisted",
+      );
     }
-    const stream = await streamReader.getStream(decoded.args[0]);
+    const stream = await streamReader.getStream(
+      (decoded.args as readonly unknown[])[0] as Hex,
+      escrow,
+    );
     if (stream.buyer.toLowerCase() !== address.toLowerCase())
       throw new Error("autonomous wallet is not the stream buyer");
   } catch (error) {

package/src/wallet/autonomous-wallet-protocol.ts

@@ -1,8 +1,17 @@
 import type { Address, Hex } from "viem";
 
+import { defaultNetwork } from "../network.js";
+
 export const AUTONOMOUS_WALLET_VERSION = 1 as const;
-export const AUTONOMOUS_WALLET_CHAIN_ID = 84532 as const;
-export const AUTONOMOUS_WALLET_CAIP2 = "eip155:84532" as const;
+/**
+ * The network an agent-owned Privy wallet is provisioned and policed on: the
+ * registry's default network. A broker's Privy policy allowlists ONE escrow and
+ * ONE USDC, so the wallet is single-network by construction; the values come
+ * from the `@absol-labs/sdk` registry rather than literals.
+ */
+export const AUTONOMOUS_WALLET_CHAIN_ID: number = defaultNetwork().chain.id;
+export const AUTONOMOUS_WALLET_CAIP2: `eip155:${number}` =
+  defaultNetwork().caip2;
 
 export interface PreparedPrivyRequest {
   readonly requestId: string;

package/src/wallet/autonomous-wallet.ts

@@ -27,6 +27,7 @@ import {
   type AutonomousWalletCredentialStore,
   type AutonomousWalletRecord,
 } from "./autonomous-wallet-store.js";
+import { defaultNetwork } from "../network.js";
 
 export {
   AUTONOMOUS_WALLET_CAIP2,
@@ -366,7 +367,8 @@ export function createAutonomousWalletProvider(
   let rpcId = 0;
   return {
     async request({ method, params = [] }) {
-      if (method === "eth_chainId") return "0x14a34";
+      if (method === "eth_chainId")
+        return `0x${AUTONOMOUS_WALLET_CHAIN_ID.toString(16)}`;
       if (method === "eth_accounts" || method === "eth_requestAccounts")
         return [address];
       if (
@@ -410,7 +412,7 @@ export function createAutonomousWalletProvider(
       }
       const response = await (
         options.fetchImpl ?? globalThis.fetch.bind(globalThis)
-      )(options.rpcUrl ?? "https://base-sepolia-rpc.publicnode.com", {
+      )(options.rpcUrl ?? defaultNetwork().rpcUrls[0], {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify(

package/src/wallet/broker-escrows.ts

@@ -0,0 +1,66 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import { streamEscrowV2Abi, streamEscrowV3Abi } from "@absol-labs/shared";
+import {
+  decodeFunctionData,
+  getAddress,
+  isAddressEqual,
+  type Address,
+  type Hex,
+} from "viem";
+
+/**
+ * Which escrows a Privy broker will send a transaction to, and for what
+ * (the V3 cutover, metrik-agent#121). Read from the SDK network registry —
+ * data, never addresses in code:
+ *
+ * - the CURRENT escrow (`network.escrow`) for every method the broker
+ *   allowlists: `openStream`, `close`, `reclaim`, `reclaimUnverified`, and the
+ *   bounded USDC `approve` to it;
+ * - each LEGACY escrow (`network.legacy`) for EXITS only: `close`, `reclaim`,
+ *   `reclaimUnverified`. Never `openStream` and never an approval: a legacy
+ *   escrow can only give an agent its own money back.
+ */
+export interface BrokerEscrowPolicy {
+  readonly current: Address;
+  readonly legacy: readonly Address[];
+}
+
+export function brokerEscrowPolicy(network: MetrikNetwork): BrokerEscrowPolicy {
+  const current = getAddress(network.escrow.address);
+  const legacy = network.legacy
+    .map((deployment) => getAddress(deployment.escrow.address))
+    .filter((escrow) => !isAddressEqual(escrow, current));
+  return Object.freeze({
+    current,
+    legacy: Object.freeze([...new Set(legacy)]),
+  });
+}
+
+/** The exit methods a legacy escrow is allowed for. */
+export const BROKER_EXIT_METHODS: ReadonlySet<string> = new Set([
+  "close",
+  "reclaim",
+  "reclaimUnverified",
+]);
+
+/** `"current"`, `"legacy"`, or `null` for an escrow the broker never calls. */
+export function escrowRole(
+  policy: BrokerEscrowPolicy,
+  target: Address,
+): "current" | "legacy" | null {
+  if (isAddressEqual(target, policy.current)) return "current";
+  return policy.legacy.some((escrow) => isAddressEqual(escrow, target))
+    ? "legacy"
+    : null;
+}
+
+/**
+ * V2 and V3 share the selectors and argument layouts of every method the
+ * broker allowlists, so one decoder serves both: V3 first, V2 for anything
+ * only V2 knows.
+ */
+const escrowCallAbi = [...streamEscrowV3Abi, ...streamEscrowV2Abi];
+
+export function decodeEscrowCall(data: Hex) {
+  return decodeFunctionData({ abi: escrowCallAbi, data });
+}