Settlement Templating Language (STL)

Release 2.0

Algosport

Jan 16, 2020

CONTENTS:

i
ii
 CHAPTER

ONE

INTRODUCTION

STL (Settlement Templating Language) is a domain-specific language used to define sporting formats and settlement
rules in sports betting.
Formats define the rules, progression and incidents that occur with a sporting contest, e.g.
• Football with regular time, extra-time and a penalty shootout may have goals, cards, corners, offsides, etc.
• 3-set tennis with a tie-break in each set is a nested collection of sets, games and points.
• NBA basketball consists of two halves of two quarters and repeating over-time periods if necessary. 1-, 2- and
3-point shots may be scored and fouls recorded.
Rules define how a selection should be settled within a given sporting format. For example, winner(*) ?= vs1,
is a winning selection when the first competitor wins the contest, however what it means to win the contest will depend
upon the sporting format.
Pricing of selections is achieved by attaching an algorithmic model to a format and running STL rules against it.

1.1 Why use STL?

1.1.1 Productivity

STL can quickly add or adapt

• one format into another, e.g. the introduction of a tie-break at 12-12 in the 5th set of Wimbledon; or
• settlements rules
and have those changes reflected in the underlying model without the need for quants or developers with highly
specialised knowledge.

1.1.2 Extensible

STL rules are incredibly flexible. Letting customers combine and manipulate those rules over the liftime of a bet
brings a wealth of new potential products and user experiences.
• Bet builder allows customers to create their own individual bets by combining pre-existing selections. If selec-
tions are already defined in STL then combining multiple selections into a single bet is incredibly simple. For
example, if a customer wishes to get a price for the combination of home win

supremacy(<RT, goals>) > 0

and total goals over 2.5

1
Settlement Templating Language (STL), Release 2.0

total(<RT, goals>) > 2.5

then we only need to request the price for the combined selection

supremacy(<RT, goals>) > 0 and total(<RT, goals>) > 2.5

from the underlying model.

• Bet customiser takes the bet builder product and throws away the need for predefined selections. The ability to
build STL rules on the fly via an interactive UI lets customers build exactly the bet they want.
• Bet editor allows customers to add and remove selections from a combined bet. As with bet builder, when all
selections are defined in STL then the interface for making such changes to bets is as simple changing the list of
selections that define the bet. Customers are then charged based on the change in expected value for the bet as
well as some level of commission.
For example, if a customer thinks that there will be over 2.5 goals in a match but now prefer the away team over
the home team, they simply edit their selections from
1. Home win, defined as supremacy(<RT, goals>) > 0
2. Over 2.5 goals, defined as total(<RT, goals>) > 2.5
to
1. Away win, defined as supremacy(<RT, goals>) < 0
2. Over 2.5 goals, defined as total(<RT, goals>) > 2.5
and we price the cost to edit the bet based on the expected payouts for

supremacy(<RT, goals>) > 0 and total(<RT, goals>) > 2.5

and

supremacy(<RT, goals>) < 0 and total(<RT, goals>) > 2.5

• Cash out is a special case of bet editor where all selections are removed from the initial bet.

2 Chapter 1. Introduction
 CHAPTER

TWO

PRIMITIVES TYPES

2.1 Numeric types

2.1.1 Integers

An integer is a values in the set Z = {. . . , −2, −1, 0, 1, 2, . . .}.

Values should be expressed in decimal (base 10) with an optional leading plus, +, the default, or minus, -, denoting
the sign, e.g. -2, +3 and 111.

2.1.2 Reals

A real is a value in the set R internally represented as a floating point value.

Real values should expressed in decimal (base 10) form with an optional leading plus, +, the default, or minus, -,
denoting the sign, e.g. -12.32, 2.0, +3.

2.2 Strings

A string is any sequence of characters enclosed in single quotes, '.

To specify a literal single quote, escape it with a backslash \. To specify a literal backslash, double it \\. All other
instances of backslash will be treated as a literal backslash: this means that the other escape sequences you might be
used to, such as \r or \n, will be output literally as specified rather than having any special meaning.

2.3 None type

2.4 Enumerations

An enumeration is some named type which may take one of a list of possible values. For example, the enumeration
type, card-type, with possible values yellow, yellow2 and red, is defined as

enum card-type = yellow | yellow2 | red

3
Settlement Templating Language (STL), Release 2.0

2.4.1 Side

A side is one of the two competitors within a contest. It is defined as the enumeration:

enum side = vs1 | vs2

2.4.2 None

The none type is used to augment another type with the lack of a value, e.g. a goal with no assist, and is defined as the
enumeration:

enum none = none

2.4.3 Unknown

The unknown type is used to augment another type when its value is not known at all, e.g. if it is unknown which
player on particular side received a card, an is defined as the enumeration:

enum unknown = unknown

2.5 Head-to-head

A head-to-head records the total of some incident group for each side.
Values are represented as (m, n) with m and n both being integer numbers, e.g. (1,0) or (12, 28).

2.6 Settlements

A settlement, ⟨𝑤, 𝑣⟩, contains a winning part, 𝑤, and voiding part, 𝑣, such that
• 0≤𝑤≤1
• 0≤𝑣≤1
• 0≤𝑤+𝑣 ≤1
A bet struck at odds, 𝑜, with stake, 𝑠, and settled at ⟨𝑤, 𝑣⟩ will have payout, 𝑝, given by

𝑝=𝑜·𝑠·𝑤+𝑠·𝑣

Settlement values are represented as in the functional form settled(w, v) taking a real valued winning part, w,
and a real valued voiding part, v, with restrictions as above.
The aliases

win = settled(1,0)
void = settled(0,1)
lose = settled(0,0)

are provided for convenience.

4 Chapter 2. Primitives types

 Settlement Templating Language (STL), Release 2.0

2.7 Collections

2.7.1 Sets

Sets contain a possibly empty number of values of the same type.

Set literals use the standard mathematical notation, {x, y, ...}, for example
• the set of integers greateer or equal to 0 and less than 4, {0, 1, 2, 3}
• the set of head-to-heads with at most one score, {(0,0), (0,1), (1,0)

2.7.2 Intervals

Mathematical interval notation is used to denote the set of values between two endpoints.
• [a,b] denotes {𝑥 | 𝑎 ≤ 𝑥 ≤ 𝑏}
• [a,b) denotes {𝑥 | 𝑎 ≤ 𝑥𝑏}
• (a,b] denotes {𝑥 | 𝑎𝑥 ≤ 𝑏}
• (a,b] denotes {𝑥 | 𝑎𝑥𝑏}
For finite sets of this form interval notation provides a succinct way to express the possible values without having to
explicitly enumerate them in a set literal.

2.7.3 Records

A record in STL is a typed collection of keys and values.

Each key is some unique identifier with an associated type. For example, the type of incidents is defined as

record incident =
{ group: identifier
}

which defines a single key, group, which has type identifier.

Records may be extended using the syntax

record extended =
{ extra-key-1: type-1
, extra-key-2: type-2
. ...
| original
}

which adds two extra keys, extra-key-1 and extra-key-2, with types, type-1 and type-2, respectively, to
the previously defined original record type.
For example, the match-play-incident type extends the incident type above

record match-play-incident =
{ winner: side
| incident
}

2.7. Collections 5
Settlement Templating Language (STL), Release 2.0

which is equivalent to

record match-play-incident =
{ group: identifier
, winner: side
}

2.7.4 Union types

Union types allow a value to be one of a number of different types.

It is typical to allow incident attributes to be unknown and potentially also none. Consider a goal incident,

record card =
{ player: unknown | string
, assist: unknown | none | string
| incident
}

which has a player attribute that must be scored by some potentially unknown player and an potential assist
attribute that may or may not be known.

2.8 Time paths

Time periods and instants in STL are represented as a path comprised of path segments that are dependent on the
format of the contest they refer to.
• 10 minutes into the second half, /H2/10:00.
• The first three games of the 2nd set, /sets[2]/[start,games[3]/end].
• 2nd and 3rd quarters, [Q2/start, Q3/end].
• Time of 3rd yellow card in regulation time, RT/cards{type=yellow}[3].
A path may refer to an interval or a single instant of time dependent on the final segment of the path.

2.8.1 Path segments

References

References give a phase independent way of refering to common instants and intervals of a phase. The valid values
are:
• start: the start of a phase.
• end: the end of a phase.
• now: the current time in a phase. Equal to start before the phase begins and end after it has completed.
• remaining: the remaining time within a phase. A synonym for [start, end].
• *: the entirety of a phase. Usually only used to represent the entire contest.

6 Chapter 2. Primitives types

 Settlement Templating Language (STL), Release 2.0

2.8.2 Clock times

A clock time, found within a timed phase is always represented in the format [±]m:ss[.ssssss].
• [±] is an optional plus (the default) or minus signifying whether the clock is counting from the start or the end
of the period, respectively.
• m refers to non-negative minutes.
• ss refers to zero-padded seconds in the interval [00, 59].
• [.ssssss] refers to optional microseconds.
Negative clock times are always assumed to count back from the least possible duration of the period they belong to,
e.g. even though the 1st half of football may run longer than 45 minutes we convert a clock time of -2:00 in the 1st
half to 43:00 and -5:00 in 90 minute regulation time to 85:00. It is unusual to require a negative clock time but it
does allow for some settlement rules to be defined in a format independent manner. Team to win the last ten minutes
could be defined for 90 minute and 80 minute football formats if only the period lengths change.

Phase segments

Phase segements directly reference the format and incidents of a contest, e.g. regulation time, sets, goals, innings.
Each such segment may optionally be filtered or indexed.
A filter applies some restriction to the set of incidents that are considered when creating the path and take the
form of a record instance.For example, if we only want to consider the games that player 1 serves, we may write
games{server=vs1}.
An index consider the progression of incidents. We can reference the nth incident from the start using positive indices
and from the end using negative indices.
• frames[-2]: penultimate frame.
• innings[4]: 4th innings.

Explicit intervals

Path segments may contain intervals of path segments.

• /games[3]/[start, points[4]/end]: 1st four points of 3rd game.
• /H2/[goals[1], corners[3]]: 1st goal in 2nd half to the 3rd corner.

2.8. Time paths 7

Settlement Templating Language (STL), Release 2.0

8 Chapter 2. Primitives types

 CHAPTER

THREE

FORMATS

Each sporting contest within the STL framework requires a format. The format defines both
1. the structure and progression of passages of play, or phases; and
2. the incidents that may occur during or as a result of one of these passages of play.

Note: It is not possible to construct your own format in STL at present, but the following section gives a better
understanding of how phases and incidents interact when building STL rules.

3.1 Structural phases

Contests in STL are organised into a progression of structural phases which are also organised into a progression of
structural phases. They form the basis around which the rules are defined and determine what kinds of incidents can
occur during each phase of play.
• Football has regulation time, comprised of two halves, potentially followed by extra time and possibly penalties.
• 3-set tennis has sets 1, 2 and 3 follow each other with each set being comprised of a progression of games each
consisiting of a progression of points.
• Post-season ice hockey has regulation time, comprised of three periods, potentially followed by one or more
over time periods.

3.1.1 Timed phases

A timed phase is either a single period or a period group.

• A single period has an associated clock, the quoted duration of the period, which may run for
– exactly that length of time, stopping at that time once it has reached it, e.g. basketball or ice hockey; or
– at least that length of time, running until the period has ended, e.g. rugby union or football.

Note: Exact clocks don’t require the period ends as soon as the clock reaches that time. This is the case in
some sports, e.g. ice hockey, but not in others, e.g. basketball and american football, where a final act or play is
allowed to run until completion.

• A period group contains multiple timed phases, i.e. a collection of single periods and period groups.
Common conventions for naming timed phases include

9
Settlement Templating Language (STL), Release 2.0

• RT for regulation time

• OT for overtime
• ET for extra time
• H prefix for halves, e.g. H1 for 1st half
• Q prefix for quarters, e.g. Q4 for 4th quarter
• P prefix for periods, e.g. P2 for 2nd period
but any unique legal identifier may be chosen.

Examples

1. Football
• Regulation time, RT, consists of two halves, H1 and H2, of at least 45 minutes:

RT [ H1 >= 45:00
, H2 >= 45:00
]

• Extra time, ET, consists of two halves, ET1 and ET2, of at least 15 minutes:

ET [ ET1 >= 15:00

, ET2 >= 15:00
]

2. Ice hockey
• Regulation time, RT, consists of three periods, P1, P2 and P3, of exactly 20 minute duration:

RT [ P1 = 20:00
, P2 = 20:00
, P3 = 20:00
]

• Regular season overtime, OT, consists of a single period of 5 minute duration:

OT = 5:00

The possibility of the period ending early due to a goal is not represented here.
• Play-off overtime, OT, consists of (a potentially repeated) period of 20 minute duration:

OT = 20:00

The possible early ending of the period due to a goal and the repetition of the period is not represented here.
3. Basketball
• Regulation time, RT, consists of two halves, H1 and H2, each consisting of two quarters, Q1 and Q2, and
Q3 and Q4, respectively, each lasting 12 minutes:

RT [ H1 [ Q1 = 12:00
, Q2 = 12:00
]
, H2 [ Q3 = 12:00
(continues on next page)

10 Chapter 3. Formats
 Settlement Templating Language (STL), Release 2.0

(continued from previous page)

, Q4 = 12:00
]
]

3.1.2 Match play phases

Match play phases are those that competitors play to win from one another.
• Points, games and sets in tennis
• Legs and sets in darts
• Frames in snooker
• Holes in match play golf
• Contests in a play-off series, e.g. NBA play-offs and MLB post-season
Dependent on the sport it may or may not be able to draw a match play phase, e.g. golf match-play and tennis games,
respectively.
Match play phases that award the same result to the winner don’t necessarily have the same internal structure.
• A set of tennis may have advantage games up until a score of 6-6 and then play a tie-break game.
• The final set of tennis and volleyball contests often have different rules to the previous sets.
To accomodate this, each match play phase is assigned to a group which determines the incident type that is awarded
when that phase is won. Differences in the rules of play are determined by a match play phase’s subgroup.

3.2 Incidents

An incident in STL records a change in state at some given instant in a contest, e.g. a free-throw being scored, a
yellow card being given to a player or a table-tennis set being won.
Each incident has a mandatry group attribute, e.g. games, cards, legs or sets.
The incident will also carray attributes relating to the structural phase the incident occurred in as well as any other
incident specific metadata. Any attributes that are unknown may be omitted from an incident record.
• A timed incident is generated during a timed phase. It records the clock time of the incident in a time attribute.
type timed-incident =
{ time: clock-time
| incident
}

A goal incident may extend a timed incident as

enum goal-method = own-goal | shot | header | free-kick | penalty

type goal =
{ side: side
, player: unknown | none | playerId
, assist: unknown | playerId
, method: unknown | goal-method
| timed-incident
}

3.2. Incidents 11
Settlement Templating Language (STL), Release 2.0

with example instances

{ group: goals
, time: RT/13:00
, side: vs2
, player: 'Kane'
, assist: none
, method: unknown
}

{ group: goals
, time: H1/46:15
, side: vs1
, player: none
, assist: 'Robertson'
, method: shot
}

• A match play incident is generated when a match play phase completes. It will include a winner attribute,
any appropriate state inherited from the phase and any other metadata that may be attached.

type match-play-incident =
{ winner: side
| incident
}

– Tennis game incident

{ group: games
, subgroup: advantage
, winner: vs1
, server: vs2
}

– A snooker frame

{ group: frames
, winner: vs1
, breakOff: unknown
, score: (147,4)
}

3.3 Predefined formats

Below is the collection of predefined formats in the STL framework.

3.3.1 Football

Incidents

• Incidents

12 Chapter 3. Formats
 Settlement Templating Language (STL), Release 2.0

enum goal-method = penalty | shot | header | free-kick | own-goal;

record goals =
{ team: side
, player: unknown | string
, method: unknown | goal-method
| timed-incident
};

enum card-type = yellow | yellow2 | red;

record cards =
{ team: side
, player: unknown | string
, type: unknown | card-type
| timed-incident
}

record corners =
{ team: side
| timed-incident
}

• Phases
– Regulation time, RT, consists of two halves, H1 and H2, of at least 45 minutes

RT [ H1 >= 45:00
, H2 >= 45:00
]

and may have goals, cards and corners incidents.

– Extra time, ET, is currently a winner only phase.
– Penalty shootout, PS, that it currently a winner only phase.

3.3. Predefined formats 13

Settlement Templating Language (STL), Release 2.0

14 Chapter 3. Formats
 CHAPTER

FOUR

RULES

STL rules are used to define individual settlement rules for a contest.

4.1 Basic operations

4.1.1 Arithmetic operations

STL supports three basic arithmetic operations which all act only on integer types:
• Addition +
• Multiplication *
• Subtraction -
These are useful for defining complex aggregates such as
• Multi-corners

total(<H1, corners>) * total(<H2, corners>)

• Booking points

10 * total(<RT, cards{type='yellow'}>) + 25 * total(<RT, cards{type='red'}>)

STL also support unary negation, -, which acts on any numeric type. This is most often seen when defining
• incidents in reverse order e.g. last goal

nth(-1, <RT, goals>)

• handicap values e.g. home wins with 0.5 handicap

asian(supremacy(<RT, goals>)) > -0.5

4.1.2 Parity operations

The parity of an integer can be tested with

odd(integer)
Returns win when an integer is odd and lose otherwise.
even(integer)
Returns win when an integer is even and lose otherwise.

15
Settlement Templating Language (STL), Release 2.0

Used for example in even total goals

even(total(<RT, goals>))

4.1.3 Comparison operations

STL supports equality comparisons

• Equals =
• Not equals <>
and ordering comparisons
• Less than <
• Less than or equal to <=
• Greater than or equal to >=
• Greater than >
These give rise to the basic settlement conditions e.g.
• Correct score is 3-2

h2h(<RT, goals>) = (3,2)

• Home/away double chance

supremacy(<RT, goals>) <> 0

• Under 2.25 goals

asian(total(<RT, goals>)) < 2.25

4.1.4 Logical operations

Settlement condtions may be combined using the logical operators and and or. This enables more complicated
settlement rules to be built up.
• Home wins from behind

anytime(supremacy(<RT, goals>) < 0) and supremacy(<RT, goals>) > 0

• Either team keeps a clean sheet

total(<RT, goals{side='vs1'}>) = 0 or total(<RT, goals{side='vs2'}>) = 0

not(settlement)
Returns the opposite settlement.
• Away team never leads

not(anytime(supremacy(<RT, goals>) < 0))

16 Chapter 4. Rules
 Settlement Templating Language (STL), Release 2.0

4.2 Samples

Samples form the basis of all settlement rules in STL. They are expressed as a pair, <time interval, incident
group>. See the sections on times, formats and incidents for more information on each component.
• <H1, goals{side=vs1}>: home team goals in the 1st half.
• <*, sets>: sets in the entire contest.
• <sets[3]/games[4], points{win-method=ace}>: aces in the 4th game of the 3rd set.

4.3 Aggregates

Aggregation functions take a sample and perform a calculation over all the relevant incidents that have occured within
the specified time period.
total(sample)
Total number of occurences of a particular sample.
supremacy(sample)
Supremacy (vs1 total - vs2 total) of a given sample.
h2h(sample)
Head-to-head score of a given sample.
winner(sample)
Three-way result of given sample - vs1, vs2 or none.
Using the example of the goals score being 2-1 during regulation time then the above functions would settle as wins
in the following scenarios
• Exactly 3 total goals
total(<RT, goals>) = 3

• Home team wins

supremacy(<RT, goals>) > 0

winner(<RT, goals>) = home

• Not an away win

not(supremacy(<RT, goals>) < 0)

result(<RT, goals>) <> away

• 2-1 correct score

h2h(<RT, goals>) = (2,1)

4.3.1 Altering aggregates

asian(aggregate)
Convert the resulting rules on a integer based aggregate - total, supremacy and any combination thereof -
to asian based resulting.

4.2. Samples 17
Settlement Templating Language (STL), Release 2.0

• Home wins draw no bet

asian(supremacy(<RT, goals>)) > 0

• Over 2.25 first half corners

asian(total(<H1, corners>)) > 2.25

anytime(rule)
Does the settlement rule iwin at any point within the time period rather than just at the end.
• home team scores first

anytime(h2h(<RT, goals>) = (1,0))

• more goals than corners at some point in the contest

anytime(total(<RT, goals>) > total(<RT, cards>))

anytime(h2h(<RT, goals>) = (1,0))

• home team win from behind

anytime(supremacy(<RT, goals>) < 0) and supremacy(<RT, goals>) > 0

4.4 Incident properties

As well as talking about the aggregation of a collection of incidents over a time period we can also refer to the nth
occurence of an incident within a time period.
nth(n, sample)
The nth occurence of a given incident within a sample. The count starts from 1, so the 2nd corner in the 2nd
half would be given by

nth(2, <H2, corners>)

Conversely, you can count backwards with the last incident having n = -1, the penultimate having n = -2,
and so on. e.g. The last home goal in regular time would be

nth(-1, <RT, goals{side='vs1'}>)

firstTo(n, sample)
Return the side (if it exists) who first reach a count of n occurences of a given sample. Like nth() it may not
exist, e.g. first to 2 yellow cards

firstTo(2, <RT, cards{type='yellow'}>)

raceTo(n, sample)
A synonym for firstTo().
ifExists(possible :: none | x, onExists :: x -> a, onNone :: a)
If a given incident exists then perform some operation on it such as projecting a property, otherwise produce
some static property.
• Home team scores 2nd goal or lose if no 2nd goal

18 Chapter 4. Rules
 Settlement Templating Language (STL), Release 2.0

ifExists(nth(2, <RT, goals>), i => $i.side = 'vs1', lose)

• Home team win 3-way race to 5 corners in first half (lose if no-one reaches 5)

ifExists(firstTo(5, <H1, corners>), i => $i = 'vs1', lose)

• Away team win 2-way race to 5 corners in first half (void if no-one reaches 5)

ifExists(firstTo(5, <H1, corners>), i => $i = 'vs2', void)

4.4. Incident properties 19