469 lines
11 KiB
Markdown
469 lines
11 KiB
Markdown
# 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.
|