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:**
- [x] 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`)
- [x] 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.

- [x] 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 |

- [x] 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.)
- [x] 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
- [x] 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
- [x] 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 |

- [x] 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` exists in **4 copies**:

- `src/cJSON.c` + `src/cJSON.h`
- `src/hush_cJSON.c` + `src/hush_cJSON.h`
- `src/cc/dapps/cJSON.c`
- `src/cc/includes/cJSON.h`

- [ ] 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`

- [x] 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).

- [x] Group entries by category (build outputs, editor files, platform-specific)
- [x] Remove stale entries for files/features that no longer exist
- [x] 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