Registration Phase

In this section, we describe the registration phase, during which the participant can register their own agent for the competition.

To do so, the participant must register with the controller agent that will be running and be connected to the OEF throughout the duration of the competition.

At the end of the registration time, the controller generates the game data for every participant (that is, the initial good holdings and the utility parameters for the goods). Then, the agent can start to negotiate and to submit transactions to the controller agent.

In the following sections, we will explain:

  • the initial setup of the controller agent;

  • how to register/unregister to TAC;

  • how the trading phase will start;

  • how to handle errors (e.g. potential disconnection from the network)

Setup of the controller agent

Before the registration phase starts, the organizer of the TAC will run the controller agent, which is a special agent that manages the TAC. Specifically, the main tasks are:

  1. Handling of registration/unregistration of the participants.

  2. Generating the game data for each agent and triggering the start of the competition.

  3. Accepting/Rejecting valid/invalid transactions submitted by the trading agents.

  4. Providing agents with state updates (e.g. when the agent reconnects after a disconnection)

Register as ‘tac’ service

The controller agent registers itself to the OEF as a service.

The data model name is "tac" and as attribute we have "version", which is a string. The TAC controller agent will register with "version"=VERSION_ID where VERSION_ID is set to a string uniquely identifying the version of the TAC.

The controller agent will wait for registration_timeout. At the end, if there are enough participant, it will start the competition. Otherwise, it will send back a TACMessage of type CANCELLED to every registered participant

sequenceDiagram participant OEF participant Controller Note right of Controller: register as a controller agent. Controller->>OEF: register_service("tac", Description{version=VERSION_ID}) Controller->>Controller: run() activate Controller deactivate Controller Note right of Controller: Waiting for 'REGISTER' messages from TAC agents, until 'start time'.

The setup of the controller agent.

How to register/unregister

In order to complete a registration, a trading agent should do the following steps:

  1. Run a search for "tac" services, with the query "version" == VERSION_ID.

  2. On the search result, send a TACMessage of type REGISTER to the right TAC controller

  3. Waiting for the GameData message.

Search for controller agent

sequenceDiagram participant Agent participant OEF participant Controller activate Controller Agent->>OEF: search_services("tac", version==1) OEF->>Agent: search result: ["Controller"] deactivate Controller

TAC Agent search for controller agents.

Register to TAC

In order to register, a TAC Agent must send a TACMessage of type REGISTER to the controller agent.

The message Register is an empty message. In order to undo the effect of the registration, the agent can unregister from the competition by sending the Unregister message.

sequenceDiagram participant Agent participant OEF participant Controller activate Controller Agent->>Controller: Message{Register{}} deactivate Controller

an agent registers to TAC.

Start of the competition

Once trading agents receive the GameData message, the competition starts and the trading phase begins.

The message GameData contains the following information:

  • money (integer): the money amount available to the TAC agent.

  • endowment (list of integers): the endowment for every good.

  • utility_params (list of floats): the utility parameters for every good.

  • nb_agents (integer): the number of agents in the competition.

  • nb_goods (integer): the number of goods in the competition.

  • tx_fee (float): the transaction fee for every trade.

  • agent_pbk_to_name (dictionary[string, string]): mapping the public key of each agent to its name.

  • good_pbk_to_name (dictionary[string, string]): mapping the public key of each good to its name.

Summary

In the following, a transition diagram that sumarize the registration phase:

sequenceDiagram participant Agent_1 participant Agent_2 participant Agent_3 participant OEF participant Controller Note over OEF: For the sake of brevity, assume that messages sent between agents are in fact sent through the OEF. Controller->>OEF: register_service("tac") Controller->>Controller: run() activate Controller Agent_1->>OEF: search_services("tac") Agent_2->>OEF: search_services("tac") Agent_3->>OEF: search_services("tac") OEF->>Agent_1: search result: [Controller] OEF->>Agent_2: search result: [Controller] OEF->>Agent_3: search result: [Controller] Agent_1->>Controller: Register() Agent_2->>Controller: Register() Agent_3->>Controller: Register() Note over Controller: When at least N TAC agents will be registered for the competition, generate a Game instance and send details to the participants. Controller->>Agent_1: GameData(money, endowment, utility_params, nb_agents, nb_goods, tx_fee, agent_pbks, agent_names, good_pbks) Controller->>Agent_2: GameData(money, endowment, utility_params, nb_agents, nb_goods, tx_fee, agent_pbks, agent_names, good_pbks) Controller->>Agent_3: GameData(money, endowment, utility_params, nb_agents, nb_goods, tx_fee, agent_pbks, agent_names, good_pbks) deactivate Controller

The transition diagram for the registration phase.