System / Architecture
One evidence pipeline, two ingestion paths.
Stargazer starts with an offline, locally retained Stellar archive. That archive is where indexing logic is developed, benchmarked, and replayed. The live service will feed newly closed ledgers into the same logical processing boundary so historical and real-time results do not drift apart.
01 / Implemented path
Archive replay produces the evidence database.
- 01
Local Galexie archive Implemented Immutable per-ledger XDR retained on the NAS.
- 02
Bounded decode Implemented Streaming zstd/XDR decode with a fixed worker and queue budget.
- 03
Indexing core Implemented Deterministic facts, exact relationships, versions, and ordered commits.
- 04
SQLite evidence stores Implemented Compact history plus an atomically published wallet serving snapshot.
- 05
Read API and demo Implemented Bounded read-only queries served through the Stargazer product.
The raw Galexie files remain the durable source of truth. Derived databases are disposable: they can be deleted, rebuilt from the archive, and compared across parser versions without downloading the source data again.
02 / Target path
Live ingestion joins before indexing logic.
- 01
RPC or Captive Core Planned Acquire recent and newly closed LedgerCloseMeta records.
- 02
Normalized ledger input In progress Give archive and live sources one versioned processing boundary.
- 03
Shared indexing modules Planned Run the same tested fact and protocol logic used during backfill.
- 04
Atomic checkpoint Planned Advance the live watermark only after facts and findings commit.
- 05
Alert delivery Planned Dispatch committed findings to subscribed users after policy checks.
Only acquisition should know whether a ledger came from the local archive, an RPC backend, or Captive Core. Once decoded, the same network coordinates, fact extraction, protocol modules, and rules should process it. This is the main architectural step still to implement.
03 / Trust boundaries
Each service has one reason to write.
| Boundary | Responsibility | Write access | Status |
|---|---|---|---|
| Archive acquisition | Retain immutable Galexie ledger objects and completion markers. | Raw archive only | Implemented |
| Archive indexer | Validate continuity, extract facts, and append ordered batches. | Compact evidence DB | Implemented |
| Wallet finalizer | Build account-oriented aggregates without mutating the evidence store. | New serving DB | Implemented |
| Read API | Validate schemas and answer bounded, deadline-limited queries. | None | Implemented |
| Alert control | Pair Telegram identities and store user policy separately. | Dedicated control DB | Pairing implemented |
| Live ledger service | Acquire, checkpoint, recover gaps, and submit normalized ledgers. | Checkpoint and event store | Planned |
04 / Deployment
Storage stays local; the public edge stays narrow.
NAS / private network
- Raw compressed Stellar archive
- Rust archive reader and wallet finalizer
- Compact and serving SQLite databases
- Read-only API and governance snapshots
Cloudflare / public edge
- SvelteKit website and server-rendered demo
- Allowlisted GET/HEAD gateway routes
- Private service binding to the NAS tunnel
- No public database or archive filesystem access
05 / Design rules
Properties the implementation must preserve.
- Evidence is replayable. Every derived fact points back to a network, ledger, transaction, and local archive path.
- Commits stay ordered. Decode may run concurrently; database state advances in deterministic ledger order.
- Backfill is silent. Historical findings are retained for review but never delivered as new live alerts.
- Unknown remains unknown. Unattributed contracts keep their on-chain address instead of receiving an invented label.
- Source and product state are separate. The read path cannot mutate evidence, and alert policy cannot rewrite chain facts.