Extend signetchallenge to set target block spacing

Inspired by bitcoin#27446, this commit
implements the proposal detailed in the comment
bitcoin#27446 (comment).

Rationale.

Introduce the ability to configure a custom target time between blocks in a
custom Bitcoin signet network. This enhancement enables users to create a signet
that is more conducive to testing. The change enhances the flexibility of signet,
rendering it more versatile for various testing scenarios. For instance, I am
currently working on setting up a signet with a 30-second block time. However,
this caused numerous difficulty adjustments, resulting in an inconsistent
network state. Regtest isn't a viable alternative for me in this context since
we prefer defaults to utilize our custom signet when configured, without
impeding local regtest development.

Implementation.

If the challenge format is "OP_RETURN PUSHDATA<params> PUSHDATA<actual
challenge>", the actual challenge from the second data push is used as the
signet challenge, and the parameters from the first push are used to configure
the network. Otherwise the challenge is used as is.

This change is backward-compatible, as per the old rules, such a signet
challenge would always evaluate to false, rendering it unused.

The only parameter currently available is "target_spacing" (default 600
seconds). To set it, place "0x01<target_spacing as uint64_t, little endian>" in
the params. Empty params are also valid. If other network parameters are added
in the future, they should use "0x02<option 2 value>", "0x03<option 3 value>",
etc., following the protobuf style.

Two public functions were added to chainparams.h:
  - ParseWrappedSignetChallenge: Extracts signet params and signet challenge
    from a wrapped signet challenge.
  - ParseSignetParams: Parses <params> bytes of the first data push.

Function ReadSigNetArgs calls ParseWrappedSignetChallenge and ParseSignetParams
to implement the new meaning of signetchallenge.

The description of the flag -signetchallenge was updated to reflect the changes.

A new unit tests file, chainparams_tests.cpp, was added, containing tests for
ParseWrappedSignetChallenge and ParseSignetParams.

The test signet_parse_tests from the file validation_tests.cpp was modified to
ensure proper understanding of the new logic.

In the functional test feature_signet.py, the value of -signetchallenge was
changed from OP_TRUE to the wrapped challenge, setting spacing to 30 seconds and
having the same actual challenge OP_TRUE.

The Signet miner was updated, introducing a new option --target-spacing with a
default of 600 seconds. It must be set to the value used by the network.

Example.

I tested this commit against Mutinynet, a signet running on a custom fork of
Bitcoin Core, implementing 30s target spacing. I successfully synchronized the
blockchain using the following config:

signet=1
[signet]
signetchallenge=6a4c09011e000000000000004c25512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae
addnode=45.79.52.207:38333
dnsseed=0

The content of this wrapped challenge:

6a OP_RETURN
4c OP_PUSHDATA1
09 (length of signet params = 9)
011e00000000000000 (signet params: 0x01, pow_target_spacing=30)
4c OP_PUSHDATA1
25 (length of challenge = 37)
512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae
(original Mutinynet challenge, can be found here:
https://blog.mutinywallet.com/mutinynet/ )

Author: starius

contrib/signet/miner

@@ -225,15 +225,15 @@ def seconds_to_hms(s):
         out = "-" + out
     return out
 
-def next_block_delta(last_nbits, last_hash, ultimate_target, do_poisson, max_interval):
+def next_block_delta(last_nbits, last_hash, ultimate_target, do_poisson, max_interval, target_spacing):
     # strategy:
     #  1) work out how far off our desired target we are
     #  2) cap it to a factor of 4 since that's the best we can do in a single retarget period
     #  3) use that to work out the desired average interval in this retarget period
     #  4) if doing poisson, use the last hash to pick a uniformly random number in [0,1), and work out a random multiplier to vary the average by
     #  5) cap the resulting interval between 1 second and 1 hour to avoid extremes
 
-    INTERVAL = 600.0*2016/2015 # 10 minutes, adjusted for the off-by-one bug
+    INTERVAL = float(target_spacing)*2016/2015 # 10 minutes, adjusted for the off-by-one bug
 
     current_target = nbits_to_target(last_nbits)
     retarget_factor = ultimate_target / current_target
@@ -308,8 +308,9 @@ def do_generate(args):
             return 1
         my_blocks = (start-1, stop, total)
 
-    if args.max_interval < 960:
-        logging.error("--max-interval must be at least 960 (16 minutes)")
+    max_interval_limit = args.target_spacing * 16 / 10
+    if args.max_interval < max_interval_limit:
+        logging.error("--max-interval must be at least %d (%f minutes)" % (max_interval_limit, max_interval_limit/60))
         return 1
 
     ultimate_target = nbits_to_target(int(args.nbits,16))
@@ -328,7 +329,7 @@ def do_generate(args):
         if lastheader is None:
             lastheader = bestheader["hash"]
         elif bestheader["hash"] != lastheader:
-            next_delta = next_block_delta(int(bestheader["bits"], 16), bestheader["hash"], ultimate_target, args.poisson, args.max_interval)
+            next_delta = next_block_delta(int(bestheader["bits"], 16), bestheader["hash"], ultimate_target, args.poisson, args.max_interval, args.target_spacing)
             next_delta += bestheader["time"] - time.time()
             next_is_mine = next_block_is_mine(bestheader["hash"], my_blocks)
             logging.info("Received new block at height %d; next in %s (%s)", bestheader["height"], seconds_to_hms(next_delta), ("mine" if next_is_mine else "backup"))
@@ -342,14 +343,14 @@ def do_generate(args):
             action_time = now
             is_mine = True
         elif bestheader["height"] == 0:
-            time_delta = next_block_delta(int(bestheader["bits"], 16), bci["bestblockhash"], ultimate_target, args.poisson, args.max_interval)
+            time_delta = next_block_delta(int(bestheader["bits"], 16), bci["bestblockhash"], ultimate_target, args.poisson, args.max_interval, args.target_spacing)
             time_delta *= 100 # 100 blocks
             logging.info("Backdating time for first block to %d minutes ago" % (time_delta/60))
             mine_time = now - time_delta
             action_time = now
             is_mine = True
         else:
-            time_delta = next_block_delta(int(bestheader["bits"], 16), bci["bestblockhash"], ultimate_target, args.poisson, args.max_interval)
+            time_delta = next_block_delta(int(bestheader["bits"], 16), bci["bestblockhash"], ultimate_target, args.poisson, args.max_interval, args.target_spacing)
             mine_time = bestheader["time"] + time_delta
 
             is_mine = next_block_is_mine(bci["bestblockhash"], my_blocks)
@@ -423,7 +424,7 @@ def do_generate(args):
         # report
         bstr = "block" if is_mine else "backup block"
 
-        next_delta = next_block_delta(block.nBits, block.hash, ultimate_target, args.poisson, args.max_interval)
+        next_delta = next_block_delta(block.nBits, block.hash, ultimate_target, args.poisson, args.max_interval, args.target_spacing)
         next_delta += block.nTime - time.time()
         next_is_mine = next_block_is_mine(block.hash, my_blocks)
 
@@ -502,6 +503,7 @@ def main():
     generate.add_argument("--backup-delay", default=300, type=int, help="Seconds to delay before mining blocks reserved for other miners (default=300)")
     generate.add_argument("--standby-delay", default=0, type=int, help="Seconds to delay before mining blocks (default=0)")
     generate.add_argument("--max-interval", default=1800, type=int, help="Maximum interblock interval (seconds)")
+    generate.add_argument("--target-spacing", default=600, type=int, help="Target interval between blocks (seconds), property of the network (default 600)")
 
     calibrate = cmds.add_parser("calibrate", help="Calibrate difficulty")
     calibrate.set_defaults(fn=do_calibrate)

src/Makefile.test.include

@@ -82,6 +82,7 @@ BITCOIN_TESTS =\
   test/blockmanager_tests.cpp \
   test/bloom_tests.cpp \
   test/bswap_tests.cpp \
+  test/chainparams_tests.cpp \
   test/checkqueue_tests.cpp \
   test/coins_tests.cpp \
   test/coinstatsindex_tests.cpp \

src/chainparams.cpp

@@ -10,6 +10,7 @@
 #include <consensus/params.h>
 #include <deploymentinfo.h>
 #include <logging.h>
+#include <script/script.h>
 #include <tinyformat.h>
 #include <util/chaintype.h>
 #include <util/strencodings.h>
@@ -21,6 +22,72 @@
 #include <stdexcept>
 #include <vector>
 
+void ParseWrappedSignetChallenge(const std::vector<uint8_t>& wrappedChallenge, std::vector<uint8_t>& outParams, std::vector<uint8_t>& outChallenge) {
+    if (wrappedChallenge.empty() || wrappedChallenge[0] != OP_RETURN) {
+        // Not a wrapped challenge.
+        outChallenge = wrappedChallenge;
+        return;
+    }
+
+    std::vector<uint8_t> params;
+    std::vector<uint8_t> challenge;
+
+    const CScript script(wrappedChallenge.begin(), wrappedChallenge.end());
+    CScript::const_iterator it = script.begin(), itend = script.end();
+    int i;
+    for (i = 0; it != itend; i++) {
+        if (i > 2) {
+            throw std::runtime_error("too many operations in wrapped challenge, must be 3.");
+        }
+        std::vector<unsigned char> push_data;
+        opcodetype opcode;
+        if (!script.GetOp(it, opcode, push_data)) {
+            throw std::runtime_error(strprintf("failed to parse operation %d in wrapped challenge script.", i));
+        }
+        if (i == 0) {
+            // OP_RETURN.
+            continue;
+        }
+        if (opcode != OP_PUSHDATA1 && opcode != OP_PUSHDATA2 && opcode != OP_PUSHDATA4) {
+                throw std::runtime_error(strprintf("operation %d of wrapped challenge script must be a PUSHDATA opcode, got 0x%02x.", i, opcode));
+        }
+        if (i == 1) {
+            params.swap(push_data);
+        } else if (i == 2) {
+            challenge.swap(push_data);
+        }
+    }
+    if (i != 3) {
+        throw std::runtime_error(strprintf("too few operations in wrapped challenge, must be 3, got %d.", i));
+    }
+
+    outParams.swap(params);
+    outChallenge.swap(challenge);
+}
+
+void ParseSignetParams(const std::vector<uint8_t>& params, CChainParams::SigNetOptions& options) {
+    if (params.empty()) {
+        return;
+    }
+
+    if (params.size() != 1 + 8) {
+        throw std::runtime_error(strprintf("signet params must have length %d, got %d.", 1+8, params.size()));
+    }
+    if (params[0] != 0x01) {
+        throw std::runtime_error(strprintf("signet params[0] must be 0x01, got 0x%02x.", params[0]));
+    }
+    // Parse little-endian 64 bit number to uint8_t.
+    const uint8_t* bytes = &params[1];
+    const uint64_t value = uint64_t(bytes[0]) | uint64_t(bytes[1])<<8 | uint64_t(bytes[2])<<16 | uint64_t(bytes[3])<<24 |
+            uint64_t(bytes[4])<<32 | uint64_t(bytes[5])<<40 | uint64_t(bytes[6])<<48 | uint64_t(bytes[7])<<56;
+    auto pow_target_spacing = int64_t(value);
+    if (pow_target_spacing <= 0) {
+        throw std::runtime_error("signet param pow_target_spacing <= 0.");
+    }
+
+    options.pow_target_spacing = pow_target_spacing;
+}
+
 void ReadSigNetArgs(const ArgsManager& args, CChainParams::SigNetOptions& options)
 {
     if (args.IsArgSet("-signetseednode")) {
@@ -35,7 +102,11 @@ void ReadSigNetArgs(const ArgsManager& args, CChainParams::SigNetOptions& option
         if (!val) {
             throw std::runtime_error(strprintf("-signetchallenge must be hex, not '%s'.", signet_challenge[0]));
         }
-        options.challenge.emplace(*val);
+        std::vector<unsigned char> params;
+        std::vector<unsigned char> challenge;
+        ParseWrappedSignetChallenge(*val, params, challenge);
+        ParseSignetParams(params, options);
+        options.challenge.emplace(challenge);
     }
 }
 

src/chainparams.h

@@ -28,4 +28,26 @@ const CChainParams &Params();
  */
 void SelectParams(const ChainType chain);
 
+/**
+ * Extracts signet params and signet challenge from wrapped signet challenge.
+ * Format of wrapped signet challenge is:
+ * If the challenge is in the form "OP_RETURN PUSHDATA<params> PUSHDATA<actual challenge>",
+ * If the input challenge does not start with OP_RETURN,
+ * sets outParams="" and outChallenge=input.
+ * If the input challenge starts with OP_RETURN, but does not satisfy the format,
+ * throws an exception.
+ */
+void ParseWrappedSignetChallenge(const std::vector<uint8_t>& wrappedChallenge, std::vector<uint8_t>& outParams, std::vector<uint8_t>& outChallenge);
+
+/**
+ * Parses signet options.
+ * The format currently supports only setting pow_target_spacing, but
+ * can be extended in the future.
+ * Possible values:
+ *  - Empty (then do nothing)
+ *  - 0x01 (pow_target_spacing as int64_t little endian) => set pow_target_spacing.
+ * If the format is wrong, throws an exception.
+ */
+void ParseSignetParams(const std::vector<uint8_t>& params, CChainParams::SigNetOptions& options);
+
 #endif // BITCOIN_CHAINPARAMS_H

src/chainparamsbase.cpp

@@ -20,7 +20,7 @@ void SetupChainParamsBaseOptions(ArgsManager& argsman)
     argsman.AddArg("-testnet", "Use the test chain. Equivalent to -chain=test.", ArgsManager::ALLOW_ANY, OptionsCategory::CHAINPARAMS);
     argsman.AddArg("-vbparams=deployment:start:end[:min_activation_height]", "Use given start/end times and min_activation_height for specified version bits deployment (regtest-only)", ArgsManager::ALLOW_ANY | ArgsManager::DEBUG_ONLY, OptionsCategory::CHAINPARAMS);
     argsman.AddArg("-signet", "Use the signet chain. Equivalent to -chain=signet. Note that the network is defined by the -signetchallenge parameter", ArgsManager::ALLOW_ANY, OptionsCategory::CHAINPARAMS);
-    argsman.AddArg("-signetchallenge", "Blocks must satisfy the given script to be considered valid (only for signet networks; defaults to the global default signet test network challenge)", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::CHAINPARAMS);
+    argsman.AddArg("-signetchallenge", "Blocks must satisfy the given script to be considered valid (only for signet networks; defaults to the global default signet test network challenge); in case -signetchallenge is in the form of 'OP_RETURN PUSHDATA<params> PUSHDATA<actual challenge>', then <actual challenge> is used as a challenge and <params> is used to set parameters of signet; currently the only supported parameter is target spacing, the format of <params> to set it is 01<8 bytes value of target spacing, seconds, little endian>", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::CHAINPARAMS);
     argsman.AddArg("-signetseednode", "Specify a seed node for the signet network, in the hostname[:port] format, e.g. sig.net:1234 (may be used multiple times to specify multiple seed nodes; defaults to the global default signet test network seed node(s))", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::CHAINPARAMS);
 }
 

src/kernel/chainparams.cpp

@@ -341,7 +341,7 @@ class SigNetParams : public CChainParams {
         consensus.CSVHeight = 1;
         consensus.SegwitHeight = 1;
         consensus.nPowTargetTimespan = 14 * 24 * 60 * 60; // two weeks
-        consensus.nPowTargetSpacing = 10 * 60;
+        consensus.nPowTargetSpacing = options.pow_target_spacing;
         consensus.fPowAllowMinDifficultyBlocks = false;
         consensus.fPowNoRetargeting = false;
         consensus.nRuleChangeActivationThreshold = 1815; // 90% of 2016

src/kernel/chainparams.h

@@ -136,6 +136,7 @@ class CChainParams
     struct SigNetOptions {
         std::optional<std::vector<uint8_t>> challenge{};
         std::optional<std::vector<std::string>> seeds{};
+        int64_t pow_target_spacing{10 * 60};
     };
 
     /**

src/test/chainparams_tests.cpp

@@ -0,0 +1,170 @@
+// Copyright (c) 2011-2024 The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#include <chainparams.h>
+
+#include <boost/test/unit_test.hpp>
+
+#include <util/strencodings.h>
+
+using namespace std::literals;
+
+BOOST_AUTO_TEST_SUITE(chainparams_tests)
+
+struct ParseWrappedSignetChallenge_TestCase
+{
+        std::string wrappedChallengeHex;
+        std::string wantParamsHex;
+        std::string wantChallengeHex;
+        std::string wantError;
+};
+
+BOOST_AUTO_TEST_CASE(parse_wrapped_signet_challenge)
+{
+    static const ParseWrappedSignetChallenge_TestCase cases[] = {
+            {
+                    "512103ad5e0edad18cb1f0fc0d28a3d4f1f3e445640337489abb10404f2d1e086be430210359ef5021964fe22d6f8e05b2463c9540ce96883fe3b278760f048f5189f2e6c452ae",
+                    "",
+                    "512103ad5e0edad18cb1f0fc0d28a3d4f1f3e445640337489abb10404f2d1e086be430210359ef5021964fe22d6f8e05b2463c9540ce96883fe3b278760f048f5189f2e6c452ae",
+                    "",
+            },
+            {
+                    "6a4c09011e000000000000004c25512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae",
+                    "011e00000000000000",
+                    "512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae",
+                    "",
+            },
+            {
+                    "6a4c004c25512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae",
+                    "",
+                    "512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae",
+                    "",
+            },
+            {
+                    "6a4c004c25512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae4c00",
+                    "",
+                    "",
+                    "too many operations in wrapped challenge, must be 3.",
+            },
+            {
+                    "6a4c09011e00000000000000",
+                    "",
+                    "",
+                    "too few operations in wrapped challenge, must be 3, got 2.",
+            },
+            {
+                    "6a4c01",
+                    "",
+                    "",
+                    "failed to parse operation 1 in wrapped challenge script.",
+            },
+            {
+                    "6a4c004c25512102f7561d208dd9ae99bf497273",
+                    "",
+                    "",
+                    "failed to parse operation 2 in wrapped challenge script.",
+            },
+            {
+                    "6a6a4c25512102f7561d208dd9ae99bf497273e16f389bdbd6c4742ddb8e6b216e64fa2928ad8f51ae4c00",
+                    "",
+                    "",
+                    "operation 1 of wrapped challenge script must be a PUSHDATA opcode, got 0x6a.",
+            },
+            {
+                    "6a4c09011e0000000000000051",
+                    "",
+                    "",
+                    "operation 2 of wrapped challenge script must be a PUSHDATA opcode, got 0x51.",
+            },
+    };
+
+    for (unsigned int i=0; i<std::size(cases); i++)
+    {
+        const auto wrappedChallenge = ParseHex(cases[i].wrappedChallengeHex);
+        const auto wantParamsHex = cases[i].wantParamsHex;
+        const auto wantChallengeHex = cases[i].wantChallengeHex;
+        const auto wantError = cases[i].wantError;
+
+        std::vector<uint8_t> gotParams;
+        std::vector<uint8_t> gotChallenge;
+        std::string gotError;
+        try {
+            ParseWrappedSignetChallenge(wrappedChallenge, gotParams, gotChallenge);
+        } catch (const std::exception& e) {
+            gotError = e.what();
+        }
+
+        BOOST_CHECK_EQUAL(HexStr(gotParams), wantParamsHex);
+        BOOST_CHECK_EQUAL(HexStr(gotChallenge), wantChallengeHex);
+        BOOST_CHECK_EQUAL(gotError, wantError);
+    }
+}
+
+struct ParseSignetParams_TestCase
+{
+        std::string paramsHex;
+        int64_t wantPowTargetSpacing;
+        std::string wantError;
+};
+
+BOOST_AUTO_TEST_CASE(parse_signet_params)
+{
+    static const ParseSignetParams_TestCase cases[] = {
+            {
+                    "",
+                    600,
+                    "",
+            },
+            {
+                    "011e00000000000000",
+                    30,
+                    "",
+            },
+            {
+                    "01e803000000000000",
+                    1000,
+                    "",
+            },
+            {
+                    "015802000000000000",
+                    600,
+                    "",
+            },
+            {
+                    "012502",
+                    600,
+                    "signet params must have length 9, got 3.",
+            },
+            {
+                    "022502000000000000",
+                    600,
+                    "signet params[0] must be 0x01, got 0x02.",
+            },
+            {
+                    "01ffffffffffffffff",
+                    600,
+                    "signet param pow_target_spacing <= 0.",
+            },
+    };
+
+    for (unsigned int i=0; i<std::size(cases); i++)
+    {
+        const auto params = ParseHex(cases[i].paramsHex);
+        const auto wantPowTargetSpacing = cases[i].wantPowTargetSpacing;
+        const auto wantError = cases[i].wantError;
+
+        CChainParams::SigNetOptions gotOptions;
+        std::string gotError;
+        try {
+            ParseSignetParams(params, gotOptions);
+        } catch (const std::exception& e) {
+            gotError = e.what();
+        }
+
+        BOOST_CHECK_EQUAL(gotOptions.pow_target_spacing, wantPowTargetSpacing);
+        BOOST_CHECK_EQUAL(gotError, wantError);
+    }
+}
+
+BOOST_AUTO_TEST_SUITE_END()