1  // Copyright (c) 2009-2010 Satoshi Nakamoto
  2  // Copyright (c) 2009-present 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_PRIMITIVES_TRANSACTION_H
  7  #define BITCOIN_PRIMITIVES_TRANSACTION_H
  8  
  9  #include <attributes.h>
 10  #include <consensus/amount.h>
 11  #include <primitives/transaction_identifier.h> // IWYU pragma: export
 12  #include <script/script.h>
 13  #include <serialize.h>
 14  
 15  #include <compare>
 16  #include <cstddef>
 17  #include <cstdint>
 18  #include <ios>
 19  #include <limits>
 20  #include <memory>
 21  #include <numeric>
 22  #include <string>
 23  #include <tuple>
 24  #include <utility>
 25  #include <vector>
 26  
 27  /** An outpoint - a combination of a transaction hash and an index n into its vout */
 28  class COutPoint
 29  {
 30  public:
 31      Txid hash;
 32      uint32_t n;
 33  
 34      static constexpr uint32_t NULL_INDEX = std::numeric_limits<uint32_t>::max();
 35  
 36      COutPoint(): n(NULL_INDEX) { }
 37      COutPoint(const Txid& hashIn, uint32_t nIn): hash(hashIn), n(nIn) { }
 38  
 39      SERIALIZE_METHODS(COutPoint, obj) { READWRITE(obj.hash, obj.n); }
 40  
 41      void SetNull() { hash.SetNull(); n = NULL_INDEX; }
 42      bool IsNull() const { return (hash.IsNull() && n == NULL_INDEX); }
 43  
 44      friend bool operator<(const COutPoint& a, const COutPoint& b)
 45      {
 46          return std::tie(a.hash, a.n) < std::tie(b.hash, b.n);
 47      }
 48  
 49      friend bool operator==(const COutPoint& a, const COutPoint& b)
 50      {
 51          return (a.hash == b.hash && a.n == b.n);
 52      }
 53  
 54      std::string ToString() const;
 55  };
 56  
 57  /** An input of a transaction.  It contains the location of the previous
 58   * transaction's output that it claims and a signature that matches the
 59   * output's public key.
 60   */
 61  class CTxIn
 62  {
 63  public:
 64      COutPoint prevout;
 65      CScript scriptSig;
 66      uint32_t nSequence;
 67      CScriptWitness scriptWitness; //!< Only serialized through CTransaction
 68  
 69      /**
 70       * Setting nSequence to this value for every input in a transaction
 71       * disables nLockTime/IsFinalTx().
 72       * It fails OP_CHECKLOCKTIMEVERIFY/CheckLockTime() for any input that has
 73       * it set (BIP 65).
 74       * It has SEQUENCE_LOCKTIME_DISABLE_FLAG set (BIP 68/112).
 75       */
 76      static const uint32_t SEQUENCE_FINAL = 0xffffffff;
 77      /**
 78       * This is the maximum sequence number that enables both nLockTime and
 79       * OP_CHECKLOCKTIMEVERIFY (BIP 65).
 80       * It has SEQUENCE_LOCKTIME_DISABLE_FLAG set (BIP 68/112).
 81       */
 82      static const uint32_t MAX_SEQUENCE_NONFINAL{SEQUENCE_FINAL - 1};
 83  
 84      // Below flags apply in the context of BIP 68. BIP 68 requires the tx
 85      // version to be set to 2, or higher.
 86      /**
 87       * If this flag is set, CTxIn::nSequence is NOT interpreted as a
 88       * relative lock-time.
 89       * It skips SequenceLocks() for any input that has it set (BIP 68).
 90       * It fails OP_CHECKSEQUENCEVERIFY/CheckSequence() for any input that has
 91       * it set (BIP 112).
 92       */
 93      static const uint32_t SEQUENCE_LOCKTIME_DISABLE_FLAG = (1U << 31);
 94  
 95      /**
 96       * If CTxIn::nSequence encodes a relative lock-time and this flag
 97       * is set, the relative lock-time has units of 512 seconds,
 98       * otherwise it specifies blocks with a granularity of 1. */
 99      static const uint32_t SEQUENCE_LOCKTIME_TYPE_FLAG = (1 << 22);
100  
101      /**
102       * If CTxIn::nSequence encodes a relative lock-time, this mask is
103       * applied to extract that lock-time from the sequence field. */
104      static const uint32_t SEQUENCE_LOCKTIME_MASK = 0x0000ffff;
105  
106      /**
107       * In order to use the same number of bits to encode roughly the
108       * same wall-clock duration, and because blocks are naturally
109       * limited to occur every 600s on average, the minimum granularity
110       * for time-based relative lock-time is fixed at 512 seconds.
111       * Converting from CTxIn::nSequence to seconds is performed by
112       * multiplying by 512 = 2^9, or equivalently shifting up by
113       * 9 bits. */
114      static const int SEQUENCE_LOCKTIME_GRANULARITY = 9;
115  
116      CTxIn()
117      {
118          nSequence = SEQUENCE_FINAL;
119      }
120  
121      explicit CTxIn(COutPoint prevoutIn, CScript scriptSigIn=CScript(), uint32_t nSequenceIn=SEQUENCE_FINAL);
122      CTxIn(Txid hashPrevTx, uint32_t nOut, CScript scriptSigIn=CScript(), uint32_t nSequenceIn=SEQUENCE_FINAL);
123  
124      SERIALIZE_METHODS(CTxIn, obj) { READWRITE(obj.prevout, obj.scriptSig, obj.nSequence); }
125  
126      friend bool operator==(const CTxIn& a, const CTxIn& b)
127      {
128          return (a.prevout   == b.prevout &&
129                  a.scriptSig == b.scriptSig &&
130                  a.nSequence == b.nSequence);
131      }
132  
133      std::string ToString() const;
134  };
135  
136  /** An output of a transaction.  It contains the public key that the next input
137   * must be able to sign with to claim it.
138   */
139  class CTxOut
140  {
141  public:
142      CAmount nValue;
143      CScript scriptPubKey;
144  
145      CTxOut()
146      {
147          SetNull();
148      }
149  
150      CTxOut(const CAmount& nValueIn, CScript scriptPubKeyIn);
151  
152      SERIALIZE_METHODS(CTxOut, obj) { READWRITE(obj.nValue, obj.scriptPubKey); }
153  
154      void SetNull()
155      {
156          nValue = -1;
157          scriptPubKey.clear();
158      }
159  
160      bool IsNull() const
161      {
162          return (nValue == -1);
163      }
164  
165      friend bool operator==(const CTxOut& a, const CTxOut& b)
166      {
167          return (a.nValue       == b.nValue &&
168                  a.scriptPubKey == b.scriptPubKey);
169      }
170  
171      std::string ToString() const;
172  };
173  
174  struct CMutableTransaction;
175  
176  struct TransactionSerParams {
177      const bool allow_witness;
178      SER_PARAMS_OPFUNC
179  };
180  static constexpr TransactionSerParams TX_WITH_WITNESS{.allow_witness = true};
181  static constexpr TransactionSerParams TX_NO_WITNESS{.allow_witness = false};
182  
183  /**
184   * Basic transaction serialization format:
185   * - uint32_t version
186   * - std::vector<CTxIn> vin
187   * - std::vector<CTxOut> vout
188   * - uint32_t nLockTime
189   *
190   * Extended transaction serialization format:
191   * - uint32_t version
192   * - unsigned char dummy = 0x00
193   * - unsigned char flags (!= 0)
194   * - std::vector<CTxIn> vin
195   * - std::vector<CTxOut> vout
196   * - if (flags & 1):
197   *   - CScriptWitness scriptWitness; (deserialized into CTxIn)
198   * - uint32_t nLockTime
199   */
200  template<typename Stream, typename TxType>
201  void UnserializeTransaction(TxType& tx, Stream& s, const TransactionSerParams& params)
202  {
203      const bool fAllowWitness = params.allow_witness;
204  
205      s >> tx.version;
206      unsigned char flags = 0;
207      tx.vin.clear();
208      tx.vout.clear();
209      /* Try to read the vin. In case the dummy is there, this will be read as an empty vector. */
210      s >> tx.vin;
211      if (tx.vin.size() == 0 && fAllowWitness) {
212          /* We read a dummy or an empty vin. */
213          s >> flags;
214          if (flags != 0) {
215              s >> tx.vin;
216              s >> tx.vout;
217          }
218      } else {
219          /* We read a non-empty vin. Assume a normal vout follows. */
220          s >> tx.vout;
221      }
222      if ((flags & 1) && fAllowWitness) {
223          /* The witness flag is present, and we support witnesses. */
224          flags ^= 1;
225          for (size_t i = 0; i < tx.vin.size(); i++) {
226              s >> tx.vin[i].scriptWitness.stack;
227          }
228          if (!tx.HasWitness()) {
229              /* It's illegal to encode witnesses when all witness stacks are empty. */
230              throw std::ios_base::failure("Superfluous witness record");
231          }
232      }
233      if (flags) {
234          /* Unknown flag in the serialization */
235          throw std::ios_base::failure("Unknown transaction optional data");
236      }
237      s >> tx.nLockTime;
238  }
239  
240  template<typename Stream, typename TxType>
241  void SerializeTransaction(const TxType& tx, Stream& s, const TransactionSerParams& params)
242  {
243      const bool fAllowWitness = params.allow_witness;
244  
245      s << tx.version;
246      unsigned char flags = 0;
247      // Consistency check
248      if (fAllowWitness) {
249          /* Check whether witnesses need to be serialized. */
250          if (tx.HasWitness()) {
251              flags |= 1;
252          }
253      }
254      if (flags) {
255          /* Use extended format in case witnesses are to be serialized. */
256          std::vector<CTxIn> vinDummy;
257          s << vinDummy;
258          s << flags;
259      }
260      s << tx.vin;
261      s << tx.vout;
262      if (flags & 1) {
263          for (size_t i = 0; i < tx.vin.size(); i++) {
264              s << tx.vin[i].scriptWitness.stack;
265          }
266      }
267      s << tx.nLockTime;
268  }
269  
270  template<typename TxType>
271  inline CAmount CalculateOutputValue(const TxType& tx)
272  {
273      return std::accumulate(tx.vout.cbegin(), tx.vout.cend(), CAmount{0}, [](CAmount sum, const auto& txout) { return sum + txout.nValue; });
274  }
275  
276  
277  /** The basic transaction that is broadcasted on the network and contained in
278   * blocks.  A transaction can contain multiple inputs and outputs.
279   */
280  class CTransaction
281  {
282  public:
283      // Default transaction version.
284      static const uint32_t CURRENT_VERSION{2};
285  
286      // The local variables are made const to prevent unintended modification
287      // without updating the cached hash value. However, CTransaction is not
288      // actually immutable; deserialization and assignment are implemented,
289      // and bypass the constness. This is safe, as they update the entire
290      // structure, including the hash.
291      const std::vector<CTxIn> vin;
292      const std::vector<CTxOut> vout;
293      const uint32_t version;
294      const uint32_t nLockTime;
295  
296  private:
297      /** Memory only. */
298      const bool m_has_witness;
299      const Txid hash;
300      const Wtxid m_witness_hash;
301  
302      Txid ComputeHash() const;
303      Wtxid ComputeWitnessHash() const;
304  
305      bool ComputeHasWitness() const;
306  
307  public:
308      /** Convert a CMutableTransaction into a CTransaction. */
309      explicit CTransaction(const CMutableTransaction& tx);
310      explicit CTransaction(CMutableTransaction&& tx);
311  
312      template <typename Stream>
313      inline void Serialize(Stream& s) const {
314          SerializeTransaction(*this, s, s.template GetParams<TransactionSerParams>());
315      }
316  
317      /** This deserializing constructor is provided instead of an Unserialize method.
318       *  Unserialize is not possible, since it would require overwriting const fields. */
319      template <typename Stream>
320      CTransaction(deserialize_type, const TransactionSerParams& params, Stream& s) : CTransaction(CMutableTransaction(deserialize, params, s)) {}
321      template <typename Stream>
322      CTransaction(deserialize_type, Stream& s) : CTransaction(CMutableTransaction(deserialize, s)) {}
323  
324      bool IsNull() const {
325          return vin.empty() && vout.empty();
326      }
327  
328      const Txid& GetHash() const LIFETIMEBOUND { return hash; }
329      const Wtxid& GetWitnessHash() const LIFETIMEBOUND { return m_witness_hash; };
330  
331      // Return sum of txouts.
332      CAmount GetValueOut() const;
333  
334      /**
335       * Calculate the total transaction size in bytes, including witness data.
336       * "Total Size" defined in BIP141 and BIP144.
337       * @return Total transaction size in bytes
338       */
339      unsigned int ComputeTotalSize() const;
340  
341      bool IsCoinBase() const
342      {
343          return (vin.size() == 1 && vin[0].prevout.IsNull());
344      }
345  
346      friend bool operator==(const CTransaction& a, const CTransaction& b)
347      {
348          return a.GetWitnessHash() == b.GetWitnessHash();
349      }
350  
351      std::string ToString() const;
352  
353      bool HasWitness() const { return m_has_witness; }
354  };
355  
356  /** A mutable version of CTransaction. */
357  struct CMutableTransaction
358  {
359      std::vector<CTxIn> vin;
360      std::vector<CTxOut> vout;
361      uint32_t version;
362      uint32_t nLockTime;
363  
364      explicit CMutableTransaction();
365      explicit CMutableTransaction(const CTransaction& tx);
366  
367      template <typename Stream>
368      inline void Serialize(Stream& s) const {
369          SerializeTransaction(*this, s, s.template GetParams<TransactionSerParams>());
370      }
371  
372      template <typename Stream>
373      inline void Unserialize(Stream& s) {
374          UnserializeTransaction(*this, s, s.template GetParams<TransactionSerParams>());
375      }
376  
377      template <typename Stream>
378      CMutableTransaction(deserialize_type, const TransactionSerParams& params, Stream& s) {
379          UnserializeTransaction(*this, s, params);
380      }
381  
382      template <typename Stream>
383      CMutableTransaction(deserialize_type, Stream& s) {
384          Unserialize(s);
385      }
386  
387      /** Compute the hash of this CMutableTransaction. This is computed on the
388       * fly, as opposed to GetHash() in CTransaction, which uses a cached result.
389       */
390      Txid GetHash() const;
391  
392      bool HasWitness() const
393      {
394          for (size_t i = 0; i < vin.size(); i++) {
395              if (!vin[i].scriptWitness.IsNull()) {
396                  return true;
397              }
398          }
399          return false;
400      }
401  };
402  
403  typedef std::shared_ptr<const CTransaction> CTransactionRef;
404  template <typename Tx> static inline CTransactionRef MakeTransactionRef(Tx&& txIn) { return std::make_shared<const CTransaction>(std::forward<Tx>(txIn)); }
405  
406  #endif // BITCOIN_PRIMITIVES_TRANSACTION_H