BUIP121: (passed) Create formal BCH specifications

[Jonathan Silverblood]

BUIP121: Create formal BCH specifications
Submitted by: Jonathan Silverblood
Date: 2019/04/01
edit 2019/5/5 by solex: budget added

Summary
The purpose of this BUIP is to develop and maintain a public specification for the Bitcoin Cash protocol.

Proposal
This BUIP proposes that we use bitcoin unlimited funds to:

• Write a formal specification for Bitcoin Cash
• Maintain a formal specification for Bitcoin Cash

Motivation
Having a proper and full documentation is beneficial to all projects that needs to interact with the Bitcoin Cash network.

Budget
A maximum expenditure cap of $20,000 is proposed for the technical author work involved.
Due to the uncertain scope of the work, this is an estimate recommended by solex.

Background
Currently there is a lot of information on how Bitcoin and it's derivates operate, but it's shattered over a large number of resources and most of it is just descriptions of what the current codebases do.

While developing projects I've repeatedly found myself in need of a specification and have been referred to the concept that the code is the specification, which is unhelpful. An example of a currently poorly documented procedure is the Bitcoin Message creation and verification process.

 

[Griffith]

To have a BU version to compete with https://github.com/bitcoincashorg/bitcoincash.org/tree/master/spec i assume? (some spec stuff is in the PRs as well)

 

[Jonathan Silverblood]

The specifications in that repo are good to have, bit they don't really cover the full protocol, seems to be mostly just information about about changes to it and things related to it, also doesn't cover how bitcoin creates and signs messages.

I've been reading on https://en.bitcoin.it/wiki/Script a lot, but that is for BTC and is also unofficial and refers to "code is the spec" for somethings.

I'd be fine if this BUIP creates a maintained specification that competes, but would be more happy if it instead creates maintained specifications that cooperate and help complete the specs that already exist.

 

[sickpig]

if memory serves there were someone in the past the started to work on a full protocol specification... need to find out who they were and if they are still working on it, or if some of their initial work is available somewhere

 

[freetrader]

There is https://www.bitcoincash.org/spec/JSON-RPC.html which covers the JSON RPC. (*)
I was looking for a previous site which I think hosted similar info, but could not find it.

Some links on the site like the 'Home' and 'Start Here' appear broken.

(*) It doesn't appear to be a supported section of the main site at all, since I don't see a link from top level.

 

[dagurval]

@freetrader I wrote this script which produces RPC documentation which can be used for Bitcoin Unlimited also.

As for protocol documentation, bitcoin.org has done a decent job of documenting under MIT license which can be used as a starting point
https://github.com/bitcoin-dot-org/bitcoin.org/tree/master/_data/devdocs/en

 

[Jonathan Silverblood]

@solex this needs a BUIP number and an update to reflect that number.

 

[solex]

@Jonathan Silverblood
Certainly. Title updated and added to BUIP index.

 

[9500]

Formal specification has a strict meaning, is that what you really want? Any specification will do IMO.

 

[Jonathan Silverblood]

My intended interpretation of the word formal is:

7. Organized; well-structured and planned.​

https://en.wiktionary.org/wiki/formal

 

[solex]

@Jonathan Silverblood
I thought it best to insert "BCH" in the title for clarity reasons.
This is a significant undertaking which deserves a specific budget authorised. I suggest asking for $20k to enable progress payments for acceptable technical author work.

 

[Jonathan Silverblood]

What happens if the proposal goes through, but there is no defined budget?

 

[Roy Badami]

While developing projects I've repeatedly found myself in need of a specification and have been referred to the concept that the code is the specification, which is unhelpful.

What happens if, after the specification has been published, the code is found not to be in accordance with the specification? Do we hard fork to follow the specification, or do we accept that, in reality, the code is the specification, and that we must correct the errors in the "formal specification" to reflect the reality of the code?

Surely, it has to be the latter! I fully support any initiative to improve protocol documentation, but the notion that there should be a formal specification that would presumably take precedence over the currently coded consensus rules seems dangerously impractical to me.

 

[Jonathan Silverblood]

It is indeed more like the latter, which is why part of this proposal is about maintaining the specification so that it stays up to date and remains relevant as the protocol evolves.

The difference being that the code is written with a specific intent and understanding in mind, and as such bugs and misstakes should not automatically be part of the specification. There is also no single code base that determines the correct behaviour, that is an emergent property based on the miners choices when it comes to which code to run, at any given time.

So a specification here, should document what our understanding and intent is about the current state of the protocol.

 

[Roy Badami]

Yes, that makes sense. I suppose I'm just nitpicking about the name "formal specification".

I'm in favour of producing something as close to a formal specification as is practicable, given reasonably available resources. I just prefer to call it documentation. As you say, the consensus rules are an emergent property of the network; therefore we can't meaningfully specify them (although we can try as a community to influence them) - all we can usefully do is document them.

 

[solex]

What happens if the proposal goes through, but there is no defined budget?

By convention we do not ask the members to approve a funded project with no ceiling. Apologies, I should have mentioned this earlier, but it is not too late to put a budget in the BUIP.
Any unfunded projects get done as and when BU development has available resources. It is faster to have funds which can be targeted where someone with the relevant skill can be hired.

 

[freetrader]

Can someone from BU update this BUIP to reflect decisions taken on its implementation since it passed?

 

[solex]

@freetrader.
Certainly. Joshua Green of BitcoinVerde saw BUIP121 and approached us in late October to take up the challenge, as his team has spare capacity in December. It is great for BCH that they can do it. Andrew Stone has been our principal contact as he has already done a substantial amount of specification work which will be re-used and extended, rather than repeated. The formal agreement to fund them to do the work was signed on the 25th. As the project commences in December, we intend to provide a substantial community update later that month.

 

[solex]

BitcoinVerde have completed their funded work under this BUIP and the results are visible on reference.cash.

This is a community resource and we welcome other contributors to complete the skeleton areas identified during this phase, which did focus first on the important areas specific to Bitcoin Cash development.

 

[freetrader]

@solex according to a source I've talked to, there is still work being done to fill in that site...
which appears correct as I'd say the majority of the mentioned topics isn't fleshed out yet?

e.g. some pages like https://reference.cash/protocol/network/node-handshake/
or https://reference.cash/protocol/blockchain/script/ appear to be just blank yet...

I'll save further review for later, preferably until someone confirms that it is ready for review.