Update docs/SETTINGS.md

docs/SETTINGS.md

@@ -1,6 +1,6 @@
 # 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.
+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:
 
@@ -10,13 +10,81 @@ The node loads `settings.ini` in this order:
 4. `settings.ini` beside the executable
 5. platform fallback path
 
-On Linux, the fallback path is `/etc/contractless/settings.ini`.
+On Linux, the fallback path is:
 
-## `[Paths]`
+```text
+/etc/contractless/settings.ini
+```
 
-### `BLOCK_PATH`
+On Windows, there is no `/etc` fallback. If no explicit config is provided, Windows checks the current working directory and then the executable directory.
 
-Base folder where block files are stored. The active network name is appended automatically.
+## 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:
 
@@ -24,29 +92,28 @@ Example:
 BLOCK_PATH = "./blocks"
 ```
 
-Testnet will store blocks under:
+Testnet stores blocks under:
 
 ```text
 ./blocks/testnet
 ```
 
-Mainnet will store blocks under:
+Mainnet stores blocks under:
 
 ```text
 ./blocks/mainnet
 ```
 
-### `TORRENT_PATH`
+The same automatic network folder is added to:
 
-Base folder where torrent metadata, staged torrents and torrent-related files are stored. The active network name is appended automatically.
+- `BLOCK_PATH`
+- `TORRENT_PATH`
+- `DB_PATH`
+- `BALANCE_SHEET`
+- `LOG_PATH`
+- `WALLET_PATH`
 
-### `DB_PATH`
+For `WALLET_PATH`, the node appends both the network folder and `WALLET_NAME`.
-
-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:
 
@@ -55,113 +122,266 @@ WALLET_PATH = "./wallets"
 WALLET_NAME = "contractless.wallet"
 ```
 
-Testnet will load the wallet from:
+Testnet loads:
 
 ```text
 ./wallets/testnet/contractless.wallet
 ```
 
-### `WALLET_NAME`
+Mainnet loads:
 
-Name of the encrypted wallet file to load at startup.
+```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.
 
-## `[Settings]`
+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.
 
-Example:
+Default:
 
 ```ini
 LOG_PATH = "./logs"
 ```
 
-Testnet will write logs under:
+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.
 
-Valid common values:
+Default:
 
-- `info`: show info, warning and error logs.
+```ini
-- `warn`: show warning and error logs.
+LOG_LEVEL = "info"
-- `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.
+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. It is validated against forbidden private or unroutable ranges before the node is accepted by peers.
+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.
 
-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.
+Default:
 
-This value is never announced to peers. It may be private, loopback or wildcard because it only controls where the local process listens.
+```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.
 
-Public testnet nodes must allow inbound traffic to this port.
+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.
 
-This should be greater than `0`. A recommended value is `50`.
+Default:
 
-If the limit is reached, new incoming peers are rejected during handshake.
+```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 discover and maintain.
+Maximum number of outgoing peer connections the node tries to maintain.
 
-This should be greater than `0`. A recommended value is `10`.
+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.
+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:
+Default:
-
-```ini
-VALIDATOR = "true"
-```
-
-Mining nodes should use:
 
 ```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:
@@ -172,21 +392,46 @@ Allowed values:
 
 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.
+
+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 discover other nodes.
+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"
+PIGGYBACK_1 = "contractless.dev:50050"
-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 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.
+Piggyback entries should resolve to public, routable peers. Private, loopback, and invalid addresses are filtered before startup connections begin.
 
 ## `[Postgres-Testnet]`
 
@@ -201,7 +446,9 @@ 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.
+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]`