Contractless/docs/SETTINGS.md

# Settings Reference

Contractless reads `settings.ini` during startup. Relative paths are resolved relative to the location of the loaded `settings.ini` file. Runtime storage paths are also scoped by active network, so testnet and mainnet data are kept in separate subfolders.

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

## `[Paths]`

### `BLOCK_PATH`

Base folder where block files are stored. The active network name is appended automatically.

Example:

```ini
BLOCK_PATH = "./blocks"
```

Testnet will store blocks under:

```text
./blocks/testnet
```

Mainnet will store blocks under:

```text
./blocks/mainnet
```

### `TORRENT_PATH`

Base folder where torrent metadata, staged torrents and torrent-related files are stored. The active network name is appended automatically.

### `DB_PATH`

Base folder for the internal sled database used for non-PostgreSQL node state. The active network name is appended automatically.

### `WALLET_PATH`

Base folder where wallet files are stored. The active network name and `WALLET_NAME` are appended automatically.

Example:

```ini
WALLET_PATH = "./wallets"
WALLET_NAME = "contractless.wallet"
```

Testnet will load the wallet from:

```text
./wallets/testnet/contractless.wallet
```

### `WALLET_NAME`

Name of the encrypted wallet file to load at startup.

### `BALANCE_SHEET`

Base folder where balance sheet files are stored. The active network name is appended automatically.

## `[Settings]`

### `LOG_PATH`

Base folder where node log files are written. The active network name is appended automatically so testnet and mainnet nodes can run side by side without writing to the same rotating log files.

Example:

```ini
LOG_PATH = "./logs"
```

Testnet will write logs under:

```text
./logs/testnet
```

### `LOG_LEVEL`

Runtime log filter.

Valid common values:

- `info`: show info, warning and error logs.
- `warn`: show warning and error logs.
- `error`: show only error logs.
- `off`: disable log output.

The logger also supports more advanced module-level filters through `flexi_logger`, but normal nodes should use one of the simple values above.

### `PUBLIC_IP`

Reachable public IP address announced by this node during handshakes and network-map broadcasts.

Use `127.0.0.1` only for local testing. A public node should use the public IP address that outside peers use to reach the configured RPC port.

This value is protocol identity. It is validated against forbidden private or unroutable ranges before the node is accepted by peers.

### `LISTEN_IP`

Local bind address used by the RPC server.

Use `0.0.0.0` to listen on all local interfaces, which is usually the correct value for nodes behind NAT or router port forwarding.

This value is never announced to peers. It may be private, loopback or wildcard because it only controls where the local process listens.

### `RPC_PORT`

Mainnet RPC port. This value is used when the node is built with the `mainnet` feature.

Mainnet builds are currently disabled during the testnet phase, but the setting exists for launch.

### `TESTNET_RPC_PORT`

Testnet RPC port. This value is used when the node is built with the `testnet` feature.

Public testnet nodes must allow inbound traffic to this port.

### `INCOMING_CONNECTIONS`

Maximum number of incoming peer connections allowed by the node.

This should be greater than `0`. A recommended value is `50`.

If the limit is reached, new incoming peers are rejected during handshake.

### `OUTGOING_CONNECTIONS`

Maximum number of outgoing peer connections the node tries to discover and maintain.

This should be greater than `0`. A recommended value is `10`.

### `VALIDATOR`

Disables local mining while keeping the node connected to peers, synced and able to validate and rebroadcast network activity.

Use this for bootstrap or validator-only nodes:

```ini
VALIDATOR = "true"
```

Mining nodes should use:

```ini
VALIDATOR = "false"
```

### `THREADS`

Number of async worker tasks used during each mining nonce round.

Contractless mining only searches one byte of nonce space per timestamp, so all workers split the fixed `0..255` nonce range. More threads do not increase the total nonce space; they only split the fixed search range across more tasks.

Allowed values:

- `1`
- `2`
- any multiple of `4`

The value must be between `1` and `256`.

## `[Piggyback]`

Piggyback entries are startup peers. The node tries these peers when it first starts so it can join the network and discover other nodes.

```ini
[Piggyback]
PIGGYBACK_1 = "contractless.dev"
PIGGYBACK_2 = "5.6.7.8:50053"
```

The node only needs one live piggyback peer to begin discovery. Additional entries are backups if earlier entries are offline or unreachable.

Piggyback entries may use a public IP endpoint or a hostname. If no port is included, the active network RPC port is used. Hostnames are resolved only for these startup entries; nodes must still announce public IP endpoints in handshakes and network mapping.

Piggyback entries should resolve to public, routable peers. Private, loopback and invalid addresses are filtered before startup connections begin.

## `[Postgres-Testnet]`

PostgreSQL connection settings used by testnet builds.

```ini
[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = change_this_password
dbname = contractless_db
```

The configured database must already exist and the configured user must be able to create tables and indexes. The node creates or migrates its own tables on startup.

## `[Postgres]`

PostgreSQL connection settings used by mainnet builds.

```ini
[Postgres]
host = 127.0.0.1
port = 5432
user = contractless
password = change_this_password
dbname = contractless_db
```

Mainnet builds are currently disabled during the testnet phase, but this section is kept so the same settings file can be prepared for launch.