Phase 1: hosted checkout, CCTP V2 cutover, managed Stellar settlement

apps/api/.env.example

@@ -23,54 +23,61 @@ JWT_SECRET="replace-with-256-bit-random"
 JWT_EXPIRY="7d"
 API_KEY_SALT="replace-with-32-byte-random"
 
+# ── Settlement key encryption ─────────────────────────────────────────
+# AES-256-GCM key-encryption-key for the managed Stellar settlement wallet
+# seeds. 32-byte random, hex-encoded. Provision via your secrets manager
+# in production; rotation procedure documented in
+# apps/api/docs/architecture/merchant-settlement-onboarding.md.
+SETTLEMENT_KEY_KEK="replace-with-32-byte-random-hex"
+
+# Stellar account that sponsors mainnet CreateAccount + ChangeTrust ops
+# for new merchants. Cost is ~1.6 XLM per merchant (reserves recoverable
+# when accounts close). Leave unset on testnet — Friendbot funds new
+# accounts for free.
+STELLAR_RESERVE_SPONSOR_SECRET=""
+
 # ── Stellar ──────────────────────────────────────────────────────────────
 # "testnet" → horizon-testnet + Soroban testnet. Switch to "mainnet" only
-# after KYB review of the entity sending real funds.
+# after KYB review of the entity sending real funds. CCTP V2 reads this
+# same var to decide whether to talk to iris-api or iris-api-sandbox.
 STELLAR_NETWORK="testnet"
 STELLAR_HORIZON_URL="https://horizon-testnet.stellar.org"
 STELLAR_SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
 
-# Relay account — used by the API to submit on-chain transactions.
+# Stellar relay account — used by the API for non-customer-facing Soroban
+# operations (e.g., self-relay CCTP mints if Forwarding Service is off).
 # DO NOT REUSE keys across environments. Fund minimally for dev.
 STELLAR_RELAY_KEYPAIR_SECRET="S..."
 STELLAR_RELAY_PUBLIC_KEY="G..."
 
 # ── Soroban contracts (deployed addresses per network) ───────────────────
-SOROBAN_HTLC_CONTRACT_ID="C..."
-STELLAR_HTLC_CONTRACT_ID="C..."
+# HTLC contract IDs removed — replaced by CCTP V2 (CctpForwarder lives in
+# the cctp module's contracts.ts table, no env var needed).
 SOROBAN_SETTLEMENT_CONTRACT_ID="C..."
 SOROBAN_FEE_COLLECTOR_CONTRACT_ID="C..."
 SOROBAN_ESCROW_CONTRACT_ID="C..."
 
-# ── EVM (HTLC relay) ─────────────────────────────────────────────────────
-# Single private key authoring HTLC transactions on every supported chain.
-# Fund per-chain as needed.
-EVM_RELAY_PRIVATE_KEY="0x..."
-PRIVATE_KEY="0x..."   # legacy alias — kept for backwards compat
-
-HTLC_ADDRESS_ETHEREUM="0x..."
-HTLC_ADDRESS_BASE="0x..."
-HTLC_ADDRESS_BNB="0x..."
-HTLC_ADDRESS_POLYGON="0x..."
-HTLC_ADDRESS_ARBITRUM="0x..."
-HTLC_ADDRESS_AVALANCHE="0x..."
-
-# RPC endpoints — use a paid provider (Alchemy/Infura/QuickNode) in prod.
+# ── EVM RPC endpoints ────────────────────────────────────────────────────
+# Used by CCTP V2 to:
+#   - Parse customer-signed burn receipts to extract the Iris nonce
+#   - (Optionally) sign destination mints when self-relay is enabled
+# Use a paid provider (Alchemy/Infura/QuickNode) in prod for rate limits.
 RPC_ETHEREUM="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
 RPC_BASE="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
 RPC_BNB="https://bsc-dataseed.binance.org/"
 RPC_POLYGON="https://polygon-rpc.com"
 RPC_ARBITRUM="https://arb1.arbitrum.io/rpc"
 RPC_AVALANCHE="https://api.avax.network/ext/bc/C/rpc"
 
-# ── Circle CCTP ──────────────────────────────────────────────────────────
-CIRCLE_API_KEY="replace-with-circle-key"
-
-# ── Wormhole ─────────────────────────────────────────────────────────────
-WORMHOLE_ENV="Testnet"   # "Mainnet" for production
-
-# ── Layerswap (Starknet routing) ─────────────────────────────────────────
-LAYERSWAP_API_KEY="replace-with-layerswap-key"
+# ── CCTP V2 (Circle Cross-Chain Transfer Protocol) ───────────────────────
+# Fast = ~8-20s with a small per-transfer fee. Standard = ~15-19 min on
+# EVM L1, effectively free. Configurable per quote at runtime — this is
+# only the default when the caller doesn't specify.
+CCTP_DEFAULT_SPEED="fast"
+# Use Circle's Forwarding Service to broadcast the destination mint
+# (Circle pays the destination gas). When false, the API self-relays
+# the mint, which requires destination-chain wallets to be funded.
+CCTP_USE_FORWARDING="true"
 
 # ── MoneyGram (cash payouts) ─────────────────────────────────────────────
 MONEYGRAM_HOME_DOMAIN="extstellar.moneygram.com"        # testnet
@@ -88,3 +95,10 @@ EMAIL_FROM="noreply@useroutr.com"
 CLOUDINARY_CLOUD_NAME="replace-me"
 CLOUDINARY_API_KEY="replace-me"
 CLOUDINARY_API_SECRET="replace-me"
+
+# ── BetterStack (uptime watchdog) ────────────────────────────────────────
+# Read-only token for the BetterStack Uptime API. /readyz uses it to
+# confirm the watchdog itself is alive (API reachable, key valid, at
+# least one un-paused monitor configured). Create at
+# https://uptime.betterstack.com/team/<id>/api-tokens.
+BETTERSTACK_API_KEY="replace-me"