hdkeychain: Introduce v2 module.

[davecgh]

NOTE: This currently contains a module replacement directive since it relies on an unreleased version of the chaincfg module. It will need to be removed once the requisite modules is released before this can be merged. However, it is otherwise ready for review.

The hdkeychain package currently has some less-than ideal APIs and behaviors that have been retained up to this point in order to avoid breaking existing caller code. However, now that versioned module support is available and in full use, these items can be addressed.

A quick overview of the issues with hdkeychain this aims to address are:

• It relies on side effects of the magic global-state registration capabilities of chaincfg which are slated to be removed
• It directly accepts *chaincfg.Params in its API funcs which tightly couples it to the specific version of chaincfg. The forces major version bumps of the hdkeychain module when the major version of chaincfg is bumped even if nothing in it that hdkeychain actually relies on changed.
• Address only return addresses of a specific type and script version. Since there ultimately will be multiple address types and script versions, it no longer makes sense to return an address which probably isn't the one the caller actually needs. Instead, the caller can make use of the ECPubKey method to obtain the public key and create the desired address from there.
• The handling of networks is error prone and could lead to subtle bugs:
  • SetNet allows changing the network after keys have already been derived and then deriving more keys which will not result in the same derivation as starting with the target network to begin with. There is also no practical use for changing a network in the middle of a derivation or providing an extended key serialized for a network that the rest of the derivation does not apply to.
  • NewKeyFromString does not accept the network the serialized extended key is intended to be for and instead parses for any recognized network. This results in requiring the caller ensuring it is for the correct network via the separate IsForNet which leads to to the next point. Instead, NewKeyFromString should take the required network as a parameter and error if the serialized extended key is not for that network.
  • IsForNet is easy for a caller to forget which means it could lead to them inadvertently using keys for other networks.

Consequently, this introduces hdkeychain/v2 which addresses the aforementioned items. A series of individual commits to make the review process easier. Each commit message more thoroughly describes its purpose, but primarily they consist of the following:

• Freeze version 1 of the hdkeychain module
• Remove the root module hdkeychain override so building the software will still produce binaries based on the v1 module until the v2 module is fully released
• Correct the keys used for the benchmarks and example docs to be correct for Decred
• Consolidate tests in the main package
• Remove Address
• Remove SetNet
• Used locally-scoped network params in the tests to permit easier mocks
• Modify NewKeyFromString to accept required network parameters and error in the case the provided serialized extended key does not correspond to the network
• Remove IsForNet
• Refactor internals to avoid relying on global chaincfg state which also leads to a slight optimization (benchmarks below)
• Introduce a new NetworkParams interface that is limited specifically to the parameters needed and update all APIs that previously accepted *chaincfg.Params to use the new interface instead.
• Convert the tests to use mock params that satisfy the interface thus preventing test failures if chaincfg changes
• Bump the module version to v2
• Update docs for the new module version

The following is a before and after comparison of the allocations and performance as a side effect of the changes:

benchmark                 old ns/op   new ns/op   delta
--------------------------------------------------------
BenchmarkDeriveHardened   5795        5600        -3.36%
BenchmarkDeriveNormal     6585        6263        -4.89%
BenchmarkPrivToPub        137         118         -13.87%
BenchmarkDeserialize      17618       17618       +0.00%
BenchmarkSerialize        21672       21061       -2.82%

benchmark                 old bytes   new bytes   delta
--------------------------------------------------------
BenchmarkDeriveHardened   1552        1536        -1.03%
BenchmarkDeriveNormal     1601        1585        -1.00%
BenchmarkPrivToPub        128         112         -12.50%
BenchmarkDeserialize      1640        1624        -0.98%
BenchmarkSerialize        1712        1712        +0.00%

Finally, it should also be noted that this only introduces the new module and does not update anything to make use of it yet, so building the software will still produce binaries based on the v1 module.

[matheusd]

An idea: also make the NetParams return the masterKey to be used when generating a new extended key. This would allow the package to be used in networks other than bitcoin/decred and remove another global magic constant.

[davecgh]

That seems like a good idea. It does mean the parameter should first be added to chaincfg and also the appropriate method introduced there so that the various chaincfg parameters implicitly satisfy the interface. Otherwise, it would require the callers to write conversion code to get it to satisfy the interface which I'd like to avoid.

[davecgh]

After discussing this with @jrick and considering it a bit more, changing the master key would actually break multi-currency wallets since the BIP defines the seed as a specific value and thus BIP44 implicitly relies on it.

[davecgh]

Updated to account for renamed HD extended key accessor funcs in chaincfg.

[davecgh]

This is ready for final review and ready to be merged.