Mirror Image: Bitcoin Core and Elements

Elements is an open source, sidechain-capable blockchain platform, based on the Bitcoin Core source code. In 2015 the first version of Elements was released, after forking and modifying the code from the upstream Bitcoin repository. This marked the launch of the first testnet Bitcoin sidechain, following the founding of Blockstream and the release of the seminal sidechains whitepaper in 2014.

In software engineering parlance, a fork is a copy of a source code repository independently maintained by a different group of developers (not to be confused with a Bitcoin fork, which is an entirely different concept). The Elements software fork was created to add new features and functionality to Bitcoin via one or more sidechains, while inheriting a solid foundation.

Elements brings the following features to the Bitcoin ecosystem:

Sidechains: the ability to run as a sidechain, validating peg-in transactions on the main Bitcoin blockchain to unlock the same value on the sidechain.
Signed blocks: deterministic block creation delegated to one or more blocksigners instead of the probabilistic block creation in proof-of-work mining.
Asset issuance: ability to issue new types of tokens on the sidechain like stablecoins, digital securities, and commodities.
Confidential Transactions: private transactions with cryptographically hidden amounts and asset types.
Cryptography: a fork of libsecp256k1 with advanced zero-knowledge primitives like Pedersen commitments, range proofs, and surjection proofs.
Script opcodes: new script opcodes for deterministic random number generation and signature verification on the stack, which enable smart contracts and covenants. Elements also reintroduces some safe opcodes that were disabled in Bitcoin by Satoshi, including string concatenation, substrings, integer shifts, and several bitwise operations.

Benefits of Maintaining Bitcoin Parity

Maintaining the Elements source code as a mirror image with merges from Bitcoin has many benefits. First, Bitcoin is the most mature and extensively tested blockchain network in existence today. By building on Bitcoin’s codebase, Elements can leverage its robust security measures and battle-tested protocols, reducing the risk of vulnerabilities and potential security issues. Elements 22 included over 700 code-related fixes and improvements from Bitcoin, in addition to the Elements-specific fixes.

Another benefit is familiarity of the codebase: it is easier for Bitcoin developers to understand and contribute to Elements code since the majority of code is shared. For example, a Bitcoin contributor can suggest performance improvements like increasing the inventory broadcast rate. In the Bitcoin messaging protocol, nodes send inventory request messages to other peers, requesting specific headers, blocks, and transactions. The peers respond by sending back the requested data, at a capped rate to avoid Denial-of-Service (DOS) attacks. Elements uses the same messaging protocol, but these values can be optimized specifically for the sidechain since it has different characteristics, like deterministic one-minute blocktimes.

Inheriting all the fundamentals from Bitcoin is a major advantage compared to rewriting the code from scratch. Everything from networking and databases, to cryptography and data structures have already been tried and tested, with years of review and fixes.

However, this does come with its own challenges and maintenance burdens - changes from upstream may conflict with our changes to the base source code. A merge conflict occurs when differing changes are made to the same code from two different sources. As a result, merge conflicts must be resolved and thoroughly reviewed, ensuring that all the unit and functional tests still pass. This means major Elements releases lag a bit behind Bitcoin, but important bug fixes or security updates are backported and released in minor versions as soon as possible.

Comparing the Code

Let’s now take a closer look at the Bitcoin and Elements repositories with a tool like Tokei, which allows us to see various statistics like the number of files, lines of code, and comments, grouped by language. At the version 23.2 snapshot, the Bitcoin repository has 2,049 files consisting of almost 650,000 lines of code, including comments and blank lines. The snapshot of Elements for the version 23 merge has 2,337 files consisting of about 730,000 lines of code. The git-diff comparison between the two repositories tells us that there are 950 files changed, with 124,223 line insertions, and 40,781 line deletions. As a rough calculation, this means that Elements is almost 80% identical code to Bitcoin.

As an example of the differences, let’s review the wallet code. In Bitcoin, the GetAvailableBalance method returns a CAmount, which is just a single number of the spendable sats in the wallet. However, Elements has asset issuance, which means that there could be any number of balances to return for the wallet. So, the GetAvailableBalance method returns a CAmountMap instead, which is a map of asset type to the amount. This allows Elements to keep and calculate a different balance for each asset type. This fundamental change, along with Confidential Transactions, accounts for a large number of the changes between Bitcoin and Elements.

Liquid: An Elements Implementation

Elements can run in two major modes: as a standalone blockchain or as a sidechain pegged to a mainchain. One example of an Elements-powered Bitcoin sidechain is the Liquid Network, where users can peg-in Bitcoin to receive Liquid Bitcoin (L-BTC) on the sidechain and take advantage of one-minute block times, cheap fees, and enhanced privacy with Confidential Transactions. Asset issuance also enables tokenizing financial instruments like promissory notes, while upgraded script opcodes and covenants allow additional capabilities, such as fully collateralized options contracts.

Blockstream’s role in Liquid is purely as a technical provider to the Federation. The Liquid governance technology board requests software features and fixes for the functionary software, and ultimately evaluates and votes on whether to adopt any changes.

Elements itself is completely open source, principally maintained by about 10 contributors. When including changes inherited from the upstream Bitcoin repo, there have been over 600 individual contributors to the codebase so far.

Currently, developers are working on bringing Elements up to parity with Bitcoin Core version 23. The major merges are done, with all conflicts resolved and code reviews in progress. Once the reviews are complete, and all backports from Bitcoin 23.1 and 23.2 are applied and tested, Elements version 23 will be released. After that, work towards the latest Bitcoin versions 24 and 25 will continue, and the process repeats.

Get Involved in Layer-2 Development

Further development of the Elements project holds significant promise for advancing Bitcoin's development and expanding its use cases. Elements, which is built on the secure and extensively tested foundation of the Bitcoin codebase, provides an environment for testing innovative features without directly impacting the main Bitcoin network. This enables developers to push the boundaries of what's possible, exploring enhancements in privacy, scalability, and interoperability. As these new features are refined and proven on Liquid, they can be strategically integrated into the mainchain, enhancing its capabilities.

New contributors to Elements are always welcome. If you would like to get involved in the development or code review of Elements, please visit the GitHub repository, or you can reach out to me personally in the Liquid Build On L2 community for any questions or guidance.