libra_client 0.1.6 → 0.1.7

data/protos/admission_control.proto

@@ -6,11 +6,9 @@ syntax = "proto3";
 package admission_control;
 
 import "get_with_proof.proto";
+import "mempool_status.proto";
 import "transaction.proto";
-import "proof.proto";
-import "ledger_info.proto";
 import "vm_errors.proto";
-import "mempool_status.proto";
 
 // -----------------------------------------------------------------------------
 // ---------------- Submit transaction
@@ -21,11 +19,20 @@ message SubmitTransactionRequest {
   types.SignedTransaction signed_txn = 1;
 }
 
+// AC response status containing code and optionally an error message.
+message AdmissionControlStatus {
+  AdmissionControlStatusCode code = 1;
+  string message = 2;
+}
+
 // Additional statuses that are possible from admission control in addition
 // to VM statuses.
-enum AdmissionControlStatus {
+enum AdmissionControlStatusCode {
+  // Validator accepted the transaction.
   Accepted = 0;
+  // The sender is blacklisted.
   Blacklisted = 1;
+  // The transaction is rejected, e.g. due to incorrect signature.
   Rejected = 2;
 }
 

data/protos/consensus.proto

@@ -0,0 +1,147 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package network;
+
+import "ledger_info.proto";
+import "transaction.proto";
+
+message ConsensusMsg {
+  oneof message {
+    Proposal proposal = 1;
+    Vote vote = 2;
+    RequestBlock request_block = 3;
+    RespondBlock respond_block = 4;
+    TimeoutMsg timeout_msg = 5;
+    SyncInfo sync_info = 6;
+  }
+}
+
+message Proposal {
+  // The proposed block
+  Block proposed_block = 1;
+  // Information about the highest QC, LedgerInfo, TimeoutCertificate, etc.
+  SyncInfo sync_info = 2;
+}
+
+message PacemakerTimeout {
+  // Round that has timed out (e.g. we propose to switch to round + 1)
+  uint64 round = 1;
+  // Author of timeout
+  bytes author = 2;
+  // Signature that this timeout was authored by owner
+  bytes signature = 3;
+  // Optional vote for the given round
+  Vote vote = 4;
+}
+
+message TimeoutMsg {
+  // Information about the highest QC, LedgerInfo, TimeoutCertificate, etc.
+  SyncInfo sync_info = 1;
+  // Timeout
+  PacemakerTimeout pacemaker_timeout = 2;
+  // Signature that this timeout was authored by owner
+  bytes signature = 3;
+}
+
+message SyncInfo {
+  // Highest quorum certificate
+  QuorumCert highest_quorum_cert = 1;
+  // Highest ledger info
+  QuorumCert highest_ledger_info = 2;
+  // Optional highest timeout certificate if available
+  PacemakerTimeoutCertificate highest_timeout_cert = 3;
+}
+
+message PacemakerTimeoutCertificate {
+  // Round for which this certificate was created
+  uint64 round = 1;
+  // List of certified timeouts
+  repeated PacemakerTimeout timeouts = 2;
+}
+
+message Block {
+  // This block's id as a hash value
+  bytes id = 1;
+  // Parent block id of this block as a hash value (all zeros to indicate the
+  // genesis block)
+  bytes parent_id = 2;
+  // Payload of the block (e.g. one or more transaction(s)
+  bytes payload = 3;
+  // The round of the block (internal monotonically increasing counter).
+  uint64 round = 4;
+  // The height of the block (position in the chain).
+  uint64 height = 5;
+  // The approximate physical microseconds since the epoch when the block was proposed
+  uint64 timestamp_usecs = 6;
+  // Contains the quorum certified ancestor and whether the quorum certified
+  // ancestor was voted on successfully
+  QuorumCert quorum_cert = 7;
+  // Author of the block that can be validated by the author's public key and
+  // the signature
+  bytes author = 8;
+  // Signature that the hash of this block has been authored by the owner of the
+  // private key
+  bytes signature = 9;
+}
+
+message QuorumCert {
+  // The vote information certified by the quorum.
+  VoteData vote_data = 1;
+  // LedgerInfo with at least 2f+1 signatures. The LedgerInfo's consensus data
+  // hash is a digest that covers vote data hash.
+  types.LedgerInfoWithSignatures signed_ledger_info = 2;
+}
+
+message VoteData {
+  // The id of the block being vote for.
+  bytes block_id = 1;
+  // The round of the block being voted for
+  uint64 round = 2;
+  // The id and the version of the state after executing the block.
+  bytes executed_state_id = 3;
+  uint64 version = 4;
+  // The id of the parent block
+  bytes parent_block_id = 5;
+  // The round of the parent block
+  uint64 parent_block_round = 6;
+  // The id of the grandparent block
+  bytes grandparent_block_id = 7;
+  // The round of the grandparent block
+  uint64 grandparent_block_round = 8;
+}
+
+message Vote {
+  // The actual vote information.
+  VoteData vote_data = 1;
+  // Author of the vote.
+  bytes author = 2;
+  // The ledger info carried with the vote (corresponding to the block of a
+  // potentially committed txn).
+  types.LedgerInfo ledger_info = 3;
+  // Signature of the ledger info.
+  bytes signature = 4;
+}
+
+message RequestBlock {
+  // The id of the requested block.
+  bytes block_id = 1;
+  uint64 num_blocks = 2;
+}
+
+enum BlockRetrievalStatus {
+  // Successfully fill in the request.
+  SUCCEEDED = 0;
+  // Can not find the block corresponding to block_id.
+  ID_NOT_FOUND = 1;
+  // Can not find enough blocks but find some.
+  NOT_ENOUGH_BLOCKS = 2;
+}
+
+message RespondBlock {
+  BlockRetrievalStatus status = 1;
+  // The responded block.
+  repeated Block blocks = 2;
+}

data/protos/events.proto

@@ -14,7 +14,7 @@ import "proof.proto";
 
 // An event emitted from a smart contract
 message Event {
-    AccessPath access_path = 1;
+    bytes key = 1;
     uint64 sequence_number = 2;
     bytes event_data = 3;
 }

data/protos/execution.proto

@@ -0,0 +1,92 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package execution;
+
+import "get_with_proof.proto";
+import "ledger_info.proto";
+import "transaction.proto";
+import "validator_set.proto";
+import "vm_errors.proto";
+
+// -----------------------------------------------------------------------------
+// ---------------- Execution Service Definition
+// -----------------------------------------------------------------------------
+service Execution {
+  // Execute a list of signed transactions given by consensus. Return the id
+  // of the block and the root hash of the ledger after applying transactions
+  // in this block.
+  rpc ExecuteBlock(ExecuteBlockRequest) returns (ExecuteBlockResponse) {}
+
+  // Commit a previously executed block that has been agreed by consensus.
+  rpc CommitBlock(CommitBlockRequest) returns (CommitBlockResponse) {}
+
+  // Execute and commit a list of signed transactions received from peer
+  // during synchronization. Return the id of the block
+  rpc ExecuteChunk(ExecuteChunkRequest) returns (ExecuteChunkResponse) {}
+}
+
+message ExecuteBlockRequest {
+  // The list of transactions from consensus.
+  repeated types.SignedTransaction transactions = 1;
+
+  // Id of the parent block.
+  // We're going to use a special GENESIS_BLOCK_ID constant defined in
+  // crypto::hash module to refer to the block id of the Genesis block, which is
+  // executed in a special way.
+  bytes parent_block_id = 2;
+
+  // Id of the current block.
+  bytes block_id = 3;
+}
+
+// Result of transaction execution.
+message ExecuteBlockResponse {
+  // Root hash of the ledger after applying all the transactions in this
+  // block.
+  bytes root_hash = 1;
+
+  // The execution result of the transactions. Each transaction has a status
+  // field that indicates whether it should be included in the ledger once the
+  // block is committed.
+  repeated types.VMStatus status = 2;
+
+  // The corresponding ledger version when this block is committed.
+  uint64 version = 3;
+
+  // If set, this field designates that if this block is committed, then the
+  // next epoch will start immediately with the included set of validators.
+  types.ValidatorSet validators = 4;
+}
+
+message CommitBlockRequest {
+  // The ledger info with signatures from 2f+1 validators. It contains the id
+  // of the block consensus wants to commit. This will cause the given block
+  // and all the uncommitted ancestors to be committed to storage.
+  types.LedgerInfoWithSignatures ledger_info_with_sigs = 1;
+}
+
+message CommitBlockResponse { CommitBlockStatus status = 1; }
+
+enum CommitBlockStatus {
+  // The block is persisted.
+  SUCCEEDED = 0;
+
+  // Something went wrong.
+  FAILED = 1;
+}
+
+// Ask Execution service to execute and commit a chunk of contiguous
+// transactions. All the transactions in this chunk should belong to the same
+// epoch E. If the caller has a list of transactions that span two epochs, it
+// should split the transactions.
+message ExecuteChunkRequest {
+  types.TransactionListWithProof txn_list_with_proof = 1;
+  types.LedgerInfoWithSignatures ledger_info_with_sigs = 2;
+}
+
+// Either all transactions are successfully executed and persisted, or nothing
+// happens.
+message ExecuteChunkResponse {}

data/protos/language_storage.proto

@@ -0,0 +1,12 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+/// The unique identifier for a module on the chain.
+message ModuleId {
+    bytes address = 1;
+    string name = 2;
+}

data/protos/mempool.proto

@@ -0,0 +1,18 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package network;
+
+import "transaction.proto";
+
+/* MempoolSyncMsg represents the messages exchanging between validators to keep
+ * transactions in sync. The proto definition provides the spec on the wire so
+ * that others can implement their mempool service in various languages.
+ * Mempool service is responsible for sending and receiving MempoolSyncMsg
+ * across validators. */
+message MempoolSyncMsg {
+  bytes peer_id = 1;
+  repeated types.SignedTransaction transactions = 2;
+}

data/protos/mempool_status.proto

@@ -5,7 +5,7 @@ syntax = "proto3";
 
 package mempool;
 
-enum MempoolAddTransactionStatus {
+enum MempoolAddTransactionStatusCode {
   // Transaction was sent to Mempool
   Valid = 0;
   // The sender does not have enough balance for the transaction.
@@ -19,3 +19,8 @@ enum MempoolAddTransactionStatus {
   // Invalid update. Only gas price increase is allowed
   InvalidUpdate = 5;
 }
+
+message MempoolAddTransactionStatus {
+  MempoolAddTransactionStatusCode code = 1;
+  string message = 2;
+}

data/protos/network.proto

@@ -0,0 +1,81 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package network;
+
+// A `PeerInfo` represents the network address(es) of a Peer.
+message PeerInfo {
+  // Monotonically increasing incarnation number used to allow peers to issue
+  // updates to their `PeerInfo` and prevent attackers from propagating old
+  // `PeerInfo`s. This is usually a timestamp.
+  uint64 epoch = 1;
+  // Network addresses this peer can be reached at. An address is a serialized
+  // [multiaddr](https://multiformats.io/multiaddr/).
+  repeated bytes addrs = 2;
+}
+
+// A `PeerInfo` authenticated by the peer's root `network_signing_key` stored
+// on-chain.
+message SignedPeerInfo {
+  // A serialized `PeerInfo`.
+  bytes peer_info = 1;
+  // A signature over the above serialzed `PeerInfo`, signed by the validator's
+  // `network_signing_key` referred to by the `peer_id` account address.
+  bytes signature = 2;
+}
+
+// Discovery information relevant to public full nodes and clients.
+message FullNodePayload {
+  // Monotonically increasing incarnation number used to allow peers to issue
+  // updates to their `FullNodePayload` and prevent attackers from propagating
+  // old `FullNodePayload`s. This is usually a timestamp.
+  uint64 epoch = 1;
+  // The DNS domain name other public full nodes should query to get this
+  // validator's list of full nodes.
+  bytes dns_seed_addr = 2;
+}
+
+// A signed `FullNodePayload`.
+message SignedFullNodePayload {
+  // A serialized `FullNodePayload`.
+  bytes payload = 1;
+  // A signature over `payload` signed by the validator's `network_signing_key`
+  // referred to by the `peer_id` account address.
+  bytes signature = 2;
+}
+
+// A `Note` contains a validator's signed `PeerInfo` as well as a signed
+// `FullNodePayload`, which provides relevant discovery info for public full
+// nodes and clients.
+message Note {
+  // Id of the peer.
+  bytes peer_id = 1;
+  // The validator node's signed `PeerInfo`.
+  SignedPeerInfo signed_peer_info = 2;
+  // The validator node's signed `FullNodePayload`.
+  SignedFullNodePayload signed_full_node_payload = 3;
+}
+
+// Discovery message exchanged as part of the discovery protocol.
+// The discovery message sent by a peer consists of notes for all the peers the
+// sending peer knows about.
+message DiscoveryMsg { repeated Note notes = 1; }
+
+// Identity message exchanged as part of the Identity protocol.
+message IdentityMsg {
+  enum Role {
+    VALIDATOR = 0;
+    FULL_NODE = 1;
+  }
+  bytes peer_id = 1;
+  repeated bytes supported_protocols = 2;
+  Role role = 3;
+}
+
+// Ping message sent as liveness probe.
+message Ping {}
+
+// Pong message sent as response to liveness probe.
+message Pong {}

data/protos/node_debug_interface.proto

@@ -0,0 +1,40 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// A Debugging interface to be used to query debug information from a Node
+syntax = "proto3";
+
+package debug;
+
+message GetNodeDetailsRequest {}
+
+message GetNodeDetailsResponse { map<string, string> stats = 1; }
+
+message GetEventsRequest {}
+
+message GetEventsResponse { repeated Event events = 1; }
+
+message Event {
+    string name = 1;
+    int64 timestamp = 2;
+    string json = 3;
+}
+
+message DumpJemallocHeapProfileRequest {}
+
+message DumpJemallocHeapProfileResponse {
+  // Status code from jemalloc mallctl call. 0 indicates success.
+  int32 status_code = 1;
+}
+
+service NodeDebugInterface {
+  // Returns debug information about node
+  rpc GetNodeDetails(GetNodeDetailsRequest) returns (GetNodeDetailsResponse) {}
+
+  // Returns recent events generated by event! macro
+  rpc GetEvents(GetEventsRequest) returns (GetEventsResponse) {}
+
+  // Triggers a dump of heap profile.
+  rpc DumpJemallocHeapProfile(DumpJemallocHeapProfileRequest)
+      returns (DumpJemallocHeapProfileResponse) {}
+}