rpc: new protobufs for better separation of concerns + real use cases

proto/compact_formats.proto

@@ -1,36 +1,20 @@
 syntax = "proto3";
 package proto;
 
-// Remember that proto3 fields are all optional.
-
-// A BlockFilter message contains identifiers to select a block: either a
-// height or a hash.
-message BlockFilter {
-     uint64 blockHeight = 1;
-     bytes blockHash = 2;
-}
-
-message RangeFilter {
-    BlockFilter start = 1;
-    BlockFilter end = 2;
-}
-
-// A TxFilter contains the information needed to identify a particular
-// transaction: either a block and an index, or a direct transaction hash.
-message TxFilter {
-     BlockFilter blockID = 1;
-     uint64 txIndex = 2;
-     bytes txHash = 3;
-}
-
+// 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 {
-    BlockFilter blockID = 1;
-    repeated CompactTx vtx = 3;
+    uint32 protoVersion = 1; // the version of this wire format, for storage
+    uint64 height = 2; // the height of this block
+    bytes hash = 3; // the hash of this block
+    uint32 time = 4; // the block time
+    bytes header = 5; // OR send the full header
+    repeated CompactTx vtx = 6; // compact transactions from this block
 }
 
 message CompactTx {
@@ -40,8 +24,15 @@ message CompactTx {
     uint64 index = 1;
     bytes hash = 2;
 
-    repeated CompactSpend spends = 3;
-    repeated CompactOutput outputs = 4;
+    // 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;
+    repeated CompactOutput outputs = 5;
 }
 
 message CompactSpend {
@@ -53,21 +44,3 @@ message CompactOutput {
     bytes epk = 2;
     bytes ciphertext = 3;
 }
-
-// An opaque blob of full transaction data, for fetching anything that is not
-// in the compact format (e.g. the memo field).
-message FullTransaction {
-    TxFilter txID = 1;
-    bytes data = 2;
-}
-
-// Empty placeholder.
-// Someday we may want to specify e.g. a particular chain fork.
-message ChainSpec {}
-
-service CompactTxStreamer {
-    rpc GetLatestBlock(ChainSpec) returns (BlockFilter) {}
-    rpc GetBlock(BlockFilter) returns (CompactBlock) {}
-    rpc GetBlockRange(RangeFilter) returns (stream CompactBlock) {}
-    rpc GetTransaction(TxFilter) returns (FullTransaction) {}
-}

proto/service.proto

@@ -0,0 +1,50 @@
+syntax = "proto3";
+package proto;
+
+// A BlockID message contains identifiers to select a block: a height or a
+// hash. If the hash is present it takes precedence.
+message BlockID {
+     uint64 height = 1;
+     bytes hash = 2;
+}
+
+// BlockRange technically allows ranging from hash to hash etc but this is not
+// currently intended for support, though there is no reason you couldn't do
+// it. Further permutations are left as an exercise.
+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.
+message TxFilter {
+     BlockID block = 1;
+     uint64 index = 2;
+     bytes hash = 3;
+}
+
+message FullTransaction {
+    TxFilter txID = 1;
+    bytes data = 2;
+}
+
+message SentTransaction {
+    bytes data = 1;
+}
+
+message SendResponse {
+    int32 errorCode = 1;
+    string errorMessage = 2;
+}
+
+// Empty placeholder. Someday we may want to specify e.g. a particular chain fork.
+message ChainSpec {}
+
+service CompactTxStreamer {
+    rpc GetLatestBlock(ChainSpec) returns (BlockID) {}
+    rpc GetBlock(BlockID) returns (CompactBlock) {}
+    rpc GetBlockRange(BlockRange) returns (stream CompactBlock) {}
+    rpc GetTransaction(TxFilter) returns (FullTransaction) {}
+    rpc SendTransaction(RawTransaction) returns (SendResponse) {}
+}