BIP3 revisions #2037

pull luke-jr wants to merge 6 commits into bitcoin:master from luke-jr:bip0003_revs changing 1 files +15 −11
  1. 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.
  2. luke-jr requested review from murchandamus on Nov 15, 2025
  3. luke-jr added the label Proposed BIP modification on Nov 15, 2025
  4. 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.”

    murchandamus commented at 11:16 pm on December 9, 2025:
    I’ve partially reverted the commit that introduced the ban on LLM use in my pull request.
  5. in bip-0003.md:241 in ea81a76555 outdated 
    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.
    luke-jr commented at 6:48 am on January 14, 2026:
    The list of examples is too long IMO.
    murchandamus commented at 10:36 pm on January 14, 2026:
    Okay, I don’t. I think it’s fine.
  6. in bip-0003.md:489 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.

    murchandamus commented at 11:29 pm on December 9, 2025:
    I split this up into two sentences, “The idea has been proposed and discussed” and “A draft by one of the authors has been previously discussed on the mailing list”.
  7. jonatack commented at 5:16 pm on November 20, 2025: member
    Concept ACK
  8. 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.

  9. in bip-0003.md:59 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.

    luke-jr commented at 6:47 am on January 14, 2026:
    It appears to contrast deputies to authors, and in doing so implies authors wrote the original document.
    murchandamus commented at 10:34 pm on January 14, 2026:
    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.
  10. in bip-0003.md:89 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, …”).
  11. 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.
    murchandamus commented at 11:15 pm on December 9, 2025:
    I’ve adopted this suggestion.
  12. 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.
  13. in bip-0003.md:266 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.

    luke-jr commented at 6:49 am on January 14, 2026:
    That isn’t clear from the current text.
    murchandamus commented at 11:30 pm on January 14, 2026:
    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.
  14. in bip-0003.md:178 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.
    luke-jr commented at 6:48 am on January 14, 2026:
    BIPs are not laws which are conformed to or not, they are standards which things are compatible with or not.
    murchandamus commented at 10:38 pm on January 14, 2026:

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

  15. 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.
    murchandamus commented at 11:25 pm on December 9, 2025:
    Taken, but changed to “or”.
  16. 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
    murchandamus commented at 11:33 pm on December 9, 2025:
    Adopted into my PR
  17. in bip-0003.md:531 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.
    murchandamus commented at 11:34 pm on December 9, 2025:
    Cherry-picked into my branch.
  18. 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 11:41 pm on December 9, 2025:
    Adopted with changes.
  19. murchandamus commented at 5:59 am on December 2, 2025: contributor
    Thanks for your review.
  20. in bip-0003.md:33 in 8320119837 outdated 
    29@@ -30,7 +30,7 @@ BIP types more clearly, and generalizes the BIP process to fit the community
30 
31 ### What is a BIP?
32 
33-BIPs are improvement proposals for Bitcoin[^capitalization]. The main topic is information and technologies that support and expand the utility of the bitcoin
34+BIPs are improvement proposals for Bitcoin. The main topic is information and technologies that support and expand the utility of the bitcoin
    murchandamus commented at 11:38 pm on December 9, 2025:
    Adopted with slight changes.
  21. in bip-0003.md:237 in ea81a76555 
    233@@ -234,7 +234,7 @@ After fleshing out the proposal further and ensuring that it is of high quality
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]".
237-Only BIP Editors may assign BIP numbers; until one has done so, author(s) should refer to their BIP by name only.
238+Only BIP Editors may assign BIP numbers; until one has done so, author(s) should refer to their BIP by name only (filenames should use an alias such as "bip-johndoe-infinitebitcoins" which includes the author's name/nick and the BIP subject).
    murchandamus commented at 11:44 pm on December 9, 2025:
    This directly contradicts the prior line, which specifies a file name without the authors’ names.
  22. murchandamus commented at 0:39 am on December 10, 2025: contributor
    I have adopted the indicated changes in #2051.
  23. jonatack commented at 11:29 pm on December 15, 2025: member
    Did #2051 fairly address your points here?
  24. bip-0003: Clarify the need for relevance as a standard a5e59dfde5
  25. bip-0003: Remove assumption Author was involved in writing the original document 3a0a85dde8
  26. bip-0003: Require the Specification section 2604a03361
  27. bip-0003: Remove implied requirement for third-party contribution to BIPs 56014a9dd2
  28. bip-0003: Soften the requirement to include test vectors to a recommendation eaacddfc42
  29. bip-0003: Replace "compliant" with "compatible" 5217ecc02e
  30. luke-jr force-pushed on Jan 13, 2026
  31. luke-jr commented at 1:39 am on January 13, 2026: member
    To a large extent, but there’s a few remaining issues. Rebased to address those.
  32. murchandamus commented at 2:31 am on January 13, 2026: contributor

    Luke,

    I have responded to each of your remaining six suggestions both on the mailing list and here with explanations why I did not adopt them. Resubmitting exactly the same suggestions that I have already addressed without responding to any of my comments or further substantiation is not constructive and does not advance this conversation.

    I would also like to point out that it has been 34 days since I updated my proposal in response to your feedback and four weeks since Jon asked here whether your points have been addressed fairly. You did not reply or “update your PR” until less than one hour after I emailed the mailing list that my activation proposal has been updated in response to several other correspondents assessing that BIP 3 has rough consensus. Your behavior could easily be understood as deliberately wasting people’s time and resources.

  33. luke-jr commented at 6:49 am on January 14, 2026: member
    More like you are deliberately misunderstanding my intentions. Obviously an email that you have updated the BIP gets people to look at the updates. I still think these changes are an improvement.
  34. murchandamus commented at 11:32 pm on January 14, 2026: contributor

    I can see why your stance here might make sense to you.

    However, in the real world, where other people’s opinions can also have weight, I authored a proposal and you suggested changes to it. I evaluated your suggestions, adopted some, and explained why I declined some others. Doubling down on your opinion without addressing my explanations at all as if you’re expecting your opinion to obviously override my rebuttals is not compelling, especially while over a dozen people indicate that the text is acceptable as is.

    I’m going to close this PR now, since BIP 3 was deployed. If you think these changes are worth going through a multi-week discussion on the mailing list and an attempt to find rough consensus for them — as is required for amending a Deployed Process BIP — please feel free to reopen it and get on that.

  35. murchandamus closed this on Jan 14, 2026


luke-jr jonatack billymcbip murchandamus

Labels
Proposed BIP modification

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bips. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-01-16 16:10 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me