feat(indexer): one loop per configured network (#161, #160)

[Salmatcre8]

Closes #161. Also closes #160 — see below.

Why this closes two issues

#161 says "use getRpc(network) (W071)". That factory doesn't exist yet — #160 is still open, and getRpc() is a global singleton. Building #161 on top of the singleton would have produced a loop that cannot index two networks and cannot be tested, so the factory is here too. It's ~40 lines and the rest of the PR depends on every line of it.

Per-network RPC (#160)

getRpc(network) caches one client per network. Resolution: SOROBAN_RPC_URL_TESTNET / _MAINNET → unsuffixed SOROBAN_RPC_URL → public testnet default. Mainnet has no free public RPC, so it throws rather than guessing an endpoint that would fail on every call.

One deliberate subtlety. The unsuffixed SOROBAN_RPC_URL applies only to the network named by STELLAR_NETWORK:

if (network === currentNetwork()) {
  const legacy = process.env.SOROBAN_RPC_URL || process.env.STELLAR_RPC_URL;
  if (legacy) return legacy;
}

Without that guard, a deployment that sets SOROBAN_RPC_URL for testnet and then enables mainnet would have its mainnet loop connect to the testnet endpoint — connect fine, index fine, and write testnet ledgers tagged network='mainnet'. Silent corruption, no error anywhere. Scoping it keeps every existing single-network deployment byte-identical while making that impossible. There's a test for it; deleting the guard fails that test and nothing else.

Per-network loops (#161)

Each loop owns a LoopState — counters, watch lists, source switcher, cursor. Nothing shared, and that's a correctness requirement rather than tidiness:

• two loops incrementing one totalIndexed make /status unable to say how far either chain got;
• the source switcher has a mutable preferred field for failover, so one shared instance means a testnet RPC outage silently repoints the mainnet loop at testnet Horizon.

Everything that names a chain is per-network with a shared fallback: SAC_CONTRACT_IDS_*, NFT_CONTRACT_IDS_*, HORIZON_URL_*, START_LEDGER_*. START_LEDGER especially — the same sequence number is a completely different point in history on each chain.

NETWORKS=testnet,mainnet opts in. Unset means one loop on STELLAR_NETWORK, exactly as today. Unrecognised entries are dropped rather than throwing (a typo shouldn't take the indexer down), and duplicates collapse so NETWORKS=testnet,testnet can't start two loops fighting over one cursor.

Loops are fault-isolated: a crash restarts that loop after 10s instead of process.exit(1). An expiring mainnet RPC key must not stop testnet indexing — or take the read API down with it, which is what the old handler did.

Three writes that were silently untagged

network carries DEFAULT 'testnet', so a missing tag compiles, typechecks, and runs while filing mainnet rows as testnet. Found and fixed:

1. upsertHostFnLogs() never set network at all.
2. pollParallel() / runPartitionWorker() called upsertTransfers and setLastIndexedLedger unscoped — so the INGEST_WORKERS > 1 path wrote every row to the default network.
3. fetchNftMetadata() read process.env.STELLAR_NETWORK directly for its passphrase, so a mainnet metadata simulation would have been built with the testnet passphrase.

Also: sac-detect's cache was keyed by contract id alone. Contract ids are network-derived so a real collision is unlikely, but it is shared mutable state between loops, which the acceptance criteria rule out. Now keyed ${network}:${contractId}.

/status

Adds a networks object with per-network lastIndexedLedger, latestLedger, lagLedgers and loop stats. Top-level fields are unchanged, so existing consumers keep working — including tests/chaos/db-restart.test.ts, whose StatusResponse interface I checked against the new shape. A network with no running loop reports running: false rather than zeroes that read as progress.

Verification

• tsc --noEmit clean
• 290 tests pass, was 270 — 20 new
• Mutation-checked: removing the legacy-RPC scope guard fails exactly one test, so the assertion is real
• Integration tests grepped for the APIs I changed. They assert only existing /status fields and use SKIP_INDEXER, so this is additive for them. (I checked because feat(db): add network column across all Prisma models (#159) #169's integration break came from tsconfig.json including only src/**/* — tracked in tests/ is not typechecked — tsconfig include is src/**/* only #170.)

Acceptance criteria

• Two loops run concurrently without shared mutable state
• Each writes rows tagged with its own network
• /status reports per-network progress
• Single-network mode still works when only one is enabled — it is the default, and unchanged

Not in scope

#163 (network selector on REST/GraphQL/WS) — reads still answer for the configured network. This PR makes the data correct per network; #163 makes it selectable.

Joined the contributor Telegram.

[drips-wave]

@Salmatcre8 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits