Merge pull request #807 from filecoin-project/@jimmylee/documentation-latest

documentation: latest updates from feedback across team
This commit is contained in:
Jim 2019-12-09 13:56:39 +01:00 committed by GitHub
commit f2efe73247
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 258 additions and 103 deletions

View File

@ -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'
```

View File

@ -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
- `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.
Options:
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)
- `http://[api:port]/rpc/v0` - HTTP endpoint
- `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
- `write` - Write to local store / chain, read private data
- `sign` - Use private keys stored in wallet for signing
- `admin` - Manage permissions
## How do I make an API request?
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).
```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`

View File

@ -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

View File

@ -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**

View File

@ -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).

View File

@ -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).
## 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.
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).

View File

@ -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).

View File

@ -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 youre 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
View **chain block height** along with other network metrics at our [chain explorer](https://lotus-metrics.kittyhawk.wtf/chain).
## Create a new address
## Create your first 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).

View File

@ -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.

View File

@ -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
click `Create Miner`
With your wallet address:
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.

View File

@ -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.

View File

@ -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`:

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.