Update proto files

- Plus related api changes adoption

lightwallet-client-lib/src/main/java/co/electriccoin/lightwallet/client/internal/BlockingLightWalletClientImpl.kt

@@ -126,7 +126,7 @@ internal class BlockingLightWalletClientImpl private constructor(
         }
 
         val result = requireChannel().createStub().getAddressUtxos(
-            Service.GetAddressUtxosArg.newBuilder().setAddress(tAddress)
+            Service.GetAddressUtxosArg.newBuilder().setAddresses(Constants.TRANSPARENT_ADDRESS_INDEX, tAddress)
                 .setStartHeight(startHeight.value).build()
         )
         return result.addressUtxosList.asSequence()

lightwallet-client-lib/src/main/java/co/electriccoin/lightwallet/client/internal/Constants.kt

@@ -3,4 +3,5 @@ package co.electriccoin.lightwallet.client.internal
 internal object Constants {
     const val LOG_TAG = "LightWalletClient" // NON-NLS
     const val ILLEGAL_ARGUMENT_EXCEPTION_MESSAGE = "Illegal argument provided - can't be empty:" // NON-NLS
+    const val TRANSPARENT_ADDRESS_INDEX = 0
 }

lightwallet-client-lib/src/main/java/co/electriccoin/lightwallet/client/internal/CoroutineLightWalletClientImpl.kt

@@ -130,7 +130,7 @@ internal class CoroutineLightWalletClientImpl private constructor(
             "${Constants.ILLEGAL_ARGUMENT_EXCEPTION_MESSAGE} address: $tAddress." // NON-NLS
         }
         return requireChannel().createStub().getAddressUtxosStream(
-            Service.GetAddressUtxosArg.newBuilder().setAddress(tAddress)
+            Service.GetAddressUtxosArg.newBuilder().setAddresses(Constants.TRANSPARENT_ADDRESS_INDEX, tAddress)
                 .setStartHeight(startHeight.value).build()
         )
     }

lightwallet-client-lib/src/main/java/co/electriccoin/lightwallet/client/internal/DarksideApi.kt

@@ -56,7 +56,7 @@ class DarksideApi private constructor(
 
     fun stageTransactions(url: String, targetHeight: BlockHeightUnsafe) = apply {
         createStub().stageTransactions(
-            DarksideTransactionsURL.newBuilder().setHeight(targetHeight.value).setUrl(url).build()
+            DarksideTransactionsURL.newBuilder().setHeight(targetHeight.value.toInt()).setUrl(url).build()
         )
     }
 
@@ -66,7 +66,7 @@ class DarksideApi private constructor(
         nonce: Int = Random.nextInt()
     ) = apply {
         createStub().stageBlocksCreate(
-            Darkside.DarksideEmptyBlocks.newBuilder().setHeight(startHeight.value).setCount(count)
+            Darkside.DarksideEmptyBlocks.newBuilder().setHeight(startHeight.value.toInt()).setCount(count)
                 .setNonce(nonce).build()
         )
     }
@@ -172,7 +172,7 @@ class DarksideApi private constructor(
 }
 
 private fun BlockHeightUnsafe.toHeight() =
-    Darkside.DarksideHeight.newBuilder().setHeight(this.value).build()
+    Darkside.DarksideHeight.newBuilder().setHeight(this.value.toInt()).build()
 
 fun DarksideApi.Companion.new(
     context: Context,

lightwallet-client-lib/src/main/proto/compact_formats.proto

@@ -1,7 +1,11 @@
-syntax = "proto3";
+// 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 java_package = "cash.z.wallet.sdk.internal.rpc";
-option go_package = "walletrpc";
+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.
@@ -11,21 +15,21 @@ option swift_prefix = "";
 //   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;
-    bytes prevHash = 4;
-    uint32 time = 5;
-    bytes header = 6; // (hash, prevHash, and time) OR (full header)
-    repeated CompactTx vtx = 7; // compact transactions from this block
+    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 {
-    // Index and hash will allow the receiver to call out to chain
-    // explorers or other data structures to retrieve more information
-    // about this transaction.
-    uint64 index = 1;
-    bytes hash = 2;
+    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
@@ -34,16 +38,30 @@ message CompactTx {
     //    valueBalance + (sum(vPubNew) - sum(vPubOld) - sum(tOut))
     uint32 fee = 3;
 
-    repeated CompactSpend spends = 4;
-    repeated CompactOutput outputs = 5;
+    repeated CompactSaplingSpend spends = 4;   // inputs
+    repeated CompactSaplingOutput outputs = 5; // outputs
+    repeated CompactOrchardAction actions = 6;
 }
 
-message CompactSpend {
-    bytes nf = 1;
+// CompactSaplingSpend is a Sapling Spend Description as described in 7.3 of the Zcash
+// protocol specification.
+message CompactSaplingSpend {
+    bytes nf = 1;   // nullifier (see the Zcash protocol specification)
 }
 
-message CompactOutput {
-    bytes cmu = 1;
-    bytes epk = 2;
-    bytes ciphertext = 3;
+// output is a Sapling Output Description as described in section 7.4 of the
+// Zcash protocol spec. Total size is 948.
+message CompactSaplingOutput {
+    bytes cmu = 1;          // note commitment u-coordinate
+    bytes epk = 2;          // ephemeral public key
+    bytes ciphertext = 3;   // first 52 bytes of ciphertext
+}
+
+// https://github.com/zcash/zips/blob/main/zip-0225.rst#orchard-action-description-orchardaction
+// (but not all fields are needed)
+message CompactOrchardAction {
+    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 note plaintext component of the encCiphertext field
 }

lightwallet-client-lib/src/main/proto/darkside.proto

@@ -5,7 +5,7 @@
 syntax = "proto3";
 package cash.z.wallet.sdk.rpc;
 option java_package = "cash.z.wallet.sdk.internal.rpc";
-option go_package = ".;walletrpc";
+option go_package = "lightwalletd/walletrpc";
 option swift_prefix = "";
 import "service.proto";
 
@@ -30,16 +30,16 @@ message DarksideBlocksURL {
 // 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 {
-    int64 height = 1;
+    int32 height = 1;
     string url = 2;
 }
 
 message DarksideHeight {
-    int64 height = 1;
+    int32 height = 1;
 }
 
 message DarksideEmptyBlocks {
-    int64 height = 1;
+    int32 height = 1;
     int32 nonce = 2;
     int32 count = 3;
 }
@@ -115,4 +115,20 @@ service DarksideStreamer {
 
     // 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) {}
+
+    // Adds a GetTreeState to the tree state cache
+    rpc AddTreeState(TreeState) returns (Empty) {}
+
+    // Removes a GetTreeState for the given height from cache if present (can't fail)
+    rpc RemoveTreeState(BlockID) returns (Empty) {}
+
+    // Clear the list of GetTreeStates entries (can't fail)
+    rpc ClearAllTreeStates(Empty) returns (Empty) {}
 }

lightwallet-client-lib/src/main/proto/service.proto

@@ -5,7 +5,7 @@
 syntax = "proto3";
 package cash.z.wallet.sdk.rpc;
 option java_package = "cash.z.wallet.sdk.internal.rpc";
-option go_package = ".;walletrpc";
+option go_package = "lightwalletd/walletrpc";
 option swift_prefix = "";
 import "compact_formats.proto";
 
@@ -33,7 +33,8 @@ message TxFilter {
 }
 
 // RawTransaction contains the complete transaction data. It also optionally includes
-// the block height in which the transaction was included.
+// 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)
@@ -110,19 +111,23 @@ message Exclude {
 
 // 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
+    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
 }
 
+// Results are sorted by height, which makes it easy to issue another
+// request that picks up from where the previous left off.
 message GetAddressUtxosArg {
-    string address = 1;
+    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;
@@ -162,17 +167,22 @@ service CompactTxStreamer {
     // in the exclude list that don't exist in the mempool are ignored.
     rpc GetMempoolTx(Exclude) returns (stream CompactTx) {}
 
+    // 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
+    // Testing-only, requires lightwalletd --ping-very-insecure (do not enable in production)
     rpc Ping(Duration) returns (PingResponse) {}
 }