🛰️

Checker Node

Checker Node is a node implementation for the Checker Network, suitable for running on all kinds of servers..

Deployment

Checker Node supports different deployment options:

• Docker
• Manual Deployment (Ubuntu)

Installation

Note: Checker Node requires Node.js, we recommend using the latest LTS version. You can install Node.js using your favorite package manager or get the official installer from Node.js downloads.

With Node.js installed, run npm to install Checker Node.

$ npm install -g @checkernetwork/node

Usage

$ FIL_WALLET_ADDRESS=... PASSPHRASE=... checker

Common Configuration

Checker Node is configured using environment variables (see The Twelve-Factor App).

The following configuration options are shared by all Checker commands:

• $CACHE_ROOT (string; optional): Checker stores temporary files (e.g. cached data) in this directory. Defaults to

  • Linux: ${XDG_CACHE_HOME:-~/.cache}/checker-network-node
  • macOS: ~/Library/Caches/network.checker.node
  • Windows: %TEMP%/Checker Network Node

• $STATE_ROOT (string; optional): Checker stores logs and subnet state in this directory. Defaults to

  • Linux: ${XDG_STATE_HOME:-~/.local/state}/checker-network-node
  • macOS: ~/Library/Application Support/network.checker.node
  • Windows: %LOCALAPPDATA%/Checker Network Node

  IMPORTANT: The$STATE_ROOT directory must be local to the computer running the Checker. This directory must not be shared with other computers operated by the user, e.g. via Windows Domain profile or cloud storage like iCloud Drive, Dropbox and OneDrive.

Commands

$ checker

Start a new Checker process. The Checker will run in foreground and can be terminated by pressing Ctrl+C.

This command has the following additional configuration in addition to common the configuration options described in Common Configuration:

• FIL_WALLET_ADDRESS (string; required): Address of the Filecoin wallet that will receive rewards. The value must be a mainnet address starting with f410, 0x.

  f1 addresses currently are not supported. Rewards for Checker operators are administered by a FEVM smart contract. It is currently technically complex to make payments to f1 addresses.

  If you just want to give core a quick spin, you can use the address 0x000000000000000000000000000000000000dEaD. Please note that any earnings sent there will be lost.

• PASSPHRASE (string; optional): a passphrase to protect the Checker instance private key stored in a file inside the STATE_ROOT directory.

• SUBNET_FILTER (string; optional): Run only the subnet with the given name. Eg:

  • SUBNET_FILTER=spark

This command outputs metrics and activity events:

$ checker
{
  "totalJobsCompleted": 161,
  "rewardsScheduledForAddress": "0.041033208757289921"
}
[4/19/2023, 9:26:54 PM] INFO  Saturn Node will try to connect to the Saturn Orchestrator...
[4/19/2023, 9:26:54 PM] INFO  Saturn Node was able to connect to the Orchestrator and will now start connecting to the Saturn network...
...

$ checker --json
{"type":"jobs-completed","total":161}
{"type":"activity:info","subnet":"Saturn","message":"Saturn Node will try to connect to the Saturn Orchestrator..."}
{"type":"activity:info","subnet":"Saturn","message":"Saturn Node was able to connect to the Orchestrator and will now start connecting to the Saturn network..."}
...

For the JSON output, the following event types exist:

• jobs-completed
  • total
• activity:info
  • subnet
  • message
• activity:error
  • subnet
  • message

Set the flag --experimental to run subnets not yet considered safe for production use. Run this at your own risk!

No subnets currently in experimental mode.

$ checker --help

Show help.

$ checker --help
Usage: checker [options]

Options:
  -j, --json                      Output JSON                          [boolean]
      --experimental              Also run experimental subnets        [boolean]
      --recreateCheckerIdOnError  Recreate Checker ID if it is corrupted
                                                                       [boolean]
  -v, --version                   Show version number                  [boolean]
  -h, --help                      Show help                            [boolean]

$ checker --version

Show version number.

$ checker --version
@checkernetwork/node: 1.0.1

Docker

Deploy Checker with Docker. Please replace FIL_WALLET_ADDRESS and ensure the passed state folder is persisted across machine restarts.

$ docker run \
	--name checker \
	--detach \
	--env FIL_WALLET_ADDRESS=0x000000000000000000000000000000000000dEaD \
        -v ./state:/home/node/.local/state/
	ghcr.io/CheckerNetwork/node

Manual Deployment (Ubuntu)

On a fresh Ubuntu machine:

# Install node.js
$ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - &&\
sudo apt-get install -y nodejs

# Install core
$ npm install -g @checkernetwork/node

# Create systemd service
# Don't forget to replace FIL_WALLET_ADDRESS and User
$ sudo tee /etc/systemd/system/checker.service > /dev/null <<EOF
[Unit]
Description=Checker Network Node
Documentation=https://github.com/CheckerNetwork/node
After=network.target

[Service]
Environment=FIL_WALLET_ADDRESS=XYZ
Type=simple
User=XYZ
ExecStart=/usr/bin/checker
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Start service
$ sudo systemctl daemon-reload
$ sudo systemctl start checker
$ sudo systemctl status checker

# Read logs
$ journalctl -u checker.service

Disclaimer

The CLI uses Sentry for error tracking. InfluxDB is used for stats.

Development

Publish a new version:

$ npm run release

Migration guide from Station Core

Station Core was recently rebranded to Checker Node. Read more here: https://blog.checker.network/posts/why-web3-needs-the-checker-network

Here is what changed:

• Node module @filecoin-station/core is now @checkernetwork/node
• CLI core is now checker
• Environment variable MODULE_FILTER is now SUBNET_FILTER
• CLI flag --recreateStationIdOnError is now --recreateCheckerIdOnError
• Activity event property .module is now .subnet
• Default state and cache paths have changed. However, when Checker Node detecs that, it will perform an automatic migration
• Repository filecoin-station/core is now checkernetwork/node