Skip to content

Commit 7b97563

Browse files
committed
Merge #19937: signet mining utility
595a34d contrib/signet: Document miner script in README.md (Anthony Towns) ff7dbdc contrib/signet: Add script for generating a signet chain (Anthony Towns) 13762bc Add bitcoin-util command line utility (Anthony Towns) 95d5d5e rpc: allow getblocktemplate for test chains when unconnected or in IBD (Anthony Towns) 81c54de rpc: update getblocktemplate with signet rule, include signet_challenge (Anthony Towns) Pull request description: Adds `contrib/signet/miner` for mining signet blocks. Adds `bitcoin-util` cli utility, with the idea being it can provide bitcoin related functionality that does not rely on the ability to access a running node. Only subcommand currently is "grind" which takes a hex-encoded header and grinds its nonce until its nBits is satisfied. Updates `getblocktemplate` to include `signet_challenge` field, and makes `getblocktemplate` require the signet rule when invoked on the signet change. Removes connectivity and IBD checks from `getblocktemplate` when applied to a test chain (regtest, testnet, signet). ACKs for top commit: laanwj: code review ACK 595a34d Tree-SHA512: 8d43297710fdc1edc58acd9b53e1bd1671e5724f7097b40ab73653715dc8becc70534c4496cbba9290f4dd6538a7a3d5830eb85f83391ea31a3bb5b9d3378cc3
2 parents 1801715 + 595a34d commit 7b97563

File tree

9 files changed

+1015
-7
lines changed

9 files changed

+1015
-7
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ src/bitcoin-cli
88
src/bitcoin-gui
99
src/bitcoin-node
1010
src/bitcoin-tx
11+
src/bitcoin-util
1112
src/bitcoin-wallet
1213
src/test/fuzz/*
1314
!src/test/fuzz/*.*

Makefile.am

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ BITCOIND_BIN=$(top_builddir)/src/$(BITCOIN_DAEMON_NAME)$(EXEEXT)
2525
BITCOIN_QT_BIN=$(top_builddir)/src/qt/$(BITCOIN_GUI_NAME)$(EXEEXT)
2626
BITCOIN_CLI_BIN=$(top_builddir)/src/$(BITCOIN_CLI_NAME)$(EXEEXT)
2727
BITCOIN_TX_BIN=$(top_builddir)/src/$(BITCOIN_TX_NAME)$(EXEEXT)
28+
BITCOIN_UTIL_BIN=$(top_builddir)/src/$(BITCOIN_UTIL_NAME)$(EXEEXT)
2829
BITCOIN_WALLET_BIN=$(top_builddir)/src/$(BITCOIN_WALLET_TOOL_NAME)$(EXEEXT)
2930
BITCOIN_NODE_BIN=$(top_builddir)/src/$(BITCOIN_MP_NODE_NAME)$(EXEEXT)
3031
BITCOIN_GUI_BIN=$(top_builddir)/src/$(BITCOIN_MP_GUI_NAME)$(EXEEXT)
@@ -81,6 +82,7 @@ $(BITCOIN_WIN_INSTALLER): all-recursive
8182
STRIPPROG="$(STRIP)" $(INSTALL_STRIP_PROGRAM) $(BITCOIN_CLI_BIN) $(top_builddir)/release
8283
STRIPPROG="$(STRIP)" $(INSTALL_STRIP_PROGRAM) $(BITCOIN_TX_BIN) $(top_builddir)/release
8384
STRIPPROG="$(STRIP)" $(INSTALL_STRIP_PROGRAM) $(BITCOIN_WALLET_BIN) $(top_builddir)/release
85+
STRIPPROG="$(STRIP)" $(INSTALL_STRIP_PROGRAM) $(BITCOIN_UTIL_BIN) $(top_builddir)/release
8486
@test -f $(MAKENSIS) && echo 'OutFile "$@"' | cat $(top_builddir)/share/setup.nsi - | $(MAKENSIS) -V2 - || \
8587
echo error: could not build $@
8688
@echo built $@
@@ -177,6 +179,9 @@ $(BITCOIN_CLI_BIN): FORCE
177179
$(BITCOIN_TX_BIN): FORCE
178180
$(MAKE) -C src $(@F)
179181

182+
$(BITCOIN_UTIL_BIN): FORCE
183+
$(MAKE) -C src $(@F)
184+
180185
$(BITCOIN_WALLET_BIN): FORCE
181186
$(MAKE) -C src $(@F)
182187

configure.ac

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ BITCOIN_DAEMON_NAME=bitcoind
2323
BITCOIN_GUI_NAME=bitcoin-qt
2424
BITCOIN_CLI_NAME=bitcoin-cli
2525
BITCOIN_TX_NAME=bitcoin-tx
26+
BITCOIN_UTIL_NAME=bitcoin-util
2627
BITCOIN_WALLET_TOOL_NAME=bitcoin-wallet
2728
dnl Multi Process
2829
BITCOIN_MP_NODE_NAME=bitcoin-node
@@ -571,7 +572,7 @@ CPPFLAGS="$CPPFLAGS -DHAVE_BUILD_INFO -D__STDC_FORMAT_MACROS"
571572

572573
AC_ARG_WITH([utils],
573574
[AS_HELP_STRING([--with-utils],
574-
[build bitcoin-cli bitcoin-tx bitcoin-wallet (default=yes)])],
575+
[build bitcoin-cli bitcoin-tx bitcoin-util bitcoin-wallet (default=yes)])],
575576
[build_bitcoin_utils=$withval],
576577
[build_bitcoin_utils=yes])
577578

@@ -593,6 +594,12 @@ AC_ARG_ENABLE([util-wallet],
593594
[build_bitcoin_wallet=$enableval],
594595
[build_bitcoin_wallet=$build_bitcoin_utils])
595596

597+
AC_ARG_ENABLE([util-util],
598+
[AS_HELP_STRING([--enable-util-util],
599+
[build bitcoin-util])],
600+
[build_bitcoin_util=$enableval],
601+
[build_bitcoin_util=$build_bitcoin_utils])
602+
596603
AC_ARG_WITH([libs],
597604
[AS_HELP_STRING([--with-libs],
598605
[build libraries (default=yes)])],
@@ -1209,6 +1216,7 @@ if test "x$enable_fuzz" = "xyes"; then
12091216
build_bitcoin_utils=no
12101217
build_bitcoin_cli=no
12111218
build_bitcoin_tx=no
1219+
build_bitcoin_util=no
12121220
build_bitcoin_wallet=no
12131221
build_bitcoind=no
12141222
build_bitcoin_libs=no
@@ -1433,7 +1441,7 @@ fi
14331441
dnl univalue check
14341442

14351443
need_bundled_univalue=yes
1436-
if test x$build_bitcoin_wallet$build_bitcoin_cli$build_bitcoin_tx$build_bitcoind$bitcoin_enable_qt$use_tests$use_bench = xnonononononono; then
1444+
if test x$build_bitcoin_wallet$build_bitcoin_cli$build_bitcoin_tx$build_bitcoin_util$build_bitcoind$bitcoin_enable_qt$use_tests$use_bench = xnononononononono; then
14371445
need_bundled_univalue=no
14381446
else
14391447
if test x$system_univalue != xno; then
@@ -1516,6 +1524,10 @@ AC_MSG_CHECKING([whether to build bitcoin-wallet])
15161524
AM_CONDITIONAL([BUILD_BITCOIN_WALLET], [test x$build_bitcoin_wallet = xyes])
15171525
AC_MSG_RESULT($build_bitcoin_wallet)
15181526

1527+
AC_MSG_CHECKING([whether to build bitcoin-util])
1528+
AM_CONDITIONAL([BUILD_BITCOIN_UTIL], [test x$build_bitcoin_util = xyes])
1529+
AC_MSG_RESULT($build_bitcoin_util)
1530+
15191531
AC_MSG_CHECKING([whether to build libraries])
15201532
AM_CONDITIONAL([BUILD_BITCOIN_LIBS], [test x$build_bitcoin_libs = xyes])
15211533
if test x$build_bitcoin_libs = xyes; then
@@ -1717,6 +1729,7 @@ AC_SUBST(BITCOIN_DAEMON_NAME)
17171729
AC_SUBST(BITCOIN_GUI_NAME)
17181730
AC_SUBST(BITCOIN_CLI_NAME)
17191731
AC_SUBST(BITCOIN_TX_NAME)
1732+
AC_SUBST(BITCOIN_UTIL_NAME)
17201733
AC_SUBST(BITCOIN_WALLET_TOOL_NAME)
17211734
AC_SUBST(BITCOIN_MP_NODE_NAME)
17221735
AC_SUBST(BITCOIN_MP_GUI_NAME)

contrib/signet/README.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,64 @@ Syntax: `getcoins.py [-h|--help] [-c|--cmd=<bitcoin-cli path>] [-f|--faucet=<fau
1717
If using the default network, invoking the script with no arguments should be sufficient under normal
1818
circumstances, but if multiple people are behind the same IP address, the faucet will by default only
1919
accept one claim per day. See `--password` above.
20+
21+
miner
22+
=====
23+
24+
To mine the first block in your custom chain, you can run:
25+
26+
cd src/
27+
CLI="./bitcoin-cli -conf=mysignet.conf"
28+
MINER="..contrib/signet/miner"
29+
GRIND="./bitcoin-util grind"
30+
ADDR=$($CLI -signet getnewaddress)
31+
$MINER --cli="$CLI" generate --grind-cmd="$GRIND" --address="$ADDR" --set-block-time=-1
32+
33+
This will mine a block with the current timestamp. If you want to backdate the chain, you can give a different timestamp to --set-block-time.
34+
35+
You will then need to pick a difficulty target. Since signet chains are primarily protected by a signature rather than proof of work, there is no need to spend as much energy as possible mining, however you may wish to choose to spend more time than the absolute minimum. The calibrate subcommand can be used to pick a target, eg:
36+
37+
$MINER calibrate --grind-cmd="$GRIND"
38+
nbits=1e00f403 for 25s average mining time
39+
40+
It defaults to estimating an nbits value resulting in 25s average time to find a block, but the --seconds parameter can be used to pick a different target, or the --nbits parameter can be used to estimate how long it will take for a given difficulty.
41+
42+
Using the --ongoing parameter will then cause the signet miner to create blocks indefinitely. It will pick the time between blocks so that difficulty is adjusted to match the provided --nbits value.
43+
44+
$MINER --cli="$CLI" generate --grind-cmd="$GRIND" --address="$ADDR" --nbits=1e00f403 --ongoing
45+
46+
Other options
47+
-------------
48+
49+
The --debug and --quiet options are available to control how noisy the signet miner's output is. Note that the --debug, --quiet and --cli parameters must all appear before the subcommand (generate, calibrate, etc) if used.
50+
51+
Instead of specifying --ongoing, you can specify --max-blocks=N to mine N blocks and stop.
52+
53+
Instead of using a single address, a ranged descriptor may be provided instead (via the --descriptor parameter), with the reward for the block at height H being sent to the H'th address generated from the descriptor.
54+
55+
Instead of calculating a specific nbits value, --min-nbits can be specified instead, in which case the mininmum signet difficulty will be targeted.
56+
57+
By default, the signet miner mines blocks at fixed intervals with minimal variation. If you want blocks to appear more randomly, as they do in mainnet, specify the --poisson option.
58+
59+
Using the --multiminer parameter allows mining to be distributed amongst multiple miners. For example, if you have 3 miners and want to share blocks between them, specify --multiminer=1/3 on one, --multiminer=2/3 on another, and --multiminer=3/3 on the last one. If you want one to do 10% of blocks and two others to do 45% each, --multiminer=1-10/100 on the first, and --multiminer=11-55 and --multiminer=56-100 on the others. Note that which miner mines which block is determined by the previous block hash, so occasional runs of one miner doing many blocks in a row is to be expected.
60+
61+
When --multiminer is used, if a miner is down and does not mine a block within five minutes of when it is due, the other miners will automatically act as redundant backups ensuring the chain does not halt. The --backup-delay parameter can be used to change how long a given miner waits, allowing one to be the primary backup (after five minutes) and another to be the secondary backup (after six minutes, eg).
62+
63+
The --standby-delay parameter can be used to make a backup miner that only mines if a block doesn't arrive on time. This can be combined with --multiminer if desired. Setting --standby-delay also prevents the first block from being mined immediately.
64+
65+
Advanced usage
66+
--------------
67+
68+
The process generate follows internally is to get a block template, convert that into a PSBT, sign the PSBT, move the signature from the signed PSBT into the block template's coinbase, grind proof of work for the block, and then submit the block to the network.
69+
70+
These steps can instead be done explicitly:
71+
72+
$CLI -signet getblocktemplate '{"rules": ["signet","segwit"]}' |
73+
$MINER --cli="$CLI" genpsbt --address="$ADDR" |
74+
$CLI -signet -stdin walletprocesspsbt |
75+
jq -r .psbt |
76+
$MINER --cli="$CLI" solvepsbt --grind-cmd="$GRIND" |
77+
$CLI -signet -stdin submitblock
78+
79+
This is intended to allow you to replace part of the pipeline for further experimentation, if desired.
80+

0 commit comments

Comments
 (0)