5.4 Usage examples

5.3 Integration Path

We are going to cover some use cases that are relevant for exchanges here, for general usage examples see our 1.0 User Guide.

Setting fees

It’s best to leave the tx fee parameters at their defaults and use z_sendmany to send transactions. The fee defaults to 0.0001 ZEN for z_sendmany, most exchanges have chosen to set the fee to 0.001 ZEN. z_sendmany uses absolute values for the fee, rather than a fee based on transaction size, so the amount will always be predictable.

Common API calls

zen-cli getnewaddress to generate a new transparent address. 

zen-cli z_getnewaddress to generate a new private address.

zen-cli getreceivedbyaddress '$zenaddr' - gets the balance of a t-addr
zen-cli listtransactions - lists most recent transactions
zen-cli gettransaction '$txid' - gets detailed information about an in-wallet transaction

zen-cli listunspent - lists unspent transaction outputs

z_sendmany

Z_sendmany is the API call best used for both transparent and shielded transactions. It supports sending from a single input t- or z-address to multiple output t- and z-addresses.

Transactions involving z-addresses will always be computationally costly, so in general only t-addresses are used.

Usage example:

t_address_sender='your t-address'  # required parameter
t_address_receiver='receiver t-address'  # required parameter
fee=0.001  # optional, default value is 0.0001
min_confirmations=1  # optional, default value is 1
amount=XXXX  # required parameter
zen-cli z_sendmany ${t_address_sender} "[{\"address\": \"$t_address_receiver\", \"amount\":

$amount, \"minconf\": $min_confirmations, \"fee\": $fee}]"

Determine spendable utxo with listunspent

Per consensus rules coinbase transactions need to be sent to a z-addr before they can be spent. This can create problems with coinbase utxo directly mined to an exchange’s wallet. The listunspent command will display the property "generated": true since Zen version 2.0.11 if a transaction is a coinbase tx.

Shielding coinbase utxo with z_shieldcoinbase

If listunspent should show any coinbase tx in your wallet the z_shieldcoinbase command makes shielding them easier, it supports aggregating multiple coinbase tx to a t-address into a single shielded transaction.

The number of coinbase utxos selected for shielding can be set with the limit parameter, which has a default value of 50. If the parameter is set to 0, the number of utxos selected is limited by the -mempooltxinputlimit option. Any limit is constrained by a consensus rule defining a maximum transaction size of 100000 bytes. 

The from address is a t-addr or "*" for all t-addrs belonging to the wallet. The to address is a z-addr. The default fee is 0.0001.

z_shieldcoinbase '$fromaddress' '$to_z-address' [fee=0.0001] [limit=50]

Returns an object containing an operationid which can be used with z_getoperationstatus and z_getoperationresult, along with key-value pairs regarding how many utxos are being shielded in this transaction and what remains to be shielded.