Dara DocsReferenceOperations
Stellar RPC runbook
The platform talks to Stellar only through our own Stellar RPC nodes (no hosted RPC in production;
STELLAR_RPC_NODES, at least two in UAT and production). Each node is stellar-rpc with captive core, following
the network (Testnet or Mainnet) and retaining a window of recent ledgers.
What the gateway does
- Samples every node every
STELLAR_HEALTH_INTERVAL(5 s): network passphrase (a node on the wrong network is never used),getHealth, latest ledger and its close time, history window, latency. - States: HEALTHY, DEGRADED (slow or lagging the best node by more than a few ledgers), UNHEALTHY. Reads go to the best usable node; submissions go to every usable node (the same signed bytes; duplicates are harmless).
- Expiry proof before any retry: an attempt is only declared EXPIRED when a healthy node has closed a ledger past
the transaction's
maxTimewithout the hash (STELLAR_ARCHITECTURE.md§7).
Sizing and settings
| Setting | Guidance |
|---|---|
| History window | At least 7 days of ledgers (RPC default); the indexer must never fall further behind than the window, or it needs the SEP-54 backfill |
| Nodes | Two or more on separate hosts and, for Mainnet, separate providers' networks; one may be under maintenance |
| Hardware | Per the current stellar-rpc requirements for the chosen window (captive core needs fast disk) |
| Time | NTP on every host; ledger close time, not local time, decides expiry |
Common situations
| Symptom | Check | Action |
|---|---|---|
One node UNHEALTHY (StellarNodeUnhealthy) | System page reason; node logs | Restart; if captive core is catching up, wait; rebuild from a recent snapshot if corrupted |
All nodes UNHEALTHY (StellarNoHealthyNode) | Network reachability, wrong passphrase in node config, disk full | Restore one node first; the gate reopens after the hold-down |
Ledger stale (StellarLedgerStale) | Compare with an independent public view of the network | If the network is halted, wait; nothing is lost: intents stay pending and are proven later |
Indexer behind the window (INDEXER_GAP) | oldest_ledger vs the indexer cursor (System page) | Check that Galexie is running and its lake directory is mounted (deploy/datalake/, BACKFILL_DATASTORE_TYPE=Filesystem); once the lake covers the cursor the indexer continues |
| Upgrades | Network protocol upgrades are announced in advance | Upgrade one node at a time; the gateway routes around the one being upgraded |
Adding or replacing a node
Add it to STELLAR_RPC_NODES (name=url), restart the services; the gateway starts sampling it and routes to it once
healthy. Remove a node the same way. No data is stored in a node that the platform depends on: the platform's
records are in PostgreSQL and on-chain.