Setting Up a Contractless Testnet Node on Windows

Running a blockchain node often sounds more difficult than it really is.

A Contractless testnet node does require a public IP address, an open port, and PostgreSQL. However, the Windows release includes tools that handle most of the installation process.

You do not need specialized mining equipment.

You also do not need to understand the Contractless source code, manually create database tables, or leave a terminal window open while the node runs.

This guide walks through the complete Windows installation using the precompiled Contractless release.

📋 What You Need

Before beginning, make sure the computer meets the recommended requirements:

• 64-bit Windows
• At least 16 GB of memory
• An Intel i5, AMD equivalent, or better processor
• A dedicated public IP address
• One open public TCP port
• Administrator access to Windows
• A reliable Internet connection
• Accurate system time

Contractless uses very little CPU while mining. Specialized GPU or ASIC mining hardware is not required.

Each mining node must use its own public IP address.

🛡️ Open PowerShell as Administrator

The PostgreSQL installer and Windows service commands require Administrator access.

Open the Start menu, search for PowerShell, right-click it, and select:

Run as administrator

The PowerShell title bar should show that the window is running as Administrator.


Change into the extracted release directory:

Set-Location "C:\Users\YOURNAME\Downloads\YOUR-EXTRACTED-FOLDER"

Replace the example path with the actual location of the extracted release.

🌐 Open the Contractless Port

Other nodes must be able to connect to your Contractless node.

The default testnet port is:

50050

This port must be allowed through Windows Firewall. You can create a Windows Firewall rule from an Administrator PowerShell window:

New-NetFirewallRule `
  -DisplayName "Contractless Testnet" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 50050 `
  -Action Allow

The result of the above command and what it would look like in your windows defender firewall is something like this:


If the computer is behind a router, which most are, the port must also be forwarded from the router to the computer running Contractless.

Different routers and ISPs provide different ways of doing this. You may have to call your ISP for instructions here but usually the settings can be found through a local web interface such as 192.168.0.1


Opening a port does not automatically make a computer insecure.

The security of an open port depends on the software listening to it. Contractless accepts its own defined network protocol through this port.

🗄️ Install PostgreSQL

Contractless uses PostgreSQL for pending transactions and transaction lookups.

The release includes an installer that can download PostgreSQL, install it, create the database, create the database user, and verify the login.

From the Powershell Run:

.\installers\postgres_installer.exe

The installer asks for:

• PostgreSQL host
• PostgreSQL port
• Database name
• Database username
• Database user password
• PostgreSQL administrator password
• Installation directory
• Data directory
• Windows service name

For a normal local installation, most default values can be accepted by pressing Enter.

The two passwords must be entered and stored securely.


After the above settings are confiured postgres will automatically download an install.

When installation finishes, it prints the PostgreSQL settings needed by Contractless.

They will look similar to this:

[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = your_database_password
dbname = contractless_db

Copy the above settings from the output as these will be needed for section below on configuring the node.

Important PostgreSQL Warning

Do not open PostgreSQL port 5432 to the public Internet.

Contractless port 50050 must be publicly accessible.

PostgreSQL port 5432 should remain local or private. The normal host value is:

host = 127.0.0.1

⚙️ Configure the Node

Open settings.ini in Notepad or another text editor.

Under [Settings], enter the public IP address used by the node:

PUBLIC_IP = "YOUR.PUBLIC.IP.ADDRESS"
LISTEN_IP = "0.0.0.0"
TESTNET_RPC_PORT = "50050"
INCOMING_CONNECTIONS = "100"
OUTGOING_CONNECTIONS = "10"

PUBLIC_IP tells other nodes how to reach this node.

LISTEN_IP = "0.0.0.0" allows Contractless to listen on the available Windows network interfaces. If you have multiple IP addresses this may need changed to match the PUBLIC_IP.

Under [Postgres-Testnet], enter the values created by the PostgreSQL installer.


The default relative storage paths can normally remain unchanged:

BLOCK_PATH = "./blocks"
TORRENT_PATH = "./torrents"
DB_PATH = "./state"
BALANCE_SHEET = "./balance_sheet"
LOG_PATH = "./logs"
WALLET_PATH = "./wallets"

Contractless automatically creates separate testnet folders inside these locations.

📁 Create the Installation Folder

Create a permanent installation folder:

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

Copy the node and unlock helper into it:

Copy-Item .\contractless-testnet.exe "C:\Program Files\Contractless\"
Copy-Item .\contractless-submit-key.exe "C:\Program Files\Contractless\"

Move the configured settings file:

Move-Item .\settings.ini "C:\Program Files\Contractless\settings.ini"

Keeping the node, helper, and settings file together gives the Windows service a stable installation path.

🔧 Install the Windows Service

Install the Contractless testnet service:

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

This command is only needed during the first installation.

You do not need to reinstall the service whenever Windows restarts or Contractless is updated.

▶️ Start the Node

Start the Windows service:

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

Contractless now runs in the background.

The service begins in a locked state because it does not store the wallet decryption key where Windows could automatically retrieve it.

🔑 Unlock the Wallet

Unlock the service by running:

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

Enter the wallet encryption key when asked.

If a wallet does not already exist, Contractless creates one using the key provided during startup.

Keep this key safe. It is required to unlock the wallet again after restarting the computer.

You can check the service’s unlock state with:

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

You can also test whether the local unlock connection is responding:

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

✅ Confirm the Node Is Running

Open the Windows Services manager:

services.msc

Find:

Contractless Testnet

Its status should show that it is running.


You can also examine the node logs.

With the default paths, testnet logs are stored under:

C:\Program Files\Contractless\logs\testnet

The logs should begin showing postgres checks, startup connections, synchronization, and block activity.


A new node may need time to download and validate the existing testnet blockchain before it begins mining. This can take several minutes to several hours depending on the size of the chain at time of startup.

🔄 Start Automatically with Windows

Contractless can start automatically when Windows starts.

Run:

sc.exe config ContractlessTestnet start= auto

You can also configure this through services.msc:

1. Open the Contractless Testnet service.
2. Select Properties.
3. Change Startup type to Automatic.
4. Select Apply.

The service will then start automatically after a reboot.

However, after every reboot you must still run:

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

The wallet intentionally remains locked until its encryption key is submitted.

⏹️ Stopping the Node

To stop Contractless safely, run:

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

This stops the service without uninstalling it or deleting blockchain data.

🔨 Updating Contractless

Updating does not require reinstalling PostgreSQL or the Windows service.

The normal update process is:

1. Stop the service.
2. Download the newest Windows release.
3. Replace the node and unlock-helper executables.
4. Start the service.
5. Submit the wallet key.

Stop the node:

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

Replace the binaries from the newly extracted release:

Copy-Item .\contractless-testnet.exe "C:\Program Files\Contractless\" -Force
Copy-Item .\contractless-submit-key.exe "C:\Program Files\Contractless\" -Force

Start and unlock it again:

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

Do not replace settings.ini during a normal update unless the release specifically requires new settings.

🎉 The Node Is Now Part of the Testnet

Once synchronization finishes, the node can:

• Validate transactions
• Receive newly discovered blocks
• Provide torrent pieces to other nodes
• Participate in orphan correction
• Mine testnet currency
• Strengthen the Contractless peer-to-peer network

Setting up a Windows node does not require specialized mining equipment or continuous terminal management.

The node runs as a normal Windows service, remains available in the background, and can start automatically with the computer.

Every independent testnet node helps reveal how Contractless behaves across different computers, Internet providers, routers, firewalls, and real-world network conditions.

That testing is what turns software running on one developer’s machine into an actual decentralized network.