api.v1.proto

// Schema definition for block request/response messages.

syntax = "proto3";

package api.v1;

// Block enumeration direction.
enum Direction {
	// Enumerate in ascending order (from child to parent).
	Ascending = 0;
	// Enumerate in descending order (from parent to canonical child).
	Descending = 1;
}

// Request block data from a peer.
message BlockRequest {
	// Bits of block data to request.
	uint32 fields = 1;
	// Start from this block.
	oneof from_block {
		// Start with given hash.
		bytes hash = 2;
		// Start with given block number.
		bytes number = 3;
	}
	// End at this block. An implementation defined maximum is used when unspecified.
	bytes to_block = 4; // optional
	// Sequence direction.
	Direction direction = 5;
	// Maximum number of blocks to return. An implementation defined maximum is used when unspecified.
	uint32 max_blocks = 6; // optional
	// Indicate to the receiver that we support multiple justifications. If the responder also
	// supports this it will populate the multiple justifications field in `BlockData` instead of
	// the single justification field.
	bool support_multiple_justifications = 7; // optional
}

// Response to `BlockRequest`
message BlockResponse {
	// Block data for the requested sequence.
	repeated BlockData blocks = 1;
}

// Block data sent in the response.
message BlockData {
	// Block header hash.
	bytes hash = 1;
	// Block header if requested.
	bytes header = 2; // optional
	// Block body if requested.
	repeated bytes body = 3; // optional
	// Block receipt if requested.
	bytes receipt = 4; // optional
	// Block message queue if requested.
	bytes message_queue = 5; // optional
	// Justification if requested.
	bytes justification = 6; // optional
	// True if justification should be treated as present but empty.
	// This hack is unfortunately necessary because shortcomings in the protobuf format otherwise
	// doesn't make in possible to differentiate between a lack of justification and an empty
	// justification.
	bool is_empty_justification = 7; // optional, false if absent
	// Justifications if requested.
	// Unlike the field for a single justification, this field does not required an associated
	// boolean to differentiate between the lack of justifications and empty justification(s). This
	// is because empty justifications, like all justifications, are paired with a non-empty
	// consensus engine ID.
	bytes justifications = 8; // optional
}