Branch data Line data Source code
1 : : // Copyright (c) 2009-2010 Satoshi Nakamoto
2 : : // Copyright (c) 2009-2021 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_MERKLEBLOCK_H
7 : : #define BITCOIN_MERKLEBLOCK_H
8 : :
9 : : #include <common/bloom.h>
10 : : #include <primitives/block.h>
11 : : #include <serialize.h>
12 : : #include <uint256.h>
13 : :
14 : : #include <set>
15 : : #include <vector>
16 : :
17 : : // Helper functions for serialization.
18 : : std::vector<unsigned char> BitsToBytes(const std::vector<bool>& bits);
19 : : std::vector<bool> BytesToBits(const std::vector<unsigned char>& bytes);
20 : :
21 : : /** Data structure that represents a partial merkle tree.
22 : : *
23 : : * It represents a subset of the txid's of a known block, in a way that
24 : : * allows recovery of the list of txid's and the merkle root, in an
25 : : * authenticated way.
26 : : *
27 : : * The encoding works as follows: we traverse the tree in depth-first order,
28 : : * storing a bit for each traversed node, signifying whether the node is the
29 : : * parent of at least one matched leaf txid (or a matched txid itself). In
30 : : * case we are at the leaf level, or this bit is 0, its merkle node hash is
31 : : * stored, and its children are not explored further. Otherwise, no hash is
32 : : * stored, but we recurse into both (or the only) child branch. During
33 : : * decoding, the same depth-first traversal is performed, consuming bits and
34 : : * hashes as they written during encoding.
35 : : *
36 : : * The serialization is fixed and provides a hard guarantee about the
37 : : * encoded size:
38 : : *
39 : : * SIZE <= 10 + ceil(32.25*N)
40 : : *
41 : : * Where N represents the number of leaf nodes of the partial tree. N itself
42 : : * is bounded by:
43 : : *
44 : : * N <= total_transactions
45 : : * N <= 1 + matched_transactions*tree_height
46 : : *
47 : : * The serialization format:
48 : : * - uint32 total_transactions (4 bytes)
49 : : * - varint number of hashes (1-3 bytes)
50 : : * - uint256[] hashes in depth-first order (<= 32*N bytes)
51 : : * - varint number of bytes of flag bits (1-3 bytes)
52 : : * - byte[] flag bits, packed per 8 in a byte, least significant bit first (<= 2*N-1 bits)
53 : : * The size constraints follow from this.
54 : : */
55 : 0 : class CPartialMerkleTree
56 : : {
57 : : protected:
58 : : /** the total number of transactions in the block */
59 : : unsigned int nTransactions;
60 : :
61 : : /** node-is-parent-of-matched-txid bits */
62 : : std::vector<bool> vBits;
63 : :
64 : : /** txids and internal hashes */
65 : : std::vector<uint256> vHash;
66 : :
67 : : /** flag set when encountering invalid data */
68 : : bool fBad;
69 : :
70 : : /** helper function to efficiently calculate the number of nodes at given height in the merkle tree */
71 : 0 : unsigned int CalcTreeWidth(int height) const {
72 [ # # # # : 0 : return (nTransactions+(1 << height)-1) >> height;
# # # # #
# ]
73 : : }
74 : :
75 : : /** calculate the hash of a node in the merkle tree (at leaf level: the txid's themselves) */
76 : : uint256 CalcHash(int height, unsigned int pos, const std::vector<uint256> &vTxid);
77 : :
78 : : /** recursive function that traverses tree nodes, storing the data as bits and hashes */
79 : : void TraverseAndBuild(int height, unsigned int pos, const std::vector<uint256> &vTxid, const std::vector<bool> &vMatch);
80 : :
81 : : /**
82 : : * recursive function that traverses tree nodes, consuming the bits and hashes produced by TraverseAndBuild.
83 : : * it returns the hash of the respective node and its respective index.
84 : : */
85 : : uint256 TraverseAndExtract(int height, unsigned int pos, unsigned int &nBitsUsed, unsigned int &nHashUsed, std::vector<uint256> &vMatch, std::vector<unsigned int> &vnIndex);
86 : :
87 : : public:
88 : :
89 : 0 : SERIALIZE_METHODS(CPartialMerkleTree, obj)
90 : : {
91 : 0 : READWRITE(obj.nTransactions, obj.vHash);
92 : 0 : std::vector<unsigned char> bytes;
93 [ # # ]: 0 : SER_WRITE(obj, bytes = BitsToBytes(obj.vBits));
[ # # # # ]
94 : 0 : READWRITE(bytes);
95 [ # # ]: 0 : SER_READ(obj, obj.vBits = BytesToBits(bytes));
96 : 0 : SER_READ(obj, obj.fBad = false);
97 : 0 : }
98 : :
99 : : /** Construct a partial merkle tree from a list of transaction ids, and a mask that selects a subset of them */
100 : : CPartialMerkleTree(const std::vector<uint256> &vTxid, const std::vector<bool> &vMatch);
101 : :
102 : : CPartialMerkleTree();
103 : :
104 : : /**
105 : : * extract the matching txid's represented by this partial merkle tree
106 : : * and their respective indices within the partial tree.
107 : : * returns the merkle root, or 0 in case of failure
108 : : */
109 : : uint256 ExtractMatches(std::vector<uint256> &vMatch, std::vector<unsigned int> &vnIndex);
110 : :
111 : : /** Get number of transactions the merkle proof is indicating for cross-reference with
112 : : * local blockchain knowledge.
113 : : */
114 [ # # ]: 0 : unsigned int GetNumTransactions() const { return nTransactions; };
115 : :
116 : : };
117 : :
118 : :
119 : : /**
120 : : * Used to relay blocks as header + vector<merkle branch>
121 : : * to filtered nodes.
122 : : *
123 : : * NOTE: The class assumes that the given CBlock has *at least* 1 transaction. If the CBlock has 0 txs, it will hit an assertion.
124 : : */
125 : : class CMerkleBlock
126 : : {
127 : : public:
128 : : /** Public only for unit testing */
129 : : CBlockHeader header;
130 : : CPartialMerkleTree txn;
131 : :
132 : : /**
133 : : * Public only for unit testing and relay testing (not relayed).
134 : : *
135 : : * Used only when a bloom filter is specified to allow
136 : : * testing the transactions which matched the bloom filter.
137 : : */
138 : : std::vector<std::pair<unsigned int, uint256> > vMatchedTxn;
139 : :
140 : : /**
141 : : * Create from a CBlock, filtering transactions according to filter
142 : : * Note that this will call IsRelevantAndUpdate on the filter for each transaction,
143 : : * thus the filter will likely be modified.
144 : : */
145 [ # # ]: 0 : CMerkleBlock(const CBlock& block, CBloomFilter& filter) : CMerkleBlock(block, &filter, nullptr) { }
146 : :
147 : : // Create from a CBlock, matching the txids in the set
148 [ # # ]: 0 : CMerkleBlock(const CBlock& block, const std::set<Txid>& txids) : CMerkleBlock{block, nullptr, &txids} {}
149 : :
150 : 0 : CMerkleBlock() = default;
151 : :
152 : 0 : SERIALIZE_METHODS(CMerkleBlock, obj) { READWRITE(obj.header, obj.txn); }
153 : :
154 : : private:
155 : : // Combined constructor to consolidate code
156 : : CMerkleBlock(const CBlock& block, CBloomFilter* filter, const std::set<Txid>* txids);
157 : : };
158 : :
159 : : #endif // BITCOIN_MERKLEBLOCK_H
|
