diff --git a/typescript/api-reference/README.md b/typescript/api-reference/README.md index a18d50dc4..15f8db8f4 100644 --- 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 index 95a043433..0775dbfd5 100644 --- 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 index d83ad0514..8d1c8cf8f 100644 --- 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 new file mode 100644 index 000000000..b28b86fac --- /dev/null +++ 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 index e3e3347f4..49218c879 100644 --- 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)