Skip to content

Draft the service idea and define the FSM specification

The first task when designing an agent service is to describe its business logic into a finite-state machine (FSM). You must be able to identify the different states of the service, and what are the events that trigger a change from one state to another.

Part of the development process covered in this guide

What you will learn

This guide covers steps 1 and 2 of the development process. You will learn how to write the FSM App specification that defines the main steps in the business logic of your service. The actual coding of the FSM App will be covered in the next step.

We will use as an example the FSM used in the Hello World service, where a set of 4 agents coordinate and take turns to print a "Hello World" message in their local console.

You must ensure that your machine satisfies the framework requirements, you have set up the framework, and you have a local registry populated with some default components. As a result you should have a Pipenv workspace folder with an initialized local registry (./packages) in it.

Draft the service idea

Describe the business logic of your service as an FSM. That is, determine, at a high level, what are the states, events and transitions of the service:

  • States define points where actions are executed (e.g., an agent sends a transaction on-chain).
  • Events represent observed conditions (e.g., all agents have shared a value, or a timeout has occurred).
  • Transitions define how to move from one state to another based on the events observed (e.g., if the service observes an error event in a certain state, then move back to the initial state).
Example of a service FSM

This is an example of the FSM of the Hello World service, at high level. You can learn more about the purpose of each of the states, events and transitions in its documentation page.


An important decision when designing your service is to determine what kind of agreement is required to transit from one state to another. For example:

  • Do agents have to collect and share a common value (e.g., a value observed from the same service provider) or a different value (e.g., each agent collects a value from a different service provider)?
  • Do all agents need to participate in the agreement to transit to another state, or is it enough that only a threshold of agents participate?

Define the FSM specification

In the workspace folder, create a file fsm_specification.yaml, which formally encodes the FSM that you have designed in the previous step. This file must adhere to a syntax that is understood by the framework. Hopefully, the example below is self-explanatory.

Example of an fsm_specification.yaml file

Given a draft of the FSM, the structure of the fsm_specification.yaml file is quite straightforward. Below we show the FSM specification file of the Hello World service.

default_start_state: RegistrationRound
final_states: []
label: HelloWorldAbciApp
- RegistrationRound
- CollectRandomnessRound
- PrintMessageRound
- RegistrationRound
- ResetAndPauseRound
- SelectKeeperRound
    (CollectRandomnessRound, DONE): SelectKeeperRound
    (CollectRandomnessRound, NO_MAJORITY): CollectRandomnessRound
    (CollectRandomnessRound, ROUND_TIMEOUT): CollectRandomnessRound
    (PrintMessageRound, DONE): ResetAndPauseRound
    (PrintMessageRound, ROUND_TIMEOUT): RegistrationRound
    (RegistrationRound, DONE): CollectRandomnessRound
    (ResetAndPauseRound, DONE): CollectRandomnessRound
    (ResetAndPauseRound, NO_MAJORITY): RegistrationRound
    (ResetAndPauseRound, RESET_TIMEOUT): RegistrationRound
    (SelectKeeperRound, DONE): PrintMessageRound
    (SelectKeeperRound, NO_MAJORITY): RegistrationRound
    (SelectKeeperRound, ROUND_TIMEOUT): RegistrationRound