From d30ac6f68101c9c31285db6b9160d0a007a9bc91 Mon Sep 17 00:00:00 2001
From: xdustinface <xdustinfacex@gmail.com>
Date: Thu, 12 Feb 2026 11:59:12 +0100
Subject: [PATCH] feat: add `CHANGELOG.md` and update `README.md`

---
 CHANGELOG.md | 14 ++++++++
 README.md    | 92 ++++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 85 insertions(+), 21 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..604b615
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+## v0.0.2 - initial SPV integration tests
+
+### Changed
+- improve the generator ([#1](https://github.com/dashpay/regtest-blockchain/pull/1)) @xdustinface
+
+### Added
+- implement unit and Integration tests for the generator ([#1](https://github.com/dashpay/regtest-blockchain/pull/1)) @xdustinface
+- add `pre-commit` and Github actions for basic CI ([#2](https://github.com/dashpay/regtest-blockchain/pull/2)) @xdustinface
+
+**Full Changelog**: https://github.com/dashpay/regtest-blockchain/compare/v0.0.1...v0.0.2
+
+## v0.0.1 - Initial test release
diff --git a/README.md b/README.md
index bc35af1..1d974a2 100644
--- a/README.md
+++ b/README.md
@@ -9,46 +9,96 @@ Contains blockchain state and wallet files with known addresses and transaction
 Download the latest release:
 
 ```bash
-curl -LO https://github.com/xdustinface/regtest-blockchain/releases/latest/download/regtest-1000.tar.gz
-tar -xzf regtest-1000.tar.gz
+curl -LO https://github.com/dashpay/regtest-blockchain/releases/latest/download/regtest-15000.tar.gz
+tar -xzf regtest-15000.tar.gz
 ```
 
 Start dashd with this data:
 
 ```bash
-dashd -datadir=./regtest-1000 -regtest -daemon
+dashd -datadir=./regtest-15000 -regtest -daemon
 ```
 
 ## What's Included
 
+Each dataset contains a full dashd data directory and exported wallet JSON files:
+
 ```
-regtest-1000/
+regtest-<height>/
 ├── dash.conf
-├── regtest/          # blockchain data
+├── regtest/            # blockchain data (blocks, chainstate, wallet dirs)
 │   ├── blocks/
 │   ├── chainstate/
-│   ├── default/      # wallet data
-│   ├── light/
-│   ├── normal/
-│   └── heavy/
-└── wallets/          # JSON wallet files with mnemonics & keys
-    ├── default.json
-    ├── light.json
-    ├── normal.json
-    └── heavy.json
+│   ├── indexes/
+│   └── <wallet_name>/  # dashd wallet directories
+└── wallets/            # exported JSON wallet files with mnemonics, addresses, UTXOs
+```
+
+The wallet JSON files contain HD mnemonics, derived addresses, transaction history, and UTXO sets for verifying sync against the blockchain.
+
+## Generating
+
+Generate test data with the included script:
+
+```bash
+# Generate 15000 blocks (outputs to data/regtest-15000/)
+python3 generate.py --blocks 15000
+
+# Specify a custom dashd binary
+python3 generate.py --blocks 15000 --dashd-path /path/to/dashd
+
+# Custom output directory
+python3 generate.py --blocks 15000 --output-dir /tmp/output
+```
+
+The `wallet-sync` strategy (default) creates a blockchain optimized for SPV wallet sync testing with targeted transactions at specific address indices, gap limit boundaries, filter batch boundaries, and coinbase reward ranges.
+
+Requires `dashd` and `dash-cli` in PATH (or specify with `--dashd-path`). Minimum block height is 120 (coinbase maturity requirement).
+
+## Re-exporting Wallet Data
+
+Re-export wallet statistics from an existing dataset without regenerating the blockchain:
+
+```bash
+python3 export_wallets.py data/regtest-15000
 ```
 
-The wallet JSON files contain HD mnemonics and derived addresses for verifying sync against the blockchain.
+This starts a temporary dashd instance, loads all wallets found in the data directory, and writes updated JSON files to `wallets/`.
+
+## Project Structure
+
+```
+├── generate.py           # main generation script
+├── export_wallets.py     # re-export wallet data from existing blockchain
+├── contrib/
+│   └── setup-dashd.py    # cross-platform dashd binary download for CI
+├── generator/            # generation library
+│   ├── dashd_manager.py  # dashd process lifecycle management
+│   ├── rpc_client.py     # dash-cli RPC wrapper
+│   ├── wallet_export.py  # wallet statistics collection and JSON export
+│   └── errors.py         # error types
+├── tests/                # unit and integration tests
+├── data/                 # generated datasets (git-tracked)
+└── .github/workflows/    # CI configuration
+```
 
-## Regenerating
+## Development
 
-Generate fresh test data with the included script:
+Install pre-commit hooks:
 
 ```bash
-# Generate 5000 blocks (outputs to data/regtest-5000/)
-./generate.py --blocks 5000
+pip install pre-commit
+pre-commit install
 ```
 
-The generator creates realistic transaction patterns across the wallet tiers - single outputs, multi-output transactions, dust amounts, and inter-wallet transfers. Each wallet maintains independent UTXOs with automatic refunding to ensure continuous activity.
+Run tests:
 
-Requires `dashd` and `dash-cli` in PATH (or specify with `--dashd-path`).
+```bash
+python3 -m pytest
+```
+
+Integration tests require a dashd binary. Set `DASHD_PATH` to run them:
+
+```bash
+DASHD_PATH=/path/to/dashd python3 -m pytest -m integration
+```