[![Crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]

See the [repo root] for build status, license, rust version, etc.

# Light-Node

The [Tendermint] light-node wraps the [light-client] crate into a command-line interface tool. 
It can be used as a standalone light client daemon and exposes a JSON-RPC endpoint 
from which you can query the current state of the light node. 

## Getting Started

### Prerequisites

This short tutorial assumes that you are familiar with how to run a Tendermint fullnode on your machine. To learn how to do this, you can consult the [quick start] section of the tendermint documentation.

This tutorial further assumes you have `git` and the latest stable rust tool-chain installed (see https://rustup.rs/).
Additionally, the `jq` tool will make your life easier when dealing with JSON output.

#### Cloning the repository

To run the light node from source you have to clone this repository first:
```
$ git clone https://github.com/informalsystems/tendermint-rs.git
```

Then navigate to the light node crate:
```
$ cd tendermint-rs/light-node
```

### Configuration

You can configure all aspects of light node via a configuration file. 
An example configuration can be found under [light_node.toml.example](light_node.toml.example). 

If you are running a Tendermint fullnode on your machine, you can simply copy and use it to get started:
```
$ cp light_node.toml.example light_node.toml
``` 
Please, take a look into the config file and edit it according to your needs.
The provided example configuration file comes with a lot of explanatory comments
which hopefully provide enough guidance to configure your light node.

### Subjective initialization
Assuming that you are running a Tendermint fullnode that exposes an RPC endpoint on your loopback interface, you can intialize the light-node subjectively following th following steps:

First, you have to obtain a header hash and height you want to trust (subjectively). For our purposes you can obtain one via querying the Tendermint fullnode you are running. 
Here we are obtaining the header hash of height 2: 
```
$ curl -X GET "http://localhost:26657/block?height=2" -H  "accept: application/json" | jq .result.block_id.hash                                              1515:15:26
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2155    0  2155    0     0   161k      0 --:--:-- --:--:-- --:--:--  161k
"76F85BEF1133114482FC8F78C5E78D2B1C1875DD8422A0394B175DD694A7FBA1"
```

You can now use this header hash to subjectively initialize your light node via:
```
$ cargo run --  initialize  2 76F85BEF1133114482FC8F78C5E78D2B1C1875DD8422A0394B175DD694A7FBA1
```

Note that calling `cargo run` for the first time might take a while as this command will also compile the light node and all its dependencies.

### Running the light node daemon

Now you can start your light node by simply running:
```
$ cargo run --  start                             
```

If everything worked the output will look sth like:
```
 cargo run --  start                           17:56:31
    Finished dev [unoptimized + debuginfo] target(s) in 0.42s
     Running `/redacted/tendermint-rs/target/debug/light_node start`
[info] synced to block 20041
[info] synced to block 20042
[info] synced to block 20044
[info] synced to block 20046
[info] synced to block 20048
[info] synced to block 20049
[info] synced to block 20051
[info] synced to block 20053
[info] synced to block 20054
[...]
```

You can stop the light node by pressing Ctrl+c.

### Help

You will notice that some config parameters can be overwritten via command line arguments. 

To get a full overview and commandline parameters and available sub-commands, run:

```
$ cargo run --  help
```
Or on a specific sub-command, e.g.:
 ```shell script
$ cargo run --  help start
 ```

### JSON-RPC Endpoint(s)

When you have a light-node running you can query its current state via:
```
$ curl localhost:8888 -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "state", "id": 1}' | jq
```

Or you can query a shorter summary via the `/status` endpoint:
```
$  curl localhost:8888 -X POST -H 'Content-Type: application/json'\                                                                        15:58:52
                                                             -d '{"jsonrpc": "2.0", "method": "status", "id": 1}' | jq

```

<details>
  <summary><b>Click here</b> to see an example for expected output for the status endpoint:</summary>

```
$ curl localhost:8888 -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "status", "id": 1}' | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   364  100   317  100    47   1843    273 --:--:-- --:--:-- --:--:--  2104
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "block_hash": "ED745723430944215F65ED78AD7DF9ED0AA8A2A3B465BF421E0BAF66AA55AA08",
    "connected_nodes": [
      "BADFADAD0BEFEEDC0C0ADEADBEEFC0FFEEFACADE",
      "CEFEEDBADFADAD0C0CEEFACADE0ADEADBEEFC0FF"
    ],
    "height": 3850,
    "valset_hash": "74F2AC2B6622504D08DD2509E28CE731985CFE4D133C9DB0CB85763EDCA95AA3"
  },
  "id": 1
}
```
</details>

<details>
  <summary><b>Click here</b> to see an example for expected output for the state endpoint:</summary>

Command:  
  ```
$ curl localhost:8888 -X POST -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "state", "id": 1}' | jq 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1902  100  1856  100    46   164k   4181 --:--:-- --:--:-- --:--:--  168k
```
Example output:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "next_validator_set": {
      "validators": [
        {
          "address": "AD358F20C8CE80889E0F0248FDDC454595D632AE",
          "proposer_priority": "0",
          "pub_key": {
            "type": "tendermint/PubKeyEd25519",
            "value": "uo9rbgR5J0kuED0C529bTa6mcHZ4uXDjJRdg1k8proY="
          },
          "voting_power": "10"
        }
      ]
    },
    "provider": "BADFADAD0BEFEEDC0C0ADEADBEEFC0FFEEFACADE",
    "signed_header": {
      "commit": {
        "block_id": {
          "hash": "76F85BEF1133114482FC8F78C5E78D2B1C1875DD8422A0394B175DD694A7FBA1",
          "parts": {
            "hash": "568F279E3F59FBE3CABEACE7A3C028C15CA6A902F9D77DDEBA3BFCB9514E2881",
            "total": "1"
          }
        },
        "height": "2",
        "round": "0",
        "signatures": [
          {
            "block_id_flag": 2,
            "signature": "sN3e6bzKLeIFNRptQ4SytBDLZJA53e92D6FWTll5Lq8Wdg4fVzxya6qx3SHFU82ukuj8jKmBMkwTTJsb8xThCQ==",
            "timestamp": "2020-07-10T12:39:06.977628900Z",
            "validator_address": "AD358F20C8CE80889E0F0248FDDC454595D632AE"
          }
        ]
      },
      "header": {
        "app_hash": "0000000000000000",
        "chain_id": "dockerchain",
        "consensus_hash": "048091BC7DDC283F77BFBF91D73C44DA58C3DF8A9CBC867405D8B7F3DAADA22F",
        "data_hash": null,
        "evidence_hash": null,
        "height": "2",
        "last_block_id": {
          "hash": "F008EACA817CF6A3918CF7A6FD44F1F2464BB24D25A7EDB45A03E8783E9AB438",
          "parts": {
            "hash": "BF5130E879A02AC4BB83E392732ED4A37BE2F01304A615467EE7960858774E57",
            "total": "1"
          }
        },
        "last_commit_hash": "474496740A2EAA967EED02B239DA302BAF696AE36AEA78F7FEFCE4A77CCA5B33",
        "last_results_hash": null,
        "next_validators_hash": "74F2AC2B6622504D08DD2509E28CE731985CFE4D133C9DB0CB85763EDCA95AA3",
        "proposer_address": "AD358F20C8CE80889E0F0248FDDC454595D632AE",
        "time": "2020-07-10T12:39:05.977628900Z",
        "validators_hash": "74F2AC2B6622504D08DD2509E28CE731985CFE4D133C9DB0CB85763EDCA95AA3",
        "version": {
          "app": "1",
          "block": "10"
        }
      }
    },
    "validator_set": {
      "validators": [
        {
          "address": "AD358F20C8CE80889E0F0248FDDC454595D632AE",
          "proposer_priority": "0",
          "pub_key": {
            "type": "tendermint/PubKeyEd25519",
            "value": "uo9rbgR5J0kuED0C529bTa6mcHZ4uXDjJRdg1k8proY="
          },
          "voting_power": "10"
        }
      ]
    }
  },
  "id": 1
}

```

</details>

[//]: # (badges)

[crate-image]: https://img.shields.io/crates/v/tendermint-light-node.svg
[crate-link]: https://crates.io/crates/tendermint-light-node
[docs-image]: https://docs.rs/tendermint-light-node/badge.svg
[docs-link]: https://docs.rs/tendermint-light-node/

[//]: # (general links)


[repo root]: https://github.com/informalsystems/tendermint-rs
[quick start]: https://github.com/tendermint/tendermint/blob/master/docs/introduction/quick-start.md
[Tendermint]: https://github.com/tendermint/tendermint
[light-client]: https://github.com/informalsystems/tendermint-rs/tree/master/light-client
