github.com/muhammedhassanm/blockchain@v0.0.0-20200120143007-697261defd4d/sawtooth-core-master/protos/consensus.proto

// Copyright 2018 Intel Corporation
//
// 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.
// -----------------------------------------------------------------------------

syntax = "proto3";

// --== Data Structures ==--

// A consensus-related message sent between peers
message ConsensusPeerMessage {
  // Interpretation is left to the consensus engine implementation
  string message_type = 1;

  // The opaque payload to send to other nodes
  bytes content = 2;

  // Used to identify the consensus engine that produced this message
  string name = 3;
  string version = 4;
}

// All information about a block that is relevant to consensus
message ConsensusBlock {
  bytes block_id = 1;
  bytes previous_id = 2;
  // The id of peer that signed this block
  bytes signer_id = 3;
  uint64 block_num = 4;
  bytes payload = 5;
  // A summary of the contents of the block
  bytes summary = 6;
}

// Information about a peer that is relevant to consensus
message ConsensusPeerInfo {
  // The unique id for this peer. This can be correlated with the signer id
  // on consensus blocks.
  bytes peer_id = 1;
}

// A settings key-value pair
message ConsensusSettingsEntry {
  string key = 1;
  string value = 2;
}

// A state key-value pair
message ConsensusStateEntry {
  string address = 1;
  bytes data = 2;
}

// --== Registration ==--

// Sent to connect with the validator
message ConsensusRegisterRequest {
  // The name of this consensus engine
  string name = 1;
  // The version of this consensus engine
  string version = 2;
}

message ConsensusRegisterResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;
  }

  Status status = 1;

  // Startup Info
  ConsensusBlock chain_head = 2;
  repeated ConsensusPeerInfo peers = 3;
  ConsensusPeerInfo local_peer_info = 4;
}

// --== Notifications ==--

// The following are notifications provided by the validator to the consensus
// engine. An ack should be sent in response to all notifications.

// - P2P -

// A new peer was added
message ConsensusNotifyPeerConnected {
  ConsensusPeerInfo peer_info = 1;
}

// An existing peer was dropped
message ConsensusNotifyPeerDisconnected {
  bytes peer_id = 1;
}

// A new message was received from a peer
message ConsensusNotifyPeerMessage {
  ConsensusPeerMessage message = 1;
  bytes sender_id = 2;
}

// - Blocks -

// A new block was received and passed initial consensus validation
message ConsensusNotifyBlockNew {
  ConsensusBlock block = 1;
}

// This block can be committed successfully
message ConsensusNotifyBlockValid {
  bytes block_id = 1;
}

// This block cannot be committed successfully
message ConsensusNotifyBlockInvalid {
  bytes block_id = 1;
}

// This block has been committed
message ConsensusNotifyBlockCommit {
  bytes block_id = 1;
}

// Confirm that the notification was received. The validator message
// correlation id is used to determine which notification this is an ack for.
message ConsensusNotifyAck {}

// --== Services Provided ==--

// The following are services provided by the validator to the consensus
// engine. All service messages have at a minimum the following possible return
// statuses:
//
//    STATUS_UNSET
//        No status was set by the validator, this should never happen
//    OK
//        The request was completed successfully
//    BAD_REQUEST
//        The request was malformed in some way
//    SERVICE_ERROR
//        The validator failed to perform the request
//    NOT_READY
//        The validator is not accepting requests, usually because it is still
//        starting up
//
// Additionally, messages may have the following additional return statuses:
//
//    INVALID_STATE
//        The request is not valid given the current state of the validator
//    UNKNOWN_BLOCK
//        No block with the given id could be found
//    UNKNOWN_PEER
//        No peer with the given id could be found

// - P2P Messaging -

// Send a consensus message to a specific, connected peer
message ConsensusSendToRequest {
  ConsensusPeerMessage message = 1;
  bytes peer_id = 2;
}

message ConsensusSendToResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_PEER = 5;
  }
  Status status = 1;
}

// Broadcast a consensus message to all peers
message ConsensusBroadcastRequest {
  ConsensusPeerMessage message = 1;
}

message ConsensusBroadcastResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;
  }
  Status status = 1;
}

// - Block Creation -

// Initialize a new block built on the block with the given previous id and
// begin adding batches to it. If no previous id is specified, the current
// head will be used.
message ConsensusInitializeBlockRequest {
  bytes previous_id = 1;
}

message ConsensusInitializeBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    INVALID_STATE = 5;
    UNKNOWN_BLOCK = 6;
  }
  Status status = 1;
}

// Stop adding batches to the current block and return a summary of its
// contents.
message ConsensusSummarizeBlockRequest {}

message ConsensusSummarizeBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    INVALID_STATE = 5;
    BLOCK_NOT_READY = 6;
  }
  Status status = 1;

  // A summary of the block contents
  bytes summary = 2;
}

// Insert the given consensus data into the block and sign it. If this call is
// successful, the consensus engine will receive the block afterwards.
message ConsensusFinalizeBlockRequest {
  // The consensus data to include in the finalized block
  bytes data = 1;
}

message ConsensusFinalizeBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    INVALID_STATE = 5;
    BLOCK_NOT_READY = 6;
  }
  Status status = 1;

  // The block id of the newly created block
  bytes block_id = 2;
}

// Stop adding batches to the current block and abandon it.
message ConsensusCancelBlockRequest {}

message ConsensusCancelBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    INVALID_STATE = 5;
  }

  Status status = 1;
}

// - Block Directives -

// Request that, for each block block in order, the block is checked to
// determine whether the block can be committed successfully or not. Blocks
// may be checked in parallel. If a new request arrives, it overrides the
// previous request allowing the engine to reprioritize the list of blocks to
// check.
//
// NOTE: OK does not mean the blocks will all commit successfully, only that
// the directive was received successfully. The engine must listen for
// notifications from the consuming component to learn if the blocks would
// commit or not.
message ConsensusCheckBlocksRequest {
  repeated bytes block_ids = 1;
}

message ConsensusCheckBlocksResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
}

// Request that the block be committed. This request fails if the block has
// not already been checked.
//
// NOTE: OK does not mean the block has been committed, only that the directive
// was received successfully. The engine must listen for notifications from the
// consuming component to learn when the block commits.
message ConsensusCommitBlockRequest {
  bytes block_id = 1;
}

message ConsensusCommitBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
}

// Inform the consuming component that this block is no longer being considered
// and can be held or freed as needed.
message ConsensusIgnoreBlockRequest {
  bytes block_id = 1;
}

message ConsensusIgnoreBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
}

// Fail this block and any of its descendants and purge them as needed.
message ConsensusFailBlockRequest {
  bytes block_id = 1;
}

message ConsensusFailBlockResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
}

// - Queries -

// Retrieve consensus-related information about blocks. If some blocks could
// not be found, only the blocks that could be found will be returned.
message ConsensusBlocksGetRequest {
  repeated bytes block_ids = 1;
}

message ConsensusBlocksGetResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
  repeated ConsensusBlock blocks = 2;
}

// Retrieve consensus-related information about the chain head.
message ConsensusChainHeadGetRequest {}

message ConsensusChainHeadGetResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    NO_CHAIN_HEAD = 5;
  }

  Status status = 1;
  ConsensusBlock block = 2;
}

// Read the values of these settings from state as of the given block. If some
// values settings keys cannot be found, the keys that were found will be
// returned.
message ConsensusSettingsGetRequest {
  bytes block_id = 1;
  repeated string keys = 2;
}

message ConsensusSettingsGetResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
  repeated ConsensusSettingsEntry entries = 2;
}

// Read the data at these addresses from state as of the given block. If some
// addresses cannot be found, state at the addresses that were found will be
// returned.
message ConsensusStateGetRequest {
  bytes block_id = 1;
  repeated string addresses = 2;
}

message ConsensusStateGetResponse {
  enum Status {
    STATUS_UNSET = 0;
    OK = 1;
    BAD_REQUEST = 2;
    SERVICE_ERROR = 3;
    NOT_READY = 4;

    UNKNOWN_BLOCK = 5;
  }

  Status status = 1;
  repeated ConsensusStateEntry entries = 2;
}