Next Version Major Changes

[David A. Harding]

Hi all,

Saīvann has created a list of things writers and other contributors can
work on:

https://github.com/bitcoin/bitcoin.org/wiki/Documentation-TODO

I want that list---or at least part of it---to be absolutely
non-controversial, so contributors who choose to work on an item can
have a reasonable expectation that anything of quality they produce will
eventually be merged into the Bitcoin.org repository.

I was thinking that we could add a section to the list for New Ideas and
that we could occasionally post a copy of the New Ideas section to this
list and have an informal vote. Items that received at least two +1
votes would move to the top sections of the list as long as they don't
receive any -1 votes.

(Any idea which creates a divergence of opinion should be discussed
before being worked upon.)

If that sounds good, here are the current items on the list for voting
on:

New Content

* Multisig wallets (hardware like Trezor or software like
GreenAddress.it)
* Threshold signatures (alternative multisig)
* Stealth addresses
* Assurance contracts
* Generating transactions with RPCs walkthrough

Improvements

* Point out that P2SH addresses start with a "3", and point out that
the bitcoind create/addmultisig creates these style of addresses.
* Provide anchor link affordance

The votes are going to be read by the people on this list, not processed
by a program, so express your vote in any non-ambiguous way you want.
Say, "+1 all" or "-1 this thing but +1 the rest" or etc...

It seems unfair for me to vote in the same message which describes the
proposals, so I'll withhold my vote until after someone else votes.

-Dave
--
David A. Harding

[David A. Harding]

On Wed, May 14, 2014 at 06:20:41PM -0400, David A. Harding wrote:
> I was thinking that we could add a section to the list for New Ideas and
> that we could occasionally post a copy of the New Ideas section to this
> list and have an informal vote.

Saīvann helped me realize that I neglected to mention two alternatives
to voting:

* Saying something like "no opinion" for ideas you don't care about.

* Saying something like "tell me more about this" for ideas you
want more details about before voting.

I'll try to quickly explain the stuff on the list which some of you may
not have heard about before:

> * Threshold signatures (alternative multisig)

As I understand it, threshold sigs allows multisig signatures without
using OP_CHECKMULTISIG. Instead, a single composite public key is
created from multiple individual public keys and then a composite
signature is created from some number signatures made by the
corresponding private keys. The result is a standard ECDSA signature
which matches a standard ECDSA public key, so the multisig stuff is
transparent to the network.

This has the advantages that multisig transcations don't take up extra
block chain space and don't use up extra sigops no matter how many
keys/signatures are used. This is a huge win for people who want >3 (or
>9) multisig.

The main source of information about it seems to be this paper:

http://www.cs.princeton.edu/~stevenag/bitcoin_threshold_signatures.pdf

This thread has discussions about it from core devs and -wizards:

https://bitcointalk.org/index.php?topic=511074.0

> * Stealth addresses

These are basically HD wallets without the wallet, so they shouldn't
require much additional text.

> * Assurance contracts

Bitcoin assurance contracts are basically decentralized Kickstarter.
They're something I think is very cool, but (to my knowledge) there's no
software implementation that makes them easy, so even if we put this
item on the todo list, I won't consider it high-priority.

> * Generating transactions with RPCs walkthrough

This would be for the devcookbook (or whatever we call it). Basically
we'll take readers through the steps of creating various different
transactions. After a small update to the HD wallet text, this will
probably be my first priority.

> * Provide anchor link affordance

This will make it easier to link to specific sections for people who
don't notice their URL bar changing when they scroll.

[Saïvann Carignan]

@instagibbs @cbeams @tgeller, any opinion?

My understanding of the suggestions is still a little bit limited, but I
notice that we're now starting to explore subjects that are more
theoretical, often without implementation or BIP published.

So just as a general thought, perhaps we can somehow separate cool
experimental/theoretical stuff from usable standards *today*?
Maybe just a disclaimer?

--

* Multisig wallets
(I don't see the connection between hardware wallets like Trezor and
multisig? Perhaps there's other protocols worth describing about
hardware wallets?)

(Should multisig be presented as a clever way to use existing HD
wallets, and not as a different wallet type? In general, I really think
+1 but perhaps it would be nice to better clarify this point?)

* Threshold signatures (alternative multisig)

It is my understanding that this is still very theorical?
If true, I vote "maybe later, wait and see"?

* Stealth addresses
It is my understanding that this idea was well received, will soon have
a BIP and isn't using fancy new crypto?
If true, +1

* Assurance contracts
+1 (Agree it's not the priority, but it's good to provide more contracts
examples IMO)

* Generating transactions with RPCs walkthrough

+1

Saïvann

[David A. Harding]

On Fri, May 16, 2014 at 03:52:04PM -0400, Saīvann Carignan wrote:
> My understanding of the suggestions is still a little bit limited, but I
> notice that we're now starting to explore subjects that are more
> theoretical, often without implementation or BIP published.

Yes; I'm not a big fan of unsupported ideas and I don't plan to write
anything myself unless there's at least sample implementation under an
open source license.

> So just as a general thought, perhaps we can somehow separate cool
> experimental/theoretical stuff from usable standards *today*?
> Maybe just a disclaimer?

Good idea. Maybe divide all the tasks into two sections: one for
high-priority tasks (extant tech) and one for low-priority tasks
(future tech).

> * Multisig wallets
> (I don't see the connection between hardware wallets like Trezor and
> multisig? Perhaps there's other protocols worth describing about
> hardware wallets?)

The confusion is my fault: I was overgeneralizing in my brain when I
created the todo item. The connection in my mushy mind is that, to the
user, these seem roughly equivilant:

* Generating an unsigned transaction on your computer and then
sending it to your Trezor to be signed.

* Generating a partially-signed transaction on your phone and then
sending it to GreenWallet.it to be fully-signed.

I have a proposal I want to discuss on the list in a few days about the
Wallet section, so (if nobody minds) I suggest we table hardware wallets
for now and vote only on adding multisig wallets to the contracts
section.

> * Threshold signatures (alternative multisig)
> It is my understanding that this is still very theorical?
> If true, I vote "maybe later, wait and see"?

In that thread I linked, I believe Mike Hearn said he wanted to implement
it as part of the bitcoinj HD wallet refactoring. So it's theoretical
only in the sense that Mike is really busy. :-)

My vote is +1, but low-priority until there's some code to see.

> * Stealth addresses
> It is my understanding that this idea was well received, will soon have
> a BIP and isn't using fancy new crypto?
> If true, +1

Yes, it uses the exact same math as HD wallets, and stealth addresses have
been implemented in the sx command-line client. I vote +1 and
high-priority (though not one of my personal high priorities).

[David A. Harding]

On Thu, May 15, 2014 at 02:31:14PM -0400, David A. Harding wrote:
> > * Assurance contracts
>
> Bitcoin assurance contracts are basically decentralized Kickstarter.
> They're something I think is very cool, but (to my knowledge) there's no
> software implementation that makes them easy

I guess I spoke too soon:

http://blog.vinumeris.com/2014/05/17/lighthouse/

(Awesome work Mike!)

I'll now +1 assurance contracts.

[Saïvann Carignan]

> http://blog.vinumeris.com/2014/05/17/lighthouse/

Indeed, awesome project!

Saïvann

[Chris Beams]

On May 16, 2014, at 9:52 PM, Saïvann Carignan <sai...@gmail.com> wrote:

> @instagibbs @cbeams @tgeller, any opinion?

Generally, I'd favor at least mentioning these concepts in the document, even if only to explain their experimental nature, and perhaps linking to the best known resources or write-ups elsewhere on the web. We can keep the treatment light.

Doing so would keep the document 'living' over time, and encourage readers to relate to the dev guide as a great place to start when researching pretty much any technical aspect of Bitcoin—including quickly assessing how mature that concept is.

Of course there would need to be some lower threshold on which topics are worth mentioning, but I'm suggesting that we err at least slightly toward a liberal policy and see what happens.

- Chris

> --
> You received this message because you are subscribed to the Google Groups "bitcoin-documentation" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to bitcoin-document...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Greg Sanders]

 * Multisig wallets (hardware like Trezor or software like 
      GreenAddress.it) 

+1 . They are the future for keeping secure people's satoshis, outside of just handing keys to a trusted third party.

    * Threshold signatures (alternative multisig) 

-1. I'd wait until someone has working software. It is quite exciting, but for now people(I think) just need <=5 sigs.

    * Stealth addresses 

-1. Standard is still a moving target. Once a final spec is created, I'll +1.

    * Assurance contracts 

+1, esp lighthouse! So cool.

    * Generating transactions with RPCs walkthrough 

+1

> To unsubscribe from this group and stop receiving emails from it, send an email to bitcoin-documentation+unsub...@googlegroups.com.

[David A. Harding]

On Wed, May 21, 2014 at 12:59:17PM -0700, Greg Sanders wrote:
> * Generating transactions with RPCs walkthrough
> +1

As I previously mentioned, this is my next project. It's going to be for
the new Developer Examples page. I also plan to move the BIP70 example
program from the Guide to the Developer Examples page and replace its
position in the guide with a short text about what BIP70 does.

In addition, I'd like at least one more section for the Developer
Examples page before we launch it, preferably from a section besides
Transactions or Payment Processing. Does anyone have any ideas?

[Saïvann Carignan]

Maybe some examples on how to make block / transaction stats on the
Block Chain subsection.

Or detect chain forks in the P2P Network subsection by connecting to
various nodes?

But I agree too that Transactions & Payment Processing are probably the
highest priorities.

Just an idea, but one thing that might be useful is how to monitor a
payment and confirmation score in "Payment Processing".

Saïvann

[Saïvann Carignan]

So far it seems to me that these subjects have a good consensus:

* Multisig wallets (hardware like Trezor or software like
GreenAddress.it)

* Assurance contracts

* Generating transactions with RPCs walkthrough

And these ones are considered too experimental for now:

* Threshold signatures (alternative multisig)

* Stealth addresses

Although as @cbeams mentioned, I also think there's only benefits from
having small mentions to exciting new concepts, so long as we don't
write more serious documentation until it's stable enough.

Saīvann

[David A. Harding]

On Thu, May 22, 2014 at 01:59:36PM -0400, Saīvann Carignan wrote:
> So far it seems to me that these subjects have a good consensus:

Agreed. I updated the TODO; diff below. Thanks Saīvann, Greg, and
Chris! -Dave


diff --git a/Documentation-TODO.md b/Documentation-TODO.md
index 635cd58..ea63481 100644
--- a/Documentation-TODO.md
+++ b/Documentation-TODO.md
@@ -11,20 +11,28 @@
* [ ] Describe regtest mode


+### Good Content For New Writers
+
+To help contribute to the Bitcoin.org documentation, you can write about
+one of the following topics pre-vetted by the [mailing list][]. To
+claim a topic, move it to the Being Made Now section above. Make sure
+you also read the contributing [readme][], and feel free to ask any
+questions on the mailing list.
+
+* [ ] Multisig wallets like GreenAddress.it
+* [ ] Hardware wallets like Trezor
+* [ ] Assurance contracts such as those created by [Lighthouse](http://blog.vinumeris.com/2014/05/17/lighthouse/)
+

### New Content Proposals

-Please use this section to suggest content to be written for future versions of the developer guide or the developer reference. (Or the forthcoming developer cookbook/developer examples/or whatever we name it.) Major suggestions or proposals to make large changes to any of the documentation should be discussed on the [mailing list](https://groups.google.com/forum/#!forum/bitcoin-documentation).
+Please use this section to suggest content to be written for future versions of the developer guide or the developer reference. (Or the forthcoming developer cookbook/developer examples/or whatever we name it.) Major suggestions or proposals to make large changes to any of the documentation should be discussed on the [mailing list][].
+

~~~
* [ ] <proposal> @<proposer>
~~~

-* [ ] Multisig wallets (hardware like Trezor or Software like GreenAddress.it) @harding
-* [ ] Threshold signatures (alternative multisig) @harding
-* [ ] Stealth addresses @harding
-* [ ] Assurance contracts @harding
-* [ ] Generating transactions with RPCs walkthrough @harding
* [ ] Add a section about handling bitcoin values. @gmaxwell says: "you do NOT want to handle them as floats [and] you often don't want to handle them as doubles. Use of floats can produce weird results due to rounding, [so] it's best to use 64 bit integers. (The RPC has special formating that always displays the trailing zeros.) A lot of people making bitcoin software make the mistake of using whatever random floating point values they have handy and then really bad things happen.


@@ -32,3 +40,18 @@ Please use this section to suggest content to be written for future versions of

* [ ] Point out that P2SH addresses start with a "3", and point out that the bitcoind create/addmultisig creates these style of addresses.

* [ ] Provide [anchor link affordance](https://github.com/saivann/bitcoin.org/issues/62) @saivann
+
+
+### Someday Content
+
+Content which participants on the mailing list have decided to avoid
+writing about in depth until an implementation (preferably open source),
+a BIP, or (best of all) both are available. However, a short description
+linking to an off-site discussion would be fine.
+
+* [ ] Threshold signatures (alternative multisig)
+* [ ] Stealth addresses
+
+
+[mailing list]: https://groups.google.com/forum/#!forum/bitcoin-documentation
+[readme]: https://github.com/bitcoin/bitcoin.org#how-to-participate
--
David A. Harding