libra_client 0.1.0

data/protos/access_path.proto

@@ -0,0 +1,11 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+message AccessPath {
+  bytes address = 1;
+  bytes path = 2;
+}

data/protos/account_state_blob.proto

@@ -0,0 +1,16 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+import "proof.proto";
+
+message AccountStateBlob { bytes blob = 1; }
+
+message AccountStateWithProof {
+  uint64 version = 1;
+  AccountStateBlob blob = 2;
+  AccountStateProof proof = 3;
+}

data/protos/admission_control.proto

@@ -0,0 +1,76 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package admission_control;
+
+import "get_with_proof.proto";
+import "transaction.proto";
+import "proof.proto";
+import "ledger_info.proto";
+import "vm_errors.proto";
+import "mempool_status.proto";
+
+// -----------------------------------------------------------------------------
+// ---------------- Submit transaction
+// -----------------------------------------------------------------------------
+// The request for transaction submission.
+message SubmitTransactionRequest {
+  // Transaction signed by wallet.
+  types.SignedTransaction signed_txn = 1;
+}
+
+// Additional statuses that are possible from admission control in addition
+// to VM statuses.
+enum AdmissionControlStatus {
+  Accepted = 0;
+  Blacklisted = 1;
+  Rejected = 2;
+}
+
+// The response for transaction submission.
+//
+// How does a client know if their transaction was included?
+// A response from the transaction submission only means that the transaction
+// was successfully added to mempool, but not that it is guaranteed to be
+// included in the chain.  Each transaction should include an expiration time in
+// the signed transaction.  Let's call this T0.  As a client, I submit my
+// transaction to a validator. I now need to poll for the transaction I
+// submitted.  I can use the query that takes my account and sequence number. If
+// I receive back that the transaction is completed, I will verify the proofs to
+// ensure that this is the transaction I expected.  If I receive a response that
+// my transaction is not yet completed, I must check the latest timestamp in the
+// ledgerInfo that I receive back from the query.  If this time is greater than
+// T0, I can be certain that my transaction will never be included.  If this
+// time is less than T0, I need to continue polling.
+message SubmitTransactionResponse {
+  // The status of a transaction submission can either be a VM status, or
+  // some other admission control/mempool specific status e.g. Blacklisted.
+  oneof status {
+    types.VMStatus vm_status = 1;
+    AdmissionControlStatus ac_status = 2;
+    mempool.MempoolAddTransactionStatus mempool_status = 3;
+  }
+  // Public key(id) of the validator that processed this transaction
+  bytes validator_id = 4;
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Service definition
+// -----------------------------------------------------------------------------
+service AdmissionControl {
+  // Public API to submit transaction to a validator.
+  rpc SubmitTransaction(SubmitTransactionRequest)
+      returns (SubmitTransactionResponse) {}
+
+  // This API is used to update the client to the latest ledger version and
+  // optionally also request 1..n other pieces of data.  This allows for batch
+  // queries.  All queries return proofs that a client should check to validate
+  // the data. Note that if a client only wishes to update to the latest
+  // LedgerInfo and receive the proof of this latest version, they can simply
+  // omit the requested_items (or pass an empty list)
+  rpc UpdateToLatestLedger(
+      types.UpdateToLatestLedgerRequest)
+      returns (types.UpdateToLatestLedgerResponse) {}
+}

data/protos/events.proto

@@ -0,0 +1,38 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// This file contains proto definitions related to events.  Events are emitted
+// by smart contract execution.  These could include events such as received
+// transactions, sent transactions, etc.
+
+syntax = "proto3";
+
+package types;
+
+import "access_path.proto";
+import "proof.proto";
+
+// An event emitted from a smart contract
+message Event {
+    AccessPath access_path = 1;
+    uint64 sequence_number = 2;
+    bytes event_data = 3;
+}
+
+// An event along with the proof for the event
+message EventWithProof {
+  uint64 transaction_version = 1;
+  uint64 event_index = 2;
+  Event event = 3;
+  EventProof proof = 4;
+}
+
+// A list of events.
+message EventsList {
+  repeated Event events = 1;
+}
+
+// A list of EventList's, each representing all events for a transaction.
+message EventsForVersions {
+    repeated EventsList events_for_version = 1;
+}

data/protos/get_with_proof.proto

@@ -0,0 +1,310 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// This file contains proto definitions for performing queries and getting back
+// results with proofs.  This is the interface for a client to query data from
+// the system. Every query result must include proof so that a client can be
+// certain that the data returned is valid.  A client must verify this proof to
+// ensure that a node isn't lying to them.
+
+// How to verify the response as a client:
+// (Note that every response comes in the form of GetWithProofResponse which
+// wraps the inner response elements that correspond to the specific request
+// types.  Below we will assume a single request/response type.  The
+// verification can be extended as needed for multiple types. Also note that we
+// will use the following notation: resp = GetWithProofResponse and req =
+// GetWithProofRequest). Also note that the following will be considered
+// equivalent for brevity: req.requested_items.get_account_state_request ==
+// req.get_account_state_request And, resp.values.get_account_state_response ==
+// resp.get_account_state_response
+//
+// GetAccountStateResponse:
+// - let state_req = req.requested_items.get_account_state_request;
+// - let state_resp = resp.values.get_account_state_response;
+// - Verify that:
+//      - state_req.access_path == state_resp.access_path
+//          - This ensures that the server is responding with the correct access
+//          path
+// - let state_data_hash = Hash(state_resp.value);
+// - let state_proof = resp.values.proof.state_proof_value.sparse_merkle_proof;
+// - Validate state_proof using state_data_hash as the leaf
+//      - When verifying the state tree, use:
+//          state_root_hash = resp.values.transaction_info.state_root_hash
+// - Validate accumulator using resp.values.transaction_info as the leaf
+//      - When verifying the accumulator, use:
+//          root_hash =
+//          resp.ledger_info_with_sigs.ledger_info.ledger_info.txn_root_hash;
+// - Validate that the transaction root hash submitted in
+// req.known_value.node_value.txn_root_hash
+//      exists in the proof for accumulator and that the proof is valid with
+//      this hash
+// - Validate ledger info
+//      - let ledger_info_hash =
+//      Hash(resp.ledger_info_with_sigs.ledger_info.ledger_info);
+//      - Verify signatures from resp.ledger_info_with_sigs.signatures are
+//      signing
+//          ledger_info_hash and that there are >2/3 nodes signing this
+//          correctly
+//      - Validate that the timestamp is relatively recent in
+//          resp.ledger_info_with_sigs.ledger_info.timestamp
+//
+//
+// GetAccountTransactionBySequenceNumberResponse:
+// - Note that other than type completed_transaction, there will be no proof
+// returned
+//      since the transaction has not yet been committed.  To ensure that a
+//      validator is telling the truth about it not being committed yet, a
+//      client should query for their account state and verify that their
+//      current sequence number is less than what they are searching for with
+//      GetAccountTransactionBySequenceNumberResponse
+// - let txn =
+//      resp.get_account_transaction_by_sequence_number_response.transaction.committed_transaction;
+// - let txn_hash = Hash(txn);
+// - Verify that resp.proof.transaction_info.signed_transaction_hash == txn_hash
+// - Validate accumulator using resp.proof.transaction_info as the leaf
+//      - When verifying the accumulator, use:
+//          root_hash =
+//          resp.ledger_info_with_sigs.ledger_info.ledger_info.txn_root_hash;
+// - Validate that the transaction root hash submitted in
+// req.known_value.node_value.txn_root_hash
+//      exists in the proof for accumulator and that the proof is valid with
+//      this hash
+// - Validate ledger info
+//      - let ledger_info_hash =
+//      Hash(resp.ledger_info_with_sigs.ledger_info.ledger_info);
+//      - Verify signatures from resp.ledger_info_with_sigs.signatures are
+//      signing
+//          ledger_info_hash and that there are >2/3 nodes signing this
+//          correctly
+//      - Validate that the timestamp is relatively recent in
+//          resp.ledger_info_with_sigs.ledger_info.timestamp
+//
+//
+// GetTransactionsResponse:
+// - for txn in resp.get_transactions_response.transactions:
+//      - let txn = txn.committed_transaction;
+//      - let txn_hash = Hash(txn);
+//      - Verify that txn.proof.transaction_info.signed_transaction_hash ==
+//      txn_hash
+//      - Validate accumulator using txn.proof.transaction_info as the leaf
+//      - When verifying the accumulator, use:
+//          root_hash =
+//          resp.ledger_info_with_sigs.ledger_info.ledger_info.txn_root_hash;
+//      - Verify that transactions are sequential and none are missing
+// - Validate ledger info
+//      - let ledger_info_hash =
+//      Hash(resp.ledger_info_with_sigs.ledger_info.ledger_info);
+//      - Verify signatures from resp.ledger_info_with_sigs.signatures are
+//      signing
+//          ledger_info_hash and that there are >2/3 nodes signing this
+//          correctly
+//      - Validate that the timestamp is relatively recent in
+//          resp.ledger_info_with_sigs.ledger_info.timestamp
+// - If the number of transactions returned is less than limit for an ascending
+// query
+//      or if the requested offset > current version for a descending query,
+//      the client should verify that the timestamp in ledger info is relatively
+//      recent to determine if it is likely that all transactions available were
+//      returned
+syntax = "proto3";
+
+package types;
+
+import "access_path.proto";
+import "account_state_blob.proto";
+import "events.proto";
+import "ledger_info.proto";
+import "transaction.proto";
+import "validator_change.proto";
+
+// -----------------------------------------------------------------------------
+// ---------------- Update to latest ledger request
+// -----------------------------------------------------------------------------
+
+// This API is used to update the client to the latest ledger version and
+// optionally also request 1..n other pieces of data.  This allows for batch
+// queries.  All queries return proofs that a client should check to validate
+// the data.
+//
+// Note that if a client only wishes to update to the latest LedgerInfo and
+// receive the proof that this latest ledger extends the client_known_version
+// ledger the client had, they can simply set the requested_items to an empty
+// list.
+message UpdateToLatestLedgerRequest {
+    // This is the version the client already trusts. Usually the client should
+    // set this to the version it obtained the last time it synced with the
+    // chain. If this is the first time ever the client sends a request, it must
+    // use the waypoint hard-coded in its software.
+    uint64 client_known_version = 1;
+
+    // The items for which we are requesting data in this API call.
+    repeated RequestItem requested_items = 2;
+}
+
+message RequestItem {
+    oneof requested_items {
+        GetAccountStateRequest get_account_state_request = 1;
+        GetAccountTransactionBySequenceNumberRequest
+        get_account_transaction_by_sequence_number_request = 2;
+        GetEventsByEventAccessPathRequest get_events_by_event_access_path_request =
+        3;
+        GetTransactionsRequest get_transactions_request = 4;
+    }
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Update to latest ledger response
+// -----------------------------------------------------------------------------
+
+// Response from getting latest ledger
+message UpdateToLatestLedgerResponse {
+    // Responses to the queries posed by the requests. The proofs generated will
+    // be relative to the version of the latest ledger provided below.
+    repeated ResponseItem response_items = 1;
+
+    // The latest ledger info this node has. It will come with at least 2f+1
+    // validator signatures as well as a proof that shows the latest ledger
+    // extends the old ledger the client had.
+    LedgerInfoWithSignatures ledger_info_with_sigs = 2;
+
+    // Validator change events from what the client last knew.  This is used to
+    // inform the client of validator changes from the client's last known version
+    // until the current version
+    repeated ValidatorChangeEventWithProof validator_change_events = 3;
+}
+
+// Individual response items to the queries posed by the requests
+message ResponseItem {
+    oneof response_items {
+        GetAccountStateResponse get_account_state_response = 3;
+        GetAccountTransactionBySequenceNumberResponse
+            get_account_transaction_by_sequence_number_response = 4;
+        GetEventsByEventAccessPathResponse get_events_by_event_access_path_response = 5;
+        GetTransactionsResponse get_transactions_response = 6;
+    }
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Get account state (balance, sequence number, etc.)
+// -----------------------------------------------------------------------------
+
+// Gets latest state for an account.
+message GetAccountStateRequest {
+    // Account for which we are fetching the state.
+    bytes address = 1;
+}
+
+// State information returned by a get account state query.
+message GetAccountStateResponse {
+    // Blob value representing the account state together with proof the client
+    // can utilize to verify it.
+    AccountStateWithProof account_state_with_proof = 1;
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Get single transaction by account + sequence number
+// -----------------------------------------------------------------------------
+// Get transactions that altered an account - this includes both sent and
+// received. A user of this should check that the data returned matches what
+// they expect.  As an example, a potential attack vector would be something
+// like the following: Alice is buying an apple from Bob. Alice's phone signs a
+// transaction X with sequence number N that pays coins to Bob. Alice transmits
+// this signature to Bob's payment terminal which then submits the transaction
+// and checks its status to see if Alice can be given the apple. However, as Bob
+// is doing this Alice constructs a second transaction X' also with sequence
+// number N. Alice gets that transaction inserted in the blockchain. If Bob
+// isn't thoughtful about how he uses this API he may assume that if he asks for
+// the N'th transaction on Alice's account that when the API returns that this
+// means the transaction has gone through. The point here is that one should be
+// careful in reading too much into "transaction X is on the chain" and focus on
+// the logs, which tell you what the transaction did.
+//
+// If a client submitted a transaction, they should also verify that the hash of
+// the returned transaction matches what they submitted.  As an example, if a
+// client has two wallets that share the same account, they may both submit a
+// transaction at the same sequence number and only one will be committed.  A
+// client should never assume that if they receive the response that this
+// transaction was included that it means that this is definitely the
+// transaction that was submitted.  They should check that the hash matches what
+// they sent
+message GetAccountTransactionBySequenceNumberRequest {
+    // Account for which to query transactions
+    bytes account = 1;
+
+    uint64 sequence_number = 2;
+
+    // Set to true to fetch events for the transaction at this version
+    bool fetch_events = 3;
+}
+
+// Transaction information for transactions requested by
+// GetAccountTransactionsRequest
+message GetAccountTransactionBySequenceNumberResponse {
+  // When the transaction requested is committed, return the committed
+  // transaction with proof.
+  SignedTransactionWithProof signed_transaction_with_proof = 2;
+  // When the transaction requested is not committed, we give a proof that
+  // shows the current sequence number is smaller than what would have been if
+  // the transaction was committed.
+  AccountStateWithProof proof_of_current_sequence_number = 3;
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Get events by event access path
+// -----------------------------------------------------------------------------
+
+// Get events that exist on an event access path.  In the current world,
+// a user may specify events that were received, events that were sent, or any
+// event that modifies their account
+message GetEventsByEventAccessPathRequest {
+    AccessPath access_path = 1;
+
+    // The sequence number of the event to start with for this query. Use a
+    // sequence number of MAX_INT to represent the latest.
+    uint64 start_event_seq_num = 2;
+
+    // If ascending is true this query will return up to `limit` events that were
+    // emitted after `start_event_seq_num`. Otherwise it will return up to `limit`
+    // events before the offset. Both cases are inclusive.
+    bool ascending = 3;
+
+    // Limit number of results
+    uint64 limit = 4;
+}
+
+message GetEventsByEventAccessPathResponse {
+    // Returns an event and proof of each of the events in the request. The first
+    // element of proofs will be the closest to `start_event_seq_num`.
+    repeated EventWithProof events_with_proof = 1;
+
+    // If the number of events returned is less than `limit` for an ascending
+    // query or if start_event_seq_num > the latest seq_num for a descending
+    // query,  returns the state of the account containing the given access path
+    // in the latest state. This allows the client to verify that there are in
+    // fact no extra events.
+    //
+    // The LedgerInfoWithSignatures which is on the main
+    // UpdateToLatestLedgerResponse can be used to validate this.
+    AccountStateWithProof proof_of_latest_event = 2;
+}
+
+// -----------------------------------------------------------------------------
+// ---------------- Get transactions
+// -----------------------------------------------------------------------------
+
+// Get up to limit transactions starting from start_version.
+message GetTransactionsRequest {
+    // The version of the transaction to start with for this query.  Use a version
+    // of MAX_INT to represent the latest.
+    uint64 start_version = 1;
+
+    // Limit number of results
+    uint64 limit = 2;
+
+    // Set to true to fetch events for the transaction at each version
+    bool fetch_events = 3;
+}
+
+message GetTransactionsResponse {
+    TransactionListWithProof txn_list_with_proof = 1;
+}