Merge pull request #112 from ChrisSon15/main

reorg of documentation and concept. delet of 'renderedForWeb' directory, uses pandoc  --katex in github actions to deploy the md-files as html files to github pages.

Author: ChrisSon15

.github/workflows/deploy-pages.yml

@@ -0,0 +1,68 @@
+name: Deploy MD to GitHub Pages
+
+on:
+  push:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pandoc and katex
+        run: |
+          sudo apt-get update && sudo apt-get install -y pandoc
+          npm install katex
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Build HTML from MD
+        run: |
+          mkdir -p public
+          # Find all .md files and convert them
+          find . -name "*.md" -not -path "./target/*" -not -path "./.github/*" | while read md_file; do
+            # Create the same directory structure in public/
+            relative_path=$(realpath --relative-to="." "$md_file")
+            html_file="public/${relative_path%.md}.md.html"
+            mkdir -p "$(dirname "$html_file")"
+            
+            echo "Converting $md_file to $html_file"
+            pandoc "$md_file" -s -o "$html_file" --metadata title="${relative_path%.md}" --lua-filter="$GITHUB_WORKSPACE/concept/pandoc/convert_links.lua" --css="$GITHUB_WORKSPACE/concept/pandoc/fullwidth.css" --embed-resources --standalone --katex="node_modules/katex/dist/"
+          done
+          
+          # Copy other assets like images, and existing HTML files
+          # We use -n to not overwrite the HTML files we just generated from MD
+          find . -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.svg" -o -name "*.html" -o -name "*.css" -o -name "*.js" \) -not -path "./target/*" -not -path "./.github/*" -not -path "./public/*" | while read asset; do
+             relative_path=$(realpath --relative-to="." "$asset")
+             dest="public/$relative_path"
+             mkdir -p "$(dirname "$dest")"
+             cp -n "$asset" "$dest"
+          done
+          
+          # Create an index.html 
+          cp public/README.md.html public/index.html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './public'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,6 @@
 target
 .idea
-/concept/tmp/
 .classpath
 .project
 .settings
+/concept/pandoc/output/

README.md

@@ -1,4 +1,4 @@
-# bisq MuSig2 Protocol
+# Bisq MuSig2 Protocol
 
 This is module inside Bisq2. it implements a new Multisig protocol for Bisq2, this protocol is similar to the protocol used in Bisq1.
 It enables to buy/sell bitcoin from other peers without needing any trust in the other peer or into any coordinator or any third party. Since there is no intermediary to
@@ -13,12 +13,15 @@ Main changes to the Bisq1 protocol are:
 
 ## overview
 
-This project is the handling the cryptographic part of the overall protocol. Even though it is the centerpiece there are more pieces necessary to pull this off.
+This project is the handling the cryptographic part of the overall protocol. Even though it is the centerpiece
+there are more pieces necessary to pull this off.
 Here is an Overview drawing:
-![modules](concept/renderedForWeb/bisq-musig-modules.png)
+
+![modules](concept/bisq-musig-modules.png)
 
 ## docs
 
+Detailed docs are in the [Concepts](concept/README.md) section.
 To get a more indepth understanding of what this module is doing, please read [SingleTxOverview](./concept/SingleTxOverview.md)
 This module's programming language is Rust.
 Technologies include:
@@ -77,5 +80,5 @@ cargo test --package protocol --lib --tests -- --nocapture
 ## reading the Markdown files
 
 Some of the markdown files have LaTeX included, you can best view them using RustRover.
-Github sucks at displaying LaTeX. I also keep an html-export of the markdown files
-in the directory 'renderedForWeb', so you can view them without RustRover.
+Github sucks at displaying LaTeX. There is also an html export on the github pages of the project
+at [github pages](https://chrisson15.github.io/bisq-musig/)

concept/MuSig2adaptor-rust.md

@@ -12,18 +12,20 @@ of a 2of2 multisig such that when Alice uses it, she must reveal $t$ to Bob.
 
 Let
 
-$$T=t \cdot G$$
-
-where \
-$t$ is secret adaptor, the secret which will be revealed\
-$T$ is public adaptor\
-$G$ is the Generator point of secp256k1\
-$m$ (the message) is the serialisation of a transaction which spends the output of the 2of2 Multisig.
+$$T=t \cdot G $$
+$$\begin{aligned}
+\text{where}& \hspace{1000pt} \\
+t & \text{ is secret adaptor, the secret which will be revealed} \\
+T &\text{ is public adaptor} \\
+G &\text{ is the Generator point of secp256k1} \\
+m &\text{ (the message) is the serialisation of a transaction which spends the output of the 2of2 Multisig.}
+\end{aligned}
+$$
 
 The function $H_{tagged}(x_1,...,x_n)$ is a hash function where the name 'tagged' is used as literal to init the hash
 and if $x_i$ is a Curvepoint then we use the compressed x-key instead. Operator '||' stands for concatenation.
 
-$$H_{tagged}(x_1,...,x_n):=sha256(sha256(sha256('tagged')||sha256('tagged'))||x_1||...||x_n)$$
+$$H_{tagged}(x_1,...,x_n):=sha256(sha256(sha256('tagged')~||~sha256('tagged'))||x_1||...||x_n)$$
 
 ## key aggregation
 
@@ -37,11 +39,13 @@ Alice does the Key Aggregation in MuSig2
 
 $$(1) \hspace{5pt} P = a_a \cdot P_a + a_b \cdot P_b$$
 
-$ \begin{eqnarray}
-where \\ \hspace{5pt} a_a &=& H_{agg}(sha256(P_a,P_b),P_a) \\
-a_b &=& 1 \\
-P_a &\ne& P_b
-\end{eqnarray}$
+$$\begin{aligned}
+\text{where}& \\
+a_a &= H_{agg}(sha256(P_a,P_b),P_a)  \hspace{1000pt} \\
+a_b &= 1 \\
+P_a &\ne P_b \\
+\end{aligned}
+$$
 
 by calling `KeyAggContext::new([P_a,P_b])` with the pubkeys of all participants.
 $a_i$ is called the coefficients.
@@ -58,12 +62,12 @@ Up to here, its independent of the message and can be precalculated.
 
 From collected Nonce the aggregated Nonce $R$ is calculated:
 
-$\hspace{100pt}\begin{eqnarray*}
-(2)\hspace{5pt} R_1 &=& R_{a,1} + R_{b,1} \\
-R_2 &=& R_{a,2} + R_{b,2} \\
-b &=& H_{non}(R_1 , R_2, P, m) \\
-(3)\hspace{5pt} R &=& R_1 + b \cdot R_2 + T
-\end{eqnarray*}$
+$$\begin{aligned}
+(2)~~ R_1 &= R_{a,1} + R_{b,1} \\
+R_2 &= R_{a,2} + R_{b,2} \\
+b &= H_{non}(R_1 , R_2, P, m) \\
+(3)~~ R &= R_1 + b \cdot R_2 + T
+\end{aligned}$$
 
 Note that the $T$ is added to $R$, this seperates normal MuSig2 from adaptive MuSig2.
 This is done via `AggNonce::sum()` and `musig2::adaptor::sign_partial(T)`. This is split into 2 methods, the aggregated Nounce is in `musig2`
@@ -100,21 +104,21 @@ pre-signature, not a valid signature.
 We can prove that this pre-signature is indeed a valid adaptor signature by multiplying with $G$ and
 setting $e:=H_{sig}(R,P,m)$:
 
-$\begin{eqnarray}
-s\cdot G &=& s_a\cdot G+s_b\cdot G ;| \hspace{3pt} with (4) \\
-&=&(r_{a,1} + b \cdot r_{a,2} + a_a \cdot e \cdot p_a)\cdot G + (r_{b,1}+b \cdot r_{b,2} + a_b \cdot e \cdot p_b)\cdot G \\
-&=&R_{a,1}+b\cdot R_{a,2} + a_a\cdot e \cdot P_a + R_{b,1}+b\cdot R_{b,2} + a_b\cdot e \cdot P_b;| \hspace{3pt} with (2) \\
-&=& R_1 + b \cdot R_2 + a_a \cdot e \cdot P_a + a_b \cdot e \cdot P_b;| \hspace{3pt} with (1) \\
-&=& R_1 + b \cdot R_2 + e \cdot P;| \hspace{3pt} with (3) \\
-&=& R - T + e \cdot P
-\end{eqnarray}$
+$$\begin{aligned}
+s\cdot G &= s_a\cdot G+s_b\cdot G ;| ~~ with (4) \\
+&=(r_{a,1} + b \cdot r_{a,2} + a_a \cdot e \cdot p_a)\cdot G + (r_{b,1}+b \cdot r_{b,2} + a_b \cdot e \cdot p_b)\cdot G \\
+&=R_{a,1}+b\cdot R_{a,2} + a_a\cdot e \cdot P_a + R_{b,1}+b\cdot R_{b,2} + a_b\cdot e \cdot P_b;| ~~ with (2) \\
+&= R_1 + b \cdot R_2 + a_a \cdot e \cdot P_a + a_b \cdot e \cdot P_b;| ~~ with (1) \\
+&= R_1 + b \cdot R_2 + e \cdot P;| ~~ with (3) \\
+&= R - T + e \cdot P
+\end{aligned}$$
 
 that means
 
-$$\begin{eqnarray}
-s \cdot G + T &=& R+e \cdot P \\
-\Leftrightarrow (s + t) \cdot G &=& R + e \cdot P
-\end{eqnarray}$$
+$$\begin{aligned}
+s \cdot G + T &= R+e \cdot P \\
+\Leftrightarrow (s + t) \cdot G &= R + e \cdot P
+\end{aligned}$$
 
 so with the discrete logarithm (DLOG) of $T$, which is  $t$, we would have a valid signature.
 

concept/ProtocolSubStates.md

@@ -8,6 +8,7 @@ substates of it. It is intended that this state maschine will be implemented in
 Bisq2 using the FSM.
 
 ![StateMachine.drawio.png](StateMachine.drawio.png)
+
 1. signing of Txs
    this is already implemented in rust, basically the running test link serves as a rust 
    implementation of what needs to be implemented in Java with FSM. Please see the [test-case here](https://github.com/bisq-network/bisq-musig/blob/main/protocol/src/lib.rs#L23).
@@ -19,29 +20,29 @@ Bisq2 using the FSM.
    -no substates-
 
 3. Seller broadcasts SwapTx
-   3.1. Seller broadcasts SwapTx has no additional state fpr the seller
-   3.2. Buyer gets informed of chain-services that SwapTx is being detected, then continue with 6.
+    1. Seller broadcasts SwapTx has no additional state for the seller
+    2. Buyer gets informed of chain-services that SwapTx is being detected, then continue with 6.
 
-4. Traders exchange secret keys for P'
-   4.1. Seller sends hie partial key to Buyer
-   4.2. Buyer receives a partial key from Seller
-   4.3. continue with 7.
+4. Traders exchange secret keys for P'\
+    1. Seller sends hie partial key to Buyer\
+    1. Buyer receives a partial key from Seller
+    1. continue with 7.
 
-5. Seller or Buyer broadcast WarningTx
+5. Seller or Buyer broadcast WarningTx.
    Note that there are two (slightly) different WarningTxs for seller and buyer
-   5.1. S or B presses the button to broadcast WarningTx
-   5.2. B or S sees that WarningTx is confirmed on blockchain (seeing in mempool is not enough)
-   5.3. continue with 8.
+    1. S or B presses the button to broadcast WarningTx
+    2. B or S sees that WarningTx is confirmed on blockchain (seeing in mempool is not enough)
+    3. continue with 8.
 
 6. No additional substates (will be one call to the rust code)
 
 7. Traders exchange secret keys for Q'
-   7.1. Buyer send private key for Q' to seller
-   7.2. Users (Buyer and seller) get informed that the trade is over and funds can be spend.
+    1. Buyer send private key for Q' to seller
+    2. Users (Buyer and seller) get informed that the trade is over and funds can be spend.
 
-8.+9. can be made into one state API-call for the java code.
+8. +9. can be made into one state API-call for the java code.
 Something like checkWarningKeysExchanged(...) could be called and returns true iff keys were present and funds have been transafered to wallet.
-9.1. Users need to be informed about funds being transferred.
+    1. Users need to be informed about funds being transferred.
 
 10. t1 expired
     time trigger should go off if other trader broadcasted the WarningTx and t1 expired. no substates

concept/README.md

@@ -0,0 +1,24 @@
+# Concept of the Protocol Bisq-MuSig
+
+## Initial idea
+
+- [SingleTxOverview.md](SingleTxOverview.md)
+- [MuSig2adaptor-rust.md](MuSig2adaptor-rust.md)
+
+## Updates to the initial idea
+
+- [update.md](update.md)
+- [ProtocolUpdate2.md](ProtocolUpdate2.md)
+
+## Different aspects in detail
+
+- [OverviewWatchTowers.md](watchtower/OverviewWatchTowers.md)
+- [partialTransaction.md](partialTransaction.md)
+- [ProtocolSubStates.md](ProtocolSubStates.md)
+- [tradefeepayment.md](tradefees/tradefeepayment.md)
+- [SilentPayment.md](silentpayment/SilentPayment.md)
+- [SPDepositTx.md](silentpayment/SPDepositTx.md)
+
+## API
+
+- [API.md](API.md)