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