Contractless/docs/WINDOWS_INSTALLATION.md

# 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 <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.