xytara 2.5.0 → 2.6.0

package/lib/treasury_destinations_contract.js

@@ -0,0 +1,543 @@
+"use strict";
+
+const { buildConfiguredTreasuryDestination, loadPaymentConfig } = require("./payment_config");
+const {
+  buildBsvTeranodeTreasuryDestination,
+  loadBsvTeranodeConfig
+} = require("./settlement_bsv_teranode");
+
+const RAIL_PROFILES = [
+  {
+    rail_id: "bsv_teranode",
+    settlement_mode: "bsv_teranode",
+    reserve_role: "strategic_native_treasury",
+    compliance_posture: "public_native_treasury_identity_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref"],
+    recommended_fields: ["network", "custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_bsv_main",
+      destination_kind: "bsv_teranode_address",
+      external_ref: "1ExampleMerchantAddress",
+      custody_ref: "vault.bsv.primary",
+      reporting_ref: "ledger.bsv.primary",
+      wallet_ref: "wallet.bsv.primary",
+      provider_ref: "arc.bsv.primary",
+      network: "mainnet",
+      storage_class: "cold_primary"
+    }
+  },
+  {
+    rail_id: "evm",
+    settlement_mode: "evm",
+    reserve_role: "canonical_contract_settlement",
+    compliance_posture: "public_settlement_destination_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "chain_id"],
+    recommended_fields: ["custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_evm_main",
+      destination_kind: "evm_address",
+      external_ref: "0xTreasuryAddress",
+      chain_id: "1",
+      custody_ref: "vault.evm.primary",
+      reporting_ref: "ledger.evm.primary",
+      provider_ref: "rpc.evm.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "base",
+    settlement_mode: "base",
+    reserve_role: "canonical_low-friction_evm_settlement",
+    compliance_posture: "public_settlement_destination_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "chain_id"],
+    recommended_fields: ["custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_base_main",
+      destination_kind: "evm_address",
+      external_ref: "0xBaseTreasuryAddress",
+      chain_id: "8453",
+      custody_ref: "vault.base.primary",
+      reporting_ref: "ledger.base.primary",
+      provider_ref: "rpc.base.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "solana_payment",
+    settlement_mode: "solana_payment",
+    reserve_role: "major_alternative_rail_settlement",
+    compliance_posture: "public_settlement_destination_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "network"],
+    recommended_fields: ["custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "asset_symbol", "storage_class"],
+    config_template: {
+      destination_id: "treasury_solana_main",
+      destination_kind: "solana_address",
+      external_ref: "ExampleSolanaTreasuryAddress",
+      network: "mainnet-beta",
+      asset_symbol: "SOL_OR_SPL",
+      custody_ref: "vault.solana.primary",
+      reporting_ref: "ledger.solana.primary",
+      wallet_ref: "wallet.solana.primary",
+      provider_ref: "rpc.solana.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "xpr_payment",
+    settlement_mode: "xpr_payment",
+    reserve_role: "major_alternative_rail_settlement",
+    compliance_posture: "public_settlement_destination_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "network"],
+    recommended_fields: ["custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "asset_symbol", "storage_class"],
+    config_template: {
+      destination_id: "treasury_xpr_main",
+      destination_kind: "proton_xpr_account",
+      external_ref: "examplexpracct",
+      network: "mainnet",
+      asset_symbol: "XPR",
+      custody_ref: "vault.xpr.primary",
+      reporting_ref: "ledger.xpr.primary",
+      wallet_ref: "wallet.xpr.primary",
+      provider_ref: "rpc.xpr.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "antelope_payment",
+    settlement_mode: "antelope_payment",
+    reserve_role: "major_alternative_rail_settlement",
+    compliance_posture: "public_settlement_destination_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "network"],
+    recommended_fields: ["custody_ref", "reporting_ref", "wallet_ref", "provider_ref", "asset_symbol", "storage_class"],
+    config_template: {
+      destination_id: "treasury_antelope_main",
+      destination_kind: "antelope_account",
+      external_ref: "exampleeosacct",
+      network: "mainnet",
+      asset_symbol: "EOSIO_OR_ANTILOPE",
+      custody_ref: "vault.antelope.primary",
+      reporting_ref: "ledger.antelope.primary",
+      wallet_ref: "wallet.antelope.primary",
+      provider_ref: "rpc.antelope.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "usdc",
+    settlement_mode: "usdc",
+    reserve_role: "stable_operating_reserve",
+    compliance_posture: "public_stable_reserve_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "asset_symbol"],
+    recommended_fields: ["chain_id", "custody_ref", "reporting_ref", "wallet_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_usdc_primary",
+      destination_kind: "stablecoin_address",
+      external_ref: "0xUsdcTreasuryAddress",
+      asset_symbol: "USDC",
+      chain_id: "8453",
+      custody_ref: "vault.usdc.primary",
+      reporting_ref: "ledger.usdc.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "dai",
+    settlement_mode: "dai",
+    reserve_role: "stable_operating_reserve",
+    compliance_posture: "public_stable_reserve_allowed",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "asset_symbol"],
+    recommended_fields: ["chain_id", "custody_ref", "reporting_ref", "wallet_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_dai_primary",
+      destination_kind: "stablecoin_address",
+      external_ref: "0xDaiTreasuryAddress",
+      asset_symbol: "DAI",
+      chain_id: "1",
+      custody_ref: "vault.dai.primary",
+      reporting_ref: "ledger.dai.primary",
+      storage_class: "warm_operational"
+    }
+  },
+  {
+    rail_id: "monero",
+    settlement_mode: "monero",
+    reserve_role: "optional_hidden_privacy_reserve",
+    compliance_posture: "internal_only_policy_gated",
+    required_fields: ["destination_id", "destination_kind", "external_ref", "policy_scope"],
+    recommended_fields: ["custody_ref", "reporting_ref", "storage_class"],
+    config_template: {
+      destination_id: "treasury_monero_private",
+      destination_kind: "monero_address",
+      external_ref: "8ExampleMoneroAddress",
+      policy_scope: "internal_optional_privacy_reserve",
+      custody_ref: "vault.monero.policy_gated",
+      reporting_ref: "ledger.monero.internal",
+      storage_class: "isolated_policy_gated"
+    }
+  }
+];
+
+function classifyDestinationSource(profile, paymentConfig) {
+  const settlementMode = profile.settlement_mode;
+  const mapEntry = paymentConfig.treasury_destinations_by_settlement_mode[settlementMode];
+  if (mapEntry && mapEntry.destination_id) {
+    return "per_settlement_mode";
+  }
+  if (settlementMode === "bsv_teranode" && buildBsvTeranodeTreasuryDestination("acct_treasury_operator", settlementMode)) {
+    return "bsv_merchant_destination";
+  }
+  if (paymentConfig.treasury_destination_id) {
+    return "global_default";
+  }
+  return "unconfigured";
+}
+
+function buildFieldValueMap(destination, bsvConfig) {
+  return {
+    destination_id: destination && destination.destination_id ? destination.destination_id : null,
+    destination_kind: destination && destination.destination_kind ? destination.destination_kind : null,
+    external_ref: destination && destination.external_ref ? destination.external_ref : null,
+    custody_ref: destination && destination.custody_ref ? destination.custody_ref : null,
+    reporting_ref: destination && destination.reporting_ref ? destination.reporting_ref : null,
+    wallet_ref: destination && destination.wallet_ref ? destination.wallet_ref : null,
+    provider_ref: destination && destination.provider_ref ? destination.provider_ref : null,
+    network: destination && destination.network ? destination.network : (bsvConfig && bsvConfig.network ? bsvConfig.network : null),
+    chain_id: destination && destination.chain_id ? destination.chain_id : null,
+    asset_symbol: destination && destination.asset_symbol ? destination.asset_symbol : null,
+    policy_scope: destination && destination.policy_scope ? destination.policy_scope : null,
+    storage_class: destination && destination.storage_class ? destination.storage_class : null
+  };
+}
+
+function listMissingFields(fieldNames, values) {
+  return fieldNames.filter((fieldName) => !values[fieldName]);
+}
+
+function buildReadinessState(source, requiredMissingFields) {
+  if (source === "per_settlement_mode" && requiredMissingFields.length === 0) {
+    return "explicit_per-rail_ready";
+  }
+  if (source === "bsv_merchant_destination" && requiredMissingFields.length === 0) {
+    return "native_bsv_ready";
+  }
+  if (source === "global_default" && requiredMissingFields.length === 0) {
+    return "fallback_only_not_explicitly_per-rail";
+  }
+  if (source === "unconfigured") {
+    return "unconfigured";
+  }
+  return "partially_configured";
+}
+
+function buildClaimDiscipline(profile, source, readinessState, configured, missingRecommendedFields) {
+  const internalOnly = profile.compliance_posture === "internal_only_policy_gated";
+  const reportingGaps = Array.isArray(missingRecommendedFields) && missingRecommendedFields.length > 0;
+  let publicClaimStatus = "readiness_template_only";
+  if (internalOnly) {
+    publicClaimStatus = "internal_policy_gated_not_public";
+  } else if (configured && reportingGaps) {
+    publicClaimStatus = "live_landing_path_with_operator_reporting_gaps";
+  } else if (configured) {
+    publicClaimStatus = "live_operational_landing_path";
+  } else if (source === "global_default") {
+    publicClaimStatus = "fallback_not_public_multi-rail_claim";
+  } else if (readinessState === "partially_configured") {
+    publicClaimStatus = "partial_configuration_not_public_claim";
+  }
+
+  const publicClaimAllowed = !internalOnly && configured;
+  return {
+    public_claim_status: publicClaimStatus,
+    public_claim_allowed: publicClaimAllowed,
+    operator_claim_allowed: configured,
+    launch_claim_role: profile.rail_id === "bsv_teranode"
+      ? "launch_primary_native_settlement"
+      : internalOnly
+        ? "internal_optional_reserve"
+        : "future_or_optional_rail",
+    claim_guidance: publicClaimAllowed
+      ? reportingGaps
+        ? "can_claim_as_configured_with_operator_reporting_gaps_disclosed"
+        : "can_claim_as_configured_live_landing_path"
+      : internalOnly
+        ? "do_not_make_public_landing_claim"
+        : "keep_as_supported_architecture_or_readiness_template_until_real_destination_is_configured",
+    reporting_gap_fields: reportingGaps ? missingRecommendedFields : []
+  };
+}
+
+function buildOperatorNextSteps(requiredMissingFields, recommendedMissingFields, claimDiscipline) {
+  const steps = [];
+  if (requiredMissingFields.length > 0) {
+    steps.push("fill_missing_required_destination_fields_before_any_live_claim");
+  }
+  if (claimDiscipline.public_claim_status === "fallback_not_public_multi-rail_claim") {
+    steps.push("replace_global_fallback_with_per-rail_destination_before_public_multi-rail_claim");
+  }
+  if (claimDiscipline.public_claim_status === "internal_policy_gated_not_public") {
+    steps.push("keep_internal_only_and_policy_gated");
+  }
+  if (recommendedMissingFields.length > 0) {
+    steps.push("add_recommended_custody_reporting_wallet_provider_or_storage_refs");
+  }
+  return steps.length ? steps : ["keep_destination_under_periodic_operator_review"];
+}
+
+function buildTreasuryDestinationProfile(profile) {
+  const paymentConfig = loadPaymentConfig();
+  const destination = buildConfiguredTreasuryDestination("acct_treasury_operator", profile.settlement_mode);
+  const source = classifyDestinationSource(profile, paymentConfig);
+  const bsvConfig = profile.settlement_mode === "bsv_teranode" ? loadBsvTeranodeConfig() : null;
+  const fieldValues = buildFieldValueMap(destination, bsvConfig);
+  const requiredMissingFields = listMissingFields(profile.required_fields, fieldValues);
+  const recommendedMissingFields = listMissingFields(profile.recommended_fields, fieldValues);
+  const readinessState = buildReadinessState(source, requiredMissingFields);
+  const configured = readinessState === "explicit_per-rail_ready" || readinessState === "native_bsv_ready";
+  const claimDiscipline = buildClaimDiscipline(profile, source, readinessState, configured, recommendedMissingFields);
+  return {
+    rail_id: profile.rail_id,
+    settlement_mode: profile.settlement_mode,
+    reserve_role: profile.reserve_role,
+    compliance_posture: profile.compliance_posture,
+    configured,
+    configuration_source: source,
+    readiness_state: readinessState,
+    public_claim_status: claimDiscipline.public_claim_status,
+    public_claim_allowed: claimDiscipline.public_claim_allowed,
+    operator_claim_allowed: claimDiscipline.operator_claim_allowed,
+    launch_claim_role: claimDiscipline.launch_claim_role,
+    claim_guidance: claimDiscipline.claim_guidance,
+    reporting_gap_fields: claimDiscipline.reporting_gap_fields,
+    explicit_per_rail_configured: source === "per_settlement_mode" && requiredMissingFields.length === 0,
+    field_requirements: {
+      required_fields: profile.required_fields,
+      recommended_fields: profile.recommended_fields,
+      missing_required_fields: requiredMissingFields,
+      missing_recommended_fields: recommendedMissingFields
+    },
+    custody_destination: destination && destination.destination_id ? {
+      destination_id: destination.destination_id,
+      destination_kind: destination.destination_kind,
+      account_id: destination.account_id,
+      external_ref: destination.external_ref || null,
+      custody_ref: destination.custody_ref || null,
+      reporting_ref: destination.reporting_ref || null,
+      wallet_ref: destination.wallet_ref || null,
+      provider_ref: destination.provider_ref || null,
+      network: destination.network || null,
+      chain_id: destination.chain_id || null,
+      asset_symbol: destination.asset_symbol || null,
+      policy_scope: destination.policy_scope || null,
+      storage_class: destination.storage_class || null
+    } : null,
+    runtime_claim_readiness: configured
+      ? "operational_claim_ready"
+      : source === "global_default"
+        ? "fallback_present_but_do_not_claim_explicit_multi-rail_landing_yet"
+        : "do_not_claim_as_live_landing_destination_yet",
+    operator_next_steps: buildOperatorNextSteps(requiredMissingFields, recommendedMissingFields, claimDiscipline),
+    config_template: profile.config_template,
+    rail_metadata: bsvConfig ? {
+      network: bsvConfig.network,
+      merchant_address: bsvConfig.merchant_address,
+      merchant_paymail: bsvConfig.merchant_paymail
+    } : null,
+    guardrails: profile.rail_id === "monero"
+      ? [
+        "internal_only",
+        "not_public_treasury_identity",
+        "must_not_weaken_reporting_or_accounting_surfaces",
+        "policy_scope_must_be_explicit_before_operational_use"
+      ]
+      : [
+        "treasury_visibility_must_flow_back_into_xytara_ledger_and_reporting",
+        "custody_destination_should_be_secure_before_operational_claims_are_made",
+        "per-rail_config_is_preferred_over_global_fallback_for_public_operational_claims"
+      ]
+  };
+}
+
+function sanitizeTreasuryDestinationProfile(profile) {
+  return {
+    rail_id: profile.rail_id,
+    settlement_mode: profile.settlement_mode,
+    reserve_role: profile.reserve_role,
+    compliance_posture: profile.compliance_posture,
+    configured: profile.configured,
+    configuration_source: profile.configuration_source,
+    readiness_state: profile.readiness_state,
+    public_claim_status: profile.public_claim_status,
+    public_claim_allowed: profile.public_claim_allowed,
+    launch_claim_role: profile.launch_claim_role,
+    claim_guidance: profile.claim_guidance,
+    reporting_gap_fields: profile.reporting_gap_fields,
+    explicit_per_rail_configured: profile.explicit_per_rail_configured,
+    field_requirements: profile.field_requirements,
+    destination_visibility: {
+      destination_kind: profile.custody_destination ? profile.custody_destination.destination_kind : null,
+      network: profile.custody_destination ? profile.custody_destination.network : null,
+      chain_id: profile.custody_destination ? profile.custody_destination.chain_id : null,
+      asset_symbol: profile.custody_destination ? profile.custody_destination.asset_symbol : null,
+      policy_scope: profile.custody_destination ? profile.custody_destination.policy_scope : null,
+      storage_class: profile.custody_destination ? profile.custody_destination.storage_class : null
+    },
+    runtime_claim_readiness: profile.runtime_claim_readiness,
+    config_template: profile.config_template,
+    guardrails: profile.guardrails
+  };
+}
+
+function buildOperatorTreasuryDestinationsPack() {
+  const profiles = RAIL_PROFILES.map(buildTreasuryDestinationProfile);
+  const configuredProfiles = profiles.filter((entry) => entry.configured);
+  const explicitProfiles = profiles.filter((entry) => entry.explicit_per_rail_configured);
+  const publicClaimableProfiles = profiles.filter((entry) => entry.public_claim_allowed);
+  const internalOnlyProfiles = profiles.filter((entry) => entry.compliance_posture === "internal_only_policy_gated");
+  return {
+    product: "xytara",
+    category: "machine-commerce-operator-treasury-destinations-pack",
+    pack_version: "xytara-operator-treasury-destinations-pack-v1",
+    posture: "operator_only_custody_visibility_and_per-rail_destination_readiness",
+    profiles,
+    readiness_summary: {
+      explicit_per_rail_configured_count: explicitProfiles.length,
+      configured_profile_count: configuredProfiles.length,
+      public_claimable_profile_count: publicClaimableProfiles.length,
+      readiness_only_profile_count: profiles.filter((entry) => !entry.public_claim_allowed && entry.compliance_posture !== "internal_only_policy_gated").length,
+      internal_only_profile_count: internalOnlyProfiles.length,
+      reporting_gap_count: profiles.filter((entry) => Array.isArray(entry.reporting_gap_fields) && entry.reporting_gap_fields.length > 0).length,
+      fallback_only_count: profiles.filter((entry) => entry.readiness_state === "fallback_only_not_explicitly_per-rail").length,
+      partially_configured_count: profiles.filter((entry) => entry.readiness_state === "partially_configured").length,
+      unconfigured_count: profiles.filter((entry) => entry.readiness_state === "unconfigured").length
+    },
+    public_claim_boundary: {
+      live_claimable_rails: publicClaimableProfiles.map((entry) => entry.rail_id),
+      readiness_only_rails: profiles
+        .filter((entry) => !entry.public_claim_allowed && entry.compliance_posture !== "internal_only_policy_gated")
+        .map((entry) => entry.rail_id),
+      internal_only_rails: internalOnlyProfiles.map((entry) => entry.rail_id),
+      rule: "only_rails_with_public_claim_allowed_true_should_be_described_as_live_landing_paths"
+    },
+    supported_surfaces: {
+      treasury_lane_ref: "/v1/treasury",
+      treasury_summary_ref_template: "/v1/economics/accounts/:account_id/treasury-summary",
+      treasury_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/treasury-signoff-pack",
+      rail_summary_ref_template: "/v1/economics/accounts/:account_id/rail-summary",
+      rail_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/rail-signoff-pack",
+      payment_setup_doc_ref: "REAL_PAYMENT_SETUP.md",
+      native_setup_doc_ref: "BSV_TERANODE_SETUP.md",
+      validation_preview_ref: "/v1/treasury-destinations/validate-preview"
+    },
+    operator_rule: configuredProfiles.length > 0
+      ? "claim_only_the_rails_with_real_configured_destinations_as_live_landing_paths"
+      : "no_multi-rail_operational_claims_until_real_destinations_exist",
+    custody_visibility_rule: "do_not_expose_real_external_refs_or_custody_refs_on_public_surfaces",
+    config_examples: Object.fromEntries(RAIL_PROFILES.map((profile) => [profile.settlement_mode, profile.config_template]))
+  };
+}
+
+function buildTreasuryDestinationsPack() {
+  const operatorPack = buildOperatorTreasuryDestinationsPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-destinations-pack",
+    pack_version: "xytara-treasury-destinations-pack-v3",
+    posture: "public_treasury_destination_readiness_without_custody_refs",
+    profiles: operatorPack.profiles.map(sanitizeTreasuryDestinationProfile),
+    readiness_summary: operatorPack.readiness_summary,
+    public_claim_boundary: operatorPack.public_claim_boundary,
+    supported_surfaces: {
+      treasury_lane_ref: "/v1/treasury",
+      treasury_summary_ref_template: "/v1/economics/accounts/:account_id/treasury-summary",
+      rail_summary_ref_template: "/v1/economics/accounts/:account_id/rail-summary",
+      payment_setup_doc_ref: "REAL_PAYMENT_SETUP.md",
+      native_setup_doc_ref: "BSV_TERANODE_SETUP.md",
+      validation_preview_ref: "/v1/treasury-destinations/validate-preview",
+      operator_pack_ref: "/v1/treasury-destinations/operator-pack"
+    },
+    operator_rule: operatorPack.operator_rule,
+    claim_discipline_rule: "unsupported_or_unconfigured_rails_may_be_listed_as_architecture_but_not_as_live_landing_paths",
+    privacy_rule: "public_surfaces_must_not_expose_real_treasury_landing_refs_or_custody_provider_refs",
+    config_examples: operatorPack.config_examples
+  };
+}
+
+function summarizeTreasuryDestinationsPack() {
+  const pack = buildTreasuryDestinationsPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-destinations-pack-summary",
+    summary_version: "xytara-treasury-destinations-pack-summary-v2",
+    profile_count: pack.profiles.length,
+    configured_profile_count: pack.profiles.filter((entry) => entry.configured).length,
+    explicit_per_rail_configured_count: pack.readiness_summary.explicit_per_rail_configured_count,
+    public_claimable_profile_count: pack.readiness_summary.public_claimable_profile_count,
+    readiness_only_profile_count: pack.readiness_summary.readiness_only_profile_count,
+    reporting_gap_count: pack.readiness_summary.reporting_gap_count,
+    internal_only_profile_count: pack.profiles.filter((entry) => entry.compliance_posture === "internal_only_policy_gated").length,
+    public_claim_boundary: pack.public_claim_boundary,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+function summarizeOperatorTreasuryDestinationsPack() {
+  const pack = buildOperatorTreasuryDestinationsPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-operator-treasury-destinations-pack-summary",
+    summary_version: "xytara-operator-treasury-destinations-pack-summary-v1",
+    profile_count: pack.profiles.length,
+    configured_profile_count: pack.readiness_summary.configured_profile_count,
+    explicit_per_rail_configured_count: pack.readiness_summary.explicit_per_rail_configured_count,
+    public_claimable_profile_count: pack.readiness_summary.public_claimable_profile_count,
+    readiness_only_profile_count: pack.readiness_summary.readiness_only_profile_count,
+    reporting_gap_count: pack.readiness_summary.reporting_gap_count,
+    internal_only_profile_count: pack.profiles.filter((entry) => entry.compliance_posture === "internal_only_policy_gated").length,
+    public_claim_boundary: pack.public_claim_boundary,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+function buildTreasuryDestinationValidationPreview(input) {
+  const providedMap = input && typeof input === "object" && !Array.isArray(input)
+    ? input.treasury_destinations_by_settlement_mode
+    : null;
+  const previousJson = process.env.XYTARA_TREASURY_DESTINATIONS_JSON;
+  const previousPath = process.env.XYTARA_TREASURY_DESTINATIONS_PATH;
+  try {
+    if (providedMap && typeof providedMap === "object") {
+      process.env.XYTARA_TREASURY_DESTINATIONS_JSON = JSON.stringify(providedMap);
+      delete process.env.XYTARA_TREASURY_DESTINATIONS_PATH;
+    }
+    const pack = buildTreasuryDestinationsPack();
+    return {
+      product: "xytara",
+      category: "machine-commerce-treasury-destination-validation-preview",
+      preview_version: "xytara-treasury-destination-validation-preview-v1",
+      operator_rule: pack.operator_rule,
+      readiness_summary: pack.readiness_summary,
+      profiles: pack.profiles.map((profile) => ({
+        rail_id: profile.rail_id,
+        readiness_state: profile.readiness_state,
+        public_claim_status: profile.public_claim_status,
+        public_claim_allowed: profile.public_claim_allowed,
+        explicit_per_rail_configured: profile.explicit_per_rail_configured,
+        missing_required_fields: profile.field_requirements.missing_required_fields,
+        missing_recommended_fields: profile.field_requirements.missing_recommended_fields
+      }))
+    };
+  } finally {
+    if (previousJson === undefined) delete process.env.XYTARA_TREASURY_DESTINATIONS_JSON;
+    else process.env.XYTARA_TREASURY_DESTINATIONS_JSON = previousJson;
+    if (previousPath === undefined) delete process.env.XYTARA_TREASURY_DESTINATIONS_PATH;
+    else process.env.XYTARA_TREASURY_DESTINATIONS_PATH = previousPath;
+  }
+}
+
+module.exports = {
+  buildOperatorTreasuryDestinationsPack,
+  summarizeOperatorTreasuryDestinationsPack,
+  buildTreasuryDestinationsPack,
+  summarizeTreasuryDestinationsPack,
+  buildTreasuryDestinationValidationPreview
+};

package/lib/treasury_egress_policy_contract.js

@@ -0,0 +1,91 @@
+"use strict";
+
+const { buildOperatorTreasuryDestinationsPack } = require("./treasury_destinations_contract");
+
+const RAILS = [
+  "bsv_teranode",
+  "evm",
+  "base",
+  "usdc",
+  "dai",
+  "monero"
+];
+
+function buildRailPolicies() {
+  const operatorPack = buildOperatorTreasuryDestinationsPack();
+  const bySettlementMode = new Map(
+    (operatorPack.profiles || []).map((profile) => [profile.settlement_mode, profile])
+  );
+  return RAILS.map((settlementMode) => {
+    const profile = bySettlementMode.get(settlementMode) || null;
+    return {
+      settlement_mode: settlementMode,
+      destination_configured: Boolean(profile && profile.configured),
+      egress_posture: "manual_review_only",
+      autonomous_release_allowed: false,
+      manual_reason_required: true,
+      signoff_required: true,
+      outbound_default_state: "blocked",
+      policy_scope: profile && profile.compliance_posture ? profile.compliance_posture : null
+    };
+  });
+}
+
+function buildTreasuryEgressPolicyPack() {
+  const railPolicies = buildRailPolicies();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-egress-policy-pack",
+    pack_version: "xytara-treasury-egress-policy-pack-v1",
+    posture: "black_hole_treasury_easy_inbound_manual_review_only_outbound",
+    autonomous_release_allowed: false,
+    operator_review_required: true,
+    manual_reason_required: true,
+    default_policy: {
+      inbound_posture: "open_to_configured_payment_and_settlement_paths",
+      outbound_posture: "blocked_until_manual_review_and_signoff",
+      autonomous_release_allowed: false,
+      operator_review_required: true,
+      manual_reason_required: true,
+      treasury_justification_required: true,
+      refund_signal_is_not_payout_authority: true,
+      dual_control_recommended: true
+    },
+    rail_policies: railPolicies,
+    control_points: [
+      "payment-ledger",
+      "reconciliation-report",
+      "treasury-signoff-pack",
+      "rail-signoff-pack",
+      "refund-review",
+      "market-signoff-pack"
+    ],
+    linked_surfaces: {
+      treasury_destinations_operator_pack_ref: "/v1/treasury-destinations/operator-pack",
+      treasury_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/treasury-signoff-pack",
+      rail_signoff_pack_ref_template: "/v1/economics/accounts/:account_id/rail-signoff-pack",
+      market_signoff_pack_ref: "/v1/economics/markets/signoff-pack",
+      payment_ledger_ref: "/v1/payment-ledger",
+      reconciliation_report_ref: "/v1/reconciliation-report"
+    },
+    operator_rule: "no_funds_leave_treasury_autonomously_without_clear_manual_reason_and_operator_review"
+  };
+}
+
+function summarizeTreasuryEgressPolicyPack() {
+  const pack = buildTreasuryEgressPolicyPack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-treasury-egress-policy-pack-summary",
+    summary_version: "xytara-treasury-egress-policy-pack-summary-v1",
+    rail_policy_count: pack.rail_policies.length,
+    configured_rail_count: pack.rail_policies.filter((entry) => entry.destination_configured).length,
+    autonomous_release_allowed: pack.default_policy.autonomous_release_allowed,
+    linked_surfaces: pack.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildTreasuryEgressPolicyPack,
+  summarizeTreasuryEgressPolicyPack
+};