Major draft content update for eip-1202.md

EIPS/eip-1202.md

@@ -39,32 +39,103 @@ Voting is one of the earliest example of EVM programming, and also a key to DAO/
 ## Specifications
 
 ```solidity
-pragma solidity ^0.5.8;
-
-
-/**
- * - Multiple issue
- * - Multiple selection
- * - Ordered multiple result
- **/
-contract ERC1202 {
-
-    // 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);
+// SPDX-License-Identifier: GPL-3.0
+
+pragma solidity >=0.7.0 <0.9.0;
+
+
+/// @title Core interface of ERC1202: A list of *REQUIRED* methods and events for 
+///        a contract to be considered conforming to ERC1202. 
+/// 
+/// @author Zainan Victor Zhou <zzn@zzn.im>
+/// 
+/// @dev Each ERC1202 contract is a cluster of issues being voted on, or done voted.
+///      Any contract of ERC1202 **MUST** implement ALL the following methods and events.
+/// 
+///      Each *issue* is identified with an `issueId`,
+///      For any given `issue`, each available option in that issue is
+///      identified with an `optionId`.
+interface ERC1202Core {
+
+    /// @dev Cast a vote for an issue with `issueId` for option with `optionId`
+    /// @param _issueId: the issue this vote is casting on.
+    /// @param _optionIds: an *ordered* array of the options being casted for the issue.
+    ///   Whenever referring to the options as a whole, the order MUST be maintained.
+    /// @return a boolean if TRUE means the vote is casted successfully. 
+    function vote(uint _issueId, uint[] memory _optionIds) external returns (bool);
+
+    /// @dev Query the top ranked options of an issue given issueId and 
+    ///      a limit of max number of top options.
+    /// @param _issueId: the issue being queried for the top options.
+    /// @param _limit: the max number of top options the caller expect to return.
+    /// @return an ordered list of the top options for given issueId and limit, 
+    ///         where the first in array is the most favorite one, and the last in 
+    ///         array is the least favorite one among the list.
+    ///         Specifically, WHEN limit = 0, returns the default length of winning
+    ///         options in their ranking in an issue. 
+    function topOptions(
+        uint _issueId, uint _limit
+        ) external view returns (uint[] memory);
+
+    /// @dev This event is emitted when a vote has been casted.
+    /// @param issueId the issue the vote is being cased on.
+    /// @param optionIds an ordered list of the options the vote is casting for.
+    event OnVote(uint indexed issueId, uint[] optionIds, address indexed voterAddr);
+
+}
+
+/// @title Metadata interface for ERC1202: A list of *RECOMMENDED* methods and events for 
+///        a contract to be considered conforming to ERC1202. 
+///
+/// @author Zainan Victor Zhou <zzn@zzn.im>
+interface ERC1202Metadata {
+
+    /// @notice A descriptive text for an issue in this contract.
+    function issueText() external view returns (string memory _text);
+
+    /// @notice A distinct Uniform Resource Identifier (URI) for a given issue.
+    /// @dev Throws if `_issueId` is not a valid issue; 
+    ///      URIs are defined in RFC 3986. 
+    function issueURI(uint256 _issueId) external view returns (string memory _uri);
+
+    /// @notice A descriptive text for an option in an issue in this contract.
+    function optionText(uint _issueId, uint _optionId) external view returns (string memory _text);
+
+    /// @notice A distinct Uniform Resource Identifier (URI) for a given option in a given issue.
+    /// @dev Throws if `_issueId` is not a valid option-issue combination; 
+    ///      URIs are defined in RFC 3986. 
+    function optionURI(uint _issueId, uint _optionId) external view returns (string memory _uri);
 }
+
+/// @title Status interface for ERC1202: A list of *RECOMMENDED* methods and events for 
+///        a contract to be considered conforming to ERC1202. 
+///
+/// @author Zainan Victor Zhou <zzn@zzn.im>
+interface ERC1202Status {
+
+    /// @dev This event is emitted when an issue has changed status.
+    /// @param issueId the issue about which a status change has happened.
+    /// @param isOpen the status
+    event OnStatusChange(uint indexed issueId, bool indexed isOpen);
+
+    /// @dev Sets the status of a issue, e.g. open for vote or closed for result.
+    /// @param _issueId the issue of Status being set.
+    /// @param _isOpen the status to set.
+    /// @return _success whether the setStatus option succeeded.
+    function setStatus(uint _issueId, bool _isOpen) external returns (bool _success);
+
+    /// @dev Gets the status of a issue, e.g. open for vote or closed for result.
+    /// @param _issueId the issue of Status being get.
+    /// @return _isOpen the status of the issue.
+    function getStatus(uint _issueId) external view returns (bool _isOpen);
+
+    /// @dev Retrieves the ranked options voted by a given voter for a given issue.
+    /// @param _issueId the issue
+    /// @param _voter the aaddres of voter.
+    /// @return _optionIds the ranked options voted by voter.
+    function voteOf(uint _issueId, address _voter) external view returns (uint[] memory _optionIds);
+}
+
 ```
 
 ## Rationale
@@ -82,20 +153,6 @@ We made the following design decisions and here are the rationales.
 ## Backward Compatibility
 There is no backward compatibility issue we are aware of.
 
-## 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)
-
 ## Security Considerations
 
 EIP-1202 is a voting standard. We expect the voting standard to be used in connection with other contracts such as token distributions, conducting actions in consensus or on behalf of an entity, multi-signature wallets, etc.
@@ -113,32 +170,6 @@ The third consideration is non-trivialness. Some voting applications assume ***a
 
 The fourth consideration is potential abuse. When voting is standardized and put on contract, it is possible to write another contract that rewards a voter to vote in a certain way. It creates potential issues of bribery and conflict of interest abuse that is previously hard to implement.
 
-
-## Bibliography
-### Related EIPs
- - [EIP-20: ERC-20 Token Standard (a.k.a. ERC-20)](./eip-20.md)
- - [EIP-165: Standard Interface Detection](./eip-165.md)
- - [EIP-721: Non-Fungible Token Standard(a.k.a. ERC-721)](./eip-721.md)
- - [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](./eip-777.md)
- - [EIP-897: ERC DelegateProxy](./eip-897.md)
- - [EIP-1155: Crypto Item Standard](./eip-1155.md)
- - [EIP-1178: Multi-class Token Standard](./eip-1178.md)
- - [EIP-1167: Minimal Proxy Contract](./eip-1167.md)
- - [EIP-1203: Multi-class Token Standard(ERC-20 Extension)](./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)
- - [Consensus/PLCR implementation](https://github.com/ConsenSys/PLCRVoting)
- - [Aragon Voting App](https://wiki.aragon.org/dev/apps/voting/)
-
-## Acknowledgement
-We appreciate Ansley, Andrew, Fred from Enigma, Fan and Raullen from IoTex for sharing us their use cases. we also appreciate the valuable input for designing an EIP from distinguished community members including: @frozeman, @fulldecent, @bingen, @aodhgan.
-
 ## Work Directory
 The drafting and revision of EIP-1202 is conducted at [GitHub/xinbenlv/eip-1202](https://github.com/xinbenlv/eip-1202)