SETUP.md

Setting up NuBot

A tutorial for custodians

Disclaimer . Use NuBot at your own risk

PLEASE BE AWARE THAT AUTOMATED TRADING WITH NUBOT MAY BE RISKY, ADDICTIVE, UNETHICAL OR ILLEGAL. ITS MISUSE MAY ALSO CAUSE FINANCIAL LOSS. NONE OF THE AUTHORS, CONTRIBUTORS, ADMINISTRATORS, OR ANYONE ELSE CONNECTED WITH NUBITS, IN ANY WAY WHATSOEVER, CAN BE RESPONSIBLE FOR THE USE YOU MAKE OF NUBOT

By using NuBot you declare to have accepted the afore-mentioned risks.

Requirements for a correct functioning

  • The machine that runs NuBot must be connected to the internet
  • The custodian must provide the bot with access to market exchanges where NuBits are traded
  • The custodian must avoid manual interaction with the exchange while the automated bot is operating. Do not try to trade, do not try to deposit/withdraw funds.
  • To communicate liquidityinfo, the custodian should possess an unlocked NuBit client which controls the custodial grant address.
  • Before running the bot on a market where another instance of NuBot is operating, make sure to reach an agreement with the other operator on the price-feed to be used.

Setup overview.

TL; DR Make sure you run both the NuBits client and NuBot on a machine connected to the internet 24/7, configure NuBits client to accept RCP commands, configure NuBot, launch it and monitor it.

Detailed tutorial below :

0) Setup the machine

NuBot can run on a computer, on a raspberry pi, or a remote VPS, as long as it has a permanent connection. The choice is up to you. It only requires a machine with 24/7 connection and recent Java Runtime Environment to be installed. NuBot comes as a cross platform executable jar file to run from command line.

Type java -version in your terminal to make sure you have JRE >= 1.7 installed on your machine, otherwise download Java JRE:1.7 from oracle's download page

In the future we will make available a docker container pre-prepared.

1) Prepare the NuBits client

To function correctly, NuBot needs to communicate with the NuBit client of the custodian. The bot needs to broadcast liquidity notification to NuNet. By doing so, it allow shareholders to have real-time information about active orders in the network across custodians, and react to it. It does so by interacting via the NuBits client of the custodian.

Install the latest version of the NuBit client from the official website and let the client sync with the network (downloading the whole blockchain from scratch can take a while).

NOTE: Is it also possible to test NuBot without being a custodian and setting the "submit-liquidity":false in the configuration file. In this case you can ignore this section.

To allow the bot to communicate with the Nu client via RCP over HTTP, open your nu.conf and add make sure you have it properly configured: Read this bitcoin tutorial to locate the data directory.

nu.conf sample configuration

server=1
rpcuser=<choose-a-username>
rpcpassword=<choose-a-password>
port=9090
rpcport=9091
rpcallowip=<ip_of_machine_running_the_bot>*

*NOTE: if you plan using NuBot and NuBits on the same machine, the last parameter can be omitted. If you plan to run the bot on a different machine, you must authorise remote calls to your Nu client.

Restart the NuBits client to make changes effective. Make sure that the NuBit client controls a public address which received a custodial grant. If the NuBits wallet is encrypted with a passphrase, make sure to unlock it, otherwise it won't accept RPC calls to liquidityinfo. Unlocking the wallet for minting only is not enough.

The two Nu wallets are locked/unlocked separately. To unlock the NuBits wallets, first make sure the client is displaying the NuBits units, then open the console and type:

walletpassphrase <your passphrase> 9999999999 

The command above will unlock the NBT wallet for 9999999999 seconds, ~ 300 years. That should be enough time for your bot to keep the peg!

2) Configure the NuBot

Download and unzip the latest stable build from the download page.

The bot reads configuration options from one or multiple .json files. Below you can find a list of all the available options parameter along a brief description. Please make sure you fully understand in which way changing a setting will affect the bot before doing anything that can lead to losses.

Its good practice separating configuration parameters in different files. In this tutorial we will use the following grouping :

  • market options: exchange keys and market-related settings ;
  • misc options: miscellaneous configuration parameters ;
  • liquidity-info options: define nubits client communication ;
  • price-tracking options: for non-USD pairs, define price feeds ;

The same structure is used in the config-sample files provided with the bot. You can edit the provided sample file or create new configuration files.


Market options

Parameters :

Parameter Default value Description Admitted values
exchangename / Name of the exchange where the bots operates see list of accepted exchange names*
apikey / Custodian's public key to access the exchange . this param is optional for ccex String
apisecret / Custodian's secret key to access the exchange String
txfee 0.2 If transaction fee not available from the exchange via api, this value will be used double. Expressed in absolute percentage. 10 = 10% , 0.5 = 0.5%
pair The currency pair where the bot operates valid currency pair for the specified eg. "nbt_usd"

** List of accepted names : "bter" ; "ccedk" ; "btce" ; "peatio" ; "poloniex" ; "ccex" ; "excoin" ; "bitcoinid"

Sample file : markets.json:

{"options": 
    {
    "exchangename":"bter",
    "apikey": "xxx",
    "apisecret": "xxx",
    "txfee": 0.2,
    "pair":"nbt_btc"
 }
}

Misc options

Parameters :

Parameter Default value Description Admitted values
dualside / If set to true, the bot will behave as a dual side custodian, if false as a sell side custodian. true,false
multiple-custodians false if set to true, will sync with remote NPT and reset orders often boolean
executeorders true if set to false the bot will print a warning instead of executing orders boolean
verbose false if set to true, will print on screen additional debug messages boolean
hipchat true if set to false will disable hipchat notifications boolean
mail-notifications true if set to false will disable email notifications boolean
mail-recipient / the email to which emergency email are sent String
emergency-timeout 60 max amount of minutes of consecutive failure. After those minute elapse, emergency procedure starts int (minutes)
keep-proceeds 0 Specific setting for KTm's proposal. Will keep the specified proceeds from sales apart instead of putting 100% of balance on buy . double. Expressed in absolute percentage. 10 = 10% , 0.5 = 0.5%
max-sell-order-volume 0 maximum volume to put on sell walls. double , expressed in NBT . 0=no limit;
max-buy-order-volume 0 maximum volume to put on buy walls. double , expressed NBT. 0=no limit;
priceincrement 0.0003 if working in sell-side mode, this value (considered USD) will be added to the sell price double , price increment in expressed USD

Sample file : misc.json:

{"options": 
    {
    "dualside": true,  
    "multiple-custodians":false,
    "submit-liquidity":true,
    "executeorders":false,
    "verbose":false,
    "hipchat":true,
    "mail-notifications":false,
    "mail-recipient":"xxx@xxx.xxx",
    "emergency-timeout":60,
    "keep-proceeds":0,
    "max-sell-order-volume" : 0,
    "max-buy-order-volume" : 0,
    "priceincrement": 0.1,
 }
}

Liquidity-info options

Parameters :

Parameter Default value Description Admitted values
submit-liquidity true if set to false, the bot will not try to submit liquidity info. If set to false, it will also allow the custodian to omit the declaration of nubitaddress , nudport , rpcuser and rpcpass boolean
nubitaddress / The public address where the custodial grant has been received valid custodian NBT addresses (String)
nudip "127.0.0.1" The IP address of the machine that hosts the Nu Client IP address (String)
nudport / The RPC port of the Nu daemon 1024...65535
rpcpass / The RPC password of the Nu daemon String
rpcuser / The RPC username of the Nu daemon String

Sample file : liquidity-info.json:

{"options": 
    {
    "submit-liquidity":true,
    "nubitaddress": "xxx",
    "nudip": "127.0.0.1",
    "nudport": 9091,
    "rpcpass": "xxx",
    "rpcuser": "xxx"
 }
}

Price-tracking options

When running the bot against a currency pair different from NBT/USD, the bot needs additional parameters to run.
The custodian must specify the price feeds that the bot must use to track the price of a currency (both fiat and crypto) different from USD.
The price feed will track the live rate between the secondary peg currency and USD.

Parameters :

Parameter Default value Description Admitted values
wallshift-threshold / how much the price need to change to trigger a wall-shift. double. Expressed in absolute percentage. 10 = 10% , 0.5 = 0.5%
spread / the spread between buy and sell walls double. Expressed in absolute percentage. 10 = 10% , 0.5 = 0.5%
main-feed / the name of the main price feed that has priority over the others **see following table
backup-feeds / a json array containing an arbitrary number (>2) of backup price feed names **see following table

See FEEDS.md for an updated list of valid feed names.

Sample file : price-tracking.json:

{"options": 
    {
     "secondary-peg-options":
    {
            "wallshift-threshold": 0.3,
            "spread": 0,
            "main-feed": "bitfinex",
            "backup-feeds": {
                "backup1" : { "name" : "blockchain"},
                "backup2" : { "name" : "coinbase"},
                "backup3" : { "name" : "bitstamp"}
                }
    }
 }
}

You can also merge all the configuration parameter under a unique .json file, although we do not recommend it.

3) Run NuBot

Now open a terminal, navigate to the folder of NuBot and execute the jar, specifying the path to the .json file(s) you want to use as configuration. This is the syntax :

java -jar NuBot.jar <path/to/options.json> [path/to/options-part2.json] ... [path/to/options-partN.json]

You can also use nohup in *nix system to redirect the output, and run it in background with the & char. For, example, if you followed the structured configuration files explained above you can run nubot with :

nohup java -jar NuBot.jar market.json misc.json liquidity-info.jon price-tracking.json  &

The bot will start and write output in the /logs folder.

To terminate the bot, exit the process with "Ctrl+C" : the bot will clear our liquidityinfo and orders.

Logging on HTML and csv

The bot produces different output log files, all stored in a special folder created for each session under logs/.
The bot creates a csv and html log for each session. There 4 levels of log messages : severe, warning, info and fine. fine are never logged to file (only to console). info are logged to file if we set"verbose"=true. warning are used for logging trading-related messages. severe are used for errors.

Additionally there are two other logs that trace the history of wall shifts and a history of snapshots of active orders.