libra_client 0.1.3

data/protos/ledger_info.proto

@@ -0,0 +1,82 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+/// Even though we don't always need all hashes, we pass them in and return them
+/// always so that we keep them in sync on the client and don't make the client
+/// worry about which one(s) to pass in which cases
+///
+/// This structure serves a dual purpose.
+///
+/// First, if this structure is signed by 2f+1 validators it signifies the state
+/// of the ledger at version `version` -- it contains the transaction
+/// accumulator at that version which commits to all historical transactions.
+/// This structure may be expanded to include other information that is derived
+/// from that accumulator (e.g. the current time according to the time contract)
+/// to reduce the number of proofs a client must get.
+///
+/// Second, the structure contains a `consensus_data_hash` value. This is the
+/// hash of an internal data structure that represents a block that is voted on
+/// by consensus.
+///
+/// Combining these two concepts when the consensus algorithm votes on a block B
+/// it votes for a LedgerInfo with the `version` being the latest version that
+/// will be committed if B gets 2f+1 votes. It sets `consensus_data_hash` to
+/// represent B so that if those 2f+1 votes are gathered, the block is valid to
+/// commit
+message LedgerInfo {
+  // Current latest version of the system
+  uint64 version = 1;
+
+  // Root hash of transaction accumulator at this version
+  bytes transaction_accumulator_hash = 2;
+
+  // Hash of consensus-specific data that is opaque to all parts of the system
+  // other than consensus.  This is needed to verify signatures because
+  // consensus signing includes this hash
+  bytes consensus_data_hash = 3;
+
+  // The block id of the last committed block corresponding to this ledger info.
+  // This field is not particularly interesting to the clients, but can be used
+  // by the validators for synchronization.
+  bytes consensus_block_id = 4;
+
+  // Epoch number corresponds to the set of validators that are active for this
+  // ledger info. The main motivation for keeping the epoch number in the
+  // LedgerInfo is to ensure that the client has enough information to verify
+  // that the signatures for this info are coming from the validators that
+  // indeed form a quorum. Without epoch number a potential attack could reuse
+  // the signatures from the validators in one epoch in order to sign the wrong
+  // info belonging to another epoch, in which these validators do not form a
+  // quorum. The very first epoch number is 0.
+  uint64 epoch_num = 5;
+
+  // Timestamp that represents the microseconds since the epoch (unix time) that is
+  // generated by the proposer of the block.  This is strictly increasing with every block.
+  // If a client reads a timestamp > the one they specified for transaction expiration time,
+  // they can be certain that their transaction will never be included in a block in the future
+  // (assuming that their transaction has not yet been included)
+  uint64 timestamp_usecs = 6;
+}
+
+/// The validator node returns this structure which includes signatures
+/// from each validator to confirm the state.  The client needs to only pass
+/// back the LedgerInfo element since the validator node doesn't need to know
+/// the signatures again when the client performs a query, those are only there
+/// for the client to be able to verify the state
+message LedgerInfoWithSignatures {
+  // Signatures of the root node from each validator
+  repeated ValidatorSignature signatures = 1;
+
+  LedgerInfo ledger_info = 2;
+}
+
+message ValidatorSignature {
+  // The account address of the validator, which can be used for retrieving its
+  // public key during the given epoch.
+  bytes validator_id = 1;
+  bytes signature = 2;
+}

data/protos/mempool_status.proto

@@ -0,0 +1,21 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package mempool;
+
+enum MempoolAddTransactionStatus {
+  // Transaction was sent to Mempool
+  Valid = 0;
+  // The sender does not have enough balance for the transaction.
+  InsufficientBalance = 1;
+  // Sequence number is old, etc.
+  InvalidSeqNumber = 2;
+  // Mempool is full (reached max global capacity)
+  MempoolIsFull = 3;
+  // Account reached max capacity per account
+  TooManyTransactions = 4;
+  // Invalid update. Only gas price increase is allowed
+  InvalidUpdate = 5;
+}

data/protos/proof.proto

@@ -0,0 +1,72 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+import "transaction_info.proto";
+
+message AccumulatorProof {
+  // The bitmap indicating which siblings are default. 1 means non-default and
+  // 0 means default. The LSB corresponds to the sibling at the bottom of the
+  // accumulator. The leftmost 1-bit corresponds to the sibling at the level
+  // just below root level in the accumulator, since this one is always
+  // non-default.
+  uint64 bitmap = 1;
+
+  // The non-default siblings. The ones near the root are at the beginning of
+  // the list.
+  repeated bytes non_default_siblings = 2;
+}
+
+message SparseMerkleProof {
+  // This proof can be used to authenticate whether a given leaf exists in the
+  // tree or not. In Rust:
+  //   - If this is `Some(HashValue, HashValue)`
+  //     - If the first `HashValue` equals requested key, this is an inclusion
+  //       proof and the second `HashValue` equals the hash of the
+  //       corresponding account blob.
+  //     - Otherwise this is a non-inclusion proof. The first `HashValue` is
+  //       the only key that exists in the subtree and the second `HashValue`
+  //       equals the hash of the corresponding account blob.
+  //   - If this is `None`, this is also a non-inclusion proof which indicates
+  //     the subtree is empty.
+  //
+  // In protobuf, this leaf field should either be
+  //   - empty, which corresponds to None in the Rust structure.
+  //   - exactly 64 bytes, which corresponds to Some<(HashValue, HashValue)>
+  //     in the Rust structure.
+  bytes leaf = 1;
+
+  // The bitmap indicating which siblings are default. 1 means non-default and
+  // 0 means default. The MSB of the first byte corresponds to the sibling at
+  // the top of the Sparse Merkle Tree. The rightmost 1-bit of the last byte
+  // corresponds to the sibling at the bottom, since this one is always
+  // non-default.
+  bytes bitmap = 2;
+
+  // The non-default siblings. The ones near the root are at the beginning of
+  // the list.
+  repeated bytes non_default_siblings = 3;
+}
+
+// The complete proof used to authenticate a signed transaction.
+message SignedTransactionProof {
+  AccumulatorProof ledger_info_to_transaction_info_proof = 1;
+  TransactionInfo transaction_info = 2;
+}
+
+// The complete proof used to authenticate an account state.
+message AccountStateProof {
+  AccumulatorProof ledger_info_to_transaction_info_proof = 1;
+  TransactionInfo transaction_info = 2;
+  SparseMerkleProof transaction_info_to_account_proof = 3;
+}
+
+// The complete proof used to authenticate an event.
+message EventProof {
+  AccumulatorProof ledger_info_to_transaction_info_proof = 1;
+  TransactionInfo transaction_info = 2;
+  AccumulatorProof transaction_info_to_event_proof = 3;
+}

data/protos/transaction.proto

@@ -0,0 +1,170 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+import "access_path.proto";
+import "events.proto";
+import "proof.proto";
+import "transaction_info.proto";
+import "google/protobuf/wrappers.proto";
+
+// A generic structure that describes a transaction that a client submits
+message RawTransaction {
+    // Sender's account address
+    bytes sender_account = 1;
+    // Sequence number of this transaction corresponding to sender's account.
+    uint64 sequence_number = 2;
+    oneof payload {
+        // The transaction script to execute.
+        Program program = 3;
+        // A write set, used for genesis blocks and other magic transactions.
+        // This bypasses the rules for regular transactions so will typically be
+        // rejected. Only under special circumstances will it be accepted.
+        WriteSet write_set = 4;
+    }
+    // Maximal total gas specified by wallet to spend for this transaction.
+    uint64 max_gas_amount = 5;
+    // The price to be paid for each unit of gas.
+    uint64 gas_unit_price = 6;  
+    // Expiration time for this transaction.  If storage is queried and
+    // the time returned is greater than or equal to this time and this
+    // transaction has not been included, you can be certain that it will
+    // never be included.
+    // If set to 0, there will be no expiration time
+    uint64 expiration_time = 7;
+}
+
+// The code for the transaction to execute
+message Program {
+    bytes code = 1;
+    repeated TransactionArgument arguments = 2;
+    repeated bytes modules = 3;
+}
+
+// An argument to the transaction if the transaction takes arguments
+message TransactionArgument {
+    enum ArgType {
+        U64 = 0;
+        ADDRESS = 1;
+        STRING = 2;
+        BYTEARRAY = 3;
+    }
+    ArgType type = 1;
+    bytes data = 2;
+}
+
+// A generic structure that represents signed RawTransaction
+message SignedTransaction {
+    // The serialized Protobuf bytes for RawTransaction, for which the signature
+    // was signed. Protobuf doesn't guarantee the serialized bytes is canonical
+    // across different language implementations, but for our use cases for
+    // transaction it is not necessary because the client is the only one to
+    // produce this bytes, which is then persisted in storage.
+    bytes raw_txn_bytes = 1;
+    // public key that corresponds to RawTransaction::sender_account
+    bytes sender_public_key = 2;
+    // signature for the hash
+    bytes sender_signature = 3;
+}
+
+message SignedTransactionWithProof {
+    // The version of the returned signed transaction.
+    uint64 version = 1;
+
+    // The transaction itself.
+    SignedTransaction signed_transaction = 2;
+
+    // The proof authenticating the signed transaction.
+    SignedTransactionProof proof = 3;
+
+    // The events yielded by executing the transaction, if requested.
+    EventsList events = 4;
+}
+
+// A generic structure that represents a block of transactions originated from a
+// particular validator instance.
+message SignedTransactionsBlock {
+    // Set of Signed Transactions
+    repeated SignedTransaction transactions = 1;
+    // Public key of the validator that created this block
+    bytes validator_public_key = 2;
+    // Signature of the validator that created this block
+    bytes validator_signature = 3;
+}
+
+// Set of WriteOps to save to storage.
+message WriteSet {
+    // Set of WriteOp for storage update.
+    repeated WriteOp write_set = 1;
+}
+
+// Write Operation on underlying storage.
+message WriteOp {
+    // AccessPath of the write set.
+    AccessPath access_path = 1;
+    // The value of the write op. Empty if `type` is Delete.
+    bytes value = 2;
+    // WriteOp type.
+    WriteOpType type = 3;
+}
+
+// Type of write operation
+enum WriteOpType {
+    // The WriteOp is to create/update the field from storage.
+    Write = 0;
+    // The WriteOp is to delete the field from storage.
+    Delete = 1;
+}
+
+// Account state as a whole.
+// After execution, updates to accounts are passed in this form to storage for
+// persistence.
+message AccountState {
+    // Account address
+    bytes address = 1;
+    // Account state blob
+    bytes blob = 2;
+}
+
+// Transaction struct to commit to storage
+message TransactionToCommit {
+    // The signed transaction which was executed
+    SignedTransaction signed_txn = 1;
+    // State db updates
+    repeated AccountState account_states = 2;
+    // Events yielded by the transaction.
+    repeated Event events = 3;
+    // The amount of gas used.
+    uint64 gas_used = 4;
+}
+
+// A list of consecutive transactions with proof. This is mainly used for state
+// synchronization when a validator would request a list of transactions from a
+// peer, verify the proof, execute the transactions and persist them. Note that
+// the transactions are supposed to belong to the same epoch E, otherwise
+// verification will fail.
+message TransactionListWithProof {
+    // The list of transactions.
+    repeated SignedTransaction transactions = 1;
+
+    // The list of corresponding TransactionInfo objects.
+    repeated TransactionInfo infos = 2;
+
+    // The list of corresponding Event objects (only present if fetch_events was set to true in req)
+    EventsForVersions events_for_versions = 3;
+
+    // If the list is not empty, the version of the first transaction.
+    google.protobuf.UInt64Value first_transaction_version = 4;
+
+    // The proofs of the first and last transaction in this chunk. When this is
+    // used for state synchronization, the validator who requests the transactions
+    // will provide a version in the request and the proofs will be relative to
+    // the given version. When this is returned in GetTransactionsResponse, the
+    // proofs will be relative to the ledger info returned in
+    // UpdateToLatestLedgerResponse.
+    AccumulatorProof proof_of_first_transaction = 5;
+    AccumulatorProof proof_of_last_transaction = 6;
+}

data/protos/transaction_info.proto

@@ -0,0 +1,26 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+// `TransactionInfo` is the object we store in the transaction accumulator. It
+// consists of the transaction as well as the execution result of this
+// transaction. This are later returned to the client so that a client can
+// validate the tree
+message TransactionInfo {
+  // Hash of the signed transaction that is stored
+  bytes signed_transaction_hash = 1;
+
+  // The root hash of Sparse Merkle Tree describing the world state at the end
+  // of this transaction
+  bytes state_root_hash = 2;
+
+  // The root hash of Merkle Accumulator storing all events emitted during this
+  // transaction.
+  bytes event_root_hash = 3;
+
+  // The amount of gas used by this transaction.
+  uint64 gas_used = 4;
+}

data/protos/validator_change.proto

@@ -0,0 +1,27 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+import "events.proto";
+import "ledger_info.proto";
+
+// This is used to prove validator changes.  When a validator is changing, it
+// triggers an event on /validator_change_account/events/sent.  To tell the
+// client about validator changes, we query
+// /validator_change_account/events/sent to get all versions that contain
+// validator changes after the version that we are trying to update from. For
+// each of these versions, the old validator set would have signed the ledger
+// info at that version.  The client needs this as well as the event results +
+// proof.  The client can then verify that these events were under the current
+// tree and that the changes were signed by the old validators (and that the
+// events correctly show which validators are the new validators).
+//
+// This message represents a single validator change event and the proof that
+// corresponds to it
+message ValidatorChangeEventWithProof {
+  LedgerInfoWithSignatures ledger_info_with_sigs = 1;
+  EventWithProof event_with_proof = 2;
+}

data/protos/vm_errors.proto

@@ -0,0 +1,276 @@
+// Copyright (c) The Libra Core Contributors
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package types;
+
+// The statuses and errors produced by the VM can be categorized into a
+// couple different types:
+// 1. Validation Statuses: all the errors that can (/should) be
+//    the result of executing the prologue -- these are primarily used by
+//    the vm validator and AC.
+// 2. Verification Errors: errors that are the result of performing
+//    bytecode verification (happens at the time of publishing).
+// 3. VM Invariant Errors: errors that arise from an internal invariant of
+//    the VM being violated. These signify a problem with either the VM or
+//    bytecode verifier.
+// 4. Binary Errors: errors that can occur during the process of
+//    deserialization of a transaction.
+// 5. Runtime Statuses: errors that can arise from the execution of a
+//    transaction (assuming the prologue executes without error). These are
+//    errors that can occur during execution due to things such as division
+//    by zero, running out of gas, etc. These do not signify an issue with
+//    the VM.
+
+// NB: we make a distinction between a status and an error here: A
+// status contains errors, along with possible affirmation of a successful
+// execution or valid prologue.
+
+// The status of a transaction as determined by the prologue.
+enum VMValidationStatusCode {
+    // We don't want the default value to be valid
+    UnknownValidationStatus = 0;
+    // The transaction has a bad signature
+    InvalidSignature = 1;
+    // Bad account authentication key
+    InvalidAuthKey = 2;
+    // Sequence number is too old
+    SequenceNumberTooOld = 3;
+    // Sequence number is too new
+    SequenceNumberTooNew = 4;
+    // Insufficient balance to pay minimum transaction fee
+    InsufficientBalanceForTransactionFee = 5;
+    // The transaction has expired
+    TransactionExpired = 6;
+    // The sending account does not exist
+    SendingAccountDoesNotExist = 7;
+    // This write set transaction was rejected because it did not meet the
+    // requirements for one.
+    RejectedWriteSet = 8;
+    // This write set transaction cannot be applied to the current state.
+    InvalidWriteSet = 9;
+    // Length of program field in raw transaction exceeded max length
+    ExceededMaxTransactionSize = 10;
+    // This script is not on our whitelist of script.
+    UnknownScript = 11;
+    // Transaction is trying to publish a new module.
+    UnknownModule = 12;
+    // Max gas units submitted with transaction exceeds max gas units bound
+    // in VM
+    MaxGasUnitsExceedsMaxGasUnitsBound = 13;
+    // Max gas units submitted with transaction not enough to cover the
+    // intrinsic cost of the transaction.
+    MaxGasUnitsBelowMinTransactionGasUnits = 14;
+    // Gas unit price submitted with transaction is below minimum gas price
+    // set in the VM.
+    GasUnitPriceBelowMinBound = 15;
+    // Gas unit price submitted with the transaction is above the maximum
+    // gas price set in the VM.
+    GasUnitPriceAboveMaxBound = 16;
+}
+
+message VMValidationStatus {
+  VMValidationStatusCode code = 1;
+  string message = 2;
+}
+
+message VMVerificationStatusList {
+    repeated VMVerificationStatus status_list = 1;
+}
+
+message VMVerificationStatus {
+    enum StatusKind {
+        SCRIPT = 0;
+        MODULE = 1;
+    }
+    StatusKind status_kind = 1;
+    // For StatusKind::SCRIPT this is ignored.
+    uint32 module_idx = 2;
+    VMVerificationErrorKind error_kind = 3;
+    string message = 4;
+}
+
+// When a code module/script is published it is verified. These are the
+// possible errors that can arise from the verification process.
+enum VMVerificationErrorKind {
+    // Likewise default to a unknown verification error
+    UnknownVerificationError = 0;
+    IndexOutOfBounds = 1;
+    RangeOutOfBounds = 2;
+    InvalidSignatureToken = 3;
+    InvalidFieldDefReference = 4;
+    RecursiveStructDefinition = 5;
+    InvalidResourceField = 6;
+    InvalidFallThrough = 7;
+    JoinFailure = 8;
+    NegativeStackSizeWithinBlock = 9;
+    UnbalancedStack = 10;
+    InvalidMainFunctionSignature = 11;
+    DuplicateElement = 12;
+    InvalidModuleHandle = 13;
+    UnimplementedHandle = 14;
+    InconsistentFields = 15;
+    UnusedFields = 16;
+    LookupFailed = 17;
+    VisibilityMismatch = 18;
+    TypeResolutionFailure = 19;
+    TypeMismatch = 20;
+    MissingDependency = 21;
+    PopReferenceError = 22;
+    PopResourceError = 23;
+    ReleaseRefTypeMismatchError = 24;
+    BrTypeMismatchError = 25;
+    AssertTypeMismatchError = 26;
+    StLocTypeMismatchError = 27;
+    StLocUnsafeToDestroyError = 28;
+    RetUnsafeToDestroyError = 29;
+    RetTypeMismatchError = 30;
+    FreezeRefTypeMismatchError = 31;
+    FreezeRefExistsMutableBorrowError = 32;
+    BorrowFieldTypeMismatchError = 33;
+    BorrowFieldBadFieldError = 34;
+    BorrowFieldExistsMutableBorrowError = 35;
+    CopyLocUnavailableError = 36;
+    CopyLocResourceError = 37;
+    CopyLocExistsBorrowError = 38;
+    MoveLocUnavailableError = 39;
+    MoveLocExistsBorrowError = 40;
+    BorrowLocReferenceError = 41;
+    BorrowLocUnavailableError = 42;
+    BorrowLocExistsBorrowError = 43;
+    CallTypeMismatchError = 44;
+    CallBorrowedMutableReferenceError = 45;
+    PackTypeMismatchError = 46;
+    UnpackTypeMismatchError = 47;
+    ReadRefTypeMismatchError = 48;
+    ReadRefResourceError = 49;
+    ReadRefExistsMutableBorrowError = 50;
+    WriteRefTypeMismatchError = 51;
+    WriteRefResourceError = 52;
+    WriteRefExistsBorrowError = 53;
+    WriteRefNoMutableReferenceError = 54;
+    IntegerOpTypeMismatchError = 55;
+    BooleanOpTypeMismatchError = 56;
+    EqualityOpTypeMismatchError = 57;
+    ExistsResourceTypeMismatchError = 58;
+    BorrowGlobalTypeMismatchError = 59;
+    BorrowGlobalNoResourceError = 60;
+    MoveFromTypeMismatchError = 61;
+    MoveFromNoResourceError = 62;
+    MoveToSenderTypeMismatchError = 63;
+    MoveToSenderNoResourceError = 64;
+    CreateAccountTypeMismatchError = 65;
+    // The self address of a module the transaction is publishing is not the sender address
+    ModuleAddressDoesNotMatchSender = 66;
+    // The module does not have any module handles. Each module or script must have at least one module handle.
+    NoModuleHandles = 67;
+}
+
+// These are errors that the VM might raise if a violation of internal
+// invariants takes place.
+enum VMInvariantViolationError {
+    UnknownInvariantViolationError = 0;
+    OutOfBoundsIndex = 1;
+    OutOfBoundsRange = 2;
+    EmptyValueStack = 3;
+    EmptyCallStack = 4;
+    PCOverflow = 5;
+    LinkerError = 6;
+    LocalReferenceError = 7;
+    StorageError = 8;
+}
+
+// Errors that can arise from binary decoding (deserialization)
+enum BinaryError {
+    UnknownBinaryError = 0;
+    Malformed = 1;
+    BadMagic = 2;
+    UnknownVersion = 3;
+    UnknownTableType = 4;
+    UnknownSignatureType = 5;
+    UnknownSerializedType = 6;
+    UnknownOpcode = 7;
+    BadHeaderTable = 8;
+    UnexpectedSignatureType = 9;
+    DuplicateTable = 10;
+}
+
+//*************************
+// Runtime errors/status
+//*************************
+
+enum RuntimeStatus {
+    UnknownRuntimeStatus = 0;
+    Executed = 1;
+    OutOfGas = 2;
+    // We tried to access a resource that does not exist under the account.
+    ResourceDoesNotExist = 3;
+    // We tried to create a resource under an account where that resource
+    // already exists.
+    ResourceAlreadyExists = 4;
+    // We accessed an account that is evicted.
+    EvictedAccountAccess = 5;
+    // We tried to create an account at an address where an account already
+    // exists.
+    AccountAddressAlreadyExists = 6;
+    TypeError = 7;
+    MissingData = 8;
+    DataFormatError = 9;
+    InvalidData = 10;
+    RemoteDataError = 11;
+    CannotWriteExistingResource = 12;
+    ValueSerializationError = 13;
+    ValueDeserializationError = 14;
+    // The sender is trying to publish a module named `M`, but the sender's account already contains
+    // a module with this name.
+    DuplicateModuleName = 15;
+}
+
+// user-defined assertion error code number
+message AssertionFailure {
+    uint64 assertion_error_code = 1;
+}
+
+message ArithmeticError {
+    enum ArithmeticErrorType {
+        UnknownArithmeticError = 0;
+        Underflow = 1;
+        Overflow = 2;
+        DivisionByZero = 3;
+        // Fill with more later
+    }
+    ArithmeticErrorType error_code = 1;
+}
+
+message DynamicReferenceError {
+    enum DynamicReferenceErrorType {
+        UnknownDynamicReferenceError = 0;
+        MoveOfBorrowedResource = 1;
+        GlobalRefAlreadyReleased = 2;
+        MissingReleaseRef = 3;
+        GlobalAlreadyBorrowed = 4;
+        // Fill with with more later
+    }
+    DynamicReferenceErrorType error_code = 1;
+}
+
+message ExecutionStatus {
+    oneof execution_status {
+        RuntimeStatus runtime_status = 1;
+        AssertionFailure assertion_failure = 2;
+        ArithmeticError arithmetic_error = 3;
+        DynamicReferenceError reference_error = 4;
+    }
+}
+
+// The status of the VM
+message VMStatus {
+    oneof error_type {
+        VMValidationStatus validation = 1;
+        VMVerificationStatusList verification = 2;
+        VMInvariantViolationError invariant_violation = 3;
+        BinaryError deserialization = 4;
+        ExecutionStatus execution = 5;
+    }
+}