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

[Emmyt24]

Depends on: #213. Blocks: #227.

Description

Configuration assumes exactly one chain. AppState holds a single
network: StellarNetwork, one horizon: Horizon, one horizon_url, one friendbot_url; the
ingest supervisor takes one Horizon URL. There is no way to express "Stellar mainnet and Base
and Arbitrum, each with its own endpoint, confirmation depth, and enable flag."

Replace the flat configuration with a per-chain structure that bin/server loads at startup and
resolves into the ChainRegistry from #213.

Requirements and context

• Support N chains where N ≥ 1, configured without recompiling.
• Fail fast and loudly at startup. A chain configured with a bad RPC URL must abort boot with a
  clear message, not fail lazily on the first customer deposit. Follow the existing precedent in
  CloudinaryConfig::from_env — but note that disabled-when-absent
  is right for image uploads and wrong for a chain that has live customer balances.
• Env-var-only config does not scale to N chains with ~8 settings each. Prefer a config file
  (TOML) with env-var override for secrets, and document the precedence order.
• Preserve the existing resilience wiring: RetryPolicy and CircuitBreaker are currently
  per-process, and must become per-chain — a degraded Base RPC must not open the circuit on
  Stellar. See crates/ingest/tests/supervisor_network_isolation_tests.rs
  for the isolation property already asserted.
• Security: RPC URLs frequently embed API keys (Alchemy, Infura). They must never appear in
  logs, error messages, or health endpoints. Wrap in a redacting Debug impl.

Suggested execution

Branch: feat/per-chain-configuration

Implement changes

• Define ChainConfig { chain_id, rpc_url (redacted Debug), enabled, confirmation_depth, poll_interval, retry, circuit, faucet_url }
  and AppConfig { chains: Vec<ChainConfig>, .. }.
• Refactor AppState to hold Arc<ChainRegistry> instead of network/horizon/horizon_url,
  keeping accessors for the Stellar path so route handlers change minimally in this PR.
• Add startup validation: chain ids are well-formed and unique, at least one chain is enabled, every
  enabled chain's RPC answers a liveness probe within a timeout.
• Move friendbot_url into the Stellar chain config (it is a Stellar-only concept and does not
  belong in shared state).
• Add a /health detail per chain — reachability and last successful poll, reusing
  LastPollTracker. Redact credentials.

Test and commit

• Test config parse: valid multi-chain file; duplicate chain id rejected; unknown chain id rejected;
  no-enabled-chains rejected.
• Test env-var override precedence explicitly.
• Test that a redacted RPC URL never appears in Debug/Display output or in a /health
  response — assert on the API-key substring being absent.
• Test that one chain's circuit breaker opening does not affect another's.
• Update .env.example, README.md, and the deployment section of
  docs/architecture.md with a worked multi-chain example.

Example commit message

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

Replaces single-chain AppState fields with a ChainRegistry built from
per-chain config, each carrying its own RPC endpoint, confirmation
depth, and resilience policy so a degraded RPC on one chain cannot
open the circuit on another.

RPC URLs use a redacting Debug impl — provider URLs embed API keys.

Refs #216

Guidelines

Keep this PR mechanical. Do not add EVM chains here — this issue delivers the shape, and #217/#218
deliver an adapter to put in it.

---

[bobo-24]

Hi! I’m a full-stack developer with a strong blockchain background, and I’m confident I can resolve this issue quickly and effectively. I’ll deliver a clean, reliable solution with immediate attention to detail, ensuring it’s completed as soon as possible. Please assign it to me—I’m ready to get started right away.

[Nexha-dev]

Hi maintainers! I'd like to take on this issue and work on the per-chain configuration and runtime registry.

I've reviewed the requirements, including the dependency on #213 and the fact that this issue is intentionally focused on providing the configuration and runtime shape rather than adding EVM adapters. I understand the goal is to replace the current single-chain assumptions with a scalable configuration model that can support multiple chains without requiring recompilation, while preserving the existing Stellar behavior and resilience guarantees.

Implementation approach

I'll start by defining the new ChainConfig and AppConfig structures, including the per-chain RPC endpoint, enable flag, confirmation depth, polling interval, retry policy, circuit-breaker configuration, and optional faucet URL. I'll use a TOML-based configuration as the primary source, with environment variables available for secret overrides, and clearly document the precedence rules.

I'll then refactor AppState to use Arc<ChainRegistry> while maintaining compatibility accessors for the existing Stellar path so that unrelated route handlers don't need unnecessary changes in this PR.

For startup validation, I'll make the application fail fast when configuration is invalid. This will include checking that:

• At least one chain is enabled.
• Chain IDs are valid and unique.
• Unknown/unsupported chain IDs are rejected appropriately.
• Every enabled chain has a valid RPC URL.
• Each enabled RPC endpoint passes a liveness check within the configured timeout.
• Configuration errors provide clear startup messages instead of being deferred until runtime.

I'll also move the Stellar-specific friendbot_url into the Stellar chain configuration rather than keeping it in shared application state.

Resilience and security

An important part of this issue is ensuring resilience is isolated per chain. I'll make sure RetryPolicy and CircuitBreaker are associated with individual chain configurations/registry entries so that an unhealthy Base RPC, for example, cannot affect Stellar's circuit state.

I'll also implement the required RPC URL redaction carefully. Since provider URLs can contain API keys, credentials must not leak through Debug, Display, health endpoints, logs, or startup errors. I'll add a redacting Debug implementation and tests that explicitly verify an API-key substring never appears in these outputs.

The /health response will expose per-chain health details such as reachability and the last successful poll using the existing LastPollTracker, while ensuring sensitive RPC credentials are never exposed.

Testing and documentation

I'll add tests covering:

• Valid multi-chain configuration parsing.
• Duplicate chain ID rejection.
• Invalid/unknown chain ID rejection.
• No-enabled-chains rejection.
• Environment-variable override precedence.
• RPC URL redaction in Debug/Display.
• RPC credential redaction in /health.
• Independent circuit-breaker behavior between chains.
• Startup/liveness validation for enabled RPC endpoints.

I'll also update .env.example, README.md, and docs/architecture.md with a practical multi-chain configuration example and the configuration precedence rules.

I'll keep the PR mechanical and focused on the configuration and registry infrastructure, without introducing EVM adapters or unrelated feature work. Before submitting, I'll run the relevant test suite and verify that the existing Stellar functionality continues to work as expected.

I'd be happy to take this issue. Thanks for considering my application!

[grantfox-oss]

🦊 GrantFox — @Nexha-dev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #216)
2. Your PR will be reviewed by the Octo-Protocol-org maintainers

Good luck! Track your progress on GrantFox.