Onboarding to Bitcoin Core

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.)

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.

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.

  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.
  • 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]

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.

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.

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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store