---
tags: Spec-Revenue-Sharing
---

# Delegation Smart Contract Specification

-----

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

------

## Mechanism/Policy/Behavioral Action Space Diagrams

- The diagrams below give a high level view of the system and the types which are sent between different entities to communicate.
- The overall legend depicts what the shapes mean while each diagram has a specific type legend explaining what the types are.
- The next section gives the specific attributes of types.
- Dotted lines show mechanisms making state changes to attributes

**Legend**

Entities: Cylinder
Decisions (Behavioral): Diamond
Policy/Process: Rectangle
Mechanism: Circle
Smart Contracts: Rectangle w/ Squiggly Line
Data Sources: Pirate Ship Sail
Circle With Color: Type

### Delegator Vault Transfers

The aspects of a delegator adding or withdrawing funds from their internal balances is shown below.


Type Legend

Red/DITM: Delegator Internal Transfer Message

Green/DID: Delegator ID

### Pool Delegation

The process by which a delegator takes their internal balance and delegates to a specific broker pool is shown below.


Type Legend

Blue/CAM: Currency Amount Message

Yellow/TAM: Token Amount Message

Purple/SAM: Swap Amount Message

### Broker Staking

The process by which a broker increases or decreases their stake in a given stream agreement is shown below.


Type Legend

Light Green/CSM: Currency Staking Message

### Yield

The process by which broker earned yield is allocated between different accounts is shown below.


Type Legend

Light Purple/RM: Revenue Message

Orange/CAMM: Currency Amount Message Multiple

### Pool Divest

The process by which a delegator withdraws from a pool is shown below. This has some nuance because it may be the case that a broker does not have enough liquidity to cover a withdraw, in which case a debit is used to keep track of IOUs to delegators.


Type Legend

Blue/CAM: Currency Amount Message

Yellow/TAM: Token Amount Message

Purple/SAM: Swap Amount Message

### Slashing Penalty

Because a broker may possibly be slashed for the stake they have in a stream, there needs to be a mechanism to map the lost funds. The below shows how it is accounted for.


Type Legend

Grey/SLASH: Slash Message

------

## System Types

The types within the system which get emitted between different mechanisms.

### Delegator Internal Transfer Message

These messages deal with delegators doing an internal deposit or withdraw.

| Variable | Description | Type |
| --------|------- | ----- |
| delegator_id | The ID of the delegator| Address|
| transfer_amount | The amount to be transferred| Integer|

### Delegator ID

The id of a delegator.

| Variable | Description | Type |
| --------|------- | ----- |
| delegator_id | The ID of the delegator| Address|

### Currency Amount Message

The currency which is being used and transferred into the system as well as IDs.

| Variable | Description | Type |
| --------|------- | ----- |
| currency_amount | Amount of currency | Integer|
| delegator_id | The ID of the delegator| Address|
| pool_id | The ID of the broker pool| Address|

### Currency Amount Message Multiple

An array of currency amount messages

| Variable | Description | Type |
| --------|------- | ----- |
| messages | Current amount messages | CurrencyAmountMessage[]|

### Token Amount Message

The token amount within the system.

| Variable | Description | Type |
| --------|------- | ----- |
| token_amount | Amount of tokens | Integer|
| delegator_id | The ID of the delegator| Address|
| pool_id | The ID of the broker pool| Address|

### Swap Amount Message

The amount of tokens and currency that are to be exchanged.

| Variable | Description | Type |
| --------|------- | ----- |
| token_amount | Amount of tokens | Integer|
| currency_amount | Amount of currency | Integer|
| delegator_id | The ID of the delegator| Address|
| pool_id | The ID of the broker pool| Address|

### Currency Staking Message

This messages depicts the amount of stake which a given broker pool is allocating to a specific stream. This can be positive (adding stake) or negative (withdrawing stake).

| Variable | Description | Type |
| --------|------- | ----- |
| currency_amount | Amount of currency | Integer|
| pool_id | The ID of the broker pool| Address|
| stream_id | The ID of the stream agreement| Address|

### Revenue Message

This message has revenue earned in a period of time as well as the broker which has earned the revenue.

| Variable | Description | Type |
| --------|------- | ----- |
| currency_amount | Amount of currency | Integer|
| pool_id | The ID of the broker pool| Address|

### Slash Message

This message denotes how much a broker was slashed by in a stream.

| Variable | Description | Type |
| --------|------- | ----- |
| currency_amount | Amount of currency | Integer|
| pool_id | The ID of the broker pool| Address|

-----

**Index notation**

| Symbol | Name | Definition | Domain | Unit |
| --------|------- | -------- | -------- | -------- |
| $t$ | Time | Index of discrete events | $\mathbb{N}_0$ | Event |
| $p$ | Broker Pool | Index of broker pools | $\mathbb{N}$ | Address |
| $d$ | Delegator | Index of delegators | $\mathbb{N}$ | Address |
| $b$ | Broker | Index of brokers | $\mathbb{N}$ | Address |
| $s$ | Stream | Index of streams | $\mathbb{N}$ | Address |

## Local State (Vault)

### State

| Symbol | Description | Domain |
| --------|------- | ----- |
| $\mathcal{D}_p^{d}$| Delegator d's pool tokens in the pool p | $\mathbb{R}_{++}$ |
| $\mathcal{I}_d$| Internal balance of delegator d | $\mathbb{R}_{++}$ |
| $\mathcal{I}_b$| Internal balance of broker b | $\mathbb{R}_{++}$ |

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

| Symbol | Description | Domain |
| --------|------- | ----- |
| $\Sigma D_p$| Total Shares for Pool | $\mathbb{R}_{++}$|

## Local State (Broker Pool)

### State

We then go on with the definition of *local states* of the delegator smart contract:

| Symbol | Description | Domain |
| --------|------- | ----- |
| $R_{p}$| Unallocated funds/free funds| $\mathbb{R}_+$|
| $\Pi_p^t$| Historical revenue earned at time t | $\mathbb{R}_+$|
| $\delta_{p}^{j}$| Debits (pool tokens) | $\mathbb{R}_{++}$ |
| $V_{p}$| Fund Value | $\mathbb{R}_{+}$ |
| $\zeta_{p}$| Slashed funds | $\mathbb{R}_{+}$ |
| $S_p^s$| Amount staked on stream s | $\mathbb{R}_{++}$ |

### Parameters

| Symbol | Description | Domain |
| --------|------- | ----- |
| $o$| Owner Share | [0, 1]|
| $b$| Broker address | |

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

| Symbol | Description | Domain |
| --------|------- | ----- |
| $\Sigma S_p$| Total Stake | $\mathbb{R}_{++}$|
| $\Sigma D_p$| Total Shares | $\mathbb{R}_{++}$|

## Local State (Broker)

### State
| Symbol | Description | Domain |
| --------|------- | ----- |
| $P$| Broker pool| $\emptyset$, broker_pool_address|
| $R_{b}$| Free funds| $\mathbb{R}_+$|

## Local State (Delegator)

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

| Symbol | Description | Domain |
| --------|------- | ----- |
| $R_{d}$| Free funds| $\mathbb{R}_+$|

## System Constraints

## Behavioral Action Space

### Actors
Delegator $i$
Broker $j$

### Delegator Actions

#### Delegator Internal Balance Deposit

This behavioral action is triggered when a delegator wants to invest into their internal balance.

##### Followed By

1. Delegator Internal Transfer + Join

##### Output

1. Delegator Internal Balance Message

##### Constraints

1. The number specified for funds is positive
2. The delegator has enough funds to actually transfer

#### Delegator Internal Balance Withdraw

This behavioral action is triggered when a delegator wants to withdraw from their internal balance.

##### Followed By

1. Delegator Withdraw Balance

##### Output

1. Delegator Internal Balance Message

##### Constraints
1. The delegator is registered to the vault
2. The delegator has more funds in the vault than they are trying to withdraw

#### Invest in Pool

This behavioral action is the process by which a delegator delegates to a pool.

##### Followed By

1. Delegator Join Check

##### Output

1. Currency Amount Message

##### Constraints

1. The delegator must have enough funds to cover this investment between their internal balances and their held funds.
2. The currency amount to invest must be positive.

#### Divest from Pool

This behavioral action is called when a delegator wants to withdraw some or all of their shares from a pool.

##### Followed By

1. Delegator Divest Check

##### Output

1. Token Amount Message

##### Constraints

1. The delegator must have more shares in the pool than they are asking to withdraw.

### Broker Actions

#### Increase Stake in Stream

This is the method by which a broker stakes on some stream.

##### Followed By

1. Increase Stake

##### Output

1. Currency Staking Message

##### Constraints

1. The broker must have enough funds for the currency staking.

#### Decrease Stake in Stream

This is the method by which a broker withdraws stake from some stream.

##### Followed By

1. Decrease Stake

##### Output

1. Currency Staking Message

##### Constraints

1. The broker must be trying to withdraw an amount equal to or less than the amount they have staked in the stream.

#### Earns Yield

This is the method by which a broker earns yield from streams. They must call this method to get the yield from the streams that has been accrued.

##### Followed By

1. Yield Policy & Mechanism

##### Output

1. Revenue Message

##### Constraints

#### Slashed in Stream

This is the behavior derived from being slashed in a stream.

##### Followed By

1. Slashing Penalty Allocation

##### Output

1. Slash Message

##### Constraints

## Policies Action Space

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

### Actors
Delegator $i$
Broker $j$

### Vault Transfer Policies

#### Delegator Internal Transfer + Join

This policy takes care of a delegator transferring funds to the vault and possibly joining.

##### Preceded By

1. Internal Balance Deposit

##### Followed By

1. Deposit Funds
2. [If new to the vault] Add Address

##### Input
1. Delegator Internal Transfer Message

##### Output
1. Delegator Internal Transfer Message
2. [If new to the vault] Delegator ID

##### Constraints

#### Delegator Withdraw Funds

This policy takes care of a delegator withdrawing funds from the vault.

##### Preceded By

1. Internal Balance Withdraw

##### Followed By

1. Withdraw Funds
2. [If all funds are taken out] Remove Address

##### Input
1. Delegator Internal Transfer Message

##### Output
1. Delegator Internal Transfer Message
2. [If all funds are taken out] Delegator ID

##### Constraints

### Pool Delegation Policies

#### Delegator Join Check

This policy takes care of checking whether a given delegator is allowed to join the pool.

##### Preceded By

1. Invest in Pool

##### Followed By

1. [If allowed] Pool Maximum Allocation

##### Input
1. Currency Amount Message

##### Output
1. [If allowed] Currency Amount Message

##### Constraints
1. The currency amount must be a positive integer
2. The delegator ID must be registered in the vault
3. The pool ID must be registered in the vault
4. The delegator must have enough funds to cover the amount between internal balance and funds

#### Pool Maximum Allocation

This policy determines the maximum allocation a pool will take. It modifies the payload to be bound as the minimum of the amount and the maximum allocation.

##### Preceded By

1. Delegator Join Check

##### Followed By

1. Delegator Invest

##### Input
1. Currency Amount Message

##### Output
1. Currency Amount Message

##### Constraints
1. The currency amount must be a positive integer
2. The delegator ID must be registered in the vault
3. The pool ID must be registered in the vault
4. The delegator must have enough funds to cover the amount between internal balance and funds

#### Delegator Invest

This policy takes a currency amount message and finds the swap rate to apply returning a swap message for what amount of shares the delegator will be getting for their contribution.

##### Preceded By

1. Pool Maximum Allocation

##### Followed By

1. Withdraw Balance
2. Allocate Pool Tokens

##### Input
1. Currency Amount Message

##### Output
1. Swap Amount Message

##### Constraints

### Broker Staking Policies

#### Increase Stake

This policy has a broker increasing their stake in a given stream.

##### Preceded By

1. Increase Stake in Stream

##### Followed By

1. Increase Stake (Broker)
2. Increase Stake (Stream)
3. Withdraw Funds

##### Input
1. Currency Staking Message

##### Output
1. Currency Staking Message
2. Currency Staking Message
3. Currency Staking Message

##### Constraints
1. The currency staking amount must be a positive integer
2. The pool ID must be registered in the vault
3. The pool must have enough funds to cover the staking
4. The stream address must be valid

#### Decrease Stake

This policy has a broker decreasing their stake in a given stream. There is the possibility of none, some, or all of the funds they receive back going to paying off debits.

##### Preceded By

1. Decrease Stake in Stream

##### Followed By

1. Decrease Stake (Broker)
2. Decrease Stake (Stream)
3. Deposit Funds
4. Stake Allocated to Debits

##### Input
1. Currency Staking Message

##### Output
1. Currency Staking Message
2. Currency Staking Message
3. Currency Staking Message
4. Currency Staking Message

##### Constraints
1. The currency staking amount must be a positive integer
2. The pool ID must be registered in the vault
3. The stream address must be valid

### Yield Policies

#### Yield

The yield policy takes revenue and splits it across the shareholders

##### Preceded By

1. Earn Yield

##### Followed By

1. Broker/Delegator IB Yield Allocation
2. Yield Allocation to Pool Value
3. Yield Allocation to Debits

##### Input
1. Revenue Message

##### Output
1. Currency Amount Message Multiple
2. Revenue Message
3. Revenue Message

##### Constraints

### Pool Divest Policies

#### Delegator Divest Check

This policy takes care of whether a delegator is allowed to divest from a broker pool.

##### Preceded By

1. Divest from Pool

##### Followed By

1. [If Allowed] Delegator Maximum Withdraw

##### Input

1. Token Amount Message

##### Output

1. [If Allowed] Token Amount Message

##### Constraints

#### Delegator Maximum Withdraw

This policy sets the maximum which may be withdrawn.

##### Preceded By

1. Delegator Divest Check

##### Followed By

1. Delegator Divest

##### Input

1. Token Amount Message

##### Output

1. Token Amount Message

##### Constraints

#### Delegator Divest

This policy finds the appropriate swap rate for the withdraw.

##### Preceded By

1. Delegator Maximum Withdraw

##### Followed By

1. Immediate Withdraw
2. Create Debit

##### Input

1. Token Amount Message

##### Output

1. Swap Amount Message

##### Constraints

### Slashing Penalty Policies

#### Slashing Penalty Allocation

This policy controls what happens when a broker is slashed in the stream.

##### Preceded By

1. Slashed in Stream

##### Followed By

1. Pool Value Decrease

##### Input

1. Slash Message

##### Output

1. Slash Message

##### Constraints

## Mechanisms

### Vault Mechanisms

#### Join/Add Address

This mechanism registers a delegator address to the vault.

##### Preceded By

1. Delegator Internal Transfer + Join

##### Followed By

None

##### Input

1. Delegator ID

##### Output

None

##### State Modifications

Variables:

1. delegator_id (Delegator ID)

State Changes:

1. delegator_addresses += delegator_id

##### Constraints

1. The delegator address must not already be in the delegator addresses

#### Remove Address

This mechanism removes a delegator address from the vault.

##### Preceded By

1. Delegator Withdraw Funds

##### Followed By

None

##### Input

1. Delegator ID

##### Output

None

##### State Modifications

Variables:

1. delegator_id (Delegator ID)

State Changes:

1. delegator_addresses -= delegator_id

##### Constraints

1. The delegator address must already be in the delegator addresses

#### Deposit Funds (Internal Balance)

This mechanism takes care of delegators adding to their internal balance in the vault.

##### Preceded By

1. Delegator Internal Transfer + Join
2. Delegator Internal Transfer
3. Immediate Withdraw

##### Followed By

None

##### Input
1. Delegator Internal Transfer Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Delegator Internal Transfer Message)
2. delegator_id (Delegator Internal Transfer Message)

State Changes:

1. funds at delegator_id -= currency_amount
2. vault internal_balance at delegator_id += currency_amount

##### Constraints
1. The currency amount must be a positive integer
2. The delegator ID must be registered in the vault
3. The delegator must have enough funds to cover the amount between internal balance and funds

#### Withdraw Funds (Internal Balance)

This mechanism takes internal balance tokens and sends them to delegators.

##### Preceded By

1. Delegator Withdraw Funds

##### Followed By

None

##### Input

1. Delegator Internal Transfer Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Delegator Internal Transfer Message)
2. delegator_id (Delegator Internal Transfer Message)

State Changes:

1. funds at delegator_id += currency_amount
2. vault internal_balance at delegator_id -= currency_amount

##### Constraints

1. The currency amount must be a positive integer
2. The delegator ID must be registered in the vault
3. The delegator must have enough DATA in the inernal balance to cover the amount of withdraw

#### Allocate Pool Tokens

##### Preceded By

1. Delegator Invest

##### Followed By

None

##### Input

1. Swap Amount Message

##### Output

1. Token Amount Message

##### State Modifications

Variables:

1. token_amount (Token Amount Message)
2. delegator_id (Token Amount Message)
3. pool_id (Token Amount Message)

State Changes:

1. Token Balances at (delegator_id, pool_id) += token_amount

##### Constraints

#### Withdraw Pool Tokens

This mechanism takes care of when pool tokens are withdrawn

##### Preceded By

1. Immediate Withdraw

##### Followed By

None

##### Input

1. Token Amount Message

##### Output

None

##### State Modifications

Variables:

1. token_amount (Token Amount Message)
2. delegator_id (Token Amount Message)
3. pool_id (Token Amount Message)

State Changes:

1. Token Balances at (delegator_id, pool_id) -= token_amount

##### Constraints

1. Token Balances at (delegator_id, pool_id) >= token_amount

#### Broker/Delegator Yield Allocations

This mechanism passes out the yield to the internal balances of the broker and delegators who are earning on it.

##### Preceded By

1. Yield Policy & Mechanism

##### Followed By

None

##### Input

1. Currency Amount Message Multiple

##### Output

None

##### State Modifications

Variables:

1. currency_amount[] (Currency Amount Message Multiple)
2. address[] (Currency Amount Message Multiple)

State Changes:

1. (for each currency_amount, address): Internal Balance at address += currency_amount

##### Constraints

### Broker/Broker Pool Mechanisms

#### Increase Stake in Stream

The mechanism by which a broker increases their stake in a stream.

##### Preceded By

1. Increase Stake

##### Followed By

None

##### Input

1. Currency Staking Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Currency Staking Message)
2. pool_id (Currency Staking Message)
3. stream_id (Currency Staking Message)

State Changes:

1. Stake at (pool_id, stream_id) += currency_amount

##### Constraints

#### Decrease Stake in Stream

The mechanism by which a broker decreases their stake in a stream.

##### Preceded By

1. Decrease Stake

##### Followed By

None

##### Input

1. Currency Staking Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Currency Staking Message)
2. pool_id (Currency Staking Message)
3. stream_id (Currency Staking Message)

State Changes:

1. Stake at (pool_id, stream_id) -= currency_amount

##### Constraints

1. Stake at (pool_id, stream_id) >= currency_amount

#### Deposit Funds

The mechanism to handle funds being added to the broker pool

##### Preceded By

1. Delegator Invest
2. Decrease stake

##### Followed By

None

##### Input

1. Swap Amount Message OR Currency Staking Message

##### Output

1. Currency Amount Message

##### State Modifications

Variables:

1. currency_amount (Swap Amount Message OR Currency Staking Message)
2. pool_id (Swap Amount Message OR Currency Staking Message)

State Changes:

1. Funds at pool_id += currency_amount
2. [IF Delegator Invest] Pool Value at pool_id += currency_amount

##### Constraints

#### Withdraw Funds

##### Preceded By

1. Immediate Withdraw

##### Followed By

None

##### Input

1. Currency Amount Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Currency Amount Message)
2. pool_id (Currency Amount Message)

State Changes:

1. Funds at pool_id -= currency_amount
2. Pool Value at pool_id -= currency_amount

##### Constraints

1. currency_amount <= Funds at pool_id
2. currency_amount <= Pool Value at pool_id

#### Add Debits

##### Preceded By

1. Create Debit

##### Followed By

None

##### Input

1. Token Amount Message

##### Output

None

##### State Modifications

Variables:

1. token_amount (Token Amount Message)
2. pool_id (Token Amount Message)
3. delegator_id (Token Amount Message)

State Changes:

1. APPEND [delegator_id, token_amount] to Debits at (pool_id)

##### Constraints

#### Yield Allocated to Pool Value

The mechanism taking yield and adding it to pool value

##### Preceded By

1. Yield Policy and Mechanism

##### Followed By

None

##### Input

1. Revenue Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Revenue Message)
2. pool_id (Revenue Message)

State Changes:

1. Funds at pool_id += currency_amount
2. Pool Value at pool_id += currency_amount

##### Constraints

#### Yield Allocated to Debits

##### Preceded By

1. Yield Policy and Mechanism

##### Followed By

None

##### Input

1. Revenue Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Revenue Message)
2. pool_id (Revenue Message)

State Changes

1. Waterfall payments sequentially on debits at pool_id.

Functions

1. EXCHANGE_RATE1(pool_tokens) -> data
2. EXCHANGE_RATE2(data) -> pool_tokens

Pseudocode:

<pre>
amount_left = currency_amount
d = debits at pool_id
while amount_left > 0:
if amount_left > EXCHANGE_RATE1(d[0].amount):
amount_left -= d[0].amount
funds at d[0].delegator_id += d[0].amount
d.pop(0)
else:
funds at d[0].delegator_id += amount_left
d[0].amount -= EXCHANGE_RATE2(amount_left)
amount_left = 0
</pre>

##### Constraints

1. currency_amount <= SUM(debits at pool_id)

#### Stake Allocated to Debits

##### Preceded By

1. Decrease Stake

##### Followed By

None

##### Input

1. Currency Staking Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Currency Staking Message)
2. pool_id (Currency Staking Message)

State Changes

1. Waterfall payments sequentially on debits at pool_id.

Functions

1. EXCHANGE_RATE1(pool_tokens) -> data
2. EXCHANGE_RATE2(data) -> pool_tokens

Pseudocode:

<pre>
amount_left = currency_amount
d = debits at pool_id
while amount_left > 0:
if amount_left > EXCHANGE_RATE1(d[0].amount):
amount_left -= d[0].amount
funds at d[0].delegator_id += d[0].amount
d.pop(0)
else:
funds at d[0].delegator_id += amount_left
d[0].amount -= EXCHANGE_RATE2(amount_left)
amount_left = 0
</pre>

##### Constraints

1. currency_amount <= SUM(debits at pool_id)

#### Immediate Withdraw

The mechanism for the amount to immediately withdraw

##### Preceded By

1. Delegator Divest

##### Followed By

1. Deposit Currency
2. Withdraw Tokens

##### Input

1. Swap Amount Message

##### Output

1. Currency Amount Message
2. Token Amount Message

##### State Modifications

None

##### Constraints

#### Create Debit

The mechanism for creating debits on a pool

##### Preceded By

1. Delegator Divest

##### Followed By

1. Add Debits

##### Input

1. Swap Amount Message

##### Output

1. Token Amount Message

##### State Modifications

None

##### Constraints

#### Pool Value Decrease

##### Preceded By

1. Slashing Penalty Allocation

##### Followed By

None

##### Input

1. Slash Message

##### Output

None

##### State Modifications

Variables:

1. currency_amount (Slash Message)
2. pool_id (Slash Message)

State Changes:

1. Pool Value at pool_id -= currency_amount

##### Constraints

1. Pool Value at pool_id >= currency_amount