contractless/Contractless
contractless
/
Contractless
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Contractless/docs/SETTINGS.md

11 KiB
Raw Blame History

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:

/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:

[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:

/etc/contractless/settings.ini

then:

BLOCK_PATH = "./blocks"

resolves under:

/etc/contractless/blocks

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

Example:

BLOCK_PATH = "./blocks"

Testnet stores blocks under:

./blocks/testnet

Mainnet stores blocks under:

./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:

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

Testnet loads:

./wallets/testnet/contractless.wallet

Mainnet loads:

./wallets/mainnet/contractless.wallet

Windows Paths

Windows accepts forward slashes in paths, and that is the clearest format for settings.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:

BLOCK_PATH = "C:\Contractless\blocks"

Avoid:

BLOCK_PATH = "C:\Contractless\blocks\"

If you want a trailing separator, use forward slashes:

BLOCK_PATH = "C:/Contractless/blocks/"

[Paths]

BLOCK_PATH

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

Default:

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:

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:

DB_PATH = "./state"

BALANCE_SHEET

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

Default:

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:

LOG_PATH = "./logs"

Testnet writes logs under:

./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:

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:

WALLET_NAME = "contractless.wallet"

[Settings]

LOG_LEVEL

Runtime log filter.

Default:

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:

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:

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:

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:

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:

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:

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:

VALIDATOR = "false"

Use validator mode for non-mining infrastructure nodes:

VALIDATOR = "true"

Mining nodes should keep this set to false.

THREADS

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

Default:

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:

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:

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:

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

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

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