Deps: go-lib and docs

Author: aopoltorzhicky

CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Run all tests (requires Docker for PostgreSQL containers)
+make test
+# or: go test -p 8 -timeout 60s ./...
+
+# Run a single test
+go test -run TestCelestialsTestSuite/TestSync ./pkg/module/...
+
+# Lint
+make lint
+
+# Regenerate mocks and enums
+make generate
+```
+
+## Architecture
+
+This is a **Celestia blockchain indexing module** built on the [DipDup indexer SDK](https://github.com/dipdup-net/indexer-sdk). It scans for changes to Celestial IDs (blockchain domains) from an external API and persists them to PostgreSQL.
+
+### Data flow
+
+1. `Module` (pkg/module) runs a periodic sync loop (default: 1 min interval)
+2. Fetches changes from external API (`pkg/api/v1`) starting from the last known `change_id`
+3. Writes results to PostgreSQL in a transaction: upsert celestials → update state → flush
+4. `CelestialState` table tracks the last processed `change_id` to enable resumable syncing
+
+### Key packages
+
+- **`pkg/module`** — Core orchestration. `Module` embeds DipDup's `BaseModule` and implements the sync loop. Configured via `ModuleOption` functions (`WithIndexPeriod`, `WithLimit`, `WithDatabaseTimeout`). Accepts an `AddressHandler` callback to resolve blockchain addresses.
+- **`pkg/api`** — External Celestials API client interface + `v1/` HTTP implementation using fast-shot (rate-limited to 5 req/s).
+- **`pkg/storage`** — Storage interfaces (`ICelestial`, `ICelestialState`, `CelestialTransaction`) and status enum (`NOT_VERIFIED`, `VERIFIED`, `PRIMARY`).
+- **`pkg/storage/postgres`** — Bun ORM implementation. Uses PostgreSQL `ON CONFLICT DO UPDATE` for idempotent upserts. Status transitions: `PRIMARY → VERIFIED` when a new primary address is set for an existing celestial.
+
+### Testing
+
+Tests use `testcontainers` to spin up a real PostgreSQL 15.8 + TimescaleDB instance. Fixtures are loaded from `/test/*.yml` via go-testfixtures. Mocks for all interfaces are auto-generated via mockgen (stored in `pkg/*/mock/`).
+
+When adding new interfaces, add a `//go:generate mockgen ...` directive and run `make generate`.

README.md

@@ -1,2 +1,96 @@
-# Celestial module
-Package containig Celestials module for indexing its data
+# Celestial Module
+
+A Go module for indexing [Celestial IDs](https://celestials.id/) — domain names on the Celestia network. Built on top of the [DipDup Indexer SDK](https://github.com/dipdup-net/indexer-sdk) and designed to be embedded into an indexer as a standalone module.
+
+## What it does
+
+The module periodically polls the external Celestials API, fetches domain changes (registrations, address updates, status changes), and persists them to PostgreSQL. It tracks progress using a `change_id` — the module remembers the last processed identifier and resumes from that point on restart.
+
+## Requirements
+
+- Go 1.25+
+- PostgreSQL 15+ with the TimescaleDB extension
+- Docker (for running tests)
+
+## Installation
+
+```bash
+go get github.com/celenium-io/celestial-module
+```
+
+## Usage
+
+```go
+import (
+    "github.com/celenium-io/celestial-module/pkg/module"
+    "github.com/celenium-io/celestial-module/pkg/storage"
+    "github.com/celenium-io/celestial-module/pkg/storage/postgres"
+)
+
+m := module.New(
+    celestialsDatasource, // config.DataSource with Celestials API URL
+    addressHandler,       // func(ctx, address string) (uint64, error)
+    celestialsStorage,    // storage.ICelestial
+    stateStorage,         // storage.ICelestialState
+    transactable,         // sdk.Transactable
+    "my-indexer",         // indexer name for state tracking
+    "celestia",           // network name
+    module.WithIndexPeriod(30*time.Second),    // sync interval (default: 1 min)
+    module.WithLimit(200),                     // batch size (default: 100)
+    module.WithDatabaseTimeout(2*time.Minute), // DB operation timeout (default: 1 min)
+)
+
+m.Start(ctx)
+defer m.Close()
+```
+
+`AddressHandler` is a callback the module uses to resolve a string address into an internal address ID. It should be implemented on the indexer side.
+
+## Structure
+
+```
+pkg/
+├── api/            # External Celestials API client
+│   ├── v1/         # HTTP implementation (fast-shot, rate limited to 5 req/s)
+│   └── mock/       # Auto-generated mocks
+├── module/         # Core indexing module
+└── storage/        # Storage interfaces and data models
+    ├── postgres/   # Bun ORM implementation (PostgreSQL)
+    └── mock/       # Auto-generated mocks
+```
+
+## Data models
+
+**Celestial** — a domain name:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Domain identifier (PK) |
+| `address_id` | uint64 | Internal ID of the linked address |
+| `image_url` | string | Image URL |
+| `change_id` | int64 | ID of the last change |
+| `status` | enum | `NOT_VERIFIED`, `VERIFIED`, `PRIMARY` |
+
+**CelestialState** — sync state:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Indexer name (PK) |
+| `change_id` | int64 | Last processed change ID |
+
+## Development
+
+```bash
+# Run tests (requires Docker)
+make test
+
+# Lint
+make lint
+
+# Regenerate mocks and enum methods
+make generate
+```
+
+## License
+
+[MIT](LICENSE)

go.mod

@@ -5,9 +5,10 @@ go 1.25.7
 replace github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1
 
 require (
-	github.com/dipdup-net/go-lib v0.5.0
-	github.com/dipdup-net/indexer-sdk v0.0.9
-	github.com/go-testfixtures/testfixtures/v3 v3.16.0
+	github.com/dipdup-io/go-lib/config v1.0.0
+	github.com/dipdup-io/go-lib/database v1.0.0
+	github.com/dipdup-net/indexer-sdk v0.0.11
+	github.com/go-testfixtures/testfixtures/v3 v3.19.0
 	github.com/goccy/go-json v0.10.5
 	github.com/jackc/pgx/v5 v5.8.0
 	github.com/opus-domini/fast-shot v1.1.4
@@ -20,31 +21,34 @@ require (
 )
 
 require (
-	dario.cat/mergo v1.0.1 // indirect
+	dario.cat/mergo v1.0.2 // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/containerd/platforms v0.2.1 // indirect
 	github.com/cpuguy83/dockercfg v0.3.2 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dipdup-io/go-lib/hasura v1.0.0 // indirect
 	github.com/dipdup-io/workerpool v0.0.4 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/docker v28.0.4+incompatible // indirect
-	github.com/docker/go-connections v0.5.0 // indirect
+	github.com/docker/docker v28.5.1+incompatible // indirect
+	github.com/docker/go-connections v0.6.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
-	github.com/ebitengine/purego v0.8.2 // indirect
+	github.com/ebitengine/purego v0.8.4 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
-	github.com/gabriel-vasile/mimetype v1.4.8 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
-	github.com/go-playground/validator/v10 v10.26.0 // indirect
-	github.com/goccy/go-yaml v1.17.1 // indirect
-	github.com/gogo/protobuf v1.3.3 // indirect
+	github.com/go-playground/validator/v10 v10.30.1 // indirect
+	github.com/goccy/go-yaml v1.18.0 // indirect
+	github.com/golang/mock v1.7.0-rc.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
@@ -58,9 +62,10 @@ require (
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
+	github.com/moby/go-archive v0.1.0 // indirect
 	github.com/moby/patternmatcher v0.6.0 // indirect
-	github.com/moby/sys/sequential v0.5.0 // indirect
-	github.com/moby/sys/user v0.3.0 // indirect
+	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
 	github.com/moby/term v0.5.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
@@ -71,10 +76,10 @@ require (
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/puzpuzpuz/xsync/v3 v3.5.1 // indirect
-	github.com/shirou/gopsutil/v4 v4.25.1 // indirect
+	github.com/shirou/gopsutil/v4 v4.25.6 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
-	github.com/testcontainers/testcontainers-go v0.37.0 // indirect
-	github.com/testcontainers/testcontainers-go/modules/postgres v0.37.0 // indirect
+	github.com/testcontainers/testcontainers-go v0.40.0 // indirect
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0 // indirect
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/tmthrgd/go-hex v0.0.0-20190904060850-447a3041c3bc // indirect
@@ -90,9 +95,10 @@ require (
 	go.opentelemetry.io/otel/trace v1.40.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.1.0 // indirect
 	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/net v0.49.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260217215200-42d3e9bedb6d // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260217215200-42d3e9bedb6d // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )