diff --git a/documentation/en/api.md b/documentation/en/api.md index 52248ba94..71b8fc1e8 100644 --- a/documentation/en/api.md +++ b/documentation/en/api.md @@ -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 ` http header +**JWT** in the `Authorization: Bearer ` http header Permissions diff --git a/documentation/en/getting-started.md b/documentation/en/getting-started.md index c5b9667b6..db8f2ebf7 100644 --- a/documentation/en/getting-started.md +++ b/documentation/en/getting-started.md @@ -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. diff --git a/documentation/en/hardware.md b/documentation/en/hardware.md index bd6947cf1..1648ede95 100644 --- a/documentation/en/hardware.md +++ b/documentation/en/hardware.md @@ -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. diff --git a/documentation/en/install-lotus-arch.md b/documentation/en/install-lotus-arch.md index dbad51119..c35888485 100644 --- a/documentation/en/install-lotus-arch.md +++ b/documentation/en/install-lotus-arch.md @@ -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 diff --git a/documentation/en/install-lotus-macos.md b/documentation/en/install-lotus-macos.md index 28ff425ec..5cb35e30c 100644 --- a/documentation/en/install-lotus-macos.md +++ b/documentation/en/install-lotus-macos.md @@ -1,4 +1,6 @@ -# Installing Lotus on MacOS +# MacOS Instructions + +> This document is a work in progress. Install these dependencies for MacOS Catalina. diff --git a/documentation/en/install-lotus-ubuntu.md b/documentation/en/install-lotus-ubuntu.md index f5331984f..4e617b9e7 100644 --- a/documentation/en/install-lotus-ubuntu.md +++ b/documentation/en/install-lotus-ubuntu.md @@ -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 diff --git a/documentation/en/join-devnet-cli.md b/documentation/en/join-devnet-cli.md index 78dc0abea..3773682f8 100644 --- a/documentation/en/join-devnet-cli.md +++ b/documentation/en/join-devnet-cli.md @@ -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 $ lotus client deal ``` -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). diff --git a/documentation/en/mining.md b/documentation/en/mining.md index 2a585b211..f2b095b5b 100644 --- a/documentation/en/mining.md +++ b/documentation/en/mining.md @@ -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 $ lotus-storage-miner state sectors ``` + +## Assign a nickname for your node + +In the `.lotus` folder, create a `config.toml` or modify an existing file with: + +``` +[Metrics] +Nickname="snoopy" +``` diff --git a/documentation/en/retrieving-data.md b/documentation/en/retrieving-data.md index 478129069..c7f9d18fd 100644 --- a/documentation/en/retrieving-data.md +++ b/documentation/en/retrieving-data.md @@ -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 @@ -8,10 +8,10 @@ LOCAL RETRIEVAL @-- ``` -Retrieve data from a miner +Retrieve data from a **Lotus Storage Miner**. ```sh $ lotus client retrieve ``` -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. diff --git a/documentation/en/setting-a-static-port.md b/documentation/en/setting-a-static-port.md new file mode 100644 index 000000000..06fefc4d5 --- /dev/null +++ b/documentation/en/setting-a-static-port.md @@ -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 +``` \ No newline at end of file diff --git a/documentation/en/storing-data.md b/documentation/en/storing-data.md index 7f67bbb9d..e46deb2a4 100644 --- a/documentation/en/storing-data.md +++ b/documentation/en/storing-data.md @@ -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 diff --git a/documentation/en/testing-with-gui.md b/documentation/en/testing-with-gui.md index 6bb9e1f7c..0bdf22df3 100644 --- a/documentation/en/testing-with-gui.md +++ b/documentation/en/testing-with-gui.md @@ -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 diff --git a/documentation/en/tracing.md b/documentation/en/tracing.md index 05a57f3b3..2faa4a109 100644 --- a/documentation/en/tracing.md +++ b/documentation/en/tracing.md @@ -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