Bitcoin development philosophy

As stated above, this is a practical guide for Bitcoin developers. However, Bitcoin is a broad and complex subject and we couldn’t possibly cover all of its aspects here. With this book, we hope to discuss the necessary features to get your development activity started as well as to enable you to further explore it on your own.

There are lots of people involved in Bitcoin; as some of them have opposing opinions, here you may find resources that express contradictory ideas. However, we always attempt to stick to the domain of facts, where opinions do not matter.

The main author of this book is Kalle Rosenbaum, and Linnéa Rosenbaum contributed as a co-author. This work was commissioned and funded by Chaincode Labs, a development center that runs educational programs for developers who want to learn about Bitcoin development.

Kalle is the author of Grokking Bitcoin (Manning Publications) and is a seasoned software developer. He’s been working professionally with Bitcoin-related development since 2015.

Linnéa has a Ph.D. in Electronic Systems. She is the Swedish translator of The Little Bitcoin Book and co-translator of The Bitcoin Standard. She is also on the board of the Swedish Bitcoin Association. Her background is in firmware development with a recent shift towards software development.

The book is sectioned into chapters, each covering a pivotal topic within Bitcoin. Every chapter guides you through the relevant information related to the chapter’s focus, with the addition of links and QR codes that will take you to articles or videos that we recommend reading or watching. The reported material was written by individuals who have studied Bitcoin development for a long time.

The links refer to external resources on platforms we cannot control. We have therefore saved the linked articles locally in this repository, along with the information on where it was copied from and when. The resources are collected in a separate document (sources/sources.adoc) and organized by the chapter they are linked to. The links found in the chapters refer to the original sources, which should be found online, but in case you don’t have an internet connection, the links appear dead, or the information seems severely changed, you can read the content locally instead.

There had been attempts at creating digital currencies before Bitcoin, but most of them failed due to a lack of governance decentralization and censorship resistance.

Miner decentralization in Bitcoin means that the ordering of transactions isn’t carried out by any single entity or fixed set of entities. It’s carried out collectively by all the actors who want to participate in it; this miners’ collective is a dynamic set of users. Anyone can join or leave as they wish. This property makes Bitcoin censorship-resistant.

If Bitcoin were centralized, it would be vulnerable to those who wished to censor it, such as governments. It would meet the same fate as earlier attempts to create digital money. In the introduction of a paper titled “Enabling Blockchain Innovations with Pegged Sidechains”, the authors explain how early versions of digital money weren’t equipped for an adversarial environment (see also Chapter 6):

It became clear that using a central server to order transactions was not a viable option due to the high risk of censorship. Even if one replaced the central server with a federation of a fixed set of n servers, of which at least m must approve of an ordering, there would still be difficulties. The problem would indeed shift to one where users must agree on this set of n servers as well as on how to replace malicious servers with good ones without relying on a central authority.

Let’s contemplate what could happen if Bitcoin were censorable. The censor could pressure users to identify themselves, to declare where their money is coming from or what they’re buying with it before allowing their transactions to enter the blockchain.

Also, the lack of censorship resistance would allow the censor to coerce users into adopting new system rules. For example, they could impose a change that allowed them to inflate the money supply, thereby enriching themselves. In such an event, a user verifying blocks would have three options to handle the new rules:

None of these options are beneficial to the user.

Censorship resistance through decentralization is what separates Bitcoin from other money systems, but it is not an easy thing to accomplish due to the double-spending problem. This is the problem of making sure no one can spend the same coin twice, an issue that many people thought was impossible to solve in a decentralized fashion. Satoshi Nakamoto write in his Bitcoin whitepaper about how to solve the double-spending problem:

Here he uses the peculiar-sounding phrase “peer-to-peer distributed timestamp server”. The keyword here is distributed, which in this context means that there is no central point of control. Nakamoto then goes on to explain how proof-of-work is the solution. Still, no one explains it better than Gregory Maxwell on Reddit, where he responds to someone who proposes to limit miners’ hash power to avoid potential 51% attacks:

The post explains how the decentralized Bitcoin network can come to an agreement on transaction ordering through the use of proof-of-work. He then concludes by saying that the 51% attack is not particularly worrisome, compared to people not caring about or not understanding Bitcoin’s decentralization properties.

The conclusion is an important one. If people don’t protect Bitcoin’s decentralization, which is a proxy for its censorship resistance, Bitcoin might fall victim to centralizing powers, until it’s so centralized that censorship becomes a thing. Then most, if not all, of its value proposition is gone. This brings us to the next section on full node decentralization.

In the paragraphs above, we’ve mostly talked about miner decentralization and how centralizating miners can allow for censorship. But there’s also another aspect of decentralization, namely full node decentralization.

The importance of full node decentralization is related to trustlessness (see Chapter 2). Suppose a user stops running their own full node due to, for example, a prohibitive increase in the cost of operation. In that case, they have to interact with the Bitcoin network in some other way, possibly by using web wallets or lightweight wallets, which requires a certain level of trust in the providers of these services. The user goes from directly enforcing the network consensus rules to trusting that someone else will. Now suppose that most users delegate consensus enforcement to a trusted entity. In that case, the network can quickly spiral into centralization, and the network rules can be changed by conspiring malicious actors.

In a Bitcoin Magazine article, Aaron van Wirdum interviews Bitcoin developers about their views on decentralization and the risks involved in increasing Bitcoin’s maximum block size. This discussion was a hot topic during the 2014-2017 era, when many people argued over increasing the block size limit to allow for more transaction throughput.

A powerful argument against increasing the block size is that it increases the cost of verification (see the Scaling chapter). If verification cost rises, it will push some users to stop running their full nodes. This, in turn, will lead to more people not being able to use the system in a trustless way. Pieter Wuille is quoted in the article, where he explains the risks of full node centralization.

There you go. Bitcoin users should run their own full nodes to deter regulators and big corporations from trying to change the consensus rules.

Bitcoin is neutral, or permissionless, as people like to call it. This means that Bitcoin doesn’t care who you are or what you use it for.

As long as you play by the rules, you’re free to use it as you please, without asking anyone for permission. This includes mining, transacting in, and building protocols and services on top of Bitcoin.

At all levels, trying to impose restrictions on who gets to use Bitcoin for what will hurt Bitcoin to the point where it’s no longer living up to its value proposition.

Pieter Wuille answers a question on Stack Exchange about how the blockchain relates to normal databases. He explains how permissionlessness is achievable through the use of proof-of-work in combination with economic incentives. He concludes:

He explains that, in order to achieve permissionlessness, the system most likely needs its own currency, thereby “limiting the use cases to effectively just cryptocurrencies”. This is because permissionless participation, or mining, requires economic incentives built into the system itself.

A compelling aspect of Bitcoin is how hard it is to grasp that no one controls it. There are no committees or executives in Bitcoin. Gregory Maxwell, again on the Bitcoin subreddit, compares this to the English language in an intriguing way:

The way Bitcoin works through decentralization resembles the extraordinary collective intelligence found among many species in nature. Computer scientist Radhika Nagpal speaks in a Ted talk about the collective behavior of fish schools and how scientists are trying to mimic it using robots.

She points out that many systems, either natural or artificial, can and do work without leaders, and they are powerful and resilient. Each individual only interacts with their immediate surroundings, but together they form something tremendous.

No matter what you think about Bitcoin, its decentralized nature makes it difficult to control. Bitcoin exists, and there’s nothing you can do about it. It’s something to be studied, not debated.

Bitcoin works trustlessly, but you still have to trust your software and hardware to some degree. That’s because your software or hardware might not be programmed to do what’s stated on the box. For example:

So, besides running a full node, you also need to make sure you’re running what you intend to. Reddit user brianddk wrote an article about the various levels of trust you can choose from, when verifying your software. In the section “Trusting the builders”, he talks about reproducible builds:

The article defines 5 levels of trust: trusting the site, the builders, the compiler, the kernel, and the hardware.

To further deepen the topic of reproducible builds, Carl Dong made a presentation about Guix (video) explaining why trusting the operating system, libraries, and compilers can be problematic, and how to fix that with a system called Guix, which is used by Bitcoin Core today.

He then explains how Guix allows us to only trust a minimal binary of 357 bytes that can be verified and fully understood if you know how to interpret the instructions. This is quite remarkable: one verifies that the 357-byte binary does what it should, then uses it to build the full build system from source code, and ends up with a Bitcoin Core binary that should be an exact copy of anyone else’s build.

There’s a mantra that many bitcoiners subscribe to, which captures well much of the above:

This alludes to the phrase "trust, but verify" that former U.S. president Ronald Reagan used in the context of nuclear disarmament. Bitcoiners switched it around to highlight the rejection of trust and the importance of running a full node.

It’s up to the users to decide to what degree they want to verify the software they use and the blockchain data they receive. As with so many other things in Bitcoin, there’s a trade-off between convenience and trustlessness. It’s almost always more convenient to use a custodial wallet compared to running Bitcoin Core on your own hardware. However, as Bitcoin software is maturing and user interfaces are improving, over time it should get better at supporting users willing to work towards trustlessness. Also, as users gain more knowledge over time, they should be able to gradually remove trust from the equation.

Some users think adversarially (see Chapter 6) and verify most aspects of the software they run. As a consequence, they reduce the need for trust to the bare minimum, as they only need to trust their computer hardware and operating system. In doing so, they also help people who don’t verify their hardware as thoroughly by raising their voices in public to warn about any issues they might find. One good example of this is an event that occurred in 2018, when someone discovered a bug that would allow miners to spend an output twice in the same transaction:

Here, an anonymous person reported an issue that turned out much worse than the reporter realized. This highlights the fact that people who verify the code often report security flaws instead of exploiting them. This is beneficial to those who aren’t able to verify everything themselves. However, users should not trust others to keep them safe, but should rather verify for themselves whenever and whatever they can; that’s how one remains as sovereign as possible, and how Bitcoin prospers. The more eyes on the software, the less likely it is that malicious code and security flaws slip through.

Privacy can mean different things in different contexts. In Bitcoin, it generally means that users don’t have to reveal their financial information to others, unless they voluntarily do so.

There are many ways in which you may leak your private information to others, with or without knowing it. Data can either leak from the public blockchain or through other means, for example when malicious actors intercept your internet communications.

It may seem obvious why privacy is important in Bitcoin, but there are some aspects of it that one might not immediately think about. On the Bitcoin Talk forum, Gregory Maxwell walks us through a lot of good reasons why he thinks privacy matters. Among them are free market, safety, and human dignity:

Maxwell also touches on fungibility, which will be discussed later in this chapter, as well as on how privacy and law enforcement are not contradictory.

We mentioned above that Bitcoin is pseudonymous, and that the pseudonyms are public keys. In the media you often hear that Bitcoin is anonymous, which is not correct. There is a distinction between anonymity and pseudonymity.

Andrew Poelstra explains in a Bitcoin Stack Exchange post what anonymity would look like in transactions:

The difference seems to be that in a pseudonymous form of money you can trace payments between pseudonyms, whereas in an anonymous form of money you can’t. Since bitcoin payments are traceable between pseudonyms, it’s not an anonymous system.

We have also said that the pseudonyms are public keys, but it’s actually addresses derived from public keys. Why do we use addresses as pseudonyms and not something else, for example some descriptive names, like “watchme1984”? This has been explained well by user Tim S., also on Bitcoin Stack Exchange:

By using addresses, or public keys, we achieve important goals, such as removing the need to somehow register a pseudonym beforehand, reducing the incentives for pseudonym reuse, avoiding blockchain bloat, and making it harder to impersonate other people.

Blockchain privacy refers to the information you disclose by transacting on the blockchain. It applies to all transactions, the ones you send as well as the ones you receive.

Satoshi Nakamoto ponders over on-chain privacy in section 7 of his Bitcoin whitepaper:

The paper summarizes the main problems of blockchain privacy, namely address reuse and address clustering. The first is self-explaining, the latter refers to the ability to decide, with some level of certainty, that a set of different addresses belongs to the same user.

Chris Belcher wrote in great detail about the different kinds of privacy leaks that can happen on the Bitcoin blockchain. We recommend you read at least the first few subsections under “Blockchain attacks on privacy.”

The takeaway is that privacy in Bitcoin isn’t perfect. It requires a significant amount of work to transact privately. Most people aren’t prepared to go that far for privacy. There seems to be a clear trade-off between privacy and usability.

Another important aspect of privacy is that the measures you take to protect your own privacy affect other users as well. If you are sloppy with your own privacy, other people might experience reduced privacy, too. Gregory Maxwell explains this very plainly on the same Bitcoin Talk discussion that we linked above, and concludes with an example:

In this case, it all went well thanks to the philanthropically-minded hacker, but don’t count on that next time.

While the blockchain proves to be a notorious source of privacy leaks, there are plenty of other leaks that don’t use the blockchain, some sneakier than others. These range from key-loggers to network traffic analysis. To read up on some of these methods, please refer again to Chris Belcher’s piece, specifically the section “Non-blockchain attacks on privacy”.

Among a plethora of attacks, Belcher mentions the possibility of someone snooping on your internet connection, for example, your ISP:

However, among the most obvious privacy leaks are exchanges. Due to laws, usually referred to as KYC (Know Your Customer) and AML (Anti-Money Laundering), that are valid in the jurisdictions they operate in, exchanges and related companies often have to collect personal data about their users, building up big databases about which users own which bitcoins. These databases are great honeypots for evil governments and criminals who are always on the lookout for new victims. There are actual markets for this kind of data, where hackers sell data to the highest bidder. To make things worse, the companies that manage these databases often have little experience with protecting financial data, in fact many of them are young start-ups, and we know for a fact that several leaks have already occurred. A few examples are India-based MobiQwik and HubSpot

Again, protecting data against this wide range of attacks is hard, and it is likely that you won’t be fully able to do so. You’ll have to opt for the trade-off between convenience and privacy that works best for you.

Fungibility, in the context of currencies, means that one coin is interchangeable for any other coin of the same currency. This funny word was briefly touched upon in Section 3.2. In the article discussed there, Gregory Maxwell stated

Here, he speaks about the dangers derived from a lack of fungibility. Suppose that you have a UTXO. That UTXO’s history can normally be traced back several hops, fanning out to multitudes of previous outputs. If any of those outputs were involved in any illegal, unwanted, or suspicious activity, then some potential recipients of your coin might reject it. If you think that your payees will verify your coins against some centralized whitelist or blacklist service, you might start checking the coins you receive too, just to be on the safe side. The result is that bad fungibility will bolster even worse fungibility.

Adam Back and Matt Corallo gave a presentation about fungibility at Scaling Bitcoin in Milan in 2016. They were thinking along the same lines:

It seems that privacy and fungibility go hand-in-hand. Fungibility will weaken if privacy is weak, for example as coins from unwanted people may become blacklisted. In the same way, privacy will weaken if fungibility is weak: if there is a blacklist, you will have to ask the blacklist providers about which coins to accept, thereby possibly revealing your IP address, email address, and other sensitive information. These two features are so intertwined that it’s hard to talk about either of them in isolation.

Several techniques have been developed to help people protecting themselves from privacy leaks. Among the most obvious ones is, as noted by Nakamoto>> in Section 3.4, using unique addresses for every transaction, but several others exist. We’re not going to teach you how to become a privacy ninja. However, Bitcoin Q+A has a quick summary of privacy-enhancing technologies, somewhat ordered by how hard they are to implement, at https://bitcoiner.guide/privacytips/. When you read it, you’ll notice that Bitcoin privacy often has to do with stuff outside of Bitcoin. For example, you shouldn’t brag about your bitcoins, and you should use Tor and VPN. The post also lists some measures directly related to Bitcoin:

In a talk at the Breaking Bitcoin conference, Chris Belcher gave an interesting practical example of how privacy has been improved.

He also mentioned this example, among others, on the Privacy page on the Bitcoin wiki.

Note how better privacy can be achieved by building systems on top of Bitcoin, as is the case with Lightning Network:

We noted in Chapter 2 that the need for trust can only increase with layers on top, but that doesn’t seem to be the case for privacy, which can be improved or made worse arbitrarily in layers on top. Why is that? Any layer on top of Bitcoin, as explained in Section 8.2.4, must use on-chain transactions occasionally, otherwise it wouldn’t be “on top of Bitcoin”. Privacy-enhancing layers generally try to use the base layer as little as possible to minimize the amount of information revealed.

The above are somewhat technical ways to improve your privacy. But there are other ways. At the beginning of this chapter, we said that Bitcoin is a pseudonymous system. This means that users in Bitcoin aren’t known by their real names or other personal data, but by their public keys. A public key is a pseudonym for a user, and a user can have multiple pseudonyms. In an ideal world, your in-person identity is decoupled from your Bitcoin pseudonyms. Unfortunately, due to the privacy problems described in this chapter, this decoupling usually degrades over time.

To mitigate the risks of having your personal data revealed is to not give it out in the first place nor to give it to centralized services, which build big databases that can leak (see Section 3.5). An article by Bitcoin Q+A explains KYC and the dangers derived from it. It also suggests some steps you can take to improve your situation.

The article suggests you avoid using exchanges that require KYC/AML and instead trade in private, or use decentralized exchanges like bisq.

For more in-depth reading about countermeasures, refer to the previously mentioned wiki article on privacy, starting at “Methods for improving privacy (non-blockchain)”.

Privacy is very important but hard to achieve. There is no privacy silver bullet. To get decent privacy in Bitcoin, you have to take active measures, some of which are costly and time-consuming.

A block reward is composed of the block subsidy plus transaction fees. The block reward needs to cover Bitcoin’s security costs. We can say for sure that under today’s conditions with regard to block subsidy, transaction fees, bitcoin price, mempool size, hash power, degree of decentralization etc., the incentives for every player to play by the rules are high enough to preserve a secure monetary system.

What happens when the block subsidy approaches zero? To keep things simple, let’s assume it actually equals zero. At this point, the system’s security cost is covered through transaction fees only. What the future holds for us when this happens, we cannot know. The uncertainty factors are numerous and we are left to speculations. For example, Paul Sztorc’s contribution to the subject in his Truthcoin blog is mostly speculations, but he has at least one solid point (please note that M2, as referred to by Sztorc, is a measurement of a fiat money supply):

Today, it is holders who pay for security (via monetary inflation). Tomorrow it will be the spenders’ turn to somehow shoulder this burden, as illustrated below.

When transaction fees are the main motivation for mining, the incentives shift. Most notably, if the mempool of a miner doesn’t contain enough transaction fees, it might become more profitable for that miner to rewrite Bitcoin’s history rather than extending it. Bitcoin Optech has a specific section on this behavior, called fee sniping, written by David Harding:

Throwing a wet blanket over our hopes for the future is the fact that if miners start conducting fee sniping, this will incentivize others to do the same, leaving even fewer honest miners. This could severely impair the overall security of Bitcoin. Harding goes on to list a few countermeasures that can be taken, such as relying on transaction time locks to restrict where in the blockchain the transaction may appear.

So, given that the consensus on finite supply remains, the block subsidy will - thanks to BIP42 which fixed a very-long-term inflation bug - get to zero around year 2140. Will the transaction fees thereafter be enough to secure the network? It’s impossible to say, but we do know a few things:

Since the transition to a fee-only block reward is so far in the future, it might be wise not to jump to conclusions and try to fix the potential issues while we can. For example, Peter Todd thinks there’s an actual risk that Bitcoin’s security budget won’t be enough in the future, and consequently argues for a small perpetual inflation in Bitcoin. However, he also thinks it’s not a good idea to discuss such an issue at this time, as he said on the What Bitcoin Did podcast:

Perhaps we could think of Bitcoin as something organic. Imagine a small, slowly-growing oak plant. Imagine also that you have never seen a fully grown tree in your life. Wouldn’t it be wise then to restrain your control issues instead of setting in advance all the rules on how this plant should be allowed to evolve and grow?

Whether the bitcoin supply will grow past 21 million we cannot say today, and that is probably not so bad. Ensuring that the security budget remains high enough is crucial but not urgent. Let’s have this discussion in 10-50 years, when we know more. If it’s still relevant.

According to Wikipedia, forward compatibility refers to the condition in which an old software can process data created by newer softwares, ignoring the parts it doesn’t understand.

Vice versa, backward compatibility refers to when data from an old software is usable on newer softwares. A change is said to be fully compatible if it’s both forward and backward compatible.

A change to the Bitcoin consensus rules is said to be a soft fork if it is fully compatible. This is the most common way to upgrade Bitcoin, for a number of reasons that we’ll discuss further in this chapter. If a change to the Bitcoin consensus rules is backward compatible but not forward compatible, it is called a hard fork.

For a technical overview of soft forks and hard forks, please read chapter 11 of Grokking Bitcoin. It explains these terms and also dives into the upgrade mechanisms. It’s recommended, although not strictly necessary, to get a grip on this before you continue reading.

Bitcoin is not the same today as it was when the genesis block was created. Several upgrades have been made throughout the years. In 2017, Eric Lombrozo spoke at the Breaking Bitcoin conference (video) about Bitcoin’s different upgrading mechanisms, pointing out how much they have evolved over time. He even explained how Satoshi Nakamoto once upgraded Bitcoin through a hard fork.

He points out that, be it intentionally or not, this hard fork created opportunities for future soft forks, namely the Script operators (opcodes) OP_NOP1-OP_NOP10. We’ll look more into this code change in chapter 9. These opcodes have been used for two soft forks so far: BIP65 (OP_CHECKLOCKTIMEVERIFY), and BIP113 (OP_SEQUENCEVERIFY).

Lombrozo also provides an overview of the way upgrade mechanisms have evolved throughout the years, up until 2017. Since then, only one other major upgrade, which we analyze in Section 5.2.3, has been deployed. The long and somewhat chaotic process that led to its activation has helped us gain further insights on upgrading mechanisms in Bitcoin.

During the activation of any fork, be it hard or soft, miner activated or user activated, there’s the risk of a long-lasting chain split. A split that lingers for more than a few blocks can cause severe damage to the sentiment around Bitcoin as well as to its price. But above all, it would cause great confusion over what Bitcoin is. Is Bitcoin this chain or that chain?

The risk with a user activated soft fork is that the new rules get activated even if the majority of the hash power doesn’t support them. This scenario would result in a long-lasting chain split, which would persist until the majority of the hash power adopts the new rules. It could be especially hard to incentivize miners to switch to the new chain if they had already mined blocks after the split on the old chain, because by switching branch they would be abandoning their own block rewards. However, it’s worth mentioning a remarkable episode: in March 2013 a long-lasting split, explained in Section 9.2.3, occurred due to an unintentional hard fork and, contrary to this incentive, two major mining pools made the decision to abandon their branch of the split in order to restore consensus.

On the other hand, the risk with a miner activated soft fork is a consequence of the fact that miners can engage in false signaling, which means that the actual share of the hash power that supports the change could be smaller than it looks. If the actual support doesn’t comprise a majority of the hash power, we’d probably see a long-lasting chain split similar to the one described in the previous paragraph. This, or at least a similar issue, has happened in reality when BIP66 was deployed (see Section 9.2.4), but it got resolved within 6 blocks or so.

Bitcoin grows and evolves with time. Different upgrade mechanisms have been used over the years and the learning curve is steep. More and more sophisticated and robust methods keep being invented, as we learn more about how the network reacts.

To keep Bitcoin in harmony, soft forks have proven to be the way forward, but the big question is still not fully answered: how do we safely deploy soft forks without causing discord?

The importance of adversarial thinking also extends to everyday Bitcoin users to some degree, not only to hardcore Bitcoin developers and experts. Ragnar Lifthasir mentions in a tweetstorm how simplistic narratives around Bitcoin - for example, “just HODL” - can be degrading to Bitcoin itself, and concludes by saying

He refers to these simplistic narratives as monomanias. Through this definition he’s saying that by focusing on a single thing - for example, “just HODL”- you risk to overlook the arguably more important stuff, such as keeping your Bitcoin secure or doing your best to use Bitcoin in a trustless manner.

There are a lot of known weaknesses in Bitcoin, and many of them are actively being exploited. To get a glimpse of that, have a look at the Weaknesses page on Bitcoin wiki. There are mentioned a wide variety of problems, such as wallet theft and denial-of-service attacks.

This type of attack is called Sybil attack, and it occurs whenever a single entity controls multiple nodes in a network and uses them to appear as multiple entities.

As the quote also mentions, the Sybil attack is not effective on the Bitcoin network because there is no voting through nodes or other numerable entities, but rather through computing power (see Section 1.1). Nonetheless, this flat structure leaves the system susceptible to other attacks. The Bitcoin wiki page also outlines other possible attacks, such as information hiding (often referred to as eclipse attack), and the way Bitcoin Core implements some heuristic countermeasures against such attacks.

The above are examples of real threats that need to be taken care of.

Eric Voskuil writes on his Cryptoeconomics wiki page about what he calls the “axiom of resistance”:

What he’s essentially saying is that only when one assumes it’s possible to create a system that states can’t control, is it meaningful to try.

This means that to work on Bitcoin you should accept the axiom of resistance, otherwise you’d better spend your time on other projects. Acknowledging that axiom helps you focusing your development efforts on the real problems at hand: coding around state-level adversaries. In other words, think adversarially.

Bitcoin Core’s source code is maintained in a Git repository hosted on GitHub. Anyone can clone that very repository without asking for any permission, and then inspect, build, or make changes to it locally. This means that there are many thousands of copies of the repository spread throughout the globe. These are all copies of the same repository, so what makes this specific GitHub Bitcoin Core repository so special? Technically it’s not special at all, but socially it has become the focal point of Bitcoin development.

Bitcoin and security expert Jameson Lopp explains this very well in a blog post titled “Who Controls Bitcoin Core?”:

He goes on to explain how Bitcoin Core’s software is maintained and secured against malicious code changes. The general takeaway from this full article is summarized at its very end:

Bitcoin Core developer Eric Lombrozo talks further about the development process in his Medium post titled “The Bitcoin Core Merge Process”.

It should be noted that pull requests can take a very long time before being merged to the repository by maintainers, and that’s usually due to a lack of review, see Section 7.5, which is often due to a lack of reviewers.

Lombrozo also talks about the process that surrounds consensus changes, but that’s a bit beyond the scope of this chapter. See Chapter 5 for more information on how the Bitcoin protocol gets upgraded.

We’ve established that anyone can write code for Bitcoin Core without asking for any permission, but not necessarily have it merged to the main Git repository. This affects any modification, from changing color schemes of the graphical user interface, to the way peer-to-peer messages are formatted, and even consensus rules, i.e. the set of rules that define a valid blockchain.

Probably equally important is that users are free to develop systems on top of Bitcoin, without asking for any permission. We’ve seen countless successful software projects that were built on top of Bitcoin, such as:

Without permissionless development, many of these projects would not have been possible. As stated in Section 1.3, if developers had to ask for permission to build protocols on top of Bitcoin, only the protocols allowed by the central developer granting committee would be developed.

It is common for systems like the ones listed above to be themselves licensed as open source software, which in turn allows for people to contribute, re-use, or review their code without asking for any permission. Open source has become the gold standard of Bitcoin software licensing.

Not having to ask for permission to develop Bitcoin software brings an interesting and important option to the table: you can write and publish code, in Bitcoin Core or any other open source project, without revealing your identity.

Many developers choose this option by operating under a pseudonym and trying to keep it detached from their true identity. The reasons for doing this can vary from developer to developer. One pseudonymous user is ZmnSCPxj. Among other projects, he contributes to Bitcoin Core and Core Lightning, one of several implementations of Lightning Network. He writes on his web page:

In his case, the reason for using a pseudonym is to be judged on his merits and not on who the person or persons behind the pseudonym is or are. Interestingly, he revealed in an article on CoinDesk that the pseudonym was created for a different reason.

Using a pseudonym indeed allows you to speak more freely without putting your personal reputation at risk should you say something stupid or make some big mistake. As it turned out, his pseudonym got very reputable and in 2019 he even got a development grant, which is in itself a testament to Bitcoin’s permissionless nature.

Arguably, the most well-known pseudonym in Bitcoin is Satoshi Nakamoto. It’s unclear why he chose to be pseudonymous, but with hindsight it was probably a good decision for multiple reasons:

Notice that these points don’t just hold true for Satoshi Nakamoto, but for anyone working in Bitcoin or holding significant amounts of the currency, to varying degrees.

Open source developers often make use of open source libraries developed by other people. This is a natural and awesome part of any healthy ecosystem. But Bitcoin software deals with real money and, in light of this, developers need to be extra careful when choosing which third party libraries it should depend on.

In a philosophical talk about cryptography (you may find the video here), Gregory Maxwell wants to redefine the term “cryptography” which he believes to be too narrow. He explains that fundamentally information wants to be free, and makes his definition of cryptography based on that:

He then introduces the term selection cryptography, referred to as the art of selecting cryptographic tools, and explains why it is an important part of cryptography. It revolves around how to select cryptographic libraries, tools, and practices, or as he says “the cryptosystem of picking cryptosystems”.

Using concrete examples, he shows how selection cryptography can easily go horribly wrong, and also proposes a list of questions you could ask yourself when practicing it. Below is a distilled version of that list:

While this is not the ultimate guide to success, it can be very helpful to go through these points when doing selection cryptography.

Due to the issues mentioned above by Maxwell, Bitcoin Core tries really hard to minimize its exposure to third party libraries. Of course, you can’t eradicate all external dependencies, otherwise you’d have to write everything by yourself, from font rendering to implementation of system calls.

This section is named “Review”, rather than “Code review”, because Bitcoin’s security relies heavily on review at multiple levels, not just source code. Moreover, different ideas require review at different levels: a consensus rule change would require a deeper review at more levels compared to a color scheme change or a typo fix.

On its way to final adoption, an idea usually flows through several phases of discussion and review. Some of these phases are listed below:

At each of these phases people with different points of view and backgrounds review the available information, be it the source code, a BIP, or just a loosely described idea. The phases are usually not performed in any strict top-down manner, indeed multiple phases can happen simultaneously, and sometimes you go back and forth between them. Different people may also provide feedback during different phases.

One of the most prolific code reviewers on Bitcoin Core is Jon Atack. He wrote a blog post about how to review pull requests in Bitcoin Core. He emphasizes that a good code reviewer focuses on how to best add value.

He highlights the fact that review is a truly limiting factor in Bitcoin Core. Lots of good ideas get stuck in a limbo where no review occurs, pending. Notice that reviewing is not only beneficial to Bitcoin, but also a great way to learn about the software while providing value to it, at the same time. Atack’s rule of thumb is to review 5-15 PRs before making any PR of your own. Again, your focus should be on how to best serve the community, not on how to get your own code merged. On top of this, he stresses the importance of doing review at the right level: is this the time for nits and typos, or does the developer need more of a conceptually-oriented review?

The second half of the post consists of some useful hands-on technical guidance on how to actually do the reviewing, and provides links to important documentation for further reading.

Bitcoin Core developer and code reviewer Gloria Zhao has written an article containing questions she usually asks herself during a review. She also states what she considers to be a good review.

Her idea that a good review should focus on what’s most needed at a specific point in time aligns well with Jon Atack’s advice. She proposes a list of questions that you may ask yourself at various levels of the review process, but stresses that this list is not in any way exhaustive nor a straight-out recipe. The list is illustrated with real-life examples from GitHub.

Lots of people work with Bitcoin open source development, either for Bitcoin Core or for other projects. Many do it in their spare time without getting any compensation, but some developers are also getting paid to do it.

Companies, individuals, and organizations who have an interest in Bitcoin’s continued success can donate funds to developers, either directly or through organizations that in turn distribute the funds to individual developers. The website polylunar.com has compiled a list of grants given out by a broad range of individuals, organizations, and companies. There are also a number of Bitcoin-focused companies that hire skilled developers to let them work full-time on Bitcoin.

People sometimes get the impression that there’s a lot of infighting and endless heated debates among Bitcoin developers, and that they are incapable of making decisions.

For example, the Taproot deployment mechanism, described in Section 5.2.3, was discussed over a long period of time during which two “camps” formed. One wanted to “fail” the upgrade if miners hadn’t overwhelmingly voted for the new rules after a certain moment, while the other wanted to enforce the rules after that moment no matter what. Michael Folkson summarizes the arguments from the two camps in an email to the Bitcoin-dev mailing list.

The debate went on seemingly forever, and it was really hard to see any consensus on this forming any time soon. This got people frustrated and as a result the heat intensified. Gregory Maxwell (as user nullc) worried on Reddit that the lengthy discussions would make the upgrade less safe.

Eventually, this dispute got resolved thanks to a new proposal by David Harding and Russel O’Connor called Speedy Trial, which entailed a comparatively shorter signaling period for miners to lock in activation of Taproot, or fail fast. If they activated it during that window of time, then Taproot would be deployed approximately 6 months later. This upgrade is covered in more detail in Chapter 5.

Someone who’s not used to Bitcoin’s development process would probably think that these heated debates look awfully bad and even toxic. There are at least two factors that make them look bad, in some people’s eyes:

Most Bitcoin developers would argue that this openness brings about a good and healthy environment, and even that it is necessary for producing the best outcome.

As hinted in Section 6.2, the second bullet above can be very beneficial but comes with a downside. An attacker could use stalling tactics, like the ones outlined in the Simple Sabotage Field Manual, to distort the decision making and development process.

Another thing worth mentioning is that, as noted in Section 7.4, since Bitcoin is money and Bitcoin Core secures unfathomable amounts of money, security in this context is not taken lightly. This is why seasoned Bitcoin Core developers might appear very hard-headed, which attitude is usually warranted. Indeed, a feature with a weak rationale behind it is not going to be accepted. The same would happen if it broke the reproducible builds (described in Section 2.1), added new dependencies, or if the code didn’t follow Bitcoin’s best practices.

New (and old) developers can get frustrated by this. But, as is customary in open source software, you can always fork the repository, merge whatever you want to your own fork, and build and run your own binary.

Scaling has been a focal point of discussion since the genesis of Bitcoin. The very first sentence of the very first email in response to Satoshi’s announcement of the Bitcoin whitepaper on the Cryptography mailing list was indeed about scaling:

The conversation in itself might not be very interesting nor accurate, but it shows that scaling has been a concern from the very beginning.

Discussions over scaling reached their peak interest around 2015-2017, when there were many different ideas circulating about whether and how to increase the maximum block size limit. That was a rather uninteresting discussion about changing a parameter in the source code, a change that didn’t fundamentally solve anything but pushed the problem of scaling further into the future, building technical debt.

In 2015, a conference called Scaling Bitcoin was held in Montreal, with a follow-up conference six months later in Hong Kong and thereafter in a number of other locations around the world. The focus was precisely on how to address scaling. Many Bitcoin developers and other enthusiasts gathered at these conferences to discuss various scaling issues and proposals. Most of these discussions didn’t revolve around block size increases but on more long-term solutions.

After the Hong Kong conference in December 2015, Gregory Maxwell summarized his view on many of the issues that had been debated, starting off with some general scaling philosophy.

He speaks about the trade-off between throughput and decentralization. If you allow for bigger blocks, you will push some people off the network because they won’t have the resources to validate the blocks anymore. But on the other hand, if access to block space becomes more expensive, fewer people will be able to afford using it as a dispute resolution mechanism. In both cases, users are pushed towards trusted services.

He continues by summarizing the many approaches to scaling presented at the conference. Among them are more computationally efficient signature verifications, segregated witness including a block size limit change, a more space-efficient block propagation mechanism, and building protocols on top of Bitcoin in layers. Many of these approaches have since been implemented.

As hinted above, scaling Bitcoin doesn’t necessarily have to be about increasing the block size limit or other limits. We now go through some general approaches to scaling, some of which don’t suffer from the throughput-decentralization trade-off mentioned in the previous section.

Imagine you discover a bug in Bitcoin Core, a bug that allows anyone to remotely shut down a Bitcoin Core node by using some specially crafted network messages. Imagine also you are not malicious and would like this issue to remain unexploited. What do you do? If you remain silent about it, someone else will probably discover the issue, and you can’t be sure that person won’t be malicious.

When a security issue is discovered, the person discovering it should employ responsible disclosure which is a term often used among Bitcoin developers. The term is explained on Wikipedia:

This means that if you find a security issue, you should report this to the team responsible for the system. But what does this mean in the context of Bitcoin? As noted in the Open source chapter, no one controls Bitcoin, but there’s currently a focal point for Bitcoin development, namely the Bitcoin Core Github repository. The maintainers of said repository are responsible for the code in it, but they’re not responsible for the system as a whole - no one is. Nevertheless, the general best practice is to send an email to security@bitcoincore.org.

In an email thread titled “Responsible disclosure of bugs” from 2017, Anthony Towns tried to summarize what he perceived to be the current best practices. He had collected inputs from several sources and different people to inform his view on the subject.

This list displays how careful one must be when publishing patches for Bitcoin, since the patch itself might give away the vulnerability. The fourth bullet is particularly interesting as it explains how to test whether a patch has been disguised well enough. Indeed, if a few really experienced developers can’t spot the vulnerability even knowing that the patch fixes one, it will probably be really hard for others to discover it.

The thread that led to this email was discussing whether, when, and how to disclose vulnerabilities to altcoins and other implementations of Bitcoin. There is no clear answer here. “Helping the good guys” seems like the sensible thing to do, but who decides who they are and where does one draw the line? Bryan Bishop argued that helping altcoins and even scamcoins defend themselves against security exploits was a moral duty.

Also leading up to Town’s email above was a post by Gregory Maxwell, in which he argued that security vulnerabilities could be more severe than they appear.

So, even if a vulnerability seems hard to exploit, it might be best to assume that it’s easily exploitable and you just haven’t figured out how yet.

He also mentions how “it’s somewhat incorrect to call this thread anything about disclosure, this thread is not about disclosure. Disclosure is when you tell the vendor. This thread is about publication and that has very different implications. Publication is when you’re sure you’ve told the prospective attackers”. This last observation concerning the distinction between disclosure and publication is an important one. The easy part is responsible disclosure; the hard part is sensible publishing.

Bitcoin started out as a one-man (at least that’s what its creator’s pseudonym suggests) project, and bitcoin had initially little to no value. As such, vulnerabilities and bug fixes were not as rigorously handled as they are today.

The Bitcoin wiki has a list of common vulnerabilities and exposures (CVEs) that Bitcoin has gone through. This section constitutes a little exposé of some of the security issues and incidents from the early years of Bitcoin. We won’t cover them all, but we selected a few that we find especially interesting.

The book is written in Asciidoctor. The main file for the book is btcphilosophy.adoc. This file then include::s each chapter as a separate file.

There’s also a separate asciidoctor file, sources/sources.adoc, that collects all the copied resources that the book refers to. They are kept separate to not make browsing the book itself too heavy.

To build this book, clone the GitHub repository:

and then build using any of the two methods below