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

documentation: small copy updates

Browse Source
This commit is contained in:
wwwjim 2019-12-04 07:39:41 -08:00
parent 6df625515a
commit 30779390a0
13 changed files with 123 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
documentation/en/api.md
View File

@ -1,21 +1,23 @@
# API
The systems API is defined in here. The RPC maps directly to the API defined here using the [JSON RPC package](https://github.com/filecoin-project/lotus/tree/master/lib/jsonrpc).
> 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).
## Overview
By default `127.0.0.1:1234` - daemon stores the api endpoint multiaddr in `~/.lotus/api`
By default `127.0.0.1:1234` - **daemon** stores the API endpoint multiaddr in `~/.lotus/api`
- `http://[api:port]/rpc/v0` - JsonRPC http endpoint
- `ws://[api:port]/rpc/v0` - JsonRPC 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 JsonRPC 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
JWT in the `Authorization: Bearer <token>` http header
**JWT** in the `Authorization: Bearer <token>` http header
Permissions

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

@ -1,18 +1,24 @@
# Lotus
Lotus is an experimental implementation of the **Filecoin Distributed Storage Network**. For more details about Filecoin, check out the [Filecoin Spec](https://github.com/filecoin-project/specs).
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.
For more details about Filecoin, check out the [Filecoin Spec](https://github.com/filecoin-project/specs).
## What can I learn here?
- If you want to [store](https://docs.lotu.sh/storing-data) or [retrieve](https://docs.lotu.sh/retrieving-data) data, you can 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) and get started.
- Learn how to join the DevNet with the [command line interface](https://docs.lotu.sh/join-devnet-cli).
- Learn how to test Lotus in a seperate local network using a [GUI](https://docs.lotu.sh/testing-with-gui).
- Learn how to mine Filecoin using the `lotus-storage-miner` in the [CLI](https://docs.lotu.sh/mining)
- 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).
- [Storing](https://docs.lotu.sh/storing-data) or [retrieving](https://docs.lotu.sh/retrieving-data) data.
- Joining the **Lotus DevNet** using your [CLI](https://docs.lotu.sh/join-devnet-cli).
- Test Lotus in a seperate local network using [Pond UI](https://docs.lotu.sh/testing-with-gui).
- Mining Filecoin using the **Lotus Storage Miner** in your [CLI](https://docs.lotu.sh/mining).
## What makes Lotus different?
Lotus is architected modularly to keep clean API boundaries while using the same process. The **Lotus Full Node** and the **Lotus Storage Miner** are two separate programs.
Lotus is architected modularly to keep clean API boundaries while using the same process. Installing Lotus will include two seperate programs:
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 full node via the websockets JSON RPC API for all of its chain interaction needs.
- The **Lotus Node**
- The **Lotus Storage Miner**
This way, a mining operation may easily run one or many storage miners, connected to one or many full node instances.
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.

2
documentation/en/hardware.md
View File

@ -1,4 +1,4 @@
# Hardware Requirements
# Hardware
Lotus can build and run on most [Linux](https://ubuntu.com/) and [MacOS](https://www.apple.com/macos) systems with at least 8GB of RAM.

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

@ -1,6 +1,6 @@
# Installing Lotus on Arch Linux
# Arch Linux Instructions
Install these dependencies for Arch Linux.
These steps will install the following dependencies:
- go (1.13 or higher)
- gcc (7.4.0 or higher)
@ -15,13 +15,13 @@ Install these dependencies for Arch Linux.
- llvm (proofs build)
- clang (proofs build)
Arch (run):
Run
```sh
sudo pacman -Syu opencl-icd-loader
```
Arch (build):
Build
```sh
sudo pacman -Syu go gcc git bzr jq pkg-config opencl-icd-loader opencl-headers

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

@ -1,4 +1,6 @@
# Installing Lotus on MacOS
# MacOS Instructions
> This document is a work in progress.
Install these dependencies for MacOS Catalina.

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

@ -1,6 +1,6 @@
# Installing Lotus on Ubuntu
# Ubuntu Instructions
Install these dependencies for Ubuntu.
These steps will install the following dependencies:
- go (1.13 or higher)
- gcc (7.4.0 or higher)
@ -15,14 +15,14 @@ Install these dependencies for Ubuntu.
- llvm (proofs build)
- clang (proofs build)
Ubuntu / Debian (run):
Run
```sh
sudo apt update
sudo apt install mesa-opencl-icd ocl-icd-opencl-dev
```
Ubuntu (build):
Build
```sh
sudo add-apt-repository ppa:longsleep/golang-backports

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

@ -1,12 +1,12 @@
# Join Lotus Devnet
# Join DevNet
## Node CLI setup
## Setup
If you have run lotus before and want to remove all previous data: `rm -rf ~/.lotus ~/.lotusstorage`
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/` directory. No configuration is needed.
The current Lotus build will automatically join the **Lotus DevNet** using the genesis and bootstrap files in the `build/` directory using a default configuration.
## Start Daemon
@ -21,13 +21,13 @@ $ lotus net peers | wc -l
2 # number of peers
```
Wait for the chain to finish syncing:
Wait for the **chain** to finish syncing:
```sh
$ lotus sync wait
```
You can view latest block height along with other network metrics at the https://lotus-metrics.kittyhawk.wtf/chain.
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
@ -38,8 +38,9 @@ $ lotus wallet new bls
t3...
```
Grab some funds from faucet - go to https://lotus-faucet.kittyhawk.wtf/, paste the address
you just created, and press Send.
- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/)
- Paste the address you created
- Press Send.
Check the wallet balance (balance is listed in attoFIL, where 1 attoFIL = 10^-18 FIL):
@ -47,11 +48,16 @@ Check the wallet balance (balance is listed in attoFIL, where 1 attoFIL = 10^-18
$ lotus wallet balance [optional address (t3...)]
```
If you see an error like `actor not found` after executing this command, it means that either your node isn't fully synced or there are no transactions to this address yet on chain. If the latter, using the faucet should 'fix' this.
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 Client to make a deal with a Miner on the same lotus Node.
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.
@ -67,8 +73,10 @@ $ lotus client query-ask <miner>
$ lotus client deal <Data CID> <miner> <price> <duration>
```
For example `\$ lotus client deal bafkre...qvtjsi t0111 36000 12` proposes a deal to store 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.
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 miners, and more, check out the [monitoring dashboard](https://lotus-metrics.kittyhawk.wtf).
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).

22
documentation/en/mining.md
View File

@ -1,17 +1,16 @@
# Getting started
Ensure that at least one BLS address (`t3..`) in your wallet exists
Ensure that at least one **BLS address** (`t3..`) in your wallet exists
```sh
$ lotus wallet list
t3...
```
With this address, go to [the faucet](https://lotus-faucet.kittyhawk.wtf/miner.html), and
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 storage miner to
appear.
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..`
@ -21,7 +20,7 @@ The screen should show: `New storage miners address is: t0..`
$ lotus-storage-miner init --actor=t01.. --owner=t3....
```
This command should return successfully after miner is setup on-chain (30-60s)
This command should return successfully after **Lotus Storage Miner** is setup on **chain**. It usually takes 30 to 60 seconds.
## Start mining
@ -37,13 +36,13 @@ $ lotus-storage-miner info
e.g. miner id `t0111`
Seal random data to start producing PoSts:
**Seal** random data to start producing **PoSts**:
```sh
$ lotus-storage-miner store-garbage
```
You can check miner power and sector usage with the miner id:
You can check **miner power** and **sector** usage with the miner id:
```sh
# Total power of the network
@ -53,3 +52,12 @@ $ lotus-storage-miner state power <miner>
$ lotus-storage-miner state sectors <miner>
```
## Assign a nickname for your node
In the `.lotus` folder, create a `config.toml` or modify an existing file with:
```
[Metrics]
Nickname="snoopy"
```

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

@ -1,6 +1,6 @@
# Retrieving Data
If you have stored data with a miner in the network, you can search for it by CID
If you have stored data with a **Lotus Storage Miner** in the network, you can search for it by **Data CID**
```sh
$ lotus client find <Data CID>
@ -8,10 +8,10 @@ LOCAL
RETRIEVAL <miner>@<miner peerId>-<deal funds>-<size>
```
Retrieve data from a miner
Retrieve data from a **Lotus Storage Miner**.
```sh
$ lotus client retrieve <Data CID> <outfile>
```
This will initiate a retrieval deal and write the data to the outfile. This process may take some time.
This will initiate a **retrieval deal** and write the data to the outfile. This process may take some time.

42
documentation/en/setting-a-static-port.md Normal file
View File

@ -0,0 +1,42 @@
# Static port
If you plan to accept a **storage deal**, you will 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.
## 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`.
```sh
[Libp2p]
ListenAddresses = ["/ip4/0.0.0.0/tcp/1347", "/ip6/::/tcp/1347"]
```
Once you update `config.toml`, restart your **daemon**.
## Open firewall on Ubuntu manually
```sh
# ufw allow 1347/tcp
```
## Open firewall using a UFW profile
Open and modify `/etc/ufw/applications.d/lotus-daemon` with:
```sh
[Lotus Daemon]
title=Lotus Daemon
description=Lotus Daemon firewall rules
ports=1347/tcp
```
Then run the following commands
```sh
$ ufw update lotus-daemon
$ ufw allow lotus-daemon
```

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

@ -1,12 +1,16 @@
# Storing Data
You can store files that have the minimum file size of 256 bytes.
## Tutorial
Start by creating a file, in this example we will use the command line to create `hello.txt`.
```sh
$ echo "Hi my name is $USER" > hello.txt
```
Afterwards you can import the file into lotus & get a **Data CID** as output.
Afterwards you can import the file into a **Lotus Node** and get a **Data CID** as output.
```sh
$ lotus client import ./hello.txt

2
documentation/en/testing-with-gui.md
View File

@ -22,7 +22,7 @@ Now go to http://127.0.0.1:2222.
- Click `[Spawn Storage Miner]` to start mining. This require's the node's wallet to have funds.
- Click on `[Client]` to open the Node's client interface and propose a deal with an existing Miner. If successful you'll see a payment channel open up with that Miner.
Don't leave Pond unattended for long periods of time (10h+), the web-ui tends to eventually consume all the available RAM.
Don't leave Pond unattended for more than 10 hours, the web client will eventually consume all available RAM.
## Troubleshooting

6
documentation/en/tracing.md
View File

@ -1,6 +1,6 @@
# 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.
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.
## Open Census
@ -8,7 +8,7 @@ Lotus uses [OpenCensus](https://opencensus.io/) for tracing application flow.
This generates spans
through the execution of annotated code paths.
Currently it is set up to use jaeger, though other tracing backends should be
Currently it is set up to use Jaeger, though other tracing backends should be
fairly easy to swap in.
## Running Locally
@ -18,7 +18,7 @@ to do this is to [download the binaries](https://www.jaegertracing.io/download/)
binary. This will start up jaeger, listen for spans on `localhost:6831`, and
expose a web UI for viewing traces on `http://localhost:16686/`.
Now, to start sending traces from lotus to jaeger, set the environment variable
Now, to start sending traces from Lotus to Jaeger, set the environment variable
`LOTUS_JAEGER` to `localhost:6831`, and start the `lotus daemon`.
Now, to view any generated traces, open up `http://localhost:16686/` in your