hush3/doc/codebase-cleanup.md

Codebase Cleanup & Organization Options

1. Remove Build Artifacts from the Working Tree

The depends/ directory alone is 1.8 GB, with 479M in depends/sources/, 302M in depends/built/. The release/ dir is 395M, and repos/ is 164M. While release/ and repos/ are already in .gitignore, the depends/built/ and depends/work/ outputs are not explicitly ignored.

Actions:

• Add depends/built/, depends/work/, depends/x86_64-w64-mingw32/ to .gitignore
• Run git clean -fdx on build output directories periodically
• The .o and .a files in src/ (e.g., 22M libbitcoin_server.a) are build outputs cluttering the source tree

2. Move Large Binary Params Out of Git History

sapling-spend.params (46M) and sapling-output.params (3.5M) are committed directly. These are cryptographic proving keys from the Zcash Sapling trusted setup ceremony and cannot be regenerated. The node shuts down without them.

Options:

• Use Git LFS to track them instead
• Download them at build/install time via a script (like Zcash's fetch-params.sh)
• Keep as-is (current deliberate design choice — guarantees out-of-box operation)

3. Clean Up Tracked Editor/Autoconf Backup Files

src/univalue/configure~ is a tracked backup file. The root configure~ also exists. These should be removed from tracking and the .gitignore pattern *~ should catch them going forward.

• Remove src/univalue/configure~ from git tracking

4. Split Monolithic Source Files

Several files are extremely large and would benefit from decomposition:

File	Lines	Suggestion
src/main.cpp	8,217	Split validation, block processing, mempool logic into separate files
src/wallet/rpcwallet.cpp	6,392	Group RPC methods by category (send, receive, list, z-operations)
src/chainparams.cpp	5,420	Extract checkpoint data and chain-specific params to separate files
src/wallet/wallet.cpp	5,059	Split wallet transaction logic from key management

• Split src/main.cpp
  • 8,217 → 2,821 lines in main.cpp
  • Created tx_validation.cpp (1,012 lines) — transaction validation (IsStandardTx, CheckTransaction, ContextualCheckInputs, etc.)
  • Created mempool_accept.cpp (524 lines) — mempool acceptance and orphan management (AcceptToMemoryPool, AddOrphanTx, etc.)
  • Created block_processing.cpp (4,064 lines) — block processing, chain management, and disk I/O (ConnectBlock, DisconnectBlock, ActivateBestChain, CheckBlock, LoadBlockIndex, etc.)
  • Created main_internal.h (83 lines) — shared internal state (block index candidates, file info, dirty sets, etc.)
• Split src/wallet/rpcwallet.cpp
  • 6,392 → 4,099 lines in rpcwallet.cpp
  • Created wallet/rpcwallet_zindex.cpp (1,193 lines) — z-index query RPCs (getalldata, z_getinfo, z_getstats, etc.)
  • Created wallet/rpcwallet_zops.cpp (1,194 lines) — shielded async operation RPCs (z_sendmany, z_shieldcoinbase, z_mergetoaddress, etc.)
  • Created wallet/rpcwallet_internal.h (45 lines) — shared declarations and THROW_IF_SYNCING macro
• Split src/chainparams.cpp
  • 5,420 → 593 lines in chainparams.cpp
  • Created chainparams_checkpoints_hush3.h (1,986 lines) — HUSH3 checkpoint data
  • Created chainparams_checkpoints_dragonx.h (2,853 lines) — DRAGONX checkpoint data
• Split src/wallet/wallet.cpp
  • 5,059 → 4,143 lines in wallet.cpp
  • Created wallet_keys.cpp (975 lines) — key management, encryption, HD seed, keypool

5. Move Implementation Out of Header Files

There are 13,652 lines of implementation code in hush_*.h headers:

Header	Lines
src/hush_utils.h	2,549
src/hush_gateway.h	2,531
src/hush_bitcoind.h	1,867
src/hush_curve25519.h	1,017
src/hush_nSPV_superlite.h	977
src/hush_nSPV_fullnode.h	914
src/hush_defs.h	656
src/hush_nSPV.h	603
src/hush_nSPV_wallet.h	505
src/hush_notary.h	469
src/hush_globals.h	360
src/hush_ccdata.h	272
src/hush_kv.h	204
src/hush_nSPV_defs.h	193

• Move implementations from hush_*.h headers to .cpp files
  • Created src/hush_impl.cpp — compiles all hush_*.h implementation via HUSH_PRIVATE_IMPLEMENTATION guard
  • Created src/hush_nSPV_impl.cpp — compiles all hush_nSPV_*.h implementation
  • Modified src/hush.h with #ifdef HUSH_PRIVATE_IMPLEMENTATION to separate implementation from declarations
  • main.cpp now includes declarations only (no longer a unity build for hush code)

6. Deduplicate Vendored Code

cJSON has been consolidated:

• src/cJSON.c + src/cJSON.h — canonical implementation, compiled as a standalone C translation unit

• src/hush_cJSON.cpp + src/hush_cJSON.h — helper/wrapper functions, compiled as a standalone C++ translation unit

• src/cc/includes/cJSON.h — thin redirect to the canonical headers above

• src/cc/dapps/cJSON.c — deleted (old 2009 fork); dapp includes updated to use canonical copy

• Consolidate to a single copy and have other modules link against it

7. Relocate Shell Scripts Out of src/

There are 15+ shell scripts and .bat files tracked inside src/:

• dragonx-cli, dragonxd, tush-cli, tushd, zush

• smartchains, purge, listassetchains, listassetchainparams

• testdragonx-cli, testdragonxd, testequihash-cli, testequihashd

• assetchains_stop, hush-arrakis-chain

• .bat variants: dragonx-cli.bat, dragonxd.bat, hush-arrakis-chain.bat

• Move shell scripts to contrib/scripts/ directory

8. Organize the repos/ Directory (N/A — repos/ is gitignored)

9. Improve .gitignore Coverage

The current .gitignore has redundant and scattered entries (e.g., src/cc/dapps/a.out listed twice, many game-related paths for a rogue game that appears obsolete).

• Group entries by category (build outputs, editor files, platform-specific)
• Remove stale entries for files/features that no longer exist
• Add depends/built/, depends/work/, depends/x86_64-*/

10. Consolidate Documentation

Docs are split across doc/, contrib/README.md, and the root.

• Create a doc/architecture.md describing the module structure

---

Recommended Priority

Highest-impact, lowest-risk changes (don't touch compiled code):

1. Items 1, 3, 9 — .gitignore cleanup and removing tracked backup files
2. Item 7 — relocate scripts out of src/

Higher-impact, higher-risk changes (affect build system and code):

4. Item 5 — move implementation out of headers
5. Item 4 — split monolithic source files
6. Item 6 — deduplicate cJSON
7. Item 2 — Move shell scripts to contrib/scripts/ directory Done — moved 15 loose scripts from contrib/ root into contrib/scripts/