doc, ui: Add sequence diagrams

basicswap/basicswap.py

@@ -2865,14 +2865,14 @@ class BasicSwap(BaseApp):
 
                     if TxTypes.XMR_SWAP_A_LOCK_REFUND_SPEND not in bid.txns:
                         try:
-                            txid = ci_from.publishTx(xmr_swap.a_lock_refund_spend_tx)
+                            txid_str = ci_from.publishTx(xmr_swap.a_lock_refund_spend_tx)
                             self.logBidEvent(bid.bid_id, EventLogTypes.LOCK_TX_A_REFUND_SPEND_TX_PUBLISHED, '', session)
 
-                            self.log.info('Submitted coin a lock refund spend tx for bid {}, txid {}'.format(bid_id.hex(), txid.hex()))
+                            self.log.info('Submitted coin a lock refund spend tx for bid {}, txid {}'.format(bid_id.hex(), txid_str))
                             bid.txns[TxTypes.XMR_SWAP_A_LOCK_REFUND_SPEND] = SwapTx(
                                 bid_id=bid_id,
                                 tx_type=TxTypes.XMR_SWAP_A_LOCK_REFUND_SPEND,
-                                txid=bytes.fromhex(txid),
+                                txid=bytes.fromhex(txid_str),
                             )
                             self.saveBidInSession(bid_id, bid, session, xmr_swap)
                             session.commit()

basicswap/http_server.py

@@ -639,6 +639,8 @@ class HttpHandler(BaseHTTPRequestHandler):
 
         messages = []
         show_txns = False
+        show_offerer_seq_diagram = False
+        show_bidder_seq_diagram = False
         show_lock_transfers = False
         edit_bid = False
         view_tx_ind = None
@@ -658,6 +660,10 @@ class HttpHandler(BaseHTTPRequestHandler):
                     messages.append('Accept failed ' + str(ex))
             elif b'show_txns' in form_data:
                 show_txns = True
+            elif b'show_offerer_seq_diagram' in form_data:
+                show_offerer_seq_diagram = True
+            elif b'show_bidder_seq_diagram' in form_data:
+                show_bidder_seq_diagram = True
             elif b'edit_bid' in form_data:
                 edit_bid = True
             elif b'edit_bid_submit' in form_data:
@@ -686,6 +692,9 @@ class HttpHandler(BaseHTTPRequestHandler):
         if bid.debug_ind is not None and bid.debug_ind > 0:
             messages.append('Debug flag set: {}, {}'.format(bid.debug_ind, DebugTypes(bid.debug_ind).name))
 
+        data['show_bidder_seq_diagram'] = show_bidder_seq_diagram
+        data['show_offerer_seq_diagram'] = show_offerer_seq_diagram
+
         old_states = []
         num_states = len(bid.states) // 12
         for i in range(num_states):
@@ -988,6 +997,10 @@ class HttpHandler(BaseHTTPRequestHandler):
                     self.putHeaders(status_code, 'text/css')
                     with open(os.path.join(static_path, 'style.css'), 'rb') as fp:
                         return fp.read()
+                elif len(url_split) > 3 and url_split[2] == 'sequence_diagrams':
+                    self.putHeaders(status_code, 'image/svg+xml')
+                    with open(os.path.join(static_path, 'sequence_diagrams', url_split[3]), 'rb') as fp:
+                        return fp.read()
                 else:
                     self.putHeaders(status_code, 'text/html')
                     return self.page_404(url_split)

basicswap/templates/bid.html

@@ -77,9 +77,29 @@
 {% endif %}
 <input name="edit_bid" type="submit" value="Edit Bid">
 {% endif %}
+<br/>
+{% if data.show_bidder_seq_diagram %}
+<input name="hide_bidder_seq_diagram" type="submit" value="Hide Bidder Sequence Diagram">
+{% else %}
+<input name="show_bidder_seq_diagram" type="submit" value="Show Bidder Sequence Diagram">
+{% endif %}
+{% if data.show_offerer_seq_diagram %}
+<input name="hide_offerer_seq_diagram" type="submit" value="Hide Offerer Sequence Diagram">
+{% else %}
+<input name="show_offerer_seq_diagram" type="submit" value="Show Offerer Sequence Diagram">
+{% endif %}
 <input type="hidden" name="formid" value="{{ form_id }}">
 </form>
 
+{% if data.show_bidder_seq_diagram %}
+<img src="/static/sequence_diagrams/bidder.alt.xu.min.svg" />
+{% endif %}
+
+{% if data.show_offerer_seq_diagram %}
+<img src="/static/sequence_diagrams/offerer.alt.xu.min.svg" />
+{% endif %}
+
+
 
 <h4>Old States</h4>
 <table>

basicswap/templates/bid_xmr.html

@@ -74,6 +74,17 @@
 {% endif %}
 <input name="edit_bid" type="submit" value="Edit Bid">
 {% endif %}
+<br/>
+{% if data.show_bidder_seq_diagram %}
+<input name="hide_bidder_seq_diagram" type="submit" value="Hide Bidder Sequence Diagram">
+{% else %}
+<input name="show_bidder_seq_diagram" type="submit" value="Show Bidder Sequence Diagram">
+{% endif %}
+{% if data.show_offerer_seq_diagram %}
+<input name="hide_offerer_seq_diagram" type="submit" value="Hide Offerer Sequence Diagram">
+{% else %}
+<input name="show_offerer_seq_diagram" type="submit" value="Show Offerer Sequence Diagram">
+{% endif %}
 <input type="hidden" name="formid" value="{{ form_id }}">
 
 {% if data.show_txns %}
@@ -119,6 +130,14 @@
 {% endif %}
 </form>
 
+{% if data.show_bidder_seq_diagram %}
+<img src="/static/sequence_diagrams/xmr.bidder.alt.xu.min.svg" />
+{% endif %}
+
+{% if data.show_offerer_seq_diagram %}
+<img src="/static/sequence_diagrams/xmr.offerer.alt.xu.min.svg" />
+{% endif %}
+
 {% if data.chain_a_lock_tx_inputs %}
 <h5>Chain A Lock TX Inputs:</h5>
 <table>

doc/protocols/sequence_diagrams/bidder.alt.xu

@@ -0,0 +1,59 @@
+xu {
+    hscale = "1.2";
+
+    CB [label=" ", linecolor="transparent"],
+    N [label="Network", linecolor="#008800", textbgcolor="#CCFFCC", arclinecolor="#008800"],
+    O [label="Offerer", linecolor="#FF0000", textbgcolor="#FFCCCC", arclinecolor="#FF0000"],
+    B [label="Bidder", linecolor="#0000FF", textbgcolor="#CCCCFF", arclinecolor="#0000FF"],
+    C [label=" ", linecolor="transparent"], C2 [label=" ", linecolor="transparent"];
+    O =>> N [label="Sends Offer"];
+    N >> B [label="Detects Offer"];
+    B =>> O [label="Sends Bid"];
+    B abox B [label="Bid Sent"];
+    O box O [label="User accepts bid"];
+    O =>> N [label="Sends Initiate Tx"],
+    C note C2
+        [label="Offerer generates secret_value and sends Hash(secret_value) to the Bidder",
+         textbgcolor="#FFFFCC"];
+    O =>> B [label="Sends BidAccept"],
+    C note C2
+        [label="ITX can be spent by
+                knowledge of the secret_value and the bidder_redeem_key or
+                after a timeout by the offerer_refund_key",
+         textbgcolor="#FFFFCC"];
+
+    B abox B [label="Bid Accepted"];
+    N >> B [label="Detects Initiate Tx"];
+    B abox B [label="ITX Sent", textbgcolor="#4bdbf1"];
+    B => B [label="Wait for ITX to confirm"], O => O [label="Wait for ITX to confirm"];
+    B abox B [label="ITX Confirmed", textbgcolor="#4bdbf1"];
+    B =>> N [label="Sends Participate Tx"],
+    C note C2
+        [label="PTX can be spent by
+                knowledge of the secret_value and the offerer_redeem_key or
+                after a timeout by the bidder_refund_key",
+         textbgcolor="#FFFFCC"];
+    B abox B [label="PTX Sent", textbgcolor="#f1db4b"];
+    N >> O [label="Detects Participate Tx"];
+    B => B [label="Wait for PTX to confirm"], O => O [label="Wait for PTX to confirm"];
+    B abox B [label="PTX Confirmed", textbgcolor="#f1db4b"];
+    B abox B [label="Bid Participating"];
+    O =>> N [label="Sends Participate Redeem Tx"],
+    C note C2
+        [label="Reveals secret_value",
+         textbgcolor="#FFFFCC"];
+    CB alt C [label="success path"] {
+        N >> B [label="Detects Participate Redeem Tx"];
+        B abox B [label="PTX Redeemed", textbgcolor="#f1db4b"];
+        B =>> N [label="Sends Initiate Redeem Tx"];
+        B => B [label="Wait for ITX Redeem to confirm"];
+        B abox B [label="ITX Redeemed", textbgcolor="#4bdbf1"];
+        B abox B [label="Bid Completed"];
+    --- [label="fail path"];
+        B => B [label="Wait for PTX locktime to expire"];
+        B =>> N [label="PTX Refund Tx"];
+        B => B [label="Wait for PTX Refund to confirm"];
+        B abox B [label="PTX Refunded", textbgcolor="#f1db4b"];
+    };
+}
+

doc/protocols/sequence_diagrams/offerer.alt.xu

@@ -0,0 +1,69 @@
+xu {
+    hscale = "1.2";
+
+    CB [label=" ", linecolor="transparent"],
+    N [label="Network", linecolor="#008800", textbgcolor="#CCFFCC", arclinecolor="#008800"],
+    O [label="Offerer", linecolor="#FF0000", textbgcolor="#FFCCCC", arclinecolor="#FF0000"],
+    B [label="Bidder", linecolor="#0000FF", textbgcolor="#CCCCFF", arclinecolor="#0000FF"],
+    C [label=" ", linecolor="transparent"], C2 [label=" ", linecolor="transparent"];
+    O =>> N [label="Sends Offer"];
+    N >> B [label="Detects Offer"];
+    B =>> O [label="Sends Bid"];
+    O abox O [label="Bid Received"];
+    O box O [label="User accepts bid"];
+    O =>> N [label="Sends Initiate Tx"],
+    C note C2
+        [label="Offerer generates secret_value and sends Hash(secret_value) to the Bidder",
+         textbgcolor="#FFFFCC"];
+    O =>> B [label="Sends BidAccept"],
+    C note C2
+        [label="ITX can be spent by
+                knowledge of the secret_value and the bidder_redeem_key or
+                after a timeout by the offerer_refund_key",
+         textbgcolor="#FFFFCC"];
+
+    O abox O [label="Bid Accepted"];
+    O abox O [label="ITX Sent", textbgcolor="#4bdbf1"];
+    N >> B [label="Detects Initiate Tx"];
+    B => B [label="Wait for ITX to confirm"], O => O [label="Wait for ITX to confirm"];
+    O abox O [label="Bid Initiated"];
+    O abox O [label="ITX Confirmed"];
+    CB alt C [label="success path"] {
+        B =>> N [label="Sends Participate Tx"],
+        C note C2
+            [label="PTX can be spent by
+                    knowledge of the secret_value and the offerer_redeem_key or
+                    after a timeout by the bidder_refund_key",
+             textbgcolor="#FFFFCC"];
+        N >> O [label="Detects Participate Tx"];
+        O abox O [label="PTX Sent", textbgcolor="#f1db4b"];
+        O => O [label="Wait for PTX to confirm"];
+        O abox O [label="PTX Confirmed", textbgcolor="#f1db4b"];
+        O abox O [label="Bid Participating"];
+        O =>> N [label="Sends Participate Redeem Tx"],
+        C note C2
+            [label="Reveals secret_value",
+             textbgcolor="#FFFFCC"];
+        N >> B [label="Detects Participate Redeem Tx"];
+        O abox O [label="PTX Redeemed", textbgcolor="#f1db4b"];
+        CB alt C [label="success path"] {
+            B =>> N [label="Sends Initiate Redeem Tx"];
+            O => O [label="Wait for ITX Redeem to confirm"];
+            O abox O [label="ITX Redeemed", textbgcolor="#4bdbf1"];
+            O abox O [label="Bid Completed"];
+        --- [label="fail path, offerer refunds ITx, bidder loses"];
+            O => O [label="Wait for ITX locktime to expire"];
+            O =>> N [label="ITX Refund Tx"];
+            O => O [label="Wait for ITX Refund to confirm"];
+            O abox O [label="ITX Refunded", textbgcolor="#4bdbf1"];
+            O abox O [label="Bid Completed"];
+        };
+    --- [label="fail path"];
+        O => O [label="Wait for ITX locktime to expire"];
+        O =>> N [label="ITX Refund Tx"];
+        O => O [label="Wait for ITX Refund to confirm"];
+        O abox O [label="ITX Refunded", textbgcolor="#4bdbf1"];
+        O abox O [label="Bid Completed"];
+    };
+
+}

doc/protocols/sequence_diagrams/xmr.offerer.alt.xu

@@ -0,0 +1,73 @@
+xu {
+    hscale="1.3", wordwraparcs=on;
+
+    CB [label=" ", linecolor="transparent"],
+    N [label="Network", linecolor="#008800", textbgcolor="#CCFFCC", arclinecolor="#008800"],
+    O [label="Offerer", linecolor="#FF0000", textbgcolor="#FFCCCC", arclinecolor="#FF0000"],
+    B [label="Bidder", linecolor="#0000FF", textbgcolor="#CCCCFF", arclinecolor="#0000FF"],
+    C [label=" ", linecolor="transparent"], C2 [label=" ", linecolor="transparent"];
+    O =>> N [label="Sends Offer"];
+    N >> B [label="Detects Offer"];
+    B =>> O [label="Sends Bid"];
+    O abox O [label="Bid Receiving"];
+    O abox O [label="Bid Received"];
+    O box O [label="User accepts bid"];
+    O =>> B [label="Sends BidAccept message"],
+            C note C2
+                [label="The BidAccept message contains the pubkeys the offerer will use and a DLEAG proof one key will work across both chains of the swapping coins",
+                 textbgcolor="#FFFFCC"];
+    O abox O [label="Bid Accepted"];
+    B =>> O [label="Sends XmrBidLockTxSigsMessage"],
+            C note C2
+                [label="The XmrBidLockTxSigsMessage contains the bidder's signatures for the script-coin-lock-refund and script-coin-lock-refund-spend txns.",
+                 textbgcolor="#FFFFCC"];
+    O =>> B [label="Sends XmrBidLockSpendTxMessage"],
+            C note C2
+                [label="The XmrBidLockSpendTxMessage contains the script-coin-lock-tx and the offerer's signature for it.",
+                 textbgcolor="#FFFFCC"];
+    O =>> N [label="Sends script-coin-lock-tx"],
+    O abox O [label="Bid Script coin spend tx valid"];
+    |||;
+    B => B [label="Wait for script-coin-lock-tx to confirm"], O => O [label="Wait for script-coin-lock-tx to confirm"];
+    O abox O [label="Bid Script coin locked"];
+    CB alt C [label="success path"] {
+        B =>> N [label="Sends noscript-coin-lock-tx"];
+        |||;
+        O => O [label="Wait for noscript-coin-lock-tx to confirm"];
+        O abox O [label="Bid Scriptless coin locked"];
+        O => B [label="Sends script-coin-lock-tx release message"],
+                C note C2
+                    [label="The XmrBidLockReleaseMessage contains the offerer's OTVES for the script-coin-lock-tx.
+                            The bidder decodes the offerer's signature from the OTVES.
+                            When the offerer has the plaintext signature, they can decode the bidder's key for the noscript-lock-tx.",
+                     textbgcolor="#FFFFCC"];
+        O abox O [label="Bid Script coin lock released"];
+        B =>> N [label="Sends script-coin-lock-spend-tx"];
+        N >> O [label="Detects script-coin-lock-spend-tx"];
+        O abox O [label="Bid Script tx redeemed"],
+                C note C2
+                    [label="The offerer extracts the bidder's plaintext signature and derives the bidder's noscript-lock-tx keyhalf.",
+                     textbgcolor="#FFFFCC"];
+        O =>> N [label="Sends noscript-coin-lock-spend-tx"];
+        O abox O [label="Bid Scriptless tx redeemed"];
+        |||;
+        O => O [label="Wait for noscript-coin-lock-spend-tx to confirm"];
+        O abox O [label="Bid Completed"];
+    --- [label="fail path"];
+        |||;
+        O => O [label="Wait for script-coin-lock-tx locktime to expire"];
+        O =>> N [label="Sends script-coin-lock-pre-refund-tx"],
+                C note C2
+                    [label="tx can be sent by either party.",
+                     textbgcolor="#FFFFCC"];
+        N >> O [label="script-coin-lock-pre-refund-tx"];
+        O abox O [label="Bid Script pre-refund tx in chain"];
+        |||;
+        O => O [label="Wait for pre-refund tx to confirm"];
+        O =>> N [label="Sends script-coin-lock-pre-refund-spend-tx"],
+                C note C2
+                    [label="Refunds the script lock tx, with the offerer's cleartext signature the bidder can refund the noscript lock tx.",
+                     textbgcolor="#FFFFCC"];
+        O abox O [label="Bid Failed, refunded"];
+    };
+}

doc/protocols/sequence_diagrams/xmr.offerer.simple.xu

@@ -0,0 +1,55 @@
+xu {
+    hscale="1.3", wordwraparcs=on;
+
+    CB [label=" ", linecolor="transparent"],
+    N [label="Network", linecolor="#008800", textbgcolor="#CCFFCC", arclinecolor="#008800"],
+    O [label="Offerer", linecolor="#FF0000", textbgcolor="#FFCCCC", arclinecolor="#FF0000"],
+    B [label="Bidder", linecolor="#0000FF", textbgcolor="#CCCCFF", arclinecolor="#0000FF"],
+    C [label=" ", linecolor="transparent"], C2 [label=" ", linecolor="transparent"];
+    O =>> N [label="Sends Offer"];
+    N >> B [label="Detects Offer"];
+    B =>> O [label="Sends Bid"];
+    O abox O [label="Bid Receiving"];
+    O abox O [label="Bid Received"];
+    O box O [label="Input: Accepts bid"];
+    O =>> B [label="Sends BidAccept message"],
+            C note C2
+                [label="The BidAccept message contains the pubkeys the offerer will use and a DLEAG proof one key will work across both chains of the swapping coins",
+                 textbgcolor="#FFFFCC"];
+    O abox O [label="Bid Accepted"];
+    B =>> O [label="Sends XmrBidLockTxSigsMessage"],
+            C note C2
+                [label="The XmrBidLockTxSigsMessage contains the bidder's signatures for the script-coin-lock-refund and script-coin-lock-refund-spend txns.",
+                 textbgcolor="#FFFFCC"];
+    O =>> B [label="Sends XmrBidLockSpendTxMessage"],
+            C note C2
+                [label="The XmrBidLockSpendTxMessage contains the script-coin-lock-tx and the offerer's signature for it.",
+                 textbgcolor="#FFFFCC"];
+    O =>> N [label="Sends script-coin-lock-tx"],
+    O abox O [label="Bid Script coin spend tx valid"];
+    |||;
+    B => B [label="Wait for script-coin-lock-tx to confirm"], O => O [label="Wait for script-coin-lock-tx to confirm"];
+    O abox O [label="Bid Script coin locked"];
+    B =>> N [label="Sends noscript-coin-lock-tx"];
+    |||;
+    O => O [label="Wait for noscript-coin-lock-tx to confirm"];
+    O abox O [label="Bid Scriptless coin locked"];
+    O => B [label="Sends script-coin-lock-tx release message"],
+            C note C2
+                [label="The XmrBidLockReleaseMessage contains the offerer's OTVES for the script-coin-lock-tx.
+                        The bidder decodes the offerer's signature from the OTVES.
+                        When the offerer has the plaintext signature, they can decode the bidder's key for the noscript-lock-tx.",
+                 textbgcolor="#FFFFCC"];
+    O abox O [label="Bid Script coin lock released"];
+    B =>> N [label="Sends script-coin-lock-spend-tx"];
+    N >> O [label="Detects script-coin-lock-spend-tx"];
+    O abox O [label="Bid Script tx redeemed"],
+            C note C2
+                [label="The offerer extracts the bidder's plaintext signature and derives the bidder's noscript-lock-tx keyhalf.",
+                 textbgcolor="#FFFFCC"];
+    O =>> N [label="Sends noscript-coin-lock-spend-tx"];
+    O abox O [label="Bid Scriptless tx redeemed"];
+    |||;
+    O => O [label="Wait for noscript-coin-lock-spend-tx to confirm"];
+    O abox O [label="Bid Completed"];
+}