Btcd RPC Client Freeze With GetBlockTemplate And Websocket

If you're experiencing issues with your btcd RPC client freezing, especially when calling .GetBlockTemplate shortly after a new block is received and the websocket interface is active, you're not alone. This article dives into a reported bug, its potential causes, and steps to reproduce it, offering a comprehensive understanding for developers and users alike.

Understanding the Issue

The primary problem occurs when the .GetBlockTemplate method is invoked immediately following the arrival of a new block, specifically when the websocket interface is in operation. In such scenarios, btcd may fail, causing GetBlockTemplate to hang indefinitely. Furthermore, attempts to shut down the client using .Shutdown() also result in a freeze, requiring a more forceful termination.

This issue can be particularly frustrating as it leads to unexpected downtime and necessitates manual intervention to restart the client. Let's delve deeper into the specifics to understand the root cause and potential solutions.

Environment Details

To effectively diagnose and address the problem, it's crucial to consider the environment in which it occurs. Here are some key environmental details associated with this bug:

• Version of btcd: v0.25.0
• Operating System: EndeavourOS
• Relevant Dependencies:
  • github.com/btcsuite/btcd v0.25.0
  • github.com/btcsuite/btcd/btcutil v1.1.7-0.20251106010755-9ff0780da683
  • github.com/btcsuite/btcd/btcec/v2 v2.3.6 (indirect)
  • github.com/btcsuite/btclog v1.0.0 (indirect)
  • github.com/btcsuite/go-socks v0.0.0-20170105172521-4720035b7bfd (indirect)
  • github.com/btcsuite/websocket v0.0.0-20150119174127-31079b680792 (indirect)

These details offer a baseline for identifying potential conflicts or compatibility issues that might contribute to the freezing problem. Knowing the specific versions of btcd and its dependencies helps in pinpointing whether the bug is related to a particular release or interaction between components.

Steps to Reproduce the Freeze

Reproducing a bug consistently is crucial for effective debugging and resolution. Here are the steps to replicate the btcd client freeze:

1. Set up rpcclient using the websocket interface: Ensure your client is configured to communicate with btcd over websockets.
2. Trigger a gbt (GetBlockTemplate) call after new blocks arrive: This is the critical step where the bug manifests. Make the GetBlockTemplate call immediately after the client receives notification of a new block.
3. Wait for the freeze: In some instances, the freeze may occur after a few hours of operation, highlighting the intermittent nature of the issue.
4. Attempt to terminate the client with SIGINT: Send an interrupt signal to the process to initiate a graceful shutdown.
5. Observe that the client does not stop: The expected behavior is for the client to shut down cleanly, but in this case, it will remain frozen.

By following these steps, you can reliably reproduce the bug and gain a better understanding of its behavior.

Error Messages and Logs

Analyzing error messages and logs is essential for diagnosing the root cause of any software issue. In this particular case, the following error message has been observed in the btcd logs:

2025-11-14 04:01:43.355 [DBG] RPCS: Received command <getblocktemplate> from [::1]:44984  # erroring gbt
2025-11-14 04:01:43.355 [DBG] MINR: Considering 2987 transactions for inclusion to new block
2025-11-14 04:01:43.853 [ERR] RPCS: Failed to create new block template: previous block must be the current chain tip 00000000000000000000a6c2839f8c2bea4f7b31c63f4bce11303007f85b3653, instead got 000000000000000000002a22ca81d279bd95d772b7c8fa3e5ed7a0ba303b0694
2025-11-14 04:01:44.356 [DBG] RPCS: Received command <getblocktemplate> from [::1]:44984  # retry loop, iter 1
2025-11-14 04:01:44.356 [DBG] MINR: Considering 573 transactions for inclusion to new block
2025-11-14 04:01:44.657 [DBG] MINR: Created new block template (501 transactions, 361584 in fees, 2031 signature operations cost, 3875333 weight, target difficulty 00000000000000000001d9360000000000000000000000000000000000000000)
2025-11-14 04:01:44.657 [DBG] RPCS: Generated block template (timestamp 2025-11-14 04:01:44 -0500 EST, target 00000000000000000001d9360000000000000000000000000000000000000000, merkle root 16fff92883e2c19c15062f2f727352734ca537ed37030fd7127b3db7688e5729)
# this is where gbt hangs in the code snippet

This log excerpt reveals a critical error: "Failed to create new block template: previous block must be the current chain tip." This error suggests a synchronization issue where the client attempts to create a block template using an outdated chain tip. The subsequent retry loop indicates that the client is attempting to recover, but ultimately the GetBlockTemplate call hangs.

Code Sample

To provide a clearer understanding of the bug and its context, here’s a code sample that triggers the issue:

package main

import (
	"log"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/btcsuite/btcd/btcjson"
	"github.com/btcsuite/btcd/btcutil"
	"github.com/btcsuite/btcd/rpcclient"
	"github.com/btcsuite/btcd/wire"
)

func main() {
	sigs := make(chan os.Signal, 1)
	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)

	triggerGBT := make(chan struct{})
	backendConnConf := &rpcclient.ConnConfig{
		Host:         "localhost:8334",
		DisableTLS:   true,
		HTTPPostMode: false,
		Endpoint:     "ws",
		User:         "btcd",
		Pass:         "btcd",
	}
	backend, err := rpcclient.New(backendConnConf, &rpcclient.NotificationHandlers{
		OnFilteredBlockConnected: func(height int32, header *wire.BlockHeader, _ []*btcutil.Tx) {
			log.Printf("new block %d\n%s\n", height, header.BlockHash())
			/// GBT fail trigger
			triggerGBT <- struct{}{}
		},
		OnFilteredBlockDisconnected: func(_ int32, _ *wire.BlockHeader) {},
	})
	if err != nil {
		log.Panicf("failed to connect to backend: %s", err)
	}
	if err := backend.NotifyBlocks(); err != nil {
		log.Panicf("failed to subscribe to block notifications: %s", err)
	}
	go func() {
		log.Print("waiting for blocks...")
		for {
			template, err := backend.GetBlockTemplate(&btcjson.TemplateRequest{
				Rules:        []string{"segwit"}, /// required by gbt
				Capabilities: []string{"proposal", "coinbasevalue", "longpoll"},
				Mode:         "template",
			})
			if err != nil {
				log.Printf("error fetching template: %s\n", err)
				time.Sleep(time.Millisecond * 500)
				continue
			}
			log.Printf("gbt success, %d txns\n", len(template.Transactions))
			<-triggerGBT
		}
	}()
	<-sigs
	log.Println("shutting down")
	backend.Shutdown() /// Doesn't progress past here
	log.Println("waiting for shutdown")
	backend.WaitForShutdown()
}

This Go code sets up an RPC client using the websocket interface, subscribes to block notifications, and triggers a GetBlockTemplate call upon receiving a new block. The critical part is the triggerGBT channel, which signals the GetBlockTemplate request immediately after a new block is connected. This sequence of events consistently leads to the freezing issue.

Expected vs. Actual Behavior

The expected behavior is that the client should process the GetBlockTemplate request without freezing, even if it's called shortly after a new block arrives. The client should also shut down gracefully when a SIGINT signal is received.

However, the actual behavior observed is that the client freezes when GetBlockTemplate is called immediately after a new block, and it fails to shut down gracefully, requiring a SIGKILL signal for termination. This discrepancy highlights a significant bug that needs addressing.

Potential Causes and Solutions

Based on the error messages and the steps to reproduce, several potential causes for this issue can be identified:

1. Synchronization Issues: The error "previous block must be the current chain tip" suggests a race condition or synchronization problem between the block notification mechanism and the GetBlockTemplate call. The client might be attempting to create a template based on a block that is no longer the tip of the chain.
2. Websocket Handling: The fact that the issue occurs specifically when using the websocket interface points to a potential problem in how btcd handles concurrent requests or notifications over websockets.
3. Resource Contention: It's possible that the GetBlockTemplate call and the block processing logic are contending for the same resources, leading to a deadlock or freeze.

To address these potential causes, the following solutions could be explored:

• Implement Proper Synchronization: Ensure that the GetBlockTemplate call is synchronized with the chain tip update. This might involve using locks or channels to coordinate access to the chain state.
• Review Websocket Handling: Investigate the websocket handling logic in btcd for potential concurrency issues or deadlocks. Ensure that notifications and RPC calls are processed in a thread-safe manner.
• Optimize Resource Management: Analyze resource usage during block processing and GetBlockTemplate calls to identify and eliminate any contention points.
• Rate Limiting: Implementing rate limiting for GetBlockTemplate calls immediately after block arrival could mitigate synchronization issues by allowing the chain tip to fully update.

Conclusion

The btcd RPC client freezing issue when using GetBlockTemplate with the websocket interface is a significant bug that can disrupt mining operations and other applications relying on btcd. By understanding the steps to reproduce, the error messages, and the potential causes, developers can work towards implementing effective solutions. Proper synchronization, careful websocket handling, and optimized resource management are key areas to focus on to resolve this issue and ensure the stability of btcd clients.

For further information and discussions on Bitcoin development, you can visit the Bitcoin Wiki.