From 578bdca171113341f1ac81c13fb6a6ef25d1fa1f Mon Sep 17 00:00:00 2001 From: Jonas Eschenburg Date: Sun, 9 Mar 2014 18:05:12 +0100 Subject: [PATCH] Added a complete transaction example diagram to documentation --- documentation/message-sequence.svg | 853 +++++++++++++++++++++++++++++ documentation/protocol.md | 27 +- 2 files changed, 875 insertions(+), 5 deletions(-) create mode 100644 documentation/message-sequence.svg diff --git a/documentation/message-sequence.svg b/documentation/message-sequence.svg new file mode 100644 index 0000000..bcac08f --- /dev/null +++ b/documentation/message-sequence.svg @@ -0,0 +1,853 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Buyer + Server + Seller + Bid1 + Tx + Bid2 + + + + INQUEUE + PLACED + MATCHED + + + INQUEUE + MATCHED + + + + ESTABLISHING + BUYER_ESTABLISHED + TRANSMITTING + + + WORKING + + + POST /bid + + <bid1> + + POST /bid + + <bid2> + + GET /bid/<bid1> + + <txid> + + GET /bid/<bid2> + + <txid> + + POST /tx/<txid>workhash=...worksecrethash=... + + POST /tx/<txid>workerurl=<wurl> + + POST <wurl>chunks=[(hash1,len1),(hash2,len2),…,(hashN, lenN)]secret=<s> + + missing=[1,2,3,…,N] + + POST <wurl>data=[data1,data2,…,data3] + + POST /tx/<txid>buyersecret=<s> + + <result AES-encrypted with random <k>> + + + UNVERIFIED + + POST <wurl>receipt=<encresulthashsig> + + POST /tx/<txid>encresulthash=SHA256(<encr. result>)encresulthashsig=<encresulthashsig>encresultkey=<k> + FINISHED + + POST /tx/<txid>acceptresult=on + + diff --git a/documentation/protocol.md b/documentation/protocol.md index 21bb23d..17bd936 100644 --- a/documentation/protocol.md +++ b/documentation/protocol.md @@ -2,12 +2,19 @@ This document describes the key concepts involved in the BitWrk service protocol Bids ==== -A bid is the statet intent to buy or sell an article. -TODO +A bid is the stated intent to buy or sell an article for a certain price. Bids can be created +clients at any time by performing an HTTP POST to http://SERVER/bid. Additional restrictions +apply, such as rate-control and having to provide a one-time random token (nonce) to avoid high +loads on the server -Transaction Phases -================== - + A bid is initially in state INQUEUE. At some (short) time later, +the server tries to match the bid against another bid. Buys match with sells and vice-versa. +If a bid can be matched right away, it will be in MATCHED state, otherwise it is placed as +an open bid. The latter is called PLACED state. If such a bid can be matched within a certain +time, it will be put into MATCHED state, too. Otherwise, the bid retires. + +Transactions +============ In BitWrk, a transaction is what is created if two bids (a buy and a sell) match. A transaction starts in ESTABLISHING phase and transitions to other phases based on @@ -27,6 +34,16 @@ To make things secure, participants must provide a signature (using the same mec Bitcoin client offers) of the sent data. The signature proves that the message was created by the participants. (See server_transaction.go, updateTransaction()) +Bid States and Transaction Phases +================================= +A complete, successful example: +------------------------------- +> + +An overview of transaction phases: +---------------------------------- +> + Explanation of message arguments --------------------------------