xytara 2.0.0 → 2.2.0

package/lib/settlement_bsv_live.js

@@ -2,17 +2,36 @@
 
 const crypto = require("crypto");
 
+const LIVE_SETTLEMENT_MODE_ALIASES = new Map([
+  ["live", "arc"],
+  ["arc", "arc"],
+  ["observe", "observe"],
+  ["observer", "observe"],
+  ["mock", "mock"]
+]);
+
 function sha256Hex(value) {
   return crypto.createHash("sha256").update(String(value || "")).digest("hex");
 }
 
 function loadBsvSettlementRuntimeConfig() {
-  const mode = String(process.env.XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE || "mock").trim().toLowerCase() || "mock";
+  const modeInput = String(process.env.XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE || "mock").trim().toLowerCase() || "mock";
+  const mode = LIVE_SETTLEMENT_MODE_ALIASES.get(modeInput) || modeInput;
   const requiredConfirmations = Math.max(1, Number(process.env.XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS || 1) || 1);
+  const network = String(process.env.XYTARA_BSV_TERANODE_NETWORK || "mainnet").trim() || "mainnet";
+  const observerNetwork = network === "mainnet" ? "main" : network === "testnet" ? "test" : network;
+  const observerUrl = String(
+    process.env.XYTARA_BSV_TERANODE_OBSERVER_URL
+      || `https://api.whatsonchain.com/v1/bsv/${observerNetwork}`
+  ).trim() || null;
   return {
     mode,
     rpc_url: String(process.env.XYTARA_BSV_TERANODE_RPC_URL || "").trim() || null,
-    network: String(process.env.XYTARA_BSV_TERANODE_NETWORK || "mainnet").trim() || "mainnet",
+    rpc_api_key: String(process.env.XYTARA_BSV_TERANODE_RPC_API_KEY || "").trim() || null,
+    rpc_auth_header: String(process.env.XYTARA_BSV_TERANODE_RPC_AUTH_HEADER || "authorization").trim() || "authorization",
+    rpc_auth_scheme: String(process.env.XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME || "").trim(),
+    observer_url: observerUrl,
+    network,
     required_confirmations: requiredConfirmations
   };
 }
@@ -21,6 +40,140 @@ function clone(value) {
   return JSON.parse(JSON.stringify(value));
 }
 
+function isLiveSettlementRuntimeMode(mode) {
+  return String(mode || "").trim().toLowerCase() !== "mock";
+}
+
+function buildRuntimeAuthHeaders(config) {
+  if (!config || !config.rpc_api_key) return {};
+  const headerName = config.rpc_auth_header || "authorization";
+  const scheme = String(config.rpc_auth_scheme || "").trim();
+  return {
+    [headerName]: scheme ? `${scheme} ${config.rpc_api_key}` : config.rpc_api_key
+  };
+}
+
+function extractSubmittedTransactionId(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  return payload.txid || payload.txId || payload.transactionId || payload.data && payload.data.txid || null;
+}
+
+async function submitArcRawTransaction(config, rawTx) {
+  const response = await fetch(config.rpc_url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...buildRuntimeAuthHeaders(config)
+    },
+    body: JSON.stringify({ rawTx })
+  });
+  const text = await response.text();
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch (_) {
+    parsed = null;
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: "settlement_submit_failed",
+      status: response.status,
+      body: parsed || text || null
+    };
+  }
+  const txid = extractSubmittedTransactionId(parsed);
+  if (!txid) {
+    return {
+      ok: false,
+      reason: "settlement_submit_missing_txid",
+      status: response.status,
+      body: parsed || text || null
+    };
+  }
+  return {
+    ok: true,
+    txid,
+    provider_ref: parsed && typeof parsed === "object" ? parsed.requestId || parsed.request_id || null : null,
+    response: parsed || text || null
+  };
+}
+
+function normalizeArcStatusUrl(config, txid) {
+  const rpcUrl = String(config && config.rpc_url || "").replace(/\/$/, "");
+  if (!rpcUrl) return null;
+  if (rpcUrl.endsWith("/tx")) return `${rpcUrl}/${encodeURIComponent(txid)}`;
+  if (rpcUrl.includes("/tx/")) return rpcUrl;
+  return `${rpcUrl}/tx/${encodeURIComponent(txid)}`;
+}
+
+async function fetchArcTransactionStatus(config, txid) {
+  const statusUrl = normalizeArcStatusUrl(config, txid);
+  if (!statusUrl) {
+    return { ok: false, reason: "settlement_transport_missing" };
+  }
+  const response = await fetch(statusUrl, {
+    headers: buildRuntimeAuthHeaders(config)
+  });
+  const text = await response.text();
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch (_) {
+    parsed = null;
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: response.status === 404 ? "tx_not_found" : "arc_status_failed",
+      status: response.status,
+      body: parsed || text || null
+    };
+  }
+  return {
+    ok: true,
+    payload: parsed || null
+  };
+}
+
+async function fetchObserverTransactionStatus(config, txid) {
+  const observerBaseUrl = String(config && config.observer_url || "").replace(/\/$/, "");
+  if (!observerBaseUrl) {
+    return { ok: false, reason: "settlement_observer_missing" };
+  }
+  const response = await fetch(`${observerBaseUrl}/tx/hash/${encodeURIComponent(txid)}`);
+  const text = await response.text();
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch (_) {
+    parsed = null;
+  }
+  if (!response.ok) {
+    return {
+      ok: false,
+      reason: response.status === 404 ? "tx_not_found" : "observer_status_failed",
+      status: response.status,
+      body: parsed || text || null
+    };
+  }
+  const confirmations = Number(
+    parsed && (
+      parsed.confirmations
+      || parsed.confirmationCount
+      || parsed.confirmation_count
+      || parsed.data && (parsed.data.confirmations || parsed.data.confirmationCount || parsed.data.confirmation_count)
+    )
+  );
+  const blockhash = parsed && (parsed.blockhash || parsed.blockHash || parsed.merkleRoot || parsed.data && (parsed.data.blockhash || parsed.data.blockHash)) || null;
+  return {
+    ok: true,
+    confirmations: Number.isFinite(confirmations) && confirmations >= 0 ? confirmations : 0,
+    blockhash,
+    payload: parsed || null
+  };
+}
+
 function buildSettlementLiveView(record) {
   if (!record) return null;
   return {
@@ -32,6 +185,7 @@ function buildSettlementLiveView(record) {
     rail: record.rail,
     confirmation_count: record.confirmation_count,
     required_confirmations: record.required_confirmations,
+    raw_tx_present: Boolean(record.raw_tx),
     submitted_at_iso: record.submitted_at_iso,
     observed_at_iso: record.observed_at_iso,
     confirmed_at_iso: record.confirmed_at_iso,
@@ -118,7 +272,8 @@ function createBsvSettlementRecord(state, transaction, receipt, paymentRecord) {
     finality_status: "pending_submission",
     confirmation_count: 0,
     required_confirmations: config.required_confirmations,
-    txid: null,
+    txid: transaction.settlement && transaction.settlement.txid ? transaction.settlement.txid : null,
+    raw_tx: transaction.settlement && transaction.settlement.raw_tx ? transaction.settlement.raw_tx : null,
     provider_ref: null,
     settlement_reference:
       transaction.settlement && transaction.settlement.binding_hash
@@ -159,7 +314,7 @@ function getBsvSettlementRecord(state, settlementId) {
   return state.bsvSettlementRecords.get(settlementId) || null;
 }
 
-function submitBsvSettlementRecord(state, settlementId) {
+async function submitBsvSettlementRecord(state, settlementId) {
   const record = getBsvSettlementRecord(state, settlementId);
   if (!record) {
     return { ok: false, reason: "settlement_not_found" };
@@ -167,14 +322,57 @@ function submitBsvSettlementRecord(state, settlementId) {
   if (record.status !== "ready_for_submission" && record.status !== "failed") {
     return { ok: true, settlement: clone(record) };
   }
+  const config = loadBsvSettlementRuntimeConfig();
   const submittedAtIso = new Date().toISOString();
-  const txid = sha256Hex(`${record.settlement_id}:${record.settlement_reference}:${record.network}`).slice(0, 64);
+  if (config.mode === "mock") {
+    const txid = sha256Hex(`${record.settlement_id}:${record.settlement_reference}:${record.network}`).slice(0, 64);
+    const next = {
+      ...record,
+      runtime_mode: config.mode,
+      status: "submitted",
+      finality_status: "submitted",
+      txid,
+      provider_ref: `bsv_teranode_submit_${record.settlement_id}`,
+      submitted_at_iso: submittedAtIso,
+      last_error: null
+    };
+    state.bsvSettlementRecords.set(settlementId, next);
+    updateArtifactsForSettlementRecord(state, next);
+    return { ok: true, settlement: clone(next) };
+  }
+
+  let txid = record.txid || null;
+  let providerRef = record.provider_ref || null;
+  if (!txid && record.raw_tx && config.mode === "arc") {
+    const submitResult = await submitArcRawTransaction(config, record.raw_tx);
+    if (!submitResult.ok) {
+      const failed = {
+        ...record,
+        runtime_mode: config.mode,
+        status: "failed",
+        finality_status: "submission_failed",
+        last_error: submitResult.reason
+      };
+      state.bsvSettlementRecords.set(settlementId, failed);
+      updateArtifactsForSettlementRecord(state, failed);
+      return { ok: false, reason: submitResult.reason, settlement: clone(failed), details: submitResult.body || null };
+    }
+    txid = submitResult.txid;
+    providerRef = submitResult.provider_ref || `arc_submit_${record.settlement_id}`;
+  }
+  if (!txid) {
+    return {
+      ok: false,
+      reason: config.mode === "observe" ? "settlement_txid_missing_for_observe_mode" : "settlement_submission_material_missing"
+    };
+  }
   const next = {
     ...record,
+    runtime_mode: config.mode,
     status: "submitted",
     finality_status: "submitted",
     txid,
-    provider_ref: `bsv_teranode_submit_${record.settlement_id}`,
+    provider_ref: providerRef || `bsv_teranode_submit_${record.settlement_id}`,
     submitted_at_iso: submittedAtIso,
     last_error: null
   };
@@ -183,7 +381,7 @@ function submitBsvSettlementRecord(state, settlementId) {
   return { ok: true, settlement: clone(next) };
 }
 
-function refreshBsvSettlementRecord(state, settlementId) {
+async function refreshBsvSettlementRecord(state, settlementId) {
   const record = getBsvSettlementRecord(state, settlementId);
   if (!record) {
     return { ok: false, reason: "settlement_not_found" };
@@ -191,17 +389,65 @@ function refreshBsvSettlementRecord(state, settlementId) {
   if (!record.txid) {
     return { ok: false, reason: "settlement_not_submitted" };
   }
+  const config = loadBsvSettlementRuntimeConfig();
+  if (config.mode === "mock") {
+    const refreshCount = (record.refresh_count || 0) + 1;
+    const confirmationCount = Math.min(record.required_confirmations + 1, record.confirmation_count + 1);
+    let status = "observed";
+    let finalityStatus = "observed";
+    let observedAtIso = record.observed_at_iso;
+    let confirmedAtIso = record.confirmed_at_iso;
+    let finalizedAtIso = record.finalized_at_iso;
+    const nowIso = new Date().toISOString();
+
+    if (!observedAtIso) observedAtIso = nowIso;
+    if (confirmationCount >= record.required_confirmations) {
+      status = "confirmed";
+      finalityStatus = "confirmed";
+      confirmedAtIso = confirmedAtIso || nowIso;
+    }
+    if (confirmationCount > record.required_confirmations) {
+      status = "finalized";
+      finalityStatus = "finalized";
+      finalizedAtIso = finalizedAtIso || nowIso;
+    }
+
+    const next = {
+      ...record,
+      refresh_count: refreshCount,
+      confirmation_count: confirmationCount,
+      status,
+      finality_status: finalityStatus,
+      observed_at_iso: observedAtIso,
+      confirmed_at_iso: confirmedAtIso,
+      finalized_at_iso: finalizedAtIso
+    };
+    state.bsvSettlementRecords.set(settlementId, next);
+    updateArtifactsForSettlementRecord(state, next);
+    return { ok: true, settlement: clone(next) };
+  }
 
   const refreshCount = (record.refresh_count || 0) + 1;
-  const confirmationCount = Math.min(record.required_confirmations + 1, record.confirmation_count + 1);
-  let status = "observed";
-  let finalityStatus = "observed";
+  let status = "submitted";
+  let finalityStatus = "submitted";
   let observedAtIso = record.observed_at_iso;
   let confirmedAtIso = record.confirmed_at_iso;
   let finalizedAtIso = record.finalized_at_iso;
+  let confirmationCount = Number(record.confirmation_count || 0);
   const nowIso = new Date().toISOString();
 
-  if (!observedAtIso) observedAtIso = nowIso;
+  const arcStatus = config.mode === "arc"
+    ? await fetchArcTransactionStatus(config, record.txid)
+    : { ok: false, reason: "arc_status_not_requested" };
+  const observerStatus = await fetchObserverTransactionStatus(config, record.txid);
+  if (arcStatus.ok || observerStatus.ok) {
+    observedAtIso = observedAtIso || nowIso;
+    status = "observed";
+    finalityStatus = "observed";
+  }
+  if (observerStatus.ok) {
+    confirmationCount = observerStatus.confirmations;
+  }
   if (confirmationCount >= record.required_confirmations) {
     status = "confirmed";
     finalityStatus = "confirmed";
@@ -212,16 +458,19 @@ function refreshBsvSettlementRecord(state, settlementId) {
     finalityStatus = "finalized";
     finalizedAtIso = finalizedAtIso || nowIso;
   }
-
   const next = {
     ...record,
+    runtime_mode: config.mode,
     refresh_count: refreshCount,
     confirmation_count: confirmationCount,
     status,
     finality_status: finalityStatus,
     observed_at_iso: observedAtIso,
     confirmed_at_iso: confirmedAtIso,
-    finalized_at_iso: finalizedAtIso
+    finalized_at_iso: finalizedAtIso,
+    last_error: observerStatus.ok || arcStatus.ok
+      ? null
+      : observerStatus.reason || arcStatus.reason || record.last_error
   };
   state.bsvSettlementRecords.set(settlementId, next);
   updateArtifactsForSettlementRecord(state, next);

package/lib/soft_launch_pack.js

@@ -0,0 +1,78 @@
+"use strict";
+
+const packageJson = require("../package.json");
+
+function buildSoftLaunchPack() {
+  return {
+    ok: true,
+    product: packageJson.name,
+    category: "machine-commerce-soft-launch-pack",
+    message_core: {
+      headline: "governed machine commerce for builders who need paid execution, reusable credits, and proof-aware followthrough",
+      short_pitch: "xytara gives agent builders and tool authors a machine-commerce spine for quote, pay, execute, inspect, and continue into proof without stitching together separate systems.",
+      when_to_lead: [
+        "when an agent or tool needs a paid capability path",
+        "when repeat usage should use funded account balance instead of repeated manual payment",
+        "when execution must stay inspectable and continue cleanly into proof review"
+      ]
+    },
+    first_targets: [
+      {
+        audience_ref: "agent_builder",
+        first_message: "start with one paid machine run and inspect the release center afterward",
+        first_proof_path: "scenario.direct_pay.trust_verify"
+      },
+      {
+        audience_ref: "adapter_author",
+        first_message: "start from the minimal third-party starter and inspect promotion workflow next",
+        first_proof_path: "partner.execution.minimal_echo"
+      },
+      {
+        audience_ref: "tool_or_marketplace_author",
+        first_message: "start with the launch summary and compare xytara against patchwork alternatives",
+        first_proof_path: "scenario.direct_pay.trust_verify"
+      }
+    ],
+    first_artifacts: {
+      release_center: "/v1/release-center/summary",
+      announcement: "/v1/announcement-pack/summary",
+      outreach_proof: "/v1/outreach-proof/summary",
+      adapter_partners: "/v1/adapter-partners/summary",
+      first_cli: "xytara-release --center --summary",
+      first_run_cli: "xytara-run --url https://xytara.onrender.com --account acct_demo --command \"cli-run\" --task trust.verify --body-json '{\"subject_id\":\"subject-1\"}' --wallet-id merchant_wallet_main --wallet-secret YOUR_LOCAL_SIGNED_SECRET --txid YOUR_BSV_TXID"
+    },
+    outreach_sequence: [
+      "send the short pitch and first proof path to a small builder set",
+      "point each audience to the matching first artifact and cli",
+      "watch which first path they actually try",
+      "collect install, wording, and trust-posture confusion",
+      "tighten docs and first-run friction before broader outreach"
+    ],
+    feedback_watchlist: [
+      "install friction",
+      "first-run confusion",
+      "adapter authoring confusion",
+      "promotion trust-model confusion",
+      "difference between direct pay and funded-runtime paths"
+    ]
+  };
+}
+
+function summarizeSoftLaunchPack() {
+  const pack = buildSoftLaunchPack();
+  return {
+    ok: true,
+    product: pack.product,
+    category: pack.category,
+    target_count: pack.first_targets.length,
+    artifact_count: Object.keys(pack.first_artifacts).length,
+    outreach_step_count: pack.outreach_sequence.length,
+    feedback_watch_count: pack.feedback_watchlist.length,
+    first_cli: pack.first_artifacts.first_cli
+  };
+}
+
+module.exports = {
+  buildSoftLaunchPack,
+  summarizeSoftLaunchPack
+};

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "xytara",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Machine commerce SDK for discovery, quoting, execution, lifecycle inspection, and adapters.",
   "main": "index.js",
+  "bin": {
+    "xytara-run": "./bin/xytara-run.js",
+    "xytara-release": "./bin/xytara-release.js"
+  },
   "type": "commonjs",
   "license": "Apache-2.0",
   "homepage": "https://xytara.com",
@@ -33,12 +37,28 @@
     "index.js",
     "client.js",
     "server.js",
+    "bin/",
     "fixtures/",
     "integrations/",
     "lib/",
     "adapters/",
+    "RELEASE_NOTES.md",
+    "RELEASE_CHECKLIST.md",
+    "PUBLISH_PLAN.md",
     ".env.example",
     "README.md",
+    "PROGRAM_STATUS.md",
+    "OPERATOR_START_HERE.md",
+    "OPERATIONS_RUNBOOK.md",
+    "PROGRAM_COMPLETE_RELEASE.md",
+    "WHY_XYTARA_XOONYA.md",
+    "CARRIED_HANDOFF_DEMO.md",
+    "PARTNER_READY_PATH.md",
+    "EXAMPLE_PATHS.md",
+    "PUBLIC_DEMO_SCRIPT.md",
+    "SUPABASE_RUNTIME_STATE_SETUP.md",
+    "ADAPTER_START_HERE.md",
+    "examples/",
     "BSV_TERANODE_SETUP.md",
     "REAL_PAYMENT_SETUP.md",
     "START_HERE.md",
@@ -60,6 +80,8 @@
     "verify:tooling": "node scripts/verify_tooling.js",
     "verify:examples": "node scripts/verify_examples.js",
     "verify:service": "node scripts/verify_service.js",
-    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js"
+    "verify:release-candidate": "node scripts/verify_release_candidate.js",
+    "verify:all": "node scripts/verify_all.js && node scripts/verify_integrations.js && node scripts/verify_adapters.js && node scripts/verify_tooling.js && node scripts/verify_examples.js && node scripts/verify_service.js",
+    "prepublishOnly": "npm run verify:release-candidate"
   }
 }