Allow blockchain.transaction.get_merkle to discover confirmation height #247

Summary

Allow the height parameter of blockchain.transaction.get_merkle to be omitted. When omitted, electrs would discover the confirming block using its local index and return the existing Merkle-proof response, including block_height.

This follows the alternative proposed by @shesek in #244.

Motivation

Some clients are given a transaction ID and an associated address and need to determine whether the transaction is confirmed and, if so, at what height.

The standard Electrum workflow obtains the height from blockchain.scripthash.get_history and then calls blockchain.transaction.get_merkle(tx_hash, height). This fails for high-activity scripts when history lookup returns Too many history entries.

The server already discovers the transaction's confirming block internally:

let blockid = self
    .query
    .chain()
    .tx_confirming_block(&txid)
    .ok_or_else(|| "tx not found or is unconfirmed")?;

The supplied height is only used afterward to verify that the caller provided the correct value.

Proposed behavior

Existing requests with an explicit height remain unchanged:

{
  "method": "blockchain.transaction.get_merkle",
  "params": ["<txid>", 962126]
}

A request may instead omit the height:

{
  "method": "blockchain.transaction.get_merkle",
  "params": ["<txid>"]
}

For a confirmed transaction, return the existing response:

{
  "block_height": 962126,
  "merkle": ["..."],
  "pos": 618
}

For an unknown or unconfirmed transaction, retain the existing error:

tx not found or is unconfirmed

When an explicit height is supplied but does not match, retain the current invalid confirmation height provided error.

Compatibility

The Electrum protocol currently requires the height parameter, so omitting it would be an electrs extension. Existing conforming requests and responses remain unchanged.

The extension:

• uses local electrs state as the single source of truth;
• requires no query-time Bitcoin Core RPC;
• avoids returning a partially compatible verbose transaction object;
• requires only a small change because electrs already discovers the height;
• returns a Merkle inclusion proof in addition to the discovered height.

The downside is that it constructs and transfers a Merkle proof when a client only needs the height. A dedicated status method would be more efficient, but would introduce a larger nonstandard API extension.

Electrum Protocol 1.7's standardized outpoint status methods are tracked in #231.