Block Node

assets/hip-1081/protobuf/block_access_service.proto

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+syntax = "proto3";
+
+package org.hiero.block.api;
+
+import "stream/block.proto";
+
+/**
+ * A request to read a single block.
+ *
+ * A client system SHALL send this message to request a single block,
+ * including the block state proof.<br/>
+ * A client MAY request that the block be sent without verification.
+ * A compliant Block Node MAY respond to requests that allow unverified
+ * responses by returning the full requested block before verifying
+ * the included block proof.<br/>
+ * A compliant Block Node MAY support _only_ requests that allow unverified
+ * blocks, but MUST clearly document that limitation, and MUST respond to
+ * a request that does not allow unverified blocks with the
+ * `ALLOW_UNVERIFIED_REQUIRED` response code.
+ */
+message BlockRequest {
+  /**
+   * The block number of a block to retrieve.
+   * <p>
+   * The requested block MUST exist on the block node.<br/>
+   * This value MUST NOT be set if `retrieve_latest` is set `true`.<br/>
+   * This value MUST be set to a valid block number if `retrieve_latest` is
+   * unset or is set `false`.
+   */
+  uint64 block_number = 1;
+
+  /**
+   * A flag to indicate that the requested block may be sent without
+   * verifying its `BlockProof`.<br/>
+   * This might be set by a client that expects to perform its own
+   * verification and wishes lower latency or, potentially, lower cost.
+   * <p>
+   * If this value is set, then the responding Block Node MAY respond with a
+   * block that has not completed verification of its `BlockProof`.<br/>
+   * If this is _not_ set then the Block Node MUST respond with either a
+   * fully verified and validated block, or `VERIFIED_BLOCK_UNAVAILABLE` if
+   * the requested block is not yet verified.<br/>
+   * The default value is _not set_.
+   */
+  bool allow_unverified = 2;
+
+  /**
+   * A flag to request the latest available block.
+   * <p>
+   * This value MAY be set `true` to request the last block available.<br/>
+   * If this value is set to `true` then `block_number` MUST NOT be set and
+   * SHALL be ignored.
+   */
+  bool retrieve_latest = 3;
+}
+
+/**
+ * A response to a `singleBlock` request.
+ *
+ * This message SHALL be sent in response to a request, and SHALL contain at
+ * least a valid `status`.<br/>
+ * If `status` is `READ_BLOCK_SUCCESS`, the response SHALL contain the
+ * requested block in the `block` field.
+ *
+ * > Note
+ * >> A block can become quite large. A client MUST be prepared to receive the
+ * >> full content of the block, perhaps many megabytes of data.
+ */
+message BlockResponse {
+  /**
+   * A response status.
+   * <p>
+   * The reported status SHALL reflect the success of the request, or
+   * a detailed reason the request failed.
+   */
+  BlockResponseCode status = 1;
+
+  /**
+   * The requested block.
+   * <p>
+   * This container object SHALL hold the entire sequence of block items
+   * for the requested block.<br/>
+   * The block items in this message SHALL be in the same order
+   * as received.<br/>
+   * The items in this message SHALL begin with a `BlockHeader` and end with
+   * a `BlockStateProof` applicable to this block.
+   */
+  com.hedera.hapi.block.stream.Block block = 2;
+}
+
+/**
+ * An enumeration indicating the status of this request.
+ */
+enum BlockResponseCode {
+  /**
+   * An "unset value" flag, this value SHALL NOT be used.<br/>
+   * This status indicates the server software failed to set a status,
+   * and SHALL be considered a software defect.
+   */
+  READ_BLOCK_UNKNOWN = 0;
+
+  /**
+   * The requesting client account lacks sufficient HBAR to pay the
+   * service fee for this request.<br/>
+   * The client MAY retry the request, but MUST increase the client
+   * account balance with this block node server before doing so.
+   */
+  READ_BLOCK_INSUFFICIENT_BALANCE = 1;
+
+  /**
+   * The request succeeded.<br/>
+   * The requested block SHALL be returned in the `block` field.
+   */
+  READ_BLOCK_SUCCESS = 2;
+
+  /**
+   * The requested block was not found.<br/>
+   * Something failed and a block that SHOULD be available was
+   * not found.<br/>
+   * The client MAY retry the request; if this result is repeated the
+   * request SHOULD be directed to a different block node server.
+   */
+  READ_BLOCK_NOT_FOUND = 3;
+
+  /**
+   * The requested block is not available on this block node server.<br/>
+   * The client SHOULD send a `serverStatus` request to determine the
+   * lowest and highest block numbers available at this block node server.
+   */
+  READ_BLOCK_NOT_AVAILABLE = 4;
+
+  /**
+   * The request for a verified block cannot be fulfilled.<br/>
+   * The client requested a verified block from a block node that does not
+   * offer verified blocks.
+   * <p>
+   * The client MAY retry the request with the `allow_unverified` flag set.
+   */
+  ALLOW_UNVERIFIED_REQUIRED = 5;
+
+  /**
+   * The request for a verified block cannot be fulfilled.<br/>
+   * The client requested a verified block from a block node but the
+   * requested block is not yet verified.
+   * <p>
+   * The client MAY retry the request after a short delay
+   * (typically 2 seconds or more).
+   */
+  VERIFIED_BLOCK_UNAVAILABLE = 6;
+}
+
+/**
+ * Remote procedure calls (RPCs) for the Block Node stream services.
+ */
+service BlockAccessService {
+  /**
+   * Read a single block from the block node.
+   * <p>
+   * The request SHALL describe the block number of the block to retrieve.
+   */
+  rpc getBlock(BlockRequest) returns (BlockResponse);
+}