Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rebrand to Checker Node. Closes #676 #677

Merged
merged 36 commits into from
Feb 19, 2025
Merged
Show file tree
Hide file tree
Changes from 35 commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
378babf
rebrand to `checker`. closes #676
juliangruber Feb 7, 2025
22d643e
fix
juliangruber Feb 7, 2025
ac1a0de
update
juliangruber Feb 7, 2025
c0a09e9
update
juliangruber Feb 7, 2025
9f91018
update
juliangruber Feb 7, 2025
3727ff8
update
juliangruber Feb 7, 2025
f4c5f03
fmt
juliangruber Feb 7, 2025
dbf2c15
update
juliangruber Feb 7, 2025
99a48fe
update
juliangruber Feb 7, 2025
ae19a1a
update
juliangruber Feb 7, 2025
9530b10
update module -> subnet (wip)
juliangruber Feb 7, 2025
c33da03
move source files fn to own lib
juliangruber Feb 7, 2025
ed1f1fe
all modules are binary now
juliangruber Feb 7, 2025
1c55de2
all modules are binary now
juliangruber Feb 7, 2025
1d42be1
more module -> subnet
juliangruber Feb 7, 2025
4362e14
finish module -> subnet
juliangruber Feb 7, 2025
ad6a3ba
fmt
juliangruber Feb 7, 2025
57a25a2
"binary module" -> "runtime"
juliangruber Feb 7, 2025
13dc1f2
clean up
juliangruber Feb 10, 2025
186bfb7
runtimes -> runtime
juliangruber Feb 10, 2025
9982614
Merge branch 'main' into update/checker-rebrand
juliangruber Feb 10, 2025
b560d7a
add migrate state root
juliangruber Feb 11, 2025
dc2ba56
log
juliangruber Feb 11, 2025
09dbe82
we need to migrate runtime state specifically
juliangruber Feb 11, 2025
f3eb6a5
fix paths
juliangruber Feb 11, 2025
fcd79fe
clean up
juliangruber Feb 11, 2025
999e86c
fix lint
juliangruber Feb 11, 2025
1e7534f
Merge branch 'main' into update/checker-rebrand
juliangruber Feb 11, 2025
1006f55
fix docs
juliangruber Feb 18, 2025
bd63e43
exit when legacy env var is used
juliangruber Feb 18, 2025
063d163
docs: add migration guide
juliangruber Feb 18, 2025
7be2b2c
refactor `exists` function
juliangruber Feb 18, 2025
dabd693
refactor
juliangruber Feb 18, 2025
8af91ae
fmt
juliangruber Feb 18, 2025
8da79de
Merge branch 'main' into update/checker-rebrand
juliangruber Feb 19, 2025
81b03aa
fix docs
juliangruber Feb 19, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .dockerignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
node_modules
modules
runtimes
npm-debug.log
28 changes: 14 additions & 14 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -73,50 +73,50 @@ jobs:
context: .
load: true
tags: core-test
cache-from: type=registry,ref=ghcr.io/filecoin-station/core
cache-from: type=registry,ref=ghcr.io/CheckerNetwork/node
cache-to: type=inline

- name: Build Docker image for other platforms
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/arm64
cache-from: type=registry,ref=ghcr.io/filecoin-station/core
cache-from: type=registry,ref=ghcr.io/CheckerNetwork/node
cache-to: type=inline

- name: Start Station Core container with PASSPHRASE
- name: Start Checker Node container with PASSPHRASE
run: |
docker run \
--name station \
--name checker \
--detach \
--env FIL_WALLET_ADDRESS=0x000000000000000000000000000000000000dEaD \
--env PASSPHRASE=secret \
$IMAGEID
env:
IMAGEID: ${{ steps.docker_build.outputs.imageid }}

- name: Print station activity
- name: Print checker activity
run: |
sleep 10 # Wait for Station modules to start
docker logs station
sleep 10 # Wait for Checker subnets to start
docker logs checker

- name: Check | Spark started
run: docker logs station | grep "Spark started"
run: docker logs checker | grep "Spark started"

- name: Start Station Core container without PASSPHRASE
- name: Start Checker Node container without PASSPHRASE
run: |
docker run \
--name station_unsecure \
--name checker_unsecure \
--detach \
--env FIL_WALLET_ADDRESS=0x000000000000000000000000000000000000dEaD \
$IMAGEID
env:
IMAGEID: ${{ steps.docker_build.outputs.imageid }}

- name: Print station activity
- name: Print checker activity
run: |
sleep 10 # Wait for Station modules to start
docker logs station_unsecure
sleep 10 # Wait for Checker subnets to start
docker logs checker_unsecure

- name: Check | Spark started
run: docker logs station_unsecure | grep "Spark started"
run: docker logs checker_unsecure | grep "Spark started"
6 changes: 3 additions & 3 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ jobs:
context: .
push: true
tags: |
ghcr.io/CheckerNetwork/core
ghcr.io/CheckerNetwork/core:${{ steps.package-version.outputs.current-version }}
ghcr.io/CheckerNetwork/node
ghcr.io/CheckerNetwork/node:${{ steps.package-version.outputs.current-version }}
platforms: linux/amd64,linux/arm64
cache-from: type=registry,ref=ghcr.io/CheckerNetwork/core
cache-from: type=registry,ref=ghcr.io/CheckerNetwork/node
cache-to: type=inline
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ typings/
# TernJS port file
.tern-port
.DS_Store
modules
runtimes

dist
.state
4 changes: 2 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
FROM node:22.13.1-slim
LABEL org.opencontainers.image.source=https://github.com/CheckerNetwork/core
LABEL org.opencontainers.image.source=https://github.com/CheckerNetwork/node
USER node
WORKDIR /usr/src/app
COPY . .
RUN npm ci --omit=dev
ENV DEPLOYMENT_TYPE=docker
CMD [ "./bin/station.js" ]
CMD [ "./bin/checker.js" ]
125 changes: 71 additions & 54 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,72 +3,73 @@
:artificial_satellite:
<br>
<br>
Station Core
Checker Node
<br>
<br>
<br>
</h1>

> Station Core is a headless version of Filecoin Station suitable for running on
> all kinds of servers.
> Checker Node is a node implementation for the
> [Checker Network](https://checker.network), suitable for running on all kinds
> of servers..

[![CI](https://github.com/filecoin-station/core/actions/workflows/ci.yml/badge.svg)](https://github.com/filecoin-station/core/actions/workflows/ci.yml)
[![CI](https://github.com/CheckerNetwork/node/actions/workflows/ci.yml/badge.svg)](https://github.com/CheckerNetwork/node/actions/workflows/ci.yml)

## Deployment

Station Core supports different deployment options:
Checker Node supports different deployment options:

- [Docker](#docker)
- [Manual Deployment (Ubuntu)](#manual-deployment-ubuntu)

## Installation

> **Note**: Station Core requires Node.js, we recommend using the latest LTS
> **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](https://nodejs.org/en/download/).

With Node.js installed, run `npm` to install Station Core.
With Node.js installed, run `npm` to install Checker Node.

```bash
$ npm install -g @filecoin-station/core
$ npm install -g @checkernetwork/node
```

## Usage

```bash
$ FIL_WALLET_ADDRESS=... PASSPHRASE=... station
$ FIL_WALLET_ADDRESS=... PASSPHRASE=... checker
```

## Common Configuration

Station Core is configured using environment variables (see
Checker Node is configured using environment variables (see
[The Twelve-Factor App](https://12factor.net/config)).

The following configuration options are shared by all Station commands:
The following configuration options are shared by all Checker commands:

- `$CACHE_ROOT` _(string; optional)_: Station stores temporary files (e.g.
- `$CACHE_ROOT` _(string; optional)_: Checker stores temporary files (e.g.
cached data) in this directory. Defaults to
- Linux: `${XDG_CACHE_HOME:-~/.cache}/filecoin-station-core`
- macOS: `~/Library/Caches/app.filstation.core`
- Windows: `%TEMP%/Filecoin Station Core`
- `$STATE_ROOT` _(string; optional)_: Station stores logs and module state in
- Linux: `${XDG_CACHE_HOME:-~/.cache}/checker-network-node`
- macOS: `~/Library/Caches/network.checker.node`
- Windows: `%TEMP%/Checker Network`
- `$STATE_ROOT` _(string; optional)_: Checker stores logs and subnet state in
this directory. Defaults to

- Linux: `${XDG_STATE_HOME:-~/.local/state}/filecoin-station-core`
- macOS: `~/Library/Application Support/app.filstation.core`
- Windows: `%LOCALAPPDATA%/Filecoin Station Core`
- 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 Station. This directory must not be shared with other computers
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

### `$ station`
### `$ checker`

Start a new Station process. The Station will run in foreground and can be
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
Expand All @@ -79,25 +80,25 @@ the configuration options described in
will receive rewards. The value must be a mainnet address starting with
`f410`, `0x`.

`f1` addresses currently are not supported. Rewards for Station operators are
`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 Station
- `PASSPHRASE` _(string; optional)_: a passphrase to protect the Checker
instance private key stored in a file inside the `STATE_ROOT` directory.

- `MODULE_FILTER` _(string; optional)_: Run only the Zinnia module with the
given name. Eg:
- `MODULE_FILTER=spark`
- `SUBNET_FILTER` _(string; optional)_: Run only the subnet with the given name.
Eg:
- `SUBNET_FILTER=spark`

This command outputs metrics and activity events:

```bash
$ station
$ checker
{
"totalJobsCompleted": 161,
"rewardsScheduledForAddress": "0.041033208757289921"
Expand All @@ -108,10 +109,10 @@ $ station
```

```bash
$ station --json
$ checker --json
{"type":"jobs-completed","total":161}
{"type":"activity:info","module":"Saturn","message":"Saturn Node will try to connect to the Saturn Orchestrator..."}
{"type":"activity:info","module":"Saturn","message":"Saturn Node was able to connect to the Orchestrator and will now start connecting to the Saturn network..."}
{"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..."}
...
```

Expand All @@ -120,56 +121,56 @@ For the JSON output, the following event types exist:
- `jobs-completed`
- `total`
- `activity:info`
- `module`
- `subnet`
- `message`
- `activity:error`
- `module`
- `subnet`
- `message`

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

No modules currently in experimental mode.
No subnets currently in experimental mode.

### `$ station --help`
### `$ checker --help`

Show help.

```bash
$ station --help
Usage: station [options]
$ checker --help
Usage: checker [options]

Options:
-j, --json Output JSON [boolean]
--experimental Also run experimental modules [boolean]
--recreateStationIdOnError Recreate Station ID if it is corrupted
--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]
```

### `$ station --version`
### `$ checker --version`

Show version number.

```bash
$ station --version
@filecoin-station/core: 1.0.1
$ checker --version
@checkernetwork/node: 1.0.1
```

## Docker

Deploy Station with [Docker](https://www.docker.com/). Please replace
Deploy Checker with [Docker](https://www.docker.com/). Please replace
`FIL_WALLET_ADDRESS` and ensure the passed `state` folder is persisted across
machine restarts.

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

## Manual Deployment (Ubuntu)
Expand All @@ -182,21 +183,21 @@ $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - &&\
sudo apt-get install -y nodejs

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

# Create systemd service
# Don't forget to replace FIL_WALLET_ADDRESS and User
$ sudo tee /etc/systemd/system/station.service > /dev/null <<EOF
$ sudo tee /etc/systemd/system/checker.service > /dev/null <<EOF
[Unit]
Description=Filecoin Station Core
Documentation=https://github.com/filecoin-station/core
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/station
ExecStart=/usr/bin/checker
Restart=always

[Install]
Expand All @@ -205,11 +206,11 @@ EOF

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

# Read logs
$ journalctl -u station.service
$ journalctl -u checker.service
```

## Disclaimer
Expand All @@ -224,3 +225,19 @@ Publish a new version:
```bash
$ 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`
Loading
Loading