Stress-test every node on the Sentinel dVPN chain. Admin-gated testing, public-read results.

What it does

Sentinel Node Tester discovers every active dVPN node on the Sentinel blockchain, opens real VPN sessions, measures actual throughput and protocol compliance, and records pass/fail results in a local SQLite database. A built-in Express dashboard lets an operator run audits and publish results. Public visitors can search and filter results — but only the operator can start or stop tests.

Core flow

Admin logs in at /admin, optionally flips the Broadcast Live toggle (controls whether public surfaces show the live in-flight audit or the last-completed snapshot), and starts an audit via POST /api/start. The continuous loop cycles through every online node; public visitors at / browse the node directory and at /live watch the real-time iteration feed via SSE — both are read-only. The operator stops the loop with POST /api/stop. No public user can trigger any test.

Routes

| Route | Who | Description | |-------|-----|-------------| | / | Public | Node directory — search, filter, sort, detail drawer. | | /live | Public | Real-time audit progress + results feed via SSE. | | /node/:addr | Public | Single-node result detail page. | | /admin (configurable) | Admin | Full control panel — start/stop audits, broadcast toggle, logs. | | /api/public/* | Public | Read-only JSON API: nodes, stats, countries, run summaries, SSE events. | | /api/start, /api/stop, /api/broadcast | Admin | Audit lifecycle + broadcast-live toggle. Admin session required. |

Quick start (local dev)

# 1. Clone
git clone https://github.com/Sentinel-Autonomybuilder/sentinel-node-tester.git
cd sentinel-node-tester

# 2. Install dependencies (downloads V2Ray binary for your platform)
npm install

# 3. Create .env and set MNEMONIC to your 12-word Cosmos phrase
cp .env.example .env

# 4. Start
#    Windows:    cscript //nologo SentinelAudit.vbs   (auto-elevates to Admin)
#    macOS:      sudo -E node server.js               (root for WireGuard)
#    Linux:      sudo -E node server.js
#    Any OS:     npm start                            (V2Ray-only, ~70% nodes)

Open http://localhost:3001 in your browser. No ADMIN_TOKEN needed for local dev — the admin surface defaults to unauthenticated (safe on localhost only).

WireGuard requires admin/root. Without elevation, V2Ray-only audits still run (~70% of nodes). Full setup walkthrough for all three platforms: SETUP.md.

CLI for scripting and AI agents

The sentinel-audit binary emits JSON on stdout for every command.

sentinel-audit serve              # Start dashboard (same as npm start)
sentinel-audit nodes --pretty     # List all active dVPN nodes as JSON
sentinel-audit balance            # Check wallet P2P balance
sentinel-audit test <sentnode1...>  # Test a single node end-to-end
sentinel-audit audit              # Full network audit across all nodes
sentinel-audit list               # Enumerate all subcommands
sentinel-audit functions --json   # Enumerate every exported SDK function

Full reference: docs/CLI.md

Audit modes

P2P (default)

Scans every active node on the Sentinel chain and opens a paid session on each. The tester wallet pays gas and bandwidth costs directly from its P2P balance. Suitable for full network audits. This is what POST /api/start does with no plan/subscription params.

Subscription / fee-granted

Pass subscriptionId + subscriptionGranter (or planId) to POST /api/start. Only nodes attached to that plan are scanned. Each session transaction is broadcast via broadcastWithFeeGrant using the plan operator's on-chain fee-grant allowance — the tester pays zero gas. This mirrors the flow used by commercial Sentinel apps where end users hold no P2P tokens.

TEST RUN

Pass testRun: true in the body or ?testRun=1 to POST /api/start. The pipeline skips chain operations and payments and writes a mode='test' run row. Used for demos and UI smoke checks. See CLAUDE.md — TEST RUN code paths are immutable.

Public deployment

Set ADMIN_TOKEN in .env to enable the admin login page. Generate a token:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Optionally change the admin path to something unguessable:

ADMIN_PATH=/my-secret-ops-panel

Put the application behind a reverse proxy (nginx, Caddy) that terminates HTTPS. The admin surface should not be reachable over plain HTTP in production. The Broadcast Live toggle (POST /api/broadcast) controls whether the public / and /live pages stream the in-flight audit or only the last-completed snapshot.

See docs/OPERATOR-RUNBOOK.md for the full deployment checklist.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MNEMONIC | Yes | — | 12-word Cosmos mnemonic. Signs session and gas transactions. Never commit to git. | | RPC | No | https://rpc.sentinel.co:443 | Primary RPC endpoint for chain queries and broadcasts. | | DENOM | No | udvpn | Token denomination. Do not change. | | GAS_PRICE | No | 0.2udvpn | Gas price for transactions. | | PORT | No | 3001 | HTTP port the server listens on. | | LISTEN_HOST | No | 127.0.0.1 | Bind address. Set 0.0.0.0 to expose on the network (with ADMIN_TOKEN). | | ADMIN_TOKEN | Recommended | — | Admin login password. If unset, admin surface is unauthenticated (localhost dev only). | | ADMIN_PATH | No | /admin | URL prefix for the admin panel. Change to an unguessable path in production. | | PUBLIC_MODE | No | false | When true, root path serves the public dashboard; admin moves to ADMIN_PATH. Requires ADMIN_TOKEN. | | INSECURE_COOKIE | No | false | Allow admin session cookies over HTTP (local dev only — production must use HTTPS). | | ENABLE_HSTS | No | false | Send Strict-Transport-Security header (set behind HTTPS proxy in production). | | LCD_ENDPOINTS | No | Built-in fallback | Comma-separated LCD URLs used only if RPC fails. | | DNS_SERVERS | No | unset | Comma-separated DNS IPs to use inside tunnels. | | NODE_DELAY_MS | No | 5000 | Milliseconds between node tests. Keep ≥ 5000 to avoid chain rate limits. | | MAX_NODES | No | 0 (all) | Cap on nodes tested per run. 0 = no limit. | | TEST_MB | No | 10 | Megabytes transferred per speed test. | | GIGABYTES_PER_NODE | No | 1 | Gigabytes allocated per opened session. | | ALLOW_PUBLIC_TEST | No | false | If true, public visitors can trigger a pre-configured test against PUBLIC_TEST_PLAN_ID / PUBLIC_TEST_SUB_ID / PUBLIC_TEST_SUB_GRANTER. Off by default — leave off unless you intend to spend your wallet on visitor traffic. | | WIREGUARD_PATH | No | auto-detected | Override the wg/wg-quick binary path on Linux/macOS. |

Architecture

Single Express process on port 3001. Two audit paths: audit/pipeline.js is the single-pass engine called by the admin "New Test" and "Retest Failed" buttons; audit/continuous.js wraps pipeline in a recursive loop with configurable inter-pass delay, emitting loop:* and iteration:* SSE events consumed by the public /live page. All results persist to audit.db (SQLite via better-sqlite3); raw per-run JSON lands in results/. The public SSE stream (/api/public/events) only forwards events while the broadcastLive toggle is on, and the redaction path strips wallet addresses, plan IDs, and fee-grant internals before fan-out.

For module dependency graph + per-stage flow, see ARCH.md. For decisions and "why we did X", see DECISIONS.md. For all reference docs, see docs/INDEX.md.

Testing this tool

npm test

License

MIT. Part of the Sentinel dVPN ecosystem.