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 <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 : 580086 : unsigned int CalcTreeWidth(int height) const {
# 71 : 580086 : return (nTransactions+(1 << height)-1) >> height;
# 72 : 580086 : }
# 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 : : SERIALIZE_METHODS(CPartialMerkleTree, obj)
# 89 : 718 : {
# 90 : 718 : READWRITE(obj.nTransactions, obj.vHash);
# 91 : 718 : std::vector<unsigned char> bytes;
# 92 : 718 : SER_WRITE(obj, bytes = BitsToBytes(obj.vBits));
# 93 : 718 : READWRITE(bytes);
# 94 : 718 : SER_READ(obj, obj.vBits = BytesToBits(bytes));
# 95 : 718 : SER_READ(obj, obj.fBad = false);
# 96 : 718 : }
# 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 : 13 : 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 : 26 : CMerkleBlock(const CBlock& block, CBloomFilter& filter) : CMerkleBlock(block, &filter, nullptr) { }
# 145 : :
# 146 : : // Create from a CBlock, matching the txids in the set
# 147 : 19 : CMerkleBlock(const CBlock& block, const std::set<uint256>& txids) : CMerkleBlock(block, nullptr, &txids) { }
# 148 : :
# 149 : 32 : CMerkleBlock() {}
# 150 : :
# 151 : 46 : 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
|