Protocol Documentation

Reset reverts all darksidewalletd state (active block range, latest height, staged blocks and transactions) and lightwalletd state (cache) to empty, the same as the initial state. This occurs synchronously and instantaneously; no reorg happens in lightwalletd. This is good to do before each independent test so that no state leaks from one test to another. Also sets (some of) the values returned by GetLightdInfo(). The Sapling activation height specified here must be where the block range starts.

StageBlocksStream accepts a list of blocks and saves them into the blocks staging area until ApplyStaged() is called; there is no immediate effect on the mock zcashd. Blocks are hex-encoded. Order is important, see ApplyStaged.

StageBlocks is the same as StageBlocksStream() except the blocks are fetched from the given URL. Blocks are one per line, hex-encoded (not JSON).

StageBlocksCreate is like the previous two, except it creates 'count' empty blocks at consecutive heights starting at height 'height'. The 'nonce' is part of the header, so it contributes to the block hash; this lets you create identical blocks (same transactions and height), but with different hashes.

StageTransactionsStream stores the given transaction-height pairs in the staging area until ApplyStaged() is called. Note that these transactions are not returned by the production GetTransaction() gRPC until they appear in a "mined" block (contained in the active blockchain presented by the mock zcashd).

StageTransactions is the same except the transactions are fetched from the given url. They are all staged into the block at the given height. Staging transactions to different heights requires multiple calls.

ApplyStaged iterates the list of blocks that were staged by the StageBlocks*() gRPCs, in the order they were staged, and "merges" each into the active, working blocks list that the mock zcashd is presenting to lightwalletd. Even as each block is applied, the active list can't have gaps; if the active block range is 1000-1006, and the staged block range is 1003-1004, the resulting range is 1000-1004, with 1000-1002 unchanged, blocks 1003-1004 from the new range, and 1005-1006 dropped. After merging all blocks, ApplyStaged() appends staged transactions (in the order received) into each one's corresponding (by height) block The staging area is then cleared. The argument specifies the latest block height that mock zcashd reports (i.e. what's returned by GetLatestBlock). Note that ApplyStaged() can also be used to simply advance the latest block height presented by mock zcashd. That is, there doesn't need to be anything in the staging area.

Calls to the production gRPC SendTransaction() store the transaction in a separate area (not the staging area); this method returns all transactions in this separate area, which is then cleared. The height returned with each transaction is -1 (invalid) since these transactions haven't been mined yet. The intention is that the transactions returned here can then, for example, be given to StageTransactions() to get them "mined" into a specified block on the next ApplyStaged().

Clear the incoming transaction pool.

Add a GetAddressUtxosReply entry to be returned by GetAddressUtxos(). There is no staging or applying for these, very simple.

Clear the list of GetAddressUtxos entries (can't fail)

Adds a GetTreeState to the tree state cache

Removes a GetTreeState for the given height from cache if present (can't fail)

Clear the list of GetTreeStates entries (can't fail)

Sets the subtree roots cache (for GetSubtreeRoots), replacing any existing entries

Stop causes the server to shut down cleanly.

Return the height of the tip of the best chain

Return the compact block corresponding to the given block identifier

Same as GetBlock except actions contain only nullifiers

Return a list of consecutive compact blocks

Same as GetBlockRange except actions contain only nullifiers

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

Submit the given transaction to the Zcash network

Return the transactions corresponding to the given t-address within the given block range NB - this method is misnamed, it returns transactions, not transaction IDs.

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.

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.

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.

Returns a stream of information about roots of subtrees of the note commitment tree for the specified shielded protocol (Sapling or Orchard).

Return information about this lightwalletd instance and the blockchain

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