The Libra Blockchain is a cryptographically authenticated distributed database, and it is based on the Libra protocol. This document briefly describes the key concepts of the Libra protocol. For a detailed description of all the elements of the Libra protocol, refer to the Libra Blockchain technical paper.
The Libra Blockchain is maintained by a distributed network of validator nodes, also known as validators. The validators collectively follow a consensus protocol to agree on an ordering of transactions in the blockchain.
The Libra testnet is a demonstration of an early prototype of the Libra Blockchain software — Libra Core.
Transactions and States
At the heart of the Libra protocol are two fundamental concepts — transactions and states. At any point in time, the blockchain has a “state.” The state (or ledger state) represents the current snapshot of data on the chain. Executing a transaction changes the state of the blockchain.
Figure 1.1 Transactions change state.
Figure 1.1 represents the change of state of the Libra Blockchain that occurs when a transaction is executed. For example, at state SN-1, Alice has a balance of 110 LBR, and Bob has a balance of 52 LBR. When a transaction is applied to the blockchain, it generates a new state. To transition from SN-1 to SN, transaction TN is applied against the state SN-1. This causes Alice’s balance to be reduced by 10 LBR and Bob’s balance to be increased by 10 LBR. The new state SN now shows these updated balances. In figure 1.1:
- A and B represent Alice’s and Bob’s accounts in the blockchain.
- SN-1 represents the (N-1)th state of the blockchain.
- TN is the n-th transaction executed on the blockchain.
- In this example, TN is - “send 10 LBR from person A’s account to person B’s account.”
- F is a deterministic function. F always returns the same final state for a specific initial state and a specific transaction. If the current state of the blockchain is SN-1, and transaction TN is executed on state SN-1, the new state of the blockchain is always SN.
- SN is the n-th state of the blockchain. SN is an outcome of applying F to SN-1 and TN.
The Libra protocol uses the Move language to implement the deterministic execution function F.
Clients of the Libra Blockchain submit transactions to request updates to the ledger state. A signed transaction on the blockchain contains:
- Sender address — Account address of the sender of the transaction.
- Sender public key — The public key that corresponds to the private key used to sign the transaction.
- Program — The program is comprised of the following:
- A Move bytecode transaction script.
- An optional list of inputs to the script. For a peer-to-peer transaction, the inputs contain the information about the recipient and the amount transferred to the recipient.
- An optional list of Move bytecode modules to publish.
- Gas price (in microlibra/gas units) — The amount the sender is willing to pay per unit of gas to execute the transaction. Gas is a way to pay for computation and storage. A gas unit is an abstract measurement of computation with no inherent real-world value.
- Maximum gas amount — The maximum units of gas the transaction is allowed to consume.
- Sequence number — An unsigned integer that must be equal to the sequence number stored under the sender’s account.
- Expiration time — The time after which the transaction ceases to be valid.
- Signature — The digital signature of the sender.
The transaction script is an arbitrary program that encodes the logic of a transaction and interacts with resources published in the distributed database of the Libra Blockchain.
The ledger state, or global state of the Libra Blockchain, is comprised of the state of all accounts in the blockchain. To execute transactions, each validator must know the global state of the latest version of the blockchain's distributed database. See versioned database.
All of the data in the Libra Blockchain is persisted in a single-versioned distributed database. A version number is an unsigned 64-bit integer that corresponds to the number of transactions the system has executed.
The versioned database allows validators to:
- Execute a transaction against the ledger state at the latest version.
- Respond to client queries about ledger history at both current and previous versions.
A Libra account is a container for Move modules and Move resources. It is identified by an account address. This essentially means that the state of each account is comprised of both code and data:
- Move modules contain code (type and procedure declarations), but they do not contain data. The procedures of a module encode the rules for updating the global state of the blockchain.
- Move resources contain data but no code. Every resource value has a type that is declared in a module published in the distributed database of the blockchain.
An account may contain an arbitrary number of Move resources and Move modules.
The address of a Libra account is a 256-bit value. Users can claim addresses using digital signatures. The account address is a cryptographic hash of a user’s public verification key. To sign a transaction sent from their account address, the user (or the custodial client representing the user) must use the private key corresponding to that account.
There is no limit on the number of addresses a Libra user can claim. To claim an account address, a transaction should be sent from an account that holds sufficient Libra to pay the account creation fee.
All of the data in the Libra Blockchain is stored in a single-versioned distributed database. The storage is used to persist agreed upon blocks of transactions and their execution results. The blockchain is represented as an ever-growing Merkle tree of transactions. A “leaf” is appended to the tree for each transaction executed on the blockchain.
- A proof is a way to verify the truth of data in the Libra Blockchain.
- Every operation stored on the blockchain can be verified cryptographically, and the resultant proof also proves that no data has been omitted. For example, if the client queried the latest n transactions from an account, the proof verifies that no transactions are omitted from the query response.
In a blockchain, the client does not need to trust the entity from which it is receiving data. A client could query for the balance of an account, ask whether a specific transaction was processed, and so on. As with other Merkle trees, the ledger history can provide an -sized proof of a specific transaction object, where n is the total number of transactions processed.
Validator Node (Validator)
Clients of the Libra Blockchain create transactions and submit them to a validator node. A validator node runs a consensus protocol (together with other validator nodes), executes the transactions, and stores the transactions and the execution results in the blockchain. Validator nodes decide which transactions will be added to the blockchain and in which order. Figure 1.2 Logical components of a validator.
A validator node contains the following logical components:
Admission Control (AC)
- Admission Control is the sole external interface of the validator node. Any request made by a client to the validator node goes to AC first.
- AC performs initial checks on the requests to protect the other parts of the validator node from corrupt or high volume input.
- Mempool is a buffer that holds the transactions that are “waiting” to be executed.
- When a new transaction is added to a validator node’s mempool, this validator node’s mempool shares this transaction with the mempools of other validators in the system.
- The consensus component is responsible for ordering blocks of transactions and agreeing on the results of execution by participating in the consensus protocol with other validator nodes in the network.
- The execution component utilizes the virtual machine (VM) to execute transactions.
- Execution’s job is to coordinate the execution of a block of transactions and maintain a transient state that can be voted upon by consensus.
- Execution maintains an in-memory representation of the results of execution until consensus commits the block to the distributed database.
Virtual Machine (VM)
- AC and Mempool use the VM component to perform validation checks on transactions.
- VM is used to run the program included in a transaction and determine the results.
The storage is used to persist agreed upon blocks of transactions and their execution results.
For information on interactions of each validator component with other components, refer to Life of a Transaction.
- Welcome Page.
- My First Transaction — Guides you through executing your very first transaction on the Libra Blockchain using the Libra CLI client.
- Getting Started with Move — Introduces you to a new blockchain programming language called Move.
- Life of a Transaction — Provides a look at what happens “under the hood” when a transaction is submitted and executed.
- Libra Core Overview — Provides the concept and implementation details of the Libra Core components through READMEs.
- CLI Guide — Lists the commands (and their usage) of the Libra CLI client.
- Libra Glossary — Provides a quick reference to Libra terminology.