Skip to main content

Substrate CLI (Advanced)

Advanced Usage

Subspace CLI is the recommended way to farm on the Subspace Network. Follow the guide below to get started or check out the project README on GitHub.

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.

CoW File Systems Warning

It is advised not to use the Subspace farmer and node on CoW file systems for any OS.

If BTRFS is used with Subspace, the directory/whole file system must be CoW disabled with the following command prior to starting Subspace.

Command to Cow Disable

sudo chattr +C path/to/data

Alternatively, non-CoW file systems like ext4 or xfs can be used instead.

HardwareSpecs
CPU2 Core+
RAM4GB+ (Rec. 8GB)
Storage150GB

B. Crypto Wallet​

Before running anything you need to have a wallet where you'll receive testnet coins. There are currently two wallets we suggest using, SubWallet being the preferred route.

Install one of the two wallets above 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 Subwallet & a Polkadot.js Wallet

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

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:
        # For running on Aarch64 add `-aarch64` after `DATE`
        image: ghcr.io/subspace/node:gemini-2a-2022-oct-06
        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-2a",
          "--base-path", "/var/subspace",
          "--execution", "wasm",
          "--state-pruning", "archive",
          "--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
        # For running on Aarch64 add `-aarch64` after `DATE`
        image: ghcr.io/subspace/farmer:gemini-2a-2022-oct-06
        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
          - farmer-data:/var/subspace:rw
    #      - /path/to/subspace-farmer:/var/subspace:rw
        ports:
    # Un-comment following line to unlock farmer's RPC
    #      - "127.0.0.1:9955:9955"
    # 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",
          "--plot-size", "100G"
        ]
    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-2a-2022-oct-06 --chain gemini-1 --base-path /path/to/directory/here --execution wasm --state-pruning archive --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​

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.

V. Having Trouble?​

If you are having some issues with running the node or the farmer for the subspace network, feel free to join our Discord or even better you can take a look at our Forums and review and existing questions or post a new one if needed!

- Forums​

- Discord​