Merge branch '0.2.x'

.github/workflows/build.yaml

@@ -15,6 +15,7 @@ jobs:
           - ubuntu:22.04
           - debian:latest
           - debian:stable
+          - debian:oldstable
           - almalinux:latest
           - amazonlinux:latest
           - fedora:latest
@@ -25,6 +26,11 @@ jobs:
           - cmake_args: "-DENABLE_API=ON -DCMAKE_C_COMPILER=gcc"
           - cmake_args: "-DENABLE_API=ON -DCMAKE_C_COMPILER=clang"
           - cmake_args: "-DENABLE_API=OFF"
+        exclude:
+          # Clang configured for C11 rejects our C23 usage
+          - os: debian:oldstable
+            config:
+              cmake_args: "-DENABLE_API=ON -DCMAKE_C_COMPILER=clang"
 
     runs-on: ubuntu-latest
 

CMakeLists.txt

@@ -1,7 +1,17 @@
-cmake_minimum_required(VERSION 3.21)
+cmake_minimum_required(VERSION 3.13)
 
 project(DATUM VERSION 0.3.1 LANGUAGES C)
-set(CMAKE_C_STANDARD 23)
+
+# Enable C23 if supported, else fall back to C11 for compatibility
+if(CMAKE_VERSION VERSION_LESS "3.21")
+    # Older CMake: C23 not recognized; use C11
+    set(CMAKE_C_STANDARD 11)
+    set(CMAKE_C_STANDARD_REQUIRED ON)
+else()
+    # CMake 3.21+: C23 is available
+    set(CMAKE_C_STANDARD 23)
+    set(CMAKE_C_STANDARD_REQUIRED OFF)
+endif()
 
 option(ENABLE_API "Build API support." ON)
 
@@ -52,6 +62,7 @@ endif()
 pkg_check_modules(SODIUM REQUIRED libsodium)
 find_package(Threads REQUIRED)
 
+include(CheckFunctionExists)
 include(CheckLibraryExists)
 include(CMakePushCheckState)
 cmake_push_check_state(RESET)
@@ -63,6 +74,15 @@ if(LIBM)
 	list(APPEND POW_LIBS "m")
 endif()
 
+set(ARGP_LIBS "")
+check_function_exists(argp_parse HAVE_ARGP_PARSE)
+if(NOT HAVE_ARGP_PARSE)
+	check_library_exists(argp argp_parse "" ARGP)
+	if(ARGP)
+		list(APPEND ARGP_LIBS "argp")
+	endif()
+endif()
+
 cmake_pop_check_state()
 
 add_custom_target(generate_git_version
@@ -98,6 +118,7 @@ target_link_libraries(datum_gateway
 	PUBLIC
 	${POW_LIBS}
 	Threads::Threads
+	${ARGP_LIBS}
 	${CURL_LIBRARIES} ${CURL_LDFLAGS} ${CURL_LDFLAGS_OTHER}
 	${JANSSON_LIBRARIES} ${JANSSON_LDFLAGS} ${JANSSON_LDFLAGS_OTHER}
 	${SODIUM_LIBRARIES} ${SODIUM_LDFLAGS} ${SODIUM_LDFLAGS_OTHER}

README.md

@@ -66,7 +66,13 @@ At this time, you must also reserve some block space for the pool's generation t
 
 Note: This reservation requirement will be removed for Bitcoin Knots users in a future version of the DATUM Gateway thanks to support for on-the-fly specification of these metrics by the client in Knots (as of version 27.1).
 
-You must also configure a "*blocknotify*" setting to alert the Gateway of new blocks.  See Installation section.
+To avoid mining stale work, you will need to ensure the DATUM Gateway receives new block notifications from your node. It is suggested you run the DATUM Gateway as the same user as your full node and utilize the following configuration line in your bitcoin.conf:
+
+    blocknotify=killall -USR1 datum_gateway
+
+Ensure you have "killall" installed on your system (*psmisc* package on many OSs).
+
+If the node and Gateway are on different systems, you may need to utilize the "NOTIFY" endpoint on the Gateway's dashboard/API instead.
 
 Finally, the Gateway must have RPC access to your node, and you must add an RPC user to your configuration to facilitate this, as well as ensuring the service running the Gateway is whitelisted for RPC access (if not on the same machine).
 
@@ -82,29 +88,53 @@ Install and fully sync your Bitcoin full node. Instructions for this are beyond
 
 Configure your node to create block templates as you desire. Be sure to reserve some space for the generation transaction, otherwise your work will not be able to fit a reward split.  See node configuration recommendations above.
 
-Install the required libraries and development packages for dependencies: cmake, pkg-config, jansson, libmicrohttpd, libsodium, and libcurl.
+Install the required libraries and development packages for dependencies: cmake, pkgconf, libcurl, jansson, libsodium, and libmicrohttpd. You may also need psmisc for your node to send blocknotify signals to the DATUM Gateway.
 
-For Debian/Ubuntu it would be:
+For Debian/Ubuntu:
 
-    sudo apt install cmake pkgconf libcurl4-openssl-dev libjansson-dev libmicrohttpd-dev libsodium-dev psmisc
+    sudo apt install cmake pkgconf libcurl4-openssl-dev libjansson-dev libsodium-dev libmicrohttpd-dev psmisc
 
-For RedHat/Fedora it would be:
+For Fedora/Amazon Linux:
 
-    sudo dnf install cmake pkgconf libcurl-devel jansson-devel libmicrohttpd-devel libsodium-devel psmisc
+    sudo dnf install cmake pkgconf libcurl-devel jansson-devel libsodium-devel libmicrohttpd-devel psmisc
+
+For Alma Linux:
+
+    sudo dnf install epel-release dnf-plugins-core
+    sudo dnf config-manager --set-enabled crb
+    sudo dnf install cmake pkgconf libcurl-devel jansson-devel libsodium-devel libmicrohttpd-devel psmisc
+
+For Oracle Linux:
+
+    sudo dnf install epel-release dnf-plugins-core
+    sudo dnf config-manager --set-enabled ol9_codeready_builder
+    sudo dnf install cmake pkgconf libcurl-devel jansson-devel libsodium-devel libmicrohttpd-devel psmisc
+
+For Alpine (also needs a standalone argp library):
+
+    sudo apk add build-base cmake pkgconf argp-standalone curl-dev jansson-dev libsodium-dev libmicrohttpd-dev psmisc
+
+For Arch:
+
+    sudo pacman -Syu base-devel cmake pkgconf curl jansson libsodium libmicrohttpd psmisc
+
+For Clear Linux:
+
+    sudo swupd bundle-add c-basic cmake pkgconf devpkg-curl devpkg-jansson devpkg-libsodium devpkg-libmicrohttpd psmisc
 
 Compile DATUM by running:
 
     cmake . && make
 
+## Usage
+
 Run the datum_gateway executable with the -? flag for detailed configuration information, descriptions, and required options.  Then construct a configuration file (defaults to "datum_gateway_config.json" in the current working directory). Be sure to also set your coinbase tags.  The primary tag setting is unused in pooled mining, however the secondary tag is intended to show on things like block explorers when you mine a block.
 
-To avoid mining stale work, you will need to ensure the DATUM Gateway receives new block notifications from your node. It is suggested you run the DATUM Gateway as the same user as your full node and utilize the following configuration line in your bitcoin.conf:
+There is an [example configuration file included in the doc/ directory](doc/example_datum_gateway_config.json) you may wish to use as a template.
+Note that the API/web admin password is also used for preventing CSRF attacks, so it is crucial you set it to something reasonably secure (or disable the API/web interface entirely).
 
-    blocknotify=killall -USR1 datum_gateway
+You should review the [documentation on usernames](doc/usernames.md) next.
-
+Once you have everything running, you can point miners at the Gateway.
-Ensure you have "killall" installed on your system (*psmisc* package on Debian-like OSs).
-
-If the node and Gateway are on different systems, you may need to utilize the "NOTIFY" endpoint on the Gateway's dashboard/API instead.
 
 ## Template/Share Requirements for Pooled Mining
 

doc/usernames.md

@@ -0,0 +1,50 @@
+## General
+
+DATUM Gateway is designed with the assumption that pool usernames are generally Bitcoin addresses.
+While it is *possible* to specify non-addresses in your miner, and pass those through to the pool, the default username in the Gateway itself (the `mining`.`pool_address` configuration option) must always be a valid Bitcoin address, and the Gateway will not fully start until it is set to one.
+
+The rest of this document deals with Stratum usernames specifically, and how they are interpreted.
+
+**Always test your full mining stack configuration.**
+Misconfiguration of either the DATUM Gateway or your miners *can* result in lost work that is impossible to recover!
+
+## Limitations
+
+DATUM Gateway has a limit of 191 characters for Stratum usernames, including all special features specified by them.
+
+Your miner likely has a lower limit.
+For example,
+Avalons truncate usernames at 63 characters;
+Whatsminer has a buffer overflow (which may damage your miner) if you exceed 127;
+and so on.
+
+Some miners replace special characters (anything except alphanumeric, underscores, periods, and tildes) with hex codes (for example, `%` becomes `%25`), which can contribute toward reaching these limits and/or potentially confuse anything looking for them.
+
+Note that Stratum usernames are *only* used for pooled mining.
+When in non-pooled mode, they have no effect whatsoever, and only `mining`.`pool_address` is used to create blocks.
+
+## Bitcoin address requirements (non-pooled mode)
+
+This version of DATUM Gateway supports Base58 (aka Legacy), Bech32 (aka Segwit), and Bech32m (aka Taproot) addresses, for Bitcoin and Bitcoin testnet only.
+
+It will not detect if you are using an address for the wrong network.
+
+## Worker names
+
+Immediately following the Bitcoin address, you may append a period (`.`) and an arbitrary worker name.
+For compatibility, pools might also support an underscore (`_`) separator, but the DATUM Gateway codebase itself does not, and the period must be used to make use of Gateway features.
+
+If the Stratum username *begins* with a period, it is interpreted as a worker name only, and appended to the Gateway's default username (`mining`.`pool_address`) before being sent to the pool.
+
+## Passing usernames to the pool
+
+There are three different ways to pass usernames to your pool.
+
+By default, the Stratum username is always passed in full, as-is.
+You can make this explicit by setting `datum`.`pool_pass_full_users` to `true` in the config file, or "Send Miner Usernames To Pool: Override Bitcoin Address" in the web configurator.
+
+If you change `datum`.`pool_pass_full_users` to `false`, you can then set `datum`.`pool_pass_workers` instead (or "Send Miner Usernames To Pool: Send as worker names" in the web configurator).
+With this setting, the entire Stratum username will be appended after the default username (`mining`.`pool_address`) as a worker.
+
+Finally, if you set both options to `false`, the Stratum username will be ignored entirely.
+Instead, only the configured default username (`mining`.`pool_address`) will be used, without any worker names.