package cash.z.wallet.sdk.rpc

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc GetLatestBlock (ChainSpec, BlockID)

  service.proto:162

  Return the BlockID of the block at the tip of the best chain

  message ChainSpec

  service.proto:54

  Chainspec is a placeholder to allow specification of a particular chain fork.

  (message has no fields)

• rpc GetBlock (BlockID, CompactBlock)

  service.proto:164

  Return the compact block corresponding to the given block identifier

• rpc GetBlockNullifiers (BlockID, CompactBlock)

  service.proto:166

  Same as GetBlock except actions contain only nullifiers

• rpc GetBlockRange (BlockRange, stream CompactBlock)

  service.proto:168

  Return a list of consecutive compact blocks

• rpc GetBlockRangeNullifiers (BlockRange, stream CompactBlock)

  service.proto:170

  Same as GetBlockRange except actions contain only nullifiers

• rpc GetTransaction (TxFilter, RawTransaction)

  service.proto:173

  Return the requested full (not compact) transaction (as from zcashd)

  message TxFilter

  service.proto:28

  A TxFilter contains the information needed to identify a particular transaction: either a block and an index, or a direct transaction hash. Currently, only specification by hash is supported.

  • optional BlockID block = 1

    block identifier, height or hash

  • uint64 index = 2

    index within the block

  • bytes hash = 3

    transaction ID (hash, txid)

• rpc SendTransaction (RawTransaction, SendResponse)

  service.proto:175

  Submit the given transaction to the Zcash network

  message SendResponse

  service.proto:48

  A SendResponse encodes an error code and a string. It is currently used only by SendTransaction(). If error code is zero, the operation was successful; if non-zero, it and the message specify the failure.

  • int32 errorCode = 1

  • string errorMessage = 2

• rpc GetTaddressTxids (TransparentAddressBlockFilter, stream RawTransaction)

  service.proto:178

  Return the txids corresponding to the given t-address within the given block range

  message TransparentAddressBlockFilter

  service.proto:81

  TransparentAddressBlockFilter restricts the results to the given address or block range.

  • string address = 1

    t-address

  • optional BlockRange range = 2

    start, end heights

• rpc GetTaddressBalance (AddressList, Balance)

  service.proto:179

  message AddressList

  service.proto:104

  • repeated string addresses = 1

• rpc GetTaddressBalanceStream (stream Address, Balance)

  service.proto:180

  message Address

  service.proto:101

  • string address = 1

• rpc GetMempoolTx (Exclude, stream CompactTx)

  service.proto:191

  Return the compact transactions currently in the mempool; the results can be a few seconds out of date. If the Exclude list is empty, return all transactions; otherwise return all *except* those in the Exclude list (if any); this allows the client to avoid receiving transactions that it already has (from an earlier call to this rpc). The transaction IDs in the Exclude list can be shortened to any number of bytes to make the request more bandwidth-efficient; if two or more transactions in the mempool match a shortened txid, they are all sent (none is excluded). Transactions in the exclude list that don't exist in the mempool are ignored.

  message Exclude

  service.proto:111

  • repeated bytes txid = 1

• rpc GetMempoolStream (Empty, stream RawTransaction)

  service.proto:195

  Return a stream of current Mempool transactions. This will keep the output stream open while there are mempool transactions. It will close the returned stream when a new block is mined.

• rpc GetTreeState (BlockID, TreeState)

  service.proto:201

  GetTreeState returns the note commitment tree state corresponding to the given block. See section 3.7 of the Zcash protocol specification. It returns several other useful values also (even though they can be obtained using GetBlock). The block can be specified by either height or hash.

• rpc GetLatestTreeState (Empty, TreeState)

  service.proto:202

• rpc GetSubtreeRoots (GetSubtreeRootsArg, stream SubtreeRoot)

  service.proto:206

  Returns a stream of information about roots of subtrees of the Sapling and Orchard note commitment trees.

  message GetSubtreeRootsArg

  service.proto:130

  • uint32 startIndex = 1

    Index identifying where to start returning subtree roots

  • ShieldedProtocol shieldedProtocol = 2

    Shielded protocol to return subtree roots for

  • uint32 maxEntries = 3

    Maximum number of entries to return, or 0 for all entries.

  message SubtreeRoot

  service.proto:135

  • bytes rootHash = 2

    The 32-byte Merkle root of the subtree.

  • bytes completingBlockHash = 3

    The hash of the block that completed this subtree.

  • uint64 completingBlockHeight = 4

    The height of the block that completed this subtree in the main chain.

• rpc GetAddressUtxos (GetAddressUtxosArg, GetAddressUtxosReplyList)

  service.proto:208

  message GetAddressUtxosReplyList

  service.proto:156

  • repeated GetAddressUtxosReply addressUtxos = 1

• rpc GetAddressUtxosStream (GetAddressUtxosArg, stream GetAddressUtxosReply)

  service.proto:209

• rpc GetLightdInfo (Empty, LightdInfo)

  service.proto:212

  Return information about this lightwalletd instance and the blockchain

  message LightdInfo

  service.proto:61

  LightdInfo returns various information about this lightwalletd instance and the state of the blockchain.

  • string version = 1

  • string vendor = 2

  • bool taddrSupport = 3

    true

  • string chainName = 4

    either "main" or "test"

  • uint64 saplingActivationHeight = 5

    depends on mainnet or testnet

  • string consensusBranchId = 6

    protocol identifier, see consensus/upgrades.cpp

  • uint64 blockHeight = 7

    latest block on the best chain

  • string gitCommit = 8

  • string branch = 9

  • string buildDate = 10

  • string buildUser = 11

  • uint64 estimatedHeight = 12

    less than tip height if zcashd is syncing

  • string zcashdBuild = 13

    example: "v4.1.1-877212414"

  • string zcashdSubversion = 14

    example: "/MagicBean:4.1.1/"

  • string donationAddress = 15

    Zcash donation UA address

• rpc Ping (Duration, PingResponse)

  service.proto:214

  Testing-only, requires lightwalletd --ping-very-insecure (do not enable in production)

  message Duration

  service.proto:89

  Duration is currently used only for testing, so that the Ping rpc can simulate a delay, to create many simultaneous connections. Units are microseconds.

  • int64 intervalUs = 1

  message PingResponse

  service.proto:96

  PingResponse is used to indicate concurrency, how many Ping rpcs are executing upon entry and upon exit (after the delay). This rpc is used for testing only.

  • int64 entry = 1

  • int64 exit = 2

Used as response type in: CompactTxStreamer.GetTaddressBalance, CompactTxStreamer.GetTaddressBalanceStream

• int64 valueZat = 1

A BlockID message contains identifiers to select a block: a height or a hash. Specification by hash is not implemented, but may be in the future.

Used as request type in: CompactTxStreamer.GetBlock, CompactTxStreamer.GetBlockNullifiers, CompactTxStreamer.GetTreeState

Used as response type in: CompactTxStreamer.GetLatestBlock

Used as field type in: BlockRange, TxFilter

• uint64 height = 1

• bytes hash = 2

BlockRange specifies a series of blocks from start to end inclusive. Both BlockIDs must be heights; specification by hash is not yet supported.

Used as request type in: CompactTxStreamer.GetBlockRange, CompactTxStreamer.GetBlockRangeNullifiers

Used as field type in: TransparentAddressBlockFilter

• optional BlockID start = 1

• optional BlockID end = 2

Information about the state of the chain as of a given block.

Used in: CompactBlock

• uint32 saplingCommitmentTreeSize = 1

  the size of the Sapling note commitment tree as of the end of this block

• uint32 orchardCommitmentTreeSize = 2

  the size of the Orchard note commitment tree as of the end of this block

A compact representation of the shielded data in a Zcash block. CompactBlock is a packaging of ONLY the data from a block that's needed to: 1. Detect a payment to your Shielded address 2. Detect a spend of your Shielded notes 3. Update your witnesses to generate new spend proofs.

Used as response type in: CompactTxStreamer.GetBlock, CompactTxStreamer.GetBlockNullifiers, CompactTxStreamer.GetBlockRange, CompactTxStreamer.GetBlockRangeNullifiers

• uint32 protoVersion = 1

  the version of this wire format, for storage

• uint64 height = 2

  the height of this block

• bytes hash = 3

  the ID (hash) of this block, same as in block explorers

• bytes prevHash = 4

  the ID (hash) of this block's predecessor

• uint32 time = 5

  Unix epoch time when the block was mined

• bytes header = 6

  (hash, prevHash, and time) OR (full header)

• repeated CompactTx vtx = 7

  zero or more compact transactions from this block

• optional ChainMetadata chainMetadata = 8

  information about the state of the chain as of this block

A compact representation of an [Orchard Action](https://zips.z.cash/protocol/protocol.pdf#actionencodingandconsensus).

Used in: CompactTx

• bytes nullifier = 1

  [32] The nullifier of the input note

• bytes cmx = 2

  [32] The x-coordinate of the note commitment for the output note

• bytes ephemeralKey = 3

  [32] An encoding of an ephemeral Pallas public key

• bytes ciphertext = 4

  [52] The first 52 bytes of the encCiphertext field

A compact representation of a [Sapling Output](https://zips.z.cash/protocol/protocol.pdf#outputencodingandconsensus). It encodes the `cmu` field, `ephemeralKey` field, and a 52-byte prefix of the `encCiphertext` field of a Sapling Output Description. Total size is 116 bytes.

Used in: CompactTx

• bytes cmu = 1

  Note commitment u-coordinate.

• bytes ephemeralKey = 2

  Ephemeral public key.

• bytes ciphertext = 3

  First 52 bytes of ciphertext.

A compact representation of a [Sapling Spend](https://zips.z.cash/protocol/protocol.pdf#spendencodingandconsensus). CompactSaplingSpend is a Sapling Spend Description as described in 7.3 of the Zcash protocol specification.

Used in: CompactTx

• bytes nf = 1

  Nullifier (see the Zcash protocol specification)

A compact representation of the shielded data in a Zcash transaction. CompactTx contains the minimum information for a wallet to know if this transaction is relevant to it (either pays to it or spends from it) via shielded elements only. This message will not encode a transparent-to-transparent transaction.

Used as response type in: CompactTxStreamer.GetMempoolTx

Used as field type in: CompactBlock

• uint64 index = 1

  Index and hash will allow the receiver to call out to chain explorers or other data structures to retrieve more information about this transaction.

  the index within the full block

• bytes hash = 2

  the ID (hash) of this transaction, same as in block explorers

• uint32 fee = 3

  The transaction fee: present if server can provide. In the case of a stateless server and a transaction with transparent inputs, this will be unset because the calculation requires reference to prior transactions. If there are no transparent inputs, the fee will be calculable as: valueBalanceSapling + valueBalanceOrchard + sum(vPubNew) - sum(vPubOld) - sum(tOut)

• repeated CompactSaplingSpend spends = 4

• repeated CompactSaplingOutput outputs = 5

• repeated CompactOrchardAction actions = 6

Empty is for gRPCs that take no arguments, currently only GetLightdInfo.

Used as request type in: CompactTxStreamer.GetLatestTreeState, CompactTxStreamer.GetLightdInfo, CompactTxStreamer.GetMempoolStream

(message has no fields)

Results are sorted by height, which makes it easy to issue another request that picks up from where the previous left off.

Used as request type in: CompactTxStreamer.GetAddressUtxos, CompactTxStreamer.GetAddressUtxosStream

• repeated string addresses = 1

• uint64 startHeight = 2

• uint32 maxEntries = 3

  zero means unlimited

Used as response type in: CompactTxStreamer.GetAddressUtxosStream

Used as field type in: GetAddressUtxosReplyList

• string address = 6

• bytes txid = 1

• int32 index = 2

• bytes script = 3

• int64 valueZat = 4

• uint64 height = 5

RawTransaction contains the complete transaction data. It also optionally includes the block height in which the transaction was included, or, when returned by GetMempoolStream(), the latest block height. FIXME: the documentation here about mempool status contradicts the documentation for the `height` field. See https://github.com/zcash/librustzcash/issues/1484

Used as request type in: CompactTxStreamer.SendTransaction

Used as response type in: CompactTxStreamer.GetMempoolStream, CompactTxStreamer.GetTaddressTxids, CompactTxStreamer.GetTransaction

• bytes data = 1

  exact data returned by Zcash 'getrawtransaction'

• uint64 height = 2

  height that the transaction was mined (or -1)

Used in: GetSubtreeRootsArg

• sapling = 0

• orchard = 1

The TreeState is derived from the Zcash z_gettreestate rpc.

Used as response type in: CompactTxStreamer.GetLatestTreeState, CompactTxStreamer.GetTreeState

• string network = 1

  "main" or "test"

• uint64 height = 2

  block height

• string hash = 3

  block id

• uint32 time = 4

  Unix epoch time when the block was mined

• string saplingTree = 5

  sapling commitment tree state

• string orchardTree = 6

  orchard commitment tree state