---
tags: Spec-Agreements
---

# Streamr Broker Agreement Subsystem Math Spec


-----

**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|

## 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}$

## 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. Given a total allocation for the epoch and the broker state, an allocation per broker is determined.

$Allocate(\Delta A, \mathcal{B})\rightarrow a_i$

##### Constraints

$0 \leq a_i \leq \Delta A$

$\sum_{i\in \mathcal{B}} a_i = \Delta A$

#### 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 have stayed in the system long enough, when this returns true all brokers will be able to leave without penalty.

$CGPL(R)\rightarrow y$

where $y \in {0,1}$

#### Check Payments Switch

This action controls if payers do or do not pay into the system at a given time.

$CPS(\mathcal{B})\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, as in something along the lines of:

$CPS(\mathcal{B})\rightarrow min(MeasurePerformance(\mathcal{B}_i)) > .5$

## Mechanisms


### Owner Mechanisms

#### Deploy Live

This is the gensis every whereby the agreement is assumed to have 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
A broker $i$ can join the agreement (and must also join the stream associated with that agreement) by staking $s_i\ge s_{min}$. The other condition is that the number of brokers is less than the maximum number of brokers, $n < n_{\max}$.

First, the condition of $s_i\ge s_{min}$ must be verified. After this has been verified, the set of brokers will be extended and this stake will increase $S$.

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

For the case of tracking the time attatched, we initialize the broker's value at 0.

$\lambda_{i} = 0$

#### Leave (Non-Penalized)

For a broker to be allowed to leave either they must have stayed for longer than the minimum epochs or CGPL returns true. Thus conditions are:

$\lambda_i \geq \tau$

or

$CGPL(R)$

Upon these conditions being met, 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$.

In a more extreme case we may require the broker to relinquish the claim on $a_i$ as well but this would easily be skirted by making a claim action before leaving.

#### Claim

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 is conditioned on the payers being required to pay.

$$ 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(\Delta A, 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$

## KPIS