@muhaven/mcp 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.9] — 2026-05-23
+
+### Added
+
+- **`pathDDecodedCall` in the position.buy echo on Path D fallback.**
+  When the bundler trace contains a `zd_sponsorUserOperation` event,
+  the handler now decodes the userOp.callData inline and surfaces:
+
+      pathDDecodedCall: {
+        sender: '0x<kernel>',
+        kernelExecuteMode: '0x<32 bytes>',
+        kernelExecuteTarget: '0x<addr>',          // should == MuHavenSubscription
+        kernelExecuteValue: '0',
+        innerSelector: '0xd29b624b',              // purchase(...)
+        innerPurchaseTokenArg: '0x<addr>',        // the RWA token (MuHavenToken)
+        innerPurchaseMaxSharesHint: '14',
+        innerPurchaseEphemeralEOA: '0x<addr>',
+        expectedSubscriptionAddress: '0x<addr>',  // MCP env wiring
+        kernelExecuteTargetMatchesSubscription: true|false,
+        interpretation: 'kernel.execute target matches MuHavenSubscription. ...',
+      }
+
+  Lets the LLM read at-a-glance which contract the kernel was about
+  to call (kernel.execute target) vs which RWA token the inner
+  purchase() carries — the two are commonly confused (the inner
+  purchase's first arg IS the token address, but the kernel.execute
+  target should be the subscription).
+
+  The `interpretation` field branches on three cases:
+    1. target == expected subscription → "shape is correct; AA23 is
+       downstream of validator signature decode; check
+       muhaven.policy.session_key_status."
+    2. target == inner purchase.token → "kernel is dispatching to
+       the token instead of the subscription — code bug."
+    3. Anything else → "unexpected third-address dispatch."
+
+- **`decodeKernelExecuteSingleCall` exported from
+  `clients/kernel-encoder.ts`.** Sibling to the existing encoder;
+  reuses the same KERNEL_EXECUTE_ABI + single-call default mode.
+  Returns `null` on unsupported modes (batch / delegate / try) so
+  the diagnostic emits a clear gap instead of garbage.
+
+- **`scripts/decode-userop-trace.ts`** — standalone CLI that takes
+  the raw `pathDBundlerTrace` JSON via stdin and prints the same
+  decode + cross-check. Useful when triaging against an older MCP
+  version that doesn't ship `pathDDecodedCall`, or for offline
+  analysis from a saved trace.
+
 ## [0.2.8] — 2026-05-23
 
 ### Added

package/dist/broker.cjs

@@ -2783,7 +2783,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.8";
+    return "0.2.9";
   }
 }
 function printVersion() {

package/dist/broker.js

@@ -2785,7 +2785,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.8";
+    return "0.2.9";
   }
 }
 function printVersion() {

package/dist/index.cjs

@@ -1968,6 +1968,26 @@ function encodeKernelExecuteSingleCall(input) {
     args: [KERNEL_V3_SINGLE_CALL_MODE_DEFAULT, executionCalldata]
   });
 }
+function decodeKernelExecuteSingleCall(data) {
+  let decoded;
+  try {
+    decoded = viem.decodeFunctionData({ abi: KERNEL_EXECUTE_ABI, data });
+  } catch {
+    return null;
+  }
+  const [mode, executionCalldata] = decoded.args;
+  if (mode !== KERNEL_V3_SINGLE_CALL_MODE_DEFAULT) {
+    return null;
+  }
+  const ec = executionCalldata.slice(2);
+  if (ec.length < 20 * 2 + 32 * 2) {
+    return null;
+  }
+  const target = `0x${ec.slice(0, 40)}`;
+  const value = BigInt(`0x${ec.slice(40, 40 + 64)}`);
+  const innerCallData = `0x${ec.slice(40 + 64)}`;
+  return { mode, target, value, innerCallData };
+}
 var ECDSA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
 var PERMISSION_USE_PREFIX = "0xff";
 function buildKernelSessionKeySignature(input) {
@@ -2357,6 +2377,79 @@ async function syncSnapshotFromMirror(deps, brokerSignerAddress) {
   }
   return { kind: "ok", sessionId: activeId };
 }
+var PURCHASE_SELECTOR_LOWER = SUBSCRIPTION_PURCHASE_SELECTOR.toLowerCase();
+function buildPathDDecodedCall(trace, deps) {
+  const sponsorEvent = trace.find((e) => e.method === "zd_sponsorUserOperation");
+  if (!sponsorEvent) return void 0;
+  let req;
+  try {
+    req = JSON.parse(sponsorEvent.requestBody);
+  } catch {
+    return void 0;
+  }
+  const userOp = req.params?.[0]?.userOp;
+  if (!userOp || typeof userOp.callData !== "string" || !userOp.callData.startsWith("0x")) {
+    return void 0;
+  }
+  const sender = userOp.sender ?? "<missing>";
+  const decoded = decodeKernelExecuteSingleCall(userOp.callData);
+  if (!decoded) {
+    return {
+      sender,
+      kernelExecuteMode: "<undecodable>",
+      kernelExecuteTarget: "<undecodable>",
+      kernelExecuteValue: "<undecodable>",
+      innerSelector: "<undecodable>",
+      interpretation: "kernel.execute callData could not be decoded as single-call default mode. The mode word is non-zero or the executionCalldata layout is unexpected. Manual decode required."
+    };
+  }
+  const innerSelector = decoded.innerCallData.slice(0, 10).toLowerCase();
+  let innerPurchaseTokenArg;
+  let innerPurchaseMaxSharesHint;
+  let innerPurchaseEphemeralEOA;
+  if (innerSelector === PURCHASE_SELECTOR_LOWER) {
+    try {
+      const inner = viem.decodeFunctionData({
+        abi: SUBSCRIPTION_PURCHASE_ABI,
+        data: decoded.innerCallData
+      });
+      const [tokenArg, , maxSharesHint, ephemeralEOA] = inner.args;
+      innerPurchaseTokenArg = tokenArg;
+      innerPurchaseMaxSharesHint = maxSharesHint.toString();
+      innerPurchaseEphemeralEOA = ephemeralEOA;
+    } catch {
+    }
+  }
+  const expectedSubscriptionAddress = deps.subscriptionAddress?.toLowerCase();
+  const kernelTargetLower = decoded.target.toLowerCase();
+  let kernelExecuteTargetMatchesSubscription;
+  let interpretation;
+  if (expectedSubscriptionAddress === void 0) {
+    interpretation = `kernel.execute target=${decoded.target}; inner purchase token=${innerPurchaseTokenArg ?? "<unknown>"}; MUHAVEN_SUBSCRIPTION_ADDRESS not wired on this MCP server \u2014 cannot cross-check.`;
+  } else if (kernelTargetLower === expectedSubscriptionAddress) {
+    kernelExecuteTargetMatchesSubscription = true;
+    interpretation = `kernel.execute target matches MuHavenSubscription (${decoded.target}). Inner purchase token = ${innerPurchaseTokenArg ?? "<unknown>"}. The shape is correct; the AA23 revert is downstream of the validator's signature decode \u2014 likely either an on-chain signer-vs-installed-permission mismatch, a target/selector not in the on-chain policy, or a cap-arg breach. Check muhaven.policy.session_key_status for the installed permission state.`;
+  } else if (innerPurchaseTokenArg !== void 0 && kernelTargetLower === innerPurchaseTokenArg.toLowerCase()) {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} = the RWA MuHavenToken (purchase.token arg0). Expected MuHavenSubscription (${deps.subscriptionAddress}). The kernel is dispatching purchase() to the token contract instead of the subscription \u2014 token doesn't have a purchase() selector, so fallback returns empty revert data (= AA23 reverted 0x). This is a code-side bug in the kernel.execute target wiring.`;
+  } else {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} \u2014 NEITHER the expected MuHavenSubscription (${deps.subscriptionAddress}) NOR the inner purchase.token arg (${innerPurchaseTokenArg ?? "<none>"}). This is an unexpected third-address dispatch; inspect deps.subscriptionAddress env wiring.`;
+  }
+  return {
+    sender,
+    kernelExecuteMode: decoded.mode,
+    kernelExecuteTarget: decoded.target,
+    kernelExecuteValue: decoded.value.toString(),
+    innerSelector,
+    innerPurchaseTokenArg,
+    innerPurchaseMaxSharesHint,
+    innerPurchaseEphemeralEOA,
+    expectedSubscriptionAddress: deps.subscriptionAddress,
+    kernelExecuteTargetMatchesSubscription,
+    interpretation
+  };
+}
 async function attemptPathD(args, deps) {
   const { shares, tokenAddress, tokenSymbol } = args;
   if (!deps.broker || !deps.bundler) {
@@ -2804,6 +2897,7 @@ async function positionBuy(input, deps) {
   let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
   let pathDBundlerTrace;
+  let pathDDecodedCall;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
     deps
@@ -2821,6 +2915,7 @@ async function positionBuy(input, deps) {
       const trace = deps.bundler.drainTrace();
       if (trace.length > 0) {
         pathDBundlerTrace = trace;
+        pathDDecodedCall = buildPathDDecodedCall(trace, deps);
       }
     }
   }
@@ -2847,7 +2942,8 @@ ${dashboardUrl}`,
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
       ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
       ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {},
-      ...pathDBundlerTrace ? { pathDBundlerTrace } : {}
+      ...pathDBundlerTrace ? { pathDBundlerTrace } : {},
+      ...pathDDecodedCall ? { pathDDecodedCall } : {}
     }
   });
 }
@@ -3198,7 +3294,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.8";
+    return "0.2.9";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.js

@@ -10,7 +10,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { platform, homedir } from 'os';
 import { connect, createServer } from 'net';
 import { setTimeout as setTimeout$1 } from 'timers/promises';
-import { parseAbi, toFunctionSelector, encodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters } from 'viem';
+import { parseAbi, toFunctionSelector, encodeFunctionData, decodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters } from 'viem';
 import { createHash, randomBytes } from 'crypto';
 import { getUserOperationHash } from 'viem/account-abstraction';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -1964,6 +1964,26 @@ function encodeKernelExecuteSingleCall(input) {
     args: [KERNEL_V3_SINGLE_CALL_MODE_DEFAULT, executionCalldata]
   });
 }
+function decodeKernelExecuteSingleCall(data) {
+  let decoded;
+  try {
+    decoded = decodeFunctionData({ abi: KERNEL_EXECUTE_ABI, data });
+  } catch {
+    return null;
+  }
+  const [mode, executionCalldata] = decoded.args;
+  if (mode !== KERNEL_V3_SINGLE_CALL_MODE_DEFAULT) {
+    return null;
+  }
+  const ec = executionCalldata.slice(2);
+  if (ec.length < 20 * 2 + 32 * 2) {
+    return null;
+  }
+  const target = `0x${ec.slice(0, 40)}`;
+  const value = BigInt(`0x${ec.slice(40, 40 + 64)}`);
+  const innerCallData = `0x${ec.slice(40 + 64)}`;
+  return { mode, target, value, innerCallData };
+}
 var ECDSA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
 var PERMISSION_USE_PREFIX = "0xff";
 function buildKernelSessionKeySignature(input) {
@@ -2353,6 +2373,79 @@ async function syncSnapshotFromMirror(deps, brokerSignerAddress) {
   }
   return { kind: "ok", sessionId: activeId };
 }
+var PURCHASE_SELECTOR_LOWER = SUBSCRIPTION_PURCHASE_SELECTOR.toLowerCase();
+function buildPathDDecodedCall(trace, deps) {
+  const sponsorEvent = trace.find((e) => e.method === "zd_sponsorUserOperation");
+  if (!sponsorEvent) return void 0;
+  let req;
+  try {
+    req = JSON.parse(sponsorEvent.requestBody);
+  } catch {
+    return void 0;
+  }
+  const userOp = req.params?.[0]?.userOp;
+  if (!userOp || typeof userOp.callData !== "string" || !userOp.callData.startsWith("0x")) {
+    return void 0;
+  }
+  const sender = userOp.sender ?? "<missing>";
+  const decoded = decodeKernelExecuteSingleCall(userOp.callData);
+  if (!decoded) {
+    return {
+      sender,
+      kernelExecuteMode: "<undecodable>",
+      kernelExecuteTarget: "<undecodable>",
+      kernelExecuteValue: "<undecodable>",
+      innerSelector: "<undecodable>",
+      interpretation: "kernel.execute callData could not be decoded as single-call default mode. The mode word is non-zero or the executionCalldata layout is unexpected. Manual decode required."
+    };
+  }
+  const innerSelector = decoded.innerCallData.slice(0, 10).toLowerCase();
+  let innerPurchaseTokenArg;
+  let innerPurchaseMaxSharesHint;
+  let innerPurchaseEphemeralEOA;
+  if (innerSelector === PURCHASE_SELECTOR_LOWER) {
+    try {
+      const inner = decodeFunctionData({
+        abi: SUBSCRIPTION_PURCHASE_ABI,
+        data: decoded.innerCallData
+      });
+      const [tokenArg, , maxSharesHint, ephemeralEOA] = inner.args;
+      innerPurchaseTokenArg = tokenArg;
+      innerPurchaseMaxSharesHint = maxSharesHint.toString();
+      innerPurchaseEphemeralEOA = ephemeralEOA;
+    } catch {
+    }
+  }
+  const expectedSubscriptionAddress = deps.subscriptionAddress?.toLowerCase();
+  const kernelTargetLower = decoded.target.toLowerCase();
+  let kernelExecuteTargetMatchesSubscription;
+  let interpretation;
+  if (expectedSubscriptionAddress === void 0) {
+    interpretation = `kernel.execute target=${decoded.target}; inner purchase token=${innerPurchaseTokenArg ?? "<unknown>"}; MUHAVEN_SUBSCRIPTION_ADDRESS not wired on this MCP server \u2014 cannot cross-check.`;
+  } else if (kernelTargetLower === expectedSubscriptionAddress) {
+    kernelExecuteTargetMatchesSubscription = true;
+    interpretation = `kernel.execute target matches MuHavenSubscription (${decoded.target}). Inner purchase token = ${innerPurchaseTokenArg ?? "<unknown>"}. The shape is correct; the AA23 revert is downstream of the validator's signature decode \u2014 likely either an on-chain signer-vs-installed-permission mismatch, a target/selector not in the on-chain policy, or a cap-arg breach. Check muhaven.policy.session_key_status for the installed permission state.`;
+  } else if (innerPurchaseTokenArg !== void 0 && kernelTargetLower === innerPurchaseTokenArg.toLowerCase()) {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} = the RWA MuHavenToken (purchase.token arg0). Expected MuHavenSubscription (${deps.subscriptionAddress}). The kernel is dispatching purchase() to the token contract instead of the subscription \u2014 token doesn't have a purchase() selector, so fallback returns empty revert data (= AA23 reverted 0x). This is a code-side bug in the kernel.execute target wiring.`;
+  } else {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} \u2014 NEITHER the expected MuHavenSubscription (${deps.subscriptionAddress}) NOR the inner purchase.token arg (${innerPurchaseTokenArg ?? "<none>"}). This is an unexpected third-address dispatch; inspect deps.subscriptionAddress env wiring.`;
+  }
+  return {
+    sender,
+    kernelExecuteMode: decoded.mode,
+    kernelExecuteTarget: decoded.target,
+    kernelExecuteValue: decoded.value.toString(),
+    innerSelector,
+    innerPurchaseTokenArg,
+    innerPurchaseMaxSharesHint,
+    innerPurchaseEphemeralEOA,
+    expectedSubscriptionAddress: deps.subscriptionAddress,
+    kernelExecuteTargetMatchesSubscription,
+    interpretation
+  };
+}
 async function attemptPathD(args, deps) {
   const { shares, tokenAddress, tokenSymbol } = args;
   if (!deps.broker || !deps.bundler) {
@@ -2800,6 +2893,7 @@ async function positionBuy(input, deps) {
   let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
   let pathDBundlerTrace;
+  let pathDDecodedCall;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
     deps
@@ -2817,6 +2911,7 @@ async function positionBuy(input, deps) {
       const trace = deps.bundler.drainTrace();
       if (trace.length > 0) {
         pathDBundlerTrace = trace;
+        pathDDecodedCall = buildPathDDecodedCall(trace, deps);
       }
     }
   }
@@ -2843,7 +2938,8 @@ ${dashboardUrl}`,
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
       ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
       ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {},
-      ...pathDBundlerTrace ? { pathDBundlerTrace } : {}
+      ...pathDBundlerTrace ? { pathDBundlerTrace } : {},
+      ...pathDDecodedCall ? { pathDDecodedCall } : {}
     }
   });
 }
@@ -3194,7 +3290,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.8";
+    return "0.2.9";
   }
 }
 function toJsonInputSchema(schema) {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Confidential RWA portfolio management on Fhenix CoFHE. Read your encrypted balances, propose yield claims and policy changes — all signing happens in a sibling broker daemon, the LLM never sees your private key.",
   "long_description": "MuHaven MCP exposes 24 tools across read.* / position.* / policy.* / issuer.* / governance.* groups for managing real-world asset (RWA) tokens with FHE-encrypted balances. Authentication uses a one-time device-code ceremony (run `muhaven-broker login`); subsequent tool calls fetch the JWT from the broker over a Unix socket. Position / governance tools deep-link to the dashboard for passkey signing — they NEVER auto-submit to a bundler. The companion `muhaven-broker` daemon must be running before tools can be invoked. See README for setup.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "MuHaven MCP server — read/position/policy toolsets bridging Claude Desktop / Cursor / Claude Code to the MuHaven backend, with a sibling muhaven-broker daemon holding the session-key private half over a local IPC socket",
   "type": "module",
   "repository": {