# 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 **Do not expose PostgreSQL to the public Internet. The PostgreSQL port should not be publicly accessible.** Contractless needs a public RPC port for peers, but PostgreSQL should stay local or private, usually on `127.0.0.1`. Do not open PostgreSQL port `5432` in your router, cloud firewall, VPS firewall, or host firewall. 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 ` 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.