# Configuration

`cuprated` reads its configuration file `Cuprated.toml` on startup - this is in the TOML file format.

`cuprated` will try to look for `Cuprated.toml` in the follow places, in order:

- PATH specified in `--config-file`
- Current directory: `./Cuprated.toml`
- OS specific directory

## `Cuprated.toml`

This is the default configuration file `cuprated` creates and uses.

If `cuprated` is started with no `--options`, then the configuration used will be equivalent to this config file.

> Some values may be different for your exact system, generate the config with `cuprated --generate-config` to see the defaults for your system.

    ##     ____                      _
    ##    / ___|   _ _ __  _ __ __ _| |_ ___
    ##   | |  | | | | '_ \| '__/ _` | __/ _ \
    ##   | |__| |_| | |_) | | | (_| | ||  __/
    ##    \____\__,_| .__/|_|  \__,_|\__\___|
    ##              |_|
    ##
    ## All these config values can be set to
    ## their default by commenting them out with '#'.
    ##
    ## Some values are already commented out,
    ## to set the value remove the '#' at the start of the line.
    ##
    ## For more documentation, see: <https://user.cuprate.org>.

    ## The network cuprated should run on.
    ##
    ## Valid values | "Mainnet", "Testnet", "Stagenet"
    network = "Mainnet"
    ## Enable/disable fast sync.
    ##
    ## Fast sync skips verification of old blocks by
    ## comparing block hashes to a built-in hash file,
    ## disabling this will significantly increase sync time.
    ## New blocks are still fully validated.
    ##
    ## Type         | boolean
    ## Valid values | true, false
    fast_sync = true

    ## Configuration for cuprated's stdout logging system.
    [tracing.stdout]
    ## The minimum log level for stdout.
    ##
    ## Levels below this one will not be shown.
    ## "error" is the highest level only showing errors,
    ## "trace" is the lowest showing as much as possible.
    ##
    ## Type         | Level
    ## Valid values | "error", "warn", "info", "debug", "trace"
    level = "info"

    ## Configuration for cuprated's file logging system.
    [tracing.file]
    ## The minimum log level for file logs.
    ##
    ## Levels below this one will not be shown.
    ## "error" is the highest level only showing errors,
    ## "trace" is the lowest showing as much as possible.
    ##
    ## Type         | Level
    ## Valid values | "error", "warn", "info", "debug", "trace"
    level = "debug"
    ## The maximum amount of log files to keep.
    ##
    ## Once this number is passed the oldest file will be deleted.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 0, 7, 200
    max_log_files = 7

    ## Configuration for cuprated's asynchronous runtime system, tokio.
    ##
    ## Tokio is used for network operations and the major services inside `cuprated`.
    [tokio]
    ## The amount of threads to spawn for the tokio thread-pool.
    ##
    ## Type         | Number
    ## Valid values | >= 1
    ## Examples     | 1, 8, 14
    #threads = 5

    ## Configuration for cuprated's thread-pool system, rayon.
    ##
    ## Rayon is used for CPU intensive tasks.
    [rayon]
    ## Type         | Number
    ## Valid values | >= 1
    ## Examples     | 1, 8, 14
    #threads = 5

    ## The clear-net P2P config.
    [p2p.clear_net]
    ## The IP address to bind and listen for connections on.
    ##
    ## Type     | IPv4/IPv6 address
    ## Examples | "0.0.0.0", "192.168.1.50", "::"
    listen_on = "0.0.0.0"
    ## The number of outbound connections to make and try keep.
    ##
    ## It's recommended to keep this value above 12.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 12, 32, 64, 100, 500
    #outbound_connections = 32
    ## The amount of extra connections to make if cuprated is under load.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 0, 12, 32, 64, 100, 500
    #extra_outbound_connections = 8
    ## The maximum amount of inbound connections to allow.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 0, 12, 32, 64, 100, 500
    #max_inbound_connections = 128
    ## The percent of connections that should be
    ## to peers that haven't connected to before.
    ##
    ## 0.0 is 0%.
    ## 1.0 is 100%.
    ##
    ## Type         | Floating point number
    ## Valid values | 0.0..1.0
    ## Examples     | 0.0, 0.5, 0.123, 0.999, 1.0
    #gray_peers_percent = 0.7
    ## The port to use to accept incoming P2P connections.
    ##
    ## Setting this to 0 will disable incoming P2P connections.
    ##
    ## Type         | Number
    ## Valid values | 0..65534
    ## Examples     | 18080, 9999, 5432
    p2p_port = 18080

    ## The address book config.
    [p2p.clear_net.address_book_config]
    ## The size of the white peer list.
    ##
    ## The white list holds peers that have been connected to before.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 1000, 500, 241
    max_white_list_length = 1000
    ## The size of the gray peer list.
    ##
    ## The gray peer list holds peers that have been
    ## told about but not connected to cuprated.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 1000, 500, 241
    max_gray_list_length = 5000
    ## The time period between address book saves.
    ##
    ## Type     | Duration
    ## Examples | { secs = 90, nanos = 0 }, { secs = 100, nano = 123 }
    peer_save_period = { secs = 90, nanos = 0 }

    ## Block downloader config.
    ##
    ## The block downloader handles downloading old blocks from peers when we are behind.
    [p2p.block_downloader]
    ## The size in bytes of the buffer between the block downloader
    ## and the place which is consuming the downloaded blocks (`cuprated`).
    ##
    ## This value is an absolute maximum,
    ## once this is reached the block downloader will pause.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 1_000_000_000, 5_500_000_000, 500_000_000
    #buffer_bytes = 1000000000
    ## The size of the in progress queue (in bytes)
    ## at which cuprated stops requesting more blocks.
    ##
    ## The value is _NOT_ an absolute maximum,
    ## the in-progress queue could get much larger.
    ## This value is only the value cuprated stops requesting more blocks,
    ## if cuprated still has requests in progress,
    ## it will still accept the response and add the blocks to the queue.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 500_000_000, 1_000_000_000,
    #in_progress_queue_bytes = 500000000
    ## The target size of a single batch of blocks (in bytes).
    ##
    ## This value must be below 100_000,000,
    ## it is not recommended to set it above 30_000_000.
    ##
    ## Type         | Number
    ## Valid values | 0..100_000,000
    #target_batch_bytes = 15000000
    ## The duration between checking the client pool for free peers.
    ##
    ## Type     | Duration
    ## Examples | { secs = 30, nanos = 0 }, { secs = 35, nano = 123 }
    check_client_pool_interval = { secs = 30, nanos = 0 }

    ## Configuration for persistent data storage.
    [storage]
    ## The amount of reader threads to spawn for the tx-pool and blockchain.
    ##
    ## The tx-pool and blockchain both share a single threadpool.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 1, 16, 10
    #reader_threads = 2

    ## The tx-pool config.
    [storage.txpool]
    ## The sync mode of the database.
    ##
    ## Using "Safe" makes the DB less likely to corrupt
    ## if there is an unexpected crash, although it will
    ## make DB writes much slower.
    ##
    ## Valid values | "Fast", "Safe"
    #sync_mode = "Fast"
    ## The maximum size of the tx-pool.
    ##
    ## Type         | Number
    ## Valid values | >= 0
    ## Examples     | 100_000_000, 50_000_000
    max_txpool_byte_size = 100000000

    ## The blockchain config.
    [storage.blockchain]
    ## The sync mode of the database.
    ##
    ## Using "Safe" makes the DB less likely to corrupt
    ## if there is an unexpected crash, although it will
    ## make DB writes much slower.
    ##
    ## Valid values | "Fast", "Safe"
    #sync_mode = "Fast"

    ## Configuration for the file-system.
    [fs]
    ## The data directory.
    ##
    ## This directory store the blockchain, transaction pool,
    ## log files, and any misc data files.
    ##
    ## The default directories for each OS:
    ##
    ## | OS      | Path                                                |
    ## |---------|-----------------------------------------------------|
    ## | Windows | "C:\Users\Alice\AppData\Roaming\Cuprate\"           |
    ## | macOS   | "/Users/Alice/Library/Application Support/Cuprate/" |
    ## | Linux   | "/home/alice/.local/share/cuprate/"                 |
    #data_directory = "/home/git/.local/share/cuprate"
    ## The cache directory.
    ##
    ## This directory store cache files.
    ## Although not recommended, this directory can be
    ## deleted without major disruption to cuprated.
    ##
    ## The default directories for each OS:
    ##
    ## | OS      | Path                                    |
    ## |---------|-----------------------------------------|
    ## | Windows | "C:\Users\Alice\AppData\Local\Cuprate\" |
    ## | macOS   | "/Users/Alice/Library/Caches/Cuprate/"  |
    ## | Linux   | "/home/alice/.cache/cuprate/"           |
    #cache_directory = "/home/git/.cache/cuprate"