                                                                    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

