EIP-1261: Membership Verification Token (MVT)

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 their day to day life. The protocol allows for the creation of software that puts everything all at one place. Their 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.

Attributes are a huge part of ERC-1261 which help to store identifiable information regarding its members. Polls can make use of attributes to calculate the voterbase. E.g: Users should belong to USA entity and not belong to Washington state attribute to be a part of a poll.

There will exist a mapping table that maps attribute headers to an array of all possible attributes. This is done in order to subdivide entities into subgroups which are exclusive and exhaustive. For example, header: blood group alphabet Array: [ o, a, b, ab ] header: blood group sign Array: [ +, - ]

NOT an example of exclusive exhaustive: Header: video subscription Array: [ Netflix, HBO, Amazon ] Because a person is not necessitated to have EXACTLY one of the elements. He or she may have none or more than one.

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.

We have also reviewed other Membership EIPs including EIP-725/735 Claim Registry. A significant difference between #735 claims and #1261 MVTs is information ownership. In #735 the Claim Holder owns any claims made about themselves. The problem with this is that there is no way for a Claim Issuer to revoke or alter a claim once it has been issued. While #735 does specify a removeClaim method, a malicious implementation could simply ignore that method call, because they own the claim.

Imagine that SafeEmploy™, a background checking company, issues a claim about Timmy. The claim states that Timmy has never been convicted of any felonies. Timmy makes some bad decisions, and now that claim is no longer true. SafeEmploy™ executes removeClaim, but Timmy’s #735 contract just ignores it, because Timmy wants to stay employed (and is crypto-clever). #1261 MVTs do not have this problem. Ownership of a badge/claim is entirely determined by the contract issuing the badges, not the one receiving them. The issuer is free to remove or change those badges as they see fit.

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, ERC173 and ERC165 interfaces (subject to “caveats” below):

/// @title ERC-1261 MVT Standard
/// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1261.md
///  The constructor should define the attribute set for this MVT.
///  Note: the ERC-165 identifier for this interface is 0x1d8362cf.
interface IERC1261 {/* is ERC173, ERC165 */
    /// @dev This emits when a token is assigned to a member.
    event Assigned(address indexed _to, uint[] attributeIndexes);

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

    /// @dev This emits when a user forfeits his membership
    event Forfeited(address indexed _to);

    /// @dev This emits when a membership request is accepted
    event ApprovedMembership(address indexed _to, uint[] attributeIndexes);

    /// @dev This emits when a membership is requested by an user
    event RequestedMembership(address indexed _to);

    /// @dev This emits when data of a member is modified.
    ///  Doesn't emit when a new membership is created and data is assigned.
    event ModifiedAttributes(address indexed _to, uint attributeIndex, uint attributeValueIndex);

    /// @notice Adds a new attribute (key, value) pair to the set of pre-existing attributes.
    /// @dev Adds a new attribute at the end of the array of attributes and maps it to `values`.
    ///  Contract can set a max number of attributes and throw if limit is reached.
    /// @param _name Name of the attribute which is to be added.
    /// @param values List of values of the specified attribute.
    function addAttributeSet(bytes32 _name, bytes32[] calldata values) external;

    /// @notice Modifies the attribute value of a specific attribute for a given `_to` address.
    /// @dev Use appropriate checks for whether a user/admin can modify the data.
    ///  Best practice is to use onlyOwner modifier from ERC173.
    /// @param _to The address whose attribute is being modified.
    /// @param _attributeIndex The index of attribute which is being modified.
    /// @param _modifiedValueIndex The index of the new value which is being assigned to the user attribute.
    function modifyAttributeByIndex(address _to, uint _attributeIndex, uint _modifiedValueIndex) 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 if some existing criteria are satisfied.
    ///  When a membership is requested, this function emits the RequestedMembership event.
    ///  dev can store the membership request and use `approveRequest` to assign membership later
    ///  dev can also oraclize the request to assign membership later
    /// @param _attributeIndexes the attribute data associated with the member.
    ///  This is an array which contains indexes of attributes.
    function requestMembership(uint[] calldata _attributeIndexes) external payable;

    /// @notice User can forfeit his membership.
    /// @dev Throws if the `msg.sender` already doesn't have the token.
    ///  The individual `msg.sender` can revoke his/her membership.
    ///  When the token is revoked, this function emits the Revoked event.
    function forfeitMembership() external payable;

    /// @notice Owner approves membership from any address.
    /// @dev Throws if the `_user` doesn't have a pending request.
    ///  Throws if the `msg.sender` is not an owner.
    ///  Approves the pending request
    ///  Make oraclize callback call this function
    ///  When the token is assigned, this function emits the `ApprovedMembership` and `Assigned` events.
    /// @param _user the user whose membership request will be approved.
    function approveRequest(address _user) external;

    /// @notice Owner discards membership from any address.
    /// @dev Throws if the `_user` doesn't have a pending request.
    ///  Throws if the `msg.sender` is not an owner.
    ///  Discards the pending request
    ///  Make oraclize callback call this function if criteria are not satisfied
    /// @param _user the user whose membership request will be discarded.
    function discardRequest(address _user) external;

    /// @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 the token is assigned, this function emits the Assigned event.
    /// @param _to The address to which the token is assigned.
    /// @param _attributeIndexes The attribute data associated with the member.
    ///  This is an array which contains indexes of attributes.
    function assignTo(address _to, uint[] calldata _attributeIndexes) external;

    /// @notice Only Owner can revoke 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 revokeFrom(address _from) external;

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

     /// @notice Gets the value collection of an attribute.
    /// @dev Returns the values of attributes as a bytes32 array.
    /// @param _name Name of the attribute whose values are to be fetched
    /// @return The values of attributes.
    function getAttributeExhaustiveCollection(bytes32 _name) external view returns (bytes32[] memory);

    /// @notice Returns the list of all past and present members.
    /// @dev Use this function along with isCurrentMember to find wasMemberOf() in Js.
    ///  It can be calculated as present in getAllMembers() and !isCurrentMember().
    /// @return List of addresses who have owned the token and currently own the token.
    function getAllMembers() external view returns (address[]);

    /// @notice Returns the count of all current members.
    /// @dev Use this function in polls as denominator to get percentage of members voted.
    /// @return Count of current Members.
    function getCurrentMemberCount() external view returns (uint);

    /// @notice Returns the list of all attribute names.
    /// @dev Returns the names of attributes as a bytes32 array.
    ///  AttributeNames are stored in a bytes32 Array.
    ///  Possible values for each attributeName are stored in a mapping(attributeName => attributeValues).
    ///  AttributeName is bytes32 and attributeValues is bytes32[].
    ///  Attributes of a particular user are stored in bytes32[].
    ///  Which has a single attributeValue for each attributeName in an array.
    ///  Use web3.toAscii(data[0]).replace(/\u0000/g, "") to convert to string in JS.
    /// @return The names of attributes.
    function getAttributeNames() external view returns (bytes32[] memory);

    /// @notice Returns the attributes of `_to` address.
    /// @dev Throws if `_to` is the zero address.
    ///  Use web3.toAscii(data[0]).replace(/\u0000/g, "") to convert to string in JS.
    /// @param _to The address whose current attributes are to be returned.
    /// @return The attributes associated with `_to` address.
    function getAttributes(address _to) external view returns (bytes32[]);

    /// @notice Returns the `attribute` stored against `_to` address.
    /// @dev Finds the index of the `attribute`.
    ///  Throws if the attribute is not present in the predefined attributes.
    ///  Returns the attributeValue for the specified `attribute`.
    /// @param _to The address whose attribute is requested.
    /// @param _attributeIndex The attribute Index which is required.
    /// @return The attribute value at the specified name.
    function getAttributeByIndex(address _to, uint _attributeIndex) external view returns (bytes32);
}

interface ERC173 /* is ERC165 */ {
    /// @dev This emits when ownership of a contract changes.
    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);

    /// @notice Get the address of the owner
    /// @return The address of the owner.
    function owner() external view;

    /// @notice Set the address of the new owner of the contract
    /// @param _newOwner The address of the new owner of the contract
    function transferOwnership(address _newOwner) external;
}

interface ERC165 {
    /// @notice Query if a contract implements an interface
    /// @param interfaceID The interface identifier, as specified in ERC-165
    /// @dev Interface identification is specified in ERC-165. This function
    ///  uses less than 30,000 gas.
    /// @return `true` if the contract implements `interfaceID` and
    ///  `interfaceID` is not 0xffffffff, `false` otherwise
    function supportsInterface(bytes4 interfaceID) external view returns (bool);
}

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 MV tokens represent.

/// @title ERC-1261 MVT 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. Any member can always ask the issuer to revoke the token from an existing address and assign to a new address. One can think of the set of MVTs as identifying a user, and you cannot split the user into parts and have it be the same user, but you can transfer a user to a new private key.

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 available on GitHub
• Blacklist certain address from receiving MV tokens — Sample contract available on GitHub
• Disallow additional memberships after a certain time is reached — Sample contract available on GitHub
• 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

ERC-173 Interface

We chose Standard Interface for Ownership (ERC-173) to manage the ownership of a ERC-1261 contract.

A future EIP/ Zeppelin may create a multi-ownable implementation for ownership. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement ERC1261Metadata, or other interfaces by delegating to a separate contract.

ERC-165 Interface

We chose Standard Interface Detection (ERC-165) to expose the interfaces that a ERC-1261 smart contract supports.

A future EIP may create a global registry of interfaces for contracts. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement ERC1261Metadata, or other interfaces by delegating to a separate contract.

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:

• Membership Verification Token(https://github.com/chaitanyapotti/MembershipVerificationToken)

Test Cases

Membership Verification Token ERC-1261 Token includes test cases written using Truffle.

Implementations

Membership Verification Token ERC1261 – a reference implementation

• MIT licensed, so you can freely use it for your projects
• Includes test cases
• Also available as a npm package - npm i membershipverificationtoken

References

Standards

1. ERC-20 Token Standard. ./eip-20.md
2. ERC-165 Standard Interface Detection. ./eip-165.md
3. ERC-725/735 Claim Registry ./eip-725.md
4. ERC-173 Owned Standard. ./eip-173.md
5. JSON Schema. https://json-schema.org/
6. Multiaddr. https://github.com/multiformats/multiaddr
7. RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt

Issues

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

Discussions

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

MVT Implementations and Other Projects

1. Membership Verification Token ERC-1261 Token. https://github.com/chaitanyapotti/MembershipVerificationToken

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Chaitanya Potti, Partha Bhattacharya, "EIP-1261: Membership Verification Token (MVT)," Ethereum Improvement Proposals, no. 1261, July 2018. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-1261.