sierpe

Sierpe is a self-hosted server that watches the Stellar network for the contracts a user registers and keeps their complete history in the operator's own Postgres database, exposed through a REST API and an embedded management UI. The project labels itself v1.5.2, with a design described as stable in docs/DESIGN.md, and states that events, contract state, token transfers, trustlines and token movements are feature-complete and run against testnet. What it indexes - Events emitted by registered contracts, discovered from each contract's on-chain spec and backfilled in chunks, then followed at the chain tip. - Contract state: the change history of storage entries plus a current snapshot. - Decoded token transfers (SEP-41 decoding, CAP-67 muxed) and the classic trustlines of SAC assets. - Token movements in or out of a contract, regardless of which contract emitted the transfer, with per-kind coverage reporting. - History below the RPC retention window: Stellar RPCs keep roughly seven days of events, so Sierpe backfills from genesis where sources allow and is designed to replay public History Archives for ranges no RPC serves; archive replay is provided via the `-full` image. How it is used Deployment is a container next to an empty Postgres. Contracts are registered at runtime as data, not code, through an authenticated call such as POST /v1/contracts with a contract ID and `from: genesis`; the server then classifies the contract, backfills its history and keeps following it. Users can query events with getEvents-v2-style filters (for example topic0 and cursors), the current storage snapshot for a key, and the history of any storage entry. Documentation lists Railway, Docker Compose and generic container deployments, and the README suggests the same binary runs on Railway, AWS, GCP or a small VPS, with a target cost under $10/month for a typical project. Requirements are Docker or Go 1.25+, with configuration through DATABASE_URL, NETWORK and ADMIN_TOKEN. API behaviour and honesty guarantees The README emphasises that coverage and gaps are first-class data: every response declares `coverage` and a `scanStatus` of HAS_MORE, WAITING_FOR_LEDGERS, OLDEST_REACHED or COMPLETE, so an empty page indicates either that nothing exists or that indexing has not reached that range. Pagination relies on opaque cursors that encode the whole query, intended to prevent drift. The full API surface is specified in docs/openapi.yaml and metrics are documented in docs/METRICS.md; a Grafana dashboard and status page are listed among the appliance deliverables. Interface and access control A management UI is embedded at `/` and there is a contract listing endpoint. An optional whole-surface Basic Auth mode is offered for deployments on public domains. Explicit non-goals The README states the project is not a hosted service, not an analytics platform (no aggregations or dashboards over user data), not a chain-wide indexer (only registered contracts are indexed), and not a framework — needing to write code to use it would be considered a bug. Roadmap Completed milestones cover the skeleton (config, health, migrations, cursor loop with continuity checks), events end-to-end, contract state, an appliance release v1.0.0, token transfers and SAC trustlines (v1.1), archive replay (v1.2), the embedded UI and contract listing (v1.3), optional Basic Auth (v1.4) and token movements with per-kind coverage (v1.5). Planned work includes contract-class discovery in v1.6, where registering a wasm hash indexes every contract deployed from it, and in v2 push delivery with signed webhooks and broker sinks, with an MCP server described as under exploration. Project material Documentation includes docs/DESIGN.md (architecture, data model, API surface, configuration, milestones), docs/DEPLOY.md, docs/KNOWLEDGE.md (29 principles distilled from production indexers, each with its source), CONTRIBUTING.md and SECURITY.md. The project is licensed under Apache-2.0 and invites issues and feedback.