diff --git a/documentation/en/api-troubleshooting.md b/documentation/en/api-troubleshooting.md new file mode 100644 index 000000000..9282764a3 --- /dev/null +++ b/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' +``` diff --git a/documentation/en/api.md b/documentation/en/api.md index 20f271154..bb6791206 100644 --- a/documentation/en/api.md +++ b/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 -- `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 ` 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` diff --git a/documentation/en/dev-tools-pond-ui.md b/documentation/en/dev-tools-pond-ui.md index 17d1143e2..1e68b929f 100644 --- a/documentation/en/dev-tools-pond-ui.md +++ b/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 diff --git a/documentation/en/getting-started.md b/documentation/en/getting-started.md index 6fed92cb9..f1715f3f2 100644 --- a/documentation/en/getting-started.md +++ b/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** diff --git a/documentation/en/install-lotus-arch.md b/documentation/en/install-lotus-arch.md index 89345b7b6..2029de6d7 100644 --- a/documentation/en/install-lotus-arch.md +++ b/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). diff --git a/documentation/en/install-lotus-macos.md b/documentation/en/install-lotus-macos.md index fe6f7475b..2fac73022 100644 --- a/documentation/en/install-lotus-macos.md +++ b/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). - -## 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: : blockstore: block not found - -``` - -* Someone is requesting a **Data CID** from you that you don't have. \ No newline at end of file +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). \ No newline at end of file diff --git a/documentation/en/install-lotus-ubuntu.md b/documentation/en/install-lotus-ubuntu.md index 3176736a9..55a6be094 100644 --- a/documentation/en/install-lotus-ubuntu.md +++ b/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). diff --git a/documentation/en/join-devnet.md b/documentation/en/join-devnet.md index 1127ff460..ac8c8dd1c 100644 --- a/documentation/en/join-devnet.md +++ b/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 - -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 ``` 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). diff --git a/documentation/en/mining-troubleshooting.md b/documentation/en/mining-troubleshooting.md new file mode 100644 index 000000000..3ca04ec56 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/documentation/en/mining.md b/documentation/en/mining.md index b087bf401..e9b338c64 100644 --- a/documentation/en/mining.md +++ b/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 -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: ``` ## 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. \ No newline at end of file diff --git a/documentation/en/retrieving-data.md b/documentation/en/retrieving-data.md index 345b4ed70..7f86873e7 100644 --- a/documentation/en/retrieving-data.md +++ b/documentation/en/retrieving-data.md @@ -16,8 +16,12 @@ lotus client find ## Retrieve by Data CID +All fields are required. + ```sh lotus client retrieve ``` +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. diff --git a/documentation/en/setting-a-static-port.md b/documentation/en/setting-a-static-port.md index 2c820d2c9..63dd0d188 100644 --- a/documentation/en/setting-a-static-port.md +++ b/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`: diff --git a/documentation/en/setup-troubleshooting.md b/documentation/en/setup-troubleshooting.md new file mode 100644 index 000000000..63d7234f9 --- /dev/null +++ b/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: : blockstore: block not found + +``` + +* Someone is requesting a **Data CID** from you that you don't have. \ No newline at end of file diff --git a/documentation/en/storing-data-troubleshooting.md b/documentation/en/storing-data-troubleshooting.md new file mode 100644 index 000000000..d39e73cf7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/documentation/en/storing-data.md b/documentation/en/storing-data.md index 219a4aed6..723088cd7 100644 --- a/documentation/en/storing-data.md +++ b/documentation/en/storing-data.md @@ -45,24 +45,11 @@ Store a **Data CID** with a miner: ```sh lotus client deal -# 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. \ No newline at end of file +From now on the **Data CID** is [retrievable](https://docs.lotu.sh/en+retrieving-data) from the **Lotus Storage Miner**. \ No newline at end of file diff --git a/documentation/en/updating-lotus.md b/documentation/en/updating-lotus.md new file mode 100644 index 000000000..bfb9ec065 --- /dev/null +++ b/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. \ No newline at end of file