How Are Changes Made To Bitcoin?

When I started to learn about bitcoin back in 2014, one of the first questions I remember asking myself was “how are changes made to bitcoin?”. So, I did some research to find out how exactly the bitcoin source code gets continuously updated overtime.

How are changes made to bitcoin? The source code for the bitcoin project named Bitcoin Core is open-source code managed through the GitHub.com/Bitcoin repository. Anyone is free to propose new contributions to the source code, by following the meritocratic Bitcoin Improvement Proposal (BIP) process. The BIP process is described in detail in BIP 2.

Below I will dig deeper into the BIP process, but first I’ll begin by exploring the notion that Bitcoin Core is a meritocracy and by listing some basic prerequisites for becoming a Bitcoin Core developer. In addition I will answer some related and commonly asked questions, such as, “Who controls Bitcoin Core?”, “Could a bad actor inject malicious code into the source code?”.

Preliminary Observations

Bitcoin Core is a meritocracy: building trust within the Bitcoin Core developer community

The Bitcoin Core project is open-source and hosted on GitHub.com/Bitcoin. This means that the Bitcoin Core source code is publicly available for anyone to consult, review and download through the GitHub repository. Anyone is welcome to make a contribution to the Bitcoin Core project, in accordance with the BIP process, by either reviewing and testing proposals that have been submitted or by making a code contribution of their own. The only thing that matters, and upon which you will be judged by the Bitcoin Core developer community, is the quality of your work

Notwithstanding the above, like with any kind of open-source project, when making your first contributions to Bitcoin Core, a good first step would be to build up your reputation among the Bitcoin Core developer community.

You could begin earning the trust of the community, for example, by making quality contributions in the form of code reviews and the testing of code that has already been submitted by other contributors. Having a solid reputation among the Bitcoin Core developers in terms of reviewing and testing code, will likely help you later on if and when you decide to make a code contribution of your own.

“The general rule of thumb is that for every pull request you do, you should be reviewing about 3 pull requests. At the beginning you may want this ratio of reviews to pull requests to be even higher.”

Jimmy Song (Bitcoin Core developer) in “A Gentle Introduction to Bitcoin Core Development“

Reviewing and testing out code submitted by others will also help you get a better understanding of the code and how all the nuts and bolts of the code fit together. These efforts will also likely improve the quality of your code contributions later on. Think of the following analogy; when you want to learn how to play basketball, you don’t start out by trying to make a slam dunk.

What are the prerequisites for contributing to Bitcoin Core?

In order to be able to make valuable contributions to the Bitcoin Core project, you’ll need to have some technical and non-technical abilities:

Technical abilities:

You need to be able to:

• code in C++ and Python.
• open a GitHub account.
• know how to fetch branches and/or tags (collectively, “refs”) from the GitHub.com/Bitcoin repository.
• install and remove software packages on your computer

Non-technical abilities:

According to renowned Bitcoin Core developer Peter Todd, having an adversarial mindset is one of the most valuable abilities to have as a code contributor. You need to be able to contemplate all the possible ways a bad actor might try to game the code to his/her own advantage and fix those potential loopholes. Few programmers are blessed with such ability, which explains the relative small number of top Bitcoin Core developers.

“Most programmers in general, do not have the capability to work on this stuff, because they don’t think adversarially. It’s a tough thing for people to imagine. Most people are just not used to imagining, “All right, what are the bad things that could happen?”
Whereas for whatever reason, I, and a few other people, are good at that. I’m quite happy to imagine all the ways people could screw people over.”

Comment by Bitcoin Core developer Peter Todd in a ‘What Bitcoin Did’ podcast interview by Peter McCormack.

Where do I start in view of contributing to Bitcoin Core?

Before making any contributions to Bitcoin Core, either by reviewing and/or testing code contributions or by submitting code proposals, a good place to start would be to:

• read how to build Bitcoin Core on your native platform here, set up your development environment and run the appropriate unit and integration tests to make sure the software is working properly;
• get acquainted with the Bitcoin Core source code;
• read the Bitcoin Core guideline for contributing; and
• subscribe to the bitcoin-dev and bitcoin-discuss mailing lists and dive into the bitcoin-dev archives and the bitcoin-discuss archives.

The bitcoin-dev and the bitcoin-discuss archives contain a complete overview of past contribution proposals and the related discussions that have taken place among the Bitcoin Core developers. Many proposals have been put forward, discussed and either accepted or rejected in the past. By reading the archives first, you’ll avoid wasting time on topics that have already been discussed in the past. In addition, you may find content that is relevant for your future work.

Other valuable resources where you can find quality information are, amongst others:

• the official Bitcoin Core website;
• Bitcoin Wiki;
• bitcointalk.org’s forum;
• Bitcoin IRC Channel
• bitcoin.stackechange.com
• Bitcoin Core community Slack

Notwithstanding the above, if you’re just starting out as a new developer, it is highly recommended that you try to find a Bitcoin Core developer who would be willing to mentor you and who can gradually guide you along the way. This is however not a requirement.

An interesting alternative in this regard would be to explore the residency programs at Chaincode Labs, where they provide trainings to become a Bitcoin Core developer.

Now let’s dig a bit deeper into the actual process for submitting a BIP.

The Bitcoin Improvement Proposal Process

We intend BIPs to be the primary mechanisms for proposing new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Bitcoin. The BIP author is responsible for building consensus within the community and documenting dissenting opinions.

2nd paragraph from the BIP2 Abstract, by author Luke Dashjr (Bitcoin Core developer)

Use the Bitcoin Core developer community as sound board for your idea

According to Bitcoin Core developer Bryan Bishop, it is generally recommended that you first socialize an idea, by talking to the Bitcoin Core developer community (e.g. through the bitcoin dev mailing list, the Bitcoin IRC Channel and/or the Bitcoin Core community Slack), before you decide to start writing a BIP. This will allow you to get a sense of (1) whether or not the idea is conceivably possible in any way and (2) whether there is any chance that people are going to be in favor of and support the proposed feature.

Write a draft proposal and a code implementation

Once you have ascertained that your idea will be well received by the Bitcoin Core developer community, the next step would be to write a draft document that describes the idea, taking into account the feedback you have already collected from the community, and submit this draft document to the bitcoin dev mailing list. At that time you can also contact the acting BIP editor (i.e. Luke Dashjr at the time of writing), who will assign a BIP number to the draft document (BIP numbers are not self assigned).

It is generally expected that you (i.e. the author of the proposal) also provide an implementation prototype of the proposal, at the time that the draft document is first circulated. In this regard it is important to keep in mind that you should always aim to produce an implementation that is fully backwards compatible with the existing Bitcoin Core code. Changes that are not backwards compatible will result in a bitcoin hard fork, creating 2 different bitcoin versions (past hard forks include, a.o. bitcoin cash, bitcoin gold, etc.). Such proposals are very unlikely to receive wide support from the Bitcoin Core developer community and other Bitcoin Core stakeholders (such as, but not limited to, the miners).

Trying to achieve consensus

“Community consensus … is very much a social phenomenon. The social consensus process is that changes should only occur after they have a general amount of consensus.”

Bitcoin Core developer Bryan Bishop in a ‘What Bitcoin Did’ podcast interview by Peter McCormack.

The next phase of the BIP process is for the bitcoin developer community to achieve what is called ‘consensus’ regarding the proposed changes.

It is up to the draft BIP author to try to find consensus within the developer community.

…, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep discussion efficient include: setting up a separate SIG mailing list for the topic, having the BIP author accept private comments in the early design phases, setting up a wiki page or git repository, etc. BIP authors should use their discretion here.

‘BIP workflow’, in BIP2, by author Luke Dashjr (Bitcoin Core developer), p.2.

There is however no definition of what is to be considered ‘consensus’, nor any kind of objective threshold that needs to be met before one can conclude that consensus has been reached. Rather, consensus could be considered achieved when the proposed code has thoroughly been vetted (i.e. discussed, reviewed and tested) and all strongly held objections which have been raised, have either been addressed or debated until most people are satisfied that such objections are wrong (i.e. all issues should be addressed satisfactorily, but not necessarily solved; e.g. sometimes technical trade-offs will be inevitable).

If a valid technical objection is raised by even just a single contributor then it must be addressed by the group or it may prevent the implementation of a proposal if sufficiently strong.

‘Lack of disagreement is more important than agreement’ in The Tao Of Bitcoin Development, Alex B., p. 8.

It is important to underline in this regard that consensus does not mean unanimous support, as this would prove virtually impossible to achieve. Rather, a more suitable measure is the lack of disagreement regarding a draft BIP. If no sufficiently strong disagreement remains that has not been thoroughly discussed, one could consider that a general amount of consensus has been reached.

Submitting a pull request

Following the discussions regarding the draft BIP, you (i.e. the author) may formally submit the (amended, as the case may be) proposal to the BIP GitHub repository as a pull request, where the BIP may get further feedback from the community.

For a BIP to be accepted by the BIP editor, the BIP must meet at least certain minimum criteria:

• it must be a clear and complete description of the proposed enhancement;
• the enhancement must represent a net improvement; and
• the proposed implementation, if applicable, must not complicate the protocol unduly.

The BIP editor may reject a pull request for any of the following reasons (non-exhaustive list):

• the BIP duplicates a previous proposal;
• the BIP is not properly formatted;
• the BIP is too broad;
• the BIP is technically unsound;
• the BIP is not adequately motivated;
• the BIP is not backwards compatible with the current Bitcoin Core implementation;
• the BIP is not in keeping with the Bitcoin Core philosophy.

A BIP that has been submitted and accepted to the GitHub repository, can be updated as necessary (e.g. based on further feedback from the community). Updates to the BIP need to be submitted by the author as pull requests.

Merging of the changes into the source code by a maintainer

After a BIP has been submitted and accepted to the GitHub repository and it appears that a general amount of consensus has been reached regarding the BIP (i.e. there are no reasonable objections, see supra, section ‘Trying to achieve consensus‘), eventually the BIP code implementation will be merged with the Bitcoin Core source code.

Only a handful of people have so-called ‘commit access’, which is the ability to sign merge commits, in view of merging the new code with the Bitcoin Core source code. These people are called the ‘maintainers’.

Every merge commit must be signed by a valid PGP key of a Bitcoin Core maintainer. Merge commits that have been signed by a maintainer, will subsequently be merged with the Bitcoin Core source code and included in the next software update to be released to the public.

Once a BIP implementation has been merged with the source code and released to the public, the nodes in the Bitcoin Core network will be able update the version of the source code that they are running.

…, each node operator must make a conscious decision to update the code they run. Bitcoin Core deliberately does not include an auto update feature, since it could potentially be used to maker users run code that they didn’t explicitly choose.

‘Layered Security’ in Who Controls Bitcoin Core?, by Jameson Lopp (Bitcoin Core developer), p. 5.

If the BIP implementation is backwards compatible with the Bitcoin Core source code (i.e. a so-called ‘soft fork’), such update will in principle be optional for the nodes that are part of the Bitcoin Core network.

Related Questions

Who controls Bitcoin Core?

No particular person or group of people controls Bitcoin Core.

Bitcoin Core is currently managed through the GitHub.com/Bitcoin repository and a handful of Bitcoin Core developers are entrusted with administrative privileges (i.e. the BIP editor can accept or reject pull requests and a handful of ‘maintainers’ can sign merge commits with their PGP key). However, Bitcoin Core could easily be managed through an entirely different repository if necessary, for instance in case the GitHub repository would get compromised in some way (e.g. a GitHub employee going rogue), and any of the administrative privileges can be revoked at any time by the community (e.g. in case a maintainer would abuse its privilege by signing merge commits without consensus).

While it is technically possible for a maintainer-organized coup to hijack the GitHub repository, censor dissenting developers, and perhaps even maintain the brand name of “Bitcoin Core”, the result would be that Bitcoin Core would stop being the development focal point. Developers who disagreed with the actions of the maintainers would simply fork the code and shift their work on a different repository over which Bitcoin Core maintainers had no administrative privileges.

‘Who are the Core Developers’, in Who Controls Bitcoin Core?, by Jameson Lopp, p.10.

In other words, the current Bitcoin Core development setup through the GitHub repository is merely functional in nature, and not essential for the functioning and development of Bitcoin Core. This means that if the Bitcoin Core project would get hijacked in some way by a particular group of developers, the other bitcoin developers would simply be able continue their vision of the bitcoin project on another platform. It is then ultimately up to the nodes of the network to decide which version of the bitcoin software they want to run.

Could a bad actor inject malicious code into the Bitcoin Core source code?

Only a handful of maintainers have ‘commit access’, i.e. have been entrusted with the PGP keys necessary to sign merge commits. Therefore, in principle only the maintainers have the ability to merge new code with the Bitcoin Core source code.

It is theoretically possible that a PGP key could get compromised or that a maintainer would abuse his/her privilege by signing a merge commit without consensus. Such occurrence would however not be problematic.

First of all, software updates are not run automatically by the nodes of the network. This means that nodes need to actively choose to run the new version of the software. If a contested piece of code was injected in the source code, nodes can choose not to run the controversial version of the software. In addition, if malicious code would make it into the Bitcoin Core source code, the Bitcoin Core developers could simply remove that particular piece of code and make the cleaned up version of the software available to the public.

How can we be certain that each merge commit has been properly signed up till now?

Any developer is able to run a verify-commit script, which performs an integrity check on every single merge commit since December 2015. If the script is successfully executed, this means that every merge commit (i.e. every change to the Bitcoin Core source code) up till now has been signed by a maintainer key.

---

Attention! Do you store your cryptocurrencies on an online platform? Please note, in that case you are not the actual owner of your cryptocurrencies!

In particular, you run the risk of losing all your cryptocurrencies, without any recourse, in the event that the online platform or your personal account falls victim to hacking or in the event of an unexpected closure (e.g. insolvency) of the online platform.

Protect yourself against hacking and take real ownership of your cryptocurrencies by storing your cryptocurrencies offline on your very own Trezor hardware wallet. Don’t wait before it’s too late and take immediate action now!

Click on the ‘Buy Now’ button below to buy a Trezor wallet from the official Trezor website.