2019-08-23 20:53:00 +02:00
---
2021-05-26 14:02:19 -05:00
title: Application Configuration
id: configuration
2019-08-23 20:53:00 +02:00
---
Bitcoin-S uses [HOCON ](https://github.com/lightbend/config/blob/master/HOCON.md )
2021-04-07 08:13:43 -05:00
to configure various parts of the application the library offers. HOCON is a superset of JSON, that is, all valid JSON
is valid HOCON.
2019-08-23 20:53:00 +02:00
All configuration for Bitcoin-S is under the `bitcoin-s` key.
2021-04-07 08:13:43 -05:00
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.
2019-08-23 20:53:00 +02:00
The resolved configuration gets parsed by
2020-12-29 14:34:37 -06:00
[`AppConfig` ](/api/org/bitcoins/db/AppConfig ).
2021-04-07 08:13:43 -05:00
`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:
2019-08-23 20:53:00 +02:00
```scala mdoc:compile-only
import org.bitcoins.wallet.config.WalletAppConfig
import com.typesafe.config.ConfigFactory
import java.nio.file.Paths
import scala.util.Properties
2020-04-25 11:28:58 -05:00
import scala.concurrent.ExecutionContext.Implicits.global
2019-08-23 20:53:00 +02:00
// reads $HOME/.bitcoin-s/
2020-08-14 08:53:07 -05:00
val defaultConfig = WalletAppConfig.fromDefaultDatadir()
2019-08-23 20:53:00 +02:00
// reads a custom data directory
val customDirectory = Paths.get(Properties.userHome, "custom-bitcoin-s-directory")
2020-08-14 08:53:07 -05:00
val configFromCustomDatadir = WalletAppConfig(customDirectory)
2019-08-23 20:53:00 +02:00
// reads a custom data directory and overrides the network to be testnet3
val customOverride = ConfigFactory.parseString("bitcoin-s.network = testnet3")
2020-08-14 08:53:07 -05:00
val configFromCustomDirAndOverride = WalletAppConfig(customDirectory, customOverride)
2019-08-23 20:53:00 +02:00
```
2021-04-07 08:13:43 -05:00
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.
2019-08-23 20:53:00 +02:00
2020-08-01 15:43:51 -05:00
## Command Line Options
There are a few command line options available that take precedence over configuration file.
- `--datadir <directory>`
2021-04-07 08:13:43 -05:00
`datadir` sets the data directory instead of using the default `$HOME/.bitcoin-s`
2020-08-01 15:43:51 -05:00
2020-12-22 07:25:50 -06:00
- `--rpcbind <ip>`
2021-04-07 08:13:43 -05:00
`rpcbind` sets the interface the rpc server binds to instead of using the default `127.0.0.1`
2020-12-22 07:25:50 -06:00
2020-08-01 15:43:51 -05:00
- `--rpcport <port>`
2021-04-07 08:13:43 -05:00
`rpcport` sets the port the rpc server binds to instead of using the default `9999`
2020-08-01 15:43:51 -05:00
- `--force-recalc-chainwork`
2021-04-07 08:13:43 -05:00
`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.
2020-11-17 13:37:48 -06:00
- `-Dlogback.configurationFile=/path/to/config.xml`
2021-04-07 08:13:43 -05:00
You can set a custom logback configuration. If you need help creating a custom logback file you can
read [the logback configuration documentation ](http://logback.qos.ch/manual/configuration.html ).
2020-08-01 15:43:51 -05:00
2019-08-23 20:53:00 +02:00
## Internal configuration
2021-04-07 08:13:43 -05:00
Database connections are also configured by using HOCON. This is done
in [`reference.conf` ](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/resources/reference.conf )
inside the `db-commons` module. The options exposed here are **not** intended to be used by users of Bitcoin-S, and are
internal only.
2020-01-27 07:04:53 -06:00
2020-03-04 09:40:50 -06:00
## Database Migrations
2021-04-07 08:13:43 -05:00
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
2020-03-04 09:40:50 -06:00
the path `chain/src/main/resources/chaindb/migration/V1__chain_db_baseline.sql` .
2021-04-07 08:13:43 -05:00
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.start()` ](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49 )
method.
2020-03-04 09:40:50 -06:00
These migrations are setup so that project's databases and migrations are independent of each other. Therefore if you
2021-04-07 08:13:43 -05:00
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
2020-08-27 14:11:24 -05:00
[`AppConfig.start()` ](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49 )
2020-03-04 09:40:50 -06:00
to ensure the entire module is initialized correctly.
2020-01-27 07:04:53 -06:00
## Example Configuration File
2021-04-07 08:13:43 -05:00
2020-01-27 07:04:53 -06:00
```$xslt
bitcoin-s {
datadir = ${HOME}/.bitcoin-s
2020-09-25 12:29:13 -05:00
network = regtest # regtest, testnet3, mainnet, signet
2021-01-28 09:44:03 -06:00
dbDefault = {
dataSourceClass = slick.jdbc.DatabaseUrlDataSource
profile = "slick.jdbc.SQLiteProfile$"
db {
# for information on parameters available here see
# https://scala-slick.org/doc/3.3.1/api/index.html#slick .jdbc.JdbcBackend$DatabaseFactoryDef@forConfig (String,Config,Driver,ClassLoader):Database
path = ${bitcoin-s.datadir}/${bitcoin-s.network}/
driver = org.sqlite.JDBC
user = ""
password = ""
host = localhost
port = 5432
# this needs to be set to 1 for SQLITE as it does not support concurrent database operations
# see: https://github.com/bitcoin-s/bitcoin-s/pull/1840
numThreads = 1
queueSize=5000
connectionPool = "HikariCP"
registerMbeans = true
}
hikari-logging = false
2021-04-10 13:51:31 -05:00
hikari-logging-interval = 10 minute
2021-01-28 09:44:03 -06:00
}
2020-09-30 07:36:23 -05:00
bitcoind-rpc {
2020-10-06 13:40:24 -05:00
# bitcoind rpc username
rpcuser = user
# bitcoind rpc password
2021-08-17 21:16:07 +05:30
# If your password contains the characters '$','{', '}', '[', ']', ':', '=', ',', '+', '#', '`', '^', '?', '!', '@', '*', '& ', whitespace
# or the string "//", enclose it in double quotes
# rpcpassword = "password=" if the original password is password=, rpcpassword = "passwo//rd" if the original password is passwo//rd etc.
# If it contains '\' or '"', escape it with '\'
# rpcpassword = "pass\\word" if the original password is pass\word, rpcpassword = "pass\"word" if the original password is pass"word
2020-10-06 13:40:24 -05:00
rpcpassword = password
2020-09-30 07:36:23 -05:00
# Binary location of bitcoind
binary = ${HOME}/.bitcoin-s/binaries/bitcoind/bitcoin-0.20.1/bin/bitcoind
# bitcoind datadir
datadir = ${HOME}/.bitcoin
# bitcoind network binding
bind = localhost
# bitcoind p2p port
port = 8333
# bitcoind rpc binding
rpcbind = localhost
# bitcoind rpc port
rpcport = 8332
2021-04-13 14:56:28 -05:00
# bitcoind zmq raw tx
zmqpubrawtx = "tcp://127.0.0.1:28332"
# bitcoind zmq raw block
zmqpubrawblock = "tcp://127.0.0.1:28333"
# bitcoind zmq hash tx
zmqpubhashtx = "tcp://127.0.0.1:28330"
# bitcoind zmq raw block
zmqpubhashblock = "tcp://127.0.0.1:28331"
2021-08-17 21:16:07 +05:30
#If you have a bitcoind instance that is running remotely on another machine, you should set it to true
isRemote = false
2020-09-30 07:36:23 -05:00
}
2020-01-27 07:04:53 -06:00
node {
2020-10-06 13:40:24 -05:00
mode = neutrino # neutrino, spv, bitcoind
2020-01-27 07:04:53 -06:00
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.
2021-01-28 09:44:03 -06:00
hikari-logging = true
2021-04-10 13:51:31 -05:00
hikari-logging-interval = 10 minute
2021-07-19 20:29:43 +05:30
# whether to have p2p peers relay us unconfirmed txs
relay = false
2020-01-27 07:04:53 -06:00
}
2021-07-13 12:27:24 -07:00
proxy {
# You can configure SOCKS5 proxy to use Tor for outgoing connections
enabled = false
2021-08-02 18:15:56 -05:00
socks5 = "127.0.0.1:9050"
}
tor {
# You can enable Tor for incoming connections
enabled = false
2021-08-04 07:06:19 -05:00
control = "127.0.0.1:9051"
2021-08-26 11:02:49 -07:00
# Tor daemon can be provided by the node operator.
# If this parameter set to true, bitcoin-s will connect the provided Tor daemon.
# Otherwise bitcoin-s will start its own pre-packaged daemon.
provided = false
# This parameter allows to use random port numbers for pre-packaged Tor daemon,
# which is useful if another Tor daemon instance already bound SOCKS5 and control ports.
# In this case bitcoin-s.tor.control and bitcoin-s.proxy.socks5
# addresses will be automatically changed to "localhost:< random port > "
use-random-ports = true
2021-08-02 18:15:56 -05:00
# The password used to arrive at the HashedControlPassword for the control port.
# If provided, the HASHEDPASSWORD authentication method will be used instead of
# the SAFECOOKIE one.
# password = securePassword
# The path to the private key of the onion service being created
# privateKeyPath = /path/to/priv/key
2021-07-13 12:27:24 -07:00
}
2020-01-27 07:04:53 -06:00
chain {
2020-07-31 10:43:04 -05:00
force-recalc-chainwork = false
2020-01-27 07:04:53 -06:00
neutrino {
2020-08-24 06:30:16 -05:00
filter-header-batch-size.default = 2000
2020-04-03 17:36:29 -05:00
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.
2021-01-30 14:56:47 -06:00
filter-batch-size = 1000
2020-01-27 07:04:53 -06:00
}
2021-01-28 09:44:03 -06:00
hikari-logging = true
2021-04-10 13:51:31 -05:00
hikari-logging-interval = 10 minute
2020-01-27 07:04:53 -06:00
}
# settings for wallet module
wallet {
2020-12-16 17:27:56 -06:00
# You can have multiple wallets by setting a different
# wallet name for each of them. They will each have
# their own unique seed and database or schema,
# depending on the database driver.
# The wallet name can contain letters, numbers, and underscores '_'.
# walletName = MyWallet0
2021-01-21 16:27:46 -06:00
defaultAccountType = segwit # legacy, segwit, nested-segwit
2020-01-27 07:04:53 -06:00
bloomFalsePositiveRate = 0.0001 # percentage
addressGapLimit = 20
discoveryBatchSize = 100
2020-04-08 16:51:17 -05:00
requiredConfirmations = 6
2020-04-10 14:19:39 -05:00
# 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
2021-01-28 09:44:03 -06:00
2021-04-07 08:13:43 -05:00
# How often the wallet will rebroadcast unconfirmed transactions
rebroadcastFrequency = 4 hours
2021-01-28 09:44:03 -06:00
hikari-logging = true
2021-04-10 13:51:31 -05:00
hikari-logging-interval = 10 minute
2020-04-10 14:19:39 -05:00
}
2020-05-04 19:09:32 -05:00
2020-11-19 06:23:26 -06:00
keymanager {
2020-11-11 12:18:02 -06:00
# You can optionally set a BIP 39 password
# bip39password = "changeMe"
# Password that your seed is encrypted with
2021-01-29 10:08:02 -06:00
aesPassword = changeMe
2021-09-18 09:49:11 -05:00
# At least 16 bytes of entropy encoded in hex
# This will be used as the seed for any
# project that is dependent on the keymanager
entropy = ""
2020-11-11 12:18:02 -06:00
}
2020-11-03 09:06:18 -06:00
# Bitcoin-S provides manny different fee providers
# You can configure your server to use any of them
# Below is some examples of different options
fee-provider {
# name = mempoolspace # Uses mempool.space's api
# The target is optional for mempool.space
# It refers to the expected number of blocks until confirmation
# target = 6
# name = bitcoinerlive # Uses bitcoiner.live's api
# The target is optional for Bitcoiner Live
# It refers to the expected number of blocks until confirmation
# target = 6
# name = bitgo # Uses BitGo's api
# The target is optional for BitGo
# It refers to the expected number of blocks until confirmation
# target = 6
# name = constant # A constant fee rate in sats/vbyte
# target = 1 # Will always use 1 sat/vbyte
}
2021-08-02 18:15:56 -05:00
dlcnode {
# The address we are listening on for incoming connections for DLCs
# Binding to 0.0.0.0 makes us listen to all incoming connections
listen = "0.0.0.0:2862"
}
2020-05-04 19:09:32 -05:00
server {
# The port we bind our rpc server on
rpcport = 9999
2020-12-22 07:25:50 -06:00
# The ip address we bind our server too
rpcbind = "127.0.0.1"
2020-05-04 19:09:32 -05:00
}
2021-01-29 11:36:39 -06:00
oracle {
2021-02-13 13:59:16 -06:00
# The port we bind our rpc server on
2021-02-16 16:43:12 -06:00
rpcport = 9998
2021-02-13 13:59:16 -06:00
# The ip address we bind our server too
rpcbind = "127.0.0.1"
2021-01-29 11:36:39 -06:00
hikari-logging = true
2021-04-10 13:51:31 -05:00
hikari-logging-interval = 10 minute
2021-02-18 12:44:48 -06:00
db {
path = ${bitcoin-s.datadir}/oracle/
}
2021-01-29 11:36:39 -06:00
}
2021-07-19 09:55:36 -05:00
testkit {
pg {
#enabled postgres backend database for all test cases
enabled = false
}
}
2020-01-27 07:04:53 -06:00
}
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
}
2020-11-23 16:03:13 -06:00
server {
# The amount of time until a request times out on the server
# If you have a large payload this may need to be bumped
# https://doc.akka.io/docs/akka-http/current/common/timeouts.html#request -timeout
request-timeout = 10s
}
2020-01-27 07:04:53 -06:00
}
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
}
}
}
2020-06-02 14:37:48 -07:00
```
2020-06-03 06:15:33 -05:00
## Database configuration
2020-06-02 14:37:48 -07:00
2021-04-07 08:13:43 -05:00
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.
2020-06-02 14:37:48 -07:00
2021-04-07 08:13:43 -05:00
`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:
2020-06-02 14:37:48 -07:00
```$xslt
bitcoin-s {
common {
profile = "slick.jdbc.PostgresProfile$"
db {
2020-08-26 12:20:18 -07:00
driver = org.postgresql.Driver
2020-12-16 17:27:56 -06:00
# these 3 options will result into a jdbc url of
# "jdbc:postgresql://localhost:5432/database"
name = database
host = localhost
port = 5432
2020-10-13 10:02:02 -05:00
user = "user"
2020-06-02 14:37:48 -07:00
password = "topsecret"
2020-08-26 12:20:18 -07:00
numThreads = 5
2021-01-28 09:44:03 -06:00
# http://scala-slick.org/doc/3.3.3/database.html
connectionPool = "HikariCP"
registerMbeans = true
2020-06-02 14:37:48 -07:00
}
}
2020-08-26 12:20:18 -07:00
chain.profile = ${bitcoin-s.common.profile}
chain.db = ${bitcoin-s.common.db}
2021-01-28 09:44:03 -06:00
chain.db.poolName = "chain-connection-pool"
2020-08-26 12:20:18 -07:00
node.profile = ${bitcoin-s.common.profile}
node.db = ${bitcoin-s.common.db}
2021-01-28 09:44:03 -06:00
node.db.poolName = "node-connection-pool"
2020-08-26 12:20:18 -07:00
wallet.profile = ${bitcoin-s.common.profile}
wallet.db = ${bitcoin-s.common.db}
2021-01-28 09:44:03 -06:00
wallet.db.poolName = "wallet-connection-pool"
2020-11-17 12:49:12 -06:00
oracle.profile = ${bitcoin-s.common.profile}
oracle.db = ${bitcoin-s.common.db}
2021-01-28 09:44:03 -06:00
oracle.db.poolName = "oracle-connection-pool"
2020-06-02 14:37:48 -07:00
}
```
2020-08-26 12:20:18 -07:00
The database driver will create a separate SQL namespace for each sub-project: `chain` , `node` and `wallet` .
2021-04-07 08:13:43 -05:00
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:
2020-06-02 14:37:48 -07:00
```$xslt
bitcoin-s {
chain {
profile = "slick.jdbc.PostgresProfile$"
db {
2020-08-26 12:20:18 -07:00
driver = org.postgresql.Driver
2020-12-16 17:27:56 -06:00
name = chaindb
host = localhost
port = 5432
2020-10-13 10:02:02 -05:00
user = "user"
2020-06-02 14:37:48 -07:00
password = "topsecret"
}
}
wallet {
profile = "slick.jdbc.PostgresProfile$"
db {
2020-08-26 12:20:18 -07:00
driver = org.postgresql.Driver
2020-12-16 17:27:56 -06:00
name = walletdb
host = localhost
port = 5432
2020-10-13 10:02:02 -05:00
user = "user"
2020-06-02 14:37:48 -07:00
password = "topsecret"
}
}
}
2020-06-03 06:15:33 -05:00
```