SDK: Add coinbase data to the SPV proof builder (#773)

Refs:
GHSA-wg2x-rv86-mmpx

The SPV proof verifier used by the `Bridge` contract has been changed.
It now expects the coinbase's preimage and merkle proof to be submitted
as part of the proven transaction's SPV proof. Here we adhere to this
requirement by adjusting the SDK's SPV proof builder accordingly.

Note: Core changes presented in this PR are equivalent to
keep-network/keep-core#3762

typescript/api-reference/README.md

@@ -611,7 +611,7 @@ Bitcoin transaction along with the inclusion proof.
 
 #### Defined in
 
-[src/lib/bitcoin/spv.ts:64](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L64)
+[src/lib/bitcoin/spv.ts:75](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L75)
 
 ___
 
@@ -686,7 +686,7 @@ Electrum script hash as a hex string.
 
 #### Defined in
 
-[src/lib/electrum/client.ts:649](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/electrum/client.ts#L649)
+[src/lib/electrum/client.ts:667](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/electrum/client.ts#L667)
 
 ___
 
@@ -957,7 +957,7 @@ The function should be used within a try-catch block.
 
 #### Defined in
 
-[src/lib/bitcoin/spv.ts:145](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L145)
+[src/lib/bitcoin/spv.ts:180](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L180)
 
 ___
 

typescript/api-reference/classes/ElectrumClient.md

@@ -24,6 +24,7 @@ Electrum-based implementation of the Bitcoin client.
 
 - [broadcast](ElectrumClient.md#broadcast)
 - [findAllUnspentTransactionOutputs](ElectrumClient.md#findallunspenttransactionoutputs)
+- [getCoinbaseTxHash](ElectrumClient.md#getcoinbasetxhash)
 - [getHeadersChain](ElectrumClient.md#getheaderschain)
 - [getNetwork](ElectrumClient.md#getnetwork)
 - [getRawTransaction](ElectrumClient.md#getrawtransaction)
@@ -167,6 +168,32 @@ ___
 
 ___
 
+### getCoinbaseTxHash
+
+▸ **getCoinbaseTxHash**(`blockHeight`): `Promise`\<[`BitcoinTxHash`](BitcoinTxHash.md)\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `blockHeight` | `number` |
+
+#### Returns
+
+`Promise`\<[`BitcoinTxHash`](BitcoinTxHash.md)\>
+
+**`See`**
+
+#### Implementation of
+
+[BitcoinClient](../interfaces/BitcoinClient.md).[getCoinbaseTxHash](../interfaces/BitcoinClient.md#getcoinbasetxhash)
+
+#### Defined in
+
+[src/lib/electrum/client.ts:646](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/electrum/client.ts#L646)
+
+___
+
 ### getHeadersChain
 
 ▸ **getHeadersChain**(`blockHeight`, `chainLength`): `Promise`\<[`Hex`](Hex.md)\>

typescript/api-reference/classes/EthereumBridge.md

@@ -148,7 +148,7 @@ EthersContractHandle.\_totalRetryAttempts
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:494](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L494)
+[src/lib/ethereum/bridge.ts:498](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L498)
 
 ___
 
@@ -177,7 +177,7 @@ Builds the UTXO hash based on the UTXO components. UTXO hash is computed as
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:618](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L618)
+[src/lib/ethereum/bridge.ts:622](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L622)
 
 ___
 
@@ -204,7 +204,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:429](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L429)
+[src/lib/ethereum/bridge.ts:433](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L433)
 
 ___
 
@@ -334,7 +334,7 @@ Bridge.getNewWalletRegisteredEvents
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:530](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L530)
+[src/lib/ethereum/bridge.ts:534](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L534)
 
 ___
 
@@ -361,7 +361,7 @@ Bridge.getRedemptionRequestedEvents
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:635](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L635)
+[src/lib/ethereum/bridge.ts:639](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L639)
 
 ___
 
@@ -381,7 +381,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:515](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L515)
+[src/lib/ethereum/bridge.ts:519](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L519)
 
 ___
 
@@ -405,7 +405,7 @@ Parsed deposit request.
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:474](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L474)
+[src/lib/ethereum/bridge.ts:478](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L478)
 
 ___
 
@@ -454,7 +454,7 @@ Parsed wallet data.
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:589](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L589)
+[src/lib/ethereum/bridge.ts:593](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L593)
 
 ___
 
@@ -510,7 +510,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:336](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L336)
+[src/lib/ethereum/bridge.ts:338](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L338)
 
 ___
 
@@ -597,7 +597,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:380](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L380)
+[src/lib/ethereum/bridge.ts:382](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L382)
 
 ___
 
@@ -644,7 +644,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:322](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L322)
+[src/lib/ethereum/bridge.ts:324](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L324)
 
 ___
 
@@ -664,7 +664,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:555](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L555)
+[src/lib/ethereum/bridge.ts:559](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L559)
 
 ___
 
@@ -690,7 +690,7 @@ ___
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:572](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L572)
+[src/lib/ethereum/bridge.ts:576](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L576)
 
 ___
 
@@ -715,7 +715,7 @@ Deposit key.
 
 #### Defined in
 
-[src/lib/ethereum/bridge.ts:455](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L455)
+[src/lib/ethereum/bridge.ts:459](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/bridge.ts#L459)
 
 ___
 

typescript/api-reference/interfaces/BitcoinClient.md

@@ -12,6 +12,7 @@ Represents a Bitcoin client.
 
 - [broadcast](BitcoinClient.md#broadcast)
 - [findAllUnspentTransactionOutputs](BitcoinClient.md#findallunspenttransactionoutputs)
+- [getCoinbaseTxHash](BitcoinClient.md#getcoinbasetxhash)
 - [getHeadersChain](BitcoinClient.md#getheaderschain)
 - [getNetwork](BitcoinClient.md#getnetwork)
 - [getRawTransaction](BitcoinClient.md#getrawtransaction)
@@ -72,6 +73,28 @@ List of UTXOs.
 
 ___
 
+### getCoinbaseTxHash
+
+▸ **getCoinbaseTxHash**(`blockHeight`): `Promise`\<[`BitcoinTxHash`](../classes/BitcoinTxHash.md)\>
+
+Gets the hash of the coinbase transaction for the given block height.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `blockHeight` | `number` | Height of the block. |
+
+#### Returns
+
+`Promise`\<[`BitcoinTxHash`](../classes/BitcoinTxHash.md)\>
+
+#### Defined in
+
+[src/lib/bitcoin/client.ts:109](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/client.ts#L109)
+
+___
+
 ### getHeadersChain
 
 ▸ **getHeadersChain**(`blockHeight`, `chainLength`): `Promise`\<[`Hex`](../classes/Hex.md)\>

typescript/api-reference/interfaces/BitcoinSpvProof.md

@@ -8,6 +8,8 @@ the Bitcoin blockchain.
 ### Properties
 
 - [bitcoinHeaders](BitcoinSpvProof.md#bitcoinheaders)
+- [coinbasePreimage](BitcoinSpvProof.md#coinbasepreimage)
+- [coinbaseProof](BitcoinSpvProof.md#coinbaseproof)
 - [merkleProof](BitcoinSpvProof.md#merkleproof)
 - [txIndexInBlock](BitcoinSpvProof.md#txindexinblock)
 
@@ -26,6 +28,31 @@ Concatenated block headers in hexadecimal format. Each block header is
 
 ___
 
+### coinbasePreimage
+
+• **coinbasePreimage**: [`Hex`](../classes/Hex.md)
+
+The sha256 preimage of the coinbase transaction hash i.e.,
+the sha256 hash of the coinbase transaction.
+
+#### Defined in
+
+[src/lib/bitcoin/spv.ts:37](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L37)
+
+___
+
+### coinbaseProof
+
+• **coinbaseProof**: [`Hex`](../classes/Hex.md)
+
+Merkle proof of coinbase transaction inclusion in a block.
+
+#### Defined in
+
+[src/lib/bitcoin/spv.ts:42](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L42)
+
+___
+
 ### merkleProof
 
 • **merkleProof**: [`Hex`](../classes/Hex.md)

typescript/api-reference/interfaces/BitcoinTxMerkleBranch.md

@@ -20,7 +20,7 @@ The height of the block the transaction was confirmed in.
 
 #### Defined in
 
-[src/lib/bitcoin/spv.ts:41](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L41)
+[src/lib/bitcoin/spv.ts:52](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L52)
 
 ___
 
@@ -34,7 +34,7 @@ the deepest pairing first. Each hash is an unprefixed hex string.
 
 #### Defined in
 
-[src/lib/bitcoin/spv.ts:48](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L48)
+[src/lib/bitcoin/spv.ts:59](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L59)
 
 ___
 
@@ -46,4 +46,4 @@ The 0-based index of the transaction's position in the block.
 
 #### Defined in
 
-[src/lib/bitcoin/spv.ts:53](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L53)
+[src/lib/bitcoin/spv.ts:64](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/bitcoin/spv.ts#L64)

typescript/src/lib/bitcoin/client.ts

@@ -101,4 +101,10 @@ export interface BitcoinClient {
    * @param transaction - Transaction to broadcast.
    */
   broadcast(transaction: BitcoinRawTx): Promise<void>
+
+  /**
+   * Gets the hash of the coinbase transaction for the given block height.
+   * @param blockHeight - Height of the block.
+   */
+  getCoinbaseTxHash(blockHeight: number): Promise<BitcoinTxHash>
 }