From 471a912e024baf34713a3f432d343f9bfaa21d5a Mon Sep 17 00:00:00 2001 From: David Llop <931684+sembrestels@users.noreply.github.com> Date: Mon, 14 May 2018 15:37:08 +0200 Subject: [PATCH] Update Payment API I included those missing commands to the API reference: `z_exportviewingkey`, `z_importviewingkey`, and `z_listunspent`. Do you think we should include `z_mergetoaddress`, `z_getpaymentdisclosure`, and `z_validatepaymentdisclosure` too, despite they are experimental? --- doc/payment-api.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/payment-api.md b/doc/payment-api.md index 7408ecba1..e639cc429 100644 --- a/doc/payment-api.md +++ b/doc/payment-api.md @@ -29,10 +29,10 @@ Optional parameters are denoted in [square brackets]. RPC calls by category: * Accounting: z_getbalance, z_gettotalbalance -* Addresses : z_getnewaddress, z_listaddresses, z_validateaddress +* Addresses : z_getnewaddress, z_listaddresses, z_validateaddress, z_exportviewingkey, z_importviewingkey * Keys : z_exportkey, z_importkey, z_exportwallet, z_importwallet * Operation: z_getoperationresult, z_getoperationstatus, z_listoperationids -* Payment : z_listreceivedbyaddress, z_sendmany, z_shieldcoinbase +* Payment : z_listreceivedbyaddress, z_listunspent, z_sendmany, z_shieldcoinbase RPC parameter conventions: @@ -65,12 +65,16 @@ z_exportkey | zaddr | _Requires an unlocked wallet or an unencrypted wallet._

Add a zkey as returned by z_exportkey to a node's wallet.

The key should be formatted using Base58Check as described in the Zcash protocol spec.

Set rescan to true (the default) to rescan the entire local block database for transactions affecting any address or pubkey script in the wallet (including transactions affecting the newly-added address for this spending key). z_exportwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._

Creates or overwrites a file with taddr private keys and zaddr private keys in a human-readable format.

Filename is the file in which the wallet dump will be placed. May be prefaced by an absolute file path. An existing file with that name will be overwritten.

No value is returned but a JSON-RPC error will be reported if a failure occurred. z_importwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._

Imports private keys from a file in wallet export file format (see z_exportwallet). These keys will be added to the keys currently in the wallet. This call may need to rescan all or parts of the block chain for transactions affecting the newly-added keys, which may take several minutes.

Filename is the file to import. The path is relative to zcashd’s working directory.

No value is returned but a JSON-RPC error will be reported if a failure occurred. +z_exportviewingkey | zaddr | Reveals the viewing key corresponding to 'zaddr'. Then the z_importviewingkey can be used with this output. +z_importviewingkey | vkey [rescan=whenkeyisnew] [startHeight=0] | Adds a viewing key (as returned by z_exportviewingkey) to your wallet. + ### Payment Command | Parameters | Description --- | --- | --- z_listreceivedbyaddress
| zaddr [minconf=1] | Return a list of amounts received by a zaddr belonging to the node’s wallet.

Optionally set the minimum number of confirmations which a received amount must have in order to be included in the result. Use 0 to count unconfirmed transactions.

Output:
[{
“txid”: “4a0f…”,
“amount”: 0.54,
“memo”:”F0FF…”,}, {...}, {...}
] +z_listunspent | [minconf=1] [maxconf=9999999] [includeWatchonly=false] [zaddrs] | Returns array of unspent shielded notes with between minconf and maxconf (inclusive) confirmations.

Optionally filter to only include notes sent to specified addresses.

When minconf is 0, unspent notes with zero confirmations are returned, even though they are not immediately spendable.

Results are an array of Objects, each of which has: {txid, jsindex, jsoutindex, confirmations, address, amount, memo} z_sendmany
| fromaddress amounts [minconf=1] [fee=0.0001] | _This is an Asynchronous RPC call_

Send funds from an address to multiple outputs. The address can be either a taddr or a zaddr.

Amounts is a list containing key/value pairs corresponding to the addresses and amount to pay. Each output address can be in taddr or zaddr format.

When sending to a zaddr, you also have the option of attaching a memo in hexadecimal format.

**NOTE:**When sending coinbase funds to a zaddr, the node's wallet does not allow any change. Put another way, spending a partial amount of a coinbase utxo is not allowed. This is not a consensus rule but a local wallet rule due to the current implementation of z_sendmany. In future, this rule may be removed.

Example of Outputs parameter:
[{“address”:”t123…”, “amount”:0.005},
,{“address”:”z010…”,”amount”:0.03, “memo”:”f508af…”}]

Optionally set the minimum number of confirmations which a private or transparent transaction must have in order to be used as an input. When sending from a zaddr, minconf must be greater than zero.

Optionally set a transaction fee, which by default is 0.0001 ZEC.

Any transparent change will be sent to a new transparent address. Any private change will be sent back to the zaddr being used as the source of funds.

Returns an operationid. You use the operationid value with z_getoperationstatus and z_getoperationresult to obtain the result of sending funds, which if successful, will be a txid. z_shieldcoinbase
| fromaddress toaddress [fee=0.0001] [limit=50] | _This is an Asynchronous RPC call_

Shield transparent coinbase funds by sending to a shielded z address. Utxos selected for shielding will be locked. If there is an error, they are unlocked. The RPC call `listlockunspent` can be used to return a list of locked utxos.

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 taddr or "*" for all taddrs belonging to the wallet. The to address is a zaddr. The default fee is 0.0001.

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.