Merge branch 'main' into feat/indexer-lag-alert

Author: Tybravo

.env.example

@@ -5,15 +5,17 @@ JWT_SECRET=your-super-secret-jwt-key-change-this
 JWT_EXPIRES_IN=7d
 BCRYPT_ROUNDS=10
 LOG_LEVEL=debug
+
 # Comma-separated list of allowed frontend origins. Use "*" to allow any origin (not recommended for production).
 CORS_ORIGIN=http://localhost:3000,http://localhost:5173
+
 RATE_LIMIT_WINDOW_MS=900000
 RATE_LIMIT_MAX_REQUESTS=100
 
 # ─── Stellar / Soroban ─────────────────────────────────────────────────────────
 # Soroban RPC endpoint.
 # Testnet  : https://soroban-testnet.stellar.org
-# Mainnet  : https://soroban-mainnet.stellar.org  (or a custom Horizon/RPC node)
+# Mainnet  : https://soroban-mainnet.stellar.org (or a custom Horizon/RPC node)
 SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
 
 # Network passphrase — must match SOROBAN_RPC_URL.
@@ -46,4 +48,4 @@ INDEXER_LAG_WEBHOOK_URL=
 ESCROW_CONTRACT_ID=
 
 # Event topic emitted by the escrow contract when funds are locked. Default: escrow_funded
-ESCROW_FUNDED_EVENT_TOPIC=escrow_funded
+ESCROW_FUNDED_EVENT_TOPIC=escrow_funded

README.md

@@ -124,6 +124,20 @@ The backend serves as the central hub connecting the frontend, database, and blo
 - `POST /shipments` - Create a shipment record.
 - `GET /shipments` - Get shipment details.
 
+### Escrow
+
+- `GET /api/v1/escrow/delivery/:id` - Fetch the escrow record (locking state, amount, asset,
+  contract id, on-chain transaction hashes) associated with a delivery. `:id` accepts either the
+  delivery `_id` or its business `deliveryId`.
+  
+### Transactions
+
+- `POST /api/v1/transactions/escrow-lock` - Build the unsigned, simulation-prepared Soroban XDR
+  that locks a delivery's escrow amount. Accepts `{ deliveryId, payerAddress }`; the amount and
+  contract target are resolved server-side from MongoDB and the deployment configuration. The
+  returned base64 envelope is signed and submitted by the client wallet — the backend never holds
+  secret keys.
+
 ### Uploads
 
 - `POST /uploads` - Upload proof of delivery or documents.