agentic-wallet-mcp 0.4.2 → 0.6.0

package/dist/server-bundle.cjs

@@ -2233,8 +2233,8 @@ var require_resolve = __commonJS({
       }
       return count;
     }
-    function getFullPath(resolver, id = "", normalize2) {
-      if (normalize2 !== false)
+    function getFullPath(resolver, id = "", normalize3) {
+      if (normalize3 !== 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 normalize2(uri, options) {
+    function normalize3(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: normalize2,
+      normalize: normalize3,
       resolve,
       resolveComponent,
       equal,
@@ -8541,13 +8541,13 @@ var require_path = __commonJS({
         return /^(?:\/|\w+:)/.test(path2);
       }
     );
-    var normalize2 = (
+    var normalize3 = (
       /**
        * Normalizes the specified path.
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path.normalize = function normalize3(path2) {
+      path.normalize = function normalize4(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 = normalize2(includePath);
+        includePath = normalize3(includePath);
       if (isAbsolute(includePath))
         return includePath;
       if (!alreadyNormalized)
-        originPath = normalize2(originPath);
-      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize2(originPath + "/" + includePath) : includePath;
+        originPath = normalize3(originPath);
+      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize3(originPath + "/" + includePath) : includePath;
     };
   }
 });
@@ -12192,7 +12192,7 @@ var require_payment_engine = __commonJS({
     var blob_decoder_1 = require_blob_decoder();
     var prepare_client_1 = require_prepare_client();
     var _sdkCtor = require("zetrix-sdk-nodejs");
-    var InsufficientBalanceError = class _InsufficientBalanceError extends Error {
+    var InsufficientBalanceError2 = class _InsufficientBalanceError extends Error {
       constructor(message, required2, available, asset) {
         super(message);
         this.required = required2;
@@ -12202,7 +12202,7 @@ var require_payment_engine = __commonJS({
         Object.setPrototypeOf(this, _InsufficientBalanceError.prototype);
       }
     };
-    exports2.InsufficientBalanceError = InsufficientBalanceError;
+    exports2.InsufficientBalanceError = InsufficientBalanceError2;
     exports2.PaymentEngine = {
       /**
        * Create a Zetrix SDK instance for the given node config.
@@ -12295,20 +12295,20 @@ var require_payment_engine = __commonJS({
           const { balance } = await exports2.PaymentEngine.fetchAccountInfo(wallet.address, node);
           const required2 = amount + fee;
           if (BigInt(balance) < required2) {
-            throw new InsufficientBalanceError(`Insufficient ZTX: required ${required2}, available ${balance}`, String(required2), balance, "ZTX");
+            throw new InsufficientBalanceError2(`Insufficient ZTX: required ${required2}, available ${balance}`, String(required2), balance, "ZTX");
           }
           return;
         }
         if (!opts.skipTokenCheck) {
           const { balance: tokenBal } = await exports2.PaymentEngine.fetchZTP20Balance(req.asset, wallet.address, node);
           if (BigInt(tokenBal) < amount) {
-            throw new InsufficientBalanceError(`Insufficient ${req.asset}: required ${req.maxAmountRequired}, available ${tokenBal}`, req.maxAmountRequired, tokenBal, req.asset);
+            throw new InsufficientBalanceError2(`Insufficient ${req.asset}: required ${req.maxAmountRequired}, available ${tokenBal}`, req.maxAmountRequired, tokenBal, req.asset);
           }
         }
         if (fee > 0n) {
           const { balance: ztxBal } = await exports2.PaymentEngine.fetchAccountInfo(wallet.address, node);
           if (BigInt(ztxBal) < fee) {
-            throw new InsufficientBalanceError(`Insufficient ZTX for gas: required ${feeLimit}, available ${ztxBal}`, feeLimit, ztxBal, "ZTX");
+            throw new InsufficientBalanceError2(`Insufficient ZTX for gas: required ${feeLimit}, available ${ztxBal}`, feeLimit, ztxBal, "ZTX");
           }
         }
       },
@@ -12547,9 +12547,17 @@ var import_node_path3 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.4.2",
+  version: "0.6.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"],
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "zetrix",
+    "wallet",
+    "x401",
+    "x402",
+    "blockchain"
+  ],
   license: "MIT",
   author: "MyEG Services Berhad",
   homepage: "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
@@ -12570,6 +12578,7 @@ var package_default = {
   files: [
     "dist/server-bundle.cjs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   scripts: {
@@ -21159,7 +21168,7 @@ var StdioServerTransport = class {
 };
 
 // src/index.ts
-var import_x402_zetrix_client = __toESM(require_dist2(), 1);
+var import_x402_zetrix_client2 = __toESM(require_dist2(), 1);
 
 // node_modules/x401-zetrix-client/dist/config.js
 var ZETRIX_OID4VP_URLS = {
@@ -21547,6 +21556,14 @@ function deriveMbiBaseUrl(network) {
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
 }
+var TOKEN_REGISTRY = {
+  JMYR: { testnet: "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b", mainnet: "ZTX3NCkXBqbyJWjZZxciQez945Lu6tGAcjNJr" }
+};
+function resolveTokenAddress(symbol, network) {
+  const entry = TOKEN_REGISTRY[symbol.toUpperCase()];
+  if (!entry) return void 0;
+  return network.includes("testnet") ? entry.testnet : entry.mainnet;
+}
 function loadConfig(env) {
   const req = (key, hint) => {
     const v = env[key];
@@ -21609,6 +21626,75 @@ async function resolveAssetSymbol(asset, query) {
   return info?.symbol ?? asset;
 }
 
+// src/clients/contract-query-client.ts
+async function queryContract(input, query) {
+  let response;
+  try {
+    response = await query({
+      contractAddress: input.contractAddress,
+      input: JSON.stringify({ method: input.method, params: input.params ?? {} }),
+      optType: 2
+    });
+  } catch (e) {
+    return { ok: false, error: `query_contract: RPC call failed \u2014 ${e.message}` };
+  }
+  if (response.errorCode !== 0) {
+    return { ok: false, error: `query_contract: contract call failed with errorCode ${response.errorCode}` };
+  }
+  const raw = response.result?.query_rets?.[0]?.result?.value;
+  if (raw === void 0) {
+    return { ok: false, error: "query_contract: no result value returned" };
+  }
+  try {
+    return { ok: true, result: JSON.parse(raw) };
+  } catch {
+    return { ok: true, result: raw };
+  }
+}
+
+// src/clients/token-balance-client.ts
+var ZTX_DECIMALS = 6;
+async function fetchZTP20BalanceStrict(contractAddress, address, query) {
+  const result = await query({
+    contractAddress,
+    input: JSON.stringify({ method: "balanceOf", params: { address } }),
+    optType: 2
+  });
+  if (result?.errorCode !== 0) {
+    throw new Error(`balanceOf failed with errorCode ${result?.errorCode}`);
+  }
+  const raw = result.result?.query_rets?.[0]?.result?.value;
+  if (raw === void 0 || raw === null || raw === "") {
+    throw new Error("balanceOf returned no value");
+  }
+  const parsed = JSON.parse(raw);
+  const balance = parsed?.balance;
+  if (typeof balance !== "string") {
+    throw new Error("balanceOf returned no balance field");
+  }
+  return balance;
+}
+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 };
+    } catch {
+      return { token: symbol, error: "query_failed" };
+    }
+  }
+  const contractAddress = deps.resolveTokenAddress(symbol);
+  if (!contractAddress) return { token: symbol, error: "unknown_token" };
+  let balance;
+  try {
+    balance = await fetchZTP20BalanceStrict(contractAddress, deps.address, deps.query);
+  } catch {
+    return { token: symbol, error: "query_failed" };
+  }
+  const info = await fetchTokenInfo(contractAddress, deps.query);
+  return { token: symbol, balance, decimals: info?.decimals ?? null };
+}
+
 // src/clients/template-info-client.ts
 async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, query) {
   const key = `template__${templateId}`;
@@ -21667,6 +21753,10 @@ var WalletBeClient = class {
   createAccount(password, label, purpose) {
     return this.post("/wallet/hsm/account/create", { password, label, purpose });
   }
+  /** GET /wallet/hsm/account/activate/status — ground-truth on-chain activation check (no local state). */
+  checkActivationStatus(address) {
+    return this.get("/wallet/hsm/account/activate/status", { address });
+  }
   async post(path, body) {
     const url = `${this.baseUrl}${path}`;
     let res;
@@ -21694,6 +21784,25 @@ var WalletBeClient = class {
     }
     return env.data;
   }
+  async get(path, query) {
+    const url = `${this.baseUrl}${path}?${new URLSearchParams(query).toString()}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: { Accept: "application/json" } });
+    } catch (e) {
+      throw new WalletBeError(`Wallet BE ${path} request failed`, void 0, e);
+    }
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new WalletBeError(`Wallet BE ${path} HTTP ${res.status}: ${text}`);
+    }
+    const env = await res.json();
+    if (env.errorCode !== 0) {
+      const detail = env.data?.errorList?.length ? ` \u2014 ${env.data.errorList.join("; ")}` : "";
+      throw new WalletBeError(`Wallet BE ${path} errorCode ${env.errorCode}: ${env.message ?? "error"}${detail}`, env.errorCode);
+    }
+    return env.data;
+  }
 };
 
 // src/signer.ts
@@ -21803,16 +21912,35 @@ var MbiVpAdapter = class {
 // src/clients/mbi-client.ts
 var MbiError = class extends Error {
   httpStatus;
-  constructor(message, httpStatus) {
+  /**
+   * MBI's own numeric code from the ResponseWrapper body — finer-grained than the HTTP status
+   * and the only reliable way to tell a *definitive* post-payment failure from an indeterminate
+   * one. Undefined when the body carries no numeric `status`.
+   */
+  mbiStatus;
+  constructor(message, httpStatus, mbiStatus) {
     super(message);
     this.name = "MbiError";
     this.httpStatus = httpStatus;
+    this.mbiStatus = mbiStatus;
   }
 };
+var MBI_SETTLEMENT_INDETERMINATE = 4012;
 var MbiClient = class _MbiClient {
   baseUrl;
-  constructor(baseUrl) {
+  /** Per-request deadline in ms. See {@link MbiClient.DEFAULT_TIMEOUT_MS}. */
+  timeoutMs;
+  /**
+   * MBI's own facilitator read timeout is 60s, and `/settle` submits
+   * a transaction on chain. A client deadline at or below that would abort a settle MBI is
+   * still legitimately waiting on — manufacturing exactly the indeterminate outcome that MR
+   * exists to prevent, except on our side where nothing records it. Sits above 60s so MBI
+   * always gets to answer first; raise it in step if MBI's own timeout is ever raised.
+   */
+  static DEFAULT_TIMEOUT_MS = 9e4;
+  constructor(baseUrl, opts) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = opts?.timeoutMs ?? _MbiClient.DEFAULT_TIMEOUT_MS;
   }
   /**
    * Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge.
@@ -21862,6 +21990,7 @@ var MbiClient = class _MbiClient {
     return fetch(`${this.baseUrl}${path}`, {
       method,
       headers,
+      signal: AbortSignal.timeout(this.timeoutMs),
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     }).catch((e) => {
       throw new MbiError(`MBI ${path} request failed: ${e.message}`);
@@ -21876,13 +22005,15 @@ var MbiClient = class _MbiClient {
   async error(res, context) {
     const text = await res.text().catch(() => "");
     let msg = text;
+    let mbiStatus;
     try {
       const j = JSON.parse(text);
+      if (typeof j.status === "number") mbiStatus = j.status;
       const truncated = text.length > _MbiClient.ERROR_BODY_MAX_LEN ? `${text.slice(0, _MbiClient.ERROR_BODY_MAX_LEN)}\u2026 (truncated, ${text.length} bytes total)` : text;
       msg = `${j.message ?? j.error ?? text} | full body: ${truncated}`;
     } catch {
     }
-    return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status);
+    return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status, mbiStatus);
   }
 };
 
@@ -22027,6 +22158,19 @@ function isVcValid(entry, now = /* @__PURE__ */ new Date()) {
   if (Number.isNaN(expiry.getTime())) return false;
   return expiry.getTime() > now.getTime();
 }
+function extractAttributeKeys(vc) {
+  if (typeof vc !== "object" || vc === null) return [];
+  const subject = vc.credentialSubject;
+  if (typeof subject !== "object" || subject === null) return [];
+  const keys = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(subject)) {
+    if (key === "id") continue;
+    if (typeof value === "object" && value !== null) {
+      for (const inner of Object.keys(value)) keys.add(inner);
+    }
+  }
+  return [...keys];
+}
 function extractValidUntil(vc, fallback) {
   if (typeof vc === "object" && vc !== null && "validUntil" in vc) {
     const v = vc.validUntil;
@@ -22035,36 +22179,99 @@ function extractValidUntil(vc, fallback) {
   return fallback;
 }
 
+// src/payment-readiness.ts
+var import_x402_zetrix_client = __toESM(require_dist2(), 1);
+var PaymentReadinessError = class extends Error {
+  shortfall;
+  constructor(message, shortfall) {
+    super(message);
+    this.name = "PaymentReadinessError";
+    this.shortfall = shortfall;
+  }
+};
+function toPaymentReadinessError(err, requestedAsset) {
+  if (!(err instanceof import_x402_zetrix_client.InsufficientBalanceError)) return null;
+  const reason = err.asset === "ZTX" && requestedAsset !== "ZTX" ? "gas" : "resource_payment";
+  return new PaymentReadinessError(err.message, {
+    asset: err.asset,
+    required: err.required,
+    available: err.available,
+    reason
+  });
+}
+async function payWithReadinessCheck(requestedAsset, rawPay) {
+  try {
+    return await rawPay();
+  } catch (err) {
+    const readinessError = toPaymentReadinessError(err, requestedAsset);
+    if (readinessError) throw readinessError;
+    throw err;
+  }
+}
+
 // src/orchestrator/subscribe.ts
+function diffAgainstTemplate(vc, fields) {
+  const held = new Set(extractAttributeKeys(vc));
+  const missing = fields.required.filter((k) => !held.has(k));
+  const dropped = [...held].filter((k) => !fields.allKeys.includes(k));
+  return missing.length > 0 || dropped.length > 0 ? { missing, dropped } : void 0;
+}
+var TERMINAL_SETTLEMENT_STATUSES = /* @__PURE__ */ new Set(["ISSUED", "FAILED"]);
+var RECOVERY_MAX_POLLS = 5;
+var RECOVERY_POLL_DELAY_MS = 2e3;
+async function pollSettlementOutcome(deps, paymentId) {
+  if (!deps.mbi.getStatus) return void 0;
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let last;
+  for (let polls = 1; polls <= RECOVERY_MAX_POLLS; polls++) {
+    let status;
+    try {
+      status = await deps.mbi.getStatus(paymentId);
+    } catch {
+      return { status: "UNKNOWN", ...last ? { txHash: last.txHash, vcId: last.vcId } : {}, polls };
+    }
+    last = { status: status.status, txHash: status.txHash, vcId: status.vcId };
+    if (TERMINAL_SETTLEMENT_STATUSES.has(status.status)) {
+      return { status: status.status, txHash: status.txHash, vcId: status.vcId, polls };
+    }
+    if (polls < RECOVERY_MAX_POLLS) await sleep(RECOVERY_POLL_DELAY_MS);
+  }
+  return { ...last, polls: RECOVERY_MAX_POLLS };
+}
 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}"` };
   }
+  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
+  const schema = fields ? { required: fields.required, optional: fields.allKeys.filter((k) => !fields.required.includes(k)) } : void 0;
   if (deps.cache && !opts.forceReissue && !opts.dryRun) {
     const cached2 = await deps.cache.get(opts.templateId);
     if (cached2 && isVcValid(cached2)) {
+      const originalPayment = { txHash: cached2.txHash, asset: cached2.paidAsset, amount: cached2.amountPaid };
+      const paidOriginally = cached2.amountPaid !== void 0 && cached2.amountPaid !== "0";
+      const staleAttributes = fields ? diffAgainstTemplate(cached2.vc, fields) : void 0;
       return {
         issued: true,
         vcId: cached2.vcId,
         vc: cached2.vc,
-        txHash: cached2.txHash,
-        paidAsset: cached2.paidAsset,
-        amountPaid: cached2.amountPaid,
-        fromCache: true
+        fromCache: true,
+        ...paidOriginally ? { originalPayment } : {},
+        ...schema ? { schema } : {},
+        ...staleAttributes ? { staleAttributes } : {}
       };
     }
   }
-  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
   const { agentDid, ...rest } = opts.attributes ?? {};
   const shouldAutoFillAgentDid = !agentDid && fields !== null && fields.allKeys.includes("agentDid");
   const attributes = shouldAutoFillAgentDid ? { agentDid: deps.holderDid, ...rest } : opts.attributes ?? {};
-  if (!opts.dryRun && fields) {
+  if (fields) {
     const attrs = attributes;
     const missing = fields.required.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
     if (missing.length > 0) {
       return {
         issued: false,
-        reason: `template requires attribute(s) not supplied: ${missing.join(", ")} \u2014 no payment made`
+        reason: `template requires attribute(s) not supplied: ${missing.join(", ")} \u2014 no payment made`,
+        ...schema ? { schema } : {}
       };
     }
   }
@@ -22073,7 +22280,15 @@ async function subscribeAndIssue(deps, opts) {
   const { signBlob: signData, publicKey } = await deps.sign(blob);
   const body = { data, signData, publicKey };
   if (opts.expirationDate) body.expirationDate = opts.expirationDate;
-  const challenge = await deps.mbi.applyChallenge(body);
+  let challenge;
+  try {
+    challenge = await deps.mbi.applyChallenge(body);
+  } catch (err) {
+    if (err instanceof MbiError) {
+      return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+    }
+    throw err;
+  }
   if (challenge.issued) {
     const issued2 = challenge.issued;
     if (deps.cache) {
@@ -22095,11 +22310,12 @@ async function subscribeAndIssue(deps, opts) {
       txHash: issued2.txHash,
       paidAsset: "none",
       amountPaid: "0",
+      ...schema ? { schema } : {},
       ...opts.dryRun ? { reason: "this template requires no payment \u2014 MBI issues synchronously at phase 1, so dryRun could not prevent this issuance" } : {}
     };
   }
   const accept = challenge.accepts[0];
-  if (!accept) return { issued: false, reason: "MBI 402 returned no payment options" };
+  if (!accept) return { issued: false, reason: "MBI 402 returned no payment options", ...schema ? { schema } : {} };
   if (opts.dryRun) {
     const quotedRaw = String(accept.asset ?? "");
     const quotedAsset = deps.resolveSymbol ? await deps.resolveSymbol(quotedRaw) : quotedRaw;
@@ -22109,16 +22325,41 @@ async function subscribeAndIssue(deps, opts) {
       quote: {
         asset: quotedAsset,
         maxAmountRequired: accept.maxAmountRequired,
-        payTo: accept.payTo,
-        ...fields ? { requiredAttributes: fields.required } : {}
-      }
+        payTo: accept.payTo
+      },
+      ...schema ? { schema } : {}
     };
   }
-  const xPayment = await deps.pay(accept);
-  const issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
+  let xPayment;
+  try {
+    xPayment = await deps.pay(accept);
+  } catch (err) {
+    if (err instanceof PaymentReadinessError) {
+      return { issued: false, reason: `insufficient funds: ${err.message}`, insufficientFunds: err.shortfall };
+    }
+    throw err;
+  }
   const rawAsset = String(accept.asset ?? "");
   const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
   const amountPaid = String(accept.maxAmountRequired ?? "");
+  let issued;
+  try {
+    issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
+  } catch (err) {
+    if (err instanceof MbiError) {
+      const paymentAttempted = { asset: paidAsset, amount: amountPaid, paymentId: challenge.paymentId };
+      const recovery = err.mbiStatus === MBI_SETTLEMENT_INDETERMINATE && challenge.paymentId ? await pollSettlementOutcome(deps, challenge.paymentId) : void 0;
+      return {
+        issued: false,
+        reason: err.message,
+        httpStatus: err.httpStatus,
+        ...schema ? { schema } : {},
+        paymentAttempted,
+        ...recovery ? { recovery } : {}
+      };
+    }
+    throw err;
+  }
   if (deps.cache) {
     await deps.cache.set(opts.templateId, {
       templateId: opts.templateId,
@@ -22137,10 +22378,23 @@ async function subscribeAndIssue(deps, opts) {
     vc: issued.verifiableCredential,
     txHash: issued.txHash,
     paidAsset,
-    amountPaid
+    amountPaid,
+    ...schema ? { schema } : {}
   };
 }
 
+// src/orchestrator/wait-for-activation.ts
+async function waitForActivation(check, address, sleep, opts = {}) {
+  const attempts = opts.attempts ?? 3;
+  const delayMs = opts.delayMs ?? 3e3;
+  for (let i = 0; i < attempts; i++) {
+    await sleep(delayMs);
+    const { activated } = await check(address);
+    if (activated) return true;
+  }
+  return false;
+}
+
 // src/orchestrator/onboard.ts
 function deriveHolderDid(publicKeyHex) {
   const hex = publicKeyHex.trim();
@@ -22158,31 +22412,383 @@ async function createHolderAccount(deps, input) {
       message: `An account already exists for this wallet (zetrixAddress=${existing.zetrixAddress}, holderDid=${existing.holderDid}). Ask the user whether to keep using it or create a brand-new one \u2014 call create_holder_account again with confirmNew:true to mint a new account.`
     };
   }
-  const { zetrixAddress, publicKeyHex } = await deps.create(input.password, input.label, input.purpose);
+  const { zetrixAddress, publicKeyHex, activated } = await deps.create(input.password, input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
   await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
-  const message = `New holder HSM account created \u2014 address, DID, and password saved to the wallet's local account store. Both will be used automatically on the next server restart; no manual config edit needed. If your MCP config also sets ZETRIX_ADDRESS/HSM_PASSWORD via environment variables, update or remove those too: an explicit env ZETRIX_ADDRESS/HSM_PASSWORD always takes precedence over the saved account. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional \u2014 it re-derives automatically).`;
-  return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, message };
+  const finalActivated = activated || await waitForActivation(deps.checkActivationStatus, zetrixAddress, deps.sleep);
+  const message = `New holder HSM account created \u2014 address, DID, and password saved to the wallet's local account store. Both will be used automatically on the next server restart; no manual config edit needed. If your MCP config also sets ZETRIX_ADDRESS/HSM_PASSWORD via environment variables, update or remove those too: an explicit env ZETRIX_ADDRESS/HSM_PASSWORD always takes precedence over the saved account. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional \u2014 it re-derives automatically).` + (finalActivated ? "" : ` Note: on-chain activation has not completed yet \u2014 balance/on-chain calls for this address may fail until it does; check again later.`);
+  return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, activated: finalActivated, message };
+}
+
+// src/iso3166.ts
+var COUNTRIES = [
+  { alpha2: "AD", alpha3: "AND", name: "Andorra" },
+  { alpha2: "AE", alpha3: "ARE", name: "United Arab Emirates" },
+  { alpha2: "AF", alpha3: "AFG", name: "Afghanistan" },
+  { alpha2: "AG", alpha3: "ATG", name: "Antigua and Barbuda" },
+  { alpha2: "AI", alpha3: "AIA", name: "Anguilla" },
+  { alpha2: "AL", alpha3: "ALB", name: "Albania" },
+  { alpha2: "AM", alpha3: "ARM", name: "Armenia" },
+  { alpha2: "AO", alpha3: "AGO", name: "Angola" },
+  { alpha2: "AQ", alpha3: "ATA", name: "Antarctica" },
+  { alpha2: "AR", alpha3: "ARG", name: "Argentina" },
+  { alpha2: "AS", alpha3: "ASM", name: "American Samoa" },
+  { alpha2: "AT", alpha3: "AUT", name: "Austria" },
+  { alpha2: "AU", alpha3: "AUS", name: "Australia" },
+  { alpha2: "AW", alpha3: "ABW", name: "Aruba" },
+  { alpha2: "AX", alpha3: "ALA", name: "\xC5land Islands" },
+  { alpha2: "AZ", alpha3: "AZE", name: "Azerbaijan" },
+  { alpha2: "BA", alpha3: "BIH", name: "Bosnia and Herzegovina" },
+  { alpha2: "BB", alpha3: "BRB", name: "Barbados" },
+  { alpha2: "BD", alpha3: "BGD", name: "Bangladesh" },
+  { alpha2: "BE", alpha3: "BEL", name: "Belgium" },
+  { alpha2: "BF", alpha3: "BFA", name: "Burkina Faso" },
+  { alpha2: "BG", alpha3: "BGR", name: "Bulgaria" },
+  { alpha2: "BH", alpha3: "BHR", name: "Bahrain" },
+  { alpha2: "BI", alpha3: "BDI", name: "Burundi" },
+  { alpha2: "BJ", alpha3: "BEN", name: "Benin" },
+  { alpha2: "BL", alpha3: "BLM", name: "Saint Barth\xE9lemy" },
+  { alpha2: "BM", alpha3: "BMU", name: "Bermuda" },
+  { alpha2: "BN", alpha3: "BRN", name: "Brunei Darussalam" },
+  { alpha2: "BO", alpha3: "BOL", name: "Bolivia (Plurinational State of)" },
+  { alpha2: "BQ", alpha3: "BES", name: "Bonaire, Sint Eustatius and Saba" },
+  { alpha2: "BR", alpha3: "BRA", name: "Brazil" },
+  { alpha2: "BS", alpha3: "BHS", name: "Bahamas" },
+  { alpha2: "BT", alpha3: "BTN", name: "Bhutan" },
+  { alpha2: "BV", alpha3: "BVT", name: "Bouvet Island" },
+  { alpha2: "BW", alpha3: "BWA", name: "Botswana" },
+  { alpha2: "BY", alpha3: "BLR", name: "Belarus" },
+  { alpha2: "BZ", alpha3: "BLZ", name: "Belize" },
+  { alpha2: "CA", alpha3: "CAN", name: "Canada" },
+  { alpha2: "CC", alpha3: "CCK", name: "Cocos (Keeling) Islands" },
+  { alpha2: "CD", alpha3: "COD", name: "Congo, Democratic Republic of the" },
+  { alpha2: "CF", alpha3: "CAF", name: "Central African Republic" },
+  { alpha2: "CG", alpha3: "COG", name: "Congo" },
+  { alpha2: "CH", alpha3: "CHE", name: "Switzerland" },
+  { alpha2: "CI", alpha3: "CIV", name: "C\xF4te d'Ivoire" },
+  { alpha2: "CK", alpha3: "COK", name: "Cook Islands" },
+  { alpha2: "CL", alpha3: "CHL", name: "Chile" },
+  { alpha2: "CM", alpha3: "CMR", name: "Cameroon" },
+  { alpha2: "CN", alpha3: "CHN", name: "China" },
+  { alpha2: "CO", alpha3: "COL", name: "Colombia" },
+  { alpha2: "CR", alpha3: "CRI", name: "Costa Rica" },
+  { alpha2: "CU", alpha3: "CUB", name: "Cuba" },
+  { alpha2: "CV", alpha3: "CPV", name: "Cabo Verde" },
+  { alpha2: "CW", alpha3: "CUW", name: "Cura\xE7ao" },
+  { alpha2: "CX", alpha3: "CXR", name: "Christmas Island" },
+  { alpha2: "CY", alpha3: "CYP", name: "Cyprus" },
+  { alpha2: "CZ", alpha3: "CZE", name: "Czechia" },
+  { alpha2: "DE", alpha3: "DEU", name: "Germany" },
+  { alpha2: "DJ", alpha3: "DJI", name: "Djibouti" },
+  { alpha2: "DK", alpha3: "DNK", name: "Denmark" },
+  { alpha2: "DM", alpha3: "DMA", name: "Dominica" },
+  { alpha2: "DO", alpha3: "DOM", name: "Dominican Republic" },
+  { alpha2: "DZ", alpha3: "DZA", name: "Algeria" },
+  { alpha2: "EC", alpha3: "ECU", name: "Ecuador" },
+  { alpha2: "EE", alpha3: "EST", name: "Estonia" },
+  { alpha2: "EG", alpha3: "EGY", name: "Egypt" },
+  { alpha2: "EH", alpha3: "ESH", name: "Western Sahara" },
+  { alpha2: "ER", alpha3: "ERI", name: "Eritrea" },
+  { alpha2: "ES", alpha3: "ESP", name: "Spain" },
+  { alpha2: "ET", alpha3: "ETH", name: "Ethiopia" },
+  { alpha2: "FI", alpha3: "FIN", name: "Finland" },
+  { alpha2: "FJ", alpha3: "FJI", name: "Fiji" },
+  { alpha2: "FK", alpha3: "FLK", name: "Falkland Islands (Malvinas)" },
+  { alpha2: "FM", alpha3: "FSM", name: "Micronesia (Federated States of)" },
+  { alpha2: "FO", alpha3: "FRO", name: "Faroe Islands" },
+  { alpha2: "FR", alpha3: "FRA", name: "France" },
+  { alpha2: "GA", alpha3: "GAB", name: "Gabon" },
+  { alpha2: "GB", alpha3: "GBR", name: "United Kingdom of Great Britain and Northern Ireland" },
+  { alpha2: "GD", alpha3: "GRD", name: "Grenada" },
+  { alpha2: "GE", alpha3: "GEO", name: "Georgia" },
+  { alpha2: "GF", alpha3: "GUF", name: "French Guiana" },
+  { alpha2: "GG", alpha3: "GGY", name: "Guernsey" },
+  { alpha2: "GH", alpha3: "GHA", name: "Ghana" },
+  { alpha2: "GI", alpha3: "GIB", name: "Gibraltar" },
+  { alpha2: "GL", alpha3: "GRL", name: "Greenland" },
+  { alpha2: "GM", alpha3: "GMB", name: "Gambia" },
+  { alpha2: "GN", alpha3: "GIN", name: "Guinea" },
+  { alpha2: "GP", alpha3: "GLP", name: "Guadeloupe" },
+  { alpha2: "GQ", alpha3: "GNQ", name: "Equatorial Guinea" },
+  { alpha2: "GR", alpha3: "GRC", name: "Greece" },
+  { alpha2: "GS", alpha3: "SGS", name: "South Georgia and the South Sandwich Islands" },
+  { alpha2: "GT", alpha3: "GTM", name: "Guatemala" },
+  { alpha2: "GU", alpha3: "GUM", name: "Guam" },
+  { alpha2: "GW", alpha3: "GNB", name: "Guinea-Bissau" },
+  { alpha2: "GY", alpha3: "GUY", name: "Guyana" },
+  { alpha2: "HK", alpha3: "HKG", name: "Hong Kong" },
+  { alpha2: "HM", alpha3: "HMD", name: "Heard Island and McDonald Islands" },
+  { alpha2: "HN", alpha3: "HND", name: "Honduras" },
+  { alpha2: "HR", alpha3: "HRV", name: "Croatia" },
+  { alpha2: "HT", alpha3: "HTI", name: "Haiti" },
+  { alpha2: "HU", alpha3: "HUN", name: "Hungary" },
+  { alpha2: "ID", alpha3: "IDN", name: "Indonesia" },
+  { alpha2: "IE", alpha3: "IRL", name: "Ireland" },
+  { alpha2: "IL", alpha3: "ISR", name: "Israel" },
+  { alpha2: "IM", alpha3: "IMN", name: "Isle of Man" },
+  { alpha2: "IN", alpha3: "IND", name: "India" },
+  { alpha2: "IO", alpha3: "IOT", name: "British Indian Ocean Territory" },
+  { alpha2: "IQ", alpha3: "IRQ", name: "Iraq" },
+  { alpha2: "IR", alpha3: "IRN", name: "Iran (Islamic Republic of)" },
+  { alpha2: "IS", alpha3: "ISL", name: "Iceland" },
+  { alpha2: "IT", alpha3: "ITA", name: "Italy" },
+  { alpha2: "JE", alpha3: "JEY", name: "Jersey" },
+  { alpha2: "JM", alpha3: "JAM", name: "Jamaica" },
+  { alpha2: "JO", alpha3: "JOR", name: "Jordan" },
+  { alpha2: "JP", alpha3: "JPN", name: "Japan" },
+  { alpha2: "KE", alpha3: "KEN", name: "Kenya" },
+  { alpha2: "KG", alpha3: "KGZ", name: "Kyrgyzstan" },
+  { alpha2: "KH", alpha3: "KHM", name: "Cambodia" },
+  { alpha2: "KI", alpha3: "KIR", name: "Kiribati" },
+  { alpha2: "KM", alpha3: "COM", name: "Comoros" },
+  { alpha2: "KN", alpha3: "KNA", name: "Saint Kitts and Nevis" },
+  { alpha2: "KP", alpha3: "PRK", name: "Korea (Democratic People's Republic of)" },
+  { alpha2: "KR", alpha3: "KOR", name: "Korea, Republic of" },
+  { alpha2: "KW", alpha3: "KWT", name: "Kuwait" },
+  { alpha2: "KY", alpha3: "CYM", name: "Cayman Islands" },
+  { alpha2: "KZ", alpha3: "KAZ", name: "Kazakhstan" },
+  { alpha2: "LA", alpha3: "LAO", name: "Lao People's Democratic Republic" },
+  { alpha2: "LB", alpha3: "LBN", name: "Lebanon" },
+  { alpha2: "LC", alpha3: "LCA", name: "Saint Lucia" },
+  { alpha2: "LI", alpha3: "LIE", name: "Liechtenstein" },
+  { alpha2: "LK", alpha3: "LKA", name: "Sri Lanka" },
+  { alpha2: "LR", alpha3: "LBR", name: "Liberia" },
+  { alpha2: "LS", alpha3: "LSO", name: "Lesotho" },
+  { alpha2: "LT", alpha3: "LTU", name: "Lithuania" },
+  { alpha2: "LU", alpha3: "LUX", name: "Luxembourg" },
+  { alpha2: "LV", alpha3: "LVA", name: "Latvia" },
+  { alpha2: "LY", alpha3: "LBY", name: "Libya" },
+  { alpha2: "MA", alpha3: "MAR", name: "Morocco" },
+  { alpha2: "MC", alpha3: "MCO", name: "Monaco" },
+  { alpha2: "MD", alpha3: "MDA", name: "Moldova, Republic of" },
+  { alpha2: "ME", alpha3: "MNE", name: "Montenegro" },
+  { alpha2: "MF", alpha3: "MAF", name: "Saint Martin (French part)" },
+  { alpha2: "MG", alpha3: "MDG", name: "Madagascar" },
+  { alpha2: "MH", alpha3: "MHL", name: "Marshall Islands" },
+  { alpha2: "MK", alpha3: "MKD", name: "North Macedonia" },
+  { alpha2: "ML", alpha3: "MLI", name: "Mali" },
+  { alpha2: "MM", alpha3: "MMR", name: "Myanmar" },
+  { alpha2: "MN", alpha3: "MNG", name: "Mongolia" },
+  { alpha2: "MO", alpha3: "MAC", name: "Macao" },
+  { alpha2: "MP", alpha3: "MNP", name: "Northern Mariana Islands" },
+  { alpha2: "MQ", alpha3: "MTQ", name: "Martinique" },
+  { alpha2: "MR", alpha3: "MRT", name: "Mauritania" },
+  { alpha2: "MS", alpha3: "MSR", name: "Montserrat" },
+  { alpha2: "MT", alpha3: "MLT", name: "Malta" },
+  { alpha2: "MU", alpha3: "MUS", name: "Mauritius" },
+  { alpha2: "MV", alpha3: "MDV", name: "Maldives" },
+  { alpha2: "MW", alpha3: "MWI", name: "Malawi" },
+  { alpha2: "MX", alpha3: "MEX", name: "Mexico" },
+  { alpha2: "MY", alpha3: "MYS", name: "Malaysia" },
+  { alpha2: "MZ", alpha3: "MOZ", name: "Mozambique" },
+  { alpha2: "NA", alpha3: "NAM", name: "Namibia" },
+  { alpha2: "NC", alpha3: "NCL", name: "New Caledonia" },
+  { alpha2: "NE", alpha3: "NER", name: "Niger" },
+  { alpha2: "NF", alpha3: "NFK", name: "Norfolk Island" },
+  { alpha2: "NG", alpha3: "NGA", name: "Nigeria" },
+  { alpha2: "NI", alpha3: "NIC", name: "Nicaragua" },
+  { alpha2: "NL", alpha3: "NLD", name: "Netherlands" },
+  { alpha2: "NO", alpha3: "NOR", name: "Norway" },
+  { alpha2: "NP", alpha3: "NPL", name: "Nepal" },
+  { alpha2: "NR", alpha3: "NRU", name: "Nauru" },
+  { alpha2: "NU", alpha3: "NIU", name: "Niue" },
+  { alpha2: "NZ", alpha3: "NZL", name: "New Zealand" },
+  { alpha2: "OM", alpha3: "OMN", name: "Oman" },
+  { alpha2: "PA", alpha3: "PAN", name: "Panama" },
+  { alpha2: "PE", alpha3: "PER", name: "Peru" },
+  { alpha2: "PF", alpha3: "PYF", name: "French Polynesia" },
+  { alpha2: "PG", alpha3: "PNG", name: "Papua New Guinea" },
+  { alpha2: "PH", alpha3: "PHL", name: "Philippines" },
+  { alpha2: "PK", alpha3: "PAK", name: "Pakistan" },
+  { alpha2: "PL", alpha3: "POL", name: "Poland" },
+  { alpha2: "PM", alpha3: "SPM", name: "Saint Pierre and Miquelon" },
+  { alpha2: "PN", alpha3: "PCN", name: "Pitcairn" },
+  { alpha2: "PR", alpha3: "PRI", name: "Puerto Rico" },
+  { alpha2: "PS", alpha3: "PSE", name: "Palestine, State of" },
+  { alpha2: "PT", alpha3: "PRT", name: "Portugal" },
+  { alpha2: "PW", alpha3: "PLW", name: "Palau" },
+  { alpha2: "PY", alpha3: "PRY", name: "Paraguay" },
+  { alpha2: "QA", alpha3: "QAT", name: "Qatar" },
+  { alpha2: "RE", alpha3: "REU", name: "R\xE9union" },
+  { alpha2: "RO", alpha3: "ROU", name: "Romania" },
+  { alpha2: "RS", alpha3: "SRB", name: "Serbia" },
+  { alpha2: "RU", alpha3: "RUS", name: "Russian Federation" },
+  { alpha2: "RW", alpha3: "RWA", name: "Rwanda" },
+  { alpha2: "SA", alpha3: "SAU", name: "Saudi Arabia" },
+  { alpha2: "SB", alpha3: "SLB", name: "Solomon Islands" },
+  { alpha2: "SC", alpha3: "SYC", name: "Seychelles" },
+  { alpha2: "SD", alpha3: "SDN", name: "Sudan" },
+  { alpha2: "SE", alpha3: "SWE", name: "Sweden" },
+  { alpha2: "SG", alpha3: "SGP", name: "Singapore" },
+  { alpha2: "SH", alpha3: "SHN", name: "Saint Helena, Ascension and Tristan da Cunha" },
+  { alpha2: "SI", alpha3: "SVN", name: "Slovenia" },
+  { alpha2: "SJ", alpha3: "SJM", name: "Svalbard and Jan Mayen" },
+  { alpha2: "SK", alpha3: "SVK", name: "Slovakia" },
+  { alpha2: "SL", alpha3: "SLE", name: "Sierra Leone" },
+  { alpha2: "SM", alpha3: "SMR", name: "San Marino" },
+  { alpha2: "SN", alpha3: "SEN", name: "Senegal" },
+  { alpha2: "SO", alpha3: "SOM", name: "Somalia" },
+  { alpha2: "SR", alpha3: "SUR", name: "Suriname" },
+  { alpha2: "SS", alpha3: "SSD", name: "South Sudan" },
+  { alpha2: "ST", alpha3: "STP", name: "Sao Tome and Principe" },
+  { alpha2: "SV", alpha3: "SLV", name: "El Salvador" },
+  { alpha2: "SX", alpha3: "SXM", name: "Sint Maarten (Dutch part)" },
+  { alpha2: "SY", alpha3: "SYR", name: "Syrian Arab Republic" },
+  { alpha2: "SZ", alpha3: "SWZ", name: "Eswatini" },
+  { alpha2: "TC", alpha3: "TCA", name: "Turks and Caicos Islands" },
+  { alpha2: "TD", alpha3: "TCD", name: "Chad" },
+  { alpha2: "TF", alpha3: "ATF", name: "French Southern Territories" },
+  { alpha2: "TG", alpha3: "TGO", name: "Togo" },
+  { alpha2: "TH", alpha3: "THA", name: "Thailand" },
+  { alpha2: "TJ", alpha3: "TJK", name: "Tajikistan" },
+  { alpha2: "TK", alpha3: "TKL", name: "Tokelau" },
+  { alpha2: "TL", alpha3: "TLS", name: "Timor-Leste" },
+  { alpha2: "TM", alpha3: "TKM", name: "Turkmenistan" },
+  { alpha2: "TN", alpha3: "TUN", name: "Tunisia" },
+  { alpha2: "TO", alpha3: "TON", name: "Tonga" },
+  { alpha2: "TR", alpha3: "TUR", name: "T\xFCrkiye" },
+  { alpha2: "TT", alpha3: "TTO", name: "Trinidad and Tobago" },
+  { alpha2: "TV", alpha3: "TUV", name: "Tuvalu" },
+  { alpha2: "TW", alpha3: "TWN", name: "Taiwan, Province of China" },
+  { alpha2: "TZ", alpha3: "TZA", name: "Tanzania, United Republic of" },
+  { alpha2: "UA", alpha3: "UKR", name: "Ukraine" },
+  { alpha2: "UG", alpha3: "UGA", name: "Uganda" },
+  { alpha2: "UM", alpha3: "UMI", name: "United States Minor Outlying Islands" },
+  { alpha2: "US", alpha3: "USA", name: "United States of America" },
+  { alpha2: "UY", alpha3: "URY", name: "Uruguay" },
+  { alpha2: "UZ", alpha3: "UZB", name: "Uzbekistan" },
+  { alpha2: "VA", alpha3: "VAT", name: "Holy See" },
+  { alpha2: "VC", alpha3: "VCT", name: "Saint Vincent and the Grenadines" },
+  { alpha2: "VE", alpha3: "VEN", name: "Venezuela (Bolivarian Republic of)" },
+  { alpha2: "VG", alpha3: "VGB", name: "Virgin Islands (British)" },
+  { alpha2: "VI", alpha3: "VIR", name: "Virgin Islands (U.S.)" },
+  { alpha2: "VN", alpha3: "VNM", name: "Viet Nam" },
+  { alpha2: "VU", alpha3: "VUT", name: "Vanuatu" },
+  { alpha2: "WF", alpha3: "WLF", name: "Wallis and Futuna" },
+  { alpha2: "WS", alpha3: "WSM", name: "Samoa" },
+  { alpha2: "YE", alpha3: "YEM", name: "Yemen" },
+  { alpha2: "YT", alpha3: "MYT", name: "Mayotte" },
+  { alpha2: "ZA", alpha3: "ZAF", name: "South Africa" },
+  { alpha2: "ZM", alpha3: "ZMB", name: "Zambia" },
+  { alpha2: "ZW", alpha3: "ZWE", name: "Zimbabwe" }
+];
+var COMMON_ALIASES = {
+  usa: "US",
+  america: "US",
+  unitedstates: "US",
+  uk: "GB",
+  unitedkingdom: "GB",
+  britain: "GB",
+  greatbritain: "GB",
+  southkorea: "KR",
+  northkorea: "KP",
+  russia: "RU",
+  vietnam: "VN",
+  laos: "LA",
+  syria: "SY",
+  iran: "IR",
+  ivorycoast: "CI",
+  czechrepublic: "CZ",
+  swaziland: "SZ",
+  burma: "MM",
+  capeverde: "CV",
+  easttimor: "TL",
+  taiwan: "TW",
+  macedonia: "MK",
+  vatican: "VA",
+  vaticancity: "VA",
+  holland: "NL",
+  moldova: "MD",
+  bolivia: "BO",
+  tanzania: "TZ",
+  venezuela: "VE",
+  palestine: "PS",
+  brunei: "BN"
+};
+function normalize(s) {
+  return s.toLowerCase().trim().replace(/[^a-z0-9]/g, "");
+}
+function isValidCountry(input) {
+  const trimmed = input.trim();
+  if (/^[A-Za-z]{2}$/.test(trimmed)) {
+    return COUNTRIES.some((c) => c.alpha2 === trimmed.toUpperCase());
+  }
+  if (/^[A-Za-z]{3}$/.test(trimmed)) {
+    return COUNTRIES.some((c) => c.alpha3 === trimmed.toUpperCase());
+  }
+  const normalized = normalize(trimmed);
+  if (COMMON_ALIASES[normalized]) return true;
+  return COUNTRIES.some((c) => normalize(c.name) === normalized);
 }
 
 // src/template-aliases.ts
+function validateDob(value) {
+  if (typeof value !== "string") return "dob must be a string in YYYY-MM-DD format";
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return `dob must match the format YYYY-MM-DD, got "${value}"`;
+  const [year, month, day] = value.split("-").map(Number);
+  const date3 = new Date(Date.UTC(year, month - 1, day));
+  const isRealCalendarDate = date3.getUTCFullYear() === year && date3.getUTCMonth() === month - 1 && date3.getUTCDate() === day;
+  if (!isRealCalendarDate) return `dob is not a valid calendar date: "${value}"`;
+  return void 0;
+}
+function validateCountryOfOrigin(value) {
+  if (typeof value !== "string" || !value.trim()) return "countryOfOrigin must be a non-empty string";
+  if (!isValidCountry(value)) return `countryOfOrigin must be an ISO 3166 country code or name, got "${value}"`;
+  return void 0;
+}
 var TEMPLATE_ALIASES = [
   {
     match: "birthcert",
-    testnet: "did:zid:d6b783559acf6ba0f7ef6e1365bdaf0774d622d8d22728ca6323677f49ee94f8",
-    mainnet: "did:zid:032cb99be3577beccfc6252783c49c83673af38f8456d73462043654d7764e83"
+    testnet: "did:zid:3c0fb79adff08e14e06dcd6e3243205010dd65f533434a3d96c55575d1d3d959",
+    mainnet: "did:zid:19091d19049abb8869b4b8e2f4a887bd1d1d86e5f5ebd0c8297000255f67765b",
+    deriveAttributes: { id: "agentUsername" },
+    validateAttributes: { dob: validateDob, countryOfOrigin: validateCountryOfOrigin }
   }
 ];
-function normalize(s) {
+function normalize2(s) {
   return s.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
+function findEntry(templateId, network) {
+  if (/^did:zid:/.test(templateId)) {
+    const key = network.includes("testnet") ? "testnet" : "mainnet";
+    return TEMPLATE_ALIASES.find((e) => e[key] === templateId);
+  }
+  const normalized = normalize2(templateId);
+  return TEMPLATE_ALIASES.find((e) => normalized.includes(e.match));
+}
 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));
+  const entry = findEntry(input, network);
   if (!entry) return void 0;
   return network.includes("testnet") ? entry.testnet : entry.mainnet;
 }
+function deriveTemplateAttributes(templateId, network, attributes) {
+  const entry = findEntry(templateId, network);
+  if (!entry?.deriveAttributes) return attributes;
+  const result = { ...attributes };
+  for (const [target, source] of Object.entries(entry.deriveAttributes)) {
+    if ((result[target] === void 0 || result[target] === null || result[target] === "") && result[source] !== void 0) {
+      result[target] = result[source];
+    }
+  }
+  return result;
+}
+function derivedAttributeKeys(templateId, network) {
+  const entry = findEntry(templateId, network);
+  return entry?.deriveAttributes ? Object.keys(entry.deriveAttributes) : [];
+}
+function validateTemplateAttributes(templateId, network, attributes) {
+  const entry = findEntry(templateId, network);
+  if (!entry?.validateAttributes) return [];
+  const errors = [];
+  for (const [key, validate] of Object.entries(entry.validateAttributes)) {
+    const value = attributes[key];
+    if (value === void 0 || value === null || value === "") continue;
+    const error2 = validate(value);
+    if (error2) errors.push(error2);
+  }
+  return errors;
+}
 
 // src/mcp-tools.ts
 async function loadValidCachedCredentials(cache) {
@@ -22194,13 +22800,15 @@ function createTools(deps) {
   return {
     async wallet_status(input = {}) {
       const balances = deps.getBalances ? await deps.getBalances() : void 0;
+      const tokenBalance = input.token && deps.queryTokenBalance ? await deps.queryTokenBalance(input.token) : 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,
-        ...balances !== void 0 ? { balances } : {}
+        ...balances !== void 0 ? { balances } : {},
+        ...tokenBalance !== void 0 ? { tokenBalance } : {}
       };
     },
     async prove_identity(input) {
@@ -22226,16 +22834,67 @@ function createTools(deps) {
     pay_and_fetch(input) {
       return payAndFetch(deps.payer, input);
     },
-    subscribe_and_issue(input) {
+    async subscribe_and_issue(input) {
       const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
-      return subscribeAndIssue(deps.subscribeDeps, resolved ? { ...input, templateId: resolved } : input);
+      const templateId = resolved ?? input.templateId;
+      const attributes = deriveTemplateAttributes(templateId, deps.config.network, input.attributes ?? {});
+      const errors = validateTemplateAttributes(templateId, deps.config.network, attributes);
+      if (errors.length > 0) {
+        return { issued: false, reason: errors.join("; ") };
+      }
+      const result = await subscribeAndIssue(deps.subscribeDeps, { ...input, templateId, attributes });
+      if (!result.schema) return result;
+      const hidden = /* @__PURE__ */ new Set(["agentDid", ...derivedAttributeKeys(templateId, deps.config.network)]);
+      return {
+        ...result,
+        schema: {
+          required: result.schema.required.filter((k) => !hidden.has(k)),
+          optional: result.schema.optional.filter((k) => !hidden.has(k))
+        }
+      };
+    },
+    /**
+     * Free schema lookup. Previously the only way to ask "what does this template need?" was
+     * subscribe_and_issue({ dryRun: true }) — a tool whose name reads as "this charges money", so
+     * an agent reasoning about required fields had no obvious reason to reach for it. Reported
+     * live: an agent discovered a newly-required attribute only by failing an issuance first.
+     */
+    async get_template_schema(input) {
+      const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
+      const templateId = resolved ?? input.templateId;
+      if (!/^did:zid:/.test(templateId)) {
+        return {
+          templateId,
+          error: `templateId must be a did:zid:... credential-definition id or a known template name, got "${input.templateId}"`
+        };
+      }
+      const fields = deps.subscribeDeps.resolveTemplateFields ? await deps.subscribeDeps.resolveTemplateFields(templateId) : null;
+      if (!fields) {
+        return {
+          templateId,
+          error: `template schema could not be read from chain for ${templateId} (unknown/inactive template, or node unavailable)`
+        };
+      }
+      const hidden = /* @__PURE__ */ new Set(["agentDid", ...derivedAttributeKeys(templateId, deps.config.network)]);
+      return {
+        templateId,
+        schema: {
+          required: fields.required.filter((k) => !hidden.has(k)),
+          optional: fields.allKeys.filter((k) => !fields.required.includes(k) && !hidden.has(k))
+        }
+      };
+    },
+    query_contract(input) {
+      return deps.queryContract(input);
     },
     create_holder_account(input) {
       return createHolderAccount(
         {
           create: deps.createAccount,
           getExistingAccount: () => Promise.resolve(deps.config.zetrixAddress ? { zetrixAddress: deps.config.zetrixAddress, holderDid: deps.config.holderDid } : null),
-          saveAccount: deps.saveAccount
+          saveAccount: deps.saveAccount,
+          checkActivationStatus: deps.checkActivationStatus,
+          sleep: deps.sleep
         },
         input
       );
@@ -22246,8 +22905,16 @@ function createTools(deps) {
 // src/orchestrator/resolve-holder.ts
 async function resolveHolder(deps, input) {
   if (!input.zetrixAddress) {
-    const { zetrixAddress, publicKeyHex } = await deps.createAccount(input.hsmPassword);
-    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), created: true, didMismatch: false };
+    const { zetrixAddress, publicKeyHex, activated } = await deps.createAccount(input.hsmPassword);
+    let finalActivated = activated;
+    if (!finalActivated) {
+      try {
+        finalActivated = await waitForActivation(deps.checkActivationStatus, zetrixAddress, deps.sleep);
+      } catch {
+        finalActivated = false;
+      }
+    }
+    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), created: true, didMismatch: false, activated: finalActivated };
   }
   const { publicKey } = await deps.signMessage(input.zetrixAddress, input.zetrixAddress, input.hsmPassword);
   const derivedDid = deriveHolderDid(publicKey);
@@ -22289,7 +22956,8 @@ function buildToolList() {
       inputSchema: {
         type: "object",
         properties: {
-          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." }
+          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." },
+          token: { type: "string", description: `Optional token symbol (e.g. "ZTX", "JMYR") to check its balance for the active network, alongside the usual status fields. Returns { balance, decimals } where balance is in the asset's raw base units \u2014 divide by 10^decimals for the human amount (e.g. balance "473999900" with decimals 6 is 473.9999 JMYR). A failed lookup reports { error: "query_failed" } rather than a zero balance.` }
         }
       }
     },
@@ -22328,9 +22996,36 @@ function buildToolList() {
         required: ["url"]
       }
     },
+    {
+      name: "get_template_schema",
+      description: `Read a VC template's declared attribute schema from chain \u2014 FREE, no payment, no signing, no MBI issuance. Call this BEFORE subscribe_and_issue to find out which attributes a template requires, rather than discovering a missing one by attempting an issuance and being rejected. Accepts a did:zid:... credential-definition id or a known template name (e.g. "AI Birthcert"). Returns { templateId, schema: { required, optional } }; attributes the wallet fills in itself (agentDid, alias-derived keys) are omitted since you never supply them. A template that cannot be read reports { error } rather than an empty schema, so "needs nothing" is never confused with "could not look it up".`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          templateId: {
+            type: "string",
+            description: 'The MBI credential-definition id (did:zid:...) or a known template name, e.g. "AI Birthcert".'
+          }
+        },
+        required: ["templateId"]
+      }
+    },
+    {
+      name: "query_contract",
+      description: 'Read-only query against a Zetrix contract or account \u2014 call an arbitrary contract method (e.g. "balanceOf", "contractInfo") and return its raw result. No signing, no state change.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          contractAddress: { type: "string", description: "Zetrix contract address to query." },
+          method: { type: "string", description: 'Contract method name, e.g. "balanceOf", "contractInfo".' },
+          params: { type: "object", description: 'Method parameters, e.g. { "address": "ZTX..." } for balanceOf.' }
+        },
+        required: ["contractAddress", "method"]
+      }
+    },
     {
       name: "subscribe_and_issue",
-      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.",
+      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. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response except a cache hit also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you see the complete field list, not just what went wrong; a cache hit skips the chain lookup and omits it.",
       inputSchema: {
         type: "object",
         properties: {
@@ -22345,7 +23040,7 @@ function buildToolList() {
           expirationDate: { type: "string" },
           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."
+            description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo }, schema: { required, optional } } without paying or issuing \u2014 use this to check the payment requirement AND the template's full attribute schema (read from chain) before spending funds. Still validates required attributes locally first \u2014 a missing one blocks before any MBI call."
           },
           forceReissue: {
             type: "boolean",
@@ -22388,10 +23083,13 @@ async function main() {
   const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
-  const { zetrixAddress, holderDid, created, didMismatch } = await resolveHolder(
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const { zetrixAddress, holderDid, created, didMismatch, activated } = await resolveHolder(
     {
       createAccount: (password) => be.createAccount(password),
-      signMessage: (message, address, password) => be.signMessage(message, address, password)
+      signMessage: (message, address, password) => be.signMessage(message, address, password),
+      checkActivationStatus: (address) => be.checkActivationStatus(address),
+      sleep
     },
     { zetrixAddress: config2.zetrixAddress, holderDid: config2.holderDid, hsmPassword }
   );
@@ -22410,6 +23108,12 @@ async function main() {
   if (didMismatch) {
     process.stderr.write(
       `agentic-wallet-mcp: configured HOLDER_DID=${config2.holderDid} does not match the account's actual public key \u2014 using the derived HOLDER_DID=${holderDid} instead. Update your MCP config.
+`
+    );
+  }
+  if (created && !activated) {
+    process.stderr.write(
+      `agentic-wallet-mcp: the newly created HSM account (ZETRIX_ADDRESS=${zetrixAddress}) has not completed on-chain activation yet \u2014 balance/on-chain calls for this address may fail until it does.
 `
     );
   }
@@ -22420,6 +23124,20 @@ async function main() {
   const sdk = new import_zetrix_sdk_nodejs.default({ host: config2.nodeHost, port: config2.nodePort });
   const contractQuery = (a) => sdk.contract.call(a);
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
+  const fetchNativeBalance = async (address) => {
+    const res = await sdk.account.getInfo(address);
+    if (res.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res.errorCode}`);
+    const balance = res.result?.balance;
+    if (typeof balance !== "string") throw new Error("getInfo returned no balance");
+    return balance;
+  };
+  const tokenBalanceDeps = {
+    address: zetrixAddress,
+    fetchNativeBalance,
+    resolveTokenAddress: (symbol) => resolveTokenAddress(symbol, config2.network) ?? null,
+    query: contractQuery
+  };
+  const queryTokenBalance2 = (token) => queryTokenBalance(tokenBalanceDeps, token);
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
@@ -22427,7 +23145,10 @@ async function main() {
   const vcCache = createFsVcCache((0, import_node_path3.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);
+    return payWithReadinessCheck(
+      String(accept.asset ?? ""),
+      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn)
+    );
   };
   const payer = async (req) => {
     const init = { method: req.method ?? "GET", headers: req.headers, body: req.body };
@@ -22438,7 +23159,15 @@ async function main() {
     const parsed = await res.json();
     const accept = parsed.accepts?.[0];
     if (!accept) throw new Error("pay_and_fetch: 402 had no accepts[]");
-    const xPayment = await pay(accept);
+    let xPayment;
+    try {
+      xPayment = await pay(accept);
+    } catch (err) {
+      if (err instanceof PaymentReadinessError) {
+        return { status: 402, body: "", paymentMade: false, amountPaid: "", amountPaidHuman: "", asset: "", insufficientFunds: err.shortfall };
+      }
+      throw err;
+    }
     const retry = await fetch(req.url, { ...init, headers: { ...req.headers ?? {}, "x-payment": xPayment } });
     const asset = await resolveSymbol(String(accept.asset ?? ""));
     return {
@@ -22468,8 +23197,12 @@ async function main() {
     makeWallet,
     payer,
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
+    queryContract: (input) => queryContract(input, contractQuery),
+    queryTokenBalance: queryTokenBalance2,
     createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
     saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
+    checkActivationStatus: (address) => be.checkActivationStatus(address),
+    sleep,
     cache: vcCache
   };
   const tools = createTools(deps);