Skip to content

Commit

Permalink
CLI guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@yaelmhoffman
yaelmhoffman committed Feb 25, 2024
1 parent 7209cdd commit 10c4e7d
Show file tree
Hide file tree
Showing 8 changed files with 82 additions and 135 deletions.
20 changes: 20 additions & 0 deletions docs/start/CLI/compiling.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
id: compiling
title: Compiling a Full Node
---

go-spacemesh has a very limited set of dependencies and requirements, the main one being a Go toolchain. It also requires `make` and [Git Large File Storage](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage). Make sure you have a [recent version of Go](https://go.dev/dl/) installed, clone the [go-spacemesh repository](https://github.com/spacemeshos/go-spacemesh), then run `make install`, which will install the other dependencies for you automatically. Note that this includes a compiled version of the Spacemesh PoST library, but as long as your Go toolchain is set up correctly, this should work out of the box.

You can see the minimum required version of Go in a few places including [`go.mod`](https://github.com/spacemeshos/go-spacemesh/blob/989682a9f574e9860912287634a47bb0db2d0640/go.mod#L3) and the [README](https://github.com/spacemeshos/go-spacemesh/blob/989682a9f574e9860912287634a47bb0db2d0640/README.md?plain=1#L89).

Assuming you intend to run your node on mainnet, **make certain that you compile using the tag that matches the [latest release](https://github.com/spacemeshos/go-spacemesh/releases)**, e.g.:

```bash
> git clone --depth 1 --branch v1.1.1 https://github.com/spacemeshos/go-spacemesh.git
> make install
> make build
```

This builds the `go-spacemesh` binary in the `build/` directory.

For the most up to date information on compiling check the [README](https://github.com/spacemeshos/go-spacemesh#readme), [Makefile](https://github.com/spacemeshos/go-spacemesh/blob/develop/Makefile) and [Makefile-libs](https://github.com/spacemeshos/go-spacemesh/blob/develop/Makefile-libs.Inc), and the [release workflow](https://github.com/spacemeshos/go-spacemesh/blob/develop/.github/workflows/release.yml).
53 changes: 53 additions & 0 deletions docs/start/CLI/config.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
id: config
title: Configuring a Full Node
---

The node currently does not need any config to run with mainnet. You can however request the config and override any needed value. To request the current mainnet compatible config please run:

```bash
> curl -s https://configs.spacemesh.network/networks.json | jq '.[0].conf'
"https://configs.spacemesh.network/config.mainnet.json"
```

Most users will want to start with the existing network config file as a template and add customizations to match their local environment and preferences. Note that **it's essential you not change existing config parameters unless you know what you're doing.** Some config sections, like `genesis`, must not be changed under any circumstances or **your node will not be compatible with mainnet.** Your messages will be dropped and your node may be banned by its peers. Some, like `p2p` and `smeshing`, may be tweaked by power users who know what they're doing, but can also cause problems for your node. Others such as `api` and `logging` are safe to change. When in doubt, [ask for help](https://chat.spacemesh.io)!

Assuming you're starting with the default network config file, you'll want to add something like the following to start smeshing:

```
"smeshing": {
"smeshing-opts": {
"smeshing-opts-datadir": "/data/post/7c8cef2b/",
"smeshing-opts-maxfilesize": 4294967296,
"smeshing-opts-numunits": 15
},
"smeshing-proving-opts": {
"smeshing-opts-proving-nonces": 144,
"smeshing-opts-proving-threads": 0
},
"smeshing-coinbase": "<your coinbase here>",
"smeshing-start": true
},
```

For more information on choosing the `smeshing-opts` and `smeshing-proving-opts`, see [fine-tuning proving](#fine-tuning-proving), [the postcli README](https://github.com/spacemeshos/post/tree/develop/cmd/postcli) and [the profiler README](https://github.com/spacemeshos/post-rs/blob/main/docs/profiler.md), respectively, and the sections below on these topics.

### Coinbase

The coinbase account (specified in the config, above, as `smeshing-coinbase`) is the account that will receive the rewards from smeshing. The coinbase account is fixed per smesher, per epoch, as the smesher commits to it in an ATX for an entire epoch. However, it can be changed at any time, and the change will take effect in the epoch that the next published ATX targets. Note that many smeshers can also use the same coinbase (although to do so would reduce privacy since those smeshers could be associated via the shared coinbase address), and also that there's no requirement that a smesher even provide a coinbase that they control. In theory the coinbase could be set to someone else's account, or even to a burn account.

The simplest way to generate a coinbase account is to install and open [Smapp](https://github.com/spacemeshos/smapp/releases); it'll automatically generate a new account the first time it's opened, assuming one doesn't already exist (make sure to backup the recovery mnemonic!).

If you prefer you can use the [`smcli` tool](https://github.com/spacemeshos/smcli) to generate and display a new wallet containing one or more accounts from the command line. See the README in that repository for more information on the tool.

Either way, you should now have a Spacemesh-compatible address in bech32 format that starts with `sm1`.

### Multiple nodes

It's possible to run multiple `go-spacemesh` processes on a single system. This is of course subject to the [resource requirements](https://github.com/spacemeshos/wiki/wiki/Smesher-Guide#Requirements) outlined above; in particular, make sure that the system has high enough bandwidth to support many nodes. You'll need to change a few parameters to enable this:

1. Node data directory: each node must have its own data directory to store network state. Specify it on the command line using the `-d datadir` flag or in the config in `{"main":{"data-folder":"<node-data-location>"}}`.
1. Smeshing data directory: each smeshing node must point to a different PoST data directory. Specify in the config using `{"smeshing":{"smeshing-opts":{"smeshing-opts-datadir":"<post-data-location>"}}}`. **See note below about avoiding equivocation!**
1. Lockfile: each running node must specify a different lockfile. Specify it on the command line using `--filelock` or in the config with `{"main":{"filelock":"<lock-file-location>"}}`, e.g. `/tmp/go-spacemesh-01.lock`.
1. GRPC API ports: assuming you have GRPC enabled, each running node must use a different set of ports for the public and private GRPC services. Specify them in the config with `{"api":{"grpc-public-listener":"<ip_addr>:<port>","grpc-private-listener":"<ip_addr>:<port>"}}"`. Use `"0.0.0.0"` to listen on all interfaces, or specify an IP address attached to a particular interface. See next section for more information on the API and the difference between public and private services.
1. P2P listen port: you can specify a different port for each node using the `--listen` CLI flag or in the config file using `"p2p": {"listen": "/ip4/0.0.0.0/tcp/6100"}`.
4 changes: 0 additions & 4 deletions docs/start/CLI/node_setup.md
View file

This file was deleted.

15 changes: 0 additions & 15 deletions docs/start/CLI/repl_setup.md
View file

This file was deleted.

0 docs/start/CLI/repl_commands.md → docs/start/CLI/running.md
View file
File renamed without changes.
112 changes: 1 addition & 111 deletions docs/start/smesher.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ While we plan to operate public nodes in the near future, we don't operate any a

## Smapp

The simplest way to run a Spacemesh node is using [Smapp](https://github.com/spacemeshos/smapp/), the wallet, full node, and miner frontend application. You can simply download and install the [latest release](https://github.com/spacemeshos/smapp/releases) for your platform and be up and running in no time. Smapp will automatically download the correct configuration file, and will show you visually the network status, its synchronization status, and the status of PoST init and smeshing. Smapp bundles a full go-spacemesh instance under the hood and manages it for you, including upgrades. See [this tutorial video](https://youtu.be/yrBU5kiyl9A?si=4UM9D7xAepYtMMC6) for more information on setting up Smapp.
The simplest way to run a Spacemesh node is using [Smapp](https://github.com/spacemeshos/smapp/), the wallet, full node, and miner frontend application. You can simply download and install the [latest release](https://github.com/spacemeshos/smapp/releases) for your platform and be up and running in no time. Smapp will automatically download the correct configuration file, and will show you visually the network status, its synchronization status, and the status of PoST init and smeshing. Smapp bundles a full go-spacemesh instance under the hood and manages it for you, including upgrades. See [our smapp guide](start/smapp/install) for more information on setting up Smapp.

Like running go-spacemesh directly from the command line, Smapp also lets you customize your config file and use the node API directly. Running Smapp doesn't provide any greater or lesser functionality than running go-spacemesh directly, but some technical users may prefer working with CLI rather than GUI, may wish to run go-spacemesh as a system service, etc. Users running without a GUI will of course have no choice but to run go-spacemesh directly via CLI.

Expand All @@ -79,116 +79,6 @@ The second file, the one called `node-config.json`, is the default network confi

Note: use caution when modifying the config! This config file must currently maintain its structure. If you update, e.g., the subkey of an object, it'll overwrite the entire object, not append it onto the main network config. See [Merge node config and custom config deeply](https://github.com/spacemeshos/smapp/issues/1407) for more information.

## CLI

It's possible to run a Spacemesh node entirely from the command line using the [go-spacemesh](https://github.com/spacemeshos/go-spacemesh) full node implementation. You can run a pre-compiled [binary release](https://github.com/spacemeshos/go-spacemesh/releases) for your platform, or you can compile the application yourself.

### Compiling

go-spacemesh has a very limited set of dependencies and requirements, the main one being a Go toolchain. It also requires `make` and [Git Large File Storage](https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage). Make sure you have a [recent version of Go](https://go.dev/dl/) installed, clone the [go-spacemesh repository](https://github.com/spacemeshos/go-spacemesh), then run `make install`, which will install the other dependencies for you automatically. Note that this includes a compiled version of the Spacemesh PoST library, but as long as your Go toolchain is set up correctly, this should work out of the box.

You can see the minimum required version of Go in a few places including [`go.mod`](https://github.com/spacemeshos/go-spacemesh/blob/989682a9f574e9860912287634a47bb0db2d0640/go.mod#L3) and the [README](https://github.com/spacemeshos/go-spacemesh/blob/989682a9f574e9860912287634a47bb0db2d0640/README.md?plain=1#L89).

Assuming you intend to run your node on mainnet, **make certain that you compile using the tag that matches the [latest release](https://github.com/spacemeshos/go-spacemesh/releases)**, e.g.:

```bash
> git clone --depth 1 --branch v1.1.1 https://github.com/spacemeshos/go-spacemesh.git
> make install
> make build
```

This builds the `go-spacemesh` binary in the `build/` directory.

For the most up to date information on compiling check the [README](https://github.com/spacemeshos/go-spacemesh#readme), [Makefile](https://github.com/spacemeshos/go-spacemesh/blob/develop/Makefile) and [Makefile-libs](https://github.com/spacemeshos/go-spacemesh/blob/develop/Makefile-libs.Inc), and the [release workflow](https://github.com/spacemeshos/go-spacemesh/blob/develop/.github/workflows/release.yml).

### Running

The node features a set of reasonable default parameters that should work well out of the box for most users and most use cases, but you can change all of them using command line flags and/or the config file. The exact command you use to run `go-spacemesh` will depend upon your local configuration and requirements. See the [README](https://github.com/spacemeshos/go-spacemesh#readme) and run `go-spacemesh -h` for the full list of arguments:

```bash
> go-spacemesh -h
start node

Usage:
node [flags]
node [command]

Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
version Show version info

Flags:
-a, --accounts string=uint64 List of prefunded accounts
--advertise-address string libp2p address with identity (example: /dns4/bootnode.spacemesh.io/tcp/5003)
--beacon-first-voting-round-duration duration First voting round duration in milliseconds (default 30m0s)
--beacon-grace-period-duration duration Grace period duration in milliseconds (default 10m0s)
--beacon-kappa int Security parameter (for calculating ATX threshold) (default 40)
--beacon-proposal-duration duration Proposal duration in milliseconds (default 4m0s)
--beacon-q *big.Rat Ratio of dishonest spacetime (for calculating ATX threshold). It should be a string representing a rational number. (default 1/3)
--beacon-rounds-number uint32 Amount of rounds in every epoch (default 300)
--beacon-sync-weight-units int Numbers of weight units to wait before determining beacon values from them. (default 800)
--beacon-theta *big.Rat Ratio of votes for reaching consensus (default 1/4)
--beacon-votes-limit uint32 Maximum allowed number of votes to be sent (default 100)
...
```

Assuming everything else is set up correctly in your config file (see next section), the only CLI flag you need is to specify the location of the config file, e.g.:

```bash
> go-spacemesh -c node-config.json
```

## Config

The node currently does not need any config to run with mainnet. You can however request the config and override any needed value. To request the current mainnet compatible config please run:

```bash
> curl -s https://configs.spacemesh.network/networks.json | jq '.[0].conf'
"https://configs.spacemesh.network/config.mainnet.json"
```

Most users will want to start with the existing network config file as a template and add customizations to match their local environment and preferences. Note that **it's essential you not change existing config parameters unless you know what you're doing.** Some config sections, like `genesis`, must not be changed under any circumstances or **your node will not be compatible with mainnet.** Your messages will be dropped and your node may be banned by its peers. Some, like `p2p` and `smeshing`, may be tweaked by power users who know what they're doing, but can also cause problems for your node. Others such as `api` and `logging` are safe to change. When in doubt, [ask for help](https://chat.spacemesh.io)!

Assuming you're starting with the default network config file, you'll want to add something like the following to start smeshing:

```
"smeshing": {
"smeshing-opts": {
"smeshing-opts-datadir": "/data/post/7c8cef2b/",
"smeshing-opts-maxfilesize": 4294967296,
"smeshing-opts-numunits": 15
},
"smeshing-proving-opts": {
"smeshing-opts-proving-nonces": 144,
"smeshing-opts-proving-threads": 0
},
"smeshing-coinbase": "<your coinbase here>",
"smeshing-start": true
},
```

For more information on choosing the `smeshing-opts` and `smeshing-proving-opts`, see [fine-tuning proving](#fine-tuning-proving), [the postcli README](https://github.com/spacemeshos/post/tree/develop/cmd/postcli) and [the profiler README](https://github.com/spacemeshos/post-rs/blob/main/docs/profiler.md), respectively, and the sections below on these topics.

### Coinbase

The coinbase account (specified in the config, above, as `smeshing-coinbase`) is the account that will receive the rewards from smeshing. The coinbase account is fixed per smesher, per epoch, as the smesher commits to it in an ATX for an entire epoch. However, it can be changed at any time, and the change will take effect in the epoch that the next published ATX targets. Note that many smeshers can also use the same coinbase (although to do so would reduce privacy since those smeshers could be associated via the shared coinbase address), and also that there's no requirement that a smesher even provide a coinbase that they control. In theory the coinbase could be set to someone else's account, or even to a burn account.

The simplest way to generate a coinbase account is to install and open [Smapp](https://github.com/spacemeshos/smapp/releases); it'll automatically generate a new account the first time it's opened, assuming one doesn't already exist (make sure to backup the recovery mnemonic!).

If you prefer you can use the [`smcli` tool](https://github.com/spacemeshos/smcli) to generate and display a new wallet containing one or more accounts from the command line. See the README in that repository for more information on the tool.

Either way, you should now have a Spacemesh-compatible address in bech32 format that starts with `sm1`.

### Multiple nodes

It's possible to run multiple `go-spacemesh` processes on a single system. This is of course subject to the [resource requirements](https://github.com/spacemeshos/wiki/wiki/Smesher-Guide#Requirements) outlined above; in particular, make sure that the system has high enough bandwidth to support many nodes. You'll need to change a few parameters to enable this:

1. Node data directory: each node must have its own data directory to store network state. Specify it on the command line using the `-d datadir` flag or in the config in `{"main":{"data-folder":"<node-data-location>"}}`.
1. Smeshing data directory: each smeshing node must point to a different PoST data directory. Specify in the config using `{"smeshing":{"smeshing-opts":{"smeshing-opts-datadir":"<post-data-location>"}}}`. **See note below about avoiding equivocation!**
1. Lockfile: each running node must specify a different lockfile. Specify it on the command line using `--filelock` or in the config with `{"main":{"filelock":"<lock-file-location>"}}`, e.g. `/tmp/go-spacemesh-01.lock`.
1. GRPC API ports: assuming you have GRPC enabled, each running node must use a different set of ports for the public and private GRPC services. Specify them in the config with `{"api":{"grpc-public-listener":"<ip_addr>:<port>","grpc-private-listener":"<ip_addr>:<port>"}}"`. Use `"0.0.0.0"` to listen on all interfaces, or specify an IP address attached to a particular interface. See next section for more information on the API and the difference between public and private services.
1. P2P listen port: you can specify a different port for each node using the `--listen` CLI flag or in the config file using `"p2p": {"listen": "/ip4/0.0.0.0/tcp/6100"}`.

## System Service

Expand Down
4 changes: 1 addition & 3 deletions docs/start/start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,7 @@ However, if your system doesn't meet the minimum [system requirements](start/sma

### CLI

CLI is a Spacemesh API client with wallet functions that operates via command-line.

**The CLI guide is currently under construction but will be available soon.**
It's possible to run a Spacemesh node entirely from the command line using the [go-spacemesh](https://github.com/spacemeshos/go-spacemesh) full node implementation. You can run a pre-compiled [binary release](https://github.com/spacemeshos/go-spacemesh/releases) for your platform, or you can compile the application yourself.

## General Smesher Guide

Expand Down
Loading

0 comments on commit 10c4e7d

Please sign in to comment.