Hardfork Upgrade Tracking

This project provides a simple server to track the upgrade status of nodes in a network. It exposes a web-based dashboard to visualize the upgrade progress and an API for nodes to submit their status.

Prerequisites

• Node.js (v18 or newer)
• npm
• A PostgreSQL database. You can easily set one up for free on Neon.

1. Setup

1. Clone the repository:

   git clone https://github.com/o1-labs/hardfork-upgrade-tracking
   cd hardfork-upgrade-tracking

2. Install dependencies:

   npm install

3. Set up environment variables:

   Create a .env file by copying the example file:

   cp .env.example .env

   Edit the .env file and set the DATABASE_URL to your PostgreSQL connection string. For example:

   DATABASE_URL="postgresql://user:password@localhost:5432/hardfork_tracking?schema=public"
   

   You can also optionally change the RELEASE_PERCENTAGE.

4. Apply the database schema:

   Run the following command to create the tables in your database:

   npx prisma db push

   Alternatively, you can use migrations:

   npx prisma migrate dev

2. Running the Project

Development Mode

You can run the server in development mode, which will automatically restart on file changes:

npm run dev

The server will start on http://localhost:3000.

Production (Node.js)

Build the project first and then start the server:

npm run build
npm run start

Production (Docker)

Docker images are published to GitHub Container Registry at ghcr.io/o1-labs/hardfork-upgrade-tracking.

Pull and run a pre-built image:

docker run --rm -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:password@host:5432/db" \
  -e RELEASE_PERCENTAGE="65" \
  ghcr.io/o1-labs/hardfork-upgrade-tracking:latest

Build locally using the Makefile:

# Using Docker
make build

# Using Podman
make podman-build

Run the locally built image:

# Using Docker
DATABASE_URL="postgresql://user:password@host:5432/db" RELEASE_PERCENTAGE=65 make run

# Using Podman
DATABASE_URL="postgresql://user:password@host:5432/db" RELEASE_PERCENTAGE=65 make podman-run

The container automatically runs prisma db push on startup to apply the database schema.

Demo environment with podman-compose:

A complete demo environment with PostgreSQL and optional Mina node is available in the demo/ directory:

cd demo

# Start tracker with postgres
podman-compose up -d

# Or include a Mina daemon that submits stats
podman-compose --profile with-mina up -d

See demo/README.md for full instructions.

Available image tags:

Tag Pattern	Description
latest	Latest release (from git tags)
v1.0.0	Specific release version
1.0.0-abc1234	Push to master (version + commit SHA)
pr-123-abc1234	Pull request build (PR number + commit SHA)

3. Viewing the UI

Once the server is running, you can view the dashboard by opening your web browser and navigating to:

http://localhost:3000/

The dashboard displays the current upgrade progress of the network.

4. Submitting Data

Nodes can submit their status by sending a POST request to the /submit/stats endpoint.

Endpoint

POST /submit/stats

Request Body

The request body must be a JSON object with the following structure:

{
  "max_observed_block_height": 8392,
  "commit_hash": "a1b2c3d4",
  "chain_id": "mainnet",
  "peer_id": "12D3KooWL7tVWT3LpBDv3p5bLNKm2w5V51s1A4Q4Zg4Q4Yq4b4Q4",
  "peer_count": 10,
  "timestamp": "2026-01-26T10:00:00.000Z",
  "block_producer_public_key": "B62q..."
}

Example curl command

curl -X POST http://localhost:3000/submit/stats \
-H "Content-Type: application/json" \
-d '{
  "max_observed_block_height": 8392,
  "commit_hash": "a1b2c3d4",
  "chain_id": "mainnet",
  "peer_id": "12D3KooWL7tVWT3LpBDv3p5bLNKm2w5V51s1A4Q4Zg4Q4Yq4b4Q4",
  "peer_count": 10,
  "timestamp": "2026-01-26T10:00:00.000Z",
  "block_producer_public_key": "B62qrPN5Y5yq8kGE3FbVKbGTdTAJNdtNtS5sKqLYxhYGDzuDv2VRvgH"
}'

Other API Endpoints

• GET /submit/stats: gets all stats
• GET /submit/stats/:peerId: gets stats for a specific peer