Skip to content

Commit

Permalink
Add API response codes
Browse files Browse the repository at this point in the history 
Signed-off-by: Nana Essilfie-Conduah <nana@swirldslabs.com>
  • Loading branch information
@Nana-EC
Nana-EC committed Dec 11, 2024
1 parent 0afa6c5 commit 584e303
Showing 1 changed file with 49 additions and 61 deletions.
110 changes: 49 additions & 61 deletions HIP/hip-1081.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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?
Expand All @@ -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.
Expand Down

0 comments on commit 584e303

Please sign in to comment.