path: root/fulcrum.conf

# Fulcrum Sample Config File
#
# Feel free to edit this file (or a copy of it) and then pass it as a bare
# argument when starting Fulcrum, e.g.:
#
#     $  ./Fulcrum myconfig.conf
#
# The configuration file format for Fulcrum resembles that of bitcoind.conf in
# that it is a simple name = value style file format, with comments denoted by
# `#` characters. Configuration variables are case insensitive and Fulcrum
# completely ignores variable names that it does not understand.
#
# Boolean variables (such as 'debug' or 'syslog' below) may be specified as name
# = 1, name = true, name = false, name = off, etc, or without any '=' sign in
# which case they are interpreted as "true".
#
# Some (but not all) configuration variables below have corresponding command-
# line equivalents (such as -D/--datadir, for example). If a configuration
# parameter is specified both in the conf file as well as the CLI, the CLI arg
# takes precedence and overrides the corresponding conf file parameter. In this
# way, it's possible to override the conf file for a particular run of Fulcrum
# while still "inheriting" the rest of the config file. Say you wanted to test
# Fulcrum against a different daemon, you would then do:
#
#     $  ./Fulcrum myconfig.conf -b 192.168.1.23:45678
#
#
# What follows below are commented-out versions (in many cases set to their
# defaults) of all of the variables you can use to customize the operation of
# Fulcrum. Required parameters have been left uncommented and must be specified
# for Fulcrum to operate correctly.


# ------------------------------------------------------------------------------
# BASIC OPTIONS
#-------------------------------------------------------------------------------

# Database directory - 'datadir' - REQUIRED
#
# Specifies the directory where to store the database. Be sure the directory is
# on a drive that has 35+ GB of space for mainnet or ~8GB of space for testnet.
# If the directory does not exist, it will be created. It is recommended you use
# an SSD, but an HDD will work as well once synched, however synching will take
# much longer on an HDD.
#
# NOTE: Use native path separators: '/' on Unix, '\' on Windows.
#
datadir = /var/lib/fulcrum


# Bitcoin daemon RPC host:port - 'bitcoind' - REQUIRED
#
# Specifies a hostname:port for connecting to the bitcoind rpc service. This is
# a required option (along with rpcuser and rpcpassword below). This
# hostname:port would be the same as you specified in your bitcoin.conf file
# under `rpcbind=` and `rpcport=`.
#
bitcoind = 127.0.0.1:8332


# Bitcoin daemon RPC username - 'rpcuser' - REQUIRED
#
# Specifies the username to use for authenticating to bitcoind. This is a
# required option, along with 'bitcoind' and 'rpcpassword'. This option should
# be the same username you specified in your bitcoind.conf file under
# `rpcuser=`. For security, you may want to omit this option from the config
# file and use the RPCUSER environment variable instead (however, the config
# file or any -u/--rpcuser CLI args will take precedence, so if you do want to
# use the environment variable scheme, then be sure to comment-out the below
# line).
#
rpcuser = Bob_The_Banker


# Bitcoin daemon RPC password - 'rpcpassword' - REQUIRED
#
# Specifies the password to use for authenticating to bitcoind. This is a
# required option, along with 'bitcoind' and 'rpcuser'. This option should be
# the same password you specified in your bitcoind.conf file under
# `rpcpassword=`. For security, you may want to omit this option from the config
# file and use the RPCPASSWORD environment variable instead (however, the config
# file or any -p/--rpcpassword CLI args will take precedence, so if you do want
# to use the environment variable scheme, then be sure to comment-out the below
# line).
#
rpcpassword = hunter1


# Bitcoin daemon poll interval - 'polltime' - Default: 2.0 seconds
#
# The number of seconds for the bitcoind poll interval. Bitcoind is polled once
# every `polltime` seconds to detect mempool and blockchain changes. This value
# must be at least 0.5 and cannot exceed 30. If not specified, the default is
# 2.0 seconds.
#
#polltime = 2.0


# TCP bind - 'tcp' - DEFAULT: 0.0.0.0:50001
#
# Specifies the TCP interface:port to bind to for Electron Cash clients to
# connect to. Default is 0.0.0.0:50001. Typically on the Electron Cash network
# 50001 & 50002 are for mainnet TCP & SSL and 60001 & 60002 are for testnet TCP
# & SSL, respectively. If you wish to bind to multiple ports, you may specify
# this option multiple times, once for each interface:port combination.
#
# Note: At the present time, outside of Tor proxying, Electron Cash clients
# typically do not like to connect to non-SSL servers -- so using just TCP will
# lead to not very many clients using your server. SSL is highly recommended.
#
# You may specify either IPv4 or IPv6 interfaces.
#
#tcp = 0.0.0.0:50001


# SSL bind - 'ssl' - DEFAULT: disabled (no SSL bind port)
#
# Specifies the SSL interface:port to bind to for Electron Cash clients to
# connect to. Default is to not use SSL. Typically on the Electron Cash network
# 50001 & 50002 are for mainnet TCP & SSL and 60001 & 60002 are for testnet TCP
# & SSL, respectively. If you wish to bind to multiple ports, you may specify
# this option multiple times, once for each interface:port combination.
#
# If you enable SSL you must also specify the 'cert' and 'key' configuration
# parameters (see below).
#
# You may specify either IPv4 or IPv6 interfaces.
#
#ssl = 0.0.0.0:50002


# SSL certificate - 'cert' - DEFAULT: None (required for SSL)
#
# Specifes the SSL certificate to use for all SSL ports. The certificate must be
# in PEM format. (Self-signed certs are ok).
#
#cert = /path/to/server.crt


# SSL private key - 'key' - DEFAULT: None (required for SSL)
#
# Specifies the SSL private key to use for encryption. At the present time only
# RSA keys are supported, and the file must be in PEM format.
#
#key = /path/to/server.key


# HTTP stats bind - 'stats' - DEFAULT: None
#
# Specifies the listen address and port for the "stats" HTTP server. You may hit
# this endpoint with /stats in your browser, and it will serve you some
# JSON-encoded statistics. The /stats endpoint is intended as a convenient way
# to keep track of what your server is up to, how many clients are connected,
# what the load it is, etc. Do *NOT* expose this port to the public! It is for
# your admin use only! The default is to not start any "stats" HTTP servers
# unless you specify this option. This option may be specified more than once to
# bind to multiple ports and/or interfaces.
#
#stats = 127.0.0.1:8080


# Syslog mode - 'syslog' - DEFAULT: off (false)
#
# Syslog mode. If on Unix, use the syslog() facility to produce log messages
# (rather than writing to stdout). This option currently has no effect on
# Windows.
#
#syslog = false


# Debug mode - 'debug' - DEFAULT: off for Release builds, on for Debug builds
#
# Specifies that logging should produce extra verbose output, which may be
# useful for diagnostics. This option is the inverse of the 'quiet' option (see
# below). You may specify either 'debug' or 'quiet', but not both.
#
# This option may be specified multiple times. In that case, network 'trace'
# output will also be generated (this is extremely verbose output typically only
# used for development and/or protocol-level troubleshooting.)
#
#debug = false


# Quiet mode - 'quiet' - DEFAULT: on for Release builds, off for Debug builds
#
# Limits logging to the normal messages, without any extra verbose debug info.
# This option is the inverse of the 'debug' option and is the default on release
# builds. You may specify either 'debug' or 'quiet', but not both.
#
#quiet = true


# CheckDB at startup - 'checkdb' - DEFAULT: off (false)
#
# If enabled, database consistency will be checked thoroughly for sanity &
# integrity each time Fulcrum is (re)started. This may take anywhere from 30
# seconds up to a few minutes depending on your system. Under normal operation
# these checks are not necessary but are provided as a debugging tool in case
# you suspect your database files may be corrupt. This also may be specified on
# the CLI via the --checkdb or -C option for a one-time check.
#
#checkdb = false


# Donation address - 'donation'
# - DEFAULT: bitcoincash:qplw0d304x9fshz420lkvys2jxup38m9symky6k028
#
# The server donation address. This address is given to users when they select
# "Help -> Donate to server" from the Electron Cash GUI, and/or clients that
# invoke the "server.donation_address" RPC method. Additionally, it can also be
# used in the banner text file as the $DONATION_ADDRESS substitution variable
# (see the 'banner' conf variable below). No checks are done on the server side
# to ensure this is a valid Bitcoin Cash address, it is just relayed to clients
# verbatim as a text string (80 characters maximum).
#
# If unspecified, the default will be the developer's donation address.
#
#donation = bitcoincash:qplw0d304x9fshz420lkvys2jxup38m9symky6k028


# Server banner text file - 'banner'
# - DEFAULT: Send a static string "Connected to a Fulcruim xx.x server"
#
# The "banner" text file to send to clients when they request the server banner.
# Specify a file path to a server-readable UTF-8 encoded text file (maximum file
# lemgth: 16384 bytes). Typically Electron Cash clients ask for the server
# banner (via the "server.banner" RPC method) when they first connect to your
# server. They then display this text in the "Console" tab of the Electron Cash
# GUI. Some server admins get creative with this file and include ASCII or emoji
# art and other fancy features, while others choose to use the banner text to
# relay technical information about the server, or both.
#
# Banner text file variable substitution:
#
# The server banner text file supports variable substitutions. You may include
# the following special tokens (case sensitive) in your text file which will be
# interpreted and replaced with the appropriate text:
#
#       $SERVER_VERSION    -  Server software version number, short.
#                             e.g.: "1.0" or "1.2", etc.
#       $SERVER_SUBVERSION -  Server software version, long.
#                             e.g.: "Fulcrum 1.0"
#       $DAEMON_VERSION    -  BitcoinD version number, short.
#                             e.g.: "0.20.6" or "1.1.7"
#       $DAEMON_SUBVERSION -  BitcoinD daemon "subversion" useragent string.
#                             e.g.: "/Bitcoin ABC:0.20.6(EB32.0; Bobs_Server)/"
#       $DONATION_ADDRESS  -  The server donation address as configured (see the
#                             section on the 'donation' conf variable).
#
#banner = /path/to/banner.txt


#-------------------------------------------------------------------------------
# PEER DISCOCERY AND PUBLIC SERVER OPTIONS
#-------------------------------------------------------------------------------

# Public hostname - 'hostname' - DEFAULT: Local IP address on server
#
# The server's public hostname. This is the hostname that your server will
# announce to clients and to other servers engaged in peer discovery. It is very
# important that you set this option, since if it is not set, the default is to
# just report your local IP address to other servers and to clients. In most
# cases this default is incorrect if your server is behind a firewall. What's
# more, this text is used to identify your server in the Electron Cash GUI, so
# the default will look like a non-human-friendly IP address, which is most
# certainly not what you want. For best results, set this option to the public
# hostname of your server as others would connect to it on the internet,
# preferably this hostname also matches the hostname in your SSL certificate
# (this latter consideration is not required just recommended). You may also
# wish to set 'public_tcp_port' and 'public_ssl_port' as well (see those
# sections in this file).
#
#hostname = fulcrum.bobs-bank.co.uk


# Public TCP port - 'public_tcp_port' - DEFAULT: The first 'tcp' port configured
#
# The server's public TCP port. This, along with 'hostname' and
# 'public_ssl_port', is announced to clients and to other servers engaged in
# peer discovery. The default is to simply use the first TCP port specified in
# the server configuration (if any). If you are behind a firewall and doing some
# port remapping, then you definitely want to set this option. This should be
# the public TCP port as would be used by the rest of the internet to connect to
# your server via an unencrypted TCP connection (non-SSL). You may also set this
# option to 0 to disable reporting any TCP port.
#
#public_tcp_port = 50001


# Public SSL port - 'public_ssl_port' - DEFAULT: The first 'ssl' port configured
#
# The server's public SSL port. This, along with 'hostname' and
# 'public_ssl_port', is announced to clients and to other servers engaged in
# peer discovery. The default is to simply use the first SSL port specified in
# the server configuration (if any). If you are behind a firewall and doing some
# port remapping, then you definitely want to set this option. This should be
# the public SSL port as would be used by the rest of the internet to connect to
# your server via SSL. You may also set this option to 0 to disable reporting
# any SSL port.
#
#public_ssl_port = 50002


# Peer discovery - 'peering' - DEFAULT: true
#
# TODO: Description here
#
#peering = true


# Peering: announce self - 'announce' - DEFAULT: true if hostname and peering
#                                                are set, false otherwise
#
# TODO: Description here
#
#announce = false


#-------------------------------------------------------------------------------
# ADVANCED OPTIONS
#-------------------------------------------------------------------------------

# Max client connections per IP - 'max_clients_per_ip' - DEFAULT: 12
#
# The maximum number of simultaneous client connections allowed per originating
# IP address. This is a simple DoS control measure to prevent excessive
# connections from 1 computer on the internet. When a client attempts to exceed
# this per-IP limit, connections past the limit will be refused. This DoS
# control measure may backfire, however, if you anticipate many users arriving
# from behind the same NATed IP address. In practice, this rarely happens, but
# if you anticipate that to be the case, feel free to set this parameter higher.
#
# A value <= 0 or an empty value will disable this limit entirely.
#
#max_clients_per_ip = 12


# Exclude from per-IP limits = 'subnets_to_exclude_from_per_ip_limits'
# - DEFAULT: 127.0.0.1/32, ::1/128
#
# Specify a comma-delimited list of subnets to exclude from the per-IP limits
# (such as max_clients_per_ip). Clients connecting from one of these subnets
# will not be subjected to any per-IP limits. The default is for any clients
# connecting from localhost (this default is particularly useful if serving via
# Tor, where all clients come from localhost). Set this to the empty string to
# not have any excluded subnets, eg "subnets_to_exclude_from_per_ip_limits =".
#
# Examples: 10.10.2.0/24, 128.101.0.0/16, 123.45., 99.74.0.0/255.255.0.0, ...
#
#subnets_to_exclude_from_per_ip_limits = 127.0.0.1/32, ::1/128


# Max history - 'max_history' - DEFAULT: 125000
#
# The maximum size of the transaction history for a particular address
# (scripthash) that the server will serve to clients, in terms of number of
# transactions. Addresses having a history exceeding this size will not
# participate in subscriptions (the history status returned will be null), and
# `get_history` and/or `listunspent` will return an empty list. From the point
# of view of a client asking for such a large history -- it will be as if the
# address in question has no history at all.
#
# Be careful increasing this limit. The default chosen is already quite generous
# with fewer than 0.0000001% of addresses on mainnet having histories in excess
# of this limit.
#
# This is a performance-saving measure designed to keep excessively large
# address histories from impacting the performance of the server and using up
# resources. Moreover, it can be argued that such users with such
# computationally expensive histories are better served running a full node
# themesleves, rather than relying on a public SPV server and/or light wallet
# system.
#
# Note that there are some addresses on the chain whose histories exceed 7.5
# million transactions. Returning such a large history to clients and/or
# calculating the "status hash" for such a large history takes on the order of
# seconds, and can impact the experience of other users of your server if
# excessive requests are made for such large histories (if this limit were not
# in place).
#
# This value may be set to any positive integer in the range: [1000, 100000000].
#
#max_history = 125000


# Maximum transmission backlog size - 'max_buffer' - DEFAULT: 4000000
#
# The maximum size in bytes of the transmission buffer "backlog" (send and
# receive) per client. This limit is a simple sanity check against DoS and/or
# misbehaving clients.
#
# As a client is sent data, it is expected that they will read it in time and
# not let it accumulate on the sending end. If the data backlog exceeds this
# size, then the client is automatically disconnected. The default chosen is a
# good size in practice, but if your server is serving up large address
# histories in excess of 55,000 transactions for a single address, and your
# clients are slow to read and consume this data, then you may want to increase
# this limit.
#
# Note that unlike ElectrumX or ElecronX, this variable does *not* limit the
# size of transaction histories that may be sent to clients. In fact, you may
# set this variable quite low and if clients can read data as it is generated,
# they may receive arbitrarily large histories from your server.
#
# You may not set this number below 64000 (64 KiB) or in excess of 100000000
# (100 MiB).
#
#max_buffer = 4000000


# Work queue size - 'workqueue' - DEFAULT: 10000
#
# The maximum size of the work queue. Requests from clients that require further
# processing (such as get_merkle, get_history, listunspent, etc) all end up
# being placed in a queue and processed asynchronously by threads in a thread
# pool. The 'workqueue' parameter sets the size of the work backlog before the
# server returns errors to clients. Normally this option does not need to be
# changed, but the parameter is exposed to server admins for testing and
# debugging purposes.
#
# It is an error to set this parameter to less than 10.
#
#workqueue = 10000


# Work queue threads - 'worker_threads' - DEFAULT: 0 (= autodetect # of CPUs)
#
# The maximum number of worker threads that can simultaneously be spawned for
# work queue processing. In most cases you want to leave this option at its
# default (0, meaning autodetect to number of cores on the system), since using
# as many threads as there are cores on the system is the most efficient overall
# setting and leads to optimal server responsiveness and performance.
#
# In general as clients make requests they are processed very quickly and CPU
# impact on the server is minimal on average. You want the server to have access
# to all your cores for when work arrives in a burst -- which is why the default
# is a good setting.
#
# However, this configuration parameter is exposed to admins wishing to cap the
# maximal load that the server can put on the system. Say you have a server with
# 16 physical cores, setting 'worker_threads = 4' will cap the total CPU load on
# the system to 25% (4 out of 16 cores).
#
# You may even wish to experiment with setting this value higher than the number
# of cores on the system since some of the work submitted to the queue is I/O
# bound work (db reads from disk), so it may actually be beneficial to set this
# higher than the number of cores on the system.
#
#worker_threads = 0   # <--- autodetect to number of cores on the system.


# Peer IP uniqueness enforcement - 'peering_enforce_unique_ip' - DEFAULT: true
#
# TODO: Description here
#
#peering_enforce_unique_ip = true