
# Hierarchical Deterministic (HD) Wallets

In Cardano, _hierarchical deterministic_ (HD) wallets are similar to those described in
[BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#motivation).

Deterministic wallets and elliptic curve mathematics permit schemes
where one can calculate a wallet public keys without revealing its
private keys. This permits for example a webshop business to let its
webserver generate fresh addresses (public key hashes) for each order
or for each customer, without giving the webserver access to the
corresponding private keys (which are required for spending the
received funds).  However, deterministic wallets typically consist of
a single "chain" of keypairs. The fact that there is only one chain
means that sharing a wallet happens on an all-or-nothing basis.

However, in some cases one only wants some (public) keys to be shared
and recoverable. In the example of a webshop, the webserver does not
need access to all public keys of the merchant's wallet; only to those
addresses which are used to receive customer's payments, and not for
example the change addresses that are generated when the merchant
spends money. Hierarchical deterministic wallets allow such selective
sharing by supporting multiple keypair chains, derived from a single
root.

## Notation

Conceptually, HD derivation can be seen as a tree with many branches,
where keys live at each node and leaf such that an entire sub-tree can
be recovered from only a parent key (and seemingly, the whole tree can
be recovered from the root master key).

[BIP32-Ed25519: Hierarchical Deterministic Keys over a Non-linear Keyspace](Ed25519_BIP.pdf).
For deriving new keys from parent keys, we use the same approach as defined in

We note \\(CKD_{priv}\\) the derivation of a private child key from a parent private key such that:

$$
CKD_{prv}((k^P, c^P), i) → (k_i, c_i)
$$

We note \\(CKD_{pub}\\) the derivation of a public child key from a parent public key such that:

$$
i <  2^{31}: CKD_{pub}((A^P, c^P), i) → (A_i, c_i)
$$

### Note
This is only possible for so-called "soft" derivation indexes, smaller than \\(2^{31}\\).

We note \\(N\\) the public key corresponding to a private key such that:

$$ N(k, c) → (A, c) $$

To shorten notation, we will borrow the same notation as described in BIP-0032
and write

\\(CKD_{priv}(CKD_{priv}(CKD_{priv}(m,3H),2),5)\\) as `m/3H/2/5`.

Equivalently for public keys, we write

\\(CKD_{pub}(CKD_{pub}(CKD_{pub}(M,3),2),5)\\) as `M/3/2/5`.

### Path Levels

Cardano wallet defines the following path levels:

$$
m / purpose_H / coin\_type_H / account_H / account\\_type / address\\_index
$$

- \\(purpose_H = 1852_H\\)
- \\(coin\\_type_H = 1815_H\\)
- \\(account_H = 0_H\\)
- \\(account\\_type \\) is either:
  - `0` to indicate an address on the external chain, that is, an address
    that is meant to be public and communicated to other users.
  - `1` to indicate an address on the internal chain, that is, an address
    that is meant for change, generated by a wallet software.
  - `2` to indicate a reward account address, used for delegation.
- \\(address\\_index\\) is either:
  - `0` if the \\(account\\_type\\) is `2`
  - Anything between \\(0\\) and \\(2^{31}\\) otherwise

In the _Byron_ era, sequential wallets used in Yoroi (a.k.a Icarus wallets) have been using $$purpose = 44_H$$ according to standard BIP-44 wallets.
The _Shelley_ era introduces however an extension to BIP-44, and therefore, uses a different $purpose$ number.

### Account Discovery

What follows is taken from the "Account Discovery" section from [BIP-0044](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#account-discovery)

When the master seed is imported from an external source the software should start to discover the accounts in the following manner:

-    derive the first account's node (index = 0)
-    derive the external chain node of this account
-    scan addresses of the external chain; respect the gap limit described below
-    if no transactions are found on the external chain, stop discovery
-    if there are some transactions, increase the account index and go to step 1

For the algorithm to be successful, software should disallow creation of new accounts if previous one has no transaction history.

Please note that the algorithm works with the transaction history, not account balances, so you can have an account with 0 total coins and the algorithm will still continue with discovery.

### Address gap limit

Address gap limit is currently set to 20. If the software hits 20 unused addresses in a row, it expects there are no used addresses beyond this point and stops searching the address chain. We scan just the external chains, because internal chains receive only coins that come from the associated external chains.

Wallet software should warn when the user is trying to exceed the gap limit on an external chain by generating a new address.
