From 4591ccb777c5f679a3e36c701efa2441a67e0a3d Mon Sep 17 00:00:00 2001 From: "@wwwjim" Date: Sun, 1 Dec 2019 16:08:53 -0800 Subject: [PATCH 1/4] documentation: light copy adjustments before major revision --- documentation/api.md | 6 +++--- documentation/getting-started.md | 16 ++++++++++++---- documentation/glossary.md | 18 +++++++++--------- documentation/hardware.md | 6 ++++-- documentation/install-lotus-arch.md | 6 +++--- documentation/install-lotus-macos.md | 6 +++--- documentation/install-lotus-ubuntu.md | 6 +++--- ...{setup-devnet-cli.md => join-devnet-cli.md} | 7 +++---- ...{setup-devnet-gui.md => join-devnet-gui.md} | 13 ++++++------- documentation/mining.md | 12 +++++++----- documentation/retrieving-data.md | 2 +- documentation/tracing.md | 3 +-- 12 files changed, 55 insertions(+), 46 deletions(-) rename documentation/{setup-devnet-cli.md => join-devnet-cli.md} (94%) rename documentation/{setup-devnet-gui.md => join-devnet-gui.md} (68%) diff --git a/documentation/api.md b/documentation/api.md index 144a2a1aa..52248ba94 100644 --- a/documentation/api.md +++ b/documentation/api.md @@ -1,6 +1,6 @@ # API -The systems API is defined in here. The RPC maps directly to the API defined here using the JSON RPC package in `lib/jsonrpc`. +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). ## Overview @@ -10,8 +10,8 @@ By default `127.0.0.1:1234` - daemon stores the api endpoint multiaddr in `~/.lo - `ws://[api:port]/rpc/v0` - JsonRPC 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`. Required permissions are -defined in `api/struct.go` +For JsonRPC 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 diff --git a/documentation/getting-started.md b/documentation/getting-started.md index d851c8490..ffac9b936 100644 --- a/documentation/getting-started.md +++ b/documentation/getting-started.md @@ -1,9 +1,17 @@ -# Project Lotus - 莲 +# 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). -## Background +## What can I learn here? -Lotus is architected modularly, and aims to keep clean API boundaries between everything, even if they are in the same process. Notably, the 'lotus full node' software, and the 'lotus storage miner' software are two separate programs. +- 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 setup a DevNet with either the [command line interface](https://docs.lotu.sh/join-devnet-cli) or a [graphical user interface](https://docs.lotu.sh/join-devnet-gui). +- Learn how to mine Filecoin using the `lotus-storage-miner` in the [CLI](https://docs.lotu.sh/mining) -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. This way, a mining operation may easily run one or many storage miners, connected to one or many full node instances. +## 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. + +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. + +This way, a mining operation may easily run one or many storage miners, connected to one or many full node instances. diff --git a/documentation/glossary.md b/documentation/glossary.md index 33300b8fb..3b3466424 100644 --- a/documentation/glossary.md +++ b/documentation/glossary.md @@ -1,33 +1,33 @@ # Glossary -## Chain/Types +**Chain: Types** Implementation of data structures used by Filecoin and their serializations. -## Chain/Store +**Chain: Store** The chainstore manages all local chain state, including block headers, messages, and state. -## Chain/State +**Chain: State** A package for dealing with the Filecoin state tree. Wraps the [HAMT](https://github.com/ipfs/go-hamt-ipld). -## Chain/Actors +**Chain: Actors** Implementations of the builtin Filecoin network actors. -## Chain/Vm +**Chain: VM** The Filecoin state machine 'vm'. Implemented here are utilities to invoke Filecoin actor methods. -## Miner +**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 +**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** -Pond 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. +[Pond](https://docs.lotu.sh/join-devnet-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. diff --git a/documentation/hardware.md b/documentation/hardware.md index 98523207f..bd6947cf1 100644 --- a/documentation/hardware.md +++ b/documentation/hardware.md @@ -1,3 +1,5 @@ -# Picking Hardware +# Hardware Requirements -Coming soon +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. + +Windows is not yet supported. diff --git a/documentation/install-lotus-arch.md b/documentation/install-lotus-arch.md index e1ca8d4e0..dbad51119 100644 --- a/documentation/install-lotus-arch.md +++ b/documentation/install-lotus-arch.md @@ -1,6 +1,6 @@ # Installing Lotus on Arch Linux -Install these dependencies: +Install these dependencies for Arch Linux. - go (1.13 or higher) - gcc (7.4.0 or higher) @@ -27,14 +27,14 @@ Arch (build): sudo pacman -Syu go gcc git bzr jq pkg-config opencl-icd-loader opencl-headers ``` -## Clone +Clone ```sh $ git clone https://github.com/filecoin-project/lotus.git $ cd lotus/ ``` -## Install +Install ```sh $ make clean all diff --git a/documentation/install-lotus-macos.md b/documentation/install-lotus-macos.md index 8c0bc3dec..28ff425ec 100644 --- a/documentation/install-lotus-macos.md +++ b/documentation/install-lotus-macos.md @@ -1,6 +1,6 @@ # Installing Lotus on MacOS -Install these dependencies: +Install these dependencies for MacOS Catalina. - go (1.13 or higher) - gcc (7.4.0 or higher) @@ -15,14 +15,14 @@ Install these dependencies: - llvm (proofs build) - clang (proofs build) -## Clone +Clone ```sh $ git clone https://github.com/filecoin-project/lotus.git $ cd lotus/ ``` -## Make & Install +Install ```sh $ make clean all diff --git a/documentation/install-lotus-ubuntu.md b/documentation/install-lotus-ubuntu.md index 332a232e5..f5331984f 100644 --- a/documentation/install-lotus-ubuntu.md +++ b/documentation/install-lotus-ubuntu.md @@ -1,6 +1,6 @@ # Installing Lotus on Ubuntu -Install these dependencies: +Install these dependencies for Ubuntu. - go (1.13 or higher) - gcc (7.4.0 or higher) @@ -30,14 +30,14 @@ sudo apt update sudo apt install golang-go gcc git bzr jq pkg-config mesa-opencl-icd ocl-icd-opencl-dev ``` -## Clone +Clone ```sh $ git clone https://github.com/filecoin-project/lotus.git $ cd lotus/ ``` -## Install +Install ```sh $ make clean all diff --git a/documentation/setup-devnet-cli.md b/documentation/join-devnet-cli.md similarity index 94% rename from documentation/setup-devnet-cli.md rename to documentation/join-devnet-cli.md index 090a3904c..78dc0abea 100644 --- a/documentation/setup-devnet-cli.md +++ b/documentation/join-devnet-cli.md @@ -1,6 +1,6 @@ -# Setup Lotus Devnet using the CLI +# Join Lotus Devnet -## Node setup +## Node CLI setup If you have run lotus before and want to remove all previous data: `rm -rf ~/.lotus ~/.lotusstorage` @@ -54,7 +54,6 @@ If you see an error like `actor not found` after executing this command, it mean It is possible for a Client to make a deal with a Miner on the same lotus Node. ```sh - # List all miners in the system. Choose one to make a deal with. $ lotus state list-miners @@ -72,4 +71,4 @@ For example `\$ lotus client deal bafkre...qvtjsi t0111 36000 12` proposes a dea ## 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 at https://lotus-metrics.kittyhawk.wtf. +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). diff --git a/documentation/setup-devnet-gui.md b/documentation/join-devnet-gui.md similarity index 68% rename from documentation/setup-devnet-gui.md rename to documentation/join-devnet-gui.md index a5ff9c95f..e5c53b4eb 100644 --- a/documentation/setup-devnet-gui.md +++ b/documentation/join-devnet-gui.md @@ -1,26 +1,25 @@ -# Setup Lotus Devnet using a GUI +# Join Lotus Devnet -As an alternative to the CLI you can use Pond, 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. +As an alternative to the [CLI](https://docs.lotu.sh/join-devnet-cli) you can use Pond, 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. -Build: +## Build ```sh $ make pond ``` -Run: +## Run ```sh $ ./pond run -Listening on http://127.0.0.1:2222 ``` Now go to http://127.0.0.1:2222. -## Thing to try +## What can I do? - The `Spawn Node` button starts a new lotus Node in a new draggable window. -- Click `[Spawn Storage Miner]` to start mining (make sure the Node's wallet has funds). +- 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. diff --git a/documentation/mining.md b/documentation/mining.md index 1046eb8cf..2a585b211 100644 --- a/documentation/mining.md +++ b/documentation/mining.md @@ -1,4 +1,4 @@ -# Mining +# Getting started Ensure that at least one BLS address (`t3..`) in your wallet exists @@ -7,13 +7,15 @@ $ lotus wallet list t3... ``` -With this address, go to 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 - It should be saying: `New storage miners address is: t0..` +appear. -Initialize storage miner: +The screen should show: `New storage miners address is: t0..` + +## Initialize ```sh $ lotus-storage-miner init --actor=t01.. --owner=t3.... @@ -21,7 +23,7 @@ $ lotus-storage-miner init --actor=t01.. --owner=t3.... This command should return successfully after miner is setup on-chain (30-60s) -Start mining: +## Start mining ```sh $ lotus-storage-miner run diff --git a/documentation/retrieving-data.md b/documentation/retrieving-data.md index dd350764e..478129069 100644 --- a/documentation/retrieving-data.md +++ b/documentation/retrieving-data.md @@ -11,7 +11,7 @@ RETRIEVAL @-- Retrieve data from a miner ```sh -\$ lotus client retrieve +$ lotus client retrieve ``` This will initiate a retrieval deal and write the data to the outfile. This process may take some time. diff --git a/documentation/tracing.md b/documentation/tracing.md index 3807ca69b..05a57f3b3 100644 --- a/documentation/tracing.md +++ b/documentation/tracing.md @@ -14,8 +14,7 @@ fairly easy to swap in. ## Running Locally To easily run and view tracing locally, first, install jaeger. The easiest way -to do this is to download the binaries from -https://www.jaegertracing.io/download/ and then run the `jaeger-all-in-one` +to do this is to [download the binaries](https://www.jaegertracing.io/download/) and then run the `jaeger-all-in-one` binary. This will start up jaeger, listen for spans on `localhost:6831`, and expose a web UI for viewing traces on `http://localhost:16686/`. From 9eae667ef7b11b046350e7b14f95ac2cc257a005 Mon Sep 17 00:00:00 2001 From: "@wwwjim" Date: Sun, 1 Dec 2019 16:28:19 -0800 Subject: [PATCH 2/4] documentation: correctly represents pond's purpose which is to test in a separate local network --- documentation/{join-devnet-gui.md => testing-with-gui.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename documentation/{join-devnet-gui.md => testing-with-gui.md} (77%) diff --git a/documentation/join-devnet-gui.md b/documentation/testing-with-gui.md similarity index 77% rename from documentation/join-devnet-gui.md rename to documentation/testing-with-gui.md index e5c53b4eb..6bb9e1f7c 100644 --- a/documentation/join-devnet-gui.md +++ b/documentation/testing-with-gui.md @@ -1,6 +1,6 @@ -# Join Lotus Devnet +# Pond UI -As an alternative to the [CLI](https://docs.lotu.sh/join-devnet-cli) you can use Pond, 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. +Pond is a graphical testbed for [Lotus](https://docs.lotu.sh). Using it will setup a seperate local network which is helpful for debugging. Pond will spin up nodes, connect them in a given topology, start them mining, and observe how they function over time. ## Build @@ -16,7 +16,7 @@ $ ./pond run Now go to http://127.0.0.1:2222. -## What can I do? +## What can I test? - The `Spawn Node` button starts a new lotus Node in a new draggable window. - Click `[Spawn Storage Miner]` to start mining. This require's the node's wallet to have funds. From 7f1ce9d7be8582a85a85c999e7173869307a38dd Mon Sep 17 00:00:00 2001 From: "@wwwjim" Date: Sun, 1 Dec 2019 16:36:29 -0800 Subject: [PATCH 3/4] documentation: updates glossary --- documentation/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/glossary.md b/documentation/glossary.md index 3b3466424..c579bfab4 100644 --- a/documentation/glossary.md +++ b/documentation/glossary.md @@ -30,4 +30,4 @@ The storage miner logic. This package also interfaces with the full node through **Pond** -[Pond](https://docs.lotu.sh/join-devnet-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. +[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. From bc50f9de7ad8bcd033a9da1d40b5b3f55de13076 Mon Sep 17 00:00:00 2001 From: "@wwwjim" Date: Sun, 1 Dec 2019 16:36:55 -0800 Subject: [PATCH 4/4] documentation: updates getting started --- documentation/getting-started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/getting-started.md b/documentation/getting-started.md index ffac9b936..c5b9667b6 100644 --- a/documentation/getting-started.md +++ b/documentation/getting-started.md @@ -5,7 +5,8 @@ Lotus is an experimental implementation of the **Filecoin Distributed Storage Ne ## 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 setup a DevNet with either the [command line interface](https://docs.lotu.sh/join-devnet-cli) or a [graphical user interface](https://docs.lotu.sh/join-devnet-gui). +- 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) ## What makes Lotus different?