shgraph.hedera-protobuf-java-api.0.56.2.source-code.block_service.proto Maven / Gradle / Ivy
/**
* # Block Service
* The Service API exposed by the Block Nodes.
*
* ### Keywords
* The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
* "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
* document are to be interpreted as described in
* [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in
* [RFC8174](https://www.ietf.org/rfc/rfc8174).
*/
syntax = "proto3";
package com.hedera.hapi.block;
/*
* Copyright (C) 2024 Hedera Hashgraph, LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
option java_package = "com.hedera.hapi.block.protoc";
// <<>> This comment is special code for setting PBJ Compiler java package
option java_multiple_files = true;
import "basic_types.proto";
import "stream/block.proto";
import "stream/block_item.proto";
/**
* Publish a stream of block items.
*
* Each request in the stream MUST contain at least one `BlockItem`.
* Each request MAY contain more than one `BlockItem`.
* A single request MUST NOT contain `BlockItem`s from more than one block.
* Each request MAY contain a variable number of `BlockItem`s.
* Each Block MUST begin with a single `BlockHeader` block item.
* If a `BlockHeader` is present in a request, it MUST be the first `BlockItem`
* in the `block_items` list.
* The block node SHALL append each `BlockItem` to an internal structure
* to reconstruct full blocks.
* The block node MUST verify the block proof for each block before sending a
* response message acknowledging that block.
* Each Block MUST end with a single `BlockProof` block item.
* If a `BlockProof` is present in a request, it MUST be the last `BlockItem`
* in the `block_items` list.
* The block node MUST verify each Block using the `BlockProof` to
* ensure all data was received and processed correctly.
*/
message PublishStreamRequest {
oneof request {
/**
* A stream item containing one or more `BlockItem`s.
*
* The full stream SHALL consist of many `block_items` messages
* followed by a single `status` message.
*/
BlockItemSet block_items = 1;
}
}
/**
* An enumeration indicating why a publisher ended a stream.
*
* This enumeration describes the reason a block stream
* (sent via `publishBlockStream`) was ended by the publisher.
*/
enum PublishStreamEndCode {
/**
* An "unset value" flag, this value SHALL NOT be used.
* This status indicates the server software failed to set a
* status, and SHALL be considered a software defect.
*/
STREAM_END_UNKNOWN = 0;
/**
* The Publisher reached a reset point.
* No errors occurred and the source node orderly ended the stream.
*
* Publishers SHOULD use this code to end a stream and restart
* occasionally. Occasionally resetting the stream increases stability and
* allows for routine network configuration changes.
*/
STREAM_END_RESET = 1;
/**
* The delay between items was too long.
* The destination system did not timely acknowledge a block.
*
* The source SHALL start a new stream before the failed block.
*/
STREAM_END_TIMEOUT = 2;
/**
* The publisher encountered an error.
* The publisher encountered an internal error and must try again later.
*
* Publishers that encounter internal logic errors, find themselves
* "behind" the network, or otherwise detect an unexpected situation MUST
* send this code and restart the stream before the failed block.
*/
STREAM_END_ERROR = 3;
/**
* The block node is too far behind to catch up directly.
* The block node responded to a block header with "BEHIND" and is
* too far behind the publisher.
*
* The block node MUST recover and "catch up" from another trustworthy
* block node.
* The publisher MAY stream items to a different block node.
* The publisher MAY resume streaming to this block node later.
* The `EndOfStream` message MUST include the earliest and latest blocks
* currently available from the publisher.
* The block node SHOULD attempt to "catch up" to the _latest_ block
* available from the publisher.
*/
STREAM_END_TOO_FAR_BEHIND = 4;
}
/**
* A wrapper around a repeated BlockItem.
* This message is required so that we can include ordered lists of block
* items as `oneof` alternatives in streams.
*
* Each `BlockItemSet` MUST contain at least one `BlockItem`,
* and MAY contain up to one full block.
* A single `BlockItemSet` SHALL NOT contain block items from
* more than one block.
* If a `BlockHeader` is present in a `BlockItemSet`, that item
* MUST be the first item in the list.
* If a `BlockProof` is present in a `BlockItemSet`, that item
* MUST be the last item in the list.
*/
message BlockItemSet {
/**
* An ordered list of `BlockItem`s.
* This list supports sending block items to subscribers in batches
* for greater channel efficiency.
*/
repeated com.hedera.hapi.block.stream.BlockItem block_items = 1;
}
/**
* A response to writing a block stream.
*
* This message is sent in response to each Block in a block stream sent
* to a block node. The block stream is sent as a stream of messages, and each
* message MAY be acknowledged with a message of this type.
* Each `BlockItem` MAY be acknowledged with an `Acknowledgement`
* response. Item acknowledgement is an OPTIONAL feature.
* Each completed block SHALL be acknowledged with an `Acknowledgement`
* response. Block acknowledgement is a REQUIRED feature.
* A final response SHALL be sent with an `EndOfStream` status result after
* the last block stream item is received, or when the receiving system
* must end the stream for any reason.
* If a failure is detected (which may include a block or block item that
* fails validation) an `EndOfStream` response SHALL be sent with a
* relevant error status.
*/
message PublishStreamResponse {
oneof response {
/**
* A response sent for each block, and optionally for each item.
*/
Acknowledgement acknowledgement = 1;
/**
* A response sent when a stream ends.
*/
EndOfStream status = 2;
}
/**
* A response to acknowledge receipt and verification of a single item
* or full block.
*/
message Acknowledgement {
oneof acknowledgements {
/**
* A response type to acknowledge a full and complete block.
*
* All block node implementations SHOULD acknowledge each block.
*/
BlockAcknowledgement block_ack = 1;
/**
* A response type to acknowledge a single `BlockItem`.
* This is an OPTIONAL message and implementations MAY choose to
* only acknowledge full blocks.
*/
ItemAcknowledgement item_ack = 2;
}
}
/**
* Acknowledgement for a single repeated `BlockItem`.
* Most nodes are expected to implement this acknowledgement only for
* debugging and development purposes.
*
* If a node implements single item acknowledgement, the block node SHALL
* send one `ItemAcknowledgement` for each repeated `BlockItem` received
* and verified.
*/
message ItemAcknowledgement {
/**
* A SHA2-384 hash of the `BlockItem`s received.
*
* This field is REQUIRED.
* A source system MUST verify that this value matches its own internal
* calculated hash value, and MUST end the stream if the values do not
* match.
*/
bytes items_hash = 1;
}
/**
* Acknowledgement of a full block.
* This message is a necessary part of the block streaming protocol.
*
* This response SHALL be sent after a block state proof item is
* received and verified.
* The block node SHALL send exactly one `BlockAcknowledgement` for
* each successful block.
* The `BlockAcknowledgement` response MAY be sent after sending an
* `ItemAcknowledgement` response for the `BlockStateProof` item
* at the end of the block, if item acknowledgement is enabled.
*/
message BlockAcknowledgement {
/**
* A block number number of the acknowledged block.
*
* A source system SHOULD verify that this value matches the block sent.
*/
uint64 block_number = 1;
/**
* A hash of the virtual merkle root for the block.
*
* This SHALL be the hash calculated by the block node for the
* root node of the virtual merkle tree that is signed by the source
* system to validate the block.
*/
bytes block_root_hash = 2;
/**
* A flag indicating that the received block duplicates an
* existing block.
*
* If a source system receives acknowledgement with this flag set
* true the source system SHOULD end the stream. The `block_number`
* returned SHALL be the last block known and verified by the receiving
* system, and the source system MAY resume publishing immediately
* after that block.
*/
bool block_already_exists = 3;
}
/**
* A message sent to end a stream.
*
* This response message SHALL be sent from a block node to a block
* stream source system when a `publishBlockStream` stream ends.
* This message SHALL be sent exactly once for each `publishBlockStream`
* call.
* The source system SHALL cease sending block items upon receiving
* this response, and MAY determine the ending state of the stream from
* the `status` enumeration and the `block_number` returned.
* A source system SHOULD verify that the `block_number` value matches the
* last block sent, and SHOULD resend one or more blocks if the value
* here does not match the expected value.
*/
message EndOfStream {
/**
* A response code.
*
* This code indicates the reason the stream ended.
* This value MUST be set to a non-default value.
*/
PublishStreamResponseCode status = 1;
/**
* The number of the last completed and _verified_ block.
*
* Nodes SHOULD only end a stream after a block state proof to avoid
* the need to resend items.
* If status is a failure code, the source node MUST start a new
* stream at the beginning of the first block _following_ this number
* (e.g. if this is 91827362983, then the new stream must start with
* the _header_ for block 91827362984).
*/
uint64 block_number = 2;
}
}
/**
* An enumeration indicating the status of this request.
*
* This enumeration SHALL describe the reason a block stream
* (sent via `publishBlockStream`) ended.
*/
enum PublishStreamResponseCode {
/**
* An "unset value" flag, this value SHALL NOT be used.
* This status indicates the server software failed to set a
* status, and SHALL be considered a software defect.
*/
STREAM_ITEMS_UNKNOWN = 0;
/**
* The request succeeded.
* No errors occurred and the source node orderly ended the stream.
*/
STREAM_ITEMS_SUCCESS = 1;
/**
* The delay between items was too long.
* The source MUST start a new stream before the failed block.
*/
STREAM_ITEMS_TIMEOUT = 2;
/**
* An item was received out-of-order.
* The source MUST start a new stream before the failed block.
*/
STREAM_ITEMS_OUT_OF_ORDER = 3;
/**
* A block state proof item could not be validated.
* The source MUST start a new stream before the failed block.
*/
STREAM_ITEMS_BAD_STATE_PROOF = 4;
/**
* The block node is "behind" the publisher.
* Ths consensus node has sent a block later than this block node
* can process. The publisher may retry by sending blocks immediately
* following the `block_number` returned, or may end the stream and
* try again later.
*
* Block nodes that are "behind" SHOULD attempt to "catch up" by requesting
* blocks from another block node or other source of recent historical
* block stream data.
*/
STREAM_ITEMS_BEHIND = 5;
}
/**
* A request to read a single block.
*
* A client system SHALL send this message to request a single block,
* including the block state proof.
* 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.
* 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 SingleBlockRequest {
/**
* The block number of a block to retrieve.
*
* The requested block MUST exist on the block node.
* This value MUST NOT be set if `retrieve_latest` is set `true`.
* 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`.
* This might be set by a client that expects to perform its own
* verification and wishes lower latency or, potentially, lower cost.
*
* If this value is set, then the responding Block Node MAY respond with a
* block that has not completed verification of its `BlockProof`.
* 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.
* The default value is _not set_.
*/
bool allow_unverified = 2;
/**
* A flag to request the latest available block.
*
* This value MAY be set `true` to request the last block available.
* 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`.
* 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 SingleBlockResponse {
/**
* A response status.
*
* The reported status SHALL reflect the success of the request, or
* a detailed reason the request failed.
*/
SingleBlockResponseCode status = 1;
/**
* The requested block.
*
* This container object SHALL hold the entire sequence of block items
* for the requested block.
* The block items in this message SHALL be in the same order
* as received.
* 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 SingleBlockResponseCode {
/**
* An "unset value" flag, this value SHALL NOT be used.
* 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.
* 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.
* The requested block SHALL be returned in the `block` field.
*/
READ_BLOCK_SUCCESS = 2;
/**
* The requested block was not found.
* Something failed and a block that SHOULD be available was
* not found.
* 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.
* 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.
* The client requested a verified block from a block node that does not
* offer verified blocks.
*
* 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.
* The client requested a verified block from a block node but the
* requested block is not yet verified.
*
* The client MAY retry the request after a short delay
* (typically 2 seconds or more).
*/
VERIFIED_BLOCK_UNAVAILABLE = 6;
}
/**
* A request to stream block items from block node to a client.
*
* The block node SHALL respond to this request with a stream of
* `SubscribeStreamResponse` messages.
* The block node SHALL stream the full contents of the blocks requested.
* The block items SHALL be streamed in order originally produced within
* a block.
* The blocks SHALL be streamed in ascending order by `block_number`.
* The block node SHALL end the stream when the last requested block has
* been sent.
* The block node SHALL end the stream with a response code status of SUCCESS
* when the stream is complete.
* The client SHOULD call the `serverStatus` rpc prior to constructing this
* request to determine the available start and end blocks.
*/
message SubscribeStreamRequest {
/**
* A block number to start the stream.
*
* This SHALL be the block number of the first block returned.
* This field MUST be less than or equal to the latest available
* block number.
*/
uint64 start_block_number = 1;
/**
* A block number to end the stream.
* This is optional, and if not set (0), the stream will be "infinite".
*
* This field MAY be zero (`0`) to indicate the stream SHOULD continue
* indefinitely, streaming new blocks as each becomes available.
* If this value is greater than zero (`0`)
*
* - This value SHALL be the number of the last block returned.
* - This field MUST NOT be less than `start_block_number`.
* - This SHOULD be a block number that is immediately available
* from the block node.
* - A block node SHALL continue to stream blocks until the last
* requested block is transmitted.
* - A block node implementation MAY reject a request for a block
* that is not yet available.
* - A block node implementation MAY accept future block numbers.
* - Block node implementations MAY charge increased fees for such
* "future" streams.
*
*/
uint64 end_block_number = 2;
/**
* A flag to indicate that the requested block(s) may be sent before
* verifying each block's `BlockProof`.
* This might be set by a client that expects to perform its own
* verification and wishes lower latency or, potentially, lower cost.
*
* If this value is set, then the responding Block Node MAY respond with
* blocks that have not (yet) completed block proof verification.
* If this is _not set_ then the Block Node MUST respond with only
* fully verified and validated block(s).
* If this is _set_, then a Block Node MAY stream items from
* blocks that have not yet been verified or do not yet have
* a block proof available.
* The default value is _not set_.
*/
bool allow_unverified = 3;
}
/**
* One item in a stream of `subscribeBlockStream` responses.
*
* The block node SHALL respond to a `subscribeBlockStream` request with a
* stream of `SubscribeStreamResponse` messages.
* The block node SHALL stream the full contents of the blocks requested.
* The block items SHALL be streamed in order originally produced within
* a block.
* The blocks SHALL be streamed in ascending order by `block_number`.
* The block node SHALL end the stream when the last requested block has
* been sent.
* The block node SHALL end the stream with a response code status of SUCCESS
* when the stream is complete.
* The block node SHALL end the stream with a response code status of
* `READ_STREAM_INVALID_START_BLOCK_NUMBER` if the start block number is
* greater than the end block number.
* The block node SHALL end the stream with a response code status of
* `READ_STREAM_INSUFFICIENT_BALANCE` if insufficient balance remains to
* complete the requested stream.
* The block node SHALL make every reasonable effort to fulfill as much of the
* request as available balance supports, in the event balance is not
* sufficient to complete the request.
*/
message SubscribeStreamResponse {
oneof response {
/**
* A final response item describing the terminal status of this stream.
*
* The block node server SHALL end the stream following this message.
*/
SubscribeStreamResponseCode status = 1;
/**
* A stream response item containing one or more `BlockItem`s.
*
* The full stream SHALL consist of many `block_items` messages
* followed by a single `status` message.
*/
BlockItemSet block_items = 2;
}
}
/**
* An enumeration indicating the status of this request.
*
* This response code SHALL be the last message in the stream of responses.
* This code SHALL represent the final status of the full request.
*/
enum SubscribeStreamResponseCode {
/**
* An "unset value" flag, this value SHALL NOT be used.
* This status indicates the server software failed to set a status,
* and SHALL be considered a software defect.
*/
READ_STREAM_UNKNOWN = 0;
/**
* The requesting client account lacks sufficient HBAR to pay the
* service fee for this request.
* The client MAY retry the request, but MUST increase the client
* account balance with this block node server before doing so.
*/
READ_STREAM_INSUFFICIENT_BALANCE = 1;
/**
* The request succeeded.
*
* The requested block(s) SHALL precede the status response
* with this value.
*/
READ_STREAM_SUCCESS = 2;
/**
* The requested start block number is not valid.
* The start block number is after the end block number, less
* than `0`, or otherwise invalid.
* The client MAY retry this request, but MUST change the
* `start_block_number` field to a valid start block.
*/
READ_STREAM_INVALID_START_BLOCK_NUMBER = 3;
/**
* The requested end block number is not valid.
* The end block number is greater than the highest current block
* number, less than `0`, or otherwise invalid.
* The client MAY retry this request, but MUST change the
* `end_block_number` field to a valid end block.
*/
READ_STREAM_INVALID_END_BLOCK_NUMBER = 4;
}
/**
* A request to read a state snapshot.
*
* A state snapshot is a full copy of the network state at the completion of a
* particular block.
*
* This request MUST contain a block number that has already reached this block
* node and completed verification, or request the "latest" snapshot.
* This request MAY specify the "latest" snapshot, and the block node SHALL
* respond with a reference to a snapshot containing the most recent contents
* of the network state known to that block node.
*/
message StateSnapshotRequest {
/**
* A block number.
*
* This SHALL be the last block number present in the snapshot
* returned.
* If `retrieve_latest` is set `true` this field SHOULD NOT be set
* and SHALL be ignored.
* A block node implementation MAY reject any request with a non-default
* value for this field, but MUST clearly document that behavior.
*/
uint64 last_block_number = 2;
/**
* A boolean to request the latest available snapshot.
*
* This value MAY be set `true` to request the most recent state snapshot
* available.
* If this value is set to `true` then `last_block_number` SHOULD NOT be
* set and SHALL be ignored.
* A block node implementation MAY reject any request with that does _not_
* set this field `true`, but MUST clearly document that behavior.
*/
bool retrieve_latest = 3;
}
/**
* A response to a request for a state snapshot.
*
* This message SHALL deliver a _reference_ to the requested snapshot
* data if successful.
* This message SHALL deliver a code indicating the reason for failure
* if unsuccessful.
*/
message StateSnapshotResponse {
/**
* A status response.
*
* This code SHALL indicate a successful call, or the detailed
* reason for failure.
*/
StateSnapshotResponseCode status = 1;
/**
* A block number.
*
* This SHALL be the number of the last block included in this
* state snapshot.
*/
uint64 last_block_number = 2;
/**
* A reference to where the requested state snapshot may be obtained.
*
*
REVIEW NOTE
* This is TEMPORARY. We have not yet designed how state snapshots may
* be sent. One idea is to use `Any` and let implementations decide;
* another is to use a time limited URL (with the same login as the block
* node server); another is to use a customer-pays cloud storage bucket.
*
*/
string snapshot_reference = 3;
}
/**
* An enumeration indicating the status of a StateSnapshotResponse request.
*/
enum StateSnapshotResponseCode {
/**
* An "unset value" flag, this value SHALL NOT be used.
* This status indicates the server software failed to set a status,
* and SHALL be considered a software defect.
*/
STATE_SNAPSHOT_UNKNOWN = 0;
/**
* The requesting client account lacks sufficient HBAR to pay the
* service fee for this request.
* The client MAY retry the request, but MUST increase the client
* account balance with this block node server before doing so.
*/
STATE_SNAPSHOT_INSUFFICIENT_BALANCE = 1;
/**
* The request succeeded.
* The full snapshot data MAY be read via the endpoint provided in the
* `snapshot_reference` field for the duration specified.
*/
STATE_SNAPSHOT_SUCCESS = 2;
}
/**
* A request for the status of a block node server.
*/
message ServerStatusRequest {}
/**
* A response to a server status request.
*
* This message SHALL provide a client with information needed to successfully
* query this block node server for a block, stream of blocks, or
* state snapshot.
* A request for blocks between `first_available_block` and
* `last_available_block`, inclusive, SHOULD succeed. Any request for blocks
* outside that range SHOULD fail.
*/
message ServerStatusResponse {
/**
* The lowest numbered block available on this block node server.
*
* Any request for a block with lower number than this value SHALL fail
* with a status value indicating and invalid start block number.
*/
uint64 first_available_block = 1;
/**
* The greatest block number available from this block node server.
*
* Any request for a block with a block number higher than this
* value MAY fail.
*/
uint64 last_available_block = 2;
/**
* A flag indicating this block node only offers the latest state snapshot.
*
* If this value is `true` the client MUST set `retrieve_latest` `true`
* in any `StateSnapshotRequest` sent to this block node.
*/
bool only_latest_state = 3;
/**
* Version information.
* Versions for the block network address book, block stream protocol
* buffer schema, and block node software.
*/
BlockNodeVersions version_information = 4;
}
/**
* Version information for a block node.
*
* The `stream_proto_version` SHOULD be an officially released Block Stream
* version.
* The `address_book_version` SHALL be defined by networks of block nodes.
* The `software_version` SHALL be defined by the implementation of the
* Block Node specification.
*/
message BlockNodeVersions {
/**
* A version of the Block Node network address book.
* The address book version describes what version of address book
* this block node holds for discovering and identifying other block nodes.
*
* This version SHALL be specific to each "network" of interconnected
* Block Nodes.
*/
proto.SemanticVersion address_book_version = 1;
/**
* A version of the Block Stream specification.
* This is the Stream version currently supported by this Block Node.
*
* Implementations SHOULD make reasonable effort to ensure the latest
* released Block Stream version is supported.
* This version MUST be an officially released Block Stream version if
* the responding block node is not private.
*/
proto.SemanticVersion stream_proto_version = 2;
/**
* A version of the block node software.
* This is the software version that this block node is currently
* running.
*
* This value is implementation-defined.
*/
proto.SemanticVersion software_version = 3;
}
/**
* Remote procedure calls (RPCs) for the Block Node ancillary services.
*/
service BlockNodeService {
/**
* Read the status of this block node server.
*
* A client SHOULD request server status prior to requesting block stream
* data or a state snapshot.
*/
rpc serverStatus(ServerStatusRequest) returns (ServerStatusResponse);
}
/**
* Remote procedure calls (RPCs) for the Block Node block services.
*/
service BlockAccessService {
/**
* Read a single block from the block node.
*
* The request SHALL describe the block number of the block to retrieve.
*/
rpc singleBlock(SingleBlockRequest) returns (SingleBlockResponse);
}
/**
* Remote procedure calls (RPCs) for the Block Node state snapshot
* and query services.
*/
service StateService {
/**
* Read a state snapshot from the block node.
*
* The request SHALL describe the last block number present in the
* snapshot.
* Block node implementations MAY decline a request for a snapshot older
* than the latest available, but MUST clearly document this behavior.
*/
rpc stateSnapshot(StateSnapshotRequest) returns (StateSnapshotResponse);
}
/**
* Remote procedure calls (RPCs) for the Block Node stream services.
*/
service BlockStreamService {
/**
* Publish a stream of blocks.
*
* Each item in the stream MUST contain one `BlockItem`.
* Each Block MUST begin with a single `BlockHeader` block item.
* The block node SHALL append each `BlockItem` to an internal structure
* to construct full blocks.
* Each Block MUST end with a single `BlockStateProof` block item.
* It is RECOMMENDED that the implementations verify the Block using the
* `BlockStateProof` to validate all data was received correctly.
* This API SHOULD, generally, be restricted based on mTLS authentication
* to a limited set of source (i.e. consensus node) systems.
*/
rpc publishBlockStream (stream PublishStreamRequest) returns (stream PublishStreamResponse);
/**
* Subscribe to a stream of blocks.
*
* Each item in the stream SHALL contain one `BlockItem` or a
* response code.
* The request message MUST specify start and end block numbers
* to return/
* The block node SHALL stream the full contents of the blocks
* requested.
* The block items SHALL be streamed in order originally produced within
* a block.
* The blocks shall be streamed in ascending order by `block_number`.
* The block node SHALL end the stream when the last requested block,
* if set, has been sent.
* A request with an end block of `0` SHALL be interpreted to indicate the
* stream has no end. The block node SHALL continue to stream new blocks
* as soon as each becomes available.
* The block node SHALL end the stream with response code containing a
* status of SUCCESS when the stream is complete.
* The block node SHALL end the stream with a response code containing a
* status of `READ_STREAM_INVALID_START_BLOCK_NUMBER` if the start block
* number is greater than the end block number.
* The block node SHALL end the stream with a response code containing a
* status of `READ_STREAM_PAYMENT_INSUFFICIENT` if insufficient payment
* remains to complete the requested stream.
* The block node SHALL make every reasonable effort to fulfill as much
* of the request as possible in the event payment is not sufficient to
* complete the request.
*/
rpc subscribeBlockStream(SubscribeStreamRequest) returns (stream SubscribeStreamResponse);
}