---
id: configuration
title: Application Configuration
---

Bitcoin-S uses [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md)
to configure various parts of the application the library offers. HOCON is a
superset of JSON, that is, all valid JSON is valid HOCON.

All configuration for Bitcoin-S is under the `bitcoin-s` key.

If you have a file `application.conf` anywhere on your classpath when using
bitcoin-s, the values there take precedence over the ones found in our
`reference.conf`. We also look for the file `bitcoin-s.conf` in the current
Bitcoin-S data directory.

The resolved configuration gets parsed by
[`AppConfig`](../../db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala).
`AppConfig` is an abstract class that's implemented by corresponding case
classes in the `wallet`, `chain` and `node` projects. Here's some examples of how to
construct a wallet configuration:

```scala mdoc:compile-only
import org.bitcoins.wallet.config.WalletAppConfig
import com.typesafe.config.ConfigFactory
import java.nio.file.Paths
import scala.util.Properties
import scala.concurrent.ExecutionContext.Implicits.global

// reads $HOME/.bitcoin-s/
val defaultConfig = WalletAppConfig.fromDefaultDatadir(false)


// reads a custom data directory
val customDirectory = Paths.get(Properties.userHome, "custom-bitcoin-s-directory")
val configFromCustomDatadir = WalletAppConfig(customDirectory, false)

// reads a custom data directory and overrides the network to be testnet3
val customOverride = ConfigFactory.parseString("bitcoin-s.network = testnet3")
val configFromCustomDirAndOverride = WalletAppConfig(customDirectory, false, customOverride)
```

You can pass as many `com.typesafe.config.Config`s as you'd like. If any
keys appear multiple times the last one encountered takes precedence.

## Command Line Options

There are a few command line options available that take precedence over configuration file.

- `--datadir <directory>`

     `datadir` sets the data directory instead of using the default `$HOME/.bitcoin-s`

- `--rpcport <port>`

    `rpcport` sets the port the rpc server binds to instead of using the default `9999`

- `--force-recalc-chainwork`

    `force-recalc-chainwork` will force a recalculation of the entire chain's chain work, this
    can be useful if there is an incompatible migration or if it got out of sync.

## Internal configuration

Database connections are also configured by using HOCON. This is done in
[`db.conf`](../../db-commons/src/main/resources/db.conf). The options
exposed here are **not** intended to
be used by users of Bitcoin-S, and are internal only.

## Database Migrations

All of our modules that require databases now have database migrations. The tool we use for these migrations is 
called [flyway](https://flywaydb.org/). To find your projects migraitons, you need to look inside of the 
`[project-name]/src/main/resources/[database-name]/migration/`. For example, the chain projects migrations live under 
the path `chain/src/main/resources/chaindb/migration/V1__chain_db_baseline.sql`.

Migrations can be executed by calling the [`DbManagement.migrate()`](https://github.com/bitcoin-s/bitcoin-s/blob/e387d075b0ff2e0a0fec15788fcb48e4ddc4d9d5/db-commons/src/main/scala/org/bitcoins/db/DbManagement.scala#L92) 
method. Migrations are applied by default on server startup, via the [`AppConfig.initialize()`](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49) 
method. 

These migrations are setup so that project's databases and migrations are independent of each other. Therefore if you
want to use the `bitcoin-s-chain` project, but not the `bitcoin-s-wallet` project, wallet migrations are not applied. 
It should be noted if you are using a module as a library, you are responsible for configuring the database via 
[slick's configuration](https://scala-slick.org/doc/3.3.1/database.html#using-typesafe-config) and calling 
[`AppConfig.initialize()`](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49) 
to ensure the entire module is initialized correctly.

## Example Configuration File
```$xslt
bitcoin-s {
    datadir = ${HOME}/.bitcoin-s
    network = regtest # regtest, testnet3, mainnet

    logging {
        # Ignore bitcoin-s logging config and use a logback config
        logback = false

        level = WARN # trace, debug, info, warn, error, off

        # You can also tune specific module loggers.
        # They each take the same levels as above.
        # If they are commented out (as they are
        # by default), `logging.level` gets used
        # instead. 
        # The available loggers are: 

        # incoming and outgoing P2P messages
        # p2p = info

        # verification of block headers, merkle trees
        # chain-verification = info

        # generation of addresses, signing of TXs
        # key-handling = info

        # wallet operations not related to key management
        # wallet = info

        # HTTP RPC server
        # http = info

        # Database interactions
        # database = info

        # whether or not to write to the log file
        disable-file = false

        # whether or not to log to stdout 
        disable-console = false
    }

    node {
        mode = neutrino # neutrino, spv

        peers = [] # a list of peer addresses in form "hostname:portnumber"
        # (e.g. "neutrino.testnet3.suredbits.com:18333")
        # Port number is optional, the default value is 8333 for mainnet,
        # 18333 for testnet and 18444 for regtest.
    }

    chain {
        force-recalc-chainwork = false
        neutrino {
            filter-header-batch-size = 2000
            filter-header-batch-size.regtest = 10
            # You can set a network specific filter-header-batch-size
            # by adding a trailing `.networkId` (main, test, regtest)
            # It is recommended to keep the main and test batch size high
            # to keep the sync time fast, however, for regtest it should be small
            # so it does not exceed the chain size.

            filter-batch-size = 100
        }
    }

    # settings for wallet module
    wallet {
        defaultAccountType = legacy # legacy, segwit, nested-segwit

        bloomFalsePositiveRate = 0.0001 # percentage

        addressGapLimit = 20

        discoveryBatchSize = 100

        requiredConfirmations = 6

        # How big the address queue size is before we throw an exception
        # because of an overflow
        addressQueueSize = 10

        # How long we attempt to generate an address for
        # before we timeout
        addressQueueTimeout = 5 seconds

   }

    server {
        # The port we bind our rpc server on
        rpcport = 9999
    }
}


akka {
    loglevel = "OFF"
    stdout-loglevel = "OFF"
    http {
        client {
            # The time after which an idle connection will be automatically closed.
            # Set to `infinite` to completely disable idle connection timeouts.

            # some requests potentially take a long time, like generate and prune
            idle-timeout = 5 minutes
        }
    }


    actor {
        debug {
            # enable DEBUG logging of all AutoReceiveMessages (Kill, PoisonPill etc.)
            autoreceive= off
            # enable function of LoggingReceive, which is to log any received message at
            # DEBUG level
            receive = on
            # enable DEBUG logging of unhandled messages
            unhandled = off

            # enable DEBUG logging of actor lifecycle changes
            lifecycle = off

            event-stream=off
        }
    }
}
```

## Database configuration

By default, bitcoin-s uses Sqlite to store its data. 
It creates three Sqlite databases in `~/.bitcoin-s/${network}`: `chain.sqlite` for `chain` project, 
`node.sqlite` for `node` project and `wallet.sqlite` the wallet. This is the default configuration, 
it doesn't require additional changes in the config file. 

`bitcoin-s` also supports PostgreSQL as a database backend. In order to use a 
PostgreSQL database for all project you need to add following into your config file: 

```$xslt
bitcoin-s {
    common {
        profile = "slick.jdbc.PostgresProfile$"
        db {
            url = "jdbc:postgresql://localhost:5432/database"
            driver = "org.postgresql.Driver"
            username = "user"
            password = "topsecret"
        }
    }
}
```

Also you can use mix databases and drivers in one configuration. For example,
This configuration file enables Sqlite for `node` project (it's default, so its configuration 
is omitted), and `walletdb` and `chaindb` PostgreSQL databases for `wallet` and `chain` projects:

```$xslt
bitcoin-s {
    chain {
        profile = "slick.jdbc.PostgresProfile$"
        db {
            url = "jdbc:postgresql://localhost:5432/chaindb"
            driver = "org.postgresql.Driver"
            username = "user"
            password = "topsecret"
        }
    }
    wallet {
        profile = "slick.jdbc.PostgresProfile$"
        db {
            url = "jdbc:postgresql://localhost:5432/walletdb"
            driver = "org.postgresql.Driver"
            username = "user"
            password = "topsecret"
        }
    }
}
```