Skip to main content
Version: gemini-1b-2022-jul-27

Farming with the CLI

caution

Update from earlier versions of Gemini 1b

There were some issues in initial Gemini 1b release gemini-1b-2022-june-02 fixed by later releases.

If you see any of these errors:

  • Node is running on non-canonical fork, full node and farmer reset is required
  • Attempt to switch to a different fork beyond archiving depth, can't do it...

That means your node is affected, and you need to follow "Switching to a new snapshot" section below to reset your node and farmer.

I. Pre-requisites


A. System Requirements

Network Warning

You will also want to ensure you have a stable Network connection. It is also important to note that plotting can be network intensive and may impact network usage if you have a hard data limit.

HardwareSpecs
CPU2 Core+
RAM4GB+ (Rec. 8GB)
Storage - Node60GB
Storage - Plot4KB+

B. Polkadot.js wallet

Before running anything you need to have a wallet where you'll receive testnet coins.

Install Polkadot.js extension into your browser and create a new account there. The address of your account will be necessary at the last step.

For help refer to our forum post How to setup a Polkadot.JS Wallet

  • make sure to follow the Bonus section of the bottom of the post above.

C. Archival or Full Node?

There is was a bug in prior versions. If you were running a version prior, and would like to switch to a Full Node, you will need to follow the wipe & purge instructions.

Before starting your node you will want to decide if you are going to run an Archival or Full node.

Full Node: This will only keep the last 1024 blocks. As a result the node will take up significantly less space, leaving more space for farming plot. Archival Node: This will keep the full history of the network on your device. As a result the node will take up more space and continue to grow.

  • Running an archival node will significantly help new users trying to sync the network.
  • Archival nodes are also helpful if you want to run your node as an RPC node for historical queries etc.

The default instructions below will assume you would like to be a full node. If you would like to run an Archival node remove the following parameters from your node command.

  • --pruning 1024
  • --keep-blocks 1024

And instead add this:

  • --pruning archive

NOTE: You can't switch between full and archival node without wiping it, so if you need that, follow steps in the Wipe & Purge section.

D. Required ports

Currently, TCP port 30333 needs to be exposed for node to work properly.

If you have a server with no firewall, there is nothing to be done, but otherwise make sure to open TCP port 30333 for incoming connections.

On the desktop side if you have a router in front of your computer, you'll need to forward TCP port 30333 to the machine on which your node is running (how this is done varied from router to router, but there is always a feature like this, refer to How to Forward Ports for a more in-depth tutorial). If you're connected directly without any router, then again nothing needs to be done in such case.

II. Installation


Looking for all Releases?

You can always find these executables in the Releases section on our GitHub

OpenCL support

If you use farmer executable starting with subspace-farmer-opencl- and see this error:

The code execution cannot proceed because OpenCL.dll was not found. Reinstalling the program may fix this problem.

Or farmer exits in CLI without any messages, it means you don't have OpenCL-capable GPU or drivers installed. Installing OpenCL GPU drivers or using farmer executable without opencl in file name will fix the issue.

We will be downloading two files for your respective operating system.

  1. Subspace-Node - This is the executable that actually makes the connection with the Subspace Network
  2. Subspace-Farmer - This is the executable that will actually farm for rewards on your allocated storage plot.
  • There is also an OpenCL option in case you have OpenCL-capable AMD, Intel or Nvidia GPU
  • Those using Docker will not have to download anything, just configure the docker-compose.yml
  1. Create subspace directory and docker-compose.yml in it with following contents:

    version: "3.7"
    services:
    node:
    # Replace `snapshot-DATE` with latest release (like `snapshot-2022-apr-29`)
    # For running on Aarch64 add `-aarch64` after `DATE`
    image: ghcr.io/subspace/node:snapshot-DATE
    volumes:
    # Instead of specifying volume (which will store data in `/var/lib/docker`), you can
    # alternatively specify path to the directory where files will be stored, just make
    # sure everyone is allowed to write there
    - node-data:/var/subspace:rw
    # - /path/to/subspace-node:/var/subspace:rw
    ports:
    # If port 30333 is already occupied by another Substrate-based node, replace all
    # occurrences of `30333` in this file with another value
    - "0.0.0.0:30333:30333"
    restart: unless-stopped
    command: [
    "--chain", "gemini-1",
    "--base-path", "/var/subspace",
    "--execution", "wasm",
    "--pruning", "1024",
    "--keep-blocks", "1024",
    "--port", "30333",
    "--rpc-cors", "all",
    "--rpc-methods", "safe",
    "--unsafe-ws-external",
    "--validator",
    # Replace `INSERT_YOUR_ID` with your node ID (will be shown in telemetry)
    "--name", "INSERT_YOUR_ID"
    ]
    healthcheck:
    timeout: 5s
    # If node setup takes longer then expected, you want to increase `interval` and `retries` number.
    interval: 30s
    retries: 5

    farmer:
    depends_on:
    node:
    condition: service_healthy
    # Replace `snapshot-DATE` with latest release (like `snapshot-2022-apr-29`)
    # For running on Aarch64 add `-aarch64` after `DATE`
    image: ghcr.io/subspace/farmer:snapshot-DATE
    # Un-comment following 2 lines to unlock farmer's RPC
    # ports:
    # - "127.0.0.1:9955:9955"
    # Instead of specifying volume (which will store data in `/var/lib/docker`), you can
    # alternatively specify path to the directory where files will be stored, just make
    # sure everyone is allowed to write there
    volumes:
    - farmer-data:/var/subspace:rw
    # - /path/to/subspace-farmer:/var/subspace:rw
    # If port 40333 is already occupied by something else, replace all
    # occurrences of `40333` in this file with another value
    - "0.0.0.0:40333:40333"
    restart: unless-stopped
    command: [
    "--base-path", "/var/subspace",
    "farm",
    "--node-rpc-url", "ws://node:9944",
    "--ws-server-listen-addr", "0.0.0.0:9955",
    "--listen-on", "/ip4/0.0.0.0/tcp/40333",
    # Replace `WALLET_ADDRESS` with your Polkadot.js wallet address
    "--reward-address", "WALLET_ADDRESS",
    # Replace `PLOT_SIZE` with plot size in gigabytes or terabytes, for instance 100G or 2T (but leave at least 60G of disk space for node and some for OS)
    "--plot-size", "PLOT_SIZE"
    ]
    volumes:
    node-data:
    farmer-data:
  2. Now edit created file:

    a. Replace INSERT_YOUR_ID with desired name that will be shown in telemetry (doesn't impact anything else)

    b. Replace WALLET_ADDRESS with your wallet address

    c. Replace PLOT_SIZE with plot size in gigabytes or terabytes, for instance 100G or 2T (but leave at least 10G of disk space for node)

    If you want to store files on a separate disk or customize port, read comments in the file.

  3. Now go to directory with docker-compose.yml and type docker-compose up -d to start everything

    You can read logs with docker-compose logs --tail=1000 -f, for the rest read Docker Compose CLI reference.

III. Post Node & Farmer Install Care


Now that your Node & Farmer have been started you will wait for the node to sync and the farmer to complete the initial plotting. While this is occuring you can check out some of the helpful resources below.

- Telemetry Server

- Block Explorer

Using a Custom Path

You can set a custom path for your node & farmer to use if you want to use an external hard drive, or set a custom path from the default. You can set the node and farmer to different directories if you would like.

Set Node Custom Path.

To set your node to use a custom path all you will need to do is add the --base-path parameter after the --chain parameter.

Example:

.\subspace-node-ubuntu-x86_64-gemini-1b-2022-jul-27 --chain gemini-1 --base-path /path/to/directory/here --execution wasm --pruning 1024 --keep-blocks 1024 --validator --name INSERT_YOUR_ID

Switching to a new snapshot

info

Unless specifically mentioned by the Development team you should NOT have to wipe & purge your configuration on new releases.

In general you should be able to download the latest release, and re-start the Node & Farmer with the same commands as you started to prior version with no errors.

There are some cases where version updates will cause issue with your Node & Farmer and you may have to wipe & purge your node, typically when errors occur. If you have any issues you can always check our Forums and hop in our Discord Server to ask for help.

Wipe & Purge

If you were running a node previously, and want to switch to a new snapshot, please perform these steps and then follow the guideline again:

# Replace `FARMER_FILE_NAME` with the name of the node file you downloaded from releases
./FARMER_FILE_NAME wipe
# Replace `NODE_FILE_NAME` with the name of the node file you downloaded from releases
./NODE_FILE_NAME purge-chain --chain gemini-1

Does not matter if the node/farmer executable is the previous one or from the new snapshot, both will work :) The reason we require this is, with every snapshot change, the network might get partitioned, and you may be on a different genesis than the current one. In plain English, these commands are like a reset button for snapshot changes.

Now follow installation guide.

Docker Wipe & Purge

In case of Docker setup run docker-compose down -v (and manually delete custom directories if you have specified them).

Now follow installation guide.

Help

There are extra commands and parameters you can use on farmer or node, use the --help after any other command to display additional options.

Below are some helpful samples:

  • ./FARMER_FILE_NAME --base-path /path/to/data farm ... : will store data in /path/to/data instead of default location
  • ./FARMER_FILE_NAME --base-path /path/to/data wipe : erases everything related to farmer if data were stored in /path/to/data
  • ./NODE_FILE_NAME --base-path /path/to/data --chain gemini-1 ... : start node and store data in /path/to/data instead of default location
  • ./NODE_FILE_NAME purge-chain --base-path /path/to/data --chain gemini-1 : erases data related to the node if data were stored in /path/to/data

Examples:

# Replace `FARMER_FILE_NAME` with the name of the node file you downloaded from releases
./FARMER_FILE_NAME farm --help
./FARMER_FILE_NAME wipe

IV. Advanced


Storing Data on the Subspace Network

We are still early in our development but would love to see people start to build on subspace. refer to you npm package subspace.js

Running an archival node

Instructions above will get you full node (doesn't store the history and state of the whole blockchain, only last 1024 blocks). If you want to opt in to storing the whole history (archival node), remove following parameters (lines) from above instructions before starting your node:

  • --pruning 1024
  • --keep-blocks 1024

And instead add this:

  • --pruning archive

Archival node is useful if you run an RPC node and want to support querying older blockchain history.

NOTE: You can't switch between full and archival node without wiping it, so if you need that, follow steps in Switching to a new snapshot section above.

Build from source (Linux)

If you're running unsupported Linux distribution or CPU architecture, you may try to build binaries yourself from source.

NOTE: This is primarily targeted at tech-savvy users and not recommended unless you know what you're doing. Please try to find answer to your question online before reaching out to maintainers.

You'll have to have Rust toolchain installed as well as LLVM and Clang in addition to usual developer tooling (Ubuntu example):

sudo apt-get install llvm clang

Now clone the source and build snapshot snapshot-2022-apr-29 (replace occurrences with the snapshot you want to build):

git clone https://github.com/subspace/subspace.git
cd subspace
git checkout snapshot-2022-apr-29
cargo build \
--profile production \
--bin subspace-node \
--bin subspace-farmer

You'll find two binaries under target/production directory once it succeeds, after which refer to instructions above on how to use them.