Generated java gRPC protocol buffers for Pirate Chain network comms.

The command used was:

./protoc --plugin=protoc-gen-grpc-java=/Users/user/Downloads/protoc-gen-grpc-java-1.45.1-osx-x86_64.exe -I=src/main/resources/proto/zcash/ --java_out=src/main/java/ --grpc-java_out=src/main/java/ src/main/resources/proto/zcash/service.proto

Then repeat, replacing service.proto with compact_formats.proto and darkside.proto

Darkside isn't needed for mainnet functionality, but included for completeness, and might be useful for testing.

pom.xml

@@ -34,6 +34,8 @@
 		<package-info-maven-plugin.version>1.1.0</package-info-maven-plugin.version>
 		<jsoup.version>1.13.1</jsoup.version>
 		<java-diff-utils.version>4.10</java-diff-utils.version>
+		<grpc.version>1.45.1</grpc.version>
+		<protobuf.version>3.19.4</protobuf.version>
 	</properties>
 	<build>
 		<sourceDirectory>src/main/java</sourceDirectory>
@@ -705,5 +707,25 @@
 			<artifactId>java-diff-utils</artifactId>
 			<version>${java-diff-utils.version}</version>
 		</dependency>
+		<dependency>
+			<groupId>io.grpc</groupId>
+			<artifactId>grpc-netty</artifactId>
+			<version>${grpc.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>io.grpc</groupId>
+			<artifactId>grpc-protobuf</artifactId>
+			<version>${grpc.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>io.grpc</groupId>
+			<artifactId>grpc-stub</artifactId>
+			<version>${grpc.version}</version>
+		</dependency>
+		<dependency>
+			<groupId>com.google.protobuf</groupId>
+			<artifactId>protobuf-java</artifactId>
+			<version>${protobuf.version}</version>
+		</dependency>
 	</dependencies>
 </project>

src/main/resources/proto/zcash/compact_formats.proto

@@ -0,0 +1,57 @@
+// Copyright (c) 2019-2020 The Zcash developers
+// Copyright (c) 2019-2021 Pirate Chain 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 = "";
+// Remember that proto3 fields are all optional. A field that is not present will be set to its zero value.
+// bytes fields of hashes are in canonical little-endian format.
+
+// CompactBlock is a packaging of ONLY the data from a block that's needed to:
+//   1. Detect a payment to your shielded Sapling address
+//   2. Detect a spend of your shielded Sapling notes
+//   3. Update your witnesses to generate new Sapling spend proofs.
+message CompactBlock {
+    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
+}
+
+// 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.
+message CompactTx {
+    uint64 index = 1;   // the index within the full block
+    bytes hash = 2;     // the ID (hash) of this transaction, same as in block explorers
+
+    // 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.
+    // in a pure-Sapling context, the fee will be calculable as:
+    //    valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut))
+    uint32 fee = 3;
+
+    repeated CompactSpend spends = 4;   // inputs
+    repeated CompactOutput outputs = 5; // outputs
+}
+
+// CompactSpend is a Sapling Spend Description as described in 7.3 of the Zcash
+// protocol specification.
+message CompactSpend {
+    bytes nf = 1;   // nullifier (see the Zcash protocol specification)
+}
+
+// output is a Sapling Output Description as described in section 7.4 of the
+// Zcash protocol spec. Total size is 948.
+message CompactOutput {
+    bytes cmu = 1;          // note commitment u-coordinate
+    bytes epk = 2;          // ephemeral public key
+    bytes ciphertext = 3;   // ciphertext and zkproof
+}

src/main/resources/proto/zcash/darkside.proto

@@ -0,0 +1,117 @@
+// 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) {}
+}

src/main/resources/proto/zcash/service.proto

@@ -0,0 +1,181 @@
+// Copyright (c) 2019-2020 The Zcash developers
+// Copyright (c) 2019-2021 Pirate Chain 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.
+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 pirated is syncing
+    string piratedBuild = 13;            // example: "v4.1.1-877212414"
+    string piratedSubversion = 14;       // example: "/MagicBean:4.1.1/"
+}
+
+// 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;
+}
+
+message Exclude {
+    repeated bytes txid = 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 pirated)
+    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 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.
+    rpc GetMempoolTx(Exclude) returns (stream CompactTx) {}
+
+    // 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 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) {}
+}