Developer Guide on bitcoin.org: writers/reviewers needed

[MarcoTC]

Thank you for this. (where is the donation address at the bottom of the page?)
Unfortunately, I'm still catching up so I'm afraid I cannot add much to this project yet.

Until now I found that documentation is all over the place and I honestly have no idea if I'm looking at recent or outdated specs. So hopefully, this will be the place where things stay updated.

Few suggestions:

- For new developers, maybe it makes sense to have a bit more general information. For example, using bitcoin-cli, RPC or using bitcoind as border router.
- Would it be an idea to have 'user contributed notes' under each section?


But thanks again. I think it's a great initiative.

[1713284067]

1713284067

[1713284067]

1713284067

[1713284067]

1713284067

[1713284067]

1713284067

[1713284067]

1713284067

[blockgenesis]

Unfortunately, I'm still catching up so I'm afraid I cannot add much to this project yet.

Actually, reviews would be very useful at this point. If you can spot any confusing text, inaccuracies, typos, etc, please make a pull req or report them as an issue. That'll be very much appreciated.

Few suggestions:

- For new developers, maybe it makes sense to have a bit more general information. For example, using bitcoin-cli, RPC or using bitcoind as border router.
- Would it be an idea to have 'user contributed notes' under each section?

Thanks! Actually if you want to work on the API reference page, that should probably be it. As for the "user contributed notes", can you further explain your idea?

[MarcoTC]

Thanks! Actually if you want to work on the API reference page, that should probably be it. As for the "user contributed notes", can you further explain your idea?

As for working on the API reference page, I wish I could. Hopefully I have enough knowledge to share after I learned more and I will certainly try to help when I'm at that point.

'User contributed notes' are user comments underneath each section.
Basically, where users can submit section related remarks, pitfalls, example code snippets etc. (that maybe can be voted up, down or away).

[Mike Hearn]

The website is purely static and for security reasons I think it should stay that way. If there is a third party commenting platform that lets us just drop something in via Javascript, I think that'd be OK but not if we need to run some kind of php/ruby thing on the bitcoin.org server itself.

[blockgenesis]

The website is purely static and for security reasons I think it should stay that way. If there is a third party commenting platform that lets us just drop something in via Javascript, I think that'd be OK but not if we need to run some kind of php/ruby thing on the bitcoin.org server itself.

Agreed, no server-side scripting for now.

[harding]

Edit:  After reading through the Bitcoin Core source code for an embarrassingly long time, I figured out that this paragraph from BIP70,

signature: digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.

means to do this:

Code:

request.signature = ""

before doing this:

Code:

request.signature = sign(priv_key, request.SerializeToString(), "sha256")

Thanks to everyone who read my previous post.

[harding]

Hi,

The payment processing section (including BIP70 payment requests) has been added to the devguide.  Comments and suggestions are welcome on the pull request.

(Please comment there even though the pull request is closed.  Every comment posted will be read and replied to.)

Thanks to Saïvann's late-night efforts, you can read the new section in nicely-formatted HTML on the demo site.

General questions or comments should be sent here, the mailing list, or submitted as an issue.

Thanks!, -Dave

[harding]

Hi,

We could use a little advice about what's relevant to wallet authors when it comes to choosing which inputs to select for making a new payment.  We described three options:

* A merge avoidance algorithm makes it harder for outsiders looking at block chain data to figure out how many satoshis the receiver has earned, spent, and saved.

* A last-in-first-out (LIFO) algorithm spends newly acquired satoshis while there's still double spend risk, possibly pushing that risk on to others. This can be good for the receiver's balance sheet but possibly bad for their reputation.

* A first-in-first-out (FIFO) algorithm spends the oldest satoshis first, which can help ensure that the receiver's payments always confirm

We were thinking about cutting out FIFO because it doesn't seem very useful (except for being reliable and easy to implement).  We were further discussing whether we should cut out LIFO---which might be useful for some applications---in order to emphesize the privacy benefits of merge avoidance.

However, none of us writers/editors have any practical experience here, so we would appreciate some developer feedback about what you need to know.  Here's a direct link to the input-selection section and our GitHub discussion of the issue.

A quick trace of Electrum's source code (which I happend to have handy) made it seem like it used FIFO.

Thanks, -Dave

[doof]

Can some please explain the procedure of signing a transaction with multiple inputs?

[BCB]

I've only just skimmed the new docs but I'm impressed.  Great job.  I'm looking forward to reading it more closely.

Thank you.

[harding]

Notes about where to contribute to the current effort from the bitcoin-development mailing list:

A new "Developer Documentation" section should be soon merged on
bitcoin.org .

Live Preview:
http://bitcoindev.us.to/en/developer-documentation

GitHub Pull Request:
https://github.com/bitcoin/bitcoin.org/pull/393

Bitcointalk Thread:
https://bitcointalk.org/index.php?topic=511876.0

We've worked hard to come up with good quality documentation and general
feedback has been positive. Reviews from experienced Bitcoin developers
would now be much appreciated. You are cordially invited to help
proofread the documentation so it can be published soon!

*Please avoid commenting on the mailing list* to not spam everyone. See
the pull request for instructions. Comments should go on the pull
request or bitcoin-documentation mailing list
https://groups.google.com/forum/#!forum/bitcoin-documentation .

[blockgenesis]

A quick update on the project:

More reviews and feedback on the pull request are very welcome so we can get this merged:
https://github.com/bitcoin/bitcoin.org/pull/393

This pull request will be merged on May 24th and hopefully will be accurate as much as possible. Reporting any inaccuracy / mistake on the pull request is very appreciated.

[doof]

Can some please explain the procedure of signing a transaction with multiple inputs?

Now that I have figured it out with help of bitcointalk members, i might add this myself.

[super3]

A quick update on the project:

More reviews and feedback on the pull request are very welcome so we can get this merged:
https://github.com/bitcoin/bitcoin.org/pull/393

This pull request will be merged on May 24th and hopefully will be accurate as much as possible. Reporting any inaccuracy / mistake on the pull request is very appreciated.

This is a grade A piece of work. Donated 0.1 BTC to your address.

[piotr_n]

Fascinating lecture.
But you cannot seriously think that this is more useful for a dev than the old wiki.
Or can you?
Well, IMHO it isn't - devs need tables and short explanations, not epic descriptions.
It looks good to be released as a book, though.

Not saying that this is a bad piece - only that it is too long to read, as for dev purposes.
Bitcoin isn't that complicated, nor we seek adventures in its documentation.

[harding]

Hi, piortr_n.

Did you checkout both the guide and the reference pages?  The guide is aimed at new developers who need to learn how Bitcoin works.  The reference is aimed at the developers who know how the general system works but need, as you say, tables and short explanations (which we've put all on one page for easy in-browser Ctrl-f searching).

• Guide: https://bitcoin.org/en/developer-guide
• Reference: https://bitcoin.org/en/developer-reference

Both are linked to from the main page, which also links to other useful resources: https://bitcoin.org/en/developer-documentation

We'll be adding more content over the next few monhs, so check back often!  Thanks!

[piotr_n]

I think I did check everything and really comparing both of your pages, to these two:
https://en.bitcoin.it/wiki/Protocol_specification
https://en.bitcoin.it/wiki/Script
.. I would not envy a guy who has to build a bitcoin software, basing only on your spec.

But OK, I understand that it isn't complete.

Still, if I may add, most of all you need a nice & clean table with all the network messages linking to their descriptions (with sub-tables describing the payload of each type).
And the same for the script - I don't see a table with script opcodes in your spec.
That's the two references I've used the most - nothing else matters that much.

You can have some more epic descriptions, but they should rather be there as an additional help.
So only if anyone doesn't understand what an opcode does (by its name or short desc), he clicks a link and goes there.

[harding]

piotr_n:

Our audience description says that we're focusing on application developers, which (in my mind) means that we prioritize writing documentation for developers who will use libraries or Bitcoin Core RPCs for the underlying network communication.

Once we've covered the topics application developers need to know, I'm happy to move on to topics library developers or core re-implementors need to know.

As for opcodes, we describe all the opcodes used in standard transactions here: https://bitcoin.org/en/developer-reference#op-codes

As for cross-reference linking, we use it extensively---there are over 2,000 links in the Guide and Reference.  Just hover your mouse over a paragraph to see all of the internal links appear in blue.  You can further hover your mouse over a term to get a brief description, and then click on it to go to the full description.

We really did put a lot of work into trying to design the docs to be useful for developers at all stages, from Bitcoin neophyte to core dev.  Given more time (or more volunteers!) we'll be able to fulfill our core mission and expand the docs to cover more and more parts of Bitcoin.

Thanks for your comments!

[blockgenesis]

Yup, it's always good to move forward and think of new improvement. We can't have everything on v0.1 .

Also, I think that's a good reason why it made sense to focus on bringing new content (walkthrough and explanations) rather than duplicating existing tables on the Wiki (and link to them instead). But at some point I agree that having all this content in a single place can indeed be a useful step forward.

[piotr_n]

OK - so it's for "applications".
Now I would have asked "what kind of applications?" if not for the fact that I already figured that you mean applications based on bitcoind's RCP API, or an API of other components that your firm is busy developing.
As an opposite to the actual (software independent) bitcoin protocol applications, as I perceive such through the proto described on the wiki.

So currently it is not a "Bitcoin Developer Reference", but rather a manual for bitcond's RPC API, right?
In such case, I have no critical comments, except maybe for the title of this doc, which I find a bit misleading, to say the least.

You ought to at least make it clear that it is a guide for a specific software API, not so much for Bitcoin as the universal bitcoin protocol.
Otherwise some more experienced devs could blame you of advertising a misleading message about what Bitcoin actually is