Project overview

Project overview

NodeSentinel is a lightweight beacon chain indexer and monitoring platform for Ethereum and Gnosis beacon chains. It collects, normalizes, and processes validator-related data from the Consensus Layer via standard Beacon node APIs and enriches it with Execution Layer data when needed.

Packages

• packages/db: Prisma schema and migrations. See packages/db/AGENTS.md for data organization and storage.
• packages/beacon-utils: Shared beacon chain utilities (BeaconTime, chain config, validator status types).
• packages/indexer: Core indexing service. See packages/indexer/AGENTS.md.
• packages/api: REST/API layer. See packages/api/AGENTS.md.
• packages/webapp: Next.js frontend. See packages/webapp/AGENTS.md.
• packages/telegram-bot: Telegram bot for alerts.

Global setup

• Install deps: pnpm install
• Run all tests: pnpm test
• Run e2e tests: pnpm test:e2e:local (from outside of a sandbox)
• Lint: pnpm lint
• Type-check: pnpm type-check is defined in the root and also on each package.

Docs

• docs: project docs. See docs/.

E2E Tests

Run e2e tests only from the repo root with pnpm test:e2e:local. Never run e2e tests directly with package scripts, Vitest, .env, or custom DB credentials. If the root command cannot be used, stop and ask.

E2E Test Documentation

Every end-to-end test must include clear comments explaining what the test does.

• Each test block (describe, test, it, etc.) should include a high-level comment describing the scenario being tested.
• Inside the test, every significant line or block should have a short comment explaining its purpose.

A developer should be able to fully understand the intent and flow of the test by reading the comments, without having to infer or guess behavior from the code itself.

GitHub workflow

• When creating pull requests, do not prefix the title with [codex].

Best practices

• Every code block must include clear comments explaining its purpose. Comments should be sufficient for a developer to understand the logic without reading the code itself.
• Every function must have a short comment summarizing what it does.
• Comments must be simple, easy to understand, direct and describe the local code only
• Do not move chat context, refactor history, or temporary reasoning into durable code comments.
• Do not mix reusable helpers with feature logic. Move reusable formatting, parsing, calculation, or conversion helpers to a shared utils module with generic names and interfaces.

Agent

• NEVER do changes without confirmation.

Communication

• Be brutally concise.
• Answer the exact question only.
• No preambles.
• No extra context.
• No alternatives unless asked.
• No "it depends" unless strictly necessary.
• State facts first.
• Then, if useful, add one supporting code reference.