Contractless

Contractless is a peer-to-peer Fair-Proof-of-Work blockchain with native multi-asset transactions, torrent-based block synchronization and deterministic orphan correction. This README contains the minimum information needed to build, configure and start a node.

For the protocol design, mining rules, balance-sheet model and orphan correction process, read the Contractless whitepaper.

Table of Contents

• Network Requirements
• Build Instructions
• PostgreSQL Setup
• Settings Configuration
• Runtime Paths
• Startup
• Additional Documentation

Network Requirements

A public node needs to be reachable by other peers.

• Open the active RPC port in the local firewall.
• Forward the active RPC port through the router or host firewall when behind NAT.
• Set IP in settings.ini to the reachable public IP or reachable domain name for the node.
• Keep system time synchronized. Any reliable NTP/time server should work because Contractless only requires second-level timestamp agreement. A common default is pool.ntp.org.
• Keep PostgreSQL reachable locally by the node process.

Loopback and private addresses are useful for local testing, but they should not be announced by a public node.

Build Instructions

Install Rust and build from the repository root.

cargo build --release

The default build target is testnet.

Build Flags

Testnet is the default feature:

cargo build --release

or explicitly:

cargo build --release --features testnet

Mainnet has a feature flag, but mainnet builds are intentionally disabled during the testnet phase:

cargo build --release --no-default-features --features mainnet

That command will fail until mainnet is enabled for launch.

PostgreSQL Setup

Contractless uses PostgreSQL for transaction lookup and mempool-style records. PostgreSQL only needs a database, user, password and permissions before the node starts. On startup, the node creates or migrates the required tables and indexes automatically. The node also uses local file and sled storage for chain state, wallets, balance sheets and torrents.

Linux PostgreSQL CLI Tool

Build the release binaries, then run the installer as root so it can install PostgreSQL if needed and create the database, user, password and permissions:

sudo ./target/release/postgres_installer

After the tool completes, copy the printed PostgreSQL values into the active PostgreSQL section of settings.ini.

Windows PostgreSQL CLI Tool

Open PowerShell as Administrator, copy the built installer into the install folder, then run it:

& "C:\Program Files\Contractless\postgres_installer.exe"

The Windows installer downloads and installs PostgreSQL when needed, then creates the configured database, user, password and permissions.

Manual PostgreSQL Setup

Manual PostgreSQL instructions should live in docs/POSTGRES.md. Until that file is fully written, use the CLI installer unless you already know how to create the database, user and permissions manually.

Settings Configuration

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
5. platform fallback path

On Linux, the fallback path is:

/etc/contractless/settings.ini

On Windows, place settings.ini beside the executable:

C:\Program Files\Contractless\settings.ini

Basic settings.ini Shape

[Paths]
BLOCK_PATH = "./blocks"
TORRENT_PATH = "./torrents"
DB_PATH = "./state"
BALANCE_SHEET = "./balance_sheet"
LOG_PATH = "./logs"
WALLET_PATH = "./wallets"
WALLET_NAME = "contractless.wallet"

[Settings]
LOG_LEVEL = "info"
IP = "YOUR.PUBLIC.IP.ADDRESS"
LISTEN_IP = "0.0.0.0"
RPC_PORT = "50050"
TESTNET_RPC_PORT = "50055"
INCOMING_CONNECTIONS = "100"
OUTGOING_CONNECTIONS = "10"
VALIDATOR = "false"
THREADS = "8"

[Piggyback]
PIGGYBACK_1 = "contractless.dev:50050"

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

[Postgres]
host = 127.0.0.1
port = 5432
user = contractless
password = your_postgres_password_here
dbname = contractless_db

THREADS must be 1, 2 or a multiple of 4, and may not be greater than 256.

LOG_LEVEL follows normal logging filters:

• info shows info, warning and error logs.
• warn shows warning and error logs.
• error shows only error logs.
• off disables log output.

Detailed settings notes should live in docs/SETTINGS.md.

Runtime Paths

Relative paths in settings.ini are resolved relative to the location of that settings.ini file. The node scopes runtime data by active network internally, so testnet and mainnet paths do not collide when using the same base folders.

The main runtime folders are:

• BLOCK_PATH: saved block files
• TORRENT_PATH: torrent metadata and staged torrents
• DB_PATH: sled state
• WALLET_PATH: encrypted wallet files
• BALANCE_SHEET: balance sheet files
• LOG_PATH: runtime logs

Linux Copy Instructions

Create the config folder and copy the sample settings file:

sudo mkdir -p /etc/contractless
sudo cp ./settings.ini /etc/contractless/settings.ini

Copy the node binary:

sudo cp ./target/release/contractless-testnet /usr/bin/

Copy any CLI tools you want available system-wide:

sudo cp ./target/release/postgres_installer /usr/bin/
sudo cp ./target/release/create_new_wallet /usr/bin/
sudo cp ./target/release/register_wallet /usr/bin/

Repeat the same pattern for any other tools from target/release.

Windows Copy Instructions

Open PowerShell as Administrator and create the install folder:

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

Copy the node, key-submit tool, PostgreSQL installer and settings file:

Copy-Item ".\target\release\contractless-testnet.exe" "C:\Program Files\Contractless\"
Copy-Item ".\target\release\contractless-submit-key.exe" "C:\Program Files\Contractless\"
Copy-Item ".\target\release\postgres_installer.exe" "C:\Program Files\Contractless\"
Copy-Item ".\settings-windows.ini" "C:\Program Files\Contractless\settings.ini"

Copy any additional CLI tools the same way.

Startup

Create or restore a wallet before starting a public node, then make sure the wallet is registered and the wallet path/name in settings.ini matches the runtime wallet.

Linux Startup

Start the testnet node:

contractless-testnet

Linux prompts for the wallet decryption key, then detaches into the background automatically.

Run in the foreground for debugging:

contractless-testnet --foreground

Check daemon status:

contractless-testnet --status

Stop the daemon:

contractless-testnet --stop

Use a specific config file:

contractless-testnet --config /path/to/settings.ini

Windows Startup

Open PowerShell as Administrator and install the service:

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

Start the service:

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

Submit the wallet decryption key from a normal user shell:

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

Stop the service:

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

Uninstall the service:

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

Startup Flags

Node flags:

• --config <path>: load a specific settings.ini.
• --foreground: Linux only; keep the process attached to the terminal.
• --status: Linux only; check daemon status.
• --stop: Linux only; stop the daemon.
• --install-service: Windows only; install the Windows service.
• --start-service: Windows only; start the Windows service.
• --stop-service: Windows only; stop the Windows service.
• --uninstall-service: Windows only; uninstall the Windows service.

Additional Documentation

• Whitepaper
• Manual PostgreSQL setup
• Settings reference
• CLI tools reference
• Transaction reference
• Developer guide