[#node]
= node
:mrdocs:

Full&hyphen;node components that run the block, chainstate, and mempool machinery&period;

== Types

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockAssembler.adoc[`BlockAssembler`] 
| Generate a new block, without valid proof&hyphen;of&hyphen;work
| xref:node/BlockCheckOptions.adoc[`BlockCheckOptions`] 
| Options controlling which checks a block&hyphen;template validity check performs&period;
| xref:node/BlockCreateOptions.adoc[`BlockCreateOptions`] 
| Block template creation options&period; These override node defaults, but can&apos;t exceed node limits (e&period;g&period; block&lowbar;reserved&lowbar;weight can&apos;t exceed max block weight)&period;
| xref:node/BlockManager.adoc[`BlockManager`] 
| Maintains a tree of blocks (stored in `m&lowbar;block&lowbar;index`) which is consulted to determine where the most&hyphen;work tip is&period;
| xref:node/BlockWaitOptions.adoc[`BlockWaitOptions`] 
| Options controlling how long a block&hyphen;template wait call blocks and when it returns&period;
| xref:node/BlockfileCursor.adoc[`BlockfileCursor`] 
| Tracks the current block file and how far its undo data has been written&period;
| xref:node/CBlockIndexHeightOnlyComparator.adoc[`CBlockIndexHeightOnlyComparator`] 
| Orders block indices purely by height, without tie&hyphen;breaking&period;
| xref:node/CBlockIndexWorkComparator.adoc[`CBlockIndexWorkComparator`] 
| Orders block indices by most accumulated work, for choosing the best tip&period;
| xref:node/CBlockTemplate.adoc[`CBlockTemplate`] 
| A candidate block together with the per&hyphen;transaction data needed to finalize it&period;
| xref:node/CacheSizes.adoc[`CacheSizes`] 
| Cache sizes split between the optional indexes and the kernel (validation) caches&period;
| xref:node/ChainstateLoadOptions.adoc[`ChainstateLoadOptions`] 
| Options controlling how the chainstate is loaded and verified&period;
| xref:node/CoinbaseTx.adoc[`CoinbaseTx`] 
| Template containing all coinbase transaction fields that are set by our miner code&period; Clients are expected to add their own outputs and typically also expand the scriptSig&period;
| xref:node/ImportMempoolOptions.adoc[`ImportMempoolOptions`] 
| Options controlling how a persisted mempool file is imported&period;
| xref:node/IndexCacheSizes.adoc[`IndexCacheSizes`] 
| Cache sizes allotted to each optional block&hyphen;chain index&period;
| xref:node/IteratorComparator.adoc[`IteratorComparator`] 
| Comparator ordering map iterators by their key, for use in ordered sets of iterators&period;
| xref:node/KernelNotifications.adoc[`KernelNotifications`] 
| Kernel notification handler that tracks chain state for code above the validation layer&period;
| xref:node/KernelState.adoc[`KernelState`] 
| State tracked by the KernelNotifications interface meant to be used by mining code, index code, RPCs, and other code sitting above the validation layer&period;
| xref:node/MiniMiner.adoc[`MiniMiner`] 
| A minimal version of BlockAssembler, using the same ancestor set scoring algorithm&period; Allows us to run this algorithm on a limited set of transactions (e&period;g&period; subset of mempool or transactions that are not yet in mempool) instead of the entire mempool, ignoring consensus rules&period; Callers may use this to&colon; &hyphen; Calculate the &quot;bump fee&quot; needed to spend an unconfirmed UTXO at a given feerate &hyphen; &quot;Linearize&quot; a list of transactions to see the order in which they would be selected for inclusion in a block
| xref:node/MiniMinerMempoolEntry.adoc[`MiniMinerMempoolEntry`] 
| Container for tracking updates to ancestor feerate as we include ancestors in the &quot;block&quot;&period;
| xref:node/NodeContext.adoc[`NodeContext`] 
| NodeContext struct containing references to chain state and connection state&period;
| xref:node/PSBTAnalysis.adoc[`PSBTAnalysis`] 
| Holds the results of AnalyzePSBT (miscellaneous information about a PSBT)
| xref:node/PSBTInputAnalysis.adoc[`PSBTInputAnalysis`] 
| Holds an analysis of one input from a PSBT
| xref:node/PackageToValidate.adoc[`PackageToValidate`] 
| A parent&sol;child transaction package queued for joint mempool validation&period;
| xref:node/PruneLockInfo.adoc[`PruneLockInfo`] 
| Records the oldest block an external component still needs, to guard it from pruning&period;
| xref:node/RejectedTxTodo.adoc[`RejectedTxTodo`] 
| Follow&hyphen;up actions returned after a transaction is rejected from the mempool&period;
| xref:node/SnapshotMetadata.adoc[`SnapshotMetadata`] 
| Metadata describing a serialized UTXO snapshot file&period;
| xref:node/TxDownloadConnectionInfo.adoc[`TxDownloadConnectionInfo`] 
| Per&hyphen;peer connection attributes that affect transaction download scheduling&period;
| xref:node/TxDownloadManager.adoc[`TxDownloadManager`] 
| Class responsible for deciding what transactions to request and, once downloaded, whether and how to validate them&period; It is also responsible for deciding what transaction packages to validate and how to resolve orphan transactions&period; Its data structures include TxRequestTracker for scheduling requests, rolling bloom filters for remembering transactions that have already been &lcub;accepted, rejected, confirmed&rcub;, an orphanage, and a registry of each peer&apos;s transaction relay&hyphen;related information&period;
| xref:node/TxDownloadManagerImpl.adoc[`TxDownloadManagerImpl`] 
| Private implementation of TxDownloadManager&period;
| xref:node/TxDownloadOptions.adoc[`TxDownloadOptions`] 
| Options used to construct a TxDownloadManager&period;
| xref:node/TxOrphanage.adoc[`TxOrphanage`] 
| A class to track orphan transactions (failed on TX&lowbar;MISSING&lowbar;INPUTS) Since we cannot distinguish orphans from bad transactions with non&hyphen;existent inputs, we heavily limit the amount of announcements (unique (NodeId, wtxid) pairs), the number of inputs, and size of the orphans stored (both individual and summed)&period; We also try to prevent adversaries from churning this data structure&colon; once global limits are reached, we continuously evict the oldest announcement (sorting non&hyphen;reconsiderable orphans before reconsiderable ones) from the most resource&hyphen;intensive peer until we are back within limits&period; &hyphen; Peers can exceed their individual limits (e&period;g&period; because they are very useful transaction relay peers) as long as the global limits are not exceeded&period; &hyphen; As long as the orphan has 1 announcer, it remains in the orphanage&period; &hyphen; No peer can trigger the eviction of another peer&apos;s orphans&period; &hyphen; Peers&apos; orphans are effectively protected from eviction as long as they don&apos;t exceed their limits&period; Not thread&hyphen;safe&period; Requires external synchronization&period;
| xref:node/Warnings.adoc[`Warnings`] 
| Manages warning messages within a node&period;
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockMap.adoc[`BlockMap`] 
| Map from block hash to its in&hyphen;memory block index entry&period;
| xref:node/ChainstateLoadResult.adoc[`ChainstateLoadResult`] 
| Chainstate load status code and optional error string&period;
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockfileType.adoc[`BlockfileType`] 
| Which kind of chainstate a block file belongs to, used to segment storage&period;
| xref:node/ChainstateLoadStatus.adoc[`ChainstateLoadStatus`] 
| Chainstate load status&period; Simple applications can just check for the success case, and treat other cases as errors&period; More complex applications may want to try reindexing in the generic failure case, and pass an interrupt callback and exit cleanly in the interrupted case&period;
| xref:node/ReadRawError.adoc[`ReadRawError`] 
| Reason a raw block read from disk failed&period;
| xref:node/TransactionError.adoc[`TransactionError`] 
| Result of attempting to submit or broadcast a transaction&period;
| xref:node/TxBroadcast.adoc[`TxBroadcast`] 
| How to broadcast a local transaction&period; Used to influence `BroadcastTransaction()` and its callers&period;
| xref:node/Warning.adoc[`Warning`] 
| Categories of node&hyphen;level warning shown to the user and over RPC&period;
|===


== Functions

[cols="1,4"]
|===
| Name| Description
| xref:node/AbortNode.adoc[`AbortNode`] 
| Abort the node in response to a fatal, unrecoverable internal error&period;
| xref:node/AddMerkleRootAndCoinbase.adoc[`AddMerkleRootAndCoinbase`] 
| Insert the coinbase transaction and compute the merkle root of a block&period;
| xref:node/AnalyzePSBT.adoc[`AnalyzePSBT`] 
| Provides helpful miscellaneous information about where a PSBT is in the signing workflow&period;
| xref:node/ApplyArgsManOptions-0c.adoc[`ApplyArgsManOptions`] 
| `ApplyArgsManOptions` overloads
| xref:node/BroadcastTransaction.adoc[`BroadcastTransaction`] 
| Submit a transaction to the mempool and (optionally) relay it to all P2P peers&period;
| xref:node/CalculateCacheSizes.adoc[`CalculateCacheSizes`] 
| Split the configured total database cache across the indexes and kernel caches&period;
| xref:node/CheckMiningOptions.adoc[`CheckMiningOptions`] 
| Check option values for validity&period; Returns an error for invalid values&period;
| xref:node/CooldownIfHeadersAhead.adoc[`CooldownIfHeadersAhead`] 
| Wait while the best known header extends the current chain tip AND at least one block is being added to the tip every 3 seconds&period; If the tip is sufficiently far behind, allow up to 20 seconds for the next tip update&period;
| xref:node/DumpMempool.adoc[`DumpMempool`] 
| Dump the mempool to a file&period;
| xref:node/FindAssumeutxoChainstateDir.adoc[`FindAssumeutxoChainstateDir`] 
| Return a path to the snapshot&hyphen;based chainstate dir, if one exists&period;
| xref:node/FindCoins.adoc[`FindCoins`] 
| Look up unspent output information&period; Returns coins in the mempool and in the current chain UTXO set&period; Iterates through all the keys in the map and populates the values&period;
| xref:node/FlattenMiningOptions.adoc[`FlattenMiningOptions`] 
| Replace null optional values with their hardcoded defaults&period;
| xref:node/GetDefaultDBCache.adoc[`GetDefaultDBCache`] 
| Return the default total database cache size in bytes&period;
| xref:node/GetMinimumTime.adoc[`GetMinimumTime`] 
| Get the minimum time a miner should use in the next block&period; This always accounts for the BIP94 timewarp rule, so does not necessarily reflect the consensus limit&period;
| xref:node/GetTip.adoc[`GetTip`] 
| Return the hash and height of the active chain tip&period;
| xref:node/GetTransaction.adoc[`GetTransaction`] 
| Return transaction with a given hash&period; If mempool is provided and block&lowbar;index is not provided, check it first for the tx&period; If &hyphen;txindex is available, check it next for the tx&period; Finally, if block&lowbar;index is provided, check for tx by reading entire block from disk&period;
| xref:node/GetWarningsForRpc.adoc[`GetWarningsForRpc`] 
| RPC helper function that wraps warnings&period;GetMessages()&period;
| xref:node/ImportBlocks.adoc[`ImportBlocks`] 
| Load blocks from the given files and activate the best chain, even if none are imported&period;
| xref:node/InterruptWait.adoc[`InterruptWait`] 
| Interrupt a blocking wait call&period;
| xref:node/LoadChainstate.adoc[`LoadChainstate`] 
| This sequence can have 4 types of outcomes&colon;
| xref:node/LoadMempool.adoc[`LoadMempool`] 
| Import the file and attempt to add its contents to the mempool&period;
| xref:node/LogOversizedDbCache.adoc[`LogOversizedDbCache`] 
| Log a warning when the configured database cache is larger than available RAM allows&period;
| xref:node/MakeMinisketch32.adoc[`MakeMinisketch32`] 
| Wrapper around Minisketch&colon;&colon;Minisketch(32, implementation, capacity)&period;
| xref:node/MakeMinisketch32FP.adoc[`MakeMinisketch32FP`] 
| Wrapper around Minisketch&colon;&colon;CreateFP&period;
| xref:node/MakeTxOrphanage-07.adoc[`MakeTxOrphanage`] 
| `MakeTxOrphanage` overloads
| xref:node/MempoolPath.adoc[`MempoolPath`] 
| Return the on&hyphen;disk path used to load and save the persisted mempool&period;
| xref:node/MergeMiningOptions.adoc[`MergeMiningOptions`] 
| Merge two BlockCreateOptions structs, replacing null values in `x` with non&hyphen;null values from `y&period;`
| xref:node/ReadCoinsViewArgs.adoc[`ReadCoinsViewArgs`] 
| Read coins&hyphen;view database options from the argument manager&period;
| xref:node/ReadDatabaseArgs.adoc[`ReadDatabaseArgs`] 
| Read database options from the argument manager&period;
| xref:node/ReadMiningArgs.adoc[`ReadMiningArgs`] 
| Read the mining options set in `args&period;` Returns an error if one was encountered&period;
| xref:node/ReadNotificationArgs.adoc[`ReadNotificationArgs`] 
| Apply notification&hyphen;related options from the argument manager&period;
| xref:node/ReadSnapshotBaseBlockhash.adoc[`ReadSnapshotBaseBlockhash`] 
| Read the blockhash of the snapshot base block that was used to construct the chainstate&period;
| xref:node/RegenerateCommitments.adoc[`RegenerateCommitments`] 
| Update an old GenerateCoinbaseCommitment from CreateNewBlock after the block txs have changed
| xref:node/ShouldPersistMempool.adoc[`ShouldPersistMempool`] 
| Determine whether the mempool should be persisted across restarts&period;
| xref:node/ShouldWarnOversizedDbCache.adoc[`ShouldWarnOversizedDbCache`] 
| Report whether the configured database cache is large enough to warrant a warning&period;
| xref:node/SubmitBlock.adoc[`SubmitBlock`] 
| Submit a block and capture the validation state via the BlockChecked callback&period; Returns whether the block was accepted as a new valid block&period;
| xref:node/UpdateTime.adoc[`UpdateTime`] 
| Update a block header&apos;s time field and return the new time&period;
| xref:node/VerifyLoadedChainstate.adoc[`VerifyLoadedChainstate`] 
| Verify a chainstate that has already been loaded&period;
| xref:node/WaitAndCreateNewBlock.adoc[`WaitAndCreateNewBlock`] 
| Return a new block template when fees rise to a certain threshold or after a new tip&semi; return nullopt if timeout is reached&period;
| xref:node/WaitTipChanged.adoc[`WaitTipChanged`] 
| Waits for the connected tip to change until timeout has elapsed&period; During node initialization, this will wait until the tip is connected (regardless of `timeout`)&period; Returns the current tip, or nullopt if the node is shutting down or interrupt() is called&period;
| xref:node/WriteSnapshotBaseBlockhash.adoc[`WriteSnapshotBaseBlockhash`] 
| Write out the blockhash of the snapshot base block that was used to construct this chainstate&period; This value is read in during subsequent initializations and used to reconstruct snapshot&hyphen;based chainstates&period;
| xref:node/operator_lshift-05.adoc[`operator&lt;&lt;`] 
| Stream insertion operators
|===


== Variables

[cols="1,4"]
|===
| Name| Description
| xref:node/BLOCKFILE_CHUNK_SIZE.adoc[`BLOCKFILE&lowbar;CHUNK&lowbar;SIZE`] 
| The pre&hyphen;allocation chunk size for blk?????&period;dat files (since 0&period;8)
| xref:node/DEFAULT_MAX_BURN_AMOUNT.adoc[`DEFAULT&lowbar;MAX&lowbar;BURN&lowbar;AMOUNT`] 
| Maximum burn value for sendrawtransaction, submitpackage, and testmempoolaccept RPC calls&period; By default, a transaction with a burn value higher than this will be rejected by these RPCs and the GUI&period; This can be overridden with the maxburnamount argument&period;
| xref:node/DEFAULT_MAX_ORPHANAGE_LATENCY_SCORE.adoc[`DEFAULT&lowbar;MAX&lowbar;ORPHANAGE&lowbar;LATENCY&lowbar;SCORE`] 
| Default value for TxOrphanage&colon;&colon;m&lowbar;max&lowbar;global&lowbar;latency&lowbar;score&period; Helps limit the maximum latency for operations like EraseForBlock and LimitOrphans&period;
| xref:node/DEFAULT_MAX_RAW_TX_FEE_RATE.adoc[`DEFAULT&lowbar;MAX&lowbar;RAW&lowbar;TX&lowbar;FEE&lowbar;RATE`] 
| Maximum fee rate for sendrawtransaction and testmempoolaccept RPC calls&period; Also used by the GUI when broadcasting a completed PSBT&period; By default, a transaction with a fee rate higher than this will be rejected by these RPCs and the GUI&period; This can be overridden with the maxfeerate argument&period;
| xref:node/DEFAULT_PERSIST_MEMPOOL.adoc[`DEFAULT&lowbar;PERSIST&lowbar;MEMPOOL`] 
| Default for &hyphen;persistmempool, indicating whether the node should attempt to automatically load the mempool on start and save to disk on shutdown
| xref:node/DEFAULT_PRINT_MODIFIED_FEE.adoc[`DEFAULT&lowbar;PRINT&lowbar;MODIFIED&lowbar;FEE`] 
| Default for whether block templates print each transaction&apos;s modified fee&period;
| xref:node/DEFAULT_RESERVED_ORPHAN_WEIGHT_PER_PEER.adoc[`DEFAULT&lowbar;RESERVED&lowbar;ORPHAN&lowbar;WEIGHT&lowbar;PER&lowbar;PEER`] 
| Default value for TxOrphanage&colon;&colon;m&lowbar;reserved&lowbar;usage&lowbar;per&lowbar;peer&period; Helps limit the total amount of memory used by the orphanage&period;
| xref:node/DEFAULT_STOPATHEIGHT.adoc[`DEFAULT&lowbar;STOPATHEIGHT`] 
| Default for `&hyphen;stopatheight`&semi; 0 means never stop at a given height&period;
| xref:node/GETDATA_TX_INTERVAL.adoc[`GETDATA&lowbar;TX&lowbar;INTERVAL`] 
| How long to wait before downloading a transaction from an additional peer
| xref:node/MAX_BLOCKFILE_SIZE.adoc[`MAX&lowbar;BLOCKFILE&lowbar;SIZE`] 
| The maximum size of a blk?????&period;dat file (since 0&period;8)
| xref:node/MAX_PEER_TX_ANNOUNCEMENTS.adoc[`MAX&lowbar;PEER&lowbar;TX&lowbar;ANNOUNCEMENTS`] 
| Maximum number of transactions to consider for requesting, per peer&period; It provides a reasonable DoS limit to per&hyphen;peer memory usage spent on announcements, while covering peers continuously sending INVs at the maximum rate (by our own policy, see DEFAULT&lowbar;TX&lowbar;SEND&lowbar;RATE) for several minutes, while not receiving the actual transaction (from any peer) in response to requests for them&period;
| xref:node/MAX_PEER_TX_REQUEST_IN_FLIGHT.adoc[`MAX&lowbar;PEER&lowbar;TX&lowbar;REQUEST&lowbar;IN&lowbar;FLIGHT`] 
| Maximum number of in&hyphen;flight transaction requests from a peer&period; It is not a hard limit, but the threshold at which point the OVERLOADED&lowbar;PEER&lowbar;TX&lowbar;DELAY kicks in&period;
| xref:node/NONPREF_PEER_TX_DELAY.adoc[`NONPREF&lowbar;PEER&lowbar;TX&lowbar;DELAY`] 
| How long to delay requesting transactions from non&hyphen;preferred peers
| xref:node/OVERLOADED_PEER_TX_DELAY.adoc[`OVERLOADED&lowbar;PEER&lowbar;TX&lowbar;DELAY`] 
| How long to delay requesting transactions from overloaded peers (see MAX&lowbar;PEER&lowbar;TX&lowbar;REQUEST&lowbar;IN&lowbar;FLIGHT)&period;
| xref:node/SNAPSHOT_BLOCKHASH_FILENAME.adoc[`SNAPSHOT&lowbar;BLOCKHASH&lowbar;FILENAME`] 
| The file in the snapshot chainstate dir which stores the base blockhash&period; This is needed to reconstruct snapshot chainstates on init&period;
| xref:node/SNAPSHOT_CHAINSTATE_SUFFIX.adoc[`SNAPSHOT&lowbar;CHAINSTATE&lowbar;SUFFIX`] 
| Suffix appended to the chainstate (leveldb) dir when created based upon a snapshot&period;
| xref:node/STORAGE_HEADER_BYTES.adoc[`STORAGE&lowbar;HEADER&lowbar;BYTES`] 
| Size of header written by WriteBlock before a serialized CBlock (8 bytes)
| xref:node/TXID_RELAY_DELAY.adoc[`TXID&lowbar;RELAY&lowbar;DELAY`] 
| How long to delay requesting transactions via txids, if we have wtxid&hyphen;relaying peers
| xref:node/UNDOFILE_CHUNK_SIZE.adoc[`UNDOFILE&lowbar;CHUNK&lowbar;SIZE`] 
| The pre&hyphen;allocation chunk size for rev?????&period;dat files (since 0&period;8)
| xref:node/UNDO_DATA_DISK_OVERHEAD.adoc[`UNDO&lowbar;DATA&lowbar;DISK&lowbar;OVERHEAD`] 
| Total overhead when writing undo data&colon; header (8 bytes) plus checksum (32 bytes)
|===


== Using Declarations

[cols="1,4"]
|===
| Name| Description
| xref:node/BlockTreeDB.adoc[`BlockTreeDB`] 
| Bring the kernel block&hyphen;tree database type into the node namespace&period;
| xref:node/CBlockFileInfo.adoc[`CBlockFileInfo`] 
| Bring the kernel block&hyphen;file info type into the node namespace&period;
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#
