Note

This is currently an experimental feature. To try it follow this guide.

Preparation instructions

Dependencies

Follow the Preliminaries and Installation sections from the AEA quick start.

How to run

First make sure you are inside your AEA's folder (see here on how to create a new agent).

Then run

aea generate protocol <path-to-protocol-specification>

where <path-to-protocol-specification> is the relative path to a protocol specification file.

If there are no errors, this command will generate the protocol and place it in your AEA project. The name of the protocol's directory will match the protocol name given in the specification.

Protocol Specification

A protocol can be described in a yaml file. As such, it needs to follow the yaml format. The following is an example protocol specification:

name: two_party_negotiation
author: fetchai
version: 0.1.0
license: Apache-2.0
description: 'A protocol for negotiation over a fixed set of resources involving two parties.'
speech_acts:
  cfp:
    query: ct:DataModel
  propose:
    query: ct:DataModel
    price: pt:float
  accept: {}
  decline: {}
  match_accept: {}

Each protocol specification yaml file contains some basic information about the protocol. The allowed fields and what they represent are:

  • name: The name of the protocol (written in snake_case)
  • authors: List of authors
  • version: The current version of the protocol
  • license: Licensing information
  • description: A short description of the protocol

Each field is a key/value pair, where both the key and the value are yaml strings. Every field is mandatory.

In addition to the above basic information, a protocol specification must describe the syntax of valid messages according to this protocol. Therefore, there is another mandatory field: speech-acts, which defines the set of performatives valid under this protocol, and a set of contents (i.e. parameters) for each performative.

The format of the speech-act is as follows: speech-act is a dictionary, where each key is a unique performative (yaml string), and the value is a content dictionary. If a performative does not have any content, then its content dictionary is empty, e.g. accept, decline and match_accept in the above protocol specification.

Each content dictionary is composed of key/value pairs, where each key is the name of a content (yaml string) and the value is its type (yaml string). For example, the query performative has one content whose name is query and whose type is ct:DataModel.

Types

The specific types which could be assigned to contents in a protocol specification are described in the table below.

Types are either user defined (i.e. custom types) or primitive:

  • Custom types are prepended with ct: and their format is described using regular expression in the table below.
  • Primitive types are prepended with pt:. There are different categories of primitive types, e.g. <PT> such as integers and booleans, <PCT> such as sets and lists, and so on. Primitive types are compositional:
    • For example, consider pt:set under <PCT>, i.e. an unordered collection of elements without duplicates. A pt:set describes the type of its elements (called "sub-type") in square brackets. The sub-type of a pt:set could either be a <PT> (e.g. pt:int, pt:bool) or <CT> (i.e. a custom type).
    • In describing the format of types, / between two sub-types should be treated as "or". For example, the sub-type of a pt:set is either a <PT> or a <CT>.

A multi type denotes an "or" separated set of sub-types, e.g. pt:union[pt:str, pt:int] as the type of a content c means c is either a pt:int or a pt:float.

An optional type for a content denotes that the content's existence is optional, but if it is present, its type must match pt:optional's sub-type.

Type Code Format Example In Python
Custom types <CT> ct:RegExp(^[A-Z][a-zA-Z0-9]*$) ct:DataModel Custom Class
Primitive types <PT> pt:bytes pt:bytes bytes
pt:int pt:int int
pt:float pt:float float
pt:bool pt:bool bool
pt:str pt:str str
Primitive collection types <PCT> pt:set[<PT>/<CT>] pt:set[pt:int] FrozenSet
pt:list[<PT>/<CT>] pt:list[ct:DataModel] Tuple
Primitive mapping types <PMT> pt:dict[<PT>/<CT>, <PT>/<CT>] pt:dict[pt:bool, ct:DataModel] Dict
Multi types <MT> pt:union[<PT>/<CT>/<PCT>/<PMT>, ..., <PT>/<CT>/<PCT>/<PMT>] pt:union[pt:str, pt:list[ct:Error]] Union
Optional types <O> pt:optional[<MT>/<PMT>/<PCT>/<PT>/<CT>] pt:optional[pt:list[pt:int]] Optional

Demo instructions

First, create a new AEA project:

aea create my_aea
cd my_aea

Second, run the generator on the sample specification:

aea generate protocol ../examples/protocol_specification_ex/sample.yaml

This will generate the protocol and place it in your AEA project.

Third, try generating other protocols by first defining a specification, then running the generator.