1// Copyright (c) 2021-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_WALLET_TRANSACTION_H
6#define BITCOIN_WALLET_TRANSACTION_H
7
8#include <attributes.h>
9#include <consensus/amount.h>
10#include <primitives/transaction.h>
11#include <tinyformat.h>
12#include <uint256.h>
13#include <util/check.h>
14#include <util/overloaded.h>
15#include <util/strencodings.h>
16#include <util/string.h>
17#include <wallet/types.h>
18
19#include <bitset>
20#include <cstdint>
21#include <map>
22#include <utility>
23#include <variant>
24#include <vector>
25
26namespace interfaces {
27class Chain;
28} // namespace interfaces
29
30namespace wallet {
31class WalletBatch;
32
33//! State of transaction confirmed in a block.
34struct TxStateConfirmed {
35    uint256 confirmed_block_hash;
36    int confirmed_block_height;
37    int position_in_block;
38
39    explicit TxStateConfirmed(const uint256& block_hash, int height, int index) : confirmed_block_hash(block_hash), confirmed_block_height(height), position_in_block(index) {}
40    std::string toString() const { return strprintf("Confirmed (block=%s, height=%i, index=%i)", confirmed_block_hash.ToString(), confirmed_block_height, position_in_block); }
41};
42
43//! State of transaction added to mempool.
44struct TxStateInMempool {
45    std::string toString() const { return strprintf("InMempool"); }
46};
47
48//! State of rejected transaction that conflicts with a confirmed block.
49struct TxStateBlockConflicted {
50    uint256 conflicting_block_hash;
51    int conflicting_block_height;
52
53    explicit TxStateBlockConflicted(const uint256& block_hash, int height) : conflicting_block_hash(block_hash), conflicting_block_height(height) {}
54    std::string toString() const { return strprintf("BlockConflicted (block=%s, height=%i)", conflicting_block_hash.ToString(), conflicting_block_height); }
55};
56
57//! State of transaction not confirmed or conflicting with a known block and
58//! not in the mempool. May conflict with the mempool, or with an unknown block,
59//! or be abandoned, never broadcast, or rejected from the mempool for another
60//! reason.
61struct TxStateInactive {
62    bool abandoned;
63
64    explicit TxStateInactive(bool abandoned = false) : abandoned(abandoned) {}
65    std::string toString() const { return strprintf("Inactive (abandoned=%i)", abandoned); }
66};
67
68//! State of transaction loaded in an unrecognized state with unexpected hash or
69//! index values. Treated as inactive (with serialized hash and index values
70//! preserved) by default, but may enter another state if transaction is added
71//! to the mempool, or confirmed, or abandoned, or found conflicting.
72struct TxStateUnrecognized {
73    uint256 block_hash;
74    int index;
75
76    TxStateUnrecognized(const uint256& block_hash, int index) : block_hash(block_hash), index(index) {}
77    std::string toString() const { return strprintf("Unrecognized (block=%s, index=%i)", block_hash.ToString(), index); }
78};
79
80//! All possible CWalletTx states
81using TxState = std::variant<TxStateConfirmed, TxStateInMempool, TxStateBlockConflicted, TxStateInactive, TxStateUnrecognized>;
82
83//! Subset of states transaction sync logic is implemented to handle.
84using SyncTxState = std::variant<TxStateConfirmed, TxStateInMempool, TxStateInactive>;
85
86//! Try to interpret deserialized TxStateUnrecognized data as a recognized state.
87static inline TxState TxStateInterpretSerialized(TxStateUnrecognized data)
88{
89    if (data.block_hash == uint256::ZERO) {
90        if (data.index == 0) return TxStateInactive{};
91    } else if (data.block_hash == uint256::ONE) {
92        if (data.index == -1) return TxStateInactive{/*abandoned=*/true};
93    } else if (data.index >= 0) {
94        return TxStateConfirmed{data.block_hash, /*height=*/-1, data.index};
95    } else if (data.index == -1) {
96        return TxStateBlockConflicted{data.block_hash, /*height=*/-1};
97    }
98    return data;
99}
100
101//! Get TxState serialized block hash. Inverse of TxStateInterpretSerialized.
102static inline uint256 TxStateSerializedBlockHash(const TxState& state)
103{
104    return std::visit(util::Overloaded{
105        [](const TxStateInactive& inactive) { return inactive.abandoned ? uint256::ONE : uint256::ZERO; },
106        [](const TxStateInMempool& in_mempool) { return uint256::ZERO; },
107        [](const TxStateConfirmed& confirmed) { return confirmed.confirmed_block_hash; },
108        [](const TxStateBlockConflicted& conflicted) { return conflicted.conflicting_block_hash; },
109        [](const TxStateUnrecognized& unrecognized) { return unrecognized.block_hash; }
110    }, state);
111}
112
113//! Get TxState serialized block index. Inverse of TxStateInterpretSerialized.
114static inline int TxStateSerializedIndex(const TxState& state)
115{
116    return std::visit(util::Overloaded{
117        [](const TxStateInactive& inactive) { return inactive.abandoned ? -1 : 0; },
118        [](const TxStateInMempool& in_mempool) { return 0; },
119        [](const TxStateConfirmed& confirmed) { return confirmed.position_in_block; },
120        [](const TxStateBlockConflicted& conflicted) { return -1; },
121        [](const TxStateUnrecognized& unrecognized) { return unrecognized.index; }
122    }, state);
123}
124
125//! Return TxState or SyncTxState as a string for logging or debugging.
126template<typename T>
127std::string TxStateString(const T& state)
128{
129    return std::visit([](const auto& s) { return s.toString(); }, state);
130}
131
132/**
133 * Cachable amount subdivided into avoid reuse and all balances
134 */
135struct CachableAmount
136{
137    std::optional<CAmount> m_avoid_reuse_value;
138    std::optional<CAmount> m_all_value;
139    inline void Reset()
140    {
141        m_avoid_reuse_value.reset();
142        m_all_value.reset();
143    }
144    void Set(bool avoid_reuse, CAmount value)
145    {
146        if (avoid_reuse) {
147            m_avoid_reuse_value = value;
148        } else {
149            m_all_value = value;
150        }
151    }
152    CAmount Get(bool avoid_reuse)
153    {
154        if (avoid_reuse) {
155            Assert(m_avoid_reuse_value.has_value());
156            return m_avoid_reuse_value.value();
157        }
158        Assert(m_all_value.has_value());
159        return m_all_value.value();
160    }
161    bool IsCached(bool avoid_reuse)
162    {
163        if (avoid_reuse) return m_avoid_reuse_value.has_value();
164        return m_all_value.has_value();
165    }
166};
167
168
169/** Legacy class used for deserializing vtxPrev for backwards compatibility.
170 * vtxPrev was removed in commit 93a18a3650292afbb441a47d1fa1b94aeb0164e3,
171 * but old wallet.dat files may still contain vtxPrev vectors of CMerkleTxs.
172 * These need to get deserialized for field alignment when deserializing
173 * a CWalletTx, but the deserialized values are discarded.**/
174class CMerkleTx
175{
176public:
177    template<typename Stream>
178    void Unserialize(Stream& s)
179    {
180        CTransactionRef tx;
181        uint256 hashBlock;
182        std::vector<uint256> vMerkleBranch;
183        int nIndex;
184
185        s >> TX_WITH_WITNESS(tx) >> hashBlock >> vMerkleBranch >> nIndex;
186    }
187};
188
189/**
190 * A transaction with a bunch of additional info that only the owner cares about.
191 * It includes any unrecorded transactions needed to link it back to the block chain.
192 */
193class CWalletTx
194{
195public:
196    // "from" and "message" are obsolete fields that could be set in
197    // the UI prior to 2011 (removed in commit 4d9b223)
198    // These fields are kept to avoid losing metadata.
199    std::optional<std::string> m_from;
200    std::optional<std::string> m_message;
201    // Comment strings provided by the user
202    std::optional<std::string> m_comment;
203    std::optional<std::string> m_comment_to;
204    std::optional<Txid> m_replaces_txid;
205    std::optional<Txid> m_replaced_by_txid;
206    // BIP 21 URI Messages
207    std::vector<std::string> m_messages;
208    // BIP 70 Payment Request (deprecated, field kept to preserve metadata from old wallets)
209    std::vector<std::string> m_payment_requests;
210    unsigned int nTimeReceived; //!< time received by this node
211    /**
212     * Stable timestamp that never changes, and reflects the order a transaction
213     * was added to the wallet. Timestamp is based on the block time for a
214     * transaction added as part of a block, or else the time when the
215     * transaction was received if it wasn't part of a block, with the timestamp
216     * adjusted in both cases so timestamp order matches the order transactions
217     * were added to the wallet. More details can be found in
218     * CWallet::ComputeTimeSmart().
219     */
220    unsigned int nTimeSmart;
221    // Cached value for whether the transaction spends any inputs known to the wallet
222    mutable std::optional<bool> m_cached_from_me{std::nullopt};
223    int64_t nOrderPos; //!< position in ordered transaction list
224    std::multimap<int64_t, CWalletTx*>::const_iterator m_it_wtxOrdered;
225
226    // memory only
227    enum AmountType { DEBIT, CREDIT, AMOUNTTYPE_ENUM_ELEMENTS };
228    mutable CachableAmount m_amounts[AMOUNTTYPE_ENUM_ELEMENTS];
229    /**
230     * This flag is true if all m_amounts caches are empty. This is particularly
231     * useful in places where MarkDirty is conditionally called and the
232     * condition can be expensive and thus can be skipped if the flag is true.
233     * See MarkDestinationsDirty.
234     */
235    mutable bool m_is_cache_empty{true};
236    mutable bool fChangeCached;
237    mutable CAmount nChangeCached;
238
239    CWalletTx(CTransactionRef tx, const TxState& state) : m_state(state)
240    {
241        Assert(tx);
242        m_canonical_wtxid = tx->GetWitnessHash();
243        m_txs.emplace(tx->GetWitnessHash(), std::move(tx));
244        SetDefaults();
245    }
246
247    template <typename Stream>
248    CWalletTx(deserialize_type, Stream& s, const std::map<Wtxid, CTransactionRef>& variants) : m_state(TxStateInactive{})
249    {
250        Unserialize(s);