BIP3 revisions

luke-jr commented at 10:00 pm on November 15, 2025: member

This addresses several issues identified in my review of BIP 3. Other unaddressed issues are being posted to the mailing list for further discussion.

bip-0003: Clarify the need for relevance as a standard 23d3417fb4

bip-0003: Remove overly broad AI/LLM usage disclosure requirement 092c9a3394

bip-0003: Remove assumption Author was involved in writing the original document 8a802cdb30

bip-0003: Require the Specification section d12b976ed2

bip-0003: Broaden reference implementation format b46e819591

bip-0003: Clarify editor assignment of BIP numbers a399d0791d

bip-0003: Remove implied requirement for third-party contribution to BIPs 687110fe31

bip-0003: Soften the requirement to include test vectors to a recommendation 1e71b24fb1

bip-0003: Replace "compliant" with "compatible" c872fc4913

bip-0003: Avoid implying BIP editors must reply to every ML post cf1b37cae4

bip-0003: Remove assumption authors submitting BIPs also proposed them to the ML themselves b7089a3f1c

bip-0003: Move Type header responsibility to the author(s) 953db4fec0

bip-0003: Changes from BIP 2: Make it match actual spec 00bef75d20

bip-0003: Drop self-contradicting capitalization Rationale 8320119837

bip-0003: Better phrasing for Rationale/OtherImplementations c3bc016e6f

bip-0003: Explicitly specify preferred method of naming files prior to assignment

Based-on: aecb84f38daf6c9c3ab5b1e87bddb3a556460812

ea81a76555

luke-jr requested review from murchandamus on Nov 15, 2025

luke-jr added the label Proposed BIP modification on Nov 15, 2025

in bip-0003.md:44 in ea81a76555

43+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).
44+A BIP may be submitted by anyone,
45 provided it is the original work of its authors and the content is of high quality, e.g. does not waste
46-the community's time. No content may be generated by AI/LLMs and authors must proactively disclose
47-up-front any use of AI/LLMs.
48+the community's time. No content may be generated by AI/LLMs.

jonatack commented at 5:01 pm on November 20, 2025:

Would prefer that authors be required to proactively disclose out of respect for the community’s time (and that of the editors).

billymcbip commented at 11:16 am on November 23, 2025:

If someone uses AI to iterate on the language of a BIP (e.g. to make it more concise), you will get a high “LLM score”, but that does not mean that the entire BIP was AI-generated. AI can level the playing field for people whose first language isn’t English.

Disclosure of AI use makes sense, but maybe we can replace the sentence ‘No content may be generated by AI/LLMs.’ with something like ‘AI/LLMs may assist with (language) refinement, but normative content must originate from the authors.’*

*Full disclosure, AI helped me generate the alternative sentence ;)

jonatack commented at 2:49 pm on November 24, 2025:

The issue is not the use of spelling and grammar checkers, which have been in use for a long time. The issue is coming from overuse of LLMs to generate the content itself.

The priority is not wasting the community’s time.

Experienced human review is the scarce resource and bottleneck, and with AI that situation doesn’t appear to be improving, at least not yet.

Who wants to review LLM content or AI hallucinations? Right, no one. Humans want to review work from humans who have shown merit.

Yes, we’ll try to have AI review the AI-generated content and code, to level the playing field… but for now, we’ll probably need to rely even more on human heuristics like reputation, proof of work, and personal recommendations, to decide what deserves expensive human attention for the proposals that get past the AI filters.

See also the discussion at https://stacker.news/items/1287863.

billymcbip commented at 12:53 pm on November 25, 2025:

Humans want to review work from humans who have shown merit.

People evidently do review BIP PRs filed by accounts with no prior contributions. Ultimately, the merit of the BIP is what matters.

jonatack commented at 6:10 pm on November 25, 2025:

Yes, I wrote “want” – not “do”.

The BIP editors do review, and you are encouraged to help by also contributing review, but that sentence summarized our general preference and mine.

murchandamus commented at 0:47 am on December 2, 2025:

Several reviewers have been suggesting that #2006 be reverted with what I find to be convincing arguments:

The rule only hurts good actors, bad actors would never disclose either way
The main motivation for the rule was to curb low-quality proposals as they waste time, but proposals are already required to be of high quality
Competent authors can use AI-tools to save time and create high-quality proposals

Therefore, this paragraph will likely not be present in BIP 3 either way.

jonatack commented at 3:33 pm on December 3, 2025:

I think it is nevertheless best to set social expectations and provide guidance not to use LLMs to generate BIP drafts or code. Using them to review your original content/work is fine, but not to generate it.

Otherwise, the asymmetry against reviewers becomes even more skewed, and simply ignoring what looks like LLM-generated content isn’t sufficient.

jonatack commented at 4:06 pm on December 3, 2025:

‘AI/LLMs may assist with (language) refinement, but normative content must originate from the authors.’

Indeed, similar to @billymcbip’s suggestion.

jonatack commented at 4:18 pm on December 3, 2025:

The rule only hurts good actors, bad actors would never disclose either way

I think the idea would be to try to ensure bad actors see their PRs closed more than good actors.

murchandamus commented at 11:00 pm on December 9, 2025:

“AI/LLMs may assist with (language) refinement, but normative content must originate from the authors.”

Isn’t that essentially covered by the prior sentence by stating “provided it is the original work of its authors”? (Full quote below.)

“A BIP may be submitted by anyone, provided it is the original work of its authors and the content is of high quality, e.g. does not waste the community’s time.”

in bip-0003.md:240 in ea81a76555

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

jonatack commented at 5:04 pm on November 20, 2025:

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.

murchandamus commented at 2:08 am on December 2, 2025:

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.

in bip-0003.md:488 in ea81a76555

484@@ -481,22 +485,22 @@ repository](https://github.com/bitcoin/bips) where it may get further feedback.
485 
486 For each new BIP pull request that comes in, an editor checks the following:
487 
488-* The idea has been previously proposed by one of the authors to the Bitcoin Development Mailing List and discussed there
489+* The idea has been previously proposed to the Bitcoin Development Mailing List and discussed there

jonatack commented at 5:09 pm on November 20, 2025:

Probably best to keep this as-is to avoid other people sniping/jumping on an idea.

Further, not only “The idea” but also the proposed draft for review on the author’s own repository.

We’re seeing new, out-of-the-blue github accounts (often with no established record or proof of work in the space) opening a PR directly to the BIPs, skipping the steps, and then using the “fait accompli” to protest the PR being closed.

murchandamus commented at 3:17 am on December 2, 2025:

I don’t feel strongly about this one. I recall three cases in which a PR was opened by someone other than the person initially proposing an idea, twice consensual, once by surprise. It seems to me that this sort of thing sorts itself out.

I’d rather reiterate explicitly that both the idea and an early draft should be sent to the mailing list, or even require at least the latter as BIP 2 does.

jonatack commented at 5:16 pm on November 20, 2025: member

Concept ACK

in bip-0003.md:41 in 23d3417fb4 outdated

36@@ -37,7 +37,9 @@ Some BIPs describe processes, implementation guidelines, best practices, inciden
37 the Bitcoin protocol, peer-to-peer network, and client software may be acceptable.
38 
39 BIPs are intended to be a means for proposing new protocol features, coordinating client standards, and
40-documenting design decisions that have gone into implementations. A BIP may be submitted by anyone,
41+documenting design decisions that have gone into implementations thereof.
42+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).

murchandamus commented at 0:36 am on December 2, 2025:

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.

in bip-0003.md:60 in 8a802cdb30 outdated

56@@ -57,8 +57,8 @@ co-owned by the Bitcoin community.
57 #### Authors and Deputies
58 
59 Authors may want additional help with the BIP process after writing an initial draft. In that case, they may assign
60-one or more Deputies to their BIP. Deputies are stand-in owners of a BIP who were not involved in writing the
61-document. They support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the
62+one or more Deputies to their BIP.

murchandamus commented at 1:00 am on December 2, 2025:

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.

in bip-0003.md:90 in d12b976ed2 outdated

86@@ -87,7 +87,8 @@ No formal or informal decision body governs Bitcoin development or decides adopt
87 
88 Authors may choose to submit BIPs in MediaWiki or Markdown[^markdown] format.
89 
90-Each BIP must have a _Preamble_, an _Abstract_, a _Copyright_, and a _Motivation_ section. Authors should consider all issues in the
91+Each BIP must have a _Preamble_, an _Abstract_, a _Motivation_, a _Specification, and a _Copyright_ section.

murchandamus commented at 1:12 am on December 2, 2025:

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, …”).

in bip-0003.md:108 in b46e819591 outdated

104@@ -105,7 +105,7 @@ following list and address each as appropriate.
105   implementers and users should deal with these incompatibilities.
106 * Reference Implementation — Where applicable, a reference implementation, test vectors, and documentation must be
107   finished before the BIP can be given the status "Complete". Test vectors must be provided in the BIP or
108-  as auxiliary files (see [Auxiliary Files](#auxiliary-files)) under an acceptable license. The reference implementation can be provided in the BIP, as an auxiliary file, or per reference to a pull request that is expected to remain available permanently.
109+  as auxiliary files (see [Auxiliary Files](#auxiliary-files)) under an acceptable license. The reference implementation can be provided in the BIP as an auxiliary file, reference to a pull request (expected to remain available permanently), a new code repository, or similar.

murchandamus commented at 1:20 am on December 2, 2025:

A specific branch seems more obvious to me than a new repository, but sure. This should be phrased in a way that makes clear that it’s expected to remain available permanently either way.

in bip-0003.md:237 in a399d0791d outdated

232@@ -233,7 +233,8 @@ specification above.
233 After fleshing out the proposal further and ensuring that it is of high quality and properly formatted, the authors
234 should open a pull request to the [BIPs repository](https://github.com/bitcoin/bips). The document must adhere to the
235 formatting requirements specified above and should be provided as a file named with a working title of the form
236-"bip-title.[md|mediawiki]". The authors must not self-assign a number to their proposal.
237+"bip-title.[md|mediawiki]".
238+Only BIP Editors may assign BIP numbers; until one has done so, author(s) should refer to their BIP by name only.

murchandamus commented at 1:23 am on December 2, 2025:

This suggestion seems fine, but please drop the parentheses on “author(s)”:

0"bip-title.[md|mediawiki]".
1Only BIP Editors may assign BIP numbers; until one has done so, authors should refer to their BIP by name only.

in bip-0003.md:265 in 1e71b24fb1 outdated

260@@ -261,7 +261,9 @@ When the authors have concluded all planned work on their proposal, are confiden
261 improvement, is clear, comprehensive, and is
262 ready for adoption by the Bitcoin community, they may update the BIP’s status to Complete to indicate that they
263 recommend adoption, implementation, or deployment of the BIP. Where applicable, the authors must ensure that any
264-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
265+proposed specification is solid, not unduly complicated, and definitive.
266+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.

murchandamus commented at 2:13 am on December 2, 2025:

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.

in bip-0003.md:180 in c872fc4913 outdated

176@@ -177,7 +177,7 @@ do not need to adhere to a specific convention.
177 ### BIP Types
178 
179 * A **Specification BIP** defines a set of technical rules describing a new feature or affecting the interoperability of implementations. The
180-  distinguishing characteristic of a Specification BIP is that it can be implemented, and implementations can be compliant with

murchandamus commented at 2:21 am on December 2, 2025:

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

in bip-0003.md:470 in cf1b37cae4 outdated

466@@ -467,7 +467,7 @@ The current BIP Editors are:
467 The BIP Editors subscribe to the Bitcoin Development Mailing List and watch the [BIPs
468 repository](https://github.com/bitcoin/bips).
469 
470-When either a new BIP idea or an early draft is submitted to the mailing list, BIP Editors and other community members should comment in regard
471+When either a new BIP idea or an early draft is submitted to the mailing list, BIP Editors and/or other community members should comment in regard

murchandamus commented at 3:01 am on December 2, 2025:

It already says “should”, but just “or” instead of “and” is also fine with me.

in bip-0003.md:496 in 953db4fec0 outdated

492@@ -493,14 +493,14 @@ For each new BIP pull request that comes in, an editor checks the following:
493 * Licensing terms are acceptable
494 * Motivation, Rationale, and Backward Compatibility have been addressed
495 * Specification provides sufficient detail for implementation
496-* The defined Layer header must be correctly assigned for the given specification
497+* The defined Type and Layer headers must be correctly assigned for the given specification

murchandamus commented at 3:18 am on December 2, 2025:

Sure, that seems fine

in bip-0003.md:529 in 00bef75d20 outdated

525@@ -526,7 +526,7 @@ mentioned in the [Changelog](#changelog) section.
526 - The comment system is abolished.[^comments]
527 - A BIP in Draft or Complete status may no longer be closed solely on grounds of not making progress for three years.[^rejection]
528   - A BIP in Draft status may be updated to Closed status if it appears to have stopped making progress for at least a
529-    year and its authors do not assert within four weeks of being contacted that they are still working on it.
530+    year and its authors do not assert within four weeks of being contacted that they intend to continue working on it.

murchandamus commented at 3:18 am on December 2, 2025:

Sure.

in bip-0003.md:651 in c3bc016e6f outdated

647@@ -648,7 +648,7 @@ feedback, and helpful comments.
648     Standards Track BIPs is dropped.
649 [^OtherImplementations]: **What is the issue with "Other Implementations" sections in BIPs?**  
650     In the past, some BIPs had "Other Implementations" sections that caused frequent change requests to existing BIPs.
651-    This put an onus on the BIP authors, and frequently led to lingering pull requests due to the corresponding BIPs’
652+    This put a burden on the BIP authors and editors, frequently leading to lingering pull requests due to the corresponding BIPs’

murchandamus commented at 3:20 am on December 2, 2025:

Sure

murchandamus commented at 5:59 am on December 2, 2025: contributor

Thanks for your review.

BIP3 revisions #2037