@deeeed/metamask-harness 0.79.0 → 0.81.0

package/library/actions/shared/perps/order-policy.mjs

@@ -0,0 +1,177 @@
+// The Perps order rule every adapter applies before dispatch (F21).
+// Testnet orders need no funding proof. A mainnet order is allowed only from a
+// synced fixture account within the house limits: 1x isolated, notional at
+// most $15, closed again inside the same action (close_immediately: true).
+
+import { isFixtureAccount } from '../wallet/fixture-accounts.mjs';
+
+export const MAINNET_HOUSE_LIMITS = Object.freeze({
+  maxNotionalUsd: '15',
+  maxNotionalBaseUnits: 15_000_000n,
+  leverage: 1,
+  marginType: 'isolated',
+});
+
+const USDC_DECIMAL = /^(?:0|[1-9][0-9]{0,11})(?:\.([0-9]{1,6}))?$/u;
+
+// USDC base units (6 decimals) of a non-negative decimal amount.
+export function usdcBaseUnits(value) {
+  const text = String(value ?? '').trim();
+  const match = USDC_DECIMAL.exec(text);
+  if (!match) throw new Error(`Perps order amount must be a USDC decimal with at most 6 decimals, got ${JSON.stringify(text)}.`);
+  const [whole, fraction = ''] = text.split('.');
+  return BigInt(whole) * 1_000_000n + BigInt(fraction.padEnd(6, '0'));
+}
+
+// The order's network: the live app's, which must agree with the node's
+// declared one. A mainnet order must declare network: mainnet, so a recipe
+// written for testnet never trades real funds because the app moved.
+export function orderNetwork({ declared, liveIsTestnet }) {
+  const live = liveIsTestnet === true ? 'testnet' : liveIsTestnet === false ? 'mainnet' : null;
+  if (!live) throw new Error('Perps order cannot verify whether the app is on testnet or mainnet.');
+  const wanted = declared == null || declared === '' ? null : String(declared).toLowerCase();
+  if (wanted && wanted !== 'testnet' && wanted !== 'mainnet') {
+    throw new Error(`Perps order network must be testnet or mainnet, got ${JSON.stringify(declared)}.`);
+  }
+  if (wanted && wanted !== live) throw new Error(`Perps order expected ${wanted}, but the app is on ${live}.`);
+  if (live === 'mainnet' && wanted !== 'mainnet') {
+    throw Object.assign(
+      new Error('PERPS_MAINNET_ORDER_REFUSED: Perps app is on mainnet but the order does not declare network: mainnet. Next: switch to testnet, or declare network: mainnet within the house limits.'),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED' },
+    );
+  }
+  return live;
+}
+
+// Whether the node asks the action to close the position it opens.
+export function closeImmediatelyRequested(node) {
+  return node?.close_immediately === true || node?.closeImmediately === true;
+}
+
+/**
+ * Decide whether a Perps order may be dispatched.
+ * @param {object} order
+ * @param {'testnet'|'mainnet'} order.network - The live app network, already cross-checked with the node.
+ * @param {string|number} order.amount - Margin in USDC.
+ * @param {number} order.leverage
+ * @param {'market'|'limit'} [order.orderType]
+ * @param {boolean} order.closeImmediately
+ * @param {boolean} order.fixtureAccount - The selected account is a synced fixture account.
+ * @returns {{ lane: 'testnet' } | { lane: 'mainnet-house-limits', notionalBaseUnits: string }}
+ */
+export function decidePerpsOrder({ network, amount, leverage, orderType = 'market', closeImmediately, fixtureAccount }) {
+  if (closeImmediately && orderType !== 'market') {
+    throw new Error('close_immediately needs a market order: a resting limit order is not a position the action can close.');
+  }
+  // Testnet keeps whatever amount format the adapter accepts; only mainnet sizes are parsed strictly.
+  if (network === 'testnet') return { lane: 'testnet' };
+  if (network !== 'mainnet') throw new Error(`Perps order network must be testnet or mainnet, got ${JSON.stringify(network)}.`);
+  const leverageValue = Number(leverage);
+  const amountBaseUnits = usdcBaseUnits(amount);
+  const notionalBaseUnits = amountBaseUnits * BigInt(Number.isInteger(leverageValue) && leverageValue > 0 ? leverageValue : 1);
+  const broken = [];
+  if (amountBaseUnits <= 0n) broken.push('the amount is not positive');
+  if (!fixtureAccount) broken.push('the selected account is not one of the synced test accounts');
+  if (leverageValue !== MAINNET_HOUSE_LIMITS.leverage) broken.push(`leverage is ${leverage}, not 1`);
+  if (notionalBaseUnits > MAINNET_HOUSE_LIMITS.maxNotionalBaseUnits) {
+    broken.push(`notional ${formatUsd(notionalBaseUnits)} is above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}`);
+  }
+  if (orderType !== 'market') broken.push(`order type is ${orderType}, not market`);
+  if (!closeImmediately) broken.push('close_immediately is not true');
+  if (broken.length > 0) {
+    throw Object.assign(
+      new Error(
+        // The code leads the message: it is what survives a live adapter's process
+        // boundary, and the wording avoids the words bounded healing reads as wallet state.
+        `PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: ${broken.join('; ')}. ` +
+          `Mainnet orders need a synced test account, a 1x isolated market order, notional at most $${MAINNET_HOUSE_LIMITS.maxNotionalUsd} and close_immediately: true. ` +
+          'Next: use testnet, or stay within those limits.',
+      ),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED' },
+    );
+  }
+  return { lane: 'mainnet-house-limits', notionalBaseUnits: `${notionalBaseUnits}` };
+}
+
+// decidePerpsOrder with the fixture check resolved from the checkout's fixture.
+export async function requirePerpsOrderAllowed({ projectRoot, selectedAddress, ...order }) {
+  const fixtureAccount = order.network === 'mainnet'
+    ? await isFixtureAccount(projectRoot, selectedAddress)
+    : false;
+  return decidePerpsOrder({ ...order, fixtureAccount });
+}
+
+// close_immediately closes the market's whole position (positions are netted
+// per market), so it must start flat: no position and no resting order that
+// could fill into the position it then closes.
+export function assertFlatBeforeRoundTrip(positions, symbol, symbolOf, orders = []) {
+  if (positions.some((position) => symbolOf(position) === symbol)) {
+    throw new Error(`close_immediately needs no open ${symbol} position before the order; close it first.`);
+  }
+  if (orders.some((order) => symbolOf(order) === symbol)) {
+    throw new Error(`close_immediately needs no resting ${symbol} order before the order; cancel it first.`);
+  }
+}
+
+// The most a market order for `amount` USDC margin can fill at. The controller
+// rounds the size to the market's szDecimals and adds one step when that falls
+// short of the USD amount (perps-controller utils/orderCalculations.ts), and the
+// fill may slip by maxSlippageBps: (amount × leverage + one step × price) × (1 + slippage).
+export function worstCaseNotionalUsd({ amount, leverage, price, szDecimals, maxSlippageBps }) {
+  const usd = Number(amount) * Number(leverage);
+  const step = 10 ** -Number(szDecimals);
+  return (usd + step * Number(price)) * (1 + Number(maxSlippageBps) / 10_000);
+}
+
+// Mainnet only: refuse before dispatch when the size the controller would submit
+// could fill above the house notional limit. Testnet needs no bound.
+export function requireHouseNotional({ network, symbol, amount, leverage, price, szDecimals, maxSlippageBps }) {
+  if (network !== 'mainnet') return null;
+  // A missing value is unknown, never zero (Number(null) is 0).
+  const known = (value) => (value == null || value === '' ? Number.NaN : Number(value));
+  const inputs = { price: known(price), szDecimals: known(szDecimals), maxSlippageBps: known(maxSlippageBps) };
+  if (!(inputs.price > 0) || !Number.isInteger(inputs.szDecimals) || inputs.szDecimals < 0
+    || !Number.isFinite(inputs.maxSlippageBps) || inputs.maxSlippageBps < 0) {
+    throw Object.assign(
+      new Error(`PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: cannot bound the ${symbol} order size (price, size decimals or slippage unknown).`),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED' },
+    );
+  }
+  const worst = worstCaseNotionalUsd({ amount, leverage, ...inputs });
+  if (worst > Number(MAINNET_HOUSE_LIMITS.maxNotionalUsd)) {
+    throw Object.assign(
+      new Error(
+        `PERPS_MAINNET_ORDER_REFUSED: Mainnet Perps order refused before dispatch: a ${symbol} order for $${Number(amount) * Number(leverage)} can fill at up to $${worst.toFixed(2)} ` +
+          `(size step ${10 ** -inputs.szDecimals} at $${inputs.price}, max slippage ${inputs.maxSlippageBps} bps), above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}. ` +
+          'Next: order less, or lower max_slippage_bps.',
+      ),
+      { code: 'PERPS_MAINNET_ORDER_REFUSED' },
+    );
+  }
+  return { worstCaseNotionalUsd: Number(worst.toFixed(6)) };
+}
+
+// The opened position must be the isolated 1x one the policy allowed, worth at
+// most the house limit, before the action closes it (mainnet), so a drift is
+// reported, not hidden. The caller closes the position first either way.
+export function assertHouseLimitPosition(position, symbol) {
+  const type = String(position?.leverage?.type ?? position?.marginType ?? '').toLowerCase();
+  const value = Number(position?.leverage?.value ?? position?.leverage);
+  if (type !== MAINNET_HOUSE_LIMITS.marginType || value !== MAINNET_HOUSE_LIMITS.leverage) {
+    throw new Error(
+      `Mainnet ${symbol} position opened as ${type || 'unknown'} ${Number.isFinite(value) ? `${value}x` : 'unknown leverage'}, not isolated 1x; it was closed.`,
+    );
+  }
+  const opened = Math.abs(Number(position?.size ?? position?.szi)) * Number(position?.entryPrice ?? position?.entryPx);
+  if (!Number.isFinite(opened) || opened > Number(MAINNET_HOUSE_LIMITS.maxNotionalUsd) + 1e-6) {
+    throw new Error(
+      `Mainnet ${symbol} position opened at ${Number.isFinite(opened) ? `$${opened.toFixed(2)}` : 'an unknown value'}, above $${MAINNET_HOUSE_LIMITS.maxNotionalUsd}; it was closed.`,
+    );
+  }
+}
+
+function formatUsd(baseUnits) {
+  const whole = baseUnits / 1_000_000n;
+  const fraction = `${baseUnits % 1_000_000n}`.padStart(6, '0').replace(/0+$/u, '');
+  return `$${whole}${fraction ? `.${fraction}` : ''}`;
+}

package/library/actions/shared/wallet/fixture-accounts.mjs

@@ -0,0 +1,84 @@
+// The checkout's synced wallet fixture (temp/recipe/runtime/wallet-fixture.json)
+// expanded into accounts: a mnemonic entry with count N yields N accounts at
+// address indexes 0..N-1, named dev1..devN from the entry's name. list_accounts
+// shows them, Core Perps actions sign with them, and the Perps order rule
+// (../perps/order-policy.mjs) checks a mainnet order's account against them.
+
+import { readFile } from 'node:fs/promises';
+import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
+
+import { walletFixturePath } from '../../harness-exports.mjs';
+
+function fixtureAccountName(base, index, count) {
+  if (count === 1) return base || 'account1';
+  const match = /^(.*?)(\d+)$/u.exec(base || 'account1');
+  return match
+    ? `${match[1]}${Number(match[2]) + index}`
+    : `${base || 'account'}${index + 1}`;
+}
+
+function mnemonicCount(entry, fixturePath, index) {
+  const count = Number(entry.count ?? entry.numberOfAccounts ?? 1);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(`${fixturePath} accounts[${index}] mnemonic count must be an integer from 1 through 100.`);
+  }
+  return count;
+}
+
+/**
+ * Expand fixture entries into `{ name, address, signer }`. `signer` is the viem
+ * account holding the key: use it to sign, never serialize it.
+ */
+export function deriveFixtureAccounts(fixture, fixturePath) {
+  if (!Array.isArray(fixture.accounts) || fixture.accounts.length === 0) {
+    throw new Error(`wallet fixture at ${fixturePath} has no accounts array.`);
+  }
+  return fixture.accounts.flatMap((entry, fixtureIndex) => {
+    if (!entry || typeof entry !== 'object' || typeof entry.value !== 'string' || !entry.value.trim()) {
+      throw new Error(`${fixturePath} accounts[${fixtureIndex}] must contain a non-empty value.`);
+    }
+    if (entry.type === 'mnemonic') {
+      const count = mnemonicCount(entry, fixturePath, fixtureIndex);
+      return Array.from({ length: count }, (_, addressIndex) => {
+        const signer = mnemonicToAccount(entry.value.trim(), { addressIndex });
+        return { name: fixtureAccountName(entry.name, addressIndex, count), address: signer.address, signer };
+      });
+    }
+    if (entry.type === 'privateKey') {
+      const raw = entry.value.trim();
+      const normalized = raw.startsWith('0x') ? raw : `0x${raw}`;
+      if (!/^0x[0-9a-fA-F]{64}$/u.test(normalized)) {
+        throw new Error(`${fixturePath} accounts[${fixtureIndex}] privateKey is not a 32-byte hex key.`);
+      }
+      const signer = privateKeyToAccount(normalized);
+      return [{ name: entry.name || `account${fixtureIndex + 1}`, address: signer.address, signer }];
+    }
+    throw new Error(`${fixturePath} accounts[${fixtureIndex}].type must be mnemonic or privateKey.`);
+  });
+}
+
+/** The checkout's fixture accounts, or null when it has no wallet fixture. */
+export async function readFixtureAccounts(projectRoot) {
+  const fixturePath = walletFixturePath(projectRoot);
+  let raw;
+  try {
+    raw = await readFile(fixturePath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  return { fixturePath, accounts: deriveFixtureAccounts(JSON.parse(raw), fixturePath) };
+}
+
+// Whether an address is one of the fixture's accounts. A missing or unreadable
+// fixture is "not a fixture account": the caller refuses, it never assumes.
+export async function isFixtureAccount(projectRoot, address) {
+  const wanted = String(address ?? '').toLowerCase();
+  if (!/^0x[0-9a-f]{40}$/u.test(wanted) || !projectRoot) return false;
+  try {
+    const loaded = await readFixtureAccounts(projectRoot);
+    return Boolean(loaded?.accounts.some((account) => account.address.toLowerCase() === wanted));
+  } catch {
+    return false;
+  }
+}

package/library/actions/terminal/app/launch.mjs

@@ -5,6 +5,7 @@
 
 import { appPort, cdpPort, isDirectRun, resolveSigner, runAdapter } from '../platform/runtime.mjs';
 import { launchTerminalBrowser } from '../../../../adapters/terminal/launch.mjs';
+import { policy } from '../../../../adapters/terminal/policy.mjs';
 
 export async function launch(input) {
   const node = input.node ?? {};
@@ -22,8 +23,8 @@ export async function launch(input) {
     'slow-mo': node.slow_mo_ms,
     network: node.network,
     'mainnet-confirmation': node.mainnet_confirmation,
-    'start-chain': node.start_chain ?? 42161,
-  });
+    'start-chain': node.start_chain ?? policy.startChain,
+  }, process.env, { policy });
   return {
     action: input.action,
     status: 'ready',

package/library/actions/terminal/platform/hud.mjs

@@ -3,8 +3,9 @@
 // the same state after every navigation. The HUD is advisory: a missing
 // browser or a busy tab skips the update instead of failing the recipe.
 
+import { isAppUrl } from '@farmslot/adapter-web/origin';
+
 import { clearHudState, hudRenderExpression, nextHudState, readHudState, writeHudState } from '../../../../adapters/terminal/lib/hud.mjs';
-import { isAppUrl } from '../../../../adapters/terminal/lib/origin.mjs';
 import { appOrigin, cdpPort, readBrowserState, terminalRuntimeDir } from './runtime.mjs';
 import { importRecipeHarnessRuntimeCdp } from '../../harness-exports.mjs';
 

package/library/actions/terminal/platform/page.mjs

@@ -6,9 +6,10 @@
 // app tab is the only tab of its window (the wallet host closes the others),
 // so it stays the window's active tab and keeps painting without it.
 
+import { isAppUrl } from '@farmslot/adapter-web/origin';
+
 import { resolveSlowMo } from '../../../../adapters/terminal/lib/display.mjs';
 import { HUD_ELEMENT } from '../../../../adapters/terminal/lib/hud.mjs';
-import { isAppUrl } from '../../../../adapters/terminal/lib/origin.mjs';
 import { cdpListenerPids } from '../../../../adapters/terminal/lib/processes.mjs';
 import { appOrigin, cdpPort, readBrowserState } from './runtime.mjs';
 import { importRecipeHarnessRuntimeCdp } from '../../harness-exports.mjs';

package/library/actions/terminal/platform/runtime.mjs

@@ -9,7 +9,8 @@ import { pathToFileURL } from 'node:url';
 
 import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 
-import { recipeRuntimeDir, walletFixturePath } from '../../harness-exports.mjs';
+import { recipeRuntimeDir } from '@farmslot/recipe-cli/harness';
+import { walletFixturePath } from '../../harness-exports.mjs';
 
 export const SIGNER_MODES = Object.freeze(['extension', 'injected']);
 export const DEFAULT_ACCOUNT = 'dev1';

package/library/actions/terminal/wallet/_signature-log.mjs

@@ -1,177 +1,56 @@
-// Read, window and assert the terminal wallet request log the wallet host
-// writes: one JSON line per request the app sent to the main wallet (method,
-// EIP-712 primary type, domain/active chain, outcome) and, in extension mode,
-// one line per confirmation window MetaMask opened. Never holds params,
-// messages or signatures.
+// The Terminal's wallet request log: where the wallet host writes it, and what
+// the Terminal forbids in it. Reading, windowing and asserting the log are
+// @farmslot/adapter-web/dapp's; the Hyperliquid rules are passed in as policy:
+//   - an L1 (agent-signed, Agent / chainId 1337) payload must never reach the
+//     main wallet (max_l1_requests, default 0);
+//   - a blocked mainnet venue request or a refused mainnet signature fails the
+//     assertion (testnet enforcement).
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import path from 'node:path';
+import { shortPrimaryType } from '@farmslot/adapter-web/dapp';
 
 import { terminalRuntimePath } from '../platform/runtime.mjs';
 
 export const L1_PRIMARY_TYPE = 'Agent';
 export const L1_CHAIN_ID = 1337;
 
-export function signatureLogPath(projectRoot) {
-  return terminalRuntimePath(projectRoot, 'wallet-requests.jsonl');
-}
-
-export function signatureCursorPath(projectRoot) {
-  return terminalRuntimePath(projectRoot, 'wallet-requests.cursor.json');
-}
-
-export function parseLog(text) {
-  return text
-    .split('\n')
-    .filter((line) => line.trim())
-    .map((line, index) => {
-      try {
-        return { seq: index, ...JSON.parse(line) };
-      } catch {
-        return { seq: index, kind: 'unparseable' };
-      }
-    });
-}
-
-export async function readLog(projectRoot) {
-  try {
-    return parseLog(await readFile(signatureLogPath(projectRoot), 'utf8'));
-  } catch (error) {
-    if (error?.code === 'ENOENT') return [];
-    throw error;
-  }
-}
-
-export async function readCursor(projectRoot) {
-  try {
-    const cursor = JSON.parse(await readFile(signatureCursorPath(projectRoot), 'utf8'));
-    return Number.isInteger(cursor.seq) ? cursor.seq : 0;
-  } catch (error) {
-    if (error?.code === 'ENOENT') return 0;
-    throw error;
-  }
-}
-
-export async function writeCursor(projectRoot, seq) {
-  await writeFile(signatureCursorPath(projectRoot), `${JSON.stringify({ seq, at: new Date().toISOString() })}\n`, { mode: 0o600 });
-}
-
-// "HyperliquidTransaction:ApproveAgent" → "ApproveAgent".
-export function shortPrimaryType(primaryType) {
-  if (primaryType == null) return null;
-  const raw = String(primaryType);
-  return raw.includes(':') ? raw.slice(raw.lastIndexOf(':') + 1) : raw;
-}
-
-export function isTypedDataRequest(entry) {
-  return entry.kind === 'request' && /^eth_signTypedData/u.test(String(entry.method));
+export function signatureLog(projectRoot) {
+  return {
+    logFile: terminalRuntimePath(projectRoot, 'wallet-requests.jsonl'),
+    cursorFile: terminalRuntimePath(projectRoot, 'wallet-requests.cursor.json'),
+  };
 }
 
 export function isL1Request(entry) {
-  return isTypedDataRequest(entry) &&
+  return entry.kind === 'request' && /^eth_signTypedData/u.test(String(entry.method)) &&
     (shortPrimaryType(entry.primaryType) === L1_PRIMARY_TYPE || Number(entry.domainChainId) === L1_CHAIN_ID);
 }
 
-export function summarize(entries) {
-  const requests = entries.filter((entry) => entry.kind === 'request');
-  const typed = requests.filter(isTypedDataRequest);
-  const byPrimaryType = {};
-  for (const entry of typed) {
-    const key = shortPrimaryType(entry.primaryType) ?? '<none>';
-    byPrimaryType[key] ??= { requested: 0, signed: 0, rejected: 0, chainIds: [] };
-    byPrimaryType[key].requested += 1;
-    if (entry.outcome === 'signed') byPrimaryType[key].signed += 1;
-    if (entry.outcome === 'rejected' || entry.outcome === 'error') byPrimaryType[key].rejected += 1;
-    if (!byPrimaryType[key].chainIds.includes(entry.domainChainId)) byPrimaryType[key].chainIds.push(entry.domainChainId);
-  }
-  const byMethod = {};
-  for (const entry of requests) byMethod[entry.method] = (byMethod[entry.method] ?? 0) + 1;
+export const TERMINAL_SIGNATURE_POLICY = Object.freeze({
+  typedDataClasses: {
+    l1Requests: {
+      match: isL1Request,
+      param: 'max_l1_requests',
+      defaultMax: 0,
+      failure: (count, max) => `L1 requests reached the main wallet: ${count} > ${max}`,
+    },
+  },
+  forbiddenEntries: {
+    blockedMainnet: {
+      match: (entry) => entry.kind === 'blocked-mainnet' && !entry.probe,
+      failure: (count) => `the browser tried to reach a mainnet venue ${count} time(s) (blocked-mainnet)`,
+    },
+    refusedMainnet: {
+      match: (entry) => entry.kind === 'refused-mainnet',
+      failure: (count) => `the app asked the wallet to sign ${count} mainnet action(s) (refused-mainnet)`,
+    },
+  },
+});
+
+// Evidence goes to <artifacts>/terminal-wallet/<node>-signature-log.json.
+export function logArtifactTarget(input) {
   return {
-    requests: requests.length,
-    typedDataRequests: typed.length,
-    l1Requests: typed.filter(isL1Request).length,
-    confirmationsShown: entries.filter((entry) => entry.kind === 'confirmation-shown').length,
-    // Testnet enforcement and evidence gaps: each one fails the assertion.
-    blockedMainnet: entries.filter((entry) => entry.kind === 'blocked-mainnet' && !entry.probe).length,
-    refusedMainnet: entries.filter((entry) => entry.kind === 'refused-mainnet').length,
-    unattributed: entries.filter((entry) => entry.kind === 'unattributed').length,
-    // Calls from an iframe, a foreign page or a blank document: refused, kept as evidence.
-    outsideAppFrame: entries.filter((entry) => entry.kind === 'outside-app-frame').length,
-    byPrimaryType,
-    byMethod,
+    artifactsDir: input.context?.artifactsDir,
+    nodeId: input.context?.nodeId ?? input.action,
+    folder: 'terminal-wallet',
   };
 }
-
-function exact(label, actual, expected, failures) {
-  if (actual !== expected) failures.push(`${label}: expected ${expected}, got ${actual}`);
-}
-
-// Every expectation is optional; max_l1_requests defaults to 0 because an L1
-// (agent-signed) payload must never reach the main wallet.
-export function evaluateSignatureLog(entries, node = {}) {
-  const summary = summarize(entries);
-  const typed = entries.filter(isTypedDataRequest);
-  const failures = [];
-  if (summary.blockedMainnet > 0) failures.push(`the browser tried to reach a mainnet venue ${summary.blockedMainnet} time(s) (blocked-mainnet)`);
-  if (summary.refusedMainnet > 0) failures.push(`the app asked the wallet to sign ${summary.refusedMainnet} mainnet action(s) (refused-mainnet)`);
-  if (summary.unattributed > 0) failures.push(`${summary.unattributed} wallet log entr(y/ies) could not be attributed to the app's top frame (unattributed)`);
-  const maxL1 = node.max_l1_requests == null ? 0 : Number(node.max_l1_requests);
-  if (summary.l1Requests > maxL1) {
-    failures.push(`L1 requests reached the main wallet: ${summary.l1Requests} > ${maxL1}`);
-  }
-  if (Array.isArray(node.allowed_primary_types)) {
-    const allowed = new Set(node.allowed_primary_types.map(shortPrimaryType));
-    for (const entry of typed) {
-      const type = shortPrimaryType(entry.primaryType);
-      if (!allowed.has(type)) failures.push(`primary type ${type} (seq ${entry.seq}) is not allowed`);
-    }
-  }
-  if (node.counts && typeof node.counts === 'object') {
-    for (const [type, expected] of Object.entries(node.counts)) {
-      exact(`signed ${shortPrimaryType(type)}`, summary.byPrimaryType[shortPrimaryType(type)]?.signed ?? 0, Number(expected), failures);
-    }
-  }
-  if (node.request_counts && typeof node.request_counts === 'object') {
-    for (const [type, expected] of Object.entries(node.request_counts)) {
-      exact(`requested ${shortPrimaryType(type)}`, summary.byPrimaryType[shortPrimaryType(type)]?.requested ?? 0, Number(expected), failures);
-    }
-  }
-  if (node.methods && typeof node.methods === 'object') {
-    for (const [method, expected] of Object.entries(node.methods)) {
-      exact(`method ${method}`, summary.byMethod[method] ?? 0, Number(expected), failures);
-    }
-  }
-  if (node.max_typed_data_requests != null && summary.typedDataRequests > Number(node.max_typed_data_requests)) {
-    failures.push(`typed-data requests ${summary.typedDataRequests} > ${node.max_typed_data_requests}`);
-  }
-  if (node.expect_confirmations != null) {
-    exact('confirmations shown', summary.confirmationsShown, Number(node.expect_confirmations), failures);
-  }
-  if (node.require_active_chain === true) {
-    for (const entry of typed.filter((item) => item.outcome === 'signed')) {
-      if (Number(entry.domainChainId) !== Number(entry.activeChainId)) {
-        failures.push(`seq ${entry.seq} ${shortPrimaryType(entry.primaryType)} signed with domain chainId ${entry.domainChainId} while the wallet was on ${entry.activeChainId}`);
-      }
-    }
-  }
-  if (node.max_rejected != null) {
-    const rejected = typed.filter((entry) => entry.outcome === 'rejected' || entry.outcome === 'error').length;
-    if (rejected > Number(node.max_rejected)) failures.push(`rejected typed-data requests ${rejected} > ${node.max_rejected}`);
-  }
-  return { ok: failures.length === 0, failures, summary };
-}
-
-export async function windowSinceCursor(projectRoot) {
-  const [entries, cursor] = await Promise.all([readLog(projectRoot), readCursor(projectRoot)]);
-  return { cursor, entries: entries.filter((entry) => entry.seq >= cursor), total: entries.length };
-}
-
-export async function writeLogArtifact(input, payload) {
-  const artifactsDir = input.context?.artifactsDir;
-  if (!artifactsDir) return [];
-  const nodeId = String(input.context?.nodeId ?? input.action).replaceAll('/', '__');
-  const relative = `terminal-wallet/${nodeId}-signature-log.json`;
-  await mkdir(path.join(artifactsDir, 'terminal-wallet'), { recursive: true });
-  await writeFile(path.join(artifactsDir, relative), `${JSON.stringify(payload, null, 2)}\n`);
-  return [{ path: relative, type: 'report', nodeId: String(input.context?.nodeId ?? input.action) }];
-}

package/library/actions/terminal/wallet/assert_signatures.mjs

@@ -3,22 +3,16 @@
 // payloads, active-chain matching and, in extension mode, confirmations shown.
 // The full window is retained as evidence whether or not the assertion holds.
 
+import { awaitSignatureLog, writeLogArtifact } from '@farmslot/adapter-web/dapp';
+
 import { isDirectRun, runAdapter } from '../platform/runtime.mjs';
-import { evaluateSignatureLog, windowSinceCursor, writeLogArtifact } from './_signature-log.mjs';
+import { TERMINAL_SIGNATURE_POLICY, logArtifactTarget, signatureLog } from './_signature-log.mjs';
 
 export async function assertSignatures(input) {
   const node = input.node ?? {};
-  const projectRoot = input.context?.projectRoot;
-  const deadline = Date.now() + Math.max(0, Number(node.timeout_ms ?? 0));
-  let window = await windowSinceCursor(projectRoot);
-  let result = evaluateSignatureLog(window.entries, node);
-  // Entries arrive asynchronously from the wallet host; allow a short settle.
-  while (!result.ok && Date.now() < deadline) {
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    window = await windowSinceCursor(projectRoot);
-    result = evaluateSignatureLog(window.entries, node);
-  }
-  const artifacts = await writeLogArtifact(input, {
+  // Entries arrive asynchronously from the wallet host; timeout_ms allows a short settle.
+  const { window, result } = await awaitSignatureLog(signatureLog(input.context?.projectRoot), node, TERMINAL_SIGNATURE_POLICY);
+  const artifacts = await writeLogArtifact(logArtifactTarget(input), {
     cursor: window.cursor,
     total: window.total,
     expectations: node,

package/library/actions/terminal/wallet/read_signatures.mjs

@@ -2,26 +2,27 @@
 // evidence. reset=true moves the window start to the end of the log so the next
 // read covers only what follows (an explicit setup step, recorded in the trace).
 
+import { resetWindow, summarize, windowSinceCursor, writeLogArtifact } from '@farmslot/adapter-web/dapp';
+
 import { isDirectRun, runAdapter } from '../platform/runtime.mjs';
-import { readLog, summarize, windowSinceCursor, writeCursor, writeLogArtifact } from './_signature-log.mjs';
+import { TERMINAL_SIGNATURE_POLICY, logArtifactTarget, signatureLog } from './_signature-log.mjs';
 
 export async function readSignatures(input) {
-  const projectRoot = input.context?.projectRoot;
+  const log = signatureLog(input.context?.projectRoot);
   if (input.node?.reset === true) {
-    const entries = await readLog(projectRoot);
-    await writeCursor(projectRoot, entries.length);
+    const { cursor, previousEntries } = await resetWindow(log);
     return {
       action: input.action,
       source: 'terminal-wallet-request-log',
       reset: true,
-      cursor: entries.length,
-      previousEntries: entries.length,
+      cursor,
+      previousEntries,
       proofPath: 'terminal-wallet-request-log',
     };
   }
-  const { cursor, entries, total } = await windowSinceCursor(projectRoot);
-  const summary = summarize(entries);
-  const artifacts = await writeLogArtifact(input, { cursor, total, summary, entries });
+  const { cursor, entries, total } = await windowSinceCursor(log);
+  const summary = summarize(entries, TERMINAL_SIGNATURE_POLICY);
+  const artifacts = await writeLogArtifact(logArtifactTarget(input), { cursor, total, summary, entries });
   return {
     action: input.action,
     source: 'terminal-wallet-request-log',