From 63094fecee54d3c3812e2896297f3c703ca407a2 Mon Sep 17 00:00:00 2001 From: sudikshyapant Date: Mon, 7 Oct 2024 22:33:21 +0545 Subject: [PATCH 1/6] docs: apply formatting updates # Documentation Pull Request Template ## Description This pull request updates the Bitcoin bridge documentation to improve clarity, accuracy, and completeness. The main changes are: 1. Update time-lock to 1 week based on current DRT implementation 2. Add information on current operator fee and mining fees 3. Ensure proper nesting in points of deposit process 4. Minor improvements to the withdrawal process description for better clarity. These updates aim to provide more accurate and up-to-date information about the Bitcoin bridge operations, enhancing user understanding and reducing potential misinterpretations. --- ## Type of Change - [ ] New Document - [x] Update to Existing Document - [ ] Bug Fix - [ ] Question/clarification - [ ] Other (please describe): --- ## Related Issues Fixes #[issue number related to documentation update, if any] --- ## Checklist - [x] I have reviewed the existing documentation to avoid duplication. - [x] The new or updated document includes clear and concise information. - [ ] All relevant sections (e.g., introduction, usage examples, references) are included. - [x] The document follows the project's style guide and formatting rules. - [ ] I have included any necessary references or external resources. - [x] Spellcheck and grammar check have been performed. - [x] (For updates) I have verified that the changes reflect the current state of the project. --- ## Additional Information The updates to the time-lock period and fee information reflect the current implementation of the Bitcoin bridge. The restructuring of certain sections aims to improve readability and reduce potential misunderstandings. --- ## Reviewer Checklist - [ ] The purpose and scope of the document are clear. - [ ] The document is easy to understand and follow. - [ ] There are no typos or grammatical errors. - [ ] All necessary sections are included and well-structured. - [ ] The document is consistent with the project's style guide. - [ ] Any referenced links or resources are valid and appropriate. --- docs/technical/bitcoin-bridge.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index cf7db64..5fe1d09 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -8,7 +8,7 @@ as "bitcoin signet" or "signet BTC" when describing the current system. The Strata bitcoin bridge enables the transfer of BTC between the bitcoin -and Strata blockchains. +and Strata blockchain. The bridge is run by a federation of operators who co-sign transactions to move BTC into and out of the Strata bridge address. @@ -31,6 +31,7 @@ it is broadcast to bitcoin for confirmation. Deposits and withdrawals are allowed in a denomination of $D$ BTC where $D = 10 \ \text{BTC}$ is a value predefined by the bridge federation. + The operator fee is set at 5% of the bridge denomination. The minimum relay fee for transactions is 10 satoshis per vByte. !!! info @@ -62,14 +63,14 @@ who sends 10[^fees] BTC to a P2TR address, where: This can be verified by revealing the random scalar $r$ used to generate the pubkey by shifting the NUMS point. -1. The script path spend has two paths: - 1. "Deposit path", an $N$-of-$N$ multisig path, +2. The script path spend has two paths: + 1. "Deposit path", an $N$-of-$N$ multisig path, where $N$ is the number of operators in the bridge. - 1. "Take back" path, + 2. "Take back" path, which allows the user to take back their funds if the bridge fails to move funds from the Deposit Request Transaction (DRT) - into the bridge address within a two-week period, - i.e. it is time-locked and the user provides a signature to spend it. + into the bridge address within a 1-week period, + i.e. it is time-locked and the user can spend it by providing a signature. This transaction has some metadata attached to it, in the form of an `OP_RETURN` output, that can be up to 80 bytes long (according to bitcoin standardness policy), @@ -77,12 +78,12 @@ and is composed of the following data: 1. Magic bytes. These take $11$ bytes and are used to identify the bridge. -1. "Take back" TapLeaf hash. +2. "Take back" TapLeaf hash. These take $32$ bytes and are used to validate the Deposit Request Transaction (DRT), while also necessary for the control block required to spend the P2TR output via the $N$-of-$N$ Tapscript. -1. Execution Layer (EL) address. +3. Execution Layer (EL) address. The Execution Layer (EL) address is the Strata address where the user wants to receive the BTC in Strata. It is a 20-byte Ethereum Virtual Machine (EVM) address. @@ -122,16 +123,15 @@ sequenceDiagram The user requests a withdrawal on Strata and an operator is assigned to fulfill the request on bitcoin: -1. The user requests a withdrawal making sure to burn the - same amount of `BTC` on Strata. -1. The assigned operator creates and signs a Withdrawal Transaction - (WT) where they spend 10 BTC from the bridge address' UTXO set, - while subtracting the operator's fee and the mining fee, - and requests the other $N−1$ operators to sign +1. The user initiates a withdrawal request, in response to which the corresponding amount of strata BTC or `sBTC` is burned from Strata. +2. After the burn is confirmed, the assigned operator creates and signs a Withdrawal Transaction + (WT) on the Bitcoin blockchain where they spend 10 BTC from the bridge address' UTXO set, + while subtracting the operator's fee (5% of the bridge denomination) and the mining fee (minimum 10 satoshis per vByte), + and requests the other $N-1$ operators to sign the Withdrawal Transaction. -1. Once all the signatures have been aggregated, the transaction is submitted to +3. Once all the signatures have been aggregated, the transaction is submitted to bitcoin. -1. Once the transaction is confirmed, +4. Once the transaction is confirmed, the withdrawal request is fulfilled. The withdrawal flow is shown below: From a583500f5cc76a135c398e7d909bae1859f697e0 Mon Sep 17 00:00:00 2001 From: sudikshyapant Date: Mon, 7 Oct 2024 22:50:07 +0545 Subject: [PATCH 2/6] fix formatting issue --- docs/technical/bitcoin-bridge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index 5fe1d09..d5ddc4e 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -64,9 +64,9 @@ who sends 10[^fees] BTC to a P2TR address, where: used to generate the pubkey by shifting the NUMS point. 2. The script path spend has two paths: - 1. "Deposit path", an $N$-of-$N$ multisig path, + 1. "Deposit path", an $N$-of-$N$ multisig path, where $N$ is the number of operators in the bridge. - 2. "Take back" path, + 2. "Take back" path, which allows the user to take back their funds if the bridge fails to move funds from the Deposit Request Transaction (DRT) into the bridge address within a 1-week period, From 807d5ed1313cc1cc9136f99ff66e7b81ff5be477 Mon Sep 17 00:00:00 2001 From: John Light Date: Mon, 7 Oct 2024 19:12:55 +0200 Subject: [PATCH 3/6] Fix formatting / typos --- docs/technical/bitcoin-bridge.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index d5ddc4e..ff89ced 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -63,10 +63,10 @@ who sends 10[^fees] BTC to a P2TR address, where: This can be verified by revealing the random scalar $r$ used to generate the pubkey by shifting the NUMS point. -2. The script path spend has two paths: +1. The script path spend has two paths: 1. "Deposit path", an $N$-of-$N$ multisig path, where $N$ is the number of operators in the bridge. - 2. "Take back" path, + 1. "Take back" path, which allows the user to take back their funds if the bridge fails to move funds from the Deposit Request Transaction (DRT) into the bridge address within a 1-week period, @@ -78,12 +78,12 @@ and is composed of the following data: 1. Magic bytes. These take $11$ bytes and are used to identify the bridge. -2. "Take back" TapLeaf hash. +1. "Take back" TapLeaf hash. These take $32$ bytes and are used to validate the Deposit Request Transaction (DRT), while also necessary for the control block required to spend the P2TR output via the $N$-of-$N$ Tapscript. -3. Execution Layer (EL) address. +1. Execution Layer (EL) address. The Execution Layer (EL) address is the Strata address where the user wants to receive the BTC in Strata. It is a 20-byte Ethereum Virtual Machine (EVM) address. @@ -123,15 +123,17 @@ sequenceDiagram The user requests a withdrawal on Strata and an operator is assigned to fulfill the request on bitcoin: -1. The user initiates a withdrawal request, in response to which the corresponding amount of strata BTC or `sBTC` is burned from Strata. -2. After the burn is confirmed, the assigned operator creates and signs a Withdrawal Transaction - (WT) on the Bitcoin blockchain where they spend 10 BTC from the bridge address' UTXO set, - while subtracting the operator's fee (5% of the bridge denomination) and the mining fee (minimum 10 satoshis per vByte), +1. The user initiates a withdrawal request, in response to which the corresponding + amount of Strata BTC is burned. +1. After the burn is confirmed, the assigned operator creates and signs a Withdrawal Transaction + (WT) on the bitcoin blockchain where they spend 10 BTC from the bridge address' UTXO set, + while subtracting the operator's fee (5% of the bridge denomination) and the mining fee + (minimum 10 satoshis per vByte), and requests the other $N-1$ operators to sign the Withdrawal Transaction. -3. Once all the signatures have been aggregated, the transaction is submitted to +1. Once all the signatures have been aggregated, the transaction is submitted to bitcoin. -4. Once the transaction is confirmed, +1. Once the transaction is confirmed, the withdrawal request is fulfilled. The withdrawal flow is shown below: From 29f876a8bdb750354326199ec2ceea19e8fadf9c Mon Sep 17 00:00:00 2001 From: John Light Date: Mon, 7 Oct 2024 19:13:19 +0200 Subject: [PATCH 4/6] Fix typo --- docs/technical/bitcoin-bridge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index ff89ced..0099bbc 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -8,7 +8,7 @@ as "bitcoin signet" or "signet BTC" when describing the current system. The Strata bitcoin bridge enables the transfer of BTC between the bitcoin -and Strata blockchain. +and Strata blockchains. The bridge is run by a federation of operators who co-sign transactions to move BTC into and out of the Strata bridge address. From 3418d17203a204ee4e53a87dfa7fb6b0a806727b Mon Sep 17 00:00:00 2001 From: John Light Date: Mon, 7 Oct 2024 19:20:16 +0200 Subject: [PATCH 5/6] docs: fix line length format Co-authored-by: Jose Storopoli --- docs/technical/bitcoin-bridge.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index 0099bbc..6e6649e 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -31,7 +31,8 @@ it is broadcast to bitcoin for confirmation. Deposits and withdrawals are allowed in a denomination of $D$ BTC where $D = 10 \ \text{BTC}$ is a value predefined by the bridge federation. - The operator fee is set at 5% of the bridge denomination. The minimum relay fee for transactions is 10 satoshis per vByte. + The operator fee is set at 5% of the bridge denomination. + The minimum relay fee for transactions is 10 satoshis per vByte. !!! info From b7984b600c1040f6208d035777062d20d3cee49e Mon Sep 17 00:00:00 2001 From: Jose Storopoli Date: Mon, 7 Oct 2024 14:23:23 -0300 Subject: [PATCH 6/6] fix: lints and formatting --- docs/technical/bitcoin-bridge.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/technical/bitcoin-bridge.md b/docs/technical/bitcoin-bridge.md index 6e6649e..6c3f921 100644 --- a/docs/technical/bitcoin-bridge.md +++ b/docs/technical/bitcoin-bridge.md @@ -46,7 +46,9 @@ it is broadcast to bitcoin for confirmation. The deposit process is initiated by the user, who sends 10[^fees] BTC to a P2TR address, where: -[^fees]: The user must pay the bitcoin network fees for both the Deposit Request and Deposit Transactions. +[^fees]: + The user must pay the bitcoin network fees for both + the Deposit Request and Deposit Transactions. 1. The key path spend is unspendable, following [BIP 341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs) @@ -124,12 +126,13 @@ sequenceDiagram The user requests a withdrawal on Strata and an operator is assigned to fulfill the request on bitcoin: -1. The user initiates a withdrawal request, in response to which the corresponding +1. The user initiates a withdrawal request, in response to which the corresponding amount of Strata BTC is burned. -1. After the burn is confirmed, the assigned operator creates and signs a Withdrawal Transaction - (WT) on the bitcoin blockchain where they spend 10 BTC from the bridge address' UTXO set, - while subtracting the operator's fee (5% of the bridge denomination) and the mining fee - (minimum 10 satoshis per vByte), +1. After the burn is confirmed, the assigned operator creates and signs + Withdrawal Transaction (WT) on the bitcoin blockchain where they spend 10 BTC + from the bridge address' UTXO set, + while subtracting the operator's fee (5% of the bridge denomination) + and the mining fee (minimum 10 satoshis per vByte), and requests the other $N-1$ operators to sign the Withdrawal Transaction. 1. Once all the signatures have been aggregated, the transaction is submitted to