Bump version and add/fix documentation

README.md

@@ -9,13 +9,33 @@ This program used to be written in Python with some C wrapped in Cython, but I h
 ## Running
 The nonceMiner binary is dependent on OpenSSL. The OpenSSL light binary is availible for Windows on [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html), and this usually comes pre-installed on Linux.
 
+The binary is executable with the following options.
+
+```
+Options:
+  -h    Print the help message
+  -a    Specify the hash algorithm {DUCO_S1, xxhash}
+  -i    Job difficulty/intensity {LOW, MEDIUM, NET, EXTREME}
+  -o    Node URL of the format <host>:<port>
+  -u    Username for mining
+  -t    Number of threads
+```
+
+Please note that the xxhash mode is additionally up to five times faster, but the server imposes a per-thread hashrate limit of 0.9 MH/s. Exceeding this limit will cause shares to be rejected.
+
 ## Compiling
 I compiled this before in Windows 10 and WSL2 (Ubuntu 20.04 LTS), so results outside these environments may vary.
 
 Prerequisites: `gcc` (MinGW on Windows), `libssl-dev` (at least a development OpenSSL binary in Windows, I used the [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) copy, *not the "light" binary*)
 
 1) Call `make nonceMiner` in the repo directory
-2) Execute `./bin/nonceMiner` in the repo directory, or pull the compiled binary from `bin`
+2) Execute `./bin/nonceMiner -u <your username here>` in the repo directory, or pull the compiled binary from `bin`
+
+Additionally, the following test programs are available:
+* `benchmark` - Evaluate DUCO-S1 and xxhash performance on your machine
+* `nonceMiner_minimal` - A minimal implementation of DUCO-S1 with no error handling or multithreading
+* `nonceMiner_minimal_xxhash` - A minimal implementation of xxhash with no error handling or multithreading
+To compile one of them, just `make` with its program name.
 
 ## Attribution
 This project uses SHA-1 code from OpenSSL.
@@ -73,4 +93,41 @@ This project uses SHA-1 code from OpenSSL.
  * Hudson ([email protected]).
  *
  */
- ```
+```
+
+This project uses xxhash.
+```
+/*
+ * xxHash - Extremely Fast Hash algorithm
+ * Copyright (C) 2012-2020 Yann Collet
+ *
+ * BSD 2-Clause License (https://www.opensource.org/licenses/bsd-license.php)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *    * Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *    * Redistributions in binary form must reproduce the above
+ *      copyright notice, this list of conditions and the following disclaimer
+ *      in the documentation and/or other materials provided with the
+ *      distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * You can contact the author at:
+ *   - xxHash homepage: https://www.xxhash.com
+ *   - xxHash source repository: https://github.com/Cyan4973/xxHash
+ */
+```

src/nonceMiner.c

@@ -1,7 +1,7 @@
 #include <stdio.h>
 #include <string.h>
 #include <time.h>
-#include <getopt.h>
+#include <getopt.h> // gcc-only library (TODO: offer cl.exe alternative?)
 #include <stdarg.h>
 #ifdef _WIN32 // Windows-unique preprocessor directives for compatiblity
     #ifdef _WIN32_WINNT
@@ -130,6 +130,19 @@ void print_formatted_log(const char* code, const char* format, ...){
     printf("\n");
 }
 
+void print_help(){
+    puts("nonceMiner v2.0.0 by colonelwatch");
+    puts("A miner applying hash midstate caching and other optimzations to the duinocoin project");
+    puts("Typical usage: nonceMiner -u <your username here> [OPTIONS]");
+    puts("Options:");
+    puts("  -h    Print the help message");
+    puts("  -a    Specify the hash algorithm {DUCO_S1, xxhash}");
+    puts("  -i    Job difficulty/intensity {LOW, MEDIUM, NET, EXTREME}");
+    puts("  -o    Node URL of the format <host>:<port>");
+    puts("  -u    Username for mining");
+    puts("  -t    Number of threads");
+}
+
 void* mining_routine(void* arg){
     int len;
     char buf[256], thread_code[16];
@@ -245,7 +258,7 @@ void* mining_routine(void* arg){
             t0 = t1;
 
             // Generates and sends result string
-            len = sprintf(buf, "%ld,%d,nonceMiner v1.4.2,%s\n", nonce, local_hashrate, identifier);
+            len = sprintf(buf, "%ld,%d,nonceMiner v2.0.0,%s\n", nonce, local_hashrate, identifier);
             len = send(soc, buf, len, 0);
             if(len == -1){
                 SPRINT_SOCK_ERRNO(buf, sizeof(buf), SOCK_ERRNO);
@@ -330,8 +343,11 @@ int main(int argc, char **argv){
     int opt;
     opterr = 0; // Disables default getopt error messages
 
-    while((opt = getopt(argc, argv, "a:i:o:u:w:t:")) != -1){
+    while((opt = getopt(argc, argv, "ha:i:o:u:w:t:")) != -1){
         switch(opt){
+            case 'h':
+                print_help();
+                return 0;
             case 'a':
                 if(strcmp(optarg, "DUCO_S1") == 0) using_xxhash = 0;
                 else if(strcmp(optarg, "xxhash") == 0) using_xxhash = 1;
@@ -405,7 +421,7 @@ int main(int argc, char **argv){
     else
         job_request_len = sprintf(job_request, "JOB,%s,%s\n", username, diff_string);
 
-    printf("Initializing nonceMiner v1.4.2...\n");
+    printf("Initializing nonceMiner v2.0.0...\n");
     printf("Configured with username '%s', ", username);
     printf("identifier '%s', ", identifier);
     printf("difficulty '%s', ", diff_string);

test/nonceMiner_minimal_xxhash.c

@@ -1,5 +1,5 @@
 /*
-    Minimum code required to solve a DUCO-S1 job, with no error handling or multithreading
+    Minimum code required to solve a xxhash job, with no error handling or multithreading
     and intended for educational/diagnostic purposes only.
     For extended use, please run the full version!
 */