EIPs/eip-1261.md at 374a3d81543335867ad682960626d4347c6532f8

18 KiB

Raw Blame History

eip	title	author	type	category	status	created	discussions-to
1261	Membership Verification Token (MVT)	Chaitanya Potti <chaitanya@electus.network>, Partha Bhattacharya <partha@electus.network>	Standards Track	ERC	Draft	2018-07-14	https://github.com/ethereum/EIPs/issues/1261

Simple Summary

A standard interface for Membership Verification Token(MVT).

Abstract

The following standard allows for the implementation of a standard API for Membership Verification Token within smart contracts(called entities). This standard provides basic functionality to track membership of individuals in certain on-chain ‘organizations’. This allows for several use cases like automated compliance, and several forms of governance and membership structures.

We considered use cases of MVTs being assigned to individuals which are non-transferable and revocable by the owner. MVTs can represent proof of recognition, proof of membership, proof of right-to-vote and several such otherwise abstract concepts on the blockchain. The following are some examples of those use cases, and it is possible to come up with several others:

Voting: Voting is inherently supposed to be a permissioned activity. So far, onchain voting systems are only able to carry out voting with coin balance based polls. This can now change and take various shapes and forms.
Passport issuance, social benefit distribution, Travel permit issuance, Drivers licence issuance are all applications which can be abstracted into membership, that is belonging of an individual to a small set, recognized by some authority as having certain entitlements, without needing any individual specific information(right to welfare, freedom of movement, authorization to operate vehicles, immigration)
Investor permissioning: Making regulatory compliance a simple on chain process. Tokenization of securities, that are streamlined to flow only to accredited addresses, tracing and certifying on chain addresses for AML purposes.
Software licencing: Software companies like game developers can use the protocol to authorize certain hardware units(consoles) to download and use specific software(games)

In general, an individual can have different memberships in his day to day life. The protocol allows for the creation of software that puts everything all at one place. His identity can be verified instantly. Imagine a world where you don't need to carry a wallet full of identity cards (Passport, gym membership, SSN, Company ID etc) and organizations can easily keep track of all its members. Organizations can easily identify and disallow fake identities.

Motivation

A standard interface allows any user,applications to work with any MVT on Ethereum. We provide for simple ERC-1261 smart contracts. Additional applications are discussed below.

This standard is inspired from the fact that voting on the blockchain is done with token balance weights. This has been greatly detrimental to the formation of flexible governance systems on the blockchain, despite the tremendous governance potential that blockchains offer. The idea was to create a permissioning system that allows organizations to vet people once into the organization on the blockchain, and then gain immense flexibility in the kind of governance that can be carried out.

Trade-off between trustlessness and usability: To truly understand the value of the protocol, it is important to understand the trade-off we are treading on. The MVT contract allows the creator to revoke the token, and essentially confiscate the membership of the member in question. To some, this might seem like an unacceptable flaw, however this is a design choice, and not a flaw. The choice may seem to place a great amount of trust in the individuals who are managing the entity contract(entity owners). If the interests of the entity owner conflict with the interests of the members, the owner may resort to addition of fake addresses(to dominate consensus) or evicting members(to censor unfavourable decisions). At first glance this appears to be a major shortcomings, because the blockchain space is used to absolute removal of authority in most cases. Even the official definition of a dapp requires the absence of any party that manages the services provided by the application. However, the trust in entity owners is not misplaced, if it can be ensured that the interests of entity owners are aligned with the interests of members. Another criticism of such a system would be that the standard edge of blockchain intermediation - “you cannot bribe the system if you don’t know who to bribe” - no longer holds. It is possible to bribe an entity owner into submission, and get them to censor or fake votes. There are several ways to respond to this argument. First of all, all activities, such as addition of members, and removal of members can be tracked on the blockchain and traces of such activity cannot be removed. It is not difficult to build analytics tools to detect malicious activity(adding 100 fake members suddenly who vote in the direction/sudden removal of a number of members voting in a certain direction). Secondly, the entity owners’ power is limited to the addition and removal of members. This means that they cannot tamper any votes. They can only alter the counting system to include fake voters or remove real voters. Any sensible auditor can identify the malicious/victim addresses and create an open source audit tool to find out the correct results. The biggest loser in this attack will be the entity owner, who has a reputation to lose. Finally, one must understand why we are taking a step away from trustlessness in this trade-off. The answer is usability. Introducing a permissioning system expands the scope of products and services that can be delivered through the blockchain, while leveraging other aspects of the blockchain(cheap, immutable, no red-tape, secure). Consider the example of the driver licence issuing agency using the ERC-1300 standard. This is a service that simply cannot be deployed in a completely trustless environment. The introduction of permissioned systems expanded the scope of services on the blockchain to cover this particular service. Sure, they have the power to revoke a person’s licence for no reason. But will they? Who stands to lose the most, if the agency acts erratically? The agency itself. Now consider the alternative, the way licences(not necessarily only drivers licence, but say shareholder certificates and so on) are issued, the amount of time consumed, the complete lack of transparency. One could argue that if the legacy systems providing these services really wanted to carry out corruption and nepotism in the execution of these services, the present systems make it much easier to do so. Also, they are not transparent, meaning that there is no way to even detect if they act maliciously. All that being said, we are very excited to share our proposal with the community and open up to suggestions in this space.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

**Every ERC-1261 compliant contract must implement the ERC1261 interface:

pragma solidity ^0.4.24;

/// @title ERC-1261 MVT Standard
/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1261.md
interface ERC1261 {
    /// @dev This emits when a token is assigned to a member.
    event Assigned(address _to);

    /// @dev This emits when a membership is revoked
    event Revoked(address _to);

    /// @dev MVT's assigned to the zero address are considered invalid, and this
    ///  function throws for queries about the zero address.
    /// @param _owner An address for whom to query the membership
    /// @return whether the member owns the token
    function isCurrentMember(address _to) external view returns (bool);

    /// @notice Find the member of an MVT
    /// @dev index starts from zero. Useful to query all addresses (past or present)
    /// @param _tokenId The index
    /// @return The address of the owner of the IVM contract
    function getAddressAtIndex(uint256 _index) external view returns (address);

    /// @notice Assigns membership of an MVT from owner address to another address
    /// @dev Throws if the member already has the token.
    ///  Throws if `_to` is the zero address.
    ///  Throws if the `msg.sender` is not an owner.
    ///  The entity assigns the membership to each individual.
    ///  When transfer is complete, this function emits the Assigned event.
    /// @param _to The member
    function assign(address _to) external;

    /// @notice Requests membership from any address
    /// @dev Throws if the `msg.sender` already has the token.
    ///  the individual `msg.sender` can request for a membership and if some exisiting criteria are satisfied,
    ///  the individual `msg.sender` receives the token.
    ///  When transfer is complete, this function emits the Assigned event.
    function assignTo() external payable;

    /// @notice Revokes the membership
    /// @dev This removes the membership of the user.
    ///  Throws if the `_from` is not an owner of the token.
    ///  Throws if the `msg.sender` is not an owner.
    ///  Throws if `_from` is the zero address.
    ///  When transaction is complete, this function emits the Revoked event.
    /// @param _from The current owner of the MVT
    function revoke(address _from) external;

    /// @notice Revokes membership from any address
    /// @dev Throws if the `msg.sender` already doesn't have the token.
    ///  the individual `msg.sender` can revoke his/her membership.
    ///  When transfer is complete, this function emits the Revoked event.
    function revokeFrom() external payable;
}

The metadata extension is OPTIONAL for ERC-1261 smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the organization which your IVM tokens represent.

/// @title ERC-1261 IVM Token Standard, optional metadata extension
/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1261.md
interface ERC1261Metadata /* is ERC1261 */ {
    /// @notice A descriptive name for a collection of MVTs in this contract
    function name() external view returns (string _name);

    /// @notice An abbreviated name for MVTs in this contract
    function symbol() external view returns (string _symbol);
}

This is the "ERC1261 Metadata JSON Schema" referenced above.

{
    "title": "Organization Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the organization to which this MVT represents",
        },
        "description": {
            "type": "string",
            "description": "Describes the organization to which this MVT represents",
        }
    }
}

Caveats

The 0.4.24 Solidity interface grammar is not expressive enough to document the ERC-1261 standard. A contract which complies with ERC-1261 MUST also abide by the following:

Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: payable, implicit nonpayable, view, and pure. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a payable function in this interface may be implemented as nonpayble (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.24 is that you can edit this interface to add stricter mutability before inheriting from your contract.
Solidity issue #3419: A contract that implements ERC1261Metadata SHALL also implement ERC1261.
Solidity issue #2330: If a function is shown in this specification as external then a contract will be compliant if it uses public visibility. As a workaround for version 0.4.24, you can edit this interface to switch to public before inheriting from your contract.
Solidity issues #3494, #3544: Use of this.*.selector is marked as a warning by Solidity, a future version of Solidity will not mark this as an error.

If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification.

Rationale

There are many potential uses of Ethereum smart contracts that depend on tracking membership. Examples of existing or planned MVT systems are Vault, a DAICO platform, and Stream, a security token framework. Future uses include the implementation of direct democracy, in-game memberships and badges, licence and travel document issuance, electronic voting machine trails, software licencing and many more.

MVT Word Choice:

Since the tokens are non transferable and revocable, they function like membership cards. Hence the word membership verification token.

Transfer Mechanism

MVTs can't be transferred. This is a design choice, and one of the features that distinguishes this protocol.

Assign and Revoke mechanism

The assign and revoke functions' documentation only specify conditions when the transaction MUST throw. Your implementation MAY also throw in other situations. This allows implementations to achieve interesting results:

Disallow additional memberships after a condition is met — Sample contract found on Electus Protocol
Blacklist certain address from receiving IVM tokens — Sample contract found on Electus Protocol
Disallow additional memberships after a certain time is reached — Sample contract found on Electus Protocol
Charge a fee to user of a transaction — require payment when calling assign and revoke so that condition checks from external sources can be made

Gas and Complexity (regarding the enumeration extension)

This specification contemplates implementations that manage a few and arbitrarily large numbers of MVTs. If your application is able to grow then avoid using for/while loops in your code. These indicate your contract may be unable to scale and gas costs will rise over time without bound

Privacy

Personal information: The protocol does not put any personal information on to the blockchain, so there is no compromise of privacy in that respect. Membership privacy: The protocol by design, makes it public which addresses are/aren’t members. Without making that information public, it would not be possible to independently audit governance activity or track admin(entity owner) activity.

Metadata Choices (metadata extension)

We have required name and symbol functions in the metadata extension. Every token EIP and draft we reviewed (ERC-20, ERC-223, ERC-677, ERC-777, ERC-827) included these functions.

We remind implementation authors that the empty string is a valid response to name and symbol if you protest to the usage of this mechanism. We also remind everyone that any smart contract can use the same name and symbol as your contract. How a client may determine which ERC-1261 smart contracts are well-known (canonical) is outside the scope of this standard.

A mechanism is provided to associate MVTs with URIs. We expect that many implementations will take advantage of this to provide metadata for each MVT system. The URI MAY be mutable (i.e. it changes from time to time). We considered an MVT representing membership of a place, in this case metadata about the organization can naturally change.

Metadata is returned as a string value. Currently this is only usable as calling from web3, not from other contracts. This is acceptable because we have not considered a use case where an on-blockchain application would query such information.

Alternatives considered: put all metadata for each asset on the blockchain (too expensive), use URL templates to query metadata parts (URL templates do not work with all URL schemes, especially P2P URLs), multiaddr network address (not mature enough)

Community Consensus

We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein.

Backwards Compatibility

We have adopted name and symbol semantics from the ERC-20 specification.

Example MVT implementations as of July 2018:

Electus Protocol(https://github.com/chaitanyapotti/ElectusProtocol/blob/master/Vault/VaultToken.sol)

Test Cases

Electus Protocol ERC-1261 Token includes test cases written using Truffle.

Implementations

Electus Protocol ERC1261 -- a reference implementation

MIT licensed, so you can freely use it for your projects
Includes test cases

References

Standards

ERC-20 Token Standard. https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md
ERC-173 Owned Standard. https://github.com/ethereum/EIPs/issues/173
Ethereum Name Service (ENS). https://ens.domains
JSON Schema. http://json-schema.org/
Multiaddr. https://github.com/multiformats/multiaddr
RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt

Issues

The Original ERC-1261 Issue. https://github.com/ethereum/eips/issues/1261
Solidity Issue #2330 -- Interface Functions are Axternal. https://github.com/ethereum/solidity/issues/2330
Solidity Issue #3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412
Solidity Issue #3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419

Discussions

Gitter #EIPs (announcement of first live discussion). https://gitter.im/ethereum/EIPs?at=5b5a1733d2f0934551d37642
ERC-1261 (announcement of first live discussion). https://github.com/ethereum/eips/issues/1261

MVT Implementations and Other Projects

Electus Protocol ERC-1261 Token. https://github.com/chaitanyapotti/ElectusProtocol

18 KiB Raw Blame History Unescape Escape