lexe_common/

constants.rs

use std::include_bytes;

use lexe_enclave::enclave::{Measurement, MrShort};
use lexe_std::const_concat_str;

use crate::{ppm, ppm::Ppm};

/// Timeout constants and hierarchies.
pub mod timeout;

// --- General --- //

/// If a node release needs to be yanked, add its semver version and measurement
/// here. See `node::approved_versions` for more info.
// e.g. "0.1.0", "0.2.1-alpha.1".
// TODO(max): We could replace these by baking in `releases-archive.json`.
pub const YANKED_NODE_VERSIONS: [&str; 0] = [];
pub const YANKED_NODE_MEASUREMENTS: [Measurement; 0] = [];
lexe_std::const_assert!(
    YANKED_NODE_VERSIONS.len() == YANKED_NODE_MEASUREMENTS.len()
);

/// The first node version to serve the `/user/v1/provision` endpoint,
/// older node versions serve only `/app/provision`.
///
/// The backend now never returns pre-`node-v0.9.12` enclaves to provision.
/// We had to filter the response, as we deployed bad clients which fail to
/// start up because they erroneously provision via the `/user` endpoint.
//
// TODO(max): Remove this once pre-`node-v0.9.12` enclaves are revoked.
pub const FIRST_USER_API_NODE_VERSION: semver::Version =
    semver::Version::new(0, 9, 12);

/// Reject backend requests for payments that are too large.
pub const MAX_PAYMENTS_BATCH_SIZE: u16 = 100;
pub const DEFAULT_PAYMENTS_BATCH_SIZE: u16 = 50;

/// Reject payment notes that are too large.
pub const MAX_PAYMENT_NOTE_BYTES: usize = 512;

/// This is both:
///
/// - The size of the `ApprovedVersions` window.
/// - The number of trusted versions that the app will try to keep provisioned.
///
/// This strikes a balance between:
///
/// 1) having a sufficient number of recent versions approved so that Lexe has
///    the ability to downgrade users (by yanking versions) if it is discovered
///    that a node release is broken in some way, and
/// 2) having so many versions approved that Lexe could downgrade users to an
///    old version that may contain vulnerabilities.
pub const RELEASE_WINDOW_SIZE: usize = 2;

// --- Channels and liquidity --- //

/// Our dust limit for e.g. our channel close txo's. If our channel balance,
/// after paying close fees, is <= this value, we will not get a txo and this
/// value is lost (goes to fees).
///
/// LDK just uses a fixed value here.
///
/// See: [`MIN_CHAN_DUST_LIMIT_SATOSHIS`](https://github.com/lightningdevkit/rust-lightning/blob/70add1448b5c36368b8f1c17d672d8871cee14de/lightning/src/ln/channel.rs#L697)
pub const LDK_DUST_LIMIT_SATS: u32 = 354;

/// The amount of liquidity (in sats) that Lexe supplies to us for free, which
/// we are not expected to pay interest on. This is also the amount of liquidity
/// Lexe's LSP will supply to a user in their first JIT zeroconf channel open.
// 50k sats = 0.0005 BTC = $25 at $50k/BTC or $50 at $100k/BTC
pub const FREE_LIQUIDITY_SAT: u32 = 50_000;

/// The maximum amount of liquidity that Lexe will supply to a user in one tx.
//
// TODO(phlip9): increase once new liquidity model is in
pub const MAX_LIQUIDITY_SAT: u32 = 1_000_000; // 0.01 BTC

/// User nodes require the LSP to reserve this proportion of the channel value
/// (in millionths) as potential punishment. LDK clamps the actual reserve
/// amount to at least 1000 sats. Since the LSP can't send this amount to the
/// user, the user's inbound liquidity is also reduced by this amount. Used for:
/// [`lightning::util::config::ChannelHandshakeConfig::their_channel_reserve_proportional_millionths`]
pub const LSP_RESERVE_PROPORTION: Ppm = ppm!(1.0%);

/// The LSP will only accept new inbound channels with channel value at or above
/// this limit in satoshis.
// 0.00005000 BTC = $2.50 at $50k/BTC or $5 at $100k/BTC
pub const LSP_USERNODE_CHANNEL_MIN_FUNDING_SATS: u32 = 5_000;

/// Unconditional extra fee the LSP<->user channel funder will pay for
/// coop-close in order to avoid a potential force-close due to fee
/// disagreement.
///
/// During modern "legacy" (not "simple_close") coop-close, the channel funder
/// proposes a `[min fee, max fee]` range that it's willing to pay. An LDK
/// counterparty then chooses the `max_fee`.
///
/// An LDK funder determines the `max_fee` by estimating the feerate for
/// [`ConfirmationTarget::NonAnchorChannelFee`] plus this
/// `FORCE_CLOSE_AVOIDANCE_MAX_FEE_SATS` value.
///
/// 2026-06-24: Prior to this date, this was 1000 sats, which meant all our
/// LSP<->User coop-closes overpaid on-chain fees by ~7-8x market rate.
///
/// See: [`lightning::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis`]
///
/// [`ConfirmationTarget::NonAnchorChannelFee`]: lightning::chain::chaininterface::ConfirmationTarget::NonAnchorChannelFee
pub const FORCE_CLOSE_AVOIDANCE_MAX_FEE_SATS: u64 = 50;

// --- Human Bitcoin Addresses --- //

/// The minimum total wallet balance (in sats) required to claim or update a
/// custom Human Bitcoin Address. Deters mass-claiming of usernames.
// 10k sats = $5 at $50k/BTC or $10 at $100k/BTC
pub const HBA_CLAIM_MIN_BALANCE_SATS: u32 = 10_000;

// --- Networking --- //

/// Fake DNS names used by the reverse proxy to route requests to user nodes.
/// Provision mode uses "{mr_short}.provision.lexe.app" and run mode uses
/// "run.lexe.app". These DNS names don't actually resolve.
pub const NODE_RUN_DNS: &str = "run.lexe.app";
pub const NODE_RUN_URL: &str = const_concat_str!("https://", NODE_RUN_DNS);
pub fn node_provision_dns(mr_short: &MrShort) -> String {
    format!("{mr_short}{NODE_PROVISION_DNS_SUFFIX}")
}
pub const NODE_PROVISION_DNS_SUFFIX: &str = ".provision.lexe.app";

// --- Esplora --- //
// Quickly test these by appending /fee-estimates and opening in browser,
// e.g. "https://testnet.ltbl.io/api/fee-estimates"

pub const MAINNET_LEXE_MEMPOOL_ESPLORA: &str = "https://lexe.mempool.space/api";
// Introduced in node-v0.6.8, lsp-v0.6.28
pub const MAINNET_LEXE_BLOCKSTREAM_ESPLORA: &str =
    "https://ipwl.blockstream.info/api";
pub const MAINNET_PUBLIC_BLOCKSTREAM_ESPLORA: &str =
    "https://blockstream.info/api";
pub const MAINNET_ESPLORA_WHITELIST: [&str; 3] = [
    MAINNET_LEXE_MEMPOOL_ESPLORA,
    MAINNET_LEXE_BLOCKSTREAM_ESPLORA,
    MAINNET_PUBLIC_BLOCKSTREAM_ESPLORA,
];

// Introduced in node-v0.7.12
pub const TESTNET3_LEXE_MEMPOOL_ESPLORA: &str =
    "https://lexe.mempool.space/testnet/api";
// Introduced in node-v0.6.8, lsp-v0.6.28
// NOTE: our ipwl doesn't currently work for testnet3
pub const TESTNET3_LEXE_BLOCKSTREAM_ESPLORA: &str =
    "https://ipwl.blockstream.info/testnet/api";
pub const TESTNET3_PUBLIC_BLOCKSTREAM_ESPLORA: &str =
    "https://blockstream.info/testnet/api";
pub const TESTNET3_LTBL_ESPLORA: &str = "https://testnet.ltbl.io/api";
pub const TESTNET3_LEXE_ESPLORA: &str = "https://esplora.staging.lexe.app/api";
pub const TESTNET3_ESPLORA_WHITELIST: [&str; 5] = [
    TESTNET3_LEXE_BLOCKSTREAM_ESPLORA,
    TESTNET3_PUBLIC_BLOCKSTREAM_ESPLORA,
    TESTNET3_LEXE_ESPLORA,
    TESTNET3_LEXE_MEMPOOL_ESPLORA,
    TESTNET3_LTBL_ESPLORA,
];

// --- Root CA certs --- //
//
// This section contains DER-encoded TLS certs for the root CAs used by various
// websites that we make requests to, including Lexe itself. For security, we
// only allow using reqwest with `rustls-tls-manual-roots`, which trusts 0 roots
// by default. Thus, it is necessary to manually include a root CA cert in our
// TLS config whenever we make a request to Lexe or an external site. For
// extra security, once a `reqwest::Client` has been configured to trust a CA
// root, it should not be reused for requests to sites with different roots.
//
// ### Instructions for adding or updating an external root cert
// (written for Brave / Chrome)
//
// - Visit the website in your browser via HTTPS.
// - Click the HTTPS lock icon and view certificate details.
// - Navigate up the certificate chain until you have selected the root cert.
// - Press "Export..."
// - When prompted for the format, use "DER-encoded binary, single certificate".
// - Save it to "lexe-common/data/<root_ca_name>_root-ca-cert.der"
// - Add a `include_bytes!()` entry below with a corresponding test.
// - Tip: You can see the full human-readable cert info with macOS Quick Look.
//
// ### Inspecting a DER-encoded certificate
//
// macOS Finder's "Quick Look" works for some certificates.
// Alternatively, view the cert from the command line:
//
// ```bash
// openssl x509 -inform der -in <certificate-name>.der -text -noout
// ```

/// The Lexe CA responsible for `lexe.app` and `.lx`.
// Serial Number : 73:bb:2d:b0:13:58:d7:1c:ca:a5:d3:56:a7:f3:33:5b:4c:3c:60:8e
//    Not Before : Nov 27 21:44:46 2024 GMT
//     Not After : Dec  4 21:44:46 2034 GMT
pub const LEXE_PROD_CA_CERT_DER: &[u8] =
    include_bytes!("../data/lexe-prod-root-ca-cert.der");

/// The Lexe CA responsible for `staging.lexe.app` and `staging.lx`.
// Serial Number : 30:ef:fb:a0:ba:ca:82:0b:7f:49:9a:46:b7:8d:05:18:23:91:62:17
//    Not Before : Jul 30 02:15:24 2024 GMT
//     Not After : Aug  6 02:15:24 2034 GMT
pub const LEXE_STAGING_CA_CERT_DER: &[u8] =
    include_bytes!("../data/lexe-staging-root-ca-cert.der");

/// The Lexe dummy CA used in local testing and development.
// Serial Number : 37:80:43:1e:b3:5c:74:e0:c4:1a:3d:45:2a:be:d0:bb:83:14:f3:6a
//    Not Before : Jan  1 00:00:00 1975 GMT
//     Not After : Jan  1 00:00:00 4096 GMT
pub const LEXE_DUMMY_CA_CERT_DER: &[u8] =
    include_bytes!("../data/lexe-dummy-root-ca-cert.der");

/// Google Trust Services Root R1 (RSA), used by `googleapis.com` and
/// `dns.google`.
// `curl https://i.pki.goog/r1.crt -o lexe-common/data/google-trust-services-root-r1-ca-cert.der`
// Serial Number : 02:03:E5:93:6F:31:B0:13:49:88:6B:A2:17
//    Not Before : Jun 22 00:00:00 2016 GMT
//     Not After : Jun 22 00:00:00 2036 GMT
pub const GTS_ROOT_R1_CA_CERT_DER: &[u8] =
    include_bytes!("../data/google-trust-services-root-r1-ca-cert.der");

/// Google Trust Services Root R2 (RSA), used by `googleapis.com` and
/// `dns.google`.
// `curl https://i.pki.goog/r2.crt -o lexe-common/data/google-trust-services-root-r2-ca-cert.der`
// Serial Number : 02:03:E5:AE:C5:8D:04:25:1A:AB:11:25:AA
//    Not Before : Jun 22 00:00:00 2016 GMT
//    Not After  : Jun 22 00:00:00 2036 GMT
pub const GTS_ROOT_R2_CA_CERT_DER: &[u8] =
    include_bytes!("../data/google-trust-services-root-r2-ca-cert.der");

/// Google Trust Services Root R3 (ECDSA), used by `googleapis.com` and
/// `dns.google`.
// `curl https://i.pki.goog/r3.crt -o lexe-common/data/google-trust-services-root-r3-ca-cert.der`
// Serial Number : 02:03:E5:B8:82:EB:20:F8:25:27:6D:3D:66
//    Not Before : Jun 22 00:00:00 2016 GMT
//    Not After  : Jun 22 00:00:00 2036 GMT
pub const GTS_ROOT_R3_CA_CERT_DER: &[u8] =
    include_bytes!("../data/google-trust-services-root-r3-ca-cert.der");

/// Google Trust Services Root R4 (ECDSA), used by `googleapis.com` and
/// `dns.google`.
// `curl https://i.pki.goog/r4.crt -o lexe-common/data/google-trust-services-root-r4-ca-cert.der`
// Serial Number : 02:03:E5:C0:68:EF:63:1A:9C:72:90:50:52
//    Not Before : Jun 22 00:00:00 2016 GMT
//    Not After  : Jun 22 00:00:00 2036 GMT
pub const GTS_ROOT_R4_CA_CERT_DER: &[u8] =
    include_bytes!("../data/google-trust-services-root-r4-ca-cert.der");

/// GlobalSign Root R4 (ECDSA), used by `googleapis.com` and `dns.google`.
// `curl https://i.pki.goog/gsr4.crt -o lexe-common/data/globalsign-root-r4-ca-cert.der`
// Serial Number : 02:03:E5:7E:F5:3F:93:FD:A5:09:21:B2:A6
//    Not Before : Nov 13 00:00:00 2012 GMT
//    Not After  : Jan 19 03:14:07 2038 GMT
pub const GS_ROOT_R4_CA_CERT_DER: &[u8] =
    include_bytes!("../data/globalsign-root-r4-ca-cert.der");

#[cfg(test)]
mod test {
    use asn1_rs::FromDer;
    use x509_parser::prelude::X509Certificate;

    use super::*;

    #[test]
    fn test_parse_ca_certs() {
        X509Certificate::from_der(LEXE_PROD_CA_CERT_DER).unwrap();
        X509Certificate::from_der(LEXE_STAGING_CA_CERT_DER).unwrap();
        X509Certificate::from_der(GTS_ROOT_R1_CA_CERT_DER).unwrap();
        X509Certificate::from_der(GTS_ROOT_R2_CA_CERT_DER).unwrap();
        X509Certificate::from_der(GTS_ROOT_R3_CA_CERT_DER).unwrap();
        X509Certificate::from_der(GTS_ROOT_R4_CA_CERT_DER).unwrap();
    }
}