documentation: latest updates from feedback across team

documentation/en/api-troubleshooting.md

@@ -0,0 +1,36 @@
+# API Troubleshooting
+
+## params
+
+`params` must be an array. If there are no `params` you should still pass an empty array.
+
+## 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'
+```
+
+## Sending a CID
+
+If you do not serialize the CID as a JSON IPLD link, 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'
+```

documentation/en/api.md

@@ -1,37 +1,81 @@
 # API
 
-> This document is a work in progress.
+Here is an early overview of how to make API calls.
 
-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).
+Implementation details for the **JSON-RPC** package are [here](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`
+API requests are made against `127.0.0.1:1234` unless you modify `~/.lotus/api`. 
 
-- `http://[api:port]/rpc/v0` - **JSON-RPC** HTTP endpoint
+Options:
-- `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
+- `http://[api:port]/rpc/v0` - HTTP endpoint
-defined in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go)
+- `ws://[api:port]/rpc/v0` -  Websocket endpoint
+- `PUT http://[api:port]/rest/v0/import` - File import, it requires write permissions.
 
-## Auth
+## What methods can I use?
 
-**JWT** in the `Authorization: Bearer <token>` http header
+Every `method` is available in [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go). 
 
-Permissions
+The necessary permissions for each are in [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go).
 
-- `read` - Read node state, no private data
+## How do I make an API request?
-- `write` - Write to local store / chain, read private data
+
-- `sign` - Use private keys stored in wallet for signing
+To demonstrate making an API request, we will take the method `ChainHead` from [api/api.go](https://github.com/filecoin-project/lotus/blob/master/api/api_full.go).
-- `admin` - Manage permissions
+
+```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 ~/.lotusstorage/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.
+
+## Authorization
+
+To authorize your request, you will need to include the **JWT** in a HTTP header, for example:
+
+```sh
+-H "Authorization: Bearer $(cat ~/.lotusstorage/token)"
+```
+
+Admin token is stored in `~/.lotus/token` for the **Lotus Node** or `~/.lotusstorage/token` for the **Lotus Storage Miner**.
+
+## Authorization types
+
+When viewing [api/struct.go](https://github.com/filecoin-project/lotus/blob/master/api/struct.go), you will encounter these types:
+
+- `read` - Read node state, no private data.
+- `write` - Write to local store / chain, read private data.
+- `sign` - Use private keys stored in wallet for signing.
+- `admin` - Manage permissions.
 
 Payload
 
 ```json
 {
-  "Allow": ["read", "write", ...]
+  "Allow": [
+    "read", 
+    "write",
+    /* other options */
+  ]
 }
 ```
-
-Admin token is stored in `~/.lotus/token`

documentation/en/dev-tools-pond-ui.md

@@ -1,6 +1,6 @@
 # Pond UI
 
-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.
+Pond is a graphical testbed for [Lotus](https://docs.lotu.sh). Using it will setup a separate 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
 

documentation/en/getting-started.md

@@ -1,6 +1,6 @@
 # Lotus
 
-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).
+Lotus is an 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).
 
@@ -13,7 +13,7 @@ For more details about Filecoin, check out the [Filecoin Spec](https://github.co
 
 ## What makes Lotus different?
 
-Lotus is architected modularly to keep clean API boundaries while using the same process. Installing Lotus will include two seperate programs:
+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 Storage Miner**

documentation/en/install-lotus-arch.md

@@ -41,4 +41,4 @@ 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).
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).

documentation/en/install-lotus-macos.md

@@ -1,10 +1,39 @@
 # MacOS Instructions
 
-We recommend for MacOS users to use [HomeBrew](https://brew.sh/) to install each package.
+## Get XCode Command Line Tools
 
-## HomeBrew installation
+To check if you already have the XCode Command Line Tools installed via the CLI, run:
 
-Run `terminal.app` and enter this command:
+```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)"
@@ -34,32 +63,4 @@ 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).
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can 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.

documentation/en/install-lotus-ubuntu.md

@@ -44,4 +44,4 @@ 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).
+After installing Lotus, you can run the `lotus` command directly from your CLI to see usage documentation. Next, you can join the [Lotus DevNet](https://docs.lotu.sh/en+join-devnet).

documentation/en/join-devnet.md

@@ -4,7 +4,7 @@
 
 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.
+If you have installed older versions, you may need to clear existing chain data and miners if you run into any errors. You can use this command:
 
 ```sh
 rm -rf ~/.lotus ~/.lotusstorage
@@ -24,23 +24,29 @@ In another terminal window, check your connection with peers:
 lotus net peers | wc -l
 ```
 
-Synchronize the **chain**:
+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://docs.lotu.sh/en+setup-troubleshooting).
+
+## Synchronize
+
+While the daemon is running, the next requirement is to sync the chain. Run the command below to start the chain sync progress. To see current chain height, visit the [network stats page](http://stats.testnet.filecoin.io/).
 
 ```sh
 lotus sync wait
 ```
 
-Congrats! Now you can perform **Lotus DevNet** operations.
+* This step will take anywhere between 30 minutes to a few hours.
+* You will be able to perform **Lotus DevNet** operations after it is finished.
 
-## Exploring the chain
+## Create your first address
-
-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...
+```
+
+Here is an example of the response
+
+```sh
+t3vhfme4qfvegqaz7m7q6o6afjcs67n6kpzv7t2eozio4chwpafwa2y4l7zhwd5eom7jmihzdg4s52dpvnclza
 ```
 
 - Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/funds.html)
@@ -49,14 +55,14 @@ t3...
 
 ## Check wallet address balance
 
-Wallet balances for the DevNet are in attoFIL. 1 attoFIL = 10^-18 FIL
+Wallet balances in the devnet are in **FIL**, the smallest denomination of FIL is an **attoFil**, where 1 attoFil = 10^-18 FIL.
 
 ```sh
-lotus wallet balance [optional address (t3...)]
+lotus wallet balance <YOUR_NEW_ADDRESS>
 ```
 
 You will not see any attoFIL in your wallet if your **chain** is not fully synced.
 
-## Monitoring Dashboard
+## Monitor the 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).
+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://lotus-metrics.kittyhawk.wtf).

documentation/en/mining-troubleshooting.md

@@ -0,0 +1,14 @@
+# Mining 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.
+
+```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.

documentation/en/mining.md

@@ -4,25 +4,32 @@ Here are instructions to learn how to perform storage mining. For hardware speci
 
 It is useful to [join the DevNet](https://docs.lotu.sh/en+join-devnet) prior to attempting storage mining for the first time.
 
+NOTE: While a miner is running, there will be many `WARN` and `ERROR` logs.
+
 ## Get started
 
-Please ensure that at least one **BLS address** (`t3..`) in your wallet exists with the following command:
+Please ensure that at least one **BLS address** in your wallet exists with the following command:
 
 ```sh
 lotus wallet list
 ```
 
-With this address, go to the [faucet](https://lotus-faucet.kittyhawk.wtf/miner.html), and
+With your wallet address:
-click `Create Miner`
 
-Await this response:
+- Visit the [faucet](https://lotus-faucet.kittyhawk.wtf/miner.html)
+- Click "Create Miner
+- DO NOT REFRESH THE PAGE. THIS OPERATION CAN TAKE SOME TIME.
+
+The task will be complete when you see:
 
 ```sh
-To initialize the storage miner run the following command
+New storage miners address is: <YOUR_NEW_MINING_ADDRESS>
 ```
 
 ## Initialize the storage miner
 
+In a CLI window, use the following command to start your miner:
+
 ```sh
 lotus-storage-miner init --actor=ACTOR_VALUE_RECEIVED --owner=OWNER_VALUE_RECEIVED
 ```
@@ -33,7 +40,7 @@ Example
 lotus-storage-miner init --actor=t01424 --owner=t3spmep2xxsl33o4gxk7yjxcobyohzgj3vejzerug25iinbznpzob6a6kexcbeix73th6vjtzfq7boakfdtd6a
 ```
 
-This command will take 30-60 seconds.
+You will have to wait some time for this operation to complete.
 
 ## Mining
 
@@ -74,14 +81,5 @@ Update `~/.lotus/config.toml` with:
 
 ```sh
 [Metrics]
-Nickname="snoopy"
+Nickname="fun"
 ```
-
-## 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.

documentation/en/retrieving-data.md

@@ -16,8 +16,12 @@ lotus client find <Data CID>
 
 ## 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.

documentation/en/setting-a-static-port.md

@@ -1,10 +1,10 @@
 # Static Ports
 
-For a **storage deal**, you can set a static port.
+For a **storage deal**, you can set a static port for the **Lotus Storage Miner**.
 
 ## 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`.
+To change the random **swarm port**, you may edit the `config.toml` file located under `$LOTUS_STORAGE_PATH`. The default location of this file is `$HOME/.lotusstorage`.
 
 To change the port to `1347`:
 

documentation/en/setup-troubleshooting.md

@@ -0,0 +1,35 @@
+# Setup Troubleshooting
+
+Here is a command that will delete your chain data and any miners you have set up:
+
+```sh
+rm -rf ~/.lotus ~/.lotusstorage
+```
+
+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.
+
+## Lotus daemon problems
+
+```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`.
+
+## Failed messages
+
+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.

documentation/en/storing-data-troubleshooting.md

@@ -0,0 +1,13 @@
+# Storage 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.

documentation/en/storing-data.md

@@ -45,24 +45,11 @@ 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.
 ```
 
+* Price is in attoFIL.
+* The `duration`, which represents how long the miner will keep your file hosted, is represented in blocks. Each block represents 30 seconds.
+
 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.

documentation/en/updating-lotus.md

@@ -0,0 +1,17 @@
+# Updating Lotus
+
+If you installed Lotus on your machine, you can upgrade to the latest version by doing the following:
+
+```sh
+git pull origin master
+```
+
+Sometimes when you run Lotus after a pull, certain commands such as `lotus daemon` may break. 
+
+Here is a command that will delete your chain data and any miners you have set up:
+
+```sh
+rm -rf ~/.lotus ~/.lotusstorage
+```
+
+This command usually resolves any issues with running `lotus` commands 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.