// 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
}

// 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
}