lightwalletd/README.md

# Overview

Hush Lightwalletd is a fork of [lightwalletd](https://github.com/adityapk00/lightwalletd) original from Zcash (ZEC).

It is a backend service that provides a bandwidth-efficient interface to the Hush blockchain for [SilentDragonLite cli](https://git.hush.is/hush/silentdragonlite-light-cli) and [SilentDragonLite](https://git.hush.is/hush/SilentDragonLite).

## Changes from upstream lightwalletd
This version of lightwalletd extends lightwalletd and:

* Adds support for HUSH
* Adds support for transparent addresses
* Adds several new RPC calls for lightclients
* Lots of perf improvements
  * Replaces SQLite with in-memory cache for Compact Blocks
  * Replace local Txstore, delegating Tx lookups to hushd
  * Remove the need for a separate ingestor

## Running your own SDL lightwalletd

#### 0. First, install Go
You will need Go >= 1.17 which you can download from the official [download page](https://golang.org/dl/) or install via your OS package manager.
Most OS package managers will not have such a new version, but you might get lucky.

This [installation](https://golang.org/doc/install) document shows how to do it on various OS's.

If you're using Ubuntu or Debian, try:

```
$ sudo apt install golang
```

#### 1. Run a Hush node.
Either compile or build the [Hush Daemon (hushd)](https://git.hush.is/hush/hush3).

Next, change your HUSH3.conf file to something like the following:

```
rpcuser=user-CHANGETHIS
rpcpassword=pass-CHANGETHIS
rpcport=18031 # this if for HUSH, change it for other HSC's
server=1
txindex=1
addressindex=1 # required for the newest lightwalletd code
rpcworkqueue=256
rpcallowip=127.0.0.1
rpcbind=127.0.0.1
```

Then start `hushd` in your command window. You might need to run with `-reindex` the first time if you are enabling `-addressindex` option for the first time. The reindex might take a while. A fresh sync is usually the fastest way to enable `-addressindex`, instead of doing a reindex.

#### 2. Compile lightwalletd
Run the build script.

```
make
```

#### 3. Get a TLS certificate and run the Lightwalletd frontend
First, get a TLS certificate:

On Ubuntu Linux, **I SUGGEST YOU DO NOT USE SNAPD** and just ```sudo apt install certbot``` and then start on [Step 7 of these instructions by the EFF](https://certbot.eff.org/instructions)

Next you decide how you want to setup lightwalletd - with (Option A) or without NGINX (Option B).

##### Option A: "Let's Encrypt" certificate using NGINX as a reverse proxy
If you running a public-facing server, the easiest way to obtain a certificate is to use a NGINX reverse proxy and get a Let's Encrypt certificate.

Create a new section for the NGINX reverse proxy:
```
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    
    server_name your_host.net;

    ssl_certificate /etc/letsencrypt/live/your_host.net/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/your_host.net/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
        
    location / {
        # Replace 9067 with the port of your gRPC server if using a custom port
        # Hush Smart Chains should use a different port than 9067 so it doesn't conflict with HUSH lightwalletd
        # NOTE: it's only safe to use --no-tls on lightwalletd if this is on localhost
        grpc_pass grpc://localhost:9067;
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

Then run the lightwalletd frontend with the following:

```
./start.sh
```

If you see the following error `"Can't create data directory: /var/lib/lightwalletd"` you need to set the correct user permissions:

```
sudo chown -R $USER:$USER /var/lib/lightwalletd
sudo chmod -R 755 /var/lib/lightwalletd
```

Note: we use the "--no-tls" option as we are using NGINX as a reverse proxy and letting it handle the TLS authentication for us instead. If you want to do TLS directly with lightwalletd with no reverse proxy, see the next section.

If you encounter an error about the lightwalletd "data directory", then set one on the command line with `--data-dir` (OR) create the `/var/lib/lightwalletd` and `/var/lib/lightwalletd/db` directories & chown that new db directory as the user account running lightwalletd and hushd.

##### Option B: "Let's Encrypt" certificate just using lightwalletd without NGINX
The other option is to configure lightwalletd to handle its own TLS authentication. Once you have a certificate that you want to use (from a certificate authority), pass the certificate to the frontend as follows:

```
./start-tls.sh -tls-cert /etc/letsencrypt/live/YOURWEBSITE/fullchain.pem -tls-key /etc/letsencrypt/live/YOURWEBSITE/privkey.pem
```

#### 4. Point the `silentdragonlite-cli` to this server
You should start seeing the frontend ingest and cache the Hush blocks after ~15 seconds. 

Now, connect to your server! (Substitute with your own below)
```
git clone https://git.hush.is/hush/silentdragonlite-cli
cd silentdragonlite-cli
cargo build --release
./target/release/silentdragonlite-cli --server https://lite.example.org
```

* If you have trouble compiling silentdragonlite-cli, then [please refer to it's separate documentation here](https://git.hush.is/hush/silentdragonlite-cli) on how to build it and what pre-requisites need to be installed.

You can also do testing with https://github.com/fullstorydev/grpcurl

## Running a server for Hush Smart Chains

This lightwalletd code can be used with any Hush Smart Chain. For example, here is how you would
run the lightwalletd for DragonX :

```
./lightwalletd --grpc-bind-addr localhost:9069 --http-bind-addr localhost:9070 --hush-conf-path ~/.hush/DRAGONX/DRAGONX.conf --no-tls --rpcport=21769
```

For this code, your Nginx config will need to use the same GRPC port, so something like `grpc_pass grpc://localhost:9069;`

The above code should be compatible with running a lightwalletd on the same server that runs one for Hush, which by default uses ports 9067 for grpc
and 9068 for http. If you are only running a single lightwalletd on a server, the following should work for DragonX :

```
./lightwalletd --grpc-bind-addr localhost:9069 --http-bind-addr localhost:9070 --hush-conf-path ~/.hush/DRAGONX/DRAGONX.conf --no-tls --rpcport=21769
```

To run lightwalletd for other HSC's, you must specific the correct RPC port via `--rpcport` , point to it's config file via `--hush-conf-path` and
use use unique ports that nothing else is using for `--grpc-bind-addr` and `--http-bind-addr` . Make sure your nginx config `grpc_pass` port matches
what you give to `--grpc-bin-addr` .


## Lightwalletd Command-line Options

These are some of the most used command line options for lightwalletd:

| CLI option       | Default        | What it does                  |
|------------------|:--------------:|:------------------------------|
| --grpc-bind-addr | 127.0.0.1:9067 | address and port to listen on via GRPC |
| --http-bind-addr | 127.0.0.1:9068 | address and port to listen on vi HTTP |
| --tls-cert       | blank          | the path to a TLS certificate |
| --tls-key        | blank          | the path to a TLS key file    |
| --no-tls         | false          | Disable TLS, serve un-encrypted traffic |
| --data-dir       | /var/lib/lightwalletd | Sets the lightwalletd data directory |
| --log-file       | blank          | log file to write to          |
| --log-level      | logrus.InfoLevel | log level 1 thru 7 (something from logrus) |
| --hush-conf-path | blank          | conf file to pull RPC creds from |
| --rpcport        | 18031          | RPC port                      |
| version          | n/a            | Display lightwalletd version  |

Run `./lightwalletd --help` or `./lightwalletd help` to see all options.

## Developing

To create a `foo.pb.go` file from a `foo.proto` file:

```
protoc --go_out=paths=source_relative:. foo.proto
```

Or do `make protobuf`

To update the version of lightwalletd, update the value of the `Version` variable in common/common.go .

## Support and Socials

* Telegram: [https://hush.is/tg](https://hush.is/tg)
* Matrix: [https://hush.is/matrix](https://hush.is/matrix)
* Twitter: [https://hush.is/twitter](https://hush.is/twitter)
* PeerTube [https://hush.is/peertube](https://hush.is/peertube)

## License
GPLv3 or later

# Copyright

2016-2024 The Hush Developers