From 511aad31aca1da94e91c6cf17a454193ce5a4073 Mon Sep 17 00:00:00 2001 From: michael1011 Date: Sat, 9 Nov 2024 16:12:05 +0100 Subject: [PATCH] docs: EVM clarifications --- docs/claiming-swaps.md | 23 ++++++++++++----------- docs/dont-trust-verify.md | 13 +++++++------ 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/claiming-swaps.md b/docs/claiming-swaps.md index 32bd76a5..cb787a82 100644 --- a/docs/claiming-swaps.md +++ b/docs/claiming-swaps.md @@ -135,25 +135,25 @@ structured like this: On EVM chains, a contract is used for enforcing swaps onchain. The source code of Boltz's contracts can be found -[here](https://github.com/BoltzExchange/boltz-core/tree/v2.1.0/contracts). To +[here](https://github.com/BoltzExchange/boltz-core/tree/v2.1.3/contracts). To fetch the current addresses of Boltz's swap contracts, use -`GET /chain/contracts`. +[`GET /chain/contracts`](https://api.boltz.exchange/swagger#/Chain/get_chain_contracts). ### Submarine Swaps The `lock` function of the swap contract is used to lock up coins for a -Submarine Swap. All parameter values are returned in the response when creating -the swap. +Submarine Swap. All values for the parameters required to call the function of +the contract are returned in the API response when creating the swap. With the `refund` function of the contract, locked coins can be refunded in case the swap fails. This function takes similar parameters as `lock`, so the values from the response of the swap creation should be stored. If this information is not available, all parameters required for a refund can also be queried from the `Lockup` event logs of the contract. The event logs are indexed by -`refundAddress`,which is the address with which the client locked the coins. +`refundAddress`, which is the address with which the client locked the coins. -To refund before the time lock of the swap expired, an EIP-712 signature can be -requested from Boltz. Use `GET /swap/submarine/{id}/refund` to obtain this +To refund before the time lock of the swap has expired, an EIP-712 signature can +be requested from Boltz. Use `GET /swap/submarine/{id}/refund` to get this signature and use it in the `refundCooperative` function of the contract. Similarly to cooperative Taproot refunds, Boltz will only return such a signature if the swap has failed already. @@ -162,7 +162,8 @@ signature if the swap has failed already. To claim coins locked in the contract, use the function `claim`. All parameters apart from the `preimage` are returned in the response when creating the swap. -The API client is responsible for securely storing the preimage after the swap. +The API client is responsible for securely storing the preimage after creating +the swap. ## Legacy Swaps @@ -213,7 +214,7 @@ refund. {% hint style="info" %} The concept of refunds exists for failed Normal Submarine Swaps and Chain Swaps. For failed Reverse Submarine Swaps, Lightning -funds automatically bounce back to the user once the payment expired, no active +funds automatically bounce back to the user once the payment expired; no active refunding is needed. {% endhint %} Refunding an output works just like claiming. Since the refund process doesn't @@ -245,7 +246,7 @@ refund info stored by the API client is lost. All clients that offer the option for users to save refund files should format them in a standardized way. This is necessary for refunds to not only work in a -client, but also but also with [Boltz](https://boltz.exchange/refund) directly. +client, but also with [Boltz](https://boltz.exchange/refund) directly. The refund files Boltz Web App generates are `JSON` on Desktop and `PNG` QR codes on mobile (because iOS browsers don't allow any other files than images to @@ -277,7 +278,7 @@ Example: } ``` -If a user lost all refund information, but still has access to the lightning +If a user lost all refund information but still has access to the lightning invoice and can extract the preimage, this can be used to claim the locked bitcoin back to a user-controlled address. Feel free to [contact us](https://discord.gg/QBvZGcW) should you be in such a situation. We diff --git a/docs/dont-trust-verify.md b/docs/dont-trust-verify.md index dad9f120..6adb6ed7 100644 --- a/docs/dont-trust-verify.md +++ b/docs/dont-trust-verify.md @@ -52,8 +52,8 @@ OP_EQUAL #### P2WSH -In P2WSH addresses the reedem script is hashed with SHA256. The output script is -also a little simpler: +In P2WSH addresses, the redeem script is hashed with SHA256. The output script +is also a little simpler: ``` OP_0 @@ -75,11 +75,11 @@ on the [Bitcoin Wiki](https://en.bitcoin.it/wiki/Script). {% endhint %} Swap amounts should be calculated by the API client (taking into account network fee and Boltz fee from `/getpairs`). Boltz API clients then should decode and -verify that a Lightning invoice generated by Boltz +verify that a Lightning invoice has been generated by Boltz - Has the same preimage hash that the client previously generated and used to call `/createswap`. -- Has the same amount than the amount used to call `/createswap`. +- Has the same amount as the amount used to call `/createswap`. Examples in JavaScript can be found [here](https://github.com/BoltzExchange/boltz-web-app/blob/421d8268d9c63ba77e200dfc52c1a76b921e788b/src/utils/validation.ts#L109). @@ -89,8 +89,9 @@ match calculated swap amounts to prevent user error. ## EVM Chain Contract Verification -Boltz API clients should verify that EVM swaps are carried out using the correct -contract by comparing the bytecode of the contract. +Boltz API clients should check that EVM swaps are carried out using a legitimate +contract by comparing the bytecode of it to a verified version or hardcoding the +address of a verified version. ## Taproot Swaps Script Path Fallback