Merge pull request #847 from zancas/match_lrz_main_protos

Match lrz main protos

zingo-testutils/proto/compact_formats.proto

@@ -1,66 +1,84 @@
-// Copyright (c) 2019-2020 The Zcash developers
+// Copyright (c) 2019-2021 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 go_package = "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.
 
+// Information about the state of the chain as of a given block.
+message ChainMetadata {
+    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 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
+    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
+    ChainMetadata chainMetadata = 8; // information about the state of the chain as of this block
 }
 
+// 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.
 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;   // 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))
+    // If there are no transparent inputs, the fee will be calculable as:
+    //    valueBalanceSapling + valueBalanceOrchard + sum(vPubNew) - sum(vPubOld) - sum(tOut)
     uint32 fee = 3;
 
-    repeated CompactSaplingSpend spends = 4;   // inputs
-    repeated CompactSaplingOutput outputs = 5; // outputs
+    repeated CompactSaplingSpend spends = 4;
+    repeated CompactSaplingOutput outputs = 5;
     repeated CompactOrchardAction actions = 6;
 }
 
+// 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.
 message CompactSaplingSpend {
-    bytes nf = 1;   // nullifier (see the Zcash protocol specification)
+    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.
+// 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.
 message CompactSaplingOutput {
-    bytes cmu = 1;          // note commitment u-coordinate
-    bytes epk = 2;          // ephemeral public key
-    bytes ciphertext = 3;   // first 52 bytes of ciphertext
+    bytes cmu = 1;          // Note commitment u-coordinate.
+    bytes ephemeralKey = 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)
+// A compact representation of an [Orchard Action](https://zips.z.cash/protocol/protocol.pdf#actionencodingandconsensus).
 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
+    bytes ciphertext = 4;       // [52] The first 52 bytes of the encCiphertext field
 }

zingo-testutils/proto/service.proto

@@ -118,6 +118,22 @@ message TreeState {
     string orchardTree = 6; // orchard commitment tree state
 }
 
+enum ShieldedProtocol {
+    sapling = 0;
+    orchard = 1;
+}
+
+message GetSubtreeRootsArg {
+    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 {
+    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.
+}
+
 // Results are sorted by height, which makes it easy to issue another
 // request that picks up from where the previous left off.
 message GetAddressUtxosArg {
@@ -142,17 +158,20 @@ service CompactTxStreamer {
     rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
     // Return the compact block corresponding to the given block identifier
     rpc GetBlock(BlockID) returns (CompactBlock) {}
+    // Same as GetBlock except actions contain only nullifiers
+    rpc GetBlockNullifiers(BlockID) returns (CompactBlock) {}
     // Return a list of consecutive compact blocks
     rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
-
+    // Same as GetBlockRange except actions contain only nullifiers
+    rpc GetBlockRangeNullifiers(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) {}
 
@@ -176,6 +195,11 @@ service CompactTxStreamer {
     // 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) {}
+
+    // Returns a stream of information about roots of subtrees of the Sapling and Orchard
+    // note commitment trees.
+    rpc GetSubtreeRoots(GetSubtreeRootsArg) returns (stream SubtreeRoot) {}
 
     rpc GetAddressUtxos(GetAddressUtxosArg) returns (GetAddressUtxosReplyList) {}
     rpc GetAddressUtxosStream(GetAddressUtxosArg) returns (stream GetAddressUtxosReply) {}