From 4d3d880036bfc823a1f9dff43f465f392043e7a4 Mon Sep 17 00:00:00 2001 From: Duke Date: Tue, 8 Aug 2023 15:40:52 -0400 Subject: [PATCH] Add docs for adding a new PoW algo --- doc/developer-notes.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 77233221c..eca281a0c 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -104,6 +104,27 @@ We should also check a recent block height to verify it's working correctly. The * If you stop a node, and restart, are the stats from `getchaintxtstats` correct, i.e. the anonset stats? For instance, `shielded_pool_size` should be close to 500000, if it's close to or exactly 0, something is wrong. * Is there a new file called `zindex.dat` in `~/.hush/HUSH3/` ? * Is `zindex.dat` 149 bytes ? + +# Adding a PoW algorithm + +We will describe here the high-level ideas on how to add a new PoW algorithm to +the Hush codebase. Adding a new PoW algo means adding a new option to the `-ac_algo` +CLI param for HSC's. + + * Add the new value to the end of the `ASSETCHAINS_ALGORITHMS` array in `src/hush_utils.h` + * You cannot add it to the front because the first element is the default "equihash" + * Increase the value of `ASSETCHAINS_NUMALGOS` by one + * This value cannot be automatically be determined by the length of the above array because Equihash has different supported variants of (N,K) values + * Add the new PoW mining library to a subdirectory in src, such as RandomX official code being in `src/RandomX` + * The largest part of adding a new PoW algo is adding a new class to src/miner.cpp + * Originally there was only BitcoinMiner, which was modified from a double-sha256 miner to an equihash miner, without changing the name + * When RandomX was added as an option, many big internals changes were needed to support more than a single miner class + * It is now easier to add PoW algos because the internals support using different miner classes + * Currently BitcoinMiner and RandomXMiner classes have a lot of duplicated code, but this is intentional + * In theory we could refactor the miner classes to share more code, but this means changes to one miner could break another and it is very challenging to test every possibile edge case for mining code + * So code duplication is purposeful, because it isolates the risk of breaking one PoW by changing another. We tried very hard to not break Equihash mining when adding RandomX mining. + * When adding a new mining class, copying the RandomXMiner class is best, since it's newer and does not contain various legacy code that still exists in BitcoinMiner + * So copy RandomXMiner to your new FooMiner, delete all the randomx-specific stuff and add in the PoW mining code # Coding