fulcrum-example-config.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 = /path/to/a/dir  # Windows: datadir = D:\FulcrumData\mainnet


# 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


# Admin RPC bind - 'admin' - DEFAULT: None
#
# Specifies the listen address and port for the admin RPC service. This service
# is used by the fulcrum_admin script to issue control commands to Fulcrum. As
# such, you should *NOT* bind to an interface and/or port that is publicly
# accessible by the rest of the internet. It is recommended that you bind to the
# loopback interface (e.g. 127.0.0.1 on IPv4). The port parameter used here can
# be given to the fulcrum_admin script via the -p arg. This option may be
# specified more than once to bind to multiple ports and/or interfaces.
#
#admin = 9000   # <-- a port number by itself implies 127.0.0.1
#admin = 127.0.0.1:9000


# 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 = 8080   # <-- a port number by itself implies 127.0.0.1
#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
#
# If set, we query other servers for their peer list and attempt to reach out to
# new servers appearing on the network. Normally, Electron Cash clients will
# query your server asking it for its list of servers, so leaving this as true
# means you will be able to return meaningful results to clients about available
# servers on the network.
#
#peering = true


# Peering: announce self - 'announce' - DEFAULT: true if hostname and peering
#                                                are set, false otherwise
#
# You must enable `peering` above and also define a `hostname` for this to have
# an effect. If set to true and the above conditions are met, then your server
# will announce itself to peers and likely appear in their server lists. Setting
# this to true ensures you get more clients connecting to your server.
#
#announce = true



#-------------------------------------------------------------------------------
# TOR Configuration (optional)
#-------------------------------------------------------------------------------
#
# This section is optional but if tor_hostname is set and if at least one
# tor_*_port is specified, we will also announce ourselves on the Tor network
# (iff announce=true).  Note Tor won't work unless you also configure a Tor
# proxy on your system, and with it, configure it to also offer a Tor hidden
# service.


# Tor hostname - 'tor_hostname' - DEFAULT: Nothing
#
# If specifeid, and if you have a Tor proxy configured, and if you have at least
# one of tor_tcp_port and/or tor_ssl_port specified, then we will anounce this
# host via Tor as a .onion host.  Note that this hostname must end in .onion.
#
#tor_hostname=aykwhy6o2o4ixushlonpjooqv73fwx7jqgoreiknnqxuqv4dwffmb7qd.onion


# Tor banner - 'tor_banner' - DEFAULT: Use the regular banner
#
# Tor banner is optional. If unset, will just use the regular banner= setting
# (if any), or a fallback string "Connected to a Fulcrum xx.yy.zz server.". This
# is here in case you want an alternate banner to be shown to users connecting
# to your server via Tor.
#
#tor_banner=/path/to/another/alternate/banner_tor.txt


# Tor TCP port - 'tor_tcp_port' - DEFAULT: Nothing
#
# If set, we will advertise ourselves as living on the .onion tor_hostname above
# and offering this port for incoming TCP connections. At least one port (along
# with tor_hostname) must be specified to announce this server via Tor.
#
# This option may not be specified multiple times.
#
#tor_tcp_port = 60001


# Tor SSL port - 'tor_ssl_port' - DEFAULT: Nothing
#
# If set, we will advertise ourselves as living on the .onion tor_hostname above
# and offering this port for incoming SSL connections. At least one port (along
# with tor_hostname) must be specified to announce this server via Tor.
#
# This option may not be specified multiple times.
#
#tor_ssl_port = 60001


# Tor proxy to use for outbound connections - 'tor_proxy, tor_user, tor_pass'
# - DEFAULT: 127.0.0.1:9050, no username, no password
#
# If you want to discover .onion peers, be sure to configure a Tor daemon to
# run alongside your server.  The default configuration is for the Tor proxy
# port to be 127.0.0.1:9050, no username, no password. If you modified the
# default in your torrc, then specify the settings used here so that Fulcrum
# may use the Tor proxy to discover .onion peers.
#
#tor_proxy = 9050   # e.g. localhost 9050. Interface ok too e.g. 10.0.0.1:9150.
#tor_user =  # leave this out unless you specified a username in your torrc
#tor_pass =  # leave this out unless you specified a password in your torrc



#-------------------------------------------------------------------------------
# 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).
#
# Note that as of Fulcrum 1.0.4, you may dynamically adjust this value for all
# connected clients using the 'maxbuffer' FulcrumAdmin command, and it will be
# applied immediately to all connected clients.
#
#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
#
# If true (the default) we reject duplicate peers that appear multiple times
# under different hostnames but using the same IP address. Only the first such
# peer is accepted and all the others are rejected and do not appear in your
# server's peer list. This is a sybil attack defense measure and likely you
# should leave it as true.
#
#peering_enforce_unique_ip = true


# Max pending connections - 'max_pending_connections' - DEFAULT: 60
#
# The maximum number of connections that may be simultaneously "pending" before
# new client connections are refused due to the backlog. "Pending" here refers
# to new connections that come in from the OS's TCP/IP stack but haven't yet
# been properly accepted by this software. The default value is 60, which is
# already quite generous. This variable is exposed for troubleshooting and
# debugging purposes and does not normally need to be modified. Valid values are
# in the range: 10 to 9999.
#
#max_pending_connections = 60


# BitcoinD request throttling - 'bitcoind_throttle- = DEFAULT: 50 20 5
#
# This is an advanced parameter added to Fulcrum v1.0.4 to control and rate-
# limit client spamming of requests that hit bitcoind, e.g.
# 'blockchain.transaction.get'. The rationale for this facility is that it's
# possible for misbehaving clients to choke the system by hitting the server (in
# particular bitcoind) with many expensive, I/O-bound requests per unit time,
# which would degrade the responsiveness of the server to other clients.
#
# This parameter must be specified as a 3-tuple (whitespace or comma-delimited).
# The three items in the tuple are: "burst limit", "low water mark", and "decay
# per second" for the first, second, and third items, respectively. The
# definition of these three parameters is described below:
#
# "burst limit" - The number of simultaneous outstanding bitcoind-bound requests
# a client may send out at once. If a client has outstanding bitcoind-bound
# requests that have not yet returned results, and the number of such requests
# hits this limit, then the client will be throttled for at least one second, or
# until the "low water mark" of extant request is reached (whichever is longer).
# In other words, the throttling is acheived by pausing all further processing
# of requests for that client, until either one second has elapsed or the
# "low-water mark" for outstanding requests (default 20) is hit. The default
# value (50) for this burst parameter is a decent value that is neither too
# liberal nor too conservative.
#
# "low water mark" - If a client is paused, then the number of requests that are
# outstanding to bitcoind must dip below this number before it is unpaused.
#
# "decay per second" - If a client has outstanding requests, and bitcoind has
# not replied in some time, "credit" the client with this many requests towards
# their burst, per second.
#
# These parameters may be queried and/or adjusted dynamically at runtime via the
# FulcrumAdmin 'bitcoind_throttle' command.
#
#bitcoind_throttle = 50 20 5