KeyChainGroup (bitcoinj 0.14 API)

java.lang.Object
- org.bitcoinj.wallet.KeyChainGroup

All Implemented Interfaces:

KeyBag
```
public class KeyChainGroup
extends Object
implements KeyBag
```
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.

Field Summary

Fields
Modifier and Type Field and Description

protected LinkedList<DeterministicKeyChain> chains

Fields
Modifier and Type	Field and Description
`protected LinkedList<DeterministicKeyChain>`	`chains`

Constructor Summary

Constructors
Constructor and Description
`KeyChainGroup(NetworkParameters params)` Creates a keychain group with no basic chain, and a single, lazily created HD chain.
`KeyChainGroup(NetworkParameters params, DeterministicKey watchKey)` Creates a keychain group with no basic chain, and an HD chain that is watching the given watching key.
`KeyChainGroup(NetworkParameters params, DeterministicSeed seed)` Creates a keychain group with no basic chain, and an HD chain initialized from the given seed.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAndActivateHDChain(DeterministicKeyChain chain)` Adds an HD chain to the chains list, and make it the default chain (from which keys are issued).
`void`	`addEventListener(KeyChainEventListener listener)` Adds a listener for events that are run when keys are added, on the user thread.
`void`	`addEventListener(KeyChainEventListener listener, Executor executor)` Adds a listener for events that are run when keys are added, on the given executor.
`boolean`	`checkAESKey(org.spongycastle.crypto.params.KeyParameter aesKey)`
`boolean`	`checkPassword(CharSequence password)`
`void`	`createAndActivateNewHDChain()` Adds a new HD chain to the chains list, and make it the default chain (from which keys are issued).
`Address`	`currentAddress(KeyChain.KeyPurpose purpose)` Returns address for a `currentKey(KeyChain.KeyPurpose)`
`DeterministicKey`	`currentKey(KeyChain.KeyPurpose purpose)` 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`.
`void`	`decrypt(org.spongycastle.crypto.params.KeyParameter aesKey)` Decrypt the keys in the group using the previously given key crypter and the AES key.
`void`	`encrypt(KeyCrypter keyCrypter, org.spongycastle.crypto.params.KeyParameter aesKey)` Encrypt the keys in the group using the KeyCrypter and the AES key.
`ECKey`	`findKeyFromPubHash(byte[] pubkeyHash)` Locates a keypair from the keychain given the hash of the public key.
`ECKey`	`findKeyFromPubKey(byte[] pubkey)` Locates a keypair from the keychain given the raw public key bytes.
`RedeemData`	`findRedeemDataFromScriptHash(byte[] scriptHash)` Locates a redeem data (redeem script and keys) from the keychain given the hash of the script.
`Address`	`freshAddress(KeyChain.KeyPurpose purpose)` Returns address for a `freshKey(KeyChain.KeyPurpose)`
`DeterministicKey`	`freshKey(KeyChain.KeyPurpose purpose)` Returns a key that has not been returned by this method before (fresh).
`List<DeterministicKey>`	`freshKeys(KeyChain.KeyPurpose purpose, int numberOfKeys)` Returns a key/s that have not been returned by this method before (fresh).
`static KeyChainGroup`	`fromProtobufEncrypted(NetworkParameters params, List<Protos.Key> keys, KeyCrypter crypter, KeyChainFactory factory)`
`static KeyChainGroup`	`fromProtobufUnencrypted(NetworkParameters params, List<Protos.Key> keys, KeyChainFactory factory)`
`DeterministicKeyChain`	`getActiveKeyChain()` Returns the key chain that's used for generation of fresh/current keys.
`BloomFilter`	`getBloomFilter(int size, double falsePositiveRate, long nTweak)`
`int`	`getBloomFilterElementCount()`
`int`	`getCombinedKeyLookaheadEpochs()` Returns a counter that increases (by an arbitrary amount) each time new keys have been calculated due to lookahead and thus the Bloom filter that was previously calculated has become stale.
`List<DeterministicKeyChain>`	`getDeterministicKeyChains()` Returns a copy of the current list of chains.
`long`	`getEarliestKeyCreationTime()`
`List<ECKey>`	`getImportedKeys()` Returns a list of the non-deterministic keys that have been imported into the wallet, or the empty list if none.
`KeyCrypter`	`getKeyCrypter()` Returns the key crypter or null if the group is not encrypted.
`int`	`getLookaheadSize()` Gets the current lookahead size being used for ALL deterministic key chains.
`int`	`getLookaheadThreshold()` Gets the current lookahead threshold being used for ALL deterministic key chains.
`boolean`	`hasKey(ECKey key)`
`int`	`importKeys(ECKey... keys)` Imports the given keys into the basic chain, creating it if necessary.
`int`	`importKeys(List<ECKey> keys)` Imports the given keys into the basic chain, creating it if necessary.
`int`	`importKeysAndEncrypt(List<ECKey> keys, org.spongycastle.crypto.params.KeyParameter aesKey)` Imports the given unencrypted keys into the basic chain, encrypting them along the way with the given key.
`boolean`	`isDeterministicUpgradeRequired()` Returns true if the group contains random keys but no HD chains.
`boolean`	`isEncrypted()` Returns true if the group is encrypted.
`boolean`	`isMarried()` Whether the active keychain is married.
`boolean`	`isRequiringUpdateAllBloomFilter()`
`boolean`	`isWatching()` Returns whether this chain has only watching keys (unencrypted keys with no private part).
`void`	`markP2SHAddressAsUsed(Address address)`
`void`	`markPubKeyAsUsed(byte[] pubkey)` Mark the DeterministicKeys as used, if they match the pubkey See `DeterministicKeyChain.markKeyAsUsed(DeterministicKey)` for more info on this.
`void`	`markPubKeyHashAsUsed(byte[] pubkeyHash)` Mark the DeterministicKeys as used, if they match the pubkeyHash See `DeterministicKeyChain.markKeyAsUsed(DeterministicKey)` for more info on this.
`int`	`numKeys()` Returns the number of keys managed by this group, including the lookahead buffers.
`boolean`	`removeEventListener(KeyChainEventListener listener)` Removes a listener for events that are run when keys are added.
`boolean`	`removeImportedKey(ECKey key)` Removes a key that was imported into the basic key chain.
`List<Protos.Key>`	`serializeToProtobuf()` Returns a list of key protobufs obtained by merging the chains.
`void`	`setLookaheadSize(int lookaheadSize)` Sets the lookahead buffer size for ALL deterministic key chains as well as for following key chains if any exist, see `DeterministicKeyChain.setLookaheadSize(int)` for more information.
`void`	`setLookaheadThreshold(int num)` Sets the lookahead buffer threshold for ALL deterministic key chains, see `DeterministicKeyChain.setLookaheadThreshold(int)` for more information.
`String`	`toString(boolean includePrivateKeys)`
`DeterministicKeyChain`	`upgradeToDeterministic(long keyRotationTimeSecs, org.spongycastle.crypto.params.KeyParameter aesKey)` 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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - chains
```
protected final LinkedList<DeterministicKeyChain> chains
```
- Constructor Detail
  - KeyChainGroup
```
public KeyChainGroup(NetworkParameters params)
```
    Creates a keychain group with no basic chain, and a single, lazily created HD chain.
  - KeyChainGroup
```
public KeyChainGroup(NetworkParameters params,
                     DeterministicSeed seed)
```
    Creates a keychain group with no basic chain, and an HD chain initialized from the given seed.
  - KeyChainGroup
```
public KeyChainGroup(NetworkParameters params,
                     DeterministicKey watchKey)
```
    Creates a keychain group with no basic chain, and an HD chain that is watching the given watching key. This HAS to be an account key as returned by DeterministicKeyChain.getWatchingKey().
- Method Detail
  - createAndActivateNewHDChain
```
public void createAndActivateNewHDChain()
```
    Adds a new HD chain to the chains list, and make it the default chain (from which keys are issued).
  - addAndActivateHDChain
```
public void addAndActivateHDChain(DeterministicKeyChain chain)
```
    Adds an HD chain to the chains list, and make it the default chain (from which keys are issued). Useful for adding a complex pre-configured keychain, such as a married wallet.
  - currentKey
```
public DeterministicKey currentKey(KeyChain.KeyPurpose purpose)
```
    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
```
public Address currentAddress(KeyChain.KeyPurpose purpose)
```
    Returns address for a currentKey(KeyChain.KeyPurpose)
  - freshKey
```
public DeterministicKey freshKey(KeyChain.KeyPurpose purpose)
```
    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
```
public List<DeterministicKey> freshKeys(KeyChain.KeyPurpose purpose,
                                        int numberOfKeys)
```
    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
  - freshAddress
```
public Address freshAddress(KeyChain.KeyPurpose purpose)
```
    Returns address for a freshKey(KeyChain.KeyPurpose)
  - getActiveKeyChain
```
public final DeterministicKeyChain getActiveKeyChain()
```
    Returns the key chain that's used for generation of fresh/current keys. This is always the newest HD chain.
  - setLookaheadSize
```
public void setLookaheadSize(int lookaheadSize)
```
    Sets the lookahead buffer size for ALL deterministic key chains as well as for following key chains if any exist, see DeterministicKeyChain.setLookaheadSize(int) for more information.
  - getLookaheadSize
```
public int getLookaheadSize()
```
    Gets the current lookahead size being used for ALL deterministic key chains. See DeterministicKeyChain.setLookaheadSize(int) for more information.
  - setLookaheadThreshold
```
public void setLookaheadThreshold(int num)
```
    Sets the lookahead buffer threshold for ALL deterministic key chains, see DeterministicKeyChain.setLookaheadThreshold(int) for more information.
  - getLookaheadThreshold
```
public int getLookaheadThreshold()
```
    Gets the current lookahead threshold being used for ALL deterministic key chains. See DeterministicKeyChain.setLookaheadThreshold(int) for more information.
  - importKeys
```
public int importKeys(List<ECKey> keys)
```
    Imports the given keys into the basic chain, creating it if necessary.
  - importKeys
```
public int importKeys(ECKey... keys)
```
    Imports the given keys into the basic chain, creating it if necessary.
  - checkPassword
```
public boolean checkPassword(CharSequence password)
```
  - checkAESKey
```
public boolean checkAESKey(org.spongycastle.crypto.params.KeyParameter aesKey)
```
  - importKeysAndEncrypt
```
public int importKeysAndEncrypt(List<ECKey> keys,
                                org.spongycastle.crypto.params.KeyParameter aesKey)
```
    Imports the given unencrypted keys into the basic chain, encrypting them along the way with the given key.
  - findRedeemDataFromScriptHash
```
@Nullable
public RedeemData findRedeemDataFromScriptHash(byte[] scriptHash)
```
    Description copied from interface: KeyBag
    
    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.
    
    Specified by:
    
    findRedeemDataFromScriptHash in interface KeyBag
  - markP2SHAddressAsUsed
```
public void markP2SHAddressAsUsed(Address address)
```
  - findKeyFromPubHash
```
@Nullable
public ECKey findKeyFromPubHash(byte[] pubkeyHash)
```
    Description copied from interface: KeyBag
    
    Locates a keypair from the keychain given the hash of the public key. This is needed when finding out which key we need to use to redeem a transaction output.
    
    Specified by:
    
    findKeyFromPubHash in interface KeyBag
    
    Returns:
    
    ECKey object or null if no such key was found.
  - markPubKeyHashAsUsed
```
public void markPubKeyHashAsUsed(byte[] pubkeyHash)
```
    Mark the DeterministicKeys as used, if they match the pubkeyHash See DeterministicKeyChain.markKeyAsUsed(DeterministicKey) for more info on this.
  - hasKey
```
public boolean hasKey(ECKey key)
```
  - findKeyFromPubKey
```
@Nullable
public ECKey findKeyFromPubKey(byte[] pubkey)
```
    Description copied from interface: KeyBag
    
    Locates a keypair from the keychain given the raw public key bytes.
    
    Specified by:
    
    findKeyFromPubKey in interface KeyBag
    
    Returns:
    
    ECKey or null if no such key was found.
  - markPubKeyAsUsed
```
public void markPubKeyAsUsed(byte[] pubkey)
```
    Mark the DeterministicKeys as used, if they match the pubkey See DeterministicKeyChain.markKeyAsUsed(DeterministicKey) for more info on this.
  - numKeys
```
public int numKeys()
```
    Returns the number of keys managed by this group, including the lookahead buffers.
  - removeImportedKey
```
public boolean removeImportedKey(ECKey key)
```
    Removes a key that was imported into the basic key chain. You cannot remove deterministic keys.
    
    Throws:
    
    IllegalArgumentException - if the key is deterministic.
  - isMarried
```
public final boolean isMarried()
```
    Whether the active keychain is married. A keychain is married when it vends P2SH addresses from multiple keychains in a multisig relationship.
    
    See Also:
    
    MarriedKeyChain
  - encrypt
```
public void encrypt(KeyCrypter keyCrypter,
                    org.spongycastle.crypto.params.KeyParameter aesKey)
```
    Encrypt the keys in the group using the KeyCrypter and the AES key. A good default KeyCrypter to use is KeyCrypterScrypt.
    
    Throws:
    
    KeyCrypterException - Thrown if the wallet encryption fails for some reason, leaving the group unchanged.
    
    DeterministicUpgradeRequiredException - Thrown if there are random keys but no HD chain.
  - decrypt
```
public void decrypt(org.spongycastle.crypto.params.KeyParameter aesKey)
```
    Decrypt the keys in the group using the previously given key crypter and the AES key. A good default KeyCrypter to use is KeyCrypterScrypt.
    
    Throws:
    
    KeyCrypterException - Thrown if the wallet decryption fails for some reason, leaving the group unchanged.
  - isEncrypted
```
public boolean isEncrypted()
```
    Returns true if the group is encrypted.
  - isWatching
```
public boolean isWatching()
```
    Returns whether this chain has only watching keys (unencrypted keys with no private part). Mixed chains are forbidden.
    
    Throws:
    
    IllegalStateException - if there are no keys, or if there is a mix between watching and non-watching keys.
  - getKeyCrypter
```
@Nullable
public KeyCrypter getKeyCrypter()
```
    Returns the key crypter or null if the group is not encrypted.
  - getImportedKeys
```
public List<ECKey> getImportedKeys()
```
    Returns a list of the non-deterministic keys that have been imported into the wallet, or the empty list if none.
  - getEarliestKeyCreationTime
```
public long getEarliestKeyCreationTime()
```
  - getBloomFilterElementCount
```
public int getBloomFilterElementCount()
```
  - getBloomFilter
```
public BloomFilter getBloomFilter(int size,
                                  double falsePositiveRate,
                                  long nTweak)
```
  - isRequiringUpdateAllBloomFilter
```
public boolean isRequiringUpdateAllBloomFilter()
```
  - addEventListener
```
public void addEventListener(KeyChainEventListener listener)
```
    Adds a listener for events that are run when keys are added, on the user thread.
  - addEventListener
```
public void addEventListener(KeyChainEventListener listener,
                             Executor executor)
```
    Adds a listener for events that are run when keys are added, on the given executor.
  - removeEventListener
```
public boolean removeEventListener(KeyChainEventListener listener)
```
    Removes a listener for events that are run when keys are added.
  - serializeToProtobuf
```
public List<Protos.Key> serializeToProtobuf()
```
    Returns a list of key protobufs obtained by merging the chains.
  - fromProtobufUnencrypted
```
public static KeyChainGroup fromProtobufUnencrypted(NetworkParameters params,
                                                    List<Protos.Key> keys,
                                                    KeyChainFactory factory)
                                             throws UnreadableWalletException
```
    Throws:
    
    UnreadableWalletException
  - fromProtobufEncrypted
```
public static KeyChainGroup fromProtobufEncrypted(NetworkParameters params,
                                                  List<Protos.Key> keys,
                                                  KeyCrypter crypter,
                                                  KeyChainFactory factory)
                                           throws UnreadableWalletException
```
    Throws:
    
    UnreadableWalletException
  - upgradeToDeterministic
```
public DeterministicKeyChain upgradeToDeterministic(long keyRotationTimeSecs,
                                                    @Nullable
                                                    org.spongycastle.crypto.params.KeyParameter aesKey)
                                             throws DeterministicUpgradeRequiresPassword,
                                                    AllRandomKeysRotating
```
    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.
    
    IllegalArgumentException - if the rotation time specified excludes all keys.
    
    DeterministicUpgradeRequiresPassword - if the key chain group is encrypted and you should provide the users encryption key.
    
    AllRandomKeysRotating
  - isDeterministicUpgradeRequired
```
public boolean isDeterministicUpgradeRequired()
```
    Returns true if the group contains random keys but no HD chains.
  - toString
```
public String toString(boolean includePrivateKeys)
```
  - getDeterministicKeyChains
```
public List<DeterministicKeyChain> getDeterministicKeyChains()
```
    Returns a copy of the current list of chains.
  - getCombinedKeyLookaheadEpochs
```
public int getCombinedKeyLookaheadEpochs()
```
    Returns a counter that increases (by an arbitrary amount) each time new keys have been calculated due to lookahead and thus the Bloom filter that was previously calculated has become stale.

Class KeyChainGroup

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

chains

Constructor Detail

KeyChainGroup

KeyChainGroup

KeyChainGroup

Method Detail

createAndActivateNewHDChain

addAndActivateHDChain

currentKey

currentAddress

freshKey

freshKeys

freshAddress

getActiveKeyChain

setLookaheadSize

getLookaheadSize

setLookaheadThreshold

getLookaheadThreshold

importKeys

importKeys

checkPassword

checkAESKey

importKeysAndEncrypt

findRedeemDataFromScriptHash

markP2SHAddressAsUsed

findKeyFromPubHash

markPubKeyHashAsUsed

hasKey

findKeyFromPubKey

markPubKeyAsUsed

numKeys

removeImportedKey

isMarried

encrypt

decrypt

isEncrypted

isWatching

getKeyCrypter

getImportedKeys

getEarliestKeyCreationTime

getBloomFilterElementCount

getBloomFilter

isRequiringUpdateAllBloomFilter

addEventListener

addEventListener

removeEventListener

serializeToProtobuf

fromProtobufUnencrypted

fromProtobufEncrypted

upgradeToDeterministic

isDeterministicUpgradeRequired

toString

getDeterministicKeyChains

getCombinedKeyLookaheadEpochs