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

Merge pull request #3431 from filecoin-project/feat/docs-reorg

Browse Source 
Docs review and re-organization
This commit is contained in:
Łukasz Magiera 2020-09-29 22:29:58 +02:00 committed by GitHub
commit 6025bceaa1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
40 changed files with 52 additions and 2122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -1,5 +1,5 @@
<p align="center">
<a href="https://lotu.sh/" title="Lotus Docs">
<a href="https://docs.filecoin.io/" title="Filecoin Docs">
<img src="documentation/images/lotus_logo_h.png" alt="Project Lotus Logo" width="244" />
</a>
</p>
@ -18,7 +18,7 @@ Lotus is an implementation of the Filecoin Distributed Storage Network. For more
## Building & Documentation
For instructions on how to build lotus from source, please visit [Lotus build and setup instruction](https://docs.filecoin.io/get-started/lotus/installation/#minimal-requirements) or read the source [here](https://github.com/filecoin-project/lotus/tree/master/documentation).
For instructions on how to build, install and setup lotus, please visit [https://docs.filecoin.io/get-started/lotus](https://docs.filecoin.io/get-started/lotus/).
## Reporting a Vulnerability

147
documentation/en/.glossary.json
View File

@ -1,146 +1 @@
{
"bellman": {
"title": "Bellman",
"value": "Bellman is a rust crate for building zk-SNARK circuits. It provides circuit traits and primitive structures, as well as basic gadget implementations such as booleans and number abstractions."
},
"nvme": {
"title": "NVMe",
"value": "(non-volatile memory express) is a host controller interface and storage protocol created to accelerate the transfer of data between enterprise and client systems and solid-state drives (SSDs) over a computer's high-speed Peripheral Component Interconnect Express (PCIe) bus."
},
"multiaddr": {
"title": "Multiaddr",
"value": "Multiaddr is a format for encoding addresses from various well-established network protocols. It is useful to write applications that future-proof their use of addresses, and allow multiple transport protocols and addresses to coexist."
},
"attofil": {
"title": "attoFIL",
"value": "AttoFIL is a word used to describe 10^-18 FIL. The word atto comes from the Norwegian and Danish term: atten eighteen."
},
"fil": {
"title": "FIL",
"value": "A ticker symbol is an abbreviation used to uniquely identify Filecoin when it is used in a wallet exchange or a cryptocurrency exchange."
},
"epost": {
"title": "Election Proof-of-Spacetime",
"value": "Election Proof-of-Spacetime couples the Proof-of-Spacetime process with block production, meaning that in order to produce a block, the miner must produce a valid Proof-of-Spacetime proof (snark output)."
},
"jwt": {
"title": "JWT",
"value": "JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties."
},
"json-rpc": {
"title": "JSON-RPC",
"value": "JSON-RPC is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a few data types and commands."
},
"bls-address": {
"title": "BLS Signature (Address)",
"value": "A Boneh–Lynn–Shacham (BLS) signature is a digital signature scheme that allows a user to determine the authenticity of a signer, and is a commonly used signature scheme in the Filecoin Distributed Storage Network."
},
"faucet": {
"title": "Filecoin Test Faucet",
"value": "A webpage where you can get free test Filecoin to participate in the Testnet."
},
"chain": {
"title": "Chain",
"value": "The Filecoin Blockchain is a distributed virtual machine that achieves consensus, processes messages, accounts for storage, and maintains security in the Filecoin Protocol. It is the main interface linking various actors in the Filecoin system."
},
"miner-power": {
"title": "Miner Power",
"value": "Miner storage in relation to network storage, tracked in the power table."
},
"sector": {
"title": "Sector",
"value": "A fixed-size block of data of SECTOR_SIZE bytes which generally contains client's data."
},
"sealing": {
"title": "Sealing",
"value": "A slow encoding process that returns commitments and proofs for data being stored in a sector."
},
"seal": {
"title": "Seal",
"value": "A slow encoding process that returns commitments and proofs for data being stored in a sector."
},
"posts": {
"title": "Proof-of-Spacetime(s)",
"value": "Filecoin is a protocol token whose blockchain runs on a novel proof, called Proof-of-Spacetime, where blocks are created by miners that are storing data."
},
"filecoin-testnet": {
"title": "Filecoin Testnet",
"value": "Until we launch, we are making lots of changes to Lotus. The Testnet is expected to bring a few significant fixes/improvements. During Testnet, you can retrieve test filecoin from our network faucet to use as collateral to start mining. Test filecoin do not have any value – the official filecoin tokens will not be released until Mainnet launch."
},
"filecoin-decentralized-storage-market": {
"title": "Filecoin Decentralized Storage Market",
"value": "Storage Market subsystem is the data entry point into the network. Miners only earn power from data stored in a storage deal and all deals live on the Filecoin network."
},
"filecoin-proof-parameters": {
"title": "Filecoin Proof Parameters",
"value": "The proving algorithms rely on a large binary parameter file."
},
"lotus-devnet": {
"title": "DevNet",
"value": "On the DevNets, you can store data as a storage client and also try how Filecoin mining works. The devnets are an important development tool for those who anticipate building applications on top of the Filecoin protocol or storing data on the decentralized storage market. "
},
"filecoin-distributed-storage-network": {
"title": "Filecoin Distributed Storage Network",
"value": "Filecoin is a distributed storage network based on a blockchain mechanism. Filecoin miners can elect to provide storage capacity for the network, and thereby earn units of the Filecoin cryptocurrency (FIL) by periodically producing cryptographic proofs that certify that they are providing the capacity specified."
},
"lotus-node": {
"title": "Lotus Node",
"value": "The Lotus Node is full of capabilities. It runs the Blockchain system, makes retrieval deals, does data transfer, supports block producer logic, and syncs and validates the chain."
},
"block-rewards": {
"title": "Block Reward",
"value": "Over the entire lifetime of the protocol, 1,400,000,000 FIL (TotalIssuance) will be given out to miners. The rate at which the funds are given out is set to halve every six years, smoothly (not a fixed jump like in Bitcoin)."
},
"block-producer-miner": {
"title": "Miner (Block Producer)",
"value": "The Block Producer Miner's logic. It currently shares an interface and process with the Lotus Node. A Block Producer chooses which messages to include in a block and is rewarded according to each message’s gas price and consumption, forming a market."
},
"lotus-miner": {
"title": "Miner (lotus-miner)",
"value": "The Miner's logic. It has its own dedicated process. Contributes to the network through Sector commitments and Proofs of Spacetime to prove that it is storing the sectors it has commited to."
},
"swarm-port": {
"title": "Swarm Port (Libp2p)",
"value": "The LibP2P Swarm manages groups of connections to peers, handles incoming and outgoing streams, and is part of the miners implementation. The port value is part of the Host interface."
},
"daemon": {
"title": "Lotus Daemon",
"value": "A Daemon is a program that runs as a background process. A Daemon in the context of the Filecoin Distributed Storage Network may enable applications to communicate with peers, handle protocols, participate in pubsub, and interact with a distributed hash table (DHT)."
},
"storage-deal": {
"title": "Storage deal",
"value": "One of the two types of deals in Filecoin markets. Storage deals are recorded on the blockchain and enforced by the protocol."
},
"retrieval-deal": {
"title": "Retrieval deal",
"value": "One of the two types of deals in Filecoin markets. Retrieval deals are off chain and enabled by micropayment channel by transacting parties."
},
"deal-cid": {
"title": "Deal CID",
"value": "CID is a format for referencing content in distributed information systems, it is a way to store information so it can be retrieved based on its content, not its location. DealCID specifically is used in storage deals."
},
"data-cid": {
"title": "Data CID",
"value": "CID is a format for referencing content in distributed information systems, it is a way to store information so it can be retrieved based on its content, not its location. DataCID specifically is used to represent the file that is stored in the Filecoin Distributed Storage Network."
},
"cid": {
"title": "CID",
"value": "A CID is a self-describing content-addressed identifier. It uses cryptographic hashes to achieve content addressing. It uses several multiformats to achieve flexible self-description, namely multihash for hashes, multicodec for data content types, and multibase to encode the CID itself into strings."
},
"total-network-power": {
"title": "Total Network Power",
"value": "A reference to all the Power Tables for every subchain, accounting for each Lotus Miner on chain."
},
"chain-block-height": {
"title": "Chain Block Height",
"value": "Chain block height is defined as the number of blocks in the chain between any given block and the very first block in the blockchain."
},
"block-height": {
"title": "Block Height",
"value": "Height of the Merkle Tree of a sector. A sector is a contiguous array of bytes that a miner puts together, seals, and performs Proofs of Spacetime on."
},
"blocktime": {
"title": "Blocktime",
"value": "The time it takes for a Block to propagate to the whole network."
}
}
{}

221
documentation/en/.library.json
View File

@ -1,232 +1,25 @@
{
"posts": [
{
"title": "Hardware Requirements",
"slug": "en+hardware",
"github": "en/hardware.md",
"title": "About Lotus",
"slug": "",
"github": "en/about.md",
"value": null,
"posts": [
{
"title": "Testing Configuration",
"slug": "en+hardware-mining",
"github": "en/hardware-mining.md",
"value": null
}
]
"posts": []
},
{
"title": "Setup",
"slug": "en+getting-started",
"github": "en/getting-started.md",
"value": null,
"posts": [
{
"title": "Arch Linux Installation",
"slug": "en+install-lotus-arch",
"github": "en/install-lotus-arch.md",
"value": null
},
{
"title": "Ubuntu Installation",
"slug": "en+install-lotus-ubuntu",
"github": "en/install-lotus-ubuntu.md",
"value": null
},
{
"title": "Fedora Installation",
"slug": "en+install-lotus-fedora",
"github": "en/install-lotus-fedora.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": "Lotus Architecture (WIP)",
"slug": "en+arch",
"github": "en/architecture.md",
"github": "en/architecture/architecture.md",
"value": null,
"posts": [
{
"title": "The Message Pool",
"slug": "en+mpool",
"github": "en/mpool.md",
"github": "en/architecture/mpool.md",
"value": null
}
]
},
{
"title": "Storage Mining",
"slug": "en+mining",
"github": "en/mining.md",
"value": null,
"posts": [
{
"title": "Lotus Worker",
"slug": "en+lotus-worker",
"github": "en/mining-lotus-worker.md",
"value": null
},
{
"title": "Static Ports",
"slug": "en+setting-a-static-port",
"github": "en/setting-a-static-port.md",
"value": null
},
{
"title": "Mining Troubleshooting",
"slug": "en+mining-troubleshooting",
"github": "en/mining-troubleshooting.md",
"value": null
}
]
},
{
"title": "Storing Data",
"slug": "en+storing-data",
"github": "en/storing-data.md",
"value": null,
"posts": [
{
"title": "Storage Troubleshooting",
"slug": "en+storing-data-troubleshooting",
"github": "en/storing-data-troubleshooting.md",
"value": null
},
{
"title": "Information for Miners",
"slug": "en+info-for-miners",
"github": "en/miner-deals.md",
"value": null
},
{
"title": "IPFS Integration",
"slug": "en+ipfs-client-integration",
"github": "en/storing-ipfs-integration.md",
"value": null
}
]
},
{
"title": "Retrieving Data",
"slug": "en+retrieving-data",
"github": "en/retrieving-data.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,
"posts": [
{
"title": "Remote API Support",
"slug": "en+api-scripting-support",
"github": "en/api-scripting-support.md",
"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": []
}
]
},
{
"title": "FAQs",
"slug": "en+faqs",
"github": "en/faqs.md",
"value": null,
"posts": []
},
{
"title": "Glossary",
"slug": "en+glossary",
"github": "en/.glossary.json",
"value": null,
"custom": {
"glossary": true
},
"posts": []
}
]
}

16
documentation/en/README.md Normal file
View File

@ -0,0 +1,16 @@
# Lotus documentation
This folder contains some Lotus documentation mostly intended for Lotus developers.
User documentation (including documentation for miners) has been moved to specific Lotus sections in https://docs.filecoin.io:
- https://docs.filecoin.io/get-started/lotus
- https://docs.filecoin.io/store/lotus
- https://docs.filecoin.io/mine/lotus
- https://docs.filecoin.io/build/lotus
## The Lotu.sh site
The https://lotu.sh and https://docs.lotu.sh sites are generated from this folder based on the index provided by [.library.json](.library.json). This is done at the [lotus-docs repository](https://github.com/filecoin-project/lotus-docs), which contains Lotus as a git submodule.
To update the site, the lotus-docs repository should be updated with the desired version for the lotus git submodule. Once pushed to master, it will be auto-deployed.

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

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

@ -0,0 +1,19 @@
# Lotus
Lotus is an implementation of the **Filecoin Distributed Storage Network**.
It is written in Go and provides a suite of command-line applications:
- Lotus Node (`lotus`): a Filecoin Node: validates network transactions, manages a FIL wallet, can perform storage and retrieval deals.
- Lotus Miner (`lotus-miner`): a Filecoin miner. See the the respective Lotus Miner section in the Mine documentation.
- Lotus Worker (`lotus-worker`): a worker that assists miners to perform mining-related tasks. See its respective guide for more information.
The [Lotus user documentation](https://docs.filecoin.io/get-started/lotus) is part of the [Filecoin documentation site](https://docs.filecoin.io):
* To install and get started with Lotus, visit the [Get Started section](https://docs.filecoin.io/get-started/lotus).
* Information about how to perform deals on the Filecoin network using Lotus can be found in the [Store section](https://docs.filecoin.io/store/lotus).
* Miners looking to provide storage to the Network can find the latest guides in the [Mine section](https://docs.filecoin.io/mine/lotus).
* Developers and integrators that wish to use the Lotus APIs can start in the [Build section](https://docs.filecoin.io/mine/lotus).
For more details about Filecoin, check out the [Filecoin Docs](https://docs.filecoin.io) and [Filecoin Spec](https://spec.filecoin.io/).

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`.

36
documentation/en/api-troubleshooting.md
View File

@ -1,36 +0,0 @@
# API Troubleshooting
## Types: params
`params` must be an array. If there are no `params` you should still pass an empty array.
## Types: TipSet
For methods such as `Filecoin.StateMinerPower`, where the method accepts the argument of the type `TipSet`, you can pass `null` to use the current chain head.
```sh
curl -X POST \
-H "Content-Type: application/json" \
--data '{ "jsonrpc": "2.0", "method": "Filecoin.StateMinerPower", "params": ["t0101", null], "id": 3 }' \
'http://127.0.0.1:1234/rpc/v0'
```
## Types: Sending a CID
If you do not serialize the CID as a [JSON IPLD link](https://did-ipid.github.io/ipid-did-method/#txref), you will receive an error. Here is an example of a broken CURL request:
```sh
curl -X POST \
-H "Content-Type: application/json" \
--data '{ "jsonrpc": "2.0", "method":"Filecoin.ClientGetDealInfo", "params": ["bafyreiaxl446wlnu6t6dpq4ivrjf4gda4gvsoi4rr6mpxau7z25xvk5pl4"], "id": 0 }' \
'http://127.0.0.1:1234/rpc/v0'
```
To fix it, change the `params` property to:
```sh
curl -X POST \
-H "Content-Type: application/json" \
--data '{ "jsonrpc": "2.0", "method":"Filecoin.ClientGetDealInfo", "params": [{"/": "bafyreiaxl446wlnu6t6dpq4ivrjf4gda4gvsoi4rr6mpxau7z25xvk5pl4"}], "id": 0 }' \
'http://127.0.0.1:1234/rpc/v0'
```

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/).
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

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

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!

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

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`.

138
documentation/en/faqs.md
View File

@ -1,138 +0,0 @@
# Frequently Asked Questions
Here are some FAQs concerning the Lotus implementation and participation in
Testnet.
For questions concerning the broader Filecoin project, please
go [here](https://filecoin.io/faqs/).
## Introduction to Lotus
### What is Lotus?
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.
More information about Lotus can be found [here](https://lotu.sh/).
### What are the components of Lotus?
Lotus is composed of two separate pieces that can talk to each other:
The Lotus Node can sync the blockchain, validating all blocks, transfers, and deals
along the way. It can also facilitate the creation of new storage deals. If you are not
interested in providing your own storage to the network, and do not want to produce blocks
yourself, then the Lotus Node is all you need!
The Lotus Miner does everything you need for the registration of storage, and the
production of new blocks. The Lotus Miner communicates with the network by talking
to a Lotus Node over the JSON-RPC API.
## Setting up a Lotus Node
### How do I set up a Lotus Node?
Follow the instructions found [here](https://lotu.sh/en+getting-started).
### Where can I get the latest version of Lotus?
Download the binary tagged as the `Latest Release` from the
[Lotus Github repo](https://github.com/filecoin-project/lotus/releases).
### What operating systems can Lotus run on?
Lotus can build and run on most Linux and MacOS systems with at least
8GB of RAM. Windows is not yet supported.
### How can I update to the latest version of Lotus?
To update Lotus, follow the instructions [here](https://lotu.sh/en+updating-lotus).
### How do I prepare a fresh installation of Lotus?
Stop the Lotus daemon, and delete all related files, including sealed and chain data by
running `rm ~/.lotus ~/.lotusminer`.
Then, install Lotus afresh by following the instructions
found [here](https://lotu.sh/en+getting-started).
### Can I configure where the node's config and data goes?
Yes! The `LOTUS_PATH` variable sets the path for where the Lotus node's data is written.
The `LOTUS_MINER_PATH` variable does the same for miner-specific information.
## Interacting with a Lotus Node
### How can I communicate with a Lotus Node?
Lotus Nodes have a command-line interface, as well as a JSON-RPC API.
### What are the commands I can send using the command-line interface?
The command-line interface is self-documenting, try running `lotus --help` from the `lotus` home
directory for more.
### 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
[here](https://lotu.sh/en+api). A JavaScript client is under development.
### What are the requests I can send over the JSON-RPC API?
Please have a look at the
[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
### What is Testnet?
Testnet is a live network of Lotus Nodes run by the
community for testing purposes.
It has 2 PiB of storage (and growing!) dedicated to it.
### 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
yet to be confirmed.
### How can I see the status of Testnet?
The [dashboard](https://stats.testnet.filecoin.io/) displays the status of the network as
well as a ton
of other metrics you might find interesting.
## Mining with a Lotus Node on Testnet
### How do I get started mining with Lotus?
Follow the instructions found [here](https://lotu.sh/en+mining).
### What are the minimum hardware requirements?
An example test configuration, and minimum hardware requirements can be found
[here](https://lotu.sh/en+hardware-mining).
Note that these might NOT be the minimum requirements for mining on Mainnet.
### 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).
### Why is my GPU not being used when sealing a sector?
Sealing a sector does not involve constant GPU operations. It's possible
that your GPU simply isn't necessary at the moment you checked.
## Advanced questions
### Is there a Docker image for lotus?
Community-contributed Docker and Docker Compose examples are available
[here](https://github.com/filecoin-project/lotus/tree/master/tools/dockers/docker-examples).
### How can I run two miners on the same machine?
You can do so by changing the storage path variable for the second miner, e.g.,
`LOTUS_MINER_PATH=~/.lotusminer2`. You will also need to make sure that no ports collide.
### How do I setup my own local devnet?
Follow the instructions found [here](https://lotu.sh/en+setup-local-dev-net).

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.

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).

62
documentation/en/install-lotus-macos.md
View File

@ -1,62 +0,0 @@
# MacOS Instructions
## Get XCode Command Line Tools
To check if you already have the XCode Command Line Tools installed via the CLI, run:
```sh
xcode-select -p
```
If this command returns a path, you can move on to the next step. Otherwise, to install via the CLI, run:
```sh
xcode-select --install
```
To update, run:
```sh
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
```
## Get HomeBrew
We recommend that MacOS users use [HomeBrew](https://brew.sh) to install each the necessary packages.
Check if you have HomeBrew:
```sh
brew -v
```
This command returns a version number if you have HomeBrew installed and nothing otherwise.
In your terminal, enter this command to install Homebrew:
```sh
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
Use the command `brew install` to install the following packages:
```sh
brew install go bzr jq pkg-config rustup
```
Clone
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
Build
```sh
make clean && make 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-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/`.

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

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).

54
documentation/en/local-dev-net.md
View File

@ -1,54 +0,0 @@
# Setup Local Devnet
Build the Lotus Binaries in debug mode, This enables the use of 2048 byte sectors.
```sh
make 2k
```
Set the `LOTUS_SKIP_GENESIS_CHECK` environment variable to `_yes_`. This tells your
Lotus node that it's okay if the genesis being used doesn't match any baked-in
genesis.
```sh
export LOTUS_SKIP_GENESIS_CHECK=_yes_
```
Download the 2048 byte parameters:
```sh
./lotus fetch-params 2048
```
Pre-seal some sectors:
```sh
./lotus-seed pre-seal --sector-size 2KiB --num-sectors 2
```
Create the genesis block and start up the first node:
```sh
./lotus-seed genesis new localnet.json
./lotus-seed genesis add-miner localnet.json ~/.genesis-sectors/pre-seal-t01000.json
./lotus daemon --lotus-make-genesis=devgen.car --genesis-template=localnet.json --bootstrap=false
```
Then, in another console, import the genesis miner key:
```sh
./lotus wallet import --as-default ~/.genesis-sectors/pre-seal-t01000.key
```
Set up the genesis miner:
```sh
./lotus-miner init --genesis-miner --actor=t01000 --sector-size=2KiB --pre-sealed-sectors=~/.genesis-sectors --pre-sealed-metadata=~/.genesis-sectors/pre-seal-t01000.json --nosync
```
Now, finally, start up the miner:
```sh
./lotus-miner run --nosync
```
If all went well, you will have your own local Lotus Devnet running.

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.

81
documentation/en/mining-lotus-worker.md
View File

@ -1,81 +0,0 @@
# Lotus Worker
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
If you are trying to use `lotus-worker` 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
Make sure that the `lotus-worker` is compiled and installed by running:
```sh
make lotus-worker
```
## Setting up the Miner
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.
Default config:
```toml
[API]
ListenAddress = "/ip4/127.0.0.1/tcp/2345/http"
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.
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.
`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.
### Connect the Lotus Worker
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`.
Once this is set, run:
```sh
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.
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.
```sh
why@computer ~/lotus> lotus-miner sealing workers
Worker 0, host computer
CPU: [ ] 0 core(s) in use
RAM: [|||||||||||||||||| ] 28% 18.1 GiB/62.7 GiB
VMEM: [|||||||||||||||||| ] 28% 18.1 GiB/62.7 GiB
GPU: GeForce RTX 2080, not used
Worker 1, host othercomputer
CPU: [ ] 0 core(s) in use
RAM: [|||||||||||||| ] 23% 14 GiB/62.7 GiB
VMEM: [|||||||||||||| ] 23% 14 GiB/62.7 GiB
GPU: GeForce RTX 2080, not used
```
### 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.
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;
```sh
lotus-worker run
```

66
documentation/en/mining-troubleshooting.md
View File

@ -1,66 +0,0 @@
# Mining Troubleshooting
## Config: Filecoin Proof Parameters directory
If you want to put the **Filecoin Proof Parameters** in a different directory, use the following environment variable:
```sh
FIL_PROOFS_PARAMETER_CACHE
```
## Error: Can't acquire bellman.lock
The **Bellman** lockfile is created to lock a GPU for a process. This bug can occur when this file isn't properly cleaned up:
```sh
mining block failed: computing election proof: github.com/filecoin-project/lotus/miner.(*Miner).mineOne
```
This bug occurs when the miner can't acquire the `bellman.lock`. To fix it you need to stop the `lotus-miner` and remove `/tmp/bellman.lock`.
## Error: Failed to get api endpoint
```sh
lotus-miner info
# WARN main lotus-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).
## Error: Your computer may not be fast enough
```sh
CAUTION: block production took longer than the block delay. Your computer may not be fast enough to keep up
```
If you see this, that means your computer is too slow and your blocks are not included in the chain, and you will not receive any rewards.
## Error: No space left on device
```sh
lotus-miner sectors pledge
# No space left on device (os error 28)
```
If you see this, that means `pledge-sector` wrote too much data to `$TMPDIR` which by default is the root partition (This is common for Linux setups). Usually your root partition does not get the largest partition of storage so you will need to change the environment variable to something else.
## Error: GPU unused
If you suspect that your GPU is not being used, first make sure it is properly configured as described in the [testing configuration page](hardware-mining.md). Once you've done that (and set the `BELLMAN_CUSTOM_GPU` as appropriate if necessary) you can verify your GPU is being used by running a quick lotus-bench benchmark.
First, to watch GPU utilization run `nvtop` in one terminal, then in a separate terminal, run:
```sh
make bench
./bench sealing --sector-size=2KiB
```
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)
```

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
```

111
documentation/en/payment-channels.md
View File

@ -1,111 +0,0 @@
# Payment Channels
Payment channels are used to transfer funds between two actors.
For example in lotus a payment channel is created when a client wants to fetch data from a provider.
The client sends vouchers for the payment channel, and the provider sends data in response.
The payment channel is created on-chain with an initial amount.
Vouchers allow the client and the provider to exchange funds incrementally off-chain.
The provider can submit vouchers to chain at any stage.
Either party to the payment channel can settle the payment channel on chain.
After a settlement period (currently 12 hours) either party to the payment channel can call collect on chain.
Collect sends the value of submitted vouchers to the channel recipient (the provider), and refunds the remaining channel balance to the channel creator (the client).
Vouchers have a lane, a nonce and a value, where vouchers with a higher nonce supersede vouchers with a lower nonce in the same lane.
Each deal is created on a different lane.
Note that payment channels and vouchers can be used for any situation in which two parties need to incrementally transfer value between each other off-chain.
## Using the CLI
For example a client creates a payment channel to a provider with value 10 FIL.
```sh
$ lotus paych add-funds <client addr> <provider addr> 10
<channel addr>
```
The client creates a voucher in lane 0 (implied) with nonce 1 (implied) and value 2.
```sh
$ lotus paych voucher create <channel addr> 2
<voucher>
```
The client sends the voucher to the provider and the provider adds the voucher to their local store.
```sh
$ lotus paych voucher add <channel addr> <voucher>
```
The provider sends some data to the client.
The client creates a voucher in lane 0 (implied) with nonce 2 (implied) and value 4.
```sh
$ lotus paych voucher create <channel addr> 4
<voucher>
```
The client sends the voucher to the provider and the provider adds the voucher and sends back more data.
etc.
The client can add value to the channel after it has been created by calling `paych add-funds` with the same client and provider addresses.
```sh
$ lotus paych add-funds <client addr> <provider addr> 5
<channel addr> # Same address as above. Channel now has 15
```
Once the client has received all their data, they may settle the channel.
Note that settlement doesn't have to be done immediately.
For example the client may keep the channel open as long as it wants to continue making deals with the provider.
```sh
$ lotus paych settle <channel addr>
```
The provider can submit vouchers to chain (note that lotus does this automatically when it sees a settle message appear on chain).
The provider may have received many vouchers with incrementally higher values.
The provider should submit the best vouchers. Note that there will be one best voucher for each lane.
```sh
$ lotus paych voucher best-spendable <channel addr>
<voucher>
<voucher>
<voucher>
$ lotus paych voucher submit <channel addr> <voucher>
```
Once the settlement period is over, either the client or provider can call collect to disburse funds.
```sh
$ lotus paych collect <channel addr>
```
Check the status of a channel that is still being created using `lotus paych status-by-from-to`.
```sh
$ lotus paych status-by-from-to <from addr> <to addr>
Creating channel
From: t3sb6xzvs6rhlziatagevxpp3dwapdolurtkpn4kyh3kgoo4tn5o7lutjqlsnvpceztlhxu3lzzfe34rvpsjgq
To: t1zip4sblhyrn4oxygzsm6nafbsynp2avmk3xafea
Pending Amt: 10000
Wait Sentinel: bafy2bzacedk2jidsyxcynusted35t5ipkhu2kpiodtwyjr3pimrhke6f5pqbm
```
Check the status of a channel that has been created using `lotus paych status`.
```sh
$ lotus paych status <channel addr>
Channel exists
Channel: t2nydpzhmeqkmid5smtqnowlr2mr5az6rexpmyv6i
From: t3sb6xzvs6rhlziatagevxpp3dwapdolurtkpn4kyh3kgoo4tn5o7lutjqlsnvpceztlhxu3lzzfe34rvpsjgq
To: t1zip4sblhyrn4oxygzsm6nafbsynp2avmk3xafea
Confirmed Amt: 10000
Pending Amt: 6000
Queued Amt: 3000
Voucher Redeemed Amt: 2000
```

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
```

46
documentation/en/setup-troubleshooting.md
View File

@ -1,46 +0,0 @@
# Setup Troubleshooting
## Config: Clearing data
Here is a command that will delete your chain data, stored wallets, stored data and any miners you have set up:
```sh
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.
## Error: Failed to connect bootstrap peer
```sh
WARN peermgr peermgr/peermgr.go:131 failed to connect to bootstrap peer: failed to dial : all dials failed
* [/ip4/147.75.80.17/tcp/1347] failed to negotiate security protocol: connected to wrong peer
```
- Try running the build steps again and make sure that you have the latest code from GitHub.
```sh
ERROR hello hello/hello.go:81 other peer has different genesis!
```
- Try deleting your file system's `~/.lotus` directory. Check that it exists with `ls ~/.lotus`.
```sh
- repo is already locked
```
- You already have another lotus daemon running.
## Config: Open files limit
On most systems you can check the open files limit with:
```sh
ulimit -n
```
You can also modify this number by using the `ulimit` command. It gives you the ability to control the resources available for the shell or process started by it. If the number is below 10000, you can change it with the following command prior to starting the Lotus daemon:
```sh
ulimit -n 10000
```

27
documentation/en/storing-data-troubleshooting.md
View File

@ -1,27 +0,0 @@
# Storage Troubleshooting
## Error: Routing: not found
```sh
WARN main lotus/main.go:72 routing: not found
```
- This miner is offline.
## Error: Failed to start deal
```sh
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.
## Error: 0kb file response during retrieval
In order to retrieve a file, it must be sealed. Miners can check sealing progress with this command:
```sh
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**.

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.

20
documentation/en/storing-ipfs-integration.md
View File

@ -1,20 +0,0 @@
# IPFS Integration
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.
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
[Client]
UseIpfs = true
```
After restarting the lotus daemon, you should be able to make deals with data in your IPFS node:
```sh
$ ipfs add -r SomeData
QmSomeData
$ ./lotus client deal QmSomeData t01000 0.0000000001 80000
```

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
```

2
tools/dockers/docker-examples/README.md
View File

@ -11,7 +11,7 @@ In this `docker-examples/` directory are community-contributed Docker and Docker
- local node for a developer (`api-local-`)
- hosted endpoint for apps / multiple developers (`api-hosted-`)
- **For a local devnet or shared devnet**
- basic local devnet (also see [lotus docs on setting up a local devnet](https://lotu.sh/en+setup-local-dev-net))
- basic local devnet (also see [lotus docs on setting up a local devnet](https://docs.filecoin.io/build/local-devnet/))
- shared devnet