dash: wire the embedded arm so --run can actually take it (#738)

The daemonless embedded template stack (SML/quorum CCbTx, DKG-window
serving, BLS-verified commitments, superblock/credit-pool/payee guards)
is merged and soak-proven, but no released --run invocation could reach
it. Taking the embedded arm needs TWO independent conditions:

  (1) the work-source arm gate -- DASHWorkSource only consults the
      embedded bundle when `is_testnet_ || embedded_mainnet_`
      (work_source.cpp get_work / resource_template_now);
  (2) a live coin-state FEED -- NodeCoinState::populated() only flips
      when CoinStateMaintainer publishes a tip, and the maintainer +
      header chain + 6 ingest legs are constructed ONLY inside
      main_dash's `if (coin_p2p)` block.

No single flag satisfied both. --embedded-mainnet armed (1) only, so
the bundle was never fed and populated() stayed false forever;
--coin-p2p-connect/--coin-p2p-discover armed (2) only. On top of that
--embedded-mainnet was absent from --help entirely, so the undocumented
combination was undiscoverable. Net effect: 100% of released --run
templates came off the dashd fallback and the whole daemonless stack
was unreachable scaffolding.

resolve_embedded_arm() (arm_resolution.hpp) makes the decision once, as
one pure function, with a strictly ONE-WAY implication:

    embedded opt-in  =>  coin-state feed     (new -- this is the wiring)
    coin-state feed  =>  embedded opt-in     (never -- explicitly not)

So --embedded-mainnet now arms both halves end to end (seed-based
discovery when no peer is pinned), while a transport flag still cannot
move the arm.

REWARD SAFETY (this node class runs a live production mining hotel, and
there is a documented incident where --coin-p2p-connect activated an
unguarded embedded arm on a live node):

  * a default --run resolves arm=dashd-fallback, unchanged;
  * --coin-p2p-connect alone resolves arm=dashd-fallback, unchanged --
    it brings up the transport and nothing else;
  * both are pinned by tests, including an exhaustive sweep of the
    un-opted-in mainnet argv quadrant;
  * verified empirically: normalized run-log diff of the pre-change vs
    post-change binary for both invocations differs ONLY by the two
    added diagnostic lines.

Also: --embedded-mainnet documented in --help, and a startup line that
names the resolved arm plus the reason, so the arm is field-checkable
instead of inferred.

Tests fold into the existing allowlisted test_dash_stratum_work_source
target (no new add_executable -> no NOT_BUILT sentinel); the allowlist
drift-guard passes.

Author: frstrtr

src/c2pool/main_dash.cpp

@@ -61,6 +61,7 @@
 #include <impl/dash/coin/zmq_tip_notify.hpp> // dash::coin::TipHashDedup / ZmqHashblockSubscriber — dashd ZMQ hashblock INSTANT tip-notify (opt-in, hardening on the #770 poll)
 #include <impl/dash/coin/coin_p2p_magic.hpp>      // dash::coin::select_coin_p2p_magic — E5 --coin-p2p-magic override (regtest ARM A dial)
 #include <impl/dash/coin/node_coin_state.hpp>  // dash::coin::NodeCoinState (embedded work bundle)
+#include <impl/dash/coin/arm_resolution.hpp>   // dash::coin::resolve_embedded_arm (#738 arm decision, one place)
 #include <impl/dash/coin/dkg_window.hpp>       // dash::coin::is_dkg_commitment_window (BLOCKER-1 guard)
 #include <impl/dash/coin/dkg_commitments.hpp>  // E1: build_daemonless_qc_plan (serve DKG windows daemonlessly)
 #include <impl/dash/coin/vendor/bls_verify.hpp>  // E1 Phase-L: make_commitment_bls_verifier (real qc verify seam)
@@ -214,7 +215,7 @@ void print_banner(const char* argv0)
         << "           [--stratum [HOST:]PORT] [--coin-p2p-connect HOST:PORT]... [--coin-p2p-discover]\n"
         << "           [--web-port PORT] [--web-host ADDR] [--dashboard-dir PATH]\n"
         << "           [--external-ip ADDR]\n"
-        << "           [--embedded-utxo]\n"
+        << "           [--embedded-utxo] [--embedded-mainnet]\n"
         << "           [--give-author PCT] [-f|--fee PCT] [--node-owner-address ADDR]\n"
         << "           [--redistribute pplns|fee|boost|donate]\n"
         << "           [--coin-zmq-hashblock tcp://HOST:PORT]\n"
@@ -238,6 +239,15 @@ void print_banner(const char* argv0)
         << "        clean_jobs notify on the fallback arm; absent/unreachable => the 3 s\n"
         << "        getbestblockhash poll is the active path (requires dashd\n"
         << "        zmqpubhashblock=tcp://HOST:PORT). No consensus effect.\n"
+        << "        --embedded-mainnet (DEFAULT OFF) is the single opt-in for the\n"
+        << "        DAEMONLESS embedded template arm on MAINNET. It lifts the arm gate\n"
+        << "        AND arms the coin-state feed that populates it (seed-based peer\n"
+        << "        discovery unless --coin-p2p-connect names peers), so one flag takes\n"
+        << "        the arm end to end. WITHOUT it a mainnet node ALWAYS serves the\n"
+        << "        reward-safe dashd-RPC fallback: --coin-p2p-connect/--coin-p2p-discover\n"
+        << "        are transport only and NEVER move the arm. Even when armed, every\n"
+        << "        per-template gate (SML fresh at tip, non-superblock, credit-pool seed\n"
+        << "        height, bestCL, MN-payee cursor, DKG plan) fails closed to dashd.\n"
         << "        --coin-p2p-magic HEX overrides the embedded coin-P2P wire magic\n"
         << "        (default mainnet bf0c6bbd / testnet cee2caff; regtest fcc1b7dc).\n"
         << "        --regtest-force-won-block (regtest E5 harness, fail-closed) drives\n"
@@ -1148,6 +1158,33 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         std::cout << "[run] web dashboard disabled (--web-port 0)\n";
     }
 
+    // ── #738: resolve WHICH template arm this invocation takes, ONCE ──────
+    // Before this, taking the embedded arm needed TWO conditions that no single
+    // flag satisfied: the work-source gate (--embedded-mainnet, half 1) AND a
+    // live coin-state feed (--coin-p2p-connect/--coin-p2p-discover, half 2,
+    // which is what constructs the maintainer that flips populated()). The
+    // embedded opt-in armed only half 1, so NodeCoinState was never fed and the
+    // arm could not be taken from any documented invocation. resolve_embedded_
+    // arm() closes that with a ONE-WAY implication: the embedded opt-in implies
+    // its own feed. The converse is deliberately absent — a transport flag NEVER
+    // moves the arm (the hotel incident where --coin-p2p-connect activated an
+    // unguarded embedded arm on a live production node). Pinned by
+    // test_dash_stratum_work_source's DashRunArmResolution suite.
+    const dash::coin::ArmResolution run_arm =
+        dash::coin::resolve_embedded_arm(dash::coin::ArmInputs{
+            testnet, embedded_mainnet,
+            !coin_p2p_targets.empty(), coin_p2p_discover });
+    // Discovery is turned on for a pinned-peer-less embedded opt-in: daemonless
+    // needs somewhere to sync from. Operator-named transport is never overridden.
+    const bool coin_p2p_discover_eff = coin_p2p_discover || run_arm.discover_implied;
+    std::cout << "[run] template arm=" << dash::coin::arm_name(run_arm.arm)
+              << " — " << dash::coin::arm_reason_text(run_arm.reason)
+              << "\n[run]       (embedded_arm_enabled="
+              << (run_arm.embedded_arm_enabled ? "yes" : "no")
+              << " coin_state_feed=" << (run_arm.coin_feed_armed ? "armed" : "off")
+              << (run_arm.discover_implied ? " discovery=implied-by-opt-in" : "")
+              << ")\n";
+
     // ── E1: OPT-IN embedded coin-network P2P dial (--coin-p2p-connect) ────
     // GUARANTEE: with no --coin-p2p-connect on argv, coin_p2p stays null and
     // this block is a no-op — the run path is unchanged and the mining-hotel
@@ -1168,7 +1205,7 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
     // Refresh timer declared LAST -> destroyed FIRST: it stops (and its lambda
     // stops capturing coin_p2p / coin_peer_mgr) before either is torn down.
     std::unique_ptr<core::Timer> coin_dial_refresh_timer;
-    if (!coin_p2p_targets.empty() || coin_p2p_discover) {
+    if (run_arm.coin_feed_armed) {
         config.coin()->m_testnet = testnet;
         // Coin-network wire magic (dashd pchMessageStart). Default: mainnet
         // bf0c6bbd / testnet cee2caff. A dev regtest dashd uses a DISTINCT magic
@@ -1185,7 +1222,7 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         coin_p2p = std::make_unique<dash::coin::p2p::CoinClient<dash::Config>>(
             &ioc, &coin_state, &config, "COIN-P2P");
 
-        if (coin_p2p_discover) {
+        if (coin_p2p_discover_eff) {
             // ── Network-standalone arm: seed-discovered, SCORED, group-diverse
             // peer set INDEPENDENT of the local dashd. The pinned local dashd
             // (--coin-p2p-connect front target, if any) is registered as the
@@ -1272,8 +1309,11 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
                 cp->update_dial_targets(std::move(refreshed));
             });
 
-            std::cout << "[run] coin-network P2P DISCOVERY armed (--coin-p2p-discover): "
-                         "DASH-isolated scored/diverse peer set, pinned="
+            std::cout << "[run] coin-network P2P DISCOVERY armed ("
+                      << (run_arm.discover_implied
+                              ? "implied by --embedded-mainnet"
+                              : "--coin-p2p-discover")
+                      << "): DASH-isolated scored/diverse peer set, pinned="
                       << pinned_str << " magic=" << net_magic_hex
                       << " proto=70230 dns_seeds=" << dash::coin::dash_dns_seeds(testnet).size()
                       << " fixed_seeds=" << dash::coin::dash_fixed_seeds(testnet).size()
@@ -2403,7 +2443,7 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         // flag) yields nullopt and the arm fails closed to the dashd fallback,
         // exactly the old refusal. The emit gate re-derives this same plan and
         // hard-rejects any template whose type-6 set drifts from it.
-        if (testnet || embedded_mainnet) {
+        if (run_arm.embedded_arm_enabled) {
             const auto qc_net = testnet ? dash::coin::LlmqNetwork::Testnet
                                         : dash::coin::LlmqNetwork::Mainnet;
             // Phase-L sourcing leg: collect REAL relayed DKG commitments off
@@ -2561,14 +2601,14 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         // Only meaningful when the embedded arm actually serves (testnet or
         // --embedded-mainnet); harmless otherwise (the arm is off, work_source
         // never consults viability).
-        node_coin_state.set_require_fresh_bestcl(testnet || embedded_mainnet);
+        node_coin_state.set_require_fresh_bestcl(run_arm.embedded_arm_enabled);
 
         // SOAK FIX (bad-cbtx-assetlocked-amount): the DIP-0027 credit-pool seed
         // rides a separate on_mnlistdiff step and can lag one block while the SML
         // hash is already at the tip; the accrual then commits a stale
         // creditPoolBalance. Refuse the embedded arm unless the credit-pool seed
         // is current AT the tip, same discipline as the SML axis.
-        node_coin_state.set_require_fresh_credit_pool(testnet || embedded_mainnet);
+        node_coin_state.set_require_fresh_credit_pool(run_arm.embedded_arm_enabled);
 
         // E4 re-soak fix (bad-cb-payee at 1519827): the projected masternode
         // payee is only dashd-exact when the payee queue has folded EVERY
@@ -2584,7 +2624,7 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         // MnStateMachine's forward-contiguity guard + the maintainer's gap
         // fail-closed path (wipe + authoritative protx re-seed) close the
         // gap itself.
-        node_coin_state.set_require_fresh_mn_payee(testnet || embedded_mainnet);
+        node_coin_state.set_require_fresh_mn_payee(run_arm.embedded_arm_enabled);
 
         // H-6: SML/quorum apply and bestCL adoption move ASYNCHRONOUSLY to the
         // header tip. When they advance (catching the SML up to a moved tip, or
@@ -2750,7 +2790,7 @@ int run_node(bool testnet, const std::string& rpc_endpoint,
         // getheaders off our current locator + a mempool prime.
         coin_p2p->set_on_handshake_complete(
             [cp = coin_p2p.get(), hc = header_chain.get(), sml_base,
-             discover = coin_p2p_discover]() {
+             discover = coin_p2p_discover_eff]() {
                 LOG_INFO << "[EMB-DASH] handshake complete -> initial sync:"
                             " getheaders + mempool + mnlistdiff(cold)"
                          << (discover ? " + getaddr (peer crawl)" : "");

src/impl/dash/coin/arm_resolution.hpp

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+#pragma once
+
+/// #738 — which template arm a `--run` invocation resolves to, as ONE pure,
+/// testable function.
+///
+/// THE DEFECT THIS CLOSES
+/// ---------------------
+/// Taking the embedded (daemonless) template arm needs TWO independent
+/// conditions, and before this header NO SINGLE FLAG satisfied both:
+///
+///   (1) the work-source arm gate — DASHWorkSource only consults the embedded
+///       bundle when `is_testnet_ || embedded_mainnet_` (work_source.cpp
+///       get_work / resource_template_now). On mainnet that means
+///       `--embedded-mainnet`.
+///   (2) a live coin-state FEED — NodeCoinState::populated() only flips once
+///       CoinStateMaintainer publishes a tip, and the maintainer + header chain
+///       + ingest legs are constructed ONLY inside main_dash's `if (coin_p2p)`
+///       block, i.e. only when `--coin-p2p-connect` / `--coin-p2p-discover`
+///       built a CoinClient.
+///
+/// `--embedded-mainnet` satisfied (1) but not (2): with no coin-P2P flag the
+/// bundle was never fed, populated() stayed false forever, and every template
+/// came off the dashd fallback. `--coin-p2p-connect` satisfied (2) but not (1).
+/// So the whole daemonless stack was unreachable from any documented
+/// invocation. This resolver makes the EMBEDDED OPT-IN imply its own feed, so
+/// one flag arms both halves end to end.
+///
+/// ★ REWARD-SAFETY INVARIANT (hotel incident: `--coin-p2p-connect` once
+/// activated an unguarded embedded arm on a live production node) ★
+/// The implication is ONE-WAY and runs only in the safe direction:
+///
+///     embedded opt-in  =>  coin-state feed        (NEW — this is the wiring)
+///     coin-state feed  =>  embedded opt-in        (NEVER — explicitly not)
+///
+/// A transport flag can therefore never flip the arm. `--coin-p2p-connect`
+/// alone on mainnet still resolves DashdFallback, exactly as today, and a bare
+/// `--run` touches none of this. Both are pinned by tests.
+///
+/// STRICTLY single-coin (src/impl/dash only) and dependency-free: no I/O, no
+/// core reach, no allocation. main_dash.cpp is the sole production caller.
+
+namespace dash {
+namespace coin {
+
+/// Which arm a `--run` invocation resolves to. "EmbeddedEligible" means the
+/// arm is ARMED, not that it will serve: every per-template viability gate
+/// (SML fresh at tip, non-superblock height, credit-pool seed height, bestCL,
+/// MN-payee cursor, DKG plan completeness) still fails closed to the dashd
+/// fallback on the hot path. This is the outer, invocation-level decision only.
+enum class WorkArm {
+    DashdFallback,      ///< retained dashd getblocktemplate RPC arm (reward-safe default)
+    EmbeddedEligible,   ///< daemonless embedded arm armed AND fed
+};
+
+/// Why the resolution came out the way it did — the operator-facing diagnosis
+/// for the startup banner, and the assertion handle for the tests.
+enum class ArmReason {
+    NoOptIn,           ///< mainnet, no --embedded-mainnet: the default posture
+    MainnetGateOff,    ///< a coin-P2P feed was requested but the arm was NOT opted in
+    NoCoinStateFeed,   ///< the arm is enabled but nothing feeds NodeCoinState
+    Armed,             ///< arm enabled AND fed
+};
+
+/// The invocation-level inputs, straight off argv.
+struct ArmInputs {
+    bool testnet           = false;  ///< --testnet / --regtest
+    bool embedded_mainnet  = false;  ///< --embedded-mainnet (the embedded opt-in)
+    bool coin_p2p_connect  = false;  ///< at least one --coin-p2p-connect HOST:PORT
+    bool coin_p2p_discover = false;  ///< --coin-p2p-discover
+};
+
+struct ArmResolution {
+    WorkArm   arm    = WorkArm::DashdFallback;
+    ArmReason reason = ArmReason::NoOptIn;
+
+    /// Construct the CoinClient + HeaderChain + CoinStateMaintainer + ingest
+    /// legs? (main_dash's `if (coin_p2p)` block.)
+    bool coin_feed_armed = false;
+
+    /// Turn on seed-based peer discovery because the embedded opt-in was given
+    /// with no pinned peer — the daemonless posture needs somewhere to sync
+    /// from. False whenever the operator named peers or asked for discovery
+    /// themselves.
+    bool discover_implied = false;
+
+    /// The work-source gate: DASHWorkSource::set_embedded_mainnet / is_testnet.
+    bool embedded_arm_enabled = false;
+};
+
+/// Pure resolution. No hidden state, no ordering dependence.
+inline ArmResolution resolve_embedded_arm(const ArmInputs& in)
+{
+    ArmResolution r;
+
+    // Half (1): the arm gate. Byte-identical to the predicate DASHWorkSource
+    // applies internally (`is_testnet_ || embedded_mainnet_`), so the two
+    // halves cannot drift.
+    r.embedded_arm_enabled = in.testnet || in.embedded_mainnet;
+
+    // Half (2): the feed. An operator-named transport (pinned peers or explicit
+    // discovery) arms it, exactly as before.
+    const bool explicit_feed = in.coin_p2p_connect || in.coin_p2p_discover;
+
+    // ★ The one-way implication. ONLY the embedded opt-in may imply a feed, and
+    // only when the operator named no transport of their own. The converse is
+    // deliberately absent: no transport flag ever sets embedded_arm_enabled.
+    r.discover_implied = in.embedded_mainnet && !explicit_feed;
+    r.coin_feed_armed  = explicit_feed || r.discover_implied;
+
+    if (!r.embedded_arm_enabled) {
+        // Mainnet with no opt-in. A requested feed still runs (block relay,
+        // witness) but cannot move the arm — the hotel-incident invariant.
+        r.arm    = WorkArm::DashdFallback;
+        r.reason = explicit_feed ? ArmReason::MainnetGateOff : ArmReason::NoOptIn;
+    } else if (!r.coin_feed_armed) {
+        // Reachable for a bare `--testnet` (arm enabled by network, no feed
+        // requested and none implied, because --embedded-mainnet is what
+        // implies one). Unchanged behaviour.
+        r.arm    = WorkArm::DashdFallback;
+        r.reason = ArmReason::NoCoinStateFeed;
+    } else {
+        r.arm    = WorkArm::EmbeddedEligible;
+        r.reason = ArmReason::Armed;
+    }
+    return r;
+}
+
+inline const char* arm_name(WorkArm a)
+{
+    switch (a) {
+        case WorkArm::EmbeddedEligible: return "embedded";
+        case WorkArm::DashdFallback:    break;
+    }
+    return "dashd-fallback";
+}
+
+inline const char* arm_reason_text(ArmReason r)
+{
+    switch (r) {
+        case ArmReason::NoOptIn:
+            return "no --embedded-mainnet (default reward-safe posture)";
+        case ArmReason::MainnetGateOff:
+            return "coin-P2P feed requested but --embedded-mainnet absent "
+                   "(transport only; the arm never follows the transport)";
+        case ArmReason::NoCoinStateFeed:
+            return "embedded arm enabled but no coin-state feed "
+                   "(--coin-p2p-connect / --coin-p2p-discover / --embedded-mainnet)";
+        case ArmReason::Armed:
+            break;
+    }
+    return "embedded opt-in + coin-state feed both present "
+           "(per-template viability gates still fail closed to dashd)";
+}
+
+}  // namespace coin
+}  // namespace dash