integration/README.md

# Hush Full Node Integration Docs

This document will help you install and maintain a Hush Full Node. It is mainly geared towards exchanges and mining pools, but
will be useful to any service provider adding Hush, such as a tipbot or exchange or mining pool. These instructions are also useful for DragonX and other Hush Arrakis Chains.

# Installing Hush from source

On Ubuntu/Linux systems, you can install Hush from [source](https://git.hush.is/hush/hush3) with these commands:

```
# install build depedencies
sudo apt-get install build-essential pkg-config libc6-dev m4 g++-multilib \
      autoconf libtool ncurses-dev unzip git python zlib1g-dev wget \
      bsdmainutils automake curl unzip nano libsodium-dev
git clone https://git.hush.is/hush/hush3.git
cd hush3
./build.sh -j4  #4 for use 4 cores
```

More details can be found [here](https://git.hush.is/hush/hush3/src/branch/master/INSTALL.md)

# Installing Hush from a binary

You can also install a binary from an [official release](https://git.hush.is/hush/hush3/releases)

# Terminology

We have a document that explains a lot of terminology [here](https://git.hush.is/hush/terminology)

# Hush RPC Docs

Every single Hush RPC is documented on the web at https://faq.hush.is/rpc/

For instance the docs for [z_listunspent](https://faq.hush.is/rpc/z_listunspent.html) RPC


# Config changes for exchanges and pools

The default location on Linux for the HUSH config file is `~/.hush/HUSH3/HUSH3.conf` . This file will have a username and password for RPC
access, so don't show the contents to untrusted people. The legacy location used to be `~/.komodo/HUSH3/HUSH3.conf` . You can move the old legacy directory to the new location and it will be found and used.

An advanced feature exchanges & pools can use is called `consolidation=1` which keeps wallets small and hence fast.
This feature will always make small transactions in the background, "consolidating" funds into very efficient amounts. This
makes future transactions fast by spending small amounts of time consolidating funds in the background. We note that turning on consolidation for an already very large wallet will have performance issues.

Here is an example config file for HUSH which is recommended for exchanges and mining pools:

```
rpcuser=someuser
rpcpassword=agoodpassword
rpcport=18031
server=1
txindex=1
rpcworkqueue=256
rpcallowip=127.0.0.1
rpcbind=127.0.0.1
# if you have servers with slow CPUs or very large existing wallets, comment out the next line
consolidation=1
```

# Tips for exchanges and mining pools
  * To shield coinbase funds use the [z_shieldcoinbase](https://faq.hush.is/rpc/z_shieldcoinbase.html) RPC
  * To get a list of all zaddrs in a wallet use the [z_listaddresses](https://faq.hush.is/rpc/z_listaddresses.html) RPC
  * It's possible that many users request a withdraw within a few seconds of each other which will spike CPU usage and potentially trigger bugs
    * Hush 3.9.1 should be less likely to have these bugs
    * It's a good idea to not let too many ztx's that spend funds from the same zaddr be queued at once.
      * So it's good to check the output of [z_getoperationstatus](https://faq.hush.is/rpc/z_getoperationstatus.html) before queuing a new ztx
      * If there are 3 or more existing ztx's in the state of "executing", do not add more
      * Wait until there are 2 or less ztx's in the "executing" state to add more to the queue
  * To detect users that are mining to your exchange:
    * Occasionally process the output of `z_listunspent`, such as once per hour via cron
    * If a certain zaddr has more than 30 zutxos (items in the array output of `z_listunspent`) it's likely they are mining to the exchange, or sending many small deposits
    * You can then manually inspect these user accounts or send them a message to not mine to the exchange
 * The [rescan](https://faq.hush.is/rpc/rescan.html) RPC in Hush 3.9.1 can be used to rescan from any block height, which minimizes downtime.
   * Example usage: `hush-cli rescan 123456`
     * The `rescan` RPC will use the existing note witness cache, which is described below.
   * Another important way to minimize downtime when restarting hushd is the use the `-keepnotewitnesscache` option to hushd, for instance:
     * `hushd -keepnotewitnesscache -rescanheight 123456` will greatly speed up rescanning by only updating the Sapling zaddr witness cache instead of calculating it from scratch   
  * It's best to only send payouts a few times per day (such as 2 or 3) instead of when they are above a threshold.
    * This will make pool wallets smaller and faster, miner wallets smaller and faster, and exchange wallets smaller and faster (because miners often mine directly to pools)
    * For exchanges, you can limit how many withdrawals a user can do per day, such as 3, and show them how many they have left. This will help keep wallets small and fast.
  * To see the balances of all zaddrs use [z_getbalances](https://faq.hush.is/rpc/z_getbalances.html)
    * Do not use [z_getbalance](https://faq.hush.is/rpc/z_getbalance.html) for each zaddr in the wallet, that will be drastically slower
 * HUSH has the unique feature of allowing a z2z transcation to spend from any zaddr with enough balance
   * This means you do not need to hardcode a zaddr in the "from" part of a z_sendmany and/or move funds around from various zaddrs
   * To use this feature, use a single lowercase "z" as the "from" in z_sendmany, such as: `z_sendmany "z" ...`
   * When using this, funds will be spent from any zaddr that has enough funds
   * Note that to use `z_sendmany` a single zaddr must have enough funds to make the transaction, funds from multiple zaddrs cannot be used. [z_mergetoaddress](https://faq.hush.is/rpc/z_mergetoaddress.html) can be used to spend funds from multiple zaddrs at one time.
   * Sometimes there are unconfirmed transactions waiting to be relayed to the network. The wallet will resend them periodically but this can be forced with the [resendwallettransactions](https://faq.hush.is/rpc/resendwallettransactions.html) RPC
  * To backup an entire wallet use the [z_exportwallet](https://faq.hush.is/rpc/z_exportwallet.html) RPC

# How Shielded Addresses (zaddrs) Are Different

  * Change from a zaddr goes back to itself! Not a different address, like in transparent addresses (taddrs).
  * Making zaddr transactions are slower, taking at least a few seconds and potentially hundreds of seconds for very large transactions, instead of a few milliseconds
  * Shielded transactions do not show the sender address, receiver address or amounts on the public explorer. You will need to use local RPC methods such as [z_viewtransaction](https://faq.hush.is/rpc/z_viewtransaction.html) or [getrawtransaction txid 1](https://faq.hush.is/rpc/getrawtransaction.html) to see those details
  * Shielded transactions are larger than transparent transactions, because more data is stored
    * Very roughly, the smallest shielded transactions are about 1KB, some can be very large up to the transaction size limit of 200KB
  * RPCs which work with zaddrs usually begin with `z_` such as `z_listunspent`. The very common `sendmany` RPC is called `z_sendmany` for zaddrs
  * To generate a new zaddr use [z_getnewaddress](https://faq.hush.is/rpc/z_getnewaddress.html)

  
# GUI wallets

Hush full node GUI wallet: [SilentDragon](https://git.hush.is/hush/SilentDragon/releases)

Hush lite wallet: [SilentDragonLite](https://git.hush.is/hush/SilentDragonLite/releases)

Android wallet (pairs with SilentDragon or SilentDragonLite): [SilentDragonAndroid](https://git.hush.is/hush/SilentDragonAndroid/releases)

# License

GPLv3

# Copyright

Copyright 2016-2024 The Hush developers