1 // Copyright (c) 2018-2022 The Limenka developers
2 // Distributed under the MIT software license, see the accompanying
3 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
4 5 #ifndef LIMENKA_INTERFACES_CHAIN_H
6 #define LIMENKA_INTERFACES_CHAIN_H
7 8 #include <blockfilter.h>
9 #include <common/settings.h>
10 #include <primitives/block.h>
11 #include <primitives/transaction.h> // For CTransactionRef
12 #include <util/result.h>
13 14 #include <any>
15 #include <functional>
16 #include <memory>
17 #include <optional>
18 #include <stddef.h>
19 #include <stdint.h>
20 #include <string>
21 #include <vector>
22 23 class ArgsManager;
24 class CBlock;
25 class CBlockUndo;
26 class CFeeRate;
27 class CRPCCommand;
28 class CScheduler;
29 class Coin;
30 class uint256;
31 enum class MemPoolRemovalReason;
32 enum class RBFTransactionState;
33 enum class ChainstateRole;
34 struct bilingual_str;
35 struct CBlockLocator;
36 struct FeeCalculation;
37 namespace node {
38 struct NodeContext;
39 struct PruneLockInfo;
40 } // namespace node
41 42 namespace interfaces {
43 44 class Handler;
45 class Wallet;
46 47 //! Helper for findBlock to selectively return pieces of block data. If block is
48 //! found, data will be returned by setting specified output variables. If block
49 //! is not found, output variables will keep their previous values.
50 class FoundBlock
51 {
52 public:
53 FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
54 FoundBlock& height(int& height) { m_height = &height; return *this; }
55 FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
56 FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
57 FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
58 //! Return whether block is in the active (most-work) chain.
59 FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
60 //! Return locator if block is in the active chain.
61 FoundBlock& locator(CBlockLocator& locator) { m_locator = &locator; return *this; }
62 //! Return next block in the active chain if current block is in the active chain.
63 FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
64 //! Read block data from disk. If the block exists but doesn't have data
65 //! (for example due to pruning), the CBlock variable will be set to null.
66 FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
67 68 uint256* m_hash = nullptr;
69 int* m_height = nullptr;
70 int64_t* m_time = nullptr;
71 int64_t* m_max_time = nullptr;
72 int64_t* m_mtp_time = nullptr;
73 bool* m_in_active_chain = nullptr;
74 CBlockLocator* m_locator = nullptr;
75 const FoundBlock* m_next_block = nullptr;
76 CBlock* m_data = nullptr;
77 mutable bool found = false;
78 };
79 80 //! Block data sent with blockConnected, blockDisconnected notifications.
81 struct BlockInfo {
82 const uint256& hash;
83 const uint256* prev_hash = nullptr;
84 int height = -1;
85 int file_number = -1;
86 unsigned data_pos = 0;
87 const CBlock* data = nullptr;
88 const CBlockUndo* undo_data = nullptr;
89 // The maximum time in the chain up to and including this block.
90 // A timestamp that can only move forward.
91 unsigned int chain_time_max{0};
92 93 BlockInfo(const uint256& hash LIFETIMEBOUND) : hash(hash) {}
94 };
95 96 //! The action to be taken after updating a settings value.
97 //! WRITE indicates that the updated value must be written to disk,
98 //! while SKIP_WRITE indicates that the change will be kept in memory-only
99 //! without persisting it.
100 enum class SettingsAction {
101 WRITE,
102 SKIP_WRITE
103 };
104 105 using SettingsUpdate = std::function<std::optional<interfaces::SettingsAction>(common::SettingsValue&)>;
106 107 //! Interface giving clients (wallet processes, maybe other analysis tools in
108 //! the future) ability to access to the chain state, receive notifications,
109 //! estimate fees, and submit transactions.
110 //!
111 //! TODO: Current chain methods are too low level, exposing too much of the
112 //! internal workings of the limenka node, and not being very convenient to use.
113 //! Chain methods should be cleaned up and simplified over time. Examples:
114 //!
115 //! * The initMessages() and showProgress() methods which the wallet uses to send
116 //! notifications to the GUI should go away when GUI and wallet can directly
117 //! communicate with each other without going through the node
118 //! (https://github.com/limenka/limenka/pull/15288#discussion_r253321096).
119 //!
120 //! * The handleRpc, registerRpcs, rpcEnableDeprecated methods and other RPC
121 //! methods can go away if wallets listen for HTTP requests on their own
122 //! ports instead of registering to handle requests on the node HTTP port.
123 //!
124 //! * Move fee estimation queries to an asynchronous interface and let the
125 //! wallet cache it, fee estimation being driven by node mempool, wallet
126 //! should be the consumer.
127 //!
128 //! * `guessVerificationProgress` and similar methods can go away if rescan
129 //! logic moves out of the wallet, and the wallet just requests scans from the
130 //! node (https://github.com/limenka/limenka/issues/11756)
131 class Chain
132 {
133 public:
134 virtual ~Chain() = default;
135 136 //! Get current chain height, not including genesis block (returns 0 if
137 //! chain only contains genesis block, nullopt if chain does not contain
138 //! any blocks)
139 virtual std::optional<int> getHeight() = 0;
140 141 //! Get block hash. Height must be valid or this function will abort.
142 virtual uint256 getBlockHash(int height) = 0;
143 144 //! Check that the block is available on disk (i.e. has not been
145 //! pruned), and contains transactions.
146 virtual bool haveBlockOnDisk(int height) = 0;
147 148 virtual bool pruneLockExists(const std::string& name) const = 0;
149 virtual bool updatePruneLock(const std::string& name, const node::PruneLockInfo& lock_info, bool sync=false) = 0;
150 virtual bool deletePruneLock(const std::string& name) = 0;
151 152 //! Get locator for the current chain tip.
153 virtual CBlockLocator getTipLocator() = 0;
154 //! Median time past of the active tip (fork-activation gating). The
155 //! default derives it through the locator so IPC proxies need no
156 //! schema change; node implementations override it directly.
157 virtual int64_t getTipMtp()
158 {
159 CBlockLocator locator = getTipLocator();
160 if (locator.IsNull()) return 0;
161 int64_t mtp{0};
162 if (!findBlock(locator.vHave.front(), FoundBlock().mtpTime(mtp))) return 0;
163 return mtp;
164 }
165 166 //! Return a locator that refers to a block in the active chain.
167 //! If specified block is not in the active chain, return locator for the latest ancestor that is in the chain.
168 virtual CBlockLocator getActiveChainLocator(const uint256& block_hash) = 0;
169 170 //! Return height of the highest block on chain in common with the locator,
171 //! which will either be the original block used to create the locator,
172 //! or one of its ancestors.
173 virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
174 175 //! Returns whether a block filter index is available.
176 virtual bool hasBlockFilterIndex(BlockFilterType filter_type) = 0;
177 178 //! Returns whether any of the elements match the block via a BIP 157 block filter
179 //! or std::nullopt if the block filter for this block couldn't be found.
180 virtual std::optional<bool> blockFilterMatchesAny(BlockFilterType filter_type, const uint256& block_hash, const GCSFilter::ElementSet& filter_set) = 0;
181 182 //! Return whether node has the block and optionally return block metadata
183 //! or contents.
184 virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
185 186 //! Find first block in the chain with timestamp >= the given time
187 //! and height >= than the given height, return false if there is no block
188 //! with a high enough timestamp and height. Optionally return block
189 //! information.
190 virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
191 192 //! Find ancestor of block at specified height and optionally return
193 //! ancestor information.
194 virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
195 196 //! Return whether block descends from a specified ancestor, and
197 //! optionally return ancestor information.
198 virtual bool findAncestorByHash(const uint256& block_hash,
199 const uint256& ancestor_hash,
200 const FoundBlock& ancestor_out={}) = 0;
201 202 //! Find most recent common ancestor between two blocks and optionally
203 //! return block information.
204 virtual bool findCommonAncestor(const uint256& block_hash1,
205 const uint256& block_hash2,
206 const FoundBlock& ancestor_out={},
207 const FoundBlock& block1_out={},
208 const FoundBlock& block2_out={}) = 0;
209 210 //! Look up unspent output information. Returns coins in the mempool and in
211 //! the current chain UTXO set. Iterates through all the keys in the map and
212 //! populates the values.
213 virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
214 215 //! Estimate fraction of total transactions verified if blocks up to
216 //! the specified block hash are verified.
217 virtual double guessVerificationProgress(const uint256& block_hash) = 0;
218 219 //! Return true if data is available for all blocks in the specified range
220 //! of blocks. This checks all blocks that are ancestors of block_hash in
221 //! the height range from min_height to max_height, inclusive.
222 virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
223 224 //! Check if transaction is RBF opt in.
225 virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;
226 227 //! Check if transaction is in mempool.
228 virtual bool isInMempool(const uint256& txid) = 0;
229 230 //! Check if transaction has descendants in mempool.
231 virtual bool hasDescendantsInMempool(const uint256& txid) = 0;
232 233 //! Transaction is added to memory pool, if the transaction fee is below the
234 //! amount specified by max_tx_fee, and broadcast to all peers if relay is set to true.
235 //! Return false if the transaction could not be added due to the fee or for another reason.
236 virtual bool broadcastTransaction(const CTransactionRef& tx,
237 const CAmount& max_tx_fee,
238 bool relay,
239 std::string& err_string) = 0;
240 241 //! Calculate mempool ancestor and descendant counts for the given transaction.
242 virtual void getTransactionAncestry(const uint256& txid, size_t& ancestors, size_t& descendants, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
243 244 //! For each outpoint, calculate the fee-bumping cost to spend this outpoint at the specified
245 // feerate, including bumping its ancestors. For example, if the target feerate is 10sat/vbyte
246 // and this outpoint refers to a mempool transaction at 3sat/vbyte, the bump fee includes the
247 // cost to bump the mempool transaction to 10sat/vbyte (i.e. 7 * mempooltx.vsize). If that
248 // transaction also has, say, an unconfirmed parent with a feerate of 1sat/vbyte, the bump fee
249 // includes the cost to bump the parent (i.e. 9 * parentmempooltx.vsize).
250 //
251 // If the outpoint comes from an unconfirmed transaction that is already above the target
252 // feerate or bumped by its descendant(s) already, it does not need to be bumped. Its bump fee
253 // is 0. Likewise, if any of the transaction's ancestors are already bumped by a transaction
254 // in our mempool, they are not included in the transaction's bump fee.
255 //
256 // Also supported is bump-fee calculation in the case of replacements. If an outpoint
257 // conflicts with another transaction in the mempool, it is assumed that the goal is to replace
258 // that transaction. As such, the calculation will exclude the to-be-replaced transaction, but
259 // will include the fee-bumping cost. If bump fees of descendants of the to-be-replaced
260 // transaction are requested, the value will be 0. Fee-related RBF rules are not included as
261 // they are logically distinct.
262 //
263 // Any outpoints that are otherwise unavailable from the mempool (e.g. UTXOs from confirmed
264 // transactions or transactions not yet broadcast by the wallet) are given a bump fee of 0.
265 //
266 // If multiple outpoints come from the same transaction (which would be very rare because
267 // it means that one transaction has multiple change outputs or paid the same wallet using multiple
268 // outputs in the same transaction) or have shared ancestry, the bump fees are calculated
269 // independently, i.e. as if only one of them is spent. This may result in double-fee-bumping. This
270 // caveat can be rectified per use of the sister-function CalculateCombinedBumpFee(…).
271 virtual std::map<COutPoint, CAmount> calculateIndividualBumpFees(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
272 273 //! Calculate the combined bump fee for an input set per the same strategy
274 // as in CalculateIndividualBumpFees(…).
275 // Unlike CalculateIndividualBumpFees(…), this does not return individual
276 // bump fees per outpoint, but a single bump fee for the shared ancestry.
277 // The combined bump fee may be used to correct overestimation due to
278 // shared ancestry by multiple UTXOs after coin selection.
279 virtual std::optional<CAmount> calculateCombinedBumpFee(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
280 281 //! Get the node's package limits.
282 //! Currently only returns the ancestor and descendant count limits, but could be enhanced to
283 //! return more policy settings.
284 virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;
285 286 //! Check if transaction will pass the mempool's chain limits.
287 virtual util::Result<void> checkChainLimits(const CTransactionRef& tx) = 0;
288 289 //! Estimate smart fee.
290 virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;
291 292 //! Fee estimator max target.
293 virtual unsigned int estimateMaxBlocks() = 0;
294 295 //! Mempool minimum fee.
296 virtual CFeeRate mempoolMinFee() = 0;
297 298 //! Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).
299 virtual CFeeRate relayMinFee() = 0;
300 301 //! Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.
302 virtual CFeeRate relayIncrementalFee() = 0;
303 304 //! Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
305 virtual CFeeRate relayDustFee() = 0;
306 307 //! Check if any block has been pruned.
308 virtual bool havePruned() = 0;
309 310 //! Get the current prune height.
311 virtual std::optional<int> getPruneHeight() = 0;
312 313 //! Check if the node is ready to broadcast transactions.
314 virtual bool isReadyToBroadcast() = 0;
315 316 //! Check if in IBD.
317 virtual bool isInitialBlockDownload() = 0;
318 319 //! Check if shutdown requested.
320 virtual bool shutdownRequested() = 0;
321 322 //! Send init message.
323 virtual void initMessage(const std::string& message) = 0;
324 325 //! Send init warning.
326 virtual void initWarning(const bilingual_str& message) = 0;
327 328 //! Send init error.
329 virtual void initError(const bilingual_str& message) = 0;
330 331 //! Ask init question.
332 virtual bool initQuestion(const bilingual_str& message, const bilingual_str& non_interactive_message, const bilingual_str& caption, unsigned int style) = 0;
333 334 //! Send progress indicator.
335 virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;
336 337 //! Chain notifications.
338 class Notifications
339 {
340 public:
341 virtual ~Notifications() = default;
342 virtual void transactionAddedToMempool(const CTransactionRef& tx) {}
343 virtual void transactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason) {}
344 virtual void blockConnected(ChainstateRole role, const BlockInfo& block) {}
345 virtual void blockDisconnected(const BlockInfo& block) {}
346 virtual void updatedBlockTip() {}
347 virtual void chainStateFlushed(ChainstateRole role, const CBlockLocator& locator) {}
348 };
349 350 //! Register handler for notifications.
351 //! Some notifications are asynchronous and may still execute after the handler is disconnected.
352 //! Use waitForNotifications() after the handler is disconnected to ensure all pending notifications
353 //! have been processed.
354 virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
355 356 //! Wait for pending notifications to be processed unless block hash points to the current
357 //! chain tip.
358 virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
359 360 //! Wait for all pending notifications up to this point to be processed
361 virtual void waitForNotifications() = 0;
362 363 //! Register handler for RPC. Command is not copied, so reference
364 //! needs to remain valid until Handler is disconnected.
365 virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;
366 367 //! Check if deprecated RPC is enabled.
368 virtual bool rpcEnableDeprecated(const std::string& method) = 0;
369 370 //! Run function after given number of seconds. Cancel any previous calls with same name.
371 virtual void rpcRunLater(const std::string& name, std::function<void()> fn, int64_t seconds) = 0;
372 373 //! Get settings value.
374 virtual common::SettingsValue getSetting(const std::string& arg) = 0;
375 376 //! Get list of settings values.
377 virtual std::vector<common::SettingsValue> getSettingsList(const std::string& arg) = 0;
378 379 //! Return <datadir>/settings.json setting value.
380 virtual common::SettingsValue getRwSetting(const std::string& name) = 0;
381 382 //! Updates a setting in <datadir>/settings.json.
383 //! Null can be passed to erase the setting. There is intentionally no
384 //! support for writing null values to settings.json.
385 //! Depending on the action returned by the update function, this will either
386 //! update the setting in memory or write the updated settings to disk.
387 virtual bool updateRwSetting(const std::string& name, const SettingsUpdate& update_function) = 0;
388 389 //! Replace a setting in <datadir>/settings.json with a new value.
390 //! Null can be passed to erase the setting.
391 //! This method provides a simpler alternative to updateRwSetting when
392 //! atomically reading and updating the setting is not required.
393 virtual bool overwriteRwSetting(const std::string& name, common::SettingsValue value, SettingsAction action = SettingsAction::WRITE) = 0;
394 395 //! Delete a given setting in <datadir>/settings.json.
396 //! This method provides a simpler alternative to overwriteRwSetting when
397 //! erasing a setting, for ease of use and readability.
398 virtual bool deleteRwSettings(const std::string& name, SettingsAction action = SettingsAction::WRITE) = 0;
399 400 //! Synchronously send transactionAddedToMempool notifications about all
401 //! current mempool transactions to the specified handler and return after
402 //! the last one is sent. These notifications aren't coordinated with async
403 //! notifications sent by handleNotifications, so out of date async
404 //! notifications from handleNotifications can arrive during and after
405 //! synchronous notifications from requestMempoolTransactions. Clients need
406 //! to be prepared to handle this by ignoring notifications about unknown
407 //! removed transactions and already added new transactions.
408 virtual void requestMempoolTransactions(Notifications& notifications) = 0;
409 410 //! Return true if an assumed-valid chain is in use.
411 virtual bool hasAssumedValidChain() = 0;
412 413 //! Get internal node context. Useful for testing, but not
414 //! accessible across processes.
415 virtual node::NodeContext* context() { return nullptr; }
416 };
417 418 //! Interface to let node manage chain clients (wallets, or maybe tools for
419 //! monitoring and analysis in the future).
420 class ChainClient
421 {
422 public:
423 virtual ~ChainClient() = default;
424 425 virtual void assignContextHACK(std::any&) {};
426 427 //! Register rpcs.
428 virtual void registerRpcs() = 0;
429 430 //! Check for errors before loading.
431 virtual bool verify() = 0;
432 433 //! Load saved state.
434 virtual bool load() = 0;
435 436 //! Start client execution and provide a scheduler.
437 virtual void start(CScheduler& scheduler) = 0;
438 439 //! Save state to disk.
440 virtual void flush() = 0;
441 442 //! Shut down client.
443 virtual void stop() = 0;
444 445 //! Set mock time.
446 virtual void setMockTime(int64_t time) = 0;
447 448 //! Mock the scheduler to fast forward in time.
449 virtual void schedulerMockForward(std::chrono::seconds delta_seconds) = 0;
450 };
451 452 //! Return implementation of Chain interface.
453 std::unique_ptr<Chain> MakeChain(node::NodeContext& node);
454 455 } // namespace interfaces
456 457 #endif // LIMENKA_INTERFACES_CHAIN_H
458