---
tags: Proposals
---

# Kick Out Voting Proposal V5

## Summary

This fifth version of the proposal improves on V4 by adding in the cancel option for flagging and also modifying the slashing for a broker so that they do not necessarily lose their entire stake but instead some parameter percentage.

The main scenario this proposal defends against are brokers not doing any work (no strategic maliciousness yet).

## Graphics

### How to Read

Behavioral Actions
These are any of the behaviors that we see an entity calling to initiate a chain of actions.

Policies
These are the blocks that take a message and map out what policies or mechanisms to call next as well as the new messages to pass to them. This is where logic such as if an audit passes happens.

Mechanisms
These are the blocks that update state in the system.

Messages
These are the inputs/outputs passed between behavioral actions, policies, and mechanisms.

### Full System Visualization

Message Legend:

red: BrokerFlaggingMessage -> {'flagging_broker': <class 'primitives.BrokerAddress'>, 'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>}

blue: PeerReviewMessage -> {'reviewer': <class 'primitives.BrokerAddress'>, 'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>, 'passed_audit': <class 'bool'>}

orange: PeerBrokersMessage -> {'address': <class 'primitives.BrokerAddress'>, 'peer_addresses': <class 'primitives.BrokerAddresses'>}

grey: BrokerAddressMessage -> {'address': <class 'primitives.BrokerAddress'>}

pink: AuditResultMessage -> {'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>, 'passed_audit': <class 'bool'>}


### Flag Broker Visualization

Message Legend:

red: BrokerFlaggingMessage -> {'flagging_broker': <class 'primitives.BrokerAddress'>, 'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>}

orange: PeerBrokersMessage -> {'address': <class 'primitives.BrokerAddress'>, 'peer_addresses': <class 'primitives.BrokerAddresses'>}

grey: BrokerAddressMessage -> {'address': <class 'primitives.BrokerAddress'>}


### Peer Review Brokers Visualization

Message Legend:

blue: PeerReviewMessage -> {'reviewer': <class 'primitives.BrokerAddress'>, 'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>, 'passed_audit': <class 'bool'>}

pink: AuditResultMessage -> {'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>, 'passed_audit': <class 'bool'>}


### Cancel Flag Visualization

Message Legend:

grey: BrokerAddressMessage -> {'address': <class 'primitives.BrokerAddress'>}

pink: AuditResultMessage -> {'flagged_broker': <class 'primitives.BrokerAddress'>, 'stream': <class 'primitives.StreamAddress'>, 'passed_audit': <class 'bool'>}


## New Parameters

| Name | Description | Type |
| -------- | -------- | -------- |
|number_peer_broker|The number of peer brokers which are assigned to a flagged broker when a flag is raised|Integer|
|number_peer_voters|The number of peer broker votes which are potentially counted for peer-review (so if this is 7, we can have anywhere from 4-7 actual counting votes, depending on how unanimous the majority is)|Integer|
|amount_stake_flagging|The amount of tokens a flagging broker has to allocate from his bounty stake to pay for peer-review service if his flagging is incorrect|Integer |
|amount_payment_reviewer|The amount of tokens a reviewer gets if he votes with the majority and his vote is counted (could either be flat amount or share of stake?)|Integer|
|amount_payment_flagger|The amount of tokens a flagger gets if his flag was found to be correct by majority vote (could also be 0 -> incentive to remove freerider from bounty could be enough and deter malicious flagging?)|Integer|
|percentage_stake_slashing|The percentage of stake that a broker is slashed by if they are voted as guilty by the flagging process|Percentage|
|min_flag_cancel_time|The minimum amount of time that a vote must have been live for before it can be cancelled with the Cancel Flag behavior.|Days/Hours|

## Behavioral Actions/Prior Actions

### Flag Broker

- This behavior is called by a broker on another broker to start the peer review process
- Broker calling this action needs to put up a stake to cover rewards if the flagging was false
- It leads to Peer Review Policy afterwards

### Peer Review Brokers

- This is the behavior of brokers peer reviewing brokers which they have been assigned to audit
- All voting goes into the peer review policy which decides the actions to take once number_peer_voters is reached

### Cancel Flag

- This behavior is called when a broker tries to cancel a flag that was put on
- It does not necessarily cancel it, this depends on the policy afterwards

## Policies

### Flag Broker Policy

- The policy which decides whether or not a flag for a broker should be added.

### Peer Review Stake Policy
- This policy determines the amount needed to be staked to start a peer-review process by a specific broker on another broker
- It calls transfer stake with the amount_stake_flagging amount which the flagger needs to put up as collateral
- It also calls the assign peer brokers policy which begins the process of the review

### Assign Peer Brokers Policy

- This policy defines which other brokers are responsible for peer-reviewing the flagged broker
- Base case is **number_peer_broker** random brokers assigned when a broker is flagged
- (Voting concludes when **number_peer_voters** brokers have voted (number_peer_voters<number_peer_broker) )
- Sam and Juuso working on ideas for assigning brokers, having a global list to choose from, and for logic for SC to do this
- Emits event that these brokers are assigned
- (brokers need to know they are assigned, and contract needs to verify)

### Peer Review Policy
- This policy determines the voting logic for external peer reviews
- Specifics needed: Time for the process, voting response, evaluation of responses
- NOTE: There are two ways to structure the voting - either we do confidential voting, where users cannot see each others votes before the vote is concluded (more complicated plus overhead), or we use e.g. 7 votes needed out of 20 brokers chosen. Only first votes count, and only until a majority was found (so first four votes yes, fifth yes vote doesn't count), which incentivizes voting early rather than scanning mempool etc to vote with majority (which again is anyways soft countered by majority running non-altered code)
- If found guilty, Failed Peer Review Policy is called otherwise Passed Peer Review Policy is called
- While voting is in progress, tracking of votes will be kept until number_peer_voters is reached
- At that point, majority wins of the votes recorded
- Those who voted are rewarded in the pay peer reviewers policy

### Passed Peer Review Policy

- This policy would deal with how rewards are given to Peer Reviewers
- There is many considerations including vesting, timing of payments, bundling of payments, etc.
- For the moment we will assume it is a simple policy that takes the reward and immediately pays out to:
- Rewards go to all non-guilty voters through Pay Peer Reviewers Policy
- Penalize Peer Review Stake Policy to punish the flagger who incorrectly flagged
- Remove Flag from Broker is called to get rid of the flag that was on the broker
- The Remove Peer Brokers to get rid of the peer brokers now that the review is complete

### Failed Peer Review Policy
- This policy which takes care of a failed peer review.
- The Pay Peer Reviewers Policy is called to reward the peer reviewers who voted guilty
- The Reward Peer Review Stake Policy is called to reward the flagger
- The Kick Out Broker mechanism is called to kick the broker from the stream
- The Remove Peer Brokers to get rid of the peer brokers now that the review is complete

### Penalize Peer Review Stake Policy
- This policy determines the penalty for a passed peer review given to the flagger
- It ends with an amount to slash from the flagger

### Reward Peer Review Stake Policy
- This policy determines the reward for a failed peer review given to the flagger
- It calls the mechanism of Reverse Transfer Stake since the broker gets back their collateral and also calls the Pay Flagger mechanism so the flagger can get a reward for flagging

### Cancel Flag Policy
- This policy decides if a flag can be cancelled
- The current implementation would be to cancel the flag if the time since the vote has been live is over the parameter min_flag_cancel_time
- If it goes through, the peer brokers will be reset, the flag will be removed and the broker's peer review stake will be reversed back into the regular account

## Mechanisms

### Add Flag to Broker

- The mechanism which sets the broker flag for the broker in the stream which has just been flagged
- This is for tracking who is under review in the stream

### Transfer Stake

- This mechanism will take an amount of stake in a stream and transfer it from the regular stake account to the peer_review_stake account
- This movement of stake allows for future use of the stake as collateral if the flagger is incorrect

### Set Peer Brokers

- This mechanism sets the peer brokers for the review process
- The stream will have a set of peer brokers mapped to the key of the broker under review

### Remove Flag from Broker

- This mechanism simply removes the flag that a broker had on it within a stream

### Remove Peer Brokers

- This is a cleanup mechanism to get rid of peer brokers that were assigned after a review is complete

### Slash Peer Review Stake

- This mechanism slashes the peer_review_stake of a broker who flagged, leaving the funds to pay for the reviwers
- It is meant to make it less likely that a broker flags random other brokers

### Reverse Transfer Stake

- This mechanism reverses the prior transfer of stake from stake to peer_review_stake, it will take the peer_review_stake and put it back into regular stake again

### Pay Peer Reviewers

- The mechanism for taking peer_review_stake account funds and allocating it to the peer reviewers

### Pay Flagger

- The mechanism for granting a reward to the flagger
- Funds are taken from the peer_review_stake account and transferred to the flagger

### Kick Broker

- Given a broker i/stream j combination, this will do the following:
- Slash percentage_stake_slashing percentage of broker[i]'s stake
- Kick the broker from the stream
- Possibly add them to a list of banned accounts

## Assumptions

1. With n-brokers selected randomly from a list of all brokers currently in bounties, the expectation is that they are live. If they do not vote, we might have the next candidate who's freeriding.
2. Sybil attacks to kick out a broker actually doing work are not easily done
3. Since the voting / validation can be included in official node software, everyone votes honestly unless they actively tweak their code to do it differently
4. Since only those who voted with majority are paid, and the assumption is that most nodes will not run maliciously tweaked code, the strategy to vote maliciously is very risky

Timeline / life cycle of a flag
======

| What | When | Description |
| ------------------- | -------- | -------- |
| Flag raised | `Bounty.flag` called | |
| Reviewers chosen | in the same transaction | |
| Start review | when reviewers notice an event | |
| Grace period? | before voting starts? | Flagged broker gets time to come back online and resume brokering |
| Voting starts | after desired review time | There should be enough time for a review (that we pay for, after all) |
| Flag cancelled | after `min_flag_cancel_time` | |
| Voting ends | after last vote is cast so there's a quorum?| | Pay the reviewers/flagger | in the same transaction? | |

Examples
========

**Setup**: Bounty has following parameters:
* minimum stake: 1 DATA
* minimum flag-stake: 2 DATA
* peer reviewer majority shares a flat reward of: 1 DATA
* slashing in case of failed peer review: 10%
* flagger reward: 100% of flag-stake

Bounty has the following brokers staked:
* Freerider 100 DATA
* Flagger 50 DATA
* SmallFlagger 5 DATA

**Example 1**: Flagger raises a flag, stakes the minimum 2 DATA on it. Flagger's stake is still 50 DATA.

If the peer review concludes that Freerider should be slashed:
* 10 DATA is slashed from Freerider. Freerider gets thrown out with 90 DATA
* 1 DATA goes to the peer reviewer majority
* 2 DATA goes to Flagger (100% of the flag-stake). Their stake is now 52 DATA
* remaining 7 DATA goes to the bounty as sponsorship

If the peer review concludes that Freerider should NOT be slashed:
* Freerider's stake is still 100 DATA
* Flagger's stake is deducted by the flag-stake, down to 48 DATA
* 1 DATA goes to the peer reviewer majority
* remaining 1 DATA goes to the bounty as sponsorship

**Example 2**: Flagger raises a flag, stakes the maximum of 9 DATA = (what Freerider stands to lose) - (what peer reviewers get). Flagger's stake is still 50 DATA.

If peer review concludes that Freerider should be slashed:
* 10 DATA is slashed from Freerider. Freerider gets thrown out with 90 DATA
* 1 DATA goes to the peer reviewer majority
* 9 DATA goes to Flagger (100% of the flag-stake). Their stake is now 59 DATA

If the peer review concludes that Freerider should NOT be slashed:
* Freerider's stake is still 100 DATA
* Flagger's stake is deducted by the flag-stake, down to 41 DATA
* 1 DATA goes to the peer reviewer majority
* remaining 8 DATA goes to the bounty as sponsorship

**Example 3**: SmallFlagger raises a flag, stakes the maximum of 4 DATA = (what SmallFlagger has staked) - (minimum stake). SmallFlagger's stake is still 5 DATA.

If peer review concludes that Freerider should be slashed:
* 10 DATA is slashed from Freerider. Freerider gets thrown out with 90 DATA
* 1 DATA goes to the peer reviewer majority
* 4 DATA goes to SmallFlagger (100% of the flag-stake). Their stake is now 9 DATA
* remaining 5 DATA goes to the bounty as sponsorship

If the peer review concludes that Freerider should NOT be slashed:
* Freerider's stake is still 100 DATA
* SmallFlagger's stake is deducted by the flag-stake, down to 1 DATA
* 1 DATA goes to the peer reviewer majority
* remaining 2 DATA goes to the bounty as sponsorship