docs: add common problems page (#606)

Co-authored-by: Kilian <kilian.rausch@gmail.com>

docs/0-conf.md

@@ -15,7 +15,7 @@ As a precautionary measure, Boltz enforces a few rules when it comes to 0-conf.
 _0-conf Swaps are subject to network conditions and only available on UTXO chains like Bitcoin or Liquid._
 
 {% hint style="info" %}
-Because of [growing adoption of`mempoolfullrbf`](https://github.com/bitcoin/bitcoin/pull/28132) by a significant set of miners, Boltz is currently **not** accepting 0-conf transactions for Normal Submarine Swaps on the Bitcoin mainchain.
+Because of [growing adoption of`mempoolfullrbf`](https://github.com/bitcoin/bitcoin/pull/28132) by a significant set of miners, Boltz is currently **not** accepting 0-conf transactions on the Bitcoin mainchain.
 {% endhint %}
 
 ## Limits

docs/SUMMARY.md

@@ -9,6 +9,7 @@
 * [📜 Claim covenants](claim-covenants.md)
 * [🚫 Don't trust. Verify!](dont-trust-verify.md)
 * [⏩ 0-conf](0-conf.md)
+* [⚠️ Common Mistakes](common-mistakes.md)
 * [🚢 Backend Deployment](deployment.md)
 * [🐳 Regtest Environment](regtest.md)
 * [🔙 Back to Docs Home](https://app.gitbook.com/o/SPM8mTvJyc7OIzGL3HD7/s/XUXMXrD8YTzvuqvAeom7/)

docs/api-v2.md

@@ -1057,7 +1057,6 @@ func main() {
 {% endtab %}
 {% endtabs %}
 
-
 ## Chain Swap (Chain -> Chain)
 
 {% tabs %}

docs/claiming-swaps.md

@@ -5,7 +5,7 @@ description: >-
   swaps.
 ---
 
-# 🙋♂ Claim & Refund Transactions
+# 🙋‍♂️ Claim & Refund Transactions
 
 Boltz API clients need to craft and broadcast
 
@@ -152,7 +152,7 @@ Examples for all output types can be found in the [`boltz-core`](https://github.
 Similar to claim transactions, Boltz API clients need to be able to craft and broadcast **refund transactions** for failed **Normal Submarine Swaps**. This section provides an overview of what refunds are, how they work and touches on the low-level scripting for your Boltz API client to successfully submit a refund.
 
 {% hint style="info" %}
-The concept of refunds currently only exists for failed Normal Submarine Swaps. In case of a failed Reverse Submarine Swaps, Lightning funds automatically bounce back to the user once the payment expired, no active refunding is needed.
+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 refunding is needed.
 {% endhint %}
 
 Refunding an output works just like claiming. Since the refund process doesn't need the preimage (or knows it but can't use it since that would require the claim keys) any value apart from the actual preimage can be used but there has to be a value to prevent the signature from being hashed and compared to the preimage hash. To save on transaction fees, we recommend using a 0 value.

docs/common-mistakes.md

@@ -0,0 +1,19 @@
+---
+description: >-
+  This document collects frequently encountered misunderstandings and common
+  mistakes when integrating Boltz API.
+---
+
+# ⚠️ Common Mistakes
+
+## Client-Side
+
+All Boltz API integrations should be client-side, meaning in end-user-controlled software on end-user-controlled devices. Boltz's non-custodial nature can only be maintained if the end user is in full control of Boltz Swaps. This concretely means that integrations should never run Boltz API clients on behalf of end users or store refund/swap information on their servers. The best way to get the broader Bitcoin community to accept and use a Boltz Swap Client is for the code to be open source and reviewed by the Boltz Team.
+
+## Online Requirement
+
+It is important to design Boltz API clients, especially on mobile, in a way that they can come online and broadcast claim transactions before a swap expires. We plan on adding [WebHook calls](https://github.com/BoltzExchange/boltz-backend/issues/605) informing about swap updates that developers can use to wake up clients with push notifications.
+
+## Retry Mechanism
+
+API clients should account for temporary network failures and, e.g., retry claiming swaps or sending payments. On mobile, claim logic should be triggered on app start and work independently of which part of the app the user navigates to. This also goes for WebView integrations of our [Web App](https://github.com/BoltzExchange/boltz-web-app).

docs/deployment.md

@@ -5,7 +5,7 @@ description: >-
   great responsibility.
 ---
 
-# 🚢 Deployment of Boltz Backend
+# 🚢 Backend Deployment
 
 Prerequisites:
 
@@ -17,8 +17,7 @@ Boltz Backend requires a synced Bitcoin Core Instance to connect to the Bitcoin
 * Have the transaction index enabled: `txindex=1`
 * Enable ZeroMQ streams for raw blocks and raw transactions: (`zmqpubrawblock=tcp://<host>:<port>` and `zmqpubrawtx=tcp://<host>:<port>`)
 
-Boltz requires a [LND](https://github.com/LightningNetwork/lnd) or [CLN](https://github.com/ElementsProject/lightning/) node running on Bitcoin to be present.
-For LND, no special configuration is needed, all [official release binaries](https://github.com/lightningnetwork/lnd/releases) are compatible.
+Boltz requires a [LND](https://github.com/LightningNetwork/lnd) or [CLN](https://github.com/ElementsProject/lightning/) node running on Bitcoin to be present. For LND, no special configuration is needed, all [official release binaries](https://github.com/lightningnetwork/lnd/releases) are compatible.
 
 ## Config Sample