fix(utxo): correct block header deserialization for AuxPow and KAWPOW coins

[shamardy]

Resolves #2048

This pull request addresses a critical UnexpectedEnd error that caused swap failures for several UTXO-based coins, including Namecoin (NMC), Cheetahcoin (CHTA), and eCash (XEC).

The Problem

The root cause was an overly broad conditional logic within the BlockHeader::deserialize function. This single function attempted to parse multiple different block header formats using if conditions based on the block version number. This led to two primary failure modes:

1. Incorrect KAWPOW Parsing

Coins like CHTA use the same version number as Ravencoin (0x30000000) for their KAWPOW implementation but do not include the extra header fields (n_height, n_nonce_u64, mix_hash) that RVN does. The deserializer was incorrectly attempting to read these non-existent fields for CHTA, causing a stream read to fail with UnexpectedEnd.

2. Brittle AuxPow Detection

The logic for detecting Auxiliary Proof-of-Work (AuxPow) headers relied on a hardcoded list of exact version numbers. The correct method is to check for a specific bit flag (1 << 8) in the version field, as the base version can change. This made the check fragile and prone to failure if a block with a different base version but an active AuxPow flag was encountered.

The Solution

This patch refactors the deserialization logic to be more precise and robust:

1. Specialized KAWPOW Logic

• A new CoinVariant::RVN has been added in mm2src/mm2_bitcoin/serialization/src/reader.rs
• The deserialization logic in mm2src/mm2_bitcoin/chain/src/block_header.rs now explicitly checks reader.coin_variant().is_rvn() before attempting to parse RVN-specific header fields
• This ensures that other coins using the KAWPOW version number are not parsed incorrectly

2. Correct AuxPow Detection

• The check for AuxPow headers has been changed from a hardcoded matches! macro to the correct bitmask check: (version & AUXPOW_VERSION_FLAG) != 0
• This aligns with the merged mining specification and correctly identifies all AuxPow-enabled blocks

3. Added Debug Utility Test

• A new, ignored test, test_scan_and_deserialize_block_headers, has been added to mm2src/coins/utxo/utxo_tests.rs
• This powerful utility allows developers to quickly scan the blockchain of any UTXO coin to pinpoint the exact block height where deserialization fails
• This will significantly speed up debugging similar issues in the future

Impact

These changes resolve the swap failures for the affected coins and make the UTXO header deserialization logic significantly more robust and maintainable.

[shamardy]

@mariocynicys all your review comments have been addressed :)

[mariocynicys]

LGTM!
Thanks

[cipig]

i got an "UnexpectedEnd" error when i called recover_funds_of_swap on this swap on maker:

{
   "error_events" : [
      "StartFailed",
      "NegotiateFailed",
      "TakerFeeValidateFailed",
      "MakerPaymentTransactionFailed",
      "MakerPaymentDataSendFailed",
      "MakerPaymentWaitConfirmFailed",
      "TakerPaymentValidateFailed",
      "TakerPaymentWaitConfirmFailed",
      "TakerPaymentSpendFailed",
      "TakerPaymentSpendConfirmFailed",
      "MakerPaymentWaitRefundStarted",
      "MakerPaymentRefundStarted",
      "MakerPaymentRefunded",
      "MakerPaymentRefundFailed",
      "MakerPaymentRefundFinished"
   ],
   "events" : [
      {
         "event" : {
            "data" : {
               "lock_duration" : 7800,
               "maker_amount" : "0.0007",
               "maker_coin" : "PIVX",
               "maker_coin_htlc_pubkey" : "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732",
               "maker_coin_start_block" : 4903981,
               "maker_payment_confirmations" : 5,
               "maker_payment_lock" : 1747549945,
               "maker_payment_requires_nota" : false,
               "maker_payment_trade_fee" : {
                  "amount" : "0.001",
                  "coin" : "PIVX",
                  "paid_from_trading_vol" : false
               },
               "my_persistent_pub" : "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732",
               "p2p_privkey" : null,
               "secret" : "c8a43ef5478519895e8affdde0ec99e9c3a0ef6ab9ceb7324d72863c21c4b02c",
               "secret_hash" : "cd9e7193fbf9b6d75ae7b3026f394f55dd6f4b6c",
               "started_at" : 1747534345,
               "taker" : "a27ba503d8d87636f289090f536d6c724ae76b16861e4241e07131fc52ab4025",
               "taker_amount" : "0.00081667875464",
               "taker_coin" : "KMD",
               "taker_coin_htlc_pubkey" : "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732",
               "taker_coin_start_block" : 4441578,
               "taker_payment_confirmations" : 3,
               "taker_payment_requires_nota" : false,
               "taker_payment_spend_trade_fee" : {
                  "amount" : "0.00001",
                  "coin" : "KMD",
                  "paid_from_trading_vol" : true
               },
               "uuid" : "be42d8c0-127c-4df5-800b-4de8318e1bf5"
            },
            "type" : "Started"
         },
         "timestamp" : 1747534345973
      },
      {
         "event" : {
            "data" : {
               "maker_coin_htlc_pubkey" : "03a27ba503d8d87636f289090f536d6c724ae76b16861e4241e07131fc52ab4025",
               "maker_coin_swap_contract_addr" : null,
               "taker_coin_htlc_pubkey" : "03a27ba503d8d87636f289090f536d6c724ae76b16861e4241e07131fc52ab4025",
               "taker_coin_swap_contract_addr" : null,
               "taker_payment_locktime" : 1747542145,
               "taker_pubkey" : "000000000000000000000000000000000000000000000000000000000000000000"
            },
            "type" : "Negotiated"
         },
         "timestamp" : 1747534361977
      },
      {
         "event" : {
            "data" : null,
            "type" : "MakerPaymentInstructionsReceived"
         },
         "timestamp" : 1747534363986
      },
      {
         "event" : {
            "data" : {
               "tx_hash" : "2c46c0cde1777107c58af82dc4e67ad6309589ac5226a932989412905ef996c7",
               "tx_hex" : "0400008085202f8901160660cb900ba86531faed0545967b1e61b35b8d942b1fb5ff67f15887c7af68020000006a473044022060e535195b3349aa0dcd951b5531dc44c9d6e31ac1461228d4d592585eea8e8602201d1f824c280853cdf02189c0f5e63837d9742f6d705b16b93bddc4a43e389788012103a27ba503d8d87636f289090f536d6c724ae76b16861e4241e07131fc52ab4025ffffffff02e8030000000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88accc8a5a08000000001976a914ae0200524d21d348b479b30e7b93d72451fdc55688ac193a2968000000000000000000000000000000"
            },
            "type" : "TakerFeeValidated"
         },
         "timestamp" : 1747534363987
      },
      {
         "event" : {
            "data" : {
               "tx_hash" : "90e5e1199e20a5116409907756b1a6f90dcfb852fc9dced0989edfe5c5b646a2",
               "tx_hex" : "0100000001041f6dc7ec3064ff6ed5239aa979efb9866dce9693266a4321003a4f5e61c69e020000006a47304402203f9e6e763473cdd06a4a0851036f3be9cb05a6ae13e886387a62553136725ee502201edff1dccc307c848afcac493a4526c0807874120a41ad6d0feb8ba97c968e3401210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ffffffff03701101000000000017a914a07d020c701d6a1f4ae33a92804725a19c3dbbf1870000000000000000166a14cd9e7193fbf9b6d75ae7b3026f394f55dd6f4b6c61e06b7c110000001976a9141462c3dd3f936d595c9af55978003b27c250441f88ac1c422968"
            },
            "type" : "MakerPaymentSent"
         },
         "timestamp" : 1747534364111
      },
      {
         "event" : {
            "data" : {
               "tx_hash" : "44d8f4c0c12ca83d81a4c1a57a29371d245857e964f0d197023a2e637c4d62cf",
               "tx_hex" : "0400008085202f8901c796f95e9012949832a92652ac899530d67ae6c42df88ac5077177e1cdc0462c010000006a47304402205fc888cc95d53c649712c24d18be626e752c01fc3c5a350dc3deab101845eecf02205d3b6cbd7c1d6143d4f8c9975a28a5a1ad46be611c0b7e18f89c017227aa1f68012103a27ba503d8d87636f289090f536d6c724ae76b16861e4241e07131fc52ab4025ffffffff03033f01000000000017a914c61e4c6c0ee6faa4ccdfff6c937a3e8d487fc736870000000000000000166a14cd9e7193fbf9b6d75ae7b3026f394f55dd6f4b6ce1475908000000001976a914ae0200524d21d348b479b30e7b93d72451fdc55688acc93b2968000000000000000000000000000000"
            },
            "type" : "TakerPaymentReceived"
         },
         "timestamp" : 1747534800903
      },
      {
         "event" : {
            "type" : "TakerPaymentWaitConfirmStarted"
         },
         "timestamp" : 1747534800903
      },
      {
         "event" : {
            "data" : {
               "error" : "maker_swap:1063] !taker_coin.wait_for_confirmations: rpc_clients:139] Tx 44d8f4c0c12ca83d81a4c1a57a29371d245857e964f0d197023a2e637c4d62cf was not found on chain after 10 tries, error: client:909] JsonRpcError { client_info: \"coin: KMD\", request: JsonRpcRequest { jsonrpc: \"2.0\", id: 8958571, method: \"blockchain.transaction.get\", params: [String(\"44d8f4c0c12ca83d81a4c1a57a29371d245857e964f0d197023a2e637c4d62cf\"), Bool(true)] }, error: Response(electrum1.cipig.net:10001, Object({\"code\": Number(2), \"message\": String(\"daemon error: DaemonError({'code': -5, 'message': 'No information available about transaction'})\")})) }"
            },
            "type" : "TakerPaymentWaitConfirmFailed"
         },
         "timestamp" : 1747537487087
      },
      {
         "event" : {
            "data" : {
               "wait_until" : 1747553645
            },
            "type" : "MakerPaymentWaitRefundStarted"
         },
         "timestamp" : 1747537487089
      },
      {
         "event" : {
            "type" : "MakerPaymentRefundStarted"
         },
         "timestamp" : 1747537487090
      },
      {
         "event" : {
            "data" : {
               "error" : "maker_swap:1315] !maker_coin.send_maker_refunds_payment: utxo_common:1958] HTLC spend fee 100000 is greater than transaction output 70000"
            },
            "type" : "MakerPaymentRefundFailed"
         },
         "timestamp" : 1747550467167
      },
      {
         "event" : {
            "type" : "Finished"
         },
         "timestamp" : 1747550467172
      }
   ],
   "gui" : "mympm",
   "maker_amount" : "0.0007",
   "maker_coin" : "PIVX",
   "maker_coin_usd_price" : null,
   "mm_version" : "2.4.0-beta_f56917b",
   "my_order_uuid" : "f98ab227-29c9-4574-a5f9-528e0ddd5b45",
   "success_events" : [
      "Started",
      "Negotiated",
      "MakerPaymentInstructionsReceived",
      "TakerFeeValidated",
      "MakerPaymentSent",
      "TakerPaymentReceived",
      "TakerPaymentWaitConfirmStarted",
      "TakerPaymentValidatedAndConfirmed",
      "TakerPaymentSpent",
      "TakerPaymentSpendConfirmStarted",
      "TakerPaymentSpendConfirmed",
      "Finished"
   ],
   "taker_amount" : "0.00081667875464",
   "taker_coin" : "KMD",
   "taker_coin_usd_price" : null,
   "type" : "Maker",
   "uuid" : "be42d8c0-127c-4df5-800b-4de8318e1bf5"
}

the error message is simply "error" : "rpc:198] RPC call failed: lp_swap:1519] saved_swap:130] maker_swap:1698] utxo_standard:453] client:1117] UnexpectedEnd" ... the log shows the same

idk if that is the same as what the PR fixes or not
anyway, coin was PIVX and it wouldn't make sense to try recover anyway since the initial error on refund was maker_swap:1315] !maker_coin.send_maker_refunds_payment: utxo_common:1958] HTLC spend fee 100000 is greater than transaction output 70000, so will be the same this time

[shamardy]

idk if that is the same as what the PR fixes or not

The UnexpectedEnd can happen for other coins, this PR fixed Namecoin (NMC), Cheetahcoin (CHTA), and eCash (XEC) that were specifically mentioned in the issue and maybe some others. UnexpectedEnd is basically problems in block headers deserializations, now I have a utility test that can uncover the reason (the bad block) quickly. I will copy this #2563 (comment) to the original issue.