This _Bitcoin Improvement Proposal (BIP)_ provides information about the preparation of BIPs and policies relating to
the publication of BIPs. It replaces [BIP2](bip-0002.mediawiki) with a streamlined process, and may be amended to
address the evolving needs of the BIP process.
## Motivation
BIP2 was written in 2016.
This BIP revisits aspects of the BIP2 process
that did not achieve broad adoption, reduces the judgment calls assigned to the BIP Editor role, delineates the
BIPTypes more clearly, and generalizes the BIP process to meet the community’s use of the repository.
## Fundamentals
### What is a BIP?
BIPs cover the range of interests of the Bitcoin[^capitalization] community. The main topic is information and technologies that support and expand the utility of the bitcoin
currency. Most BIPs provide a concise, self-contained, technical description of one new concept, feature, or standard.
Some BIPs describe processes, implementation guidelines, best practices, incident reports (e.g.,
[BIP50](bip-0050.mediawiki)), or other information relevant to the Bitcoin community. However, any topics related to
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.
The scope of the BIP
repository is limited to BIPs that do not oppose the fundamental principle that Bitcoin constitutes a peer-to-peer
electronic cash system for the bitcoin currency.
### BIP Ownership
Each BIP is primarily owned by its authors and represents the authors’ opinion or recommendation. The authors are
expected to foster discussion, address feedback and dissenting opinions, and, if applicable, advance the adoption of
their proposal within the Bitcoin community. As a BIP progresses through the workflow, it becomes increasingly
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
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.
### What is the Significance of BIPs?
BIPs do not define what Bitcoin is: individual BIPs do not represent Bitcoin community consensus or a general
recommendation for implementation. A BIP represents a personal recommendation by the BIP authors to the Bitcoin
community. Some BIPs may never be adopted. Some BIPs may be adopted by one or more Bitcoin clients or other related
software. Some may even end up changing the consensus rules that the Bitcoin ecosystem jointly enforces.
### What is the Purpose of the BIPs Repository?
The [BIPs repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.
Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established
source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and
allows any community member to retain a complete copy of the archive easily.
The BIPs repository is not a tool to track acceptance[^acceptance], adoption, or community consensus on BIPs, beyond
providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin
development emerges from the participation of shareholders across the ecosystem.
## BIP Format and Structure
### Specification
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
following list and address each as appropriate.
* Preamble — Headers containing metadata about the BIP (see the section [BIP Header Preamble](#bip-header-preamble)
below).
* Abstract — A short description of the issue being addressed.
* Motivation — Why is this BIP being written? Clearly explain how the existing situation presents a problem and why the proposed idea resolves the
issue or improves upon the current situation.
* Specification — The technical specification should describe the syntax and semantics of any new feature. The
specification should be detailed enough to enable any Bitcoin project to create an interoperable implementation.
* Rationale — The rationale fleshes out the specification by describing what inspired the design and why particular
design decisions were made. It should describe related work and alternate designs that were considered. The rationale
should record relevant objections or important concerns that were raised and addressed as this proposal was developed.
* Backward Compatibility — Any BIP that introduces incompatibilities must include a section describing these incompatibities and their severity as well as provide instructions on how
implementers and users should deal with these incompatibilities.
* Reference Implementation — Where applicable, a reference implementation, test vectors, and documentation must be
finished before the BIP can be given the status "Complete". Test vectors must be provided in the BIP or
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.
* Changelog — A section to track modifications to a BIP after reaching Complete status.
* Copyright — The BIP must be placed under an acceptable license (see [BIP Licensing](#bip-licensing) below).
#### BIP Header Preamble
Each BIP must begin with an [RFC 822-style header preamble](https://www.w3.org/Protocols/rfc822/). The headers must
appear in the following order. Headers marked with "\*" are optional. All other headers are required.
* BIP — The assigned number of the BIP. Please use "?" before a number has been assigned by the BIP Editors.
* Layer — The layer of Bitcoin the BIP applies to using the BIP classification defined in [BIP123](bip-0123.mediawiki).
* Authors — The names (or pseudonyms) and email addresses of all authors of the BIP. The format of each authors header
value must be
Random J. User <address@dom.ain>
Multiple authors are recorded on separate lines:
Authors: Random J. User <address@dom.ain>
Anata Sample <anata@domain.example>
* Deputies — Additional owners of the BIP that are not authors. The Deputies header uses the same format as the
Authors header. See the [BIP Ownership](#bip-ownership) section above.
* Status — The stage of the workflow of the proposal. See the [Workflow](#workflow) section below.
* Type — See the [BIP Types](#bip-types) section below for a description of the three BIP types.
* License and License-Code — These headers list SPDX License Identifier(s) of the acceptable licenses under which the
BIP and corresponding code are available. See the [BIP Licensing](#bip-licensing) section below for a description of
the Licenses and their SPDX License Identifiers. If there are multiple acceptable licenses, each should be on a
separate line.
* Discussion — The Discussion header points the audience to relevant discussions of the BIP, e.g., the mailing list
thread in which the idea for the BIP was discussed, a thread where a new version of the BIP was presented, or relevant
discussion threads on other platforms. Entries take the format "yyyy-mm-dd: URL", e.g., `2009-01-09:
https://www.mail-archive.com/cryptography@metzdowd.com/msg10142.html`, using the date and URL of the start of the
conversation. Multiple discussions should be listed on separate lines.
* Version — The current version number of this BIP. See the [Changelog](#changelog) section below.
* Requires — A list of existing BIPs the new proposal depends on. If multiple BIPs
are required, they should be listed in one line separated by a comma and space (e.g., "1, 2").
* Replaces — BIP authors may place the numbers of one or more prior BIPs in the Replaces header to recommend that their
BIP succeeds, supersedes, or renders obsolete those prior BIPs.
* Proposed-Replacement[^superseded-by-proposed-replacement] — When a later BIP indicates that it intends to supersede an
existing BIP, the later BIP’s number is added to the Proposed-Replacement header of the existing BIP to indicate the
potential successor BIP.
#### Auxiliary Files
BIPs may include auxiliary files such as diagrams and source code. Auxiliary files must be included in a subdirectory
for that BIP named `bip-XXXX`, where "XXXX" is the BIP number zero-padded to four digits. File names in the subdirectory
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
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.
* A **Process BIP** describes a process surrounding Bitcoin, or proposes a change to (or an event in) a process. Process
BIPs are like Specification BIPs, but apply to topics other than the Bitcoin protocol and Bitcoin implementations.
They often require community consensus and are typically binding for the corresponding process. Examples include
procedures, guidelines, and changes to decision-making processes such as the BIP Process.
## Workflow
The BIP process starts with a new idea for Bitcoin. Each potential BIP must have authors—people who write the BIP,
gather feedback, shepherd the discussion in the appropriate forums, and finally recommend a mature proposal to the
community.
### Ideation
After having an idea, the authors should evaluate whether it meets the criteria to become a BIP, as described in this
BIP. 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 authors should first research whether an idea has been considered before. Ideas in Bitcoin are often rediscovered,
and prior related discussions may inform the authors of the issues that may arise in its progression. After some investigation,
the novelty of an idea can be tested by posting about it to the [Bitcoin Development Mailing
List](https://groups.google.com/g/bitcoindev). Prior correspondence can be found in the [mailing list
archive](https://gnusha.org/pi/bitcoindev/).
Vetting an idea publicly before investing the time to describe the idea formally is meant to save both the authors and
the broader community time. Not only may someone point out relevant discussion topics that were missed in the authors’
research, or that an idea is guaranteed to be rejected based on prior discussions, but describing an idea publicly also
tests whether it is of interest to more people besides the authors. After establishing that the idea may be of interest
to the Bitcoin community, the authors should work on drafting a BIP.
As a first sketch of the proposal is taking shape, the authors should present it to the [Bitcoin Development Mailing
List](https://groups.google.com/g/bitcoindev). This gives the authors a chance to collect initial feedback and address
fundamental concerns. If the authors wish to work in public on the proposal at this stage, it is recommended that they
open a pull request against one of their forks of the BIPs repository instead of the main BIPs repository.
It is recommended that complicated proposals be split into separate BIPs that each focus on a specific component of the
overall proposal.
### Progression through BIP Statuses
The following sections refer to BIP Status Field values. The BIP Status Field is defined in the Header Preamble
specification above.
#### Draft
After fleshing out the proposal further and ensuring that it is of high quality and properly formatted, the authors
should open a pull request to the [BIPs repository](https://github.com/bitcoin/bips). The document must adhere to the
formatting requirements specified above and should be provided as a file named with a working title of the form
"bip-title.[md|mediawiki]". The authors must not self-assign a number to their proposal.
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. The BIP editors should
delay number assignment 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
to refer to it by a number.
Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too
unfocused or too broad, fail to provide proper motivation, fail to address backward compatibility where necessary, or
fail to specify the feature clearly and comprehensively. Reviewers and BIP editors should provide guidance on how the
proposal may be improved to progress toward readiness. Pull requests that are proposing off-topic ideas or
have stopped making progress may be closed.
When the proposal is ready and has been assigned a number, a BIP editor will merge it into the BIPs repository. After the
BIP has been merged to the repository, its main focus should no longer shift significantly, even while the authors may
continue to update the proposal as necessary. Updates to merged documents by the authors should also be submitted as
pull requests.
#### Complete[^complete]
When the authors have concluded all planned work on their proposal, are confident that their BIP represents a net
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
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.
A BIP may remain in the Complete status indefinitely unless its authors decide to move it to Closed or it is advanced to
Deployed.
Complete is the final status for most successful Informational BIPs.
#### Deployed
A settled[^settled] BIP may be advanced to Deployed upon request by any community member with evidence[^evidence] that the idea
described in the BIP is in active use. Convincing evidence includes for example: an established project having deployed support
for the BIP in mainnet software releases, a soft fork proposal’s activation criteria having been met on the network, or
rough consensus for the BIP having been demonstrated.
At that point, the BIP should be considered final and any breaking changes to the BIP should be proposed as a new
separate BIP.[^new-BIP]
##### Process BIPs
A Process BIP may change status from Complete to Deployed when it achieves rough consensus on the Bitcoin Development Mailing List. Such a
proposal is said to have rough consensus if it has been open to discussion on the mailing list for at least
one month, and no person maintains any unaddressed substantiated objections to it. Addressed or obstructive objections
may be ignored/overruled by general agreement that they have been sufficiently addressed, but clear reasoning must be
given in such circumstances. Deployed Process BIPs may be modified indefinitely as long as a proposed modification has
rough consensus per the same criteria.[^living-documents]
#### Closed[^closed]
A BIP that is of historical interest only, and is not being actively worked on, promoted or in active use, should be
marked as Closed. The reason for moving the
proposal to (or from) Closed should be recorded in the Changelog section in the same commit that updates the status.
BIPs do not get deleted, they are retained even after being updated to Closed.
Transitions involving the Closed state are:
##### Draft ↦ Closed
BIP authors may decide on their own to change their BIP’s status from Draft to Closed. If a Draft BIP stops making
progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, the community may move the BIP
to Closed unless the authors assert that they intend to continue work within four weeks of being contacted.
##### Complete ↦ Closed
BIPs that had attained the Complete status, i.e., that had been recommended for adoption, may be moved to Closed per the
authors’ announcement to the Bitcoin Development Mailing List[^bip-announcements-to-list]. However, if someone volunteers to adopt the proposal
within four weeks, they become the BIP's author or deputy, and the BIP will
remain Complete instead.
##### Deployed ↦ Closed
A BIP may evolve from Deployed to Closed when it is no longer in active use. Any community member may initiate this
Status update by announcing it to the mailing list[^bip-announcements-to-list], and proceed if no objections have been raised for four weeks.
##### Closed ↦ Draft
The Closed status is generally intended to be a final status for BIPs,
and if BIP authors decide to make another attempt at a previously Closed BIP, it is generally recommended to create a new
proposal. (Obviously, the authors may borrow any amount of inspiration or actual text from any prior BIPs as licensing
permits.) The authors should take special care to address the issues that caused the prior attempt’s abandonment. Even
if the prior attempt had been assigned a number, the new BIP will generally be assigned a distinct number. However, if it is
obvious that the new attempt directly continues work on the same idea, it may be reasonable to return the
Closed BIP to Draft status.
### Changelog
To help implementers understand updates to a BIP, any changes after it has reached Complete must be tracked with version,
date, and description in a Changelog section sorted by most recent version first. The version number is inspired by semantic versioning (MAJOR.MINOR.PATCH).
The MAJOR version is incremented if changes to the BIP’s Specification are introduced that are incompatible with prior
versions (which should be rare after a BIP is Complete, and only happen in well-grounded exceptional cases to a BIP that
is Deployed). The MINOR version is incremented whenever the specification of the BIP is changed or extended in a
backward-compatible way. The PATCH version is incremented for other changes to the BIP that are noteworthy (bug fixes,
test vectors, important clarifications, etc.). Version 1.0.0 is used to label the promotion to
Complete. A Changelog section may be introduced during the Draft phase to record significant changes (using versions 0.x.y).
Example:
> __Changelog__
>
> * __2.0.0__ (2025-01-22):
> * Introduce a breaking change in the specification to fix a bug.
> * __1.1.0__ (2025-01-17):
> * Add a backward compatible extension to the BIP.
> * __1.0.1__ (2025-01-15):
> * Clarify an edge case and add corresponding test vectors.
> * __1.0.0__ (2025-01-14):
> * Complete planned work on the BIP.
After a BIP receives a Changelog, the
Preamble must indicate the latest version in the Version header. The Changelog highlights revisions to BIPs to human readers. A single
BIP shall not recommend more than one variant of an idea at the same time. A different or
competing variant of an existing BIP must be published as a separate BIP.
### Adoption of Proposals
The BIPs repository does not track the sentiment on proposals and does not track the adoption of BIPs beyond whether they
are in active use or not. It is not intended for BIPs to list additional implementations beyond the reference
implementation: the BIPs repository is not a signpost where to find implementations.[^OtherImplementations] After a BIP
is advanced to Complete, it is up to the Bitcoin community to evaluate, adopt, ignore, or reject a BIP. Individual
Bitcoin projects are encouraged to publish a list of BIPs they implement. A good example of this at the time of writing
this BIP can be observed in Bitcoin Core’s [doc/bips.md](https://github.com/bitcoin/bitcoin/blob/master/doc/bips.md)
file.
### Transferring BIP Ownership
It occasionally becomes necessary to transfer ownership of BIPs to new owners. In general, it would be preferable to
retain the original authors of the transferred BIP, but that is up to the original authors. A good reason to transfer
ownership is because the original authors no longer have the time or interest in updating it or following through with
the BIP process, or are unreachable or unresponsive. A bad reason
to transfer ownership is because someone doesn't agree with the direction of the BIP. The community tries to build
consensus around a BIP, but if that's not possible, rather than fighting over control, the dissenters should supply a
competing BIP.
If someone is interested in assuming ownership of a BIP, they should send an email asking to take over, addressed to the
original authors, the BIPEditors, and the Bitcoin Development Mailing List[^bip-announcements-to-list]. If the authors are unreachable or do not respond in a timely
manner (e.g., four weeks), the BIP editors will make a unilateral decision whether to appoint the applicants as
[Authors or Deputies](#authors-and-deputies) (which may be amended should the original authors make a delayed reappearance).
## BIP Licensing
The Bitcoin project develops a global peer-to-peer digital cash system. Open standards are indispensable for continued
interoperability. Open standards reduce friction, and encourage anybody and everyone to contribute, compete, and
innovate on a level playing field. Only freely licensed contributions are accepted to the BIPs repository.
### Specification
Each new BIP must identify at least one acceptable license in its preamble. Licenses must be referenced per their
respective [SPDX License identifier](https://spdx.org/licenses). New BIPs may be accepted with the licenses described
below.
For example, a preamble might include the following License header:
License: CC0-1.0
GNU-All-Permissive
In this case, the BIP text is fully licensed under both the Creative Commons CC0 1.0 Universal license as well as the
GNU All-Permissive License, and anyone may modify and redistribute the text provided they comply with the terms of
*either* license. In other words, the license list is an "OR choice", not an "AND also" requirement.
It is also possible to license source code differently from the BIP text by including the optional License-Code header
after the License header. Again, each license must be referenced by their respective SPDX License identifier shown
below.
Each source code file or source directory should specify the license under which it is made available as is common in
software (e.g., with a license header or a LICENSE/COPYING file). It is recommended to make any test vectors available
under CC0-1.0 or GNU-All-Permissive in addition to any other licenses to allow anyone to copy test vectors into their
implementations without introducing license hindrances. Licenses listed in the License-Code header apply to all source
directories, source code files, and test vectors provided with the BIP except those where a LICENSE file in a directory
or the file header states otherwise.
For example, a preamble specifying the optional License-Code header might look like:
License: CC0-1.0
License-Code: MIT
In this case, the code in the BIP is not available under CC0-1.0, but is only available under the terms of the MIT
License.
BIPs are not required to be *exclusively* licensed under approved terms, and may also be licensed under unacceptable
licenses *in addition to* at least one acceptable license. In this case, only the acceptable license(s) should be listed
in the License and License-Code headers.
It is recommended that BIPs that include literal code be licensed under the same license terms as the project it
modifies. For example, literal code intended for Bitcoin Core would ideally be licensed (or dual-licensed) under the MIT
license terms.
In all cases, details of the licensing terms must be provided in the Copyright section of the BIP.
