Replace WalletEventListener.onDeadTransaction with a generic confidence changed callb...
[elbandi:fedoracoinj.git] / src / com / google / bitcoin / core / Wallet.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 com.google.bitcoin.core.WalletTransaction.Pool;
20 import com.google.bitcoin.utils.EventListenerInvoker;
21 import org.slf4j.Logger;
22 import org.slf4j.LoggerFactory;
23
24 import java.io.*;
25 import java.math.BigInteger;
26 import java.util.*;
27 import java.util.concurrent.ExecutionException;
28
29 import static com.google.bitcoin.core.Utils.bitcoinValueToFriendlyString;
30
31 /**
32  * A Wallet stores keys and a record of transactions that have not yet been spent. Thus, it is capable of
33  * providing transactions on demand that meet a given combined value.<p>
34  * <p/>
35  * The Wallet is read and written from disk, so be sure to follow the Java serialization versioning rules here. We
36  * use the built in Java serialization to avoid the need to pull in a potentially large (code-size) third party
37  * serialization library.<p>
38  */
39 public class Wallet implements Serializable {
40     private static final Logger log = LoggerFactory.getLogger(Wallet.class);
41     private static final long serialVersionUID = 2L;
42
43     // Algorithm for movement of transactions between pools. Outbound tx = us spending coins. Inbound tx = us
44     // receiving coins. If a tx is both inbound and outbound (spend with change) it is considered outbound for the
45     // purposes of the explanation below.
46     //
47     // 1. Outbound tx is created by us: ->pending
48     // 2. Outbound tx that was broadcast is accepted into the main chain:
49     //     <-pending  and
50     //       If there is a change output  ->unspent
51     //       If there is no change output ->spent
52     // 3. Outbound tx that was broadcast is accepted into a side chain:
53     //     ->inactive  (remains in pending).
54     // 4. Inbound tx is accepted into the best chain:
55     //     ->unspent/spent
56     // 5. Inbound tx is accepted into a side chain:
57     //     ->inactive
58     //     Whilst it's also 'pending' in some sense, in that miners will probably try and incorporate it into the
59     //     best chain, we don't mark it as such here. It'll eventually show up after a re-org.
60     // 6. Outbound tx that is pending shares inputs with a tx that appears in the main chain:
61     //     <-pending ->dead
62     //
63     // Re-orgs:
64     // 1. Tx is present in old chain and not present in new chain
65     //       <-unspent/spent  ->pending
66     //       These newly inactive transactions will (if they are relevant to us) eventually come back via receive()
67     //       as miners resurrect them and re-include into the new best chain.
68     // 2. Tx is not present in old chain and is present in new chain
69     //       <-inactive  and  ->unspent/spent
70     // 3. Tx is present in new chain and shares inputs with a pending transaction, including those that were resurrected
71     //    due to point (1)
72     //       <-pending ->dead
73     //
74     // Balance:
75     // 1. Sum up all unspent outputs of the transactions in unspent.
76     // 2. Subtract the inputs of transactions in pending.
77     // 3. If requested, re-add the outputs of pending transactions that are mine. This is the estimated balance.
78
79     /**
80      * Map of txhash->Transactions that have not made it into the best chain yet. They are eligible to move there but
81      * are waiting for a miner to create a block on the best chain including them. These transactions inputs count as
82      * spent for the purposes of calculating our balance but their outputs are not available for spending yet. This
83      * means after a spend, our balance can actually go down temporarily before going up again! We should fix this to
84      * allow spending of pending transactions.
85      *
86      * Pending transactions get announced to peers when they first connect. This means that if we're currently offline,
87      * we can still create spends and upload them to the network later.
88      */
89     final Map<Sha256Hash, Transaction> pending;
90
91     /**
92      * Map of txhash->Transactions where the Transaction has unspent outputs. These are transactions we can use
93      * to pay other people and so count towards our balance. Transactions only appear in this map if they are part
94      * of the best chain. Transactions we have broacast that are not confirmed yet appear in pending even though they
95      * may have unspent "change" outputs.<p>
96      * <p/>
97      * Note: for now we will not allow spends of transactions that did not make it into the block chain. The code
98      * that handles this in BitCoin C++ is complicated. Satoshis code will not allow you to spend unconfirmed coins,
99      * however, it does seem to support dependency resolution entirely within the context of the memory pool so
100      * theoretically you could spend zero-conf coins and all of them would be included together. To simplify we'll
101      * make people wait but it would be a good improvement to resolve this in future.
102      */
103     final Map<Sha256Hash, Transaction> unspent;
104
105     /**
106      * Map of txhash->Transactions where the Transactions outputs are all fully spent. They are kept separately so
107      * the time to create a spend does not grow infinitely as wallets become more used. Some of these transactions
108      * may not have appeared in a block yet if they were created by us to spend coins and that spend is still being
109      * worked on by miners.<p>
110      * <p/>
111      * Transactions only appear in this map if they are part of the best chain.
112      */
113     final Map<Sha256Hash, Transaction> spent;
114
115     /**
116      * An inactive transaction is one that is seen only in a block that is not a part of the best chain. We keep it
117      * around in case a re-org promotes a different chain to be the best. In this case some (not necessarily all)
118      * inactive transactions will be moved out to unspent and spent, and some might be moved in.<p>
119      * <p/>
120      * Note that in the case where a transaction appears in both the best chain and a side chain as well, it is not
121      * placed in this map. It's an error for a transaction to be in both the inactive pool and unspent/spent.
122      */
123     private Map<Sha256Hash, Transaction> inactive;
124
125     /**
126      * A dead transaction is one that's been overridden by a double spend. Such a transaction is pending except it
127      * will never confirm and so should be presented to the user in some unique way - flashing red for example. This
128      * should nearly never happen in normal usage. Dead transactions can be "resurrected" by re-orgs just like any
129      * other. Dead transactions are not in the pending pool.
130      */
131     private Map<Sha256Hash, Transaction> dead;
132
133     /**
134      * A list of public/private EC keys owned by this user.
135      */
136     public final ArrayList<ECKey> keychain;
137
138     private final NetworkParameters params;
139
140     // Primitive kind of versioning protocol that does not break serializability. If this is true it means the
141     // Transaction objects in this wallet have confidence objects. If false (the default for old wallets missing
142     // this field) then we need to migrate.
143     private boolean hasTransactionConfidences;
144
145     transient private ArrayList<WalletEventListener> eventListeners;
146
147     /**
148      * Creates a new, empty wallet with no keys and no transactions. If you want to restore a wallet from disk instead,
149      * see loadFromFile.
150      */
151     public Wallet(NetworkParameters params) {
152         this.params = params;
153         keychain = new ArrayList<ECKey>();
154         unspent = new HashMap<Sha256Hash, Transaction>();
155         spent = new HashMap<Sha256Hash, Transaction>();
156         inactive = new HashMap<Sha256Hash, Transaction>();
157         pending = new HashMap<Sha256Hash, Transaction>();
158         dead = new HashMap<Sha256Hash, Transaction>();
159         eventListeners = new ArrayList<WalletEventListener>();
160         hasTransactionConfidences = true;
161     }
162     
163     public NetworkParameters getNetworkParameters() {
164         return params;
165     }
166
167     /**
168      * Returns a snapshot of the keychain. This view is not live.
169      */
170     public synchronized Iterable<ECKey> getKeys() {
171         return new ArrayList<ECKey>(keychain);
172     }
173
174     /**
175      * Uses Java serialization to save the wallet to the given file.
176      */
177     public synchronized void saveToFile(File f) throws IOException {
178         FileOutputStream stream = null;
179         try {
180             stream = new FileOutputStream(f);
181             saveToFileStream(stream);
182         } finally {
183             if (stream != null) stream.close();
184         }
185     }
186
187     /**
188      * Uses Java serialization to save the wallet to the given file stream.
189      */
190     public synchronized void saveToFileStream(OutputStream f) throws IOException {
191         ObjectOutputStream oos = new ObjectOutputStream(f);
192         oos.writeObject(this);
193         oos.close();
194     }
195
196     /** Returns the parameters this wallet was created with. */
197     public NetworkParameters getParams() {
198         return params;
199     }
200
201
202     /**
203      * Returns a wallet deserialized from the given file.
204      */
205     public static Wallet loadFromFile(File f) throws IOException {
206         return loadFromFileStream(new FileInputStream(f));
207     }
208     
209     private boolean isConsistent() {
210         // Pending and inactive can overlap, so merge them before counting
211         HashSet<Transaction> pendingInactive = new HashSet<Transaction>();
212         pendingInactive.addAll(pending.values());
213         pendingInactive.addAll(inactive.values());
214         
215         return getTransactions(true, true).size() ==
216                unspent.size() + spent.size() + pendingInactive.size() + dead.size();
217     }
218
219     /**
220      * Returns a wallet deserialized from the given input stream.
221      */
222     public static Wallet loadFromFileStream(InputStream f) throws IOException {
223         ObjectInputStream ois = null;
224         try {
225             ois = new ObjectInputStream(f);
226             return (Wallet) ois.readObject();
227         } catch (ClassNotFoundException e) {
228             throw new RuntimeException(e);
229         } finally {
230             if (ois != null) ois.close();
231         }
232     }
233
234     private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
235         in.defaultReadObject();
236         eventListeners = new ArrayList<WalletEventListener>();
237         maybeMigrateToTransactionConfidences();
238     }
239
240     /** Migrate old wallets that don't have any tx confidences, filling out whatever information we can. */
241     private void maybeMigrateToTransactionConfidences() {
242         if (hasTransactionConfidences) return;
243         // We can't fill out tx confidence objects exactly, we don't have enough data to do that. But we do the
244         // best we can.
245         List<Transaction> transactions = new LinkedList<Transaction>();
246         transactions.addAll(unspent.values());
247         transactions.addAll(spent.values());
248         for (Transaction tx : transactions) {
249             TransactionConfidence confidence = tx.getConfidence();
250             confidence.setConfidenceType(TransactionConfidence.ConfidenceType.BUILDING);
251             Set<StoredBlock> appearsIn = tx.appearsIn;
252             // appearsIn is being migrated away from, in favor of just storing the hashes instead of full blocks.
253             // TODO: Clear this code out once old wallets fade away.
254             if (appearsIn != null) {
255                 int minHeight = Integer.MAX_VALUE;
256                 for (StoredBlock block : appearsIn) {
257                     minHeight = Math.min(minHeight, block.getHeight());
258                 }
259                 confidence.setAppearedAtChainHeight(minHeight);
260             }
261         }
262         for (Transaction tx : pending.values()) {
263             tx.getConfidence().setConfidenceType(TransactionConfidence.ConfidenceType.NOT_SEEN_IN_CHAIN);
264         }
265         for (Transaction tx : inactive.values()) {
266             tx.getConfidence().setConfidenceType(TransactionConfidence.ConfidenceType.NOT_IN_BEST_CHAIN);
267         }
268         for (Transaction tx : dead.values()) {
269             tx.getConfidence().setConfidenceType(TransactionConfidence.ConfidenceType.OVERRIDDEN_BY_DOUBLE_SPEND);
270             // We'd ideally like to set overridingTransaction here, but old wallets don't have that data.
271             // Dead transactions in the wallet should be rare, so API users will just have to handle this
272             // edge case until old wallets have gone away.
273         }
274         hasTransactionConfidences = true;
275     }
276
277     /**
278      * Called by the {@link BlockChain} when we receive a new block that sends coins to one of our addresses or
279      * spends coins from one of our addresses (note that a single transaction can do both).<p>
280      *
281      * This is necessary for the internal book-keeping Wallet does. When a transaction is received that sends us
282      * coins it is added to a pool so we can use it later to create spends. When a transaction is received that
283      * consumes outputs they are marked as spent so they won't be used in future.<p>
284      *
285      * A transaction that spends our own coins can be received either because a spend we created was accepted by the
286      * network and thus made it into a block, or because our keys are being shared between multiple instances and
287      * some other node spent the coins instead. We still have to know about that to avoid accidentally trying to
288      * double spend.<p>
289      *
290      * A transaction may be received multiple times if is included into blocks in parallel chains. The blockType
291      * parameter describes whether the containing block is on the main/best chain or whether it's on a presently
292      * inactive side chain. We must still record these transactions and the blocks they appear in because a future
293      * block might change which chain is best causing a reorganize. A re-org can totally change our balance!
294      */
295     public synchronized void receiveFromBlock(Transaction tx, StoredBlock block,
296                                        BlockChain.NewBlockType blockType) throws VerificationException, ScriptException {
297         receive(tx, block, blockType, false);
298     }
299
300     /**
301      * Called when we have found a transaction (via network broadcast or otherwise) that is relevant to this wallet
302      * and want to record it. Note that we <b>cannot verify these transactions at all</b>, they may spend fictional
303      * coins or be otherwise invalid. They are useful to inform the user about coins they can expect to receive soon,
304      * and if you trust the sender of the transaction you can choose to assume they are in fact valid and will not
305      * be double spent as an optimization.
306      *
307      * @param tx
308      * @throws VerificationException
309      * @throws ScriptException
310      */
311     public synchronized void receivePending(Transaction tx) throws VerificationException, ScriptException {
312         // Can run in a peer thread.
313
314         // Ignore it if we already know about this transaction. Receiving a pending transaction never moves it
315         // between pools.
316         EnumSet<Pool> containingPools = getContainingPools(tx);
317         if (!containingPools.equals(EnumSet.noneOf(Pool.class))) {
318             log.info("Received tx we already saw in a block or created ourselves: " + tx.getHashAsString());
319             return;
320         }
321
322         // We only care about transactions that:
323         //   - Send us coins
324         //   - Spend our coins
325         if (!isTransactionRelevant(tx, true)) {
326             log.debug("Received tx that isn't relevant to this wallet, discarding.");
327             return;
328         }
329
330         BigInteger valueSentToMe = tx.getValueSentToMe(this);
331         BigInteger valueSentFromMe = tx.getValueSentFromMe(this);
332         if (log.isInfoEnabled()) {
333             log.info(String.format("Received a pending transaction %s that spends %s BTC from our own wallet," +
334                     " and sends us %s BTC", tx.getHashAsString(), Utils.bitcoinValueToFriendlyString(valueSentFromMe),
335                     Utils.bitcoinValueToFriendlyString(valueSentToMe)));
336         }
337
338         // Mark the tx as having been seen but is not yet in the chain. This will normally have been done already by
339         // the Peer before we got to this point, but in some cases (unit tests, other sources of transactions) it may
340         // have been missed out.
341         TransactionConfidence.ConfidenceType currentConfidence = tx.getConfidence().getConfidenceType();
342         if (currentConfidence == TransactionConfidence.ConfidenceType.UNKNOWN) {
343             tx.getConfidence().setConfidenceType(TransactionConfidence.ConfidenceType.NOT_SEEN_IN_CHAIN);
344             invokeOnTransactionConfidenceChanged(tx);
345         }
346
347         BigInteger balance = getBalance();
348
349         // If this tx spends any of our unspent outputs, mark them as spent now, then add to the pending pool. This
350         // ensures that if some other client that has our keys broadcasts a spend we stay in sync. Also updates the
351         // timestamp on the transaction.
352         commitTx(tx);
353
354         // Event listeners may re-enter so we cannot make assumptions about wallet state after this loop completes.
355         BigInteger newBalance = balance.add(valueSentToMe).subtract(valueSentFromMe);
356         if (valueSentToMe.compareTo(BigInteger.ZERO) > 0)
357             invokeOnCoinsReceived(tx, balance, newBalance);
358         if (valueSentFromMe.compareTo(BigInteger.ZERO) > 0)
359             invokeOnCoinsSent(tx, balance, newBalance);
360     }
361
362     // Boilerplate that allows event listeners to delete themselves during execution, and auto locks the listener.
363     private void invokeOnCoinsReceived(final Transaction tx, final BigInteger balance, final BigInteger newBalance) {
364         EventListenerInvoker.invoke(eventListeners, new EventListenerInvoker<WalletEventListener>() {
365             @Override public void invoke(WalletEventListener listener) {
366                 listener.onCoinsReceived(Wallet.this, tx, balance, newBalance);
367             }
368         });
369     }
370
371     private void invokeOnCoinsSent(final Transaction tx, final BigInteger prevBalance, final BigInteger newBalance) {
372         EventListenerInvoker.invoke(eventListeners, new EventListenerInvoker<WalletEventListener>() {
373             @Override public void invoke(WalletEventListener listener) {
374                 listener.onCoinsSent(Wallet.this, tx, prevBalance, newBalance);
375             }
376         });
377     }
378
379     /**
380      * Returns true if the given transaction sends coins to any of our keys, or has inputs spending any of our outputs,
381      * and if includeDoubleSpending is true, also returns true if tx has inputs that are spending outputs which are
382      * not ours but which are spent by pending transactions.<p>
383      *
384      * Note that if the tx has inputs containing one of our keys, but the connected transaction is not in the wallet,
385      * it will not be considered relevant.
386      */
387     public synchronized boolean isTransactionRelevant(Transaction tx,
388                                                       boolean includeDoubleSpending) throws ScriptException {
389         return tx.getValueSentFromMe(this).compareTo(BigInteger.ZERO) > 0 ||
390                tx.getValueSentToMe(this).compareTo(BigInteger.ZERO) > 0 ||
391                (includeDoubleSpending && (findDoubleSpendAgainstPending(tx) != null));
392     }
393
394     /**
395      * Checks if "tx" is spending any inputs of pending transactions. Not a general check, but it can work even if
396      * the double spent inputs are not ours. Returns the pending tx that was double spent or null if none found.
397      */
398     private Transaction findDoubleSpendAgainstPending(Transaction tx) {
399         // Compile a set of outpoints that are spent by tx.
400         HashSet<TransactionOutPoint> outpoints = new HashSet<TransactionOutPoint>();
401         for (TransactionInput input : tx.getInputs()) {
402             outpoints.add(input.getOutpoint());
403         }
404         // Now for each pending transaction, see if it shares any outpoints with this tx.
405         for (Transaction p : pending.values()) {
406             for (TransactionInput input : p.getInputs()) {
407                 if (outpoints.contains(input.getOutpoint())) {
408                     // It does, it's a double spend against the pending pool, which makes it relevant.
409                     return p;
410                 }
411             }
412         }
413         return null;
414     }
415
416     private synchronized void receive(Transaction tx, StoredBlock block,
417                                       BlockChain.NewBlockType blockType,
418                                       boolean reorg) throws VerificationException, ScriptException {
419         // Runs in a peer thread.
420         BigInteger prevBalance = getBalance();
421
422         Sha256Hash txHash = tx.getHash();
423
424         boolean bestChain = blockType == BlockChain.NewBlockType.BEST_CHAIN;
425         boolean sideChain = blockType == BlockChain.NewBlockType.SIDE_CHAIN;
426
427         BigInteger valueSentFromMe = tx.getValueSentFromMe(this);
428         BigInteger valueSentToMe = tx.getValueSentToMe(this);
429         BigInteger valueDifference = valueSentToMe.subtract(valueSentFromMe);
430
431         if (!reorg) {
432             log.info("Received tx{} for {} BTC: {}", new Object[]{sideChain ? " on a side chain" : "",
433                     bitcoinValueToFriendlyString(valueDifference), tx.getHashAsString()});
434         }
435
436         // If this transaction is already in the wallet we may need to move it into a different pool. At the very
437         // least we need to ensure we're manipulating the canonical object rather than a duplicate.
438         Transaction wtx;
439         if ((wtx = pending.remove(txHash)) != null) {
440             // Make sure "tx" is always the canonical object we want to manipulate, send to event handlers, etc.
441             tx = wtx;
442
443             log.info("  <-pending");
444             // A transaction we created appeared in a block. Probably this is a spend we broadcast that has been
445             // accepted by the network.
446             //
447             if (bestChain) {
448                 if (valueSentToMe.equals(BigInteger.ZERO)) {
449                     // There were no change transactions so this tx is fully spent.
450                     log.info("  ->spent");
451                     boolean alreadyPresent = spent.put(tx.getHash(), tx) != null;
452                     assert !alreadyPresent : "TX in both pending and spent pools";
453                 } else {
454                     // There was change back to us, or this tx was purely a spend back to ourselves (perhaps for
455                     // anonymization purposes).
456                     log.info("  ->unspent");
457                     boolean alreadyPresent = unspent.put(tx.getHash(), tx) != null;
458                     assert !alreadyPresent : "TX in both pending and unspent pools";
459                 }
460             } else if (sideChain) {
461                 // The transaction was accepted on an inactive side chain, but not yet by the best chain.
462                 log.info("  ->inactive");
463                 // It's OK for this to already be in the inactive pool because there can be multiple independent side
464                 // chains in which it appears:
465                 //
466                 //     b1 --> b2
467                 //        \-> b3
468                 //        \-> b4 (at this point it's already present in 'inactive'
469                 boolean alreadyPresent = inactive.put(tx.getHash(), tx) != null;
470                 if (alreadyPresent)
471                     log.info("Saw a transaction be incorporated into multiple independent side chains");
472                 // Put it back into the pending pool, because 'pending' means 'waiting to be included in best chain'.
473                 pending.put(tx.getHash(), tx);
474             }
475         } else {
476             // This TX didn't originate with us. It could be sending us coins and also spending our own coins if keys
477             // are being shared between different wallets.
478             if (sideChain) {
479                 log.info("  ->inactive");
480                 inactive.put(tx.getHash(), tx);
481             } else if (bestChain) {
482                 // This can trigger tx confidence listeners to be run in the case of double spends. We may need to
483                 // delay the execution of the listeners until the bottom to avoid the wallet mutating during updates.
484                 processTxFromBestChain(tx);
485             }
486         }
487
488         log.info("Balance is now: " + bitcoinValueToFriendlyString(getBalance()));
489
490         // WARNING: The code beyond this point can trigger event listeners on transaction confidence objects, which are
491         // in turn allowed to re-enter the Wallet. This means we cannot assume anything about the state of the wallet
492         // from now on. The balance just received may already be spent.
493
494         // Mark the tx as appearing in this block so we can find it later after a re-org. This also lets the
495         // transaction update its confidence and timestamp bookkeeping data.
496         if (block != null) {
497             tx.setBlockAppearance(block, bestChain);
498             invokeOnTransactionConfidenceChanged(tx);
499         }
500
501         // Inform anyone interested that we have received or sent coins but only if:
502         //  - This is not due to a re-org.
503         //  - The coins appeared on the best chain.
504         //  - We did in fact receive some new money.
505         //  - We have not already informed the user about the coins when we received the tx broadcast, or for our
506         //    own spends. If users want to know when a broadcast tx becomes confirmed, they need to use tx confidence
507         //    listeners.
508         //
509         // TODO: Decide whether to run the event listeners, if a tx confidence listener already modified the wallet.
510         boolean wasPending = wtx != null;
511         if (!reorg && bestChain && !wasPending) {
512             BigInteger newBalance = getBalance();
513             if (valueSentToMe.compareTo(BigInteger.ZERO) > 0) {
514                 invokeOnCoinsReceived(tx, prevBalance, newBalance);
515             }
516             if (valueSentFromMe.compareTo(BigInteger.ZERO) > 0) {
517                 invokeOnCoinsSent(tx, prevBalance, newBalance);
518             }
519         }
520         
521         assert isConsistent();
522     }
523
524     /**
525      * Handle when a transaction becomes newly active on the best chain, either due to receiving a new block or a
526      * re-org making inactive transactions active.
527      */
528     private void processTxFromBestChain(Transaction tx) throws VerificationException, ScriptException {
529         // This TX may spend our existing outputs even though it was not pending. This can happen in unit
530         // tests, if keys are moved between wallets, and if we're catching up to the chain given only a set of keys.
531         updateForSpends(tx, true);
532         if (!tx.getValueSentToMe(this).equals(BigInteger.ZERO)) {
533             // It's sending us coins.
534             log.info("  new tx ->unspent");
535             boolean alreadyPresent = unspent.put(tx.getHash(), tx) != null;
536             assert !alreadyPresent : "TX was received twice";
537         } else if (!tx.getValueSentFromMe(this).equals(BigInteger.ZERO)) {
538             // It spent some of our coins and did not send us any.
539             log.info("  new tx ->spent");
540             boolean alreadyPresent = spent.put(tx.getHash(), tx) != null;
541             assert !alreadyPresent : "TX was received twice";
542         } else {
543             // It didn't send us coins nor spend any of our coins. If we're processing it, that must be because it
544             // spends outpoints that are also spent by some pending transactions - maybe a double spend of somebody
545             // elses coins that were originally sent to us? ie, this might be a Finney attack where we think we
546             // received some money and then the sender co-operated with a miner to take back the coins, using a tx
547             // that isn't involving our keys at all.
548             Transaction doubleSpend = findDoubleSpendAgainstPending(tx);
549             if (doubleSpend == null)
550                 throw new IllegalStateException("Received an irrelevant tx that was not a double spend.");
551             // This is mostly the same as the codepath in updateForSpends, but that one is only triggered when
552             // the transaction being double spent is actually in our wallet (ie, maybe we're double spending).
553             log.warn("Saw double spend from chain override pending tx {}", doubleSpend.getHashAsString());
554             log.warn("  <-pending ->dead");
555             pending.remove(doubleSpend.getHash());
556             dead.put(doubleSpend.getHash(), doubleSpend);
557             // Inform the event listeners of the newly dead tx.
558             doubleSpend.getConfidence().setOverridingTransaction(tx);
559             invokeOnTransactionConfidenceChanged(doubleSpend);
560         }
561     }
562
563     /**
564      * Updates the wallet by checking if this TX spends any of our outputs, and marking them as spent if so. It can
565      * be called in two contexts. One is when we receive a transaction on the best chain but it wasn't pending, this
566      * most commonly happens when we have a set of keys but the wallet transactions were wiped and we are catching up
567      * with the block chain. It can also happen if a block includes a transaction we never saw at broadcast time.
568      * If this tx double spends, it takes precedence over our pending transactions and the pending tx goes dead.
569      *
570      * The other context it can be called is from {@link Wallet#receivePending(Transaction)} ie we saw a tx be
571      * broadcast or one was submitted directly that spends our own coins. If this tx double spends it does NOT take
572      * precedence because the winner will be resolved by the miners - we assume that our version will win,
573      * if we are wrong then when a block appears the tx will go dead.
574      */
575     private void updateForSpends(Transaction tx, boolean fromChain) throws VerificationException {
576         // tx is on the best chain by this point.
577         List<TransactionInput> inputs = tx.getInputs();
578         for (int i = 0; i < inputs.size(); i++) {
579             TransactionInput input = inputs.get(i);
580             TransactionInput.ConnectionResult result = input.connect(unspent, false);
581             if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
582                 // Not found in the unspent map. Try again with the spent map.
583                 result = input.connect(spent, false);
584                 if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
585                     // Doesn't spend any of our outputs or is coinbase.
586                     continue;
587                 }
588             }
589
590             if (result == TransactionInput.ConnectionResult.ALREADY_SPENT) {
591                 // Double spend! Work backwards like so:
592                 //
593                 //   A  -> spent by B [pending]
594                 //     \-> spent by C [chain]
595                 Transaction doubleSpent = input.getOutpoint().fromTx;   // == A
596                 assert doubleSpent != null;
597                 int index = (int) input.getOutpoint().getIndex();
598                 TransactionOutput output = doubleSpent.getOutputs().get(index);
599                 TransactionInput spentBy = output.getSpentBy();
600                 assert spentBy != null;
601                 Transaction connected = spentBy.getParentTransaction();
602                 assert connected != null;
603                 if (fromChain) {
604                     // This must have overridden a pending tx, or the block is bad (contains transactions
605                     // that illegally double spend: should never occur if we are connected to an honest node).
606                     if (pending.containsKey(connected.getHash())) {
607                         log.warn("Saw double spend from chain override pending tx {}", connected.getHashAsString());
608                         log.warn("  <-pending ->dead");
609                         pending.remove(connected.getHash());
610                         dead.put(connected.getHash(), connected);
611                         // Now forcibly change the connection.
612                         input.connect(unspent, true);
613                         // Inform the [tx] event listeners of the newly dead tx. This sets confidence type also.
614                         connected.getConfidence().setOverridingTransaction(tx);
615                         invokeOnTransactionConfidenceChanged(connected);
616                     }
617                 } else {
618                     // A pending transaction that tried to double spend our coins - we log and ignore it, because either
619                     // 1) The double-spent tx is confirmed and thus this tx has no effect .... or
620                     // 2) Both txns are pending, neither has priority. Miners will decide in a few minutes which won.
621                     log.warn("Saw double spend from another pending transaction, ignoring tx {}",
622                              tx.getHashAsString());
623                     log.warn("  offending input is input {}", i);
624                     return;
625                 }
626             } else if (result == TransactionInput.ConnectionResult.SUCCESS) {
627                 // Otherwise we saw a transaction spend our coins, but we didn't try and spend them ourselves yet.
628                 // The outputs are already marked as spent by the connect call above, so check if there are any more for
629                 // us to use. Move if not.
630                 Transaction connected = input.getOutpoint().fromTx;
631                 maybeMoveTxToSpent(connected, "prevtx");
632             }
633         }
634     }
635
636     /**
637      * If the transactions outputs are all marked as spent, and it's in the unspent map, move it.
638      */
639     private void maybeMoveTxToSpent(Transaction tx, String context) {
640         if (tx.isEveryOwnedOutputSpent(this)) {
641             // There's nothing left I can spend in this transaction.
642             if (unspent.remove(tx.getHash()) != null) {
643                 if (log.isInfoEnabled()) {
644                     log.info("  " + context + " <-unspent");
645                     log.info("  " + context + " ->spent");
646                 }
647                 spent.put(tx.getHash(), tx);
648             }
649         }
650     }
651
652     /**
653      * Adds an event listener object. Methods on this object are called when something interesting happens,
654      * like receiving money.<p>
655      * <p/>
656      * Threading: Event listener methods are dispatched on library provided threads and the both the wallet and the
657      * listener objects are locked during dispatch, so your listeners do not have to be thread safe. However they
658      * should not block as the Peer will be unresponsive to network traffic whilst your listener is running.
659      */
660     public synchronized void addEventListener(WalletEventListener listener) {
661         eventListeners.add(listener);
662     }
663
664     /**
665      * Removes the given event listener object. Returns true if the listener was removed,
666      * false if that listener was never added.
667      */
668     public synchronized boolean removeEventListener(WalletEventListener listener) {
669         return eventListeners.remove(listener);
670     }
671
672     /**
673      * Updates the wallet with the given transaction: puts it into the pending pool and sets the spent flags. Used in
674      * two situations:<p>
675      *
676      * <ol>
677      *     <li>When we have just successfully transmitted the tx we created to the network.</li>
678      *     <li>When we receive a pending transaction that didn't appear in the chain yet,
679      *         and we did not create it, and it spends some of our outputs.</li>
680      * </ol>
681      */
682     public synchronized void commitTx(Transaction tx) throws VerificationException {
683         assert !pending.containsKey(tx.getHash()) : "commitTx called on the same transaction twice";
684         log.info("commitTx of {}", tx.getHashAsString());
685         tx.updatedAt = Utils.now();
686         // Mark the outputs we're spending as spent so we won't try and use them in future creations. This will also
687         // move any transactions that are now fully spent to the spent map so we can skip them when creating future
688         // spends.
689         updateForSpends(tx, false);
690         // Add to the pending pool. It'll be moved out once we receive this transaction on the best chain.
691         log.info("->pending: {}", tx.getHashAsString());
692         pending.put(tx.getHash(), tx);
693         
694         assert isConsistent();
695     }
696
697     /**
698      * Returns a set of all transactions in the wallet.
699      *
700      * @param includeDead     If true, transactions that were overridden by a double spend are included.
701      * @param includeInactive If true, transactions that are on side chains (are unspendable) are included.
702      */
703     public synchronized Set<Transaction> getTransactions(boolean includeDead, boolean includeInactive) {
704         Set<Transaction> all = new HashSet<Transaction>();
705         all.addAll(unspent.values());
706         all.addAll(spent.values());
707         all.addAll(pending.values());
708         if (includeDead)
709             all.addAll(dead.values());
710         if (includeInactive)
711             all.addAll(inactive.values());
712         return all;
713     }
714
715     /**
716      * Returns a set of all WalletTransactions in the wallet.
717      */
718     public synchronized Iterable<WalletTransaction> getWalletTransactions() {
719         HashSet<Transaction> pendingInactive = new HashSet<Transaction>();
720         pendingInactive.addAll(pending.values());
721         pendingInactive.retainAll(inactive.values());
722         HashSet<Transaction> onlyPending = new HashSet<Transaction>();
723         HashSet<Transaction> onlyInactive = new HashSet<Transaction>();
724         onlyPending.addAll(pending.values());
725         onlyPending.removeAll(pendingInactive);
726         onlyInactive.addAll(inactive.values());
727         onlyInactive.removeAll(pendingInactive);
728         
729         Set<WalletTransaction> all = new HashSet<WalletTransaction>();
730
731         addWalletTransactionsToSet(all, Pool.UNSPENT, unspent.values());
732         addWalletTransactionsToSet(all, Pool.SPENT, spent.values());
733         addWalletTransactionsToSet(all, Pool.DEAD, dead.values());
734         addWalletTransactionsToSet(all, Pool.PENDING, onlyPending);
735         addWalletTransactionsToSet(all, Pool.INACTIVE, onlyInactive);
736         addWalletTransactionsToSet(all, Pool.PENDING_INACTIVE, pendingInactive);
737         return all;
738     }
739
740     private static synchronized void addWalletTransactionsToSet(Set<WalletTransaction> txs,
741             Pool poolType, Collection<Transaction> pool) {
742         for (Transaction tx : pool) {
743             txs.add(new WalletTransaction(poolType, tx));
744         }
745     }
746     
747     public synchronized void addWalletTransaction(WalletTransaction wtx) {
748         switch (wtx.getPool()) {
749         case UNSPENT:
750             unspent.put(wtx.getTransaction().getHash(), wtx.getTransaction());
751             break;
752         case SPENT:
753             spent.put(wtx.getTransaction().getHash(), wtx.getTransaction());
754             break;
755         case PENDING:
756             pending.put(wtx.getTransaction().getHash(), wtx.getTransaction());
757             break;
758         case DEAD:
759             dead.put(wtx.getTransaction().getHash(), wtx.getTransaction());
760             break;
761         case INACTIVE:
762             inactive.put(wtx.getTransaction().getHash(), wtx.getTransaction());
763             break;
764         case PENDING_INACTIVE:
765             pending.put(wtx.getTransaction().getHash(), wtx.getTransaction());
766             inactive.put(wtx.getTransaction().getHash(), wtx.getTransaction());
767             break;
768         default:
769             throw new RuntimeException("Unknown wallet transaction type " + wtx.getPool());
770         }
771     }
772
773     /**
774      * Returns all non-dead, active transactions ordered by recency.
775      */
776     public List<Transaction> getTransactionsByTime() {
777         return getRecentTransactions(0, false);
778     }
779
780     /**
781      * Returns an list of N transactions, ordered by increasing age. Transactions on side chains are not included.
782      * Dead transactions (overridden by double spends) are optionally included. <p>
783      * <p/>
784      * Note: the current implementation is O(num transactions in wallet). Regardless of how many transactions are
785      * requested, the cost is always the same. In future, requesting smaller numbers of transactions may be faster
786      * depending on how the wallet is implemented (eg if backed by a database).
787      */
788     public synchronized List<Transaction> getRecentTransactions(int numTransactions, boolean includeDead) {
789         assert numTransactions >= 0;
790         // Firstly, put all transactions into an array.
791         int size = getPoolSize(WalletTransaction.Pool.UNSPENT) +
792                 getPoolSize(WalletTransaction.Pool.SPENT) +
793                 getPoolSize(WalletTransaction.Pool.PENDING);
794         if (numTransactions > size || numTransactions == 0) {
795             numTransactions = size;
796         }
797         ArrayList<Transaction> all = new ArrayList<Transaction>(getTransactions(includeDead, false));
798         // Order by date.
799         Collections.sort(all, Collections.reverseOrder(new Comparator<Transaction>() {
800             public int compare(Transaction t1, Transaction t2) {
801                 return t1.getUpdateTime().compareTo(t2.getUpdateTime());
802             }
803         }));
804         if (numTransactions == all.size()) {
805             return all;
806         } else {
807             all.subList(numTransactions, all.size()).clear();
808             return all;
809         }
810     }
811
812     /**
813      * Returns a transaction object given its hash, if it exists in this wallet, or null otherwise.
814      */
815     public synchronized Transaction getTransaction(Sha256Hash hash) {
816         Transaction tx;
817         if ((tx = pending.get(hash)) != null)
818             return tx;
819         else if ((tx = unspent.get(hash)) != null)
820             return tx;
821         else if ((tx = spent.get(hash)) != null)
822             return tx;
823         else if ((tx = inactive.get(hash)) != null)
824             return tx;
825         else if ((tx = dead.get(hash)) != null)
826             return tx;
827         return null;
828     }
829
830     /**
831      * Deletes transactions which appeared above the given block height from the wallet, but does not touch the keys.
832      * This is useful if you have some keys and wish to replay the block chain into the wallet in order to pick them up.
833      */
834     public synchronized void clearTransactions(int fromHeight) {
835         if (fromHeight == 0) {
836             unspent.clear();
837             spent.clear();
838             pending.clear();
839             inactive.clear();
840             dead.clear();
841         } else {
842             throw new UnsupportedOperationException();
843         }
844     }
845
846     synchronized EnumSet<Pool> getContainingPools(Transaction tx) {
847         EnumSet<Pool> result = EnumSet.noneOf(Pool.class);
848         Sha256Hash txHash = tx.getHash();
849         if (unspent.containsKey(txHash)) {
850             result.add(Pool.UNSPENT);
851         }
852         if (spent.containsKey(txHash)) {
853             result.add(Pool.SPENT);
854         }
855         if (pending.containsKey(txHash)) {
856             result.add(Pool.PENDING);
857         }
858         if (inactive.containsKey(txHash)) {
859             result.add(Pool.INACTIVE);
860         }
861         if (dead.containsKey(txHash)) {
862             result.add(Pool.DEAD);
863         }
864         return result;
865     }
866
867     synchronized int getPoolSize(WalletTransaction.Pool pool) {
868         switch (pool) {
869             case UNSPENT:
870                 return unspent.size();
871             case SPENT:
872                 return spent.size();
873             case PENDING:
874                 return pending.size();
875             case INACTIVE:
876                 return inactive.size();
877             case DEAD:
878                 return dead.size();
879             case ALL:
880                 return unspent.size() + spent.size() + pending.size() + inactive.size() + dead.size();
881         }
882         throw new RuntimeException("Unreachable");
883     }
884
885     /**
886      * Statelessly creates a transaction that sends the given number of nanocoins to address. The change is sent to
887      * {@link Wallet#getChangeAddress()}, so you must have added at least one key.<p>
888      * <p/>
889      * This method is stateless in the sense that calling it twice with the same inputs will result in two
890      * Transaction objects which are equal. The wallet is not updated to track its pending status or to mark the
891      * coins as spent until commitTx is called on the result.
892      */
893     public synchronized Transaction createSend(Address address, BigInteger nanocoins) {
894         return createSend(address, nanocoins, getChangeAddress());
895     }
896
897     /**
898      * Sends coins to the given address but does not broadcast the resulting pending transaction. It is still stored
899      * in the wallet, so when the wallet is added to a {@link PeerGroup} or {@link Peer} the transaction will be
900      * announced to the network.
901      *
902      * @param to Address to send the coins to.
903      * @param nanocoins How many coins to send.
904      * @return the Transaction that was created, or null if there are insufficient coins in thew allet.
905      */
906     public synchronized Transaction sendCoinsOffline(Address to, BigInteger nanocoins) {
907         Transaction tx = createSend(to, nanocoins);
908         if (tx == null)   // Not enough money! :-(
909             return null;
910         try {
911             commitTx(tx);
912         } catch (VerificationException e) {
913             throw new RuntimeException(e);  // Cannot happen unless there's a bug, as we just created this ourselves.
914         }
915         return tx;
916     }
917
918     /**
919      * Sends coins to the given address, via the given {@link PeerGroup}. Change is returned to {@link Wallet#getChangeAddress()}.
920      * The transaction will be announced to any connected nodes asynchronously. If you would like to know when
921      * the transaction was successfully sent to at least one node, use 
922      * {@link Wallet#sendCoinsOffline(Address, java.math.BigInteger)} and then {@link PeerGroup#broadcastTransaction(Transaction)}
923      * on the result to obtain a {@link java.util.concurrent.Future<Transaction>}.
924      *
925      * @param peerGroup a PeerGroup to use for broadcast.
926      * @param to        Which address to send coins to.
927      * @param nanocoins How many nanocoins to send. You can use Utils.toNanoCoins() to calculate this.
928      * @return the Transaction
929      * @throws IOException if there was a problem broadcasting the transaction
930      */
931     public synchronized Transaction sendCoinsAsync(PeerGroup peerGroup, Address to, BigInteger nanocoins) throws IOException {
932         Transaction tx = sendCoinsOffline(to, nanocoins);
933         if (tx == null)
934             return null;  // Not enough money.
935         // Just throw away the Future here. If the user wants it, they can call sendCoinsOffline/broadcastTransaction
936         // themselves.
937         peerGroup.broadcastTransaction(tx);
938         return tx;
939     }
940
941     /**
942      * Sends coins to the given address, via the given {@link PeerGroup}. Change is returned to {@link Wallet#getChangeAddress()}.
943      * The method will block until the transaction has been announced to at least one node.
944      *
945      * @param peerGroup a PeerGroup to use for broadcast or null.
946      * @param to        Which address to send coins to.
947      * @param nanocoins How many nanocoins to send. You can use Utils.toNanoCoins() to calculate this.
948      * @return The {@link Transaction} that was created or null if there was insufficient balance to send the coins.
949      */
950     public synchronized Transaction sendCoins(PeerGroup peerGroup, Address to, BigInteger nanocoins) {
951         Transaction tx = sendCoinsOffline(to, nanocoins);
952         if (tx == null)
953             return null;  // Not enough money.
954         try {
955             return peerGroup.broadcastTransaction(tx).get();
956         } catch (InterruptedException e) {
957             throw new RuntimeException(e);
958         } catch (ExecutionException e) {
959             throw new RuntimeException(e);
960         }
961     }
962
963     /**
964      * Sends coins to the given address, via the given {@link Peer}. Change is returned to {@link Wallet#getChangeAddress()}.
965      * If an exception is thrown by {@link Peer#sendMessage(Message)} the transaction is still committed, so the
966      * pending transaction must be broadcast <b>by you</b> at some other time.
967      *
968      * @param to        Which address to send coins to.
969      * @param nanocoins How many nanocoins to send. You can use Utils.toNanoCoins() to calculate this.
970      * @return The {@link Transaction} that was created or null if there was insufficient balance to send the coins.
971      * @throws IOException if there was a problem broadcasting the transaction
972      */
973     public synchronized Transaction sendCoins(Peer peer, Address to, BigInteger nanocoins) throws IOException {
974         // TODO: This API is fairly questionable and the function isn't tested. If anything goes wrong during sending
975         // on the peer you don't get access to the created Transaction object and must fish it out of the wallet then
976         // do your own retry later.
977
978         Transaction tx = createSend(to, nanocoins);
979         if (tx == null)   // Not enough money! :-(
980             return null;
981         try {
982             commitTx(tx);
983         } catch (VerificationException e) {
984             throw new RuntimeException(e);  // Cannot happen unless there's a bug, as we just created this ourselves.
985         }
986         peer.sendMessage(tx);
987         return tx;
988     }
989
990     /**
991      * Creates a transaction that sends $coins.$cents BTC to the given address.<p>
992      * <p/>
993      * IMPORTANT: This method does NOT update the wallet. If you call createSend again you may get two transactions
994      * that spend the same coins. You have to call commitTx on the created transaction to prevent this,
995      * but that should only occur once the transaction has been accepted by the network. This implies you cannot have
996      * more than one outstanding sending tx at once.
997      *
998      * @param address       The BitCoin address to send the money to.
999      * @param nanocoins     How much currency to send, in nanocoins.
1000      * @param changeAddress Which address to send the change to, in case we can't make exactly the right value from
1001      *                      our coins. This should be an address we own (is in the keychain).
1002      * @return a new {@link Transaction} or null if we cannot afford this send.
1003      */
1004     public synchronized Transaction createSend(Address address, BigInteger nanocoins, Address changeAddress) {
1005         log.info("Creating send tx to " + address.toString() + " for " +
1006                 bitcoinValueToFriendlyString(nanocoins));
1007
1008         Transaction sendTx = new Transaction(params);
1009         sendTx.addOutput(nanocoins, address);
1010
1011         if (completeTx(sendTx, changeAddress)) {
1012             return sendTx;
1013         } else {
1014             return null;
1015         }
1016     }
1017
1018     /**
1019      * Takes a transaction with arbitrary outputs, gathers the necessary inputs for spending, and signs it
1020      * @param sendTx           The transaction to complete
1021      * @param changeAddress    Which address to send the change to, in case we can't make exactly the right value from
1022      *                         our coins. This should be an address we own (is in the keychain).
1023      * @return False if we cannot afford this send, true otherwise
1024      */
1025     public synchronized boolean completeTx(Transaction sendTx, Address changeAddress) {
1026         // Calculate the transaction total
1027         BigInteger nanocoins = BigInteger.ZERO;
1028         for(TransactionOutput output : sendTx.getOutputs()) {
1029             nanocoins = nanocoins.add(output.getValue());
1030         }
1031
1032         log.info("Completing send tx with {} outputs totalling {}", sendTx.getOutputs().size(), bitcoinValueToFriendlyString(nanocoins));
1033
1034         // To send money to somebody else, we need to do gather up transactions with unspent outputs until we have
1035         // sufficient value. Many coin selection algorithms are possible, we use a simple but suboptimal one.
1036         // TODO: Sort coins so we use the smallest first, to combat wallet fragmentation and reduce fees.
1037         BigInteger valueGathered = BigInteger.ZERO;
1038         List<TransactionOutput> gathered = new LinkedList<TransactionOutput>();
1039         for (Transaction tx : unspent.values()) {
1040             for (TransactionOutput output : tx.getOutputs()) {
1041                 if (!output.isAvailableForSpending()) continue;
1042                 if (!output.isMine(this)) continue;
1043                 gathered.add(output);
1044                 valueGathered = valueGathered.add(output.getValue());
1045             }
1046             if (valueGathered.compareTo(nanocoins) >= 0) break;
1047         }
1048         // Can we afford this?
1049         if (valueGathered.compareTo(nanocoins) < 0) {
1050             log.info("Insufficient value in wallet for send, missing " +
1051                     bitcoinValueToFriendlyString(nanocoins.subtract(valueGathered)));
1052             // TODO: Should throw an exception here.
1053             return false;
1054         }
1055         assert gathered.size() > 0;
1056         sendTx.getConfidence().setConfidenceType(TransactionConfidence.ConfidenceType.NOT_SEEN_IN_CHAIN);
1057         BigInteger change = valueGathered.subtract(nanocoins);
1058         if (change.compareTo(BigInteger.ZERO) > 0) {
1059             // The value of the inputs is greater than what we want to send. Just like in real life then,
1060             // we need to take back some coins ... this is called "change". Add another output that sends the change
1061             // back to us.
1062             log.info("  with " + bitcoinValueToFriendlyString(change) + " coins change");
1063             sendTx.addOutput(new TransactionOutput(params, sendTx, change, changeAddress));
1064         }
1065         for (TransactionOutput output : gathered) {
1066             sendTx.addInput(output);
1067         }
1068
1069         // Now sign the inputs, thus proving that we are entitled to redeem the connected outputs.
1070         try {
1071             sendTx.signInputs(Transaction.SigHash.ALL, this);
1072         } catch (ScriptException e) {
1073             // If this happens it means an output script in a wallet tx could not be understood. That should never
1074             // happen, if it does it means the wallet has got into an inconsistent state.
1075             throw new RuntimeException(e);
1076         }
1077         log.info("  completed {}", sendTx.getHashAsString());
1078         return true;
1079     }
1080
1081     /**
1082      * Takes a transaction with arbitrary outputs, gathers the necessary inputs for spending, and signs it.
1083      * Change goes to {@link Wallet#getChangeAddress()}
1084      * @param sendTx           The transaction to complete
1085      * @return False if we cannot afford this send, true otherwise
1086      */
1087     public synchronized boolean completeTx(Transaction sendTx) {
1088         return completeTx(sendTx, getChangeAddress());
1089     }
1090
1091     synchronized Address getChangeAddress() {
1092         // For now let's just pick the first key in our keychain. In future we might want to do something else to
1093         // give the user better privacy here, eg in incognito mode.
1094         assert keychain.size() > 0 : "Can't send value without an address to use for receiving change";
1095         ECKey first = keychain.get(0);
1096         return first.toAddress(params);
1097     }
1098
1099     /**
1100      * Adds the given ECKey to the wallet. There is currently no way to delete keys (that would result in coin loss).
1101      */
1102     public synchronized void addKey(ECKey key) {
1103         assert !keychain.contains(key);
1104         keychain.add(key);
1105     }
1106
1107     /**
1108      * Locates a keypair from the keychain given the hash of the public key. This is needed when finding out which
1109      * key we need to use to redeem a transaction output.
1110      *
1111      * @return ECKey object or null if no such key was found.
1112      */
1113     public synchronized ECKey findKeyFromPubHash(byte[] pubkeyHash) {
1114         for (ECKey key : keychain) {
1115             if (Arrays.equals(key.getPubKeyHash(), pubkeyHash)) return key;
1116         }
1117         return null;
1118     }
1119
1120     /**
1121      * Returns true if this wallet contains a public key which hashes to the given hash.
1122      */
1123     public synchronized boolean isPubKeyHashMine(byte[] pubkeyHash) {
1124         return findKeyFromPubHash(pubkeyHash) != null;
1125     }
1126
1127     /**
1128      * Locates a keypair from the keychain given the raw public key bytes.
1129      *
1130      * @return ECKey or null if no such key was found.
1131      */
1132     public synchronized ECKey findKeyFromPubKey(byte[] pubkey) {
1133         for (ECKey key : keychain) {
1134             if (Arrays.equals(key.getPubKey(), pubkey)) return key;
1135         }
1136         return null;
1137     }
1138
1139     /**
1140      * Returns true if this wallet contains a keypair with the given public key.
1141      */
1142     public synchronized boolean isPubKeyMine(byte[] pubkey) {
1143         return findKeyFromPubKey(pubkey) != null;
1144     }
1145
1146     /**
1147      * It's possible to calculate a wallets balance from multiple points of view. This enum selects which
1148      * getBalance() should use.<p>
1149      * <p/>
1150      * Consider a real-world example: you buy a snack costing $5 but you only have a $10 bill. At the start you have
1151      * $10 viewed from every possible angle. After you order the snack you hand over your $10 bill. From the
1152      * perspective of your wallet you have zero dollars (AVAILABLE). But you know in a few seconds the shopkeeper
1153      * will give you back $5 change so most people in practice would say they have $5 (ESTIMATED).<p>
1154      */
1155     public enum BalanceType {
1156         /**
1157          * Balance calculated assuming all pending transactions are in fact included into the best chain by miners.
1158          * This is the right balance to show in user interfaces.
1159          */
1160         ESTIMATED,
1161
1162         /**
1163          * Balance that can be safely used to create new spends. This is all confirmed unspent outputs minus the ones
1164          * spent by pending transactions, but not including the outputs of those pending transactions.
1165          */
1166         AVAILABLE
1167     }
1168
1169     /**
1170      * Returns the AVAILABLE balance of this wallet. See {@link BalanceType#AVAILABLE} for details on what this
1171      * means.<p>
1172      * <p/>
1173      * Note: the estimated balance is usually the one you want to show to the end user - however attempting to
1174      * actually spend these coins may result in temporary failure. This method returns how much you can safely
1175      * provide to {@link Wallet#createSend(Address, java.math.BigInteger)}.
1176      */
1177     public synchronized BigInteger getBalance() {
1178         return getBalance(BalanceType.AVAILABLE);
1179     }
1180
1181     /**
1182      * Returns the balance of this wallet as calculated by the provided balanceType.
1183      */
1184     public synchronized BigInteger getBalance(BalanceType balanceType) {
1185         BigInteger available = BigInteger.ZERO;
1186         for (Transaction tx : unspent.values()) {
1187             for (TransactionOutput output : tx.getOutputs()) {
1188                 if (!output.isMine(this)) continue;
1189                 if (!output.isAvailableForSpending()) continue;
1190                 available = available.add(output.getValue());
1191             }
1192         }
1193         if (balanceType == BalanceType.AVAILABLE)
1194             return available;
1195         assert balanceType == BalanceType.ESTIMATED;
1196         // Now add back all the pending outputs to assume the transaction goes through.
1197         BigInteger estimated = available;
1198         for (Transaction tx : pending.values()) {
1199             for (TransactionOutput output : tx.getOutputs()) {
1200                 if (!output.isMine(this)) continue;
1201                 estimated = estimated.add(output.getValue());
1202             }
1203         }
1204         return estimated;
1205     }
1206
1207     @Override
1208     public synchronized String toString() {
1209         StringBuilder builder = new StringBuilder();
1210         builder.append(String.format("Wallet containing %s BTC in:\n", bitcoinValueToFriendlyString(getBalance())));
1211         builder.append(String.format("  %d unspent transactions\n", unspent.size()));
1212         builder.append(String.format("  %d spent transactions\n", spent.size()));
1213         builder.append(String.format("  %d pending transactions\n", pending.size()));
1214         builder.append(String.format("  %d inactive transactions\n", inactive.size()));
1215         builder.append(String.format("  %d dead transactions\n", dead.size()));
1216         // Do the keys.
1217         builder.append("\nKeys:\n");
1218         for (ECKey key : keychain) {
1219             builder.append("  addr:");
1220             builder.append(key.toAddress(params));
1221             builder.append(" ");
1222             builder.append(key.toString());
1223             builder.append("\n");
1224         }
1225         // Print the transactions themselves
1226         if (unspent.size() > 0) {
1227             builder.append("\nUNSPENT:\n");
1228             for (Transaction tx : unspent.values()) builder.append(tx);
1229         }
1230         if (spent.size() > 0) {
1231             builder.append("\nSPENT:\n");
1232             for (Transaction tx : spent.values()) builder.append(tx);
1233         }
1234         if (pending.size() > 0) {
1235             builder.append("\nPENDING:\n");
1236             for (Transaction tx : pending.values()) builder.append(tx);
1237         }
1238         if (inactive.size() > 0) {
1239             builder.append("\nINACTIVE:\n");
1240             for (Transaction tx : inactive.values()) builder.append(tx);
1241         }
1242         if (dead.size() > 0) {
1243             builder.append("\nDEAD:\n");
1244             for (Transaction tx : dead.values()) builder.append(tx);
1245         }
1246         return builder.toString();
1247     }
1248
1249     /**
1250      * Called by the {@link BlockChain} when the best chain (representing total work done) has changed. In this case,
1251      * we need to go through our transactions and find out if any have become invalid. It's possible for our balance
1252      * to go down in this case: money we thought we had can suddenly vanish if the rest of the network agrees it
1253      * should be so.<p>
1254      *
1255      * The oldBlocks/newBlocks lists are ordered height-wise from top first to bottom last.
1256      */
1257     synchronized void reorganize(List<StoredBlock> oldBlocks, List<StoredBlock> newBlocks) throws VerificationException {
1258         // This runs on any peer thread with the block chain synchronized.
1259         //
1260         // The reorganize functionality of the wallet is tested in ChainSplitTests.
1261         //
1262         // For each transaction we track which blocks they appeared in. Once a re-org takes place we have to find all
1263         // transactions in the old branch, all transactions in the new branch and find the difference of those sets.
1264         //
1265         // receive() has been called on the block that is triggering the re-org before this is called.
1266
1267         List<Sha256Hash> oldBlockHashes = new ArrayList<Sha256Hash>(oldBlocks.size());
1268         List<Sha256Hash> newBlockHashes = new ArrayList<Sha256Hash>(newBlocks.size());
1269         log.info("Old part of chain (top to bottom):");
1270         for (StoredBlock b : oldBlocks) {
1271             log.info("  {}", b.getHeader().getHashAsString());
1272             oldBlockHashes.add(b.getHeader().getHash());
1273         }
1274         log.info("New part of chain (top to bottom):");
1275         for (StoredBlock b : newBlocks) {
1276             log.info("  {}", b.getHeader().getHashAsString());
1277             newBlockHashes.add(b.getHeader().getHash());
1278         }
1279
1280         // Transactions that appear in the old chain segment.
1281         Map<Sha256Hash, Transaction> oldChainTransactions = new HashMap<Sha256Hash, Transaction>();
1282         // Transactions that appear in the old chain segment and NOT the new chain segment.
1283         Map<Sha256Hash, Transaction> onlyOldChainTransactions = new HashMap<Sha256Hash, Transaction>();
1284         // Transactions that appear in the new chain segment.
1285         Map<Sha256Hash, Transaction> newChainTransactions = new HashMap<Sha256Hash, Transaction>();
1286         // Transactions that don't appear in either the new or the old section, ie, the shared trunk.
1287         Map<Sha256Hash, Transaction> commonChainTransactions = new HashMap<Sha256Hash, Transaction>();
1288
1289         Map<Sha256Hash, Transaction> all = new HashMap<Sha256Hash, Transaction>();
1290         all.putAll(unspent);
1291         all.putAll(spent);
1292         all.putAll(inactive);
1293         for (Transaction tx : all.values()) {
1294             Collection<Sha256Hash> appearsIn = tx.getAppearsInHashes();
1295             assert appearsIn != null;
1296             // If the set of blocks this transaction appears in is disjoint with one of the chain segments it means
1297             // the transaction was never incorporated by a miner into that side of the chain.
1298             boolean inOldSection = !Collections.disjoint(appearsIn, oldBlockHashes);
1299             boolean inNewSection = !Collections.disjoint(appearsIn, newBlockHashes);
1300             boolean inCommonSection = !inNewSection && !inOldSection;
1301
1302             if (inCommonSection) {
1303                 boolean alreadyPresent = commonChainTransactions.put(tx.getHash(), tx) != null;
1304                 assert !alreadyPresent : "Transaction appears twice in common chain segment";
1305             } else {
1306                 if (inOldSection) {
1307                     boolean alreadyPresent = oldChainTransactions.put(tx.getHash(), tx) != null;
1308                     assert !alreadyPresent : "Transaction appears twice in old chain segment";
1309                     if (!inNewSection) {
1310                         alreadyPresent = onlyOldChainTransactions.put(tx.getHash(), tx) != null;
1311                         assert !alreadyPresent : "Transaction appears twice in only-old map";
1312                     }
1313                 }
1314                 if (inNewSection) {
1315                     boolean alreadyPresent = newChainTransactions.put(tx.getHash(), tx) != null;
1316                     assert !alreadyPresent : "Transaction appears twice in new chain segment";
1317                 }
1318             }
1319         }
1320
1321         // If there is no difference it means we have nothing we need to do and the user does not care.
1322         boolean affectedUs = !oldChainTransactions.equals(newChainTransactions);
1323         log.info(affectedUs ? "Re-org affected our transactions" : "Re-org had no effect on our transactions");
1324         if (!affectedUs) return;
1325
1326         // For simplicity we will reprocess every transaction to ensure it's in the right bucket and has the right
1327         // connections. Attempting to update each one with minimal work is possible but complex and was leading to
1328         // edge cases that were hard to fix. As re-orgs are rare the amount of work this implies should be manageable
1329         // unless the user has an enormous wallet. As an optimization fully spent transactions buried deeper than
1330         // 1000 blocks could be put into yet another bucket which we never touch and assume re-orgs cannot affect.
1331
1332         for (Transaction tx : onlyOldChainTransactions.values()) log.info("  Only Old: {}", tx.getHashAsString());
1333         for (Transaction tx : oldChainTransactions.values()) log.info("  Old: {}", tx.getHashAsString());
1334         for (Transaction tx : newChainTransactions.values()) log.info("  New: {}", tx.getHashAsString());
1335
1336         // Break all the existing connections.
1337         for (Transaction tx : all.values())
1338             tx.disconnectInputs();
1339         for (Transaction tx : pending.values())
1340             tx.disconnectInputs();
1341         // Reconnect the transactions in the common part of the chain.
1342         for (Transaction tx : commonChainTransactions.values()) {
1343             TransactionInput badInput = tx.connectForReorganize(all);
1344             assert badInput == null : "Failed to connect " + tx.getHashAsString() + ", " + badInput.toString();
1345         }
1346         // Recalculate the unspent/spent buckets for the transactions the re-org did not affect.
1347         log.info("Moving transactions");
1348         unspent.clear();
1349         spent.clear();
1350         inactive.clear();
1351         for (Transaction tx : commonChainTransactions.values()) {
1352             int unspentOutputs = 0;
1353             for (TransactionOutput output : tx.getOutputs()) {
1354                 if (output.isAvailableForSpending()) unspentOutputs++;
1355             }
1356             if (unspentOutputs > 0) {
1357                 log.info("  TX {}: ->unspent", tx.getHashAsString());
1358                 unspent.put(tx.getHash(), tx);
1359             } else {
1360                 log.info("  TX {}: ->spent", tx.getHashAsString());
1361                 spent.put(tx.getHash(), tx);
1362             }
1363         }
1364         // Inform all transactions that exist only in the old chain that they have moved, so they can update confidence
1365         // and timestamps. Transactions will be told they're on the new best chain when the blocks are replayed.
1366         for (Transaction tx : onlyOldChainTransactions.values()) {
1367             tx.notifyNotOnBestChain();
1368         }
1369         // Now replay the act of receiving the blocks that were previously in a side chain. This will:
1370         //   - Move any transactions that were pending and are now accepted into the right bucket.
1371         //   - Connect the newly active transactions.
1372         Collections.reverse(newBlocks);  // Need bottom-to-top but we get top-to-bottom.
1373         for (StoredBlock b : newBlocks) {
1374             log.info("Replaying block {}", b.getHeader().getHashAsString());
1375             Set<Transaction> txns = new HashSet<Transaction>();
1376             Sha256Hash blockHash = b.getHeader().getHash();
1377             for (Transaction tx : newChainTransactions.values()) {
1378                 if (tx.getAppearsInHashes().contains(blockHash)) {
1379                     txns.add(tx);
1380                     log.info("  containing tx {}", tx.getHashAsString());
1381                 }
1382             }
1383             for (Transaction t : txns) {
1384                 try {
1385                     receive(t, b, BlockChain.NewBlockType.BEST_CHAIN, true);
1386                 } catch (ScriptException e) {
1387                     throw new RuntimeException(e);  // Cannot happen as these blocks were already verified.
1388                 }
1389             }
1390         }
1391
1392         // Find the transactions that didn't make it into the new chain yet. For each input, try to connect it to the
1393         // transactions that are in {spent,unspent,pending}. Check the status of each input. For inactive
1394         // transactions that only send us money, we put them into the inactive pool where they sit around waiting for
1395         // another re-org or re-inclusion into the main chain. For inactive transactions where we spent money we must
1396         // put them back into the pending pool if we can reconnect them, so we don't create a double spend whilst the
1397         // network heals itself.
1398         Map<Sha256Hash, Transaction> pool = new HashMap<Sha256Hash, Transaction>();
1399         pool.putAll(unspent);
1400         pool.putAll(spent);
1401         pool.putAll(pending);
1402         Map<Sha256Hash, Transaction> toReprocess = new HashMap<Sha256Hash, Transaction>();
1403         toReprocess.putAll(onlyOldChainTransactions);
1404         toReprocess.putAll(pending);
1405         log.info("Reprocessing transactions not in new best chain:");
1406         // Note, we must reprocess dead transactions first. The reason is that if there is a double spend across
1407         // chains from our own coins we get a complicated situation:
1408         //
1409         // 1) We switch to a new chain (B) that contains a double spend overriding a pending transaction. It goes dead.
1410         // 2) We switch BACK to the first chain (A). The dead transaction must go pending again.
1411         // 3) We resurrect the transactions that were in chain (B) and assume the miners will start work on putting them
1412         //    in to the chain, but it's not possible because it's a double spend. So now that transaction must become
1413         //    dead instead of pending.
1414         //
1415         // This only occurs when we are double spending our own coins.
1416         for (Transaction tx : dead.values()) {
1417             reprocessTxAfterReorg(pool, tx);
1418         }
1419         for (Transaction tx : toReprocess.values()) {
1420             reprocessTxAfterReorg(pool, tx);
1421         }
1422
1423         log.info("post-reorg balance is {}", Utils.bitcoinValueToFriendlyString(getBalance()));
1424
1425         // Inform event listeners that a re-org took place. They should save the wallet at this point.
1426         EventListenerInvoker.invoke(eventListeners, new EventListenerInvoker<WalletEventListener>() {
1427             @Override
1428             public void invoke(WalletEventListener listener) {
1429                 listener.onReorganize(Wallet.this);
1430             }
1431         });
1432         assert isConsistent();
1433     }
1434
1435     private void reprocessTxAfterReorg(Map<Sha256Hash, Transaction> pool, Transaction tx) {
1436         log.info("TX {}", tx.getHashAsString());
1437         int numInputs = tx.getInputs().size();
1438         int noSuchTx = 0;
1439         int success = 0;
1440         boolean isDead = false;
1441         for (TransactionInput input : tx.getInputs()) {
1442             if (input.isCoinBase()) {
1443                 // Input is not in our wallet so there is "no such input tx", bit of an abuse.
1444                 noSuchTx++;
1445                 continue;
1446             }
1447             TransactionInput.ConnectionResult result = input.connect(pool, false);
1448             if (result == TransactionInput.ConnectionResult.SUCCESS) {
1449                 success++;
1450             } else if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
1451                 noSuchTx++;
1452             } else if (result == TransactionInput.ConnectionResult.ALREADY_SPENT) {
1453                 isDead = true;
1454                 // This transaction was replaced by a double spend on the new chain. Did you just reverse
1455                 // your own transaction? I hope not!!
1456                 log.info("   ->dead, will not confirm now unless there's another re-org", tx.getHashAsString());
1457                 TransactionOutput doubleSpent = input.getConnectedOutput(pool);
1458                 Transaction replacement = doubleSpent.getSpentBy().getParentTransaction();
1459                 dead.put(tx.getHash(), tx);
1460                 pending.remove(tx.getHash());
1461                 // This updates the tx confidence type automatically.
1462                 tx.getConfidence().setOverridingTransaction(replacement);
1463                 invokeOnTransactionConfidenceChanged(tx);
1464                 break;
1465             }
1466         }
1467         if (isDead) return;
1468
1469         if (noSuchTx == numInputs) {
1470             log.info("   ->inactive", tx.getHashAsString());
1471             inactive.put(tx.getHash(), tx);
1472         } else if (success == numInputs - noSuchTx) {
1473             // All inputs are either valid for spending or don't come from us. Miners are trying to reinclude it.
1474             log.info("   ->pending", tx.getHashAsString());
1475             pending.put(tx.getHash(), tx);
1476             dead.remove(tx.getHash());
1477         }
1478     }
1479
1480     private void invokeOnTransactionConfidenceChanged(final Transaction tx) {
1481         EventListenerInvoker.invoke(eventListeners, new EventListenerInvoker<WalletEventListener>() {
1482             @Override
1483             public void invoke(WalletEventListener listener) {
1484                 listener.onTransactionConfidenceChanged(Wallet.this, tx);
1485             }
1486         });
1487     }
1488
1489
1490     /**
1491      * Returns an immutable view of the transactions currently waiting for network confirmations.
1492      */
1493     public synchronized Collection<Transaction> getPendingTransactions() {
1494         return Collections.unmodifiableCollection(pending.values());
1495     }
1496
1497     /**
1498      * Returns the earliest creation time of the keys in this wallet, in seconds since the epoch, ie the min of 
1499      * {@link com.google.bitcoin.core.ECKey#getCreationTimeSeconds()}. This can return zero if at least one key does
1500      * not have that data (was created before key timestamping was implemented). <p>
1501      *     
1502      * This method is most often used in conjunction with {@link PeerGroup#setFastCatchupTimeSecs(long)} in order to
1503      * optimize chain download for new users of wallet apps. Backwards compatibility notice: if you get zero from this
1504      * method, you can instead use the time of the first release of your software, as it's guaranteed no users will
1505      * have wallets pre-dating this time. <p>
1506      * 
1507      * If there are no keys in the wallet, the current time is returned.
1508      */
1509     public synchronized long getEarliestKeyCreationTime() {
1510         if (keychain.size() == 0) {
1511             return Utils.now().getTime() / 1000;
1512         }
1513         long earliestTime = Long.MAX_VALUE;
1514         for (ECKey key : keychain) {
1515             earliestTime = Math.min(key.getCreationTimeSeconds(), earliestTime);
1516         }
1517         return earliestTime;
1518     }
1519     
1520     // This object is used to receive events from a Peer or PeerGroup. Currently it is only used to receive
1521     // transactions. Note that it does NOT pay attention to block message because they will be received from the
1522     // BlockChain object along with extra data we need for correct handling of re-orgs.
1523     private transient PeerEventListener peerEventListener;
1524
1525     /**
1526      * Use the returned object can be used to connect the wallet to a {@link Peer} or {@link PeerGroup} in order to
1527      * receive and process blocks and transactions.
1528      */
1529     public synchronized PeerEventListener getPeerEventListener() {
1530         if (peerEventListener == null) {
1531             // Instantiate here to avoid issues with wallets resurrected from serialized copies.
1532             peerEventListener = new AbstractPeerEventListener() {
1533                 @Override
1534                 public void onTransaction(Peer peer, Transaction t) {
1535                     // Runs locked on a peer thread.
1536                     try {
1537                         receivePending(t);
1538                     } catch (VerificationException e) {
1539                         log.warn("Received broadcast transaction that does not validate: {}", t);
1540                         log.warn("VerificationException caught", e);
1541                     } catch (ScriptException e) {
1542                         log.warn("Received broadcast transaction with not understood scripts: {}", t);
1543                         log.warn("ScriptException caught", e);
1544                     }
1545                 }
1546             };
1547         }
1548         return peerEventListener;
1549     }
1550 }