Add API response codes

Signed-off-by: Nana Essilfie-Conduah <nana@swirldslabs.com>

Author: Nana-EC

HIP/hip-1081.md

@@ -69,16 +69,6 @@ over HTTP. In the future it may be valuable to explore and add additional protoc
 graphQL) based on community needs.
 
 
-<aside>
-🚨 **Open Task:** Flesh out design decisions approach
-</aside>
-
-<aside>
-🚨 **Open Task:** Add diagram showing BN system location in overall Hedera architecture
-Highlight CN(s) -> BN -> MN + block stream clients
-</aside>
-
-
 ### Upgradeability
 
 It is a goal of a block node to be easy to run by users across different, languages, platform and cloud hosting
@@ -332,14 +322,13 @@ sequenceDiagram
 
 Additional response codes and their details are noted below
 
-| Response code         | Description   |
-| --------------------- | ------------- |
-| STREAM_END_UNKNOWN    | This status indicates the server software failed to set a status, and SHALL be considered
-a software defect. |
-
-<aside>
-🚨 **Open Task:** Add all known response codes
-</aside>
+| Response code             | Description   |
+| ------------------------- | ------------- |
+| STREAM_END_UNKNOWN        | The server software failed to set a status, and SHALL be considered a software defect. |
+| STREAM_END_RESET          | The Publisher reached a reset point. |
+| STREAM_END_TIMEOUT        | The delay between items was too long. |
+| STREAM_END_ERROR          | The publisher encountered an error. |
+| STREAM_END_TOO_FAR_BEHIND | The block node is too far behind to catch up directly. |
 
 > When the producer is a consensus node it is important to expose error cases that suggest a blocks node is falling
 behind or failing to store blocks when expected.
@@ -386,14 +375,15 @@ An overview of communication between a Block Node and a subscriber is as follows
 
 Additional response codes and their details are noted below
 
-| Response code         | Description   |
-| --------------------- | ------------- |
-| READ_STREAM_UNKNOWN   | This status indicates the server software failed to set a status and SHALL be considered a
-software defect. |
+| Response code                             | Description   |
+| ----------------------------------------- | ------------- |
+| READ_STREAM_UNKNOWN                       | The server software failed to set a status and SHALL be considered a software defect. |
+| READ_STREAM_INSUFFICIENT_BALANCE          | The requesting client account lacks sufficient HBAR to pay the service fee for this request. |
+| READ_STREAM_SUCCESS                       | The request succeeded. |
+| READ_STREAM_INVALID_START_BLOCK_NUMBER    | The requested start block number is not valid. |
+| READ_STREAM_INVALID_END_BLOCK_NUMBER      | The requested end block number is not valid. |
+| READ_STREAM_NOT_AVAILABLE                 | The requested stream is not available. |
 
-<aside>
-🚨 **Open Task:** Add all known response codes
-</aside>
 
 #### Block Service
 
@@ -416,9 +406,16 @@ service BlockAccessService {
 > Note: A stream of state changes highlighting the changes in a given block may be obtained by utilizing block item
 filtering on the block service.
 
-<aside>
-🚨 **Open Task:** Add all known response codes for API
-</aside>
+| Response code                     | Description   |
+| --------------------------------- | ------------- |
+| READ_BLOCK_UNKNOWN                | The server software failed to set a status,and SHALL be considered a software defect. |
+| READ_BLOCK_INSUFFICIENT_BALANCE   | The requesting client account lacks sufficient HBAR to pay the service fee for this request. |
+| READ_BLOCK_SUCCESS                | The request succeeded. |
+| READ_BLOCK_NOT_FOUND              | The requested block was not found. |
+| READ_BLOCK_NOT_AVAILABLE          | The requested block is not available on this block node server. |
+| ALLOW_UNVERIFIED_REQUIRED         | The request for a verified block cannot be fulfilled because the block node does not offer verified blocks. |
+| VERIFIED_BLOCK_UNAVAILABLE        | The request for a verified block cannot be fulfilled because the block node has yet to verify the block. |
+
 
 #### State Service
 
@@ -438,16 +435,18 @@ service StateService {
 ```
 
 <aside>
-🚨 **Open Task:** Flesh out 3 different state related query endpoints
+🚨 **Open Task:** Flesh out 2 different state related query endpoints
 1. State snapshot - covering latest state and historical state. All cases represent verified state at the end of a
     block.
 2. Single entity state query e.g. return account 0.0.x 
   - Add new endpoint to proto
 </aside>
 
-<aside>
-🚨 **Open Task:** Add all known response codes for API
-</aside>
+| Response code                         | Description   |
+| ------------------------------------- | ------------- |
+| STATE_SNAPSHOT_UNKNOWN                | The server software failed to set a status,and SHALL be considered a software defect. |
+| STATE_SNAPSHOT_INSUFFICIENT_BALANCE   | The requesting client account lacks sufficient HBAR to pay the service fee for this request. |
+| STATE_SNAPSHOT_SUCCESS                | The request succeeded. |
 
 #### Reconnect Service
 
@@ -459,12 +458,6 @@ Hashgraph state management.
 As such the block node will replace the teaching role of a consensus node today and serve as a reliable teacher to any
 consensus node or block node coming online and looking for latest network details.
 
-<aside>
-🚨 **Open Task:** Expand
-1. Speak to the need and value of BN provided reconnect vs CN
-2. Highlight BN -> BN reconnect
-3. Note details of what reconnect will provide i.e. latest state + x
-</aside>
 
 #### Proof Service
 
@@ -474,32 +467,11 @@ and could not offer state proof for historical state.
 By maintaining live state, historical state snapshots, and streaming block stream information a block node can finally
 fill this gap and provide users with a variety of proofs, including state proofs.
 
-<aside>
-🚨 **Open Task:** Flesh out response components
-Noting the 3 different proof types
-1. Block Proof
-2. Block Item Proof 
-3. State Proof
-</aside>
 
 ### Discovery
 
 To ensure a robust decentralized network it is important for block nodes to be easily discovered by clients.
 
-<aside>
-🚨 **Open Task:** Explain how block nodes provide discovery details. 
-Considerations
-- Are they self reported?
-- Are they onchain?
-- What requirements if any are there for a block node and operator?
-</aside>
-
-<aside>
-🚨 **Open Task:** Explain how block nodes are discovered
-- by a client so they can query data
-- by a CN so they can push data e.g. by address book
-</aside>
-
 
 ### Monetization
 
@@ -611,8 +583,18 @@ A running block node that requires a state snapshot for some reason should retri
 🚨 **Open Task:** Summarize initial claims and initial reasons to not support
 </aside>
 
-## Open Issues/Ideas
-
+## Open Issues/Ideas/Tasks
+- [ ] Flesh out design decisions approach in `Rationale` section
+- [ ] Add diagram showing BN system location in overall Hedera architecture in `Rationale` section
+    - Highlight CN(s) -> BN -> MN + block stream clients
+- [ ] Flesh out PRoof Service response components, Noting the 3 different proof types
+    - Block Proof
+    - Block Item Proof 
+    - State Proof
+- [ ] Expand Reconnect Service
+    - Speak to the need and value of BN provided reconnect vs CN
+    - Highlight BN -> BN reconnect
+    - Note details of what reconnect will provide i.e. latest state + x
 - [ ] Q: “As a block node operator I should be able to attach custom plugins to the block node, which can utilize its
     functionality.” How should this intent be highlighted in specification. Are the detail more implementation and future
     expansions that should be captured in separate HIPs and product EPICs?
@@ -624,11 +606,17 @@ nodes here? Previously the CN output state every 15 mins
     - Pause in stream due to CN upgrades - Confirm and improve explanation
     - Pauses in stream due to no Block Proof - Confirm and improve explanation
 - [ ] Q: How can block nodes provide discovery details?
+    Considerations
+    - Are they self reported?
+    - Are they onchain?
+    - What requirements if any are there for a block node and operator?
     - One idea is "There should be a mechanism that is on chain and self reported (could just be an HCS topic with a
     custom fee), but that should not be the only mechanism. Community innovation in this area should be encouraged
     (perhaps someone will build a "Block Market" to find and obtain blocks according to a wide variety of criteria,
     similar to a wholesale electric power market)."
 - [ ] Q: How will block nodes be discovered?
+    - by a client so they can query data
+    - by a CN so they can push data e.g. by address book
     - One idea that is optional and customizable by CN & BNs is "Client should have many options. Possibilities
     include address book entries, block nodes that offer listings of other block nodes (sort of like how some bit
     torrent services work), or even "block node rating" services that offer curated lists.