Reference / Data model

Separate chain facts, attribution, projections, and delivery state.

Stargazer stores the smallest durable facts required to prove a relationship or change, while the raw archive preserves everything needed for later decoding. Human labels, protocol semantics, wallet rankings, and notification state live in separate layers with different trust boundaries.

01 / Storage layers

Four stores, four purposes.

Layer 1 · Evidence

Raw Galexie archive

Immutable compressed ledger objects. The durable fallback when a new field must be parsed.

Layer 2 · Historical facts

Compact SQLite database

Ordered ledgers, retained contract transactions, graph edges, attribution roots, and executable history.

Layer 3 · Read projection

Serving SQLite database

Wallet activity totals and ranking indexes rebuilt from exact historical edges.

Layer 4 · User control

Alert-control database

Telegram pairing, alert policy, and entitlement state. It never rewrites ledger evidence.

02 / Compact schema

Append-efficient facts and small indexed histories.

Checkpoint and provenance

compact_meta compact_ledgers

Network binding, ledger hash chain, close time, archive path, and retained counts.

Transaction graph

contract_transactions transaction_wallets transaction_contracts transaction_wallet_contracts wallet_contracts

Attribution and usage

protocols protocol_contracts transaction_protocols protocol_usage contract_usage

Contract lifecycle

contract_executable_history contract_current_executable contract_availability_events contract_code

Large account-first and ranking indexes are intentionally omitted during bulk ingestion. The post-backfill finalizer builds them in a separate serving generation, avoiding random index maintenance on the historical hot path.

03 / Exact relationships

A transaction participant is not automatically a protocol user.

Stargazer creates a wallet-to-contract edge only from one of two evidence paths:

Effective operation source. A direct contract call links to that operation's explicit source, or to the transaction source when no operation source exists.
Soroban authorization subtree. An authorized account links only to contracts actually present inside its authorization subtree.

Fee-only participants, event-only touches, diagnostic-only touches, and executable-version observations remain valid transaction evidence but do not invent a wallet dependency. Muxed accounts normalize to their base G... identity while preserving the distinction in raw evidence.

04 / Transaction identity

Store the hash needed for retrieval, not a misleading “signature.”

The durable identifier is Stellar's canonical 32-byte transaction hash. A transaction envelope can contain several decorated signatures, so “transaction signature” is not a unique retrieval key. The compact database stores the hash, ledger sequence, apply order, success flag, and archive path.

Old RPC calls may fall outside provider retention. The local archive coordinates are therefore the authoritative retrieval path for historical transaction evidence.

05 / Protocol attribution

Labels require a source.

Attributed

A contract exactly matches a source-backed registry root with a protocol name, role, and optional source URL. A protocol is counted at most once per transaction.

Unattributed

The contract remains queryable using its checksum-valid C... address. Stargazer does not hide it or invent a project identity.

Factory-child expansion, ownership inference, and time-valid registry mappings remain roadmap work. A materially changed registry currently requires a fresh compact database to avoid stale mappings.

06 / Contract versions

An upload is not an upgrade.

Observation	Stored meaning	Alert meaning
Wasm upload	Code hash and first observed provenance	Precursor only; no instance changed
First state in a bounded window	Non-exact baseline, active before the window	Not presented as a deployment or upgrade
Created or changed executable	Chronological instance executable transition	Eligible upgrade evidence
Restoration with same executable	Availability event only	Not an upgrade
Removal	Availability event; history is preserved	Lifecycle signal

The current implementation treats the contract-instance ledger diff as canonical. Corroborating that transition with the system executable_update event remains a later normalization step.

07 / Alert provenance

Every alert should say how it was produced.

Archive-derived transition: Deterministic executable history reconstructed from retained ledgers.
Historical incident finding: A bounded, versioned correlation rule with replay coverage and delivery disabled.
Forward controller alert: A post-execution Classic account policy or activity change from the governance watcher.
Future live finding: A committed live-ledger rule result eligible for an outbox and user delivery policy.

AI-generated explanation is never the evidence boundary. It may summarize a deterministic finding, but the underlying coordinates, parser version, primary sources, and coverage limits remain the verifiable record.