[Access] Implement gRPC streaming endpoint SubscribeAccountStatuses

protobuf/flow/executiondata/executiondata.proto

@@ -48,7 +48,7 @@ service ExecutionDataAPI {
   // all events are returned.
   //
   // Responses are returned for each block containing at least one event that
-  // matches the filter. Additionally, heatbeat responses
+  // matches the filter. Additionally, heartbeat responses
   // (SubscribeEventsResponse with no events) are returned periodically to allow
   // clients to track which blocks were searched. Clients can use this
   // information to determine which block to start from when reconnecting.
@@ -66,6 +66,30 @@ service ExecutionDataAPI {
   // GetRegisterValues gets the values for the given register IDs as of the given block height
   rpc GetRegisterValues(GetRegisterValuesRequest)
       returns (GetRegisterValuesResponse);
+
+  // SubscribeAccountStatuses streams account statuses for all blocks starting at the requested
+  // start block, up until the latest available block. Once the latest is
+  // reached, the stream will remain open and responses are sent for each new
+  // block as it becomes available.
+  //
+  // Events within each block are filtered by the provided StatusFilter, and only
+  // those events that match the filter are returned. If no filter is provided,
+  // all events are returned.
+  //
+  // Responses are returned for each block containing at least one event that
+  // matches the filter. Additionally, heartbeat responses
+  // (SubscribeAccountStatusesResponse with no events) are returned periodically to allow
+  // clients to track which blocks were searched. Clients can use this
+  // information to determine which block to start from when reconnecting.
+  //
+  // Errors:
+  // - InvalidArgument is returned if the request contains an invalid
+  // StatusFilter or start block.
+  // - NotFound is returned if the start block is not currently available on the
+  // node. This may happen if the block was from a previous spork, or if the block has yet
+  //   not been received.
+  rpc SubscribeAccountStatuses(SubscribeAccountStatusesRequest)
+      returns (stream SubscribeAccountStatusesResponse);
 }
 
 // The request for GetExecutionDataByBlockID
@@ -230,4 +254,78 @@ message GetRegisterValuesResponse {
 
   // raw register values at the given height.
   repeated bytes values = 1;
-}
+}
+
+// The request for SubscribeAccountStatuses
+message SubscribeAccountStatusesRequest {
+  // Block ID of the first block to search for events.
+  // Only one of start_block_id and start_block_height may be provided,
+  // otherwise an InvalidArgument error is returned. If neither are provided,
+  // the latest sealed block is used.
+  bytes start_block_id = 1;
+
+  // Block height of the first block to search for events.
+  // Only one of start_block_id and start_block_height may be provided,
+  // otherwise an InvalidArgument error is returned. If neither are provided,
+  // the latest sealed block is used.
+  uint64 start_block_height = 2;
+
+  // Unique identifier for the account being streamed
+  bytes address = 3;
+
+  // Filter to apply to events for each block searched.
+  // If no filter is provided, all statuses are returned.
+  StatusFilter filter = 4;
+
+  // Interval in block heights at which the server should return a heartbeat
+  // message to the client. The heartbeat is a normal SubscribeAccountStatusesResponse
+  // with no events, and allows clients to track which blocks were searched.
+  // Clients can use this information to determine which block to start from
+  // when reconnecting.
+  //
+  // The interval is calculated from the last response returned, which could be
+  // either another heartbeat or a response containing events.
+  uint64 heartbeat_interval = 5;
+
+  // Preferred event encoding version of the block events payload.
+  // Possible variants:
+  // 1. CCF
+  // 2. JSON-CDC
+  entities.EventEncodingVersion event_encoding_version = 6;
+}
+
+// The response for SubscribeAccountStatuses
+message SubscribeAccountStatusesResponse {
+  // Block ID of the block containing the events.
+  bytes block_id = 1;
+
+  // Unique identifier for the account being streamed
+  bytes address = 2;
+
+  // Events matching the StatusFilter in the request.
+  // The API may return no events which signals a periodic heartbeat. This
+  // allows clients to track which blocks were searched. Client can use this
+  // information to determine which block to start from when reconnecting.
+  repeated entities.Event events = 3;
+
+  // The MessageIndex of the response message.
+  // Used by the client to ensure they received all messages.
+  uint64 messageIndex = 4;
+}
+
+// StatusesFilter defines the filter to apply to block events.
+// Filters are applied as an OR operation, i.e. any event matching any of the
+// filters is returned. If no filters are provided, all events are returned. If
+// there are any invalid filters, the API will return an InvalidArgument error.
+message StatusFilter {
+  // A list of full event types to include.
+  //
+  // All events exactly matching any of the provided event types will be
+  // returned.
+  //
+  // Event types have 2 formats:
+  // - Protocol events:
+  //     flow.[event name]
+  repeated string event_type = 1;
+}
+