From cd331cc30ef0536eed176d809afccecb28f9fc23 Mon Sep 17 00:00:00 2001
From: Thomas Dinsdale-Young <ty@concordium.com>
Date: Fri, 15 Dec 2023 17:51:45 +0100
Subject: [PATCH] Endpoint for querying light blocks.

---
 v2/concordium/service.proto |  5 ++++
 v2/concordium/types.proto   | 50 +++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/v2/concordium/service.proto b/v2/concordium/service.proto
index ccb51d5..1df4abf 100644
--- a/v2/concordium/service.proto
+++ b/v2/concordium/service.proto
@@ -336,4 +336,9 @@ service Queries {
   //    a bug.
   //  * `UNIMPLEMENTED` if the endpoint is disabled on the node.
   rpc DryRun (stream DryRunRequest) returns (stream DryRunResponse);
+
+  // Get a sequence of finalization proofs and Merkle finalization committee proofs that will
+  // allow a light client to update its current last finalized block from a trusted start block
+  // to a specified target block.
+  rpc GetLightBlocks (LightBlocksRequest) returns (stream LightBlocksItem);
 }
diff --git a/v2/concordium/types.proto b/v2/concordium/types.proto
index c3eda14..07be10c 100644
--- a/v2/concordium/types.proto
+++ b/v2/concordium/types.proto
@@ -3540,3 +3540,53 @@ message DryRunSuccessResponse {
     }
 }
 
+// A request from a light client to catch up from a trusted block to a subsequent finalized
+// block.
+message LightBlocksRequest {
+    // The highest finalized block currently trusted by the light client.
+    BlockHashInput from = 1;
+    // The target finalized block to catch the light client up to.
+    // The request will fail if this is not descended from the 'from' block.
+    BlockHashInput to = 2;
+    // If true, indicates that the light client is not aware of the current epoch finalization
+    // committee for it's highest finalized block.
+    bool current_committee_unknown = 3;
+    // If true, indicates that the light client is not aware of the next epoch finalization
+    // committee for it's highest finalized block.
+    bool next_committee_unknown = 4;
+    // If true, the response should include a proof of the next epoch finalization committee for
+    // the 'to' block.
+    bool next_committee_required = 5;
+}
+
+// Representation of a generic Merkle proof.
+// A Merkle proof can be canonically converted to a root hash by converting each of its
+// branches to bytes, concatenating them, and then taking the SHA256 hash of the result.
+message MerkleProof {
+    // The branches of the Merkle proof.
+    repeated MerkleBranch branches = 1;
+}
+
+// Branches of a Merkle proof.
+// A Merkle branch is either raw data bytes or a sub-Merkle proof.
+message MerkleBranch {
+    oneof branch {
+        // Raw data bytes. For this case, 'raw_data' is the representation of the branch
+        // as bytes.
+        bytes raw_data = 1;
+        // A sub-proof. For this case, the root hash of 'sub_proof' is the representation
+        // of the branch as bytes.
+        MerkleProof sub_proof = 2;
+    }
+}
+
+// An item produced in response to a `LightBlocksRequest`.
+message LightBlocksItem {
+    oneof item {
+        // A finalization entry proving that a block is finalized, and checkable knowing
+        // the finalization committee for the epoch of the block.
+        EpochFinalizationEntry finalization_entry = 1;
+        // A Merkle proof of what the next or current epoch finalization committee is for a block.
+        MerkleProof committee_proof = 2;
+    }
+}
\ No newline at end of file