ERC-1261 Membership Verification Token (MVT)
Stagnant · Signatures & auth · created 2018-07-14
A non-transferable membership token that the issuer can revoke, used as a standard for proving and managing organizational affiliation and eligibility on-chain.
Why it is needed
Blockchain voting and governance have generally relied on voting power proportional to token balance. This approach makes it difficult to build flexible governance structures. In addition, services that need to prove affiliation or eligibility, such as passport issuance, driver's licenses, memberships, or investor accreditation checks, are not well suited to representation as transferable tokens, since allowing eligibility to be bought and sold undermines the whole point. Under the existing ERC-725/735 claim registry, ownership of a claim belongs to the holder, so even if the issuer wants to revoke a claim whose underlying facts have changed, there is no way to enforce it if the holder's contract simply ignores the removeClaim call. Until now there has been no standard that allows membership to be verified on-chain while still letting the issuer revoke or modify eligibility.
What to implement
event Assigned(address indexed _to, uint[] attributeIndexes);: An event triggered when a token (membership) is assigned to a member.event Revoked(address indexed _to);: An event triggered when a membership is revoked.event Forfeited(address indexed _to);: An event triggered when a user voluntarily forfeits their own membership.event ApprovedMembership(address indexed _to, uint[] attributeIndexes);: An event triggered when a membership application is approved.event RequestedMembership(address indexed _to);: An event triggered when a user applies for membership.event ModifiedAttributes(address indexed _to, uint attributeIndex, uint attributeValueIndex);: An event triggered when a member's attribute value is modified (not triggered on initial assignment).function addAttributeSet(bytes32 _name, bytes32[] calldata values) external;: Appends a new attribute (a key and a list of values) to the end of the existing set of attributes.function modifyAttributeByIndex(address _to, uint _attributeIndex, uint _modifiedValueIndex) external;: Changes a specific attribute value of a specific address to a different value.function requestMembership(uint[] calldata _attributeIndexes) external payable;: Any address can apply for membership by attaching attribute data.function forfeitMembership() external payable;: A member voluntarily forfeits their own membership.function approveRequest(address _user) external;: The owner approves a pending membership application and assigns the token.function discardRequest(address _user) external;: The owner discards a pending membership application.function assignTo(address _to, uint[] calldata _attributeIndexes) external;: The owner directly assigns membership to a specific address without going through the application process.function revokeFrom(address _from) external;: The owner revokes the membership of a specific address.function isCurrentMember(address _to) external view returns (bool);: Queries whether the given address is currently a member of the organization.function getAttributeExhaustiveCollection(bytes32 _name) external view returns (bytes32[] memory);: Queries the full list of values a specific attribute name can take.function getAllMembers() external view returns (address[]);: Queries the list of all past and current member addresses.function getCurrentMemberCount() external view returns (uint);: Queries the current number of members.function getAttributeNames() external view returns (bytes32[] memory);: Queries the list of all registered attribute names.function getAttributes(address _to) external view returns (bytes32[]);: Queries all attribute values held by a specific address.function getAttributeByIndex(address _to, uint _attributeIndex) external view returns (bytes32);: Queries a specific attribute value of a specific address.function name() external view returns (string _name);: Returns the name describing the set of MVTs issued by this contract.function symbol() external view returns (string _symbol);: Returns the abbreviated symbol for the MVT issued by this contract.
In depth
The exclusive and exhaustive structure of attributes
An attribute header maps to an array of values that are mutually exclusive and exhaustive. For example, a blood type ABO header maps to the value array [o, a, b, ab], and a blood type Rh header maps to the value array [+, -]. By contrast, something like a video subscription service, where a user is not forced to have exactly one value (they may have none, or multiple of Netflix, HBO, and Amazon), is explicitly noted as not a suitable example. This structure is used to divide an organization into fine-grained subgroups, such as voting eligibility groups.
Enrollment flow: requestMembership and approval/discard
Users apply for membership by calling requestMembership with an attribute index, and the call fails if msg.sender already holds a token. A RequestedMembership event is emitted on application. When the owner approves a pending request via approveRequest, both ApprovedMembership and Assigned events are emitted, and the owner can discard a request via discardRequest. Both functions must fail if the user has no pending request or if the caller is not the owner. The specification notes that an implementation could also use an oraclize callback to call these functions and automate approval/rejection.
Failure conditions for assignTo/revokeFrom and forfeitMembership
assignTo is a function that lets the owner grant membership directly without going through the application process, and it must fail if the target already holds a token, is the zero address, or the caller is not the owner. revokeFrom must fail if _from is not the token holder, is the zero address, or the caller is not the owner. forfeitMembership fails if msg.sender does not hold a token. The specification only defines the minimum conditions under which these functions must fail, so an implementation can impose additional conditions, such as a membership deadline having passed, a blacklisted address, or unpaid fees, to make them fail in more cases.
Non-transferable design
MVT has no transfer function. A member who wants to change address must ask the issuer to revoke the token from the old address and reassign it to the new one. The specification explains that while a user cannot be split and distributed, a user can be moved to a new private key, and that this non-transferability is what makes the token function like a membership card, which is the basis for the name Membership Verification Token.
Dependency on ERC-173/ERC-165
Every ERC-1261 compliant contract must implement the ERC1261, ERC173, and ERC165 interfaces together. ERC-173 (the ownership standard) is used to check whether the caller is the owner for management functions such as assignTo, revokeFrom, and addAttributeSet, while ERC-165 (the interface detection standard) is used to query which interfaces a contract supports. This standard's ERC-165 identifier is specified as 0x1d8362cf.
Optional metadata extension
The name() and symbol() functions are an OPTIONAL extension for ERC-1261 smart contracts, following the convention of existing token standards such as ERC-20. An empty string is a valid response for both functions, and since other contracts may use the same name/symbol, determining which contract is canonical is explicitly stated to be out of scope for this standard. A separate organization metadata JSON schema defines name and description fields.
Difference from the ERC-725/735 claim registry
The explanation notes that in the ERC-725/735 claim registry, ownership of a claim belongs to the holder who received it, so even if the issuer calls removeClaim, revocation cannot be enforced if the holder's contract ignores it. As an example, it cites a case where a background-check company's clean-record claim no longer reflects reality, yet it remains in place if the holder ignores the removeClaim call. ERC-1261 avoids this problem by placing ownership of the badge/claim with the issuing entity contract, so that the issuer can revoke or change it at will.
Proposal status: Stagnant
This proposal is currently marked Stagnant, meaning it is not being actively discussed or advanced.