Skip to documentation
Stargazer Docs

Documentation pages
Browse documentation Overview

How Stargazer processes Stellar data

Stargazer keeps the raw ledger evidence close to the indexer, derives compact databases for product queries, and is designed to reuse the same deterministic processing core for new ledgers and historical replays.

Current system and target architecture

The archive-backed demo path is implemented. Continuous live ingestion and broader off-chain signal collection are the next operating layers; this documentation labels those boundaries explicitly.

What local-first means

The local archive is a retained Galexie copy on the NAS, alongside local index databases and benchmarks. It lets engineering runs use stable inputs, resume without redownloading history, and preserve an exact path back to the compressed ledger evidence.

It is not a Stellar validating node and it does not publish a network history archive. The application consumes complete LedgerCloseMeta records exported by Galexie; its own databases contain derived, searchable facts.

Archive-backed product path

The bulk path separates immutable evidence, ingestion-optimized storage, and query-optimized serving data. That keeps the large historical write path lean and the public API bounded.

  1. 01
    Local Galexie archive Implemented

    Closed ledger partitions are kept on the NAS so large historical passes are reproducible and do not depend on repeated RPC retrieval.

  2. 02
    Bounded Rust decoding Implemented

    Compressed XDR streams directly into capped workers. Ledgers may decode concurrently, but validation and database writes remain in canonical order.

  3. 03
    Compact reverse index Implemented

    Contract transactions, exact wallet-to-contract edges, protocol attribution, and executable history are committed to a resumable SQLite database.

  4. 04
    Serving snapshot Implemented

    A separate bounded-memory finalizer derives wallet activity and leaderboard orderings, then publishes the completed database with an atomic rename.

  5. 05
    Read API and demo Implemented

    The API opens the evidence and serving databases read-only, validates their coverage, and exposes bounded wallet, protocol, upgrade, and ranking queries.

One processing contract, two time horizons

Historical path

Closed archive partitions are processed oldest first. Decoding can run concurrently within a fixed memory budget, while commits preserve ledger order and advance one durable high-water mark.

Live path

RPC or Captive Core will supply newly confirmed ledger metadata to the same normalization and indexing boundary. If the live cursor falls behind, retained archive data fills the missing range before the tail resumes.

Adding an indexer starts with history

A new fact extractor should prove that it can replay deterministically before it is trusted with live alerts. The offline archive is therefore part of the development loop, not only a bootstrap mechanism.

  1. 01
    Define the new fact Planned

    Add the parser, schema contract, provenance rules, and representative regression fixtures.

  2. 02
    Replay the offline archive Planned

    Run the new indexer against retained local XDR with notification delivery disabled and durable checkpoints enabled.

  3. 03
    Validate and publish Planned

    Compare coverage and invariants, then atomically expose the completed tables or serving snapshot.

  4. 04
    Continue from the live cursor Planned

    Hand the same normalized ledger input to the optimized indexer and use the archive path to recover any gap.

Documentation map

Use the component pages for implementation details, operating boundaries, and roadmap scope.