Update Bitcoin Knots to 1.2.16

[Retropex]

Type

App update
Superseed #6038

App

App ID: bitcoin-knots
Upstream project: Bitcoin Knots
Version: v1.2.16

Summary

Add the BLAKE2b consensus code.

Verification

Umbrel testing performed:

Environment tested:

• Umbrel device
• Local umbrelOS test environment
• Not runtime tested

Architecture tested:

• amd64
• arm64

Hey @nmfretz @al-lac may I ask you to check on this?

[Retropex]

Hey @nmfretz @al-lac, any idea on when this will be merged?

[al-lac]

The team is probably working a lot on getting the 2.0 update ready. But @nmfretz or @kaichappel will get to it soon.

[Retropex]

Thanks!
Note that people already use that version by tweaking the git repo.
No bug has been encountered.
If you are worried about potential breaking bugs, I’m confident there is none.

[Retropex]

Hey guys, it's been almost two weeks since the original PR.
I understand you are busy with umbrel 2.0 but I need this merged please.

[nmfretz]

Really sorry @Retropex! Taking a look at this right now.

[nmfretz]

If you are worried about potential breaking bugs, I’m confident there is none.

Just to clarify, I’ll look at this specifically from an umbrelOS app ecosystem and packaging perspective. Even if Knots itself behaves exactly as intended, the protocol changes still break compatibility with other installed apps using it as their backend... because Knots currently declares implements: bitcoin, which tells umbrelOS that companion apps can use Knots as a compatible backend.

implements: bitcoin is a compatibility declaration in umbrelOS. It allows apps that depend on bitcoin, such as Electrs, Lightning Node, and Core Lightning, to use Knots as their backend. This isn’t a judgement about naming or what should be considered Bitcoin. It’s just about the interface and chain behaviour those existing apps expect.

The BLAKE2b changes break that compatibility once activated. I just tested activation in regtest. Core Lightning rejected the new block format and entered a restart loop, Electrs stopped answering requests, and LND stopped reporting itself as synced. So it's a breaking change for connected Umbrel apps (independently of any in-app bugs).

I think we should handle the update like this:

• Remove implements: bitcoin from the manifest, so Knots is no longer offered as a backend for apps using that dependency. And then apps compatible with the updated protocol could be submitted separately with an explicit bitcoin-knots dependency
• Add a prominent compatibility warning and instructions at the start of the release notes. Users can continue running Knots, but need to review connected apps before updating. Those who want to keep using affected apps will need to connect them to a compatible backend; others will need instructions for safely retiring those apps. For Lightning, this must include handling existing channels and funds before stopping or uninstalling

That'd let Knots continue receiving updates under the existing app id, while making the compatibility change explicit and preventing new incompatible connections.

Lemme just add some inline suggestions in a sec.

[nmfretz]

I’ve left some suggested changes below to handle the compatibility change and help users manage their existing connections. What do you think?

I’ve left the app description as-is. Would you like to update any of that wording for this release?

[nmfretz]

Remove this compatibility declaration so Knots is no longer offered as a backend for apps that depend on bitcoin.

-implements:
-  - bitcoin

Here’s the corresponding exports.sh update.

export APP_BITCOIN_KNOTS_NODE_IP="10.21.21.7"
export APP_BITCOIN_KNOTS_TOR_PROXY_IP="10.21.22.12"
export APP_BITCOIN_KNOTS_I2P_DAEMON_IP="10.21.22.13"

export APP_BITCOIN_KNOTS_DATA_DIR="${EXPORTS_APP_DIR}/data/bitcoin"
export APP_BITCOIN_KNOTS_RPC_PORT="9332"
export APP_BITCOIN_KNOTS_P2P_PORT="9333"
# Additional inbound P2P listener granting whitelisted permissions (whitebind) to this port; for trusted internal apps only; do not publish externally
export APP_BITCOIN_KNOTS_P2P_WHITEBIND_PORT="9335"
export APP_BITCOIN_KNOTS_TOR_PORT="8334"
export APP_BITCOIN_KNOTS_ZMQ_RAWBLOCK_PORT="48332"
export APP_BITCOIN_KNOTS_ZMQ_RAWTX_PORT="48333"
export APP_BITCOIN_KNOTS_ZMQ_HASHBLOCK_PORT="48334"
export APP_BITCOIN_KNOTS_ZMQ_SEQUENCE_PORT="48335"
export APP_BITCOIN_KNOTS_ZMQ_HASHTX_PORT="48336"

# These are legacy env vars we need to keep around for DATUM compatibility
export APP_BITCOIN_KNOTS_INTERNAL_RPC_PORT="9332"
export APP_BITCOIN_KNOTS_INTERNAL_P2P_PORT="9333"

export APP_BITCOIN_KNOTS_NETWORK="mainnet" 

# Check for an existing settings.json file to override APP_BITCOIN_KNOTS_NETWORK with user's choice
{
	BITCOIN_APP_CONFIG_FILE="${EXPORTS_APP_DIR}/data/app/settings.json"
	if [[ -f "${BITCOIN_APP_CONFIG_FILE}" ]]
	then
		bitcoin_app_network=$(jq -r '.chain' "${BITCOIN_APP_CONFIG_FILE}")
		case $bitcoin_app_network in
			"main")
				APP_BITCOIN_KNOTS_NETWORK="mainnet";;
			"test")
				APP_BITCOIN_KNOTS_NETWORK="testnet";;
			"testnet4")
				APP_BITCOIN_KNOTS_NETWORK="testnet4";;
			"signet")
				APP_BITCOIN_KNOTS_NETWORK="signet";;
			"regtest")
				APP_BITCOIN_KNOTS_NETWORK="regtest";;
			*)
				if [[ -n "$bitcoin_app_network" ]] && [[ "$bitcoin_app_network" != "null" ]]; then
					echo "Warning (${EXPORTS_APP_ID}): Invalid network '${bitcoin_app_network}' in settings.json. Exporting APP_BITCOIN_KNOTS_NETWORK as default 'mainnet'."
				fi;;
		esac
	fi
} > /dev/null || true

BITCOIN_ENV_FILE="${EXPORTS_APP_DIR}/.env"

if [[ ! -f "${BITCOIN_ENV_FILE}" ]]; then
	
	if [[ -z ${BITCOIN_RPC_USER+x} ]] || [[ -z ${BITCOIN_RPC_PASS+x} ]]; then
		BITCOIN_RPC_USER="umbrel"
		BITCOIN_RPC_DETAILS=$("${EXPORTS_APP_DIR}/scripts/rpcauth.py" "${BITCOIN_RPC_USER}")
		BITCOIN_RPC_PASS=$(echo "$BITCOIN_RPC_DETAILS" | tail -1)
	fi

	echo "export APP_BITCOIN_KNOTS_RPC_USER='${BITCOIN_RPC_USER}'"	>> "${BITCOIN_ENV_FILE}"
	echo "export APP_BITCOIN_KNOTS_RPC_PASS='${BITCOIN_RPC_PASS}'"	>> "${BITCOIN_ENV_FILE}"
fi

. "${BITCOIN_ENV_FILE}"

rpc_hidden_service_file="${EXPORTS_TOR_DATA_DIR}/app-${EXPORTS_APP_ID}-rpc/hostname"
p2p_hidden_service_file="${EXPORTS_TOR_DATA_DIR}/app-${EXPORTS_APP_ID}-p2p/hostname"
export APP_BITCOIN_KNOTS_RPC_HIDDEN_SERVICE="$(cat "${rpc_hidden_service_file}" 2>/dev/null || echo "notyetset.onion")"
export APP_BITCOIN_KNOTS_P2P_HIDDEN_SERVICE="$(cat "${p2p_hidden_service_file}" 2>/dev/null || echo "notyetset.onion")"

# electrs compatible network param
export APP_BITCOIN_KNOTS_NETWORK_ELECTRS=$APP_BITCOIN_KNOTS_NETWORK
if [[ "${APP_BITCOIN_KNOTS_NETWORK_ELECTRS}" = "mainnet" ]]; then
	APP_BITCOIN_KNOTS_NETWORK_ELECTRS="bitcoin"
fi

[nmfretz]

Here are the suggested release notes.

Suggested change

	Update to Bitcoin Knots v29.4.1.knots20260508
	🚨 This version adds BIP 110 code directly into the Bitcoin Knots codebase 🚨
	In order to avoid appyling this upgrade by accident, this version requires you to accept or switch to another version directly on the Umbrel UI.
	🚨 This version adds BLAKE2b hardfork code into the Bitcoin Knots codebase 🚨
	🚨 COMPATIBILITY CHANGE: Review connected apps before updating.
	This update adds Bitcoin Knots v29.4.1.knots20260508, which includes a BLAKE2b hard fork that changes the proof-of-work algorithm and block format at mainnet block 961,640.
	These protocol changes affect apps and wallets that use Knots as their Bitcoin backend, either directly or through another app. Before updating, review all of those connections, including anything connected through an indexer or Lightning node. Integrations that do not support the updated protocol may stop working or syncing.
	Knots will no longer be offered as a Bitcoin backend for other apps in umbrelOS. Existing connections will not be automatically disconnected or switched to another provider. Apps left connected may fail to start or stop syncing.
	You can continue running Knots after this update. For any connected apps that don’t support the updated protocol, you can choose to reconnect them to a compatible backend or safely stop using them, following the guidance below.
	If you choose to reconnect affected apps to another backend:
	1. Install and fully sync a compatible Bitcoin provider on the same chain and network your connected apps use.
	2. Open each affected app's settings in umbrelOS, select that provider, and save. If an app connects through an indexer, update the indexer's Bitcoin connection too. Update any manually configured wallet or RPC connections. Installing another provider alone does not change existing connections.
	3. Confirm each app reconnects and finishes syncing. Complete these steps before updating Knots to avoid interrupting those apps. You do not need to uninstall Knots.
	If you no longer want to use an affected app, stop it before updating rather than leaving it connected. Lightning users must complete the additional steps below before stopping their node.
	⚡ LIGHTNING NODE AND CORE LIGHTNING: Keep your node connected to a synced, compatible Bitcoin backend while you have open channels or unresolved payments or channel closures. Otherwise, it may miss channel activity and be unable to respond in time, putting funds at risk. When changing providers, confirm your node finishes syncing and existing channels are available. Do not uninstall or reset your Lightning app, or delete its wallet or channel data, to change the connection.
	If you want to retire your Lightning node, first close all channels and keep it running with a synced, compatible backend until all payments and channel closures are resolved and your funds are confirmed and spendable on-chain. Before uninstalling, withdraw any remaining wallet funds to a wallet you control and confirm receipt. Simply stopping the app does not safely retire the node.
	Already updated? You can still change affected apps' Bitcoin connections using the steps above. They may remain unavailable or out of sync until reconnected. If you have Lightning channels or unresolved payments or closures, restore a synced, compatible backend promptly, even if you intend to retire the node.
	Full upstream release notes: https://github.com/bitcoinknots/bitcoin/releases/tag/v29.4.1.knots20260508

[Retropex]

Thanks for the feedback @nmfretz! 🙏

While I understand the willingness to remove implements, we have to keep in mind that I know a lot of people that will stick to the older version of Bitcoin Nodes, which perfectly works with all other apps. It's simply because they don't want to go back to core due to the lack of customization options.

Additionally in the BLAKE2b ecosystem, a handful of third-party app stores have implemented apps with the bitcoin variable, not bitcoin-knots. Changing the variable now will break such apps from these app stores.
The same thing has been done with startOS, and it has brought a lot of confusion.