agentic-wallet-mcp 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -8,6 +8,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.8.1] — 19 August 2026
+
+### Fixed
+
+- **A payment blocked by the spending cap, or rejected for insufficient balance, now names the
+  real token and shows a human-readable amount** — e.g. `10000 (0.01 JMYR)` instead of a bare raw
+  integer that got mislabeled as ZTX once relayed. Affects `pay_and_fetch`, `subscribe_and_issue`,
+  and `request_ai_birthcert_verification`, since all three share the same payment step.
+- **A wallet holding a ZTP20 token (e.g. JMYR) but zero ZTX no longer fails with a raw, opaque
+  error when trying to pay.** The wallet now checks its own ZTX gas balance before attempting the
+  payment and reports a clear "send some ZTX first" message — working around a bug in
+  `x402-zetrix-client` where its own gas check runs after an on-chain call that can itself fail
+  unhelpfully on a zero-gas account.
+
+### Changed
+
+- The known-but-never-confirmed mainnet SSIVC host is now a named, exported constant
+  (`UNVERIFIED_MAINNET_SSIVC_BASE_URL`) instead of only living in a comment — still not wired in by
+  default (`SSIVC_BASE_URL` remains the way to enable it on mainnet), but easier to flip on once
+  confirmed reachable.
+
 ## [0.8.0] — 17 August 2026
 
 ### Added

package/dist/server-bundle.cjs

@@ -12548,7 +12548,7 @@ var import_node_path6 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.8.0",
+  version: "0.8.1",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -21496,9 +21496,18 @@ var import_node_path = require("node:path");
 
 // src/payment-guard.ts
 var PaymentCapError = class extends Error {
-  constructor(message) {
+  /**
+   * Set only when the failure is "requested amount exceeds the configured cap" — carries the raw
+   * asset identifier and raw base-unit amounts so a caller with symbol/decimals resolution (e.g.
+   * index.ts's `pay`) can rebuild a human-readable message without re-deriving these numbers.
+   * Undefined for configuration-shaped failures (missing cap entry, malformed input), which have
+   * no amount to render more legibly.
+   */
+  detail;
+  constructor(message, detail) {
     super(message);
     this.name = "PaymentCapError";
+    this.detail = detail;
   }
 };
 function isNonNegativeIntegerString(v) {
@@ -21538,7 +21547,10 @@ function assertWithinPaymentCap(accept, caps) {
   const required2 = BigInt(requiredRaw);
   const cap = BigInt(capRaw);
   if (required2 > cap) {
-    throw new PaymentCapError(`payment blocked: requested ${required2} ${asset || "(unknown asset)"} exceeds configured MAX_PAYMENT_AMOUNT ${cap}`);
+    throw new PaymentCapError(
+      `payment blocked: requested ${required2} ${asset || "(unknown asset)"} exceeds configured MAX_PAYMENT_AMOUNT ${cap}`,
+      { asset, requiredRaw: required2.toString(), capRaw: cap.toString() }
+    );
   }
 }
 
@@ -21645,6 +21657,23 @@ async function resolveAssetSymbol(asset, query) {
   const info = await fetchTokenInfo(asset, query);
   return info?.symbol ?? asset;
 }
+var ZTX_DECIMALS = 6;
+async function resolveAssetInfo(asset, query) {
+  if (asset === "ZTX") return { symbol: "ZTX", decimals: ZTX_DECIMALS };
+  if (asset === "") return { symbol: "", decimals: 0 };
+  const info = await fetchTokenInfo(asset, query);
+  return info ?? { symbol: asset, decimals: 0 };
+}
+function formatHumanAmount(raw, decimals) {
+  if (!/^\d+$/.test(raw) || decimals <= 0) return raw;
+  const base = 10n ** BigInt(decimals);
+  const value = BigInt(raw);
+  const wholePart = value / base;
+  const fracPart = value % base;
+  if (fracPart === 0n) return wholePart.toString();
+  const fracStr = fracPart.toString().padStart(decimals, "0").replace(/0+$/, "");
+  return `${wholePart}.${fracStr}`;
+}
 
 // src/clients/contract-query-client.ts
 async function queryContract(input, query) {
@@ -21673,7 +21702,7 @@ async function queryContract(input, query) {
 }
 
 // src/clients/token-balance-client.ts
-var ZTX_DECIMALS = 6;
+var ZTX_DECIMALS2 = 6;
 function parseNativeBalance(res) {
   if (res?.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res?.errorCode}`);
   if (res.result === void 0 || res.result === null) throw new Error("getInfo returned no result");
@@ -21707,7 +21736,7 @@ async function queryTokenBalance(deps, token) {
   const symbol = token.toUpperCase();
   if (symbol === "ZTX") {
     try {
-      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS };
+      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS2 };
     } catch {
       return { token: symbol, error: "query_failed" };
     }
@@ -23705,13 +23734,53 @@ async function main() {
   const vcCache = createFsVcCache((0, import_node_path6.join)(config2.stateDir, "vc-cache", cacheScope));
   const mbi = new MbiClient(config2.mbiBaseUrl);
   const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
-  const pay = (accept) => {
-    assertWithinPaymentCap(accept, config2.maxPaymentAmount);
-    return payWithReadinessCheck(
-      String(accept.asset ?? ""),
-      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
-      activated
-    );
+  const formatAssetAmount = async (asset, raw) => {
+    const { symbol, decimals } = await resolveAssetInfo(asset, contractQuery);
+    const label = symbol || "(unknown asset)";
+    const human = formatHumanAmount(raw, decimals);
+    return human === raw ? `${raw} ${label}` : `${raw} (${human} ${label})`;
+  };
+  const pay = async (accept) => {
+    const rawAsset = String(accept.asset ?? "");
+    try {
+      assertWithinPaymentCap(accept, config2.maxPaymentAmount);
+    } catch (err) {
+      if (err instanceof PaymentCapError && err.detail) {
+        const { asset, requiredRaw, capRaw } = err.detail;
+        throw new PaymentCapError(
+          `payment blocked: requested ${await formatAssetAmount(asset, requiredRaw)} exceeds configured MAX_PAYMENT_AMOUNT ${await formatAssetAmount(asset, capRaw)}`,
+          err.detail
+        );
+      }
+      throw err;
+    }
+    if (rawAsset !== "" && rawAsset !== "ZTX") {
+      const gasBalance = await fetchNativeBalance(zetrixAddress).catch(() => null);
+      if (gasBalance === "0") {
+        const { symbol } = await resolveAssetInfo(rawAsset, contractQuery);
+        throw new PaymentReadinessError(
+          `this wallet has 0 ZTX to pay network gas \u2014 the ${symbol || rawAsset} balance is separate from gas, and every transaction costs a small amount of ZTX regardless of which token is being paid. Send some ZTX to ${zetrixAddress} first, then retry.`,
+          { asset: "ZTX", required: "unknown", available: "0", reason: "gas" }
+        );
+      }
+    }
+    try {
+      return await payWithReadinessCheck(
+        rawAsset,
+        () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
+        activated
+      );
+    } catch (err) {
+      if (err instanceof PaymentReadinessError && err.shortfall.reason !== "not_activated") {
+        const { asset, required: required2, available, reason } = err.shortfall;
+        const label = reason === "gas" ? "ZTX for gas" : (await resolveAssetInfo(asset, contractQuery)).symbol || asset;
+        throw new PaymentReadinessError(
+          `insufficient ${label} \u2014 required ${await formatAssetAmount(asset, required2)}, available ${await formatAssetAmount(asset, available)}`,
+          err.shortfall
+        );
+      }
+      throw err;
+    }
   };
   const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
     const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path6.join)(config2.stateDir, "ssivc-session.json"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",