filecoin-network-stats is a visual interface for tracking the state of the Filecoin network. This repository contains two sub projects: the dashboard itself (located in frontend), and a stat collection server (located in backend).

By default, all stats on the frontend are cached for 1 minute unless otherwise noted. The stats collection server waits 4 blocks before considering a block to be 'finalized,' and so will appear to be behind the tip of the chain.

The filecoin-network-stats frontend is a React/Redux application written in Typescript. It uses AmCharts4 as its charting library. To start the frontend, run the following commands from within the frontend directory:

npm install
npm run dev

npm run dev will point the frontend to a local backend running on port 8081. To point to a different backend, run the following command instead:

BACKEND_URL=<your-backend-url> webpack-dev-server --hot

The dashboard updates itself via a polling loop that hits the backend's /sync endpoint every 5 seconds. This was chosen over WebSockets due to simplicity, and how it allows non-browser clients to query the backend's data as well without having to open a persistent connection.

debug leaks memory when new instances are called in a loop. Since numerous transitive dependencies of this project do that, the postinstall script replaces debug with a no-op version.

The app's backend is a Node.js application written in Typescript. It talks to a Postgres database and a local go-filecoin full node. The backend will by default listen for heartbeats on port 8080, and incoming API requests on port 8081. To get started running the backend, start by installing dependencies and compiling the application:

cd backend
npm i
npm run build

To start the backend, first create a .env file with the following environment variables in the backend directory:

export DB_URL=<your-postgres-url>
export FULL_NODE_URL=<your-full-node-url>
export IS_MASTER=true
export PEER_INFO_FILE=./peerId.json
export HEARTBEAT_PORT=8080
export API_PORT=8081
export LOG_LEVEL=info

Then, create a peerId.json by running the following command from your backend directory:

node -e "require('peer-id').create({ bits: 1024 }, (err, id) => { if (err) { throw err; } console.log(JSON.stringify(id.toJSON(), null, 2))})" > peerId.json

The above steps only need to be performed on fresh installations. Next, you'll need to migrate the database via the following command:

DATABASE_URL=<your database url> db-migrate up

Now you're ready to start your node:

source ./.env && node ./dist/src/main.js

That's it! You're off to the races. To collect statistics on node counts and locations, ask miners to set their node's heartbeatUrl and nickname, like this:

go-filecoin config heartbeat.nickname '"Pizzanode"'
go-filecoin config heartbeat.beatTarget "/dns4/<your-backend-domain-name>/tcp/8080/ipfs/<your-peer-id>"

The backend exposes a REST API for some stats:

The dashboard uses these to populate historical graphs when the user toggles between timeframes. You can also make a GET request to /sync to retrieve all of the stats that the dashboard uses to update itself.

For more information about the backend, check out docs/backend.md.

You may find it easier to npm link the filecoin-network-stats-common dependency if you're actively developing. To do so, run these commands from the root of the repo:

cd common
npm run build
npm link
cd ../frontend
npm link filecoin-network-stats-common
cd ../backend
npm link filecoin-network-stats-common

Then, run npm run build from the common directory whenever you make changes to common dependencies. This prevents you from having to re-run npm install every time you change something in common.