WalletAppKit (core 0.15 API)

java.lang.Object
- com.google.common.util.concurrent.AbstractIdleService
- - org.bitcoinj.kits.WalletAppKit

All Implemented Interfaces:

com.google.common.util.concurrent.Service
```
public class WalletAppKit
extends com.google.common.util.concurrent.AbstractIdleService
```
Utility class that wraps the boilerplate needed to set up a new SPV bitcoinj app. Instantiate it with a directory and file prefix, optionally configure a few things, then use startAsync and optionally awaitRunning. The object will construct and configure a BlockChain, SPVBlockStore, Wallet and PeerGroup. Depending on the value of the blockingStartup property, startup will be considered complete once the block chain has fully synchronized, so it can take a while.

To add listeners and modify the objects that are constructed, you can either do that by overriding the onSetupCompleted() method (which will run on a background thread) and make your changes there, or by waiting for the service to start and then accessing the objects from wherever you want. However, you cannot access the objects this class creates until startup is complete.

The asynchronous design of this class may seem puzzling (just use AbstractIdleService.awaitRunning() if you don't want that). It is to make it easier to fit bitcoinj into GUI apps, which require a high degree of responsiveness on their main thread which handles all the animation and user interaction. Even when blockingStart is false, initializing bitcoinj means doing potentially blocking file IO, generating keys and other potentially intensive operations. By running it on a background thread, there's no risk of accidentally causing UI lag.

Note that AbstractIdleService.awaitRunning() can throw an unchecked IllegalStateException if anything goes wrong during startup - you should probably handle it and use Throwable.getCause() to figure out what went wrong more precisely. Same thing if you just use the AbstractIdleService.startAsync() method.

Nested Class Summary
- Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
  com.google.common.util.concurrent.Service.Listener, com.google.common.util.concurrent.Service.State

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`autoStop`
`protected boolean`	`blockingStartup`
`protected java.io.InputStream`	`checkpoints`
`protected Context`	`context`
`protected java.io.File`	`directory`
`protected PeerDiscovery`	`discovery`
`protected DownloadProgressTracker`	`downloadListener`
`protected java.lang.String`	`filePrefix`
`protected static org.slf4j.Logger`	`log`
`protected NetworkParameters`	`params`
`protected PeerAddress[]`	`peerAddresses`
`protected Script.ScriptType`	`preferredOutputScriptType`
`protected DeterministicKey`	`restoreFromKey`
`protected DeterministicSeed`	`restoreFromSeed`
`protected KeyChainGroupStructure`	`structure`
`protected boolean`	`useAutoSave`
`protected java.lang.String`	`userAgent`
`protected BlockChain`	`vChain`
`protected java.lang.String`	`version`
`protected PeerGroup`	`vPeerGroup`
`protected BlockStore`	`vStore`
`protected Wallet`	`vWallet`
`protected java.io.File`	`vWalletFile`
`protected WalletProtobufSerializer.WalletFactory`	`walletFactory`

Constructor Summary

Constructors
Constructor and Description
`WalletAppKit(Context context, Script.ScriptType preferredOutputScriptType, KeyChainGroupStructure structure, java.io.File directory, java.lang.String filePrefix)` Creates a new WalletAppKit, with the given `Context`.
`WalletAppKit(NetworkParameters params, java.io.File directory, java.lang.String filePrefix)` Creates a new WalletAppKit, with a newly created `Context`.
`WalletAppKit(NetworkParameters params, Script.ScriptType preferredOutputScriptType, KeyChainGroupStructure structure, java.io.File directory, java.lang.String filePrefix)` Creates a new WalletAppKit, with a newly created `Context`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BlockChain`	`chain()`
`WalletAppKit`	`connectToLocalHost()` Will only connect to localhost.
`protected PeerGroup`	`createPeerGroup()`
`protected Wallet`	`createWallet()`
`java.io.File`	`directory()`
`boolean`	`isChainFileLocked()` Tests to see if the spvchain file has an operating system file lock on it.
`protected void`	`onSetupCompleted()` This method is invoked on a background thread after all objects are initialised, but before the peer group or block chain download is started.
`NetworkParameters`	`params()`
`PeerGroup`	`peerGroup()`
`protected BlockStore`	`provideBlockStore(java.io.File file)` Override this to use a `BlockStore` that isn't the default of `SPVBlockStore`.
`protected java.util.List<WalletExtension>`	`provideWalletExtensions()` Override this to return wallet extensions if any are necessary.
`WalletAppKit`	`restoreWalletFromKey(DeterministicKey accountKey)` If an account key is set here then any existing wallet that matches the file name will be renamed to a backup name, the chain file will be deleted, and the wallet object will be instantiated with the given key instead of a fresh seed being created.
`WalletAppKit`	`restoreWalletFromSeed(DeterministicSeed seed)` If a seed is set here then any existing wallet that matches the file name will be renamed to a backup name, the chain file will be deleted, and the wallet object will be instantiated with the given seed instead of a fresh one being created.
`WalletAppKit`	`setAutoSave(boolean value)` If true, the wallet will save itself to disk automatically whenever it changes.
`WalletAppKit`	`setAutoStop(boolean autoStop)` If true, will register a shutdown hook to stop the library.
`WalletAppKit`	`setBlockingStartup(boolean blockingStartup)` If true (the default) then the startup of this service won't be considered complete until the network has been brought up, peer connections established and the block chain synchronised.
`WalletAppKit`	`setCheckpoints(java.io.InputStream checkpoints)` If set, the file is expected to contain a checkpoints file calculated with BuildCheckpoints.
`WalletAppKit`	`setDiscovery(PeerDiscovery discovery)` Sets the peer discovery class to use.
`WalletAppKit`	`setDownloadListener(DownloadProgressTracker listener)` If you want to learn about the sync process, you can provide a listener here.
`WalletAppKit`	`setPeerNodes(PeerAddress... addresses)` Will only connect to the given addresses.
`protected void`	`setupAutoSave(Wallet wallet)`
`WalletAppKit`	`setUserAgent(java.lang.String userAgent, java.lang.String version)` Sets the string that will appear in the subver field of the version message.
`WalletAppKit`	`setWalletFactory(WalletProtobufSerializer.WalletFactory walletFactory)` Sets a wallet factory which will be used when the kit creates a new wallet.
`protected void`	`shutDown()`
`protected void`	`startUp()`
`BlockStore`	`store()`
`Wallet`	`wallet()`

Methods inherited from class com.google.common.util.concurrent.AbstractIdleService
addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, executor, failureCause, isRunning, serviceName, startAsync, state, stopAsync, toString

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

- Field Detail
  - log
```
protected static final org.slf4j.Logger log
```
  - params
```
protected final NetworkParameters params
```
  - preferredOutputScriptType
```
protected final Script.ScriptType preferredOutputScriptType
```
  - structure
```
protected final KeyChainGroupStructure structure
```
  - filePrefix
```
protected final java.lang.String filePrefix
```
  - vChain
```
protected volatile BlockChain vChain
```
  - vStore
```
protected volatile BlockStore vStore
```
  - vWallet
```
protected volatile Wallet vWallet
```
  - vPeerGroup
```
protected volatile PeerGroup vPeerGroup
```
  - directory
```
protected final java.io.File directory
```
  - vWalletFile
```
protected volatile java.io.File vWalletFile
```
  - useAutoSave
```
protected boolean useAutoSave
```
  - peerAddresses
```
protected PeerAddress[] peerAddresses
```
  - downloadListener
```
protected DownloadProgressTracker downloadListener
```
  - autoStop
```
protected boolean autoStop
```
  - checkpoints
```
protected java.io.InputStream checkpoints
```
  - blockingStartup
```
protected boolean blockingStartup
```
  - userAgent
```
protected java.lang.String userAgent
```
  - version
```
protected java.lang.String version
```
  - walletFactory
```
protected WalletProtobufSerializer.WalletFactory walletFactory
```
  - restoreFromSeed
```
@Nullable
protected DeterministicSeed restoreFromSeed
```
  - restoreFromKey
```
@Nullable
protected DeterministicKey restoreFromKey
```
  - discovery
```
@Nullable
protected PeerDiscovery discovery
```
  - context
```
protected volatile Context context
```
- Constructor Detail
  - WalletAppKit
```
public WalletAppKit(NetworkParameters params,
                    java.io.File directory,
                    java.lang.String filePrefix)
```
    Creates a new WalletAppKit, with a newly created Context. Files will be stored in the given directory.
  - WalletAppKit
```
public WalletAppKit(NetworkParameters params,
                    Script.ScriptType preferredOutputScriptType,
                    @Nullable
                    KeyChainGroupStructure structure,
                    java.io.File directory,
                    java.lang.String filePrefix)
```
    Creates a new WalletAppKit, with a newly created Context. Files will be stored in the given directory.
  - WalletAppKit
```
public WalletAppKit(Context context,
                    Script.ScriptType preferredOutputScriptType,
                    @Nullable
                    KeyChainGroupStructure structure,
                    java.io.File directory,
                    java.lang.String filePrefix)
```
    Creates a new WalletAppKit, with the given Context. Files will be stored in the given directory.
- Method Detail
  - setPeerNodes
```
public WalletAppKit setPeerNodes(PeerAddress... addresses)
```
    Will only connect to the given addresses. Cannot be called after startup.
  - connectToLocalHost
```
public WalletAppKit connectToLocalHost()
```
    Will only connect to localhost. Cannot be called after startup.
  - setAutoSave
```
public WalletAppKit setAutoSave(boolean value)
```
    If true, the wallet will save itself to disk automatically whenever it changes.
  - setDownloadListener
```
public WalletAppKit setDownloadListener(DownloadProgressTracker listener)
```
    If you want to learn about the sync process, you can provide a listener here. For instance, a DownloadProgressTracker is a good choice. This has no effect unless setBlockingStartup(false) has been called too, due to some missing implementation code.
  - setAutoStop
```
public WalletAppKit setAutoStop(boolean autoStop)
```
    If true, will register a shutdown hook to stop the library. Defaults to true.
  - setCheckpoints
```
public WalletAppKit setCheckpoints(java.io.InputStream checkpoints)
```
    If set, the file is expected to contain a checkpoints file calculated with BuildCheckpoints. It makes initial block sync faster for new users - please refer to the documentation on the bitcoinj website (https://bitcoinj.github.io/speeding-up-chain-sync) for further details.
  - setBlockingStartup
```
public WalletAppKit setBlockingStartup(boolean blockingStartup)
```
    If true (the default) then the startup of this service won't be considered complete until the network has been brought up, peer connections established and the block chain synchronised. Therefore AbstractIdleService.awaitRunning() can potentially take a very long time. If false, then startup is considered complete once the network activity begins and peer connections/block chain sync will continue in the background.
  - setUserAgent
```
public WalletAppKit setUserAgent(java.lang.String userAgent,
                                 java.lang.String version)
```
    Sets the string that will appear in the subver field of the version message.
    
    Parameters:
    
    userAgent - A short string that should be the name of your app, e.g. "My Wallet"
    
    version - A short string that contains the version number, e.g. "1.0-BETA"
  - setWalletFactory
```
public WalletAppKit setWalletFactory(WalletProtobufSerializer.WalletFactory walletFactory)
```
    Sets a wallet factory which will be used when the kit creates a new wallet.
  - restoreWalletFromSeed
```
public WalletAppKit restoreWalletFromSeed(DeterministicSeed seed)
```
    If a seed is set here then any existing wallet that matches the file name will be renamed to a backup name, the chain file will be deleted, and the wallet object will be instantiated with the given seed instead of a fresh one being created. This is intended for restoring a wallet from the original seed. To implement restore you would shut down the existing appkit, if any, then recreate it with the seed given by the user, then start up the new kit. The next time your app starts it should work as normal (that is, don't keep calling this each time).
  - restoreWalletFromKey
```
public WalletAppKit restoreWalletFromKey(DeterministicKey accountKey)
```
    If an account key is set here then any existing wallet that matches the file name will be renamed to a backup name, the chain file will be deleted, and the wallet object will be instantiated with the given key instead of a fresh seed being created. This is intended for restoring a wallet from an account key. To implement restore you would shut down the existing appkit, if any, then recreate it with the key given by the user, then start up the new kit. The next time your app starts it should work as normal (that is, don't keep calling this each time).
  - setDiscovery
```
public WalletAppKit setDiscovery(@Nullable
                                 PeerDiscovery discovery)
```
    Sets the peer discovery class to use. If none is provided then DNS is used, which is a reasonable default.
  - provideWalletExtensions
```
protected java.util.List<WalletExtension> provideWalletExtensions()
                                                           throws java.lang.Exception
```
    Override this to return wallet extensions if any are necessary.
    
    When this is called, chain(), store(), and peerGroup() will return the created objects, however they are not initialized/started.
    
    Throws:
    
    java.lang.Exception
  - provideBlockStore
```
protected BlockStore provideBlockStore(java.io.File file)
                                throws BlockStoreException
```
    Override this to use a BlockStore that isn't the default of SPVBlockStore.
    
    Throws:
    
    BlockStoreException
  - onSetupCompleted
```
protected void onSetupCompleted()
```
    This method is invoked on a background thread after all objects are initialised, but before the peer group or block chain download is started. You can tweak the objects configuration here.
  - isChainFileLocked
```
public boolean isChainFileLocked()
                          throws java.io.IOException
```
    Tests to see if the spvchain file has an operating system file lock on it. Useful for checking if your app is already running. If another copy of your app is running and you start the appkit anyway, an exception will be thrown during the startup process. Returns false if the chain file does not exist or is a directory.
    
    Throws:
    
    java.io.IOException
  - startUp
```
protected void startUp()
                throws java.lang.Exception
```
    Specified by:
    
    startUp in class com.google.common.util.concurrent.AbstractIdleService
    
    Throws:
    
    java.lang.Exception
  - setupAutoSave
```
protected void setupAutoSave(Wallet wallet)
```
  - createWallet
```
protected Wallet createWallet()
```
  - createPeerGroup
```
protected PeerGroup createPeerGroup()
                             throws java.util.concurrent.TimeoutException
```
    Throws:
    
    java.util.concurrent.TimeoutException
  - shutDown
```
protected void shutDown()
                 throws java.lang.Exception
```
    Specified by:
    
    shutDown in class com.google.common.util.concurrent.AbstractIdleService
    
    Throws:
    
    java.lang.Exception
  - params
```
public NetworkParameters params()
```
  - chain
```
public BlockChain chain()
```
  - store
```
public BlockStore store()
```
  - wallet
```
public Wallet wallet()
```
  - peerGroup
```
public PeerGroup peerGroup()
```
  - directory
```
public java.io.File directory()
```

Class WalletAppKit

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.google.common.util.concurrent.AbstractIdleService

Methods inherited from class java.lang.Object

Field Detail

log

params

preferredOutputScriptType

structure

filePrefix

vChain

vStore

vWallet

vPeerGroup

directory

vWalletFile

useAutoSave

peerAddresses

downloadListener

autoStop

checkpoints

blockingStartup

userAgent

version

walletFactory

restoreFromSeed

restoreFromKey

discovery

context

Constructor Detail

WalletAppKit

WalletAppKit

WalletAppKit

Method Detail

setPeerNodes

connectToLocalHost

setAutoSave

setDownloadListener

setAutoStop

setCheckpoints

setBlockingStartup

setUserAgent

setWalletFactory

restoreWalletFromSeed

restoreWalletFromKey

setDiscovery

provideWalletExtensions

provideBlockStore

onSetupCompleted

isChainFileLocked

startUp

setupAutoSave

createWallet

createPeerGroup

shutDown

params

chain

store

wallet

peerGroup

directory