@muhaven/mcp 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-05-23
+
+### Fixed
+
+- **`PLACEHOLDER_SIGNATURE` size 86 bytes → 66 bytes** to match the
+  real Kernel v3.1 PermissionValidator signature shape that
+  `buildKernelSessionKeySignature` produces:
+
+      byte 0       — 0xff (PermissionValidator "use root permission" sentinel)
+      bytes 1..65  — 65-byte ECDSA
+      = 66 bytes total
+
+  Pre-0.2.5 the placeholder was 86 bytes — the OLD enable-mode shape
+  (1 byte prefix + 20 bytes validator + 65 bytes ECDSA). The paymaster
+  simulated the validator with the wrong-length signature, the
+  validator reverted with `AA23 reverted`, and
+  `zd_sponsorUserOperation` returned rpc_error → MCP mapped to
+  `paymaster_rejected`. This is the load-bearing piece that 0.2.4 did
+  NOT close.
+
+### Added
+
+- **`pathDFallbackDetail` in the `muhaven.position.buy` echo.** Every
+  Path D fallback (`bundler_setup_failed`, `paymaster_rejected`,
+  `encrypt_shares_server_error`, etc.) now carries the underlying
+  error message in addition to the structured reason code. Pre-0.2.5
+  the message was dropped → every new gate required curl repro to
+  find the actual error class (cost ~2 publish cycles during the
+  2026-05-23 smoke). Future fallback iterations are self-diagnosing.
+  Untrusted-network input (bundler RPC error messages) is sanitized
+  server-side before crossing into the echo (existing
+  `sanitizeRpcMessageForLlmContext` boundary).
+
+### Changed
+
+- **`DEFAULT_REQUEST_TIMEOUT_MS` 15s → 75s.** The cold-start FHE
+  encrypt at `/api/v1/agent/path-d/encrypt-shares` costs ~25s on
+  first call after fhe-worker container boot (CoFHE verifier-
+  signature handshake). The 15s default cut the MCP-side fetch
+  before the backend's reply arrived → spurious
+  `encrypt_shares_server_error`. Operators on warm setups can
+  tighten via `MUHAVEN_REQUEST_TIMEOUT_MS`. Subsequent encrypts
+  after warm-up are sub-second; the 75s ceiling is defensive
+  headroom, not steady-state latency.
+
+## [0.2.4] — 2026-05-23
+
+### Fixed
+
+- **Paymaster RPC method + param shape**:
+  `pm_sponsorUserOperation` → `zd_sponsorUserOperation`. ZeroDev v3
+  endpoints route paymaster RPCs through Alchemy infrastructure, which
+  exposes only ERC-7677 (`pm_getPaymasterStubData` / `pm_getPaymasterData`)
+  and ZeroDev-prefixed (`zd_sponsorUserOperation`) — the legacy
+  `pm_sponsorUserOperation` returns `"Unsupported method"` from
+  Alchemy. The MCP server's `attemptPathD` failed at
+  `pathDFallbackReason: paymaster_rejected` on every Path D autonomous
+  buy. Fix: switch method name + change request shape from positional
+  `[userOp, entryPoint]` to wrapped
+  `[{chainId, userOp, entryPointAddress, shouldOverrideFee, shouldConsume}]`.
+  Matches `@zerodev/sdk@5.5.10`'s `paymaster/sponsorUserOperation.js`
+  byte-for-byte. Verified 2026-05-23 via direct curl reproduction
+  against the prod bundler URL (bare → "Unsupported method"; correct
+  shape → simulation result with AA23 from synthetic UserOp, proving
+  the method works).
+
+  `sponsorUserOp` now requires `expectedChainId` in `BundlerClientOptions`
+  (throws `BundlerClientError(config)` when missing) — the chainId is
+  part of the request envelope. Defaults conservative placeholder gas
+  limits on the userOp when the caller omits them (ZeroDev's Zod
+  validator requires the gas fields in the request even though
+  simulation recomputes them).
+
+  Added 3 regression tests pinning the new method name, the wrapped
+  envelope, the gas-default behaviour + a `config`-error case when
+  expectedChainId is missing.
+
 ## [0.2.3] — 2026-05-23
 
 ### Fixed

package/dist/broker.cjs

@@ -10,7 +10,7 @@ var crypto = require('crypto');
 
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
-var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 75e3;
 var DEFAULT_BROKER_TIMEOUT_MS = 5e3;
 var DEFAULT_BROKER_MAX_BYTES = 64 * 1024;
 var DEFAULT_JWT_CACHE_TTL_SEC = 30;
@@ -2783,7 +2783,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.3";
+    return "0.2.5";
   }
 }
 function printVersion() {

package/dist/broker.js

@@ -12,7 +12,7 @@ var getDirname = () => path.dirname(getFilename());
 var __dirname$1 = /* @__PURE__ */ getDirname();
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
-var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 75e3;
 var DEFAULT_BROKER_TIMEOUT_MS = 5e3;
 var DEFAULT_BROKER_MAX_BYTES = 64 * 1024;
 var DEFAULT_JWT_CACHE_TTL_SEC = 30;
@@ -2785,7 +2785,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.3";
+    return "0.2.5";
   }
 }
 function printVersion() {

package/dist/index.cjs

@@ -22,7 +22,7 @@ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${_
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
-var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 75e3;
 var DEFAULT_BROKER_TIMEOUT_MS = 5e3;
 var DEFAULT_BROKER_MAX_BYTES = 64 * 1024;
 var DEFAULT_JWT_CACHE_TTL_SEC = 30;
@@ -1071,7 +1071,28 @@ var BundlerClient = class {
    * `estimateUserOpGas` round-trip on the happy path).
    */
   async sponsorUserOp(userOp, entryPoint) {
-    const result = await this.rpc("pm_sponsorUserOperation", [userOp, entryPoint]);
+    if (this.options.expectedChainId === void 0) {
+      throw new BundlerClientError(
+        "config",
+        "sponsorUserOp requires expectedChainId in BundlerClientOptions \u2014 ZeroDev paymaster needs it in the request envelope"
+      );
+    }
+    const userOpWithGas = {
+      ...userOp,
+      callGasLimit: userOp.callGasLimit ?? "0x100000",
+      // 1_048_576
+      verificationGasLimit: userOp.verificationGasLimit ?? "0x100000",
+      preVerificationGas: userOp.preVerificationGas ?? "0x100000"
+    };
+    const result = await this.rpc("zd_sponsorUserOperation", [
+      {
+        chainId: this.options.expectedChainId,
+        userOp: userOpWithGas,
+        entryPointAddress: entryPoint,
+        shouldOverrideFee: false,
+        shouldConsume: true
+      }
+    ]);
     return parseSponsoredFields(result);
   }
   /**
@@ -1902,7 +1923,7 @@ var SUBSCRIPTION_PURCHASE_SELECTOR = viem.toFunctionSelector(
 var SUBSCRIPTION_PURCHASE_ABI = viem.parseAbi([
   "function purchase(address token, (uint256 ctHash, uint8 securityZone, uint8 utype, bytes signature) encShares, uint128 maxSharesHint, address ephemeralEOA)"
 ]);
-var PLACEHOLDER_SIGNATURE = "0x" + "fe".repeat(86);
+var PLACEHOLDER_SIGNATURE = "0xff" + "fe".repeat(65);
 function ok(data) {
   return { ok: true, data };
 }
@@ -2646,6 +2667,7 @@ async function positionBuy(input, deps) {
   const navDisplay = formatUsd6AsDecimal(navUsd6);
   const sharesStr = shares.toString();
   let pathDFallbackReason;
+  let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
@@ -2656,6 +2678,7 @@ async function positionBuy(input, deps) {
   }
   if (pathD.kind === "fallback") {
     pathDFallbackReason = pathD.reason;
+    pathDFallbackDetail = pathD.message;
     if (pathD.submittedUserOpHash) {
       pathDSubmittedUserOpHash = pathD.submittedUserOpHash;
     }
@@ -2681,6 +2704,7 @@ ${dashboardUrl}`,
       effectiveNotionalUsd6: effectiveNotionalUsd6.toString(),
       navUsd6: navUsd6.toString(),
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
+      ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
       ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {}
     }
   });
@@ -3032,7 +3056,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.3";
+    return "0.2.5";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.d.cts

@@ -708,6 +708,17 @@ interface PartialUserOpForSponsorship {
     readonly maxPriorityFeePerGas: `0x${string}`;
     /** Worst-case placeholder so paymaster simulates realistic gas. */
     readonly signature: `0x${string}`;
+    /**
+     * Optional pre-estimated gas fields. ZeroDev's `zd_sponsorUserOperation`
+     * does its own simulation + recomputes these in the response, so
+     * passing placeholders is OK — but the upstream Zod validator
+     * REQUIRES the fields to be present. `sponsorUserOp` defaults them
+     * to safe placeholders when omitted (the response carries the real
+     * values for the caller to use).
+     */
+    readonly callGasLimit?: `0x${string}`;
+    readonly verificationGasLimit?: `0x${string}`;
+    readonly preVerificationGas?: `0x${string}`;
 }
 interface SponsoredUserOpFields {
     readonly paymaster: `0x${string}`;

package/dist/index.d.ts

@@ -708,6 +708,17 @@ interface PartialUserOpForSponsorship {
     readonly maxPriorityFeePerGas: `0x${string}`;
     /** Worst-case placeholder so paymaster simulates realistic gas. */
     readonly signature: `0x${string}`;
+    /**
+     * Optional pre-estimated gas fields. ZeroDev's `zd_sponsorUserOperation`
+     * does its own simulation + recomputes these in the response, so
+     * passing placeholders is OK — but the upstream Zod validator
+     * REQUIRES the fields to be present. `sponsorUserOp` defaults them
+     * to safe placeholders when omitted (the response carries the real
+     * values for the caller to use).
+     */
+    readonly callGasLimit?: `0x${string}`;
+    readonly verificationGasLimit?: `0x${string}`;
+    readonly preVerificationGas?: `0x${string}`;
 }
 interface SponsoredUserOpFields {
     readonly paymaster: `0x${string}`;

package/dist/index.js

@@ -18,7 +18,7 @@ import { privateKeyToAccount } from 'viem/accounts';
 // src/server.ts
 var DEFAULT_BACKEND_URL = "https://api.muhaven.app";
 var DEFAULT_DASHBOARD_URL = "https://muhaven.app";
-var DEFAULT_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_REQUEST_TIMEOUT_MS = 75e3;
 var DEFAULT_BROKER_TIMEOUT_MS = 5e3;
 var DEFAULT_BROKER_MAX_BYTES = 64 * 1024;
 var DEFAULT_JWT_CACHE_TTL_SEC = 30;
@@ -1067,7 +1067,28 @@ var BundlerClient = class {
    * `estimateUserOpGas` round-trip on the happy path).
    */
   async sponsorUserOp(userOp, entryPoint) {
-    const result = await this.rpc("pm_sponsorUserOperation", [userOp, entryPoint]);
+    if (this.options.expectedChainId === void 0) {
+      throw new BundlerClientError(
+        "config",
+        "sponsorUserOp requires expectedChainId in BundlerClientOptions \u2014 ZeroDev paymaster needs it in the request envelope"
+      );
+    }
+    const userOpWithGas = {
+      ...userOp,
+      callGasLimit: userOp.callGasLimit ?? "0x100000",
+      // 1_048_576
+      verificationGasLimit: userOp.verificationGasLimit ?? "0x100000",
+      preVerificationGas: userOp.preVerificationGas ?? "0x100000"
+    };
+    const result = await this.rpc("zd_sponsorUserOperation", [
+      {
+        chainId: this.options.expectedChainId,
+        userOp: userOpWithGas,
+        entryPointAddress: entryPoint,
+        shouldOverrideFee: false,
+        shouldConsume: true
+      }
+    ]);
     return parseSponsoredFields(result);
   }
   /**
@@ -1898,7 +1919,7 @@ var SUBSCRIPTION_PURCHASE_SELECTOR = toFunctionSelector(
 var SUBSCRIPTION_PURCHASE_ABI = parseAbi([
   "function purchase(address token, (uint256 ctHash, uint8 securityZone, uint8 utype, bytes signature) encShares, uint128 maxSharesHint, address ephemeralEOA)"
 ]);
-var PLACEHOLDER_SIGNATURE = "0x" + "fe".repeat(86);
+var PLACEHOLDER_SIGNATURE = "0xff" + "fe".repeat(65);
 function ok(data) {
   return { ok: true, data };
 }
@@ -2642,6 +2663,7 @@ async function positionBuy(input, deps) {
   const navDisplay = formatUsd6AsDecimal(navUsd6);
   const sharesStr = shares.toString();
   let pathDFallbackReason;
+  let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
@@ -2652,6 +2674,7 @@ async function positionBuy(input, deps) {
   }
   if (pathD.kind === "fallback") {
     pathDFallbackReason = pathD.reason;
+    pathDFallbackDetail = pathD.message;
     if (pathD.submittedUserOpHash) {
       pathDSubmittedUserOpHash = pathD.submittedUserOpHash;
     }
@@ -2677,6 +2700,7 @@ ${dashboardUrl}`,
       effectiveNotionalUsd6: effectiveNotionalUsd6.toString(),
       navUsd6: navUsd6.toString(),
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
+      ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
       ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {}
     }
   });
@@ -3028,7 +3052,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.3";
+    return "0.2.5";
   }
 }
 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.3",
+  "version": "0.2.5",
   "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.3",
+  "version": "0.2.5",
   "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": {