Why Code Review Is a Security Practice in Bitcoin Development
A change can look straightforward and still have effects its author did not expect. A bug fix might miss an edge case, a new feature might make it easier to exhaust a node’s resources, or a small adjustment might change behavior elsewhere in the software.
Code review helps developers investigate these possibilities before a change is accepted. It involves understanding the problem, examining the proposed solution, testing its behavior, and asking what might have been overlooked.
In this article, we’ll use Bitcoin Core as an example to explore why review matters, what reviewers look for, and how developers can get involved. Other Bitcoin projects have their own contribution processes, but many of the same principles apply.
Bitcoin Core validates transactions and blocks and connects nodes across the peer-to-peer network. A mistake in consensus-critical code could cause nodes to disagree about whether a block is valid. A vulnerability in networking code could allow an attacker to crash a node or consume its resources.
Review cannot guarantee that software is free from bugs or vulnerabilities. But it is an important security practice: it gives other developers a chance to challenge assumptions, check the implementation, and identify problems before they reach users.
Why Review Matters
Bitcoin Core operates through an open contribution process in which developers can propose changes, test patches, and review other contributors' work. The process allows people with different areas of expertise to examine the codebase, while requiring proposed changes to meet the project's technical standards before maintainers accept them.
The level of scrutiny depends on what a change affects. A documentation update has different implications from a modification to transaction validation or peer-to-peer networking, where errors can affect node behaviour and reliability.
Reviewers need to establish whether a patch solves the problem it was designed to address, handles relevant edge cases, and preserves expected behaviour elsewhere in the system. They also consider whether the implementation introduces security risks, such as unsafe handling of unexpected inputs or resource consumption that could be exploited by remote peers.
Consensus-critical code requires particularly careful examination because mistakes can affect how nodes determine whether blocks and transactions satisfy Bitcoin's consensus rules. Bitcoin Core's contribution guidelines specify a higher bar for peer review when changes affect consensus-critical code, reflecting the potential consequences of introducing errors into this part of the software.
The project's published security advisories document vulnerabilities discovered in previous versions of Bitcoin Core, including issues involving denial of service and consensus failures. These cases demonstrate the range of problems that can affect Bitcoin software and why changes need to be examined in the context of the components they modify.
What Developers Look for During a Review
A reviewer begins by understanding the problem a pull request addresses, then examines the implementation, its interactions with other components, and the evidence provided to demonstrate that the change works as intended.
Understanding the Problem and the Proposed Solution
A pull request should explain what needs to change, why the change is necessary, and how the proposed implementation addresses the problem. This context allows reviewers to assess the technical approach before examining individual lines of code.
For example, a patch intended to improve how a node processes a particular network message needs to explain the existing behaviour and the problem the modification is meant to resolve. If the implementation addresses only one observed symptom while leaving the underlying issue unresolved, reviewers may ask for further investigation or a different approach.
Bitcoin Core's contribution guidelines ask authors to describe their changes and explain their reasoning, giving reviewers the information needed to evaluate the proposal and understand its purpose in the future.
Examining Edge Cases
Reviewers also consider how the implementation behaves under conditions that may not be covered by its primary use case. A function may handle valid input correctly while failing when it receives malformed data, encounters an unexpected sequence of events, or needs to recover from an error.
In peer-to-peer networking code, this can involve examining how a node processes messages from other peers and whether particular inputs could cause crashes or excessive resource consumption. In validation code, the focus may be on whether the implementation handles relevant conditions correctly and preserves the expected application of consensus rules.
These questions help reviewers identify missing safeguards and determine whether additional tests or changes to the implementation are necessary.
Tracing the Effects Across the Codebase
A patch may modify only a small part of the codebase while affecting components that depend on its behaviour. Reviewers therefore need to understand relevant dependencies and consider whether the change could introduce regressions or alter an interface used elsewhere.
Bitcoin Core's developer notes provide guidance on development practices, including testing requirements for changes that affect externally observable behaviour. These practices help contributors determine what needs to be checked when a proposed modification changes how the software operates.
The amount of investigation depends on the change itself, with modifications to consensus-critical logic and other security-sensitive components requiring particular care.
Checking the Tests
Tests provide evidence about how a change behaves, and reviewers assess whether that evidence is sufficient for the problem being addressed. Bitcoin Core's developer notes recommend automated tests for externally observable changes, including new features and bug fixes, and describe how tests should be organised around different types of modifications.
A reviewer may examine whether tests reproduce the original problem, verify the expected behaviour after the fix, and cover relevant edge cases. Depending on the change, this could involve unit tests, functional tests, fuzz testing, or targeted manual testing.
Bitcoin Core's testing documentation provides resources for understanding the project's testing infrastructure. Reviewing the tests alongside the implementation helps contributors identify behaviours that still need to be investigated.
How a Pull Request Moves Through Review
Code review develops through discussion between the author and the people examining the proposed change. Reviewers may question the technical approach, identify problems in the implementation, or request additional tests, while the author responds with explanations, revisions, or further evidence.
The process begins with an assessment of the proposal's purpose and technical rationale. Once reviewers understand what the change is intended to accomplish, they can examine the implementation and determine whether it meets the project's requirements.
Feedback may lead to several revisions before the patch is ready for a decision. Reviewers then assess the updated changes, while maintainers consider the review and other relevant requirements when deciding whether to merge the pull request.
Bitcoin Core's contribution guidelines explain this workflow and the role of peer review in evaluating proposed changes. The time required varies according to the complexity of the patch, the availability of reviewers, and the amount of discussion needed to resolve technical questions.
For contributors, understanding this process helps set expectations about the work involved in getting a change accepted and explains why responding carefully to review feedback is part of open-source development.
Why Testing and Code Review Work Together
Automated tests can verify specific behaviours and help detect regressions, while code review allows developers to question whether the tests cover the relevant scenarios and whether the implementation introduces assumptions that could fail elsewhere.
Consider a proposed change to how a node processes messages from its peers. Tests may confirm that a valid message is handled correctly, while a reviewer may investigate how the implementation responds to unexpected data or repeated messages that place additional demands on the node. That investigation could reveal a missing test or a condition the implementation needs to handle differently.
This is how review and testing inform one another. Tests provide repeatable evidence about particular behaviours, and reviewers examine the assumptions behind the implementation and the coverage provided by those tests. Neither can establish that every possible defect has been eliminated, but together they support a more thorough evaluation of the change.
Getting Started With Bitcoin Core Code Review
You do not have to begin by reviewing a complex change to consensus-critical code. A more practical starting point is a focused pull request in an area you understand or want to learn about.
The Bitcoin Core contribution guide explains the contribution workflow and review expectations, while the developer notes and testing documentation provide further guidance on development practices and how to test changes.
After becoming familiar with these resources, a developer can choose a pull request in an area they understand or want to investigate. Reading the description establishes the purpose of the change, while examining the diff and tracing the relevant code helps reveal how the implementation works. The reviewer can then inspect the available tests, identify questions about the proposed behaviour, and reproduce the reported issue where possible.
Once you have that background, you can approach a review in a few steps.
Start With the Description
Read what the author says the patch does and why it is needed. If the pull request links to an issue or earlier discussion, follow that context.
Before judging the solution, try to explain the problem in your own words.
Read the Change in Context
Examine the diff, then look at the surrounding code. Follow relevant function calls and check how other components use the behavior being changed.
You do not need to understand the entire codebase to make a useful contribution. You do need to be clear about which parts you have examined and where your understanding is still limited.
Test What You Can
Where possible, reproduce the reported problem and check what happens with the patch applied. Run relevant tests and consider whether an additional test would help answer a specific question.
Be precise about your environment and what you tested. Successfully building the software is not the same as testing the behavior a patch changes.
Leave Specific, Useful Feedback
Explain the reasoning behind a concern so the author has something concrete to investigate. Pointing to a particular code path, describing an unexpected result, or sharing steps to reproduce a problem is more useful than saying that something looks wrong.
It is also fine to ask a question when you are unsure. Make it clear whether you are identifying a confirmed issue, raising a possibility, or asking for help understanding the code.
Distinguish between conclusions based on reading and behavior you have independently tested. If you review only part of a patch, say so. A limited review with a clear scope is more useful than a broad claim you cannot support.
Learn Alongside Other Reviewers
The Bitcoin Core PR Review Club offers another way to get started. It uses selected pull requests to help participants explore the codebase, discuss technical questions, and practice review.
Reading other contributors’ reviews can also be valuable. Pay attention to the questions they ask, the evidence they provide, and how their feedback changes as a patch develops.
Over time, this helps you build both technical knowledge and the judgment needed to assess more complex changes.
Contributing to the Security of Bitcoin Software
As Bitcoin’s software ecosystem grows and evolves, security becomes increasingly important. Protecting it requires more than writing new code: it also depends on carefully examining changes, testing assumptions, and identifying problems before they reach users.
Code review is part of that work. It cannot eliminate every risk, but it helps contributors catch mistakes, question technical decisions, and build confidence in the software people rely on.
For developers looking to contribute, review is both a way to learn and a way to strengthen Bitcoin’s security. Taking the time to understand a patch, test its behavior, and share clear findings is valuable open-source work.
