Implement redemptions with a proxy for redemption integrations

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)

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)
 
 ___
 

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)

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)

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)

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
 }

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,

typescript/src/services/redemptions/index.ts

@@ -1 +1,2 @@
 export * from "./redemptions-service"
+export * from "./redeemer-proxy"

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>
+}