A deterministic key chain is a KeyChain that uses the
BIP 32 standard, as implemented by
DeterministicHierarchy, to derive all the keys in the keychain from a master seed.
This type of wallet is extremely convenient and flexible. Although backing up full wallet files is always a good
idea, to recover money only the root seed needs to be preserved and that is a number small enough that it can be
written down on paper or, when represented using a BIP 39 MnemonicCode,
dictated over the phone (possibly even memorized).

This class builds on DeterministicHierarchy and
DeterministicKey by adding support for serialization to and from protobufs,
and encryption of parts of the key tree. Internally it arranges itself as per the BIP 32 spec, with the seed being
used to derive a master key, which is then used to derive an account key, the account key is used to derive two
child keys called the internal and external parent keys (for change and handing out addresses respectively)
and finally the actual leaf keys that users use hanging off the end. The leaf keys are special in that they don't
internally store the private part at all, instead choosing to rederive the private key from the parent when
needed for signing. This simplifies the design for encrypted key chains.

The key chain manages a lookahead zone. This zone is required because when scanning the chain, you don't
know exactly which keys might receive payments. The user may have handed out several addresses and received payments
on them, but for latency reasons the block chain is requested from remote peers in bulk, meaning you must
"look ahead" when calculating keys to put in the Bloom filter. The default lookahead zone is 100 keys, meaning if
the user hands out more than 100 addresses and receives payment on them before the chain is next scanned, some
transactions might be missed. 100 is a reasonable choice for consumer wallets running on CPU constrained devices.
For industrial wallets that are receiving keys all the time, a higher value is more appropriate. Ideally DKC and the
wallet would know how to adjust this value automatically, but that's not implemented at the moment.

In fact the real size of the lookahead zone is larger than requested, by default, it's one third larger. This
is because the act of deriving new keys means recalculating the Bloom filters and this is an expensive operation.
Thus, to ensure we don't have to recalculate on every single new key/address requested or seen we add more buffer
space and only extend the lookahead zone when that buffer is exhausted. For example with a lookahead zone of 100
keys, you can request 33 keys before more keys will be calculated and the Bloom filter rebuilt and rebroadcast.
But even when you are requesting the 33rd key, you will still be looking 100 keys ahead.

DeterministicKeyChain

Generates a new key chain with entropy selected randomly from the given SecureRandom
object and of the requested size in bits. The derived seed is further protected with a user selected passphrase
(see BIP 39).

DeterministicKeyChain

Creates a deterministic key chain starting from the given entropy. All keys yielded by this chain will be the same
if the starting seed is the same. You should provide the creation time in seconds since the UNIX epoch for the
seed: this lets us know from what part of the chain we can expect to see derived keys appear.

DeterministicKeyChain

Creates a deterministic key chain that watches the given (public only) root key. You can use this to calculate
balances and generally follow along, but spending is not possible with such a chain. Currently you can't use
this method to watch an arbitrary fragment of some other tree, this limitation may be removed in future.

DeterministicKeyChain

Creates a deterministic key chain with the given watch key. If isFollowing flag is set then this keychain follows
some other keychain. In a married wallet following keychain represents "spouse's" keychain.

markKeyAsUsed

Mark the DeterministicKey as used.
Also correct the issued{Internal|External}Keys counter, because all lower children seem to be requested already.
If the counter was updated, we also might trigger lookahead.

getWatchingKey

Use this when you would like to create a watching key chain that follows this one, but can't spend money from it.
The returned key can be serialized and then passed into watch(org.bitcoinj.crypto.DeterministicKey)
on another system to watch the hierarchy.

Note that the returned key is not pubkey only unless this key chain already is: the returned key can still
be used for signing etc if the private key bytes are available.

isWatching

public boolean isWatching()

Returns true if this chain is watch only, meaning it has public keys but no private key.

getEarliestKeyCreationTime

Returns the earliest creation time of keys in this chain, in seconds since the epoch. This can return zero
if at least one key does not have that data (was created before key timestamping was implemented). If there
are no keys in the wallet, Long.MAX_VALUE is returned.

toEncrypted

Returns a new keychain holding identical/cloned keys to this chain, but encrypted under the given key.
Old keys and keychains remain valid and so you should ensure you don't accidentally hold references to them.

toDecrypted

Decrypt the key chain with the given AES key and whatever KeyCrypter is already set. Note that if you
just want to spend money from an encrypted wallet, don't decrypt the whole thing first. Instead, set the
SendRequest.aesKey field before asking the wallet to build the send.

getFilter

Gets a bloom filter that contains all of the public keys from this chain, and which will provide the given
false-positive rate if it has size elements. Keep in mind that you will get 2 elements in the bloom filter for
each key in the key chain, for the public key and the hash of the public key (address form). For this reason
size should be at least 2x the result of KeyChain.numKeys().

getLookaheadSize

public int getLookaheadSize()

The number of public keys we should pre-generate on each path before they are requested by the app. This is
required so that when scanning through the chain given only a seed, we can give enough keys to the remote node
via the Bloom filter such that we see transactions that are "from the future", for example transactions created
by a different app that's sharing the same seed, or transactions we made before but we're replaying the chain
given just the seed. The default is 100.

setLookaheadSize

public void setLookaheadSize(int lookaheadSize)

Sets a new lookahead size. See getLookaheadSize() for details on what this is. Setting a new size
that's larger than the current size will return immediately and the new size will only take effect next time
a fresh filter is requested (e.g. due to a new peer being connected). So you should set this before starting
to sync the chain, if you want to modify it. If you haven't modified the lookahead threshold manually then
it will be automatically set to be a third of the new size.

setLookaheadThreshold

public void setLookaheadThreshold(int num)

Sets the threshold for the key pre-generation. This is used to avoid adding new keys and thus
re-calculating Bloom filters every time a new key is calculated. Without a lookahead threshold, every time we
received a relevant transaction we'd extend the lookahead zone and generate a new filter, which is inefficient.

getLookaheadThreshold

public int getLookaheadThreshold()

Gets the threshold for the key pre-generation. See setLookaheadThreshold(int) for details on what this
is. The default is a third of the lookahead size (100 / 3 == 33). If you don't modify it explicitly then this
value will always be one third of the lookahead size.

maybeLookAhead

public void maybeLookAhead()

Pre-generate enough keys to reach the lookahead size. You can call this if you need to explicitly invoke
the lookahead procedure, but it's normally unnecessary as it will be done automatically when needed.

maybeLookAheadScripts

public void maybeLookAheadScripts()

Housekeeping call to call when lookahead might be needed. Normally called automatically by KeychainGroup.

getIssuedExternalKeys

public int getIssuedExternalKeys()

Returns number of keys used on external path. This may be fewer than the number that have been deserialized
or held in memory, because of the lookahead zone.

getIssuedInternalKeys

public int getIssuedInternalKeys()

Returns number of keys used on internal path. This may be fewer than the number that have been deserialized
or held in memory, because of the lookahead zone.