Contractless/docs/SETTINGS.md

# Settings Reference

Contractless reads `settings.ini` during startup. This file controls runtime paths, logging, networking, peer discovery, mining behavior, paid data lookup fees, and PostgreSQL connection settings.

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, there is no `/etc` fallback. If no explicit config is provided, Windows checks the current working directory and then the executable directory.

## Default Settings

Example testnet settings:

```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"
PUBLIC_IP            = "your.public.ip.address"
LISTEN_IP            = "0.0.0.0"
RPC_PORT             = "50055"
TESTNET_RPC_PORT     = "50050"
INCOMING_CONNECTIONS = "100"
OUTGOING_CONNECTIONS = "10"
VALIDATOR            = "false"
THREADS              = "8"
STORAGE_LOOKUP_FEE_PER_BYTE = "0.0001"

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

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

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

## Paths and Network Folders

Relative paths are resolved relative to the loaded `settings.ini` file, not always relative to the terminal's current folder.

If Linux uses:

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

then:

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

resolves under:

```text
/etc/contractless/blocks
```

Contractless automatically appends the active network name to runtime storage paths. You do not add `testnet` or `mainnet` yourself.

Example:

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

Testnet stores blocks under:

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

Mainnet stores blocks under:

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

The same automatic network folder is added to:

- `BLOCK_PATH`
- `TORRENT_PATH`
- `DB_PATH`
- `BALANCE_SHEET`
- `LOG_PATH`
- `WALLET_PATH`

For `WALLET_PATH`, the node appends both the network folder and `WALLET_NAME`.

Example:

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

Testnet loads:

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

Mainnet loads:

```text
./wallets/mainnet/contractless.wallet
```

## Windows Paths

Windows accepts forward slashes in paths, and that is the clearest format for `settings.ini`:

```ini
BLOCK_PATH = "C:/Contractless/blocks"
TORRENT_PATH = "C:/Contractless/torrents"
DB_PATH = "C:/Contractless/state"
BALANCE_SHEET = "C:/Contractless/balance_sheet"
LOG_PATH = "C:/Contractless/logs"
WALLET_PATH = "C:/Contractless/wallets"
```

Backslashes can also be used, but avoid ending a quoted Windows path with a single trailing backslash because it can be confused with escaping the closing quote in some INI parsers or editors.

Good:

```ini
BLOCK_PATH = "C:\Contractless\blocks"
```

Avoid:

```ini
BLOCK_PATH = "C:\Contractless\blocks\"
```

If you want a trailing separator, use forward slashes:

```ini
BLOCK_PATH = "C:/Contractless/blocks/"
```

## `[Paths]`

### `BLOCK_PATH`

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

Default:

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

### `TORRENT_PATH`

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

Default:

```ini
TORRENT_PATH = "./torrents"
```

### `DB_PATH`

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

On Linux, the daemon PID file is also stored under the active network's `DB_PATH`.

Default:

```ini
DB_PATH = "./state"
```

### `BALANCE_SHEET`

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

Default:

```ini
BALANCE_SHEET = "./balance_sheet"
```

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

Default:

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

Testnet writes logs under:

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

Logs are written to rotating `node` log files. The current logger rotates at about 10 MB per file and keeps up to 10 log files.

### `WALLET_PATH`

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

Default:

```ini
WALLET_PATH = "./wallets"
```

### `WALLET_NAME`

Name of the encrypted wallet file to load at startup. If the wallet file does not exist, the node creates it the first time it starts and asks for a wallet encryption key.

Default:

```ini
WALLET_NAME = "contractless.wallet"
```

## `[Settings]`

### `LOG_LEVEL`

Runtime log filter.

Default:

```ini
LOG_LEVEL = "info"
```

Log levels are minimum severity filters, not exact categories. For example, `warn` means "write warnings and errors," not "write only warning lines."

Common choices:

| Value | What It Writes |
| --- | --- |
| `error` | Errors only |
| `warn` | Warnings and errors |
| `info` | Info, warnings, and errors |
| `off` | Disables log output |

Normal public nodes should use `info`.

The node writes logs to files under `LOG_PATH`; it does not use `LOG_LEVEL` to print normal runtime logs into the terminal.

### `PUBLIC_IP`

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

Default placeholder:

```ini
PUBLIC_IP = "your.public.ip.address"
```

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. Peers reject private, loopback, and unroutable public identities for public network operation.

### `LISTEN_IP`

Local bind address used by the RPC server.

Default:

```ini
LISTEN_IP = "0.0.0.0"
```

Use `0.0.0.0` to listen on all local interfaces. This is usually correct for public nodes, VPS nodes, and nodes behind NAT or router port forwarding.

This value is local bind configuration and is not announced as the node identity. 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.

Default:

```ini
RPC_PORT = "50055"
```

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.

Default:

```ini
TESTNET_RPC_PORT = "50050"
```

Public testnet nodes must allow inbound traffic to this port. This is the public Contractless port peers use to connect to your node.

Do not confuse this with PostgreSQL port `5432`. The Contractless RPC port may be public; the PostgreSQL port should not be public.

### `INCOMING_CONNECTIONS`

Maximum number of incoming peer connections allowed by the node.

Default:

```ini
INCOMING_CONNECTIONS = "100"
```

If the limit is reached, new incoming peers are rejected during handshake. Public nodes usually want this higher than a private test node, as long as the machine has enough network and memory capacity.

### `OUTGOING_CONNECTIONS`

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

Default:

```ini
OUTGOING_CONNECTIONS = "10"
```

Outgoing peers are the nodes your node actively connects to. Once a node joins the network, it can use the network map to fill outgoing connections up to this limit.

### `VALIDATOR`

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

Default:

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

Use validator mode for non-mining infrastructure nodes:

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

Mining nodes should keep this set to `false`.

### `THREADS`

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

Default:

```ini
THREADS = "8"
```

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

### `STORAGE_LOOKUP_FEE_PER_BYTE`

Fee charged by this node for paid storage lookups, in decimal CLTC/CLC per byte returned.

Default:

```ini
STORAGE_LOOKUP_FEE_PER_BYTE = "0.0001"
```

Data storage transactions let users store app data on chain. Public RPC nodes can serve lookups for that data. This setting lets a node operator charge for storage lookup bandwidth and processing.

Examples:

```ini
STORAGE_LOOKUP_FEE_PER_BYTE = "0.0001"
```

Charge `0.0001` CLTC/CLC per byte returned.

The lookup tool asks the node for the byte count and total lookup cost before payment. If the requester accepts, the lookup payment is made as a normal transfer transaction to the node's wallet, plus the normal transfer transaction fee.

When the requester is the same wallet as the node operator's wallet, the node verifies the signed lookup request and returns the data without broadcasting a payment transaction. Node operators do not need to set this value to `0` for their own local lookups to be free.

Node operators can set this to `0` during testing or raise it if they are serving dapp data to external users.

## `[Piggyback]`

Piggyback entries are startup peers. The node tries these peers when it first starts so it can join the network and learn the current network map.

Default:

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

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

These values are intentionally mostly self-explanatory. 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.

PostgreSQL should not be publicly exposed. In normal node setups, `host = 127.0.0.1` is the correct value.

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