docs: helpful comments on a few proto types

Adds a few explanatory comments to the protobuf message types: 1. Attempts to describe the expected shape of Address. 2. Explains the lo/hi denom representation of a uint128. 3. Explicitly mentions return type of `stream` where appropriate. Refs #2768. Closes #2734.
penumbra-zone · Jul 1, 2023 · 3b74fd4 · 3b74fd4
1 parent 109416e
commit 3b74fd4
Show file tree

Hide file tree

Showing 8 changed files with 79 additions and 16 deletions.
diff --git a/crates/proto/src/gen/penumbra.client.v1alpha1.rs b/crates/proto/src/gen/penumbra.client.v1alpha1.rs
@@ -850,6 +850,7 @@ pub mod oblivious_query_service_client {
             self.inner = self.inner.accept_compressed(encoding);
             self
         }
+        /// Returns a stream of `CompactBlockRangeResponse`s.
         pub async fn compact_block_range(
             &mut self,
             request: impl tonic::IntoRequest<super::CompactBlockRangeRequest>,
@@ -910,6 +911,7 @@ pub mod oblivious_query_service_client {
             );
             self.inner.unary(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `ValidatorInfoResponse`s.
         pub async fn validator_info(
             &mut self,
             request: impl tonic::IntoRequest<super::ValidatorInfoRequest>,
@@ -1183,6 +1185,7 @@ pub mod specific_query_service_client {
             );
             self.inner.unary(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `SwapExecutionsResponses`.
         pub async fn swap_executions(
             &mut self,
             request: impl tonic::IntoRequest<super::SwapExecutionsRequest>,
@@ -1205,6 +1208,7 @@ pub mod specific_query_service_client {
             );
             self.inner.server_streaming(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `ArbExecutionsResponses`.
         pub async fn arb_executions(
             &mut self,
             request: impl tonic::IntoRequest<super::ArbExecutionsRequest>,
@@ -1227,6 +1231,7 @@ pub mod specific_query_service_client {
             );
             self.inner.server_streaming(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `LiquidityPositionsResponse`s.
         pub async fn liquidity_positions(
             &mut self,
             request: impl tonic::IntoRequest<super::LiquidityPositionsRequest>,
@@ -1271,6 +1276,7 @@ pub mod specific_query_service_client {
             );
             self.inner.unary(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `LiquidityPositionsByIdResponse`s.
         pub async fn liquidity_positions_by_id(
             &mut self,
             request: impl tonic::IntoRequest<super::LiquidityPositionsByIdRequest>,
@@ -1295,6 +1301,7 @@ pub mod specific_query_service_client {
             );
             self.inner.server_streaming(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `LiquidityPositionsByPriceResponse`s.
         pub async fn liquidity_positions_by_price(
             &mut self,
             request: impl tonic::IntoRequest<super::LiquidityPositionsByPriceRequest>,
@@ -1441,6 +1448,7 @@ pub mod specific_query_service_client {
         }
         /// General-purpose prefixed key-value state query API, that can be used to query
         /// arbitrary prefixes in the JMT storage.
+        /// Returns a stream of `PrefixValueResponse`s.
         pub async fn prefix_value(
             &mut self,
             request: impl tonic::IntoRequest<super::PrefixValueRequest>,
@@ -1676,6 +1684,7 @@ pub mod oblivious_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `CompactBlockRangeResponse`s.
         async fn compact_block_range(
             &self,
             request: tonic::Request<super::CompactBlockRangeRequest>,
@@ -1694,6 +1703,7 @@ pub mod oblivious_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `ValidatorInfoResponse`s.
         async fn validator_info(
             &self,
             request: tonic::Request<super::ValidatorInfoRequest>,
@@ -2054,6 +2064,7 @@ pub mod specific_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `SwapExecutionsResponses`.
         async fn swap_executions(
             &self,
             request: tonic::Request<super::SwapExecutionsRequest>,
@@ -2064,6 +2075,7 @@ pub mod specific_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `ArbExecutionsResponses`.
         async fn arb_executions(
             &self,
             request: tonic::Request<super::ArbExecutionsRequest>,
@@ -2074,6 +2086,7 @@ pub mod specific_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `LiquidityPositionsResponse`s.
         async fn liquidity_positions(
             &self,
             request: tonic::Request<super::LiquidityPositionsRequest>,
@@ -2091,6 +2104,7 @@ pub mod specific_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `LiquidityPositionsByIdResponse`s.
         async fn liquidity_positions_by_id(
             &self,
             request: tonic::Request<super::LiquidityPositionsByIdRequest>,
@@ -2101,6 +2115,7 @@ pub mod specific_query_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `LiquidityPositionsByPriceResponse`s.
         async fn liquidity_positions_by_price(
             &self,
             request: tonic::Request<super::LiquidityPositionsByPriceRequest>,
@@ -2149,6 +2164,7 @@ pub mod specific_query_service_server {
             + 'static;
         /// General-purpose prefixed key-value state query API, that can be used to query
         /// arbitrary prefixes in the JMT storage.
+        /// Returns a stream of `PrefixValueResponse`s.
         async fn prefix_value(
             &self,
             request: tonic::Request<super::PrefixValueRequest>,

diff --git a/crates/proto/src/gen/penumbra.core.crypto.v1alpha1.rs b/crates/proto/src/gen/penumbra.core.crypto.v1alpha1.rs
@@ -10,11 +10,13 @@ pub struct Fee {
     #[prost(message, optional, tag = "2")]
     pub asset_id: ::core::option::Option<AssetId>,
 }
-/// A Penumbra address.
+/// A Penumbra address. An address in Penumbra is a Bech32m-encoded
+/// string, with the human-readable prefix (HRP) `penumbrav2t`.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Address {
-    /// The bytes of the address.
+    /// The bytes of the address. Must be represented as a series of
+    /// `uint8` (i.e. values 0 through 255), with a length of 80 elements.
     #[prost(bytes = "vec", tag = "1")]
     pub inner: ::prost::alloc::vec::Vec<u8>,
     /// Alternatively, a Bech32m-encoded string representation of the `inner`
@@ -135,6 +137,11 @@ pub struct AssetId {
     #[prost(string, tag = "3")]
     pub alt_base_denom: ::prost::alloc::string::String,
 }
+/// The quantity of a particular Asset. Represented as a 128-bit unsigned integer,
+/// split over two fields, `lo` and `hi`, representing the low- and high-order bytes
+/// of the 128-bit value, respectively. Clients must assemble these bits in their
+/// implementation into a `uint128` or comparable data structure, in order to model
+/// the Amount accurately.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Amount {

diff --git a/crates/proto/src/gen/penumbra.view.v1alpha1.rs b/crates/proto/src/gen/penumbra.view.v1alpha1.rs
@@ -733,6 +733,7 @@ pub mod view_protocol_service_client {
             self.inner.unary(request.into_request(), path, codec).await
         }
         /// Stream sync status updates until the view service has caught up with the core.chain.v1alpha1.
+        /// Returns a stream of `StatusStreamResponse`s.
         pub async fn status_stream(
             &mut self,
             request: impl tonic::IntoRequest<super::StatusStreamRequest>,
@@ -756,6 +757,7 @@ pub mod view_protocol_service_client {
             self.inner.server_streaming(request.into_request(), path, codec).await
         }
         /// Queries for notes that have been accepted by the core.chain.v1alpha1.
+        /// Returns a stream of `NotesResponse`s.
         pub async fn notes(
             &mut self,
             request: impl tonic::IntoRequest<super::NotesRequest>,
@@ -778,6 +780,7 @@ pub mod view_protocol_service_client {
             );
             self.inner.server_streaming(request.into_request(), path, codec).await
         }
+        /// Returns a stream of `NotesForVotingResponse`s.
         pub async fn notes_for_voting(
             &mut self,
             request: impl tonic::IntoRequest<super::NotesForVotingRequest>,
@@ -845,6 +848,7 @@ pub mod view_protocol_service_client {
             self.inner.unary(request.into_request(), path, codec).await
         }
         /// Queries for assets.
+        /// Returns a stream of `AssetsResponse`s.
         pub async fn assets(
             &mut self,
             request: impl tonic::IntoRequest<super::AssetsRequest>,
@@ -967,7 +971,8 @@ pub mod view_protocol_service_client {
             );
             self.inner.unary(request.into_request(), path, codec).await
         }
-        /// Query for balance of a given address
+        /// Query for balance of a given address.
+        /// Returns a stream of `BalanceByAddressResponses`.
         pub async fn balance_by_address(
             &mut self,
             request: impl tonic::IntoRequest<super::BalanceByAddressRequest>,
@@ -1074,6 +1079,7 @@ pub mod view_protocol_service_client {
             self.inner.unary(request.into_request(), path, codec).await
         }
         /// Query for the full transactions in the given range of blocks.
+        /// Returns a stream of `TransactionInfoResponse`s.
         pub async fn transaction_info(
             &mut self,
             request: impl tonic::IntoRequest<super::TransactionInfoRequest>,
@@ -1292,6 +1298,7 @@ pub mod view_protocol_service_server {
             + Send
             + 'static;
         /// Stream sync status updates until the view service has caught up with the core.chain.v1alpha1.
+        /// Returns a stream of `StatusStreamResponse`s.
         async fn status_stream(
             &self,
             request: tonic::Request<super::StatusStreamRequest>,
@@ -1303,6 +1310,7 @@ pub mod view_protocol_service_server {
             + Send
             + 'static;
         /// Queries for notes that have been accepted by the core.chain.v1alpha1.
+        /// Returns a stream of `NotesResponse`s.
         async fn notes(
             &self,
             request: tonic::Request<super::NotesRequest>,
@@ -1313,6 +1321,7 @@ pub mod view_protocol_service_server {
             >
             + Send
             + 'static;
+        /// Returns a stream of `NotesForVotingResponse`s.
         async fn notes_for_voting(
             &self,
             request: tonic::Request<super::NotesForVotingRequest>,
@@ -1338,6 +1347,7 @@ pub mod view_protocol_service_server {
             + Send
             + 'static;
         /// Queries for assets.
+        /// Returns a stream of `AssetsResponse`s.
         async fn assets(
             &self,
             request: tonic::Request<super::AssetsRequest>,
@@ -1373,7 +1383,8 @@ pub mod view_protocol_service_server {
             >
             + Send
             + 'static;
-        /// Query for balance of a given address
+        /// Query for balance of a given address.
+        /// Returns a stream of `BalanceByAddressResponses`.
         async fn balance_by_address(
             &self,
             request: tonic::Request<super::BalanceByAddressRequest>,
@@ -1408,6 +1419,7 @@ pub mod view_protocol_service_server {
             + Send
             + 'static;
         /// Query for the full transactions in the given range of blocks.
+        /// Returns a stream of `TransactionInfoResponse`s.
         async fn transaction_info(
             &self,
             request: tonic::Request<super::TransactionInfoRequest>,

diff --git a/crates/proto/src/gen/proto_descriptor.bin b/crates/proto/src/gen/proto_descriptor.bin
diff --git a/proto/go/gen/penumbra/core/crypto/v1alpha1/crypto.pb.go b/proto/go/gen/penumbra/core/crypto/v1alpha1/crypto.pb.go
diff --git a/proto/penumbra/penumbra/client/v1alpha1/client.proto b/proto/penumbra/penumbra/client/v1alpha1/client.proto
@@ -22,9 +22,11 @@ import "tendermint/types/validator.proto";
 // but requesting the asset denomination for a specific asset id is not, because
 // it reveals that the client has an interest in that asset specifically.
 service ObliviousQueryService {
+  // Returns a stream of `CompactBlockRangeResponse`s.
   rpc CompactBlockRange(CompactBlockRangeRequest) returns (stream CompactBlockRangeResponse);
   rpc ChainParameters(ChainParametersRequest) returns (ChainParametersResponse);
   rpc EpochByHeight(EpochByHeightRequest) returns (EpochByHeightResponse);
+  // Returns a stream of `ValidatorInfoResponse`s.
   rpc ValidatorInfo(ValidatorInfoRequest) returns (stream ValidatorInfoResponse);
   rpc Info(InfoRequest) returns (InfoResponse);
 }
@@ -118,12 +120,17 @@ service SpecificQueryService {
   rpc SwapExecution(SwapExecutionRequest) returns (SwapExecutionResponse);
   rpc ArbExecution(ArbExecutionRequest) returns (ArbExecutionResponse);
 
+  // Returns a stream of `SwapExecutionsResponses`.
   rpc SwapExecutions(SwapExecutionsRequest) returns (stream SwapExecutionsResponse);
+  // Returns a stream of `ArbExecutionsResponses`.
   rpc ArbExecutions(ArbExecutionsRequest) returns (stream ArbExecutionsResponse);
 
+  // Returns a stream of `LiquidityPositionsResponse`s.
   rpc LiquidityPositions(LiquidityPositionsRequest) returns (stream LiquidityPositionsResponse);
   rpc LiquidityPositionById(LiquidityPositionByIdRequest) returns (LiquidityPositionByIdResponse);
+  // Returns a stream of `LiquidityPositionsByIdResponse`s.
   rpc LiquidityPositionsById(LiquidityPositionsByIdRequest) returns (stream LiquidityPositionsByIdResponse);
+  // Returns a stream of `LiquidityPositionsByPriceResponse`s.
   rpc LiquidityPositionsByPrice(LiquidityPositionsByPriceRequest) returns (stream LiquidityPositionsByPriceResponse);
 
   rpc Spread(SpreadRequest) returns (SpreadResponse);
@@ -140,6 +147,7 @@ service SpecificQueryService {
 
   // General-purpose prefixed key-value state query API, that can be used to query
   // arbitrary prefixes in the JMT storage.
+  // Returns a stream of `PrefixValueResponse`s.
   rpc PrefixValue(PrefixValueRequest) returns (stream PrefixValueResponse);
 }
 

diff --git a/proto/penumbra/penumbra/core/crypto/v1alpha1/crypto.proto b/proto/penumbra/penumbra/core/crypto/v1alpha1/crypto.proto
@@ -11,14 +11,16 @@ message Fee {
     AssetId asset_id = 2;
 }
 
-// A Penumbra address.
+// A Penumbra address. An address in Penumbra is a Bech32m-encoded
+// string, with the human-readable prefix (HRP) `penumbrav2t`.
 message Address {
-    // The bytes of the address.
+    // The bytes of the address. Must be represented as a series of
+    // `uint8` (i.e. values 0 through 255), with a length of 80 elements.
     bytes inner = 1;
-    
+
     // Alternatively, a Bech32m-encoded string representation of the `inner`
     // bytes.
-    // 
+    //
     // NOTE: implementations are not required to support parsing this field.
     // Implementations should prefer to encode the bytes in all messages they
     // produce. Implementations must not accept messages with both `inner` and
@@ -78,10 +80,10 @@ message BalanceCommitment {
 message AssetId {
     // The bytes of the asset ID.
     bytes inner = 1;
-    
+
     // Alternatively, a Bech32m-encoded string representation of the `inner`
     // bytes.
-    // 
+    //
     // NOTE: implementations are not required to support parsing this field.
     // Implementations should prefer to encode the `inner` bytes in all messages they
     // produce. Implementations must not accept messages with both `inner` and
@@ -97,6 +99,11 @@ message AssetId {
     string alt_base_denom = 3;
 }
 
+// The quantity of a particular Asset. Represented as a 128-bit unsigned integer,
+// split over two fields, `lo` and `hi`, representing the low- and high-order bytes
+// of the 128-bit value, respectively. Clients must assemble these bits in their
+// implementation into a `uint128` or comparable data structure, in order to model
+// the Amount accurately.
 message Amount {
     uint64 lo = 1;
     uint64 hi = 2;