diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ae92fc78f2..97882db944 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -11,7 +11,7 @@ first. See CONTRIBUTING.md socket["<datadir>/node.sock"] - wallet[bitcoin-wallet] -- connects to --> socket - gui[bitcoin-gui] -- connects to --> socket + node[qtum-node] -- listens on --> socket["<datadir>/node.sock"] + wallet[qtum-wallet] -- connects to --> socket + gui[qtum-gui] -- connects to --> socket ``` @@ -90,7 +90,7 @@ This section describes the major components of the Inter-Process Communication ( ### The `libmultiprocess` Runtime Library - **Core Functionality**: The `libmultiprocess` runtime library's primary function is to instantiate the generated client and server classes as needed. -- **Bootstrapping IPC Connections**: It provides functions for starting new IPC connections, specifically binding generated client and server classes for an initial `interfaces::Init` interface (defined in [`src/interfaces/init.h`](../../src/interfaces/init.h)) to a UNIX socket. This initial interface has methods returning other interfaces that different Bitcoin Core modules use to communicate after the bootstrapping phase. +- **Bootstrapping IPC Connections**: It provides functions for starting new IPC connections, specifically binding generated client and server classes for an initial `interfaces::Init` interface (defined in [`src/interfaces/init.h`](../../src/interfaces/init.h)) to a UNIX socket. This initial interface has methods returning other interfaces that different Qtum Core modules use to communicate after the bootstrapping phase. - **Asynchronous I/O and Thread Management**: The library is also responsible for managing I/O and threading. Particularly, it ensures that IPC requests never block each other and that new threads on either side of a connection can always make client calls. It also manages worker threads on the server side of calls, ensuring that calls from the same client thread always execute on the same server thread (to avoid locking issues and support nested callbacks). ### Type Hooks in [`src/ipc/capnp/*-types.h`](../../src/ipc/capnp/) @@ -124,13 +124,13 @@ Diagram showing generated source files and includes. ### Selection of Cap’n Proto The choice to use [Cap’n Proto](https://capnproto.org/) for IPC was primarily influenced by its support for passing object references and managing object lifetimes, which would have to be implemented manually with a framework that only supported plain requests and responses like [gRPC](https://grpc.io/). The support is especially helpful for passing callback objects like `std::function` and enabling bidirectional calls between processes. -The choice to use an RPC framework at all instead of a custom protocol was necessitated by the size of Bitcoin Core internal interfaces which consist of around 150 methods that pass complex data structures and are called in complicated ways (in parallel, and from callbacks that can be nested and stored). Writing a custom protocol to wrap these complicated interfaces would be a lot more work, akin to writing a new RPC framework. +The choice to use an RPC framework at all instead of a custom protocol was necessitated by the size of Qtum Core internal interfaces which consist of around 150 methods that pass complex data structures and are called in complicated ways (in parallel, and from callbacks that can be nested and stored). Writing a custom protocol to wrap these complicated interfaces would be a lot more work, akin to writing a new RPC framework. ### Hiding IPC The IPC mechanism is deliberately isolated from the rest of the codebase so less code has to be concerned with IPC. -Building Bitcoin Core with IPC support is optional, and node, wallet, and GUI code can be compiled to either run in the same process or separate processes. The build system also ensures Cap’n Proto library headers can only be used within the [`src/ipc/capnp/`](../../src/ipc/capnp/) directory, not in other parts of the codebase. +Building Qtum Core with IPC support is optional, and node, wallet, and GUI code can be compiled to either run in the same process or separate processes. The build system also ensures Cap’n Proto library headers can only be used within the [`src/ipc/capnp/`](../../src/ipc/capnp/) directory, not in other parts of the codebase. The libmultiprocess runtime is designed to place as few constraints as possible on IPC interfaces and to make IPC calls act like normal function calls. Method arguments, return values, and exceptions are automatically serialized and sent between processes. Object references and `std::function` arguments are tracked to allow invoked code to call back into invoking code at any time. And there is a 1:1 threading model where every client thread has a corresponding server thread responsible for executing incoming calls from that thread (there can be multiple calls from the same thread due to callbacks) without blocking, and holding the same thread-local variables and locks so behavior is the same whether IPC is used or not. @@ -150,23 +150,23 @@ The currently defined IPC interfaces are unstable, and can change freely with no ## Security Considerations -The integration of [Cap’n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) into the Bitcoin Core architecture increases its potential attack surface. Cap’n Proto, being a complex and substantial new dependency, introduces potential sources of vulnerability, particularly through the creation of new UNIX sockets. The inclusion of libmultiprocess, while a smaller external dependency, also contributes to this risk. However, plans are underway to incorporate libmultiprocess as a git subtree, aligning it more closely with the project's well-reviewed internal libraries. While adopting these multiprocess features does introduce some risk, it's worth noting that they can be disabled, allowing builds without these new dependencies. This flexibility ensures that users can balance functionality with security considerations as needed. +The integration of [Cap’n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) into the Qtum Core architecture increases its potential attack surface. Cap’n Proto, being a complex and substantial new dependency, introduces potential sources of vulnerability, particularly through the creation of new UNIX sockets. The inclusion of libmultiprocess, while a smaller external dependency, also contributes to this risk. However, plans are underway to incorporate libmultiprocess as a git subtree, aligning it more closely with the project's well-reviewed internal libraries. While adopting these multiprocess features does introduce some risk, it's worth noting that they can be disabled, allowing builds without these new dependencies. This flexibility ensures that users can balance functionality with security considerations as needed. ## Example Use Cases and Flows ### Retrieving a Block Hash -Let’s walk through an example where the `bitcoin-wallet` process requests the hash of a block at a specific height from the `bitcoin-node` process. This example demonstrates the practical application of the IPC mechanism, specifically the interplay between C++ method calls and Cap’n Proto-generated RPC calls. +Let’s walk through an example where the `qtum-wallet` process requests the hash of a block at a specific height from the `qtum-node` process. This example demonstrates the practical application of the IPC mechanism, specifically the interplay between C++ method calls and Cap’n Proto-generated RPC calls.
```mermaid sequenceDiagram - box "bitcoin-wallet process" + box "qtum-wallet process" participant WalletCode as Wallet code participant ChainClient as Generated Chain client class
ProxyClient end - box "bitcoin-node process" + box "qtum-node process" participant ChainServer as Generated Chain server class
ProxyServer participant LocalChain as Chain object
node::ChainImpl end @@ -183,7 +183,7 @@ sequenceDiagram Chain::getBlockHash call diagram
-1. **Initiation in bitcoin-wallet** +1. **Initiation in qtum-wallet** - The wallet process calls the `getBlockHash` method on a `Chain` object. This method is defined as a virtual method in [`src/interfaces/chain.h`](../../src/interfaces/chain.h). 2. **Translation to Cap’n Proto RPC** @@ -191,38 +191,38 @@ sequenceDiagram - The client subclass is automatically generated by the `mpgen` tool from the [`chain.capnp`](https://github.com/ryanofsky/bitcoin/blob/pr/ipc/src/ipc/capnp/chain.capnp) file in [`src/ipc/capnp/`](../../src/ipc/capnp/). 3. **Request Preparation and Dispatch** - - The `getBlockHash` method of the generated `Chain` client subclass in `bitcoin-wallet` populates a Cap’n Proto request with the `height` parameter, sends it to `bitcoin-node` process, and waits for a response. + - The `getBlockHash` method of the generated `Chain` client subclass in `qtum-wallet` populates a Cap’n Proto request with the `height` parameter, sends it to `qtum-node` process, and waits for a response. -4. **Handling in bitcoin-node** - - Upon receiving the request, the Cap'n Proto dispatching code in the `bitcoin-node` process calls the `getBlockHash` method of the `Chain` [server class](#c-server-classes-in-generated-code). +4. **Handling in qtum-node** + - Upon receiving the request, the Cap'n Proto dispatching code in the `qtum-node` process calls the `getBlockHash` method of the `Chain` [server class](#c-server-classes-in-generated-code). - The server class is automatically generated by the `mpgen` tool from the [`chain.capnp`](https://github.com/ryanofsky/bitcoin/blob/pr/ipc/src/ipc/capnp/chain.capnp) file in [`src/ipc/capnp/`](../../src/ipc/capnp/). - - The `getBlockHash` method of the generated `Chain` server subclass in `bitcoin-wallet` receives a Cap’n Proto request object with the `height` parameter, and calls the `getBlockHash` method on its local `Chain` object with the provided `height`. - - When the call returns, it encapsulates the return value in a Cap’n Proto response, which it sends back to the `bitcoin-wallet` process, + - The `getBlockHash` method of the generated `Chain` server subclass in `qtum-wallet` receives a Cap’n Proto request object with the `height` parameter, and calls the `getBlockHash` method on its local `Chain` object with the provided `height`. + - When the call returns, it encapsulates the return value in a Cap’n Proto response, which it sends back to the `qtum-wallet` process, 5. **Response and Return** - - The `getBlockHash` method of the generated `Chain` client subclass in `bitcoin-wallet` which sent the request now receives the response. + - The `getBlockHash` method of the generated `Chain` client subclass in `qtum-wallet` which sent the request now receives the response. - It extracts the block hash value from the response, and returns it to the original caller. ## Future Enhancements Further improvements are possible such as: -- Separating indexes from `bitcoin-node`, and running indexing code in separate processes (see [indexes: Stop using node internal types #24230](https://github.com/bitcoin/bitcoin/pull/24230)). +- Separating indexes from `qtum-node`, and running indexing code in separate processes (see [indexes: Stop using node internal types #24230](https://github.com/bitcoin/bitcoin/pull/24230)). - Enabling wallet processes to listen for JSON-RPC requests on their own ports instead of needing the node process to listen and forward requests to them. - Automatically generating `.capnp` files from C++ interface definitions (see [Interface Definition Maintenance](#interface-definition-maintenance)). - Simplifying and stabilizing interfaces (see [Interface Stability](#interface-stability)). - Adding sandbox features, restricting subprocess access to resources and data (see [https://eklitzke.org/multiprocess-bitcoin](https://eklitzke.org/multiprocess-bitcoin)). -- Using Cap'n Proto's support for [other languages](https://capnproto.org/otherlang.html), such as [Rust](https://github.com/capnproto/capnproto-rust), to allow code written in other languages to call Bitcoin Core C++ code, and vice versa (see [How to rustify libmultiprocess? #56](https://github.com/chaincodelabs/libmultiprocess/issues/56)). +- Using Cap'n Proto's support for [other languages](https://capnproto.org/otherlang.html), such as [Rust](https://github.com/capnproto/capnproto-rust), to allow code written in other languages to call Qtum Core C++ code, and vice versa (see [How to rustify libmultiprocess? #56](https://github.com/chaincodelabs/libmultiprocess/issues/56)). ## Conclusion -This modularization represents an advancement in Bitcoin Core's architecture, offering enhanced security, flexibility, and maintainability. The project invites collaboration and feedback from the community. +This modularization represents an advancement in Qtum Core's architecture, offering enhanced security, flexibility, and maintainability. The project invites collaboration and feedback from the community. ## Appendices ### Glossary of Terms -- **abstract class**: A class in C++ that consists of virtual functions. In the Bitcoin Core project, they define interfaces for inter-component communication. +- **abstract class**: A class in C++ that consists of virtual functions. In the Qtum Core project, they define interfaces for inter-component communication. - **asynchronous I/O**: A form of input/output processing that allows a program to continue other operations while a transmission is in progress. @@ -232,11 +232,11 @@ This modularization represents an advancement in Bitcoin Core's architecture, of - **Cap’n Proto struct**: A structured data format used in Cap’n Proto, similar to structs in C++, for organizing and transporting data across different processes. -- **client class (in generated code)**: A C++ class generated from a Cap’n Proto interface which inherits from a Bitcoin core abstract class, and implements each virtual method to send IPC requests to another process. (see also [components section](#c-client-subclasses-in-generated-code)) +- **client class (in generated code)**: A C++ class generated from a Cap’n Proto interface which inherits from a Qtum core abstract class, and implements each virtual method to send IPC requests to another process. (see also [components section](#c-client-subclasses-in-generated-code)) - **IPC (inter-process communication)**: Mechanisms that enable processes to exchange requests and data. -- **ipc::Exception class**: A class within Bitcoin Core's protocol-agnostic IPC code that is thrown by client class methods when there is an IPC error. +- **ipc::Exception class**: A class within Qtum Core's protocol-agnostic IPC code that is thrown by client class methods when there is an IPC error. - **libmultiprocess**: A custom library and code generation tool used for creating IPC interfaces and managing IPC connections. @@ -246,9 +246,9 @@ This modularization represents an advancement in Bitcoin Core's architecture, of - **protocol-agnostic code**: Generic IPC code in [`src/ipc/`](../../src/ipc/) that does not rely on Cap’n Proto and could be used with other protocols. Distinct from code in [`src/ipc/capnp/`](../../src/ipc/capnp/) which relies on Cap’n Proto. -- **RPC (remote procedure call)**: A protocol that enables a program to request a service from another program in a different address space or network. Bitcoin Core uses [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) for RPC. +- **RPC (remote procedure call)**: A protocol that enables a program to request a service from another program in a different address space or network. Qtum Core uses [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) for RPC. -- **server class (in generated code)**: A C++ class generated from a Cap’n Proto interface which handles requests sent by a _client class_ in another process. The request handled by calling a local Bitcoin Core interface method, and the return values (if any) are sent back in a response. (see also: [components section](#c-server-classes-in-generated-code)) +- **server class (in generated code)**: A C++ class generated from a Cap’n Proto interface which handles requests sent by a _client class_ in another process. The request handled by calling a local Qtum Core interface method, and the return values (if any) are sent back in a response. (see also: [components section](#c-server-classes-in-generated-code)) - **unix socket**: Communication endpoint which is a filesystem path, used for exchanging data between processes running on the same host. diff --git a/doc/files.md b/doc/files.md index f88d3f91a1..18f642cc7d 100644 --- a/doc/files.md +++ b/doc/files.md @@ -1,4 +1,4 @@ -# Bitcoin Core file system +# Qtum Core file system **Contents** @@ -20,19 +20,19 @@ ## Data directory location -The data directory is the default location where the Bitcoin Core files are stored. +The data directory is the default location where the Qtum Core files are stored. 1. The default data directory paths for supported platforms are: Platform | Data directory path ---------|-------------------- -Linux | `$HOME/.bitcoin/` -macOS | `$HOME/Library/Application Support/Bitcoin/` -Windows | `%APPDATA%\Bitcoin\` [\[1\]](#note1) +Linux | `$HOME/.qtum/` +macOS | `$HOME/Library/Application Support/Qtum/` +Windows | `%APPDATA%\Qtum\` [\[1\]](#note1) 2. A custom data directory path can be specified with the `-datadir` option. -3. All content of the data directory, except for `bitcoin.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: +3. All content of the data directory, except for `qtum.conf` file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ: Chain option | Data directory path -------------------------------|------------------------------ @@ -47,7 +47,7 @@ Subdirectory | File(s) | Description -------------------|-----------------------|------------ `blocks/` | | Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`) `blocks/index/` | LevelDB database | Block index; `-blocksdir` option does not affect this path -`blocks/` | `blkNNNNN.dat`[\[2\]](#note2) | Actual Bitcoin blocks (in network format, dumped in raw on disk, 128 MiB per file) +`blocks/` | `blkNNNNN.dat`[\[2\]](#note2) | Actual Qtum blocks (in network format, dumped in raw on disk, 128 MiB per file) `blocks/` | `revNNNNN.dat`[\[2\]](#note2) | Block undo data (custom format) `chainstate/` | LevelDB database | Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from) `indexes/txindex/` | LevelDB database | Transaction index; *optional*, used if `-txindex=1` @@ -57,9 +57,9 @@ Subdirectory | File(s) | Description `wallets/` | | [Contains wallets](#multi-wallet-environment); can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, wallets reside in the [data directory](#data-directory-location) `./` | `anchors.dat` | Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to re-connect to on startup `./` | `banlist.json` | Stores the addresses/subnets of banned nodes. -`./` | `bitcoin.conf` | User-defined [configuration settings](bitcoin-conf.md) for `bitcoind` or `bitcoin-qt`. File is not written to by the software and must be created manually. Path can be specified by `-conf` option -`./` | `bitcoind.pid` | Stores the process ID (PID) of `bitcoind` or `bitcoin-qt` while running; created at start and deleted on shutdown; can be specified by `-pid` option -`./` | `debug.log` | Contains debug information and general logging generated by `bitcoind` or `bitcoin-qt`; can be specified by `-debuglogfile` option +`./` | `qtum.conf` | User-defined [configuration settings](bitcoin-conf.md) for `qtumd` or `qtum-qt`. File is not written to by the software and must be created manually. Path can be specified by `-conf` option +`./` | `qtumd.pid` | Stores the process ID (PID) of `qtumd` or `qtum-qt` while running; created at start and deleted on shutdown; can be specified by `-pid` option +`./` | `debug.log` | Contains debug information and general logging generated by `qtumd` or `qtum-qt`; can be specified by `-debuglogfile` option `./` | `fee_estimates.dat` | Stores statistics used to estimate minimum transaction fees required for confirmation `./` | `guisettings.ini.bak` | Backup of former [GUI settings](#gui-settings) after `-resetguisettings` option is used `./` | `ip_asn.map` | IP addresses to Autonomous System Numbers (ASNs) mapping used for bucketing of the peers; path can be specified with the `-asmap` option @@ -67,7 +67,7 @@ Subdirectory | File(s) | Description `./` | `onion_v3_private_key` | Cached Tor onion service private key for `-listenonion` option `./` | `i2p_private_key` | Private key that corresponds to our I2P address. When `-i2psam=` is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist. `./` | `peers.dat` | Peer IP address database (custom format) -`./` | `settings.json` | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from [bitcoin.conf](bitcoin-conf.md). File is created automatically if read-write settings storage is not disabled with `-nosettings` option. Path can be specified with `-settings` option +`./` | `settings.json` | Read-write settings set through GUI or RPC interfaces, augmenting manual settings from [qtum.conf](bitcoin-conf.md). File is created automatically if read-write settings storage is not disabled with `-nosettings` option. Path can be specified with `-settings` option `./` | `.cookie` | Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by `-rpccookiefile` option `./` | `.lock` | Data directory lock file @@ -105,11 +105,11 @@ Subdirectory | File | Description ## GUI settings -`bitcoin-qt` uses [`QSettings`](https://doc.qt.io/qt-5/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored). +`qtum-qt` uses [`QSettings`](https://doc.qt.io/qt-5/qsettings.html) class; this implies platform-specific [locations where application settings are stored](https://doc.qt.io/qt-5/qsettings.html#locations-where-application-settings-are-stored). ## Legacy subdirectories and files -These subdirectories and files are no longer used by Bitcoin Core: +These subdirectories and files are no longer used by Qtum Core: Path | Description | Repository notes ---------------|-------------|----------------- diff --git a/doc/productivity.md b/doc/productivity.md index e9b7bc270c..5946d73f92 100644 --- a/doc/productivity.md +++ b/doc/productivity.md @@ -75,9 +75,9 @@ When rebuilding during development, note that running `make`, without giving a t Obviously, it is important to build and run the tests at appropriate times -- but when you just want a quick compile to check your work, consider picking one or a set of build targets relevant to what you're working on, e.g.: ```sh -make src/bitcoind src/bitcoin-cli -make src/qt/bitcoin-qt -make -C src bitcoin_bench +make src/qtumd src/qtum-cli +make src/qt/qtum-qt +make -C src qtum_bench ``` (You can and should combine this with `-j`, as above, for a parallel build.) @@ -179,7 +179,7 @@ When looking at other's pull requests, it may make sense to add the following se ``` [remote "upstream-pull"] fetch = +refs/pull/*/head:refs/remotes/upstream-pull/* - url = git@github.com:bitcoin/bitcoin.git + url = git@github.com:qtumproject/qtum.git ``` This will add an `upstream-pull` remote to your git repository, which can be fetched using `git fetch --all` or `git fetch upstream-pull`. It will download and store on disk quite a lot of data (all PRs, including merged and closed ones). Afterwards, you can use `upstream-pull/NUMBER/head` in arguments to `git show`, `git checkout` and anywhere a commit id would be acceptable to see the changes from pull request NUMBER. diff --git a/doc/reduce-memory.md b/doc/reduce-memory.md index 2710797ef3..07383870c7 100644 --- a/doc/reduce-memory.md +++ b/doc/reduce-memory.md @@ -1,6 +1,6 @@ # Reduce Memory -There are a few parameters that can be dialed down to reduce the memory usage of `bitcoind`. This can be useful on embedded systems or small VPSes. +There are a few parameters that can be dialed down to reduce the memory usage of `qtumd`. This can be useful on embedded systems or small VPSes. ## In-memory caches @@ -12,9 +12,9 @@ The size of some in-memory caches can be reduced. As caches trade off memory usa ## Memory pool -- In Bitcoin Core there is a memory pool limiter which can be configured with `-maxmempool=`, where `` is the size in MB (1000). The default value is `300`. +- In Qtum Core there is a memory pool limiter which can be configured with `-maxmempool=`, where `` is the size in MB (1000). The default value is `300`. - The minimum value for `-maxmempool` is 5. - - A lower maximum mempool size means that transactions will be evicted sooner. This will affect any uses of `bitcoind` that process unconfirmed transactions. + - A lower maximum mempool size means that transactions will be evicted sooner. This will affect any uses of `qtumd` that process unconfirmed transactions. - Since `0.14.0`, unused memory allocated to the mempool (default: 300MB) is shared with the UTXO cache, so when trying to reduce memory usage you should limit the mempool, with the `-maxmempool` command line argument. @@ -43,12 +43,12 @@ threads take up 8MiB for the thread stack on a 64-bit system, and 4MiB in a ## Linux specific -By default, glibc's implementation of `malloc` may use more than one arena. This is known to cause excessive memory usage in some scenarios. To avoid this, make a script that sets `MALLOC_ARENA_MAX` before starting bitcoind: +By default, glibc's implementation of `malloc` may use more than one arena. This is known to cause excessive memory usage in some scenarios. To avoid this, make a script that sets `MALLOC_ARENA_MAX` before starting qtumd: ```bash #!/usr/bin/env bash export MALLOC_ARENA_MAX=1 -bitcoind +qtumd ``` -The behavior was introduced to increase CPU locality of allocated memory and performance with concurrent allocation, so this setting could in theory reduce performance. However, in Bitcoin Core very little parallel allocation happens, so the impact is expected to be small or absent. +The behavior was introduced to increase CPU locality of allocated memory and performance with concurrent allocation, so this setting could in theory reduce performance. However, in Qtum Core very little parallel allocation happens, so the impact is expected to be small or absent. diff --git a/test/README.md b/test/README.md index 0d1e06c0ad..f03e41d98c 100644 --- a/test/README.md +++ b/test/README.md @@ -1,4 +1,4 @@ -This directory contains integration tests that test bitcoind and its +This directory contains integration tests that test qtumd and its utilities in their entirety. It does not contain unit tests, which can be found in [/src/test](/src/test), [/src/wallet/test](/src/wallet/test), etc. @@ -8,9 +8,9 @@ This directory contains the following sets of tests: - [fuzz](/test/fuzz) A runner to execute all fuzz targets from [/src/test/fuzz](/src/test/fuzz). - [functional](/test/functional) which test the functionality of -bitcoind and bitcoin-qt by interacting with them through the RPC and P2P +qtumd and qtum-qt by interacting with them through the RPC and P2P interfaces. -- [util](/test/util) which tests the utilities (bitcoin-util, bitcoin-tx, ...). +- [util](/test/util) which tests the utilities (qtum-util, qtum-tx, ...). - [lint](/test/lint/) which perform various static analysis checks. The util tests are run as part of `make check` target. The fuzz tests, functional @@ -18,7 +18,7 @@ tests and lint scripts can be run as explained in the sections below. # Running tests locally -Before tests can be run locally, Bitcoin Core must be built. See the [building instructions](/doc#building) for help. +Before tests can be run locally, Qtum Core must be built. See the [building instructions](/doc#building) for help. ## Fuzz tests @@ -164,29 +164,29 @@ umount /Volumes/ramdisk ##### Resource contention -The P2P and RPC ports used by the bitcoind nodes-under-test are chosen to make -conflicts with other processes unlikely. However, if there is another bitcoind +The P2P and RPC ports used by the qtumd nodes-under-test are chosen to make +conflicts with other processes unlikely. However, if there is another qtumd process running on the system (perhaps from a previous test which hasn't successfully -killed all its bitcoind nodes), then there may be a port conflict which will +killed all its qtumd nodes), then there may be a port conflict which will cause the test to fail. It is recommended that you run the tests on a system -where no other bitcoind processes are running. +where no other qtumd processes are running. On linux, the test framework will warn if there is another -bitcoind process running when the tests are started. +qtumd process running when the tests are started. -If there are zombie bitcoind processes after test failure, you can kill them +If there are zombie qtumd processes after test failure, you can kill them by running the following commands. **Note that these commands will kill all -bitcoind processes running on the system, so should not be used if any non-test -bitcoind processes are being run.** +qtumd processes running on the system, so should not be used if any non-test +qtumd processes are being run.** ```bash -killall bitcoind +killall qtumd ``` or ```bash -pkill -9 bitcoind +pkill -9 qtumd ``` @@ -197,11 +197,11 @@ functional test is run and is stored in test/cache. This speeds up test startup times since new blockchains don't need to be generated for each test. However, the cache may get into a bad state, in which case tests will fail. If this happens, remove the cache directory (and make -sure bitcoind processes are stopped as above): +sure qtumd processes are stopped as above): ```bash rm -rf test/cache -killall bitcoind +killall qtumd ``` ##### Test logging @@ -216,7 +216,7 @@ levels using the logger included in the test_framework, e.g. - when run directly, *all* logs are written to `test_framework.log` and INFO level and above are output to the console. - when run by [our CI (Continuous Integration)](/ci/README.md), no logs are output to the console. However, if a test - fails, the `test_framework.log` and bitcoind `debug.log`s will all be dumped + fails, the `test_framework.log` and qtumd `debug.log`s will all be dumped to the console to help troubleshooting. These log files can be located under the test data directory (which is always @@ -231,7 +231,7 @@ e.g. `self.nodes[0]`. To change the level of logs output to the console, use the `-l` command line argument. -`test_framework.log` and bitcoind `debug.log`s can be combined into a single +`test_framework.log` and qtumd `debug.log`s can be combined into a single aggregate log by running the `combine_logs.py` script. The output can be plain text, colorized text or html. For example: @@ -258,9 +258,9 @@ import pdb; pdb.set_trace() ``` anywhere in the test. You will then be able to inspect variables, as well as -call methods that interact with the bitcoind nodes-under-test. +call methods that interact with the qtumd nodes-under-test. -If further introspection of the bitcoind instances themselves becomes +If further introspection of the qtumd instances themselves becomes necessary, this can be accomplished by first setting a pdb breakpoint at an appropriate location, running the test to that point, then using `gdb` (or `lldb` on macOS) to attach to the process and debug. @@ -283,13 +283,13 @@ test run: Use the path to find the pid file in the temp folder: ```bash -cat /tmp/user/1000/testo9vsdjo3/node1/regtest/bitcoind.pid +cat /tmp/user/1000/testo9vsdjo3/node1/regtest/qtumd.pid ``` Then you can use the pid to start `gdb`: ```bash -gdb /home/example/bitcoind +gdb /home/example/qtumd ``` Note: gdb attach step may require ptrace_scope to be modified, or `sudo` preceding the `gdb`.