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

Installing Hush from a binary

You can also install a binary from an official release

Terminology

We have a document that explains a lot of terminology here

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 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 RPC
• To get a list of all zaddrs in a wallet use the z_listaddresses 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 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 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
  • Do not use z_getbalance 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 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 RPC
• To backup an entire wallet use the z_exportwallet 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 or getrawtransaction txid 1 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

GUI wallets

Hush full node GUI wallet: SilentDragon

Hush lite wallet: SilentDragonLite

Android wallet (pairs with SilentDragon or SilentDragonLite): SilentDragonAndroid

License

GPLv3

Copyright

Copyright 2016-2024 The Hush developers