src/coins.h

   1 // Copyright (c) 2009-2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2016 The Bitcoin Core developers
   3 // Distributed under the MIT software license, see the accompanying
   4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
   5
   6 #ifndef BITCOIN_COINS_H
   7 #define BITCOIN_COINS_H
   8
   9 #include "primitives/transaction.h"
  10 #include "compressor.h"
  11 #include "core_memusage.h"
  12 #include "hash.h"
  13 #include "memusage.h"
  14 #include "serialize.h"
  15 #include "uint256.h"
  16
  17 #include <assert.h>
  18 #include <stdint.h>
  19
  20 #include <boost/foreach.hpp>
  21 #include <unordered_map>
  22
  23 /**
  24  * A UTXO entry.
  25  *
  26  * Serialized format:
  27  * - VARINT((coinbase ? 1 : 0) | (height << 1))
  28  * - the non-spent CTxOut (via CTxOutCompressor)
  29  */
  30 class Coin
  31 {
  32 public:
  33     //! unspent transaction output
  34     CTxOut out;
  35
  36     //! whether containing transaction was a coinbase
  37     unsigned int fCoinBase : 1;
  38
  39     //! at which height this containing transaction was included in the active block chain
  40     uint32_t nHeight : 31;
  41
  42     //! construct a Coin from a CTxOut and height/coinbase information.
  43     Coin(CTxOut&& outIn, int nHeightIn, bool fCoinBaseIn) : out(std::move(outIn)), fCoinBase(fCoinBaseIn), nHeight(nHeightIn) {}
  44     Coin(const CTxOut& outIn, int nHeightIn, bool fCoinBaseIn) : out(outIn), fCoinBase(fCoinBaseIn),nHeight(nHeightIn) {}
  45
  46     void Clear() {
  47         out.SetNull();
  48         fCoinBase = false;
  49         nHeight = 0;
  50     }
  51
  52     //! empty constructor
  53     Coin() : fCoinBase(false), nHeight(0) { }
  54
  55     bool IsCoinBase() const {
  56         return fCoinBase;
  57     }
  58
  59     template<typename Stream>
  60     void Serialize(Stream &s) const {
  61         assert(!IsPruned());
  62         uint32_t code = nHeight * 2 + fCoinBase;
  63         ::Serialize(s, VARINT(code));
  64         ::Serialize(s, CTxOutCompressor(REF(out)));
  65     }
  66
  67     template<typename Stream>
  68     void Unserialize(Stream &s) {
  69         uint32_t code = 0;
  70         ::Unserialize(s, VARINT(code));
  71         nHeight = code >> 1;
  72         fCoinBase = code & 1;
  73         ::Unserialize(s, REF(CTxOutCompressor(out)));
  74     }
  75
  76     bool IsPruned() const {
  77         return out.IsNull();
  78     }
  79
  80     size_t DynamicMemoryUsage() const {
  81         return memusage::DynamicUsage(out.scriptPubKey);
  82     }
  83 };
  84
  85 class SaltedOutpointHasher
  86 {
  87 private:
  88     /** Salt */
  89     const uint64_t k0, k1;
  90
  91 public:
  92     SaltedOutpointHasher();
  93
  94     /**
  95      * This *must* return size_t. With Boost 1.46 on 32-bit systems the
  96      * unordered_map will behave unpredictably if the custom hasher returns a
  97      * uint64_t, resulting in failures when syncing the chain (#4634).
  98      */
  99     size_t operator()(const COutPoint& id) const {
 100         return SipHashUint256Extra(k0, k1, id.hash, id.n);
 101     }
 102 };
 103
 104 struct CCoinsCacheEntry
 105 {
 106     Coin coin; // The actual cached data.
 107     unsigned char flags;
 108
 109     enum Flags {
 110         DIRTY = (1 << 0), // This cache entry is potentially different from the version in the parent view.
 111         FRESH = (1 << 1), // The parent view does not have this entry (or it is pruned).
 112         /* Note that FRESH is a performance optimization with which we can
 113          * erase coins that are fully spent if we know we do not need to
 114          * flush the changes to the parent cache.  It is always safe to
 115          * not mark FRESH if that condition is not guaranteed.
 116          */
 117     };
 118
 119     CCoinsCacheEntry() : flags(0) {}
 120     explicit CCoinsCacheEntry(Coin&& coin_) : coin(std::move(coin_)), flags(0) {}
 121 };
 122
 123 typedef std::unordered_map<COutPoint, CCoinsCacheEntry, SaltedOutpointHasher> CCoinsMap;
 124
 125 /** Cursor for iterating over CoinsView state */
 126 class CCoinsViewCursor
 127 {
 128 public:
 129     CCoinsViewCursor(const uint256 &hashBlockIn): hashBlock(hashBlockIn) {}
 130     virtual ~CCoinsViewCursor() {}
 131
 132     virtual bool GetKey(COutPoint &key) const = 0;
 133     virtual bool GetValue(Coin &coin) const = 0;
 134     virtual unsigned int GetValueSize() const = 0;
 135
 136     virtual bool Valid() const = 0;
 137     virtual void Next() = 0;
 138
 139     //! Get best block at the time this cursor was created
 140     const uint256 &GetBestBlock() const { return hashBlock; }
 141 private:
 142     uint256 hashBlock;
 143 };
 144
 145 /** Abstract view on the open txout dataset. */
 146 class CCoinsView
 147 {
 148 public:
 149     //! Retrieve the Coin (unspent transaction output) for a given outpoint.
 150     virtual bool GetCoins(const COutPoint &outpoint, Coin &coin) const;
 151
 152     //! Just check whether we have data for a given outpoint.
 153     //! This may (but cannot always) return true for spent outputs.
 154     virtual bool HaveCoins(const COutPoint &outpoint) const;
 155
 156     //! Retrieve the block hash whose state this CCoinsView currently represents
 157     virtual uint256 GetBestBlock() const;
 158
 159     //! Do a bulk modification (multiple Coin changes + BestBlock change).
 160     //! The passed mapCoins can be modified.
 161     virtual bool BatchWrite(CCoinsMap &mapCoins, const uint256 &hashBlock);
 162
 163     //! Get a cursor to iterate over the whole state
 164     virtual CCoinsViewCursor *Cursor() const;
 165
 166     //! As we use CCoinsViews polymorphically, have a virtual destructor
 167     virtual ~CCoinsView() {}
 168
 169     //! Estimate database size (0 if not implemented)
 170     virtual size_t EstimateSize() const { return 0; }
 171 };
 172
 173
 174 /** CCoinsView backed by another CCoinsView */
 175 class CCoinsViewBacked : public CCoinsView
 176 {
 177 protected:
 178     CCoinsView *base;
 179
 180 public:
 181     CCoinsViewBacked(CCoinsView *viewIn);
 182     bool GetCoins(const COutPoint &outpoint, Coin &coin) const override;
 183     bool HaveCoins(const COutPoint &outpoint) const override;
 184     uint256 GetBestBlock() const override;
 185     void SetBackend(CCoinsView &viewIn);
 186     bool BatchWrite(CCoinsMap &mapCoins, const uint256 &hashBlock) override;
 187     CCoinsViewCursor *Cursor() const override;
 188     size_t EstimateSize() const override;
 189 };
 190
 191
 192 /** CCoinsView that adds a memory cache for transactions to another CCoinsView */
 193 class CCoinsViewCache : public CCoinsViewBacked
 194 {
 195 protected:
 196     /**
 197      * Make mutable so that we can "fill the cache" even from Get-methods
 198      * declared as "const".
 199      */
 200     mutable uint256 hashBlock;
 201     mutable CCoinsMap cacheCoins;
 202
 203     /* Cached dynamic memory usage for the inner Coin objects. */
 204     mutable size_t cachedCoinsUsage;
 205
 206 public:
 207     CCoinsViewCache(CCoinsView *baseIn);
 208
 209     // Standard CCoinsView methods
 210     bool GetCoins(const COutPoint &outpoint, Coin &coin) const;
 211     bool HaveCoins(const COutPoint &outpoint) const;
 212     uint256 GetBestBlock() const;
 213     void SetBestBlock(const uint256 &hashBlock);
 214     bool BatchWrite(CCoinsMap &mapCoins, const uint256 &hashBlock);
 215
 216     /**
 217      * Check if we have the given utxo already loaded in this cache.
 218      * The semantics are the same as HaveCoins(), but no calls to
 219      * the backing CCoinsView are made.
 220      */
 221     bool HaveCoinsInCache(const COutPoint &outpoint) const;
 222
 223     /**
 224      * Return a reference to Coin in the cache, or a pruned one if not found. This is
 225      * more efficient than GetCoins. Modifications to other cache entries are
 226      * allowed while accessing the returned pointer.
 227      */
 228     const Coin& AccessCoin(const COutPoint &output) const;
 229
 230     /**
 231      * Add a coin. Set potential_overwrite to true if a non-pruned version may
 232      * already exist.
 233      */
 234     void AddCoin(const COutPoint& outpoint, Coin&& coin, bool potential_overwrite);
 235
 236     /**
 237      * Spend a coin. Pass moveto in order to get the deleted data.
 238      * If no unspent output exists for the passed outpoint, this call
 239      * has no effect.
 240      */
 241     void SpendCoin(const COutPoint &outpoint, Coin* moveto = nullptr);
 242
 243     /**
 244      * Push the modifications applied to this cache to its base.
 245      * Failure to call this method before destruction will cause the changes to be forgotten.
 246      * If false is returned, the state of this cache (and its backing view) will be undefined.
 247      */
 248     bool Flush();
 249
 250     /**
 251      * Removes the UTXO with the given outpoint from the cache, if it is
 252      * not modified.
 253      */
 254     void Uncache(const COutPoint &outpoint);
 255
 256     //! Calculate the size of the cache (in number of transaction outputs)
 257     unsigned int GetCacheSize() const;
 258
 259     //! Calculate the size of the cache (in bytes)
 260     size_t DynamicMemoryUsage() const;
 261
 262     /**
 263      * Amount of bitcoins coming in to a transaction
 264      * Note that lightweight clients may not know anything besides the hash of previous transactions,
 265      * so may not be able to calculate this.
 266      *
 267      * @param[in] tx    transaction for which we are checking input total
 268      * @return  Sum of value of all inputs (scriptSigs)
 269      */
 270     CAmount GetValueIn(const CTransaction& tx) const;
 271
 272     //! Check whether all prevouts of the transaction are present in the UTXO set represented by this view
 273     bool HaveInputs(const CTransaction& tx) const;
 274
 275 private:
 276     CCoinsMap::iterator FetchCoins(const COutPoint &outpoint) const;
 277
 278     /**
 279      * By making the copy constructor private, we prevent accidentally using it when one intends to create a cache on top of a base cache.
 280      */
 281     CCoinsViewCache(const CCoinsViewCache &);
 282 };
 283
 284 //! Utility function to add all of a transaction's outputs to a cache.
 285 // It assumes that overwrites are only possible for coinbase transactions,
 286 // TODO: pass in a boolean to limit these possible overwrites to known
 287 // (pre-BIP34) cases.
 288 void AddCoins(CCoinsViewCache& cache, const CTransaction& tx, int nHeight);
 289
 290 //! Utility function to find any unspent output with a given txid.
 291 const Coin& AccessByTxid(const CCoinsViewCache& cache, const uint256& txid);
 292
 293 #endif // BITCOIN_COINS_H