Contractless/README.md

# 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](https://contractless.community/contractless_whitepaper.pdf).

## Table of Contents

- [Network Requirements](#network-requirements)
- [Build Instructions](#build-instructions)
- [PostgreSQL Setup](#postgresql-setup)
- [Settings Configuration](#settings-configuration)
- [Runtime Paths](#runtime-paths)
- [Startup](#startup)
- [Additional Documentation](#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.

```bash
cargo build --release
```

The default build target is testnet.

### Build Flags

Testnet is the default feature:

```bash
cargo build --release
```

or explicitly:

```bash
cargo build --release --features testnet
```

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

```bash
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:

```bash
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:

```powershell
& "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](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:

```text
/etc/contractless/settings.ini
```

On Windows, place `settings.ini` beside the executable:

```text
C:\Program Files\Contractless\settings.ini
```

### Basic `settings.ini` Shape

```ini
[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](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:

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

Copy the node binary:

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

Copy any CLI tools you want available system-wide:

```bash
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:

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

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

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

```bash
contractless-testnet
```

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

Run in the foreground for debugging:

```bash
contractless-testnet --foreground
```

Check daemon status:

```bash
contractless-testnet --status
```

Stop the daemon:

```bash
contractless-testnet --stop
```

Use a specific config file:

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

### Windows Startup

Open PowerShell as Administrator and install the service:

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

Start the service:

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

Submit the wallet decryption key from a normal user shell:

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

Stop the service:

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

Uninstall the service:

```powershell
& "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](https://contractless.community/contractless_whitepaper.pdf)
- [Manual PostgreSQL setup](docs/POSTGRES.md)
- [Settings reference](docs/SETTINGS.md)
- [CLI tools reference](docs/CLI_TOOLS.md)
- [Transaction reference](docs/TRANSACTIONS.md)
- [Developer guide](docs/DEV.md)