@carnesen/bitcoin-regtest-service

A Node.js library for managing a "regtest"-mode bitcoind service. The package includes runtime JavaScript files suitable for Node.js >=8 as well as the corresponding TypeScript type declarations.

Usage

The RegtestService class combines features of @carnesen/bitcoin-config, @carnesen/bitcoin-software, and @carnesen/bitcoin-service into a single easy-to-use object. The start method installs the software and writes a config file before spawning the service. A common use case is for unit testing:

const { regtestService } = require('@carnesen/bitcoin-regtest-service');

describe('A unit test', () => {
  beforeAll(() => regtest.start(), 30000);
  // ^^ This method installs the software if it hasn't been already,
  // which can take upward of 30 seconds depending on bandwidth.

  afterAll(() => regtest.stop());

  it('does the right thing', () => {
    // Some test that uses the bitcoin regtest service ...
  })
})

API

new RegtestService({datadir?}): instance

Create a new instance of the RegtestService class.

datadir

Optional string. Absolute path of a directory for the service software and its data.

instance.start(): Promise<void>

Installs the software if it hasn't been already, writes a configuration file, and starts the bitcoind service.

instance.stop(): Promise<void>

Stops the service.

instance.restart(): Promise<void>

Restarts the service.

instance.isRunning(): Promise<boolean>

Returns a promise that resolves to true if the service is running or false if it is not.

instance.bitcoinHome

string getter. Absolute path where the regtest service's software is installed.

instance.configFilePath

string getter. Absolute path of the regtest service's configuration file.

instance.rpcHref

string getter. "href" string of the service's remote procedure call (RPC) interface(e.g. 'http://rpcuser:rpcpassword@localhost:48332'), suitable for parsing using the WHATWG URL API.

More information

Check out the tests directory for more examples of how to use this library. 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.

Related

• @carnesen/bitcoin-regtest-service-cli: A Node.js command-line interface for managing a regtest-mode bitcoind service
• @carnesen/bitcoin-config: A Node.js library for bitcoin server software configuration
• @carnesen/bitcoin-service: A Node.js library for managing the bitcoin service bitcoind
• @carnesen/bitcoin-software: A Node.js library for installing bitcoin server software

License

MIT © Chris Arnesen