Pirate Chain Integration Guide

Pirate Chain Exchange Integration Guide

Please see below the instructions to install Pirate daemon, best practices and tips.

- !!! IMPORTANT !!!

PirateChain (ARRR) is a fully shielded chain and ONLY uses zs addresses - transparent addresses are NOT permitted to perform transactions other than generating coinbase (mining) and notarizations by elected KMD notaries; the usual RPC commands generally don't apply

RPC commands for Pirate start with z_ -> see pirate-cli help for a list of available commands

1. Build the daemon

sudo apt-get update && sudo apt-get upgrade -y

sudo apt-get install build-essential pkg-config libc6-dev m4 g++-multilib autoconf libtool libncurses-dev unzip git python zlib1g-dev wget bsdmainutils automake libboost-all-dev libssl-dev libprotobuf-dev protobuf-compiler libgtest-dev libqt4-dev libqrencode-dev libdb++-dev ntp ntpdate software-properties-common libevent-dev curl libcurl4-gnutls-dev cmake clang libsodium-dev jq htop -y

git clone https://github.com/PirateNetwork/pirate

cd pirate 

./zcutil/fetch-params.sh

./zcutil/build.sh -j$(nproc)

2. Set shortcuts for ease of use and start the daemon:

sudo ln -sf /home/$USER/pirate/src/pirate-cli /usr/local/bin/pirate-cli 
sudo ln -sf /home/$USER/pirate/src/pirated /usr/local/bin/pirated

pirated &

• on first run of daemon the configuration file is created in ~/.komodo/PIRATE/PIRATE.conf <- you can specify a different location by passing -datadir=/path/to/data/dir when running the daemon (!!! if you do so you will need to run that param every time you run/restart the daemon)

3. Managing and getting info about transactions:

!!! Using 2 different nodes is highly recommended:

• 1 that will hold the deposit wallet (containing deposit addresses for each user depending on how your exchange engine works)
• 1 that will hold the withdraw wallet (from which withdraws will be issued to users)

In order to achieve this setup the funds from the deposit wallet need to be swept regularly (sent) to the withdraw wallet.

• To query addresses and check for deposits you have the following rpc commands: z_listunspent - this gives you a list of unspent notes/available funds (shielded utxos or shortly zutxos) It is recommended to index/cache in a local db the transactions that appear here along with txids and have your system mark them as credited or not - it will make your life easy in the long run if claims for deposits not arriving will arise, but this is left to your own assessment depending on how your engine works

- !!! You can NOT search for addresses or txid’s in any explorer - this is the core of Pirate Chain - privacy

z_listreceivedbyaddress <zsAddress> - this gives you a list of all transactions received by an address, however there is no information available as to where it came from, nor the amount - useful for cross referencing txids from this rpc call to txids with indexed txids from z_listunspent above

z_viewtransaction <txid> - this gives you information about a txid. For funds sent you can see the originating address where funds were sent from (yours) and destination address, as well as amount. For funds received you only see your address and amount, along with other zk-SNARKs information such as commitment, rk, nullifier, but these are not really useful from an exchange point of view.

• Sending funds (issuing withdrawals):

z_sendmany "yourWithdrawZsAddress" '[{"address":"userZsAddress", "amount": <amount>}]' - this will return an opid (operation id)

- !!! opids are cleared on daemon restart or when z_getoperationresult is called

!!! z_getoperationstatus '["<opid>"]' - this returns the status of the opid returned from z_sendmany; you are only interested in the following 2 statuses: success and failed

You should index/save to a local db the full output of this rpc call if status is success or failed, otherwise you will have a lot of trouble resolving claims for "withdraw did not reach my wallet"

- !!! IMPORTANT !!!

You MUST take into consideration change field when performing transactions - i.e. if partial withdraws are processed from deposit address of user you must account for change as it goes back to the same deposit address and you mustn't credit it to users' balance in your accounting system hence why using separate deposit/withdraw wallets should be used to reduce overhead in your exchange engine.

Quick shortcut to create an example PIRATE.conf if you don't want daemon to create it automatically:

mkdir -p ~/.komodo/PIRATE

cat << EOF > ~/.komodo/PIRATE/PIRATE.conf
rpcuser=user$(openssl rand -hex 32)
rpcpassword=pass$(openssl rand -hex 32)
rpcport=45453
server=1
txindex=1
daemon=1
rpcworkqueue=256
rpcallowip=127.0.0.1
rpcbind=127.0.0.1
consolidation=1
deletetx=1
keeptxnum=1000
EOF

chmod 600 ~/.komodo/PIRATE/PIRATE.conf

4. Wallet Management to keep wallet.dat at a reasonable size

The following .conf options are enabled thanks to our latest feature from Forge - wallet pruner

• Set 1:

consolidation - Enable auto Sapling note consolidation (set to 1 to enable)

consolidatesaplingaddress=<zaddr>

consolidationtxfee - Fee amount in Satoshis used send consolidation transactions. (default 0)

• Set 2:

deletetx - Enable Old Transaction Deletion (set to 1 to enable)

deleteinterval - Delete transaction every blocks during inital block download (default: 1000)

keeptxnum - Keep the last transactions (default: 200)

keeptxfornblocks - Keep transactions for at least blocks (default: 10000)

The first set will enable the node to create automatic 0 fee transactions that will sweep all of the notes and send them to the same address they were found in. This reduces the number of notes the node has to track, but all balances will remain the same

Set 1 is for sapling transactions only Set 2 is for the tx pruning.

These features remove the need for script-based wallet management relying on z_mergetoaddress

================================================================================================

Tips & tricks

TIP #1: on daemon build,before running./zcutil/build.sh you can edit src/net.cpp and replace MAX_OUTBOUND_CONNECTIONS=16 with MAX_OUTBOUND_CONNECTIONS=150 <- this will allow you to set maxconnections=100 in .komodo/PIRATE/PIRATE.conf and have a hyper-connected node

TIP #2: add daemon=1 to .conf so you don't have to add & whenever you start the daemon

TIP #3: don't run Pirate in docker - docker is not currently supported, however we are testing a dockerized version and will be made available in the future

TIP #4: don't use -zapwallettxes unless you REALLY have to

TIP #5: never send/move funds when chain is syncing <- that will most likely earn you a need for -rescan and that may take a while depending on your specs; we have implemented a fail-safe for this so not relevant anymore

TIP #6: confirmations field from rpc json when querying a txid will use dPoW(delayed proof of work) confirmations <- you want to use that over rawconfirmations :: when using dPoW confirmations, confirmations stays at 1 until a notarization happens (snapshot on KMD + LTC blockchains, generally every 10-15 mins); once a notarization happens confirmations == rawconfirmations meaning that as long as you have confirmations > 2 you are safe as an exchange from 51% attacks & double spends and will vastly reduce deposit/withdrawals time, making for a great user experience – recommended confirmations: anything above 2 but that is left to your own judgement

TIP #7: you will want to employ a mechanism of defense against mining to exchange address such as a fee for deposits under X ARRR or limit deposits to 1 / hour <- shielded transactions are heavy and thousands of small deposits will bloat your wallet to 2+ GB in no time <- this will no longer be relevant as we are currently testing a new release to mitigate such issues