Skip to content

BIP3 revisions #2037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
luke-jr wants to merge 6 commits into from
Closed

BIP3 revisions #2037

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a5e59df
bip-0003: Clarify the need for relevance as a standard
luke-jr Nov 15, 2025
3a0a85d
bip-0003: Remove assumption Author was involved in writing the origin…
luke-jr Nov 15, 2025
2604a03
bip-0003: Require the Specification section
luke-jr Nov 15, 2025
56014a9
bip-0003: Remove implied requirement for third-party contribution to …
luke-jr Nov 15, 2025
eaacddf
bip-0003: Soften the requirement to include test vectors to a recomme…
luke-jr Nov 15, 2025
5217ecc
bip-0003: Replace "compliant" with "compatible"
luke-jr Nov 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions bip-0003.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,9 @@ Some BIPs describe processes, implementation guidelines, best practices, inciden
the Bitcoin protocol, peer-to-peer network, and client software may be acceptable.

BIPs are intended to be a means for proposing new protocol features, coordinating client standards, and
documenting design decisions that have gone into implementations. BIPs may be submitted by anyone, provided the
documenting design decisions that have gone into implementations thereof.
BIPs should cover topics that at least potentially have a need of standardization, involving multiple projects, and not merely configuration (such as default settings or per-node policies, except where the latter may overlap with standardized interactions).
Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very similar language regarding proposals being relevant is already found in the workflow section below: “The idea must be of interest to the broader community or relevant to multiple software projects. Minor improvements and matters concerning only a single project usually do not require standardization and should instead be brought up directly to the relevant project.”

The rest of this suggestion also seems superfluous, as policy that is only relevant to one project is considered non-relevant per the quoted section, and policy that is relevant to multiple projects or otherwise of interest to the broader community could clearly be useful here.

BIPs may be submitted by anyone, provided the
content is of high quality, e.g., does not waste the community’s time.

The scope of the BIPs
Expand All @@ -54,8 +56,8 @@ co-owned by the Bitcoin community.
#### Authors and Deputies

Authors may want additional help with the BIP process after writing an initial draft. In that case, they may assign
one or more Deputies to their BIP. Deputies are stand-in owners of a BIP who were not involved in writing the
document. They support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the
one or more Deputies to their BIP.
Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commit message:

“Remove assumption Author was involved in writing the original document”

The edited line describes Deputies, not Authors.

From Email:

  • Authors/Deputies assumes the champion (Author) was involved in writing
    the document. This is a deviation from the current process where the
    champion can be reassigned by editors if the current one is MIA.

That’s one of the reasons to introduce Deputies: it allows us to appoint Authors or Deputies depending on the situation.

Copy link
Member Author

@luke-jr luke-jr Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It appears to contrast deputies to authors, and in doing so implies authors wrote the original document.

Copy link
Contributor

@murchandamus murchandamus Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the Authors are generally the people that wrote the original document. People that took over ownership at a later time would likely only be inserted as Deputies now that BIP 3 is deployed.

Deputies support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the
authors. Deputies may perform the role of Authors for any aspect of the BIP process unless overruled by an Author.
Deputies share ownership of the BIP at the discretion of the Authors.

Expand Down Expand Up @@ -84,7 +86,8 @@ No formal or informal decision body governs Bitcoin development or decides adopt

Authors may choose to submit BIPs in MediaWiki or Markdown[^markdown] format.

Each BIP must have a _Preamble_, an _Abstract_, a _Copyright_, and a _Motivation_ section. Authors should consider all issues in the
Each BIP must have a _Preamble_, an _Abstract_, a _Motivation_, a _Specification, and a _Copyright_ section.
Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have Informational BIPs that don’t have a Specification section, and it seems to me that Informational BIPs do not require a Specification section. The BIP Types section specifies that Specification BIPs require a Specification, and heavily implies that Process BIPs do, too (“Process BIPs are like Specification BIPs, …”).

Authors should consider all issues in the
following list and address each as appropriate.

* Preamble — Headers containing metadata about the BIP (see the section [BIP Header Preamble](#bip-header-preamble)
Expand Down Expand Up @@ -175,7 +178,7 @@ do not need to adhere to a specific convention.
### BIP Types

* A **Specification BIP** defines a set of technical rules describing a new feature or affecting the interoperability of implementations. The
distinguishing characteristic of a Specification BIP is that it can be implemented, and implementations can be compliant with
Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, these sentences are correct. I mean compliant, as in, it must be possible for implementations to “conform to the requirements” of the Specification.

Copy link
Member Author

@luke-jr luke-jr Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BIPs are not laws which are conformed to or not, they are standards which things are compatible with or not.

Copy link
Contributor

@murchandamus murchandamus Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m not sure why you are hung-up on this. It’s obviously a fine term for what I’m trying to express.

image

distinguishing characteristic of a Specification BIP is that it can be implemented, and implementations can be compatible with
it. Specification BIPs must have a Specification section, must have a Backward Compatibility section (if incompatibilities are introduced), and can only be advanced to Complete after they contain or refer to a reference implementation and test vectors.
* An **Informational BIP** describes a Bitcoin design issue, or provides general guidelines or other information to the
Bitcoin community.
Expand Down Expand Up @@ -235,9 +238,8 @@ formatting requirements specified above and should be provided as a file named w
BIP by name only.

BIPs that (1) adhere to the formatting requirements, (2) are on-topic, and (3) have materially progressed beyond the
ideation phase, e.g., by generating substantial public discussion and commentary from diverse contributors, by
independent Bitcoin projects working on adopting the proposal, or by the authors working for an extended period toward
improving the proposal based on community feedback, will be assigned a number by a BIP Editor. A number may be
ideation phase, will be assigned a number by a BIP Editor.
Copy link
Member

@jonatack jonatack Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noting here that I would like to think about this more. It seems to me that the bar for numbers might be too low and that standards on quality/proof of work, soundness, completeness, and originality may need reinforcing in light of the ease of lobbing LLM-generated slop or hallucinations over the fence at us.

Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that this keeps the criteria as before and only drops the examples of how “progressed beyond ideation” may present, this seems like a disimprovement to me. Clearly, a list of examples is not meant to be considered exhaustive, perhaps you could suggest more examples how progressing beyond the ideation phase might present.

Copy link
Member Author

@luke-jr luke-jr Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The list of examples is too long IMO.

Copy link
Contributor

@murchandamus murchandamus Jan 14, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I don’t think so. It’s fine.

A number may be
considered assigned only after it has been publicly announced in the pull request by a BIP Editor. The BIP Editors should
not assign a number when they perceive a proposal being met with lack of interest: number assignment facilitates the
distributed discussion of ideas, but before a proposal garners some interest in the Bitcoin community, there is no need
Expand All @@ -260,14 +262,16 @@ When the authors have concluded all planned work on their proposal, are confiden
improvement, is clear, comprehensive, and is
ready for adoption by the Bitcoin community, they may update the BIP’s status to Complete to indicate that they
recommend adoption, implementation, or deployment of the BIP. Where applicable, the authors must ensure that any
proposed specification is solid, not unduly complicated, and definitive. Specification BIPs must come with or refer to a working reference implementation and comprehensive test vectors before they can be moved to Complete. Subsequently, the BIP’s content should only be
proposed specification is solid, not unduly complicated, and definitive.
Specification BIPs must come with or refer to a working reference implementation and should include comprehensive test vectors before they can be moved to Complete.
Copy link
Contributor

@murchandamus murchandamus Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From email:

  • Test vectors may not be applicable to all specification BIPs.

In that case “comprehensive test vectors” may refer to a one-sentence explanation in the BIP why test vectors don’t make sense.

Copy link
Member Author

@luke-jr luke-jr Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That isn't clear from the current text.

Copy link
Contributor

@murchandamus murchandamus Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The definition of a Specification BIP is that it can be implemented. If it can be implemented, it can be tested. I don’t see why there would ever be an exception, but if you have a good example, please feel free to provide it. Given the hypothetical example you’ll provide, I would love to see whether it would be ambiguous whether test vectors are required.

Subsequently, the BIP’s content should only be
adjusted in minor details, e.g., to improve language, clarify ambiguities, backfill omissions in the specification, add
test vectors for edge cases, or address other issues discovered as the BIP is being adopted.

A Complete BIP can only move to Deployed or Closed. Any necessary changes to the specification should be minimal and
interfere as little as possible with ongoing adoption. If a Complete BIP is found to need substantial functional
changes, it may be preferable to move it to Closed[^new-BIP], and to start a new BIP with the changes instead.
Otherwise, it could cause confusion as to what being compliant with the BIP means.
Otherwise, it could cause confusion as to what being compatible with the BIP means.

A BIP may remain in the Complete status indefinitely unless its authors or deputies decide to move it to Closed or it is advanced to
Deployed.
Expand Down Expand Up @@ -713,7 +717,7 @@ feedback, and helpful comments.
preferred.
[^new-BIP]: **Why should the specification of an implemented BIP no longer be changed?**
After a Complete or Deployed BIP has been deployed by one or more implementations, breaking changes to the
specification could lead to a situation where multiple "compliant" implementations fail at being interoperable,
specification could lead to a situation where multiple "compatible" implementations fail at being interoperable,
because they implemented different versions of the same BIP. Therefore, even changes to the specification of
Complete BIPs should be avoided, but Deployed BIPs should never be subject to breaking changes to their
specification.
Expand Down