agentic-wallet-mcp 0.3.1 → 0.4.0

package/README.md

@@ -20,15 +20,23 @@ VC issuance → identity proof → pay-per-use).
 
 | Tool | Does | Input | Output (shape) |
 |---|---|---|---|
-| `wallet_status` | Report holder DID/address/network + client-supplied held VCs | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
-| `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
+| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache) | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
+| `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc?, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
 | `pay_and_fetch` | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on `402` | `{ url, method?, headers?, body? }` | `{ status, body, paymentMade, amountPaid, amountPaidHuman, asset }` |
-| `subscribe_and_issue` | Build the signed payload → pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate? }` | `{ issued, vcId, vc, txHash }` |
+| `subscribe_and_issue` | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate?, dryRun?, forceReissue? }` | `{ issued, vcId, vc, txHash, fromCache? }` |
 | `create_holder_account` | Onboarding: manually mint an additional/replacement HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below) | `{ password, label?, purpose? }` | `{ zetrixAddress, holderDid, publicKeyHex, message }` |
 
-> The wallet **never persists VCs** — the client holds them and passes them in (e.g. `vc` on
-> `prove_identity`, `heldCredentials` on `wallet_status`). All Ed25519 signing goes through
-> Wallet BE HSM; no plaintext private keys.
+> **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
+> (scoped per network + holder — different identities or networks never share a cache).
+> `subscribe_and_issue` checks the cache before paying: a still-valid cached VC is returned
+> immediately with `fromCache: true` and **no payment made**; pass `forceReissue: true` to pay
+> and issue fresh regardless. `wallet_status`/`prove_identity` fall back to the cache
+> automatically when you don't pass `heldCredentials`/`vc` explicitly — `prove_identity` only
+> auto-selects when there's exactly one valid cached VC; with zero or several, it errors and
+> asks you to pass `vc` explicitly. Explicitly passing `vc`/`heldCredentials` (including `[]`)
+> always overrides the cache. Validity is read from the VC's own `validUntil` field, falling
+> back to the `expirationDate` requested at issuance; a VC with neither is cached indefinitely.
+> All Ed25519 signing still goes through Wallet BE HSM; no plaintext private keys.
 
 > `create_holder_account` mints a **brand-new** keypair — Wallet BE's `/account/create` has no
 > way to provision a pre-chosen address. It returns the new `zetrixAddress`/`holderDid` for you
@@ -126,8 +134,9 @@ network:
 
 Only set any of the four explicitly if you run your own instance of that service instead of the
 default one — an explicit value always wins over the network default. The `*.myegdev.com`
-(testnet) hosts are internal — unreachable without VPN; see "Network reachability &
-troubleshooting" below if any of them time out.
+(testnet) hosts are public endpoints — no VPN needed; if you're on a corporate VPN and one of
+them times out, disconnecting it is more likely to fix that than connecting it. See "Network
+reachability & troubleshooting" below.
 
 That's the complete list — no VC-MCP subprocess, no BaaS gateway key, no manually-configured
 BBS+ key to set up.
@@ -220,13 +229,13 @@ Independent of Phases 2/3 — no VC or identity proof involved, just a fresh pay
 
 ## Network reachability & troubleshooting
 
-Several dependencies sit behind a corporate VPN or a CDN edge. When something that worked before
-suddenly times out or 403s, check this table before assuming a code regression — in every case
-observed so far, the code was correct and the network/edge state had changed.
+The `*.myegdev.com` testnet endpoints are public — no VPN needed to reach them. One dependency
+sits behind a CDN edge (see the ZID resolver row below). When something that worked before
+suddenly times out or 403s, check this table before assuming a code regression.
 
 | Symptom | Cause | Fix / status |
 |---|---|---|
-| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | `*.myegdev.com` hosts are internal — unreachable without VPN | Connect/reconnect your VPN, then retry. Verify first: `curl -I https://wallet-api.myegdev.com/server` |
+| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | Transient network issue, or (if you're on a corporate VPN) the VPN routing away from the public internet | If you're on a VPN, try disconnecting it and retrying. Verify reachability directly: `curl -I https://wallet-api.myegdev.com/server` |
 | `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) sitting behind a Cloudflare **managed challenge** that blocks plain server-to-server `fetch` | Server-to-server access to the resolver must be allowlisted so it returns `200` directly. If the challenge is active, `prove_identity`'s `issuerKeys` input is the fallback — fetch the DID document via a real browser (it clears the JS challenge) and pass its `verificationMethod` entries' `publicKeyMultibase` (BBS+) / `publicKeyHex` (Ed25519) directly. |
 | `OID4VP backend returned a malformed presentation definition` | Historical SDK bug: the live sandbox's `GET /v1/presentation/{id}` response has no `expires_at` field, but the SDK guard required one | **Fixed** in `x401-zetrix-client` — `expiresAt` is now optional on `PresentationDefinition`. If you see this, you're on a stale cached `npx` install — clear it (`npx clear-npx-cache` or bump the version) to pick up the current published `agentic-wallet-mcp`. |
 | `SUBMIT_FAILED: OID4VP backend returned 401 ... Missing X-Wallet-Public-Key header` | Historical SDK gap: `POST /v1/presentation/submit` requires wallet-auth headers (`X-Wallet-Public-Key` / `X-Wallet-Signed-Data`, holder signs their own address) that the SDK didn't send | **Fixed** — `X401Wallet` now accepts an injected `submitAuth` provider and the wallet wires it automatically; nothing to configure. |

package/dist/server-bundle.cjs

@@ -2233,8 +2233,8 @@ var require_resolve = __commonJS({
       }
       return count;
     }
-    function getFullPath(resolver, id = "", normalize) {
-      if (normalize !== false)
+    function getFullPath(resolver, id = "", normalize2) {
+      if (normalize2 !== false)
         id = normalizeId(id);
       const p = resolver.parse(id);
       return _getFullPath(resolver, p);
@@ -3630,7 +3630,7 @@ var require_fast_uri = __commonJS({
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
-    function normalize(uri, options) {
+    function normalize2(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
         normalizeString(uri, options);
@@ -3897,7 +3897,7 @@ var require_fast_uri = __commonJS({
     }
     var fastUri = {
       SCHEMES,
-      normalize,
+      normalize: normalize2,
       resolve,
       resolveComponent,
       equal,
@@ -8541,13 +8541,13 @@ var require_path = __commonJS({
         return /^(?:\/|\w+:)/.test(path2);
       }
     );
-    var normalize = (
+    var normalize2 = (
       /**
        * Normalizes the specified path.
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path.normalize = function normalize2(path2) {
+      path.normalize = function normalize3(path2) {
         path2 = path2.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
         var parts = path2.split("/"), absolute = isAbsolute(path2), prefix = "";
         if (absolute)
@@ -8570,12 +8570,12 @@ var require_path = __commonJS({
     );
     path.resolve = function resolve(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
-        includePath = normalize(includePath);
+        includePath = normalize2(includePath);
       if (isAbsolute(includePath))
         return includePath;
       if (!alreadyNormalized)
-        originPath = normalize(originPath);
-      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize(originPath + "/" + includePath) : includePath;
+        originPath = normalize2(originPath);
+      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize2(originPath + "/" + includePath) : includePath;
     };
   }
 });
@@ -12540,11 +12540,14 @@ __export(index_exports, {
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_crypto2 = require("node:crypto");
+var import_node_os = require("node:os");
+var import_node_path2 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.3.1",
+  version: "0.4.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   license: "MIT",
@@ -21607,7 +21610,7 @@ async function resolveAssetSymbol(asset, query) {
 }
 
 // src/clients/template-info-client.ts
-async function fetchTemplateRequiredFields(templateId, registryAddress, nodeBaseUrl, query) {
+async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, query) {
   const key = `template__${templateId}`;
   const url = `${nodeBaseUrl.replace(/\/+$/, "")}/getAccountMetaData?address=${encodeURIComponent(registryAddress)}&key=${encodeURIComponent(key)}`;
   let res;
@@ -21621,10 +21624,16 @@ async function fetchTemplateRequiredFields(templateId, registryAddress, nodeBase
   if (!value) return null;
   try {
     const parsed = JSON.parse(value);
-    if (parsed.applyFormat === void 0 || parsed.applyFormat === null) return [];
+    if (parsed.applyFormat === void 0 || parsed.applyFormat === null) return { required: [], allKeys: [] };
     const format = typeof parsed.applyFormat === "string" ? JSON.parse(parsed.applyFormat) : parsed.applyFormat;
     if (!Array.isArray(format)) return null;
-    return format.filter((e) => e && e.mandatory === 1 && typeof e.key === "string" && e.key !== "").map((e) => e.key);
+    const entries = format.filter(
+      (e) => !!e && typeof e.key === "string" && e.key !== ""
+    );
+    return {
+      required: entries.filter((e) => e.mandatory === 1).map((e) => e.key),
+      allKeys: entries.map((e) => e.key)
+    };
   } catch {
     return null;
   }
@@ -21721,6 +21730,10 @@ function findLeafPath(obj, key) {
   }
   return null;
 }
+function flattenLeafPaths(obj, prefix = []) {
+  if (!isRecord2(obj)) return prefix.length ? [prefix.join(".")] : [];
+  return Object.entries(obj).flatMap(([k, v]) => flattenLeafPaths(v, [...prefix, k]));
+}
 function dcqlToRevealAttributes(credentialQuery, vc) {
   if (!isRecord2(credentialQuery) || !Array.isArray(credentialQuery.credentials)) return [];
   const subject = isRecord2(vc) && isRecord2(vc.credentialSubject) ? vc.credentialSubject : void 0;
@@ -21743,7 +21756,9 @@ function dcqlToRevealAttributes(credentialQuery, vc) {
       }
     }
   }
-  return out;
+  if (!subject) return out;
+  const canonicalIndex = new Map(flattenLeafPaths(subject).map((path, i) => [path, i]));
+  return out.map((path, i) => ({ path, key: canonicalIndex.get(path) ?? Number.MAX_SAFE_INTEGER, i })).sort((a, b) => a.key - b.key || a.i - b.i).map((entry) => entry.path);
 }
 var MbiVpAdapter = class {
   constructor(mbi, signHexBlob, signMessage, holderAddress, resolveIssuerKeys, present) {
@@ -21950,17 +21965,92 @@ function zetrixHexStringToBytes(s) {
   return out;
 }
 
+// src/clients/vc-cache.ts
+var import_node_crypto = require("node:crypto");
+var import_promises = require("node:fs/promises");
+var import_node_path = require("node:path");
+function cacheFileName(templateId) {
+  return `${(0, import_node_crypto.createHash)("sha256").update(templateId).digest("hex")}.json`;
+}
+function isCachedVcShape(value) {
+  return typeof value === "object" && value !== null && typeof value.templateId === "string" && "vc" in value && typeof value.issuedAt === "string";
+}
+function createFsVcCache(baseDir) {
+  return {
+    async get(templateId) {
+      try {
+        const raw = await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), "utf8");
+        const parsed = JSON.parse(raw);
+        return isCachedVcShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(templateId, entry) {
+      await (0, import_promises.mkdir)(baseDir, { recursive: true, mode: 448 });
+      await (0, import_promises.writeFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), JSON.stringify(entry), { encoding: "utf8", mode: 384 });
+    },
+    async list() {
+      let files;
+      try {
+        files = await (0, import_promises.readdir)(baseDir);
+      } catch {
+        return [];
+      }
+      const entries = await Promise.all(
+        files.filter((f) => f.endsWith(".json")).map(async (f) => {
+          try {
+            const parsed = JSON.parse(await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, f), "utf8"));
+            return isCachedVcShape(parsed) ? parsed : null;
+          } catch {
+            return null;
+          }
+        })
+      );
+      return entries.filter((e) => e !== null);
+    }
+  };
+}
+function isVcValid(entry, now = /* @__PURE__ */ new Date()) {
+  if (!entry.validUntil) return true;
+  const expiry = new Date(entry.validUntil);
+  if (Number.isNaN(expiry.getTime())) return false;
+  return expiry.getTime() > now.getTime();
+}
+function extractValidUntil(vc, fallback) {
+  if (typeof vc === "object" && vc !== null && "validUntil" in vc) {
+    const v = vc.validUntil;
+    if (typeof v === "string") return v;
+  }
+  return fallback;
+}
+
 // src/orchestrator/subscribe.ts
 async function subscribeAndIssue(deps, opts) {
   if (!/^did:zid:/.test(opts.templateId)) {
     return { issued: false, reason: `templateId must be a did:zid:... credential-definition id, got "${opts.templateId}"` };
   }
+  if (deps.cache && !opts.forceReissue && !opts.dryRun) {
+    const cached2 = await deps.cache.get(opts.templateId);
+    if (cached2 && isVcValid(cached2)) {
+      return {
+        issued: true,
+        vcId: cached2.vcId,
+        vc: cached2.vc,
+        txHash: cached2.txHash,
+        paidAsset: cached2.paidAsset,
+        amountPaid: cached2.amountPaid,
+        fromCache: true
+      };
+    }
+  }
+  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
   const { agentDid, ...rest } = opts.attributes ?? {};
-  const attributes = agentDid ? opts.attributes : { agentDid: deps.holderDid, ...rest };
-  const required2 = deps.resolveRequiredFields ? await deps.resolveRequiredFields(opts.templateId) : null;
-  if (!opts.dryRun && required2) {
+  const shouldAutoFillAgentDid = !agentDid && fields !== null && fields.allKeys.includes("agentDid");
+  const attributes = shouldAutoFillAgentDid ? { agentDid: deps.holderDid, ...rest } : opts.attributes ?? {};
+  if (!opts.dryRun && fields) {
     const attrs = attributes;
-    const missing = required2.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
+    const missing = fields.required.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
     if (missing.length > 0) {
       return {
         issued: false,
@@ -21986,7 +22076,7 @@ async function subscribeAndIssue(deps, opts) {
         asset: quotedAsset,
         maxAmountRequired: accept.maxAmountRequired,
         payTo: accept.payTo,
-        ...required2 ? { requiredAttributes: required2 } : {}
+        ...fields ? { requiredAttributes: fields.required } : {}
       }
     };
   }
@@ -21994,13 +22084,26 @@ async function subscribeAndIssue(deps, opts) {
   const issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
   const rawAsset = String(accept.asset ?? "");
   const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
+  const amountPaid = String(accept.maxAmountRequired ?? "");
+  if (deps.cache) {
+    await deps.cache.set(opts.templateId, {
+      templateId: opts.templateId,
+      vc: issued.verifiableCredential,
+      vcId: issued.vcId,
+      txHash: issued.txHash,
+      paidAsset,
+      amountPaid,
+      issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      validUntil: extractValidUntil(issued.verifiableCredential, opts.expirationDate)
+    });
+  }
   return {
     issued: true,
     vcId: issued.vcId,
     vc: issued.verifiableCredential,
     txHash: issued.txHash,
     paidAsset,
-    amountPaid: String(accept.maxAmountRequired ?? "")
+    amountPaid
   };
 }
 
@@ -22018,22 +22121,59 @@ async function createHolderAccount(create, input) {
   return { zetrixAddress, holderDid, publicKeyHex, message };
 }
 
+// src/template-aliases.ts
+var TEMPLATE_ALIASES = [
+  {
+    match: "birthcert",
+    testnet: "did:zid:d6b783559acf6ba0f7ef6e1365bdaf0774d622d8d22728ca6323677f49ee94f8",
+    mainnet: "did:zid:032cb99be3577beccfc6252783c49c83673af38f8456d73462043654d7764e83"
+  }
+];
+function normalize(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function resolveTemplateAlias(input, network) {
+  if (/^did:zid:/.test(input)) return void 0;
+  const normalized = normalize(input);
+  const entry = TEMPLATE_ALIASES.find((e) => normalized.includes(e.match));
+  if (!entry) return void 0;
+  return network.includes("testnet") ? entry.testnet : entry.mainnet;
+}
+
 // src/mcp-tools.ts
+async function loadValidCachedCredentials(cache) {
+  if (!cache) return [];
+  const all = await cache.list();
+  return all.filter((entry) => isVcValid(entry));
+}
 function createTools(deps) {
   return {
     async wallet_status(input = {}) {
       const balances = deps.getBalances ? await deps.getBalances() : void 0;
+      const credentials = input.heldCredentials ?? (await loadValidCachedCredentials(deps.cache)).map((entry) => entry.vc);
       return {
         holderDid: deps.config.holderDid,
         zetrixAddress: deps.config.zetrixAddress,
         network: deps.config.network,
-        credentials: input.heldCredentials ?? [],
+        credentials,
         ...balances !== void 0 ? { balances } : {}
       };
     },
-    prove_identity(input) {
+    async prove_identity(input) {
+      let vc = input.vc;
+      if (vc === void 0) {
+        const cached2 = await loadValidCachedCredentials(deps.cache);
+        if (cached2.length === 0) {
+          throw new Error("prove_identity: no vc supplied and no valid credential is cached \u2014 call subscribe_and_issue first, or pass vc explicitly.");
+        }
+        if (cached2.length > 1) {
+          const ids = cached2.map((entry) => entry.templateId).join(", ");
+          throw new Error(`prove_identity: no vc supplied and multiple credentials are cached (templateIds: ${ids}) \u2014 pass vc explicitly to select one.`);
+        }
+        vc = cached2[0].vc;
+      }
       const wallet = deps.makeWallet({
-        vc: input.vc,
+        vc,
         revealAttribute: input.revealAttribute,
         issuerKeys: input.issuerKeys
       });
@@ -22043,7 +22183,8 @@ function createTools(deps) {
       return payAndFetch(deps.payer, input);
     },
     subscribe_and_issue(input) {
-      return subscribeAndIssue(deps.subscribeDeps, input);
+      const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
+      return subscribeAndIssue(deps.subscribeDeps, resolved ? { ...input, templateId: resolved } : input);
     },
     create_holder_account(input) {
       return createHolderAccount(deps.createAccount, input);
@@ -22073,7 +22214,7 @@ function buildToolList() {
       inputSchema: {
         type: "object",
         properties: {
-          heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds (the wallet does not persist them)." }
+          heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds. Omit to report whatever the wallet has cached locally from prior subscribe_and_issue calls instead." }
         }
       }
     },
@@ -22084,7 +22225,7 @@ function buildToolList() {
         type: "object",
         properties: {
           proofRequest: { type: "string", description: "The PROOF-REQUEST header value from the 401 challenge." },
-          vc: { type: "object", description: "The client-held VerifiableCredential to present." },
+          vc: { type: "object", description: "The VerifiableCredential to present. Omit to use the wallet's single locally-cached credential, if there is exactly one \u2014 the call fails with a clear error if none or several are cached." },
           revealAttribute: { type: "array", items: { type: "string" }, description: "Dotted disclosure paths to reveal. Omit to reveal exactly the claims the challenge (DCQL) requests; a challenge naming no claims reveals all." },
           issuerKeys: {
             type: "object",
@@ -22095,7 +22236,7 @@ function buildToolList() {
             description: "Optional issuer verification keys to bypass the ZID resolver when it is unreachable (e.g. Cloudflare-gated). When set, resolution is skipped."
           }
         },
-        required: ["proofRequest", "vc"]
+        required: ["proofRequest"]
       }
     },
     {
@@ -22114,13 +22255,13 @@ function buildToolList() {
     },
     {
       name: "subscribe_and_issue",
-      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay.",
+      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay.",
       inputSchema: {
         type: "object",
         properties: {
           templateId: {
             type: "string",
-            description: `The MBI credential-definition id to issue, e.g. "did:zid:...". Take this from the x401 challenge's credential_requirements.query.credentials[].id \u2014 NOT from requirementsId (that's just a label for the requirement set, e.g. "agent-identity").`
+            description: `The MBI credential-definition id to issue, e.g. "did:zid:...". Take this from the x401 challenge's credential_requirements.query.credentials[].id \u2014 NOT from requirementsId (that's just a label for the requirement set, e.g. "agent-identity"). A known template's natural-language name (e.g. "AI Birthcert") is also accepted and resolved to the right did:zid:... for the configured network.`
           },
           attributes: {
             type: "object",
@@ -22130,6 +22271,10 @@ function buildToolList() {
           dryRun: {
             type: "boolean",
             description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo, requiredAttributes? } } without paying or issuing \u2014 use this to check the payment requirement AND the template's required attributes (read from chain) before spending funds."
+          },
+          forceReissue: {
+            type: "boolean",
+            description: "Skip the local cache and pay + issue a fresh credential regardless of what is already cached."
           }
         },
         required: ["templateId", "attributes"]
@@ -22186,7 +22331,9 @@ async function main() {
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
-  const resolveRequiredFields = (templateId) => fetchTemplateRequiredFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
+  const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
+  const cacheScope = (0, import_node_crypto2.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
+  const vcCache = createFsVcCache((0, import_node_path2.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
   const pay = (accept) => {
     assertWithinPaymentCap(accept, config2.maxPaymentAmount);
     return import_x402_zetrix_client.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn);
@@ -22229,8 +22376,9 @@ async function main() {
     config: { holderDid, zetrixAddress, network: config2.network },
     makeWallet,
     payer,
-    subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveRequiredFields },
-    createAccount: (password, label, purpose) => be.createAccount(password, label, purpose)
+    subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
+    createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
+    cache: vcCache
   };
   const tools = createTools(deps);
   const server = new Server({ name: "agentic-wallet-mcp", version: packageVersion }, { capabilities: { tools: {} } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   "license": "MIT",