PoC: integration test for option_htlcs_claim_tx

.github/workflows/benchmarks.yml

@@ -31,13 +31,18 @@ jobs:
         uses: actions/cache@v4
         with:
           path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
-          key: electrs-${{ runner.os }}-${{ runner.arch }}
-      - name: Download bitcoind/electrs
-        if: "(steps.cache-bitcoind.outputs.cache-hit != 'true' || steps.cache-electrs.outputs.cache-hit != 'true')"
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download bitcoind
+        if: "steps.cache-bitcoind.outputs.cache-hit != 'true'"
         run: |
-          source ./scripts/download_bitcoind_electrs.sh
+          source ./scripts/download_bitcoind.sh
           mkdir -p bin
           mv "$BITCOIND_EXE" bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./scripts/build_electrs.sh
+          mkdir -p bin
           mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
       - name: Set bitcoind/electrs environment variables
         run: |

.github/workflows/hrn-integration.yml

@@ -28,13 +28,18 @@ jobs:
         uses: actions/cache@v4
         with:
           path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
-          key: electrs-${{ runner.os }}-${{ runner.arch }}
-      - name: Download bitcoind/electrs
-        if: "steps.cache-bitcoind.outputs.cache-hit != 'true' || steps.cache-electrs.outputs.cache-hit != 'true'"
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download bitcoind
+        if: "steps.cache-bitcoind.outputs.cache-hit != 'true'"
         run: |
-          source ./scripts/download_bitcoind_electrs.sh
+          source ./scripts/download_bitcoind.sh
           mkdir -p bin
           mv "$BITCOIND_EXE" bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./scripts/build_electrs.sh
+          mkdir -p bin
           mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
       - name: Set bitcoind/electrs environment variables
         run: |

.github/workflows/postgres-integration.yml

@@ -43,13 +43,18 @@ jobs:
         uses: actions/cache@v4
         with:
           path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
-          key: electrs-esplora_a33e97e1-${{ runner.os }}-${{ runner.arch }}
-      - name: Download bitcoind/electrs
-        if: "steps.cache-bitcoind.outputs.cache-hit != 'true' || steps.cache-electrs.outputs.cache-hit != 'true'"
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download bitcoind
+        if: "steps.cache-bitcoind.outputs.cache-hit != 'true'"
         run: |
-          source ./scripts/download_bitcoind_electrs.sh
+          source ./scripts/download_bitcoind.sh
           mkdir -p bin
           mv "$BITCOIND_EXE" bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./scripts/build_electrs.sh
+          mkdir -p bin
           mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
       - name: Set bitcoind/electrs environment variables
         run: |

.github/workflows/rust.yml

@@ -60,23 +60,30 @@ jobs:
         uses: actions/cache@v4
         with:
           path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
-          key: electrs-${{ runner.os }}-${{ runner.arch }}
-      - name: Download bitcoind/electrs
-        if: "matrix.platform != 'windows-latest' && (steps.cache-bitcoind.outputs.cache-hit != 'true' || steps.cache-electrs.outputs.cache-hit != 'true')"
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download bitcoind
+        if: "matrix.platform != 'windows-latest' && steps.cache-bitcoind.outputs.cache-hit != 'true'"
         run: |
-          source ./scripts/download_bitcoind_electrs.sh
+          source ./scripts/download_bitcoind.sh
           mkdir -p bin
           mv "$BITCOIND_EXE" bin/bitcoind-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "matrix.platform != 'windows-latest' && steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./scripts/build_electrs.sh
+          mkdir -p bin
           mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
       - name: Set bitcoind/electrs environment variables
         run: |
           echo "BITCOIND_EXE=$( pwd )/bin/bitcoind-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
           echo "ELECTRS_EXE=$( pwd )/bin/electrs-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
       - name: Build on Rust ${{ matrix.toolchain }}
-        run: cargo build --verbose --color always
+        run: |
+          cargo build --verbose --color always
       - name: Build with UniFFI support on Rust ${{ matrix.toolchain }}
         if: matrix.build-uniffi
-        run: cargo build --features uniffi --verbose --color always
+        run: |
+          cargo build --features uniffi --verbose --color always
       - name: Check release build on Rust ${{ matrix.toolchain }}
         run: cargo check --release --verbose --color always
       - name: Check release build with UniFFI support on Rust ${{ matrix.toolchain }}

.github/workflows/vss-integration.yml

@@ -31,6 +31,21 @@ jobs:
         uses: actions/checkout@v6
         with:
           path: ldk-node
+      - name: Enable caching for electrs
+        id: cache-electrs
+        uses: actions/cache@v5
+        with:
+          path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./ldk-node/scripts/build_electrs.sh
+          mkdir -p bin
+          mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
+      - name: Set electrs environment variable
+        run: |
+          echo "ELECTRS_EXE=$( pwd )/bin/electrs-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
       - name: Checkout VSS
         uses: actions/checkout@v6
         with:

.github/workflows/vss-no-auth-integration.yml

@@ -31,6 +31,21 @@ jobs:
         uses: actions/checkout@v6
         with:
           path: ldk-node
+      - name: Enable caching for electrs
+        id: cache-electrs
+        uses: actions/cache@v5
+        with:
+          path: bin/electrs-${{ runner.os }}-${{ runner.arch }}
+          key: electrs-submit-package-${{ runner.os }}-${{ runner.arch }}
+      - name: Download electrs
+        if: "steps.cache-electrs.outputs.cache-hit != 'true'"
+        run: |
+          source ./ldk-node/scripts/build_electrs.sh
+          mkdir -p bin
+          mv "$ELECTRS_EXE" bin/electrs-${{ runner.os }}-${{ runner.arch }}
+      - name: Set electrs environment variable
+        run: |
+          echo "ELECTRS_EXE=$( pwd )/bin/electrs-${{ runner.os }}-${{ runner.arch }}" >> "$GITHUB_ENV"
       - name: Checkout VSS
         uses: actions/checkout@v6
         with:

CHANGELOG.md

@@ -5,6 +5,10 @@
   prior LSPS2 fee-limit state stored in `PaymentKind::Bolt11Jit` is not migrated.
 - Users of the VSS storage backend must upgrade their VSS server to at least version
   `v0.1.0-alpha.0` before upgrading LDK Node.
+- Usage of anchor channels now requires that the Bitcoin node used to broadcast transactions relays
+  TRUC, P2A, and ephemeral dust. Bitcoin Core v29 and above satisfy this requirement. Esplora chain
+  sources also need to support the `/txs/package` endpoint, and Electrum chain sources need to
+  support the `broadcast_package` method added in Electrum protocol v1.6.
 
 ## Feature and API updates
 - The Bitcoin Core RPC and REST chain-source builder methods now accept an optional
@@ -16,6 +20,17 @@
 - `EsploraSyncConfig` and `ElectrumSyncConfig` now support `force_wallet_full_scan`. When set,
   the on-chain wallet keeps using BDK `full_scan` instead of incremental sync until a full scan
   succeeds, allowing restored wallets to rediscover funds sent to previously-unknown addresses.
+- Experimental support for the `option_htlcs_claim_tx` channel type has been added via a new
+  `AnchorChannelsConfig::negotiate_htlcs_claim_tx` option (default `false`). When enabled, channels
+  negotiate (on top of zero-fee commitments) a channel type that commits, via `OP_TEMPLATEHASH`
+  (BIP-446/448), to a fixed version 3 claim transaction in the preimage spend path of offered HTLC
+  outputs, closing the last on-chain pinning vector in Lightning. On-chain resolution of such an
+  offered HTLC broadcasts the zero-fee, template-committed claim transaction together with a
+  fee-paying child as a TRUC 1-parent-1-child package (via Bitcoin Core's `submitpackage`). It
+  depends on the `OP_TEMPLATEHASH` soft fork, pulled in via a `bitcoin` fork through
+  `[patch.crates-io]`. The zero-fee commitment groundwork this builds on is adapted from ldk-node
+  PR #660. *(This feature was
+  developed with the assistance of Claude, an AI tool.)*
 
 ## Bug Fixes and Improvements
 - Building a fresh node against a Bitcoin Core RPC or REST chain source that fails to return the

Cargo.toml

@@ -41,6 +41,13 @@ postgres = ["dep:tokio-postgres", "dep:native-tls", "dep:postgres-native-tls"]
 #lightning-macros = { version = "0.2.0" }
 #lightning-dns-resolver = { version = "0.3.0" }
 
+# EXPERIMENTAL: these are redirected by the `[patch]` section at the bottom of this manifest to the
+# public `templatehash_antipinning` branch of https://github.com/darosior/rust-lightning (= upstream
+# main + the `option_htlcs_claim_tx` / OP_TEMPLATEHASH anti-pinning commits). The patch targets the
+# git URL so that *all* consumers in the graph (including `bitcoin-payment-instructions`, which also
+# depends on `lightning` from this URL) resolve to the same crate instance. The `rev` below is
+# nominal and overridden by the patch; swap both back to a real published `rev` once the branch
+# lands upstream.
 lightning = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "3dfcc4cca1866c5e5d4d4eaf3b82e09584e2ce5c", features = ["std"] }
 lightning-types = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "3dfcc4cca1866c5e5d4d4eaf3b82e09584e2ce5c" }
 lightning-invoice = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "3dfcc4cca1866c5e5d4d4eaf3b82e09584e2ce5c", features = ["std"] }
@@ -123,6 +130,39 @@ panic = "abort"
 [profile.dev]
 panic = "abort"
 
+# EXPERIMENTAL: the `option_htlcs_claim_tx` channel type relies on the `OP_TEMPLATEHASH`
+# (BIP-446/448) opcode, which is not yet available in a released `bitcoin`. Pull it from a fork
+# that cherry-picks BIP-446/448 onto the same `bitcoin` patch release we otherwise depend on. This
+# mirrors the identical patch in rust-lightning's own Cargo.toml (patch sections only apply from
+# the root workspace, so it must be declared here too).
+[patch.crates-io]
+bitcoin = { git = "https://github.com/darosior/rust-bitcoin", branch = "bip448-0.32.4" }
+# The fork's `bitcoin` pulls its own `bitcoin_hashes`/`bitcoin-units`; patch those to the same fork
+# too so the whole graph (including dev-dependencies like `electrsd`/`corepc-node` that depend on
+# `bitcoin_hashes` directly from crates.io) resolves to a single instance, avoiding "multiple
+# versions of crate bitcoin_hashes" type mismatches (e.g. on `Txid`) when building all targets.
+bitcoin_hashes = { git = "https://github.com/darosior/rust-bitcoin", branch = "bip448-0.32.4" }
+bitcoin-units = { git = "https://github.com/darosior/rust-bitcoin", branch = "bip448-0.32.4" }
+
+# EXPERIMENTAL: redirect the rust-lightning git dependency (used both directly above and
+# transitively by `bitcoin-payment-instructions`) to the public `templatehash_antipinning` branch
+# that carries the `option_htlcs_claim_tx` / OP_TEMPLATEHASH work. Patching the git URL (rather than
+# using path deps directly) keeps the whole dependency graph on a single `lightning` crate instance,
+# avoiding "two versions of crate lightning" type mismatches. Drop this once the branch lands upstream.
+[patch."https://github.com/lightningdevkit/rust-lightning"]
+lightning = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-types = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-invoice = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-net-tokio = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-persister = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-background-processor = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-rapid-gossip-sync = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-block-sync = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-transaction-sync = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-liquidity = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-macros = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+lightning-dns-resolver = { git = "https://github.com/darosior/rust-lightning", branch = "templatehash_antipinning" }
+
 [lints.rust.unexpected_cfgs]
 level = "forbid"
 # When adding a new cfg attribute, ensure that it is added to this list.

bindings/ldk_node.udl

@@ -231,6 +231,7 @@ enum NodeError {
 	"LnurlAuthFailed",
 	"LnurlAuthTimeout",
 	"InvalidLnurl",
+	"ChainSourceNotSupported",
 };
 
 typedef dictionary NodeStatus;

scripts/build_electrs.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+set -eox pipefail
+
+# Our Esplora-based tests require `electrs` binaries. Here, we
+# download the code, build the binaries, and export their location
+# via `ELECTRS_EXE`/`BITCOIND_EXE` which will be used by the
+# `electrsd`/`bitcoind` crates in our tests.
+
+HOST_PLATFORM="$(rustc --version --verbose | grep "host:" | awk '{ print $2 }')"
+ELECTRS_GIT_REPO="https://github.com/tankyleo/blockstream-electrs.git"
+ELECTRS_TAG="2026-05-26-electrum-submit-package"
+ELECTRS_REV="8c06d8010e43f793b1a65f83695ea846e5cd83ed"
+if [[ "$HOST_PLATFORM" != *linux* && "$HOST_PLATFORM" != *darwin* ]]; then
+	printf "\n\n"
+	echo "Unsupported platform: $HOST_PLATFORM Exiting.."
+	exit 1
+fi
+
+DL_TMP_DIR=$(mktemp -d)
+trap 'rm -rf -- "$DL_TMP_DIR"' EXIT
+
+pushd "$DL_TMP_DIR"
+git clone --branch "$ELECTRS_TAG" --depth 1 "$ELECTRS_GIT_REPO" blockstream-electrs
+cd blockstream-electrs
+CURRENT_HEAD=$(git rev-parse HEAD)
+if [ "$CURRENT_HEAD" != "$ELECTRS_REV" ]; then
+  echo "ERROR: HEAD does not match expected commit"
+  echo "expected: $ELECTRS_REV"
+  echo "actual:   $CURRENT_HEAD"
+  exit 1
+fi
+RUSTFLAGS="" cargo build
+export ELECTRS_EXE="$DL_TMP_DIR"/blockstream-electrs/target/debug/electrs
+chmod +x "$ELECTRS_EXE"
+popd

scripts/download_bitcoind_electrs.sh → scripts/download_bitcoind.sh

@@ -1,24 +1,18 @@
 #!/bin/bash
 set -eox pipefail
 
-# Our Esplora-based tests require `electrs` and `bitcoind`
-# binaries. Here, we download the binaries, validate them, and export their
-# location via `ELECTRS_EXE`/`BITCOIND_EXE` which will be used by the
+# Our Esplora-based tests require `bitcoind` binaries. Here, we
+# download the binaries, validate them, and export their location
+# via `ELECTRS_EXE`/`BITCOIND_EXE` which will be used by the
 # `electrsd`/`bitcoind` crates in our tests.
 
 HOST_PLATFORM="$(rustc --version --verbose | grep "host:" | awk '{ print $2 }')"
-ELECTRS_DL_ENDPOINT="https://github.com/RCasatta/electrsd/releases/download/electrs_releases"
-ELECTRS_VERSION="esplora_a33e97e1a1fc63fa9c20a116bb92579bbf43b254"
 BITCOIND_DL_ENDPOINT="https://bitcoincore.org/bin/"
 BITCOIND_VERSION="29.0"
 if [[ "$HOST_PLATFORM" == *linux* ]]; then
-	ELECTRS_DL_FILE_NAME=electrs_linux_"$ELECTRS_VERSION".zip
-	ELECTRS_DL_HASH="865e26a96e8df77df01d96f2f569dcf9622fc87a8d99a9b8fe30861a4db9ddf1"
 	BITCOIND_DL_FILE_NAME=bitcoin-"$BITCOIND_VERSION"-x86_64-linux-gnu.tar.gz
 	BITCOIND_DL_HASH="a681e4f6ce524c338a105f214613605bac6c33d58c31dc5135bbc02bc458bb6c"
 elif [[ "$HOST_PLATFORM" == *darwin* ]]; then
-	ELECTRS_DL_FILE_NAME=electrs_macos_"$ELECTRS_VERSION".zip
-	ELECTRS_DL_HASH="2d5ff149e8a2482d3658e9b386830dfc40c8fbd7c175ca7cbac58240a9505bcd"
 	BITCOIND_DL_FILE_NAME=bitcoin-"$BITCOIND_VERSION"-x86_64-apple-darwin.tar.gz
 	BITCOIND_DL_HASH="5bb824fc86a15318d6a83a1b821ff4cd4b3d3d0e1ec3d162b805ccf7cae6fca8"
 else
@@ -31,13 +25,6 @@ DL_TMP_DIR=$(mktemp -d)
 trap 'rm -rf -- "$DL_TMP_DIR"' EXIT
 
 pushd "$DL_TMP_DIR"
-ELECTRS_DL_URL="$ELECTRS_DL_ENDPOINT"/"$ELECTRS_DL_FILE_NAME"
-curl -L -o "$ELECTRS_DL_FILE_NAME" "$ELECTRS_DL_URL"
-echo "$ELECTRS_DL_HASH  $ELECTRS_DL_FILE_NAME"|shasum -a 256 -c
-unzip "$ELECTRS_DL_FILE_NAME"
-export ELECTRS_EXE="$DL_TMP_DIR"/electrs
-chmod +x "$ELECTRS_EXE"
-
 BITCOIND_DL_URL="$BITCOIND_DL_ENDPOINT"/bitcoin-core-"$BITCOIND_VERSION"/"$BITCOIND_DL_FILE_NAME"
 curl -L -o "$BITCOIND_DL_FILE_NAME" "$BITCOIND_DL_URL"
 echo "$BITCOIND_DL_HASH  $BITCOIND_DL_FILE_NAME"|shasum -a 256 -c

src/builder.rs

@@ -2012,6 +2012,10 @@ fn build_with_store_internal(
 				Arc::clone(&channel_manager),
 				Arc::clone(&om_resolver),
 				IgnoringMessageHandler {},
+				// Don't intercept messages addressed to unknown SCIDs: our mailbox can only key by
+				// node id, so we'd be unable to forward them anyway (see the
+				// `OnionMessageIntercepted` handler).
+				false,
 			))
 		} else {
 			Arc::new(OnionMessenger::new(