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

Merge pull request #765 from filecoin-project/@jimmylee/current-documentation

Browse Source 
documentation: current state of public documentation from https://docs.lotu.sh
This commit is contained in:
Jim 2019-12-06 07:30:22 -08:00 committed by GitHub
commit 6114de84d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 316 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
documentation/cn/.gitkeep
View File

3
documentation/cn/api.md Normal file
View File

@ -0,0 +1,3 @@
# API
工作正在进行中

3
documentation/cn/dev-tools-jaegar-tracing.md Normal file
View File

@ -0,0 +1,3 @@
# Jaegar Tracing
工作正在进行中

3
documentation/cn/dev-tools-pond-ui.md Normal file
View File

@ -0,0 +1,3 @@
# Pond UI
工作正在进行中

3
documentation/cn/dev-tools.md Normal file
View File

@ -0,0 +1,3 @@
# Development Tools
工作正在进行中

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

@ -0,0 +1,3 @@
# Lotus
工作正在进行中

3
documentation/cn/hardware-mining.md Normal file
View File

@ -0,0 +1,3 @@
# Mining Hardware
工作正在进行中

3
documentation/cn/hardware.md Normal file
View File

@ -0,0 +1,3 @@
# Hardware
工作正在进行中

3
documentation/cn/install-lotus-arch.md Normal file
View File

@ -0,0 +1,3 @@
# Arch Linux Instructions
工作正在进行中

3
documentation/cn/install-lotus-macos.md Normal file
View File

@ -0,0 +1,3 @@
# MacOS Instructions
工作正在进行中

3
documentation/cn/install-lotus-ubuntu.md Normal file
View File

@ -0,0 +1,3 @@
# Ubuntu Instructions
工作正在进行中

3
documentation/cn/join-devnet.md Normal file
View File

@ -0,0 +1,3 @@
# Join DevNet
工作正在进行中

3
documentation/cn/mining.md Normal file
View File

@ -0,0 +1,3 @@
# Storage Mining
工作正在进行中

3
documentation/cn/retrieving-data.md Normal file
View File

@ -0,0 +1,3 @@
# Retrieving Data
工作正在进行中

3
documentation/cn/setting-a-static-port.md Normal file
View File

@ -0,0 +1,3 @@
# Static Ports
工作正在进行中

3
documentation/cn/storing-data.md Normal file
View File

@ -0,0 +1,3 @@
# Storing Data
工作正在进行中

8
documentation/en/api.md
View File

@ -2,17 +2,17 @@
> This document is a work in progress.
The systems API is defined in here. The **JSON RPC** maps directly to the API defined here using the [JSON RPC package](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
The systems API is defined in here. The **JSON-RPC** maps directly to the API defined here using the [JSON-RPC package](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
## Overview
By default `127.0.0.1:1234` - **daemon** stores the API endpoint multiaddr in `~/.lotus/api`
- `http://[api:port]/rpc/v0` - **JSON RPC** HTTP endpoint
- `ws://[api:port]/rpc/v0` - **JSON RPC** websocket endpoint
- `http://[api:port]/rpc/v0` - **JSON-RPC** HTTP endpoint
- `ws://[api:port]/rpc/v0` - **JSON-RPC** websocket endpoint
- `PUT http://[api:port]/rest/v0/import` - import file to the node repo, it requires write permission.
For **JSON RPC** interface definition see [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go). Required permissions are
For **JSON-RPC** interface definition see [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go). Required permissions are
defined in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go)
## Auth

2
documentation/en/dev-tools-jaegar-tracing.md
View File

@ -1,4 +1,4 @@
# Tracing
# Jaegar Tracing
Lotus has tracing built into many of its internals. To view the traces, first download [Jaeger](https://www.jaegertracing.io/download/) (Choose the 'all-in-one' binary). Then run it somewhere, start up the lotus daemon, and open up localhost:16686 in your browser.

6
documentation/en/dev-tools-pond-ui.md
View File

@ -5,16 +5,16 @@ Pond is a graphical testbed for [Lotus](https://docs.lotu.sh). Using it will set
## Build
```sh
$ make pond
make pond
```
## Run
```sh
$ ./pond run
./pond run
```
Now go to http://127.0.0.1:2222.
Now go to `http://127.0.0.1:2222`.
## What can I test?

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

@ -1,15 +1,15 @@
# Lotus
Lotus is an alternative implementation of the **Filecoin Distributed Storage Network**. It is the only implementation you will be able to use when the **Filecoin TestNet** launches.
Lotus is an alternative implementation of the **Filecoin Distributed Storage Network**. You can run the Lotus software client to join the **Filecoin TestNet** (when it launches).
For more details about Filecoin, check out the [Filecoin Spec](https://github.com/filecoin-project/specs).
## What can I learn here?
- How to install Lotus on [Arch Linux](https://docs.lotu.sh/install-lotus-arch), [Ubuntu](https://docs.lotu.sh/install-lotus-ubuntu), or [MacOS](https://docs.lotu.sh/install-lotus-macos).
- Joining the **Lotus DevNet** using your [CLI](https://docs.lotu.sh/join-devnet-cli).
- [Storing](https://docs.lotu.sh/storing-data) or [retrieving](https://docs.lotu.sh/retrieving-data) data.
- Mining Filecoin using the **Lotus Storage Miner** in your [CLI](https://docs.lotu.sh/mining).
- How to install Lotus on [Arch Linux](https://docs.lotu.sh/en+install-lotus-arch), [Ubuntu](https://docs.lotu.sh/en+install-lotus-ubuntu), or [MacOS](https://docs.lotu.sh/en+install-lotus-macos).
- Joining the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).
- [Storing](https://docs.lotu.sh/en+storing-data) or [retrieving](https://docs.lotu.sh/en+retrieving-data) data.
- Mining Filecoin using the **Lotus Storage Miner** in your [CLI](https://docs.lotu.sh/en+mining).
## What makes Lotus different?
@ -18,6 +18,6 @@ Lotus is architected modularly to keep clean API boundaries while using the same
- The **Lotus Node**
- The **Lotus Storage Miner**
The **Lotus Storage Miner** is intended to be run on the machine that manages a single storage miner instance, and is meant to communicate with the **Lotus Node** via the websockets **JSON RPC** API for all of the chain interaction needs.
The **Lotus Storage Miner** is intended to be run on the machine that manages a single storage miner instance, and is meant to communicate with the **Lotus Node** via the websockets **JSON-RPC** API for all of the chain interaction needs.
This way, a mining operation may easily run a **Lotus Storage Miner** or many of them, connected to one or many **Lotus Node** instances.

33
documentation/en/glossary.md
View File

@ -1,33 +0,0 @@
# Glossary
**Chain: Types**
Implementation of data structures used by Filecoin and their serializations.
**Chain: Store**
The chainstore manages all local chain state, including block headers, messages, and state.
**Chain: State**
A package for dealing with the Filecoin state tree. Wraps the [HAMT](https://github.com/ipfs/go-hamt-ipld).
**Chain: Actors**
Implementations of the builtin Filecoin network actors.
**Chain: VM**
The Filecoin state machine 'vm'. Implemented here are utilities to invoke Filecoin actor methods.
**Miner**
The block producer logic. This package interfaces with the full node through the API, despite currently being implemented in the same process (very likely to be extracted as its own separate process in the near future).
**Storage**
The storage miner logic. This package also interfaces with the full node through a subset of the api. This code is used to implement the `lotus-storage-miner` process.
**Pond**
[Pond](https://docs.lotu.sh/testing-with-gui) is a graphical testbed for lotus. It can be used to spin up nodes, connect them in a given topology, start them mining, and observe how they function over time.

5
documentation/en/hardware-mining.md Normal file
View File

@ -0,0 +1,5 @@
# Mining Hardware
> This page is a work in progress. EVERYTHING HERE CAN CHANGE AND WILL CHANGE. PURCHASE HARDWARE AT YOUR OWN RISK.
Please check out this [GitHub issue](https://github.com/filecoin-project/lotus/issues/694) to see benchmarks from existing hardware setups if you plan on participating in the **Filecoin TestNet**

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

@ -30,15 +30,15 @@ sudo pacman -Syu go gcc git bzr jq pkg-config opencl-icd-loader opencl-headers
Clone
```sh
$ git clone https://github.com/filecoin-project/lotus.git
$ cd lotus/
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
Install
```sh
$ make clean all
$ sudo make install
make clean all
sudo make install
```
Now you can use the command `lotus` in the command line.
Now you can use the command `lotus` in the CLI and join the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).

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

@ -1,34 +1,65 @@
# MacOS Instructions
> This document is a work in progress.
We recommend for MacOS users to use [HomeBrew](https://brew.sh/) to install each package.
Install these dependencies for MacOS Catalina.
## HomeBrew installation
- go (1.13 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)
Clone
Run `terminal.app` and enter this command:
```sh
$ git clone https://github.com/filecoin-project/lotus.git
$ cd lotus/
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
Install
Use the command `brew install` to install the following packages:
```sh
$ make clean all
$ sudo make install
brew install go
brew install bzr
brew install jq
brew install pkg-config
brew install rustup
```
Now you can use the command `lotus` in the command line.
## Clone
```sh
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
## Build
```sh
make clean all
sudo make install
```
Now you can use the command `lotus` in the CLI and join the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).
## Troubleshooting
You may run into problems with running `lotus daemon`, here are some common cases:
```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`.
## Explanations
Some errors will occur that do not prevent Lotus from working:
```sh
ERROR chainstore store/store.go:564 get message get failed: <Data CID>: blockstore: block not found
```
* Someone is requesting a **Data CID** from you that you don't have.

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

@ -33,15 +33,15 @@ sudo apt install golang-go gcc git bzr jq pkg-config mesa-opencl-icd ocl-icd-ope
Clone
```sh
$ git clone https://github.com/filecoin-project/lotus.git
$ cd lotus/
git clone https://github.com/filecoin-project/lotus.git
cd lotus/
```
Install
```sh
$ make clean all
$ sudo make install
make clean all
sudo make install
```
Now you can use the command `lotus` in the command line.
Now you can use the command `lotus` in the CLI and join the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).

82
documentation/en/join-devnet-cli.md
View File

@ -1,82 +0,0 @@
# Join DevNet
## Setup
If you have run Lotus before and want to remove all previous data: `rm -rf ~/.lotus ~/.lotusstorage`
## Genesis & Bootstrap
The current Lotus build will automatically join the **Lotus DevNet** using the genesis and bootstrap files in the `build/`.
## Start Daemon
```sh
$ lotus daemon
```
In another window check that you are connected to the network:
```sh
$ lotus net peers | wc -l
2 # number of peers
```
Wait for the **chain** to finish syncing:
```sh
$ lotus sync wait
```
You can view latest **chain block height** along with other network metrics at the [chain block height explorer](https://lotus-metrics.kittyhawk.wtf/chain).
## Basics
Create a new address:
```sh
$ lotus wallet new bls
t3...
```
- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/funds.html)
- Paste the address you created
- Press Send.
Check the wallet balance (balance is listed in attoFIL, where 1 attoFIL = 10^-18 FIL):
```sh
$ lotus wallet balance [optional address (t3...)]
```
If you see an error like `actor not found` after executing this command, it means that either:
* Your **Lotus Node** isn't fully synced
* There are no transactions to this address yet on chain.
If the latter, using the **faucet** should fix this.
## Make a deal
It is possible for a **Lotus Node** Client to make a deal with a **Lotus Storage Miner** on the same **Lotus Node**.
```sh
# List all miners in the system. Choose one to make a deal with.
$ lotus state list-miners
# List asks proposed by a miner
$ lotus client query-ask <miner>
# Propose a deal with a miner. Price is in attoFIL/byte/block. Duration is # of blocks.
$ lotus client deal <Data CID> <miner> <price> <duration>
```
Here is an example of what could happen
> `$ lotus client deal bafkre...qvtjsi t0111 36000 12` proposes a deal to store **Data CID** `bafkre...qvtjsi` with miner `t0111` at price `36000` for a duration of `12` blocks. If successful, the `client deal` command will return a **Deal CID**.
## Monitoring Dashboard
To see the latest network activity, including **chain block height**, **blocktime**, **total network power**, largest **block producer miner**, check out the [monitoring dashboard](https://lotus-metrics.kittyhawk.wtf).

62
documentation/en/join-devnet.md Normal file
View File

@ -0,0 +1,62 @@
# Join DevNet
## Introduction
Anyone can set up a **Lotus Node** and connect to the **Lotus DevNet**. This is the best way to explore the current CLI and the **Filecoin Decentralized Storage Market**.
If you have run Lotus before, you may need to clear existing data if you encounter errors.
```sh
rm -rf ~/.lotus ~/.lotusstorage
```
## 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
```
Synchronize the **chain**:
```sh
lotus sync wait
```
Congrats! Now you can perform **Lotus DevNet** operations.
## Exploring the chain
View **chain block height** along with other network metrics at our [chain explorer](https://lotus-metrics.kittyhawk.wtf/chain).
## Create a new address
```sh
lotus wallet new bls
t3...
```
- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/funds.html)
- Paste the address you created.
- Press the send button.
## Check wallet address balance
Wallet balances for the DevNet are in attoFIL. 1 attoFIL = 10^-18 FIL
```sh
lotus wallet balance [optional address (t3...)]
```
You will not see any attoFIL in your wallet if your **chain** is not fully synced.
## Monitoring Dashboard
To see the latest network activity, including **chain block height**, **blocktime**, **total network power**, largest **block producer miner**, check out the [monitoring dashboard](https://lotus-metrics.kittyhawk.wtf).

74
documentation/en/mining.md
View File

@ -1,63 +1,87 @@
# Getting started
# Storage Mining
Ensure that at least one **BLS address** (`t3..`) in your wallet exists
Here are instructions to learn how to perform storage mining. For hardware specifications please read [this](https://docs.lotu.sh/en+hardware-mining).
It is useful to [join the DevNet](https://docs.lotu.sh/en+join-devnet) prior to attempting storage mining for the first time.
## Get started
Please ensure that at least one **BLS address** (`t3..`) in your wallet exists with the following command:
```sh
$ lotus wallet list
t3...
lotus wallet list
```
With this address, go to the [faucet](https://lotus-faucet.kittyhawk.wtf/miner.html), and
click `Create Miner`
Wait for a page telling you the address of the newly created **Lotus Storage Miner** to appear.
The screen should show: `New storage miners address is: t0..`
## Initialize
Await this response:
```sh
$ lotus-storage-miner init --actor=t01.. --owner=t3....
To initialize the storage miner run the following command
```
This command should return successfully after **Lotus Storage Miner** is setup on **chain**. It usually takes 30 to 60 seconds.
## Start mining
## Initialize the storage miner
```sh
$ lotus-storage-miner run
lotus-storage-miner init --actor=ACTOR_VALUE_RECEIVED --owner=OWNER_VALUE_RECEIVED
```
To view the miner id used for deals:
Example
```sh
$ lotus-storage-miner info
lotus-storage-miner init --actor=t01424 --owner=t3spmep2xxsl33o4gxk7yjxcobyohzgj3vejzerug25iinbznpzob6a6kexcbeix73th6vjtzfq7boakfdtd6a
```
e.g. miner id `t0111`
This command will take 30-60 seconds.
## Mining
To mine:
```sh
lotus-storage-miner run
```
Get information about your miner:
```sh
lotus-storage-miner info
# example: miner id `t0111`
```
**Seal** random data to start producing **PoSts**:
```sh
$ lotus-storage-miner store-garbage
lotus-storage-miner store-garbage
```
You can check **miner power** and **sector** usage with the miner id:
Get **miner power** and **sector usage**:
```sh
# Total power of the network
$ lotus-storage-miner state power
lotus-storage-miner state power
# returns total power
$ lotus-storage-miner state power <miner>
lotus-storage-miner state power <miner>
$ lotus-storage-miner state sectors <miner>
lotus-storage-miner state sectors <miner>
```
## Assign a nickname for your node
## Change nickname
Update `~/.lotus/config.toml` with:
In the `.lotus` folder, modify `config.toml` with:
```sh
[Metrics]
Nickname="snoopy"
```
## Troubleshooting
```sh
lotus-storage-miner info
# WARN main lotus-storage-miner/main.go:73 failed to get api endpoint: (/Users/myrmidon/.lotusstorage) %!w(*errors.errorString=&{API not running (no endpoint)}):
```
If you see this, that means your **Lotus Storage Miner** isn't ready yet.

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

@ -1,17 +1,23 @@
# Retrieving Data
If you have stored data with a **Lotus Storage Miner** in the network, you can search for it by **Data CID**
> 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 a **Data CID** with the **Lotus Storage Miner** in the network.
If you would like to learn how to store a **Data CID** on a miner, read the instructions [here](https://docs.lotu.sh/en+storing-data).
## Find by Data CID
```sh
$ lotus client find <Data CID>
LOCAL
RETRIEVAL <miner>@<miner peerId>-<deal funds>-<size>
lotus client find <Data CID>
# LOCAL
# RETRIEVAL <miner>@<miner peerId>-<deal funds>-<size>
```
Retrieve data from a **Lotus Storage Miner**.
## Retrieve by Data CID
```sh
$ lotus client retrieve <Data CID> <outfile>
lotus client retrieve <Data CID> <outfile>
```
This will initiate a **retrieval deal** and write the data to the outfile. This process may take 2 to 10 minutes.
This command will initiate a **retrieval deal** and write the data to your computer. This process may take 2 to 10 minutes.

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

@ -1,31 +1,29 @@
# Static port
# Static Ports
For a **storage deal**, you may want to set a static port and open it in your firewall to ensure clients can connect to you.
Lotus binds to a random **swarm port** by default.
For a **storage deal**, you can set a static port.
## Setup
To change the random **swarm port**, you may edit the `config.toml` file located under `$LOTUS_PATH`. The default location of this file is `$HOME/.lotus`.
Here is an example of changing the port to `1347`.
To change the port to `1347`:
```sh
[Libp2p]
ListenAddresses = ["/ip4/0.0.0.0/tcp/1347", "/ip6/::/tcp/1347"]
```
Once you update `config.toml`, restart your **daemon**.
After changing the port value, restart your **daemon**.
## Ubuntu's Uncomplicated Firewall
Open firewall manually
Open firewall manually:
```sh
# ufw allow 1347/tcp
ufw allow 1347/tcp
```
Or open and modify the profile located at `/etc/ufw/applications.d/lotus-daemon`
Or open and modify the profile located at `/etc/ufw/applications.d/lotus-daemon`:
```sh
[Lotus Daemon]
@ -34,9 +32,9 @@ description=Lotus Daemon firewall rules
ports=1347/tcp
```
Then run the following commands
Then run these commands:
```sh
$ ufw update lotus-daemon
$ ufw allow lotus-daemon
ufw update lotus-daemon
ufw allow lotus-daemon
```

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

@ -1,20 +1,68 @@
# Storing Data
Start by creating a file, in this example we will use the command line to create `hello.txt`.
> 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 DevNet**.
## Adding a file
```sh
$ echo "Hi my name is $USER" > hello.txt
lotus client import ./your-example-file.txt
```
Afterwards you can import the file into a **Lotus Node** and get a **Data CID** as output.
Upon success, this command will return a **Data CID**.
## List local files
The command to see a list of files by `CID`, `name`, `size` in bytes, and `status`:
```sh
$ lotus client import ./hello.txt
<Data CID>
lotus client local
```
To see a list of files by `CID`, `name`, `size`, `status`.
An example of the output:
```sh
$ lotus client local
bafkreierupr5ioxn4obwly4i2a5cd2rwxqi6kwmcyyylifxjsmos7hrgpe Development/sample-1.txt 2332 ok
bafkreieuk7h4zs5alzpdyhlph4lxkefowvwdho3a3pml6j7dam5mipzaii Development/sample-2.txt 30618 ok
```
## Make a Miner Deal on DevNet
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>
# price is in attoFIL/byte/block
# duration is number of blocks.
```
Upon success, this command will return a **Deal CID**.
From now on the **Data CID** is [retrievable](https://docs.lotu.sh/en+retrieving-data) from the **Lotus Storage Miner**.
## Troubleshooting
```sh
WARN main lotus/main.go:72 routing: not found
```
* This miner is offline.
```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.