com.google.bitcoin.core

Interface WalletEventListener

All Known Implementing Classes:

AbstractWalletEventListener, NativeWalletEventListener

public interface WalletEventListener

Implementors are called when the contents of the wallet changes, for instance due to receiving/sending money or a block chain re-organize. It may be convenient to derive from AbstractWalletEventListener instead.

Method Summary

Methods

Modifier and Type	Method and Description
void	onCoinsReceived(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) This is called when a transaction is seen that sends coins to this wallet, either because it was broadcast across the network or because a block was received.
void	onCoinsSent(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance) This is called when a transaction is seen that sends coins from this wallet, either because it was broadcast across the network or because a block was received.
void	onKeysAdded(Wallet wallet, List<ECKey> keys) Called whenever a new key is added to the wallet, whether that be via Wallet.addKeys(java.util.List) or due to some other automatic derivation.
void	onReorganize(Wallet wallet) This is called when a block is received that triggers a block chain re-organization.
void	onScriptsAdded(Wallet wallet, List<Script> scripts) Called whenever a new watched script is added to the wallet.
void	onTransactionConfidenceChanged(Wallet wallet, Transaction tx) Called when a transaction changes its confidence level.
void	onWalletChanged(Wallet wallet) Designed for GUI applications to refresh their transaction lists.

Method Detail

onCoinsReceived

void onCoinsReceived(Wallet wallet,
                   Transaction tx,
                   BigInteger prevBalance,
                   BigInteger newBalance)

This is called when a transaction is seen that sends coins to this wallet, either because it was broadcast across the network or because a block was received. If a transaction is seen when it was broadcast, onCoinsReceived won't be called again when a block containing it is received. If you want to know when such a transaction receives its first confirmation, register a TransactionConfidence event listener using the object retrieved via Transaction.getConfidence(). It's safe to modify the wallet in this callback, for example, by spending the transaction just received.

Parameters:

wallet - The wallet object that received the coins

tx - The transaction which sent us the coins.

prevBalance - Balance before the coins were received.

newBalance - Current balance of the wallet. This is the 'estimated' balance.

onCoinsSent

void onCoinsSent(Wallet wallet,
               Transaction tx,
               BigInteger prevBalance,
               BigInteger newBalance)

This is called when a transaction is seen that sends coins from this wallet, either because it was broadcast across the network or because a block was received. This may at first glance seem useless, because in the common case you already know about such transactions because you created them with the Wallets createSend/sendCoins methods. However when you have a wallet containing only keys, and you wish to replay the block chain to fill it with transactions, it's useful to find out when a transaction is discovered that sends coins from the wallet.

It's safe to modify the wallet from inside this callback, but if you're replaying the block chain you should be careful to avoid such modifications. Otherwise your changes may be overridden by new data from the chain.

Parameters:

wallet - The wallet object that this callback relates to (that sent the coins).

tx - The transaction that sent the coins to someone else.

prevBalance - The wallets balance before this transaction was seen.

newBalance - The wallets balance after this transaction was seen. This is the 'estimated' balance.

onReorganize

void onReorganize(Wallet wallet)

This is called when a block is received that triggers a block chain re-organization.

A re-organize means that the consensus (chain) of the network has diverged and now changed from what we believed it was previously. Usually this won't matter because the new consensus will include all our old transactions assuming we are playing by the rules. However it's theoretically possible for our balance to change in arbitrary ways, most likely, we could lose some money we thought we had.

It is safe to use methods of wallet whilst inside this callback.

onTransactionConfidenceChanged

void onTransactionConfidenceChanged(Wallet wallet,
                                  Transaction tx)

Called when a transaction changes its confidence level. You can also attach event listeners to the individual transactions, if you don't care about all of them. Usually you would save the wallet to disk after receiving this callback unless you already set up autosaving.

You should pay attention to this callback in case a transaction becomes dead, that is, a transaction you believed to be active (send or receive) becomes overridden by the network. This can happen if

1. You are sharing keys between wallets and accidentally create/broadcast a double spend.
2. Somebody is attacking the network and reversing transactions, ie, the user is a victim of fraud.
3. A bug: for example you create a transaction, broadcast it but fail to commit it. The Wallet will then re-use the same outputs when creating the next spend.

To find if the transaction is dead, you can use tx.getConfidence().getConfidenceType() == TransactionConfidence.ConfidenceType.DEAD. If it is, you should notify the user in some way so they know the thing they bought may not arrive/the thing they sold should not be dispatched.

Note that this callback will be invoked for every transaction in the wallet, for every new block that is received (because the depth has changed). If you want to update a UI view from the contents of the wallet it is more efficient to use onWalletChanged instead.

onWalletChanged

void onWalletChanged(Wallet wallet)

Designed for GUI applications to refresh their transaction lists. This callback is invoked in the following situations:

1. A new block is received (and thus building transactions got more confidence)
2. A pending transaction is received
3. A pending transaction changes confidence due to some non-new-block related event, such as being announced by more peers or by a double-spend conflict being observed.
4. A re-organize occurs. Call occurs only if the re-org modified any of our transactions.
5. A new spend is committed to the wallet

When this is called you can refresh the UI contents from the wallet contents. It's more efficient to use this rather than onTransactionConfidenceChanged() + onReorganize() because you only get one callback per block rather than one per transaction per block. Note that this is not called when a key is added.

onKeysAdded

void onKeysAdded(Wallet wallet,
               List<ECKey> keys)

Called whenever a new key is added to the wallet, whether that be via Wallet.addKeys(java.util.List) or due to some other automatic derivation.

onScriptsAdded

void onScriptsAdded(Wallet wallet,
                  List<Script> scripts)

Called whenever a new watched script is added to the wallet.