Replace WalletEventListener.onDeadTransaction with a generic confidence changed callb...
[elbandi:fedoracoinj.git] / src / com / google / bitcoin / core / WalletEventListener.java
1 /**
2  * Copyright 2011 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *    http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package com.google.bitcoin.core;
18
19 import java.math.BigInteger;
20
21 /**
22  * Implementing WalletEventListener allows you to learn when the contents of the wallet changes due to
23  * receiving money or a block chain re-organize. Methods are called with the event listener object locked so your
24  * implementation does not have to be thread safe. It may be convenient to derive from
25  * {@link AbstractWalletEventListener} instead.<p>
26  *
27  * It is safe to call methods of the wallet during event listener execution, and also for a listener to remove itself.
28  * Other types of modifications generally aren't safe.
29  */
30 public interface WalletEventListener {
31     /**
32      * This is called on a Peer thread when a transaction is seen that sends coins <b>to</b> this wallet, either because it
33      * was broadcast across the network or because a block was received. If a transaction is seen when it was broadcast,
34      * onCoinsReceived won't be called again when a block containing it is received. If you want to know when such a
35      * transaction receives its first confirmation, register a {@link TransactionConfidence} event listener using
36      * the object retrieved via {@link com.google.bitcoin.core.Transaction#getConfidence()}. It's safe to modify the
37      * wallet in this callback, for example, by spending the transaction just received.
38      *
39      * @param wallet      The wallet object that received the coins
40      * @param tx          The transaction which sent us the coins.
41      * @param prevBalance Balance before the coins were received.
42      * @param newBalance  Current balance of the wallet. This is the 'estimated' balance.
43      */
44     void onCoinsReceived(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance);
45
46     /**
47      * This is called on a Peer thread when a transaction is seen that sends coins <b>from</b> this wallet, either
48      * because it was broadcast across the network or because a block was received. This may at first glance seem 
49      * useless, because in the common case you already know about such transactions because you created them with
50      * the Wallets createSend/sendCoins methods. However when you have a wallet containing only keys, and you wish
51      * to replay the block chain to fill it with transactions, it's useful to find out when a transaction is discovered
52      * that sends coins from the wallet.<p>
53      *
54      * It's safe to modify the wallet from inside this callback, but if you're replaying the block chain you should
55      * be careful to avoid such modifications. Otherwise your changes may be overridden by new data from the chain.
56      *
57      * @param wallet       The wallet object that this callback relates to (that sent the coins).
58      * @param tx           The transaction that sent the coins to someone else.
59      * @param prevBalance  The wallets balance before this transaction was seen.
60      * @param newBalance   The wallets balance after this transaction was seen. This is the 'estimated' balance.
61      */
62     void onCoinsSent(Wallet wallet, Transaction tx, BigInteger prevBalance, BigInteger newBalance);
63
64     /**
65      * This is called on a Peer thread when a block is received that triggers a block chain re-organization.<p>
66      * <p/>
67      * A re-organize means that the consensus (chain) of the network has diverged and now changed from what we
68      * believed it was previously. Usually this won't matter because the new consensus will include all our old
69      * transactions assuming we are playing by the rules. However it's theoretically possible for our balance to
70      * change in arbitrary ways, most likely, we could lose some money we thought we had.<p>
71      * <p/>
72      * It is safe to use methods of wallet whilst inside this callback.
73      * <p/>
74      * TODO: Finish this interface.
75      */
76     void onReorganize(Wallet wallet);
77
78     // TODO: Flesh out the docs below some more to clarify what happens during re-orgs and other edge cases.
79     /**
80      * Called on a Peer thread when a transaction changes its confidence level. You can also attach event listeners to
81      * the individual transactions, if you don't care about all of them. Usually you would save the wallet to disk after
82      * receiving this callback.<p>
83      *
84      * You should pay attention to this callback in case a transaction becomes <i>dead</i>, that is, a transaction you
85      * believed to be active (send or receive) becomes overridden by the network. This can happen if<p>
86      *
87      * <ol>
88      *     <li>You are sharing keys between wallets and accidentally create/broadcast a double spend.</li>
89      *     <li>Somebody is attacking the network and reversing transactions, ie, the user is a victim of fraud.</li>
90      *     <li>A bug: for example you create a transaction, broadcast it but fail to commit it. The {@link Wallet}
91      *     will then re-use the same outputs when creating the next spend.</li>
92      * </ol><p>
93      *
94      * To find if the transaction is dead, you can use <tt>tx.getConfidence().getConfidenceType() ==
95      * TransactionConfidence.ConfidenceType.OVERRIDDEN_BY_DOUBLE_SPEND</tt>. If it is, you should notify the user
96      * in some way so they know the thing they bought may not arrive/the thing they sold should not be dispatched.
97      *
98      * @param wallet
99      * @param tx
100      */
101     void onTransactionConfidenceChanged(Wallet wallet, Transaction tx);
102 }