transaction.h raw
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 namespace std {
407 /** Disable default std::hash for CTransactionRef to prevent accidentally
408 * comparing by pointer. Use CTransactionRefHash or provide a custom
409 * hasher. */
410 template <>
411 struct hash<CTransactionRef> {
412 hash() = delete;
413 // Belt-and-suspenders, already implied by the above.
414 size_t operator()(const CTransactionRef&) const = delete;
415 };
416 } // namespace std
417
418 #endif // BITCOIN_PRIMITIVES_TRANSACTION_H
419