This document describes the key concepts involved in the BitWrk service protocols.
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
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.
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 messages posted by the participants.
The messages (in the boxes) are the messages the two participants send to the BitWrk server. Behind the scenes, the participants transmit work and result information over a direct connection (initiated by the buyer). All communication is done via HTTP.
A message sent to the BitWrk server is represented by an HTTP POST to http://SERVER/tx/TXID (where TXID is an opaque ID string received from the bid, such as "aghzfmJpdHdya3IlCxINQXJ0aWNsZUVudGl0eSIIYV9mb29iYXIMCxICVHgY5bgCDA", and SERVER is the service address, e.g. "bitwrk.appspot.com").
Data is transferred as form data (Content-Type application/x-www-form-urlencoded). To make things secure, participants must provide a signature (using the same mechanism the Bitcoin client offers) of the sent data. The signature proves that the message was created by the participants. (See server_transaction.go, updateTransaction())
| Argument | Data Type | Description |
|---|---|---|
| workhash | hex-encoded, 32 bytes | A SHA-256 sum of the work package |
| worksecrethash | hex-encoded, 32 bytes | SHA-256(workhash|buyersecret), both inputs to SHA256 are the binary 32 byte values of workhash and buyersecret |
| workerurl | URL | The address the seller wants to have the work package delivered to. Will be used for all direct communication between buyer and seller. |
| buyersecret | hex-encoded, 32 bytes | Random value generated by the buyer and sent to the seller after transmitting the work package. Its purpose is to prevent sellers from hijacking other seller's workers. |
| encresulthash | hex-encoded, 32 bytes | After the seller has computed the result, it sends it back to the buyer, but encrypted with a one-time key (encresulthash). This way, the buyer will not immediately be able to take the result (and run with it), but needs to sign of a receipt for the received, encrypted, result data. This is the encrypted result's SHA256 check sum |
| encresulthashsig | base64-encoded, 65 bytes | A Bitcoin-like signature, issued by the buyer, of the encrypted result's hash value. By providing this signature, the seller can prove that the buyer has received the result correctly. There is no denial for the buyer. |
| encresultkey | hex-encoded, 32 bytes | The secret AES-256 key used for encrypting the result. By publishing the key together with the buyer's signature of the encrypted result, the seller proves that the buyer has received the result, and releases the encryption. |
| acceptwork, rejectwork, rejectresult | "on" | Tags to accept work, reject work or reject a result. |
- Maximum duration of bid: 2 min (bid.go, NewBid())
- New Transaction: 1 min (transaction.go, NewTransaction())
- Transmitting: +2 min (transaction.go, phaseArrivalFuncs)
- Working: +5 min
- Unverified: +15 min
- Finished: instant retirement
- Work/Result instant retirement