cerc-io/lotus
16
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 27 Wiki Activity

Docs review and re-organization

Browse Source 
This:

* Re-organizes the docs into sections that align with what docs.filecoin.io becoming:
  * An installation section
  * A "getting started" section (lotus client focused)
  * A "storing" section (lotus client focused)
  * A "mining" section (miner focused)
  * A "build" section (developer focused)
  * An legacy "architecture" section is left in the last place.

A few high-value documentation pages have been reviewed and updated with the latest recommendations:

* Installation section and lotus setup
* Miner setup
* etc.
...

Other pages have been correctly merged into the new relevant sections. Some pages have not been touched. The filesystem layout of the documentation has been changed into folders corresponding to the sections (as requested by @cw). Some pages that were not linked at all and/or where hidden, have been moved to "unclassified".

This should make the porting of the Lotus documentation to docs.filecoin.io much easier, while ensuring it is more up to date than it was before.

For the moment, this breaks most links as link-aliasing is not supported in lotus-docs.
This commit is contained in:
Hector Sanjuan 2020-08-31 17:11:01 +02:00
parent 97273655dc
commit fe52c47570
57 changed files with 1239 additions and 1357 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -280,7 +280,7 @@ method-gen:
gen: type-gen method-gen gen: type-gen method-gen
docsgen: docsgen:
go run ./api/docgen > documentation/en/api-methods.md go run ./api/docgen > documentation/en/building/api-methods.md
print-%: print-%:
@echo $*=$($*) @echo $*=$($*)

353
documentation/en/.library.json
View File

@ -1,214 +1,207 @@
{ {
"posts": [ "posts": [
{ {
"title": "Hardware Requirements", "title": "About Lotus",
"slug": "en+hardware", "slug": "en+lotus",
"github": "en/hardware.md", "github": "en/about.md",
"value": null,
"posts": []
},
{
"title": "Installation",
"slug": "en+install",
"github": "en/installation/installation.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "Testing Configuration", "title": "Linux installation",
"slug": "en+hardware-mining", "slug": "en+install-linux",
"github": "en/hardware-mining.md", "github": "en/installation/install-linux.md",
"value": null "value": null
} },
{
"title": "MacOS installation",
"slug": "en+install-macos",
"github": "en/installation/install-macos.md",
"value": null
},
{
"title": "Updating Lotus",
"slug": "en+update",
"github": "en/installation/update.md",
"value": null
}
] ]
}, },
{ {
"title": "Setup", "title": "Getting started",
"slug": "en+getting-started", "slug": "en+getting-started",
"github": "en/getting-started.md", "github": "en/getting-started/getting-started.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "Arch Linux Installation", "title": "Setting up Lotus",
"slug": "en+install-lotus-arch", "slug": "en+setup",
"github": "en/install-lotus-arch.md", "github": "en/getting-started/setup.md",
"value": null "value": null
}, },
{ {
"title": "Ubuntu Installation",
"slug": "en+install-lotus-ubuntu", "title": "Obtaining and sending FIL",
"github": "en/install-lotus-ubuntu.md", "slug": "en+wallet",
"value": null "github": "en/getting-started/wallet.md",
}, "value": null
{ },
"title": "Fedora Installation", {
"slug": "en+install-lotus-fedora", "title": "Setup troubleshooting",
"github": "en/install-lotus-fedora.md", "slug": "en+setup-troubleshooting",
"value": null "github": "en/getting-started/setup-troubleshooting.md",
}, "value": null
{ }
"title": "MacOS Installation",
"slug": "en+install-lotus-macos",
"github": "en/install-lotus-macos.md",
"value": null
},
{
"title": "Updating Lotus",
"slug": "en+updating-lotus",
"github": "en/updating-lotus.md",
"value": null
},
{
"title": "Join Testnet",
"slug": "en+join-testnet",
"github": "en/join-testnet.md",
"value": null
},
{
"title": "Use Lotus with systemd",
"slug": "en+install-systemd-services",
"github": "en/install-systemd-services.md",
"value": null
},
{
"title": "Setup Troubleshooting",
"slug": "en+setup-troubleshooting",
"github": "en/setup-troubleshooting.md",
"value": null
},
{
"title": "Environment Variables",
"slug": "en+env-vars",
"github": "en/environment-vars.md",
"value": null
}
] ]
}, },
{ {
"title": "Architecture", "title": "Storing and retrieving data",
"slug": "en+arch", "slug": "en+store",
"github": "en/architecture.md", "github": "en/store/store.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "The Message Pool", "title": "Making storage deals",
"slug": "en+mpool", "slug": "en+making-deals",
"github": "en/mpool.md", "github": "en/store/making-deals.md",
"value": null "value": null
} },
{
"title": "Adding data from IPFS",
"slug": "en+adding-from-ipfs",
"github": "en/store/adding-from-ipfs.md",
"value": null
},
{
"title": "Retrieving data",
"slug": "en+retriving",
"github": "en/store/retrieve.md",
"value": null
},
{
"title": "Storage Troubleshooting",
"slug": "en+storage-troubleshooting",
"github": "en/store/storage-troubleshooting.md",
"value": null
}
] ]
}, },
{ {
"title": "Storage Mining", "title": "Storage mining",
"slug": "en+mining", "slug": "en+mining",
"github": "en/mining.md", "github": "en/mining/mining.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "Lotus Worker", "title": "Miner setup",
"slug": "en+lotus-worker", "slug": "en+miner-setup",
"github": "en/mining-lotus-worker.md", "github": "en/mining/miner-setup.md",
"value": null "value": null
}, },
{ {
"title": "Static Ports", "title": "Managing deals",
"slug": "en+setting-a-static-port", "slug": "en+managing-deals",
"github": "en/setting-a-static-port.md", "github": "en/mining/managing-deals.md",
"value": null "value": null
}, },
{ {
"title": "Mining Troubleshooting", "title": "Lotus Worker",
"slug": "en+mining-troubleshooting", "slug": "en+lotus-worker",
"github": "en/mining-troubleshooting.md", "github": "en/mining/lotus-seal-worker.md",
"value": null "value": null
} },
{
"title": "Benchmarking GPUs",
"slug": "en+gpus",
"github": "en/mining/gpus.md",
"value": null
},
{
"title": "Mining Troubleshooting",
"slug": "en+mining-troubleshooting",
"github": "en/mining/mining-troubleshooting.md",
"value": null
}
] ]
}, },
{ {
"title": "Storing Data", "title": "Building",
"slug": "en+storing-data", "slug": "en+building",
"github": "en/storing-data.md", "github": "en/building/building.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "Storage Troubleshooting", "title": "Setting up remote API access",
"slug": "en+storing-data-troubleshooting", "slug": "en+remote-api",
"github": "en/storing-data-troubleshooting.md", "github": "en/building/remote-api.md",
"value": null "value": null,
}, "posts": []
{ },
"title": "Information for Miners", {
"slug": "en+info-for-miners", "title": "API endpoints and methods",
"github": "en/miner-deals.md", "slug": "en+api",
"value": null "github": "en/building/api.md",
}, "value": null,
{ "posts": []
"title": "IPFS Integration", },
"slug": "en+ipfs-client-integration", {
"github": "en/storing-ipfs-integration.md", "title": "API Reference",
"value": null "slug": "en+api-methods",
} "github": "en/building/api-methods.md",
"value": null,
"posts": []
},
{
"title": "Payment Channels",
"slug": "en+payment-channels",
"github": "en/building/payment-channels.md",
"value": null,
"posts": []
},
{
"title": "Running a local devnet",
"slug": "en+local-devnet",
"github": "en/building/local-devnet.md",
"value": null,
"posts": []
},
{
"title": "Jaeger Tracing",
"slug": "en+jaeger-tracing",
"github": "en/building/jaeger-tracing.md",
"value": null,
"posts": []
},
{
"title": "API Troubleshooting",
"slug": "en+api-troubleshooting",
"github": "en/building/api-troubleshooting.md",
"value": null,
"posts": []
}
] ]
}, },
{ {
"title": "Retrieving Data", "title": "Lotus Architecture (WIP)",
"slug": "en+retrieving-data", "slug": "en+arch",
"github": "en/retrieving-data.md", "github": "en/architectiure/architecture.md",
"value": null,
"posts": []
},
{
"title": "Payment Channels",
"slug": "en+payment-channels",
"github": "en/payment-channels.md",
"value": null,
"posts": []
},
{
"title": "Command Line Interface",
"slug": "en+cli",
"github": "en/cli.md",
"value": null,
"posts": []
},
{
"title": "API",
"slug": "en+api",
"github": "en/api.md",
"value": null, "value": null,
"posts": [ "posts": [
{ {
"title": "Remote API Support", "title": "The Message Pool",
"slug": "en+api-scripting-support", "slug": "en+mpool",
"github": "en/api-scripting-support.md", "github": "en/architecture/mpool.md",
"value": null "value": null
}, }
{
"title": "API Methods",
"slug": "en+api-methods",
"github": "en/api-methods.md",
"value": null
},
{
"title": "API Troubleshooting",
"slug": "en+api-troubleshooting",
"github": "en/api-troubleshooting.md",
"value": null
}
]
},
{
"title": "Developer Tools",
"slug": "en+dev-tools",
"github": "en/dev-tools.md",
"value": null,
"posts": [
{
"title": "Setup Local Devnet",
"slug": "en+setup-local-dev-net",
"github": "en/local-dev-net.md",
"value": null,
"posts": []
},
{
"title": "Jaeger Tracing",
"slug": "en+dev-tools-jaeger-tracing",
"github": "en/dev-tools-jaeger-tracing.md",
"value": null,
"posts": []
}
] ]
}, },
{ {
@ -224,7 +217,7 @@
"github": "en/.glossary.json", "github": "en/.glossary.json",
"value": null, "value": null,
"custom": { "custom": {
"glossary": true "glossary": true
}, },
"posts": [] "posts": []
} }

14
documentation/en/about.md Normal file
View File

@ -0,0 +1,14 @@
# Lotus
Lotus is an implementation of the **Filecoin Distributed Storage Network**.
The **Lotus Node** (and the mining applications) can be built to join any of the [Filecoin networks](https://docs.filecoin.io/how-to/networks/).
For more details about Filecoin, check out the [Filecoin Docs](https://docs.filecoin.io) and [Filecoin Spec](https://filecoin-project.github.io/specs/).
## What can I learn here?
* How to [install](en+installation) and [setup](en+setup) the Lotus software
* How to [store data on the Filecoin network](en+store)
* How to [setup a high performance FIL miner](en+miner-setup)
* How to [configure and access Lotus APIs](en+remote-api)

25
documentation/en/api-scripting-support.md
View File

@ -1,25 +0,0 @@
# Remote API Support
You may want to delegate the work **Lotus Miner** or **Lotus Node** performs to other machines.
Here is how to setup the necessary authorization and environment variables.
## Environment variables
Environmental variables are variables that are defined for the current shell and are inherited by any child shells or processes. Environmental variables are used to pass information into processes that are spawned from the shell.
Using the [JWT you generated](https://lotu.sh/en+api#how-do-i-generate-a-token-18865), you can assign it and the **multiaddr** to the appropriate environment variable.
```sh
# Lotus Node
FULLNODE_API_INFO="JWT_TOKEN:/ip4/127.0.0.1/tcp/1234/http"
# Lotus Miner
MINER_API_INFO="JWT_TOKEN:/ip4/127.0.0.1/tcp/2345/http"
```
You can also use `lotus auth api-info --perm admin` to quickly create _API_INFO env vars
- The **Lotus Node**'s `mutliaddr` is in `~/.lotus/api`.
- The default token is in `~/.lotus/token`.
- The **Lotus Miner**'s `multiaddr` is in `~/.lotusminer/config`.
- The default token is in `~/.lotusminer/token`.

85
documentation/en/api.md
View File

@ -1,85 +0,0 @@
# API
Here is an early overview of how to make API calls.
Implementation details for the **JSON-RPC** package are [here](https://github.com/filecoin-project/go-jsonrpc).
## Overview: How do you modify the config.toml to change the API endpoint?
API requests are made against `127.0.0.1:1234` unless you modify `.lotus/config.toml`.
Options:
- `http://[api:port]/rpc/v0` - HTTP endpoint
- `ws://[api:port]/rpc/v0` - Websocket endpoint
- `PUT http://[api:port]/rest/v0/import` - File import, it requires write permissions.
## What methods can I use?
For now, you can look into different files to find methods available to you based on your needs:
- [Both Lotus node + miner APIs](https://github.com/filecoin-project/lotus/blob/master/api/api_common.go)
- [Lotus node API](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)
- [Lotus miner API](https://github.com/filecoin-project/lotus/blob/master/api/api_storage.go)
The necessary permissions for each are in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go).
## How do I make an API request?
To demonstrate making an API request, we will take the method `ChainHead` from [api/api_full.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
```go
ChainHead(context.Context) (*types.TipSet, error)
```
And create a CURL command. In this command, `ChainHead` is included as `{ "method": "Filecoin.ChainHead" }`:
```sh
curl -X POST \
-H "Content-Type: application/json" \
--data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
'http://127.0.0.1:1234/rpc/v0'
```
If the request requires authorization, add an authorization header:
```sh
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(cat ~/.lotusminer/token)" \
--data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
'http://127.0.0.1:1234/rpc/v0'
```
> In the future we will add a playground to make it easier to build and experiment with API requests.
## CURL authorization
To authorize your request, you will need to include the **JWT** in a HTTP header, for example:
```sh
-H "Authorization: Bearer $(cat ~/.lotusminer/token)"
```
Admin token is stored in `~/.lotus/token` for the **Lotus Node** or `~/.lotusminer/token` for the **Lotus Miner**.
## How do I generate a token?
To generate a JWT with custom permissions, use this command:
```sh
# Lotus Node
lotus auth create-token --perm admin
# Lotus Miner
lotus-miner auth create-token --perm admin
```
## What authorization level should I use?
When viewing [api/apistruct/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/apistruct/struct.go), you will encounter these types:
- `read` - Read node state, no private data.
- `write` - Write to local store / chain, and `read` permissions.
- `sign` - Use private keys stored in wallet for signing, `read` and `write` permissions.
- `admin` - Manage permissions, `read`, `write`, and `sign` permissions.

2
documentation/en/architecture.md → documentation/en/architecture/architecture.md
View File

@ -6,7 +6,7 @@ Filecoin protocol, validating the blocks and state transitions.
The specification for the Filecoin protocol can be found [here](https://filecoin-project.github.io/specs/). The specification for the Filecoin protocol can be found [here](https://filecoin-project.github.io/specs/).
For information on how to setup and operate a Lotus node, For information on how to setup and operate a Lotus node,
please follow the instructions [here](https://lotu.sh/en+getting-started). please follow the instructions [here](en+getting-started).
# Components # Components

0
documentation/en/mpool.md → documentation/en/architecture/mpool.md
View File

0
documentation/en/api-methods.md → documentation/en/building/api-methods.md
View File

0
documentation/en/api-troubleshooting.md → documentation/en/building/api-troubleshooting.md
View File

38
documentation/en/building/api.md Normal file
View File

@ -0,0 +1,38 @@
# API endpoints and methods
The API can be accessed on:
- `http://[api:port]/rpc/v0` - HTTP RPC-API endpoint
- `ws://[api:port]/rpc/v0` - Websocket RPC-API endpoint
- `PUT http://[api:port]/rest/v0/import` - REST endpoint for file import (multipart upload). It requires write permissions.
The RPC methods can be found in the [Reference](en+api-methods) and directly in the source code:
- [Both Lotus node + miner APIs](https://github.com/filecoin-project/lotus/blob/master/api/api_common.go)
- [Lotus node API](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)
- [Lotus miner API](https://github.com/filecoin-project/lotus/blob/master/api/api_storage.go)
## JSON-RPC client
Lotus uses its own Go library implementation of [JSON-RPC](https://github.com/filecoin-project/go-jsonrpc).
## cURL example
To demonstrate making an API request, we will take the method `ChainHead` from [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
```go
ChainHead(context.Context) (*types.TipSet, error)
```
And create a CURL command. In this command, `ChainHead` is included as `{ "method": "Filecoin.ChainHead" }`:
```sh
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(cat ~/.lotusminer/token)" \
--data '{ "jsonrpc": "2.0", "method": "Filecoin.ChainHead", "params": [], "id": 3 }' \
'http://127.0.0.1:1234/rpc/v0'
```
(See [this section](en+remote-api) to learn how to generate authorization tokens).

5
documentation/en/building/building.md Normal file
View File

@ -0,0 +1,5 @@
# Building with Lotus
Lotus applications provide HTTP (JSON-RPC) APIs that allow developers to control Lotus programatically.
This section dives into how to setup and use these APIs, additionally providing information on advanced Lotus features and workflows, like Payment Channels or how to setup a fully local Lotus development network.

0
documentation/en/dev-tools-jaeger-tracing.md → documentation/en/building/jaeger-tracing.md
View File

0
documentation/en/local-dev-net.md → documentation/en/building/local-devnet.md
View File

0
documentation/en/payment-channels.md → documentation/en/building/payment-channels.md
View File

69
documentation/en/building/remote-api.md Normal file
View File

@ -0,0 +1,69 @@
# Setting up remote API access
The **Lotus Miner** and the **Lotus Node** applications come with their own local API endpoints setup by default when they are running.
These endpoints are used by `lotus` and `lotus-miner` to interact with the running process. In this section we will explain how to enable remote access to the Lotus APIs.
Note that instructions are the same for `lotus` and `lotus-miner`. For simplicity, we will just show how to do it with `lotus`.
## Setting the listening interface for the API endpoint
By default, the API listens on the local "loopback" interface (`127.0.0.1`). This is configured in the `config.toml` file:
```toml
[API]
# ListenAddress = "/ip4/127.0.0.1/tcp/1234/http"
# RemoteListenAddress = ""
# Timeout = "30s"
```
To access the API remotely, Lotus needs to listen on the right IP/interface. The IP associated to each interface can be usually found with the command `ip a`. Once the right IP is known, it can be set in the configuration:
```toml
[API]
ListenAddress = "/ip4/<EXTERNAL_INTERFACE_IP>/tcp/3453/http" # port is an example
# Only relevant for lotus-miner
# This should be the IP:Port pair where the miner is reachable from anyone trying to dial to it.
# If you have placed a reverse proxy or a NAT'ing device in front of it, this may be different from
# the EXTERNAL_INTERFACE_IP.
RemoteListenAddress = "<EXTERNAL_IP_AS_SEEN_BY_OTHERS:<EXTERNAL_PORT_AS_SEEN_BY_OTHERS>"
```
> `0.0.0.0` can be used too. This is a wildcard that means "all interfaces". Depending on the network setup, this may affect security (listening on the wrong, exposed interface).
After making these changes, please restart the affected process.
## Issuing tokens
Any client wishing to talk to the API endpoints will need a token. Tokens can be generated with:
```sh
lotus auth create-token --perm <read,write,sign,admin>
```
(similarly for the Lotus Miner).
The permissions work as follows:
- `read` - Read node state, no private data.
- `write` - Write to local store / chain, and `read` permissions.
- `sign` - Use private keys stored in wallet for signing, `read` and `write` permissions.
- `admin` - Manage permissions, `read`, `write`, and `sign` permissions.
Tokens can then be used in applications by setting an Authorization header as:
```
Authorization: Bearer <token>
```
## Environment variables
`lotus`, `lotus-miner` and `lotus-worker` can actually interact with their respective applications running on a different node. All is needed to configure them are the following the *environment variables*:
```sh
FULLNODE_API_INFO="TOKEN:/ip4/<IP>/tcp/<PORT>/http"
MINER_API_INFO="TOKEN:/ip4/<IP>/tcp/<PORT>/http"
```

108
documentation/en/cli.md
View File

@ -1,108 +0,0 @@
# Lotus Command Line Interface
The Command Line Interface (CLI) is a convenient way to interact with
a Lotus node. You can use the CLI to operate your node,
get information about the blockchain,
manage your accounts and transfer funds,
create storage deals, and much more!
The CLI is intended to be self-documenting, so when in doubt, simply add `--help`
to whatever command you're trying to run! This will also display all of the
input parameters that can be provided to a command.
We highlight some of the commonly
used features of the CLI below.
All CLI commands should be run from the home directory of the Lotus project.
## Operating a Lotus node
### Starting up a node
```sh
lotus daemon
```
This command will start up your Lotus node, with its API port open at 1234.
You can pass `--api=<number>` to use a different port.
### Checking your sync progress
```sh
lotus sync status
```
This command will print your current tipset height under `Height`, and the target tipset height
under `Taregt`.
You can also run `lotus sync wait` to get constant updates on your sync progress.
### Getting the head tipset
```sh
lotus chain head
```
### Control the logging level
```sh
lotus log set-level
```
This command can be used to toggle the logging levels of the different
systems of a Lotus node. In decreasing order
of logging detail, the levels are `debug`, `info`, `warn`, and `error`.
As an example,
to set the `chain` and `blocksync` to log at the `debug` level, run
`lotus log set-level --system chain --system blocksync debug`.
To see the various logging system, run `lotus log list`.
### Find out what version of Lotus you're running
```sh
lotus version
```
## Managing your accounts
### Listing accounts in your wallet
```sh
lotus wallet list
```
### Creating a new account
```sh
lotus wallet new bls
```
This command will create a new BLS account in your wallet; these
addresses start with the prefix `t3`. Running `lotus wallet new secp256k1`
(or just `lotus wallet new`) will create
a new Secp256k1 account, which begins with the prefix `t1`.
### Getting an account's balance
```sh
lotus wallet balance <address>
```
### Transferring funds
```sh
lotus send --source=<source address> <destination address> <amount>
```
This command will transfer `amount` (in attoFIL) from `source address` to `destination address`.
### Importing an account into your wallet
```sh
lotus wallet import <path to private key>
```
This command will import an account whose private key is saved at the specified file.
### Exporting an account from your wallet
```sh
lotus wallet export <address>
```
This command will print out the private key of the specified address
if it is in your wallet. Always be careful with your private key!

3
documentation/en/dev-tools.md
View File

@ -1,3 +0,0 @@
# Developer Tools
> Running a local network can be a great way to understand how Lotus works and test your setup.

65
documentation/en/environment-vars.md
View File

@ -1,65 +0,0 @@
# Lotus Environment Variables
## Building
## Common
The environment variables are common across most lotus binaries.
### `LOTUS_FD_MAX`
Sets the file descriptor limit for the process. This should be set high (8192
or higher) if you ever notice 'too many open file descriptor' errors.
### `LOTUS_JAEGER`
This can be set to enable jaeger trace reporting. The value should be the url
of the jaeger trace collector, the default for most jaeger setups should be
`localhost:6831`.
### `LOTUS_DEV`
If set to a non-empty value, certain parts of the application will print more
verbose information to aid in development of the software. Not recommended for
end users.
## Lotus Daemon
### `LOTUS_PATH`
Sets the location for the lotus daemon on-disk repo. If left empty, this defaults to `~/.lotus`.
### `LOTUS_SKIP_GENESIS_CHECK`
Can be set to `_yes_` if you wish to run a lotus network with a different
genesis than the default one built into your lotus binary.
### `LOTUS_CHAIN_TIPSET_CACHE`
Sets the cache size for the chainstore tipset cache. The default value is 8192,
but if your usage of the lotus API involves frequent arbitrary tipset lookups,
you may want to increase this.
### `LOTUS_CHAIN_INDEX_CACHE`
Sets the cache size for the chainstore epoch index cache. The default value is 32768,
but if your usage of the lotus API involves frequent deep chain lookups for
block heights that are very far from the current chain height, you may want to
increase this.
### `LOTUS_BSYNC_MSG_WINDOW`
Set the initial maximum window size for message fetching blocksync requests. If
you have a slower internet connection and are having trouble syncing, you might
try lowering this down to 10-20 for a 'poor' internet connection.
## Lotus Miner
A number of environment variables are respected for configuring the behavior of the filecoin proving subsystem. For more details on those [see here](https://github.com/filecoin-project/rust-fil-proofs/#settings).
### `LOTUS_MINER_PATH`
Sets the location for the lotus miners on-disk repo. If left empty, this defaults to `~/.lotusminer`.

36
documentation/en/faqs.md
View File

@ -11,7 +11,6 @@ go [here](https://filecoin.io/faqs/).
Lotus is an implementation of the **Filecoin Distributed Storage Network**, written in Go. Lotus is an implementation of the **Filecoin Distributed Storage Network**, written in Go.
It is designed to be modular and interoperable with any other implementation of the Filecoin Protocol. It is designed to be modular and interoperable with any other implementation of the Filecoin Protocol.
More information about Lotus can be found [here](https://lotu.sh/).
### What are the components of Lotus? ### What are the components of Lotus?
@ -30,21 +29,19 @@ to a Lotus Node over the JSON-RPC API.
### How do I set up a Lotus Node? ### How do I set up a Lotus Node?
Follow the instructions found [here](https://lotu.sh/en+getting-started). Follow the instructions found [here](en+install) and [here](en+setup).
### Where can I get the latest version of Lotus? ### Where can I get the latest version of Lotus?
Download the binary tagged as the `Latest Release` from the Download the binary tagged as the `Latest Release` from the [Lotus Github repo](https://github.com/filecoin-project/lotus/releases) or checkout the `master` branch of the source repository.
[Lotus Github repo](https://github.com/filecoin-project/lotus/releases).
### What operating systems can Lotus run on? ### What operating systems can Lotus run on?
Lotus can build and run on most Linux and MacOS systems with at least Lotus can build and run on most Linux and MacOS systems with [at least 8GB of RAM](en+install#hardware-requirements-1). Windows is not yet supported.
8GB of RAM. Windows is not yet supported.
### How can I update to the latest version of Lotus? ### How can I update to the latest version of Lotus?
To update Lotus, follow the instructions [here](https://lotu.sh/en+updating-lotus). To update Lotus, follow the instructions [here](en+update).
### How do I prepare a fresh installation of Lotus? ### How do I prepare a fresh installation of Lotus?
@ -52,7 +49,7 @@ Stop the Lotus daemon, and delete all related files, including sealed and chain
running `rm ~/.lotus ~/.lotusminer`. running `rm ~/.lotus ~/.lotusminer`.
Then, install Lotus afresh by following the instructions Then, install Lotus afresh by following the instructions
found [here](https://lotu.sh/en+getting-started). found [here](en+install).
### Can I configure where the node's config and data goes? ### Can I configure where the node's config and data goes?
@ -73,48 +70,45 @@ directory for more.
### How can I send a request over the JSON-RPC API? ### How can I send a request over the JSON-RPC API?
Information on how to send a `cURL` request to the JSON-RPC API can be found Information on how to send a `cURL` request to the JSON-RPC API can be found
[here](https://lotu.sh/en+api). A JavaScript client is under development. [here](en+api).
### What are the requests I can send over the JSON-RPC API? ### What are the requests I can send over the JSON-RPC API?
Please have a look at the Please have a look [here](en+api).
[source code](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go)
for a list of methods supported by the JSON-RPC API.
## The Test Network ## The Test Network
### What is Testnet? ### What is Testnet?
Testnet is a live network of Lotus Nodes run by the Testnet is a live network of Lotus Nodes run by the
community for testing purposes. community for testing purposes.
It has 2 PiB of storage (and growing!) dedicated to it.
### Is FIL on the Testnet worth anything? ### Is FIL on the Testnet worth anything?
Nothing at all! Real-world incentives may be provided in a future phase of Testnet, but this is Nothing at all!
yet to be confirmed.
### How can I see the status of Testnet? ### How can I see the status of Testnet?
The [dashboard](https://stats.testnet.filecoin.io/) displays the status of the network as The [dashboard](https://stats.testnet.filecoin.io/) displays the status of the network as
well as a ton well as a ton of other metrics you might find interesting.
of other metrics you might find interesting.
## Mining with a Lotus Node on Testnet ## Mining with a Lotus Node on Testnet
### How do I get started mining with Lotus? ### How do I get started mining with Lotus?
Follow the instructions found [here](https://lotu.sh/en+mining). Follow the instructions found [here](en+mining).
### What are the minimum hardware requirements? ### What are the minimum hardware requirements?
An example test configuration, and minimum hardware requirements can be found An example test configuration, and minimum hardware requirements can be found
[here](https://lotu.sh/en+hardware-mining). [here](en+install#hardware-requirements-8).
Note that these might NOT be the minimum requirements for mining on Mainnet. Note that these might NOT be the minimum requirements for mining on Mainnet.
### What are some GPUs that have been tested? ### What are some GPUs that have been tested?
A list of benchmarked GPUs can be found [here](https://lotu.sh/en+hardware-mining#benchmarked-gpus-7393). See previous question.
### Why is my GPU not being used when sealing a sector? ### Why is my GPU not being used when sealing a sector?
@ -135,4 +129,4 @@ You can do so by changing the storage path variable for the second miner, e.g.,
### How do I setup my own local devnet? ### How do I setup my own local devnet?
Follow the instructions found [here](https://lotu.sh/en+setup-local-dev-net). Follow the instructions found [here](en+local-devnet).

23
documentation/en/getting-started.md
View File

@ -1,23 +0,0 @@
# Lotus
Lotus is an implementation of the **Filecoin Distributed Storage Network**. You can run the Lotus software client to join the **Filecoin Testnet**.
For more details about Filecoin, check out the [Filecoin Docs](https://docs.filecoin.io) and [Filecoin Spec](https://filecoin-project.github.io/specs/).
## What can I learn here?
- How to install Lotus on [Arch Linux](https://lotu.sh/en+install-lotus-arch), [Ubuntu](https://lotu.sh/en+install-lotus-ubuntu), or [MacOS](https://lotu.sh/en+install-lotus-macos).
- Joining the [Lotus Testnet](https://lotu.sh/en+join-testnet).
- [Storing](https://lotu.sh/en+storing-data) or [retrieving](https://lotu.sh/en+retrieving-data) data.
- Mining Filecoin using the **Lotus Miner** in your [CLI](https://lotu.sh/en+mining).
## How is Lotus designed?
Lotus is architected modularly to keep clean API boundaries while using the same process. Installing Lotus will include two separate programs:
- The **Lotus Node**
- The **Lotus Miner**
The **Lotus Miner** is intended to be run on the machine that manages a single miner instance, and is meant to communicate with the **Lotus Node** via the websocket **JSON-RPC** API for all of the chain interaction needs.
This way, a mining operation may easily run a **Lotus Miner** or many of them, connected to one or many **Lotus Node** instances.

3
documentation/en/getting-started/getting-started.md Normal file
View File

@ -0,0 +1,3 @@
# Getting started
This section will get you started with Lotus. We will setup the Lotus daemon (that should already be [installed](en+install)), start it, create a wallet and use it to send and receive some Filecoin.

13
documentation/en/setup-troubleshooting.md → documentation/en/getting-started/setup-troubleshooting.md
View File

@ -1,5 +1,12 @@
# Setup Troubleshooting # Setup Troubleshooting
## Error: initializing node error: cbor input had wrong number of fields
This happens when you are starting Lotus which has been compiled for one network, but it encounters data in the Lotus data folder which is for a different network, or for an older incompatible version.
The solution is to clear the data folder (see below).
## Config: Clearing data ## Config: Clearing data
Here is a command that will delete your chain data, stored wallets, stored data and any miners you have set up: Here is a command that will delete your chain data, stored wallets, stored data and any miners you have set up:
@ -8,7 +15,7 @@ Here is a command that will delete your chain data, stored wallets, stored data
rm -rf ~/.lotus ~/.lotusminer rm -rf ~/.lotus ~/.lotusminer
``` ```
This command usually resolves any issues with running `lotus` but it is not always required for updates. We will share information about when resetting your chain data and miners is required for an update in the future. Note you do not always need to clear your data for [updating](en+update).
## Error: Failed to connect bootstrap peer ## Error: Failed to connect bootstrap peer
@ -33,6 +40,8 @@ ERROR hello hello/hello.go:81 other peer has different genesis!
## Config: Open files limit ## Config: Open files limit
Lotus will attempt to set up the file descriptor (FD) limit automatically. If that does not work, you can still configure your system to allow higher than the default values.
On most systems you can check the open files limit with: On most systems you can check the open files limit with:
```sh ```sh
@ -44,3 +53,5 @@ You can also modify this number by using the `ulimit` command. It gives you the
```sh ```sh
ulimit -n 10000 ulimit -n 10000
``` ```
Note that this is not persisted and that systemd manages its own FD limits for services. Please use your favourite search engine to find instructions on how to persist and configure FD limits for your system.

169
documentation/en/getting-started/setup.md Normal file
View File

@ -0,0 +1,169 @@
# Setting up Lotus
Your Lotus binaries have been installed and you are ready to start participating in the Filecoin network.
## Selecting the right network
You should have built the Lotus binaries from the right Github branch and Lotus will be fully setup to join the matching [Filecoin network](https://docs.filecoin.io/how-to/networks/). For more information on switching networks, check the [updating Lotus section](en+update).
## Starting the daemon
To start the daemon simply run:
```sh
lotus daemon
```
or if you are using the provided systemd service files, do:
```sh
systemctl start lotus-daemon
```
__If you are using Lotus from China__, make sure you set the following environment variable before running Lotus:
```
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
During the first start, Lotus:
* Will setup its data folder at `~/.lotus`
* Will download the necessary parameters
* Start syncing the Lotus chain
If you started lotus using systemd, the logs will appear in `/var/log/lotus/daemon.log` (not in journalctl as usual), otherwise you will see them in your screen.
Do not be appalled by the amount of warnings and sometimes errors showing in the logs, there are usually part of the usual functioning of the daemon as part of a distributed network.
## Waiting to sync
After the first start, the chain will start syncing until it has reached the tip. You can check how far the syncing process is with:
```sh
lotus sync status
```
You can also interactively wait for the chain to be fully synced with:
```sh
lotus sync wait
```
## Interacting with the Lotus daemon
As shown above, the `lotus` command allows to interact with the running daemon. You will see it getting used in many of the documentation examples.
This command-line-interface is self-documenting:
```sh
# Show general help
lotus --help
# Show specific help for the "client" subcommand
lotus client --help
```
For example, after your Lotus daemon has been running for a few minutes, use `lotus` to check the number of other peers that it is connected to in the Filecoin network:
```sh
lotus net peers
```
## Controlling the logging level
```sh
lotus log set-level
```
This command can be used to toggle the logging levels of the different
systems of a Lotus node. In decreasing order
of logging detail, the levels are `debug`, `info`, `warn`, and `error`.
As an example,
to set the `chain` and `blocksync` to log at the `debug` level, run
`lotus log set-level --system chain --system blocksync debug`.
To see the various logging system, run `lotus log list`.
## Configuration
### Configuration file
The Lotus daemon stores a configuration file in `~/.lotus/config.toml`. Note that by default all settings are commented. Here is an example configuration:
```toml
[API]
# Binding address for the Lotus API
ListenAddress = "/ip4/127.0.0.1/tcp/1234/http"
# Not used by lotus daemon
RemoteListenAddress = ""
# General network timeout value
Timeout = "30s"
# Libp2p provides connectivity to other Filecoin network nodes
[Libp2p]
# Binding address swarm - 0 means random port.
ListenAddresses = ["/ip4/0.0.0.0/tcp/0", "/ip6/::/tcp/0"]
# Insert any addresses you want to explicitally
# announce to other peers here. Otherwise, they are
# guessed.
AnnounceAddresses = []
# Insert any addresses to avoid announcing here.
NoAnnounceAddresses = []
# Connection manager settings, decrease if your
# machine is overwhelmed by connections.
ConnMgrLow = 150
ConnMgrHigh = 180
ConnMgrGrace = "20s"
# Pubsub is used to broadcast information in the network
[Pubsub]
Bootstrapper = false
RemoteTracer = "/dns4/pubsub-tracer.filecoin.io/tcp/4001/p2p/QmTd6UvR47vUidRNZ1ZKXHrAFhqTJAD27rKL9XYghEKgKX"
# This section can be used to enable adding and retriving files from IPFS
[Client]
UseIpfs = false
IpfsMAddr = ""
IpfsUseForRetrieval = false
# Metrics configuration
[Metrics]
Nickname = ""
HeadNotifs = false
```
### Ensuring connectivity to your Lotus daemon
Usually your lotus daemon will establish connectivity with others in the network and try to make itself diallable using uPnP. If you wish to manually ensure that your daemon is reachable:
* Set a fixed port of your choice in the `ListenAddresses` in the Libp2p section (i.e. 6665).
* Open a port in your router that is forwarded to this port. This is usually called featured as "Port forwarding" and the instructions differ from router model to model but there are many guides online.
* Add your public IP/port to `AnnounceAddresses`. i.e. `/ip4/<yourIP>/tcp/6665/`.
Note that it is not a requirement to use Lotus as a client to the network to be fully reachable, as your node already connects to others directly.
### Environment variables
Common to most Lotus binaries:
* `LOTUS_FD_MAX`: Sets the file descriptor limit for the process
* `LOTUS_JAEGER`: Sets the Jaeger URL to send traces. See TODO.
* `LOTUS_DEV`: Any non-empty value will enable more verbose logging, useful only for developers.
Specific to the *Lotus daemon*:
* `LOTUS_PATH`: Location to store Lotus data (defaults to `~/.lotus`).
* `LOTUS_SKIP_GENESIS_CHECK=_yes_`: Set only if you wish to run a lotus network with a different genesis block.
* `LOTUS_CHAIN_TIPSET_CACHE`: Sets the size for the chainstore tipset cache. Defaults to `8192`. Increase if you perform frequent arbitrary tipset lookups.
* `LOTUS_CHAIN_INDEX_CACHE`: Sets the size for the epoch index cache. Defaults to `32768`. Increase if you perform frequent deep chain lookups for block heights far from the latest height.
* `LOTUS_BSYNC_MSG_WINDOW`: Set the initial maximum window size for message fetching blocksync request. Set to 10-20 if you have an internet connection with low bandwidth.
Specific to the *Lotus miner*:
* `LOTUS_MINER_PATH`: Location for the miner's on-disk repo. Defaults to `./lotusminer`.
* A number of environment variables are respected for configuring the behaviour of the Filecoin proving subsystem. [See here](en+miner-setup).

58
documentation/en/getting-started/wallet.md Normal file
View File

@ -0,0 +1,58 @@
# Obtaining and sending FIL
In order to receive and send FIL with Lotus you will need to have installed the program and be running the Lotus daemon.
## Creating a wallet
```sh
lotus wallet new bls
```
This will print your Filecoin address.
Your wallet information is stored in the `~/.lotus/keystore` (or `$LOTUS_PATH/keystore`). For instructions on export/import, see below.
You can create multiple wallets and list them with:
```sh
lotus wallet list
```
## Obtaining FIL
FIL can be obtained either by using one of the Faucets (available for the test networks) or by buying it from an exchange supporting FIL trading (once mainnet has launched).
Once you have received some FIL you can check your balance with:
```sh
lotus wallet balance
```
Remember that your will only see the latest balance when your daemon is fully synced to the chain.
## Sending FIL
Sending some FIL can be achieved by running:
```sh
lotus wallet send <address> <amount>
```
Make sure to check `lotus wallet send --help` for additional options.
## Exporting and importing a wallet
You can export and re-import a wallet with:
```sh
lotus wallet export <address> > wallet.private
```
and:
```sh
lotus wallet import wallet.private
```
Keep your wallet's private key safe!

54
documentation/en/hardware-mining.md
View File

@ -1,54 +0,0 @@
# Protocol Labs Standard Testing Configuration
> This documentation page describes the standard testing configuration the Protocol Labs team has used to test **Lotus Miner**s on Lotus. There is no guarantee this testing configuration will be suitable for Filecoin storage mining at MainNet launch. If you need to buy new hardware to join the Filecoin Testnet, we recommend to buy no more hardware than you require for testing. To learn more please read this [Protocol Labs Standard Testing Configuration post](https://filecoin.io/blog/filecoin-testnet-mining/).
**Sector sizes** and **minimum pledged storage** required to mine blocks are two very important Filecoin Testnet parameters that impact hardware decisions. We will continue to refine all parameters during Testnet.
BECAUSE OF THIS, OUR STANDARD TESTING CONFIGURATION FOR FILECOIN MAINNET CAN AND WILL CHANGE. YOU HAVE BEEN WARNED.
## Example configuration
The setup below is a minimal example for sealing 32 GiB sectors on Lotus:
- 2 TB of hard drive space.
- 8 core CPU
- 128 GiB of RAM
Note that 1GB sectors don't require as high of specs, but are likely to be removed as we improve the performance of 32GB sector sealing.
For the first part of the sealing process, AMD CPU's are __highly recommended__, because of the `Intel SHA Extensions` instruction set that is available there ever since the `Zen` microarchitecture. Hence, AMD CPU's seem to perform much better on the testnet than other CPU's. Contrary to what the name implies, this extended instruction set is not available on recent Intel desktop/server chips.
## Testnet discoveries
- If you only have 128GiB of ram, enabling 256GB of **NVMe** swap on an SSD will help you avoid out-of-memory issues while mining.
## Benchmarked GPUs
GPUs are a must for getting **block rewards**. Here are a few that have been confirmed to generate **SNARKs** quickly enough to successfully mine blocks on the Lotus Testnet.
- GeForce RTX 2080 Ti
- GeForce RTX 2080 SUPER
- GeForce RTX 2080
- GeForce GTX 1080 Ti
- GeForce GTX 1080
- GeForce GTX 1060
## Testing other GPUs
If you want to test a GPU that is not explicitly supported, use the following global **environment variable**:
```sh
BELLMAN_CUSTOM_GPU="<NAME>:<NUMBER_OF_CORES>"
```
Here is an example of trying a GeForce GTX 1660 Ti with 1536 cores.
```sh
BELLMAN_CUSTOM_GPU="GeForce GTX 1660 Ti:1536"
```
To get the number of cores for your GPU, you will need to check your card’s specifications.
## Benchmarking
Here is a [benchmarking tool](https://github.com/filecoin-project/lotus/tree/master/cmd/lotus-bench) and a [GitHub issue thread](https://github.com/filecoin-project/lotus/issues/694) for those who wish to experiment with and contribute hardware setups for the **Filecoin Testnet**.

7
documentation/en/hardware.md
View File

@ -1,7 +0,0 @@
# Hardware
> This page is a work in progress. Exact mining requirements are still in the works.
Lotus can build and run on most [Linux](https://ubuntu.com/) and [MacOS](https://www.apple.com/macos) systems with at least 8GiB of RAM.
Windows is not yet supported.

51
documentation/en/install-lotus-arch.md
View File

@ -1,51 +0,0 @@
# Arch Linux Instructions
These steps will install the following dependencies:
- go (1.14 or higher)
- gcc (7.4.0 or higher)
- git (version 2 or higher)
- bzr (some go dependency needs this)
- jq
- pkg-config
- opencl-icd-loader
- opencl driver (like nvidia-opencl on arch) (for GPU acceleration)
- opencl-headers (build)
- rustup (proofs build)
- llvm (proofs build)
- clang (proofs build)
### Install dependencies
```sh
sudo pacman -Syu opencl-icd-loader gcc git bzr jq pkg-config opencl-icd-loader opencl-headers
```
### Install Go 1.14
Install the latest version of Go by following [the docs on their website](https://golang.org/doc/install).
### Clone the Lotus repository
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
### Build the Lotus binaries from source and install
! **If you are running an AMD platform or if your CPU supports SHA extensions you will want to build the Filecoin proofs natively**
```sh
make clean && make all
sudo make install
```
#### Native Filecoin FFI building
```sh
env env RUSTFLAGS="-C target-cpu=native -g" FFI_BUILD_FROM_SOURCE=1 make clean deps all
sudo make install
```
After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://lotu.sh/en+join-testnet).

54
documentation/en/install-lotus-fedora.md
View File

@ -1,54 +0,0 @@
# Fedora Instructions
> tested on 30
**NOTE:** If you have an AMD GPU the opencl instructions may be incorrect...
These steps will install the following dependencies:
- go (1.14 or higher)
- gcc (7.4.0 or higher)
- git (version 2 or higher)
- bzr (some go dependency needs this)
- jq
- pkg-config
- rustup (proofs build)
- llvm (proofs build)
- clang (proofs build)
### Install dependencies
```sh
$ sudo dnf -y update
$ sudo dnf -y install gcc git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
### Install Go 1.14
Install the latest version of Go by following [the docs on their website](https://golang.org/doc/install).
### Clone the Lotus repository
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
### Build the Lotus binaries from source and install
! **If you are running an AMD platform or if your CPU supports SHA extensions you will want to build the Filecoin proofs natively**
```sh
$ make clean && make all
$ sudo make install
```
#### Native Filecoin FFI building
```sh
env env RUSTFLAGS="-C target-cpu=native -g" FFI_BUILD_FROM_SOURCE=1 make clean deps all
sudo make install
```
After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus TestNet](https://lotu.sh/en+join-testnet).

54
documentation/en/install-lotus-ubuntu.md
View File

@ -1,54 +0,0 @@
# Ubuntu Instructions
These steps will install the following dependencies:
- go (1.14 or higher)
- gcc (7.4.0 or higher)
- git (version 2 or higher)
- bzr (some go dependency needs this)
- jq
- pkg-config
- opencl-icd-loader
- opencl driver (like nvidia-opencl on arch) (for GPU acceleration)
- opencl-headers (build)
- rustup (proofs build)
- llvm (proofs build)
- clang (proofs build)
### Install dependencies
```sh
sudo apt update
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl
sudo apt upgrade
```
### Install Go 1.14
Install the latest version of Go by following [the docs on their website](https://golang.org/doc/install).
### Clone the Lotus repository
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
### Build the Lotus binaries from source and install
! **If you are running an AMD platform or if your CPU supports SHA extensions you will want to build the Filecoin proofs natively**
```sh
make clean && make all
sudo make install
```
#### Native Filecoin FFI building
```sh
env env RUSTFLAGS="-C target-cpu=native -g" FFI_BUILD_FROM_SOURCE=1 make clean deps all
sudo make install
```
After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://lotu.sh/en+join-testnet).

145
documentation/en/install-systemd-services.md
View File

@ -1,145 +0,0 @@
# Use Lotus with systemd
Lotus is capable of running as a systemd service daemon. You can find installable service files for systemd in the [lotus repo scripts directory](https://github.com/filecoin-project/lotus/tree/master/scripts) as files with `.service` extension. In order to install these service files, you can copy these `.service` files to the default systemd unit load path.
The services expect their binaries to be present in `/usr/local/bin/`. You can use `make` to install them by running:
```sh
$ sudo make install
```
for `lotus` and `lotus-storage-miner` and
```sh
$ sudo make install-chainwatch
```
for the `chainwatch` tool.
## Installing services via `make`
If your host uses the default systemd unit load path, the `lotus-daemon` and `lotus-miner` services can be installed by running:
```sh
$ sudo make install-services
```
To install the the `lotus-chainwatch` service run:
```sh
$ sudo make install-chainwatch-service
```
You can install all services together by running:
```sh
$ sudo make install-all-services
```
The `lotus-daemon` and the `lotus-miner` services can be installed individually too by running:
```sh
$ sudo make install-daemon-service
```
and
```sh
$ sudo make install-miner-service
```
### Notes
When installing the `lotus-miner` and/or `lotus-chainwatch` service the `lotus-daemon` service gets automatically installed since the other two services depend on it being installed to run.
All `install-*-service*` commands will install the latest binaries in the lotus build folders to `/usr/local/bin/`. If you do not want to use the latest build binaries please copy the `*.service` files by hand.
## Removing via `make`
All services can beremoved via `make`. To remove all services together run:
```sh
$ sudo make clean-all-services
```
Individual services can be removed by running:
```sh
$ sudo make clean-chainwatch-services
$ sudo make clean-miner-services
$ sudo make clean-daemon-services
```
### Notes
The services will be stoppend and disabled when removed.
Removing the `lotus-daemon` service will automatically remove the depending services `lotus-miner` and `lotus-chainwatch`.
## Controlling services
All service can be controlled with the `systemctl`. A few basic control commands are listed below. To get detailed infos about the capabilities of the `systemctl` command please consult your distributions man pages by running:
```sh
$ man systemctl
```
### Start/Stop services
You can start the services by running:
```sh
$ sudo systemctl start lotus-daemon
$ sudo systemctl start lotus-miner
$ sudo systemctl start lotus-chainwatch
```
and can be stopped by running:
```sh
$ sudo systemctl stop lotus-daemon
$ sudo systemctl stop lotus-miner
$ sudo systemctl stop lotus-chainwatch
```
### Enabling services on startup
To enable the services to run automatically on startup execute:
```sh
$ sudo systemctl enable lotus-daemon
$ sudo systemctl enable lotus-miner
$ sudo systemctl enable lotus-chainwatch
```
To disable the services on startup run:
```sh
$ sudo systemctl disable lotus-daemon
$ sudo systemctl disable lotus-miner
$ sudo systemctl disable lotus-chainwatch
```
### Notes
Systemd will not let services be enabled or started without their requirements. Starting the `lotus-chainwatch` and/or `lotus-miner` service with automatically start the `lotus-daemon` service (if installed!). Stopping the `lotus-daemon` service will stop the other two services. The same pattern is executed for enabling and disabling the services.
## Interacting with service logs
Logs from the services can be reviewed using `journalctl`.
### Follow logs from a specific service unit
```sh
$ sudo journalctl -u lotus-daemon -f
```
### View logs in reverse order
```sh
$ sudo journalctl -u lotus-miner -r
```
### Log files
Besides the systemd service logs all services save their own log files in `/var/log/lotus/`.

129
documentation/en/installation/install-linux.md Normal file
View File

@ -0,0 +1,129 @@
# Linux installation
This page will show you the steps to build and install Lotus in your Linux computer.
## Dependencies
### System dependencies
First of all, building Lotus will require installing some system dependencies, usually provided by your distribution.
For Arch Linux:
```sh
sudo pacman -Syu opencl-icd-loader gcc git bzr jq pkg-config opencl-icd-loader opencl-headers
```
For Ubuntu:
```sh
sudo apt update
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl
sudo apt upgrade
```
For Fedora:
```sh
sudo dnf -y update
sudo dnf -y install gcc git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm
```
For OpenSUSE:
```sh
sudo zypper in gcc git jq make libOpenCL1 opencl-headers ocl-icd-devel clang llvm
sudo ln -s /usr/lib64/libOpenCL.so.1 /usr/lib64/libOpenCL.so
```
### Rustup
Lotus needs [rustup](https://rustup.rs/):
```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Please make sure your `$PATH` variable is correctly configured after the rustup installation so that `cargo` and `rustc` are found in their rustup-configured locations.
### Go
To build lotus you will need a working installation of **[Go1.14](https://golang.org/dl/)**. Follow the [installation instructions](https://golang.org/doc/install), which generally amount to:
```sh
# Example! Check the installation instructions.
wget -c https://dl.google.com/go/go1.14.7.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local
```
## Build and install Lotus
With all the above, you are ready to build and install the Lotus suite (`lotus`, `lotus-miner` and `lotus-worker`):
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
__IF YOU ARE IN CHINA__, set `export GOPROXY=https://goproxy.cn` before building
Now, choose the network that you will be joining:
* For `testnet`: `git checkout master`
* For `nerpa`: `git checkout ntwk-nerpa`
* For `butterfly`: `git checkout ntwk-butterfly`
Once on the right branch, do:
```sh
make clean install
sudo make install
```
This will put `lotus`, `lotus-miner` and `lotus-worker` in `/usr/local/bin`. `lotus` will use the `$HOME/.lotus` folder by default for storage (configuration, chain data, wallets...). `lotus-miner` will use `$HOME/.lotusminer` respectively. See the *environment variables* section below for how to customize these.
> Remeber to [move your Lotus folder](en+update) if you are switching between different networks, or there has been a network reset.
### Native Filecoin FFI
Some newer processors (AMD Zen (and later), Intel Ice Lake) have support SHA extensions. To make full use of your processor's capabilities, make sure you set the following variables BEFORE building from source (as described above):
```sh
export RUSTFLAGS="-C target-cpu=native -g"
export FFI_BUILD_FROM_SOURCE=1
```
> __NOTE__: This method of building does not produce portable binaries! Make sure you run the binary in the same machine as you built it.
### systemd service files
Lotus provides Systemd service files. They can be installed with:
```sh
make install-daemon-service
make install-miner-service
```
After that, you should be able to control Lotus using `systemctl`.
## Troubleshooting
This section mentions some of the common pitfalls for building Lotus. Check the [getting started](en+getting-started) section for more tips on issues when running the lotus daemon.
### Build errors
Please check the build logs closely. If you have a dirty state in your git branch make sure to:
```sh
git checkout <desired_branch>
git reset origin/<desired_branch> --hard
make clean
```
### Slow builds from China
Users from China can speed up their builds by setting:
```sh
export GOPROXY=https://goproxy.cn
```

2
documentation/en/install-lotus-macos.md → documentation/en/installation/install-macos.md
View File

@ -59,4 +59,4 @@ make clean && make all
sudo make install sudo make install
``` ```
After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus Testnet](https://lotu.sh/en+join-testnet). After intalling Lotus you will be ready to [setup and run the daemon](en+setup.md).

39
documentation/en/installation/installation.md Normal file
View File

@ -0,0 +1,39 @@
# Installation
Lotus can be installed in [Linux](en-install-linux) and [MacOS](en-install-macos) machines by building it from source. Windows is not supported yet.
This section contains guides to install Lotus in the supported platforms.
Lotus is made of 3 binaries:
* `lotus`: the main [Lotus node](en+setup) (Lotus client)
* `lotus-miner`: an application specifically for [Filecoin mining](en+miner-setup)
* `lotus-worker`: an additional [application to offload some heavy-processing tasks](en+lotus-worker) from the Lotus Miner.
These applications are written in Go, but also import several Rust libraries. Lotus does not distribute
pre-compiled builds.
## Hardware requirements
### For client nodes
* 8GiB of RAM
* Recommended for syncing speed: CPU with support for *Intel SHA Extensions* (AMD since Zen microarchitecture, Intel since Ice Lake).
* Recommended for speed: SSD hard drive (the bigger the better)
### For miners
The following correspond to the latest testing configuration:
* 2 TB of hard drive space
* 8 core CPU
* 128 GiB of RAM with 256 GiB of NVMe SSD storage for swap (or simply, more RAM).
* Recommended for speed: CPU with support for *Intel SHA Extensions* (AMD since Zen microarchitecture, Intel since Ice Lake).
* GPU for block mining. The following have been [confirmed to be fast enough](en+gpus):
- GeForce RTX 2080 Ti
- GeForce RTX 2080 SUPER
- GeForce RTX 2080
- GeForce GTX 1080 Ti
- GeForce GTX 1080
- GeForce GTX 1060

72
documentation/en/installation/update.md Normal file
View File

@ -0,0 +1,72 @@
# Updating and restarting Lotus
Updating Lotus is as simple as rebuilding and re-installing the software as explained in the previous sections.
You can verify which version of Lotus you are running with:
```sh
lotus version
```
Make sure that you `git pull` the branch that corresponds to the network that your Lotus daemon is using:
```sh
git pull origin <branch>
make clean
make all
sudo make install # if necessary
```
Finally, restart the Lotus Node and/or Lotus Miner(s).
__CAVEAT__: If you are running miners: check if your miner is safe to shut down and restart: `lotus-miner proving info`. If any deadline shows a block height in the past, do not restart:
In the following example, Deadline Open is 454 which is earlier than Current Epoch of 500. This miner should **not** be shut down or restarted.
```
$ sudo lotus-miner proving info
Miner: t01001
Current Epoch: 500
Proving Period Boundary: 154
Proving Period Start: 154 (2h53m0s ago)
Next Period Start: 3034 (in 21h7m0s)
Faults: 768 (100.00%)
Recovering: 768
Deadline Index: 5
Deadline Sectors: 0
Deadline Open: 454 (23m0s ago)
Deadline Close: 514 (in 7m0s)
Deadline Challenge: 434 (33m0s ago)
Deadline FaultCutoff: 384 (58m0s ago)
```
In this next example, the miner can be safely restarted because no Deadlines are earlier than Current Epoch of 497. You have ~45 minutes before the miner must be back online to declare faults (FaultCutoff). If the miner has no faults, you have about an hour.
```
$ sudo lotus-miner proving info
Miner: t01000
Current Epoch: 497
Proving Period Boundary: 658
Proving Period Start: 658 (in 1h20m30s)
Next Period Start: 3538 (in 25h20m30s)
Faults: 0 (0.00%)
Recovering: 0
Deadline Index: 0
Deadline Sectors: 768
Deadline Open: 658 (in 1h20m30s)
Deadline Close: 718 (in 1h50m30s)
Deadline Challenge: 638 (in 1h10m30s)
Deadline FaultCutoff: 588 (in 45m30s)
```
## Switching networks and network resets
If you wish to switch to a different lotus network or there has been a network reset, you will need to:
* Checkout the appropiate repository branch and rebuild
* Ensure you do not mix Lotus data (`LOTUS_PATH`, usually `~/.lotus`) from a previous or different network. For this, either:
* Rename the folder to something else or,
* Set a different `LOTUS_PATH` for the new network.
* Same for `~/.lotusminer` if you are running a miner.
Note that deleting the Lotus data folder will wipe all the chain data, wallets and configuration, so think twice before taking any non-reversible action.

93
documentation/en/join-testnet.md
View File

@ -1,93 +0,0 @@
# Join Testnet
## Introduction
Anyone can set up a **Lotus Node** and connect to the **Lotus Testnet**. This is the best way to explore the current CLI and the **Filecoin Decentralized Storage Market**.
## Note: Using the Lotus Node from China
If you are trying to use `lotus` from China. You should set this **environment variable** on your machine:
```sh
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
## Get started
Start the **daemon** using the default configuration in `./build`:
```sh
lotus daemon
```
In another terminal window, check your connection with peers:
```sh
lotus net peers | wc -l
```
In order to connect to the network, you need to be connected to at least 1 peer. If you’re seeing 0 peers, read our [troubleshooting notes](https://lotu.sh/en+setup-troubleshooting).
Make sure that you have a reasonable "open files limit" set on your machine, such as 10000. If you're seeing a lower value, such as 256 (default on macOS), read our [troubleshooting notes](https://lotu.sh/en+setup-troubleshooting) on how to update it prior to starting the Lotus daemon.
## Chain sync
While the daemon is running, the next requirement is to sync the chain. Run the command below to view the chain sync progress. To see current chain height, visit the [network stats page](https://stats.testnet.filecoin.io/).
```sh
lotus sync wait
```
- This step will take anywhere between a few hours to a couple of days.
- You will be able to perform **Lotus Testnet** operations after it is finished.
## Create your first address
Initialize a new wallet:
```sh
lotus wallet new
```
Sometimes your operating system may limit file name length to under 150 characters. You need to use a file system that supports long filenames.
Here is an example of the response:
```sh
t1aswwvjsae63tcrniz6x5ykvsuotlgkvlulnqpsi
```
- Visit the [faucet](http://spacerace.faucet.glif.io/) to add funds.
- Paste the address you created under REQUEST.
- Press the Request button.
## Check wallet address balance
Wallet balances in the Lotus Testnet are in **FIL**, the smallest denomination of FIL is an **attoFil**, where 1 attoFil = 10^-18 FIL.
```sh
lotus wallet balance <YOUR_NEW_ADDRESS>
```
You will not see any attoFIL in your wallet if your **chain** is not fully synced.
## Send FIL to another wallet
To send FIL to another wallet from your default account, use this command:
```
lotus send <target> <amount>
```
## Configure your node's connectivity
To effectively accept incoming storage & retrieval deals, your Lotus node needs to be accessible to other nodes on the network. To improve your connectivity, be sure to:
- [Set the multiaddresses for you miner to listen on](https://docs.filecoin.io/mine/connectivity/#setting-multiaddresses)
- [Maintain a healthy peer count](https://docs.filecoin.io/mine/connectivity/#checking-peer-count)
- [Enable port forwarding](https://docs.filecoin.io/mine/connectivity/#port-forwarding)
- [Configure your public IP address and port](https://docs.filecoin.io/mine/connectivity/#setting-a-public-ip-address)
## Monitor the dashboard
To see the latest network activity, including **chain block height**, **block height**, **blocktime**, **total network power**, largest **block producer miner**, check out the [monitoring dashboard](https://stats.testnet.filecoin.io).

39
documentation/en/miner-deals.md
View File

@ -1,39 +0,0 @@
# Information for Miners
Here is how a miner can get set up to accept storage deals. The first step is
to install a Lotus node and sync to the top of the chain.
## Set up an ask
```
lotus-miner set-price <price>
```
This command will set up your miner to accept deal proposals that meet the input price.
The price is inputted in FIL per GiB per epoch, and the default is 0.0000000005.
## Ensure you can be discovered
Clients need to be able to find you in order to make storage deals with you.
While there isn't necessarily anything you need to do to become discoverable, here are some things you can
try to check that people can connect to you.
To start off, make sure you are connected to at least some peers, and your port is
open and working.
### Connect to your own node
If you are in contact with someone else running Lotus, you can ask them to try connecting
to your node. To do so, provide them your peer ID, which you can get by running `lotus net id` on
your node.
They can then try running `lotus net findpeer <peerID>` to get your address(es), and can then
run `lotus net connect <address>` to connect to you. If successful, your node will now
appear on their peers list (run `lotus net peers` to check).
You can also check this by running a second instance of Lotus yourself.
### Query your own ask
A client should be able to find your ask by running `lotus client query-ask <minerID>`. If
someone is not able to retrieve your ask by doing so, then there is an issue with your node.

149
documentation/en/mining.md
View File

@ -1,149 +0,0 @@
# Storage Mining
Here are instructions to learn how to perform storage mining. For hardware specifications please read [this](https://lotu.sh/en+hardware-mining).
It is useful to [join the Testnet](https://lotu.sh/en+join-testnet) prior to attempting storage mining for the first time.
## Note: Using the Lotus Miner from China
If you are trying to use `lotus-miner` from China. You should set this **environment variable** on your machine.
```sh
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
## Get started
Please ensure that at least one **BLS address** (starts with `t3`) in your wallet exists with the following command:
```sh
lotus wallet list
```
If you do not have a bls address, create a new bls wallet:
```sh
lotus wallet new bls
```
With your wallet address:
- Visit the [faucet](http://spacerace.faucet.glif.io/)
- Paste the address you created under REQUEST.
- Press the Request button.
- Run `/lotus-miner init --owner=<blsAddress> --worker=<blsAddress>`
You will have to wait some time for this operation to complete.
## Mining
To mine:
```sh
lotus-miner run
```
If you are downloading **Filecoin Proof Parameters**, the download can take some time.
Get information about your miner:
```sh
lotus-miner info
# example: miner id `t0111`
```
**Seal** random data to start producing **PoSts**:
```sh
lotus-miner sectors pledge
```
- Warning: On Linux configurations, this command will write data to `$TMPDIR` which is not usually the largest partition. You should point the value to a larger partition if possible.
Get **miner power** and **sector usage**:
```sh
lotus state power
# returns total power
lotus state power <miner>
lotus state sectors <miner>
```
## Performance tuning
### `FIL_PROOFS_MAXIMIZE_CACHING=1` Environment variable
This env var can be used with `lotus-miner`, `lotus-worker`, and `lotus-bench` to make the precommit1 step faster at the cost of some memory use (1x sector size)
### `FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1` Environment variable
This env var can be used with `lotus-miner`, `lotus-worker`, and `lotus-bench` to enable experimental precommit2 GPU acceleration
### Setting multiaddresses
Set multiaddresses for the miner to listen on in a miner's `config.toml` file
(by default, it is located at `~/.lotusminer/config.toml`). The `ListenAddresses` in this file should be interface listen addresses (usually `/ip4/0.0.0.0/tcp/PORT`), and the `AnnounceAddresses` should match the addresses being passed to `set-addrs`.
The addresses passed to `set-addrs` parameter in the commands below should be currently active and dialable; confirm they are before entering them.
Once the config file has been updated, set the on-chain record of the miner's listen addresses:
```
lotus-miner actor set-addrs <multiaddr_1> <multiaddr_2> ... <multiaddr_n>
```
This updates the `MinerInfo` object in the miner's actor, which will be looked up
when a client attempts to make a deal. Any number of addresses can be provided.
Example:
```
lotus-miner actor set-addrs /ip4/123.123.73.123/tcp/12345 /ip4/223.223.83.223/tcp/23456
```
# Separate address for windowPoSt messages
WindowPoSt is the mechanism through which storage is verified in Filecoin. It requires miners to submit proofs for all sectors every 24h, which require sending messages to the chain.
Because many other mining related actions require sending messages to the chain, and not all of those are "high value", it may be desirable to use a separate account to send PoSt messages from. This allows for setting lower GasFeeCaps on the lower value messages without creating head-of-line blocking problems for the PoSt messages in congested chain conditions
To set this up, first create a new account, and send it some funds for gas fees:
```sh
lotus wallet new bls
t3defg...
lotus send t3defg... 100
```
Next add the control address
```sh
lotus-miner actor control set t3defg...
Add t3defg...
Pass --really-do-it to actually execute this action
```
Now actually set the addresses
```sh
lotus-miner actor control set --really-do-it t3defg...
Add t3defg...
Message CID: bafy2..
```
Wait for the message to land on chain
```sh
lotus state wait-msg bafy2..
...
Exit Code: 0
...
```
Check miner control address list to make sure the address was correctly setup
```sh
lotus-miner actor control list
name ID key use balance
owner t01111 t3abcd... other 300 FIL
worker t01111 t3abcd... other 300 FIL
control-0 t02222 t3defg... post 100 FIL
```

17
documentation/en/mining/gpus.md Normal file
View File

@ -0,0 +1,17 @@
# Benchmarking additional GPUs
If you want to test a GPU that is not explicitly supported, set the following *environment variable*:
```sh
BELLMAN_CUSTOM_GPU="<NAME>:<NUMBER_OF_CORES>"
```
Here is an example of trying a GeForce GTX 1660 Ti with 1536 cores.
```sh
BELLMAN_CUSTOM_GPU="GeForce GTX 1660 Ti:1536"
```
To get the number of cores for your GPU, you will need to check your card’s specifications.
To perform the benchmark you can use Lotus' [benchmarking tool](https://github.com/filecoin-project/lotus/tree/master/cmd/lotus-bench). Results and discussion are tracked in a [GitHub issue thread](https://github.com/filecoin-project/lotus/issues/694).

58
documentation/en/mining-lotus-worker.md → documentation/en/mining/lotus-seal-worker.md
View File

@ -2,24 +2,14 @@
The **Lotus Worker** is an extra process that can offload heavy processing tasks from your **Lotus Miner**. The sealing process automatically runs in the **Lotus Miner** process, but you can use the Worker on another machine communicating over a fast network to free up resources on the machine running the mining process. The **Lotus Worker** is an extra process that can offload heavy processing tasks from your **Lotus Miner**. The sealing process automatically runs in the **Lotus Miner** process, but you can use the Worker on another machine communicating over a fast network to free up resources on the machine running the mining process.
## Note: Using the Lotus Worker from China ## Installation
If you are trying to use `lotus-worker` from China. You should set this **environment variable** on your machine: The `lotus-worker` application is installed along with the others when running `sudo make install` as shown in the [Installation section](en+install-linux). For simplicity, we recommend following the same procedure in the machines that will run the Lotus Workers (even if the Lotus miner and the Lotus daemon are not used there).
```sh
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
## Get Started
Make sure that the `lotus-worker` is compiled and installed by running:
```sh
make lotus-worker
```
## Setting up the Miner ## Setting up the Miner
### Allow external connections to the miner API
First, you will need to ensure your `lotus-miner`'s API is accessible over the network. First, you will need to ensure your `lotus-miner`'s API is accessible over the network.
To do this, open up `~/.lotusminer/config.toml` (Or if you manually set `LOTUS_MINER_PATH`, look under that directory) and look for the API field. To do this, open up `~/.lotusminer/config.toml` (Or if you manually set `LOTUS_MINER_PATH`, look under that directory) and look for the API field.
@ -32,30 +22,49 @@ ListenAddress = "/ip4/127.0.0.1/tcp/2345/http"
RemoteListenAddress = "127.0.0.1:2345" RemoteListenAddress = "127.0.0.1:2345"
``` ```
To make your node accessible over the local area network, you will need to determine your machines IP on the LAN, and change the `127.0.0.1` in the file to that address. To make your node accessible over the local area network, you will need to determine your machine's IP on the LAN (`ip a`), and change the `127.0.0.1` in the file to that address.
A more permissive and less secure option is to change it to `0.0.0.0`. This will allow anyone who can connect to your computer on that port to access the [API](https://lotu.sh/en+api). They will still need an auth token. A more permissive and less secure option is to change it to `0.0.0.0`. This will allow anyone who can connect to your computer on that port to access the miner's API, though they will still need an auth token.
`RemoteListenAddress` must be set to an address which other nodes on your network will be able to reach. `RemoteListenAddress` must be set to an address which other nodes on your network will be able to reach.
Next, you will need to [create an authentication token](https://lotu.sh/en+api-scripting-support#generate-a-jwt-46). All Lotus APIs require authentication tokens to ensure your processes are as secure against attackers attempting to make unauthenticated requests to them. ### Create an authentication token
### Connect the Lotus Worker Write down the output of:
On the machine that will run `lotus-worker`, set the `MINER_API_INFO` environment variable to `TOKEN:MINER_NODE_MULTIADDR`. Where `TOKEN` is the token we created above, and `NIMER_NODE_MULTIADDR` is the `multiaddr` of the **Lotus Miner** API that was set in `config.toml`. ```sh
lotus-miner auth api-info --perm admin
```
Once this is set, run: The Lotus Workers will need this token to connect to the miner.
## Connecting the Lotus Workers
On each machine that will run the `lotus-worker` application you will need to define the following *environment variable*:
```sh
export MINER_API_INFO:<TOKEN>:/ip4/<miner_api_address>/tcp/2345`
```
If you are trying to use `lotus-worker` from China. You should additionally set:
```sh
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
Once that is done, you can run the Worker with:
```sh ```sh
lotus-worker run lotus-worker run
``` ```
If you are running multiple workers on the same host, you will need to specify the `--listen` flag and ensure each worker is on a different port. > If you are running multiple workers on the same host, you will need to specify the `--listen` flag and ensure each worker is on a different port.
To check that the **Lotus Worker** is connected to your **Lotus Miner**, run `lotus-miner sealing workers` and check that the remote worker count has increased. On your Lotus miner, check that the workers are correctly connected:
```sh ```sh
why@computer ~/lotus> lotus-miner sealing workers lotus-miner sealing workers
Worker 0, host computer Worker 0, host computer
CPU: [ ] 0 core(s) in use CPU: [ ] 0 core(s) in use
RAM: [|||||||||||||||||| ] 28% 18.1 GiB/62.7 GiB RAM: [|||||||||||||||||| ] 28% 18.1 GiB/62.7 GiB
@ -69,9 +78,10 @@ Worker 1, host othercomputer
GPU: GeForce RTX 2080, not used GPU: GeForce RTX 2080, not used
``` ```
### Running locally for manually managing process priority ## Running locally for manually managing process priority
You can also run the **Lotus Worker** on the same machine as your **Lotus Miner**, so you can manually manage the process priority. You can also run the **Lotus Worker** on the same machine as your **Lotus Miner**, so you can manually manage the process priority.
To do so you have to first __disable all seal task types__ in the miner config. This is important to prevent conflicts between the two processes. To do so you have to first __disable all seal task types__ in the miner config. This is important to prevent conflicts between the two processes.
You can then run the miner on your local-loopback interface; You can then run the miner on your local-loopback interface;

19
documentation/en/mining/managing-deals.md Normal file
View File

@ -0,0 +1,19 @@
# Managing deals
While the Lotus Miner is running as a daemon, the `lotus-miner` application can be used to manage and configure the miner:
```sh
lotus-miner storage-deals --help
```
Running the above command will show the different options related to deals. For example, `lotus-miner storage-deals set-ask` allows to set the price for storage that your miner uses to respond ask requests from clients.
If deals are ongoing, you can check the data transfers with:
```sh
lotus-miner data-transfers list
```
Make sure you explore the `lotus-miner` CLI. Every command is self-documented and takes a `--help` flag that offers specific information about it.

241
documentation/en/mining/miner-setup.md Normal file
View File

@ -0,0 +1,241 @@
# Miner setup
This page will guide you through all you need to know to sucessfully run a **Lotus Miner**. Before proceeding, remember that you should be running the Lotus daemon on a fully synced chain.
## Performance tweaks
This is a list of performance tweaks to consider before starting the miner:
### Building
As [explained already](en+install-linux#native-filecoin-ffi-10) should have exported the following variables before building the Lotus applications:
```sh
export RUSTFLAGS="-C target-cpu=native -g"
export FFI_BUILD_FROM_SOURCE=1
```
### Environment
For high performance mining, we recommend setting the following variables in your environment so that they are available when running any of the Lotus applications:
```sh
# See https://github.com/filecoin-project/bellman
export BELLMAN_CPU_UTILIZATION=0.875
# See https://github.com/filecoin-project/rust-fil-proofs/
export FIL_PROOFS_MAXIMIZE_CACHING=1 # More speed at RAM cost (1x sector-size of RAM - 32 GB).
export FIL_PROOFS_USE_GPU_COLUMN_BUILDER=1 # precommit2 GPU acceleration
export FIL_PROOFS_USE_GPU_TREE_BUILDER=1
```
IF YOU ARE RUNNING FROM CHINA:
```sh
export IPFS_GATEWAY="https://proof-parameters.s3.cn-south-1.jdcloud-oss.com/ipfs/"
```
IF YOUR MINER RUNS IN A DIFFERENT MACHINE AS THE LOTUS DAEMON:
```sh
export FULLNODE_API_INFO=<api_token>:/ip4/<lotus_daemon_ip>/tcp/<lotus_daemon_port>/http
```
If you will be using systemd service files to run the Lotus daemon and miner, make sure you include these variables manually in the service files.
### Adding swap
If you have only 128GiB of RAM, you will need to make sure your system provides at least an extra 256GiB of fast swap (preferably NVMe SSD):
```sh
sudo fallocate -l 256G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# show current swap spaces and take note of the current highest priority
swapon --show
# append the following line to /etc/fstab (ensure highest priority) and then reboot
# /swapfile swap swap pri=50 0 0
sudo reboot
# check a 256GB swap file is automatically mounted and has the highest priority
swapon --show
```
## Creating a new BLS wallet
You will need a BLS wallet (`t3...`) for mining. To create it, if you don't have one already, run:
```sh
lotus wallet new bls
```
Next make sure to [send some funds](en+wallet) to this address so that the miner setup can be completed.
## Initializing the miner
> SPACE RACE:
> To participate in the Space race, please register your miner:
>
> - Visit the [faucet](http://spacerace.faucet.glif.io/)
> - Paste the address you created under REQUEST.
> - Press the Request button.
Now that you have a miner address you can initialize the Lotus Miner:
```sh
lotus-miner init --owner=<bls address> --no-local-storage
```
* The `--no-local-storage` flag is used so that we configure specific locations for storage later below.
* The init process will download over 100GiB of initialization parameters to /var/tmp/filecoin-proof-parameters. Make sure there is space or set `FIL_PROOFS_PARAMETER_CACHE` to somewhere else.
* The Lotus Miner configuration folder is created at `~/.lotusminer/` or `$LOTUS_MINER_PATH` if set.
## Reachability
Before you start your miner, it is __very important__ to configure it so that it is reachable from any peer in the Filecoin network. For this you will need a stable public IP and edit your `~/.lotusminer/config.toml` as follows:
```toml
...
[Libp2p]
ListenAddresses = ["/ip4/0.0.0.0/tcp/24001"] # choose a fixed port
AnnounceAddresses = ["/ip4/<YOUR_PUBLIC_IP_ADDRESS>/tcp/24001"] # important!
...
```
Once you start your miner, make sure you can connect to its public IP/port (you can use `telnet`, `nc` for the task...). If you have an active firewall or some sort, you may need to additionally open ports in it.
## Starting the miner
You are now ready to start your Lotus miner:
```sh
lotus-miner run
```
or if you are using the systemd service file:
```sh
systemctl start lotus-miner
```
> __Do not proceed__ from here until you have verified that your miner not only is running, but also __reachable on its public IP address__.
## Publishing the miner addresses
Once the miner is up and running, publish your miner address (which you configured above) on the chain (please ensure it is dialable):
```sh
lotus-miner actor set-addrs /ip4/<YOUR_PUBLIC_IP_ADDRESS>/tcp/24001
```
## Setting locations for sealing and long-term storage
If you used the `--no-local-storage` flag during initialization, you can now specify the disk locations for sealing (SSD recommended) and long-term storage (otherwise you can skip this):
```
lotus-miner storage attach --init --seal <PATH_FOR_SEALING_STORAGE>
lotus-miner storage attach --init --store <PATH_FOR_LONG_TERM_STORAGE>
lotus-miner storage list
```
## Pledging sectors
If you would like to compete for block rewards by increasing your power in the network as soon as possible, you can optionally pledge one or several sectors, depending on your storage. It can also be used to test that the sealing process works correctly. Pledging is equivalent to storing random data instead of real data obtained through storage deals.
> Note that pledging sectors to the mainnet network makes most sense when trying to obtain a reasonable amount of total power in the network, thus obtaining real chances to mine new blocks. Otherwise it is only useful for testing purposes.
If you decide to go ahead, then do:
```sh
lotus-miner sectors pledge
```
This will write data to `$TMPDIR` so make sure that there is enough space available.
You shoud check that your sealing job has started with:
```sh
lotus-miner sealing jobs
```
This will be accommpanied by a file in `<PATH_FOR_SEALING_STORAGE>/unsealed`.
After some minutes, you can check the sealing progress with:
```sh
lotus-miner sectors list
# and
lotus-miner sealing workers
```
When sealing for the new is complete, `pSet: NO` will become `pSet: YES`.
Once the sealing is finished, you will want to configure how long it took your miner to seal this sector and configure the miner accordingly. To find out how long it took use:
```
lotus-miner sectors status --log 0
```
Once you know, you can edit the Miner's `~/.lotusminer/config.toml` accordingly:
```
...
[Dealmaking]
...
ExpectedSealDuration = "12h0m0s" # The time it took your miner
```
You can also take the chance to edit other values, such as `WaitForDealsDelay` which specifies the delay between accepting the first deal and sealing, allowing to place multiple deals in the same sector.
Once you are done editing the configuration, [restart your miner](en+update).
If you wish to be able to re-use a pledged sector for real storage deals before the pledged period of 6 months ends, you will need to mark them for upgrade:
```sh
lotus-miner sectors mark-for-upgrade <sector number>
```
The sector should become inactive within 24 hours. From that point, the pledged storage can be re-used to store real data associated with real storage deals.
## Separate address for windowPoSt messages
WindowPoSt is the mechanism through which storage is verified in Filecoin. It requires miners to submit proofs for all sectors every 24h, which require sending messages to the chain.
Because many other mining related actions require sending messages to the chain, and not all of those are "high value", it may be desirable to use a separate account to send PoSt messages from. This allows for setting lower GasFeeCaps on the lower value messages without creating head-of-line blocking problems for the PoSt messages in congested chain conditions
To set this up, first create a new account, and send it some funds for gas fees:
```sh
lotus wallet new bls
t3defg...
lotus send t3defg... 100
```
Next add the control address:
```sh
lotus-miner actor control set --really-do-it t3defg...
Add t3defg...
Message CID: bafy2..
```
Wait for the message to land on chain:
```sh
lotus state wait-msg bafy2..
...
Exit Code: 0
...
```
Finally, check the miner control address list to make sure the address was correctly setup:
```sh
lotus-miner actor control list
name ID key use balance
owner t01111 t3abcd... other 300 FIL
worker t01111 t3abcd... other 300 FIL
control-0 t02222 t3defg... post 100 FIL
```

9
documentation/en/mining-troubleshooting.md → documentation/en/mining/mining-troubleshooting.md
View File

@ -25,7 +25,7 @@ lotus-miner info
# WARN main lotus-storage-miner/main.go:73 failed to get api endpoint: (/Users/myrmidon/.lotusminer) %!w(*errors.errorString=&{API not running (no endpoint)}): # WARN main lotus-storage-miner/main.go:73 failed to get api endpoint: (/Users/myrmidon/.lotusminer) %!w(*errors.errorString=&{API not running (no endpoint)}):
``` ```
If you see this, that means your **Lotus Miner** isn't ready yet. You need to finish [syncing the chain](https://lotu.sh/en+join-testnet). If you see this, that means your **Lotus Miner** isn't ready yet. You need to finish [syncing the chain](en+setup#waiting-to-sync-370).
## Error: Your computer may not be fast enough ## Error: Your computer may not be fast enough
@ -57,10 +57,3 @@ make bench
This process uses a fair amount of GPU, and generally takes ~4 minutes to complete. If you do not see any activity in nvtop from lotus during the entire process, it is likely something is misconfigured with your GPU. This process uses a fair amount of GPU, and generally takes ~4 minutes to complete. If you do not see any activity in nvtop from lotus during the entire process, it is likely something is misconfigured with your GPU.
## Checking Sync Progress
You can use this command to check how far behind you are on syncing:
```sh
date -d @$(./lotus chain getblock $(./lotus chain head) | jq .Timestamp)
```

8
documentation/en/mining/mining.md Normal file
View File

@ -0,0 +1,8 @@
# Storage Mining
This section of the documentation explains how to do storage mining with Lotus. Please note that not everyone can do storage mining, and that you should not attempt it on on networks where sector sizes are 32GB+ unless you meet the [hardware requirements](en+install#hardware-requirements-1).
From this point we assume that you have setup and are running the [Lotus Node](en+setup), that it has fully synced the Filecoin chain and that you are familiar with how to interact with it using the `lotus` command-line interface.
In order to perform storage mining, apart from the Lotus daemon, you will be additionally interacting with the `lotus-miner` and potentially the `lotus-worker` applications (which you should have [installed](en+install-linux) along the `lotus` application already).

27
documentation/en/retrieving-data.md
View File

@ -1,27 +0,0 @@
# Retrieving Data
> There are recent bug reports with these instructions. If you happen to encounter any problems, please create a [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a maintainer will address the problem as soon as they can.
Here are the operations you can perform after you have stored and sealed a **Data CID** with the **Lotus Miner** in the network.
If you would like to learn how to store a **Data CID** on a miner, read the instructions [here](https://lotu.sh/en+storing-data).
## Find by Data CID
```sh
lotus client find <Data CID>
# LOCAL
# RETRIEVAL <miner>@<miner peerId>-<deal funds>-<size>
```
## Retrieve by Data CID
All fields are required.
```sh
lotus client retrieve <Data CID> <outfile>
```
If the outfile does not exist it will be created in the Lotus repository directory.
This command will initiate a **retrieval deal** and write the data to your computer. This process may take 2 to 10 minutes.

54
documentation/en/setting-a-static-port.md
View File

@ -1,54 +0,0 @@
# Static Ports
Depending on how your network is set up, you may need to set a static port to successfully connect to peers to perform storage deals with your **Lotus Miner**.
## Setup
To change the random **swarm port**, you may edit the `config.toml` file located under `$LOTUS_MINER_PATH`. The default location of this file is `$HOME/.lotusminer`.
To change the port to `1347`:
```sh
[Libp2p]
ListenAddresses = ["/ip4/0.0.0.0/tcp/1347", "/ip6/::/tcp/1347"]
```
After changing the port value, restart your **daemon**.
## Announce Addresses
If the **swarm port** is port-forwarded from another address, it is possible to control what addresses
are announced to the network.
```sh
[Libp2p]
AnnounceAddresses = ["/ip4/<public-ip>/tcp/1347"]
```
If non-empty, this array specifies the swarm addresses to announce to the network. If empty, the daemon will announce inferred swarm addresses.
Similarly, it is possible to set `NoAnnounceAddresses` with an array of addresses to not announce to the network.
## Ubuntu's Uncomplicated Firewall
Open firewall manually:
```sh
ufw allow 1347/tcp
```
Or open and modify the profile located at `/etc/ufw/applications.d/lotus-daemon`:
```sh
[Lotus Daemon]
title=Lotus Daemon
description=Lotus Daemon firewall rules
ports=1347/tcp
```
Then run these commands:
```sh
ufw update lotus-daemon
ufw allow lotus-daemon
```

6
documentation/en/storing-ipfs-integration.md → documentation/en/store/adding-from-ipfs.md
View File

@ -1,10 +1,10 @@
# IPFS Integration # Adding data from IPFS
Lotus supports making deals with data stored in IPFS, without having to re-import it into lotus. Lotus supports making deals with data stored in IPFS, without having to re-import it into lotus.
To enable this integration, you need to have an IPFS daemon running in the background. To enable this integration, you need to have an IPFS daemon running in the background.
Then, open up `~/.lotus/config.toml` (or if you manually set `LOTUS_PATH`, look under that directory)
and look for the Client field, and set `UseIpfs` to `true`. Then, open up `~/.lotus/config.toml` (or if you manually set `LOTUS_PATH`, look under that directory) and look for the Client field, and set `UseIpfs` to `true`.
```toml ```toml
[Client] [Client]

71
documentation/en/store/making-deals.md Normal file
View File

@ -0,0 +1,71 @@
# Making storage deals
## Adding a file to Lotus
Before sending data to a Filecoin miner for storage, the data needs to be correctly formatted and packed. This can be achieved by locally importing the data into Lotus with:
```sh
lotus client import ./your-example-file.txt
```
Upon success, this command will return a **Data CID**. This is a very important piece of information, as it will be used to make deals to both store and retrieve the data in the future.
You can list the data CIDs of the files you locally imported with:
```sh
lotus client local
```
## Storing data in the network
To store data in the network you will need to:
* Find a Filecoin miner willing to store it
* Make a deal with the miner agreeing on the price to pay and the duration for which the data should be stored.
You can obtain a list of all miners in the network with:
```sh
lotus state list-miners
t0xxxx
t0xxxy
t0xxxz
...
```
This will print a list of miner IDs. In order to ask for the terms offered by a particular miner, you can then run:
```sh
lotus client query-ask <miner>
```
If you are satisfied with the terms, you can proceed to propose a deal to the miner, using the **Data CID** that you obtained during the import step:
```sh
lotus client deal
```
This command will interactively ask you for the CID, miner ID and duration in days for the deal. You can also call it with arguments:
```sh
lotus client deal <data CID> <miner> <price> <duration>
```
where the `duration` is expressed in blocks (1 block is equivalent to 30s).
## Checking the status of the deals
You can list deals with:
```sh
lotus client list-deals
```
Among other things, this will give you information about the current state on your deals, whether they have been published on chain (by the miners) and whether the miners have been slashed for not honoring them.
For a deal to succeed, the miner needs to be correctly configured and running, accept the deal and *seal* the file correctly. Otherwise, the deal will appear in error state.
You can make deals with multiple miners for the same data.
Once a deal is sucessful and the data is *sealed*, it can be [retrieved](en+retrieving).

27
documentation/en/store/retrieve.md Normal file
View File

@ -0,0 +1,27 @@
# Retrieving Data
Once data has been succesfully [stored](en+making-deals) and sealed by a Filecoin miner, it can be retrieved.
In order to do this we will need to create a **retrieval deal**.
## Finding data by CID
In order to retrieve some data you will need the **Data CID** that was used to create the storage deal.
You can find who is storing the data by running:
```sh
lotus client find <Data CID>
```
## Making a retrieval deal
You can then make a retrieval deal with:
```sh
lotus client retrieve <Data CID> <outfile>
```
This commands take other optional flags (check `--help`).
If the outfile does not exist it will be created in the Lotus repository directory. This process may take 2 to 10 minutes.

13
documentation/en/storing-data-troubleshooting.md → documentation/en/store/storage-troubleshooting.md
View File

@ -2,11 +2,11 @@
## Error: Routing: not found ## Error: Routing: not found
```sh ```
WARN main lotus/main.go:72 routing: not found WARN main lotus/main.go:72 routing: not found
``` ```
- This miner is offline. This error means that the miner is offline.
## Error: Failed to start deal ## Error: Failed to start deal
@ -14,14 +14,17 @@ WARN main lotus/main.go:72 routing: not found
WARN main lotus/main.go:72 failed to start deal: computing commP failed: generating CommP: Piece must be at least 127 bytes WARN main lotus/main.go:72 failed to start deal: computing commP failed: generating CommP: Piece must be at least 127 bytes
``` ```
- There is a minimum file size of 127 bytes. This error means that there is a minimum file size of 127 bytes.
## Error: 0kb file response during retrieval ## Error: 0kb file response during retrieval
In order to retrieve a file, it must be sealed. Miners can check sealing progress with this command: This means that the file to be retrieved may have not yet been sealed and is thus, not retrievable yet.
Miners can check sealing progress with this command:
```sh ```sh
lotus-miner sectors list lotus-miner sectors list
``` ```
When sealing is complete, `pSet: NO` will become `pSet: YES`. From now on the **Data CID** is [retrievable](https://lotu.sh/en+retrieving-data) from the **Lotus Miner**. When sealing is complete, `pSet: NO` will become `pSet: YES`.

11
documentation/en/store/store.md Normal file
View File

@ -0,0 +1,11 @@
# Storing and retrieving data
Lotus enables you to store any data on the Filecoin network and retrieve it later. This is achieved by making *deals* with miners.
A *storage deal* specifies that a miner should store ceratin data for a previously agreed period and price.
Once a deal is made, the data is then sent to the miners, which regularly proves that it is storing it. If they fail to do so, the miner is penalized (slashed).
The data can be retrieved with a *retrieval deal*.
This section explains how to use Lotus to [store](en+making-deals) and [retrieve](en+retrieving) data from the Filecoin network.

62
documentation/en/storing-data.md
View File

@ -1,62 +0,0 @@
# Storing Data
> There are recent bug reports with these instructions. If you happen to encounter any problems, please create a [GitHub issue](https://github.com/filecoin-project/lotus/issues/new) and a maintainer will address the problem as soon as they can.
Here are instructions for how to store data on the **Lotus Testnet**.
## Adding a file locally
Adding a file locally allows you to make miner deals on the **Lotus Testnet**.
```sh
lotus client import ./your-example-file.txt
```
Upon success, this command will return a **Data CID**.
## List your local files
The command to see a list of files by `CID`, `name`, `size` in bytes, and `status`:
```sh
lotus client local
```
An example of the output:
```sh
bafkreierupr5ioxn4obwly4i2a5cd2rwxqi6kwmcyyylifxjsmos7hrgpe Development/sample-1.txt 2332 ok
bafkreieuk7h4zs5alzpdyhlph4lxkefowvwdho3a3pml6j7dam5mipzaii Development/sample-2.txt 30618 ok
```
## Make a Miner Deal on Lotus Testnet
Get a list of all miners that can store data:
```sh
lotus state list-miners
```
Get the requirements of a miner you wish to store data with:
```sh
lotus client query-ask <miner>
```
Store a **Data CID** with a miner:
```sh
lotus client deal <Data CID> <miner> <price> <duration>
```
Check the status of a deal:
```sh
lotus client list-deals
```
- The `duration`, which represents how long the miner will keep your file hosted, is represented in blocks. Each block represents 25 seconds.
Upon success, this command will return a **Deal CID**.
The miner will need to **seal** the file before it can be retrieved. If the **Lotus Miner** is not running on a machine designed for sealing, the process will take a very long time.

0
documentation/en/dev/WIP-arch-complementary-notes.md → documentation/en/unclassified/WIP-arch-complementary-notes.md
View File

0
documentation/en/block-validation.md → documentation/en/unclassified/block-validation.md
View File

0
documentation/en/dev/create-miner.md → documentation/en/unclassified/create-miner.md
View File

0
documentation/en/dev-tools-pond-ui.md → documentation/en/unclassified/dev-tools-pond-ui.md
View File

0
documentation/en/sealing-procs.md → documentation/en/unclassified/sealing-procs.md
View File

14
documentation/en/updating-lotus.md
View File

@ -1,14 +0,0 @@
# Updating Lotus
If you installed Lotus on your machine, you can upgrade to the latest version by doing the following:
```sh
# get the latest
git pull origin master
# clean and remake the binaries
make clean && make build
# instal binaries in correct location
make install # or sudo make install if necessary
```