/workdir/bitcoin/src/merkleblock.h

Source (jump to first uncovered line)
// Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2021 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#ifndef BITCOIN_MERKLEBLOCK_H
#define BITCOIN_MERKLEBLOCK_H

#include <common/bloom.h>
#include <primitives/block.h>
#include <serialize.h>
#include <uint256.h>

#include <set>
#include <vector>

// Helper functions for serialization.
std::vector<unsigned char> BitsToBytes(const std::vector<bool>& bits);
std::vector<bool> BytesToBits(const std::vector<unsigned char>& bytes);

/** Data structure that represents a partial merkle tree.
 *
 * It represents a subset of the txid's of a known block, in a way that
 * allows recovery of the list of txid's and the merkle root, in an
 * authenticated way.
 *
 * The encoding works as follows: we traverse the tree in depth-first order,
 * storing a bit for each traversed node, signifying whether the node is the
 * parent of at least one matched leaf txid (or a matched txid itself). In
 * case we are at the leaf level, or this bit is 0, its merkle node hash is
 * stored, and its children are not explored further. Otherwise, no hash is
 * stored, but we recurse into both (or the only) child branch. During
 * decoding, the same depth-first traversal is performed, consuming bits and
 * hashes as they written during encoding.
 *
 * The serialization is fixed and provides a hard guarantee about the
 * encoded size:
 *
 *   SIZE <= 10 + ceil(32.25*N)
 *
 * Where N represents the number of leaf nodes of the partial tree. N itself
 * is bounded by:
 *
 *   N <= total_transactions
 *   N <= 1 + matched_transactions*tree_height
 *
 * The serialization format:
 *  - uint32     total_transactions (4 bytes)
 *  - varint     number of hashes   (1-3 bytes)
 *  - uint256[]  hashes in depth-first order (<= 32*N bytes)
 *  - varint     number of bytes of flag bits (1-3 bytes)
 *  - byte[]     flag bits, packed per 8 in a byte, least significant bit first (<= 2*N-1 bits)
 * The size constraints follow from this.
 */
class CPartialMerkleTree
{
protected:
    /** the total number of transactions in the block */
    unsigned int nTransactions;

    /** node-is-parent-of-matched-txid bits */
    std::vector<bool> vBits;

    /** txids and internal hashes */
    std::vector<uint256> vHash;

    /** flag set when encountering invalid data */
    bool fBad;

    /** helper function to efficiently calculate the number of nodes at given height in the merkle tree */
    unsigned int CalcTreeWidth(int height) const {
        return (nTransactions+(1 << height)-1) >> height;
    }

    /** calculate the hash of a node in the merkle tree (at leaf level: the txid's themselves) */
    uint256 CalcHash(int height, unsigned int pos, const std::vector<uint256> &vTxid);

    /** recursive function that traverses tree nodes, storing the data as bits and hashes */
    void TraverseAndBuild(int height, unsigned int pos, const std::vector<uint256> &vTxid, const std::vector<bool> &vMatch);

    /**
     * recursive function that traverses tree nodes, consuming the bits and hashes produced by TraverseAndBuild.
     * it returns the hash of the respective node and its respective index.
     */
    uint256 TraverseAndExtract(int height, unsigned int pos, unsigned int &nBitsUsed, unsigned int &nHashUsed, std::vector<uint256> &vMatch, std::vector<unsigned int> &vnIndex);

public:

    SERIALIZE_METHODS(CPartialMerkleTree, obj)
    {
        READWRITE(obj.nTransactions, obj.vHash);
        std::vector<unsigned char> bytes;
        SER_WRITE(obj, bytes = BitsToBytes(obj.vBits));
        READWRITE(bytes);
        SER_READ(obj, obj.vBits = BytesToBits(bytes));
        SER_READ(obj, obj.fBad = false);
    }

    /** Construct a partial merkle tree from a list of transaction ids, and a mask that selects a subset of them */
    CPartialMerkleTree(const std::vector<uint256> &vTxid, const std::vector<bool> &vMatch);

    CPartialMerkleTree();

    /**
     * extract the matching txid's represented by this partial merkle tree
     * and their respective indices within the partial tree.
     * returns the merkle root, or 0 in case of failure
     */
    uint256 ExtractMatches(std::vector<uint256> &vMatch, std::vector<unsigned int> &vnIndex);

    /** Get number of transactions the merkle proof is indicating for cross-reference with
     * local blockchain knowledge.
     */
    unsigned int GetNumTransactions() const { return nTransactions; };

};


/**
 * Used to relay blocks as header + vector<merkle branch>
 * to filtered nodes.
 *
 * NOTE: The class assumes that the given CBlock has *at least* 1 transaction. If the CBlock has 0 txs, it will hit an assertion.
 */
class CMerkleBlock
{
public:
    /** Public only for unit testing */
    CBlockHeader header;
    CPartialMerkleTree txn;

    /**
     * Public only for unit testing and relay testing (not relayed).
     *
     * Used only when a bloom filter is specified to allow
     * testing the transactions which matched the bloom filter.
     */
    std::vector<std::pair<unsigned int, uint256> > vMatchedTxn;

    /**
     * Create from a CBlock, filtering transactions according to filter
     * Note that this will call IsRelevantAndUpdate on the filter for each transaction,
     * thus the filter will likely be modified.
     */
    CMerkleBlock(const CBlock& block, CBloomFilter& filter) : CMerkleBlock(block, &filter, nullptr) { }

    // Create from a CBlock, matching the txids in the set
    CMerkleBlock(const CBlock& block, const std::set<Txid>& txids) : CMerkleBlock{block, nullptr, &txids} {}

    CMerkleBlock() = default;

    SERIALIZE_METHODS(CMerkleBlock, obj) { READWRITE(obj.header, obj.txn); }

private:
    // Combined constructor to consolidate code
    CMerkleBlock(const CBlock& block, CBloomFilter* filter, const std::set<Txid>* txids);
};

#endif // BITCOIN_MERKLEBLOCK_H

Line	Count	Source (jump to first uncovered line)
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		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	0	}
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		SERIALIZE_METHODS(CPartialMerkleTree, obj)
90	0	{
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	} Unexecuted instantiation: void CPartialMerkleTree::SerializationOps<DataStream, CPartialMerkleTree, ActionUnserialize>(CPartialMerkleTree&, DataStream&, ActionUnserialize) Unexecuted instantiation: void CPartialMerkleTree::SerializationOps<DataStream, CPartialMerkleTree const, ActionSerialize>(CPartialMerkleTree const&, DataStream&, ActionSerialize) Unexecuted instantiation: void CPartialMerkleTree::SerializationOps<VectorWriter, CPartialMerkleTree const, ActionSerialize>(CPartialMerkleTree const&, VectorWriter&, ActionSerialize)
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); } Unexecuted instantiation: void CMerkleBlock::SerializationOps<DataStream, CMerkleBlock, ActionUnserialize>(CMerkleBlock&, DataStream&, ActionUnserialize) Unexecuted instantiation: void CMerkleBlock::SerializationOps<DataStream, CMerkleBlock const, ActionSerialize>(CMerkleBlock const&, DataStream&, ActionSerialize) Unexecuted instantiation: void CMerkleBlock::SerializationOps<VectorWriter, CMerkleBlock const, ActionSerialize>(CMerkleBlock const&, VectorWriter&, ActionSerialize)
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

Coverage Report

Created: 2024-08-21 05:08