8.1 KiB

Raw Permalink Blame History

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:

cargo build --release

The same testnet build can be requested explicitly:

cargo build --release --features testnet

Mainnet has its own feature flag:

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:

target\release\

The testnet node binary is:

target\release\contractless-testnet.exe

The Windows service unlock helper is:

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.

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:

cargo build --release

Run the PostgreSQL installer from an elevated PowerShell window:

.\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:

[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:

--config <path>
SETTINGS_PATH environment variable
.\settings.ini
settings.ini beside the executable

For a stable Windows service install, use:

C:\Program Files\Contractless\settings.ini

Create the install directory from an elevated PowerShell window:

New-Item -ItemType Directory -Force "C:\Program Files\Contractless"

Move the repository settings file into the install directory:

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:

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:

Copy-Item .\target\release\postgres_installer.exe "C:\Program Files\Contractless\"

Copy wallet tools:

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:

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:

& "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:

& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service

After the service starts, submit the wallet decryption key:

& "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:

& "C:\Program Files\Contractless\contractless-submit-key.exe" ping

Check the service unlock state:

& "C:\Program Files\Contractless\contractless-submit-key.exe" status

Stop the Service

Stop the service from an elevated PowerShell window:

& "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:

sc.exe config ContractlessTestnet start= auto

Or use Windows Services:

Open services.msc
Find Contractless Testnet
Open Properties
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:

& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service

Pull the latest source:

git pull

Rebuild:

cargo build --release

Copy the updated binaries:

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