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