Using HD Bitcoin wallets with Drupal Coin Tools

Retrieved from the Wayback Machine.

Each Coin Tools payment needs its own Bitcoin address. This is necessary so that it is clear whether or not the payment has been completed. It is also important for preserving anonymity.

In order to participate in the Bitcoin network, a Drupal website must talk to a Bitcoin node. Currently Coin Tools utilises the reference implementation, bitcoind.

bitcoind has wallet functionality built in. In fact, it was originally released as a desktop wallet for Microsoft Windows. By default, bitcoind will pre-generate a pool of 100 pairs of addresses and corresponding private keys. This pool will be increased as necessary.

This presents a number of problems. If data-loss were to occur on the server, the private keys could be unrecoverable and therefore the funds stored on the addresses would be unspendable. If a hacker gains access to the server they could copy the keys and steal the funds. The private keys can be encrypted, but the password is exposed on the server when generating new keys and spending funds.

To solve these problems, key pairs could be pre-generated in a secure environment and then the public addresses uploaded to the server.

Logistically this is challenging. A much more robust solution to this problem is to use Hierarchical Deterministic Wallets as described in BIP 32 (with draft extensions in BIPs 43, 44 & 45).

HD wallets are composed of a tree of pairs of extended public (xpub) and extended private (xprv) keys derived from a single seed or mnemonic sentence. An xprv can generate its child xpubs and child xprvs. An xpub can only generate its child xpubs. Any extended key can be converted into it's non-extended variant that cannot generate children.

A non-extended public key can be converted into a payment address. A non-extended private key can be used to spend funds that are held on the payment address it is associated with.

An example extended public key is:

xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8

An example extended private key is:

xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi

Extended key pairs are also considered to be either hardened or non-hardened. One of the properties of extended keys is that if an attacker knows a non-hardened private key and the parent xpub, they are able to determine the parent xprv.

In situations where private keys are to be distributed, for example within a company, hardened derivation must be used to prevent other private keys at the same level from being determined.

A further property of extended keys is that xpubs are not capable of generating hardened child public keys at all. This is fine because in an untrusted environment (with only a non-hardened xpub) no private keys will be present.

Payment addresses in an HD wallet can be considered to be either internal or external. External addresses are used when funds are being paid into an account from outside the wallet. Internal addresses are used as change addresses.

The default wallet layout is shown below:

HD wallets have many use-cases and BIP 32 identifies several.

"Unsecure money receiver" is the use-case to solve the problem described in this blog post.

The idea is to maintain an HD wallet in a secure environment. An account would be created in this wallet for the purpose of receiving payments in a specific Coin Tools payment type. The xpub for external addresses from this account would then be exported and added to the configuration of the payment type within Drupal.

Despite the obvious complexity of HD wallets, the concept of creating an account for a specific person, organisation or reason and exporting the xpub is actually very simple. The key point is that only one authority should be making payments into an specific xpub, otherwise addresses would be used multiple times. Scanning for unused addresses would not be an effective strategy to prevent this. Stealth addresses could become a solution for allocation of payment addresses without an authority.

Coin Tools can "interrogate" the provided xpub. The results of this process will be displayed, including the first four addresses that can be generated from the xpub and the relative path of the next address Coin Tools will generate:

Every key pair in the wallet has a path specifying the indexes at each level in the hierarchy, for example M/44'/0'/0'/0/3. Absolute paths have either an m or M as their first component. Relative paths have an index as their first component. In the example above we can see that the xpub has a depth of 3, so relative paths start with describing the index at depth 4.

A ' or _H character after an index in the path indicates that the index is actually i+2³¹. This means that keys at this level have hardened derivation.

According to BIP 43 (draft), the index at level 1 should be the hardened index of the BIP that describes the layout of the hierarchy beneath it. In the example above it is 44, meaning that it is using the layout from BIP 44 instead of the default one from BIP 32.

Despite the fact that many wallets are now HD, support for exporting account xpubs is currently quite low. However, some HD wallets that do not allow xpubs to be exported for regular accounts will allow xpubs to be exported from multisig accounts, for example Coinkite. In the future Coin Tools will support generation of addresses from multisig xpubs.

The only wallets that I know of that will export an xpub from a non-multisig account are Wallet32 and Electrum.

Both these wallets export xpubs that allow derivation of both the external (0/i) and internal (1/i) addresses. This is useful for watching an account balance but means that an entity making the payments into the account has greater ability to spy on subsequent transactions than would otherwise be possible. Coin Tools is currently hard coded to use the relative path 0/i. This will need to be made configurable as Coinkite xpubs do not need any prefix on the index.

It is essential that the addresses generated by Coin Tools match those generated by the wallet otherwise the account will not receive the payments. The xpub in the previous screenshot was exported from a Wallet32 account. In the following screenshot we can see that the addresses displayed in Wallet32 are the same as those generated by Coin Tools:

In theory when an xpub is imported the addresses should be scanned to make sure the xpub has not been used before. However, bitcoind does not maintain the correct indexes to be able to quickly list transactions for arbitrary addresses. When Coin Tools needs to receive a payment on an address from an xpub, it adds it as a watch-only address using the "importaddress" bitcoind command. The "rescan" parameter is set to false which means that transactions that happened before the address was added are not detectable. If this parameter is set to true it can take many minutes even on an SSD to import each address.

Coin Tools uses the Drupal State API to maintain the next index for each xpub. If there are more unreceived payments in a row than the gap limit of the wallet software, the wallet will loose track of later payments. To avoid this happening, payments that expire should maybe have their addresses put in a pool for re-use. However this may cause a problem if someone records the payment address and then satisfies the payment at a later time after it has expired.

Of course, if a hacker gained access to the web server they could change an xpub to their own. This would mean that until the problem was detected and the service shut down the hacker would be receiving the funds instead of the intended recipient. While damaging, this would be nowhere near as bad as the total loss of a hot wallet.

In order to facilitate handling of HD wallets, Coin Tools was converted to use the BitWasp PHP Bitcoin library instead of Gogulski.