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 <algorithm>
16#include <compare>
17#include <cstddef>
18#include <cstdint>
19#include <ios>
20#include <limits>
21#include <memory>
22#include <numeric>
23#include <string>
24#include <tuple>
25#include <utility>
26#include <vector>
27
28/** An outpoint - a combination of a transaction hash and an index n into its vout */
29class COutPoint
30{
31public:
32    Txid hash;
33    uint32_t n;
34
35    static constexpr uint32_t NULL_INDEX = std::numeric_limits<uint32_t>::max();
36
37    COutPoint(): n(NULL_INDEX) { }
38    COutPoint(const Txid& hashIn, uint32_t nIn): hash(hashIn), n(nIn) { }
39
40    SERIALIZE_METHODS(COutPoint, obj) { READWRITE(obj.hash, obj.n); }
41
42    void SetNull() { hash.SetNull(); n = NULL_INDEX; }
43    bool IsNull() const { return (hash.IsNull() && n == NULL_INDEX); }
44
45    friend bool operator<(const COutPoint& a, const COutPoint& b)
46    {
47        return std::tie(a.hash, a.n) < std::tie(b.hash, b.n);
48    }
49
50    friend bool operator==(const COutPoint& a, const COutPoint& b)
51    {
52        return (a.hash == b.hash && a.n == b.n);
53    }
54
55    std::string ToString() const;
56};
57
58/** An input of a transaction.  It contains the location of the previous
59 * transaction's output that it claims and a signature that matches the
60 * output's public key.
61 */
62class CTxIn
63{
64public:
65    COutPoint prevout;
66    CScript scriptSig;
67    uint32_t nSequence;
68    CScriptWitness scriptWitness; //!< Only serialized through CTransaction
69
70    /**
71     * Setting nSequence to this value for every input in a transaction
72     * disables nLockTime/IsFinalTx().
73     * It fails OP_CHECKLOCKTIMEVERIFY/CheckLockTime() for any input that has
74     * it set (BIP 65).
75     * It has SEQUENCE_LOCKTIME_DISABLE_FLAG set (BIP 68/112).
76     */
77    static constexpr uint32_t SEQUENCE_FINAL{0xffffffff};
78    /**
79     * This is the maximum sequence number that enables both nLockTime and
80     * OP_CHECKLOCKTIMEVERIFY (BIP 65).
81     * It has SEQUENCE_LOCKTIME_DISABLE_FLAG set (BIP 68/112).
82     */
83    static constexpr uint32_t MAX_SEQUENCE_NONFINAL{SEQUENCE_FINAL - 1};
84
85    // Below flags apply in the context of BIP 68. BIP 68 requires the tx
86    // version to be set to 2, or higher.
87    /**
88     * If this flag is set, CTxIn::nSequence is NOT interpreted as a
89     * relative lock-time.
90     * It skips SequenceLocks() for any input that has it set (BIP 68).
91     * It fails OP_CHECKSEQUENCEVERIFY/CheckSequence() for any input that has
92     * it set (BIP 112).
93     */
94    static constexpr uint32_t SEQUENCE_LOCKTIME_DISABLE_FLAG{1U << 31};
95
96    /**
97     * If CTxIn::nSequence encodes a relative lock-time and this flag
98     * is set, the relative lock-time has units of 512 seconds,
99     * otherwise it specifies blocks with a granularity of 1. */
100    static constexpr uint32_t SEQUENCE_LOCKTIME_TYPE_FLAG{1 << 22};
101
102    /**
103     * If CTxIn::nSequence encodes a relative lock-time, this mask is
104     * applied to extract that lock-time from the sequence field. */
105    static constexpr uint32_t SEQUENCE_LOCKTIME_MASK{0x0000ffff};
106
107    /**
108     * In order to use the same number of bits to encode roughly the
109     * same wall-clock duration, and because blocks are naturally
110     * limited to occur every 600s on average, the minimum granularity
111     * for time-based relative lock-time is fixed at 512 seconds.
112     * Converting from CTxIn::nSequence to seconds is performed by
113     * multiplying by 512 = 2^9, or equivalently shifting up by
114     * 9 bits. */
115    static constexpr int SEQUENCE_LOCKTIME_GRANULARITY{9};
116
117    CTxIn()
118    {
119        nSequence = SEQUENCE_FINAL;
120    }
121
122    explicit CTxIn(COutPoint prevoutIn, CScript scriptSigIn=CScript(), uint32_t nSequenceIn=SEQUENCE_FINAL);
123    CTxIn(Txid hashPrevTx, uint32_t nOut, CScript scriptSigIn=CScript(), uint32_t nSequenceIn=SEQUENCE_FINAL);
124
125    SERIALIZE_METHODS(CTxIn, obj) { READWRITE(obj.prevout, obj.scriptSig, obj.nSequence); }
126
127    friend bool operator==(const CTxIn& a, const CTxIn& b)
128    {
129        return (a.prevout   == b.prevout &&
130                a.scriptSig == b.scriptSig &&
131                a.nSequence == b.nSequence);
132    }
133
134    std::string ToString() const;
135};
136
137/** An output of a transaction.  It contains the public key that the next input
138 * must be able to sign with to claim it.
139 */
140class CTxOut
141{
142public:
143    CAmount nValue;
144    CScript scriptPubKey;
145
146    CTxOut()
147    {
148        SetNull();
149    }
150
151    CTxOut(const CAmount& nValueIn, CScript scriptPubKeyIn);
152
153    SERIALIZE_METHODS(CTxOut, obj) { READWRITE(obj.nValue, obj.scriptPubKey); }
154
155    void SetNull()
156    {
157        nValue = -1;
158        scriptPubKey.clear();
159    }
160
161    bool IsNull() const
162    {
163        return (nValue == -1);
164    }
165
166    friend bool operator==(const CTxOut& a, const CTxOut& b)
167    {
168        return (a.nValue       == b.nValue &&
169                a.scriptPubKey == b.scriptPubKey);
170    }
171
172    std::string ToString() const;
173};
174
175struct CMutableTransaction;
176
177struct TransactionSerParams {
178    const bool allow_witness;
179    SER_PARAMS_OPFUNC
180};
181inline constexpr TransactionSerParams TX_WITH_WITNESS{.allow_witness = true};
182inline constexpr TransactionSerParams TX_NO_WITNESS{.allow_witness = false};
183
184/**
185 * Basic transaction serialization format:
186 * - uint32_t version
187 * - std::vector<CTxIn> vin
188 * - std::vector<CTxOut> vout
189 * - uint32_t nLockTime
190 *
191 * Extended transaction serialization format:
192 * - uint32_t version
193 * - unsigned char dummy = 0x00
194 * - unsigned char flags (!= 0)
195 * - std::vector<CTxIn> vin
196 * - std::vector<CTxOut> vout
197 * - if (flags & 1):
198 *   - CScriptWitness scriptWitness; (deserialized into CTxIn)
199 * - uint32_t nLockTime
200 */
201template<typename Stream, typename TxType>
202void UnserializeTransaction(TxType& tx, Stream& s, const TransactionSerParams& params)
203{
204    const bool fAllowWitness = params.allow_witness;
205
206    s >> tx.version;
207    unsigned char flags = 0;
208    tx.vin.clear();
209    tx.vout.clear();
210    /* Try to read the vin. In case the dummy is there, this will be read as an empty vector. */
211    s >> tx.vin;
212    if (tx.vin.size() == 0 && fAllowWitness) {
213        /* We read a dummy or an empty vin. */
214        s >> flags;
215        if (flags != 0) {
216            s >> tx.vin;
217            s >> tx.vout;
218        }
219    } else {
220        /* We read a non-empty vin. Assume a normal vout follows. */
221        s >> tx.vout;
222    }
223    if ((flags & 1) && fAllowWitness) {
224        /* The witness flag is present, and we support witnesses. */
225        flags ^= 1;
226        for (size_t i = 0; i < tx.vin.size(); i++) {
227            s >> tx.vin[i].scriptWitness.stack;
228        }
229        if (!tx.HasWitness()) {
230            /* It's illegal to encode witnesses when all witness stacks are empty. */
231            throw std::ios_base::failure("Superfluous witness record");
232        }
233    }
234    if (flags) {
235        /* Unknown flag in the serialization */
236        throw std::ios_base::failure("Unknown transaction optional data");
237    }
238    s >> tx.nLockTime;
239}
240
241template<typename Stream, typename TxType>
242void SerializeTransaction(const TxType& tx, Stream& s, const TransactionSerParams& params)
243{
244    const bool fAllowWitness = params.allow_witness;
245
246    s << tx.version;
247    unsigned char flags = 0;
248    // Consistency check
249    if (fAllowWitness) {
250        /* Check whether witnesses need to be serialized. */