Research
The thinking behind every Stellar Index choice. Architecture decision records (ADRs) below capture every load-bearing design call with its alternatives + consequences. The operations runbooks and architecture narratives live alongside the source on GitHub.
Architecture narratives
7 docs · source on GitHubIngest pipeline — the one canonical data path
How a Stellar ledger event becomes a row in our trades hypertable. Galexie → MinIO → ledgerstream → dispatcher → per-source decoders. The one canonical path.
Aggregation plan — the policy chain from raw trade to served price
The policy chain from raw trade to served price — class filter, outlier filter, VWAP, freeze gate. Every load-bearing decision the aggregator makes.
Supply pipeline — three-algorithm derivation, per-asset refresh
Three-domain supply derivation: XLM hard-coded, classic from ledger entries, SEP-41 from event sums. Per-asset refresh cadence. ADR-0011 in full.
Per-contract schema evolution across versions — handling strategy
Soroban DeFi contracts upgrade in place, and event schemas can change with them. How decoders stay correct across WASM versions, including for backfill.
Oracle manipulation — attack catalogue and defensive layers
Attack catalogue: TWAP-window stuffing, single-block manipulation, oracle drift. The defensive layers we run, ordered by how cheap they are to detect.
High-Availability Infrastructure Plan
Per-region high-availability topology — colo primary + cloud DR, three-tier hot/warm/cold storage, the failover decision tree.
SemVer policy for Stellar Index
What bumps the major / minor / patch on every binary release. Public types in pkg/* are SemVer-stable; internal/* moves freely.
Operations runbooks
4 guides · source on GitHubThe recipes any new operator (or auditor) would want to read before standing up their own copy. Per-alert on-call runbooks stay private; these four are the cross-cutting procedures.
Archival node bring-up — end-to-end recipe
Six-step recipe to stand up a new archival node from a fresh box. ~10–13 hours wall-clock for the full mainnet history catch-up; mostly bandwidth-bound. Includes the disaster-recovery triage tree.
Release process — cutting a Stellar Index binary release
How a binary release is cut. CHANGELOG promotion, tag push, cross-compiled binaries, SHA256SUMS, and an automated GitHub release with auto-extracted notes. Includes the manual fallback path when CI is unavailable.
Deploy workflow — pushing a tagged release to a region
Pushing a tagged release into a region. Stage → backup → atomic install → restart → health probe → automatic rollback on failure. Operator-triggered, never automatic on tag.
Incident (SEV) Playbook
Incident response procedure. Severity classification (SEV-1 / SEV-2 / SEV-3), responder roles, customer-comms cadence, postmortem requirement.
Architecture decision records
36 records · source on GitHubNetwork explorer (full Stellar + Soroban) over the certified lake
Factory-anchored contract gating for Soroban decoders
Tiered data architecture — ClickHouse raw lake, Postgres served tier
Completeness verification — substrate continuity, recognition, projection reconciliation
Per-source tables are projections of soroban_events
Coverage signal is data-derived from authoritative stores
Per-source coverage invariant
Tokenized real-world assets as AssetType "rwa
Stablecoin → fiat proxy is late-binding aggregator policy, not eager ingest normalisation
Caddy trusts Cloudflare for client-IP signal via CIDR-pinned static list
Redis HA via Sentinel (not Cluster)
SEP-41 supply observer — mint / burn / clawback event-stream tracking
Classic-supply observers — Trustline / ClaimableBalance / LiquidityPool / ContractData entry tracking
AccountEntry observer — live home-domain + reserve-balance tracking
Chart API contract — timeframe + granularity + price_type
Anomaly response policy and confidence scoring — per-asset statistical baselines
API consistency surfaces — closed-bucket, tip, and observations
Archive completeness invariants and dual-archive integrity model
Per-region storage strategies for archival nodes (Hetzner full / AWS hybrid / Vultr hybrid)
API rates served from last-closed bucket, never in-progress
Crypto tickers as AssetType "crypto
Adopt go-stellar-sdk/xdr for SCVal decoding in source connectors
Three-domain supply algorithm — XLM hard-coded, classic from ledger entries, SEP-41 from event sums
Off-chain fiat currencies as AssetType "fiat
API latency budget — per-component time slices summing to p95 ≤ 200ms / p99 ≤ 500ms
Per-region HA topology — colo primary + cloud DR, three-tier hot/warm/cold storage
Redis as hot-path cache + rate-limit + ephemeral state
TimescaleDB for price time-series storage
Monorepo with a single Go module
Tier-1 three-validator aspiration (post-launch)
i128 / u128 values preserved end-to-end; never truncated to int64
Self-hosted storage is S3-compatible (MinIO), not local filesystem
Horizon is not in the Stellar Index architecture
Proposed
Why we publish all of this
Stellar already has Horizon. The reason a second pricing stack adds value is methodology — what gets included in the VWAP, how we handle cross-pair triangulation, what triggers a freeze, how we audit a Soroban contract before flipping BackfillSafe. None of that is useful behind a closed door. Every choice has an ADR with a "Why this not the alternative" section; every alert has a runbook.