Config

The config module provides the text forms of libbitcoin values, and the options module (options/) the machinery that reads them from a command line, environment variables and a configuration file. Each value type converts to and from a string through stream operators, which is the interface options::typed_value<Type> (options/value.hpp) uses to parse and display option values: a token is extracted with operator>> in the classic locale and must be consumed whole, and a default is displayed with operator<<. The parser, setting and printer classes of options/ load, describe and print the options of an application such as bs or bx. Paths are relative to include/bitcoin/system/ in libbitcoin-system, at master 0cd57fcf (2026-10-27).

1. Value types#

1.1 Stream round trip#

Every value type has the same shape: construction from its native value, construction from a string (which throws on malformed text), an implicit conversion back to the native value, and a friend pair of stream operators in the same text format (config/hash256.hpp):

class BC_API hash256 final
{
public:
    typedef std::vector<hash256> list;

    hash256() NOEXCEPT;
    hash256(hash_digest&& value) NOEXCEPT;
    hash256(const hash_digest& value) NOEXCEPT;
    hash256(const std::string& base16) THROWS;

    std::string to_string() const NOEXCEPT;

    operator const hash_digest&() const NOEXCEPT;
    operator uint256_t() const NOEXCEPT;

    friend std::istream& operator>>(std::istream& stream,
        hash256& argument) THROWS;
    friend std::ostream& operator<<(std::ostream& stream,
        const hash256& argument) NOEXCEPT;

private:
    hash_digest value_;
};

Extraction reports failure by throwing istream_exception with the offending text. The string constructor delegates to extraction, so both paths share one decoder. hash256 and hash160 use the reversed byte order of displayed hashes (decode_hash, encode_hash).

1.2 Chain object wrappers#

block, header, transaction, input, output, point and script derive from the corresponding chain:: class, so a parsed option is the chain object itself. Block, header and transaction text is the base16 wire serialization, and extraction rejects an object that does not deserialize as valid (src/config/header.cpp):

std::istream& operator>>(std::istream& stream, header& argument) THROWS
{
    std::string base16{};
    stream >> base16;

    data_chunk bytes{};
    if (!decode_base16(bytes, base16))
        throw istream_exception(base16);

    argument = chain::header{ bytes };

    if (!argument.is_valid())
        throw istream_exception(base16);

    return stream;
}

Script text is the opcode mnemonic form; construction from a data_chunk takes the serialized script instead. Points, inputs and outputs are colon delimited tuples (point::delimiter):

1.3 Network addresses#

authority, endpoint and url parse host and port text, with IPv6 hosts in bracketed literal form. authority holds an IP address, port and CIDR suffix ([IPv6]|IPv4[:port][/cidr]), and its equality treats a zero port as any port and a nonzero CIDR as subnet containment. endpoint holds a host name or address with an optional port ([scheme://]host[:port]), and url also retains the scheme. Both provide to_local(), which replaces a * host with localhost. The free functions in config/utilities.hpp implement the shared parsing and the denormalization of IPv4-mapped IPv6 addresses to native IPv4. All four address types and version specialize std::hash over their string form.

2. Settings#

2.1 Chain parameters#

system::settings (settings.hpp) holds the consensus parameters of a network, populated by its chain::selection constructor (mainnet, testnet3, testnet4, regtest, signet). Three of its members are config types, so they are set from configuration text through the same stream operators:

config::block genesis_block{};
config::script signet_challenge{};

config::hash256 minimum_work{};

2.2 Bound settings#

options/setting.hpp declares option values that are bound to a member of a settings object and take that member's value at declaration as their default. setting_value<Type> is an options::typed_value<Type> that also implements printable, so the current and default values of an option can be reported as text:

template <typename Type>
class setting_value
  : public typed_value<Type>,
    public printable
{
public:
    setting_value(Type* store, bool secret=false) THROWS;

    string_list values() const NOEXCEPT override;

    std::string default_text() const NOEXCEPT override;

    void parse(std::any& value, const string_list& tokens,
        const std::string& option) const THROWS override;

The factory setting(&store) declares a displayed setting and secret(&store) one whose value is withheld: a secret reports one empty value and empty default text. For integral types, parse accepts comma digit grouping (1,000,000) through ungroup. is_configured is true when a variable was set by the command line, environment or configuration file, and false when it is unset or holds its declared default.

path and base85 specialize options::is_whole_token_t as true, so typed_value constructs them from the whole token rather than by stream extraction, which cannot produce an empty token. path extraction also reads the full line, so paths may contain spaces.

3. Parsing and help#

parser is an abstract base for an application's option parser. A derived class supplies four sets of metadata, and the base loads each source into one retained variables_map:

load_configuration_variables reads the file named by a path option. With no file it parses an empty stream, which populates the declared defaults.

printer serializes the same metadata as command line help (commandline) or as a configuration settings listing (settings). It normalizes each option into a parameter (long and short names, position, argument limit, description, values), and parameter::description replaces {} in an option's description with the default text of its bound setting.

4. Config objects#

5. Other libraries#

Other libraries of the stack provide config objects in the same pattern, each round-tripping through its stream operators.