feat(config): per-chain configuration and runtime registry

.env.example

@@ -1,6 +1,21 @@
 # Copy to `.env` and fill in. NEVER commit `.env`.
 
-# --- Network ---
+# --- Chains ---
+# Multi-chain configuration precedence (see octo.chains.example.toml and
+# docs/architecture.md's "Per-chain configuration" section for the full picture):
+#   1. CHAIN_CONFIG_PATH, if set, MUST name an existing TOML file (a typo'd path aborts boot,
+#      it does not silently fall back) describing one or more [[chains]].
+#   2. Else, if ./octo.chains.toml exists in the working directory, it's used automatically.
+#   3. Else, the single-chain NETWORK/HORIZON_URL/FRIENDBOT_URL/HORIZON_* vars below build one
+#      implicit Stellar chain — this is what today's single-chain deployments keep using
+#      unmodified.
+# In all cases, a chain's `rpc_url` can be overridden per-deploy-environment (e.g. to inject a
+# secret without putting it in the config file) via OCTO_CHAIN_<CHAIN_ID>_RPC_URL, where
+# <CHAIN_ID> is the chain's id upper-cased with every non-alphanumeric character replaced by `_`
+# (e.g. chain id "stellar:testnet" -> OCTO_CHAIN_STELLAR_TESTNET_RPC_URL).
+# CHAIN_CONFIG_PATH=octo.chains.toml
+
+# --- Network (legacy single-chain fallback; ignored when a chain config file is in effect) ---
 # Which Stellar network the server operates on: "testnet" or "mainnet".
 NETWORK=testnet
 

Cargo.toml

@@ -55,6 +55,7 @@ sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio",
 # --- serde / utility ---
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+toml = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 thiserror = "1"

README.md

@@ -104,6 +104,12 @@ curl -s -X POST localhost:8080/v1/wallets/<WALLET_ID>/submit-signed \
 See [docs/non-custodial-flow.md](docs/non-custodial-flow.md) for the full
 build → sign → relay sequence.
 
+By default the server runs a single Stellar chain from `.env`. To run more than one chain (e.g.
+Stellar mainnet alongside a future EVM chain), point `CHAIN_CONFIG_PATH` at a TOML file like
+[`octo.chains.example.toml`](octo.chains.example.toml) instead — see the "Deployment: per-chain
+configuration" section of [docs/architecture.md](docs/architecture.md) for the full precedence
+rules and `GET /health/chains` for per-chain reachability.
+
 ## Security architecture
 
 octo is non-custodial: user wallet keys are generated and held **client-side** (browser/SDK), so