midefos/basicswap
1
0
Fork 0
mirror of https://github.com/basicswap/basicswap.git synced 2025-11-05 10:28:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: Describe reverse adaptor sig protocol.

Browse Source
This commit is contained in:
tecnovert
2023-07-06 15:13:19 +02:00
parent f6fb11f452
commit be46d8a7bd
19 changed files with 1182 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
doc/protocols/xmr.md → doc/protocols/adaptor_sig.md
View File

@@ -1,4 +1,4 @@
# XMR protocol
# Adaptor Signature Swap protocol
## WIP
@@ -10,21 +10,24 @@ An OtVES:
- The encrypting private key (b) can be recovered using both the encrypted and decrypted signatures.
Leader - sends the first lock tx.
Offerer - Sends the offer
Bidder - Sends the bid
Leader - Sends the first lock tx (ITX)
Follower - Sends the second lock tx (PTX)
NOSCRIPT_COIN lock tx:
- sent second
- is sent to a combined key using a private key from each participant.
- Sent second.
- Is sent to a combined key using a private key from each participant.
SCRIPT_COIN lock tx:
- Sent first
- Requires two signatures to spend from.
- Refund to sender txn is presigned for and can only be mined in the future.
- Spending the refund tx reveals the leader's NOSCRIPT_COIN split private key
- Spending the refund tx reveals the leader's NOSCRIPT_COIN split private key.
- Sender withholds signature until NOSCRIPT_COIN lock tx is confirmed.
- spending the spend txn reveals the follower's NOSCRIPT_COIN split private key
- spending the spend txn reveals the follower's NOSCRIPT_COIN split private key.
```
@@ -32,48 +35,49 @@ Offerer (Leader) | Bidder
------------------------------------------------------------------------|-------------------------------------------------------------------------------|
o1. Sends offer | |
- x SCRIPT_COIN for y NOSCRIPT_COIN | |
- sends smsg OfferMessage | |
- Sends smsg OfferMessage | |
| b1. Receives offer |
| - validates offer |
| - Validates offer |
| b2. Sends bid |
| - sends smsgs XmrBidMessage + 2x XmrSplitMessage |
| - Sends smsgs XmrBidMessage + 2x XmrSplitMessage |
| |
o2. Receives bid | |
- validates bid | |
- Validates bid | |
o3. Accepts bid | |
- sends smsgs XmrBidAcceptMessage + 2x XmrSplitMessage | |
- Sends smsgs XmrBidAcceptMessage + 2x XmrSplitMessage | |
| |
| b3. Receives bid accept |
| - validates |
| - signs for lock tx refund |
| - sends smsg XmrBidLockTxSigsMessage |
| - Validates |
| - Signs for lock tx refund |
| - Sends smsg XmrBidLockTxSigsMessage |
| |
o4. Receives bidder lock refund tx signatures | |
- sends smsg XmrBidLockSpendTxMessage | |
- full SCRIPT_COIN lock tx | |
- signature to prove leader can sign for split key | |
- submits SCRIPT_COIN lock tx to network | |
- Sends smsg XmrBidLockSpendTxMessage | |
- Full SCRIPT_COIN lock tx | |
- Signature to prove leader can sign for split key | |
- Submits SCRIPT_COIN lock tx to network | |
| |
| b4. Receives XmrBidLockSpendTxMessage |
| - validates SCRIPT_COIN lock tx and signature |
| - waits for SCRIPT_COIN lock tx to confirm in chain |
| - Validates SCRIPT_COIN lock tx and signature |
| - Waits for SCRIPT_COIN lock tx to confirm in chain |
| b5. Sends NOSCRIPT_COIN lock tx |
| |
o5. Waits for NOSCRIPT_COIN lock tx to confirm in chain | |
o6. Sends SCRIPT_COIN lock release. | |
- sends smsg XmrBidLockReleaseMessage | |
- includes OtVES ciphertext signature for the SCRIPT_COIN lock | |
- Sends smsg XmrBidLockReleaseMessage | |
- Includes OtVES ciphertext signature for the SCRIPT_COIN lock | |
spend tx. | |
| |
| b6. Receives offerer OtVES for SCRIPT_COIN lock spend tx. |
| - submits SCRIPT_COIN lock spend tx to network. |
| - Submits SCRIPT_COIN lock spend tx to network. |
| |
o7. Waits for SCRIPT_COIN lock spend tx. | |
- Extracts the NOSCRIPT_COIN bidders key using the signature | |
o8. Combines the keys to spend from the NOSCRIPT_COIN lock tx | |
- submits NOSCRIPT_COIN lock spend tx to network | |
- Submits NOSCRIPT_COIN lock spend tx to network | |
```
Per swap (including the offer smsg):
Offerer sent 6 smsgs (2 extra from split messages)
Bidder sent 4 smsgs (2 extra from split messages)

85
doc/protocols/adaptor_sig_reversed.md Normal file
View File

@@ -0,0 +1,85 @@
# Reverse Adaptor Signature Swap protocol
## WIP
Offerer - Sends the offer
Bidder - Sends the bid
Leader - Sends the first lock tx (ITX)
Follower - Sends the second lock tx (PTX)
The ITX must be sent from the script chain (coin A).
The side sending the ITX can be switched and the system can abstract to
users that the protocol is running in the opposite direction.
NOSCRIPT_COIN lock tx:
- Sent second.
- Is sent to a combined key using a private key from each participant.
SCRIPT_COIN lock tx:
- Sent first.
- Requires two signatures to spend from.
- Refund to sender txn is presigned for and can only be mined in the future.
- Spending the refund tx reveals the leader's NOSCRIPT_COIN split private key.
- Sender withholds signature until NOSCRIPT_COIN lock tx is confirmed.
- spending the spend txn reveals the follower's NOSCRIPT_COIN split private key.
```
Offerer (Follower) | Bidder (Leader) |
------------------------------------------------------------------------|-------------------------------------------------------------------------------|
o1. Sends offer | |
- x NOSCRIPT_COIN for y SCRIPT_COIN | |
- Sends smsg OfferMessage | |
| b1. Receives offer |
| - Validates offer |
| b2. Sends bid intent message |
| - Sends smsg ADSBidIntentMessage |
| |
o2. Receives bid intent message | |
- Validates bid intent | |
o3. Accepts bid intent message | |
- Sends smsgs ADSBidIntentAcceptMessage + 2x XmrSplitMessage | |
| |
| b3. Receives bid intent message |
| - Sends smsgs XmrBidAcceptMessage + 2x XmrSplitMessage |
| |
o4. Receives bid accept | |
- Validates | |
- Signs for lock tx refund | |
- Sends smsg XmrBidLockTxSigsMessage | |
| |
| b4. Receives bidder lock refund tx signatures |
| - Sends smsg XmrBidLockSpendTxMessage |
| - Full SCRIPT_COIN lock tx |
| - Signature to prove leader can sign for split key |
| - Submits SCRIPT_COIN lock tx to network |
| |
o5. Receives XmrBidLockSpendTxMessage | |
- Validates SCRIPT_COIN lock tx and signature | |
- Waits for SCRIPT_COIN lock tx to confirm in chain | |
o6. Sends NOSCRIPT_COIN lock tx | |
| |
| b5. Waits for NOSCRIPT_COIN lock tx to confirm in chain |
| b6. Sends SCRIPT_COIN lock release. |
| - Sends smsg XmrBidLockReleaseMessage |
| - Includes OtVES ciphertext signature for the SCRIPT_COIN lock |
| spend tx. |
| |
o7. Receives leader OtVES for SCRIPT_COIN lock spend tx. | |
- Submits SCRIPT_COIN lock spend tx to network. | |
| |
| b7. Waits for SCRIPT_COIN lock spend tx. |
| - Extracts the NOSCRIPT_COIN follower's key using the signature |
| b8. Combines the keys to spend from the NOSCRIPT_COIN lock tx |
| - Submits NOSCRIPT_COIN lock spend tx to network |
```
Per swap (including the offer smsg):
Offerer sent 5 smsgs (2 extra from split messages)
Bidder sent 6 smsgs (2 extra from split messages)

0
doc/protocols/seller_first.md → doc/protocols/secret_hash_seller_first.md
View File

0
doc/protocols/sequence_diagrams/xmr.bidder.alt.xu → doc/protocols/sequence_diagrams/ads.bidder.alt.xu
View File

0
doc/protocols/sequence_diagrams/xmr.offerer.alt.xu → doc/protocols/sequence_diagrams/ads.offerer.alt.xu
View File

79
doc/protocols/sequence_diagrams/ads.rev.bidder.xu Normal file
View File

@@ -0,0 +1,79 @@
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 BidIntent message"];
B abox B [label="Bid Request sent"];
O box O [label="User accepts bid"];
O =>> B [label="Sends BidIntentAccept 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"];
B abox B [label="Bid Receiving accept"];
B =>> O [label="Sends BidAccept message"];
B abox B [label="Bid Accepted"];
O =>> B [label="Sends XmrBidLockTxSigsMessage"],
C note C2
[label="The XmrBidLockTxSigsMessage contains the offerer's signatures for the script-coin-lock-refund and script-coin-lock-refund-spend txns.",
textbgcolor="#FFFFCC"];
B abox B [label="Exchanged script lock tx sigs msg"];
B =>> N [label="Sends script-coin-lock-tx"];
B abox B [label="Bid Script coin spend tx valid"];
B =>> O [label="Sends XmrBidLockSpendTxMessage"],
C note C2
[label="The XmrBidLockSpendTxMessage contains the script-coin-lock-tx and proof the bidder can sign it.",
textbgcolor="#FFFFCC"];
B abox B [label="Exchanged script lock spend tx msg"];
|||;
O => O [label="Wait for script-coin-lock-tx to confirm"], B => B [label="Wait for script-coin-lock-tx to confirm"];
B abox B [label="Bid Script coin locked"];
CB alt C [label="success path"] {
O =>> N [label="Sends noscript-coin-lock-tx"];
|||;
B => B [label="Wait for noscript-coin-lock-tx to confirm"];
B abox B [label="Bid Scriptless coin locked"];
B => O [label="Sends script-coin-lock-tx release message"],
C note C2
[label="The XmrBidLockReleaseMessage contains the bidder's OTVES for the script-coin-lock-tx.
The offerer decodes the bidder's signature from the OTVES.
When the bidder has the plaintext signature, they can decode the offerer's key for the noscript-lock-tx.",
textbgcolor="#FFFFCC"];
B abox B [label="Bid Script coin lock released"];
O =>> N [label="Sends script-coin-lock-spend-tx"];
N >> B [label="Detects script-coin-lock-spend-tx"];
B abox B [label="Bid Script tx redeemed"],
C note C2
[label="The bidder extracts the offerer's plaintext signature and derives the offerer's noscript-lock-tx keyhalf.",
textbgcolor="#FFFFCC"];
B =>> N [label="Sends noscript-coin-lock-spend-tx"];
B abox B [label="Bid Scriptless tx redeemed"];
|||;
B => B [label="Wait for noscript-coin-lock-spend-tx to confirm"];
B abox B [label="Bid Completed"];
--- [label="fail path"];
|||;
B => B [label="Wait for script-coin-lock-tx locktime to expire"];
B =>> N [label="Sends script-coin-lock-pre-refund-tx"],
C note C2
[label="tx can be sent by either party.",
textbgcolor="#FFFFCC"];
N >> B [label="script-coin-lock-pre-refund-tx"];
B abox B [label="Bid Script pre-refund tx in chain"];
|||;
B => B [label="Wait for pre-refund tx to confirm"];
B =>> N [label="Sends script-coin-lock-pre-refund-spend-tx"],
C note C2
[label="Refunds the script lock tx, with the bidder's cleartext signature the offerer can refund the noscript lock tx.",
textbgcolor="#FFFFCC"];
B abox B [label="Bid Failed, refunded"];
};
}

86
doc/protocols/sequence_diagrams/ads.rev.offerer.xu Normal file
View File

@@ -0,0 +1,86 @@
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 BidIntent message"];
O abox O [label="Bid Received"];
O box O [label="User accepts bid"];
O =>> B [label="Sends BidIntentAccept 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"];
B =>> O [label="Sends BidAccept message"],
C note C2
[label="The BidAccept message contains the pubkeys the bidder 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"];
O =>> B [label="Sends XmrBidLockTxSigsMessage"],
C note C2
[label="The XmrBidLockTxSigsMessage contains the offerer's signatures for the script-coin-lock-refund and script-coin-lock-refund-spend txns.",
textbgcolor="#FFFFCC"];
O abox O [label="Exchanged script lock tx sigs msg"];
B =>> O [label="Sends XmrBidLockSpendTxMessage"],
C note C2
[label="The XmrBidLockSpendTxMessage contains the script-coin-lock-tx and proof the bidder can sign it.",
textbgcolor="#FFFFCC"];
B =>> N [label="Sends script-coin-lock-tx"],
O abox O [label="Bid Script coin spend tx valid"];
O abox O [label="Exchanged script lock spend tx msg"];
O => O [label="Wait for script-coin-lock-tx to confirm"];
O abox O [label="Bid Script coin locked"];
# offerer would only send noscript-coin-lock-tx if script-coin-lock-tx validates
O =>> N [label="Sends noscript-coin-lock-tx"];
O => O [label="Wait for noscript-coin-lock-tx to confirm"], B => B [label="Wait for noscript-coin-lock-tx to confirm"];
O abox O [label="Bid Scriptless coin locked"];
CB alt C [label="success path"] {
B => O [label="Sends script-coin-lock-tx release message"],
C note C2
[label="The XmrBidLockReleaseMessage contains the bidder's OTVES for it.
The offerer decodes the bidder's signature from the OTVES.
When the bidder has the plaintext signature, they can decode the offerer's noscript-coin-lock-tx signature.",
textbgcolor="#FFFFCC"];
O abox O [label="Script coin lock released"];
O =>> N [label="Sends script-coin-lock-spend-tx"];
O abox O [label="Script tx redeemed"];
O abox O [label="Bid Completed"];
--- [label="fail path"];
|||;
O => O [label="Wait for script-coin-lock-tx lock to expire"];
B =>> N [label="Sends script-coin-lock-pre-refund-tx"],
C note C2
[label="tx can be sent by either party.",
textbgcolor="#FFFFCC"];
N >> B [label="script-coin-lock-pre-refund-tx"];
O abox O [label="Bid Script pre-refund tx in chain"];
CB alt C [label="bidder refunds script coin lock tx"] {
|||;
B => B [label="Wait for pre-refund tx to confirm"];
B =>> N [label="Sends script-coin-lock-pre-refund-spend-tx"],
C note C2
[label="Refunds the script lock tx, with the bidder's cleartext signature the offerer can refund the noscript lock tx.
Once the lock expires the pre-refund tx can be spent by the offerer.",
textbgcolor="#FFFFCC"];
B abox B [label="Bid Failed, refunded"];
N >> O [label="Detects script-coin-lock-pre-refund-spend-tx"],
C note C2
[label="offerer recovers the bidder's scriptless chain key-shard.",
textbgcolor="#FFFFCC"];
O =>> N [label="Sends scriptless-coin-lock-recover-tx"];
O abox O [label="Bid Scriptless tx recovered"];
O abox O [label="Bid Failed, refunded"];
--- [label="offerer swipes script coin lock tx"];
|||;
O => O [label="Wait for pre-refund tx lock to expire"];
O =>> N [label="Sends script-coin-lock-pre-refund-swipe-tx"];
O abox O [label="Bid Failed, swiped"];
};
};
}

12
doc/protocols/sequence_diagrams/notes.txt
View File

@@ -11,13 +11,17 @@ npm install -g mscgenjs-cli
mscgenjs -T svg -i bidder.alt.xu -o bidder.alt.xu.svg
mscgenjs -T svg -i offerer.alt.xu -o offerer.alt.xu.svg
mscgenjs -T svg -i xmr.bidder.alt.xu -o xmr.bidder.alt.xu.svg
mscgenjs -T svg -i xmr.offerer.alt.xu -o xmr.offerer.alt.xu.svg
mscgenjs -T svg -i ads.bidder.alt.xu -o ads.bidder.alt.xu.svg
mscgenjs -T svg -i ads.offerer.alt.xu -o ads.offerer.alt.xu.svg
mscgenjs -T svg -i ads.rev.bidder.xu -o ads.rev.bidder.xu.svg
mscgenjs -T svg -i ads.rev.offerer.xu -o ads.rev.offerer.xu.svg
npm -g install svgo
svgo --pretty bidder.alt.xu.svg -o bidder.alt.xu.min.svg
svgo --pretty offerer.alt.xu.svg -o offerer.alt.xu.min.svg
svgo --pretty xmr.bidder.alt.xu.svg -o xmr.bidder.alt.xu.min.svg
svgo --pretty xmr.offerer.alt.xu.svg -o xmr.offerer.alt.xu.min.svg
svgo --pretty ads.bidder.alt.xu.svg -o ads.bidder.alt.xu.min.svg
svgo --pretty ads.offerer.alt.xu.svg -o ads.offerer.alt.xu.min.svg
svgo --pretty ads.rev.bidder.xu.svg -o ads.rev.bidder.xu.min.svg
svgo --pretty ads.rev.offerer.xu.svg -o ads.rev.offerer.xu.min.svg