Full node basics: an introduction to full nodes in the Libra network

January 23, 2020

Libra Engineering Team

Note: Libra Core software is still under development; the information and the terminology used in this document are subject to change.

This is the first post in a series on full nodes in the Libra network. Our goal for this post is to introduce the basic concepts associated with full nodes and talk about the motivation behind full nodes. A Libra node is a peer entity that participates in the Libra network and tracks the state of the Libra Blockchain. Libra clients (e.g., wallet applications) interact with the Libra Blockchain via Libra nodes. There are two types of nodes in the Libra network: full nodes and validator nodes. The Libra protocol can be configured to run either as a validator node or as a full node.

The functionality of being a validator and being a full node are related. For example, before joining the set of validators, a new validator will often run as a full node in order to synchronize to the blockchain. An entity that was formerly a validator, but has exited the validator set, might continue operation as a full node.

Why are full nodes important?

  • Full nodes ("FNs") enable external validation of blockchain correctness. FNs revalidate and replay all the transactions committed by validators when they synchronize to the current state of the blockchain. This allows full nodes to ensure that transactions have been executed according to the rules of the protocol.
  • FNs make it easier to scale read traffic. They serve read queries from clients.
  • FNs enable greater insight into the blockchain for third-party blockchain applications such as explorers, wallets, exchanges, and so on. If an entity (e.g., an exchange or a wallet) runs a full node, that entity can:
    • Get a consistent view of the Libra network
    • Avoid rate limitations on read traffic
    • Run custom analytics on historical data
    • Get notifications about particular on-chain events
  • FNs protect validators from Distributed Denial of Service (DDoS) attacks.

Who runs Libra full nodes?

It's important to understand that all full nodes have the same functionality and store the same data, irrespective of who runs them. The accuracy of the data stored by full nodes is authenticated by validators. So, who might run full nodes?

  • A wallet or exchange might run a full node to handle traffic from its own internal services, avoiding the need to rely on an external service.
  • A validator might run a full node to scale the operations of that validator.
  • An entity might also decide to run a full node as a public service to:
    • Provide a scalable public read/write infrastructure
    • Provide a public history of the blockchain and safeguard the blockchain against forks and invalid protocol changes

When would a Libra client interact with a full node?

Libra clients (e.g., wallet applications) use full nodes to access information from the Libra Blockchain. If a Libra validator operates a set of full nodes, a Libra client interacts with those full nodes instead of directly interacting with the validator itself.

  • A full node can answer all read queries from clients without interacting with validators.
  • A full node proxies write requests (e.g., transaction submissions) from clients to the validator associated with the full node.

What's the difference between validator nodes and full nodes?

Validator nodesFull nodes
Are run by members of the validator set (i.e., Libra Association Members)Are run by anybody
Validate transactions as part of the consensus process that is part of the operation of the Libra BlockchainValidate transactions as a part of synchronizing to the Libra Blockchain from validators
Are focused on writes — they accept transactions from clients and insert them into the Libra BlockchainAre focused on reads — they can handle queries from clients and provide scale for the validators
Provide signatures that authenticate the state of the Libra BlockchainRely on validator signatures to prove the correctness of their results to clients
Are only required to have knowledge of the current state of the blockchainMaintain historical information about the state of the blockchain

Note: A read query is a request to fetch the current state of the blockchain (e.g., account balance, last transactions, etc.). A write request is the submission of a new transaction.

Does a full node stay synchronized with the blockchain?

A full node synchronizes to the latest state of the blockchain when:

  • It comes online for the first time (bootstrap)
  • It restarts
  • It comes online after being offline for some time
  • After a network partition heals

During normal FN workload, FNs synchronize with their upstream nodes continuously using the StateSynchronizer protocol.

What's next?

In a future post in this series, we'll talk about running full nodes on the Libra network.

Steering committee now governs Libra technical development

January 16, 2020

Michael Engle, Libra Association

On December 16, 2019, the council of the Libra Association voted to establish a Technical Steering Committee (TSC) for the Libra project and elected five members that each contribute a unique perspective and bring valuable domain expertise to the project.

The role of the TSC is to oversee and coordinate the technical design and development of the Libra network. Responsibilities include:

  • Directing the technical roadmap for the Libra network
  • Forming Technical Working Groups to fast-track research into selected specific issues
  • Guiding codebase development
  • Building a healthy and engaged Libra developer community

Establishing an independent TSC that is responsible for technical development of the Libra network is an important step forward for the Libra project. It has always been the Association's vision that the Libra project would be self-governing and independent of any one organization's control.

As a project rooted in technological innovation, technical stewardship is a significant component of self-governance for the Libra project. In Q1 2020, the TSC will publish its technical governance framework and associated documents. This will include the process by which the open source community can propose technical changes to the network and a transparent process for evaluating those proposals.

Meet the TSC members

Diogo Monica, Co-Founder and President at Anchorage. Diogo is the President and co-founder of Anchorage, an industry-leading digital asset custodian. He holds a Ph.D. in computer science from the Technical University of Lisbon, has worked in software security for over 15 years, and is a published author of several peer-reviewed papers in distributed systems and information security. As an early employee at Square, Diogo led the platform security team that built the infrastructure that Square uses today, in the process developing widely recognized best-in-class production security practices. At Docker, he built and led the security team, and his code today helps secure hundreds of millions of servers worldwide as one of the core underpinnings of modern infrastructure: containers.

"For the Libra Blockchain to serve billions of users worldwide, security must be its foundation. We are using the best of modern security engineering to prepare the Libra network to operate on a global scale." - Diogo Monica

George Cabrera III, Libra Core Product Lead at Calibra. George, a 20-year software engineering veteran, has been working as the product lead for Libra Core for over a year. In the past, George worked as a technical lead at Network Appliance and at Facebook in the Core Data team designing Facebook's core caching system. He also spent three years leading the technical integration of both Instagram and WhatsApp into Facebook. He then moved onto helping create the Telecom Infra Project and Facebook's Connectivity team. Finally, as an early team member, he supported the Libra project as a product manager to and through the delivery of the Libra testnet and continues in his role as one of the most senior technical staff in Calibra.

"The Libra Association's mission is to be a financial infrastructure that empowers billions of people, and having a group to guide the design, building, and ongoing maintenance of that infrastructure is vital to its success. The creation of this committee represents a notable milestone for Libra's openness and sustainability as we forge ahead towards our mainnet launch." - George Cabrera III

Joe Lallouz, CEO and Founder at Bison Trails. Joe is the CEO of Bison Trails, an industry-leading blockchain infrastructure company and developer of a protocol-agnostic infrastructure platform committed to democratizing access to blockchain networks. Under Joe's leadership, Bison Trails built a reputation as a trusted partner for protocol teams working to develop and deploy new blockchain projects. Joe is one of the world's experts on blockchain network scalability, security, and decentralization: critical areas to a network's adoption and success. As a Libra Association Member, Bison Trails launched the first validator node on the Libra testnet after Calibra and is actively engaged supporting the protocol's development.

"Our goal is to ensure the Libra network is decentralized, secure, and well-orchestrated, with the infrastructure in place to support billions of transactions. This aligns well with our vision of democratizing access to the decentralized future." - Joe Lallouz

Nick Grossman, Partner at Union Square Ventures. Nick is a partner at Union Square Ventures, an early stage venture capital firm with a long track record of investments in areas including social networking, developer tools, fintech, and cryptocurrency/blockchain infrastructure. Nick has extensive experience leading and advising startups, particularly around security, data, privacy, and regulatory issues. Previously, he led an incubator for startups at the intersection of cities and data at OpenPlans, with a focus on leading open source projects, building open data platforms, and supporting open standards efforts. Nick has an undergraduate degree from Stanford University, and has held academic affiliations at the MIT Media Lab and Harvard Law School.

"Libra has the potential to be a breakthrough project in the digital asset and payments space. To achieve this potential, the project must demonstrate credible independence and be welcoming to potential partners and contributors." - Nick Grossman

Ric Shreves, Director, Emerging Technology at Mercy Corps. In his role as Director of Emerging Technology at Mercy Corps, Ric explores new approaches and innovations for humanitarian aid and development, including the potential of distributed ledgers and digital currencies. Before joining Mercy Corps, Ric worked for two decades as an IT consultant and author of over a dozen books on open source technologies. His clients included BASF, The Economist Group, the Stock Exchange of Thailand, Colgate-Palmolive, and many others. In 2008, Ric served as the President of the market-leading open source content management system, Mambo (The Mambo Foundation), giving him experience with the challenges of managing open source projects and community and developer relations.

"Designed from the outset to be transparent by default, and governed with the philosophy of open source participation, the Libra network represents a unique opportunity to build a financially inclusive world." - Ric Shreves

What's next

Watch this space to learn more about our technical governance. We will be releasing more information about how members of the developer community can get involved with technical development of the Libra network, including the process for submitting a Libra Improvement Proposal. We are also looking to fill a new role, that of Technical Program Manager, that will be responsible for shepherding the product roadmap alongside the Technical Steering Committee and helping facilitate developer community involvement. Visit our Careers page to learn about this and other job opportunities with the Libra Association.

Reconfiguration support is live on testnet

January 14, 2020

Libra Engineering Team

We're happy to announce that Libra protocol now provides initial support for reconfiguration, which is the ability to change any configuration parameter on the blockchain without restarting any validators and while preserving Libra Byzantine Fault Tolerance (LibraBFT) safety and liveness guarantees. Reconfiguration has been successfully executed several times on testnet to add and remove validators from the validator set. We expect that reconfiguration will be used to add new validators to pre-mainnet. In the future, reconfiguration can be leveraged to change other configuration parameters such as upgrading the consensus protocol or the Move language specifications.

How it works

A set of configurations — for example, a consensus protocol and a set of validators — is used to create a consensus instance. The first consensus instance is generated after the reconfiguration transaction in the genesis block. Once the first consensus instance is active, transactions are proposed and committed by this consensus instance. In the future, a reconfiguration transaction may be committed by the current consensus instance that creates a new consensus instance (potentially with a different consensus protocol and/or a different set of validators) to continue the chain of committed transactions going forward.

We were able to demonstrate the low cost of reconfiguration from the results of early experiments. The data shows that reconfiguration finished within a few seconds, and the performance cost was minor.

As depicted below, removing a node has no impact on a steady transaction rate. Adding a node temporarily slows the transaction rate for a brief period while all live nodes are trying to help the added node replay the transaction that it missed after being removed from the test Libra Blockchain. The transaction rate spike from the added node illustrates the catch-up rate for the missing transactions.

What's next

We will share a detailed reconfiguration report in the near future. Additionally, we are working on supporting more configuration parameters with reconfiguration.

Stay tuned!

How gas works on the Libra blockchain

January 8, 2020

Libra Engineering Team

Note : The Libra Core software and the Move language are still under development; the information and the terminology used in this document are subject to change.

This post starts a series on gas on the Libra blockchain. The goal of this series is to take you from "I have no idea what gas means" to understanding what gas is and, at a high level, how it works. As the first post in this series, our goal here is to introduce the subject and provide an overview of the design and design goals. In subsequent posts we'll dig in and explore each area in more technical detail.

What is gas?

Put simply:

Gas is a way for the Move virtual machine to track and account for the abstract representation of computational resources consumed during execution.

In this way, gas is central to one of the most basic and crucial properties we need in Move:

The computational resources consumed by Move programs running on the blockchain are bounded.

Gas is a way to ensure that all programs terminate; it also provides the ability to charge a transaction fee based in part on the resources consumed during the execution of the transaction.

What does gas look like for a developer?

The transaction a client submits for execution contains a specified max_gas_amount and gas_price. max_gas_amount is the maximum amount of gas that can be used to execute the transaction, and therefore it bounds the amount of computational resources that can be consumed by the transaction. gas_price is a way to move from the abstract units of resource consumption that are used in the virtual machine (VM) — gas units — into Libra. Consequently, the transaction submitter is guaranteed to be charged at most gas_price * max_gas_amount (the "gas liability") for the execution of the transaction.

Similarities with other blockchains

Fees for executing transactions were originally pioneered by Bitcoin, and the idea of gas and gas-based execution fees were introduced by Ethereum. The design of gas on the Libra blockchain has benefited greatly from their designs, and in many ways the gas design for the Libra blockchain is similar to Ethereum's.

Core design principles

The design of gas in Move is motivated by three central principles.

First, Move is Turing complete. Because of this, determining if a given Move program terminates cannot be decided statically. However, by ensuring that (1) every bytecode instruction has a non-zero cost, and (2) the amount of gas that any program can be started with is bounded, we get this termination property for programs almost free of cost.

Second, we want to both discourage DDoS attacks and encourage judicious use of the network. This means that the computed resource consumption should reflect the real-world resource usage as closely as possible. It is important to note that resource consumption needs to be carefully defined; defining the relationships between different dimensions of resources is crucial.

Lastly, the resource usage of a program needs to be agreed upon in consensus. Taking this to its eventual conclusion means that the method of accounting for resource consumption needs to be deterministic. This in particular rules out other means of tracking resource usage, such as cycle counters or any type of timing-based methods, since these are not guaranteed to be deterministic across nodes. In particular, the method for tracking resource usage needs to be abstract.

Diving into the details

In this section, we'll provide a high-level technical overview of gas in the VM.

Different types of resources

For the VM to execute a transaction, the gas system needs to track the primary resources that are used by both the network and the VM. These fall into three resource "dimensions": (1) the computational cost of executing the transaction itself; (2) the network cost of sending the transaction over the network; and finally (3) the storage cost of storing the data created and read during the transaction on the blockchain. The first two of these resources (compute and network) are ephemeral, whereas storage is long lived; once data is allocated, that data persists until it is deleted. In the case of accounts, the data lives indefinitely.

Each of these resource dimensions can fluctuate independently of the other. However, we also have only one gas price. This means the gas usage contributed for each resource dimension needs to be correct, because the gas price only acts as a multiplier to the total gas usage, not usage by dimension. Thus, the essential property that we design for is that the gas usage of a transaction needs to be as highly correlated with the real-world cost associated with executing the transaction as possible.

That's all on this area for now, but stay tuned for an upcoming post where we'll dive into the details of this part of the gas system and how to determine the ratios between different resource dimensions in the Libra blockchain. Now, let's take a look at how gas is implemented in the VM.

Gas and transaction flow

When a transaction is executed by the VM, it is responsible for computing the resource usage of the transaction, then multiplying this by the gas price submitted with the transaction to arrive at the fee for execution. Different aspects of resource usage are charged for at different times in the transaction flow. The basics of the transaction flow and the gas-related logic are detailed in the following diagram:

Gas and Transaction Flow Diagram

Note in the diagram that both the prologue and epilogue sections are marked in red. This is because both of these sections of the transaction flow need to be unmetered:

  • In the prologue, it's not known if the submitting account has enough Libra to cover its gas liability, or if the transaction submitter even has authority over the submitting account. Due to this lack of knowledge, when the prologue is executed, it needs to be unmetered; deducting gas for transactions that fail the prologue could allow unauthorized deductions from accounts.

  • The epilogue is in part responsible for debiting the execution fee from the sending account and distributing it[2]. Because of this, the epilogue must run even if the transaction execution has run out of gas. Likewise, we don't want it to run out of gas while debiting the transaction sender's account as this would cause additional computation to be performed without any transaction fee being charged.

Taken together, this non-metering of both the prologue and epilogue requires the MIN_TXN_FEE to be enough to cover the average cost of running both. This is fairly straightforward to determine since metering must be deterministic and since both of these are relatively simple pieces of code that don't perform any complex operations.

After the prologue has run and we've checked in part that the account can cover its gas liability, the rest of the transaction flow starts with the "gas tank" full at max_gas_amount. The MIN_TXN_FEE is charged, after which the gas tank is then deducted (or "charged") for each instruction executed by the VM. This per-instruction deduction continues until either (1) the execution of the transaction has completed — in which case, the epilogue is run and the execution fee deducted — or (2) the "gas tank" becomes empty, in which case an OutOfGas error is raised. In the former, the fee is distributed and the result of the transaction is persisted. The latter causes the execution of the transaction to stop when the error is raised, following which the total gas liability of the transaction is deducted and distributed. No other remnants of the execution are persisted other than the deduction in this case[2].

Wrapping things up

In this post, we offered a high-level overview of the design space around gas in the Libra blockchain. In future posts, we'll explore each aspect of gas in further technical detail.

Endnotes

[1] This will be discussed more in the upcoming posts on the distribution of transaction fees and the economics of gas and transaction fees.

[2] Along with the deduction of the gas liability, the sequence number of the account is also incremented.

Libra Core Roadmap #2

December 17, 2019

Libra Engineering Team

At-a-glance

In Roadmap #2, we will focus on three main things: 1) delivering mainnet features in priority order, 2) defining launch criteria for going from Libra pre-mainnet to mainnet, and 3) educating and including the Libra community so that they can be valuable contributors to the Libra project.

  1. Mainnet feature work
  2. Libra pre-mainnet
  3. Community support and working in the open

Roadmap #1 retrospective

Overview

Roadmap #1 was marked by discussions of design shifts in Libra Core ranging from how we deploy Libra pre-mainnet to Move script publishing. Thankfully, we remain on schedule for feature completeness and the community is growing strongly!

Highlights

  • Mainnet feature work: We finalized our designs in all major features for mainnet feature completeness, and all teams have moved into execution mode.
  • Pre-mainnet deployment: Pre-mainnet work has changed to adjust for changes in membership and extended timelines for testing.
  • Community support: Interest in the Libra project has turned into implementation and collaborative design!
    • We have regular calls with the Libra Association members to share progress and answer questions.
    • The Libra Developer Blog had its first contribution from an Association member.
    • We have participated in a few conferences like those at SF Blockchain Week to discuss topics like identity and security/privacy/economics.
    • We are using a GitHub Kanban to manage the project and provide complete transparency.

Roadmap #2

Roadmap #2 goals are to execute to our roadmap, define requirements for v1 launch, modify our pre-mainnet approach for non-technical members, and increase community involvement.

Mainnet feature work

We have finished relevant design work and have gone through a thorough, bottom-up timeline plan for all features. We are now working on a full set of Libra protocol architecture documents and finalizing our external APIs with input from the community. Moving forward, we are starting to identify the work needed to enable the community that the Libra project hopes to attract.

Below is a summary of our progress. Some new items have been added for visibility into what the team is doing right now. For a project management level view, see our GitHub Kanban and Recent Issues Updates.

Top priority feature list and status

FeatureWorkstreamCurrent Status
Addressing / InteroperabilityLibra ProtocolWe are working through community feedback and input from the workshop session at the Libra Core Summit.
Full NodesLibra ProtocolFull node MVP done!
Full nodes have been pushed to testnet. We still have work to do on configuration/testing and discoverability.
Libra Protocol DefinitionLibra ProtocolNo new progress.
Reconfiguration (of the Validator Set)Libra ProtocolWe are actively working on consensus workflow (the unit test is pending review) as well as smart contract support (key rotation is supported, but adding/removing is in progress)
Reliability and TestingLibra ProtocolIntegrated Cluster Test now runs on every diff and discovers bugs in mempool/state sync, measures TPS (transactions per second) and latency.
WaypointsLibra ProtocolWe realized we could simplify the StateSynchronization flow (consensus/state synchronizer integration on GitHub)), so this is being worked on as a precursor to the rest of the Waypoints work.
CollectionsMoveMVP for Vector done!
We might still want to revisit the API to figure out a better standard library experience.
EventsMoveDone!
Next steps are to optimize the storage schema.
GenericsMoveNearly done!
  • IR parser, compiler, and all verifier checks have been implemented.
  • Fully supported in the VM, except for publishing generic resources directly. (A non-generic wrapper needs to be used right now.)
  • Next steps are to add more handwritten tests and prop tests.
Developer InfrastructureLibra CommunityWe are in the process of finalizing the release process, but recently have:
  • Now run continuous build and cluster test every 3 hours
  • Initiated notifications when nightly integration fails for Docker, config, or fuzzing tests
Pub/SubLibra CommunityPrototype done!
We have a working prototype that we are productionizing now. We went with an adaptor layer that lets any pub/sub system integrate on top of Libra Core (e.g., RabbitMQ)
TCBSecurity / CryptoAmazing progress here!
  • Isolated the core logic for consensus safety along with the consensus private key. Next steps are to construct an independent process for full process separation of trusted and untrusted code.
  • Circulating an initial proposal on the Executor/VM safety. The main focus here is to establish a trusted path between consensus safety logic and this work and establishing trust on storage.
  • Shared proposal for automated, online key rotation with the experts at BisonTrails. They provided feedback that this proposal is more secure than typical approaches but very appropriate considering what is at stake.
SerializationSecurity / CryptoDone!
Libra Canonical Serialization (LCS) has been finished and is in use throughout the system.
Libra Pre-MainnetProduction Ops(see Libra pre-mainnet section below)
Libra TestnetProduction Ops(see Libra pre-mainnet section below)

Libra pre-mainnet

We now have eight validator nodes deployed to Libra pre-mainnet!

New strategy for pre-mainnet for non-technical Association members

MainNet Roadmap

We created a new milestone for non-technical member validator node deployments. These are members that may not have an in-house technical team. The Libra Association, Partnerships, and the Libra protocol team are working on a strategy to assist non-technical members to deploy when the software is feature complete. Such members need to start preparing for how they will deploy their validator node, either by hiring technical support or utilizing a third party to run their validator node.

Going forward, we will focus on inviting organizations to join the Libra Association, keep growing the network, and continue marching towards a self-service model.

A community of Libra validator node operators

Our initial members are aligned with us on the vision that the Libra network needs to become a self-service model in order to scale to 100 members. Members have been involved and were at the first Libra Core Summit on a node operations panel and leading breakout discussions. Bison Trails also wrote a Libra blog about running a validator node. The initial member team we have is strong and we have been growing the community (both SREs and software engineers).

We created a Libra Slack Workspace open to all members, which has several discussion channels and has helped grow this community. We have also launched a member portal that will have slack bots, provide support to members, integrate with GitHub, Discourse and the CLA processes, and allow members access to documentation, configs, and more.

We are also working to figure out thesoftware release process, continuous integration/deployment, and topics like which software branches members should use.

Mainnet exit criteria and launch readiness

Exit Criteria

As we get closer to launch, the Association will need to identify metrics that will enable members to evaluate whether the Libra blockchain is ready for launch (a public launch of the network will be subject to a vote by the Council of the Association). We need to measure success and identify dependencies. We have kick-started these discussions. In Roadmap #2, we will start to define these metrics (technical and non-technical). First we will start on the Libra protocol.

Technical metrics: Metrics related to the Libra protocol software (network, developer infrastructure, storage, etc.), Libra protocol and wallet dependencies, testing real money, scaling testing, etc.

Non-technical metrics: Metrics related to the Libra Association, the reserve, other wallets, go-to-market metrics, etc.

Community support and working in the open

Having delivered on Roadmap #1 goals, we've expanded what we're doing in order to really push quality, size, and engagement in the Libra community. Here are our added plans.

Transparency

We already work completely in the open, publish our plans (including this document), and have a rotation of on-call engineers to support our testnet, forums, and incoming GitHub issues. However, all of these things are reactive and sharing out what we've already done. We have also streamlined our CLA process for Association members and external contributors (individuals and corporations) to enable their contributions.

For Roadmap #2, we want to get buy-in on plans for how to be proactive and begin to involve the community in how decisions are made and things are built. To that end, we're writing proposals for formal Libra Technical Working Groups (e.g., discussions of interoperability and a universal Identity standard).

Having input from the community will also create a much better product. In the realm of how things happen off-chain instead of internal to the Libra protocol, there is very fertile ground to plant seeds of community growth without slowing down our march to mainnet.

Community building

We are working to directly build the community up instead of letting it come to us. It's not completely clear what this will look like right now, but there are two main audiences: Association members and non-member client developers (both app level and smart contract level).

For Association members, we held the first Libra Core Summit in mid-November 2019. The goal of this effort included creating a community of the technical points of contact of the Association membership, teaching our members how the Libra network works technically, and brainstorming which working groups are needed.

For client developers, we're actively engaging to source many of our product requirements around developer infrastructure and APIs directly from the community. To date, we have been focused on creating something new and were more internal facing. This marks a shift to very active solicitation and research in order to best enable the Libra community.

How to contribute code to the Libra project: about the CLA process

December 10, 2019

Eric Nakagawa, Calibra

Built on open source software, the Libra network relies on a vibrant community of developers to enhance and continue growing the system. Any consumer, developer, or business can use the Libra network, build products on top of it, and add value through their services. This is foundational to the goal of building more inclusive financial options for billions of people around the world.

Developers must complete and sign a CLA before submitting code to the Libra project on GitHub. Use of a CLA is a common and well-accepted practice in open source projects, including well-known projects from Apache Software Foundation, Google (including Go), Python, Django, and more. CLAs can help remove ambiguities around a person or corporation's contributions and allow developers to contribute to and more confidently adopt projects.

Submit a CLA for your contribution

To contribute, you must first submit a CLA. Follow these steps:

  1. Go to https://github.com/libra/libra.

  2. Click New pull request.

  3. Click Create pull request. If you've not submitted a pull request for Libra from your GitHub account before, you'll see this:

  4. Click through to sign the CLA.

  5. Once you're on the "Sign an agreement" page, choose which type of CLA best fits how you plan to contribute to the project (as an individual or as a member of a corporation).

  6. Follow the directions on screen to either sign and complete the Individual Agreement, or submit a request for a Corporate Agreement.

    Individual

    Fill out the contribution form. If you are an individual, you will be sent to GitHub to authorize your account. Once you accept, your request will be processed automatically.

    On behalf of a corporation

    For contributions on behalf of a corporation, once your form is submitted, a Libra project team member will review and reach out to complete the process of adding you and any other contributors from your organization. This process includes signature of a corporate CLA via DocuSign and then whitelisting members of your organization.

  1. After CLA approval, you'll see a Signed icon and you'll be able to merge PRs.

    As in any open source project, a CLA qualifies contributions for review, but submissions are not guaranteed to be accepted by the maintainers. Code review and code acceptance are managed by project maintainers. Review the Contribution Guide and Coding Guidelines prior to submitting your changes.

Checking the status of your CLA

Individual CLA

Checking your individual CLA status is easy. In each PR in GitHub, select "Recheck CLA". This will prompt the CLA verification process to run again.

If you haven't signed the CLA, you can click on the "Needs Signature" from your PR to be taken to the Individual CLA selection page. Once you've signed, you can recheck your CLA.

Corporate CLA

The best way to check on your corporate CLA status is to simply email support@libra.org. Someone will be in contact with you within a few days to update the status of your CLA.

You can also recheck the status of your corporate CLA using these steps:

  1. Complete the Corporate CLA form.
  2. Select a Libra project member contact as the point of contact.
  3. Wait for the authorized signer to sign the CLA.
  4. When you receive the appropriate GitHub usernames and emails you can send them to support@libra.org to have them added to the whitelist.

Please note, this process can take several days, depending on the response time between each step.

Five months and growing strong: the Libra project

November 15, 2019

Michael Engle, Libra Association

It's been just five months since we announced the Libra project on June 18, 2019, and nearly a month since the Libra Association charter was signed by its members in Geneva. We've been working diligently to build the global community of developers and the technical infrastructure needed to support it. Here are a few highlights of what we've been working on:

  • Inviting community participation in shaping how we get to mainnet by making a detailed technical roadmap available to all.
  • Encouraging developers to test Libra network functionality by launching and continuously improving testnet, which has logged more than 51,000 transactions since we reset the testnet on September 17, 2019.
  • Simplifying how developers work with the Libra project team, so they can focus more on building — by integrating our online developer community, GitHub, CLA process, and more.
  • Teaching developers of all backgrounds and skill levels how to work with the Libra network by consistently publishing documentation and technical blogs.
  • Incentivizing developers to help us find and fix bugs faster by launching a Bug Bounty program.

Our community of developers has responded enthusiastically, logging an amazing 34 projects in just seven weeks since launch of the testnet:

  • 10 wallets
  • 11 blockchain explorers
  • 2 IDEs
  • 1 API
  • 11 clients

We want to say a very big thank you to all the developers in the community for all the hard work. We’re thrilled to be part of such a passionate community!

Building involvement in Libra Core

The success of the Libra project lies with the extended community that supports it. To help us build on our existing foundation by getting even more people involved, we recently held a Libra Core Summit with Libra Association technical team members. It was our first step towards a collaborative development plan for Libra Core and Move. In the future, we intend to continue to host events for all developers to discuss issues, challenges, and opportunities in the Libra ecosystem.

In addition to an expanded overview of the backstory, economics, and vision for the Libra project, topics covered include:

  • An overview of Libra Core and its roadmap
  • How to run a Libra node
  • How to build a Libra wallet
  • How to scale the Libra network
  • Libra wallet interoperability

Expanding to the pre-mainnet

Until we launch mainnet, the best and fastest way we have to demonstrate Libra network functionality and provide early access is through our pre-mainnet. Pre-mainnet, a version of testnet available to Libra Association members, makes it easier and faster to test, troubleshoot, diagnose, and resolve software edge cases. One measure of our success in this phase is the number of nodes that are live on the pre-mainnet. Currently, pre-mainnet has:

  • Deployed nodes: 7
  • In-process nodes: 6
  • In-process nodes without a technical team: 8

For those organizations without a technical team to implement a node, the Libra Association is working on a strategy to support deployment in 2020, when the Libra Core feature set is complete.

The Libra Association intends to deploy 100 nodes on the mainnet, representing a mix of on-premises and cloud-hosted infrastructure. All the work we are doing now on pre-mainnet supports this goal of greater resiliency on the network through a wider diversity of infrastructure.

Deepening the developer experience

As a Libra developer, we know that you commit significant time and resources to your work. We want to give you tools that will support you in making the most of your time and technical investments. Our work here includes:

  • Providing guides, documentation, and content for blockchain, smart contract, and wallet/client developers
  • Providing structured discussions and support
  • Advocating for transparency and access
  • Scaling outreach through tooling, events, programs, and bounties
  • Supporting engineering efforts of the Technical Steering Committee and Roadmap process.

Now, we want to make it easier and faster to submit code and documentation to the Libra project. On November 26th, we’re launching a new, streamlined process for completing Contributor License Agreements (CLAs). As with many open-source projects, you must complete and sign a CLA before you can submit code to the Libra project on GitHub.

Our new process streamlines how CLAs are submitted, reviewed, and verified, whether for individuals or for contributors working on behalf of a corporation or business.

You can start the process from GitHub. Choose which type of CLA best fits your situation (individual or corporate), fill out a form, and go from there. If your CLA requires additional signatures, we’ll make sure to collect those so you can focus on your code.

As in any open source project, a CLA qualifies contributions for review, but submissions are not guaranteed to be accepted by maintainers. If you have an ambitious feature that you wish to add to Libra Core, and which does not fit into the existing Roadmap, reach out through engineering channels or to the Libra Association to start a discussion. Code review and code acceptance is managed by project maintainers. Review the Contribution Guide and Coding Guidelines prior to submitting your changes.

Expanding the technical Roadmap and technical governance

You can check the technical progress we're making toward the Libra Core mainnet launch on our Roadmap. Completed work includes:

  • Libra Canonical Serialization (LCS)
  • MVP for full nodes
  • MVP for vectors in Move
  • Events

We have a lot of work still to do, and we need a passionate, dedicated community to help us all get to mainnet launch. To help us get there and make the best use of all the knowledge in our community, we plan to launch a Technical Steering Committee (TSC) in the coming months.

The TSC will oversee and coordinate the technical design and development of the Libra network on behalf of the Libra Association members. Libra Association members will decide together how the TSC will operate, including how its members will be determined, the full scope of its responsibilities, and how the extended community can support specific initiatives.

What opportunities interest you as a Libra developer?

As a Libra developer, you’re an incredibly important contributor to the Libra project. We’re excited to be on this journey with you, and with everyone in our extended developer community, and we look forward to our continued progress toward mainnet launch.

We invite you to dive in deeper, wherever you see the best opportunity to help us all move forward faster:

The Libra Consensus Protocol: Today and Next Steps

November 9, 2019

Libra Association

The Libra blockchain development team is excited to share version 3 of the Libra consensus whitepaper with the community. This whitepaper features two important advances:

  • It moves the whitepaper close to the released open-source codebase. Moving on, the Libra blockchain development team is committed to continue maintaining close affinity between the whitepaper and the codebase.

  • It includes roadmap items shared by the Libra blockchain development team concerning several coming enhancements and extensions.

Algorithmic Overview

The whitepaper provides a high-level overview of the Libra network algorithmic core, LBFT. It starts with background on classic BFT solutions. It then outlines the algorithmic core of the Libra network; illustrated using detailed examples and artwork that explain tricky Byzantine attack scenarios.

The whitepaper explains the basic structure of the core 3-round consensus protocol, which is based on HotStuff, and the manner in which it spreads three rounds across three consecutive blocks in the chain. For example, a simple chain is depicted on the right. (Curious to know what QC means? then you should read the whitepaper!)

The whitepaper walks the reader through sophisticated scenarios as shown below, illustrating how LBFT maintains safety against Byzantine attacks. On the left is a forking scenario created by a single Byzantine leader. On the right is a scenario that forks from a commit branch, right after the committed block, abandoning all but the committed block. The whitepaper discusses the commits resulting in these scenarios.

Code Walkthrough

The whitepaper serves as a high-level code walkthrough. It includes an accurate and detailed pseudo-code that reflects the code structure and key parts, with slight deviations driven only by brevity or encapsulation considerations. Names of API methods and modules reflect actual codebase names as much as possible.

The description breaks down the code into the following modules:

  • Ledger module: stores a local, forkable speculative ledger state.

  • Block-tree module : creates proposal blocks and votes. It keeps track of a tree of blocks pending commitment with votes and QC's on them.

  • Safety module: implements the core consensus safety rules.

  • Pacemaker module: is the liveness keeper that advances rounds.

  • ProposerElection module: maps rounds to leaders.

A Main module is the glue that dispatches messages and timer event handlers.

Take one module as an example, the Pacemaker. The whitepaper describes the implementation details materialized in the Libra blockchain for guaranteeing liveness. A requisite for progress is round synchronization, a mechanism for bringing all honest validators to execute the same round for sufficient overlap.

Round synchronization is governed by the Pacemaker module. The Pacemaker keeps track of votes and of time. In a "happy path", the Pacemaker module at each validator observes progress (a leader proposal for the current round) and advances to the next round. In a "recovery path", the Pacemaker observes lack of progress in a round. Upon a local round timeout, the Pacemaker broadcasts a TimeoutMsg notification.

Whenever the Pacemaker receives a certificate, either a quorum certificate (QC) or a timeout certificate (TC), it instructs the validator to advance to the next round. It additionally instructs the validator to forward the QC/TC to the leader of the round. This guarantees that upon entering a round with an honest leader, all validators will synchronize to within two network transmission delays.

These sub-algorithms and others are explained in the whitepaper, accompanied by detailed pseudocode and correctness proof arguments.

Next Steps

The whitepaper touches on some roadmap topics that the Libra blockchain will include in the future. More details about each topic will appear in supplemental documents in the near future.

Briefly, the Libra blockchain development team is sharing in this whitepaper high level notes on epoch-change and reconfiguration; on deploying TCB to increase validator security; on two performance enhancements, "nil-block" and "alternate-proposer", devised in order to cope with faulty validators acting in leader role; and on increasing BFT beyond one-third via flexibility approaches.

A Guide To Running Libra Validators

October 29, 2019

Bison Trails

As a member of the Libra Association, Bison Trails has gained in-depth experience running the first non-Calibra validator node on the Libra testnet network. In this post we detail our learnings from that exercise and offer our recommendations for other validator node operators on how to optimize node performance.

Getting Started Running a Validator (the short version)

Before we get into the details of some of our lessons learned, we encourage you to download and run the Libra network software. The Libra project team has open source software available on GitHub accompanied by excellent documentation on the Libra project developer's site. They provide a guided tour of the Libra blockchain, an introduction to the Move programming language, and detailed instructions on how to build and run a validator. We won't get down in the weeds in this post, but the distilled version of running a node via Docker is as simple as checking out the source code and either:

  1. Running via Docker locally by following the instructions in the "docker" directory of the testnet branch of Libra core
  2. Running a network on AWS using Terraform, again following the instructions in the "terraform" directory of the testnet branch of Libra core

In either case, you should use the testnet branch of the code, as it is both more stable and recommended by the Libra blockchain developer documentation.

It is relatively straightforward to run a validator using either of the methods above. We recommend you run via Docker locally at first to get a feel for the configuration of a node, see what its logs look like using the docker logs command, and understand how the validators are bootstrapped to discover each other. Once you're comfortable locally, the Terraform deployment will launch a more realistic network of validators communicating with each other over the internet.

Our suggestions below will make the most sense to those who have already taken a crack at running the software by either of these methods, although we've written them to be useful if you're here before you run your first validator.

Three Ways to Prepare for Mainnet

Next, we would like to share three suggestions based on our initial experience running a Libra validator and our prior experiences with other blockchain networks.

1. Persist the Blockchain

When the Libra network launches, the ledger state will grow over time as new accounts are added and validated transaction executions create new versions of the ledger state. The database that stores ledger state will grow accordingly. It is important that validators and full nodes are able to recover quickly in the event that, for whatever reason, the validator process is restarted. In the worst case, a node can always, in theory, just resync the entire history starting from the genesis block, but this costly and time-consuming sync can be avoided trivially by storing the blockchain on a persistent volume.

By convention, Libra validators are typically configured to store the blockchain data in the directory "/opt/libra/data"; you can store blockchain data elsewhere by changing the storage section of /opt/libra/etc/node.config.toml, but we recommend you stick to the default location.

Figure 1: recommended storage configuration excerpted from node.config.toml

dir = "/opt/libra/data"

Regardless of which system directory your node uses to store the blockchain, you will need to mount a persistent volume at that point in the directory tree. When running via Docker, which we recommend, this is as simple as using the --volume or --mount flag to specify mount details. For example, assuming you've mounted a multi-TB persistent volume on the host at /data, and your configuration files are available on a secure volume /libra-config, you can invoke Docker to use the volume as follows:

Figure 2: using the volume flag to persist

$ docker run -v /data:/opt/libra/data -v /config:/opt/libra/etc libra_e2e

And, in fact, the Terraform templates provided in the Libra blockchain source code use such a configuration to store Libra blockchain data on an EBS volume.

At Bison Trails, we also have proprietary systems that periodically snapshot the blockchain data so that if we lose a volume or if a particular data center becomes unavailable (not an infrequent occurrence across the hundreds of thousands of blockchain nodes running worldwide), we can quickly start a new node with a new volume or in a different location. That said, one of the first things we did with our own Libra validator, separate and apart from these advanced types of systems, was to store blockchain directory in a persistent location.

2. Metrics and Alerts

At Bison Trails, we're accustomed to adding a monitoring layer alongside the running blockchain software so that we can anticipate and take any scaling actions required through the normal evolution of the network and can react to any unanticipated events.

In the case of the Libra blockchain, the core development team has given all validators a huge head start by shipping software that already publishes extremely useful metrics via Prometheus. Prometheus is an excellent time-series data solution that is becoming the gold standard of metrics and alerting for devops teams. The best way to experience these metrics is to run a validator network via the Terraform method described above in Getting Started Running a Validator. As you can see in the screenshot below, it provides an out-of-the-box dashboard with many of the key metrics for individual as well as network-wide nodes.

Figure 3: Libra core ships with working metrics and example dashboards

Example Dashboard

From running nodes across many networks, we have instituted a fairly broad and rigorous approach to monitoring our nodes. We view metrics in three general categories:

  • System metrics, e.g. CPU/memory/disk utilization
  • Blockchain node, e.g. process health, node connectivity, data transfer
  • Blockchain application, e.g. block rates, transaction rates, and validation statistics

For each metric that we track, we have alerts that can broadly be classified as either critical or non-critical. With the Libra mainnet not yet launched, and the core development clipping along at an extremely aggressive pace, nobody at Bison Trails gets paged if a validator process stalls. However, as launch approaches, we will be tightening down our alert thresholds and severities, and we recommend that key performance metrics be monitored by any Libra Association member who runs a node, with alerts in place where appropriate.

3. Protect Your Keys

Our final suggestion relates to key management for your Libra node. First, a caveat: the practices around key management of a validator are evolving, so what we are describing here is not intended to be used for mainnet, but instead intended to get Association members and other node operators thinking about the validator keys. The methods below will certainly change as some of the operational questions around keys, key rotation, HSMs and other security questions are addressed in the coming months.

Libra validators currently run with three key pairs stored in two configuration files:

  • A consensus key stored in /opt/libra/etc/consensus_keypair.config.toml
  • Network identity and signing keys stored in /opt/libra/etc/network_keypair.config.toml

At Bison Trails, we use a layered approach to securing access to keys. Since a Libra validator needs to read keys from files, the following two practices apply:

  1. Restrict the key file permissions: whatever user, the validator process is the only process that needs to read these files, and no process needs to write to them, so we recommend the permissions mode be set to "400", meaning the user can read, and nobody else can read or write.
  2. Don't touch the disk: at a minimum we recommend that you use tmpfs volumes for your Docker image and include bootstrapping code to make the configuration files available on the tmpfs volume.

If you are just experimenting with the validators locally, there is no need to protect the keys, but it is important to note the fundamental differences between development mode and what you will want to do in production so that you are prepared for mainnet launch.

Learning More About the Libra blockchain

In this post we have shared three of the ways that Libra node operators can approach preparing their Validators and Full Nodes for mainnet. In addition to the lessons we have learned from our hands-on experience running a validator, we have also found the following resources to be extremely helpful in learning more about the Libra blockchain:

About Bison Trails

Bison Trails is pioneering blockchain infrastructure. Our technology platform provides enterprise-grade security, multi-cloud and multi-region distribution, and a 99.99% uptime guarantee. Our aim is to strengthen the entire blockchain ecosystem, by providing robust infrastructure for the pioneers of tomorrow.

In this post, we sketched out some of the suggestions we have to improve your Libra validator. If you have questions for us about your Libra validator, or any network software, we would love to hear from you. Contact us at hi@bisontrails.co.

Simplifying Libra Transaction Payloads: Deprecation of the "Program" Type

October 22, 2019

Calibra Engineering

Overview

We are simplifying the types of payload a Libra transaction can contain. Currently, the transaction payload of type "Program" allows both a Move module to be published and a Move transaction script to be executed within the same transaction. We will soon be deprecating the "Program" type. The benefits of making this change and the impact of this change are described in this document.

Payload of a Libra Transaction

Currently, the payload of a Libra transaction has the following three variants:

pub enumTransactionPayload {
    /// A regular programmatic transaction that is executed by the VM.
    Program(Program),     /// A genesis transaction.
    WriteSet(WriteSet),
    /// A transaction that publishes a module.
    Module(Module),
    /// A transaction that executes a script.
    Script(Script),
}
  • Program
    • Encodes a peer-to-peer transaction.
    • Within the same transaction, Move modules can be published and Move transaction scripts can be executed.
  • Writeset
    • Contains a simple writeset.
    • Used for genesis transactions only.
  • Module
    • Used to publish a Move module.
    • The payload is a single serialized Move CompiledModule.
    • A transaction with this type of payload just publishes the CompiledModule and does nothing else.
  • Script
    • Used to execute a Move transaction script.
    • The payload is a serialized Move CompiledScript.
    • A transaction with this type of payload just executes the CompiledScript and does nothing else.

Note: Currently, module transactions are accepted on local networks only.

What Will Change?

You may have noticed that the "Program" type is essentially a combination of the "Module" and the "Script" types. In the next week, the "Program" type will be removed from this implementation.

What Are the Benefits of This Change?

There are two major benefits to using "Script" and "Module" types separately instead of combining them into the (soon-to-be deprecated) "Program" type:

  • Reduces the size of a transaction - In the current implementation, for a regular peer-to-peer transaction, the module information should be encoded in the transaction as an empty "to-be-published" modules vector, even if there is no module to be published. This costs extra bytes.
  • Simplifies the VM structure - The VM caches the modules published on-chain for better performance. The semantics for transactions of payload type "Program" complicates the caching story of VM significantly. The VM must deal with the fact that, even if a "Program" attempts to publish a legitimate module, it can fail subsequently during the execution of the transaction script. When there's a script execution failure, the VM needs to get rid of the cached module so that this specific module is not visible to future transactions.

What Do We Lose From This Change?

Nothing!

Move modules are stateless, and there's no difference between publishing modules within one transaction or across different transactions.

How Do We Transition to the New Implementation?

The Libra codebase has been modified and all occurrences of the old transaction type have been removed (PR #923).

If you want to execute a transaction with a "Script" payload, the current transaction payload would look like this:

TransactionPayload::Program(
Program::new(
/*code*/ some_bytes,
/*args*/ args_vector,
/*module*/ vec![])
)

You will need to change it to:

TransactionPayload::Script(
Script::new(
/*code*/ some_bytes,
/*args*/ args_vector)
)

Similarly, if you were trying to publish a module, your current transaction payload would look like this:

TransactionPayload::Program(
Program::new(
/*code*/ some_bytes,    // Just an empty main function
/*args*/ args_vector,
/*module*/ vec![compiled_module_bytes])
)

You will need to change it to:

TransactionPayload::Module(Module::new(/*code*/ compiled_module_bytes))

We will support all transaction payload types on testnet for a few more weeks, following which the "Program" variant in transaction.rs will be removed.

Who is Impacted by This Change?

As the transaction payload bytes remain unchanged, this transition will be easy. However, wallet and client developers should be aware of this transition, as this will change the format of the transaction accepted by the Libra testnet.

Libra Developer Documentation Updated

The Libra developer documentation has been updated to reflect these new changes. Assume that any Libra transaction contains a script payload.

Next →