Class KeyChainGroup

A KeyChainGroup is used by the Wallet and
manages: a BasicKeyChain object (which will normally be empty), and zero or more
DeterministicKeyChains. A deterministic key chain will be created lazily/on demand
when a fresh or current key is requested, possibly being initialized from the private key bytes of the earliest non
rotating key in the basic key chain if one is available, or from a fresh random seed if not.

If a key rotation time is set, it may be necessary to add a new DeterministicKeyChain with a fresh seed
and also preserve the old one, so funds can be swept from the rotating keys. In this case, there may be
more than one deterministic chain. The latest chain is called the active chain and is where new keys are served
from.

The wallet delegates most key management tasks to this class. It is not thread safe and requires external
locking, i.e. by the wallet lock. The group then in turn delegates most operations to the key chain objects,
combining their responses together when necessary.

Deterministic key chains have a concept of a lookahead size and threshold. Please see the discussion in the
class docs for DeterministicKeyChain for more information on this topic.

Returns a key that hasn't been seen in a transaction yet, and which is suitable for displaying in a wallet
user interface as "a convenient key to receive funds on" when the purpose parameter is
KeyChain.KeyPurpose.RECEIVE_FUNDS.

currentKey

Returns a key that hasn't been seen in a transaction yet, and which is suitable for displaying in a wallet
user interface as "a convenient key to receive funds on" when the purpose parameter is
KeyChain.KeyPurpose.RECEIVE_FUNDS. The returned key is stable until
it's actually seen in a pending or confirmed transaction, at which point this method will start returning
a different key (for each purpose independently).

This method is not supposed to be used for married keychains and will throw UnsupportedOperationException if
the active chain is married.
For married keychains use currentAddress(KeyChain.KeyPurpose)
to get a proper P2SH address

currentAddress

freshKey

Returns a key that has not been returned by this method before (fresh). You can think of this as being
a newly created key, although the notion of "create" is not really valid for a
DeterministicKeyChain. When the parameter is
KeyChain.KeyPurpose.RECEIVE_FUNDS the returned key is suitable for being put
into a receive coins wizard type UI. You should use this when the user is definitely going to hand this key out
to someone who wishes to send money.

This method is not supposed to be used for married keychains and will throw UnsupportedOperationException if
the active chain is married.
For married keychains use freshAddress(KeyChain.KeyPurpose)
to get a proper P2SH address

freshKeys

Returns a key/s that have not been returned by this method before (fresh). You can think of this as being
newly created key/s, although the notion of "create" is not really valid for a
DeterministicKeyChain. When the parameter is
KeyChain.KeyPurpose.RECEIVE_FUNDS the returned key is suitable for being put
into a receive coins wizard type UI. You should use this when the user is definitely going to hand this key out
to someone who wishes to send money.

This method is not supposed to be used for married keychains and will throw UnsupportedOperationException if
the active chain is married.
For married keychains use freshAddress(KeyChain.KeyPurpose)
to get a proper P2SH address

findRedeemDataFromScriptHash

Locates a redeem data (redeem script and keys) from the keychain given the hash of the script.
This is needed when finding out which key and script we need to use to locally sign a P2SH transaction input.
It is assumed that wallet should not have more than one private key for a single P2SH tx for security reasons.
Returns RedeemData object or null if no such data was found.

If the key chain contains only random keys and no deterministic key chains, this method will create a chain
based on the oldest non-rotating private key (i.e. the seed is derived from the old wallet).

Parameters:

keyRotationTimeSecs - If non-zero, UNIX time for which keys created before this are assumed to be
compromised or weak, those keys will not be used for deterministic upgrade.

aesKey - If non-null, the encryption key the keychain is encrypted under. If the keychain is encrypted
and this is not supplied, an exception is thrown letting you know you should ask the user for
their password, turn it into a key, and then try again.

Returns:

the DeterministicKeyChain that was created by the upgrade.

Throws:

IllegalStateException - if there is already a deterministic key chain present or if there are
no random keys (i.e. this is not an upgrade scenario), or if aesKey is
provided but the wallet is not encrypted.