Bitcoin Core  25.99.0
P2P Digital Currency
txoutproof.cpp
Go to the documentation of this file.
1 // Copyright (c) 2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2022 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 #include <chain.h>
7 #include <chainparams.h>
8 #include <coins.h>
9 #include <index/txindex.h>
10 #include <merkleblock.h>
11 #include <node/blockstorage.h>
12 #include <primitives/transaction.h>
13 #include <rpc/server.h>
14 #include <rpc/server_util.h>
15 #include <rpc/util.h>
16 #include <univalue.h>
17 #include <util/strencodings.h>
18 #include <validation.h>
19 
21 
23 {
24  return RPCHelpMan{"gettxoutproof",
25  "\nReturns a hex-encoded proof that \"txid\" was included in a block.\n"
26  "\nNOTE: By default this function only works sometimes. This is when there is an\n"
27  "unspent output in the utxo for this transaction. To make it always work,\n"
28  "you need to maintain a transaction index, using the -txindex command line option or\n"
29  "specify the block in which the transaction is included manually (by blockhash).\n",
30  {
31  {"txids", RPCArg::Type::ARR, RPCArg::Optional::NO, "The txids to filter",
32  {
33  {"txid", RPCArg::Type::STR_HEX, RPCArg::Optional::OMITTED, "A transaction hash"},
34  },
35  },
36  {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::OMITTED, "If specified, looks for txid in the block with this hash"},
37  },
38  RPCResult{
39  RPCResult::Type::STR, "data", "A string that is a serialized, hex-encoded data for the proof."
40  },
41  RPCExamples{""},
42  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
43  {
44  std::set<uint256> setTxids;
45  UniValue txids = request.params[0].get_array();
46  if (txids.empty()) {
47  throw JSONRPCError(RPC_INVALID_PARAMETER, "Parameter 'txids' cannot be empty");
48  }
49  for (unsigned int idx = 0; idx < txids.size(); idx++) {
50  auto ret = setTxids.insert(ParseHashV(txids[idx], "txid"));
51  if (!ret.second) {
52  throw JSONRPCError(RPC_INVALID_PARAMETER, std::string("Invalid parameter, duplicated txid: ") + txids[idx].get_str());
53  }
54  }
55 
56  const CBlockIndex* pblockindex = nullptr;
57  uint256 hashBlock;
58  ChainstateManager& chainman = EnsureAnyChainman(request.context);
59  if (!request.params[1].isNull()) {
60  LOCK(cs_main);
61  hashBlock = ParseHashV(request.params[1], "blockhash");
62  pblockindex = chainman.m_blockman.LookupBlockIndex(hashBlock);
63  if (!pblockindex) {
64  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Block not found");
65  }
66  } else {
67  LOCK(cs_main);
68  Chainstate& active_chainstate = chainman.ActiveChainstate();
69 
70  // Loop through txids and try to find which block they're in. Exit loop once a block is found.
71  for (const auto& tx : setTxids) {
72  const Coin& coin = AccessByTxid(active_chainstate.CoinsTip(), tx);
73  if (!coin.IsSpent()) {
74  pblockindex = active_chainstate.m_chain[coin.nHeight];
75  break;
76  }
77  }
78  }
79 
80 
81  // Allow txindex to catch up if we need to query it and before we acquire cs_main.
82  if (g_txindex && !pblockindex) {
83  g_txindex->BlockUntilSyncedToCurrentChain();
84  }
85 
86  if (pblockindex == nullptr) {
87  const CTransactionRef tx = GetTransaction(/*block_index=*/nullptr, /*mempool=*/nullptr, *setTxids.begin(), hashBlock, chainman.m_blockman);
88  if (!tx || hashBlock.IsNull()) {
89  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Transaction not yet in block");
90  }
91 
92  LOCK(cs_main);
93  pblockindex = chainman.m_blockman.LookupBlockIndex(hashBlock);
94  if (!pblockindex) {
95  throw JSONRPCError(RPC_INTERNAL_ERROR, "Transaction index corrupt");
96  }
97  }
98 
99  CBlock block;
100  if (!chainman.m_blockman.ReadBlockFromDisk(block, *pblockindex)) {
101  throw JSONRPCError(RPC_INTERNAL_ERROR, "Can't read block from disk");
102  }
103 
104  unsigned int ntxFound = 0;
105  for (const auto& tx : block.vtx) {
106  if (setTxids.count(tx->GetHash())) {
107  ntxFound++;
108  }
109  }
110  if (ntxFound != setTxids.size()) {
111  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Not all transactions found in specified or retrieved block");
112  }
113 
114  DataStream ssMB{};
115  CMerkleBlock mb(block, setTxids);
116  ssMB << mb;
117  std::string strHex = HexStr(ssMB);
118  return strHex;
119  },
120  };
121 }
122 
124 {
125  return RPCHelpMan{"verifytxoutproof",
126  "\nVerifies that a proof points to a transaction in a block, returning the transaction it commits to\n"
127  "and throwing an RPC error if the block is not in our best chain\n",
128  {
129  {"proof", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The hex-encoded proof generated by gettxoutproof"},
130  },
131  RPCResult{
132  RPCResult::Type::ARR, "", "",
133  {
134  {RPCResult::Type::STR_HEX, "txid", "The txid(s) which the proof commits to, or empty array if the proof cannot be validated."},
135  }
136  },
137  RPCExamples{""},
138  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
139  {
140  DataStream ssMB{ParseHexV(request.params[0], "proof")};
141  CMerkleBlock merkleBlock;
142  ssMB >> merkleBlock;
143 
145 
146  std::vector<uint256> vMatch;
147  std::vector<unsigned int> vIndex;
148  if (merkleBlock.txn.ExtractMatches(vMatch, vIndex) != merkleBlock.header.hashMerkleRoot)
149  return res;
150 
151  ChainstateManager& chainman = EnsureAnyChainman(request.context);
152  LOCK(cs_main);
153 
154  const CBlockIndex* pindex = chainman.m_blockman.LookupBlockIndex(merkleBlock.header.GetHash());
155  if (!pindex || !chainman.ActiveChain().Contains(pindex) || pindex->nTx == 0) {
156  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Block not found in chain");
157  }
158 
159  // Check if proof is valid, only add results if so
160  if (pindex->nTx == merkleBlock.txn.GetNumTransactions()) {
161  for (const uint256& hash : vMatch) {
162  res.push_back(hash.GetHex());
163  }
164  }
165 
166  return res;
167  },
168  };
169 }
170 
172 {
173  static const CRPCCommand commands[]{
174  {"blockchain", &gettxoutproof},
175  {"blockchain", &verifytxoutproof},
176  };
177  for (const auto& c : commands) {
178  t.appendCommand(c.name, &c);
179  }
180 }
int ret
uint256 hashMerkleRoot
Definition: block.h:27
uint256 GetHash() const
Definition: block.cpp:11
Definition: block.h:69
std::vector< CTransactionRef > vtx
Definition: block.h:72
The block chain is a tree shaped structure starting with the genesis block at the root,...
Definition: chain.h:159
unsigned int nTx
Number of transactions in this block.
Definition: chain.h:190
bool Contains(const CBlockIndex *pindex) const
Efficiently check whether a block is present in this chain.
Definition: chain.h:482
Used to relay blocks as header + vector<merkle branch> to filtered nodes.
Definition: merkleblock.h:125
CBlockHeader header
Public only for unit testing.
Definition: merkleblock.h:128
CPartialMerkleTree txn
Definition: merkleblock.h:129
uint256 ExtractMatches(std::vector< uint256 > &vMatch, std::vector< unsigned int > &vnIndex)
extract the matching txid's represented by this partial merkle tree and their respective indices with...
unsigned int GetNumTransactions() const
Get number of transactions the merkle proof is indicating for cross-reference with local blockchain k...
Definition: merkleblock.h:113
RPC command dispatcher.
Definition: server.h:135
Chainstate stores and provides an API to update our local knowledge of the current best chain.
Definition: validation.h:466
CChain m_chain
The current chain of blockheaders we consult and build on.
Definition: validation.h:540
CCoinsViewCache & CoinsTip() EXCLUSIVE_LOCKS_REQUIRED(
Definition: validation.h:565
Provides an interface for creating and interacting with one or two chainstates: an IBD chainstate gen...
Definition: validation.h:818
CChain & ActiveChain() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
Definition: validation.h:1039
node::BlockManager m_blockman
A single BlockManager instance is shared across each constructed chainstate to avoid duplicating bloc...
Definition: validation.h:939
A UTXO entry.
Definition: coins.h:32
bool IsSpent() const
Either this coin never existed (see e.g.
Definition: coins.h:80
uint32_t nHeight
at which height this containing transaction was included in the active block chain
Definition: coins.h:41
Double ended buffer combining vector and stream-like interfaces.
Definition: streams.h:204
void push_back(UniValue val)
Definition: univalue.cpp:104
@ VARR
Definition: univalue.h:23
size_t size() const
Definition: univalue.h:70
bool empty() const
Definition: univalue.h:68
const UniValue & get_array() const
constexpr bool IsNull() const
Definition: uint256.h:42
bool ReadBlockFromDisk(CBlock &block, const FlatFilePos &pos) const
Functions for disk access for blocks.
CBlockIndex * LookupBlockIndex(const uint256 &hash) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
256-bit opaque blob.
Definition: uint256.h:106
const Coin & AccessByTxid(const CCoinsViewCache &view, const uint256 &txid)
Utility function to find any unspent output with a given txid.
Definition: coins.cpp:345
RecursiveMutex cs_main
Mutex to guard access to validation specific variables, such as reading or changing the chainstate.
Definition: cs_main.cpp:8
CTransactionRef GetTransaction(const CBlockIndex *const block_index, const CTxMemPool *const mempool, const uint256 &hash, uint256 &hashBlock, const BlockManager &blockman)
Return transaction with a given hash.
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:421
UniValue JSONRPCError(int code, const std::string &message)
Definition: request.cpp:58
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
Definition: protocol.h:43
@ RPC_INTERNAL_ERROR
Definition: protocol.h:35
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
Definition: protocol.h:41
std::vector< unsigned char > ParseHexV(const UniValue &v, std::string strName)
Definition: util.cpp:90
uint256 ParseHashV(const UniValue &v, std::string strName)
Utilities: convert hex-encoded Values (throws error if not hex).
Definition: util.cpp:77
ChainstateManager & EnsureAnyChainman(const std::any &context)
Definition: server_util.cpp:78
@ STR_HEX
Special type that is a STR with only hex chars.
@ OMITTED
Optional argument for which the default value is omitted from help text for one of two reasons:
@ NO
Required arg.
@ STR_HEX
Special string with only hex chars.
#define LOCK(cs)
Definition: sync.h:258
std::unique_ptr< TxIndex > g_txindex
The global transaction index, used in GetTransaction. May be null.
Definition: txindex.cpp:16
void RegisterTxoutProofRPCCommands(CRPCTable &t)
Definition: txoutproof.cpp:171
static RPCHelpMan gettxoutproof()
Definition: txoutproof.cpp:22
static RPCHelpMan verifytxoutproof()
Definition: txoutproof.cpp:123
std::string HexStr(const Span< const uint8_t > s)
Convert a span of bytes to a lower-case hexadecimal string.