Onboarding to Bitcoin Core

Over the past year, I’ve fallen down the wonderful rabbit hole of contributing to Bitcoin Core. Along the way, I’ve been very fortunate to receive guidance and support from many people, and I’ve gleaned a few tricks of my own. In this post, I’d like to consolidate and share some of the tools I’ve found effective.

Contributing to Bitcoin Core is only one way to help advance the protocol. Other options include (and extend far beyond) participating in mailing list discussions, researching attack vectors or scaling techniques, contributing to one of the Lightning clients [1] [2] [3] [4], or developing relevant tooling like the secpk256k1 library or a better testing infrastructure. But this post doesn’t cover any of those topics.

This post is about Bitcoin Core, through the lens of my onboarding experience. I hope it helps you identify your own path to contribute.

Before you start

• First, read the white paper. Really. If you haven’t read it yet, quit reading this and go straight there.
• Understanding the conceptual fundamentals of how Bitcoin works is necessary to make meaningful PRs to Bitcoin Core (including most small ones). There’s a lot of ways to get exposure. I’d start with reading one of the books (Mastering Bitcoin, Programming Bitcoin, or Grokking Bitcoin). For maneuvering online material, I would visit Jameson Lopp’s resource list or the Chaincode Labs curriculum. The first has more breadth, but the second is specifically geared towards protocol development.
• If your goal is to contribute to Bitcoin Core, don’t get stuck trying to learn the details of every concept. There are many topics with infinite nuance. The goal is to get a high level understanding and be exposed to different parts of the system. It takes time to internalize the fundamentals of how this distributed consensus system operates.
• The Bitcoin Optech weekly newsletter is *the best* way to learn about the technical developments in the ecosystem. Dave Harding is a word wizard that makes it accessible to stay up to date. I highly recommend subscribing.

Choose what to tune out

That process doesn’t stop once you’ve decided you want to contribute to Bitcoin Core. There is enough complexity and development within the project to keep anyone busy for multiple lifetimes. To choose how you spend your attention, it’s helpful to identify what you *don’t* want to attend to (at least for now.)

To make changes, developing breadth and depth are both important. Finding the right balance is an art that develops over time. Breadth increases exposure to new concepts and helps identify what work is relevant. In order to propose a PR that improves the codebase, understanding the bigger picture context is just as crucial as digging into one aspect and familiarizing yourself fully with your proposed changeset.

People who want to help love recommending more things you should read/learn/consume/understand… I’ve already explicitly done so above- I recommended 3 books, 2 infinite lists of material, and 1 weekly newsletter. That too, in the “before you start” section! There’s also implicit pressure when you interact with others to be knowledgeable about a vast number of topics to contribute to whatever conversation arises. This is great for breadth, but only you can create your path to pursue depth. To make a PR you need to develop specific knowledge (regardless of how small the surface area) that allows you to offer the change. Don’t get stuck in the “consume” phase, focus will ensure you continue to the “create” phase.

This is even more crucial if you aren’t spending all day working on Bitcoin. It’s an incredibly complex project. Create space. Even seemingly simple tasks can take a while.

Ok, enough life advice for now. Back to some project specifics…

Get familiar with the codebase

• Clone the repo, compile it and run tests.
• Read through the developer docs in the project:

1. The Contributing to Bitcoin Core guide is essential knowledge for getting started, including pull request philosophy and how the review process works.
2. The Developer Notes are good to skim through initially, then revisit before you’re opening a PR to ensure you adhere to the current standards.
3. The Productivity Notes have tricks that are *extremely useful* to acquire at different parts of developing your workflow. I highly recommend doing the first four right away (install ccache, use ./configure to your advantage, compile with make -j [num-cores], and provide build targets).

• Read the onboarding blog posts written by Jimmy Song and John Newbery.
• Attend the weekly PR review club. Reviewing PRs is crucial to the project. More relevantly, as you are getting started, it is an effective way to learn about the codebase and merge process. The review club is a way to get familiar with specific changesets with support from others. The value you can derive from review club is a direct product of the energy you are willing to invest. The weekly notes help draw awareness to patterns such as technical architecture and historical context, which takes a lot longer to develop independently. Whether you tune in to the meeting and just lurk or spend time spelunking around the code ahead of time and participate, you are sure to learn a lot. Preparing ahead of time allows you to take advantage of the session to vocalize questions or build confidence around your understanding of the code.

Find your first PR

As you start acclimatizing to the codebase, you might be feeling ready to make a PR, but not be sure how to choose a contribution that is valuable to the project. It’s highly likely that the various avenues mentioned in this post so far are plenty for helping expose you to a meaningful niche waiting to be worked on. But if you’re still searching, here are some other options:

• Monitor the labels good first issue and up for grabs. With up-for-grabs, make sure you filter to include both open and closed.
• Grep the codebase for the string “TODO” and parse through to see if any look reasonable for your level of familiarity with the codebase. I’ve come across some in tests that look beginner-friendly.
• Choose a section of the codebase (aka one of the sections in the contributing docs) and pay attention to relevant PRs being opened. If you follow along with the PR conversations, you will *definitely* notice follow up to-do’s. Also, think critically about how to test the changes. Opening PR’s to address follow ups and increase test coverage will be much appreciated. You can also gain familiarity with a section by visiting the relevant the pr-review-club history.

The nature of open source contributions means there is no centralized project management system. It follows that there are changesets that are useful to the project that are not necessarily the best use of the PR author’s attention and skillset. So, part of onboarding as a contributor is finding the (niched but) useful contributions that are along your learning curve. My first PR was seeing through this up-for-grabs PR.

I’ve been very surprised to observe how much low-hanging fruit there is to contribute. I would have never expected before taking a careful look at the Github project.

For the amount of “street-cred” and intimidation the Bitcoin Core project comes with, it is incredible to see how accessible contributing is. Observing the never-ending list of (both simple and complex) todos has really put in perspective how young the Bitcoin project is and the blatant need for more contributors.

Embrace the internet to further your learning

When I started learning C++, I got some great books, but honestly, I’m still making my way through them.

Hands-on learning works best for me, and I was focused on learning the most relevant parts of the language that would allow me to read the Bitcoin Core codebase.

So, I write code. When I come across a new C++ concept, I read the docs and try to isolate the functionality in an example program. I always have a tmux tab open that I call c++ play. These programs also serve as documentation of concepts I have tinkered with. Another great tool is the Compiler Explorer. I find the color-coded highlighting particularly helpful for comparing multiple ways of executing the same functionality to see if the differences are superficial, get optimized out, or fundamentally change the work being done.

To dive deeper into specific C++ concepts, I’ve been enjoying watching CppCon talks, especially the “Back to Basics” track.

This is a good start, but sometimes I want to talk to a human. Initially, I sometimes had questions around punctuation that I didn’t know how to google for (e.g. learning that a carefully placed : indicates an initializer list). These days, I more often want to confirm the understanding I’ve gleaned from docs and tinkering.

I have found some wonderful online communities with strangers willing to help point me in the right direction. For C++ there’s a cpplang slack, a ##C++-general irc channel, and #include<C++> community with a discord server. I’ve been amazed at how helpful internet strangers have been. I’ve also hopped on the #git irc channel for git specific questions.

Two notes:

1. I encourage asking for help, but please be respectful and thoughtful about how you do it. Do the due diligence and try to find your answer on your own first. Be gracious and use communication channels appropriate for your question. People don’t owe you answers. Any help offered is out of generosity.
2. Selecting an irc client: I’ve found irccloud to be a simple, aesthetically pleasing client that doesn’t require you to invest in tooling. There is also the option of having a persistent username and logs for a small fee. There are many options for irc clients, but I recommend focusing your decision making power on more influential decisions and simply choosing a client at whim.

Most of my favorite Bitcoin resources are sprinkled throughout this post, but here are some I’d like to highlight for maneuvering the code:

• Developer reference for P2P messages and RPCs
• Bitcoin stack exchange has discussion specific to protocol development scattered through various questions and answers. It doesn’t get indexed very well by google, so it’s worth visiting the site directly and searching by topic
• Fabian Jahr has put together a comprehensive doc around debugging techniques [talk] [gist]
• I enjoyed the architecture overview given by James O’Beirne [talk] [slides]

If you are grappling with a technical concept and aren’t sure what to try, please reach out to me! I definitely don’t have all the answers, but I’m happy to brainstorm avenues to find solutions.

More avenues for learning about Bitcoin

There are a lot of great ways to increase your exposure to the developments in the Bitcoin ecosystem. Here are some options that are high signal to noise:

• There is an irc meeting every Thursday at 19:00 UTC in #bitcoin-core-dev
• The #bitcoin-core-pr-reviews channel is also sometimes used to discuss processes and tooling, so paying attention might be helpful.
• Revisit the Chaincode Labs bitcoin curriculum. There is so much great material in there- talks, papers, and even code challenges!
• Attend high-quality conferences.
• Watch videos from previous conferences. I learned a lot by using my commute to listen to and watch videos from Bitcoin Edge Dev++ [2017] &[2018].
• If you live in a city where it is an option, attend a Socratic seminar.
• Read the bitcoin wiki, specifically the protocol and privacy pages.
• Chaincode recently started a protocol focused podcast.

Becoming familiar with the Bitcoin protocol is no simple task, especially if you have other life commitments like a full-time job or being a student. I use spaced repetition flashcards to memorize new information. I highly recommend. It helps catalyze your ability to persist information so you can spend more time on acquiring new concepts or applying what you’ve learned. I use Anki to create flashcards from my laptop and review them from my phone. This has the added perk of doing concept learning on the go and allowing any spare time blocks to be spent on a specific task in the codebase.

Keep an eye on the Chaincode residency program. I feel deeply grateful to have been able to participate last summer, and it was game-changing in terms of onboarding me to the project. But keep in mind that its a highly competitive program, and any contributions to Bitcoin Core you do ahead of time will increase your chances of acceptance (participating in the review club, reviewing PRs, making PRs, etc.).

Seriously. Do It.

Contributing to Bitcoin Core is hard, but it is far from impossible. I had never written (or really even read) any C++ before starting this journey. It’s natural to be intimidated, but don’t let that stop you.

Be patient with yourself. Everything I’ve ever done in Bitcoin Core has taken at least one or two forevers to accomplish. One time I spent 3 full days in the integration tests iterating through different ways of filling a mempool with transactions. My first few attempts required the test setup to be unreasonably long, so I had to keep trying different methods. Don’t get stuck with an internal narrative of “this should be easy.” Focus on what you can learn and keep trying.

When starting off it’s easy for “Bitcoin Core” and “core contributors” to seem like this one big nebulous organization that’s impossible to break into, but it is useful to keep perspective that the contributors are just individuals who are passionate about Bitcoin. I’ve been pleasantly surprised to discover how helpful and supportive people have been. Everyone who works on the project is extremely bandwidth constrained, so if you are making meaningful contributions, people are encouraging.

This is important. Don’t start by correcting typos in PRs. Be patient, invest in your learning, observe the project, and identify how you can make meaningful contributions.

Wherever you are along your learning curve, you can be an asset to the project. If you are committed to dedicating your energy and have the ability to think critically and learn, you are an asset. Don’t let arrogance or insecurity steer you astray.

To conclude, some whimsical ponderings…

If we were to draw a picture of the various learning paths to contribute to Bitcoin Core, it surely wouldn’t be nicely ordered and linear like a blockchain. Pursue your own journey, take some scenic tours, and have a great time.

Navigating the open source realm reminds me a lot of off-trail backpacking.

With backpacking, I first inspect the area I want to visit on a topographic map (topo) and draw a rough path of my intended journey, trying to stay in the gentlest terrain. The topos of the bitcoin realm have nothing on the USGS maps that so wonderfully help me navigate through the Sierras. So, when navigating Bitcoin, you first have to piece together a rough map of the area with snippets of understanding, and then chart out an approach. My hope with this post is to make that process slightly easier.

Hiking the actual path requires constant iteration. With every step, you take in new information that you use to identify the path of least resistance so you can utilize your energy to adventure deep into the mountainous terrain. You have to pay attention to the details of every step, but also to the macro route it is amounting to.

The process is similar in Bitcoin. As you learn more, you get views of the upcoming terrain and have to constantly course correct to keep yourself moving forward in a reasonable way. Sometimes you hit a cliff and have to backtrack and try an alternate route. Path finding requires a lot of energy and attention. You have to be a navigator and a hiker.

I could probably double the length of this post by diving into the similarities between my experiences, but instead, I’ll end it here with this-

Good luck! I hope to see you on GitHub :)

If you have questions or suggestions, please DM me on twitter.

Thank you to my reviewers: Jonas, Carla and Paul.