001/**
002 * Copyright 2011 Google Inc.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *    http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.bitcoin.core;
018
019import com.google.bitcoin.core.TransactionConfidence.ConfidenceType;
020import com.google.bitcoin.core.WalletTransaction.Pool;
021import com.google.bitcoin.crypto.KeyCrypter;
022import com.google.bitcoin.crypto.KeyCrypterException;
023import com.google.bitcoin.crypto.KeyCrypterScrypt;
024import com.google.bitcoin.store.WalletProtobufSerializer;
025import com.google.bitcoin.utils.Locks;
026import com.google.common.base.Objects;
027import com.google.common.base.Preconditions;
028import com.google.common.collect.*;
029import com.google.common.util.concurrent.ListenableFuture;
030import com.google.common.util.concurrent.SettableFuture;
031import org.bitcoinj.wallet.Protos.Wallet.EncryptionType;
032import org.slf4j.Logger;
033import org.slf4j.LoggerFactory;
034import org.spongycastle.crypto.params.KeyParameter;
035
036import java.io.*;
037import java.math.BigInteger;
038import java.util.*;
039import java.util.concurrent.CopyOnWriteArrayList;
040import java.util.concurrent.DelayQueue;
041import java.util.concurrent.Delayed;
042import java.util.concurrent.TimeUnit;
043import java.util.concurrent.locks.ReentrantLock;
044
045import static com.google.bitcoin.core.Utils.bitcoinValueToFriendlyString;
046import static com.google.common.base.Preconditions.*;
047
048// To do list:
049//
050// - Make the keychain member protected and switch it to be a hashmap of some kind so key lookup ops are faster.
051// - Refactor how keys are managed to better handle things like deterministic wallets in future.
052// - Decompose the class where possible: break logic out into classes that can be customized/replaced by the user.
053//     - [Auto]saving to a backing store
054//     - Key management
055//     - just generally make Wallet smaller and easier to work with
056// - Make clearing of transactions able to only rewind the wallet a certain distance instead of all blocks.
057// - Make it scale:
058//     - eliminate all the algorithms with quadratic complexity (or worse)
059//     - don't require everything to be held in RAM at once
060//     - consider allowing eviction of no longer re-orgable transactions or keys that were used up
061
062/**
063 * <p>A Wallet stores keys and a record of transactions that send and receive value from those keys. Using these,
064 * it is able to create new transactions that spend the recorded transactions, and this is the fundamental operation
065 * of the Bitcoin protocol.</p>
066 *
067 * <p>To learn more about this class, read <b><a href="http://code.google.com/p/bitcoinj/wiki/WorkingWithTheWallet">
068 *     working with the wallet.</a></b></p>
069 *
070 * <p>To fill up a Wallet with transactions, you need to use it in combination with a {@link BlockChain} and various
071 * other objects, see the <a href="http://code.google.com/p/bitcoinj/wiki/GettingStarted">Getting started</a> tutorial
072 * on the website to learn more about how to set everything up.</p>
073 *
074 * <p>Wallets can be serialized using either Java serialization - this is not compatible across versions of bitcoinj,
075 * or protocol buffer serialization. You need to save the wallet whenever it changes, there is an auto-save feature
076 * that simplifies this for you although you're still responsible for manually triggering a save when your app is about
077 * to quit because the auto-save feature waits a moment before actually committing to disk to avoid IO thrashing when
078 * the wallet is changing very fast (eg due to a block chain sync). See
079 * {@link Wallet#autosaveToFile(java.io.File, long, java.util.concurrent.TimeUnit, com.google.bitcoin.core.Wallet.AutosaveEventListener)}
080 * for more information about this.</p>
081 */
082public class Wallet implements Serializable, BlockChainListener {
083    private static final Logger log = LoggerFactory.getLogger(Wallet.class);
084    private static final long serialVersionUID = 2L;
085
086    protected final ReentrantLock lock = Locks.lock("wallet");
087
088    // The various pools below give quick access to wallet-relevant transactions by the state they're in:
089    //
090    // Pending:  Transactions that didn't make it into the best chain yet. Pending transactions can be killed if a
091    //           double-spend against them appears in the best chain, in which case they move to the dead pool.
092    //           If a double-spend appears in the pending state as well, currently we just ignore the second
093    //           and wait for the miners to resolve the race.
094    // Unspent:  Transactions that appeared in the best chain and have outputs we can spend. Note that we store the
095    //           entire transaction in memory even though for spending purposes we only really need the outputs, the
096    //           reason being that this simplifies handling of re-orgs. It would be worth fixing this in future.
097    // Spent:    Transactions that appeared in the best chain but don't have any spendable outputs. They're stored here
098    //           for history browsing/auditing reasons only and in future will probably be flushed out to some other
099    //           kind of cold storage or just removed.
100    // Dead:     Transactions that we believe will never confirm get moved here, out of pending. Note that the Satoshi
101    //           client has no notion of dead-ness: the assumption is that double spends won't happen so there's no
102    //           need to notify the user about them. We take a more pessimistic approach and try to track the fact that
103    //           transactions have been double spent so applications can do something intelligent (cancel orders, show
104    //           to the user in the UI, etc). A transaction can leave dead and move into spent/unspent if there is a
105    //           re-org to a chain that doesn't include the double spend.
106
107    final Map<Sha256Hash, Transaction> pending;
108    final Map<Sha256Hash, Transaction> unspent;
109    final Map<Sha256Hash, Transaction> spent;
110    final Map<Sha256Hash, Transaction> dead;
111
112    // A list of public/private EC keys owned by this user. Access it using addKey[s], hasKey[s] and findPubKeyFromHash.
113    private ArrayList<ECKey> keychain;
114
115    private final NetworkParameters params;
116
117    private Sha256Hash lastBlockSeenHash;
118    private int lastBlockSeenHeight = -1;
119
120    private transient CopyOnWriteArrayList<WalletEventListener> eventListeners;
121
122    // Auto-save code. This all should be generalized in future to not be file specific so you can easily store the
123    // wallet into a database using the same mechanism. However we need to inform stores of each specific change with
124    // some objects representing those changes, which is more complex. To avoid poor performance in 0.6 on phones that
125    // have a lot of transactions in their wallet, we use the simpler approach. It's needed because the wallet stores
126    // the number of confirmations and accumulated work done for each transaction, so each block changes each tx.
127    private transient File autosaveToFile;
128    private transient boolean dirty;  // Is a write of the wallet necessary?
129    private transient AutosaveEventListener autosaveEventListener;
130    private transient long autosaveDelayMs;
131
132    // A listener that relays confidence changes from the transaction confidence object to the wallet event listener,
133    // as a convenience to API users so they don't have to register on every transaction themselves.
134    private transient TransactionConfidence.Listener txConfidenceListener;
135
136    // If a TX hash appears in this set then notifyNewBestBlock will ignore it, as its confidence was already set up
137    // in receive() via Transaction.setBlockAppearance(). As the BlockChain always calls notifyNewBestBlock even if
138    // it sent transactions to the wallet, without this we'd double count.
139    private transient HashSet<Sha256Hash> ignoreNextNewBlock;
140    // Whether or not to ignore nLockTime > 0 transactions that are received to the mempool.
141    private boolean acceptTimeLockedTransactions;
142
143    /** Represents the results of a {@link CoinSelector#select(java.math.BigInteger, java.util.LinkedList)}  operation */
144    public static class CoinSelection {
145        public BigInteger valueGathered;
146        public Set<TransactionOutput> gathered;
147        public CoinSelection(BigInteger valueGathered, Set<TransactionOutput> gathered) {
148            this.valueGathered = valueGathered;
149            this.gathered = gathered;
150        }
151    }
152
153    /**
154     * A CoinSelector is responsible for picking some outputs to spend, from the list of all spendable outputs. It
155     * allows you to customize the policies for creation of transactions to suit your needs. The select operation
156     * may return a {@link CoinSelection} that has a valueGathered lower than the requested target, if there's not
157     * enough money in the wallet.
158     */
159    public interface CoinSelector {
160        public CoinSelection select(BigInteger target, LinkedList<TransactionOutput> candidates);
161    }
162
163    /**
164     * This class implements a {@link CoinSelector} which attempts to get the highest priority possible. This means that
165     * the transaction is the most likely to get confirmed
166     * Note that this means we may end up "spending" more priority than would be required to get the transaction we are
167     * creating confirmed.
168     */
169    public static class DefaultCoinSelector implements CoinSelector {
170        public CoinSelection select(BigInteger biTarget, LinkedList<TransactionOutput> candidates) {
171            long target = biTarget.longValue();
172            HashSet<TransactionOutput> selected = new HashSet<TransactionOutput>();
173            // Sort the inputs by age*value so we get the highest "coindays" spent.
174            // TODO: Consider changing the wallets internal format to track just outputs and keep them ordered.
175            ArrayList<TransactionOutput> sortedOutputs = new ArrayList<TransactionOutput>(candidates);
176            // When calculating the wallet balance, we may be asked to select all possible coins, if so, avoid sorting
177            // them in order to improve performance.
178            if (!biTarget.equals(NetworkParameters.MAX_MONEY)) {
179                Collections.sort(sortedOutputs, new Comparator<TransactionOutput>() {
180                    public int compare(TransactionOutput a, TransactionOutput b) {
181                        int depth1 = 0;
182                        int depth2 = 0;
183                        TransactionConfidence conf1 = a.parentTransaction.getConfidence();
184                        TransactionConfidence conf2 = b.parentTransaction.getConfidence();
185                        if (conf1.getConfidenceType() == ConfidenceType.BUILDING) depth1 = conf1.getDepthInBlocks();
186                        if (conf2.getConfidenceType() == ConfidenceType.BUILDING) depth2 = conf2.getDepthInBlocks();
187                        BigInteger aValue = a.getValue();
188                        BigInteger bValue = b.getValue();
189                        BigInteger aCoinDepth = aValue.multiply(BigInteger.valueOf(depth1));
190                        BigInteger bCoinDepth = bValue.multiply(BigInteger.valueOf(depth2));
191                        int c1 = bCoinDepth.compareTo(aCoinDepth);
192                        if (c1 != 0) return c1;
193                        // The "coin*days" destroyed are equal, sort by value alone to get the lowest transaction size.
194                        int c2 = bValue.compareTo(aValue);
195                        if (c2 != 0) return c2;
196                        // They are entirely equivalent (possibly pending) so sort by hash to ensure a total ordering.
197                        BigInteger aHash = a.parentTransaction.getHash().toBigInteger();
198                        BigInteger bHash = b.parentTransaction.getHash().toBigInteger();
199                        return aHash.compareTo(bHash);
200                    }
201                });
202            }
203            // Now iterate over the sorted outputs until we have got as close to the target as possible or a little
204            // bit over (excessive value will be change).
205            long total = 0;
206            for (TransactionOutput output : sortedOutputs) {
207                if (total >= target) break;
208                // Only pick chain-included transactions, or transactions that are ours and pending.
209                if (!shouldSelect(output.parentTransaction)) continue;
210                selected.add(output);
211                total += output.getValue().longValue();
212            }
213            // Total may be lower than target here, if the given candidates were insufficient to create to requested
214            // transaction.
215            return new CoinSelection(BigInteger.valueOf(total), selected);
216        }
217
218        /** Sub-classes can override this to just customize whether transactions are usable, but keep age sorting. */
219        protected boolean shouldSelect(Transaction tx) {
220            return isSelectable(tx);
221        }
222
223        public static boolean isSelectable(Transaction tx) {
224            // Only pick chain-included transactions, or transactions that are ours and pending.
225            TransactionConfidence confidence = tx.getConfidence();
226            ConfidenceType type = confidence.getConfidenceType();
227            if (type.equals(ConfidenceType.BUILDING)) return true;
228            return type.equals(ConfidenceType.PENDING) &&
229                   confidence.getSource().equals(TransactionConfidence.Source.SELF) &&
230                   confidence.numBroadcastPeers() > 1;
231        }
232    }
233
234    /**
235     * This coin selector will select any transaction at all, regardless of where it came from or whether it was
236     * confirmed yet.
237     */
238    public static class AllowUnconfirmedCoinSelector extends DefaultCoinSelector {
239        @Override protected boolean shouldSelect(Transaction tx) {
240            return true;
241        }
242
243        private static AllowUnconfirmedCoinSelector instance;
244        public static AllowUnconfirmedCoinSelector get() {
245            // This doesn't have to be thread safe as the object has no state, so discarded duplicates are harmless.
246            if (instance == null)
247                instance = new AllowUnconfirmedCoinSelector();
248            return instance;
249        }
250    }
251
252    private transient CoinSelector coinSelector = new DefaultCoinSelector();
253
254    // The keyCrypter for the wallet. This specifies the algorithm used for encrypting and decrypting the private keys.
255    private KeyCrypter keyCrypter;
256    // The wallet version. This is an int that can be used to track breaking changes in the wallet format.
257    // You can also use it to detect wallets that come from the future (ie they contain features you
258    // do not know how to deal with).
259    private int version;
260    // User-provided description that may help people keep track of what a wallet is for.
261    private String description;
262    // Stores objects that know how to serialize/unserialize themselves to byte streams and whether they're mandatory
263    // or not. The string key comes from the extension itself.
264    private final HashMap<String, WalletExtension> extensions;
265
266    /**
267     * Creates a new, empty wallet with no keys and no transactions. If you want to restore a wallet from disk instead,
268     * see loadFromFile.
269     */
270    public Wallet(NetworkParameters params) {
271        this(params, null);
272    }
273
274    /**
275     * Create a wallet with a keyCrypter to use in encrypting and decrypting keys.
276     */
277    public Wallet(NetworkParameters params, KeyCrypter keyCrypter) {
278        this.keyCrypter = keyCrypter;
279        this.params = checkNotNull(params);
280        keychain = new ArrayList<ECKey>();
281        unspent = new HashMap<Sha256Hash, Transaction>();
282        spent = new HashMap<Sha256Hash, Transaction>();
283        pending = new HashMap<Sha256Hash, Transaction>();
284        dead = new HashMap<Sha256Hash, Transaction>();
285        eventListeners = new CopyOnWriteArrayList<WalletEventListener>();
286        extensions = new HashMap<String, WalletExtension>();
287        createTransientState();
288    }
289
290    private void createTransientState() {
291        ignoreNextNewBlock = new HashSet<Sha256Hash>();
292        txConfidenceListener = new TransactionConfidence.Listener() {
293            @Override
294            public void onConfidenceChanged(Transaction tx) {
295                lock.lock();
296                // The invokers unlock us immediately so if an exception is thrown, the lock will be already open.
297                invokeOnTransactionConfidenceChanged(tx);
298                // Many onWalletChanged events will not occur because they are suppressed, eg, because:
299                //   - we are inside a re-org
300                //   - we are in the middle of processing a block
301                //   - the confidence is changing because a new best block was accepted
302                // It will run in cases like:
303                //   - the tx is pending and another peer announced it
304                //   - the tx is pending and was killed by a detected double spend that was not in a block
305                // The latter case cannot happen today because we won't hear about it, but in future this may
306                // become more common if conflict notices are implemented.
307                invokeOnWalletChanged();
308                lock.unlock();
309            }
310        };
311        acceptTimeLockedTransactions = false;
312    }
313
314    public NetworkParameters getNetworkParameters() {
315        return params;
316    }
317
318    /**
319     * Returns a snapshot of the keychain. This view is not live.
320     */
321    public List<ECKey> getKeys() {
322        lock.lock();
323        try {
324            return new ArrayList<ECKey>(keychain);
325        } finally {
326            lock.unlock();
327        }
328    }
329
330    /**
331     * Removes the given key from the keychain. Be very careful with this - losing a private key <b>destroys the
332     * money associated with it</b>.
333     * @return Whether the key was removed or not.
334     */
335    public boolean removeKey(ECKey key) {
336        lock.lock();
337        try {
338            return keychain.remove(key);
339        } finally {
340            lock.unlock();
341        }
342    }
343    
344    /**
345     * Returns the number of keys in the keychain.
346     */
347    public int getKeychainSize() {
348        lock.lock();
349        try {
350            return keychain.size();
351        } finally {
352            lock.unlock();
353        }
354    }
355
356    private void saveToFile(File temp, File destFile) throws IOException {
357        FileOutputStream stream = null;
358        try {
359            stream = new FileOutputStream(temp);
360            saveToFileStream(stream);
361            // Attempt to force the bits to hit the disk. In reality the OS or hard disk itself may still decide
362            // to not write through to physical media for at least a few seconds, but this is the best we can do.
363            stream.flush();
364            stream.getFD().sync();
365            stream.close();
366            stream = null;
367            if (Utils.isWindows()) {
368                // Work around an issue on Windows whereby you can't rename over existing files.
369                File canonical = destFile.getCanonicalFile();
370                canonical.delete();
371                if (temp.renameTo(canonical))
372                    return;  // else fall through.
373                throw new IOException("Failed to rename " + temp + " to " + canonical);
374            } else if (!temp.renameTo(destFile)) {
375                throw new IOException("Failed to rename " + temp + " to " + destFile);
376            }
377            lock.lock();
378            try {
379                if (destFile.equals(autosaveToFile)) {
380                    dirty = false;
381                }
382            } finally {
383                lock.unlock();
384            }
385        } finally {
386            if (stream != null) {
387                stream.close();
388            }
389            if (temp.delete()) {
390                log.warn("Deleted temp file after failed save.");
391            }
392        }
393    }
394
395    /**
396     * Uses protobuf serialization to save the wallet to the given file. To learn more about this file format, see
397     * {@link WalletProtobufSerializer}. Writes out first to a temporary file in the same directory and then renames
398     * once written.
399     */
400    public void saveToFile(File f) throws IOException {
401        File directory = f.getAbsoluteFile().getParentFile();
402        File temp = File.createTempFile("wallet", null, directory);
403        saveToFile(temp, f);
404    }
405
406    /**
407     * <p>Whether or not the wallet will ignore transactions that have a lockTime parameter > 0. By default, all such
408     * transactions are ignored, because they are useful only in special protocols and such a transaction may not
409     * confirm as fast as an app typically expects. By setting this property to true, you are acknowledging that
410     * you understand what time-locked transactions are, and that your code is capable of handling them without risk.
411     * For instance you are not providing anything valuable in return for an unconfirmed transaction that has a lock
412     * time far in the future (which opens you up to Finney attacks).</p>
413     *
414     * <p>Note that this property is not serialized. So you have to set it to true each time you load or create a
415     * wallet.</p>
416     */
417    public void setAcceptTimeLockedTransactions(boolean acceptTimeLockedTransactions) {
418        lock.lock();
419        try {
420            this.acceptTimeLockedTransactions = acceptTimeLockedTransactions;
421        } finally {
422            lock.unlock();
423        }
424    }
425
426    /**
427     * See {@link Wallet#setAcceptTimeLockedTransactions(boolean)} for an explanation of this property.
428     */
429    public boolean doesAcceptTimeLockedTransactions() {
430        lock.lock();
431        try {
432            return acceptTimeLockedTransactions;
433        } finally {
434            lock.unlock();
435        }
436    }
437
438    // Auto-saving can be done on a background thread if the user wishes it, this is to avoid stalling threads calling
439    // into the wallet on serialization/disk access all the time which is important in GUI apps where you don't want
440    // the main thread to ever wait on disk (otherwise you lose a lot of responsiveness). The primary case where it
441    // can be a problem is during block chain syncup - the wallet has to be saved after every block to record where
442    // it got up to and for updating the transaction confidence data, which can slow down block chain download a lot.
443    // So this thread not only puts the work of saving onto a background thread but also coalesces requests together.
444    private static class AutosaveThread extends Thread {
445        private static DelayQueue<AutosaveThread.WalletSaveRequest> walletRefs = new DelayQueue<WalletSaveRequest>();
446        private static AutosaveThread globalThread;
447
448        private AutosaveThread() {
449            // Allow the JVM to shut down without waiting for this thread. Note this means users could lose auto-saves
450            // if they don't explicitly save the wallet before terminating!
451            setDaemon(true);
452            setName("Wallet auto save thread");
453            setPriority(Thread.MIN_PRIORITY);   // Avoid competing with the UI.
454        }
455
456        /** Returns the global instance that services all wallets. It never shuts down. */
457        public static void maybeStart() {
458            if (walletRefs.size() == 0) return;
459
460            synchronized (AutosaveThread.class) {
461                if (globalThread == null) {
462                    globalThread = new AutosaveThread();
463                    globalThread.start();
464                }
465            }
466        }
467
468        /** Called by a wallet when it's become dirty (changed). Will start the background thread if needed. */
469        public static void registerForSave(Wallet wallet, long delayMsec) {
470            walletRefs.add(new WalletSaveRequest(wallet, delayMsec));
471            maybeStart();
472        }
473
474        public void run() {
475            log.info("Auto-save thread starting up");
476            while (true) {
477                try {
478                    WalletSaveRequest req = walletRefs.poll(5, TimeUnit.SECONDS);
479                    if (req == null) {
480                        if (walletRefs.size() == 0) {
481                            // No work to do for the given delay period, so let's shut down and free up memory.
482                            // We'll get started up again if a wallet changes once more.
483                            break;
484                        } else {
485                            // There's work but nothing to do just yet. Go back to sleep and try again.
486                            continue;
487                        }
488                    }
489
490                    req.wallet.lock.lock();
491                    try {
492                        if (req.wallet.dirty) {
493                            if (req.wallet.autoSave()) {
494                                // Something went wrong, abort!
495                                break;
496                            }
497                        }
498                    } finally {
499                        req.wallet.lock.unlock();
500                    }
501                } catch (InterruptedException e) {
502                    log.error("Auto-save thread interrupted during wait", e);
503                    break;
504                }
505            }
506            log.info("Auto-save thread shutting down");
507            synchronized (AutosaveThread.class) {
508                Preconditions.checkState(globalThread == this);   // There should only be one global thread.
509                globalThread = null;
510            }
511            // There's a possible shutdown race where work is added after we decided to shutdown but before
512            // we cleared globalThread.
513            maybeStart();
514        }
515
516        private static class WalletSaveRequest implements Delayed {
517            public final Wallet wallet;
518            public final long startTimeMs, requestedDelayMs;
519
520            public WalletSaveRequest(Wallet wallet, long requestedDelayMs) {
521                this.startTimeMs = System.currentTimeMillis();
522                this.requestedDelayMs = requestedDelayMs;
523                this.wallet = wallet;
524            }
525
526            public long getDelay(TimeUnit timeUnit) {
527                long delayRemainingMs = requestedDelayMs - (System.currentTimeMillis() - startTimeMs);
528                return timeUnit.convert(delayRemainingMs, TimeUnit.MILLISECONDS);
529            }
530
531            public int compareTo(Delayed delayed) {
532                if (delayed == this) return 0;
533                long delta = getDelay(TimeUnit.MILLISECONDS) - delayed.getDelay(TimeUnit.MILLISECONDS);
534                return (delta > 0 ? 1 : (delta < 0 ? -1 : 0));
535            }
536
537            @Override
538            public boolean equals(Object obj) {
539                if (!(obj instanceof WalletSaveRequest)) return false;
540                WalletSaveRequest w = (WalletSaveRequest) obj;
541                return w.startTimeMs == startTimeMs &&
542                       w.requestedDelayMs == requestedDelayMs &&
543                       w.wallet == wallet;
544            }
545
546            @Override
547            public int hashCode() {
548                return Objects.hashCode(wallet, startTimeMs, requestedDelayMs);
549            }
550        }
551    }
552
553    /** Returns true if the auto-save thread should abort */
554    private boolean autoSave() {
555        lock.lock();
556        final Sha256Hash lastBlockSeenHash = this.lastBlockSeenHash;
557        final AutosaveEventListener autosaveEventListener = this.autosaveEventListener;
558        final File autosaveToFile = this.autosaveToFile;
559        lock.unlock();
560        try {
561            log.info("Auto-saving wallet, last seen block is {}", lastBlockSeenHash);
562            File directory = autosaveToFile.getAbsoluteFile().getParentFile();
563            File temp = File.createTempFile("wallet", null, directory);
564            if (autosaveEventListener != null)
565                autosaveEventListener.onBeforeAutoSave(temp);
566            // This will clear the dirty flag.
567            saveToFile(temp, autosaveToFile);
568            if (autosaveEventListener != null)
569                autosaveEventListener.onAfterAutoSave(autosaveToFile);
570        } catch (Exception e) {
571            if (autosaveEventListener != null && autosaveEventListener.caughtException(e))
572                return true;
573            else
574                throw new RuntimeException(e);
575        }
576        return false;
577    }
578
579    /**
580     * Implementors can handle exceptions thrown during wallet auto-save, and to do pre/post treatment of the wallet.
581     */
582    public interface AutosaveEventListener {
583        /**
584         * Called on the auto-save thread if an exception is caught whilst saving the wallet.
585         * @return if true, terminates the auto-save thread. Otherwise sleeps and then tries again.
586         */
587        public boolean caughtException(Throwable t);
588
589        /**
590         * Called on the auto-save thread when a new temporary file is created but before the wallet data is saved
591         * to it. If you want to do something here like adjust permissions, go ahead and do so. The wallet is locked
592         * whilst this method is run.
593         */
594        public void onBeforeAutoSave(File tempFile);
595
596        /**
597         * Called on the auto-save thread after the newly created temporary file has been filled with data and renamed.
598         * The wallet is locked whilst this method is run.
599         */
600        public void onAfterAutoSave(File newlySavedFile);
601    }
602
603    /**
604     * <p>Sets up the wallet to auto-save itself to the given file, using temp files with atomic renames to ensure
605     * consistency. After connecting to a file, you no longer need to save the wallet manually, it will do it
606     * whenever necessary. Protocol buffer serialization will be used.</p>
607     *
608     * <p>If delayTime is set, a background thread will be created and the wallet will only be saved to
609     * disk every so many time units. If no changes have occurred for the given time period, nothing will be written.
610     * In this way disk IO can be rate limited. It's a good idea to set this as otherwise the wallet can change very
611     * frequently, eg if there are a lot of transactions in it or during block sync, and there will be a lot of redundant
612     * writes. Note that when a new key is added, that always results in an immediate save regardless of
613     * delayTime. <b>You should still save the wallet manually when your program is about to shut down as the JVM
614     * will not wait for the background thread.</b></p>
615     *
616     * <p>An event listener can be provided. If a delay >0 was specified, it will be called on a background thread
617     * with the wallet locked when an auto-save occurs. If delay is zero or you do something that always triggers
618     * an immediate save, like adding a key, the event listener will be invoked on the calling threads.</p>
619     *
620     * @param f The destination file to save to.
621     * @param delayTime How many time units to wait until saving the wallet on a background thread.
622     * @param timeUnit the unit of measurement for delayTime.
623     * @param eventListener callback to be informed when the auto-save thread does things, or null
624     */
625    public void autosaveToFile(File f, long delayTime, TimeUnit timeUnit,
626                               AutosaveEventListener eventListener) {
627        lock.lock();
628        try {
629            Preconditions.checkArgument(delayTime >= 0);
630            autosaveToFile = Preconditions.checkNotNull(f);
631            if (delayTime > 0) {
632                autosaveEventListener = eventListener;
633                autosaveDelayMs = TimeUnit.MILLISECONDS.convert(delayTime, timeUnit);
634            }
635        } finally {
636            lock.unlock();
637        }
638    }
639
640    private void queueAutoSave() {
641        lock.lock();
642        try {
643            if (this.autosaveToFile == null) return;
644            if (autosaveDelayMs == 0) {
645                // No delay time was specified, so save now.
646                try {
647                    saveToFile(autosaveToFile);
648                } catch (IOException e) {
649                    throw new RuntimeException(e);
650                }
651            } else {
652                // If we need to, tell the auto save thread to wake us up. This will start the background thread if one
653                // doesn't already exist. It will wake up once the delay expires and call autoSave().
654                // The background thread is shared between all wallets.
655                if (!dirty) {
656                    dirty = true;
657                    AutosaveThread.registerForSave(this, autosaveDelayMs);
658                }
659            }
660        } finally {
661            lock.unlock();
662        }
663    }
664
665    /**
666     * Uses protobuf serialization to save the wallet to the given file stream. To learn more about this file format, see
667     * {@link WalletProtobufSerializer}.
668     */
669    public void saveToFileStream(OutputStream f) throws IOException {
670        lock.lock();
671        try {
672            new WalletProtobufSerializer().writeWallet(this, f);
673        } finally {
674            lock.unlock();
675        }
676    }
677
678    /** Returns the parameters this wallet was created with. */
679    public NetworkParameters getParams() {
680        return params;
681    }
682
683    /**
684     * Returns a wallet deserialized from the given file.
685     */
686    public static Wallet loadFromFile(File f) throws IOException {
687        FileInputStream stream = new FileInputStream(f);
688        try {
689            return loadFromFileStream(stream);
690        } finally {
691            stream.close();
692        }
693    }
694    
695    public boolean isConsistent() {
696        lock.lock();
697        try {
698            boolean success = true;
699            Set<Transaction> transactions = getTransactions(true);
700
701            Set<Sha256Hash> hashes = new HashSet<Sha256Hash>();
702            for (Transaction tx : transactions) {
703                hashes.add(tx.getHash());
704            }
705
706            int size1 = transactions.size();
707
708            if (size1 != hashes.size()) {
709                log.error("Two transactions with same hash");
710                success = false;
711            }
712
713            int size2 = unspent.size() + spent.size() + pending.size() + dead.size();
714            if (size1 != size2) {
715                log.error("Inconsistent wallet sizes: {} {}", size1, size2);
716                success = false;
717            }
718
719            for (Transaction tx : unspent.values()) {
720                if (!tx.isConsistent(this, false)) {
721                    success = false;
722                    log.error("Inconsistent unspent tx {}", tx.getHashAsString());
723                }
724            }
725
726            for (Transaction tx : spent.values()) {
727                if (!tx.isConsistent(this, true)) {
728                    success = false;
729                    log.error("Inconsistent spent tx {}", tx.getHashAsString());
730                }
731            }
732
733            if (!success) log.error(toString());
734            return success;
735        } finally {
736            lock.unlock();
737        }
738    }
739
740    /**
741     * Returns a wallet deserialized from the given input stream.
742     */
743    public static Wallet loadFromFileStream(InputStream stream) throws IOException {
744        // Determine what kind of wallet stream this is: Java Serialization or protobuf format.
745        stream = new BufferedInputStream(stream);
746        stream.mark(100);
747        boolean serialization = stream.read() == 0xac && stream.read() == 0xed;
748        stream.reset();
749
750        Wallet wallet;
751        
752        if (serialization) {
753            ObjectInputStream ois = null;
754            try {
755                ois = new ObjectInputStream(stream);
756                wallet = (Wallet) ois.readObject();
757            } catch (ClassNotFoundException e) {
758                throw new RuntimeException(e);
759            } finally {
760                if (ois != null) ois.close();
761            }
762        } else {
763            wallet = new WalletProtobufSerializer().readWallet(stream);
764        }
765        
766        if (!wallet.isConsistent()) {
767            log.error("Loaded an inconsistent wallet");
768        }
769        return wallet;
770    }
771
772    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
773        in.defaultReadObject();
774        createTransientState();
775    }
776    
777    /**
778     * Called by the {@link BlockChain} when we receive a new filtered block that contains a transactions previously
779     * received by a call to @{link receivePending}.<p>
780     *
781     * This is necessary for the internal book-keeping Wallet does. When a transaction is received that sends us
782     * coins it is added to a pool so we can use it later to create spends. When a transaction is received that
783     * consumes outputs they are marked as spent so they won't be used in future.<p>
784     *
785     * A transaction that spends our own coins can be received either because a spend we created was accepted by the
786     * network and thus made it into a block, or because our keys are being shared between multiple instances and
787     * some other node spent the coins instead. We still have to know about that to avoid accidentally trying to
788     * double spend.<p>
789     *
790     * A transaction may be received multiple times if is included into blocks in parallel chains. The blockType
791     * parameter describes whether the containing block is on the main/best chain or whether it's on a presently
792     * inactive side chain. We must still record these transactions and the blocks they appear in because a future
793     * block might change which chain is best causing a reorganize. A re-org can totally change our balance!
794     */
795    public void notifyTransactionIsInBlock(Sha256Hash txHash, StoredBlock block,
796                                           BlockChain.NewBlockType blockType) throws VerificationException {
797        lock.lock();
798        try {
799            Transaction tx = pending.get(txHash);
800            if (tx == null)
801                return;
802            receive(tx, block, blockType, false);
803        } finally {
804            lock.unlock();
805        }
806    }
807
808    /** The results of examining the dependency graph of a pending transaction for protocol abuse. */
809    protected static class AnalysisResult {
810        // Which tx, if any, had a non-zero lock time.
811        Transaction timeLocked;
812        // In future, depth, fees, if any are non-standard, anything else that's interesting ...
813    }
814
815    /**
816     * <p>Called when we have found a transaction (via network broadcast or otherwise) that is relevant to this wallet
817     * and want to record it. Note that we <b>cannot verify these transactions at all</b>, they may spend fictional
818     * coins or be otherwise invalid. They are useful to inform the user about coins they can expect to receive soon,
819     * and if you trust the sender of the transaction you can choose to assume they are in fact valid and will not
820     * be double spent as an optimization.</p>
821     *
822     * <p>Before this method is called, {@link Wallet#isPendingTransactionRelevant(Transaction)} should have been
823     * called to decide whether the wallet cares about the transaction - if it does, then this method expects the
824     * transaction and any dependencies it has which are still in the memory pool.</p>
825     */
826    public void receivePending(Transaction tx, List<Transaction> dependencies) throws VerificationException {
827        // Can run in a peer thread. This method will only be called if a prior call to isPendingTransactionRelevant
828        // returned true, so we already know by this point that it sends coins to or from our wallet, or is a double
829        // spend against one of our other pending transactions.
830        //
831        // Do a brief risk analysis of the transaction and its dependencies to check for any possible attacks.
832        lock.lock();
833        try {
834            tx.verify();
835            // Repeat the check of relevancy here, even though the caller may have already done so - this is to avoid
836            // race conditions where receivePending may be being called in parallel.
837            if (!isPendingTransactionRelevant(tx))
838                return;
839            AnalysisResult analysis = analyzeTransactionAndDependencies(tx, dependencies);
840            if (analysis.timeLocked != null && !doesAcceptTimeLockedTransactions()) {
841                log.warn("Transaction {}, dependency of {} has a time lock value of {}", new Object[]{
842                        analysis.timeLocked.getHashAsString(), tx.getHashAsString(), analysis.timeLocked.getLockTime()});
843                return;
844            }
845            BigInteger valueSentToMe = tx.getValueSentToMe(this);
846            BigInteger valueSentFromMe = tx.getValueSentFromMe(this);
847            if (log.isInfoEnabled()) {
848                log.info(String.format("Received a pending transaction %s that spends %s BTC from our own wallet," +
849                        " and sends us %s BTC", tx.getHashAsString(), Utils.bitcoinValueToFriendlyString(valueSentFromMe),
850                        Utils.bitcoinValueToFriendlyString(valueSentToMe)));
851            }
852            if (tx.getConfidence().getSource().equals(TransactionConfidence.Source.UNKNOWN)) {
853                log.warn("Wallet received transaction with an unknown source. Consider tagging tx!");
854            }
855            // Mark the tx as having been seen but is not yet in the chain. This will normally have been done already by
856            // the Peer before we got to this point, but in some cases (unit tests, other sources of transactions) it may
857            // have been missed out.
858            ConfidenceType currentConfidence = tx.getConfidence().getConfidenceType();
859            if (currentConfidence == ConfidenceType.UNKNOWN) {
860                tx.getConfidence().setConfidenceType(ConfidenceType.PENDING);
861                // Manually invoke the wallet tx confidence listener here as we didn't yet commit therefore the
862                // txConfidenceListener wasn't added.
863                invokeOnTransactionConfidenceChanged(tx);
864            }
865            // If this tx spends any of our unspent outputs, mark them as spent now, then add to the pending pool. This
866            // ensures that if some other client that has our keys broadcasts a spend we stay in sync. Also updates the
867            // timestamp on the transaction and registers/runs event listeners.
868            //
869            // Note that after we return from this function, the wallet may have been modified.
870            commitTx(tx);
871        } finally {
872            lock.unlock();
873        }
874    }
875
876    private static AnalysisResult analyzeTransactionAndDependencies(Transaction tx, List<Transaction> dependencies) {
877        AnalysisResult result = new AnalysisResult();
878        if (tx.isTimeLocked())
879            result.timeLocked = tx;
880        if (dependencies != null) {
881            for (Transaction dep : dependencies) {
882                if (dep.isTimeLocked()) {
883                    result.timeLocked = dep;
884                }
885            }
886        }
887        return result;
888    }
889
890    /**
891     * This method is used by a {@link Peer} to find out if a transaction that has been announced is interesting,
892     * that is, whether we should bother downloading its dependencies and exploring the transaction to decide how
893     * risky it is. If this method returns true then {@link Wallet#receivePending(Transaction, java.util.List)}
894     * will soon be called with the transactions dependencies as well.
895     */
896    boolean isPendingTransactionRelevant(Transaction tx) throws ScriptException {
897        lock.lock();
898        try {
899            // Ignore it if we already know about this transaction. Receiving a pending transaction never moves it
900            // between pools.
901            EnumSet<Pool> containingPools = getContainingPools(tx);
902            if (!containingPools.equals(EnumSet.noneOf(Pool.class))) {
903                log.debug("Received tx we already saw in a block or created ourselves: " + tx.getHashAsString());
904                return false;
905            }
906
907            // We only care about transactions that:
908            //   - Send us coins
909            //   - Spend our coins
910            if (!isTransactionRelevant(tx)) {
911                log.debug("Received tx that isn't relevant to this wallet, discarding.");
912                return false;
913            }
914
915            if (tx.isTimeLocked() && !acceptTimeLockedTransactions) {
916                log.warn("Received transaction {} with a lock time of {}, but not configured to accept these, discarding",
917                        tx.getHashAsString(), tx.getLockTime());
918                return false;
919            }
920            return true;
921        } finally {
922            lock.unlock();
923        }
924    }
925
926    /**
927     * <p>Returns true if the given transaction sends coins to any of our keys, or has inputs spending any of our outputs,
928     * and if includeDoubleSpending is true, also returns true if tx has inputs that are spending outputs which are
929     * not ours but which are spent by pending transactions.</p>
930     *
931     * <p>Note that if the tx has inputs containing one of our keys, but the connected transaction is not in the wallet,
932     * it will not be considered relevant.</p>
933     */
934    public boolean isTransactionRelevant(Transaction tx) throws ScriptException {
935        lock.lock();
936        try {
937            return tx.getValueSentFromMe(this).compareTo(BigInteger.ZERO) > 0 ||
938                   tx.getValueSentToMe(this).compareTo(BigInteger.ZERO) > 0 ||
939                   checkForDoubleSpendAgainstPending(tx, false);
940        } finally {
941            lock.unlock();
942        }
943    }
944
945    /**
946     * Checks if "tx" is spending any inputs of pending transactions. Not a general check, but it can work even if
947     * the double spent inputs are not ours. Returns the pending tx that was double spent or null if none found.
948     */
949    private boolean checkForDoubleSpendAgainstPending(Transaction tx, boolean takeAction) {
950        checkState(lock.isLocked());
951        // Compile a set of outpoints that are spent by tx.
952        HashSet<TransactionOutPoint> outpoints = new HashSet<TransactionOutPoint>();
953        for (TransactionInput input : tx.getInputs()) {
954            outpoints.add(input.getOutpoint());
955        }
956        // Now for each pending transaction, see if it shares any outpoints with this tx.
957        for (Transaction p : pending.values()) {
958            for (TransactionInput input : p.getInputs()) {
959                // This relies on the fact that TransactionOutPoint equality is defined at the protocol not object
960                // level - outpoints from two different inputs that point to the same output compare the same.
961                TransactionOutPoint outpoint = input.getOutpoint();
962                if (outpoints.contains(outpoint)) {
963                    // It does, it's a double spend against the pending pool, which makes it relevant.
964                    if (takeAction) {
965                        // Look for the actual input object in tx that is double spending.
966                        TransactionInput overridingInput = null;
967                        for (TransactionInput txInput : tx.getInputs()) {
968                            if (txInput.getOutpoint().equals(outpoint)) overridingInput = txInput;
969                        }
970                        killTx(tx, checkNotNull(overridingInput), p);
971                    }
972                    return true;
973                }
974            }
975        }
976        return false;
977    }
978
979    /**
980     * Called by the {@link BlockChain} when we receive a new block that sends coins to one of our addresses or
981     * spends coins from one of our addresses (note that a single transaction can do both).<p>
982     *
983     * This is necessary for the internal book-keeping Wallet does. When a transaction is received that sends us
984     * coins it is added to a pool so we can use it later to create spends. When a transaction is received that
985     * consumes outputs they are marked as spent so they won't be used in future.<p>
986     *
987     * A transaction that spends our own coins can be received either because a spend we created was accepted by the
988     * network and thus made it into a block, or because our keys are being shared between multiple instances and
989     * some other node spent the coins instead. We still have to know about that to avoid accidentally trying to
990     * double spend.<p>
991     *
992     * A transaction may be received multiple times if is included into blocks in parallel chains. The blockType
993     * parameter describes whether the containing block is on the main/best chain or whether it's on a presently
994     * inactive side chain. We must still record these transactions and the blocks they appear in because a future
995     * block might change which chain is best causing a reorganize. A re-org can totally change our balance!
996     */
997    public void receiveFromBlock(Transaction tx, StoredBlock block,
998                                 BlockChain.NewBlockType blockType) throws VerificationException {
999        lock.lock();
1000        try {
1001            receive(tx, block, blockType, false);
1002        } finally {
1003            lock.unlock();
1004        }
1005    }
1006
1007    private void receive(Transaction tx, StoredBlock block, BlockChain.NewBlockType blockType, boolean reorg) throws VerificationException {
1008        // Runs in a peer thread.
1009        checkState(lock.isLocked());
1010        BigInteger prevBalance = getBalance();
1011        Sha256Hash txHash = tx.getHash();
1012        boolean bestChain = blockType == BlockChain.NewBlockType.BEST_CHAIN;
1013        boolean sideChain = blockType == BlockChain.NewBlockType.SIDE_CHAIN;
1014
1015        BigInteger valueSentFromMe = tx.getValueSentFromMe(this);
1016        BigInteger valueSentToMe = tx.getValueSentToMe(this);
1017        BigInteger valueDifference = valueSentToMe.subtract(valueSentFromMe);
1018
1019        log.info("Received tx {} for {} BTC: {} in block {}", new Object[]{sideChain ? "on a side chain" : "",
1020                bitcoinValueToFriendlyString(valueDifference), tx.getHashAsString(),
1021                block != null ? block.getHeader().getHash() : "(unit test)"});
1022
1023        onWalletChangedSuppressions++;
1024
1025        // If this transaction is already in the wallet we may need to move it into a different pool. At the very
1026        // least we need to ensure we're manipulating the canonical object rather than a duplicate.
1027        Transaction wtx;
1028        if ((wtx = pending.remove(txHash)) != null) {
1029            log.info("  <-pending");
1030            // Make sure "tx" is always the canonical object we want to manipulate, send to event handlers, etc.
1031            tx = wtx;
1032        }
1033        boolean wasPending = wtx != null;
1034
1035        if (bestChain) {
1036            if (wasPending) {
1037                // Was pending and is now confirmed. Disconnect the outputs in case we spent any already: they will be
1038                // re-connected by processTxFromBestChain below.
1039                for (TransactionOutput output : tx.getOutputs()) {
1040                    final TransactionInput spentBy = output.getSpentBy();
1041                    if (spentBy != null) spentBy.disconnect();
1042                }
1043            }
1044            // TODO: This can trigger tx confidence listeners to be run in the case of double spends.
1045            // We should delay the execution of the listeners until the bottom to avoid the wallet mutating.
1046            processTxFromBestChain(tx);
1047        } else {
1048            checkState(sideChain);
1049            // Transactions that appear in a side chain will have that appearance recorded below - we assume that
1050            // some miners are also trying to include the transaction into the current best chain too, so let's treat
1051            // it as pending, except we don't need to do any risk analysis on it.
1052            if (wasPending) {
1053                // Just put it back in without touching the connections.
1054                addWalletTransaction(Pool.PENDING, tx);
1055            } else {
1056                // Ignore the case where a tx appears on a side chain at the same time as the best chain (this is
1057                // quite normal and expected).
1058                Sha256Hash hash = tx.getHash();
1059                if (!unspent.containsKey(hash) && !spent.containsKey(hash)) {
1060                    // Otherwise put it (possibly back) into pending.
1061                    // Committing it updates the spent flags and inserts into the pool as well.
1062                    tx.getConfidence().setConfidenceType(ConfidenceType.PENDING);
1063                    commitTx(tx);
1064                }
1065            }
1066        }
1067
1068        if (block != null) {
1069            // Mark the tx as appearing in this block so we can find it later after a re-org. This also tells the tx
1070            // confidence object about the block and sets its work done/depth appropriately.
1071            // TODO: This can trigger re-entrancy: delay running confidence listeners.
1072            tx.setBlockAppearance(block, bestChain);
1073            if (bestChain) {
1074                // Don't notify this tx of work done in notifyNewBestBlock which will be called immediately after
1075                // this method has been called by BlockChain for all relevant transactions. Otherwise we'd double
1076                // count.
1077                ignoreNextNewBlock.add(txHash);
1078            }
1079        }
1080
1081        // Inform anyone interested that we have received or sent coins but only if:
1082        //  - This is not due to a re-org.
1083        //  - The coins appeared on the best chain.
1084        //  - We did in fact receive some new money.
1085        //  - We have not already informed the user about the coins when we received the tx broadcast, or for our
1086        //    own spends. If users want to know when a broadcast tx becomes confirmed, they need to use tx confidence
1087        //    listeners.
1088        if (!reorg && bestChain && !wasPending) {
1089            BigInteger newBalance = getBalance();  // This is slow.
1090            log.info("Balance is now: " + bitcoinValueToFriendlyString(newBalance));
1091            int diff = valueDifference.compareTo(BigInteger.ZERO);
1092            // We pick one callback based on the value difference, though a tx can of course both send and receive
1093            // coins from the wallet.
1094            if (diff > 0) {
1095                invokeOnCoinsReceived(tx, prevBalance, newBalance);
1096            } else if (diff < 0) {
1097                invokeOnCoinsSent(tx, prevBalance, newBalance);
1098            } else {
1099                // We have a transaction that didn't change our balance. Probably we sent coins between our own keys.
1100                invokeOnWalletChanged();
1101            }
1102        }
1103
1104        // Wallet change notification will be sent shortly after the block is finished processing, in notifyNewBestBlock
1105        onWalletChangedSuppressions--;
1106
1107        checkState(isConsistent());
1108        queueAutoSave();
1109    }
1110
1111    /**
1112     * <p>Called by the {@link BlockChain} when a new block on the best chain is seen, AFTER relevant wallet
1113     * transactions are extracted and sent to us UNLESS the new block caused a re-org, in which case this will
1114     * not be called (the {@link Wallet#reorganize(StoredBlock, java.util.List, java.util.List)} method will
1115     * call this one in that case).</p>
1116     * <p/>
1117     * <p>Used to update confidence data in each transaction and last seen block hash. Triggers auto saving.
1118     * Invokes the onWalletChanged event listener if there were any affected transactions.</p>
1119     */
1120    public void notifyNewBestBlock(StoredBlock block) throws VerificationException {
1121        // Check to see if this block has been seen before.
1122        Sha256Hash newBlockHash = block.getHeader().getHash();
1123        if (newBlockHash.equals(getLastBlockSeenHash()))
1124            return;
1125        lock.lock();
1126        try {
1127            // Store the new block hash.
1128            setLastBlockSeenHash(newBlockHash);
1129            setLastBlockSeenHeight(block.getHeight());
1130            // TODO: Clarify the code below.
1131            // Notify all the BUILDING transactions of the new block.
1132            // This is so that they can update their work done and depth.
1133            onWalletChangedSuppressions++;
1134            Set<Transaction> transactions = getTransactions(true);
1135            for (Transaction tx : transactions) {
1136                if (ignoreNextNewBlock.contains(tx.getHash())) {
1137                    // tx was already processed in receive() due to it appearing in this block, so we don't want to
1138                    // notify the tx confidence of work done twice, it'd result in miscounting.
1139                    ignoreNextNewBlock.remove(tx.getHash());
1140                } else {
1141                    tx.getConfidence().notifyWorkDone(block.getHeader());
1142                }
1143            }
1144            queueAutoSave();
1145            onWalletChangedSuppressions--;
1146            invokeOnWalletChanged();
1147        } finally {
1148            lock.unlock();
1149        }
1150    }
1151
1152    /**
1153     * Handle when a transaction becomes newly active on the best chain, either due to receiving a new block or a
1154     * re-org. Places the tx into the right pool, handles coinbase transactions, handles double-spends and so on.
1155     */
1156    private void processTxFromBestChain(Transaction tx) throws VerificationException {
1157        checkState(lock.isLocked());
1158        checkState(!pending.containsKey(tx.getHash()));
1159
1160        // This TX may spend our existing outputs even though it was not pending. This can happen in unit
1161        // tests, if keys are moved between wallets, if we're catching up to the chain given only a set of keys,
1162        // or if a dead coinbase transaction has moved back onto the main chain.
1163        boolean isDeadCoinbase = tx.isCoinBase() && dead.containsKey(tx.getHash());
1164        if (isDeadCoinbase) {
1165            // There is a dead coinbase tx being received on the best chain. A coinbase tx is made dead when it moves
1166            // to a side chain but it can be switched back on a reorg and 'resurrected' back to spent or unspent.
1167            // So take it out of the dead pool.
1168            log.info("  coinbase tx {} <-dead: confidence {}", tx.getHashAsString(),
1169                    tx.getConfidence().getConfidenceType().name());
1170            dead.remove(tx.getHash());
1171        }
1172
1173        // Update tx and other unspent/pending transactions by connecting inputs/outputs.
1174        updateForSpends(tx, true);
1175
1176        // Now make sure it ends up in the right pool. Also, handle the case where this TX is double-spending
1177        // against our pending transactions. Note that a tx may double spend our pending transactions and also send
1178        // us money/spend our money.
1179        boolean hasOutputsToMe = tx.getValueSentToMe(this, true).compareTo(BigInteger.ZERO) > 0;
1180        if (hasOutputsToMe) {
1181            // Needs to go into either unspent or spent (if the outputs were already spent by a pending tx).
1182            if (tx.isEveryOwnedOutputSpent(this)) {
1183                log.info("  tx {} ->spent (by pending)", tx.getHashAsString());
1184                addWalletTransaction(Pool.SPENT, tx);
1185            } else {
1186                log.info("  tx {} ->unspent", tx.getHashAsString());
1187                addWalletTransaction(Pool.UNSPENT, tx);
1188            }
1189        } else if (tx.getValueSentFromMe(this).compareTo(BigInteger.ZERO) > 0) {
1190            // Didn't send us any money, but did spend some. Keep it around for record keeping purposes.
1191            log.info("  tx {} ->spent", tx.getHashAsString());
1192            addWalletTransaction(Pool.SPENT, tx);
1193        }
1194
1195        checkForDoubleSpendAgainstPending(tx, true);
1196    }
1197
1198    /**
1199     * <p>Updates the wallet by checking if this TX spends any of our outputs, and marking them as spent if so. If
1200     * fromChain is true, also checks to see if any pending transaction spends outputs of this transaction and marks
1201     * the spent flags appropriately.</p>
1202     *
1203     * <p>It can be called in two contexts. One is when we receive a transaction on the best chain but it wasn't pending,
1204     * this most commonly happens when we have a set of keys but the wallet transactions were wiped and we are catching
1205     * up with the block chain. It can also happen if a block includes a transaction we never saw at broadcast time.
1206     * If this tx double spends, it takes precedence over our pending transactions and the pending tx goes dead.</p>
1207     *
1208     * <p>The other context it can be called is from {@link Wallet#receivePending(Transaction, java.util.List)},
1209     * ie we saw a tx be broadcast or one was submitted directly that spends our own coins. If this tx double spends
1210     * it does NOT take precedence because the winner will be resolved by the miners - we assume that our version will
1211     * win, if we are wrong then when a block appears the tx will go dead.</p>
1212     *
1213     * @param tx The transaction which is being updated.
1214     * @param fromChain If true, the tx appeared on the current best chain, if false it was pending.
1215     */
1216    private void updateForSpends(Transaction tx, boolean fromChain) throws VerificationException {
1217        checkState(lock.isLocked());
1218        if (fromChain)
1219            checkState(!pending.containsKey(tx.getHash()));
1220        for (TransactionInput input : tx.getInputs()) {
1221            TransactionInput.ConnectionResult result = input.connect(unspent, TransactionInput.ConnectMode.ABORT_ON_CONFLICT);
1222            if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
1223                // Not found in the unspent map. Try again with the spent map.
1224                result = input.connect(spent, TransactionInput.ConnectMode.ABORT_ON_CONFLICT);
1225                if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
1226                    // Not found in the unspent and spent maps. Try again with the pending map.
1227                    result = input.connect(pending, TransactionInput.ConnectMode.ABORT_ON_CONFLICT);
1228                    if (result == TransactionInput.ConnectionResult.NO_SUCH_TX) {
1229                        // Doesn't spend any of our outputs or is coinbase.
1230                        continue;
1231                    }
1232                }
1233            }
1234
1235            if (result == TransactionInput.ConnectionResult.ALREADY_SPENT) {
1236                if (fromChain) {
1237                    // Double spend from chain: this will be handled later by checkForDoubleSpendAgainstPending.
1238                } else {
1239                    // We saw two pending transactions that double spend each other. We don't know which will win.
1240                    // This should not happen.
1241                    log.warn("Saw two pending transactions double spend each other: {} vs {}",
1242                            tx.getHash(), input.getConnectedOutput().getSpentBy().getParentTransaction().getHash());
1243                    log.warn("  offending input is input {}", tx.getInputs().indexOf(input));
1244                }
1245            } else if (result == TransactionInput.ConnectionResult.SUCCESS) {
1246                // Otherwise we saw a transaction spend our coins, but we didn't try and spend them ourselves yet.
1247                // The outputs are already marked as spent by the connect call above, so check if there are any more for
1248                // us to use. Move if not.
1249                Transaction connected = checkNotNull(input.getOutpoint().fromTx);
1250                maybeMovePool(connected, "prevtx");
1251            }
1252        }
1253        // Now check each output and see if there is a pending transaction which spends it. This shouldn't normally
1254        // ever occur because we expect transactions to arrive in temporal order, but this assumption can be violated
1255        // when we receive a pending transaction from the mempool that is relevant to us, which spends coins that we
1256        // didn't see arrive on the best chain yet. For instance, because of a chain replay or because of our keys were
1257        // used by another wallet somewhere else.
1258        if (fromChain) {
1259            for (Transaction pendingTx : pending.values()) {
1260                for (TransactionInput input : pendingTx.getInputs()) {
1261                    TransactionInput.ConnectionResult result = input.connect(tx, TransactionInput.ConnectMode.ABORT_ON_CONFLICT);
1262                    // This TX is supposed to have just appeared on the best chain, so its outputs should not be marked
1263                    // as spent yet. If they are, it means something is happening out of order.
1264                    checkState(result != TransactionInput.ConnectionResult.ALREADY_SPENT);
1265                    if (result == TransactionInput.ConnectionResult.SUCCESS) {
1266                        log.info("Connected pending tx input {}:{}",
1267                                pendingTx.getHashAsString(), pendingTx.getInputs().indexOf(input));
1268                    }
1269                }
1270                // If the transactions outputs are now all spent, it will be moved into the spent pool by the
1271                // processTxFromBestChain method.
1272            }
1273        }
1274    }
1275
1276    // Updates the wallet when a double spend occurs.
1277    private void killTx(Transaction overridingTx, TransactionInput overridingInput, Transaction killedTx) {
1278        final Sha256Hash killedTxHash = killedTx.getHash();
1279        if (overridingTx == null) {
1280            // killedTx depended on a transaction that died because it was double spent or a coinbase that got re-orgd.
1281            killedTx.getConfidence().setOverridingTransaction(null);
1282            pending.remove(killedTxHash);
1283            unspent.remove(killedTxHash);
1284            spent.remove(killedTxHash);
1285            addWalletTransaction(Pool.DEAD, killedTx);
1286            // TODO: Properly handle the recursive nature of killing transactions here.
1287            return;
1288        }
1289        TransactionOutPoint overriddenOutPoint = overridingInput.getOutpoint();
1290        // It is expected that we may not have the overridden/double-spent tx in our wallet ... in the (common?!) case
1291        // where somebody is stealing money from us, the overriden tx belongs to someone else.
1292        log.warn("Saw double spend of {} from chain override pending tx {}",
1293                overriddenOutPoint, killedTx.getHashAsString());
1294        log.warn("  <-pending ->dead   killed by {}", overridingTx.getHashAsString());
1295        pending.remove(killedTxHash);
1296        addWalletTransaction(Pool.DEAD, killedTx);
1297        log.info("Disconnecting inputs of the newly dead tx");
1298        for (TransactionInput deadInput : killedTx.getInputs()) {
1299            Transaction connected = deadInput.getOutpoint().fromTx;
1300            if (connected == null) continue;
1301            deadInput.disconnect();
1302            maybeMovePool(connected, "kill");
1303        }
1304        // Try and connect the overriding input to something in our wallet. It's expected that this will mostly fail
1305        // because when somebody else is double-spending away a payment they made to us, we won't have the overridden
1306        // tx as it's not ours to begin with. It'll only be found if we're double spending our own payments.
1307        log.info("Trying to connect overriding tx back");
1308        TransactionInput.ConnectionResult result = overridingInput.connect(unspent, TransactionInput.ConnectMode.DISCONNECT_ON_CONFLICT);
1309        if (result == TransactionInput.ConnectionResult.SUCCESS) {
1310            maybeMovePool(overridingInput.getOutpoint().fromTx, "kill");
1311        } else {
1312            result = overridingInput.connect(spent, TransactionInput.ConnectMode.DISCONNECT_ON_CONFLICT);
1313            if (result == TransactionInput.ConnectionResult.SUCCESS) {
1314                maybeMovePool(overridingInput.getOutpoint().fromTx, "kill");
1315            }
1316        }
1317        log.info("Informing tx listeners of double spend event");
1318        killedTx.getConfidence().setOverridingTransaction(overridingTx);  // RE-ENTRY POINT
1319        // TODO: Recursively kill other transactions that were double spent.
1320    }
1321
1322    /**
1323     * If the transactions outputs are all marked as spent, and it's in the unspent map, move it.
1324     * If the owned transactions outputs are not all marked as spent, and it's in the spent map, move it.
1325     */
1326    private void maybeMovePool(Transaction tx, String context) {
1327        checkState(lock.isLocked());
1328        if (tx.isEveryOwnedOutputSpent(this)) {
1329            // There's nothing left I can spend in this transaction.
1330            if (unspent.remove(tx.getHash()) != null) {
1331                if (log.isInfoEnabled()) {
1332                    log.info("  {} {} <-unspent ->spent", tx.getHashAsString(), context);
1333                }
1334                spent.put(tx.getHash(), tx);
1335            }
1336        } else {
1337            if (spent.remove(tx.getHash()) != null) {
1338                if (log.isInfoEnabled()) {
1339                    log.info("  {} {} <-spent ->unspent", tx.getHashAsString(), context);
1340                }
1341                unspent.put(tx.getHash(), tx);
1342            }
1343        }
1344    }
1345
1346    /**
1347     * Adds an event listener object. Methods on this object are called when something interesting happens,
1348     * like receiving money.
1349     */
1350    public void addEventListener(WalletEventListener listener) {
1351        eventListeners.add(listener);
1352    }
1353
1354    /**
1355     * Removes the given event listener object. Returns true if the listener was removed, false if that listener
1356     * was never added.
1357     */
1358    public boolean removeEventListener(WalletEventListener listener) {
1359        return eventListeners.remove(listener);
1360    }
1361
1362    /**
1363     * Calls {@link Wallet#commitTx} if tx is not already in the pending pool
1364     *
1365     * @return true if the tx was added to the wallet, or false if it was already in the pending pool
1366     */
1367    public boolean maybeCommitTx(Transaction tx) throws VerificationException {
1368        tx.verify();
1369        lock.lock();
1370        try {
1371            if (pending.containsKey(tx.getHash()))
1372                return false;
1373            log.info("commitTx of {}", tx.getHashAsString());
1374            BigInteger balance = getBalance();
1375            tx.setUpdateTime(Utils.now());
1376            // Mark the outputs we're spending as spent so we won't try and use them in future creations. This will also
1377            // move any transactions that are now fully spent to the spent map so we can skip them when creating future
1378            // spends.
1379            updateForSpends(tx, false);
1380            // Add to the pending pool. It'll be moved out once we receive this transaction on the best chain.
1381            // This also registers txConfidenceListener so wallet listeners get informed.
1382            log.info("->pending: {}", tx.getHashAsString());
1383            addWalletTransaction(Pool.PENDING, tx);
1384
1385            // Event listeners may re-enter so we cannot make assumptions about wallet state after this loop completes.
1386            try {
1387                BigInteger valueSentFromMe = tx.getValueSentFromMe(this);
1388                BigInteger valueSentToMe = tx.getValueSentToMe(this);
1389                BigInteger newBalance = balance.add(valueSentToMe).subtract(valueSentFromMe);
1390                if (valueSentToMe.compareTo(BigInteger.ZERO) > 0)
1391                    invokeOnCoinsReceived(tx, balance, newBalance);
1392                if (valueSentFromMe.compareTo(BigInteger.ZERO) > 0)
1393                    invokeOnCoinsSent(tx, balance, newBalance);
1394
1395                invokeOnWalletChanged();
1396            } catch (ScriptException e) {
1397                // Cannot happen as we just created this transaction ourselves.
1398                throw new RuntimeException(e);
1399            }
1400
1401            checkState(isConsistent());
1402            queueAutoSave();
1403        } finally {
1404            lock.unlock();
1405        }
1406        return true;
1407    }
1408
1409    /**
1410     * <p>Updates the wallet with the given transaction: puts it into the pending pool, sets the spent flags and runs
1411     * the onCoinsSent/onCoinsReceived event listener. Used in two situations:</p>
1412     *
1413     * <ol>
1414     *     <li>When we have just successfully transmitted the tx we created to the network.</li>
1415     *     <li>When we receive a pending transaction that didn't appear in the chain yet, and we did not create it.</li>
1416     * </ol>
1417     *
1418     * <p>Triggers an auto save.</p>
1419     */
1420    public void commitTx(Transaction tx) throws VerificationException {
1421        checkArgument(maybeCommitTx(tx), "commitTx called on the same transaction twice");
1422    }
1423
1424    /**
1425     * Returns a set of all transactions in the wallet.
1426     * @param includeDead     If true, transactions that were overridden by a double spend are included.
1427     */
1428    public Set<Transaction> getTransactions(boolean includeDead) {
1429        lock.lock();
1430        try {
1431            Set<Transaction> all = new HashSet<Transaction>();
1432            all.addAll(unspent.values());
1433            all.addAll(spent.values());
1434            all.addAll(pending.values());
1435            if (includeDead)
1436                all.addAll(dead.values());
1437            return all;
1438        } finally {
1439            lock.unlock();
1440        }
1441    }
1442
1443    /**
1444     * Returns a set of all WalletTransactions in the wallet.
1445     */
1446    public Iterable<WalletTransaction> getWalletTransactions() {
1447        lock.lock();
1448        try {
1449            Set<WalletTransaction> all = new HashSet<WalletTransaction>();
1450            addWalletTransactionsToSet(all, Pool.UNSPENT, unspent.values());
1451            addWalletTransactionsToSet(all, Pool.SPENT, spent.values());
1452            addWalletTransactionsToSet(all, Pool.DEAD, dead.values());
1453            addWalletTransactionsToSet(all, Pool.PENDING, pending.values());
1454            return all;
1455        } finally {
1456            lock.unlock();
1457        }
1458    }
1459
1460    private static void addWalletTransactionsToSet(Set<WalletTransaction> txs,
1461                                                   Pool poolType, Collection<Transaction> pool) {
1462        for (Transaction tx : pool) {
1463            txs.add(new WalletTransaction(poolType, tx));
1464        }
1465    }
1466
1467    /**
1468     * Adds a transaction that has been associated with a particular wallet pool. This is intended for usage by
1469     * deserialization code, such as the {@link WalletProtobufSerializer} class. It isn't normally useful for
1470     * applications. It does not trigger auto saving.
1471     */
1472    public void addWalletTransaction(WalletTransaction wtx) {
1473        lock.lock();
1474        try {
1475            addWalletTransaction(wtx.getPool(), wtx.getTransaction());
1476        } finally {
1477            lock.unlock();
1478        }
1479    }
1480
1481    /**
1482     * Adds the given transaction to the given pools and registers a confidence change listener on it.
1483     */
1484    private void addWalletTransaction(Pool pool, Transaction tx) {
1485        checkState(lock.isLocked());
1486        switch (pool) {
1487        case UNSPENT:
1488            checkState(unspent.put(tx.getHash(), tx) == null);
1489            break;
1490        case SPENT:
1491            checkState(spent.put(tx.getHash(), tx) == null);
1492            break;
1493        case PENDING:
1494            checkState(pending.put(tx.getHash(), tx) == null);
1495            break;
1496        case DEAD:
1497            checkState(dead.put(tx.getHash(), tx) == null);
1498            break;
1499        case PENDING_INACTIVE:
1500            checkState(pending.put(tx.getHash(), tx) == null);
1501            break;
1502        default:
1503            throw new RuntimeException("Unknown wallet transaction type " + pool);
1504        }
1505        // This is safe even if the listener has been added before, as TransactionConfidence ignores duplicate
1506        // registration requests. That makes the code in the wallet simpler.
1507        tx.getConfidence().addEventListener(txConfidenceListener);
1508    }
1509
1510    /**
1511     * Returns all non-dead, active transactions ordered by recency.
1512     */
1513    public List<Transaction> getTransactionsByTime() {
1514        return getRecentTransactions(0, false);
1515    }
1516
1517    /**
1518     * Returns an list of N transactions, ordered by increasing age. Transactions on side chains are not included.
1519     * Dead transactions (overridden by double spends) are optionally included. <p>
1520     * <p/>
1521     * Note: the current implementation is O(num transactions in wallet). Regardless of how many transactions are
1522     * requested, the cost is always the same. In future, requesting smaller numbers of transactions may be faster
1523     * depending on how the wallet is implemented (eg if backed by a database).
1524     */
1525    public List<Transaction> getRecentTransactions(int numTransactions, boolean includeDead) {
1526        lock.lock();
1527        try {
1528            checkArgument(numTransactions >= 0);
1529            // Firstly, put all transactions into an array.
1530            int size = getPoolSize(Pool.UNSPENT) +
1531                    getPoolSize(Pool.SPENT) +
1532                    getPoolSize(Pool.PENDING);
1533            if (numTransactions > size || numTransactions == 0) {
1534                numTransactions = size;
1535            }
1536            ArrayList<Transaction> all = new ArrayList<Transaction>(getTransactions(includeDead));
1537            // Order by date.
1538            Collections.sort(all, Collections.reverseOrder(new Comparator<Transaction>() {
1539                public int compare(Transaction t1, Transaction t2) {
1540                    return t1.getUpdateTime().compareTo(t2.getUpdateTime());
1541                }
1542            }));
1543            if (numTransactions == all.size()) {
1544                return all;
1545            } else {
1546                all.subList(numTransactions, all.size()).clear();
1547                return all;
1548            }
1549        } finally {
1550            lock.unlock();
1551        }
1552    }
1553
1554    /**
1555     * Returns a transaction object given its hash, if it exists in this wallet, or null otherwise.
1556     */
1557    public Transaction getTransaction(Sha256Hash hash) {
1558        lock.lock();
1559        try {
1560            Transaction tx;
1561            if ((tx = pending.get(hash)) != null)
1562                return tx;
1563            else if ((tx = unspent.get(hash)) != null)
1564                return tx;
1565            else if ((tx = spent.get(hash)) != null)
1566                return tx;
1567            else if ((tx = dead.get(hash)) != null)
1568                return tx;
1569            return null;
1570        } finally {
1571            lock.unlock();
1572        }
1573    }
1574
1575    /**
1576     * Deletes transactions which appeared above the given block height from the wallet, but does not touch the keys.
1577     * This is useful if you have some keys and wish to replay the block chain into the wallet in order to pick them up.
1578     * Triggers auto saving.
1579     */
1580    public void clearTransactions(int fromHeight) {
1581        lock.lock();
1582        try {
1583            if (fromHeight == 0) {
1584                unspent.clear();
1585                spent.clear();
1586                pending.clear();
1587                dead.clear();
1588                queueAutoSave();
1589            } else {
1590                throw new UnsupportedOperationException();
1591            }
1592        } finally {
1593            lock.unlock();
1594        }
1595    }
1596
1597    EnumSet<Pool> getContainingPools(Transaction tx) {
1598        lock.lock();
1599        try {
1600            EnumSet<Pool> result = EnumSet.noneOf(Pool.class);
1601            Sha256Hash txHash = tx.getHash();
1602            if (unspent.containsKey(txHash)) {
1603                result.add(Pool.UNSPENT);
1604            }
1605            if (spent.containsKey(txHash)) {
1606                result.add(Pool.SPENT);
1607            }
1608            if (pending.containsKey(txHash)) {
1609                result.add(Pool.PENDING);
1610            }
1611            if (dead.containsKey(txHash)) {
1612                result.add(Pool.DEAD);
1613            }
1614            return result;
1615        } finally {
1616            lock.unlock();
1617        }
1618    }
1619
1620    int getPoolSize(WalletTransaction.Pool pool) {
1621        lock.lock();
1622        try {
1623            switch (pool) {
1624                case UNSPENT:
1625                    return unspent.size();
1626                case SPENT:
1627                    return spent.size();
1628                case PENDING:
1629                    return pending.size();
1630                case DEAD:
1631                    return dead.size();
1632                case ALL:
1633                    return unspent.size() + spent.size() + pending.size() + dead.size();
1634            }
1635            throw new RuntimeException("Unreachable");
1636        } finally {
1637            lock.unlock();
1638        }
1639    }
1640
1641    //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
1642    //
1643    //  SEND APIS
1644    //
1645    //////////////////////////////////////////////////////////////////////////////////////////////////////////////////
1646
1647    /** A SendResult is returned to you as part of sending coins to a recipient. */
1648    public static class SendResult {
1649        /** The Bitcoin transaction message that moves the money. */
1650        public Transaction tx;
1651        /** A future that will complete once the tx message has been successfully broadcast to the network. */
1652        public ListenableFuture<Transaction> broadcastComplete;
1653    }
1654
1655    /**
1656     * A SendRequest gives the wallet information about precisely how to send money to a recipient or set of recipients.
1657     * Static methods are provided to help you create SendRequests and there are a few helper methods on the wallet that
1658     * just simplify the most common use cases. You may wish to customize a SendRequest if you want to attach a fee or
1659     * modify the change address.
1660     */
1661    public static class SendRequest {
1662        /**
1663         * <p>A transaction, probably incomplete, that describes the outline of what you want to do. This typically will
1664         * mean it has some outputs to the intended destinations, but no inputs or change address (and therefore no
1665         * fees) - the wallet will calculate all that for you and update tx later.</p>
1666         *
1667         * <p>Be careful when adding outputs that you check the min output value
1668         * ({@link TransactionOutput#getMinNonDustValue(BigInteger)}) to avoid the whole transaction being rejected
1669         * because one output is dust.</p>
1670         *
1671         * <p>If there are already inputs to the transaction, make sure their out point has a connected output,
1672         * otherwise their value will be added to fee.  Also ensure they are either signed or are spendable by a wallet
1673         * key, otherwise the behavior of {@link Wallet#completeTx(Wallet.SendRequest)} is undefined (likely
1674         * RuntimeException).</p>
1675         */
1676        public Transaction tx;
1677
1678        /**
1679         * "Change" means the difference between the value gathered by a transactions inputs (the size of which you
1680         * don't really control as it depends on who sent you money), and the value being sent somewhere else. The
1681         * change address should be selected from this wallet, normally. <b>If null this will be chosen for you.</b>
1682         */
1683        public Address changeAddress = null;
1684
1685        /**
1686         * <p>A transaction can have a fee attached, which is defined as the difference between the input values
1687         * and output values. Any value taken in that is not provided to an output can be claimed by a miner. This
1688         * is how mining is incentivized in later years of the Bitcoin system when inflation drops. It also provides
1689         * a way for people to prioritize their transactions over others and is used as a way to make denial of service
1690         * attacks expensive.</p>
1691         *
1692         * <p>This is a constant fee (in satoshis) which will be added to the transaction. It is recommended that it be
1693         * at least {@link Transaction#REFERENCE_DEFAULT_MIN_TX_FEE} if it is set, as default reference clients will
1694         * otherwise simply treat the transaction as if there were no fee at all.</p>
1695         *
1696         * <p>Once {@link Wallet#completeTx(com.google.bitcoin.core.Wallet.SendRequest)} is called, this is set to the
1697         * value of the fee that was added.</p>
1698         *
1699         * <p>You might also consider adding a {@link SendRequest#feePerKb} to set the fee per kb of transaction size
1700         * (rounded down to the nearest kb) as that is how transactions are sorted when added to a block by miners.</p>
1701         */
1702        public BigInteger fee = null;
1703
1704        /**
1705         * <p>A transaction can have a fee attached, which is defined as the difference between the input values
1706         * and output values. Any value taken in that is not provided to an output can be claimed by a miner. This
1707         * is how mining is incentivized in later years of the Bitcoin system when inflation drops. It also provides
1708         * a way for people to prioritize their transactions over others and is used as a way to make denial of service
1709         * attacks expensive.</p>
1710         *
1711         * <p>This is a dynamic fee (in satoshis) which will be added to the transaction for each kilobyte in size after
1712         * the first. This is useful as as miners usually sort pending transactions by their fee per unit size when
1713         * choosing which transactions to add to a block. Note that, to keep this equivalent to the reference client
1714         * definition, a kilobyte is defined as 1000 bytes, not 1024.</p>
1715         *
1716         * <p>You might also consider using a {@link SendRequest#fee} to set the fee added for the first kb of size.</p>
1717         */
1718        public BigInteger feePerKb = DEFAULT_FEE_PER_KB;
1719
1720        /**
1721         * If you want to modify the default fee for your entire app without having to change each SendRequest you make,
1722         * you can do it here. This is primarily useful for unit tests.
1723         */
1724        public static BigInteger DEFAULT_FEE_PER_KB = Transaction.REFERENCE_DEFAULT_MIN_TX_FEE;
1725
1726        /**
1727         * <p>Requires that there be enough fee for a default reference client to at least relay the transaction.
1728         * (ie ensure the transaction will not be outright rejected by the network). Defaults to true, you should
1729         * only set this to false if you know what you're doing.</p>
1730         *
1731         * <p>Note that this does not enforce certain fee rules that only apply to transactions which are larger than
1732         * 26,000 bytes. If you get a transaction which is that large, you should set a fee and feePerKb of at least
1733         * {@link Transaction#REFERENCE_DEFAULT_MIN_TX_FEE}.</p>
1734         */
1735        public boolean ensureMinRequiredFee = true;
1736
1737        /**
1738         * The AES key to use to decrypt the private keys before signing.
1739         * If null then no decryption will be performed and if decryption is required an exception will be thrown.
1740         * You can get this from a password by doing wallet.getKeyCrypter().derivePassword(password).
1741         */
1742        public KeyParameter aesKey = null;
1743
1744        // Tracks if this has been passed to wallet.completeTx already: just a safety check.
1745        private boolean completed;
1746
1747        private SendRequest() {}
1748
1749        /**
1750         * <p>Creates a new SendRequest to the given address for the given value.</p>
1751         *
1752         * <p>Be very careful when value is smaller than {@link Transaction#MIN_NONDUST_OUTPUT} as the transaction will
1753         * likely be rejected by the network in this case.</p>
1754         */
1755        public static SendRequest to(Address destination, BigInteger value) {
1756            SendRequest req = new Wallet.SendRequest();
1757            req.tx = new Transaction(destination.getParameters());
1758            req.tx.addOutput(value, destination);
1759            return req;
1760        }
1761
1762        /**
1763         * <p>Creates a new SendRequest to the given pubkey for the given value.</p>
1764         *
1765         * <p>Be careful to check the output's value is reasonable using
1766         * {@link TransactionOutput#getMinNonDustValue(BigInteger)} afterwards or you risk having the transaction
1767         * rejected by the network. Note that using {@link SendRequest#to(Address, java.math.BigInteger)} will result
1768         * in a smaller output, and thus the ability to use a smaller output value without rejection.</p>
1769         */
1770        public static SendRequest to(NetworkParameters params, ECKey destination, BigInteger value) {
1771            SendRequest req = new SendRequest();
1772            req.tx = new Transaction(params);
1773            req.tx.addOutput(value, destination);
1774            return req;
1775        }
1776
1777        /** Simply wraps a pre-built incomplete transaction provided by you. */
1778        public static SendRequest forTx(Transaction tx) {
1779            SendRequest req = new SendRequest();
1780            req.tx = tx;
1781            return req;
1782        }
1783    }
1784
1785    /**
1786     * <p>Statelessly creates a transaction that sends the given value to address. The change is sent to
1787     * {@link Wallet#getChangeAddress()}, so you must have added at least one key.</p>
1788     *
1789     * <p>If you just want to send money quickly, you probably want
1790     * {@link Wallet#sendCoins(PeerGroup, Address, java.math.BigInteger)} instead. That will create the sending
1791     * transaction, commit to the wallet and broadcast it to the network all in one go. This method is lower level
1792     * and lets you see the proposed transaction before anything is done with it.</p>
1793     *
1794     * <p>This is a helper method that is equivalent to using {@link Wallet.SendRequest#to(Address, java.math.BigInteger)}
1795     * followed by {@link Wallet#completeTx(Wallet.SendRequest)} and returning the requests transaction object.
1796     * Note that this means a fee may be automatically added if required, if you want more control over the process,
1797     * just do those two steps yourself.</p>
1798     *
1799     * <p>IMPORTANT: This method does NOT update the wallet. If you call createSend again you may get two transactions
1800     * that spend the same coins. You have to call {@link Wallet#commitTx(Transaction)} on the created transaction to
1801     * prevent this, but that should only occur once the transaction has been accepted by the network. This implies
1802     * you cannot have more than one outstanding sending tx at once.</p>
1803     *
1804     * <p>You MUST ensure that nanocoins is smaller than {@link Transaction#MIN_NONDUST_OUTPUT} or the transaction will
1805     * almost certainly be rejected by the network as dust.</p>
1806     *
1807     * @param address       The Bitcoin address to send the money to.
1808     * @param nanocoins     How much currency to send, in nanocoins.
1809     * @return either the created Transaction or null if there are insufficient coins.
1810     * coins as spent until commitTx is called on the result.
1811     */
1812    public Transaction createSend(Address address, BigInteger nanocoins) {
1813        SendRequest req = SendRequest.to(address, nanocoins);
1814        if (completeTx(req)) {
1815            return req.tx;
1816        } else {
1817            return null;  // No money.
1818        }
1819    }
1820
1821    /**
1822     * Sends coins to the given address but does not broadcast the resulting pending transaction. It is still stored
1823     * in the wallet, so when the wallet is added to a {@link PeerGroup} or {@link Peer} the transaction will be
1824     * announced to the network. The given {@link SendRequest} is completed first using
1825     * {@link Wallet#completeTx(Wallet.SendRequest)} to make it valid.
1826     *
1827     * @return the Transaction that was created, or null if there are insufficient coins in the wallet.
1828     */
1829    public Transaction sendCoinsOffline(SendRequest request) {
1830        lock.lock();
1831        try {
1832            if (!completeTx(request))
1833                return null;  // Not enough money! :-(
1834            commitTx(request.tx);
1835            return request.tx;
1836        } catch (VerificationException e) {
1837            throw new RuntimeException(e);  // Cannot happen unless there's a bug, as we just created this ourselves.
1838        } finally {
1839            lock.unlock();
1840        }
1841    }
1842
1843    /**
1844     * <p>Sends coins to the given address, via the given {@link PeerGroup}. Change is returned to
1845     * {@link Wallet#getChangeAddress()}. Note that a fee may be automatically added if one may be required for the
1846     * transaction to be confirmed.</p>
1847     *
1848     * <p>The returned object provides both the transaction, and a future that can be used to learn when the broadcast
1849     * is complete. Complete means, if the PeerGroup is limited to only one connection, when it was written out to
1850     * the socket. Otherwise when the transaction is written out and we heard it back from a different peer.</p>
1851     *
1852     * <p>Note that the sending transaction is committed to the wallet immediately, not when the transaction is
1853     * successfully broadcast. This means that even if the network hasn't heard about your transaction you won't be
1854     * able to spend those same coins again.</p>
1855     *
1856     * <p>You MUST ensure that value is smaller than {@link Transaction#MIN_NONDUST_OUTPUT} or the transaction will
1857     * almost certainly be rejected by the network as dust.</p>
1858     *
1859     * @param peerGroup a PeerGroup to use for broadcast or null.
1860     * @param to        Which address to send coins to.
1861     * @param value     How much value to send. You can use Utils.toNanoCoins() to calculate this.
1862     * @return An object containing the transaction that was created, and a future for the broadcast of it.
1863     */
1864    public SendResult sendCoins(PeerGroup peerGroup, Address to, BigInteger value) {
1865        SendRequest request = SendRequest.to(to, value);
1866        return sendCoins(peerGroup, request);
1867    }
1868
1869    /**
1870     * <p>Sends coins according to the given request, via the given {@link PeerGroup}.</p>
1871     *
1872     * <p>The returned object provides both the transaction, and a future that can be used to learn when the broadcast
1873     * is complete. Complete means, if the PeerGroup is limited to only one connection, when it was written out to
1874     * the socket. Otherwise when the transaction is written out and we heard it back from a different peer.</p>
1875     *
1876     * <p>Note that the sending transaction is committed to the wallet immediately, not when the transaction is
1877     * successfully broadcast. This means that even if the network hasn't heard about your transaction you won't be
1878     * able to spend those same coins again.</p>
1879     *
1880     * @param peerGroup a PeerGroup to use for broadcast or null.
1881     * @param request the SendRequest that describes what to do, get one using static methods on SendRequest itself.
1882     * @return An object containing the transaction that was created, and a future for the broadcast of it.
1883     */
1884    public SendResult sendCoins(PeerGroup peerGroup, SendRequest request) {
1885        // Does not need to be synchronized as sendCoinsOffline is and the rest is all thread-local.
1886
1887        // Commit the TX to the wallet immediately so the spent coins won't be reused.
1888        // TODO: We should probably allow the request to specify tx commit only after the network has accepted it.
1889        Transaction tx = sendCoinsOffline(request);
1890        if (tx == null)
1891            return null;  // Not enough money.
1892        SendResult result = new SendResult();
1893        result.tx = tx;
1894        // The tx has been committed to the pending pool by this point (via sendCoinsOffline -> commitTx), so it has
1895        // a txConfidenceListener registered. Once the tx is broadcast the peers will update the memory pool with the
1896        // count of seen peers, the memory pool will update the transaction confidence object, that will invoke the
1897        // txConfidenceListener which will in turn invoke the wallets event listener onTransactionConfidenceChanged
1898        // method.
1899        result.broadcastComplete = peerGroup.broadcastTransaction(tx);
1900        return result;
1901    }
1902
1903    /**
1904     * Sends coins to the given address, via the given {@link Peer}. Change is returned to {@link Wallet#getChangeAddress()}.
1905     * If an exception is thrown by {@link Peer#sendMessage(Message)} the transaction is still committed, so the
1906     * pending transaction must be broadcast <b>by you</b> at some other time. Note that a fee may be automatically added
1907     * if one may be required for the transaction to be confirmed.
1908     *
1909     * @return The {@link Transaction} that was created or null if there was insufficient balance to send the coins.
1910     * @throws IOException if there was a problem broadcasting the transaction
1911     */
1912    public Transaction sendCoins(Peer peer, SendRequest request) throws IOException {
1913        Transaction tx = sendCoinsOffline(request);
1914        if (tx == null)
1915            return null;  // Not enough money.
1916        peer.sendMessage(tx);
1917        return tx;
1918    }
1919
1920    /**
1921     * Given a spend request containing an incomplete transaction, makes it valid by adding inputs and outputs according
1922     * to the instructions in the request. The transaction in the request is modified by this method, as is the fee
1923     * parameter.
1924     *
1925     * @param req a SendRequest that contains the incomplete transaction and details for how to make it valid.
1926     * @throws IllegalArgumentException if you try and complete the same SendRequest twice.
1927     * @return whether or not the requested send is affordable.
1928     */
1929    public boolean completeTx(SendRequest req) {
1930        lock.lock();
1931        try {
1932            Preconditions.checkArgument(!req.completed, "Given SendRequest has already been completed.");
1933            // Calculate the amount of value we need to import.
1934            BigInteger value = BigInteger.ZERO;
1935            for (TransactionOutput output : req.tx.getOutputs()) {
1936                value = value.add(output.getValue());
1937            }
1938            BigInteger totalOutput = value;
1939
1940            log.info("Completing send tx with {} outputs totalling {} (not including fees)",
1941                    req.tx.getOutputs().size(), bitcoinValueToFriendlyString(value));
1942
1943            // If any inputs have already been added, we don't need to get their value from wallet
1944            BigInteger totalInput = BigInteger.ZERO;
1945            for (TransactionInput input : req.tx.getInputs())
1946                if (input.getConnectedOutput() != null)
1947                    totalInput = totalInput.add(input.getConnectedOutput().getValue());
1948                else
1949                    log.warn("SendRequest transaction already has inputs but we don't know how much they are worth - they will be added to fee.");
1950            value = value.subtract(totalInput);
1951
1952            List<TransactionInput> originalInputs = new ArrayList<TransactionInput>(req.tx.getInputs());
1953
1954            // We need to know if we need to add an additional fee because one of our values are smaller than 0.01 BTC
1955            boolean needAtLeastReferenceFee = false;
1956            if (req.ensureMinRequiredFee) {
1957                for (TransactionOutput output : req.tx.getOutputs())
1958                    if (output.getValue().compareTo(Utils.CENT) < 0) {
1959                        needAtLeastReferenceFee = true;
1960                        break;
1961                    }
1962            }
1963
1964            // Calculate a list of ALL potential candidates for spending and then ask a coin selector to provide us
1965            // with the actual outputs that'll be used to gather the required amount of value. In this way, users
1966            // can customize coin selection policies.
1967            //
1968            // Note that this code is poorly optimized: the spend candidates only alter when transactions in the wallet
1969            // change - it could be pre-calculated and held in RAM, and this is probably an optimization worth doing.
1970            // Note that output.isMine(this) needs to test the keychain which is currently an array, so it's
1971            // O(candidate outputs ^ keychain.size())! There's lots of low hanging fruit here.
1972            LinkedList<TransactionOutput> candidates = calculateSpendCandidates(true);
1973            // This can throw InsufficientMoneyException.
1974            FeeCalculation feeCalculation;
1975            try {
1976                feeCalculation = new FeeCalculation(req, value, originalInputs, needAtLeastReferenceFee, candidates);
1977            } catch (InsufficientMoneyException e) {
1978                // TODO: Propagate this after 0.9 is released and stop returning a boolean.
1979                return false;
1980            }
1981            CoinSelection bestCoinSelection = feeCalculation.bestCoinSelection;
1982            TransactionOutput bestChangeOutput = feeCalculation.bestChangeOutput;
1983
1984            for (TransactionOutput output : bestCoinSelection.gathered)
1985                req.tx.addInput(output);
1986
1987            totalInput = totalInput.add(bestCoinSelection.valueGathered);
1988
1989            if (bestChangeOutput != null) {
1990                req.tx.addOutput(bestChangeOutput);
1991                totalOutput = totalOutput.add(bestChangeOutput.getValue());
1992                log.info("  with {} coins change", bitcoinValueToFriendlyString(bestChangeOutput.getValue()));
1993            }
1994            final BigInteger calculatedFee = totalInput.subtract(totalOutput);
1995            if (calculatedFee.compareTo(BigInteger.ZERO) > 0) {
1996                log.info("  with a fee of {}", bitcoinValueToFriendlyString(calculatedFee));
1997            }
1998
1999            // Now sign the inputs, thus proving that we are entitled to redeem the connected outputs.
2000            try {
2001                req.tx.signInputs(Transaction.SigHash.ALL, this, req.aesKey);
2002            } catch (ScriptException e) {
2003                // If this happens it means an output script in a wallet tx could not be understood. That should never
2004                // happen, if it does it means the wallet has got into an inconsistent state.
2005                throw new RuntimeException(e);
2006            }
2007
2008            // Check size.
2009            int size = req.tx.bitcoinSerialize().length;
2010            if (size > Transaction.MAX_STANDARD_TX_SIZE) {
2011                // TODO: Throw an unchecked protocol exception here.
2012                log.warn(String.format(
2013                        "Transaction could not be created without exceeding max size: %d vs %d",
2014                        size, Transaction.MAX_STANDARD_TX_SIZE));
2015                return false;
2016            }
2017
2018            // Label the transaction as being self created. We can use this later to spend its change output even before
2019            // the transaction is confirmed.
2020            req.tx.getConfidence().setConfidenceType(ConfidenceType.PENDING);
2021            req.tx.getConfidence().setSource(TransactionConfidence.Source.SELF);
2022            req.completed = true;
2023            req.fee = calculatedFee;
2024            log.info("  completed {} with {} inputs", req.tx.getHashAsString(), req.tx.getInputs().size());
2025            return true;
2026        } finally {
2027            lock.unlock();
2028        }
2029    }
2030
2031    private LinkedList<TransactionOutput> calculateSpendCandidates(boolean excludeImmatureCoinbases) {
2032        checkState(lock.isLocked());
2033        LinkedList<TransactionOutput> candidates = Lists.newLinkedList();
2034        for (Transaction tx : Iterables.concat(unspent.values(), pending.values())) {
2035            // Do not try and spend coinbases that were mined too recently, the protocol forbids it.
2036            if (excludeImmatureCoinbases && !tx.isMature()) continue;
2037            for (TransactionOutput output : tx.getOutputs()) {
2038                if (!output.isAvailableForSpending()) continue;
2039                if (!output.isMine(this)) continue;
2040                candidates.add(output);
2041            }
2042        }
2043        return candidates;
2044    }
2045
2046    /** Returns the address used for change outputs. Note: this will probably go away in future. */
2047    public Address getChangeAddress() {
2048        lock.lock();
2049        try {
2050            // For now let's just pick the first key in our keychain. In future we might want to do something else to
2051            // give the user better privacy here, eg in incognito mode.
2052            checkState(keychain.size() > 0, "Can't send value without an address to use for receiving change");
2053            ECKey first = keychain.get(0);
2054            return first.toAddress(params);
2055        } finally {
2056            lock.unlock();
2057        }
2058    }
2059
2060    /**
2061     * Adds the given ECKey to the wallet. There is currently no way to delete keys (that would result in coin loss).
2062     * If {@link Wallet#autosaveToFile(java.io.File, long, java.util.concurrent.TimeUnit, com.google.bitcoin.core.Wallet.AutosaveEventListener)}
2063     * has been called, triggers an auto save bypassing the normal coalescing delay and event handlers.
2064     * If the key already exists in the wallet, does nothing and returns false.
2065     */
2066    public boolean addKey(final ECKey key) {
2067        return addKeys(Lists.newArrayList(key)) == 1;
2068    }
2069
2070    /**
2071     * Adds the given keys to the wallet. There is currently no way to delete keys (that would result in coin loss).
2072     * If {@link Wallet#autosaveToFile(java.io.File, long, java.util.concurrent.TimeUnit, com.google.bitcoin.core.Wallet.AutosaveEventListener)}
2073     * has been called, triggers an auto save bypassing the normal coalescing delay and event handlers.
2074     * Returns the number of keys added, after duplicates are ignored. The onKeyAdded event will be called for each key
2075     * in the list that was not already present.
2076     */
2077    public int addKeys(final List<ECKey> keys) {
2078        int added = 0;
2079        lock.lock();
2080        try {
2081            // TODO: Consider making keys a sorted list or hashset so membership testing is faster.
2082            for (final ECKey key : keys) {
2083                if (keychain.contains(key)) continue;
2084
2085                // If the key has a keyCrypter that does not match the Wallet's then a KeyCrypterException is thrown.
2086                // This is done because only one keyCrypter is persisted per Wallet and hence all the keys must be homogenous.
2087                if (keyCrypter != null && keyCrypter.getUnderstoodEncryptionType() != EncryptionType.UNENCRYPTED) {
2088                    if (key.isEncrypted() && !keyCrypter.equals(key.getKeyCrypter())) {
2089                        throw new KeyCrypterException("Cannot add key " + key.toString() + " because the keyCrypter does not match the wallets. Keys must be homogenous.");
2090                    }
2091                }
2092                keychain.add(key);
2093                added++;
2094            }
2095            if (autosaveToFile != null) {
2096                autoSave();
2097            }
2098        } finally {
2099            lock.unlock();
2100        }
2101
2102        for (ECKey key : keys) {
2103            // TODO: Change this interface to be batch-oriented.
2104            for (WalletEventListener listener : eventListeners) {
2105                listener.onKeyAdded(key);
2106            }
2107        }
2108        return added;
2109    }
2110
2111    /**
2112     * Locates a keypair from the keychain given the hash of the public key. This is needed when finding out which
2113     * key we need to use to redeem a transaction output.
2114     *
2115     * @return ECKey object or null if no such key was found.
2116     */
2117    public ECKey findKeyFromPubHash(byte[] pubkeyHash) {
2118        lock.lock();
2119        try {
2120            for (ECKey key : keychain) {
2121                if (Arrays.equals(key.getPubKeyHash(), pubkeyHash)) return key;
2122            }
2123            return null;
2124        } finally {
2125            lock.unlock();
2126        }
2127    }
2128
2129    /** Returns true if the given key is in the wallet, false otherwise. Currently an O(N) operation. */
2130    public boolean hasKey(ECKey key) {
2131        lock.lock();
2132        try {
2133            return keychain.contains(key);
2134        } finally {
2135            lock.unlock();
2136        }
2137    }
2138
2139    /**
2140     * Returns true if this wallet contains a public key which hashes to the given hash.
2141     */
2142    public boolean isPubKeyHashMine(byte[] pubkeyHash) {
2143        return findKeyFromPubHash(pubkeyHash) != null;
2144    }
2145
2146    /**
2147     * Locates a keypair from the keychain given the raw public key bytes.
2148     * @return ECKey or null if no such key was found.
2149     */
2150    public ECKey findKeyFromPubKey(byte[] pubkey) {
2151        lock.lock();
2152        try {
2153            for (ECKey key : keychain) {
2154                if (Arrays.equals(key.getPubKey(), pubkey)) return key;
2155            }
2156            return null;
2157        } finally {
2158            lock.unlock();
2159        }
2160    }
2161
2162    /**
2163     * Returns true if this wallet contains a keypair with the given public key.
2164     */
2165    public boolean isPubKeyMine(byte[] pubkey) {
2166        return findKeyFromPubKey(pubkey) != null;
2167    }
2168
2169    /**
2170     * <p>It's possible to calculate a wallets balance from multiple points of view. This enum selects which
2171     * getBalance() should use.</p>
2172     *
2173     * <p>Consider a real-world example: you buy a snack costing $5 but you only have a $10 bill. At the start you have
2174     * $10 viewed from every possible angle. After you order the snack you hand over your $10 bill. From the
2175     * perspective of your wallet you have zero dollars (AVAILABLE). But you know in a few seconds the shopkeeper
2176     * will give you back $5 change so most people in practice would say they have $5 (ESTIMATED).</p>
2177     */
2178    public enum BalanceType {
2179        /**
2180         * Balance calculated assuming all pending transactions are in fact included into the best chain by miners.
2181         * This includes the value of immature coinbase transactions.
2182         */
2183        ESTIMATED,
2184
2185        /**
2186         * Balance that can be safely used to create new spends. This is whatever the default coin selector would
2187         * make available, which by default means transaction outputs with at least 1 confirmation and pending
2188         * transactions created by our own wallet which have been propagated across the network.
2189         */
2190        AVAILABLE
2191    }
2192
2193    /**
2194     * Returns the AVAILABLE balance of this wallet. See {@link BalanceType#AVAILABLE} for details on what this
2195     * means.
2196     */
2197    public BigInteger getBalance() {
2198        return getBalance(BalanceType.AVAILABLE);
2199    }
2200
2201    /**
2202     * Returns the balance of this wallet as calculated by the provided balanceType.
2203     */
2204    public BigInteger getBalance(BalanceType balanceType) {
2205        lock.lock();
2206        try {
2207            if (balanceType == BalanceType.AVAILABLE) {
2208                return getBalance(coinSelector);
2209            } else if (balanceType == BalanceType.ESTIMATED) {
2210                LinkedList<TransactionOutput> all = calculateSpendCandidates(false);
2211                BigInteger value = BigInteger.ZERO;
2212                for (TransactionOutput out : all) value = value.add(out.getValue());
2213                return value;
2214            } else {
2215                throw new AssertionError("Unknown balance type");  // Unreachable.
2216            }
2217        } finally {
2218            lock.unlock();
2219        }
2220    }
2221
2222    /**
2223     * Returns the balance that would be considered spendable by the given coin selector. Just asks it to select
2224     * as many coins as possible and returns the total.
2225     */
2226    public BigInteger getBalance(CoinSelector selector) {
2227        lock.lock();
2228        try {
2229            checkNotNull(selector);
2230            LinkedList<TransactionOutput> candidates = calculateSpendCandidates(true);
2231            CoinSelection selection = selector.select(NetworkParameters.MAX_MONEY, candidates);
2232            return selection.valueGathered;
2233        } finally {
2234            lock.unlock();
2235        }
2236    }
2237
2238    @Override
2239    public String toString() {
2240        return toString(false, null);
2241    }
2242
2243    /**
2244     * Formats the wallet as a human readable piece of text. Intended for debugging, the format is not meant to be
2245     * stable or human readable.
2246     * @param includePrivateKeys Whether raw private key data should be included.
2247     * @param chain If set, will be used to estimate lock times for block timelocked transactions.
2248     */
2249    public String toString(boolean includePrivateKeys, AbstractBlockChain chain) {
2250        lock.lock();
2251        try {
2252            StringBuilder builder = new StringBuilder();
2253            builder.append(String.format("Wallet containing %s BTC in:%n", bitcoinValueToFriendlyString(getBalance())));
2254            builder.append(String.format("  %d unspent transactions%n", unspent.size()));
2255            builder.append(String.format("  %d spent transactions%n", spent.size()));
2256            builder.append(String.format("  %d pending transactions%n", pending.size()));
2257            builder.append(String.format("  %d dead transactions%n", dead.size()));
2258            builder.append(String.format("Last seen best block: (%d) %s%n",
2259                    getLastBlockSeenHeight(), getLastBlockSeenHash()));
2260            if (this.keyCrypter != null) {
2261                builder.append(String.format("Encryption: %s%n", keyCrypter.toString()));
2262            }
2263            // Do the keys.
2264            builder.append("\nKeys:\n");
2265            for (ECKey key : keychain) {
2266                builder.append("  addr:");
2267                builder.append(key.toAddress(params));
2268                builder.append(" ");
2269                builder.append(includePrivateKeys ? key.toStringWithPrivate() : key.toString());
2270                builder.append("\n");
2271            }
2272            // Print the transactions themselves
2273            if (unspent.size() > 0) {
2274                builder.append("\nUNSPENT:\n");
2275                toStringHelper(builder, unspent, chain);
2276            }
2277            if (spent.size() > 0) {
2278                builder.append("\nSPENT:\n");
2279                toStringHelper(builder, spent, chain);
2280            }
2281            if (pending.size() > 0) {
2282                builder.append("\nPENDING:\n");
2283                toStringHelper(builder, pending, chain);
2284            }
2285            if (dead.size() > 0) {
2286                builder.append("\nDEAD:\n");
2287                toStringHelper(builder, dead, chain);
2288            }
2289            return builder.toString();
2290        } finally {
2291            lock.unlock();
2292        }
2293    }
2294
2295    private void toStringHelper(StringBuilder builder, Map<Sha256Hash, Transaction> transactionMap,
2296                                AbstractBlockChain chain) {
2297        checkState(lock.isLocked());
2298        for (Transaction tx : transactionMap.values()) {
2299            try {
2300                builder.append("Sends ");
2301                builder.append(Utils.bitcoinValueToFriendlyString(tx.getValueSentFromMe(this)));
2302                builder.append(" and receives ");
2303                builder.append(Utils.bitcoinValueToFriendlyString(tx.getValueSentToMe(this)));
2304                builder.append(", total value ");
2305                builder.append(Utils.bitcoinValueToFriendlyString(tx.getValue(this)));
2306                builder.append(".\n");
2307            } catch (ScriptException e) {
2308                // Ignore and don't print this line.
2309            }
2310            builder.append(tx.toString(chain));
2311        }
2312    }
2313
2314    /**
2315     * <p>Don't call this directly. It's not intended for API users.</p>
2316     *
2317     * <p>Called by the {@link BlockChain} when the best chain (representing total work done) has changed. This can
2318     * cause the number of confirmations of a transaction to go higher, lower, drop to zero and can even result in
2319     * a transaction going dead (will never confirm) due to a double spend.</p>
2320     *
2321     * <p>The oldBlocks/newBlocks lists are ordered height-wise from top first to bottom last.</p>
2322     */
2323    public void reorganize(StoredBlock splitPoint, List<StoredBlock> oldBlocks, List<StoredBlock> newBlocks) throws VerificationException {
2324        lock.lock();
2325        try {
2326            // This runs on any peer thread with the block chain locked.
2327            //
2328            // The reorganize functionality of the wallet is tested in ChainSplitTest.java
2329            //
2330            // receive() has been called on the block that is triggering the re-org before this is called, with type
2331            // of SIDE_CHAIN.
2332            //
2333            // Note that this code assumes blocks are not invalid - if blocks contain duplicated transactions,
2334            // transactions that double spend etc then we can calculate the incorrect result. This could open up
2335            // obscure DoS attacks if someone successfully mines a throwaway invalid block and feeds it to us, just
2336            // to try and corrupt the internal data structures. We should try harder to avoid this but it's tricky
2337            // because there are so many ways the block can be invalid.
2338
2339            // Map block hash to transactions that appear in it.
2340            Multimap<Sha256Hash, Transaction> mapBlockTx = ArrayListMultimap.create();
2341            for (Transaction tx : getTransactions(true)) {
2342                Collection<Sha256Hash> appearsIn = tx.getAppearsInHashes();
2343                if (appearsIn == null) continue;  // Pending.
2344                for (Sha256Hash block : appearsIn)
2345                    mapBlockTx.put(block, tx);
2346            }
2347
2348            List<Sha256Hash> oldBlockHashes = new ArrayList<Sha256Hash>(oldBlocks.size());
2349            log.info("Old part of chain (top to bottom):");
2350            for (StoredBlock b : oldBlocks) {
2351                log.info("  {}", b.getHeader().getHashAsString());
2352                oldBlockHashes.add(b.getHeader().getHash());
2353            }
2354            log.info("New part of chain (top to bottom):");
2355            for (StoredBlock b : newBlocks) {
2356                log.info("  {}", b.getHeader().getHashAsString());
2357            }
2358
2359            // Avoid spuriously informing the user of wallet changes whilst we're re-organizing. This also prevents the
2360            // user from modifying wallet contents (eg, trying to spend) whilst we're in the middle of the process.
2361            onWalletChangedSuppressions++;
2362
2363            Collections.reverse(newBlocks);  // Need bottom-to-top but we get top-to-bottom.
2364
2365            // For each block in the old chain, disconnect the transactions. It doesn't matter if
2366            // we don't do it in the exact ordering they appeared in the chain, all we're doing is ensuring all
2367            // the outputs are freed up so we can connect them back again in the next step.
2368            LinkedList<Transaction> oldChainTxns = Lists.newLinkedList();
2369            for (Sha256Hash blockHash : oldBlockHashes) {
2370                for (Transaction tx : mapBlockTx.get(blockHash)) {
2371                    final Sha256Hash txHash = tx.getHash();
2372                    if (tx.isCoinBase()) {
2373                        log.warn("Coinbase tx {} -> dead", tx.getHash());
2374                        // All the transactions that we have in our wallet which spent this coinbase are now invalid
2375                        // and will never confirm. Hopefully this should never happen - that's the point of the maturity
2376                        // rule that forbids spending of coinbase transactions for 100 blocks.
2377                        //
2378                        // This could be recursive, although of course because we don't have the full transaction
2379                        // graph we can never reliably kill all transactions we might have that were rooted in
2380                        // this coinbase tx. Some can just go pending forever, like the Satoshi client. However we
2381                        // can do our best.
2382                        //
2383                        // TODO: Is it better to try and sometimes fail, or not try at all?
2384                        killTx(null, null, tx);
2385                    } else {
2386                        for (TransactionOutput output : tx.getOutputs()) {
2387                            TransactionInput input = output.getSpentBy();
2388                            if (input != null) input.disconnect();
2389                        }
2390                        for (TransactionInput input : tx.getInputs()) {
2391                            input.disconnect();
2392                        }
2393                        oldChainTxns.add(tx);
2394                        unspent.remove(txHash);
2395                        spent.remove(txHash);
2396                        checkState(!pending.containsKey(txHash));
2397                        checkState(!dead.containsKey(txHash));
2398                    }
2399                }
2400            }
2401
2402            // Put all the disconnected transactions back into the pending pool and re-connect them.
2403            for (Transaction tx : oldChainTxns) {
2404                // Coinbase transactions on the old part of the chain are dead for good and won't come back unless
2405                // there's another re-org.
2406                if (tx.isCoinBase()) continue;
2407                log.info("  ->pending {}", tx.getHash());
2408                tx.getConfidence().setConfidenceType(ConfidenceType.PENDING);  // Wipe height/depth/work data.
2409                addWalletTransaction(Pool.PENDING, tx);
2410                updateForSpends(tx, false);
2411            }
2412
2413            // Note that dead transactions stay dead. Consider a chain that Finney attacks T1 and replaces it with
2414            // T2, so we move T1 into the dead pool. If there's now a re-org to a chain that doesn't include T2, it
2415            // doesn't matter - the miners deleted T1 from their mempool, will resurrect T2 and put that into the
2416            // mempool and so T1 is still seen as a losing double spend.
2417
2418            // The old blocks have contributed to the depth and work done for all the transactions in the
2419            // wallet that are in blocks up to and including the chain split block.
2420            // The total depth and work done is calculated here and then subtracted from the appropriate transactions.
2421            int depthToSubtract = oldBlocks.size();
2422            BigInteger workDoneToSubtract = BigInteger.ZERO;
2423            for (StoredBlock b : oldBlocks) {
2424                workDoneToSubtract = workDoneToSubtract.add(b.getHeader().getWork());
2425            }
2426            log.info("depthToSubtract = " + depthToSubtract + ", workDoneToSubtract = " + workDoneToSubtract);
2427            // Remove depthToSubtract and workDoneToSubtract from all transactions in the wallet except for pending.
2428            subtractDepthAndWorkDone(depthToSubtract, workDoneToSubtract, spent.values());
2429            subtractDepthAndWorkDone(depthToSubtract, workDoneToSubtract, unspent.values());
2430            subtractDepthAndWorkDone(depthToSubtract, workDoneToSubtract, dead.values());
2431
2432            // The effective last seen block is now the split point so set the lastSeenBlockHash.
2433            setLastBlockSeenHash(splitPoint.getHeader().getHash());
2434
2435            // For each block in the new chain, work forwards calling receive() and notifyNewBestBlock().
2436            // This will pull them back out of the pending pool, or if the tx didn't appear in the old chain and
2437            // does appear in the new chain, will treat it as such and possibly kill pending transactions that
2438            // conflict.
2439            for (StoredBlock block : newBlocks) {
2440                log.info("Replaying block {}", block.getHeader().getHashAsString());
2441                for (Transaction tx : mapBlockTx.get(block.getHeader().getHash())) {
2442                    log.info("  tx {}", tx.getHash());
2443                    try {
2444                        receive(tx, block, BlockChain.NewBlockType.BEST_CHAIN, true);
2445                    } catch (ScriptException e) {
2446                        throw new RuntimeException(e);  // Cannot happen as these blocks were already verified.
2447                    }
2448                }
2449                notifyNewBestBlock(block);
2450            }
2451            log.info("post-reorg balance is {}", Utils.bitcoinValueToFriendlyString(getBalance()));
2452            // Inform event listeners that a re-org took place. They should save the wallet at this point.
2453            invokeOnReorganize();
2454            onWalletChangedSuppressions--;
2455            invokeOnWalletChanged();
2456            checkState(isConsistent());
2457        } finally {
2458            lock.unlock();
2459        }
2460    }
2461
2462    /**
2463     * Subtract the supplied depth and work done from the given transactions.
2464     */
2465    private static void subtractDepthAndWorkDone(int depthToSubtract, BigInteger workDoneToSubtract,
2466                                                 Collection<Transaction> transactions) {
2467        for (Transaction tx : transactions) {
2468            if (tx.getConfidence().getConfidenceType() == ConfidenceType.BUILDING) {
2469                tx.getConfidence().setDepthInBlocks(tx.getConfidence().getDepthInBlocks() - depthToSubtract);
2470                tx.getConfidence().setWorkDone(tx.getConfidence().getWorkDone().subtract(workDoneToSubtract));
2471            }
2472        }
2473    }
2474
2475    /**
2476     * Returns an immutable view of the transactions currently waiting for network confirmations.
2477     */
2478    public Collection<Transaction> getPendingTransactions() {
2479        lock.lock();
2480        try {
2481            return Collections.unmodifiableCollection(pending.values());
2482        } finally {
2483            lock.unlock();
2484        }
2485    }
2486
2487    /**
2488     * Returns the earliest creation time of the keys in this wallet, in seconds since the epoch, ie the min of 
2489     * {@link com.google.bitcoin.core.ECKey#getCreationTimeSeconds()}. This can return zero if at least one key does
2490     * not have that data (was created before key timestamping was implemented). <p>
2491     *     
2492     * This method is most often used in conjunction with {@link PeerGroup#setFastCatchupTimeSecs(long)} in order to
2493     * optimize chain download for new users of wallet apps. Backwards compatibility notice: if you get zero from this
2494     * method, you can instead use the time of the first release of your software, as it's guaranteed no users will
2495     * have wallets pre-dating this time. <p>
2496     * 
2497     * If there are no keys in the wallet, the current time is returned.
2498     */
2499    public long getEarliestKeyCreationTime() {
2500        lock.lock();
2501        try {
2502            if (keychain.size() == 0) {
2503                return Utils.now().getTime() / 1000;
2504            }
2505            long earliestTime = Long.MAX_VALUE;
2506            for (ECKey key : keychain) {
2507                earliestTime = Math.min(key.getCreationTimeSeconds(), earliestTime);
2508            }
2509            return earliestTime;
2510        } finally {
2511            lock.unlock();
2512        }
2513    }
2514
2515    /** Returns the hash of the last seen best-chain block. */
2516    public Sha256Hash getLastBlockSeenHash() {
2517        lock.lock();
2518        try {
2519            return lastBlockSeenHash;
2520        } finally {
2521            lock.unlock();
2522        }
2523    }
2524
2525    public void setLastBlockSeenHash(Sha256Hash lastBlockSeenHash) {
2526        lock.lock();
2527        try {
2528            this.lastBlockSeenHash = lastBlockSeenHash;
2529        } finally {
2530            lock.unlock();
2531        }
2532    }
2533
2534    public void setLastBlockSeenHeight(int lastBlockSeenHeight) {
2535        lock.lock();
2536        try {
2537            this.lastBlockSeenHeight = lastBlockSeenHeight;
2538        } finally {
2539            lock.unlock();
2540        }
2541    }
2542
2543    /** Returns the height of the last seen best-chain block. Can be -1 if a wallet is old and doesn't have that data. */
2544    public int getLastBlockSeenHeight() {
2545        lock.lock();
2546        try {
2547            return lastBlockSeenHeight;
2548        } finally {
2549            lock.unlock();
2550        }
2551    }
2552
2553    /**
2554     * Convenience wrapper around {@link Wallet#encrypt(com.google.bitcoin.crypto.KeyCrypter,
2555     * org.spongycastle.crypto.params.KeyParameter)} which uses the default Scrypt key derivation algorithm and
2556     * parameters, derives a key from the given password and returns the created key.
2557     */
2558    public KeyParameter encrypt(CharSequence password) {
2559        checkNotNull(password);
2560        checkArgument(password.length() > 0);
2561        KeyCrypter scrypt = new KeyCrypterScrypt();
2562        KeyParameter derivedKey = scrypt.deriveKey(password);
2563        encrypt(scrypt, derivedKey);
2564        return derivedKey;
2565    }
2566
2567    /**
2568     * Encrypt the wallet using the KeyCrypter and the AES key. A good default KeyCrypter to use is
2569     * {@link com.google.bitcoin.crypto.KeyCrypterScrypt}.
2570     *
2571     * @param keyCrypter The KeyCrypter that specifies how to encrypt/ decrypt a key
2572     * @param aesKey AES key to use (normally created using KeyCrypter#deriveKey and cached as it is time consuming to create from a password)
2573     * @throws KeyCrypterException Thrown if the wallet encryption fails. If so, the wallet state is unchanged.
2574     */
2575    public void encrypt(KeyCrypter keyCrypter, KeyParameter aesKey) {
2576        lock.lock();
2577        try {
2578            checkNotNull(keyCrypter);
2579            checkState(getEncryptionType() == EncryptionType.UNENCRYPTED, "Wallet is already encrypted");
2580            // Create a new arraylist that will contain the encrypted keys
2581            ArrayList<ECKey> encryptedKeyChain = new ArrayList<ECKey>();
2582            for (ECKey key : keychain) {
2583                if (key.isEncrypted()) {
2584                    // Key is already encrypted - add as is.
2585                    encryptedKeyChain.add(key);
2586                } else {
2587                    // Encrypt the key.
2588                    ECKey encryptedKey = key.encrypt(keyCrypter, aesKey);
2589
2590                    // Check that the encrypted key can be successfully decrypted.
2591                    // This is done as it is a critical failure if the private key cannot be decrypted successfully
2592                    // (all bitcoin controlled by that private key is lost forever).
2593                    // For a correctly constructed keyCrypter the encryption should always be reversible so it is just being as cautious as possible.
2594                    if (!ECKey.encryptionIsReversible(key, encryptedKey, keyCrypter, aesKey)) {
2595                        // Abort encryption
2596                        throw new KeyCrypterException("The key " + key.toString() + " cannot be successfully decrypted after encryption so aborting wallet encryption.");
2597                    }
2598
2599                    encryptedKeyChain.add(encryptedKey);
2600                }
2601            }
2602
2603            // Now ready to use the encrypted keychain so go through the old keychain clearing all the unencrypted private keys.
2604            // (This is to avoid the possibility of key recovery from memory).
2605            for (ECKey key : keychain) {
2606                if (!key.isEncrypted()) {
2607                    key.clearPrivateKey();
2608                }
2609            }
2610
2611            // Replace the old keychain with the encrypted one.
2612            keychain = encryptedKeyChain;
2613
2614            // The wallet is now encrypted.
2615            this.keyCrypter = keyCrypter;
2616
2617            if (autosaveToFile != null) {
2618                autoSave();
2619            }
2620        } finally {
2621            lock.unlock();
2622        }
2623    }
2624
2625    /**
2626     * Decrypt the wallet with the wallets keyCrypter and AES key.
2627     *
2628     * @param aesKey AES key to use (normally created using KeyCrypter#deriveKey and cached as it is time consuming to create from a password)
2629     * @throws KeyCrypterException Thrown if the wallet decryption fails. If so, the wallet state is unchanged.
2630     */
2631    public void decrypt(KeyParameter aesKey) {
2632        lock.lock();
2633        try {
2634            // Check the wallet is already encrypted - you cannot decrypt an unencrypted wallet.
2635            checkState(getEncryptionType() != EncryptionType.UNENCRYPTED, "Wallet is already decrypted");
2636            // Check that the wallet keyCrypter is non-null.
2637            // This is set either at construction (if an encrypted wallet is created) or by wallet encryption.
2638            checkNotNull(keyCrypter);
2639
2640            // Create a new arraylist that will contain the decrypted keys
2641            ArrayList<ECKey> decryptedKeyChain = new ArrayList<ECKey>();
2642
2643            for (ECKey key : keychain) {
2644                // Decrypt the key.
2645                if (!key.isEncrypted()) {
2646                    // Not encrypted - add to chain as is.
2647                    decryptedKeyChain.add(key);
2648                } else {
2649                    ECKey decryptedECKey = key.decrypt(keyCrypter, aesKey);
2650                    decryptedKeyChain.add(decryptedECKey);
2651                }
2652            }
2653
2654            // Replace the old keychain with the unencrypted one.
2655            keychain = decryptedKeyChain;
2656
2657            // The wallet is now unencrypted.
2658            keyCrypter = null;
2659
2660            if (autosaveToFile != null) {
2661                autoSave();
2662            }
2663        } finally {
2664            lock.unlock();
2665        }
2666    }
2667
2668    /**
2669     * Create a new, random encrypted ECKey and add it to the wallet.
2670     *
2671     * @param keyCrypter The keyCrypter to use in encrypting the new key
2672     * @param aesKey The AES key to use to encrypt the new key
2673     * @return ECKey the new, encrypted ECKey
2674     */
2675    public ECKey addNewEncryptedKey(KeyCrypter keyCrypter, KeyParameter aesKey) {
2676        ECKey newKey = (new ECKey()).encrypt(checkNotNull(keyCrypter), checkNotNull(aesKey));
2677        addKey(newKey);
2678        return newKey;
2679    }
2680
2681    /**
2682     * <p>Convenience wrapper around {@link Wallet#addNewEncryptedKey(com.google.bitcoin.crypto.KeyCrypter,
2683     * org.spongycastle.crypto.params.KeyParameter)} which just derives the key afresh and uses the pre-set
2684     * keycrypter. The wallet must have been encrypted using one of the encrypt methods previously.</p>
2685     *
2686     * <p>Note that key derivation is deliberately very slow! So if you plan to add multiple keys, it can be
2687     * faster to use the other method instead and re-use the {@link KeyParameter} object instead.</p>
2688     */
2689    public ECKey addNewEncryptedKey(CharSequence password) {
2690        lock.lock();
2691        try {
2692            checkNotNull(keyCrypter, "Wallet is not encrypted, you must call encrypt() first.");
2693            return addNewEncryptedKey(keyCrypter, keyCrypter.deriveKey(password));
2694        } finally {
2695            lock.unlock();
2696        }
2697    }
2698
2699    /**
2700     *  Check whether the password can decrypt the first key in the wallet.
2701     *  This can be used to check the validity of an entered password.
2702     *
2703     *  @return boolean true if password supplied can decrypt the first private key in the wallet, false otherwise.
2704     */
2705    public boolean checkPassword(CharSequence password) {
2706        lock.lock();
2707        try {
2708            if (keyCrypter == null) {
2709                // The password cannot decrypt anything as the keyCrypter is null.
2710                return false;
2711            }
2712            return checkAESKey(keyCrypter.deriveKey(checkNotNull(password)));
2713        } finally {
2714            lock.unlock();
2715        }
2716    }
2717
2718    /**
2719     *  Check whether the AES key can decrypt the first encrypted key in the wallet.
2720     *
2721     *  @return boolean true if AES key supplied can decrypt the first encrypted private key in the wallet, false otherwise.
2722     */
2723    public boolean checkAESKey(KeyParameter aesKey) {
2724        lock.lock();
2725        try {
2726            // If no keys then cannot decrypt.
2727            if (!getKeys().iterator().hasNext())
2728                return false;
2729            // Find the first encrypted key in the wallet.
2730            ECKey firstEncryptedECKey = null;
2731            Iterator<ECKey> iterator = getKeys().iterator();
2732            while (iterator.hasNext() && firstEncryptedECKey == null) {
2733                ECKey loopECKey = iterator.next();
2734                if (loopECKey.isEncrypted()) {
2735                    firstEncryptedECKey = loopECKey;
2736                }
2737            }
2738            // There are no encrypted keys in the wallet.
2739            if (firstEncryptedECKey == null)
2740                return false;
2741            String originalAddress = firstEncryptedECKey.toAddress(getNetworkParameters()).toString();
2742            if (firstEncryptedECKey.isEncrypted() && firstEncryptedECKey.getEncryptedPrivateKey() != null) {
2743                try {
2744                    ECKey rebornKey = firstEncryptedECKey.decrypt(keyCrypter, aesKey);
2745
2746                    // Check that the decrypted private key's address is correct ie it decrypted accurately.
2747                    String rebornAddress = rebornKey.toAddress(getNetworkParameters()).toString();
2748                    return originalAddress.equals(rebornAddress);
2749                } catch (KeyCrypterException ede) {
2750                    // The AES key supplied is incorrect.
2751                    return false;
2752                }
2753            }
2754            return false;
2755        } finally {
2756            lock.unlock();
2757        }
2758    }
2759
2760    /**
2761     * Get the wallet's KeyCrypter.
2762     * (Used in encrypting/ decrypting an ECKey).
2763     */
2764    public KeyCrypter getKeyCrypter() {
2765        lock.lock();
2766        try {
2767            return keyCrypter;
2768        } finally {
2769            lock.unlock();
2770        }
2771    }
2772
2773    /**
2774     * Sets the wallet's KeyCrypter.
2775     * Note that this does not encrypt the wallet, and should only be used if the keyCrypter can not be included in the
2776     * constructor during initial wallet loading.
2777     * Note that if the keyCrypter was not properly set during wallet load, {@link Wallet#getEncryptionType()} and
2778     * {@link Wallet#isEncrypted()} will not return the correct results.
2779     */
2780    public void setKeyCrypter(KeyCrypter keyCrypter) {
2781        lock.lock();
2782        try {
2783            checkState(this.keyCrypter == null);
2784            this.keyCrypter = keyCrypter;
2785        } finally {
2786            lock.unlock();
2787        }
2788    }
2789
2790    /**
2791     * Get the type of encryption used for this wallet.
2792     *
2793     * (This is a convenience method - the encryption type is actually stored in the keyCrypter).
2794     */
2795    public EncryptionType getEncryptionType() {
2796        lock.lock();
2797        try {
2798            if (keyCrypter == null) {
2799                // Unencrypted wallet.
2800                return EncryptionType.UNENCRYPTED;
2801            } else {
2802                return keyCrypter.getUnderstoodEncryptionType();
2803            }
2804        } finally {
2805            lock.unlock();
2806        }
2807    }
2808
2809    /** Returns true if the wallet is encrypted using any scheme, false if not. */
2810    public boolean isEncrypted() {
2811        return getEncryptionType() != EncryptionType.UNENCRYPTED;
2812    }
2813
2814    /**
2815     * Get the version of the Wallet.
2816     * This is an int you can use to indicate which versions of wallets your code understands,
2817     * and which come from the future (and hence cannot be safely loaded).
2818     */
2819    public int getVersion() {
2820        return version;
2821    }
2822
2823    /**
2824     * Set the version number of the wallet. See {@link Wallet#getVersion()}.
2825     */
2826    public void setVersion(int version) {
2827        this.version = version;
2828    }
2829
2830    /**
2831     * Set the description of the wallet.
2832     * This is a Unicode encoding string typically entered by the user as descriptive text for the wallet.
2833     */
2834    public void setDescription(String description) {
2835        this.description = description;
2836    }
2837
2838    /**
2839     * Get the description of the wallet. See {@link Wallet#setDescription(String))}
2840     */
2841    public String getDescription() {
2842        return description;
2843    }
2844
2845    /**
2846     * Gets the number of elements that will be added to a bloom filter returned by getBloomFilter
2847     */
2848    public int getBloomFilterElementCount() {
2849        int size = getKeychainSize() * 2;
2850        for (Transaction tx : getTransactions(false)) {
2851            for (TransactionOutput out : tx.getOutputs()) {
2852                try {
2853                    if (out.isMine(this) && out.getScriptPubKey().isSentToRawPubKey())
2854                        size++;
2855                } catch (ScriptException e) {
2856                    throw new RuntimeException(e); // If it is ours, we parsed the script corectly, so this shouldn't happen
2857                }
2858            }
2859        }
2860        return size;
2861    }
2862    
2863    /**
2864     * Gets a bloom filter that contains all of the public keys from this wallet, and which will provide the given
2865     * false-positive rate. See the docs for {@link BloomFilter} for a brief explanation of anonymity when using filters.
2866     */
2867    public BloomFilter getBloomFilter(double falsePositiveRate) {
2868        return getBloomFilter(getBloomFilterElementCount(), falsePositiveRate, (long)(Math.random()*Long.MAX_VALUE));
2869    }
2870    
2871    /**
2872     * Gets a bloom filter that contains all of the public keys from this wallet,
2873     * and which will provide the given false-positive rate if it has size elements.
2874     * Keep in mind that you will get 2 elements in the bloom filter for each key in the wallet.
2875     * 
2876     * This is used to generate a BloomFilter which can be #{link BloomFilter.merge}d with another.
2877     * It could also be used if you have a specific target for the filter's size.
2878     * 
2879     * See the docs for {@link BloomFilter(int, double)} for a brief explanation of anonymity when using bloom filters.
2880     */
2881    public BloomFilter getBloomFilter(int size, double falsePositiveRate, long nTweak) {
2882        BloomFilter filter = new BloomFilter(size, falsePositiveRate, nTweak);
2883        lock.lock();
2884        try {
2885            for (ECKey key : keychain) {
2886                filter.insert(key.getPubKey());
2887                filter.insert(key.getPubKeyHash());
2888            }
2889        } finally {
2890            lock.unlock();
2891        }
2892        for (Transaction tx : getTransactions(false)) {
2893            for (int i = 0; i < tx.getOutputs().size(); i++) {
2894                TransactionOutput out = tx.getOutputs().get(i);
2895                try {
2896                    if (out.isMine(this) && out.getScriptPubKey().isSentToRawPubKey()) {
2897                        TransactionOutPoint outPoint = new TransactionOutPoint(params, i, tx);
2898                        filter.insert(outPoint.bitcoinSerialize());
2899                    }
2900                } catch (ScriptException e) {
2901                    throw new RuntimeException(e); // If it is ours, we parsed the script corectly, so this shouldn't happen
2902                }
2903            }
2904        }
2905        return filter;
2906    }
2907
2908    /** Returns the {@link CoinSelector} object which controls which outputs can be spent by this wallet. */
2909    public CoinSelector getCoinSelector() {
2910        lock.lock();
2911        try {
2912            return coinSelector;
2913        } finally {
2914            lock.unlock();
2915        }
2916    }
2917
2918    /**
2919     * A coin selector is responsible for choosing which outputs to spend when creating transactions. The default
2920     * selector implements a policy of spending transactions that appeared in the best chain and pending transactions
2921     * that were created by this wallet, but not others.
2922     */
2923    public void setCoinSelector(CoinSelector coinSelector) {
2924        lock.lock();
2925        try {
2926            this.coinSelector = coinSelector;
2927        } finally {
2928            lock.unlock();
2929        }
2930    }
2931
2932    /**
2933     * Convenience wrapper for <tt>setCoinSelector(Wallet.AllowUnconfirmedCoinSelector.get())</tt>. If this method
2934     * is called on the wallet then transactions will be used for spending regardless of their confidence. This can
2935     * be dangerous - only use this if you absolutely know what you're doing!
2936     */
2937    public void allowSpendingUnconfirmedTransactions() {
2938        setCoinSelector(Wallet.AllowUnconfirmedCoinSelector.get());
2939    }
2940
2941    /**
2942     * Returns a future that will complete when the balance of the given type is equal or larger to the given value.
2943     * If the wallet already has a large enough balance the future is returned in a pre-completed state. Note that this
2944     * method is not blocking, if you want to <i>actually</i> wait immediately, you have to call .get() on the result.
2945     */
2946    public ListenableFuture<BigInteger> getBalanceFuture(final BigInteger value, final BalanceType type) {
2947        final SettableFuture<BigInteger> future = SettableFuture.create();
2948        final BigInteger current = getBalance(type);
2949        if (current.compareTo(value) >= 0) {
2950            // Already have enough.
2951            future.set(current);
2952            return future;
2953        }
2954        addEventListener(new AbstractWalletEventListener() {
2955            private boolean done = false;
2956
2957            @Override
2958            public void onTransactionConfidenceChanged(Wallet wallet, Transaction tx) {
2959                check();
2960            }
2961
2962            private void check() {
2963                final BigInteger newBalance = getBalance(type);
2964                if (!done && newBalance.compareTo(value) >= 0) {
2965                    // Have enough now.
2966                    done = true;
2967                    removeEventListener(this);
2968                    future.set(newBalance);
2969                }
2970            }
2971
2972            @Override
2973            public void onCoinsReceived(Wallet w, Transaction t, BigInteger b1, BigInteger b2) {
2974                check();
2975            }
2976        });
2977        return future;
2978    }
2979
2980    /////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2981    //
2982    // Extensions to the wallet format.
2983
2984    /**
2985     * By providing an object implementing the {@link WalletExtension} interface, you can save and load arbitrary
2986     * additional data that will be stored with the wallet. Each extension is identified by an ID, so attempting to
2987     * add the same extension twice (or two different objects that use the same ID) will throw an IllegalStateException.
2988     */
2989    public void addExtension(WalletExtension extension) {
2990        String id = checkNotNull(extension).getWalletExtensionID();
2991        lock.lock();
2992        try {
2993            if (extensions.containsKey(id))
2994                throw new IllegalStateException("Cannot add two extensions with the same ID: " + id);
2995            extensions.put(id, extension);
2996            queueAutoSave();
2997        } finally {
2998            lock.unlock();
2999        }
3000    }
3001
3002    /**
3003     * Atomically adds extension or returns an existing extension if there is one with the same id alreadypresent.
3004     */
3005    public WalletExtension addOrGetExistingExtension(WalletExtension extension) {
3006        String id = checkNotNull(extension).getWalletExtensionID();
3007        lock.lock();
3008        try {
3009            WalletExtension previousExtension = extensions.get(id);
3010            if (previousExtension != null)
3011                return previousExtension;
3012            extensions.put(id, extension);
3013            queueAutoSave();
3014            return extension;
3015        } finally {
3016            lock.unlock();
3017        }
3018    }
3019
3020    /**
3021     * Either adds extension as a new extension or replaces the existing extension if one already exists with the same
3022     * id. This also triggers wallet auto-saving, so may be useful even when called with the same extension as is
3023     * already present.
3024     */
3025    public void addOrUpdateExtension(WalletExtension extension) {
3026        String id = checkNotNull(extension).getWalletExtensionID();
3027        lock.lock();
3028        try {
3029            extensions.put(id, extension);
3030            queueAutoSave();
3031        } finally {
3032            lock.unlock();
3033        }
3034    }
3035
3036    /** Returns a snapshot of all registered extension objects. The extensions themselves are not copied. */
3037    public Map<String, WalletExtension> getExtensions() {
3038        lock.lock();
3039        try {
3040            return ImmutableMap.copyOf(extensions);
3041        } finally {
3042            lock.unlock();
3043        }
3044    }
3045
3046    /////////////////////////////////////////////////////////////////////////////////////////////////////////////////
3047    //
3048    // Boilerplate for running event listeners - unlocks the wallet, runs, re-locks.
3049
3050    private void invokeOnTransactionConfidenceChanged(Transaction tx) {
3051        checkState(lock.isLocked());
3052        lock.unlock();
3053        try {
3054            for (WalletEventListener listener : eventListeners) {
3055                listener.onTransactionConfidenceChanged(this, tx);
3056            }
3057        } finally {
3058            lock.lock();
3059        }
3060    }
3061
3062    private int onWalletChangedSuppressions = 0;
3063    private void invokeOnWalletChanged() {
3064        // Don't invoke the callback in some circumstances, eg, whilst we are re-organizing or fiddling with
3065        // transactions due to a new block arriving. It will be called later instead.
3066        checkState(lock.isLocked());
3067        Preconditions.checkState(onWalletChangedSuppressions >= 0);
3068        if (onWalletChangedSuppressions > 0) return;
3069        lock.unlock();
3070        try {
3071            for (WalletEventListener listener : eventListeners) {
3072                listener.onWalletChanged(this);
3073            }
3074        } finally {
3075            lock.lock();
3076        }
3077    }
3078
3079    private void invokeOnCoinsReceived(Transaction tx, BigInteger balance, BigInteger newBalance) {
3080        checkState(lock.isLocked());
3081        lock.unlock();
3082        try {
3083            for (WalletEventListener listener : eventListeners) {
3084                listener.onCoinsReceived(Wallet.this, tx, balance, newBalance);
3085            }
3086        } finally {
3087            lock.lock();
3088        }
3089    }
3090
3091    private void invokeOnCoinsSent(Transaction tx, BigInteger prevBalance, BigInteger newBalance) {
3092        checkState(lock.isLocked());
3093        lock.unlock();
3094        try {
3095            for (WalletEventListener listener : eventListeners) {
3096                listener.onCoinsSent(Wallet.this, tx, prevBalance, newBalance);
3097            }
3098        } finally {
3099            lock.lock();
3100        }
3101    }
3102
3103    private void invokeOnReorganize() {
3104        checkState(lock.isLocked());
3105        lock.unlock();
3106        try {
3107            for (WalletEventListener listener : eventListeners) {
3108                listener.onReorganize(Wallet.this);
3109            }
3110        } finally {
3111            lock.lock();
3112        }
3113    }
3114
3115    private class FeeCalculation {
3116        private CoinSelection bestCoinSelection;
3117        private TransactionOutput bestChangeOutput;
3118
3119        public FeeCalculation(SendRequest req, BigInteger value, List<TransactionInput> originalInputs,
3120                              boolean needAtLeastReferenceFee, LinkedList<TransactionOutput> candidates) throws InsufficientMoneyException {
3121            // There are 3 possibilities for what adding change might do:
3122            // 1) No effect
3123            // 2) Causes increase in fee (change < 0.01 COINS)
3124            // 3) Causes the transaction to have a dust output or change < fee increase (ie change will be thrown away)
3125            // If we get either of the last 2, we keep note of what the inputs looked like at the time and try to
3126            // add inputs as we go up the list (keeping track of minimum inputs for each category).  At the end, we pick
3127            // the best input set as the one which generates the lowest total fee.
3128            BigInteger additionalValueForNextCategory = null;
3129            CoinSelection selection3 = null;
3130            CoinSelection selection2 = null;
3131            TransactionOutput selection2Change = null;
3132            CoinSelection selection1 = null;
3133            TransactionOutput selection1Change = null;
3134            // We keep track of the last size of the transaction we calculated but only if the act of adding inputs and
3135            // change resulted in the size crossing a 1000 byte boundary. Otherwise it stays at zero.
3136            int lastCalculatedSize = 0;
3137            BigInteger valueNeeded;
3138            while (true) {
3139                resetTxInputs(req, originalInputs);
3140
3141                BigInteger fees = req.fee == null ? BigInteger.ZERO : req.fee;
3142                if (lastCalculatedSize > 0) {
3143                    // If the size is exactly 1000 bytes then we'll over-pay, but this should be rare.
3144                    fees = fees.add(BigInteger.valueOf((lastCalculatedSize / 1000) + 1).multiply(req.feePerKb));
3145                } else {
3146                    fees = fees.add(req.feePerKb);  // First time around the loop.
3147                }
3148                if (needAtLeastReferenceFee && fees.compareTo(Transaction.REFERENCE_DEFAULT_MIN_TX_FEE) < 0)
3149                    fees = Transaction.REFERENCE_DEFAULT_MIN_TX_FEE;
3150
3151                valueNeeded = value.add(fees);
3152                if (additionalValueForNextCategory != null)
3153                    valueNeeded = valueNeeded.add(additionalValueForNextCategory);
3154                BigInteger additionalValueSelected = additionalValueForNextCategory;
3155
3156                // Of the coins we could spend, pick some that we actually will spend.
3157                CoinSelection selection = coinSelector.select(valueNeeded, candidates);
3158                // Can we afford this?
3159                if (selection.valueGathered.compareTo(valueNeeded) < 0)
3160                    break;
3161                checkState(selection.gathered.size() > 0 || originalInputs.size() > 0);
3162
3163                // We keep track of an upper bound on transaction size to calculate fees that need to be added.
3164                // Note that the difference between the upper bound and lower bound is usually small enough that it
3165                // will be very rare that we pay a fee we do not need to.
3166                //
3167                // We can't be sure a selection is valid until we check fee per kb at the end, so we just store
3168                // them here temporarily.
3169                boolean eitherCategory2Or3 = false;
3170                boolean isCategory3 = false;
3171
3172                BigInteger change = selection.valueGathered.subtract(valueNeeded);
3173                if (additionalValueSelected != null)
3174                    change = change.add(additionalValueSelected);
3175
3176                // If change is < 0.01 BTC, we will need to have at least minfee to be accepted by the network
3177                if (req.ensureMinRequiredFee && !change.equals(BigInteger.ZERO) &&
3178                        change.compareTo(Utils.CENT) < 0 && fees.compareTo(Transaction.REFERENCE_DEFAULT_MIN_TX_FEE) < 0) {
3179                    // This solution may fit into category 2, but it may also be category 3, we'll check that later
3180                    eitherCategory2Or3 = true;
3181                    additionalValueForNextCategory = Utils.CENT;
3182                    // If the change is smaller than the fee we want to add, this will be negative
3183                    change = change.subtract(Transaction.REFERENCE_DEFAULT_MIN_TX_FEE.subtract(fees));
3184                }
3185
3186                int size = 0;
3187                TransactionOutput changeOutput = null;
3188                if (change.compareTo(BigInteger.ZERO) > 0) {
3189                    // The value of the inputs is greater than what we want to send. Just like in real life then,
3190                    // we need to take back some coins ... this is called "change". Add another output that sends the change
3191                    // back to us. The address comes either from the request or getChangeAddress() as a default.
3192                    Address changeAddress = req.changeAddress;
3193                    if (changeAddress == null)
3194                        changeAddress = getChangeAddress();
3195                    changeOutput = new TransactionOutput(params, req.tx, change, changeAddress);
3196                    // If the change output would result in this transaction being rejected as dust, just drop the change and make it a fee
3197                    if (req.ensureMinRequiredFee && Transaction.MIN_NONDUST_OUTPUT.compareTo(change) >= 0) {
3198                        // This solution definitely fits in category 3
3199                        isCategory3 = true;
3200                        additionalValueForNextCategory = Transaction.REFERENCE_DEFAULT_MIN_TX_FEE.add(
3201                                                         Transaction.MIN_NONDUST_OUTPUT.add(BigInteger.ONE));
3202                    } else {
3203                        size += changeOutput.bitcoinSerialize().length + VarInt.sizeOf(req.tx.getOutputs().size()) - VarInt.sizeOf(req.tx.getOutputs().size() - 1);
3204                        // This solution is either category 1 or 2
3205                        if (!eitherCategory2Or3) // must be category 1
3206                            additionalValueForNextCategory = null;
3207                    }
3208                } else {
3209                    if (eitherCategory2Or3) {
3210                        // This solution definitely fits in category 3 (we threw away change because it was smaller than MIN_TX_FEE)
3211                        isCategory3 = true;
3212                        additionalValueForNextCategory = Transaction.REFERENCE_DEFAULT_MIN_TX_FEE.add(BigInteger.ONE);
3213                    }
3214                }
3215
3216                // Now add unsigned inputs for the selected coins.
3217                for (TransactionOutput output : selection.gathered) {
3218                    TransactionInput input = req.tx.addInput(output);
3219                    // If the scriptBytes don't default to none, our size calculations will be thrown off.
3220                    checkState(input.getScriptBytes().length == 0);
3221                }
3222
3223                // Estimate transaction size and loop again if we need more fee per kb. The serialized tx doesn't
3224                // include things we haven't added yet like input signatures/scripts or the change output.
3225                size += req.tx.bitcoinSerialize().length;
3226                size += estimateBytesForSigning(selection);
3227                if (size/1000 > lastCalculatedSize/1000 && req.feePerKb.compareTo(BigInteger.ZERO) > 0) {
3228                    lastCalculatedSize = size;
3229                    // We need more fees anyway, just try again with the same additional value
3230                    additionalValueForNextCategory = additionalValueSelected;
3231                    continue;
3232                }
3233
3234                if (isCategory3) {
3235                    if (selection3 == null)
3236                        selection3 = selection;
3237                } else if (eitherCategory2Or3) {
3238                    // If we are in selection2, we will require at least CENT additional. If we do that, there is no way
3239                    // we can end up back here because CENT additional will always get us to 1
3240                    checkState(selection2 == null);
3241                    checkState(additionalValueForNextCategory.equals(Utils.CENT));
3242                    selection2 = selection;
3243                    selection2Change = checkNotNull(changeOutput); // If we get no change in category 2, we are actually in category 3
3244                } else {
3245                    // Once we get a category 1 (change kept), we should break out of the loop because we can't do better
3246                    checkState(selection1 == null);
3247                    checkState(additionalValueForNextCategory == null);
3248                    selection1 = selection;
3249                    selection1Change = changeOutput;
3250                }
3251
3252                if (additionalValueForNextCategory != null) {
3253                    if (additionalValueSelected != null)
3254                        checkState(additionalValueForNextCategory.compareTo(additionalValueSelected) > 0);
3255                    continue;
3256                }
3257                break;
3258            }
3259
3260            resetTxInputs(req, originalInputs);
3261
3262            if (selection3 == null && selection2 == null && selection1 == null) {
3263                log.warn("Insufficient value in wallet for send: needed {}", bitcoinValueToFriendlyString(valueNeeded));
3264                throw new InsufficientMoneyException();
3265            }
3266
3267            BigInteger lowestFee = null;
3268            bestCoinSelection = null;
3269            bestChangeOutput = null;
3270            if (selection1 != null) {
3271                if (selection1Change != null)
3272                    lowestFee = selection1.valueGathered.subtract(selection1Change.getValue());
3273                else
3274                    lowestFee = selection1.valueGathered;
3275                bestCoinSelection = selection1;
3276                bestChangeOutput = selection1Change;
3277            }
3278
3279            if (selection2 != null) {
3280                BigInteger fee = selection2.valueGathered.subtract(checkNotNull(selection2Change).getValue());
3281                if (lowestFee == null || fee.compareTo(lowestFee) < 0) {
3282                    lowestFee = fee;
3283                    bestCoinSelection = selection2;
3284                    bestChangeOutput = selection2Change;
3285                }
3286            }
3287
3288            if (selection3 != null) {
3289                if (lowestFee == null || selection3.valueGathered.compareTo(lowestFee) < 0) {
3290                    bestCoinSelection = selection3;
3291                    bestChangeOutput = null;
3292                }
3293            }
3294        }
3295
3296        private int estimateBytesForSigning(CoinSelection selection) {
3297            int size = 0;
3298            for (TransactionOutput output : selection.gathered) {
3299                try {
3300                    if (output.getScriptPubKey().isSentToAddress()) {
3301                        // Send-to-address spends usually take maximum pubkey.length (as it may be compressed or not) + 75 bytes
3302                        size += findKeyFromPubHash(output.getScriptPubKey().getPubKeyHash()).getPubKey().length + 75;
3303                    } else if (output.getScriptPubKey().isSentToRawPubKey())
3304                        size += 74; // Send-to-pubkey spends usually take maximum 74 bytes to spend
3305                    else
3306                        throw new RuntimeException("Unknown output type returned in coin selection");
3307                } catch (ScriptException e) {
3308                    // If this happens it means an output script in a wallet tx could not be understood. That should never
3309                    // happen, if it does it means the wallet has got into an inconsistent state.
3310                    throw new RuntimeException(e);
3311                }
3312            }
3313            return size;
3314        }
3315
3316        private void resetTxInputs(SendRequest req, List<TransactionInput> originalInputs) {
3317            req.tx.clearInputs();
3318            for (TransactionInput input : originalInputs)
3319                req.tx.addInput(input);
3320        }
3321    }
3322}