@rozoai/checkout 0.1.23 → 0.1.24

package/scripts/dist/create-order.js

@@ -678,15 +678,27 @@ function buildAttribution({ utmSource, identity } = {}) {
   };
 }
 var INTENTS_BASE = process.env.ROZO_CHECKOUT_INTENTS_BASE || "https://intentapiv4.rozo.ai/functions/v1/payment-api";
-async function quoteInvoice({ url, linkId }) {
+async function quoteInvoice({ url, linkId, beta }) {
   const body = url ? { url } : { payment_id: linkId };
-  return postJson(`${MPP_BASE}/quote-invoice`, body);
+  return postJson(withBeta(`${MPP_BASE}/quote-invoice`, beta), body);
+}
+function withBeta(url, beta) {
+  if (!beta) return url;
+  const u = new URL(url);
+  u.searchParams.set("beta", beta);
+  return u.toString();
 }
 var QUOTE_RECEIPT_RETRY_BUDGET_MS = 2e4;
-async function createInvoice({ url, linkId, source, quoteReceipt, utmSource, email }) {
+async function createInvoice({ url, linkId, source, quoteReceipt, utmSource, email, beta }) {
   const body = {
     ...url ? { url } : { payment_id: linkId },
-    source: { chainId: String(source.chainId), tokenSymbol: source.tokenSymbol },
+    source: {
+      chainId: String(source.chainId),
+      tokenSymbol: source.tokenSymbol,
+      // Shielded ZEC: the router passes this to intents, which hands out a
+      // pool Unified Address instead of a transparent one. Never sent otherwise.
+      ...source.shielded === true ? { shielded: true } : {}
+    },
     ...quoteReceipt ? { quoteReceipt } : {},
     client: CLIENT_LABEL,
     attribution: buildAttribution({ utmSource }),
@@ -695,7 +707,7 @@ async function createInvoice({ url, linkId, source, quoteReceipt, utmSource, ema
     ...email ? { email } : {}
   };
   return postJson(
-    `${MPP_BASE}/create-invoice`,
+    withBeta(`${MPP_BASE}/create-invoice`, beta),
     body,
     quoteReceipt ? { maxTotalWaitMs: QUOTE_RECEIPT_RETRY_BUDGET_MS } : void 0
   );
@@ -740,7 +752,8 @@ var CHAIN_NAMES = {
   42161: "Arbitrum",
   900: "Solana",
   1500: "Stellar",
-  lightning: "Bitcoin Lightning"
+  lightning: "Bitcoin Lightning",
+  9133: "Zcash"
 };
 var CHAIN_FAMILY = {
   1: "evm",
@@ -750,7 +763,9 @@ var CHAIN_FAMILY = {
   42161: "evm",
   900: "solana",
   1500: "stellar",
-  lightning: "lightning"
+  lightning: "lightning",
+  // Zcash: the CLI creates shielded orders only (pool Unified Address); it never signs.
+  9133: "zcash"
 };
 var SUPPORTED_SOURCES = [
   { chainId: "1", chain: "Ethereum", tokens: ["USDC", "USDT", "ETH"] },
@@ -760,7 +775,9 @@ var SUPPORTED_SOURCES = [
   { chainId: "8453", chain: "Base", tokens: ["USDC", "ETH"] },
   { chainId: "42161", chain: "Arbitrum", tokens: ["USDC", "USDT", "ETH"] },
   { chainId: "1500", chain: "Stellar", tokens: ["USDC"] },
-  { chainId: "lightning", chain: "Bitcoin Lightning", tokens: ["BTC"] }
+  { chainId: "lightning", chain: "Bitcoin Lightning", tokens: ["BTC"] },
+  // ZEC (Beta): shielded orders only, offered per invoice by the router (see lib/zec.mjs).
+  { chainId: "9133", chain: "Zcash", tokens: ["ZEC"] }
 ];
 var NATIVE_COINS = Object.freeze({
   "1:ETH": { chainId: "1", symbol: "ETH", decimals: 18 },
@@ -794,7 +811,9 @@ var DECIMALS = {
   "42161:ETH": 18,
   "56:BNB": 18,
   "137:POL": 18,
-  "900:SOL": 9
+  "900:SOL": 9,
+  // Zcash: zatoshi.
+  "9133:ZEC": 8
 };
 var AmountError = class extends Error {
   constructor(code, message) {
@@ -964,7 +983,9 @@ var MARGINS_MS = {
   42161: 10 * MINUTE,
   900: 5 * MINUTE,
   1500: 10 * MINUTE,
-  lightning: 10 * MINUTE
+  lightning: 10 * MINUTE,
+  // Zcash: 75 s blocks, 1 to 2 confirmations, then the hub advances the merchant.
+  9133: 10 * MINUTE
 };
 var BOLT11_MIN_VALIDITY_MS = 10 * MINUTE;
 var DEFAULT_MARGIN_MS = 10 * MINUTE;
@@ -1129,6 +1150,161 @@ function nativeDepositWarnings({ tokenSymbol, chainId }) {
   ];
 }
 
+// scripts/src/lib/zec.mjs
+var ZEC_CHAIN_ID = "9133";
+var ZEC_SYMBOL = "ZEC";
+var ZEC_SOURCE_META_KEY = "ZEC@9133";
+var ZEC_BETA_PARAM = "zec,zec_shielded";
+var ZEC_SHIELDED_MAX_USD = 1200;
+var ZEC_MIN_USD = 5;
+var ZEC_TWO_CONF_FROM_USD = 110;
+var ZEC_PAYIN_STATES = /* @__PURE__ */ new Set(["awaiting", "seen", "confirming", "eligible", "expired", "reorged"]);
+var UA_RE = /^u1[02-9ac-hj-np-z]{100,400}$/;
+function isZecSource(chainId, tokenSymbol) {
+  return String(chainId ?? "").trim() === ZEC_CHAIN_ID && String(tokenSymbol ?? "").trim().toUpperCase() === ZEC_SYMBOL;
+}
+function isUnifiedAddress(value) {
+  return typeof value === "string" && UA_RE.test(value.trim());
+}
+function zecRequiredConfirmations(usd) {
+  const n = Number(usd);
+  return Number.isFinite(n) && n >= ZEC_TWO_CONF_FROM_USD ? 2 : 1;
+}
+function zecShieldedOfferFor({ supportedSources, sourceMeta, callerPaysUsd }) {
+  const list = supportedSources && typeof supportedSources === "object" ? supportedSources[ZEC_CHAIN_ID] : null;
+  if (!Array.isArray(list) || !list.map((t) => String(t).toUpperCase()).includes(ZEC_SYMBOL)) {
+    return {
+      ok: false,
+      code: "ZEC_NOT_OFFERED",
+      reason: "ZEC is not offered for this invoice. Pay with USDC or USDT instead.",
+      requiredConfirmations: null
+    };
+  }
+  const meta = sourceMeta && typeof sourceMeta === "object" ? sourceMeta[ZEC_SOURCE_META_KEY] : null;
+  const available = meta && typeof meta === "object" && (meta.shieldedAvailable === true || meta.shielded_available === true);
+  if (!available) {
+    return {
+      ok: false,
+      code: "ZEC_SHIELDED_NOT_AVAILABLE",
+      reason: "Paying from a shielded balance is not available for this invoice right now.",
+      requiredConfirmations: null
+    };
+  }
+  const usd = Number(callerPaysUsd);
+  if (!Number.isFinite(usd) || usd <= 0) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_UNKNOWN",
+      reason: "The quote carries no USD amount, so the shielded ZEC limits cannot be checked. Pay with USDC or USDT instead.",
+      requiredConfirmations: null
+    };
+  }
+  if (usd > ZEC_SHIELDED_MAX_USD) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_TOO_HIGH",
+      reason: `Shielded ZEC is limited to $${ZEC_SHIELDED_MAX_USD} per payment during the beta; this invoice is $${usd}. Pay with USDC or USDT instead.`,
+      requiredConfirmations: null
+    };
+  }
+  if (usd < ZEC_MIN_USD) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_TOO_LOW",
+      reason: `ZEC payments need an invoice of at least $${ZEC_MIN_USD}; this one is $${usd}. Pay with another coin.`,
+      requiredConfirmations: null
+    };
+  }
+  return { ok: true, code: null, reason: null, requiredConfirmations: zecRequiredConfirmations(usd) };
+}
+function zecStatusOf(source) {
+  const z = source?.zec;
+  if (!z || typeof z !== "object") return null;
+  const receive = z.receive === "shielded" || z.receive === "transparent" ? z.receive : null;
+  const payinState = ZEC_PAYIN_STATES.has(z.payinState) ? z.payinState : null;
+  const confirmations = Number.isInteger(z.confirmations) && z.confirmations >= 0 ? z.confirmations : null;
+  const requiredConfirmations = z.requiredConfirmations === 1 || z.requiredConfirmations === 2 ? z.requiredConfirmations : null;
+  const quoteExpiresAt = typeof z.quoteExpiresAt === "string" && z.quoteExpiresAt ? z.quoteExpiresAt : null;
+  const receivedZat = typeof z.receivedZat === "string" && /^\d+$/.test(z.receivedZat) ? z.receivedZat : null;
+  return { receive, payinState, confirmations, requiredConfirmations, quoteExpiresAt, receivedZat };
+}
+function zecMoneySeen(zec) {
+  if (!zec) return false;
+  if (zec.payinState === "seen" || zec.payinState === "confirming" || zec.payinState === "eligible") return true;
+  if (zec.receivedZat !== null && zec.receivedZat !== "0") return true;
+  if (zec.payinState === null) return true;
+  return false;
+}
+function parsePaymentUri(uri) {
+  if (typeof uri !== "string") return null;
+  const m = /^zcash:([0-9a-z]+)\?([^#]*)$/i.exec(uri.trim());
+  if (!m) return null;
+  const address = m[1];
+  const out = { address, amount: null, memo: null };
+  const seen = /* @__PURE__ */ new Set();
+  for (const part of m[2].split("&")) {
+    if (!part) return null;
+    const eq = part.indexOf("=");
+    if (eq <= 0) return null;
+    const key = part.slice(0, eq);
+    const value = part.slice(eq + 1);
+    if (seen.has(key)) return null;
+    seen.add(key);
+    if (key === "amount") {
+      if (!/^\d+(\.\d{1,8})?$/.test(value)) return null;
+      out.amount = value;
+    } else if (key === "memo") {
+      if (!/^[A-Za-z0-9_-]{1,684}$/.test(value)) return null;
+      out.memo = value;
+    } else {
+      return null;
+    }
+  }
+  if (out.amount === null) return null;
+  return out;
+}
+function sameDecimal(a, b) {
+  const norm = (v) => {
+    const s = String(v ?? "").trim();
+    if (!/^\d+(\.\d+)?$/.test(s)) return null;
+    const [w, f = ""] = s.split(".");
+    const frac = f.replace(/0+$/, "");
+    return `${w.replace(/^0+(?=\d)/, "")}${frac ? `.${frac}` : ""}`;
+  };
+  const na = norm(a);
+  return na !== null && na === norm(b);
+}
+function validateShieldedDeposit(source) {
+  const address = typeof source?.receiverAddress === "string" ? source.receiverAddress.trim() : "";
+  if (!isUnifiedAddress(address)) {
+    return { ok: false, code: "ZEC_ADDRESS_INVALID", reason: "The order did not return a mainnet Unified Address (u1...). Refusing to show it as payable." };
+  }
+  const uri = typeof source?.paymentUri === "string" ? source.paymentUri.trim() : "";
+  if (!uri) {
+    return { ok: false, code: "ZEC_PAYMENT_URI_MISSING", reason: "The order carries no payment URI yet. Nothing is payable until it appears." };
+  }
+  const parsed = parsePaymentUri(uri);
+  if (!parsed) {
+    return { ok: false, code: "ZEC_PAYMENT_URI_INVALID", reason: "The payment URI is not a single-payment ZIP-321 URI. Refusing to show it." };
+  }
+  if (parsed.address !== address) {
+    return { ok: false, code: "ZEC_PAYMENT_URI_MISMATCH", reason: "The payment URI names a different address than the order. Refusing to show it." };
+  }
+  if (!sameDecimal(parsed.amount, source?.amount)) {
+    return { ok: false, code: "ZEC_PAYMENT_URI_MISMATCH", reason: "The payment URI amount differs from the order amount. Refusing to show it." };
+  }
+  return { ok: true, code: null, reason: null, address, paymentUri: uri, memo: parsed.memo };
+}
+function zecDepositWarnings({ requiredConfirmations }) {
+  return [
+    "Pay from a shielded balance, in ONE transaction, exactly the amount shown. The price is locked only until the time shown; after that, do not send, start a new order.",
+    "Underpayments are not refunded automatically: a short payment is held for support, not credited.",
+    `Scan the payment URI (QR content) with a shielded wallet such as Zashi; it carries the address, the amount and the order memo. Do not edit any of them.`,
+    `The merchant is paid after ${requiredConfirmations ?? 1} confirmation${requiredConfirmations === 2 ? "s" : ""} (about 75 seconds each).`,
+    `Beta: up to $${ZEC_SHIELDED_MAX_USD} per payment.`
+  ];
+}
+
 // scripts/src/lib/guards.mjs
 var UNPAID_STATUS = "payment_unpaid";
 function receiptSignal(source) {
@@ -1182,6 +1358,11 @@ function validateDepositInstructions(source) {
       reason: "The live payments response returned no deposit address."
     };
   }
+  if (family === "zcash" && zecStatusOf(source)?.receive === "shielded") {
+    const zec = validateShieldedDeposit(source);
+    if (!zec.ok) return { ok: false, code: zec.code, reason: zec.reason };
+    return { ok: true, code: null, reason: null, family, amountAtomic, payTo: zec.address, memo: null, paymentUri: zec.paymentUri };
+  }
   if (family === "stellar" && !memo) {
     return {
       ok: false,
@@ -1214,13 +1395,14 @@ function reuseGuard({ payment, requested, reused = false }) {
   const hasTx = source.txHash !== null && source.txHash !== void 0 && source.txHash !== "";
   const signal = receiptSignal(source);
   const hasConfirm = source.confirmedAt !== null && source.confirmedAt !== void 0 && source.confirmedAt !== "";
-  if (hasTx || signal.money || hasConfirm) {
+  const zecSeen = isZecSource(source.chainId, source.tokenSymbol) && zecMoneySeen(zecStatusOf(source));
+  if (hasTx || signal.money || hasConfirm || zecSeen) {
     return {
       ok: false,
       code: "ORDER_ALREADY_FUNDED",
-      reason: signal.unparsable ? "This order reports an amountReceived that cannot be read. It is treated as funded until a human confirms otherwise \u2014 do NOT pay again." : "This Coinbase link already has a funded Rozo order (it may have been paid elsewhere). Do NOT pay again \u2014 escalate for manual reconciliation.",
+      reason: signal.unparsable ? "This order reports an amountReceived that cannot be read. It is treated as funded until a human confirms otherwise \u2014 do NOT pay again." : zecSeen && !hasTx && !signal.money && !hasConfirm ? "A shielded ZEC payment to this order has already been seen on the network. Do NOT pay again; watch it with status instead." : "This Coinbase link already has a funded Rozo order (it may have been paid elsewhere). Do NOT pay again \u2014 escalate for manual reconciliation.",
       moneyDetected: true,
-      evidence: { ...evidence, receipt: signal.receipt, receiptUnparsable: signal.unparsable }
+      evidence: { ...evidence, receipt: signal.receipt, receiptUnparsable: signal.unparsable, ...zecSeen ? { zec: zecStatusOf(source) } : {} }
     };
   }
   if (payment?.status !== UNPAID_STATUS) {
@@ -1248,6 +1430,28 @@ function reuseGuard({ payment, requested, reused = false }) {
       evidence
     };
   }
+  if (isZecSource(gotChain, gotToken)) {
+    const zec = zecStatusOf(source);
+    const wantReceive = requested?.shielded === true ? "shielded" : "transparent";
+    if (!zec || zec.receive !== wantReceive) {
+      return {
+        ok: false,
+        code: "ZEC_RECEIVE_MODE_MISMATCH",
+        reason: `This link already has a ZEC order that is paid ${zec?.receive ?? "in an unknown way"}, but you asked for ${wantReceive}. Nothing new was created. Pay that order the way it was made, or wait for it to expire unfunded.`,
+        moneyDetected: false,
+        evidence: { ...evidence, zec }
+      };
+    }
+    if (zec.payinState === "expired" || zec.payinState === "reorged") {
+      return {
+        ok: false,
+        code: "ZEC_QUOTE_EXPIRED",
+        reason: `The ZEC price lock on this order has ${zec.payinState === "reorged" ? "been disturbed by a reorg" : "expired"} with nothing received. Do not pay it; re-run pay to get a fresh order.`,
+        moneyDetected: false,
+        evidence: { ...evidence, zec }
+      };
+    }
+  }
   const deposit = validateDepositInstructions(source);
   if (!deposit.ok) {
     return {
@@ -1555,7 +1759,19 @@ async function main(argv) {
       { supported: SUPPORTED_SOURCES }
     );
   }
-  const requested = { chainId, tokenSymbol };
+  const zec = isZecSource(chainId, tokenSymbol);
+  const shielded = Boolean(args.shielded);
+  if (zec && !shielded) {
+    throw new SkillError(
+      "ZEC_SHIELDED_REQUIRED",
+      "ZEC orders from this CLI pay from a shielded balance: add --shielded. For transparent ZEC use https://checkout.rozo.ai/zec."
+    );
+  }
+  if (shielded && !zec) {
+    throw new SkillError("CONFLICTING_FLAGS", "--shielded only applies to ZEC (--chain 9133 --token ZEC).");
+  }
+  const requested = zec ? { chainId, tokenSymbol, shielded: true } : { chainId, tokenSymbol };
+  const beta = zec ? ZEC_BETA_PARAM : void 0;
   const confirmed = Boolean(args.confirm);
   const email = contactEmailFromArgs(args);
   let blacklist;
@@ -1568,7 +1784,7 @@ async function main(argv) {
     );
   }
   const { linkId: parsedLinkId } = extractLinkId(String(url));
-  const quote = await quoteInvoice({ url: String(url) });
+  const quote = await quoteInvoice({ url: String(url), beta });
   const snapshot = snapshotFromQuote(quote);
   const quoteReceipt = quote?.quoteReceipt ?? null;
   const native = isNativeSource(chainId, tokenSymbol);
@@ -1593,10 +1809,31 @@ async function main(argv) {
       );
     }
   }
+  let zecOffer = null;
+  if (zec) {
+    zecOffer = zecShieldedOfferFor({
+      supportedSources: quote?.supportedSources,
+      sourceMeta: quote?.sourceMeta,
+      callerPaysUsd: snapshot.callerPays ?? snapshot.original
+    });
+    if (!zecOffer.ok) {
+      emit(
+        {
+          success: false,
+          step: "zec-offer",
+          error: { code: zecOffer.code, message: zecOffer.reason },
+          linkId: snapshot.linkId ?? parsedLinkId,
+          guidance: "Nothing was created. Choose USDC or USDT, or another coin the quote lists."
+        },
+        EXIT_ERROR
+      );
+    }
+  }
   const created = await createInvoice({
     url: String(url),
     source: requested,
     quoteReceipt,
+    beta,
     utmSource: typeof args["utm-source"] === "string" ? args["utm-source"] : void 0,
     email
   });
@@ -1606,6 +1843,33 @@ async function main(argv) {
     });
   }
   const rozoPaymentId = assertRozoPaymentId(created.rozoPaymentId);
+  if (zec && (created.sourceMismatch === true || created.sourceMismatchCode === "ZEC_RECEIVE_MODE_MISMATCH")) {
+    const remainingMs = created.expiresAt ? Date.parse(created.expiresAt) - Date.now() : NaN;
+    emit(
+      {
+        success: false,
+        step: "reuse-source-mismatch",
+        error: {
+          code: "ZEC_RECEIVE_MODE_MISMATCH",
+          message: "This link already has an unpaid ZEC order of the other kind (transparent or shielded). Only one order exists per link at a time, so nothing new was created."
+        },
+        linkId: created.linkId ?? parsedLinkId,
+        rozoPaymentId,
+        paymentLink: created.paymentLink ?? null,
+        existingOrder: {
+          rozoPaymentId,
+          chainId: created.source?.chainId ?? null,
+          tokenSymbol: created.source?.tokenSymbol ?? null,
+          receive: created.source?.zec?.receive ?? null,
+          expiresAt: created.expiresAt ?? null,
+          expiresIn: Number.isFinite(remainingMs) ? formatRemaining(remainingMs) : null
+        },
+        nextAction: { type: "choose_method", canRetryQuery: true, canCreateOrder: false, canSend: false, switchPossibleAfter: created.expiresAt ?? null },
+        guidance: "Pay the existing order on https://checkout.rozo.ai/zec with the mode it was made for, or wait for its price lock to expire unfunded (about 30 minutes) and run pay again: an expired, unfunded ZEC order is replaced."
+      },
+      EXIT_ERROR
+    );
+  }
   const verify = verifyCreateAgainstQuote({ snapshot, created, requested });
   if (!verify.ok) {
     const onlySourceDrift = verify.drift.length > 0 && verify.drift.every((d) => d.field.startsWith("source."));
@@ -1685,7 +1949,8 @@ async function main(argv) {
   } catch {
     prior = null;
   }
-  const quoteExpiresAt = priceLockFor({
+  const zecStatus = zec ? zecStatusOf(source) : null;
+  const quoteExpiresAt = zec ? zecStatus?.quoteExpiresAt ?? null : priceLockFor({
     native,
     payment,
     others: [created?.quoteExpiresAt, prior?.quoteExpiresAt, prior?.confirmation?.quoteExpiresAt]
@@ -1699,7 +1964,7 @@ async function main(argv) {
     // separate expiry if the backend exposes one; otherwise the intent expiry
     // governs and we still require the 10-minute floor via the margin.
     ...lightning ? { bolt11ExpiresAt: payment?.expiresAt } : {},
-    ...native ? { quoteExpiresAt } : {}
+    ...native || zec ? { quoteExpiresAt } : {}
   });
   if (!expiry.ok) {
     emit(
@@ -1759,13 +2024,13 @@ async function main(argv) {
     paymentLink: created.paymentLink ?? null,
     merchant: created.merchant ?? snapshot.merchant,
     invoiceAmount: created.original ?? snapshot.original,
-    source: { chainId: source.chainId, tokenSymbol: source.tokenSymbol },
+    source: { chainId: source.chainId, tokenSymbol: source.tokenSymbol, ...zec ? { receive: "shielded" } : {} },
     receiverAddress: source.receiverAddress,
     receiverMemo: source.receiverMemo ?? null,
     amount: source.amount,
     amountUnit: source.amountUnit ?? null,
     expiresAt: payment?.expiresAt ?? null,
-    ...native ? { quoteExpiresAt } : {}
+    ...native || zec ? { quoteExpiresAt } : {}
   });
   const usd = created.original ?? snapshot.original;
   const family = chainFamily(source.chainId);
@@ -1776,10 +2041,10 @@ async function main(argv) {
       source,
       invoiceAmount: usd,
       tier,
-      ...native ? { quoteExpiresAt } : {}
+      ...native || zec ? { quoteExpiresAt } : {}
     });
   }
-  const memoRequirement = lightning ? "Lightning invoices carry their own routing data; there is no separate memo." : source.receiverMemo ? "This deposit REQUIRES the memo/tag below. Sending without it will very likely lose the funds." : family === "stellar" ? "A Stellar deposit always requires a memo." : "This deposit does not use a memo. Leave the memo field empty.";
+  const memoRequirement = lightning ? "Lightning invoices carry their own routing data; there is no separate memo." : zec ? "The order memo is inside the payment URI; scanning it fills the memo for you. Do not type one." : source.receiverMemo ? "This deposit REQUIRES the memo/tag below. Sending without it will very likely lose the funds." : family === "stellar" ? "A Stellar deposit always requires a memo." : "This deposit does not use a memo. Leave the memo field empty.";
   emit({
     success: true,
     step: "create-order",
@@ -1824,8 +2089,16 @@ async function main(argv) {
       // Native coins are exact-out like Lightning: this exact coin amount,
       // at a price locked only until quoteExpiresAt.
       native,
-      exactOut: native || lightning,
-      quoteExpiresAt: native ? quoteExpiresAt : null
+      exactOut: native || lightning || zec,
+      quoteExpiresAt: native || zec ? quoteExpiresAt : null,
+      // Shielded ZEC: what the payer scans. The QR content is the URI,
+      // shown verbatim; it carries the address, the amount and the memo.
+      ...zec ? {
+        shielded: true,
+        paymentUri: depositInfo.paymentUri,
+        requiredConfirmations: zecStatus?.requiredConfirmations ?? zecOffer?.requiredConfirmations ?? null,
+        payinState: zecStatus?.payinState ?? null
+      } : {}
     } : null,
     depositWithheld: !confirmed,
     // Safe for prose / chat.
@@ -1840,14 +2113,15 @@ async function main(argv) {
       memoType: source.receiverMemo ? STELLAR_MEMO_TYPE : null,
       memoRequirement,
       native,
-      priceLockedUntil: native ? quoteExpiresAt : null,
+      priceLockedUntil: native || zec ? quoteExpiresAt : null,
       // The bare decimal amount (not secret), for balance comparisons.
-      coinAmount: isSatsUnit(source.amountUnit) ? null : String(source.amount ?? "")
+      coinAmount: isSatsUnit(source.amountUnit) ? null : String(source.amount ?? ""),
+      ...zec ? { shielded: true, requiredConfirmations: zecStatus?.requiredConfirmations ?? zecOffer?.requiredConfirmations ?? null } : {}
     },
     expiry: {
       intentExpiresAt: payment?.expiresAt ?? null,
       coinbaseExpiry: snapshot?.coinbase?.preApprovalExpiry ?? null,
-      quoteExpiresAt: native ? quoteExpiresAt : null,
+      quoteExpiresAt: native || zec ? quoteExpiresAt : null,
       effectiveDeadlineIso: new Date(expiry.effectiveDeadlineMs).toISOString(),
       // A duration, not just a timestamp: this is what a payer actually needs.
       expiresIn: formatRemaining(expiry.msRemaining),
@@ -1864,7 +2138,8 @@ async function main(argv) {
         memoRequirement,
         "Send exactly once. A second send to the same one-time address is not guaranteed to be credited.",
         "The deposit amount can exceed the invoice: it includes the bridge and network fees.",
-        ...native ? nativeDepositWarnings({ tokenSymbol: source.tokenSymbol, chainId: source.chainId }) : []
+        ...native ? nativeDepositWarnings({ tokenSymbol: source.tokenSymbol, chainId: source.chainId }) : [],
+        ...zec ? zecDepositWarnings({ requiredConfirmations: zecStatus?.requiredConfirmations ?? zecOffer?.requiredConfirmations ?? null }) : []
       ]
     },
     blacklist: {
@@ -1874,7 +2149,7 @@ async function main(argv) {
     },
     nextStep: confirmed ? {
       modeA: "Give the user the `deposit` block, then poll: status.js --rozo-payment-id <id>",
-      modeB: family === "evm" ? `send-evm.js --rozo-payment-id ${rozoPaymentId} --send  (requires ROZO_CHECKOUT_EVM_KEY)` : family === "solana" ? `send-sol.js --rozo-payment-id ${rozoPaymentId} --send  (requires ROZO_CHECKOUT_SOL_KEY)` : "not available for this chain \u2014 pay from a wallet (Mode A)"
+      modeB: family === "evm" ? `send-evm.js --rozo-payment-id ${rozoPaymentId} --send  (requires ROZO_CHECKOUT_EVM_KEY)` : family === "solana" ? `send-sol.js --rozo-payment-id ${rozoPaymentId} --send  (requires ROZO_CHECKOUT_SOL_KEY)` : zec ? "not available: scan deposit.paymentUri with a shielded Zcash wallet (Mode A)" : "not available for this chain \u2014 pay from a wallet (Mode A)"
     } : {
       confirm: "Re-run this exact command with --confirm once the user has said yes."
     }

package/scripts/dist/quote.js

@@ -301,9 +301,15 @@ var MPP_BASE = process.env.ROZO_CHECKOUT_MPP_BASE || "https://apiserver.mpproute
 var CLIENT_LABEL = `rozo-checkout-cli/${PKG_VERSION}`;
 var ATTRIBUTION_CLIENT = `rozo-checkout-skill/${PKG_VERSION}`;
 var INTENTS_BASE = process.env.ROZO_CHECKOUT_INTENTS_BASE || "https://intentapiv4.rozo.ai/functions/v1/payment-api";
-async function quoteInvoice({ url, linkId }) {
+async function quoteInvoice({ url, linkId, beta }) {
   const body = url ? { url } : { payment_id: linkId };
-  return postJson(`${MPP_BASE}/quote-invoice`, body);
+  return postJson(withBeta(`${MPP_BASE}/quote-invoice`, beta), body);
+}
+function withBeta(url, beta) {
+  if (!beta) return url;
+  const u = new URL(url);
+  u.searchParams.set("beta", beta);
+  return u.toString();
 }
 function snapshotFromQuote(quote) {
   const cb = quote?.coinbasePayment || quote?.paymentLink || null;
@@ -333,7 +339,8 @@ var CHAIN_NAMES = {
   42161: "Arbitrum",
   900: "Solana",
   1500: "Stellar",
-  lightning: "Bitcoin Lightning"
+  lightning: "Bitcoin Lightning",
+  9133: "Zcash"
 };
 var SUPPORTED_SOURCES = [
   { chainId: "1", chain: "Ethereum", tokens: ["USDC", "USDT", "ETH"] },
@@ -343,7 +350,9 @@ var SUPPORTED_SOURCES = [
   { chainId: "8453", chain: "Base", tokens: ["USDC", "ETH"] },
   { chainId: "42161", chain: "Arbitrum", tokens: ["USDC", "USDT", "ETH"] },
   { chainId: "1500", chain: "Stellar", tokens: ["USDC"] },
-  { chainId: "lightning", chain: "Bitcoin Lightning", tokens: ["BTC"] }
+  { chainId: "lightning", chain: "Bitcoin Lightning", tokens: ["BTC"] },
+  // ZEC (Beta): shielded orders only, offered per invoice by the router (see lib/zec.mjs).
+  { chainId: "9133", chain: "Zcash", tokens: ["ZEC"] }
 ];
 var NATIVE_COINS = Object.freeze({
   "1:ETH": { chainId: "1", symbol: "ETH", decimals: 18 },
@@ -434,7 +443,9 @@ var MARGINS_MS = {
   42161: 10 * MINUTE,
   900: 5 * MINUTE,
   1500: 10 * MINUTE,
-  lightning: 10 * MINUTE
+  lightning: 10 * MINUTE,
+  // Zcash: 75 s blocks, 1 to 2 confirmations, then the hub advances the merchant.
+  9133: 10 * MINUTE
 };
 var BOLT11_MIN_VALIDITY_MS = 10 * MINUTE;
 var DEFAULT_MARGIN_MS = 10 * MINUTE;
@@ -454,6 +465,69 @@ function parseDeadline(value) {
   return Number.isFinite(t) ? t : null;
 }
 
+// scripts/src/lib/zec.mjs
+var ZEC_CHAIN_ID = "9133";
+var ZEC_SYMBOL = "ZEC";
+var ZEC_SOURCE_META_KEY = "ZEC@9133";
+var ZEC_BETA_PARAM = "zec,zec_shielded";
+var ZEC_SHIELDED_MAX_USD = 1200;
+var ZEC_MIN_USD = 5;
+var ZEC_TWO_CONF_FROM_USD = 110;
+function isZecSource(chainId, tokenSymbol) {
+  return String(chainId ?? "").trim() === ZEC_CHAIN_ID && String(tokenSymbol ?? "").trim().toUpperCase() === ZEC_SYMBOL;
+}
+function zecRequiredConfirmations(usd) {
+  const n = Number(usd);
+  return Number.isFinite(n) && n >= ZEC_TWO_CONF_FROM_USD ? 2 : 1;
+}
+function zecShieldedOfferFor({ supportedSources, sourceMeta, callerPaysUsd }) {
+  const list = supportedSources && typeof supportedSources === "object" ? supportedSources[ZEC_CHAIN_ID] : null;
+  if (!Array.isArray(list) || !list.map((t) => String(t).toUpperCase()).includes(ZEC_SYMBOL)) {
+    return {
+      ok: false,
+      code: "ZEC_NOT_OFFERED",
+      reason: "ZEC is not offered for this invoice. Pay with USDC or USDT instead.",
+      requiredConfirmations: null
+    };
+  }
+  const meta = sourceMeta && typeof sourceMeta === "object" ? sourceMeta[ZEC_SOURCE_META_KEY] : null;
+  const available = meta && typeof meta === "object" && (meta.shieldedAvailable === true || meta.shielded_available === true);
+  if (!available) {
+    return {
+      ok: false,
+      code: "ZEC_SHIELDED_NOT_AVAILABLE",
+      reason: "Paying from a shielded balance is not available for this invoice right now.",
+      requiredConfirmations: null
+    };
+  }
+  const usd = Number(callerPaysUsd);
+  if (!Number.isFinite(usd) || usd <= 0) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_UNKNOWN",
+      reason: "The quote carries no USD amount, so the shielded ZEC limits cannot be checked. Pay with USDC or USDT instead.",
+      requiredConfirmations: null
+    };
+  }
+  if (usd > ZEC_SHIELDED_MAX_USD) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_TOO_HIGH",
+      reason: `Shielded ZEC is limited to $${ZEC_SHIELDED_MAX_USD} per payment during the beta; this invoice is $${usd}. Pay with USDC or USDT instead.`,
+      requiredConfirmations: null
+    };
+  }
+  if (usd < ZEC_MIN_USD) {
+    return {
+      ok: false,
+      code: "ZEC_AMOUNT_TOO_LOW",
+      reason: `ZEC payments need an invoice of at least $${ZEC_MIN_USD}; this one is $${usd}. Pay with another coin.`,
+      requiredConfirmations: null
+    };
+  }
+  return { ok: true, code: null, reason: null, requiredConfirmations: zecRequiredConfirmations(usd) };
+}
+
 // scripts/src/lib/guards.mjs
 function normalizeDecimal(v) {
   if (v === null || v === void 0) return null;
@@ -529,7 +603,7 @@ async function main(argv) {
     chosenSource = { chainId, tokenSymbol };
   }
   const now = Date.now();
-  const quote = await quoteInvoice({ url: String(url) });
+  const quote = await quoteInvoice({ url: String(url), beta: ZEC_BETA_PARAM });
   const snapshot = snapshotFromQuote(quote);
   const payability = derivePayable(snapshot, now);
   const nativeOffered = Object.values(NATIVE_COINS).map((c) => ({
@@ -544,6 +618,20 @@ async function main(argv) {
       callerPaysUsd: snapshot.callerPays ?? snapshot.original
     })
   })).filter((c) => c.offer.ok).map((c) => ({ chainId: c.chainId, tokenSymbol: c.tokenSymbol, chain: c.chain, minUsd: c.offer.minUsd }));
+  const zecOffer = zecShieldedOfferFor({
+    supportedSources: quote?.supportedSources,
+    sourceMeta: quote?.sourceMeta,
+    callerPaysUsd: snapshot.callerPays ?? snapshot.original
+  });
+  const zecShielded = {
+    offered: zecOffer.ok,
+    code: zecOffer.code,
+    reason: zecOffer.reason,
+    requiredConfirmations: zecOffer.requiredConfirmations,
+    maxUsd: ZEC_SHIELDED_MAX_USD,
+    note: "ZEC (Beta) is paid from a shielded wallet, exact amount in one transaction; the CLI shows the address, amount and payment URI and never sends. Underpayments are not refunded automatically."
+  };
+  const zecRequested = chosenSource && isZecSource(chosenSource.chainId, chosenSource.tokenSymbol) ? zecOffer : null;
   const nativeRequested = chosenSource && isNativeSource(chosenSource.chainId, chosenSource.tokenSymbol) ? nativeOfferFor({
     ...chosenSource,
     supportedSources: quote?.supportedSources,
@@ -572,6 +660,7 @@ async function main(argv) {
     // and the native coins it makes payable for this invoice.
     routerSupportedSources: quote?.supportedSources && typeof quote.supportedSources === "object" ? quote.supportedSources : null,
     nativeOffered,
+    zecShielded,
     nativeNote: "Native coins are exact-out: the coin amount is fixed at order creation and its price is locked only until quoteExpiresAt. Up to $3,500 per invoice; native ETH on Ethereum needs $1.",
     quoteReceipt: quote?.quoteReceipt ?? null,
     quoteReceiptTtlSeconds: 60,
@@ -589,6 +678,13 @@ async function main(argv) {
     payload.error = { code: nativeRequested.code, message: nativeRequested.reason };
     emit(payload, EXIT_ERROR);
   }
+  if (zecRequested && !zecRequested.ok) {
+    payload.success = false;
+    payload.nextStep = null;
+    payload.error = { code: zecRequested.code, message: zecRequested.reason };
+    emit(payload, EXIT_ERROR);
+  }
+  if (zecRequested) payload.nextStep = "create-order.js --url <url> --chain 9133 --token ZEC --shielded";
   if (snapshot.callerPays && snapshot.original && normalizeDecimal(snapshot.callerPays) !== normalizeDecimal(snapshot.original)) {
     payload.warnings = [
       `callerPays (${snapshot.callerPays}) differs from the invoice amount (${snapshot.original}). This flow is supposed to charge the full invoice \u2014 do not proceed until that is explained.`