---
tags: Spec-Agreements
---

# Stream Agreement Subsystem Math Spec V2


Green: unique identifiers / brokers
Blue: token flows / accounting
Diamonds: external actions that trigger changes in the state / state mutation events = transactions

-----

**Domain notation**

- $\mathbb{N}$, the natural numbers
- $\mathbb{R}$, the real numbers
- $\mathbb{R}_+$, non-negative real numbers
- $\mathbb{R}_{++}$, strictly positive real numbers
- $\mathbb{R}_{+}^n$ ($\mathbb{R}_{++}^n$), $n$-dimensional vector of non-negative (strictly positive) real numbers
- $\mathbb{R}_{+}^{n \times m}$, ($\mathbb{R}_{++}^{n \times m}$) $n$-by-$m$ dimensional matrix of non-negative (strictly positive) real numbers

------

## Global State

We start with the definition of *global states* of the agreement:

#### System State
| Symbol | Description | Domain | Initial Value |
| --------|------- | ----- | ----- |
| $R$| Unallocated Funds| $\mathbb{R}_+$| $R_{0}$|
| $\mathcal{B}$| Set of all Committed Brokers | | $\bar{B}$|

#### Stateful Metrics
These variables can all be computed from variables within either the local or global state.

| Symbol | Description | Domain | Initial Value |
| --------|------- | ----- | ----- |
| $A (= \sum_{i\in \mathcal{B}} a_i)$ | Allocated Funds| $\mathbb{R}_+$| 0|
|$n$ $(= \vert \mathcal{B}\vert)$|Number of Committed Brokers|$\mathbb{R}_+$, $[n_{\min}, n_{\max}]$|$n_{\min}$|
|$S(=\sum_{i\in \mathcal{B}} s_i)$|Total Broker Stake|$\mathbb{R}_{+}$|$n_{\min} \cdot s_{min}$|
| $\Delta A(= \sum_{i\in \mathcal{B}} \Delta a_i)$ | Allocation Per Epoch | $\mathbb{R}_{+}$ |

#### Parameters

| Symbol | Description | Domain |
| ---------- | ------------------------- | ---------------- |
| $s_{\min}$ | Minimum Stake | $\mathbb{R}_{+}$ |
| $\Delta t$ | Epoch Length | $\mathbb{R}_{+}$ |
| $\tau$ | Minimum Epochs | $\mathbb{R}_{+}$ |
| $n_{\min}$ | Minimum Number of Brokers | $\mathbb{R}_{+}$ |
| $n_{\max}$ | Maximum Number of Brokers | $\mathbb{R}_{+}$ |
| $R_{0}$ | Initial Funding | $\mathbb{R}_{+}$ |
| $\bar{B}$ | Initial Committed Brokers | |
| $\Delta F$ | Payer Payments per Epoch | $\mathbb{R}_{+}$ |

## Local State (Agent Level)

We move forward to define the *local states* of the agents (every ith broker) participating in the system:

| Symbol | Description | Domain | Initial Value |
| --------|------- | ----- | ----- |
| $a_i$ | Allocated Funds/Bounty| $\mathbb{R}_+$| 0|
| $s_i$ | Broker Stake| $\mathbb{R}_{++}$| $s_{min}$|
| $\lambda_i$ | Time Attached| $\mathbb{R}_{++}$| 0|
| $p_i$ | Performance Metric| $[0,1]$| |

## System Constraints

### Minimum Funding

The funding at any point in time must be at the minimum funding amount.

$F \geq F_{min}$

### Minimum Stake

All brokers must have at least the minimum stake.

$s_i \geq s_{min}$

### Number of Brokers

The number of brokers must be constrained within the minimum and maximum number of brokers at all times.

$n_{\min} \leq n \leq n_{\max}$

## Policies Action Space

Here we define the action space for different functions utilized in the mechanisms.

### Actors
Broker $i$

### Actions

#### Allocate

The action which maps the current epochs allocation to different brokers in the system. These inputs are not necessarily all required but rather are all possible needs for different allocation functions.

$Allocate(\mathcal{B}, R, s_{i}, p_{i}, n)\rightarrow a_i$

##### Constraints

$0 \leq a_i$

$\sum_{i\in \mathcal{B}} a_i \leq R$

#### Measure Performance

This action maps each broker to a measure of performance. This can also be coming from an oracle but should only be high trust signals to avoid manipulation.

$MeasurePerformance(\mathcal{B}_i)\rightarrow p_i$

where $p_i \in [0,1]$

#### Check Global Penalized Leaving

This action controls the ability of the entire set of brokers to be able to leave with or without penalty on their stake. While individual brokers may be allowed to leave if they satisfy certain requirements, when this returns true all brokers will be able to leave without penalty.

$CGPL(R, n)\rightarrow y$

where $y \in {0,1}$

#### Check Local Penalized Leaving

This action controls the ability of the individual broker to leave without a penalty on stake. One possible example policy would be when a broker has been in the system for a minimum period of time.

$CLPL(\lambda_i, a_i)\rightarrow y$

where $y \in {0,1}$

#### Check Penalized Leaving

This function serves as a wrapper around the two penalized leaving functions prior to determine if a broker can leave without penalty.

$CPL(R, \lambda_i, a_i)\rightarrow CGPL(R) \text{ OR } CLPL(\lambda_i, a_i) \rightarrow y$

where $y \in {0,1}$

#### Check Ability to Join

This action controls the logic of whether or not an individual broker is capable of joining the agreement.

$CAJ(n, n_{max}, s_i, i)\rightarrow y$

where $y \in {0,1}$

The most likely constraints placed on the broker join would be that there are less than a maximum number of brokers in the system, and the broker has a minimum stake required to join.

## Behavioral Action Space

#### Check Payments Switch

This action controls if payers decide to top up the funds.

$CPS(\mathcal{B}, p_i, R)\rightarrow y$

where $y \in {0,1}$

An example of this switch would be a check that sounds payments are only to be allocated when minimum performance has been met by all brokers, and the funds have fallen below some constant C.

$CPS(\mathcal{B})\rightarrow min(p_i) > .5 \text{ AND } R < C$

#### Allocation Claim

This action controls whether an individual broker choses to claim their allocation.

$AC(a_i)\rightarrow y$

where $y \in {0,1}$

An example would be one where a distribution which is fit to historical data is mapped to boolean values by way of checking if a randomly drawn number is above or below the cdf given the current allocation.

#### Broker Entry

This action holds the logic of brokers joining the system.

$BrokerEntry(n, n_{max}, R) \rightarrow y$

where $y \in {0,1,2...n-n_{max}}$

An example is a poisson random variable for the number of brokers that are entering at a given point where the distribution is conditioned on the unallocated funds.

#### Broker Leaving

This action holds the logic of brokers leaving the system.

$BrokerLeaving(n, R) \rightarrow y$

where $y \in {0,1,2...n}$

## Mechanisms


**TODO: Replace F with R in the diagram ^**
In the picture, F (funds, total payments) is confused with R (unallocated payments). During allocation, tokens move from R to A (allocated funds), so F = R + A should stay the same. R is how the horizon is calculated, not F. F is drained when brokens claim their A, but that should have nothing to do with the state.

### Owner Mechanisms

#### Deploy Live

In the beginning, there should be some quantity of funds $F$ such that $H>H_{\min}$ and a valid number of brokers such that $n_{\min} \leq n \leq n_{\max}$. All steps prior to this live deployment are specified in [Streamr Broker Agreements](https://hackmd.io/e6yijck6TGC2qNWy7i14bg).

#### Cancel

In the event that the owner closes down a contract, each Broker gets back their stake, and recieves any unclaimed tokens allocated to their address as well an equal share of the remaining unallocated assets.

That is to say the quantity $\Delta d_i$ of data tokens is distributed to each broker $i \in \mathcal{B}$

$$\Delta d_i = s_i + a_i + \frac{R}{N}$$

and thus the penultimate financial state of the contract is

$$S=0\\
R = 0\\
A = 0 $$

when the contract is self-destructed.

#### Forced Cancel

There may conditions under which any address may trigger the cancel but these conditions should be indicative of a failure on the part of the payer. An example policy would be to allow forced cancel when $n < n_{\min}$.

### Broker Mechanisms

#### Join

First, when a broker makes the behavioral decision to join the agreement, the availability to join is checked:

$CAJ(n, n_{max}, s_i, i)\rightarrow y$

If y equals 0, the action will be canceled otherwise if it is equal to 1, the set of brokers will be extended and this stake will increase $S$.

$$ \mathcal{B}^+ = \mathcal{B} \cup \{i\}\\
S^+ = S+s_i\\
$$

#### Leave

When the behavioral decision to leave has been made, a check is done to determine if the broker will be penalized.

$CPL(R, \lambda_i, a_i)\rightarrow y$

If y = 1, then there is no penalized leaving and that mechanism handles the action from that point, otherwise it is handled within a penalized leaving.

#### Leave (Non-Penalized)

The broker may leave and will recover their stake and as well will realize their allocations, taking them from the system.

$$\mathcal{B}^+ = \mathcal{B}-\{i\}\\
S^+ = S-s_i \\
A^+= A-a_i$$

This also implies that the stateful metric of $F$ will be updated as so:

$$F^+= F-a_i$$

The broker will receive $s_i + a_i$.

#### Leave (Penalized)

In a case where these conditions are not met, we will have the similar closing out of local broker state, but now they will be forfeiting their stake which will go to the pool of unallocated funds.

$$\mathcal{B}^+ = \mathcal{B}-\{i\}\\
S^+ = S-s_i \\
A^+= A-a_i\\
R^+ = R+s_i$$

This also implies that the stateful metric of $F$ will be updated as so:

$$F^+= F-a_i+s_i$$

The broker will receive $a_i$.

#### Claim

This action is started by the behavior claim action.

There are no constraints on frequency of claims that a broker may make. It is assumed that a claim is for the full amount exactly. When broker i initiates a claim, the following state variables will be updated:

$A^+= A-a_i$

As well, they will receive receive a_i and the local state for the broker will be set to 0 on their claims.

$a_i= 0$

### Payer Mechanisms

A payer, who may or may not be the owner may contribute funds to the agreement in order to ensure its continued existence.

#### Payments

A payer takes the action pay by providing a quantity of DATA tokens $\Delta F$ which increased the unallocated funds (and thus also the total funds).

This relies on the behavioral action of

$CPS(\mathcal{B}, p_i, R)\rightarrow y$

where if y equals 1, funds are allocated to the agreement.

$$ F^+ = F+\Delta F \cdot CPS(\mathcal{B})\\
R^+ = R + \Delta F \cdot CPS(\mathcal{B})$$

### System Mechanisms

#### Time Update & Allocation (Synthetic State Change)

The synthetic state change is a change the contract state that is not realized until later. In this case the automatic allocation of funds from the pool $R$ to the pool $A$ is implicit. For reference see geyser contracts, although rewards each participant is entitled to are determinstic, they are not actually resolved until they make a claim, see broker actions.

Per epoch $t$ of length $\Delta t$, let $\mathcal{B}_t$ be the set of brokers $i\in \mathcal{B}$ for the entirety of the epoch, and if $n_t= \vert \mathcal{B}_t\vert>n_\min$ then

$$a_i^+ = a_i +Allocate(\mathcal{B}, R, s_{i}, p_{i}, n)\\
\Delta A=\sum Allocate(\mathcal{B}, R, s_{i}, p_{i}, n)\\
A^+ = A+\Delta A\\
R^+=R-\Delta A$$

Note that $F^+ = F$ so no tokens are actually flowing, this book-keeping reflects the amount of funds broker $i$ will recieve in the event that they make a claim or other payout event occurs.

As well, for each broker, there will be an update to its time in the system.

$\lambda_i^+ = \lambda_i + 1$