xytara 3.1.13 → 3.1.14

package/lib/settlement_bsv_live.js

@@ -1,600 +1,600 @@
-"use strict";
-
-const crypto = require("crypto");
-const { buildFetchOptionsForPurpose } = require("./network_transport");
-
-const LIVE_SETTLEMENT_MODE_ALIASES = new Map([
-  ["live", "arc"],
-  ["arc", "arc"],
-  ["observe", "observe"],
-  ["observer", "observe"],
-  ["mock", "mock"]
-]);
-
-function firstEnv(...names) {
-  for (const name of names) {
-    const value = process.env[name];
-    if (typeof value === "string" && value.trim().length > 0) {
-      return value.trim();
-    }
-  }
-  return null;
-}
-
-function sha256Hex(value) {
-  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
-}
-
-function loadBsvSettlementRuntimeConfig() {
-  const modeInput = String(
-    firstEnv(
-      "XYTARA_BSV_SETTLEMENT_RUNTIME_MODE",
-      "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(firstEnv("XYTARA_BSV_REQUIRED_CONFIRMATIONS", "XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS") || 1) || 1
-  );
-  const network = String(firstEnv("XYTARA_BSV_NETWORK", "XYTARA_BSV_TERANODE_NETWORK") || "mainnet").trim() || "mainnet";
-  const observerNetwork = network === "mainnet" ? "main" : network === "testnet" ? "test" : network;
-  const observerUrl = String(
-    firstEnv("XYTARA_BSV_OBSERVER_URL", "XYTARA_BSV_TERANODE_OBSERVER_URL")
-      || `https://api.whatsonchain.com/v1/bsv/${observerNetwork}`
-  ).trim() || null;
-  return {
-    mode,
-    rpc_url: firstEnv("XYTARA_BSV_ARC_RPC_URL", "XYTARA_BSV_ARC_URL", "XYTARA_BSV_TERANODE_RPC_URL"),
-    rpc_api_key: firstEnv("XYTARA_BSV_ARC_RPC_API_KEY", "XYTARA_BSV_ARC_API_KEY", "XYTARA_BSV_TERANODE_RPC_API_KEY"),
-    rpc_auth_header: String(firstEnv("XYTARA_BSV_ARC_RPC_AUTH_HEADER", "XYTARA_BSV_ARC_AUTH_HEADER", "XYTARA_BSV_TERANODE_RPC_AUTH_HEADER") || "authorization").trim() || "authorization",
-    rpc_auth_scheme: String(firstEnv("XYTARA_BSV_ARC_RPC_AUTH_SCHEME", "XYTARA_BSV_ARC_AUTH_SCHEME", "XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME") || "").trim(),
-    observer_url: observerUrl,
-    network,
-    required_confirmations: requiredConfirmations
-  };
-}
-
-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 }),
-    ...buildFetchOptionsForPurpose("settlement")
-  });
-  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),
-    ...buildFetchOptionsForPurpose("settlement")
-  });
-  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)}`, buildFetchOptionsForPurpose("settlement"));
-  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 {
-    settlement_id: record.settlement_id,
-    status: record.status,
-    finality_status: record.finality_status,
-    txid: record.txid,
-    network: record.network,
-    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,
-    finalized_at_iso: record.finalized_at_iso,
-    next_refresh_at_iso: record.next_refresh_at_iso || null,
-    refresh_count: record.refresh_count,
-    runtime_mode: record.runtime_mode
-  };
-}
-
-function updateArtifactsForSettlementRecord(state, record) {
-  if (!record) return;
-  const linked = state.transactions.get(record.transaction_id);
-  if (linked) {
-    const settlementLive = buildSettlementLiveView(record);
-    const verified = record.finality_status === "confirmed" || record.finality_status === "finalized";
-    const transaction = {
-      ...linked.transaction,
-      settlement: {
-        ...(linked.transaction.settlement || {}),
-        status: record.status,
-        verified,
-        txid: record.txid || (linked.transaction.settlement && linked.transaction.settlement.txid) || null,
-        live: settlementLive
-      }
-    };
-    const receipt = {
-      ...linked.receipt,
-      settlement: {
-        ...(linked.receipt.settlement || {}),
-        status: record.status,
-        verified,
-        txid: record.txid || (linked.receipt.settlement && linked.receipt.settlement.txid) || null,
-        live: settlementLive
-      }
-    };
-    const next = {
-      ...linked,
-      transaction,
-      receipt
-    };
-    state.transactions.set(record.transaction_id, next);
-    state.receipts.set(receipt.receipt_id, next);
-  }
-
-  if (Array.isArray(state.paymentLedger)) {
-    state.paymentLedger = state.paymentLedger.map((entry) => {
-      if (!entry || entry.payment_id !== record.payment_id) return entry;
-      return {
-        ...entry,
-        settlement: {
-          ...(entry.settlement || {}),
-          status: record.status,
-          verified: record.finality_status === "confirmed" || record.finality_status === "finalized",
-          txid: record.txid || (entry.settlement && entry.settlement.txid) || null,
-          live: buildSettlementLiveView(record)
-        },
-        live_settlement: buildSettlementLiveView(record)
-      };
-    });
-  }
-}
-
-function createBsvSettlementRecord(state, transaction, receipt, paymentRecord) {
-  if (!transaction || !transaction.settlement || transaction.settlement.rail !== "bsv_teranode") return null;
-  const config = loadBsvSettlementRuntimeConfig();
-  const settlementId = transaction.settlement && transaction.settlement.settlement_id
-    ? transaction.settlement.settlement_id
-    : `settlement_${crypto.randomBytes(6).toString("hex")}`;
-  const existing = state.bsvSettlementRecords.get(settlementId);
-  if (existing) return existing;
-  const record = {
-    settlement_id: settlementId,
-    transaction_id: transaction.transaction_id,
-    receipt_id: receipt && receipt.receipt_id ? receipt.receipt_id : null,
-    payment_id: paymentRecord && paymentRecord.payment_id ? paymentRecord.payment_id : null,
-    account_id: transaction.account_id || null,
-    quote_id: transaction.quote_id || null,
-    amount_minor: transaction.amount_minor,
-    currency: transaction.currency,
-    rail: "bsv_teranode",
-    network: transaction.settlement && transaction.settlement.network ? transaction.settlement.network : config.network,
-    runtime_mode: config.mode,
-    status: "ready_for_submission",
-    finality_status: "pending_submission",
-    confirmation_count: 0,
-    required_confirmations: config.required_confirmations,
-    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
-        ? transaction.settlement.binding_hash
-        : null,
-    merchant_address:
-      transaction.settlement && transaction.settlement.hints
-        ? transaction.settlement.hints.merchant_address || null
-        : null,
-    merchant_paymail:
-      transaction.settlement && transaction.settlement.hints
-        ? transaction.settlement.hints.merchant_paymail || null
-        : null,
-    created_at_iso: new Date().toISOString(),
-    submitted_at_iso: null,
-    observed_at_iso: null,
-    confirmed_at_iso: null,
-    finalized_at_iso: null,
-    next_refresh_at_iso: null,
-    refresh_count: 0,
-    last_error: null
-  };
-  state.bsvSettlementRecords.set(settlementId, record);
-  updateArtifactsForSettlementRecord(state, record);
-  return record;
-}
-
-function listBsvSettlementRecords(state, filters = {}) {
-  const records = Array.from(state.bsvSettlementRecords.values());
-  let items = records;
-  if (filters.status) items = items.filter((item) => item.status === filters.status);
-  if (filters.account_id) items = items.filter((item) => item.account_id === filters.account_id);
-  if (filters.transaction_id) items = items.filter((item) => item.transaction_id === filters.transaction_id);
-  if (filters.payment_id) items = items.filter((item) => item.payment_id === filters.payment_id);
-  return items;
-}
-
-function getBsvSettlementRecord(state, settlementId) {
-  return state.bsvSettlementRecords.get(settlementId) || null;
-}
-
-function normalizeOptionalString(value) {
-  if (typeof value !== "string") return null;
-  const normalized = value.trim();
-  return normalized ? normalized : null;
-}
-
-function normalizeTxid(value) {
-  const txid = normalizeOptionalString(value);
-  if (!txid) return null;
-  const lowered = txid.toLowerCase();
-  return /^[a-f0-9]{64}$/.test(lowered) ? lowered : null;
-}
-
-function normalizeRawTransaction(value) {
-  const rawTx = normalizeOptionalString(value);
-  if (!rawTx) return null;
-  if (rawTx.length < 20 || rawTx.length % 2 !== 0) return null;
-  return /^[a-f0-9]+$/i.test(rawTx) ? rawTx.toLowerCase() : null;
-}
-
-function updateBsvSettlementSubmissionMaterial(state, settlementId, payload = {}) {
-  const body = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
-  const record = getBsvSettlementRecord(state, settlementId);
-  if (!record) {
-    return { ok: false, reason: "settlement_not_found" };
-  }
-  if (record.status !== "ready_for_submission" && record.status !== "failed") {
-    return {
-      ok: false,
-      reason: "settlement_material_update_not_allowed",
-      settlement: clone(record)
-    };
-  }
-
-  const txidInput = body.txid || body.txId || body.transaction_id || body.transactionId;
-  const rawTxInput = body.raw_tx || body.rawTx || body.raw_transaction || body.rawTransaction;
-  const txid = normalizeTxid(txidInput);
-  const rawTx = normalizeRawTransaction(rawTxInput);
-  if (txidInput && !txid) {
-    return { ok: false, reason: "settlement_txid_invalid", settlement: clone(record) };
-  }
-  if (rawTxInput && !rawTx) {
-    return { ok: false, reason: "settlement_raw_tx_invalid", settlement: clone(record) };
-  }
-  if (!txid && !rawTx) {
-    return { ok: false, reason: "settlement_submission_material_required", settlement: clone(record) };
-  }
-
-  const next = {
-    ...record,
-    txid: txid || record.txid || null,
-    raw_tx: rawTx || record.raw_tx || null,
-    provider_ref: normalizeOptionalString(body.provider_ref || body.providerRef) || record.provider_ref || null,
-    network: normalizeOptionalString(body.network) || record.network,
-    runtime_mode: loadBsvSettlementRuntimeConfig().mode,
-    finality_status: "pending_submission",
-    last_error: null,
-    submission_material_updated_at_iso: new Date().toISOString()
-  };
-  state.bsvSettlementRecords.set(settlementId, next);
-  updateArtifactsForSettlementRecord(state, next);
-  return { ok: true, settlement: clone(next) };
-}
-
-async function submitBsvSettlementRecord(state, settlementId) {
-  const record = getBsvSettlementRecord(state, settlementId);
-  if (!record) {
-    return { ok: false, reason: "settlement_not_found" };
-  }
-  if (record.status !== "ready_for_submission" && record.status !== "failed") {
-    return { ok: true, settlement: clone(record) };
-  }
-  const config = loadBsvSettlementRuntimeConfig();
-  const submittedAtIso = new Date().toISOString();
-  const nextRefreshAtIso = new Date(Date.now() + 1500).toISOString();
-  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,
-      next_refresh_at_iso: nextRefreshAtIso,
-      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: providerRef || `bsv_teranode_submit_${record.settlement_id}`,
-    submitted_at_iso: submittedAtIso,
-    next_refresh_at_iso: nextRefreshAtIso,
-    last_error: null
-  };
-  state.bsvSettlementRecords.set(settlementId, next);
-  updateArtifactsForSettlementRecord(state, next);
-  return { ok: true, settlement: clone(next) };
-}
-
-async function refreshBsvSettlementRecord(state, settlementId) {
-  const record = getBsvSettlementRecord(state, settlementId);
-  if (!record) {
-    return { ok: false, reason: "settlement_not_found" };
-  }
-  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,
-      next_refresh_at_iso: status === "finalized" ? null : new Date(Date.now() + 1500).toISOString()
-    };
-    state.bsvSettlementRecords.set(settlementId, next);
-    updateArtifactsForSettlementRecord(state, next);
-    return { ok: true, settlement: clone(next) };
-  }
-
-  const refreshCount = (record.refresh_count || 0) + 1;
-  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();
-
-  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";
-    confirmedAtIso = confirmedAtIso || nowIso;
-  }
-  if (confirmationCount > record.required_confirmations) {
-    status = "finalized";
-    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,
-    next_refresh_at_iso: status === "finalized" ? null : new Date(Date.now() + 1500).toISOString(),
-    last_error: observerStatus.ok || arcStatus.ok
-      ? null
-      : observerStatus.reason || arcStatus.reason || record.last_error
-  };
-  state.bsvSettlementRecords.set(settlementId, next);
-  updateArtifactsForSettlementRecord(state, next);
-  return { ok: true, settlement: clone(next) };
-}
-
-function summarizeBsvSettlementRecords(state) {
-  const records = Array.from(state.bsvSettlementRecords.values());
-  return {
-    settlement_count: records.length,
-    status_counts: records.reduce((acc, item) => {
-      const key = item && item.status ? item.status : "unknown";
-      acc[key] = (acc[key] || 0) + 1;
-      return acc;
-    }, {}),
-    finality_counts: records.reduce((acc, item) => {
-      const key = item && item.finality_status ? item.finality_status : "unknown";
-      acc[key] = (acc[key] || 0) + 1;
-      return acc;
-    }, {})
-  };
-}
-
-module.exports = {
-  buildSettlementLiveView,
-  createBsvSettlementRecord,
-  getBsvSettlementRecord,
-  listBsvSettlementRecords,
-  loadBsvSettlementRuntimeConfig,
-  refreshBsvSettlementRecord,
-  submitBsvSettlementRecord,
-  summarizeBsvSettlementRecords,
-  updateBsvSettlementSubmissionMaterial,
-  updateArtifactsForSettlementRecord
-};
+"use strict";
+
+const crypto = require("crypto");
+const { buildFetchOptionsForPurpose } = require("./network_transport");
+
+const LIVE_SETTLEMENT_MODE_ALIASES = new Map([
+  ["live", "arc"],
+  ["arc", "arc"],
+  ["observe", "observe"],
+  ["observer", "observe"],
+  ["mock", "mock"]
+]);
+
+function firstEnv(...names) {
+  for (const name of names) {
+    const value = process.env[name];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
+function sha256Hex(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function loadBsvSettlementRuntimeConfig() {
+  const modeInput = String(
+    firstEnv(
+      "XYTARA_BSV_SETTLEMENT_RUNTIME_MODE",
+      "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(firstEnv("XYTARA_BSV_REQUIRED_CONFIRMATIONS", "XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS") || 1) || 1
+  );
+  const network = String(firstEnv("XYTARA_BSV_NETWORK", "XYTARA_BSV_TERANODE_NETWORK") || "mainnet").trim() || "mainnet";
+  const observerNetwork = network === "mainnet" ? "main" : network === "testnet" ? "test" : network;
+  const observerUrl = String(
+    firstEnv("XYTARA_BSV_OBSERVER_URL", "XYTARA_BSV_TERANODE_OBSERVER_URL")
+      || `https://api.whatsonchain.com/v1/bsv/${observerNetwork}`
+  ).trim() || null;
+  return {
+    mode,
+    rpc_url: firstEnv("XYTARA_BSV_ARC_RPC_URL", "XYTARA_BSV_ARC_URL", "XYTARA_BSV_TERANODE_RPC_URL"),
+    rpc_api_key: firstEnv("XYTARA_BSV_ARC_RPC_API_KEY", "XYTARA_BSV_ARC_API_KEY", "XYTARA_BSV_TERANODE_RPC_API_KEY"),
+    rpc_auth_header: String(firstEnv("XYTARA_BSV_ARC_RPC_AUTH_HEADER", "XYTARA_BSV_ARC_AUTH_HEADER", "XYTARA_BSV_TERANODE_RPC_AUTH_HEADER") || "authorization").trim() || "authorization",
+    rpc_auth_scheme: String(firstEnv("XYTARA_BSV_ARC_RPC_AUTH_SCHEME", "XYTARA_BSV_ARC_AUTH_SCHEME", "XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME") || "").trim(),
+    observer_url: observerUrl,
+    network,
+    required_confirmations: requiredConfirmations
+  };
+}
+
+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 }),
+    ...buildFetchOptionsForPurpose("settlement")
+  });
+  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),
+    ...buildFetchOptionsForPurpose("settlement")
+  });
+  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)}`, buildFetchOptionsForPurpose("settlement"));
+  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 {
+    settlement_id: record.settlement_id,
+    status: record.status,
+    finality_status: record.finality_status,
+    txid: record.txid,
+    network: record.network,
+    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,
+    finalized_at_iso: record.finalized_at_iso,
+    next_refresh_at_iso: record.next_refresh_at_iso || null,
+    refresh_count: record.refresh_count,
+    runtime_mode: record.runtime_mode
+  };
+}
+
+function updateArtifactsForSettlementRecord(state, record) {
+  if (!record) return;
+  const linked = state.transactions.get(record.transaction_id);
+  if (linked) {
+    const settlementLive = buildSettlementLiveView(record);
+    const verified = record.finality_status === "confirmed" || record.finality_status === "finalized";
+    const transaction = {
+      ...linked.transaction,
+      settlement: {
+        ...(linked.transaction.settlement || {}),
+        status: record.status,
+        verified,
+        txid: record.txid || (linked.transaction.settlement && linked.transaction.settlement.txid) || null,
+        live: settlementLive
+      }
+    };
+    const receipt = {
+      ...linked.receipt,
+      settlement: {
+        ...(linked.receipt.settlement || {}),
+        status: record.status,
+        verified,
+        txid: record.txid || (linked.receipt.settlement && linked.receipt.settlement.txid) || null,
+        live: settlementLive
+      }
+    };
+    const next = {
+      ...linked,
+      transaction,
+      receipt
+    };
+    state.transactions.set(record.transaction_id, next);
+    state.receipts.set(receipt.receipt_id, next);
+  }
+
+  if (Array.isArray(state.paymentLedger)) {
+    state.paymentLedger = state.paymentLedger.map((entry) => {
+      if (!entry || entry.payment_id !== record.payment_id) return entry;
+      return {
+        ...entry,
+        settlement: {
+          ...(entry.settlement || {}),
+          status: record.status,
+          verified: record.finality_status === "confirmed" || record.finality_status === "finalized",
+          txid: record.txid || (entry.settlement && entry.settlement.txid) || null,
+          live: buildSettlementLiveView(record)
+        },
+        live_settlement: buildSettlementLiveView(record)
+      };
+    });
+  }
+}
+
+function createBsvSettlementRecord(state, transaction, receipt, paymentRecord) {
+  if (!transaction || !transaction.settlement || transaction.settlement.rail !== "bsv_teranode") return null;
+  const config = loadBsvSettlementRuntimeConfig();
+  const settlementId = transaction.settlement && transaction.settlement.settlement_id
+    ? transaction.settlement.settlement_id
+    : `settlement_${crypto.randomBytes(6).toString("hex")}`;
+  const existing = state.bsvSettlementRecords.get(settlementId);
+  if (existing) return existing;
+  const record = {
+    settlement_id: settlementId,
+    transaction_id: transaction.transaction_id,
+    receipt_id: receipt && receipt.receipt_id ? receipt.receipt_id : null,
+    payment_id: paymentRecord && paymentRecord.payment_id ? paymentRecord.payment_id : null,
+    account_id: transaction.account_id || null,
+    quote_id: transaction.quote_id || null,
+    amount_minor: transaction.amount_minor,
+    currency: transaction.currency,
+    rail: "bsv_teranode",
+    network: transaction.settlement && transaction.settlement.network ? transaction.settlement.network : config.network,
+    runtime_mode: config.mode,
+    status: "ready_for_submission",
+    finality_status: "pending_submission",
+    confirmation_count: 0,
+    required_confirmations: config.required_confirmations,
+    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
+        ? transaction.settlement.binding_hash
+        : null,
+    merchant_address:
+      transaction.settlement && transaction.settlement.hints
+        ? transaction.settlement.hints.merchant_address || null
+        : null,
+    merchant_paymail:
+      transaction.settlement && transaction.settlement.hints
+        ? transaction.settlement.hints.merchant_paymail || null
+        : null,
+    created_at_iso: new Date().toISOString(),
+    submitted_at_iso: null,
+    observed_at_iso: null,
+    confirmed_at_iso: null,
+    finalized_at_iso: null,
+    next_refresh_at_iso: null,
+    refresh_count: 0,
+    last_error: null
+  };
+  state.bsvSettlementRecords.set(settlementId, record);
+  updateArtifactsForSettlementRecord(state, record);
+  return record;
+}
+
+function listBsvSettlementRecords(state, filters = {}) {
+  const records = Array.from(state.bsvSettlementRecords.values());
+  let items = records;
+  if (filters.status) items = items.filter((item) => item.status === filters.status);
+  if (filters.account_id) items = items.filter((item) => item.account_id === filters.account_id);
+  if (filters.transaction_id) items = items.filter((item) => item.transaction_id === filters.transaction_id);
+  if (filters.payment_id) items = items.filter((item) => item.payment_id === filters.payment_id);
+  return items;
+}
+
+function getBsvSettlementRecord(state, settlementId) {
+  return state.bsvSettlementRecords.get(settlementId) || null;
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+}
+
+function normalizeTxid(value) {
+  const txid = normalizeOptionalString(value);
+  if (!txid) return null;
+  const lowered = txid.toLowerCase();
+  return /^[a-f0-9]{64}$/.test(lowered) ? lowered : null;
+}
+
+function normalizeRawTransaction(value) {
+  const rawTx = normalizeOptionalString(value);
+  if (!rawTx) return null;
+  if (rawTx.length < 20 || rawTx.length % 2 !== 0) return null;
+  return /^[a-f0-9]+$/i.test(rawTx) ? rawTx.toLowerCase() : null;
+}
+
+function updateBsvSettlementSubmissionMaterial(state, settlementId, payload = {}) {
+  const body = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const record = getBsvSettlementRecord(state, settlementId);
+  if (!record) {
+    return { ok: false, reason: "settlement_not_found" };
+  }
+  if (record.status !== "ready_for_submission" && record.status !== "failed") {
+    return {
+      ok: false,
+      reason: "settlement_material_update_not_allowed",
+      settlement: clone(record)
+    };
+  }
+
+  const txidInput = body.txid || body.txId || body.transaction_id || body.transactionId;
+  const rawTxInput = body.raw_tx || body.rawTx || body.raw_transaction || body.rawTransaction;
+  const txid = normalizeTxid(txidInput);
+  const rawTx = normalizeRawTransaction(rawTxInput);
+  if (txidInput && !txid) {
+    return { ok: false, reason: "settlement_txid_invalid", settlement: clone(record) };
+  }
+  if (rawTxInput && !rawTx) {
+    return { ok: false, reason: "settlement_raw_tx_invalid", settlement: clone(record) };
+  }
+  if (!txid && !rawTx) {
+    return { ok: false, reason: "settlement_submission_material_required", settlement: clone(record) };
+  }
+
+  const next = {
+    ...record,
+    txid: txid || record.txid || null,
+    raw_tx: rawTx || record.raw_tx || null,
+    provider_ref: normalizeOptionalString(body.provider_ref || body.providerRef) || record.provider_ref || null,
+    network: normalizeOptionalString(body.network) || record.network,
+    runtime_mode: loadBsvSettlementRuntimeConfig().mode,
+    finality_status: "pending_submission",
+    last_error: null,
+    submission_material_updated_at_iso: new Date().toISOString()
+  };
+  state.bsvSettlementRecords.set(settlementId, next);
+  updateArtifactsForSettlementRecord(state, next);
+  return { ok: true, settlement: clone(next) };
+}
+
+async function submitBsvSettlementRecord(state, settlementId) {
+  const record = getBsvSettlementRecord(state, settlementId);
+  if (!record) {
+    return { ok: false, reason: "settlement_not_found" };
+  }
+  if (record.status !== "ready_for_submission" && record.status !== "failed") {
+    return { ok: true, settlement: clone(record) };
+  }
+  const config = loadBsvSettlementRuntimeConfig();
+  const submittedAtIso = new Date().toISOString();
+  const nextRefreshAtIso = new Date(Date.now() + 1500).toISOString();
+  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,
+      next_refresh_at_iso: nextRefreshAtIso,
+      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: providerRef || `bsv_teranode_submit_${record.settlement_id}`,
+    submitted_at_iso: submittedAtIso,
+    next_refresh_at_iso: nextRefreshAtIso,
+    last_error: null
+  };
+  state.bsvSettlementRecords.set(settlementId, next);
+  updateArtifactsForSettlementRecord(state, next);
+  return { ok: true, settlement: clone(next) };
+}
+
+async function refreshBsvSettlementRecord(state, settlementId) {
+  const record = getBsvSettlementRecord(state, settlementId);
+  if (!record) {
+    return { ok: false, reason: "settlement_not_found" };
+  }
+  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,
+      next_refresh_at_iso: status === "finalized" ? null : new Date(Date.now() + 1500).toISOString()
+    };
+    state.bsvSettlementRecords.set(settlementId, next);
+    updateArtifactsForSettlementRecord(state, next);
+    return { ok: true, settlement: clone(next) };
+  }
+
+  const refreshCount = (record.refresh_count || 0) + 1;
+  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();
+
+  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";
+    confirmedAtIso = confirmedAtIso || nowIso;
+  }
+  if (confirmationCount > record.required_confirmations) {
+    status = "finalized";
+    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,
+    next_refresh_at_iso: status === "finalized" ? null : new Date(Date.now() + 1500).toISOString(),
+    last_error: observerStatus.ok || arcStatus.ok
+      ? null
+      : observerStatus.reason || arcStatus.reason || record.last_error
+  };
+  state.bsvSettlementRecords.set(settlementId, next);
+  updateArtifactsForSettlementRecord(state, next);
+  return { ok: true, settlement: clone(next) };
+}
+
+function summarizeBsvSettlementRecords(state) {
+  const records = Array.from(state.bsvSettlementRecords.values());
+  return {
+    settlement_count: records.length,
+    status_counts: records.reduce((acc, item) => {
+      const key = item && item.status ? item.status : "unknown";
+      acc[key] = (acc[key] || 0) + 1;
+      return acc;
+    }, {}),
+    finality_counts: records.reduce((acc, item) => {
+      const key = item && item.finality_status ? item.finality_status : "unknown";
+      acc[key] = (acc[key] || 0) + 1;
+      return acc;
+    }, {})
+  };
+}
+
+module.exports = {
+  buildSettlementLiveView,
+  createBsvSettlementRecord,
+  getBsvSettlementRecord,
+  listBsvSettlementRecords,
+  loadBsvSettlementRuntimeConfig,
+  refreshBsvSettlementRecord,
+  submitBsvSettlementRecord,
+  summarizeBsvSettlementRecords,
+  updateBsvSettlementSubmissionMaterial,
+  updateArtifactsForSettlementRecord
+};