GuidesDiscussions & SupportGitHub
HomeGuidesChangelog
GuidesDiscussions & SupportGitHubLog In
Guides

Syscoin 5.0.0 Upgrade Guide

Suggest Edits

Upgrade & Installation Guide: Syscoin Core 5.0.0 (Nexus)

Introduction

This guide provides step-by-step instructions for upgrading your existing Syscoin Core installation to version 5.0.0 (codename Nexus) or performing a fresh installation. Syscoin Core 5.0.0 is a mandatory upgrade for all users, especially Sentry Node operators, due to significant protocol changes and new features.

Please read through the entire guide carefully before starting, particularly the backup instructions and system requirements.

Table of Contents

IMPORTANT: Backup Your Wallet FIRST!

Warning: This is the most critical step. Failure to back up your wallet could result in the permanent loss of your funds. Do NOT skip this section.

Your wallet.dat file contains the private keys needed to access your Syscoin.

  1. Locate your Syscoin Data Folder:

    • Windows: %APPDATA%\Syscoin (You can paste this into the File Explorer address bar, e.g., C:\Users\YourUserName\Appdata\Roaming\Syscoin)
    • Linux: ~/.syscoin (This is a hidden directory in your home folder)
    • MacOS: ~/Library/Application Support/Syscoin (Access via Finder > Go > Go to Folder...)

  2. Find the wallet.dat file inside the Data Folder.

  3. Copy wallet.dat to multiple secure, offline locations. Examples include:

    • Encrypted USB drives
    • External hard drives
    • Another computer (ensure it's secure)
    • Do not rely on just one backup location.

Prerequisites

Ensure your system meets the following minimum requirements before proceeding:

  • Operating System:
    • Recommended: Ubuntu 24.04 LTS
    • Supported: Linux (kernel 3+), macOS 10.15+, Windows 7+ (64-bit required)
  • Memory (RAM): 8 GB minimum
    • Note: Running with less than 8GB RAM can cause significant performance issues or failures, especially during the initial sync or the automatic reindex required for version 5.0.0.
  • Swap Space: 4 GB minimum swapfile is strongly recommended, particularly on systems with only 8GB RAM, to ensure stability during initial sync or reindex.
  • Disk Space: Sufficient disk space for the blockchain (currently ~30GB+, growing over time) and operating system. SSD is highly recommended for performance.

Upgrade Process Overview

The general process involves these main steps:

  1. Stop your current Syscoin Core software.
  2. Install the new Syscoin Core 5.0.0 software (using binaries or compiling).
  3. Start the new software; it will automatically reindex the blockchain on the first launch.
  4. Verify Masternode/Sentry Node status (if applicable).

Step 1: Stop Syscoin Core

Before installing the new version, you must completely shut down your current Syscoin Core instance (syscoind or Syscoin-Qt).

  • Syscoin-Qt (Graphical Wallet): Go to File > Exit.
  • syscoind (Daemon/Server): Use the stop command.
    • If running as a systemd service (common on Linux servers): 
      sudo systemctl stop syscoind
    • If running manually or via screen/tmux: 
      # Navigate to the directory containing syscoin-cli if needed
./syscoin-cli stop
  • Wait a few minutes to ensure the process has fully shut down before proceeding. You can check using ps aux | grep syscoin (Linux/Mac) or Task Manager (Windows).

Step 2: Install/Upgrade Syscoin Core 5.0.0

Choose the instructions relevant to your operating system. Using pre-built binaries is generally easier and recommended for most users.

Windows

  1. Download: Go to the official Syscoin Core releases page:
    https://github.com/syscoin/syscoin/releases
    Download the latest 5.0.0+ Windows package:

    • syscoin-*-win64-setup.exe: Recommended installer.
    • syscoin-*-win64.zip: Standalone version (extract and run).

  2. Install:

    • If using the .exe installer, run it and follow the prompts. It will typically handle uninstalling the old version and installing the new one.
    • If using the .zip archive, extract it to your desired location (e.g., replacing your previous installation files).

  3. Proceed to Step 3: First Launch and Automatic Reindex.

Linux / MacOS

Option 1: Using Pre-built Binaries (Recommended)

Linux

  1. Download: Get the latest 5.0.0+ Linux binary archive (.tar.gz) from the releases page:
    https://github.com/syscoin/syscoin/releases

    # Example for 5.0.0 - replace URL if a newer patch version is available
wget https://github.com/syscoin/syscoin/releases/download/v5.0.0/syscoin-5.0.0-x86_64-linux-gnu.tar.gz

  2. Verify Checksum (Critical Security Step):

    • Download the SHA256SUMS file (and optionally SHA256SUMS.asc for GPG verification) from the same release page.

    • Verify the integrity of the downloaded archive:

      # Verify against the downloaded checksums file
sha256sum --ignore-missing -c SHA256SUMS

# Look for the line corresponding to the .tar.gz file you downloaded.
# It MUST say: OK

    • Warning: Do not proceed if the checksum verification fails.

  3. Extract:

    tar xzf syscoin-5.0.0-x86_64-linux-gnu.tar.gz

  4. Install Binaries: Copy the executables to a standard location like /usr/local/bin.

    sudo install -m 0755 -o root -g root -t /usr/local/bin syscoin-5.0.0/bin/*

    This command copies syscoind, syscoin-cli, and syscoin-qt.

  5. Proceed to Step 3: First Launch and Automatic Reindex.

MacOS

  1. Download: Get the latest 5.0.0+ macOS disk image (.dmg) from the releases page:
    https://github.com/syscoin/syscoin/releases

  2. Verify Checksum (Recommended): Similar to Linux, download the SHA256SUMS file and verify the .dmg file's integrity using shasum -a 256 <filename>.dmg and comparing the output to the hash listed in the SHA256SUMS file.

  3. Install:

    • Open the downloaded .dmg file.
    • Drag the Syscoin-Qt application icon into your Applications folder. Replace the existing version if prompted.

  4. Proceed to Step 3: First Launch and Automatic Reindex.

Option 2: Compiling from Source (Advanced)

Click here for instructions on compiling from source

Compiling from source is generally for advanced users or developers. Ensure you have the necessary build dependencies installed first (see doc/build-*.md in the source repository).

  1. Navigate to your source code directory:

    cd ~/syscoin # Or wherever your source code resides

  2. (Optional but Recommended) Clean previous build: If upgrading from a previously compiled version:

    git status # Check for local changes, stash or commit if needed
# git stash save "Pre-5.0-compile-changes" # Example stash command
make clean
# Optionally, uninstall old system-wide binaries if previously installed
# sudo make uninstall

  3. Fetch and Checkout the 5.0.0 tag:

    git fetch origin
git checkout v5.0.0

  4. Build Syscoin Core:

    ./autogen.sh
./configure # Add options if needed, e.g., --without-gui for server builds
make -j$(nproc) # Use $(sysctl -n hw.ncpu) on MacOS

  5. (Optional) Install system-wide:

    sudo make install

    If you don't run make install, the binaries (syscoind, syscoin-cli, syscoin-qt) will be in the src/ directory (or src/qt/ for syscoin-qt).

  6. Proceed to Step 3: First Launch and Automatic Reindex.

Step 3: First Launch and Automatic Reindex

Now that the new version is installed, start Syscoin Core.

  • Syscoin-Qt (Graphical): Launch it from your Start Menu (Windows), Applications folder (MacOS), or command line (syscoin-qt).
  • syscoind (Daemon):
    • If using systemd: 
      sudo systemctl start syscoind
    • If running manually: 
      # Navigate to the directory containing the binary if not installed system-wide
./syscoind -daemon

Automatic Reindex:

  • On the first launch of version 5.0.0, the software will detect the upgrade and automatically initiate a reindex of the blockchain data.
  • You will see messages indicating this in the logs (debug.log) or the graphical interface's splash screen/status bar.
  • This process is mandatory and can take a significant amount of time (hours to over a day depending on your hardware, especially disk speed). Do not interrupt it.
  • The node will not be fully functional or synced until the reindex completes.
  • Subsequent starts will not reindex unless manually specified or if data corruption is detected.

You can monitor progress via the debug.log file located in your Syscoin Data Folder or using syscoin-cli getblockchaininfo.

Step 4: Masternode / Sentry Node Specifics

If you are running a Masternode/Sentry Node:

  1. Use the Official Script: For upgrades or new setups, it's highly recommended to use the official Masternode setup script:

  2. Start Node: After running the script or manually upgrading syscoind, start the node (as shown in Step 3). It will perform the automatic reindex.

  3. Check Status: Once the reindex is complete and the node is synced, verify your Masternode's status from your controller wallet (where you hold the collateral):

    # In the controller wallet's Debug Console or via syscoin-cli
masternode status

    Look for status: "Masternode successfully started" or status: "Ready". It might take some time for the network to recognize the node after the upgrade and reindex.

  4. Note: Syscoin Core 5.0.0 removes the need for the external sentinel process. Its functionality is now integrated into syscoind.

Troubleshooting

  • Reindex Slow/Stuck: Ensure you meet the RAM and Swap requirements. Check disk I/O isn't bottlenecked. Patience is key; it's a long process. Check debug.log for errors. When it was stuck try a fresh synchronization.
  • Node Won't Start: Check debug.log for specific error messages. Common issues include insufficient disk space, file permission problems, or incomplete shutdown of the old version.
  • Masternode Not Starting/ENABLED:
    • Ensure the node is fully synced after reindexing.
    • Verify your masternode.conf (controller wallet) and syscoin.conf (on the Sentry Node VPS) settings are correct.
    • Check the Sentry Node's firewall allows traffic on the Syscoin P2P port (default 8369).
    • Wait some time (up to an hour) after syncing for the network status to update.
    • Issue a masternode start-alias <your_alias> command from the controller wallet if needed.
  • Other Issues: Consult the official Syscoin documentation, check Syscoin GitHub Issues, or ask for help in the official Syscoin Discord/Telegram channels, providing details from your debug.log.

Updated 3 months ago