--- eip: 1202 title: Voting Standard author: Zainan Victor Zhou (@xinbenlv), Evan (@evbots), Yin Xu (@yingogobot) type: Standards Track category: ERC status: Draft created: 2018-07-08 discussions-to: https://github.com/ethereum/EIPs/issues/1202 --- ## Note to Readers 1. We are still open to have co-author to collaborate, in particular, we are looking for co-authors of the following category: - standard designers who are experienced in application-layer standard design, or - developers who have experience with blockchain-based voting system in practice - researchers with research interest in crypto/zero-knowledge-proof voting 2. We have two discussion destinations: - [Github Ethereum EIP Issue #1202](https://github.com/ethereum/EIPs/issues/1202) for long and more mature thoughts - [Telegram Channel t.me/erc1202](https://t.me/erc1202) for real-time and related random chat. 3. We are actively working on updating this draft as many feedbacks have come in since it merged into official EIP repo. If you are viewing a snapshot of this draft, please be adviced the latest dev version of ERC 1202 can be found [here](https://github.com/xinbenlv/eip-1202-draft/blob/master/EIP-1202.md) ## Simple Summary Propose a standard interface for voting. ## Abstract This proposal creates a standard API for implementing voting within smart contract. This standard provides functionalities to voting as well as to view the vote result and set voting status. ## Motivation Voting is one of the earliest example of EVM programming, and also a key to DAO/organizational governance process. We foresee many DAOs will ultimately need to leverage voting as one of the important part of their governance. By creating a voting standard for smart contract / token, we can have the following benefits ### Benefits 1. Allow general UI and applications to be built on top of a standardized voting to allow more general user to participate, and encourage more DApp and DAO to think about their governance 2. Allow delegate voting / smart contract voting, automatic voting 3. Allow voting results to be recorded on-chain, in a standard way, and allow DAOs and DApps to honor the voting result programmatically. 4. Allow the compatibility with token standard such as [ERC-20](https://eips.ethereum.org/EIPS/eip-20) or other new standards([EIP-777](https://eips.ethereum.org/EIPS/eip-777)) and item standard such as [EIP-721](https://eips.ethereum.org/EIPS/eip-721) 5. Create massive potential for interoperability within Ethereum echo systems and other system. 6. Allow setting voting deadline, allow determine on single or multiple options. Allow requiring voting orders. (trade-off is interface complexity, we might need [ERC-20](https://eips.ethereum.org/EIPS/eip-20) approach and later a [EIP-777](https://eips.ethereum.org/EIPS/eip-777) for advanced voting) 7. Recording the voting with weights with token amount. 8. Possibly allow trust-worthy privacy-safe voting and anonymous voting (with either voter address being un-associated with the vote they cast, given a list of randomized/obfuscated voting options). 8 9. Possibly allow result in reward by voting partitipation or voting result ### Use-cases: 1. Determine on issuing new token, issuing more token or issuing sub-token 2. Determine on creating new item under [EIP-721](https://eips.ethereum.org/EIPS/eip-721) 3. Determine on election on certain person or smart contract to be delegated leader for project or subproject 4. Determine on auditing result ownership allowing migration of smart contract proxy address ## Specifications ### Simple Version The simple version of specification makes the assumption that each smart contract voting standard is: *Single Issue*, *Single Selection* and *Single Outcome* ```solidity pragma solidity ^0.4.22; /** * - Single issue * - Single selection * * Discussion: * 1. Each address has a weight determined by other input decided by the actual implementation * which is suggested to be set upon the initialization * 2. Is there certain naming convention to follow? */ interface ERC1202 { // Vote with an option. The caller needs to handle success or not function vote(uint option) external returns (bool success); function setStatus(bool isOpen) external returns (bool success); function issueDescription() external view returns (string desc); function availableOptions() external view returns (uint[] options); function optionDescription(uint option) external view returns (string desc); function ballotOf(address addr) external view returns (uint option); function weightOf(address addr) external view returns (uint weight); function getStatus() external view returns (bool isOpen); function weightedVoteCountsOf(uint option) external view returns (uint count); function winningOption() external view returns (uint option); event OnVote(address indexed _from, uint _value); event OnStatusChange(bool newIsOpen); } ``` ### Advanced Version ```solidity pragma solidity ^0.4.22; /** * - Multiple issue * - Multiple selection * - Ordered multiple result * Discussion: * 1. Each address has a weight determined by other input decided by the actual implementation * which is suggested to be set upon the initialization * 2. Is there certain naming convention to follow? */ contract AdvancedERC1202 { // Vote with an option. The caller needs to handle success or not function vote(uint issueId, uint option) public returns (bool success); function setStatus(uint issueId, bool isOpen) public returns (bool success); function issueDescription(uint issueId) public view returns (string desc); function availableOptions(uint issueId) public view returns (uint[] options); function optionDescription(uint issueId, uint option) public view returns (string desc); function ballotOf(uint issueId, address addr) public view returns (uint option); function weightOf(uint issueId, address addr) public view returns (uint weight); function getStatus(uint issueId) public view returns (bool isOpen); function weightedVoteCountsOf(uint issueId, uint option) public view returns (uint count); function topOptions(uint issueId, uint limit) public view returns (uint[] topOptions_); event OnVote(uint issueId, address indexed _from, uint _value); event OnStatusChange(uint issueId, bool newIsOpen); } ``` ## Rationale We made the following design decisions and here are the rationales. - **Granularity and Anonymity:**: We created a `view` function `ballotOf` primarily making it easier for people to check the vote from certain address. This has the following assumptions: * It's possible to check someone's vote directly given an address. If implementor don't want to make it so easiy, they can simply reject all calls to this function. We want to make sure that we support both anonymous voting an non-anonymous voting. However since all calls to a smart contract is logged in block history, there is really no secrecy unless done with cryptography tricks. I am not cryptography-savvy enough to comment on the possibility. Please see "Second Feedback Questions 2018" for related topic. * It's assumes for each individual address, they can only vote for one decision. They can distribute their available voting power into more granular level. If implementor wants allow this, they ask the user to create another wallet address and grant the new address certain power. For example, a token based voting where voting weight is determined by the amount of token held by a voter, a voter who wants to distribute its voting power in two different option(option set) can transfer some of the tokens to the new account and cast the votes from both accounts. - **Weight**: We assume there are `weight` of votes and can be checked by calling `weightOf(address addr)`, and the weight distribution is either internally determined or determined by constructor. However we have not been considering updating the weight distribution. Please comment on this design decision as we want to learn how likely an implementor would want to be able to update the voting weight distributions. ### Security and Privacy of Voting // TODO ## Backward Compatibility There is no backward compatibility issue we are aware of. ## Interactions with other ERCs // TODO add interaction discussion for the following ERCs ERC20, ERC721, ERC735, ERC780, ERC165 ## Simple Code Examples ### Example 1: Simplest Version: Single Issue Yes/No Question Per Smart Contract Address Per Non-Weighted Vote - [Source Code](https://github.com/xinbenlv/eip-1202-draft/blob/master/contracts/simple-version/SimplestVote1202.sol) - [Deployment (Ropsten)](https://ropsten.etherscan.io/address/0x067e76ddd9c67f7ae606b18d881545512d4b680c#code) ### Example 2: TokenVote with Simple Interface with Weight Assigned by Token and Pre-registered Snapshot of Token-Holders - [Source Code](https://github.com/xinbenlv/eip-1202-draft/blob/master/contracts/simple-version/TokenVote1202.sol) - [Deployment (Ropsten)](https://ropsten.etherscan.io/address/0x5bd007a224fe8820b19cc0bce8e241f4752ce74d#code) ### Example 3: TokenVote with Advanced Interface - [Source Code](https://github.com/xinbenlv/eip-1202-draft/blob/master/contracts/advanced-version/AdvancedTokenVote1202.sol) - [Deployment (Ropsten)](https://ropsten.etherscan.io/address/0xfd8b3be5f9db4662d1c9269f948345b46e37fd26#code) ## Comprehensive Application Examples ### Example 1: Joint Wallet Account Spending Approval // TODO ### Example 2: Secret Vote // TODO ### Example 3: Token Re-issue // TODO ### Example 4: Multi-input Oracle // TODO ## Case Study ### Existing Voting Systems in Blockchain World // TODO #### Carbon Vote // TODO #### PLACE Voting https://medium.com/@jameson.quinn/how-place-voting-works-617a5e8ac422 #### PLCR Voting [PLCR Voting: ](https://github.com/ConsenSys/PLCRVoting) https://medium.com/metax-publication/a-walkthrough-of-plcr-voting-in-solidity-92420bd5b87c #### ### Exiting Voting Systems in Real World // TODO #### Simple Majority Vote Requiring Quorum (e.g. Company Board) // TODO, and a small variant: ZaiGeZaiGu function committee approval (1/2 as quorum, majority vote) #### Two-tiered Shareholder Vote (e.g. GOOG, FB) // TODO #### Jury Decision of US Federal Criminal Court (All Ayle for Guity, 5/5 for Tie) // TODO #### US Presidential Election: Different Vote Time, Multi-Reginal, Two-level (General and Editorial(delegate)) // TODO #### Super-Girl China 2005: Idol Ranking Vote, Multiple Votes Allowed // TODO ## Summary of Discussions ### Early Feedback Questions (2018-07-08) Here are a few early questions I'd like to ask people here. 1. Have we had any duplicated EIPs that I overlooked. If not, have anyone attempted to do so, and why it did not continue to exist? **Answer**: We concluded there is no duplicated efforts working on creating a voting standard. 2. Should each issue have its own smart contract address (like individual item on [EIP-721](https://eips.ethereum.org/EIPS/eip-721)) or should it support multiple items in [EIP-1155](https://eips.ethereum.org/EIPS/eip-1155), or should it support multi-class voting in [EIP-1178](https://eips.ethereum.org/EIPS/eip-1178), [EIP-1203](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1203.md) (e.g. certain issue can override another issue) **Answer**: We will provide examples of both and seek comments. 3. Should the voting support proxy(e.g [EIP-897](https://eips.ethereum.org/EIPS/eip-897), [EIP-1167](https://eips.ethereum.org/EIPS/eip-1167)) and migration? What are potential security concerns **Answer**: It shall not be determined by this ERC. 4. Should it be proposed in a single phase standard or multiple separate into multiple phase, with earlier phase supporting easiest and simplest interface, and later phase supporting more advanced interfaces? (I intuitively believe it will be the latter, but not sure if it might be possible to do it all-at once.) **Answer**: It will unavoidably require upgrade in the future, but supporting multiple issue multiple options will be good enough so far. 1. Should it support or optionally support [EIP-165](https://eips.ethereum.org/EIPS/eip-165)? For public voting, support EIP-165 make it easier to discover, but for secret voting people might not want to disclose a voting for certain issue even exist. **Answer**: It shall not be determined by this ERC. ### Second Feedback Questions 2018-07-19 1. Is it technically possible to achieve anonymous voting on current Ethereum/EVM setup, is it possible that people either hide their identity, or hide what selection they made in a vote given that for a smart contract the public states are visible from block history directly, and internal private state can be replied in any fullnode? 2. number byte length: for simplicity we are using `uint` anywhere undecided. We need to decided what number byte length should we use for `weights` and `options`. ## Bibliography ### Related EIPs - [EIP-20: ERC-20 Token Standard (a.k.a. ERC-20)](https://eips.ethereum.org/EIPS/eip-20) - [EIP-165: Standard Interface Detection](https://eips.ethereum.org/EIPS/eip-165) - [EIP-721: Non-Fungible Token Standard(a.k.a. ERC-721)](https://eips.ethereum.org/EIPS/eip-721) - [EIP-735: ERC: Claim Holder](https://github.com/ethereum/EIPs/issues/735) - [EIP-780: ERC: Ethereum Claims Registry](https://github.com/ethereum/EIPs/issues/780) - [EIP-777: A New Advanced Token Standard](https://eips.ethereum.org/EIPS/eip-777) - [EIP-897: ERC DelegateProxy](https://eips.ethereum.org/EIPS/eip-897) - [EIP-1155: Crypto Item Standard](https://eips.ethereum.org/EIPS/eip-1155) - [EIP-1178: Multi-class Token Standard](https://eips.ethereum.org/EIPS/eip-1178) - [EIP-1167: Minimal Proxy Contract](https://eips.ethereum.org/EIPS/eip-1167) - [EIP-1203: Multi-class Token Standard(ERC-20 Extension)](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1203.md) ### Worthnoting Projects - [Ethereum DAO: How to build a DEMOCRACY on the blockchain](https://www.ethereum.org/dao) - [Carbon Vote](http://carbonvote.com/) - [Paper: A Smart Contract for Boardroom Voting with Maximum Voter Privacy](https://eprint.iacr.org/2017/110.pdf) - *Suggested by @aodhgan* - [Private Voting for TCR](https://blog.enigma.co/private-voting-for-tcrs-with-enigma-b441b5d4fa7b) ### Worthnoting Academic Papers ## Request for Comment We kindly request the community for comments, in particular, the following ERC and projects related authors: - ERC-20: @frozeman, @vbuterin - ERC-721: @fulldecent, Dieter Shirley, Jacob Evans, Nastassia Sachs - Carbon Vote: @lgn21st, @Aaaaaashu - Alex Van de Sande (Mist) and Nick Johnson (ENS) * - suggested by Fabian (@frozeman)* - Will Warren, 0xProject a project who cares a lot about governance. * - nominated by Evan()@evanbots)* Your comments and suggestions will be greatly appreciated. ## Acknowledgement The authors of EIP 1202 greatly appreciate the valuable input from distinguished community members including: @frozeman, @fulldecent, @bingen, @aodhgan. ## EIP Work Logs - 2018-07-08: (@xinbenlv) Created early feedback request. Asked around discussion channels suggested in [EIP-1](https://eips.ethereum.org/EIPS/eip-1), such as [Ethereum-Magicians](https://ethereum-magicians.org/t/eip-x-voting-standard-early-feedback-wanted/670/2), [Gitter](https://gitter.im/ethereum/EIPs), [Reddit](https://www.reddit.com/r/ethereum/comments/8x6k11/early_feedback_request_for_eipx_voting_standard/) - 2018-07-09: (@xinbenlv)Added examples outline. Request for co-author. - 2018-07-17: (@xinbenlv)Added co-author. @evbots, added two simple examples. - 2018-07-19: (@xinbenlv)Added interface-like specification. Moved content from [issue](https://github.com/ethereum/EIPs/issues/1202) to [xinbenlv's Github repo](https://github.com/xinbenlv/eip-1202-draft/blob/master/EIP-1202.md) . Added TokenVote example. - 2018-07-20: (@xinbenlv)Added advanced token vote example. - 2018-07-22: (@xinbenlv)Moved official discussion thread from [github issue](https://github.com/ethereum/EIPs/issues/1202) to [ethereum-magicians](https://ethereum-magicians.org/t/erc-1202-voting-standard-official-discussion-thread/670) - moved back as it's ok to use GitHub issue as official discussion thread. - 2018-07-23: (@xinbenlv) - added co-author Yin Xu (@yingogobot) - added outline for a few applications and case studies for further drafting. - added citation of ERC-735 and ERC-780 - 2018-07-25: (@xinbenlv) Added input from @fulldecent, @bingen, @aodhgan to mention the privacy casting, PLCR etc, and added placeholders for related session. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).