GITBOOK-11: added explainers on sBTC fees

Author: eric-stacks

docs/build/.gitbook/assets/image (3).png

@@ -60,7 +60,7 @@ const deposit = buildSbtcDepositAddress({
 ```
 
 {% hint style="info" %}
-The `maxSignerFee` applies to the bitcoin transaction sweeping funds into, or out of, the consolidated UTXO locked exclusively by sBTC Signers' aggregate address. Depending on network congestion, specify a custom fee your users would be willing to spend. The default value will be 80,000 sats. If the actual fee spent is less than the default value, the difference will be returned.
+The `maxSignerFee` refers to the fee in the bitcoin transaction sweeping funds into, or out of, the consolidated UTXO locked exclusively by sBTC Signers' aggregate address. Depending on network congestion, specify a custom fee your users would be willing to spend. The default value will be 80,000 sats. The user's responsibility of the actual fee spent is actually deducted from the amount of sBTC that will be minted.
 {% endhint %}
 
 The `buildSbtcDepositAddress` will return with a schema of:
@@ -199,7 +199,9 @@ And that's all to it. You've successfully allowed your app to handle incoming BT
 
 ***
 
-### \[Insights] What scripts make up the custom P2TR bitcoin address?
+### \[Additional Insights] 
+
+### What scripts make up the custom P2TR bitcoin address?
 
 As mentioned above, you're not directly sending bitcoin to the public sBTC Signers' [bitcoin address](https://mempool.space/address/bc1prcs82tvrz70jk8u79uekwdfjhd0qhs2mva6e526arycu7fu25zsqhyztuy), but rather sending to a custom P2TR address where both the user and sBTC Signers have control over. Besides the default key path spend, this custom P2TR address also contains 2 sets of scripts:
 
@@ -266,3 +268,22 @@ export function buildSbtcReclaimScript(opts: {
 {% endcode %}
 
 Behind the scenes, these two script construction methods are being abstracted away by `buildSbtcDepositAddress` which you've implemented on the front-end.
+
+### How are fees dealt with?
+
+**During deposits**
+
+The `maxSignerFee` refers to the fee in the bitcoin transaction sweeping funds into the consolidated UTXO locked exclusively by sBTC Signers' aggregate address. Depending on network congestion, specify a custom fee your users would be willing to spend. The default value will be 80,000 sats. The user's responsibility of the actual fee spent (for the sweep transaction) is actually deducted from the amount of sBTC that will be minted.
+
+**During withdrawals**
+
+The fees specified in `max-fee` of the function `initiate-withdrawal-request` of the [`.sbtc-withdrawal`](https://explorer.hiro.so/txid/SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-withdrawal?chain=mainnet) contract are referring to the fees paid of the bitcoin withdrawal transaction.
+
+#### How to estimate how much in fees one should spend?
+
+If you want to estimate how much one would expect to be charged in fees, you'd have to estimate the size of the transaction (vbytes) and the current network's fee rate. Below are some estimations you could use as a benchmark:
+
+**For deposits**: \~250 vbytes times the prevailing sats per vbyte fee rate \
+**For withdrawals**: \~170 vbtytes times the prevailing sats per vbyte rate 
+
+And although many deposits and withdrawals can be combined, these values should be the maximum that a user will be charged regardless of how many other deposits or withdrawals are being serviced in a single transaction by the Signers. Meaning when more than one user's request is included in a sweep transaction on the L1, the users share the fees in proportion to their deposit or withdrawal request's actual weight on the L1.

docs/build/sbtc/how-to-use-the-sbtc-js-library-for-bridging/btc-to-sbtc.md

@@ -171,14 +171,29 @@ And that's all to it. You've successfully allowed your app to handle incoming sB
 
 ***
 
-### \[Insights] What are the different bitcoin address types?
+### \[Additional Insights] 
+
+### What are the different bitcoin address types?
 
 Bitcoin addresses come in several types, each serving specific purposes and providing different functionalities. Each address type has evolved to enhance security, scalability, and functionality of Bitcoin transactions in response to the network's growing needs.
 
 Check out the dedicated Hiro blog post to learn more about the why and how different bitcoin addresses are constructed:
 
 {% embed url="https://www.hiro.so/blog/understanding-the-differences-between-bitcoin-address-formats-when-developing-your-app" %}
 
+### Why does the withdrawal (peg-out) take longer to provide a bitcoin txid from the Emily API?
+
+The current flow right now goes like this:
+
+1. The user creates a withdrawal request via a contract call on Stacks. In this example, let's say the withdrawal transaction is confirmed in a Stacks block anchored to a Bitcoin block at height N.
+2. The Signers and Emily get the event from the contract call above. Emily marks the withdrawal as pending.
+3. The Signers wait until that Bitcoin block is final enough, which is at Bitcoin block N+6. When that Bitcoin block arrives they create and broadcast a sweep transaction fulfilling the withdrawal request. Then the Signers tell Emily that they have accepted the withdrawal request.
+4. Usually the sweep transaction is included in the next block, so it's confirmed at block N+7.
+5. The Signers issue the contract call finalizing the withdrawal on Stacks, and Emily finds out about the transaction fulfilling the withdrawal.
+
+Here are some useful notes about the above process: \
+When the Signers tell Emily that the withdrawal has been accepted, they don't tell her about the bitcoin transaction that it's accepted in. This is intentional, because the final transaction fulfilling the withdrawal is not known until it is confirmed. It could also be the case that the Signers attempt to fulfill the withdrawal request but end up never fulfilling it. As in, the Signers could create a transaction fulfilling the withdrawal request, where they broadcast it to the Bitcoin network, but that transaction is never confirmed and never will be. Moreover, this situation is not too unlikely; it can happen when fees spike relative to the user's max fee. The current approach sidesteps all of that UX complexity and prudently informs Emily about the transaction ID after it is known to be confirmed. Moreover, some wallets can tell you if there is a payment made out to you by just examining the Bitcoin mempool. 
+
 [^1]: ```
     type AddressInfo = {
       bech32: boolean;