Where validation becomes chain state

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

313,176 bytes · SHA-256 8626f665975c1c50… · View upstream ↗

1251    // ConsensusScriptChecks to make the outputs available for subsequent transactions.
1252    for (Workspace& ws : workspaces) {
1253        if (!ConsensusScriptChecks(ws)) {
1254            results.emplace(ws.m_ptx->GetWitnessHash(), MempoolAcceptResult::Failure(ws.m_state));
1255            // Since PolicyScriptChecks() passed, this should never fail.
1256            Assume(false);
1257            all_submitted = false;
1258            package_state.Invalid(PackageValidationResult::PCKG_MEMPOOL_ERROR,
1259                                  strprintf("BUG! PolicyScriptChecks succeeded but ConsensusScriptChecks failed: %s",
1260                                            ws.m_ptx->GetHash().ToString()));
1261        }
1262        // Remove first failing tx and all subsequent in package
1263        if (!all_submitted) {
1264            if (!m_subpackage.m_changeset) m_subpackage.m_changeset = m_pool.GetChangeSet();
1265            m_subpackage.m_changeset->StageRemoval(m_pool.GetIter(ws.m_ptx->GetHash()).value());
1266        }
1267    }
1268    if (!all_submitted) {
1269        Assume(m_subpackage.m_changeset);
1270        // This code should be unreachable; it's here as belt-and-suspenders
1271        // to try to ensure we have no consensus-invalid transactions in the
1272        // mempool.
1273        m_subpackage.m_changeset->Apply();
1274        m_subpackage.m_changeset.reset();
1275        return false;
1276    }
1277
1278    std::vector<Wtxid> all_package_wtxids;
1279    all_package_wtxids.reserve(workspaces.size());
1280    std::transform(workspaces.cbegin(), workspaces.cend(), std::back_inserter(all_package_wtxids),
1281                   [](const auto& ws) { return ws.m_ptx->GetWitnessHash(); });
1282
1283    if (!m_subpackage.m_replaced_transactions.empty()) {
1284        LogDebug(BCLog::MEMPOOL, "replaced %u mempool transactions with %u new one(s) for %s additional fees, %d delta bytes\n",
1285                 m_subpackage.m_replaced_transactions.size(), workspaces.size(),
1286                 m_subpackage.m_total_modified_fees - m_subpackage.m_conflicting_fees,
1287                 m_subpackage.m_total_vsize - static_cast<int>(m_subpackage.m_conflicting_size));
1288    }
1289
1290    // Add successful results. The returned results may change later if LimitMempoolSize() evicts them.
1291    for (Workspace& ws : workspaces) {
1292        auto iter = m_pool.GetIter(ws.m_ptx->GetHash());
1293        Assume(iter.has_value());
1294        const auto effective_feerate = args.m_package_feerates ? ws.m_package_feerate :
1295            CFeeRate{ws.m_modified_fees, static_cast<int32_t>(ws.m_vsize)};
1296        const auto effective_feerate_wtxids = args.m_package_feerates ? all_package_wtxids :
1297            std::vector<Wtxid>{ws.m_ptx->GetWitnessHash()};
1298        results.emplace(ws.m_ptx->GetWitnessHash(),
1299                        MempoolAcceptResult::Success(std::move(m_subpackage.m_replaced_transactions), ws.m_vsize,
1300                                         ws.m_base_fees, effective_feerate, effective_feerate_wtxids));
1301        if (!m_pool.m_opts.signals) continue;
1302        const CTransaction& tx = *ws.m_ptx;
1303        const auto tx_info = NewMempoolTransactionInfo(ws.m_ptx, ws.m_base_fees,
1304                                                       ws.m_vsize, (*iter)->GetHeight(),
1305                                                       args.m_bypass_limits, args.m_package_submission,
1306                                                       IsCurrentForFeeEstimation(m_active_chainstate),
1307                                                       m_pool.HasNoInputsOf(tx));
1308        m_pool.m_opts.signals->TransactionAddedToMempool(tx_info, m_pool.GetAndIncrementSequence());
1309    }
1310    return all_submitted;
1311}
1312
1313MempoolAcceptResult MemPoolAccept::AcceptSingleTransactionInternal(const CTransactionRef& ptx, ATMPArgs& args)
1314{
1315    AssertLockHeld(cs_main);
1316    AssertLockHeld(m_pool.cs);
1317
1318    Workspace ws(ptx);
1319    const std::vector<Wtxid> single_wtxid{ws.m_ptx->GetWitnessHash()};
1320
1321    if (!PreChecks(args, ws)) {
1322        if (ws.m_state.GetResult() == TxValidationResult::TX_RECONSIDERABLE) {
1323            // Failed for fee reasons. Provide the effective feerate and which tx was included.
1324            return MempoolAcceptResult::FeeFailure(ws.m_state, CFeeRate(ws.m_modified_fees, ws.m_vsize), single_wtxid);
1325        }
1326        return MempoolAcceptResult::Failure(ws.m_state);
1327    }
1328
1329    if (m_subpackage.m_rbf && !ReplacementChecks(ws)) {
1330        if (ws.m_state.GetResult() == TxValidationResult::TX_RECONSIDERABLE) {
1331            // Failed for incentives-based fee reasons. Provide the effective feerate and which tx was included.
1332            return MempoolAcceptResult::FeeFailure(ws.m_state, CFeeRate(ws.m_modified_fees, ws.m_vsize), single_wtxid);
1333        }
1334        return MempoolAcceptResult::Failure(ws.m_state);
1335    }
1336
1337    // Check if the transaction would exceed the cluster size limit.
1338    if (!m_subpackage.m_changeset->CheckMemPoolPolicyLimits()) {
1339        ws.m_state.Invalid(TxValidationResult::TX_MEMPOOL_POLICY, "too-large-cluster", "");
1340        return MempoolAcceptResult::Failure(ws.m_state);
1341    }
1342
1343    // Now that we've verified the cluster limit is respected, we can perform
1344    // calculations involving the full ancestors of the tx.
1345    if (ws.m_conflicts.size()) {
1346        auto ancestors = m_subpackage.m_changeset->CalculateMemPoolAncestors(ws.m_tx_handle);
1347
1348        // A transaction that spends outputs that would be replaced by it is invalid. Now
1349        // that we have the set of all ancestors we can detect this
1350        // pathological case by making sure ws.m_conflicts and this tx's ancestors don't
1351        // intersect.
1352        if (const auto err_string{EntriesAndTxidsDisjoint(ancestors, ws.m_conflicts, ptx->GetHash())}) {
1353            // We classify this as a consensus error because a transaction depending on something it
1354            // conflicts with would be inconsistent.
1355            ws.m_state.Invalid(TxValidationResult::TX_CONSENSUS, "bad-txns-spends-conflicting-tx", *err_string);
1356            return MempoolAcceptResult::Failure(ws.m_state);
1357        }
1358    }
1359
1360    m_subpackage.m_total_vsize = ws.m_vsize;
1361    m_subpackage.m_total_modified_fees = ws.m_modified_fees;
1362
1363    // Individual modified feerate exceeded caller-defined max; abort
1364    if (args.m_client_maxfeerate && CFeeRate(ws.m_modified_fees, ws.m_vsize) > args.m_client_maxfeerate.value()) {
1365        ws.m_state.Invalid(TxValidationResult::TX_MEMPOOL_POLICY, "max feerate exceeded", "");
1366        return MempoolAcceptResult::Failure(ws.m_state);
1367    }
1368
1369    if (!args.m_bypass_limits && m_pool.m_opts.require_standard) {
1370        Wtxid dummy_wtxid;
1371        if (!CheckEphemeralSpends(/*package=*/{ptx}, m_pool.m_opts.dust_relay_feerate, m_pool, ws.m_state, dummy_wtxid)) {
1372            return MempoolAcceptResult::Failure(ws.m_state);
1373        }
1374    }
1375
1376    // Perform the inexpensive checks first and avoid hashing and signature verification unless
1377    // those checks pass, to mitigate CPU exhaustion denial-of-service attacks.
1378    if (!PolicyScriptChecks(ws)) return MempoolAcceptResult::Failure(ws.m_state);
1379
1380    if (!ConsensusScriptChecks(ws)) return MempoolAcceptResult::Failure(ws.m_state);
1381
1382    const CFeeRate effective_feerate{ws.m_modified_fees, static_cast<int32_t>(ws.m_vsize)};
1383    // Tx was accepted, but not added
1384    if (args.m_test_accept) {
1385        return MempoolAcceptResult::Success(std::move(m_subpackage.m_replaced_transactions), ws.m_vsize,
1386                                            ws.m_base_fees, effective_feerate, single_wtxid);
1387    }
1388
1389    FinalizeSubpackage(args);
1390
1391    // Limit the mempool, if appropriate.
1392    if (!args.m_package_submission && !args.m_bypass_limits) {
1393        LimitMempoolSize(m_pool, m_active_chainstate.CoinsTip());
1394        // If mempool contents change, then the m_view cache is dirty. Given this isn't a package
1395        // submission, we won't be using the cache anymore, but clear it anyway for clarity.
1396        CleanupTemporaryCoins();
1397
1398        if (!m_pool.exists(ws.m_hash)) {
1399            // The tx no longer meets our (new) mempool minimum feerate but could be reconsidered in a package.
1400            ws.m_state.Invalid(TxValidationResult::TX_RECONSIDERABLE, "mempool full");
1401            return MempoolAcceptResult::FeeFailure(ws.m_state, CFeeRate(ws.m_modified_fees, ws.m_vsize), {ws.m_ptx->GetWitnessHash()});
1402        }
1403    }
1404
1405    if (m_pool.m_opts.signals) {
1406        const CTransaction& tx = *ws.m_ptx;
1407        auto iter = m_pool.GetIter(tx.GetHash());
1408        Assume(iter.has_value());
1409        const auto tx_info = NewMempoolTransactionInfo(ws.m_ptx, ws.m_base_fees,
1410                                                       ws.m_vsize, (*iter)->GetHeight(),
1411                                                       args.m_bypass_limits, args.m_package_submission,
1412                                                       IsCurrentForFeeEstimation(m_active_chainstate),
1413                                                       m_pool.HasNoInputsOf(tx));
1414        m_pool.m_opts.signals->TransactionAddedToMempool(tx_info, m_pool.GetAndIncrementSequence());
1415    }
1416
1417    if (!m_subpackage.m_replaced_transactions.empty()) {
1418        LogDebug(BCLog::MEMPOOL, "replaced %u mempool transactions with 1 new transaction for %s additional fees, %d delta bytes\n",
1419                 m_subpackage.m_replaced_transactions.size(),
1420                 ws.m_modified_fees - m_subpackage.m_conflicting_fees,
1421                 ws.m_vsize - static_cast<int>(m_subpackage.m_conflicting_size));
1422    }
1423
1424    return MempoolAcceptResult::Success(std::move(m_subpackage.m_replaced_transactions), ws.m_vsize, ws.m_base_fees,
1425                                        effective_feerate, single_wtxid);
1426}
1427
1428PackageMempoolAcceptResult MemPoolAccept::AcceptMultipleTransactionsInternal(const std::vector<CTransactionRef>& txns, ATMPArgs& args)
1429{
1430    AssertLockHeld(cs_main);
1431    AssertLockHeld(m_pool.cs);
1432
1433    // These context-free package limits can be done before taking the mempool lock.
1434    PackageValidationState package_state;
1435    if (!IsWellFormedPackage(txns, package_state)) return PackageMempoolAcceptResult(package_state, {});
1436
1437    std::vector<Workspace> workspaces{};
1438    workspaces.reserve(txns.size());
1439    std::transform(txns.cbegin(), txns.cend(), std::back_inserter(workspaces),
1440                   [](const auto& tx) { return Workspace(tx); });
1441    std::map<Wtxid, MempoolAcceptResult> results;
1442
1443    // Do all PreChecks first and fail fast to avoid running expensive script checks when unnecessary.
1444    for (Workspace& ws : workspaces) {
1445        if (!PreChecks(args, ws)) {
1446            package_state.Invalid(PackageValidationResult::PCKG_TX, "transaction failed");
1447            // Exit early to avoid doing pointless work. Update the failed tx result; the rest are unfinished.
1448            results.emplace(ws.m_ptx->GetWitnessHash(), MempoolAcceptResult::Failure(ws.m_state));
1449            return PackageMempoolAcceptResult(package_state, std::move(results));
1450        }
1451
1452        // Individual modified feerate exceeded caller-defined max; abort
1453        // N.B. this doesn't take into account CPFPs. Chunk-aware validation may be more robust.
1454        if (args.m_client_maxfeerate && CFeeRate(ws.m_modified_fees, ws.m_vsize) > args.m_client_maxfeerate.value()) {
1455            // Need to set failure here both individually and at package level
1456            ws.m_state.Invalid(TxValidationResult::TX_MEMPOOL_POLICY, "max feerate exceeded", "");
1457            package_state.Invalid(PackageValidationResult::PCKG_TX, "transaction failed");
1458            // Exit early to avoid doing pointless work. Update the failed tx result; the rest are unfinished.
1459            results.emplace(ws.m_ptx->GetWitnessHash(), MempoolAcceptResult::Failure(ws.m_state));
1460            return PackageMempoolAcceptResult(package_state, std::move(results));
1461        }
1462
1463        // Make the coins created by this transaction available for subsequent transactions in the
1464        // package to spend. If there are no conflicts within the package, no transaction can spend a coin
1465        // needed by another transaction in the package. We also need to make sure that no package
1466        // tx replaces (or replaces the ancestor of) the parent of another package tx. As long as we
1467        // check these two things, we don't need to track the coins spent.
1468        // If a package tx conflicts with a mempool tx, PackageRBFChecks() ensures later that any package RBF attempt
1469        // has *no* in-mempool ancestors, so we don't have to worry about subsequent transactions in
1470        // same package spending the same in-mempool outpoints. This needs to be revisited for general
1471        // package RBF.
1472        m_viewmempool.PackageAddTransaction(ws.m_ptx);
1473    }
1474
1475    // At this point we have all in-mempool parents, and we know every transaction's vsize.
1476    // Run the TRUC checks on the package.
1477    for (Workspace& ws : workspaces) {
1478        if (auto err{PackageTRUCChecks(m_pool, ws.m_ptx, ws.m_vsize, txns, ws.m_parents)}) {
1479            package_state.Invalid(PackageValidationResult::PCKG_POLICY, "TRUC-violation", err.value());
1480            return PackageMempoolAcceptResult(package_state, {});
1481        }
1482    }
1483
1484    // Transactions must meet two minimum feerates: the mempool minimum fee and min relay fee.
1485    // For transactions consisting of exactly one child and its parents, it suffices to use the
1486    // package feerate (total modified fees / total virtual size) to check this requirement.
1487    // Note that this is an aggregate feerate; this function has not checked that there are transactions
1488    // too low feerate to pay for themselves, or that the child transactions are higher feerate than
1489    // their parents. Using aggregate feerate may allow "parents pay for child" behavior and permit
1490    // a child that is below mempool minimum feerate. To avoid these behaviors, callers of
1491    // AcceptMultipleTransactions need to restrict txns topology (e.g. to ancestor sets) and check
1492    // the feerates of individuals and subsets.
1493    m_subpackage.m_total_vsize = std::accumulate(workspaces.cbegin(), workspaces.cend(), int64_t{0},
1494        [](int64_t sum, auto& ws) { return sum + ws.m_vsize; });
1495    m_subpackage.m_total_modified_fees = std::accumulate(workspaces.cbegin(), workspaces.cend(), CAmount{0},
1496        [](CAmount sum, auto& ws) { return sum + ws.m_modified_fees; });
1497    const CFeeRate package_feerate(m_subpackage.m_total_modified_fees, m_subpackage.m_total_vsize);
1498    std::vector<Wtxid> all_package_wtxids;
1499    all_package_wtxids.reserve(workspaces.size());
1500    std::transform(workspaces.cbegin(), workspaces.cend(), std::back_inserter(all_package_wtxids),

FILE GUIDE · KEY SECTIONS

Where validation becomes chain state

This large file coordinates several validation stages. This guide follows the transaction-admission and block-connection entry points; it is not a line-by-line proof of the entire implementation.

Line 779 ↗

Before mempool admission

PreChecks performs early admission checks using the transaction and node state. Mempool admission includes local policy as well as validity requirements, so rejection here is not automatically proof that a transaction could never appear in a valid block.

Line 1152 ↗

Check spending authorization

This stage checks scripts under the selected consensus flags after the policy-stage checks. The implementation and its callers matter together: merely decoding a transaction does not validate its signatures.

Line 2178 ↗

Undo a connected block

DisconnectBlock reads undo information and reverses UTXO changes. This supports reorganizations. Reversing a block requires restoring the spent outputs, not just removing the outputs it created.

Line 2294 ↗

Apply a block to a coin view

ConnectBlock checks a block in chain context and applies its transaction effects to the supplied UTXO view. Its fJustCheck mode and surrounding activation logic determine whether the operation is a check or part of committing a new chain state.

Line 4413 ↗

A block-processing entry point

This entry point coordinates processing of a newly received block with block acceptance and chain activation. Receiving bytes, accepting their header and selecting the active chain are distinct operations.

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.