zmqpubhashblock no longer accepts ipc:// socket paths after v8.26.X upgrade

[8eS3rz4sDu8oUx4q39hhv8o2k2e72dkb]

Hello!
I’ve been running digibyted for years with the following line in my config to publish ZMQ hash blocks via a local Unix socket (to avoid TCP connections and reduce latency):

zmqpubhashblock=ipc:///tmp/dgb.hashblock

After upgrading DigiByte Core from v8.22.2 to v8.26.1, my systemd service started crashing immediately after launch.

When I tried running the QT GUI version to debug the issue, I received the following error message:

The node fails to start, displaying the “Invalid port specified” error, apparently rejecting ipc:// endpoints.

It seems that the logic has changed and the program now expects a TCP port (e.g. tcp://127.0.0.1:XXXX), but my setup uses a Unix domain socket (ipc://) instead.
I carefully read through the release notes and changelogs, but found no mention of any changes to the zmqpubhashblock configuration behavior.

Please clarify whether this was an intentional change or a regression.
If unintentional, it would be great to restore support for Unix domain sockets (ipc://) since they provide lower latency and local-only communication without the need for TCP ports.
zmqpubhashblock should continue to accept both ipc:// and tcp:// endpoints, as it did in previous versions (v8.22.2 and earlier).

Thanks for your time and the great work on DigiByte Core!

I am running DigiByte Core v8.26.1 on x86_64 Linux with xUbuntu 24.04.

[JaredTate]

Thank you for bringing this to our attention and for the detailed bug report! You've identified a regression bug that affects users who rely on Unix domain sockets (IPC) for ZMQ notifications.

After investigating, here's what's going on:

---

TL;DR - What's Happening

The Bad News:

• This is a confirmed regression bug in DigiByte v8.26.1
• Your configuration zmqpubhashblock=ipc:///tmp/dgb.hashblock worked perfectly in v8.22.2
• It's broken in v8.26.1 due to code inherited from Bitcoin Core v26.2
• You're not doing anything wrong - the software has a bug

The Good News:

• This was already fixed in Bitcoin Core v28.0 (April 2024)
• We can backport the fix to DigiByte
• There are workarounds available right now

---

Quick Fix - What You Can Do Right Now

If you need to get your node running immediately, change your config from:

# OLD (broken in v8.26):
zmqpubhashblock=ipc:///tmp/dgb.hashblock

To:

# NEW (works in v8.26):
zmqpubhashblock=tcp://127.0.0.1:212024

What this does:

• Uses TCP socket instead of Unix domain socket (IPC)
• Your node will start without errors
• Minimal performance difference for most use cases
• You can switch back to IPC once we release the fix

Alternative: Downgrade to v8.22.2 where IPC sockets work

---

What's the Issue? (Plain English Explanation)

Background: ZMQ and Unix Sockets

Think of ZMQ (ZeroMQ) as a notification system that lets DigiByte tell other programs when important events happen (like a new block being found).

There are two ways to set up these notifications:

1. TCP sockets - Like a phone number: tcp://127.0.0.1:212024
2. Unix domain sockets (IPC) - Like a file path: ipc:///tmp/dgb.hashblock

Unix sockets (IPC) are faster and more secure for local communication because:

• They don't use network overhead (no TCP/IP stack)
• Access is controlled by file system permissions
• They can't be accessed remotely (local-only by design)

The Problem

When DigiByte v8.26 was created, it merged code from Bitcoin Core v26.2. That Bitcoin version introduced strict validation that checks if all ZMQ addresses have valid port numbers.

The problem? Unix domain sockets don't use port numbers - they use file paths!

So when you configure:

zmqpubhashblock=ipc:///tmp/dgb.hashblock

The validation code tries to find a port number in /tmp/dgb.hashblock, fails to find one, and crashes the node with:

Invalid port specified in -zmqpubhashblock: 'ipc:///tmp/dgb.hashblock'

This is exactly the error you're seeing!

Why It's Broken - The Technical Deep Dive

To understand why this breaks, we need to look at what happens when DigiByte starts up with your configuration.

What Bitcoin Core v26.2 Added

Bitcoin Core v26.2 introduced centralized validation for all network-related configuration options. The goal was to catch configuration errors early (during startup) rather than failing later when trying to use the connection.

The validation code checks if socket addresses have valid port numbers by using a function called SplitHostPort().

How SplitHostPort() Works

The SplitHostPort() function (located in src/util/strencodings.cpp:100) parses addresses in the format host:port:

Expected formats:

• 127.0.0.1:212024 → host: 127.0.0.1, port: 212024 ✅
• localhost:212024 → host: localhost, port: 212024 ✅
• [::1]:212024 → host: ::1 (IPv6), port: 212024 ✅

The parsing logic:

1. Find the last : character in the address
2. Everything before : is the host
3. Everything after : should be a valid port number (1-65535)
4. Return true if a valid port was found, false otherwise

What Happens with IPC Sockets

When you configure ipc:///tmp/dgb.hashblock, here's what happens:

Step 1: The validation code runs during startup:

for (const std::string port_option : {"-zmqpubhashblock", ...}) {
    for (const std::string& socket_addr : args.GetArgs(port_option)) {
        std::string host_out;
        uint16_t port_out{0};
        if (!SplitHostPort(socket_addr, port_out, host_out)) {
            // If this returns false, initialization fails!
            return InitError(InvalidPortErrMsg(port_option, socket_addr));
        }
    }
}

Step 2: SplitHostPort() receives: ipc:///tmp/dgb.hashblock

Step 3: It finds the last : character → position is after ipc

Step 4: It tries to parse //tmp/dgb.hashblock as a port number

Step 5: //tmp/dgb.hashblock is not a valid number (must be 1-65535)

Step 6: Function returns false (validation failed!)

Step 7: DigiByte crashes with error:

Invalid port specified in -zmqpubhashblock: 'ipc:///tmp/dgb.hashblock'

Why This Validation Doesn't Make Sense for IPC

The fundamental problem is that Unix domain sockets don't have or need port numbers. They're identified by filesystem paths, not network addresses.

• TCP socket: tcp://127.0.0.1:212024 → needs IP and port
• Unix socket: ipc:///tmp/dgb.hashblock → only needs filesystem path

The validation code incorrectly assumes ALL socket addresses must have the format host:port, which is only true for TCP/IP sockets, not Unix domain sockets.

Why It Worked in v8.22.2

DigiByte v8.22.2 (and earlier) didn't have this validation code. Configuration options were passed directly to ZMQ without validation, and ZMQ's libzmq library knew how to handle both:

• tcp://127.0.0.1:212024 → TCP socket
• ipc:///tmp/dgb.hashblock → Unix domain socket

The validation was only performed when ZMQ actually tried to use the address, at which point libzmq would handle it correctly.

Why Bitcoin Core v26.2 Broke It

The Bitcoin Core developers added this validation to catch configuration errors early, but they didn't account for Unix domain sockets in their initial implementation. This was an oversight that was discovered and fixed in Bitcoin Core v28.0 when they explicitly added Unix socket support.

Timeline: When It Worked, When It Broke, When It Was Fixed

Version	Status	Details
DigiByte v8.22.2	✅ Worked	No strict validation - IPC sockets worked fine
Bitcoin Core v26.2	❌ Broken	Added validation that breaks IPC sockets
DigiByte v8.26.1	❌ Broken	Inherited the bug from Bitcoin v26.2
Bitcoin Core v28.0	✅ Fixed	Added proper Unix socket support (April 2024)
DigiByte Future	⏳ Pending	Fix needs to be backported

---

Workarounds You Can Use Right Now

Option 1: Use TCP Instead of IPC (Recommended for Now)

Change your configuration from:

# OLD (broken in v8.26):
zmqpubhashblock=ipc:///tmp/dgb.hashblock

To:

# NEW (works in v8.26):
zmqpubhashblock=tcp://127.0.0.1:212024

Pros:

• Works immediately
• No need to downgrade

Cons:

• Slightly slower (minimal difference for most use cases)
• Uses network stack instead of filesystem
• Requires port management

Option 2: Downgrade to v8.22.2

Stay on the previous version until the fix is released in a future DigiByte update.

Pros:

• IPC sockets work as expected
• Your existing configuration works unchanged

Cons:

• Missing other v8.26 features and fixes

---

The Technical Details (For Those Interested)

How Bitcoin Core Fixed It

Bitcoin Core fixed this issue in two stages:

1. Bitcoin Core PR #27375 (March 2024)

Link: bitcoin/bitcoin#27375

Title: "net: support unix domain sockets for -proxy and -onion"

This PR added Unix socket support for proxy connections and created the infrastructure needed.

2. Bitcoin Core PR #27679 (April 2024)

Link: bitcoin/bitcoin#27679

Title: "ZMQ: Support UNIX domain sockets"

This PR extended Unix socket support to ZMQ notifications specifically.

Key commits:

• Main fix: c87b0a0ff4cb6d83bb59360ac4453f6daa871177
• Merged into Bitcoin Core v28.0 on April 22, 2024

How the Fix Works

The fix allows certain options (including all ZMQ options) to bypass port validation when they use Unix sockets.

The Code Change Explained

Before (Broken - v8.26.1):

// All ZMQ options MUST pass port validation
for (const std::string port_option : {"-zmqpubhashblock", ...}) {
    for (const std::string& socket_addr : args.GetArgs(port_option)) {
        std::string host_out;
        uint16_t port_out{0};

        // Try to split into host:port
        if (!SplitHostPort(socket_addr, port_out, host_out)) {
            // ❌ FAILS for "ipc:///tmp/dgb.hashblock"
            //    because it can't find a valid port number
            return InitError(InvalidPortErrMsg(port_option, socket_addr));
        }
    }
}

After (Fixed - Bitcoin v28.0):

// Each option has a flag indicating if it supports Unix sockets
for (const auto &port_option : std::vector<std::pair<std::string, bool>>{
    // Option name              Unix socket support?
    {"-zmqpubhashblock",        true},   // ✅ Yes
    {"-zmqpubhashtx",           true},   // ✅ Yes
    {"-zmqpubrawblock",         true},   // ✅ Yes
    {"-zmqpubrawtx",            true},   // ✅ Yes
    {"-zmqpubsequence",         true},   // ✅ Yes
    {"-rpcbind",                false},  // ❌ No (must have port)
    ...
}) {
    const std::string arg{port_option.first};
    const bool unix{port_option.second};  // Does this support Unix sockets?

    for (const std::string& socket_addr : args.GetArgs(arg)) {
        std::string host_out;
        uint16_t port_out{0};

        // Try to split into host:port
        if (!SplitHostPort(socket_addr, port_out, host_out)) {
            #if HAVE_SOCKADDR_UN
            // NEW: Check if this is a Unix socket
            if (unix && socket_addr.find(ADDR_PREFIX_UNIX) == 0) {
                continue;  // ✅ Skip validation for "unix://..." addresses
            }
            #endif
            // If not a Unix socket, validation failed
            return InitError(InvalidPortErrMsg(arg, socket_addr));
        }
    }
}

How It Works Step-by-Step

Scenario: User configures zmqpubhashblock=unix:///tmp/dgb.hashblock

1. Loop encounters -zmqpubhashblock with unix = true
2. Tries SplitHostPort("unix:///tmp/dgb.hashblock", ...)
3. Function returns false (can't parse as host:port)
4. NEW CHECK: Is unix flag true? YES
5. NEW CHECK: Does address start with unix://? YES
6. Result: Skip the error, continue to next option ✅

Scenario: User configures rpcbind=unix:///tmp/rpc.sock

1. Loop encounters -rpcbind with unix = false
2. Tries SplitHostPort("unix:///tmp/rpc.sock", ...)
3. Function returns false (can't parse as host:port)
4. NEW CHECK: Is unix flag true? NO
5. Result: Validation fails, show error ❌ (correct behavior - RPC must use TCP)

The Prefix Conversion

Additionally, the fix converts the unix:// prefix to ipc:// internally in src/zmq/zmqnotificationinterface.cpp:

for (std::string& address : gArgs.GetArgs(arg)) {
    // libzmq uses prefix "ipc://" for UNIX domain sockets
    if (address.substr(0, ADDR_PREFIX_UNIX.length()) == ADDR_PREFIX_UNIX) {
        // Convert: "unix:///tmp/socket" → "ipc:///tmp/socket"
        address.replace(0, ADDR_PREFIX_UNIX.length(), ADDR_PREFIX_IPC);
    }
    // Now pass "ipc:///tmp/socket" to libzmq
}

This is necessary because:

• Bitcoin Core uses unix:// for consistency with -proxy and -onion options
• libzmq (the ZMQ library) expects ipc:// for Unix domain sockets
• The conversion happens transparently inside DigiByte

Error Location in Code

• File: src/init.cpp lines 1380-1400 (DigiByte v8.26.1)
• Function: SplitHostPort() in src/util/strencodings.cpp:100
  • Expects format host:port
  • Returns false when it cannot extract a valid port number
  • This causes the "Invalid port specified" error

---

What Needs to Happen (For DigiByte Developers)

Immediate Action Required

Cherry-pick the following commits from Bitcoin Core v28.0 into DigiByte:

1. Primary fix: Commit c87b0a0ff4 from PR #27679

   • Files modified:
     • src/init.cpp - Update validation logic
     • src/zmq/zmqnotificationinterface.cpp - Handle unix→ipc prefix conversion
     • src/zmq/zmqutil.h - Add ADDR_PREFIX_IPC constant

2. Dependencies: May also need commit 0ed2c130e7 from PR #27375 for base infrastructure

Configuration Syntax Note

Important: The Bitcoin Core v28 fix uses unix:// prefix (not ipc://).

After applying the fix, users would need to change their config:

Current (v8.22.2 - works):

zmqpubhashblock=ipc:///tmp/dgb.hashblock

Bitcoin v28 syntax:

zmqpubhashblock=unix:///tmp/dgb.hashblock

Recommendation for DigiByte: Consider also accepting ipc:// directly for backward compatibility with existing DigiByte configurations. This would require a minor modification to the Bitcoin Core fix but would prevent breaking existing user configs.

Testing

The fix includes comprehensive functional tests in test/functional/interface_zmq.py that should be adapted for DigiByte's test suite.

Documentation Updates

Current documentation (doc/zmq.md:88) shows IPC examples:

-zmqpubrawtx=ipc:///tmp/digibyted.tx.raw

After the fix, update to recommend unix:// prefix (or document that both ipc:// and unix:// are supported).

---

Additional Technical Information

ZMQ Library Behavior

libzmq natively supports IPC sockets with the ipc:// prefix:

• Documentation: https://libzmq.readthedocs.io/en/latest/zmq_ipc.html
• Format: ipc:///path/to/socket (note three slashes)

The Bitcoin fix uses unix:// for consistency with -proxy and -onion options, then converts to ipc:// internally.

---

References

• Bitcoin Core PR #27375: net: support unix domain sockets for -proxy and -onion bitcoin/bitcoin#27375
• Bitcoin Core PR #27679: ZMQ: Support UNIX domain sockets bitcoin/bitcoin#27679
• Bitcoin Core v28.0 Release Notes: https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-28.0.md
• libzmq IPC Documentation: https://libzmq.readthedocs.io/en/latest/zmq_ipc.html
• DigiByte ZMQ Documentation: doc/zmq.md

---

Summary for You

This was NOT an intentional change - it's a regression that slipped through during the Bitcoin Core v26.2 merge. Your setup with ipc:///tmp/dgb.hashblock worked correctly in v8.22.2 and should continue to work in future versions once we backport the fix.

For now, please use the TCP workaround (tcp://127.0.0.1:212024) or stay on v8.22.2 until we release a fixed version.

Note on port 212024: We suggest using port 212024 for ZMQ on mainnet (related to DigiByte's mainnet P2P port 12024). This distinguishes it from other applications and improves connectivity.

Thank you again for the detailed report and for your patience!

---

Contact / Issue Reporting:

• DigiByte GitHub Issues: https://github.com/digibyte-core/digibyte/issues
• DigiByte Discord: https://discord.gg/kKJ3NJz

---

Document created: 2025-11-03

Last updated: 2025-11-03

DigiByte Version Affected: v8.26.1

Fix Available In: Bitcoin Core v28.0 (not yet backported to DigiByte)

[8eS3rz4sDu8oUx4q39hhv8o2k2e72dkb]

Thank you for confirming this, we will be waiting for a quick solution to this issue in new releases.

But for now I will downgrade to 8.22.2 for a while.

[JaredTate]

Thank you for confirming this, we will be waiting for a quick solution to this issue in new releases.

But for now I will downgrade to 8.22.2 for a while.

Why would you not first try the suggestion made?? Its not reccomended to downgrade:

Try (works in v8.26):

zmqpubhashblock=tcp://127.0.0.1:212024

[8eS3rz4sDu8oUx4q39hhv8o2k2e72dkb]

Yes, I tried, tcp:// works great but unfortunately, this method does not suit me for my tasks. I only work with sockets.

[ycagel]

Yes, I tried, tcp:// works great but unfortunately, this method does not suit me for my tasks. I only work with sockets.

Can we close this since @JaredTate has provided a solution?

[8eS3rz4sDu8oUx4q39hhv8o2k2e72dkb]

This is not a solution - it is a regression. Due to this limitation, I cannot upgrade to the latest version and must remain on the previous release. The code should be modified to match the behavior as it was in Bitcoin Core or Bitcoin Knots so the ZMQ protocol’s full functionality is restored.