Guidance on Qtum Deployment

Guidance on Qtum Deployment

Overview

This guide covers deploying, running, and making RPC calls to a Qtum node. It assumes basic familiarity with command-line interfaces on Linux, macOS, or Windows. For GUI wallet usage, refer to the Qtum Wallet Tutorial.

Getting Qtum Node

1. Download Prebuilt Binaries

The simplest method is downloading the latest binaries from the Qtum releases page. Binaries are available for Linux, Windows, macOS, and Raspberry Pi.

Current stable version: 29.1 (based on Bitcoin Core 29.1)

Available platforms:

• macOS: qtum-{version}-arm64-apple-darwin.dmg (Apple Silicon) or qtum-{version}-x86_64-apple-darwin.tar.gz (Intel)

• Linux: qtum-{version}-x86_64-linux-gnu.tar.gz (64-bit) or qtum-{version}-aarch64-linux-gnu.tar.gz (ARM64)

• Windows: qtum-{version}-win64.zip (64-bit) or qtum-{version}-win32.zip (32-bit)

• Raspberry Pi: qtum-{version}-arm-linux-gnueabihf.tar.gz

After extraction, qtumd and qtum-cli binaries will be located in <install-path>/bin/.

2. Package Manager Installation (Ubuntu Linux)

Ubuntu, Debian, and Mint users can install via apt repository:

# Add Qtum repository
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BF5B197D
echo "deb https://repo.qtum.info/apt/ubuntu/ $(lsb_release -cs) main" |sudo tee -a /etc/apt/sources.list.d/qtum.list
sudo apt update
sudo apt install qtum

Raspberry Pi users can also use apt. See the Raspberry Pi installation guide.

After installation, qtumd and qtum-cli are available system-wide.

3. Build from Source

For the latest development version, clone the repository and build using CMake:

git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

Build Prerequisites

Qtum uses CMake for its build system (migrated from Autotools in Bitcoin Core 29.1). Detailed instructions are available in the repository:

• Linux: build-unix.md

• macOS: build-osx.md

• Windows: build-windows.md

Minimum CMake version required: 3.22

macOS Build Example

# Install dependencies via Homebrew
brew install cmake boost libevent gmp protobuf qt@6 qrencode

# Clone repository
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum

# Configure with CMake
cmake -B build

# Build (use -j N for N parallel jobs)
cmake --build build -j$(sysctl -n hw.physicalcpu)

# Optional: Install binaries
cmake --install build

# Binaries will be in build/src/

How to Run Qtum-Qt.app with a Self-Signed Certificate on macOS

If you have downloaded Qtum-Qt.app and want to run it on macOS, you may encounter security restrictions. This guide provides specific instructions for using a self-signed certificate to allow Qtum-Qt.app to run.

Steps

1. Create a Self-Signed Certificate (Skip if you already have a certificate for code signing)

1. Open Keychain Access (Applications > Utilities > Keychain Access).

2. In the Keychain Access menu, select Certificate Assistant > Create a Certificate.

3. Enter a name for your certificate (e.g., "Qtum Certificate").

4. Set Identity Type to Self-Signed Root.

5. Set Certificate Type to Code Signing.

6. Click Create to generate the certificate.

2. Sign the Qtum-Qt.app Application

1. Open Terminal.

2. Use the following codesign command to sign Qtum-Qt.app with the newly created certificate:

   codesign --force --deep --sign "Qtum Certificate" /path/to/Qtum-Qt.app

   Replace "Qtum Certificate" with the name of your certificate, and ensure /path/to/Qtum-Qt.app/ points to the actual location of the app on your system. Remove Qtum from MacOS Quarantine: sudo xattr -rd com.apple.quarantine Qtum-Qt.app

3. Open Qtum from the Applications menu

*Note: The same procedure can be used to sign qtumd, qtum-cli and other command line binaries.

4. Docker Image

For users with Docker installed, pull the official Qtum image:

docker pull qtum/qtum:latest

For Docker deployment instructions, see How to Launch Qtum with Docker.

Key Binaries

• qtumd: Qtum Core daemon (full node)

• qtum-cli: Command-line interface for RPC calls

• qtum-qt: GUI wallet application (if built with Qt support)

Deploy Qtum Node

Start the Daemon

./qtumd -daemon

This launches qtumd as a background daemon. To enable smart contract event logging, add the -logevents flag:

./qtumd -daemon -logevents

Additional Options

View all available options:

./qtumd -help

Stop the Daemon

./qtum-cli stop

Data Directory

The default data directory varies by platform:

• Linux: ~/.qtum/

• macOS: ~/Library/Application Support/Qtum/

• Windows: %APPDATA%\Qtum\

Use the -datadir option to specify a custom location.

Initial Blockchain Sync

On first launch, Qtum will sync the entire blockchain history. This may take several hours depending on network speed and hardware. Progress and diagnostics are logged to ~/.qtum/debug.log.

Local RPC Calls

With qtumd running, use qtum-cli to interact with the node:

./qtum-cli getblockchaininfo

Example output:

{
  "chain": "main",
  "blocks": 850123,
  "headers": 850123,
  "bestblockhash": "a1b2c3...",
  "difficulty": 12345678.90,
  "time": 1698765432,
  "verificationprogress": 0.9999
}

List All RPC Commands

./qtum-cli help

Get Help for Specific Commands

./qtum-cli help getblockchaininfo

JSON-RPC Configuration

Remote RPC Setup

To enable remote RPC access, configure RPC credentials using either method:

Method 1: Configuration File

Create ~/.qtum/qtum.conf:

# RPC credentials (required)
rpcuser=your_username
rpcpassword=your_secure_password

# Allow remote connections (default: localhost only)
# IPv4 example:
#rpcallowip=192.168.1.0/24
# IPv6 example:
#rpcallowip=2001:db8:85a3::/64

# RPC port (default: 3889 for mainnet, 13889 for testnet)
#rpcport=3889

# Enable server mode
server=1

For more configuration options, see qtum.conf example.

Restart the node after creating or modifying qtum.conf.

Method 2: Command-Line Arguments

./qtumd -daemon \
  -rpcuser=your_username \
  -rpcpassword=your_secure_password \
  -rpcallowip=192.168.1.0/24

JSON-RPC Call Examples

Using curl

curl --user your_username:your_secure_password \
  --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"getblockchaininfo","params":[]}' \
  -H 'content-type: text/plain;' \
  http://192.168.1.100:3889/

Using Postman or Similar Tools

• URL: http://192.168.1.100:3889/

• Method: POST

• Headers: Content-Type: text/plain

• Auth: Basic Auth with RPC username/password

• Body:

  {  "jsonrpc": "1.0",  "id": "test",  "method": "getblockchaininfo",  "params": []}

Nginx Reverse Proxy (Optional)

Nginx can simplify remote RPC access by hiding credentials and providing additional security:

Configuration Example

Setup: Qtum node at 192.168.1.100, Nginx proxy at 192.168.1.50

1. Update qtum.conf on the node:

   rpcuser=internal_user
   rpcpassword=internal_password
   rpcallowip=192.168.1.50/32

2. Configure Nginx on the proxy server:

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://192.168.1.100:3889;
           # Base64 encoding of "internal_user:internal_password"
           proxy_set_header Authorization "Basic aW50ZXJuYWxfdXNlcjppbnRlcm5hbF9wYXNzd29yZA==";
       }
   }

3. Make RPC calls through the proxy:

   curl --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' \
     -H 'content-type: text/plain;' \
     http://192.168.1.50/

This approach enhances security by centralizing authentication and enabling request filtering.

Useful Resources

• Build Documentation:

  • README.md

  • build-unix.md

  • build-osx.md

  • build-windows.md

• Configuration:

  • qtum.conf examples

• macOS Specific:

  • macOS Code Signing Guide

• Command References:

  ./qtumd -help           # View all daemon options
  ./qtum-cli help         # List all RPC commands
  ./qtum-cli help <cmd>   # Get help for specific command

• CMake Build System:

  cmake -B build -LH      # List all CMake configuration options

• Official Resources:

  • Qtum GitHub Repository

  • Qtum Documentation

  • Release Notes