FlyClient support for light clients

packages/zaino-proto/lightwallet-protocol/walletrpc/service.proto

@@ -17,7 +17,9 @@ enum PoolType {
 }
 
 // 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.
+// hash. Support for specification by hash is not mandatory. (If `hash` is
+// non-empty, the rpc may return an error.) This field is present to support
+// a possible future upgrade.
 message BlockID {
     uint64 height = 1;
     bytes hash = 2;
@@ -28,7 +30,7 @@ message BlockID {
 //
 // If no pool types are specified, the server should default to the legacy
 // behavior of returning only data relevant to the shielded (Sapling and
-// Orchard) pools; otherwise, the server should prune `CompactBlocks` returned
+// Orchard) pools; otherwise, the server should prune `CompactBlock`s returned
 // to include only data relevant to the requested pool types. Clients MUST 
 // verify that the version of the server they are connected to are capable
 // of returning pruned and/or transparent data before setting `poolTypes`
@@ -216,19 +218,70 @@ message GetAddressUtxosReplyList {
     repeated GetAddressUtxosReply addressUtxos = 1;
 }
 
+// A node in the MMR tree, identified by its position in the
+// flat array representation of the tree (see ZIP-221).
+message MMRNode {
+    // Position in the MMR flat array representation
+    uint32 position = 1;
+    // Serialized zcash_history::Entry bytes for this node
+    bytes data = 2;
+}
+
+// An MMR inclusion proof for a block in the chain history tree (ZIP-221).
+//
+// Contains the MMR root and auth data root for a specific chain tip,
+// plus the Merkle path proving the requested block is in the committed chain.
+// The client can verify:
+//   hashBlockCommitments = BLAKE2b-256("ZcashBlockCommit" || mmr_root || auth_data_root || [0u8;32])
+// against the block header at `tip_height` (obtainable via GetBlock) to
+// authenticate the MMR root, then verify the inclusion proof against it.
+//
+// Future optimization: a range variant could batch multiple proofs sharing
+// common MMR subtree nodes.
+message BlockInclusionProof {
+    // hashLightClientRoot: the MMR root committed in the block at tip_height (32 bytes).
+    bytes mmr_root = 1;
+    // hashAuthDataRoot: the transaction auth data commitment from ZIP-244
+    // for the block at tip_height (32 bytes).
+    bytes auth_data_root = 2;
+    // The MMR leaf entry for the requested block.
+    MMRNode leaf = 3;
+    // Sibling nodes along the path from leaf to root (bottom-up order).
+    repeated MMRNode siblings = 4;
+    // Height of the block whose header commits to mmr_root and auth_data_root.
+    // The client should fetch this block's header (via GetBlock) and verify
+    // hashBlockCommitments against the returned mmr_root and auth_data_root.
+    uint32 tip_height = 5;
+}
+
 service CompactTxStreamer {
     // Return the BlockID of the block at the tip of the best chain
     rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
 
-    // Return the compact block corresponding to the given block identifier
+    // Return the compact block corresponding to the given block identifier.
+    //
+    // The returned `CompactBlock` includes transaction data for all value
+    // pools, including transparent inputs (`vin`) and outputs (`vout`). This
+    // differs from `GetBlockRange`, which supports filtering by pool type and
+    // defaults to returning only shielded (Sapling and Orchard) data. Clients
+    // that require only data for specific pools should use `GetBlockRange`
+    // with the appropriate `poolTypes` set.
+    //
+    // Note: the single null-outpoint input for coinbase transactions is
+    // omitted from the `vin` field of the corresponding `CompactTx`. See the
+    // documentation of the `CompactTx` message for details.
     rpc GetBlock(BlockID) returns (CompactBlock) {}
 
-    // Same as GetBlock except the returned CompactBlock value contains only
-    // nullifiers.
+    // Return a compact block containing only nullifier information for the
+    // shielded pools (Sapling spend nullifiers and Orchard action nullifiers).
+    // Transparent transaction data, Sapling outputs, full Orchard action data,
+    // and commitment tree sizes are not included.
     //
-    // Note: this method is deprecated. Implementations should ignore any
-    // `PoolType::TRANSPARENT` member of the `poolTypes` argument.
-    rpc GetBlockNullifiers(BlockID) returns (CompactBlock) {}
+    // Note: this method is deprecated; use `GetBlockRange` with the
+    // appropriate `poolTypes` instead.
+    rpc GetBlockNullifiers(BlockID) returns (CompactBlock) {
+      option deprecated = true;
+    }
 
     // Return a list of consecutive compact blocks in the specified range,
     // which is inclusive of `range.end`.
@@ -237,12 +290,18 @@ service CompactTxStreamer {
     // otherwise blocks are returned in decreasing height order.
     rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
 
-    // Same as GetBlockRange except the returned CompactBlock values contain
-    // only nullifiers.
+    // Return a stream of compact blocks for the specified range, where each
+    // block contains only nullifier information for the shielded pools
+    // (Sapling spend nullifiers and Orchard action nullifiers). Transparent
+    // transaction data, Sapling outputs, full Orchard action data, and
+    // commitment tree sizes are not included. Implementations MUST ignore any
+    // `PoolType::TRANSPARENT` member of the `poolTypes` field of the request.
     //
-    // Note: this method is deprecated. Implementations should ignore any
-    // `PoolType::TRANSPARENT` member of the `poolTypes` argument.
-    rpc GetBlockRangeNullifiers(BlockRange) returns (stream CompactBlock) {}
+    // Note: this method is deprecated; use `GetBlockRange` with the
+    // appropriate `poolTypes` instead.
+    rpc GetBlockRangeNullifiers(BlockRange) returns (stream CompactBlock) {
+      option deprecated = true;
+    }
 
     // Return the requested full (not compact) transaction (as from zcashd)
     rpc GetTransaction(TxFilter) returns (RawTransaction) {}
@@ -300,4 +359,18 @@ service CompactTxStreamer {
 
     // Testing-only, requires lightwalletd --ping-very-insecure (do not enable in production)
     rpc Ping(Duration) returns (PingResponse) {}
+
+    // Get an MMR inclusion proof for a specific block (ZIP-221).
+    //
+    // Returns the MMR root, auth data root, and a Merkle path proving
+    // the block is included in the current chain tip's committed history.
+    // The client should:
+    //   1. Get the tip block header via GetBlock.
+    //   2. Call this RPC to get the MMR root and inclusion proof.
+    //   3. Verify hashBlockCommitments in the header against mmr_root + auth_data_root.
+    //   4. Verify the Merkle path against the MMR root.
+    //
+    // For FlyClient verification, the client selects blocks to challenge
+    // using the sampling distribution from https://eprint.iacr.org/2019/226.
+    rpc GetBlockInclusionProof(BlockID) returns (BlockInclusionProof) {}
 }