doc: Document how DATUM Gateway handles usernames

README.md

@@ -64,7 +64,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).
 
@@ -86,15 +92,15 @@ Compile DATUM by running:
 
     cmake . && make
 
-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:
+## Usage
 
-    blocknotify=killall -USR1 datum_gateway
+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.
 
-Ensure you have "killall" installed on your system (*psmisc* package on Debian-like OSs).
+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).
 
-If the node and Gateway are on different systems, you may need to utilize the "NOTIFY" endpoint on the Gateway's dashboard/API instead.
+You should review the [documentation on usernames](doc/usernames.md) next.
+Once you have everything running, you can point miners at the Gateway.
 
 ## 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.