Bitcoin canister proposal 144665 fixes get_utxos prefix-address bug

NNS proposal 144665, submitted on November 2, 2026, upgrades the Bitcoin canister ghsi2-tqaaa-aaaan-aaaca-cai to release/2026-11-02. The new release stops get_utxos from returning UTXOs that belong to other, longer addresses whose string starts with the queried address. If your canister reads Bitcoin UTXOs, check the vote result, verify the Wasm hash and re-check your deposit records once the upgrade is live.

What changed in release/2026-11-02

The proposal gives one motivation: "Exclude other addresses from address UTXO range queries." The release range 4a7f021..e21267e contains two commits under canister/: the release chore (#552) and the fix a479aca fix: DEFI-3039: Exclude other addresses from address UTXO range queries (#551).

The facts from the proposal:

The GitHub release release/2026-11-02 lists the same SHA-256 for ic-btc-canister.wasm.gz and links back to proposal 144665.

Pull request #551 explains the bug. The canister keeps a stable index whose keys are address || height || outpoint, with no separator after the address. A range scan for one address could therefore also cover the keys of a longer address that starts with the same characters. The PR's example is a P2WSH address crafted to start with a P2WPKH address. The PR says these foreign UTXOs showed up on the first page and also when paginating.

The fix has three parts:

1. The range scan now starts at height MAX_ADDRESS_UTXO_HEIGHT (2^24 - 1). The first byte of that encoded height is 0xFF, which sorts after any ASCII address byte, so the scan never reaches keys of longer addresses.
2. The canister asserts that indexed heights stay at or below that limit. The check runs once per block in ingest_block and also in the offline state builder. Reaching the limit traps instead of returning an error.
3. As defence in depth, range results are filtered on the exact queried address. Debug builds panic on a mismatch, so a regression cannot hide behind the filter.

The PR states: "No data migration is needed." The canbench results in the PR show no significant instruction changes for bitcoin_get_utxos_baseline or bitcoin_get_utxos_stress.

Who is affected and why it matters

This affects any canister that reads Bitcoin UTXOs for an address through the Bitcoin canister's UTXO API. Typical cases are deposit detection, balance displays built from UTXO lists, and wallets that pick inputs from the returned UTXOs.

Before the fix, a query for a P2WPKH address could return outputs that the address does not control. The effects could include:

• A wallet canister that builds a transaction from those UTXOs produces inputs it cannot sign, so the transaction fails.
• A deposit flow that credits users based on the returned UTXOs could credit coins that the canister cannot spend.
• Pagination results could contain entries from another address, so page-by-page totals would be wrong.

To trigger the bug, someone has to send coins to an address whose string begins with your address. The PR shows that such a valid P2WSH address can be built. PR #551 does not report any case of this happening on mainnet. It describes the issue as a correctness fix with a regression test.

The new height limit of 2^24 - 1 (16,777,215) is far above the current Bitcoin block height. It does not affect callers today.

What to do now

The upgrade needs no code changes from callers: the API and the upgrade argument stay the same. Use this checklist:

1. Open proposal 144665 on the NNS dashboard and confirm it has been adopted and executed before you rely on the new behaviour.
2. If you vote or review NNS proposals, rebuild the Wasm and compare hashes. These commands from the proposal apply to commit e21267e:

git fetch
git checkout e21267ebd071a9f3745e04424d3293b76c96589c
"./scripts/docker-build" "ic-btc-canister"
sha256sum ./ic-btc-canister.wasm.gz
# expected: b539b2cef300cf2f30ab7080c1fcb8319ad5de04a4c7a8790f6050af4e06e4e8

3. Check the upgrade argument hash the same way:

didc encode -d canister/candid.did -t '(canister_arg)' '(variant { upgrade })' | xxd -r -p | sha256sum
# expected: 1c08f4660179db8e87a4a5060ca93ea2f476fed7c25a2bd92f9cf8375eff87d9

4. After execution, re-query get_utxos for the addresses your canister watches. Compare the results with the UTXOs you have already credited or spent. A recorded UTXO that no longer appears, and that your canister has not spent, is worth investigating.
5. If your deposit or wallet code caches UTXO lists across calls, refresh the cache after the upgrade, so that lists fetched before the fix are not reused.
6. If you test against a local Bitcoin canister, move your local setup to release/2026-11-02 so that your tests match mainnet behaviour.

Caveats

Check the vote result on the dashboard before you treat the new behaviour as live on mainnet. The fix depends on block heights staying below 2^24. The code asserts this and traps if the limit is reached, by design.