sorolens

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 9)

Observability toolkit for Soroban smart contracts: events, storage TTL, invocation health.

sorolens Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![CI](https://github.com/sorolens/sorolens/actions/workflows/ci.yml/badge.svg)](https://github.com/sorolens/sorolens/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/sorolens/sorolens/main/LICENSE)
[![Release](https://img.shields.io/github/v/release/sorolens/sorolens)](https://github.com/sorolens/sorolens/releases)
# Sorolens
Indexed observability for Soroban smart contracts: events, invocations, resource metrics, and storage TTL health in one place.
---
## The problem
### Soroban's public RPC retains events for 24 hours and transaction data for up to 7 days. There is no persistent index of what your contract did, what it cost, or which storage entries are close to expiring. The Stellar Lab contract explorer is excellent for point-in-time inspection but has no history, no API, and no alerting. Sorolens fills that gap.
---
## What it does
- Indexes events, invocations, and storage entries for any tracked Soroban contract into Postgres.
- Exposes a REST API (`/api/v1`) queryable by your backend or CI pipeline.
- Shows decoded event topics and values, per-invocation resource metrics (CPU instructions, memory, ledger bytes, fee charged), and storage TTL health in a Next.js dashboard.
- Alerts when persistent storage entries are within a configurable number of ledgers of expiry.

## Quickstart
### Prerequisites
- Docker and Docker Compose
- Go 1.23+
- Node 22+ and pnpm 9+
### 1. Start local dependencies
```bash
docker compose up -d
```
This starts Postgres 16 and Redis locally. The `docker-compose.yml` at the repo root maps Postgres to `localhost:5432` and Redis to `localhost:6379`.
### 2. Apply the database schema
```bash
cd services/indexer
go run ./cmd/migrate up
```
### 3. Track a contract and run the indexer
```bash
# Register a contract (uses the local API)
go run ./cmd/sorolens track CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC --network testnet
# Run one indexer cycle manually
go run ./cmd/sorolens index --once
```
The dashboard is at `http://localhost:3000` after `pnpm dev` in `apps/web`.
---
## How to contribute

1. **Find an issue** – Browse the [open issues](https://github.com/sorolens/sorolens/issues) and pick one that interests you. Look for labels like `good first issue` or `help wanted`.
2. **Claim it** – Comment "I'd like to work on this" on the issue. A maintainer will assign it to you.
3. **Open a PR** – Follow the branch naming and commit conventions in [CONTRIBUTING.md](./CONTRIBUTING.md) and open a pull request against `main`.

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full walkthrough, including local setup, running tests, and the PR checklist.
---
## Architecture

> See `ARCHITECTURE.md` for the full system diagram, data flows, schema DDL, and REST API reference.
---
## Tech stack
| Layer | Technology |
|---|---|
| API | Go 1.23, chi, pgx v5, deployed as Vercel serverless functions |
| Indexer | Go 1.23, runs as a GitHub Actions scheduled workflow (5-minute cron) |
| Database | Postgres 16, hosted on Neon |
| Cache / locks | Redis, hosted on Upstash |
| Dashboard | Next.js 15, TypeScript, Tailwind CSS, deployed on Vercel |
| XDR decoder | TypeScript package (`packages/xdr`), wraps `@stellar/stellar-sdk` |
| CLI | Go 1.23, cobra |
| Fixture contract | Rust (stable), Soroban SDK, deployed to Stellar testnet |
---
## Monorepo layout
```
sorolens/
  apps/
    api/          Go API (Vercel serverless functions)
    web/          Next.js 15 dashboard
  services/
    indexer/      Go indexer worker
  packages/
    xdr/          TypeScript XDR decoder
  cli/            Go CLI (cobra)
  contracts/
    counter/      Rust Soroban fixture contract
  docs/
    screenshots/  Screenshot placeholders
```
---
## Contributing
### See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, branch conventions, commit format, and a full walkthrough of adding a new XDR type decoder.
---
## Code of conduct
### See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
---

## Contributors

Thanks to everyone who has contributed to Sorolens!

[![Contributors](https://contrib.rocks/image?repo=sorolens/sorolens)](https://github.com/sorolens/sorolens/graphs/contributors)

## License
MIT. See [LICENSE](./LICENSE).

sorolens

sorolens Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

sorolens

sorolens Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README