Redemption prototype: Observe incoming proposals (#3639)

Refs #3609

Here is the first part of the client-side redemption support. In this
PR, we are integrating with the recent changes introduced in the
`WalletCoordinator` contract
(keep-network/tbtc-v2#633) and we are adding the
ability to observe incoming redemption proposals. Here is a brief
description of particular changes.

### `WalletCoordinator` contract integration code

We are adding all the boilerplate code required to see redemption
proposals emitted by the `WalletCoordinator` contract. This work
includes:
- Updates of contract bindings
- Integration with the `tbtc` package through the
`tbtc.WalletCoordinatorChain` interface and `chain/ethereum`
implementation
- Implementation of tools allowing to convert between length-prefixed
redeemer output scripts used by the smart contracts and the prefixless
form preferred in the off-chain client

### Observe incoming proposals

This part uses the code described in the previous section to:

- Handle incoming redemption proposals submitted to the
`WalletCoordinator` contract
- De-duplicate incoming proposals
- Confirm the finality of the incoming proposals

Author: pdyraga

pkg/bitcoin/bitcoin.go

@@ -7,6 +7,11 @@
 // type should leak outside.
 package bitcoin
 
+import (
+	"bytes"
+	"github.com/btcsuite/btcd/wire"
+)
+
 // CompactSizeUint is a documentation type that is supposed to capture the
 // details of the Bitcoin's CompactSize Unsigned Integer. It represents a
 // number value encoded to bytes according to the following rules:
@@ -22,6 +27,19 @@ package bitcoin
 // https://developer.bitcoin.org/reference/transactions.html#compactsize-unsigned-integers
 type CompactSizeUint uint64
 
+// readCompactSizeUint reads the leading CompactSizeUint from the provided
+// variable length data. Returns the value held by the CompactSizeUint as
+// the first argument and the byte length of the CompactSizeUint as the
+// second one.
+func readCompactSizeUint(varLenData []byte) (CompactSizeUint, int, error) {
+	csu, err := wire.ReadVarInt(bytes.NewReader(varLenData), 0)
+	if err != nil {
+		return 0, 0, err
+	}
+
+	return CompactSizeUint(csu), wire.VarIntSerializeSize(csu), nil
+}
+
 // ByteOrder represents the byte order used by the Bitcoin byte arrays. The
 // Bitcoin ecosystem is not totally consistent in this regard and different
 // byte orders are used depending on the purpose.

pkg/bitcoin/bitcoin_test.go

@@ -0,0 +1,79 @@
+package bitcoin
+
+import (
+	"encoding/hex"
+	"fmt"
+	"github.com/keep-network/keep-core/internal/testutils"
+	"reflect"
+	"testing"
+)
+
+func TestReadCompactSizeUint(t *testing.T) {
+	fromHex := func(hexString string) []byte {
+		bytes, err := hex.DecodeString(hexString)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return bytes
+	}
+
+	var tests = map[string]struct {
+		data               []byte
+		expectedValue      CompactSizeUint
+		expectedByteLength int
+		expectedErr        error
+	}{
+		"1-byte compact size uint": {
+			data:               fromHex("bb"),
+			expectedValue:      187,
+			expectedByteLength: 1,
+		},
+		"3-byte compact size uint": {
+			data:               fromHex("fd0302"),
+			expectedValue:      515,
+			expectedByteLength: 3,
+		},
+		"5-byte compact size uint": {
+			data:               fromHex("fe703a0f00"),
+			expectedValue:      998000,
+			expectedByteLength: 5,
+		},
+		"9-byte compact size uint": {
+			data:               fromHex("ff57284e56dab40000"),
+			expectedValue:      198849843832919,
+			expectedByteLength: 9,
+		},
+		"malformed compact size uint": {
+			data:        fromHex("fd01"),
+			expectedErr: fmt.Errorf("unexpected EOF"),
+		},
+	}
+
+	for testName, test := range tests {
+		t.Run(testName, func(t *testing.T) {
+			value, byteLength, err := readCompactSizeUint(test.data)
+
+			if !reflect.DeepEqual(test.expectedErr, err) {
+				t.Errorf(
+					"unexpected error\nexpected: %+v\nactual:   %+v\n",
+					test.expectedErr,
+					err,
+				)
+			}
+
+			testutils.AssertIntsEqual(
+				t,
+				"value",
+				int(test.expectedValue),
+				int(value),
+			)
+
+			testutils.AssertIntsEqual(
+				t,
+				"byte length",
+				test.expectedByteLength,
+				byteLength,
+			)
+		})
+	}
+}

pkg/bitcoin/script.go

@@ -4,10 +4,36 @@ import (
 	"crypto/ecdsa"
 	"crypto/elliptic"
 	"crypto/sha256"
+	"fmt"
 	"github.com/btcsuite/btcd/txscript"
 	"github.com/btcsuite/btcutil"
 )
 
+// Script represents an arbitrary Bitcoin script, NOT prepended with the
+// byte-length of the script
+type Script []byte
+
+// NewScriptFromVarLenData construct a Script instance based on the provided
+// variable length data prepended with a CompactSizeUint.
+func NewScriptFromVarLenData(varLenData []byte) (Script, error) {
+	// Extract the CompactSizeUint value that holds the byte length of the script.
+	// Also, extract the byte length of the CompactSizeUint itself.
+	scriptByteLength, compactByteLength, err := readCompactSizeUint(varLenData)
+	if err != nil {
+		return nil, fmt.Errorf("cannot read compact size uint: [%v]", err)
+	}
+
+	// Make sure the combined byte length of the script and the byte length
+	// of the CompactSizeUint matches the total byte length of the variable
+	// length data. Otherwise, the input data slice is malformed.
+	if uint64(scriptByteLength)+uint64(compactByteLength) != uint64(len(varLenData)) {
+		return nil, fmt.Errorf("malformed var len data")
+	}
+
+	// Extract the actual script by omitting the leading CompactSizeUint.
+	return varLenData[compactByteLength:], nil
+}
+
 // PublicKeyHash constructs the 20-byte public key hash by applying SHA-256
 // then RIPEMD-160 on the provided ECDSA public key.
 func PublicKeyHash(publicKey *ecdsa.PublicKey) [20]byte {
@@ -28,7 +54,7 @@ func PublicKeyHash(publicKey *ecdsa.PublicKey) [20]byte {
 // PayToWitnessPublicKeyHash constructs a P2WPKH script for the provided
 // 20-byte public key hash. The function assumes the provided public key hash
 // is valid.
-func PayToWitnessPublicKeyHash(publicKeyHash [20]byte) ([]byte, error) {
+func PayToWitnessPublicKeyHash(publicKeyHash [20]byte) (Script, error) {
 	return txscript.NewScriptBuilder().
 		AddOp(txscript.OP_0).
 		AddData(publicKeyHash[:]).
@@ -37,7 +63,7 @@ func PayToWitnessPublicKeyHash(publicKeyHash [20]byte) ([]byte, error) {
 
 // PayToPublicKeyHash constructs a P2PKH script for the provided 20-byte public
 // key hash. The function assumes the provided public key hash is valid.
-func PayToPublicKeyHash(publicKeyHash [20]byte) ([]byte, error) {
+func PayToPublicKeyHash(publicKeyHash [20]byte) (Script, error) {
 	return txscript.NewScriptBuilder().
 		AddOp(txscript.OP_DUP).
 		AddOp(txscript.OP_HASH160).
@@ -47,9 +73,6 @@ func PayToPublicKeyHash(publicKeyHash [20]byte) ([]byte, error) {
 		Script()
 }
 
-// Script represents an arbitrary Bitcoin script.
-type Script []byte
-
 // WitnessScriptHash constructs the 32-byte witness script hash by applying
 // single SHA-256 on the provided Script.
 func WitnessScriptHash(script Script) [32]byte {
@@ -69,7 +92,7 @@ func ScriptHash(script Script) [20]byte {
 
 // PayToWitnessScriptHash constructs a P2WSH script for the provided 32-byte
 // witness script hash. The function assumes the provided script hash is valid.
-func PayToWitnessScriptHash(witnessScriptHash [32]byte) ([]byte, error) {
+func PayToWitnessScriptHash(witnessScriptHash [32]byte) (Script, error) {
 	return txscript.NewScriptBuilder().
 		AddOp(txscript.OP_0).
 		AddData(witnessScriptHash[:]).
@@ -78,7 +101,7 @@ func PayToWitnessScriptHash(witnessScriptHash [32]byte) ([]byte, error) {
 
 // PayToScriptHash constructs a P2SH script for the provided 20-byte script
 // hash. The function assumes the provided script hash is valid.
-func PayToScriptHash(scriptHash [20]byte) ([]byte, error) {
+func PayToScriptHash(scriptHash [20]byte) (Script, error) {
 	return txscript.NewScriptBuilder().
 		AddOp(txscript.OP_HASH160).
 		AddData(scriptHash[:]).

pkg/bitcoin/script_test.go

@@ -4,13 +4,68 @@ import (
 	"crypto/ecdsa"
 	"crypto/elliptic"
 	"encoding/hex"
+	"fmt"
+	"reflect"
 	"testing"
 
 	"github.com/btcsuite/btcd/btcec"
 
 	"github.com/keep-network/keep-core/internal/testutils"
 )
 
+func TestNewScriptFromVarLenData(t *testing.T) {
+	fromHex := func(hexString string) []byte {
+		bytes, err := hex.DecodeString(hexString)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return bytes
+	}
+
+	var tests = map[string]struct {
+		data           []byte
+		expectedScript Script
+		expectedErr    error
+	}{
+		"proper variable length data": {
+			data:           fromHex("1600148db50eb52063ea9d98b3eac91489a90f738986f6"),
+			expectedScript: fromHex("00148db50eb52063ea9d98b3eac91489a90f738986f6"),
+		},
+		"nil variable length data": {
+			data:        nil,
+			expectedErr: fmt.Errorf("cannot read compact size uint: [EOF]"),
+		},
+		"variable length data with missing script": {
+			data:        fromHex("16"),
+			expectedErr: fmt.Errorf("malformed var len data"),
+		},
+		"variable length data with missing compact size uint": {
+			data:        fromHex("00148db50eb52063ea9d98b3eac91489a90f738986f6"),
+			expectedErr: fmt.Errorf("malformed var len data"),
+		},
+		"variable length data with wrong compact size uint value": {
+			data:        fromHex("1500148db50eb52063ea9d98b3eac91489a90f738986f6"),
+			expectedErr: fmt.Errorf("malformed var len data"),
+		},
+	}
+
+	for testName, test := range tests {
+		t.Run(testName, func(t *testing.T) {
+			script, err := NewScriptFromVarLenData(test.data)
+
+			if !reflect.DeepEqual(test.expectedErr, err) {
+				t.Errorf(
+					"unexpected error\nexpected: %+v\nactual:   %+v\n",
+					test.expectedErr,
+					err,
+				)
+			}
+
+			testutils.AssertBytesEqual(t, test.expectedScript, script)
+		})
+	}
+}
+
 func TestPublicKeyHash(t *testing.T) {
 	// An arbitrary uncompressed public key.
 	publicKeyBytes, err := hex.DecodeString(

pkg/bitcoin/transaction.go

@@ -226,9 +226,10 @@ type TransactionOutput struct {
 	// Value denotes the number of satoshis to spend. Zero is a valid value.
 	Value int64
 	// PublicKeyScript defines the conditions that must be satisfied to spend
-	// this output. This slice MUST NOT start with the byte-length of the script
-	// encoded as CompactSizeUint as this is done during transaction serialization.
-	PublicKeyScript []byte
+	// this output. As stated in the Script docstring, this field MUST NOT
+	// start with the byte-length of the script encoded as CompactSizeUint as
+	// this is done during transaction serialization.
+	PublicKeyScript Script
 }
 
 // UnspentTransactionOutput represents an unspent output (UTXO) of a Bitcoin

pkg/chain/ethereum/tbtc.go

@@ -1533,3 +1533,59 @@ func (tc *TbtcChain) SubmitDepositSweepProposalWithReimbursement(
 func (tc *TbtcChain) GetDepositSweepMaxSize() (uint16, error) {
 	return tc.walletCoordinator.DepositSweepMaxSize()
 }
+
+func (tc *TbtcChain) OnRedemptionProposalSubmitted(
+	handler func(event *tbtc.RedemptionProposalSubmittedEvent),
+) subscription.EventSubscription {
+	onEvent := func(
+		proposal tbtcabi.WalletCoordinatorRedemptionProposal,
+		coordinator common.Address,
+		blockNumber uint64,
+	) {
+		tbtcProposal, err := convertRedemptionProposalFromAbiType(proposal)
+		if err != nil {
+			logger.Errorf(
+				"unexpected proposal in RedemptionProposalSubmitted event: [%v]",
+				err,
+			)
+			return
+		}
+
+		handler(&tbtc.RedemptionProposalSubmittedEvent{
+			Proposal:    tbtcProposal,
+			Coordinator: chain.Address(coordinator.Hex()),
+			BlockNumber: blockNumber,
+		})
+	}
+
+	return tc.walletCoordinator.
+		RedemptionProposalSubmittedEvent(nil, nil).
+		OnEvent(onEvent)
+}
+
+func convertRedemptionProposalFromAbiType(
+	proposal tbtcabi.WalletCoordinatorRedemptionProposal,
+) (*tbtc.RedemptionProposal, error) {
+	redeemersOutputScripts := make(
+		[]bitcoin.Script,
+		len(proposal.RedeemersOutputScripts),
+	)
+
+	for i, script := range proposal.RedeemersOutputScripts {
+		// The on-chain script representation is prepended with the script's
+		// byte-length while bitcoin.Script is not. We need to remove the
+		// length prefix.
+		parsedScript, err := bitcoin.NewScriptFromVarLenData(script)
+		if err != nil {
+			return nil, fmt.Errorf("cannot parse redeemer output script: [%v]", err)
+		}
+
+		redeemersOutputScripts[i] = parsedScript
+	}
+
+	return &tbtc.RedemptionProposal{
+		WalletPublicKeyHash:    proposal.WalletPubKeyHash,
+		RedeemersOutputScripts: redeemersOutputScripts,
+		RedemptionTxFee:        proposal.RedemptionTxFee,
+	}, nil
+}