Add Subsection About Wallet Programs, Incl. Hardware Wallets

[harding]

Preview: http://dg1.dtrt.org/en/developer-guide#wallets

The existing Wallet section only covers private key storage. This PR moves that text into a Wallet Files subsection (changing every h3 to h4 and h4 to h5) and adds a new Wallet Programs subsection, giving the document the revised hierarchy:

• Wallets
  • Wallet Programs
    • Full-Service Wallets
    • Signing-Only Wallets
      • Offline Wallets
      • Hardware Wallets
    • Distributing-Only Wallets
  • Wallet Files
    • [Previous text; nothing has been removed]

All the text in Wallet Programs and its children is new. It describes the essential functions of a wallet program and how multiple programs can work together to fulfill those functions, as in the case of a signing-only wallet.

[instagibbs]

As usual, great.

[harding]

@instagibbs thanks!

In the absence of critical feedback, this PR will be merged around 13:00 UTC on June 9th.

[saivann]

Maybe it would be more accurate to say "distributing addresses"? If that makes sense, there is also various other occurences that can be fixed later in the text.

[harding]

Wallets always distribute public keys (in some form). They don't always distribute addresses. An example of a case where a wallet distributes pubkeys instead of addresses is for a multisig output, such as those created by GreenAddress.it's software.

(Note: I'm not exactly sure how GreenAddress.it works---I don't use it---but either your mobile app sends them groups of pre-generated pubkeys or it sends them a parent pubkey.)

Because pubkeys are always distributed in some form, I'd prefer to use that as the term instead of addresses.

[saivann]

@harding It's indeed easier to understand the "private key / public key" logic I guess. I think I was only worried this could confuse/conflicts with the "conceal your public keys" argument for not re-using addresses. But I don't have a strong opinion here. About the GreenAddress example, IIRC they use P2SH, so the final transaction still conceals the public keys behind a multisig address. Although it is true that public keys are sooner or later revealed in all cases anyway.

[harding]

@saivann GreenAddress.it (GA) does indeed use P2SH---but in order for them to generate a 2-of-2 P2SH multisig address, they have to have a pubkey from your private wallet and a pubkey from their private wallet, so your wallet is actually distributing pubkeys.

In any multisig transaction, you will have to give your co-signers a pubkey. I agree this seems to conflict with the risks identified in the avoiding key reuse, but the risk is probably smaller---you only have to worry about the people you shared your pubkey with cracking ECDSA, not everyone with access to the block chain. For example, GA users only have to worry about GA hacking ECDSA instead of some random genius hacker.

I'll see if I can make this more clear when we add the multisig wallet subsection.

[saivann]

@harding Re: GA, Ah yes, sure! I was referring to how I read "...distributing public keys in order to receive satoshis" (I read "send addresses in payment requests to receive satoshis"). In the GA / offline / hardware wallets examples, the signing-only wallet does both tasks (signing transactions and distributing public keys to the watching wallet), while the watching wallet takes care of payment requests and creating transactions.

[harding]

@saivann fair enough. I'm just not really sure how to word it without being repetitive or incorrect. It would be nice to have a phrase we could use both here and in the other sections where we have the same problem. "Receiving information" sounds too generic; "output script" isn't quite correct in the case of addresses. Maybe "public key in some form"? Or "public key (address)"?

If we change it here, we should change it other places too, so I'm going to assume this is a non-blocking change. Thanks!

[saivann]

@harding Yes I think it's already fine as it is, I just wanted to point it out in case we found something better. Maybe I'll make a suggestion later if you haven't already rewritten this differently. Clearly not a blocking issue, thanks!

[saivann]

While cumbersome, using "parent private keys and parent public keys", and "child private keys and child public keys" here would allow accurate crossref links to be applied, otherwise it links to just "public keys".

[harding]

Yeah, I had the same problem in the HD wallet section. I'll fix it up and see if I can keep it readable at the same time. Thanks!

[saivann]

Maybe we can only make sure it's working correctly on the first occurence - when readers are more likely to need a definition, and later prioritize increased readability?

[saivann]

Avoiding key reuse is probably a good tips for pre-populated databases as well. How about we mention this once in the following paragraph:

To avoid key reuse, a method must be used to ensure the same public
key isn't distributed twice. This can be a database entry for each key distributed,
or an incrementing pointer to the current child key index number
*when using a parent public key*.

Or then again, mention something like this on the "pre-populate database" text:

To avoid key reuse, webservers should keep track of used keys
and never run out of public keys. This can be made easier by using
parent public keys as suggested in the next method.

[harding]

Good idea! I completely missed the implication there that avoiding key reuse only applied to the second list item. I'll fix that. Thanks!

[saivann]

@harding Very nice text! Thanks!!

[harding]

@saivann Commit 63e838f makes all the changes you suggested (I hope). I also updated the preview: http://dg1.dtrt.org/en/developer-guide#wallets

If everything looks good, either let me know so I can merge or merge yourself. Thanks!

[saivann]

@harding LGTM, thanks again for your great work on this!