# SCF Voting Mechanism PoC Design

<style>
body {
counter-reset: heading;
}

h2:before {
content: counter(heading)". ";
counter-increment: heading;
}

h2 {
counter-reset: subheading;
}
h3:before {
content: counter(heading)"." counter(subheading)". ";
counter-increment: subheading;
}

h3 {
counter-reset: subsubheading;
}
h4:before {
content: counter(heading)"." counter(subheading)"." counter(subsubheading)". ";
counter-increment: subsubheading;
}

h4 {
counter-reset: subsubsubheading;
}
h5:before {
content: counter(heading)"." counter(subheading)"." counter(subsubheading)"."counter(subsubsubheading)". ";
counter-increment: subsubsubheading;
}
</style>

## Intro

During the first phase of collaboration, the SDF and BlockScience teams collectively uncovered requirements and desirables for the design of a Proof of Concept voting mechanism for the Stellar Development Fund.

As an output of the second phase, this document describes the design of a voting mechanism PoC. This PoC was developed jointly by BlockScience and the SDF.

## Purpose

Design a POC for a novel Voting Mechanism for the Stellar Community Fund (SCF) that would be implemented and deployed using Soroban, Stellar’s native smart contracts platform (currently in preview release).

Votes will be cast on proposals for distribution of SCF funds to projects to benefit the Stellar Community. Votes can have differing weights and can be both provided directly by the users or indirectly through delegation.

## PoC Design Goals

* Award SCF funds in a manner that brings long-term value to the ecosystem.
* This requires the mechanism to be contextually “**fair**” and “**good**”,
* coordinating participants around **value-adding activities**.
* Modular and flexible.
* This enables adaptability to further use-cases (eg. **Public Goods** vs. VC style funding) and
* allows the community to **co-own** and **co-operate** the mechanisms.
* Additionally, the mechanism should be **scalable** beyond currently limited groups of participants
* Limited complexity --- i.e., **simplicity**. Users should not feel overwhelmed by the logical parts of the mechanism.
* Similarities to already established concepts around Stellar Consensus Protocol (such as trust and Quorums) are regarded as being highly desirable.
* Additionally, SDF strives to enable innovative mechanisms rather than porting of (potentially) contextually non-fitting but already established mechanisms.
* (Definitions:)
* “**fair**”: The mechanism should not without good reason benefit some members of the community over others.
* “**good**”: The mechanism should work for the benefit of the community and not harm its development.
* **value-adding activities**: The activities resulting from the mechanism should bring positive value to the community.
* **Public Goods**: Goods and services that are available to all, but might not have enough incentive for individuals to fund them alone. As opposed to Private Goods, which are owned and benefit individuals, leaving them enough incentive to fund them.
* **co-own**: The mechanism should not be owned by individuals, but by the community as a whole.
* **co-operate**: The community should be able to operate and adapt the mechanisms without relying on specific actors.
* **scalable**: The mechanism should be effective still when numbers of participants are increasing.
* **simplicity**: The community should not feel overwhelmed in understanding, using and adapting the mechanism.

### Proposal Voting Round Protocol Overview

*Figure Round Timeline: The timeline followed by this PoC*

## PoC Requirements in terms of User Stories

To assess whether the PoC implementation conforms to surfaced requirements and desirables, we express them in relationship to User Stories.
In this section, we enumerate a semi-exhaustive set of stories, grouped across User Categories (Generic SCF User, Voter, Monitor and Administrator)

### Generic SCF User

As a generic SCF User, I want
* the mechanisms used in the SCF to be simple enough for me to reason about them and flexible enough for them to be adapted to a changing environment or new use-cases.
* Neural Governance consists of several reasonably simple components, which show complexity only through composition. It allows allows to be parametrized to a changed environment and is designed with separate modules, which can be omitted, changed as well as new modules added to.
* the mechanisms used to be novel applications but also show familiarity to concepts I already know.
* Quorum Voting has similarities to well-known delegation schemes as well as the Stellar Consensus Protocol known to the community and allows for variable Quorum sizes, thresholds, formation and conditional logic to be added to.
* Quorum Voting and Neural Governance are novel applications and combinations of concepts seen before.

The way on which the PoC achieves those stories can roughly mapped by:
* simple flexible $\rightarrow$ Neural Governance
* novel familiar $\rightarrow$ Quorum Voting
* round voting results as signal $\rightarrow$ voting power

### Voter User

* As an eligible voter in the Stellar Network community, I want to be able to and have the choice to vote in a round so that I can assign my voting power for or against each proposal in the round.
* As an eligible voter in the Stellar Network community, I want to be able to delegate my vote on any proposal that I do not want to vote on so that I can entrust my voting power to other users.
* As an eligible voter in the Stellar Network community, I want to be able to check my voting power at any time so that I make informed decisions about delegating my vote.
* As an eligible voter in the Stellar Network community, I want to be able to change my vote for any proposal prior to vote tallying so that I account for changes in my understanding of the issues involved.
* As an eligible voter in the Stellar Network community, I want to be informed of changes in estimated voting power of my delegated votes prior to vote tallying so that I can update my delegations.

### Monitor User

* As a voting round monitor, I want to be informed of the operational status of the Stellar Voting System so that I can alert an administrator of issues.
* As a voting round monitor, I want to be able to check the progress of a voting round so that I can provide feedback to the community.
* As a voting round monitor, I want to be informed of the results of vote tallying so that I can inform the community.

### Administrator

* As a voting round administrator, I want to configure the Neural Governance component so that it fulfills the agreed upon rules for a voting round.
* As a voting round administrator I want to be able to configure a voting round so that a RoundBallot can be generated.
* As a voting round administrator, I want to be informed of operational issues so that I can
* fix issues if I am able to do so, or
* escalate issues if I am unable to fix them.

## PoC Components

The proposed implementation of the SDF Voting Mechanism consists of three main components:
1. PollingPlace
2. PrecinctHQ
3. NeuralGovernance

The following figure illustrates how these components are integrated into a voting mechanism in the PoC. Each component is described in detail in the following sections.

Figure SystemDiagram: This figure shows the components that will be implemented in the POC including interfaces required by and provided by each component.

### The PollingPlace Component

The PollingPlace component implements the user interface with which a voter casts their votes for proposals in a given round of voting using a ballot. PollingPlace transmits a voter's ballot to the Governance component's input interface.

| Interface ID | Method Description | Method Signature | Method Return |
| ------- | ------------------ | --------------------- | ------------- |
| 1 | Voter UI | vote(voterID, ballot) | JSON |
| 2 | Governance module interface | Non-specified | Non-specified |

#### The User Interface SubComponent

* Voting UI --- Fills out a ballot
* Vote Delegation (UI) --- Specifies a delegation policy

### The PrecinctHQ Component

The PrecinctHQ component implements a governor interface through which the governance component transmits the results of a voting round. PrecintHQ implements two user interfaces --- an administrative interface with which a voting round is configured and operated, and an interface from which to monitor the status of a voting round.

PrecintHQ calls into the Monitoring and Administration interfaces exposed by the Governance component. PrecinctHQ

| Interface ID | Method Description | Method Signature | Method Return |
| -------- | -------- | -------- | ------ |
| 1 | Retrieve Vote Data | JSON | JSON |
| 2 | Retrieve Round Configuration | JSON | JSON |
| 3 | Precint Configuration | JSON | JSON |
| 4 | Ballot Results | JSON | JSON |

### The Governance Component --- Neural Governance

The Governance component with which business rules for voting and vote weighting and vote aggregation are specified in subcomponents called neurons. The Governance component also implements non-neural subcomponents which provide input and output interfaces.

![NeuralGovernanceComponent](https://lucid.app/publicSegments/view/91ee8d70-640e-4b45-85af-7f2d27c68670/image.png "Neural Governance Component interfaces" =400x250)

*Figure NeuralGovernanceComponent: externally exposed interfaces of the Neural Governance Component.*

The neural governance component interfaces with operational polling place and PrecinctHQ modules through well defined, fixed, interfaces that have no dependence on the internal of the neural governance component. The neural components that implement voting policy within the neural governance component each communicates.

![NeuralSubcomponent](https://lucid.app/publicSegments/view/215186f0-0005-4709-86d2-dc44d9eae21f/image.png
"Standardized neural subcomponent interfaces")
*Figure NeuralSubcomponent: Each neuron is a modularized subcomponent that implements a vote accounting rule. Externally, communication with a neuron is mediated through a standard set of interfaces. Internally, the functionality of a neuron is implemented by a standardized framework of elements.*

Becuase of this combination of internal modulatity and fixed external interfaces, Neural Governance can be extensively modified without altering the existing architecture.

#### Non-neural Subcomponents

The non-neural components implement the interfaces that the VotingPlace and PrecintHQ must acquire in order to communicate with the Governance component.

##### Neural Governance Voting Subcomponent

The Neural Governance Voting subcomponent provides the interface acquired by Polling Place. Neural Governance Voting acquires the Input interface provided by the QuorumVotingInputNeuron. Each voter's ballot is passed from the Polling Place to the Neural Governance Voting subcomponent via this interface as a RoundBallot. The Neural Governance Voting subcomponent collates RoundBallots from all voters in a round into a RoundVotingMatrix.

| Interface ID | Method Description | Method Signature | Method Return |
| -------- | -------- | -------- | ------ |
| 1 | Ballot input | Text | JSON |

##### Neural Governance Monitoring Subcomponent

| Interface ID | Method Description | Method Signature | Method Return |
| -------- | -------- | -------- | ------ |
| 1 | Text | Text | JSON |

#### Neural Subcomponents

Each neural subcomponent exposes the same interfaces shown in Fig. NeuralSubcomponent. Neurons are wired Output to Input as shown in Fig. SystemDiagram.

| Interface ID | Method Description | Method Signature | Method Return |
| ----- | ------------- | -------- | ---- |
| 1 | Input | Text | JSON |
| 2 | Oracle | Text | JSON |
| 3 | Configuration | Text | JSON |
| 4 | Output | Text | JSON |

## PoC Data Structures

On this section, we describe schemas for the API Calls that users would invoke for interacting the the PoC components

### Round Ballot

The Round Ballot call encapsulates the user action of participating on an Voting Round. An user can either Vote or Delegate. On the first case, he also must provide an list of projects being voted, and on the second case he must provide his list of candidate users to form his Quorum.

{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "$id": "https://stellar.org/QuorumVoting.json.schema",
    "definitions": {
        "RoundBallot": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "roundID": {
                    "type": "string"
                },
                "voterID": {
                    "type": "string",
                    "format": "integer"
                },
                "ballotType": {
                    "type": "string",
                    "enum": ["Vote", "Delegate"]
                }
                "votes": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Vote"
                    }
                }
            },
            "required": [
                "roundID",
                "voterID",
                "ballotType",
                "votes"
            ],
            "if": {
                "properties": {
                    "voteType": {
                        "const": "Delegate"
                    }
                }
            },
            "then": {
                "properties": {
                    "delegatePolicy": "$ref": "#/definitions/VoterDelegationPolicy"
                    }
                }
            },
            "title": "RoundBallot"
        }
    }
}

### Vote

The Vote Schema encapsulates an User Vote towards an Specific Project.

{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "$id": "https://stellar.org/QuorumVoting.json.schema",
    "definitions": {
        "Vote": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "voterID": {
                    "type": "string",
                    "format": "integer"
                },
                "proposalID": {
                    "type": "string",
                    "format": "integer"
                },
                "roundID": {
                    "type": "string"
                },
                "voteCast": {
                    "type": "string",
                    "enum": ["Yes", "No", "Abstain"]
                }
            },
            "required": [
                "proposalID",
                "roundID",
                "voteCast",
                "voterID"
            ],
            "title": "Vote",
            "description": "Schema of a Vote object for Stellar. Represents a single vote cast by a voter.",
        }
    }
}

### Voter Delegation Policy

The Voter Delegation Policy object encapsulates an list of 5 to 10 Potential Delegatees for forming an User Quorum.

{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "$id": "https://stellar.org/QuorumVoting.json.schema",
    "definitions": {
        "VoterDelegationPolicy": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "voterID": {
                    "type": "string",
                    "format": "integer",
                    "description": "The ID of the voter to whom this policy belongs."
                },
                "roundID": {
                    "type": "string",
                    "description": "The ID of the voting round to which this policy applies."
                },
                "delegateList": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "format": "integer",
                        "minItems": 5,
                        "maxItems": 10,
                        "uniqueItems": true
                    },
                    "description": "A list of voter IDs specified for delegation by this policy."
                }
            },
            "required": [
                "voterID",
                "roundID",
                "delegateList"
            ],
            "title": "Voter Delegation Policy",
            "description": "Schema of a VoterDelegationPolicy object for Stellar. Represents to whom a voter is delegating vote."
        }
    }
}

## References

[SCF Voting Mechanism PoC Specification](/GMs8iB1MQEGsJirqqPm3NA)