8/7/89 Santa Fe Institute's D O U B L E A U C T I O N T O U R N A M E N T CHAPTER 8 -- THE MESSAGE PASSING PROTOCOL ----------------------------------------- This chapter gives technical details of the message-passing protocol which is used for communication between the player programs and the monitor program. It is not needed by participants who base their programs on a skeleton program. 8.1 Messages and message packets -------------------------------- The tournament involves a central monitor program and a number of competing player programs. The player programs communicate only with the monitor, not directly with each other. All communication is performed by sending and receiving simple messages. A message consist of a single line containing a sequence of integers. Each integer is right justified in a 5-column field, blank filled on the left. A typical message might be ...14..350...-1 where each . represents a space. All integers lie in the range -999 to 9999 to leave at least one blank between columns. The first integer in each message indicates the message type. Here we name such message types according to the code table in Section 8.6. Thus a typical message is written: OFFER offer-price offerer The capitalized name OFFER stands for the unique integer code for this message type (16 from Section 8.6), whereas the lower-case names 'offer-price' and 'offerer' stand for parameter values that are conveyed by the message. Each communication from a player program to the monitor consists of a single message with one parameter (i.e. two integers in all). In some cases the parameter is unused and is set to 0. Most communications from the monitor to a player program consist of several messages called a message packet. The individual messages all have 2 parameters (i.e. 3 integers in all). In some cases the second parameter is unused and is set to 0. In the networked version of the game, in which the monitor and player programs may be on different machines, there are some initial pre-game messages exchanged before the main game begins. These pre-game messages are not purely numeric and do not obey the above conventions. They are described in Section 8.4. 8.2 Order of message packets ---------------------------- The following table shows the sequence of messages in a game: Step Monitor packets Trader messages ------------------------------------------------------------ Initialization Initialization-1 ACCEPT or REFUSE Initialization-2 READY ------------------------------------------------------------ Round Round ) READY ) ------------------------------------------------------------ ) Period Period ) ) READY ) ) ------------------------------------------------------------ ) ) Bid-offer Bid-offer ) ) ) k BID or OFFER or NONE ) ) j ) Bid-offer result ) ) ) ------------------------------------------------------------ ) i ) ) Buy-sell Buy-sell ) ) ) BUY or SELL or NONE ) ) ) Buy-sell result ) ) ) ------------------------------------------------------------ End End-of-game ------------------------------------------------------------ i, j, and k show the number of times each group is repeated: i = ntimes j = nperiods k = nrounds The center and right columns show the message packets and messages in each step, reading down the page in order. The game may be divided into 6 types of steps, as shown in the left column. Each game has one initialization step and one end step. Between these there are 'nrounds' rounds, each consisting of one round step and then 'nperiods' periods. Each period consists of one period step and then 'ntimes' alternating bid-offer and buy-sell steps. These steps are described in detail in the remaining sections of this document. Appendix B provides a summary of all steps and their messages. The center column shows the message packets sent by the monitor to the player programs. These may be either single or multiple messages, as detailed below. The right-hand column shows the messages sent by the player programs to the monitor. The messages shown are alternatives. In a bid-offer step, for example, each player program is expected to send either a BID message or an OFFER message or a NONE message. 8.3 Individual Steps of a DA game --------------------------------- Initialization step ------------------- The initialization step occurs once at the start of a game. It consists of: 1. An initialization-1 packet from the monitor that provides the general parameters for the game; 2. A response from the player program that either agrees to play (ACCEPT) or drops out at this stage (REJECT); 3. An initialization-2 packet from the monitor that provides more specific information about the game and gives parameters particular to each player; 4. A READY response from the player program when it is ready to play. INITIALIZATION-1 PACKET The first initialization packet gives general information about the game. The following messages will be sent in order: TYPE protocol monitor GAME game-type game-id LENGTH nrounds 0 LENGTH nperiods ntimes TOKENS max-tokens 0 NUMBER max-buyers max-sellers ROLE role timeout The variables have the following meanings: protocol Specifies the version of the message-passing protocol being followed. This should match that of the player programs. protocol = 5 for the version described in this document. monitor Specifies the version of the monitor in use. This can be ignored by participants. game-type Used to identify different types of games that will be played, conveying the values of the token-generation random number parameters. See the gametype variable in chapter 3 of the documentation for details. game-id Provides a unique identification for this particular game. game-id will be increased for each game played. nrounds Specifies the maximum number of rounds in the game. Maximum 20. nperiods Specifies the maximum number of periods in each round. Maximum 5. ntimes Specifies the maximum number of time steps in each period. In each time step there is first a bid-offer step and then a buy-sell step. A period will never be terminated early (before ntimes time steps have been played) unless no bids, offers, buys, or sells are occurring, and no mutually profitable trades could be made. Termination will not necessarily occur in such a case. Maximum 400. max-tokens Specifies the maximum number of tokens that any player will be allotted in any round of this game. Maximum 8. A maximum of 4 will be used in the tournament. max-buyers Specifies the maximum number of buyers in this game; the actual number (given in the initialization-2 packet) may be less because some players may drop out after this step. Maximum 20. max-sellers Specifies the maximum number of sellers in this game; the actual number (given in the initialization-2 packet) may be less because some players may drop out after this step. Maximum 20. role Takes one of two values, and should match the type of player program it is sent to: 1 For a buyer. 2 For a seller. timeout Specifies the conditions under which the monitor will timeout a player in any step: 0 Timeout occurs after a short time, which may vary from step to step. Governed by the timefactors in the monitor's game file. 9999 No timeout because the player was given the -w flag in the monitor's player file. The monitor will wait indefinitely for the player. other Approximate number of seconds until timeout. This is the timeout value from the monitor's game file. When a player is timed out in a bid-offer or buy-sell step it is given a "late" (-2) status when it next does respond. The player is terminated if it times out in any other step, or is not responding at the end of a period. FIRST RESPONSE MESSAGE The player program must respond to the initialization-1 packet with one of the following messages: ACCEPT player-number or REFUSE reason In the first case the player program agrees to play the game, and should not drop out at any future stage. In the second case the program refuses to play and gives a reason; it should then exit immediately. player-number Identifies the particular player program. Should be unique for each player. Use the value assigned to you, or 0 if a correct value is unknown. 9999 is normally used for a human player. reason A reason for refusing to play. Possible values are: 1 protocol is unacceptable. 2 game-type is unacceptable. 4 nrounds is unacceptable. 8 nperiods is unacceptable. 16 ntimes is unacceptable. 32 max-tokens is unacceptable. 64 max-buyers or max-sellers is unacceptable. 128 role is unacceptable. 256 timeout is unacceptable. <0 Other program error or problem. Several of the values 1--256 may be added together if multiple conditions apply. INITIALIZATION-2 PACKET The second initialization packet gives specific information about the game and the player. The following messages will be sent in order: NUMBER nbuyers nsellers BUYERS number-1 number-2 BUYERS number-3 number-4 . . . SELLERS number-1 number-2 SELLERS number-3 number-4 . . . LIMITS minprice maxprice PLAYER id 0 The variables have the following meanings: nbuyers The actual number of buyers. nsellers The actual number of sellers. number-n The player-number of buyer or seller n. Enough BUYERS messages are supplied to give the player-number of each buyer. Enough SELLERS messages are supplied to give the player-number of each seller. If the number of buyers or sellers is odd, the last number-n parameter will be 0. Any or all of the other number-n parameters may be zero if the appropriate value is unknown or the players are anonymous. minprice The minimum price value allowed. Minimum 1. maxprice The maximum price value allowed. Maximum 9999. id Your own identification number, between 1 and nbuyers if you are a buyer, and between 1 and nsellers if you are a seller. Players are referred to during the game by these identification numbers, not by their player-number. SECOND RESPONSE MESSAGE The second response message just consists of an acknowledgement when ready: READY id id must be your correct identification number. Start of round step ------------------- A start of round step occurs at the start of each round of the game. It consists of: 1. A round packet from the monitor, giving the number of the current round, and token values for the round; 2. A READY response from the player program when it is ready to continue play. ROUND PACKET FROM MONITOR The round packet consists of the following messages: ROUND r ntokens PRICES price1 price2 PRICES price3 price4 . . . The variables have the following meanings: r The number of this round: r = 1, 2, ..., nrounds. ntokens The number of tokens you are given for this round. price1--4 Your redemption values, in decreasing order for a buyer, and in increasing order for a seller. There will be ntokens such values in all (shown as 4 here), given in as many PRICES messages as needed. The last parameter of the last PRICES message will be 0 if ntokens is odd. RESPONSE The response message just consists of an acknowledgement when ready: READY id id must be your correct identification number. Start of period step -------------------- A start of period step occurs at the start of each period of each round of the game. It consists of: 1. A period packet from the monitor, giving the number of the current period; 2. A READY response from the player program when it is ready to continue play. PERIOD PACKET FROM MONITOR The period packet consists of a single message: PERIOD r p The variables have the following meanings: r The number of the current round. p The number of this period: p = 1, 2, ..., nperiods. RESPONSE The response message just consists of an acknowledgement when ready: READY id id must be your correct identification number. Bid-offer step -------------- A bid-offer step occurs at each time in each period. It consists of three stages: 1. A bid-offer packet from the monitor defining the start of the step and giving the current time; 2. After processing, a response from each player that specifies a bid, an offer, or neither; 3. A bid-offer result packet from the monitor that reports on what happened during this step, and gives the current status. BID-OFFER PACKET A bid-offer packet consists of a single BIDOFF message: BIDOFF t nobidoff The variables have the following meanings: t The current time: t = 1, 2, ..., ntimes. nobidoff A variable saying whether a bid or offer is allowed by this player in this step: 0 Bid or offer allowed. 1 No bid or offer allowed---no tokens left. RESPONSE The response from the player must be one of the following messages: BID bid-price or OFFER offer-price or NONE 0 A buyer may send a BID message to make a bid or a NONE message to do nothing. A seller may send an OFFER message to make an offer or a NONE message to do nothing. The message must be NONE if 'nobidoff' was non-zero in the BIDOFF message. The variables have the following meanings: bid-price The price of the bid being made. This must obey minprice <= bid-price <= maxprice and must be higher than the current bid price if there is one. offer-price The price of the offer being made. This must obey minprice <= offer-price <= maxprice and must be lower than the current offer price if there is one. BID-OFFER RESULT PACKET The bid-offer result packet from the monitor reports on the disposition of this player's response (BID or OFFER or NONE), and on the other bids and offers made in this step. It consists of a BODISP message, possibly some BID and/or OFFER messages, and then a CBID and a COFFER message: BODISP status trades BID bid-price bidder BID bid-price bidder . . . OFFER offer-price offerer OFFER offer-price offerer . . . CBID current-bid cbidder COFFER current-offer cofferer There is one BID message for each new bid made, and one OFFER message for each new offer made. Two of each are shown above, but there could be from none up to 'nbuyers' or 'nsellers' such messages. The BODISP, CBID, and COFFER messages always appear. The variables have the following meanings: status The disposition of the previous BID, OFFER, or NONE response. Possible values are: 0 NONE message received OK. You do not have an outstanding bid or offer. 1 NONE message received OK. Your previous bid or offer is still the current bid or offer. 2 BID or OFFER message received OK. Your bid or offer is now the current bid or offer. 3 BID or OFFER message received OK. Your bid or offer was bettered by another player. 4 BID or OFFER message received OK. Your bid or offer was equaled by another player, and you lost the random tie-break. -1 BID or OFFER message received, but unacceptable because nobidoff was non-zero or because the bid-price or offer-price was invalid; see the requirements listed in the response subsection above. -2 BID or OFFER message received, but too late. Your request was ignored and you missed one or more steps. trades Number of trades made so far by this player. bid-price The price of a bid that was made. The BID messages are arranged in increasing order of bid-price, with the last one (if any) producing the current bid price. bidder The id number of the buyer making the bid. offer-price The price of an offer that was made. The OFFER messages are arranged in decreasing order of offer-price, with the last one (if any) producing the current offer price. offerer The id number of the seller making the offer. current-bid The current bid price, or zero if none. If there were any bids this is equal to the highest bid-price. If there were no new bids the previous value of current-bid (which may be 0) is retained. cbidder The id number of the buyer whose bid is the current bid, or 0 if none. current-offer The current offer price, or zero if none. If there were any offers this is equal to the lowest offer-price. If there were no new offers the previous value of current-offer (which may be 0) is retained. cofferer The id number of the seller whose offer is the current offer, or 0 if none. Buy-sell step ------------- A buy-sell step occurs at each time in each period, after the corresponding bid-offer step. It consists of three stages: 1. A buy-sell packet from the monitor defining the start of the step and giving the current time; 2. After processing, a response from each player specifying a buy request, a sell request, or neither; 3. A buy-sell result packet from the monitor that reports on what happened during this step, and gives the current status. BUY-SELL PACKET A buy-sell packet consists of a single BUYSELL message: BUYSELL t nobuysell The variables have the following meanings: t The current time: t = 1, 2, ..., ntimes. nobuysell A variable saying whether a buy or sell request is allowed by this player in this step: 0 Buy or sell request allowed. 1 No buy or sell request allowed---no tokens left. 2 No buy or sell request allowed---no current offer or bid. 4 No buy or sell request allowed---not the holder of the current bid or offer. If several of the codes 1, 2, 4 apply they will be added together. RESPONSE The response from the player must be one of the following messages: BUY current-offer or SELL current-bid or NONE 0 A buyer may send a BUY message to request a buy, or a NONE message to do nothing. A seller may send a SELL message to request a sell, or a NONE message to do nothing. The message must be NONE if nobuysell was non-zero in the BUYSELL message. The variables have the following meanings: current-offer The current offer price, as given in the preceding COFFER message. This must be given correctly. current-bid The current bid price, as given in the preceding CBID message. This must be given correctly. BUY-SELL RESULT PACKET The buy-sell result packet from the monitor reports on the disposition of this player's response (BUY or SELL or NONE), and on the BUY or SELL request that was accepted, if any. Other players' requests that were not accepted are not reported. It consists of a BSDISP message, possibly a TRADE and a PLAYERS message, and then a CBID and a COFFER message: BSDISP status trades TRADE type price TRADERS buyer seller CBID current-bid cbidder COFFER current-offer cofferer Both the TRADE and TRADER messages appear if a transaction occurred; otherwise neither appears. The BSDISP, CBID, and COFFER messages always appear. The variables have the following meanings: status The disposition of the previous BUY, SELL, or NONE response. Possible values are: 0 NONE message received OK. 1 BUY or SELL message received OK and accepted. You just made a trade. 2 BUY or SELL message received OK, but not accepted because both the current bidder and the current offerer requested a buy or sell and you lost the random 50--50 toss. 3 BUY or SELL message received OK, but not accepted because another buyer or seller (the same type as you) also made a valid request, and won the random tie-break. -1 BUY or SELL message received, but unacceptable because nobuysell was non-zero, or because the current-bid or current-offer specified did not match the actual current bid or offer price. -2 BUY or SELL message received, but too late. Your request was ignored and you missed one or more steps. Note that you may have made a trade even if 'status' is not 1, because another player may have accepted your current bid or offer. Check whether 'buyer' or 'seller' (as appropriate) is equal to your 'id' to know for sure. trades Number of trades made so far by this player. type A code specifying which type of transaction occurred: 1 A BUY request was accepted. 2 A SELL request was accepted. price The price of the transaction that occurred. This will be equal to the previous current offer price if 'type' = 1, or to the previous current bid price if 'type' = 2. buyer The identification number of the buyer involved in the transaction. seller The identification number of the seller involved in the transaction. current-bid The current bid price, or 0 if none. This will definitely be 0 if there was a TRADE message. Otherwise it will be non-zero if it was previously non-zero. cbidder The id number of the buyer whose bid is the current bid, or 0 if none. current-offer The current offer price, or 0 if none. This will definitely be 0 if there was a TRADE message. Otherwise it will be non-zero if it was previously non-zero. cofferer The id number of the seller whose offer is the current offer, or 0 if none. End of game step ---------------- The end of game step consists of a single message from the monitor to each player: END profit efficiency The variables have the following meanings: profit The total profit made by the player in this game. Values larger than 9999 or smaller than -999 are reported as 9999 and -999, respectively. efficiency The ratio of 'profit' to the profit predicted by economic theory, times 100. This is a measure of how well the player performed, with 100 being "average" and higher values being better. The player program should terminate itself upon receiving this message. 8.4 Special Messages -------------------- QUIT messages ------------- At any stage where an ordinary message is expected, the player program may send the monitor the message: QUIT type The monitor will then drop that player from the game. 'type' should be zero for an intentional abandonment of the game (normally used only for a human player), or non-zero if an unexpected fatal error occurred in the player program. The monitor will report "quit" for the first case, and "fatal error" for the second. The player program itself should print an appropriate error message (to stderr if UNIX). KILLED messages --------------- The monitor (or DANI) may at any time send a player the message: KILLED reason 0 The player program should print an error message (to stderr if UNIX) if desired and then exit immediately. The reason parameter is a code saying why the monitor killed the player: 1. Killed by the operator running the monitor. 2. The player was not responding at the end of a period. A temporary lack of response is allowed within a period (and gives status = -2), but is fatal at the end of a period. 3. The player sent a message with a message type that was either illegal in the current context, or entirely unknown (not in Appendix C). 4. The player sent an undecodable message (not 2 integers). 5. The monitor couldn't find or couldn't read the .out message file which should have been written by the player (file-based communication only). 6. The monitor couldn't read a message from the player because of an I/O failure (pipe-based or inet-based communication only). 7. The monitor encountered an error, probably because the game wasn't properly defined. 8. The game was abandoned, probably because there weren't enough players. 9. Killed by DANI due to a communications problem or inconsistency. >10. Another reason -- reserved for possible future use. 0. No error -- silent kill; used by DANI if there isn't actually a game in progress. TEST messages ------------- TEST messages are used by the monitor or by DANI to check that a player is functioning properly. At any time the monitor or dani may send the message: TEST k 0 and the player should respond with: TEST k The variable k is an arbitrary integer, which must be echoed correctly in the player's reply. Pre-game messages ----------------- In the networked version of the game, in which the monitor and player programs may be on different machines, there are some initial pre-game messages exchanged before the main game begins. They apply equally whether the player is actually an interface to a human player, or is a machine player. They are as follows: 1. FROM PLAYER TO MONITOR The player program must initiate the dialogue with: DA role type userid name Note that 'DA' means the literal upper-case characters DA, not a numeric code. role Specifies the roles that the player is willing to play: 1 for a buyer, 2 for a seller, 3 for either, 0 for inquiry only. type Specifies the type of player: 1 for a human player directly connected, 2 for a machine player directly connected, 3 for any player connected via DANI. userid The program's userid on the player's local machine. Up to 8 characters. name The player's or player program's name, up to 30 characters before the newline. 2. FROM MONITOR TO PLAYER The monitor responds with one or more textual messages, which should normally be printed or displayed by the player, followed by one of the following: either by start nogame abort 'start' signifies that the main game (starting with the initialization-1 packet) is about to begin. 'nogame' indicates that there is no current game in which to participate. 'abort' signifies that, although a game was expected to begin, either the whole game has been aborted or the player is not eligible to play in it. The reason for an 'abort' message will be given in the preceding textual messages. The player program should exit after receiving a 'nogame' or 'abort' message. 8.5 Summary ----------- This summarizes the messages passed in a game, in order. Indented messages are from the player programs to the monitor. TYPE protocol monitor GAME game-type game-id LENGTH nrounds 0 LENGTH nperiods ntimes TOKENS max-tokens 0 NUMBER max-buyers max-sellers ROLE role timeout ACCEPT player-number or REFUSE reason NUMBER nbuyers nsellers BUYERS number-1 number-2 (Note 1) SELLERS number-1 number-2 (Note 1) LIMITS minprice maxprice PLAYER id 0 READY id A: ROUND r ntokens PRICES price-1 price-2 (Note 2) READY id B: PERIOD r p READY id C: BIDOFF t nobidoff BID bid-price or OFFER offer-price or NONE 0 BODISP status trades BID bid-price bidder (Note 3) OFFER offer-price offerer (Note 3) CBID current-bid cbidder COFFER current-offer cofferer BUYSELL t nobuysell BUY current-offer or SELL current-bid or NONE 0 BSDISP status trades TRADE type price (Note 4) TRADERS buyer seller (Note 4) CBID current-bid cbidder COFFER current-offer cofferer Go to A, B, C, or D. D: END profit efficiency Notes: 1. Enough of these messages appear to give a number for each buyer and each seller. 2. Enough of these messages appear to give 'ntokens' price values. 3. Zero or more of each of these messages appear. 4. Neither or both of these messages appear. 8.6 Code Table -------------- This table assigns numerical values to each of the keywords mentioned in the text. The alphabetical order used is purely arbitrary, and may not be maintained in the future if further keywords are added. The values listed here will not be changed. ACCEPT 1 BID 2 BIDOFF 3 BODISP 4 BSDISP 5 BUY 6 BUYERS 29 BUYSELL 7 CBID 8 COFFER 9 END 10 GAME 11 KILLED 98 LENGTH 12 LIMITS 13 NONE 14 NUMBER 15 OFFER 16 PERIOD 17 PLAYER 18 PRICES 19 QUIT 99 READY 20 REFUSE 21 ROUND 27 ROLE 22 SELL 23 SELLERS 30 TEST 31 TOKENS 28 TRADE 24 TRADERS 25 TYPE 26