Example of Protocol (Multilock)

[fredo]

Assuming Alice (Maker) and Bob (Taker) want to engage in an exchange of red (R-Token) and blue (B-Token). Alice is offering three R-Token in exchange for three B-Token. Both have a direct channel within the Red Token Network and a Blue Token Network and they deposited their respective amount of token into the their channels.

##Roles

Commitment Service (CS)

Furthermore, it exists a Commitment Service which is also listening to incoming offers and comes into play at contract signing (Commitment Phase).

Describe mechanism of hash and multilocked payments

1) Offering

Alice broadcasts the offer which is a description of a receiving transfer and an outgoing transfer to the public chatroom. Commitment Service (CS), as well as traders, are listening to that chatroom.

id	sell_token	sell_amount	buy_token	buy_amount	secrethash	signature
orderhash	Red	3	Blue	3	secrethashAlice	sigAlice

Bob creates an offer what is called an inverse offer.

id	sell_token	sell_amount	buy_token	buy_amount	secrethash	signature
orderhash	Blue	3	Red	3	secrethashBob	sigBob

Bob wants to accept this offer and contacts the CS. Commitment Service accepts to be the chosen CS.
Bob sends an offer acceptance to CS with orderID.

2) Offer match

CS has found the match and will initiate the trade by starting the Commitment Phase

2.1) CS initiates trade. Sends commitment request to both. Initiates time out.

CS sends the commitment request to Alice and to Bob.

To Alice

id	opponent	secrethash	signature
orderhash	addressBob	secrethashBob	sigCS

To Bob

id	opponent	secrethash	signature
orderhash	addressAlice	secrethashAlice	sigCS

2.2) Alice's and Bob's Raiden Nodes create a commitment by generating the next balance proof ### Describe Balance Proof (BP) (=Commitment) ... containing a multilocked payment for the opponent. What is a multilocked payment and pass it back to their Raidex Node which passes it back to CS. Optionally to guarantee privacy it can be encrypted by the opponents public key. Both BPs contain the locked transfer with both secret hashes of Alice and Bob.

Encryped Message = ...

Enc(Pub_Bob, [(BalanceProof_Alice)sig_Alice]
Enc(Pub_Alice, [(BalanceProof_Bob)sig_Bob]

2.3) CS collects encrypted BPs.

3) Commitment

3.1) CS send encrypted messages to Alice and Bob.
3.2) Alice and Bob decrypt the messages. They verify the Balance Proofs. They blindfold the message details
3.3) They send the signed Balance Proof for monitoring services to CS + the secret.

Commitment is now final.

4) Settlement

4.1) CS sends secret pair to Alice and Bob. secret pair - was ist das?

4.2) CS sends blindfolded BPs to Monitoring Service

4.3) Alice and Bob will unlock the payment.

Alice sends unlocked payment of 3 R-Token.
Bob sends unlocked payment of 3 B-Token.

Commitment Service could cooperate with a Monitoring service to guarantee the binding.

[stefante]

@luehrsFred : So far the example describes the happy case. Might be good to also include the unhappy case.

[fredo]

Sure.

The Unhappy Case only happens after both parties have signed the Offer and the CS initiates the trade (2.1)

Basically from that point forward one possible scenario of unhappy case is that one party times out.

Unhappy Case: Timeout

Whenever the CS demands a message (e. g. the balance proof) and a party does not respond, the party's deposit will get slashed. This timeout is called synchronization timeout.

Unhappy Case: Invalid State Change

At 2.2) the parties are requested to send their new balance proof (state change) to the CS. If their is no timeout then in step 3.1) each party will receive and validate the BP. Usually, the received BP is not necessary, since the BP should be also received via the raiden network. (which is acutally the expected incoming payment).

What the client will do in the Unhappy Case at 3.2:

1. Check if the incoming payment is the expected payment
2. If there is no or an not acceptable incoming payment

• proceed with decrypting the BP from 3.1
• validate the BP

3. If this is also an invalid BP

• call a dispute to the CS and do not send the secret reveal at 4.1)

Dispute protocol

Let's assume Alice misbehaved but did not timeout.

1. Bob calls a dispute

• Call dispute to CS
• provide the latest state (latest BP) signed by Alice and other necessary information (Nonce, current Balance, etc)
• CS demands the valid BP again from alice (now knowing the latest signed BP from alice submitted by Bob)
• Alice will send the latest BP
• With the State History knowing the CS can either slash the deposit by the cheating party or resolve the mismatch if alice provided correct BPs (forwarding it to Bob).