###### tags: cascading-vote-capital

# Cascading Vote Capital Mathematical Specification

**Created By: Sean McOwen at BlockScience**

## Types

Definitions of types that would be used to ensure type safety with domains, codomains, etc.

| Type Name | Type |
| -------- | ----- |
| addressType |int|
| capitalType |int|
| castVoteType | Tuple[addressType, int]|
| voteEnumType | Dict[int, str]|

## States

The states of the system that could be taken as a snapshot at any time

### Global State

| Variable | Description | Type |
| --------|------- | ----- |
| users | The set of all users in the system | List[UserEntity]|
| current_vote | The current vote happening now| VoteEntity|

### User State

| Variable | Description | Type |
| --------|------- | ----- |
| user_address | The address of the user| addressType|
| controlled_capital | The amount of capital the user controls| capitalType|
| delegate | The address of the delegate that the user has chosen to delegate to| addressType|

### Vote State

| Variable | Description | Type |
| --------|------- | ----- |
| vote_address | The address of the vote| addressType|
| vote_reference | A link to the detailed description of the vote| string|
| start | When the voting starts | datetime|
| end | When the vote ends | datetime|
| vote_enum | Mapping of what each integer number represents in terms of voting choice | voteEnumType|
| registered_votes | All the votes which have been cast so far on the proposal | List[castVoteType]|

## Stateful Metrics

These are things that can be derived from the state at any point but would not be held as part of the state.

### Global State

| Variable | Description | Type | Computation Instruction |
| --------|------- | ----- | ----- |
|total_capital|The total capital in the system|capitalType|Sum the controlled_capital in all users in the system|

### User State

| Variable | Description | Type | Computation Instruction |
| --------|------- | ----- | ----- |
|delegated_voting_capital|The voting capital that has been delegated to this user. This can change depending on recent voting. |capitalType|Need to traverse the tree and find what amount of delegation passes to this user|

### Vote State

| Variable | Description | Type | Computation Instruction |
| --------|------- | ----- | ----- |
|current_votes|A snapshot at the current time of what the votes add up to based on voting and delegation|voteEnumType|Using the registered_votes and traversing the tree, the current votes can be calculated|

## Parameters

Parameters that could be toggled in the system to produce different outcomes.

### Vote Parameters

| Variable | Description | Type |
| --------|------- | ----- |
|minimum_vote_time|The minimum amount of time that a vote has to be live for|DeltaTime|
|maximum_vote_time|The maximum amount of time that a vote can be live for|DeltaTime|

## Entities

The entities that need to be represented within the system.

| Entity | Description | State | Notes |
| --------|------- | ----- | ----- |
|User|The users in the system who can do voting|User State|There will be 0-N users in a system|
|Vote|The votes being debated on in the system|Vote State|There can be many votes over the lifetime of the sytem, however, there should only be one active vote at a time|

## Spaces

The spaces denote payloads that pass through domains and codomains.

### UserJoinSpace

The space which denotes the interface for users joining a system

{user_address: addressType,
controlled_capital: capitalType,
delegate: addressType}

### UserLeaveSpace

The space which denotes the interface for users leaving the system

{user_address: addressType}

### UserEdgeSpace

The space which denotes a source and target user edge

{source: addressType,
target: addressType}

### Proposal Vote Space

{address: addressType,
vote: integer}

### New Vote Space

{vote: voteState}

### Finish Vote Space

{address: addressType}

## Boundary Actions

The definition of different actions that might happen outside of the system such as users joining the system which then need to flow through a chain of actions in the system.

### User Join System

**Description**

The boundary action which triggers a user joining the system

**Called By**

1. User Entities

**Followed By**

1. User Join Policy with spaces transmitted of:
- UserJoinSpace

**Constraints**

1. The user must not already be a part of the system
2. The controlled capital must be consistent
3. The delegate can't be the same as the user_address
4. The user calling this must be the same as the address

### User Leave System

**Description**

The boundary action which triggers a user leaving the system

**Called By**

1. User Entities

**Followed By**

1. User Leave Policy with spaces transmitted of:
- UserLeaveSpace

**Constraints**
1. The user must be part of the system
2. The user calling this must be the same as the address

### Change Delegate

**Description**

The boundary action which triggers a change of a user's delegate

**Called By**

1. User Entities

**Followed By**

1. Change Delegate Policy with spaces transmitted of:
- UserEdgeSpace

**Constraints**
1. The source user must be part of the system
2. The target user must be part of the system
3. The user calling this must be the same as the source address
4. The source and target user can't be the same

### Vote on Proposal

**Description**

The action of voting on the current proposal

**Called By**

1. User Entities

**Followed By**

1. Proposal Vote Policy with spaces transmitted of:
- ProposalVoteSpace

**Constraints**
1. The address is in the system
2. The vote attribute of the passed space is part of the votingEnum of the current active vote (valid voting choice)

## Control Actions

The definition of actions that the system might call, such as an action to update the vote in a circumstance.

### Update Active Vote

**Description**

The system control action which changes what the current active vote is.

Note: How the next active vote is decided is abstracted as outside the system

**Followed By**

1. Update Active Vote Policy with spaces transmitted of:
- NewVoteSpace

**Constraints**
1. There is no current active vote in the system

### Finish Vote

**Description**

The system control action which starts the chain of ending the vote

**Followed By**

1. Finish Vote Policy with spaces transmitted of:
- FinishVoteSpace

**Constraints**

1. The address matches the address of the current active vote

## Policies

A definition of the policies that handle all logical things. This could be, for example, a policy which determines under what conditions a user is allowed to join the system.

### User Join Policy

**Description**

The policy which takes care of users joining the system including:

1. Validating that the user is not already in the set of users
2. Validating the controlled capital is correct and/or computing what it should be
3. Optionally calling the Add User Mechanism if validation is correct

**Followed By**

1. [Optional] Add User Mechanism with spaces transmitted of:
- UserJoinSpace

**Constraints**

### User Leave Policy

**Description**

The policy which takes care of users leaving and anything that needs to happen including:

1. Validation that the user can leave
2. Anything that might need to happen with checking issues from this user being a delegate of other users
3. Anything involved with taking out a vote that the user had submitted on an active vote

**Followed By**

1. [Optional] Remove User Mechanism with spaces transmitted of:
- UserLeaveSpace

**Constraints**

### Change Delegate Policy

**Description**

The policy which takes care of the logic for switching delegates including:

1. Whether the action is able to occur

**Followed By**

1. [Optional] Change Delegate Mechanism with spaces transmitted of:
- UserEdgeSpace

**Constraints**

### Proposal Vote Policy

**Description**

The policy which accounts for how voting on a policy works including:

1. Checking if a vote has already been cast (and possibly allowing for replacement of a vote)
2. Checking if the vote is valid

**Followed By**

1. [Optional] Add Vote Mechanism with spaces transmitted of:
- ProposalVoteSpace

**Constraints**

### Update Active Vote Policy

**Description**

Policy for updating the current active vote

**Followed By**

1. [Optional] Update Active Vote Mechanism with spaces transmitted of:
- NewVoteSpace

**Constraints**

### Finish Vote Policy

**Description**

Policy for finishing the current active vote

1. Takes care of validating if the vote can be finished
2. Takes care of tallying of the votes through the cascading vote capital algorithm
3. Triggers any outside actions that happen with the conclusion of the vote
4. Removes the current active vote upon completion

**Followed By**

TBD

**Constraints**

## State Update Mechanisms

Anything that updates state in the system, usually policies will call these with the outputs of logic. The reasoning to split them out is so that if at some point you want to add a recording variable every time an account is changed or do something like have a variable listener, you can just change the mechanism responsible for it in only one place.

### Add User Mechanism

**Description**

The mechanism which adds a user to the global set of users

**Inputs**

1. UserJoinSpace

** Logic **

1. Add the user_address from _INPUTS[0] to the global state of users

### Remove User Mechanism

**Description**

The mechanism which removes a user from the global set of users

**Inputs**

1. UserLeaveSpace

** Logic **

1. Remove the user_address from _INPUTS[0] to the global state of users

### Change Delegate Mechanism

**Description**

The mechanism which changes the delegate for a user

**Inputs**

1. UserEdgeSpace

** Logic **

1. Set the delegate attribute of _INPUTS[0].source to _INPUTS[0].target

### Update Active Vote Mechanism

**Description**

The mechanism which updates what the active vote is

**Inputs**

1. NewVoteSpace

** Logic **

1. Set the global state's active vote attribute to _INPUTS[0].vote

### Add Vote Mechanism

**Description**

The mechanism which adds a vote for a proposal

**Inputs**

1. ProposalVoteSpace

** Logic **

1. Append the vote from _INPUTS[0] to the global space's active vote registered_votes attribute

## Issue Log

1. What happens when user X has a delegate of user Y, but then Y leaves the system?
2. Do we need to extend to more than one active voting happening at a time
- What implications would it have for delegation, what if you only agree with the delegate on one of the voting issues
- Delegation is done at a global/system level, but then there are individual voting decisions
- Unless I am mistaken on this, it means you can't choose delegation on an issue by issue basis
- Unless it is on an individual level in which case it defeats the purpose of having a fail safe for not voting because then you need to delegate every single vote
3. What if a user tries to leave and they have an active vote already put in?
4. There has to be tracking of delegation changes at every point if we want to be able to go back to a vote and recreate what happened
5. This only will work for getting full votes under the assumption of a completely circular and connected systems. If there are pockets of users delegating only within that group, there is of course a risk that no one votes in the pocket and no voting takes place
6. How likely is it that there will just be a few individuals that all get delegated too, defeating the purpose of even having a cascading vote because there is no possible cascade to take place?
7. Z Thoughts:

I think some of the ancillaries will include:
clarity
about the reference struct from which voting power is derived
a process by which a proposal goes from candidate to active
only one vote
active at a time
voting power for an activate determined by a snapshot
at the time the vote became active
a clear rule about whether re-
delegation is allowed during an active vote or only between active votes
…
likely more tbd

I think we need to account for how votes are initiated — can mostly abstract it away but instances of votes are bounded, a main question in any voting protocol is how do they come into existence and what triggers their resolution