Add docs/WINDOWS_INSTALLATION.md

docs/WINDOWS_INSTALLATION.md

@@ -0,0 +1,282 @@
+# Windows Installation
+
+This guide explains how to build, install, configure, and run a Contractless testnet node as a Windows service.
+
+Windows service commands should be run from an elevated PowerShell window. The service runs in the background and must be unlocked with `contractless-submit-key.exe` after it starts.
+
+## Build Flags
+
+The default build target is testnet:
+
+```powershell
+cargo build --release
+```
+
+The same testnet build can be requested explicitly:
+
+```powershell
+cargo build --release --features testnet
+```
+
+Mainnet has its own feature flag:
+
+```powershell
+cargo build --release --no-default-features --features mainnet
+```
+
+Mainnet is not active during the testnet phase. Use the testnet binary unless mainnet has been officially enabled.
+
+After building, release binaries are written to:
+
+```text
+target\release\
+```
+
+The testnet node binary is:
+
+```text
+target\release\contractless-testnet.exe
+```
+
+The Windows service unlock helper is:
+
+```text
+target\release\contractless-submit-key.exe
+```
+
+## PostgreSQL Installation
+
+The Windows PostgreSQL installer requires an elevated terminal. If you prefer to create PostgreSQL manually, [create the PostgreSQL database manually](src/branch/main/docs/POSTGRES.md).
+
+Contractless uses PostgreSQL for transaction lookup and mempool-style records. The node creates and updates its own tables during startup, but PostgreSQL itself must exist first with a database, user, password, and permissions.
+
+Build the release binaries first:
+
+```powershell
+cargo build --release
+```
+
+Run the PostgreSQL installer from an elevated PowerShell window:
+
+```powershell
+.\target\release\postgres_installer.exe
+```
+
+The Windows installer:
+
+- checks whether PostgreSQL already exists at the selected install path
+- downloads the PostgreSQL installer when needed
+- installs PostgreSQL unattended
+- creates or updates the configured database user
+- creates the configured database when it does not already exist
+- verifies the blockchain database login
+- prints the `[Postgres]` and `[Postgres-Testnet]` settings blocks to paste into `settings.ini`
+
+For testnet builds, paste the printed values into `[Postgres-Testnet]` in the active `settings.ini`.
+
+Example:
+
+```ini
+[Postgres-Testnet]
+host = 127.0.0.1
+port = 5432
+user = contractless
+password = your_postgres_password_here
+dbname = contractless_db
+```
+
+## Run Path and Settings Location
+
+The node loads `settings.ini` in this order:
+
+1. `--config <path>`
+2. `SETTINGS_PATH` environment variable
+3. `.\settings.ini`
+4. `settings.ini` beside the executable
+
+For a stable Windows service install, use:
+
+```text
+C:\Program Files\Contractless\settings.ini
+```
+
+Create the install directory from an elevated PowerShell window:
+
+```powershell
+New-Item -ItemType Directory -Force "C:\Program Files\Contractless"
+```
+
+Move the repository settings file into the install directory:
+
+```powershell
+Move-Item .\settings.ini "C:\Program Files\Contractless\settings.ini"
+```
+
+The node also scopes runtime folders by network internally, so testnet data and mainnet data do not collide.
+
+Important runtime paths:
+
+| Setting | Purpose |
+| --- | --- |
+| `BLOCK_PATH` | Saved block files |
+| `TORRENT_PATH` | Torrent metadata and staged torrents |
+| `DB_PATH` | sled state |
+| `BALANCE_SHEET` | Balance files |
+| `LOG_PATH` | Runtime logs |
+| `WALLET_PATH` | Wallet directory |
+| `WALLET_NAME` | Wallet filename |
+
+## Copy Binaries
+
+Copy the testnet node binary and Windows unlock helper into the install directory:
+
+```powershell
+Copy-Item .\target\release\contractless-testnet.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\contractless-submit-key.exe "C:\Program Files\Contractless\"
+```
+
+Copy the PostgreSQL installer if you want it available from the install directory:
+
+```powershell
+Copy-Item .\target\release\postgres_installer.exe "C:\Program Files\Contractless\"
+```
+
+Copy wallet tools:
+
+```powershell
+Copy-Item .\target\release\create_new_wallet.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\recreate_wallet.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\recreate_wallet_from_image.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\register_wallet.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\verify_address.exe "C:\Program Files\Contractless\"
+```
+
+Copy transaction and lookup tools as needed:
+
+```powershell
+Copy-Item .\target\release\create_transfer_tx.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\broadcast_transaction.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\lookup_height.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\lookup_transaction.exe "C:\Program Files\Contractless\"
+Copy-Item .\target\release\lookup_remote_balance.exe "C:\Program Files\Contractless\"
+```
+
+You can copy any additional tools from `target\release` using the same pattern.
+
+## Install the Service
+
+Install the Windows service from an elevated PowerShell window:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --install-service
+```
+
+This command is only needed the first time the service is installed. Do not run `--install-service` every time you restart the node, rebuild from source, or copy in a newer binary.
+
+The service is installed using the binary path where `contractless-testnet.exe` is located when `--install-service` is run. If you later move the binary to a different folder, uninstall and reinstall the service from the new path.
+
+## Start and Unlock the Service
+
+Start the service:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service
+```
+
+After the service starts, submit the wallet decryption key:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-submit-key.exe"
+```
+
+The service starts in a locked state. It does not begin normal unlocked node operation until `contractless-submit-key.exe` accepts the wallet key.
+
+Check the unlock pipe:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-submit-key.exe" ping
+```
+
+Check the service unlock state:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-submit-key.exe" status
+```
+
+## Stop the Service
+
+Stop the service from an elevated PowerShell window:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service
+```
+
+## Automatic Startup
+
+The service can be configured to start automatically with Windows.
+
+From an elevated PowerShell window:
+
+```powershell
+sc.exe config ContractlessTestnet start= auto
+```
+
+Or use Windows Services:
+
+1. Open `services.msc`
+2. Find `Contractless Testnet`
+3. Open Properties
+4. Set Startup type to `Automatic`
+
+If the service is set to start automatically, you do not need to run `--start-service` after every reboot. You still need to run `contractless-submit-key.exe` after the computer restarts because the service cannot unlock the wallet without the wallet decryption key.
+
+## Updating a Node
+
+For normal source updates, do not reinstall the service.
+
+Stop the service:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service
+```
+
+Pull the latest source:
+
+```powershell
+git pull
+```
+
+Rebuild:
+
+```powershell
+cargo build --release
+```
+
+Copy the updated binaries:
+
+```powershell
+Copy-Item .\target\release\contractless-testnet.exe "C:\Program Files\Contractless\" -Force
+Copy-Item .\target\release\contractless-submit-key.exe "C:\Program Files\Contractless\" -Force
+```
+
+Start the service:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service
+```
+
+Submit the wallet decryption key:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-submit-key.exe"
+```
+
+## Uninstall the Service
+
+Uninstall the service only when you want to remove the Windows service registration:
+
+```powershell
+& "C:\Program Files\Contractless\contractless-testnet.exe" --uninstall-service
+```
+
+Uninstalling is not part of normal updates.