feat(intents,solvers,archival): token FKs, replica routing, cold storage, keyset pagination

.env.example

@@ -548,3 +548,35 @@ DATASETS_PUBLIC_BUCKET=vortex-public-datasets
 DATASETS_STORAGE_KIND=memory
 DATASETS_LOCAL_DIR=./data/datasets
 
+
+# ─── Read replicas (#411) ─────────────────────────────────────────────────────
+# Comma-separated read-replica Postgres connection strings.
+# Leave blank to route all reads to the primary.
+# Example: postgresql://vortex:vortex@replica1:5432/vortex?schema=public,postgresql://vortex:vortex@replica2:5432/vortex?schema=public
+DATABASE_REPLICA_URLS=
+# Maximum replica replication lag (ms) before a replica is bypassed for reads.
+# Default: 5000 (5 s). Requests that arrive with a recent-write token always use the primary.
+MAX_REPLICA_LAG_MS=5000
+
+# ─── Cursor HMAC secret (#412) ────────────────────────────────────────────────
+# HMAC-SHA256 key used to sign opaque pagination cursors.
+# Required in production — generate with: openssl rand -hex 32
+CURSOR_HMAC_SECRET=dev-cursor-hmac-secret-do-not-use-in-prod
+
+# ─── Cold-storage archival (#413) ─────────────────────────────────────────────
+# Enable the daily archival job that moves terminal intents to Parquet in S3.
+ARCHIVAL_ENABLED=false
+# S3 bucket name. Works with MinIO locally (docker compose --profile archival up).
+ARCHIVAL_BUCKET_NAME=vortex-archives
+# S3-compatible endpoint URL. Leave blank for AWS S3 in production.
+# For local MinIO: http://localhost:9000
+ARCHIVAL_S3_ENDPOINT=
+ARCHIVAL_S3_REGION=us-east-1
+ARCHIVAL_S3_ACCESS_KEY_ID=
+ARCHIVAL_S3_SECRET_ACCESS_KEY=
+# Intents older than this many days (from their terminal transition) are eligible for archival.
+ARCHIVAL_RETENTION_DAYS=30
+# S3 key prefix for date partitions. Written as: <prefix>YYYY-MM-DD/
+ARCHIVAL_PARTITION_PREFIX=date=
+# Maximum rows written to a single Parquet file before rotating to a new file.
+ARCHIVAL_MAX_ROWS_PER_FILE=100000

.env.mainnet.example

@@ -380,3 +380,24 @@ SENTRY_DSN=<CHANGE_ME>
 # info is the right level for production — "debug" is too noisy.
 LOG_LEVEL=info
 
+
+# ─── Read replicas (#411) ─────────────────────────────────────────────────────
+# RECOMMENDED: route read-heavy endpoints to replicas to reduce primary load.
+DATABASE_REPLICA_URLS=<CHANGE_ME>  # e.g. postgresql://vortex:<SECRET>@replica.prod.vortex.trade:5432/vortex?schema=public
+MAX_REPLICA_LAG_MS=5000
+
+# ─── Cursor HMAC secret (#412) ────────────────────────────────────────────────
+# REQUIRED in production. Generate with: openssl rand -hex 32
+CURSOR_HMAC_SECRET=<CHANGE_ME>
+
+# ─── Cold-storage archival (#413) ─────────────────────────────────────────────
+# RECOMMENDED: archive terminal intents to keep the hot DB small.
+ARCHIVAL_ENABLED=true
+ARCHIVAL_BUCKET_NAME=vortex-archives-prod
+ARCHIVAL_S3_ENDPOINT=          # blank = AWS S3
+ARCHIVAL_S3_REGION=us-east-1
+ARCHIVAL_S3_ACCESS_KEY_ID=<CHANGE_ME>
+ARCHIVAL_S3_SECRET_ACCESS_KEY=<CHANGE_ME>
+ARCHIVAL_RETENTION_DAYS=30
+ARCHIVAL_PARTITION_PREFIX=date=
+ARCHIVAL_MAX_ROWS_PER_FILE=100000

.env.staging.example

@@ -245,3 +245,21 @@ OUTBOX_LEASE_SECONDS=120
 SLASH_CHALLENGE_WINDOW_SECONDS=600
 SLASH_CLOCK_SKEW_TOLERANCE_SECONDS=30
 SLASH_MAX_SUBMIT_ATTEMPTS=5
+
+# ─── Read replicas (#411) ─────────────────────────────────────────────────────
+DATABASE_REPLICA_URLS=
+MAX_REPLICA_LAG_MS=5000
+
+# ─── Cursor HMAC secret (#412) ────────────────────────────────────────────────
+CURSOR_HMAC_SECRET=dev-cursor-hmac-secret-do-not-use-in-prod
+
+# ─── Cold-storage archival (#413) ─────────────────────────────────────────────
+ARCHIVAL_ENABLED=false
+ARCHIVAL_BUCKET_NAME=vortex-archives-staging
+ARCHIVAL_S3_ENDPOINT=
+ARCHIVAL_S3_REGION=us-east-1
+ARCHIVAL_S3_ACCESS_KEY_ID=
+ARCHIVAL_S3_SECRET_ACCESS_KEY=
+ARCHIVAL_RETENTION_DAYS=30
+ARCHIVAL_PARTITION_PREFIX=date=
+ARCHIVAL_MAX_ROWS_PER_FILE=100000

.env.testnet.example

@@ -1,3 +1,22 @@
+
+
+# ─── Read replicas (#411) ─────────────────────────────────────────────────────
+DATABASE_REPLICA_URLS=
+MAX_REPLICA_LAG_MS=5000
+
+# ─── Cursor HMAC secret (#412) ────────────────────────────────────────────────
+CURSOR_HMAC_SECRET=dev-cursor-hmac-secret-do-not-use-in-prod
+
+# ─── Cold-storage archival (#413) ─────────────────────────────────────────────
+ARCHIVAL_ENABLED=false
+ARCHIVAL_BUCKET_NAME=vortex-archives-testnet
+ARCHIVAL_S3_ENDPOINT=http://localhost:9000
+ARCHIVAL_S3_REGION=us-east-1
+ARCHIVAL_S3_ACCESS_KEY_ID=minioadmin
+ARCHIVAL_S3_SECRET_ACCESS_KEY=minioadmin
+ARCHIVAL_RETENTION_DAYS=30
+ARCHIVAL_PARTITION_PREFIX=date=
+ARCHIVAL_MAX_ROWS_PER_FILE=100000
 # .env.testnet.example
 #
 # Environment template for LOCAL DEVELOPMENT against Stellar TESTNET.