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

### `IP`

Reachable IP address or domain name announced by this node during handshakes.

Use `127.0.0.1` only for local testing. A public node should use a public IP address or a domain name that resolves to the node and reaches the configured RPC port.

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

### `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 = "1.2.3.4:50053"
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 should be 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.