@chainvue/verus-sapling 0.0.0

package/proto/darkside.proto

@@ -0,0 +1,124 @@
+// Copyright (c) 2019-2020 The Zcash developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or https://www.opensource.org/licenses/mit-license.php .
+
+syntax = "proto3";
+package cash.z.wallet.sdk.rpc;
+option go_package = "lightwalletd/walletrpc";
+option swift_prefix = "";
+import "service.proto";
+
+message DarksideMetaState {
+    int32 saplingActivation = 1;
+    string branchID = 2;
+    string chainName = 3;
+}
+
+// A block is a hex-encoded string.
+message DarksideBlock {
+    string block = 1;
+}
+
+// DarksideBlocksURL is typically something like:
+// https://raw.githubusercontent.com/zcash-hackworks/darksidewalletd-test-data/master/basic-reorg/before-reorg.txt
+message DarksideBlocksURL {
+    string url = 1;
+}
+
+// DarksideTransactionsURL refers to an HTTP source that contains a list
+// of hex-encoded transactions, one per line, that are to be associated
+// with the given height (fake-mined into the block at that height)
+message DarksideTransactionsURL {
+    int32 height = 1;
+    string url = 2;
+}
+
+message DarksideHeight {
+    int32 height = 1;
+}
+
+message DarksideEmptyBlocks {
+    int32 height = 1;
+    int32 nonce = 2;
+    int32 count = 3;
+}
+
+// Darksidewalletd maintains two staging areas, blocks and transactions. The
+// Stage*() gRPCs add items to the staging area; ApplyStaged() "applies" everything
+// in the staging area to the working (operational) state that the mock zcashd
+// serves; transactions are placed into their corresponding blocks (by height).
+service DarksideStreamer {
+    // 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.
+    rpc Reset(DarksideMetaState) returns (Empty) {}
+
+    // 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.
+    rpc StageBlocksStream(stream DarksideBlock) returns (Empty) {}
+
+    // StageBlocks is the same as StageBlocksStream() except the blocks are fetched
+    // from the given URL. Blocks are one per line, hex-encoded (not JSON).
+    rpc StageBlocks(DarksideBlocksURL) returns (Empty) {}
+
+    // 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.
+    rpc StageBlocksCreate(DarksideEmptyBlocks) returns (Empty) {}
+
+    // 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).
+    rpc StageTransactionsStream(stream RawTransaction) returns (Empty) {}
+
+    // 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.
+    rpc StageTransactions(DarksideTransactionsURL) returns (Empty) {}
+
+    // 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.
+    rpc ApplyStaged(DarksideHeight) returns (Empty) {}
+
+    // 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().
+    rpc GetIncomingTransactions(Empty) returns (stream RawTransaction) {}
+
+    // Clear the incoming transaction pool.
+    rpc ClearIncomingTransactions(Empty) returns (Empty) {}
+
+    // Add a GetAddressUtxosReply entry to be returned by GetAddressUtxos().
+    // There is no staging or applying for these, very simple.
+    rpc AddAddressUtxo(GetAddressUtxosReply) returns (Empty) {}
+
+    // Clear the list of GetAddressUtxos entries (can't fail)
+    rpc ClearAddressUtxo(Empty) returns (Empty) {}
+}

package/proto/service.proto

@@ -0,0 +1,172 @@
+// Copyright (c) 2019-2020 The Zcash developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or https://www.opensource.org/licenses/mit-license.php .
+
+syntax = "proto3";
+package cash.z.wallet.sdk.rpc;
+option go_package = "lightwalletd/walletrpc";
+option swift_prefix = "";
+import "compact_formats.proto";
+
+// 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.
+message BlockID {
+     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.
+message BlockRange {
+    BlockID start = 1;
+    BlockID end = 2;
+}
+
+// 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.
+message TxFilter {
+     BlockID block = 1;     // block identifier, height or hash
+     uint64 index = 2;      // index within the block
+     bytes hash = 3;        // transaction ID (hash, txid)
+}
+
+// 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.
+message RawTransaction {
+    bytes data = 1;     // exact data returned by Zcash 'getrawtransaction'
+    uint64 height = 2;  // height that the transaction was mined (or -1)
+}
+
+// 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.
+message SendResponse {
+    int32 errorCode = 1;
+    string errorMessage = 2;
+}
+
+// Chainspec is a placeholder to allow specification of a particular chain fork.
+message ChainSpec {}
+
+// Empty is for gRPCs that take no arguments, currently only GetLightdInfo.
+message Empty {}
+
+// LightdInfo returns various information about this lightwalletd instance
+// and the state of the blockchain.
+message LightdInfo {
+    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 chainID = 15;
+}
+
+// TransparentAddressBlockFilter restricts the results to the given address
+// or block range.
+message TransparentAddressBlockFilter {
+    string address = 1;     // t-address
+    BlockRange range = 2;   // start, end heights
+}
+
+// Duration is currently used only for testing, so that the Ping rpc
+// can simulate a delay, to create many simultaneous connections. Units
+// are microseconds.
+message Duration {
+    int64 intervalUs = 1;
+}
+
+// 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.
+message PingResponse {
+    int64 entry = 1;
+    int64 exit = 2;
+}
+
+message Address {
+    string address = 1;
+}
+message AddressList {
+    repeated string addresses = 1;
+}
+message Balance {
+    int64 valueZat = 1;
+}
+
+// The TreeState is derived from the Zcash z_gettreestate rpc.
+message TreeState {
+    string network = 1; // "main" or "test"
+    uint64 height = 2;
+    string hash = 3;    // block id
+    uint32 time = 4;    // Unix epoch time when the block was mined
+    string tree = 5;    // sapling commitment tree state
+}
+
+// Results are sorted by height, which makes it easy to issue another
+// request that picks up from where the previous left off.
+message GetAddressUtxosArg {
+    repeated string addresses = 1;
+    uint64 startHeight = 2;
+    uint32 maxEntries = 3; // zero means unlimited
+}
+message GetAddressUtxosReply {
+    string address = 6;
+    bytes txid = 1;
+    int32 index = 2;
+    bytes script = 3;
+    int64 valueZat = 4;
+    uint64 height = 5;
+}
+message GetAddressUtxosReplyList {
+    repeated GetAddressUtxosReply addressUtxos = 1;
+}
+
+service CompactTxStreamer {
+    // Return the height of the tip of the best chain
+    rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
+    // Return the compact block corresponding to the given block identifier
+    rpc GetBlock(BlockID) returns (CompactBlock) {}
+    // Return a list of consecutive compact blocks
+    rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
+
+    // Return the requested full (not compact) transaction (as from zcashd)
+    rpc GetTransaction(TxFilter) returns (RawTransaction) {}
+    // Submit the given transaction to the Zcash network
+    rpc SendTransaction(RawTransaction) returns (SendResponse) {}
+
+    // Return the txids corresponding to the given t-address within the given block range
+    rpc GetTaddressTxids(TransparentAddressBlockFilter) returns (stream RawTransaction) {}
+    rpc GetTaddressBalance(AddressList) returns (Balance) {}
+    rpc GetTaddressBalanceStream(stream Address) returns (Balance) {}
+
+    // 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 GetMempoolStream(Empty) returns (stream RawTransaction) {}
+
+    // 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 GetTreeState(BlockID) returns (TreeState) {}
+    rpc GetLatestTreeState(Empty) returns (TreeState) {}
+
+    rpc GetAddressUtxos(GetAddressUtxosArg) returns (GetAddressUtxosReplyList) {}
+    rpc GetAddressUtxosStream(GetAddressUtxosArg) returns (stream GetAddressUtxosReply) {}
+
+    // Return information about this lightwalletd instance and the blockchain
+    rpc GetLightdInfo(Empty) returns (LightdInfo) {}
+    // Testing-only, requires lightwalletd --ping-very-insecure (do not enable in production)
+    rpc Ping(Duration) returns (PingResponse) {}
+}