Implement redemptions with a proxy for redemption integrations (#814)

In this PR we introduce a RedeemerProxy interface that can be used by integrators to route tBTC redemption through the tBTC Bridge. An example of the integrator is Acre's [BitcoinRedeemer contract](https://github.com/thesis/acre/blob/main/solidity/contracts/BitcoinRedeemer.sol) that requires the redemption data to handle stBTC -> tBTC -> Bitcoin conversion in one transaction. When redeeming tBTC the challenge is to assemble redemption data to contain valid wallet UTXO and other data in the format expected by the Bridge. It is expected that the integrator will implement `RedeemerProxy` interface by exposing two functions: - `redeemerAddress(): ChainIdentifier` - that will return the Ethereum address to which the tBTC balance will be assigned in case of problems with redemption, - `requestRedemption(redemptionData: Hex): Promise<Hex>` - a callback function that will be called with assembled `redemptionData` to proceed with a custom integrator's logic. The integrator should use the `requestRedemptionWithProxy` function to execute the redemption.
keep-network · Jun 11, 2024 · 6e5e75b · 6e5e75b
2 parents 51094e4 + 548332d
commit 6e5e75b
Show file tree

Hide file tree

Showing 13 changed files with 480 additions and 95 deletions.
diff --git a/typescript/api-reference/README.md b/typescript/api-reference/README.md
@@ -67,6 +67,7 @@
 - [L1BitcoinDepositor](interfaces/L1BitcoinDepositor.md)
 - [L2BitcoinDepositor](interfaces/L2BitcoinDepositor.md)
 - [L2TBTCToken](interfaces/L2TBTCToken.md)
+- [RedeemerProxy](interfaces/RedeemerProxy.md)
 - [RedemptionRequest](interfaces/RedemptionRequest.md)
 - [TBTCToken](interfaces/TBTCToken.md)
 - [TBTCVault](interfaces/TBTCVault.md)

diff --git a/typescript/api-reference/classes/EthereumTBTCToken.md b/typescript/api-reference/classes/EthereumTBTCToken.md
@@ -142,7 +142,7 @@ EthersContractHandle.\_totalRetryAttempts
 
 #### Defined in
 
-[src/lib/ethereum/tbtc-token.ts:135](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/tbtc-token.ts#L135)
+[src/lib/ethereum/tbtc-token.ts:139](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/tbtc-token.ts#L139)
 
 ___
 
@@ -163,9 +163,15 @@ ___
 
 [`Hex`](Hex.md)
 
+**`See`**
+
+#### Implementation of
+
+[TBTCToken](../interfaces/TBTCToken.md).[buildRequestRedemptionData](../interfaces/TBTCToken.md#buildrequestredemptiondata)
+
 #### Defined in
 
-[src/lib/ethereum/tbtc-token.ts:104](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/tbtc-token.ts#L104)
+[src/lib/ethereum/tbtc-token.ts:108](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/ethereum/tbtc-token.ts#L108)
 
 ___
 

diff --git a/typescript/api-reference/classes/RedemptionsService.md b/typescript/api-reference/classes/RedemptionsService.md
@@ -15,10 +15,12 @@ Service exposing features related to tBTC v2 redemptions.
 
 ### Methods
 
+- [determineRedemptionData](RedemptionsService.md#determineredemptiondata)
 - [determineWalletMainUtxo](RedemptionsService.md#determinewalletmainutxo)
 - [findWalletForRedemption](RedemptionsService.md#findwalletforredemption)
 - [getRedemptionRequests](RedemptionsService.md#getredemptionrequests)
 - [requestRedemption](RedemptionsService.md#requestredemption)
+- [requestRedemptionWithProxy](RedemptionsService.md#requestredemptionwithproxy)
 
 ## Constructors
 
@@ -39,7 +41,7 @@ Service exposing features related to tBTC v2 redemptions.
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:30](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L30)
+[src/services/redemptions/redemptions-service.ts:31](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L31)
 
 ## Properties
 
@@ -51,7 +53,7 @@ Bitcoin client handle.
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:28](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L28)
+[src/services/redemptions/redemptions-service.ts:29](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L29)
 
 ___
 
@@ -63,10 +65,37 @@ Handle to tBTC contracts.
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:24](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L24)
+[src/services/redemptions/redemptions-service.ts:25](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L25)
 
 ## Methods
 
+### determineRedemptionData
+
+▸ **determineRedemptionData**(`bitcoinRedeemerAddress`, `amount`): `Promise`\<\{ `mainUtxo`: [`BitcoinUtxo`](../README.md#bitcoinutxo) ; `redeemerOutputScript`: [`Hex`](Hex.md) ; `walletPublicKey`: [`Hex`](Hex.md)  }\>
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `bitcoinRedeemerAddress` | `string` | Bitcoin address redeemed BTC should be sent to. Only P2PKH, P2WPKH, P2SH, and P2WSH address types are supported. |
+| `amount` | `BigNumber` | The amount to be redeemed with the precision of the tBTC on-chain token contract. |
+
+#### Returns
+
+`Promise`\<\{ `mainUtxo`: [`BitcoinUtxo`](../README.md#bitcoinutxo) ; `redeemerOutputScript`: [`Hex`](Hex.md) ; `walletPublicKey`: [`Hex`](Hex.md)  }\>
+
+Object containing:
+         - Bitcoin public key of the wallet asked to handle the redemption.
+           Presented in the compressed form (33 bytes long with 02 or 03 prefix).
+         - Main UTXO of the wallet.
+         - Redeemer output script.
+
+#### Defined in
+
+[src/services/redemptions/redemptions-service.ts:132](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L132)
+
+___
+
 ### determineWalletMainUtxo
 
 ▸ **determineWalletMainUtxo**(`walletPublicKeyHash`, `bitcoinNetwork`): `Promise`\<`undefined` \| [`BitcoinUtxo`](../README.md#bitcoinutxo)\>
@@ -90,7 +119,7 @@ Promise holding the wallet main UTXO or undefined value.
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:225](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L225)
+[src/services/redemptions/redemptions-service.ts:300](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L300)
 
 ___
 
@@ -116,7 +145,7 @@ Promise with the wallet details needed to request a redemption.
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:106](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L106)
+[src/services/redemptions/redemptions-service.ts:181](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L181)
 
 ___
 
@@ -147,7 +176,7 @@ Throws an error if no redemption request exists for the given
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:337](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L337)
+[src/services/redemptions/redemptions-service.ts:412](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L412)
 
 ___
 
@@ -176,4 +205,36 @@ Object containing:
 
 #### Defined in
 
-[src/services/redemptions/redemptions-service.ts:48](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L48)
+[src/services/redemptions/redemptions-service.ts:49](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L49)
+
+___
+
+### requestRedemptionWithProxy
+
+▸ **requestRedemptionWithProxy**(`bitcoinRedeemerAddress`, `amount`, `redeemerProxy`): `Promise`\<\{ `targetChainTxHash`: [`Hex`](Hex.md) ; `walletPublicKey`: [`Hex`](Hex.md)  }\>
+
+Requests a redemption of TBTC v2 token into BTC using a custom integration.
+The function builds the redemption data and handles the redemption request
+through the provided redeemer proxy.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `bitcoinRedeemerAddress` | `string` | Bitcoin address the redeemed BTC should be sent to. Only P2PKH, P2WPKH, P2SH, and P2WSH address types are supported. |
+| `amount` | `BigNumberish` | The amount to be redeemed with the precision of the tBTC on-chain token contract. |
+| `redeemerProxy` | [`RedeemerProxy`](../interfaces/RedeemerProxy.md) | Object impleenting functions required to route tBTC redemption requests through the tBTC bridge. |
+
+#### Returns
+
+`Promise`\<\{ `targetChainTxHash`: [`Hex`](Hex.md) ; `walletPublicKey`: [`Hex`](Hex.md)  }\>
+
+Object containing:
+         - Target chain hash of the request redemption transaction
+           (for example, Ethereum transaction hash)
+         - Bitcoin public key of the wallet asked to handle the redemption.
+           Presented in the compressed form (33 bytes long with 02 or 03 prefix).
+
+#### Defined in
+
+[src/services/redemptions/redemptions-service.ts:88](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redemptions-service.ts#L88)
diff --git a/typescript/api-reference/interfaces/RedeemerProxy.md b/typescript/api-reference/interfaces/RedeemerProxy.md
@@ -0,0 +1,53 @@
+# Interface: RedeemerProxy
+
+Interface defining functions required to route tBTC redemption requests through
+the tBTC bridge by custom integrators.
+
+## Table of contents
+
+### Methods
+
+- [redeemerAddress](RedeemerProxy.md#redeemeraddress)
+- [requestRedemption](RedeemerProxy.md#requestredemption)
+
+## Methods
+
+### redeemerAddress
+
+▸ **redeemerAddress**(): [`ChainIdentifier`](ChainIdentifier.md)
+
+Chain identifier of the redeemer. This is the address that will be able to
+claim the tBTC tokens if anything goes wrong during the redemption process.
+
+#### Returns
+
+[`ChainIdentifier`](ChainIdentifier.md)
+
+#### Defined in
+
+[src/services/redemptions/redeemer-proxy.ts:13](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redeemer-proxy.ts#L13)
+
+___
+
+### requestRedemption
+
+▸ **requestRedemption**(`redemptionData`): `Promise`\<[`Hex`](../classes/Hex.md)\>
+
+Requests redemption of tBTC token with determined redemption data.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `redemptionData` | [`Hex`](../classes/Hex.md) | Data required to redeem the tBTC tokens. |
+
+#### Returns
+
+`Promise`\<[`Hex`](../classes/Hex.md)\>
+
+Target chain hash of the request redemption transaction
+         (for example, Ethereum transaction hash)
+
+#### Defined in
+
+[src/services/redemptions/redeemer-proxy.ts:21](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/services/redemptions/redeemer-proxy.ts#L21)
diff --git a/typescript/api-reference/interfaces/TBTCToken.md b/typescript/api-reference/interfaces/TBTCToken.md
@@ -10,12 +10,40 @@ Interface for communication with the TBTC v2 token on-chain contract.
 
 ### Methods
 
+- [buildRequestRedemptionData](TBTCToken.md#buildrequestredemptiondata)
 - [getChainIdentifier](TBTCToken.md#getchainidentifier)
 - [requestRedemption](TBTCToken.md#requestredemption)
 - [totalSupply](TBTCToken.md#totalsupply)
 
 ## Methods
 
+### buildRequestRedemptionData
+
+▸ **buildRequestRedemptionData**(`redeemer`, `walletPublicKey`, `mainUtxo`, `redeemerOutputScript`): [`Hex`](../classes/Hex.md)
+
+Prepare tBTC Redemption Data in the raw bytes format expected by the tBTC
+Bridge contract. The data is used to request a redemption of TBTC v2 token
+through custom integration with the tBTC Bridge contract.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `redeemer` | [`ChainIdentifier`](ChainIdentifier.md) | Chain identifier of the redeemer. This is the address that will be able to claim the tBTC tokens if anything goes wrong during the redemption process. |
+| `walletPublicKey` | [`Hex`](../classes/Hex.md) | The Bitcoin public key of the wallet. Must be in the compressed form (33 bytes long with 02 or 03 prefix). |
+| `mainUtxo` | [`BitcoinUtxo`](../README.md#bitcoinutxo) | The main UTXO of the wallet. Must match the main UTXO held by the on-chain Bridge contract. |
+| `redeemerOutputScript` | [`Hex`](../classes/Hex.md) | The output script that the redeemed funds will be locked to. Must not be prepended with length. |
+
+#### Returns
+
+[`Hex`](../classes/Hex.md)
+
+#### Defined in
+
+[src/lib/contracts/tbtc-token.ts:61](https://github.com/keep-network/tbtc-v2/blob/main/typescript/src/lib/contracts/tbtc-token.ts#L61)
+
+___
+
 ### getChainIdentifier
 
 ▸ **getChainIdentifier**(): [`ChainIdentifier`](ChainIdentifier.md)

diff --git a/typescript/src/lib/contracts/tbtc-token.ts b/typescript/src/lib/contracts/tbtc-token.ts
@@ -43,4 +43,25 @@ export interface TBTCToken {
     redeemerOutputScript: Hex,
     amount: BigNumber
   ): Promise<Hex>
+
+  /**
+   * Prepare tBTC Redemption Data in the raw bytes format expected by the tBTC
+   * Bridge contract. The data is used to request a redemption of TBTC v2 token
+   * through custom integration with the tBTC Bridge contract.
+   * @param redeemer - Chain identifier of the redeemer. This is the address that
+   *        will be able to claim the tBTC tokens if anything goes wrong during
+   *        the redemption process.
+   * @param walletPublicKey - The Bitcoin public key of the wallet. Must be in
+   *        the compressed form (33 bytes long with 02 or 03 prefix).
+   * @param mainUtxo - The main UTXO of the wallet. Must match the main UTXO
+   *        held by the on-chain Bridge contract.
+   * @param redeemerOutputScript - The output script that the redeemed funds
+   *        will be locked to. Must not be prepended with length.
+   */
+  buildRequestRedemptionData(
+    redeemer: ChainIdentifier,
+    walletPublicKey: Hex,
+    mainUtxo: BitcoinUtxo,
+    redeemerOutputScript: Hex
+  ): Hex
 }
diff --git a/typescript/src/lib/ethereum/tbtc-token.ts b/typescript/src/lib/ethereum/tbtc-token.ts
@@ -101,7 +101,11 @@ export class EthereumTBTCToken
     return Hex.from(tx.hash)
   }
 
-  private buildRequestRedemptionData(
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {TBTCToken#buildRequestRedemptionData}
+   */
+  buildRequestRedemptionData(
     redeemer: EthereumAddress,
     walletPublicKey: Hex,
     mainUtxo: BitcoinUtxo,

diff --git a/typescript/src/services/redemptions/index.ts b/typescript/src/services/redemptions/index.ts
@@ -1 +1,2 @@
 export * from "./redemptions-service"
+export * from "./redeemer-proxy"
diff --git a/typescript/src/services/redemptions/redeemer-proxy.ts b/typescript/src/services/redemptions/redeemer-proxy.ts
@@ -0,0 +1,22 @@
+import { ChainIdentifier } from "../../lib/contracts"
+import { Hex } from "../../lib/utils"
+
+/**
+ * Interface defining functions required to route tBTC redemption requests through
+ * the tBTC bridge by custom integrators.
+ */
+export interface RedeemerProxy {
+  /**
+   * Chain identifier of the redeemer. This is the address that will be able to
+   * claim the tBTC tokens if anything goes wrong during the redemption process.
+   */
+  redeemerAddress(): ChainIdentifier
+
+  /**
+   * Requests redemption of tBTC token with determined redemption data.
+   * @param redemptionData Data required to redeem the tBTC tokens.
+   * @returns Target chain hash of the request redemption transaction
+   *          (for example, Ethereum transaction hash)
+   */
+  requestRedemption(redemptionData: Hex): Promise<Hex>
+}