Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

JSON-RPC methods

This reference documents every JSON-RPC method Zallet provides. It is generated from the same source as the zallet rpc help output and the machine-readable OpenRPC document served by the rpc.discover method, and a test pins it to that source, so it always matches the release it ships with.

decoderawtransaction

Return a JSON object representing the serialized, hex-encoded transaction.

Arguments

  • hexstring (string, required) The transaction hex string.

decodescript

Decodes a hex-encoded script.

Arguments

  • hexstring (string, required): The hex-encoded script.

getrawtransaction

Returns the raw transaction data for the given transaction ID.

NOTE: If blockhash is provided, only that block will be searched, and if the transaction is in the mempool or other blocks, or if the node backing this wallet does not have the given block available, the transaction will not be found.

Arguments

  • txid (string, required) The transaction ID.
  • verbose (numeric, optional, default=0) If 0, return a string of hex-encoded data. If non-zero, return a JSON object with information about txid.
  • blockhash (string, optional) The block in which to look for the transaction.

getwalletinfo

Only available in wallet builds of Zallet.

Returns wallet state information.

getwalletstatus

Returns wallet status information.

help

Only available in wallet builds of Zallet.

List all commands, or get help for a specified command.

Arguments

  • command (string, optional) The command to get help on.

listaddresses

Lists the addresses managed by this wallet by source.

Sources include:

  • Addresses generated from randomness by a legacy zcashd wallet.
  • Sapling addresses generated from the legacy zcashd HD seed.
  • Imported watchonly transparent addresses.
  • Shielded addresses tracked using imported viewing keys.
  • Addresses derived from mnemonic seed phrases.

In the case that a source does not have addresses for a value pool, the key associated with that pool will be absent.

REMINDER: It is recommended that you back up your wallet files regularly. If you have not imported externally-produced keys, it only necessary to have backed up the wallet’s key storage file.

rpc.discover

Only available in wallet builds of Zallet.

Returns an OpenRPC schema as a description of this service.

stop

Stop the running zallet process.

Notes

  • Works for non windows targets only.
  • Works only if the network of the running zallet process is Regtest.

validateaddress

Validate a transparent Zcash address, returning information about it.

Arguments

  • address (string, required): The transparent address to validate.

verifymessage

Verify a signed message.

Arguments

  • zcashaddress (string, required): The Zcash transparent address used to sign the message.
  • signature (string, required): The signature provided by the signer in base64 encoding.
  • message (string, required): The message that was signed.

walletlock

Only available in wallet builds of Zallet.

Removes the wallet encryption key from memory, locking the wallet.

After calling this method, you will need to call walletpassphrase again before being able to call any methods which require the wallet to be unlocked.

walletpassphrase

Only available in wallet builds of Zallet.

Stores the wallet decryption key in memory for timeout seconds.

If the wallet is locked, this API must be invoked prior to performing operations that require the availability of private keys, such as sending funds.

Issuing the walletpassphrase command while the wallet is already unlocked will set a new unlock time that overrides the old one.

z_converttex

Converts a transparent P2PKH Zcash address to a TEX address.

TEX addresses (defined in ZIP 320) are transparent-source-only addresses.

The input address must be valid for the network this node is running on.

Arguments

  • transparent_address (string, required): The transparent P2PKH address to convert.

z_exportkey

Only available in wallet builds of Zallet.

Exports the spending key for a Sapling payment address.

The wallet must be unlocked to use this method.

Warning

This exports only the Sapling spending key. It is not a complete backup of the funds reachable from this account’s root of spending authority: in particular, any Orchard funds derived from the same seed are not represented by the exported key. Do not rely on z_exportkey as a wallet backup — use a full seed/wallet backup instead, or you may lose access to funds.

Arguments

  • address (string, required) The Sapling payment address corresponding to the spending key to export.

z_exportviewingkey

Only available in wallet builds of Zallet.

Reveals the viewing key corresponding to ‘zaddr’.

Arguments

  • zaddr (string, required) The Sapling payment address or unified address.
  • ivk (boolean, optional, default=false) When true, export the unified incoming viewing key (UIVK) for the account holding zaddr instead of the full viewing key.

Returns

A string containing the viewing key:

  • For a Sapling payment address, the Sapling extended full viewing key (zxviews…).
  • For a unified address, the unified full viewing key (uview…) of the account holding the address.
  • When ivk is true, the unified incoming viewing key (uivk…) of the account holding the address, for either address kind. Note that a UIVK grants incoming viewing capability for every pool in the account, even when zaddr is a Sapling address.

z_getaccount

Returns details about the given account.

Arguments

  • account_uuid (string, required): The UUID of the wallet account.

z_getaddressforaccount

For the given account, derives a Unified Address in accordance with the remaining arguments:

  • If no list of receiver types is given (or the empty list []), the best and second-best shielded receiver types, along with the “p2pkh” (i.e. transparent) receiver type, will be used.
  • If no diversifier index is given, then:
    • If a transparent receiver would be included (either because no list of receiver types is given, or the provided list includes “p2pkh”), the next unused index (that is valid for the list of receiver types) will be selected.
    • If only shielded receivers would be included (because a list of receiver types is given that does not include “p2pkh”), a time-based index will be selected.

The account parameter must be a UUID or account number that was previously generated by a call to the z_getnewaccount RPC method. The legacy account number is only supported for wallets containing a single seed phrase.

Once a Unified Address has been derived at a specific diversifier index, re-deriving it (via a subsequent call to z_getaddressforaccount with the same account and index) will produce the same address with the same list of receiver types. An error will be returned if a different list of receiver types is requested, including when the empty list [] is provided (if the default receiver types don’t match).

z_getbalanceforaccount

Only available in wallet builds of Zallet.

Returns the account’s spendable balance for each value pool (“transparent”, “sapling”, and “orchard”).

Pools for which the balance is zero are not shown.

Arguments

  • account (string or numeric, required) Either the UUID or the ZIP 32 account index of the account, as returned by z_getnewaccount.
  • minconf (numeric, optional, default=1) Only include outputs in transactions confirmed at least this many times.

z_getbalances

Only available in wallet builds of Zallet.

Returns the balances available for each independent spending authority held by the wallet, and optionally the balances and received amounts associated with imported watch-only addresses and viewing keys.

This includes funds held by each HD-derived Unified Account in the wallet, spending keys imported with z_importkey, and (if enabled) the legacy transparent pool of funds.

Arguments

  • minconf (numeric, optional, default=1) Only include unspent outputs in transactions confirmed at least this many times.

z_getnewaccount

Only available in wallet builds of Zallet.

Prepares and returns a new account.

If the wallet contains more than one UA-compatible HD seed phrase, the seedfp argument must be provided. Available seed fingerprints can be found in the output of the listaddresses RPC method.

Within a UA-compatible HD seed phrase, accounts are numbered starting from zero; this RPC method selects the next available sequential account number.

Each new account is a separate group of funds within the wallet, and adds an additional performance cost to wallet scanning.

Use the z_getaddressforaccount RPC method to obtain addresses for an account.

z_getnotescount

Only available in wallet builds of Zallet.

Returns the number of notes available in the wallet for each shielded value pool.

Arguments

  • minconf: Only include notes in transactions confirmed at least this many times (default = 1). Must be at least 1 when as_of_height is provided.
  • as_of_height: Execute the query as if it were run when the blockchain was at the height specified by this argument. The default is to use the entire blockchain that the node is aware of. -1 can be used as in other RPC calls to indicate the current height (including the mempool), but this does not support negative values in general. A “future” height will fall back to the current height.

z_getoperationresult

Only available in wallet builds of Zallet.

Retrieve the result and status of an operation which has finished, and then remove the operation from memory.

  • If the operation has failed, it will include an error object.
  • If the operation has succeeded, it will include the result value.
  • If the operation was cancelled, there will be no error object or result value.

Arguments

  • operationid (array, optional) A list of operation ids we are interested in. If not provided, retrieve all finished operations known to the node.

z_getoperationstatus

Only available in wallet builds of Zallet.

Get operation status and any associated result or error data.

The operation will remain in memory.

  • If the operation has failed, it will include an error object.
  • If the operation has succeeded, it will include the result value.
  • If the operation was cancelled, there will be no error object or result value.

Arguments

  • operationid (array, optional) A list of operation ids we are interested in. If not provided, examine all operations known to the node.

z_gettotalbalance

Only available in wallet builds of Zallet.

Returns the total value of funds stored in the node’s wallet.

TODO: Currently watchonly addresses cannot be omitted; include_watchonly must be set to true.

Arguments

  • minconf (numeric, optional, default=1) Only include private and transparent transactions confirmed at least this many times.
  • include_watchonly (bool, optional, default=false) Also include balance in watchonly addresses (see ‘importaddress’ and ‘z_importviewingkey’).

z_importaddress

Only available in wallet builds of Zallet.

Imports a transparent address into the wallet for a given account.

The hex data can be either:

  • A compressed or uncompressed public key (imports as P2PKH).
  • A redeem script (imports as P2SH).

Returns the type of address imported and the corresponding transparent address.

Arguments

  • account (string, required) The account UUID.
  • hex_data (string, required) Hex-encoded public key or redeem script.
  • rescan (boolean, optional, default=true) If true, rescan the chain for UTXOs belonging to all wallet transparent addresses after importing.

z_importkey

Only available in wallet builds of Zallet.

Imports a spending key into the wallet.

Only Sapling extended spending keys are supported.

Arguments

  • key (string, required) The spending key to import.
  • rescan (string, optional, default=“whenkeyisnew”) Whether to rescan the blockchain for transactions (“yes”, “no”, or “whenkeyisnew”). When rescan is enabled, the wallet’s background sync engine will scan for historical transactions from the given start height.
  • startHeight (numeric, optional, default=0) Block height from which to begin the rescan. Only used when rescan is “yes” or “whenkeyisnew” (for a new key).

z_listaccounts

Returns the list of accounts created with z_getnewaccount or z_recoveraccounts.

Arguments

  • include_addresses (bool, optional, default=true) Also include the addresses known to the wallet for this account.

z_listoperationids

Only available in wallet builds of Zallet.

Returns the list of operation ids currently known to the wallet.

Arguments

  • status (string, optional) Filter result by the operation’s state e.g. “success”.

z_listtransactions

Returns a list of the wallet’s transactions, optionally filtered by account and block range.

Arguments

  • account_uuid: The UUID of the wallet account. If omitted, return transactions for all accounts in the wallet.
  • start_height: The inclusive lower bound of block heights for which transactions mined in those blocks should be returned. If omitted, the start height will default to the account birthday height if an account UUID is specified, or the minimum birthday height among accounts in the wallet if no account is specified.
  • end_height: The exclusive upper bound of block heights for which transactions mined in those blocks should be returned. If omitted, return all transactions mined or created above the start height.
  • offset: An optional number of transactions to skip over before a page of results is returned. Defaults to zero.
  • limit: An optional upper bound on the number of results that should be returned in a page.

WARNING: This is currently an experimental feature; arguments and result data may change at any time.

z_listunifiedreceivers

Returns a record of the individual receivers contained within the provided UA, keyed by receiver type. The UA may not have receivers for some receiver types, in which case those keys will be absent.

Transactions that send funds to any of the receivers returned by this RPC method will be detected by the wallet as having been sent to the unified address.

Arguments

  • unified_address (string, required) The unified address to inspect.

z_listunspent

Only available in wallet builds of Zallet.

Returns an array of unspent shielded notes with between minconf and maxconf (inclusive) confirmations.

Results may be optionally filtered 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.

Arguments

  • minconf: Select outputs with at least this many confirmations (default = 1). Must be at least 1 when as_of_height is provided.
  • maxconf: Select outputs with at most this many confirmations (default = unlimited).
  • include_watchonly: Include notes/utxos for which the wallet does not provide spending capability (default = false).
  • addresses: A list of addresses for which to retrieve UTXOs. For shielded addresses that correspond to a unified account, unspent notes belonging to that account are returned irrespective of whether the provided address’s diversifier corresponds to the diversifier of the address that received the funds. If this parameter is omitted or empty, all notes are returned, irrespective of account. (default = None)
  • as_of_height: Execute the query as if it were run when the blockchain was at the height specified by this argument. The default is to use the entire blockchain that the node is aware of. -1 can be used as in other RPC calls to indicate the current height (including the mempool), but this does not support negative values in general. A “future” height will fall back to the current height.

z_recoveraccounts

Only available in wallet builds of Zallet.

Tells the wallet to track specific accounts.

Returns the UUIDs within this Zallet instance of the newly-tracked accounts. Accounts that are already tracked by the wallet are ignored.

After calling this method, a subsequent call to z_getnewaccount will add the first account with index greater than all indices provided here for the corresponding seedfp (as well as any already tracked by the wallet).

Each tracked account is a separate group of funds within the wallet, and adds an additional performance cost to wallet scanning.

Use the z_getaddressforaccount RPC method to obtain addresses for an account.

Arguments

  • accounts (array, required) An array of JSON objects representing the accounts to recover, with the following fields:
    • name (string, required)
    • seedfp (string, required) The seed fingerprint for the mnemonic phrase from which the account is derived. Available seed fingerprints can be found in the output of the listaddresses RPC method.
    • zip32_account_index (numeric, required)
    • birthday_height (numeric, required)

z_sendmany

Only available in wallet builds of Zallet.

Send a transaction with multiple recipients.

This is an async operation; it returns an operation ID string that you can pass to z_getoperationstatus or z_getoperationresult.

Amounts are decimal numbers with at most 8 digits of precision.

Change generated from one or more transparent addresses flows to a new transparent address, while change generated from a legacy Sapling address returns to itself. TODO: https://github.com/zcash/zallet/issues/138

When sending from a unified address, change is returned to the internal-only address for the associated unified account.

When spending coinbase UTXOs, only shielded recipients are permitted and change is not allowed; the entire value of the coinbase UTXO(s) must be consumed. TODO: https://github.com/zcash/zallet/issues/137

Arguments

  • fromaddress (string, required) The transparent or shielded address to send the funds from. The following special strings are also accepted:
    • "ANY_TADDR": Select non-coinbase UTXOs from any transparent address in the legacy zcashd pool of funds. This requires features.legacy_pool_seed_fingerprint to be set in the Zallet config file to the seed fingerprint of the zcashd wallet that was migrated into this wallet; without it there is no legacy pool to spend from and the call is rejected. Covering the payment from more than one of the pool’s addresses links them on-chain, so such a call requires a privacy policy of AllowLinkingAccountAddresses (or of NoPrivacy, if it also has a transparent recipient or transparent change). Use z_shieldcoinbase to shield coinbase UTXOs from multiple transparent addresses. If a unified address is provided for this argument, the TXOs to be spent will be selected from those associated with the account corresponding to that unified address, from value pools corresponding to the receivers included in the UA.
  • amounts (array, required) An array of JSON objects representing the amounts to send, with the following fields:
    • address (string, required) A taddr, zaddr, or Unified Address.
    • amount (numeric, required) The numeric amount in ZEC.
    • memo (string, optional) If the address is a zaddr, raw data represented in hexadecimal string format. If the output is being sent to a transparent address, it’s an error to include this field.
  • minconf (numeric, optional) Only use funds confirmed at least this many times.
  • fee (numeric, optional) If set, it must be null. Zallet always uses a fee calculated according to ZIP 317.
  • privacy_policy (string, optional, default="FullPrivacy") Policy for what information leakage is acceptable. One of the following strings:
    • "FullPrivacy": Only allow fully-shielded transactions (involving a single shielded value pool).
    • "AllowRevealedAmounts": Allow funds to cross between shielded value pools, revealing the amount that crosses pools.
    • "AllowRevealedRecipients": Allow transparent recipients. This also implies revealing information described under "AllowRevealedAmounts".
    • "AllowRevealedSenders": Allow transparent funds to be spent, revealing the sending addresses and amounts. This implies revealing information described under "AllowRevealedAmounts".
    • "AllowFullyTransparent": Allow transaction to both spend transparent funds and have transparent recipients. This implies revealing information described under "AllowRevealedSenders" and "AllowRevealedRecipients".
    • "AllowLinkingAccountAddresses": Allow selecting transparent coins from the full account, rather than just the funds sent to the transparent receiver in the provided Unified Address. This implies revealing information described under "AllowRevealedSenders".
    • "NoPrivacy": Allow the transaction to reveal any information necessary to create it. This implies revealing information described under "AllowFullyTransparent" and "AllowLinkingAccountAddresses".

z_shieldcoinbase

Only available in wallet builds of Zallet.

Shields coinbase UTXOs from a single wallet-owned source into a shielded address.

This is an asynchronous operation; it returns an operation id that can be used with z_getoperationstatus or z_getoperationresult.

Arguments

  • fromaddress: Either a single transparent address owned by this wallet, or an account UUID (string) to sweep every coinbase UTXO across that account’s transparent receivers. Arrays of addresses are not accepted; pass the account UUID instead if you need to sweep across multiple receivers. Unlike zcashd, the wildcard "*" (sweep all wallet t-addrs) is rejected with an InvalidParameter error: cross-account sweeps would correlate otherwise-unrelated accounts on-chain, so callers must scope the sweep to a single account by passing its UUID.

  • toaddress: Any Zcash shielded address (Sapling, Orchard, or Unified with a shielded receiver) that will receive the shielded funds. Need not belong to this wallet. Transparent / TEX destinations are rejected by the backend.

  • fee (numeric, optional): If set, it must be null. Zallet always uses a fee calculated according to ZIP 317; the parameter is accepted for positional compatibility with zcashd’s z_shieldcoinbase only.

  • limit (numeric, optional): If supplied, caps the number of selected coinbase UTXOs to the highest-value n of those eligible. Recommended for wallets with many eligible coinbase UTXOs: without it, a single transaction is built containing all eligible UTXOs, which can exceed transaction-size limits at broadcast time.

  • memo (string, optional): If supplied, stored in the memo field of the resulting shielded payment. Hex-encoded, up to 1024 hex characters (= 512 bytes).

  • privacy_policy (string, optional): Policy for what information leakage is acceptable. Coinbase shielding always reveals the source transparent address(es), so only two policy values are accepted:

    • "AllowRevealedSenders": Allow revealing the source transparent address. Sufficient when sweeping from a single t-addr.
    • "AllowLinkingAccountAddresses": Additionally allow linking multiple source t-addrs on-chain. Required when sweeping from an account UUID that expands to >1 transparent receiver with eligible coinbase UTXOs.

    When omitted or null, the default is chosen from fromaddress: "AllowRevealedSenders" for a single t-addr, or "AllowLinkingAccountAddresses" for an account UUID. Any other policy name (including stricter values like "FullPrivacy" and looser ones like "NoPrivacy") is rejected.

Returns

An object matching zcashd’s z_shieldcoinbase shape:

  • remainingUTXOs (numeric): Eligible-but-not-selected coinbase UTXO count.
  • remainingValue (numeric, ZEC): Total value of those UTXOs.
  • shieldingUTXOs (numeric): Number of coinbase UTXOs being shielded by this operation.
  • shieldingValue (numeric, ZEC): Total value being shielded.
  • opid (string): Operation id.

z_viewtransaction

Returns detailed information about in-wallet transaction txid.

This method returns information about spends and outputs within the transaction that are visible to the wallet. Importantly, this does not include information about spent notes that are not controlled by spending or viewing keys in the wallet, and so callers MUST NOT use the spends or outputs fields to compute balances or fees themselves. Use the provided accounts and fee fields instead.