A Node.js library for bitcoin server software configuration
$ npm install @carnesen/bitcoin-config
The package includes runtime JavaScript files suitable for Node.js >=8 as well as the corresponding TypeScript type declarations.
Here's an example that reads and parses the default configuration file (e.g. ~/.bitcoin/bitcoin.conf on Linux):
const { readConfigFiles, DEFAULT_CONFIG_FILE_PATH } = require('@carnesen/bitcoin-config');
const config = readConfigFiles(DEFAULT_CONFIG_FILE_PATH);
console.log(config);
/*
{ regtest: true,
daemon: true,
rpcconnect: '1.2.3.4',
rpcport: 33333 }
*/In TypeScript, the returned config object is intelligently typed, e.g. regtest has type boolean.
Here's an example of writing a configuration file:
const { writeConfigFile, DEFAULT_CONFIG_FILE_PATH } = require('@carnesen/bitcoin-config');
const { changed } = writeConfigFile(DEFAULT_CONFIG_FILE_PATH, {
regtest: true,
rpcconnect: '1.2.3.4',
sections: {
regtest: {
rpcport: 33333,
},
},
});
const message = changed
? `Wrote "${DEFAULT_CONFIG_FILE_PATH}"`
: `File "${DEFAULT_CONFIG_FILE_PATH}" has not changed`;
console.log(message);Now the file at DEFAULT_CONFIG_FILE_PATH has contents:
# This is a bitcoin configuration file written using @carnesen/bitcoin-config
# Run this node on its own independent test network.
regtest=1
# Send commands to node running on <ip>
rpcconnect=1.2.3.4
[regtest]
# Listen for JSON-RPC connections on this port.
rpcport=33333Suppose now we want to update the configuration file:
const { updateConfigFile, DEFAULT_CONFIG_FILE_PATH } = require('@carnesen/bitcoin-config');
updateConfigFile(DEFAULT_CONFIG_FILE_PATH, {
daemon: true,
rpcconnect: null,
});This update means "set the daemon property to true and unset (delete) the rpcconnect property".
string. The (platform-dependent) default path of the bitcoin configuration file, e.g. ~/.bitcoin/bitcoin.conf on Linux.
{[optionName: string]: {longName, typeName, description, defaultValue}}. An object containing all available bitcoin configuration options. The keys are the option names (e.g. rpcuser) and the values are objects containing typeName etc. Currently there are 147 items in BITCOIN_CONFIG_OPTIONS. If an option is missing, please file an issue or submit a pull request on this project's repository on GitHub.
A TypeScript type derived from BITCOIN_CONFIG_OPTIONS. The type's keys are the option names (e.g. rpcuser) and the values are TypeScript analogs of the typeNames. Effectively,
type BitcoinConfig = {
testnet: boolean;
timeout: number;
rpcuser: string;
rpcauth: string[];
...
}A TypeScript interface that extends BitcoinConfig with an additional property sections. As of Bitcoin Core v0.17.0, configuration files can have INI "sections", for example:
# bitcoin.conf
rpcuser=carnesen
[main]
rpcpassword=abcd1234
[regtest]
rpcpassword=passwordThis means that when the node is running on the "main" chain rpcpassword is "abcd1234", but when it's running in "regtest" mode, rpcpassword is simply "password". The sections property of a SectionedConfig represents those chain-specific configuration options. Not all options are allowed in all sections. For example, the chain selection options regtest and testnet are only allowed at the top of the file above the sections. Other options such as acceptnonstdtxn are not allowed in the "main" section. The config argument of writeConfigFile described below has type SectionedConfig.
Reads and parses a bitcoin configuration file from disk
string. Absolute path of a bitcoin configuration file.
SectionedConfig. As described above. The return value represents the full contents of a single bitcoin configuration file.
Reads, parses, and merges a bitcoin configuration file together with all its includeconf files.
string. Absolute path of a bitcoin configuration file.
BitcoinConfig. Whereas readConfigFile returns the full contents of a single file, readConfigFiles returns the merged content of (potentially) several files. If the configuration file at filePath specifies any includeconfs, those are read and merged into the original. What makes the result a BitcoinConfig not a SectionedConfig is that if there is a configuration section for the currently-active chain, that gets merged into the any-chain values from the top part of the config files above the sections. The logic for casting and merging values is meant to reproduce as closely as possible that of Bitcoin Core. So you're getting as a return value the effective "active" configuration.
Serializes a configuration object and writes it to disk
string. Absolute path of a bitcoin configuration file.
SectionedConfig. A configuration object to serialize and write to disk
boolean. The writeConfigFile function is idempotent in the sense that if an existing file at filePath has contents identical to what it's about to write, it does not re-write the file. Instead it just returns changed as false and leaves the file alone.
string. The serialized representation of the passed configuration object
string. When writeConfigFile writes a file to disk, it first move an existing file at that location to ${filePath}.bak. backupFilePath is the absolute path of the backup file.
Extracts a "chain name" ('main' | 'test' | 'regtest') from boolean properties regtest and testnet.
{
regtest?: boolean;
testnet?: boolean;
}'main' | 'test' | 'regtest'
Returns a new configuration object with the boolean properties regtest and testnet set appropriately based on the provided "chain name" ('main' | 'test' | 'regtest').
Returns an object containing the default configuration for the specified chain
'main' | 'test' | 'regtest'
DefaultConfig. A literal-specific object type with default values for the specified chain. For example, the expression getDefaultConfig('main').rpcport has value 8332 and a numeric literal type 8332.
string. A serialized SectionConfig.
SectionedConfig. A configuration object parsed from serializedConfig.
SectionedConfig. A configuration object.
string. An INI-serialized version of sectionedConfig.
Updates or creates a bitcoin configuration file
string. Absolute path of a bitcoin configuration file. Will be created if it does not exist.
NullableSectionedConfig. Basically a SectionedConfig but where every property's type includes null. A delta property value null means "delete this property".
Same as writeConfigFile above.
Converts a datadir-relative file path into an absolute one.
string. An absolute path (e.g. '/home/carnesen/.bitcoin/bitcoin.conf') or a relative one (e.g. 'bitcoin.conf'.
string (optional). Absolute path of a bitcoin data directory. Default value is platform dependent, e.g. ~/.bitcoin on Linux.
'main' | 'regtest' | 'test' (optional). If provided, '', '/regtest', or '/testnet3', respectively, is appended to the absolute path. Blocks and other data is written to these subdirectories.
string. An absolute file path string.
This library has over 80 unit tests with >98% coverage. The tests make assertions not only about its runtime behavior but also about its types using dtslint. If you want to see more examples of how it works, that'd be a good place to start. If you encounter any bugs or have any questions or feature requests, please don't hesitate to file an issue or submit a pull request on this project's repository on GitHub.
MIT © Chris Arnesen