status-im
/
EIPs
mirror of https://github.com/status-im/EIPs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
EIPs/EIPS/eip-1616.md

396 lines
22 KiB
Markdown
Raw Blame History

---
eip: 1616
title: ERC-1616 Attribute Registry Standard
author: 0age (@0age), Santiago Palladino (@spalladino), Leo Arias (@elopio), Alejo Salles (@fiiiu), Stephane Gosselin (@thegostep)
discussions-to: https://github.com/ethereum/EIPs/issues/1616
status: Draft
type: Standards Track
category: ERC
created: 2018-11-23
requires: 165
---
## Simple Summary
<!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP.-->
EIP-1616 provides a basic interface for querying a registry for attribute metadata assigned to Ethereum accounts.
## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->
This EIP contains the following core ideas:
1. Instead of relying directly on the reputation of a claims issuer to assess the veracity of a given claim, trust can be brought up to the level of a registry curator. This registry which we call an "**Attribute Registry**" allows for reduced complexity in implementation since a party needing to verify an attribute can now work with a trusted claims aggregator instead of relying on individual claim providers.
2. Claims are abstracted as standard "attributes" which represent metadata assigned to an account, with claims decoupled from the issuing party. Attributes are registered as a flat `uint256 -> uint256` key-value pair on each account, with the important property that **each attribute type has one canonical value per address**. This property allows for composability of attribute registries and advanced attribute formation.
3. There is a generic method for determining the set of attribute keys or IDs made available by the registry. The standard does not specify requirements or recommendations for how attributes and their values are managed, or what additional metadata may be associated with attributes. It is likely that a standard set of attribute names and metadata schema could be proposed in a separate EIP.
Potential advanced uses of attribute registries include:
* Encoding complex boolean expressions which combine multiple attributes into a single uint256 key, which is then parsed and evaluated by the registry logic.
* Using values associated with an attribute to query additional on-chain or off-chain metadata.
* Resolving attribute values by calling into separate attribute registries or other contracts, delegating authority without changing the interface of the registry.
## Motivation
<!--The motivation is critical for EIPs that want to change the Ethereum protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the EIP solves. EIP submissions without sufficient motivation may be rejected outright.-->
This EIP is motivated by the need for contracts and external accounts to be able to verify information about a given address from a single trusted source **without concerning themselves with the particular details of how the information was obtained**, and to do so in as simple a manner as possible. It is also motivated by the desire to promote broad **cross-compatibility and composability** between attribute registries, a property which is amplified by both the simplicity of the interface as well as by the guarantees on uniqueness provided by the proposed standard.
Existing EIPs for assigning metadata to an account include EIP-735 and EIP-780, which both allow for multiple claims to be issued on the same address for any given claim topic. This forces verifiers of said metadata to assess the veracity of each claim, taking into account the relative reputation of each claim issuer. It also prescribes a methodology for adding and removing claims, which may not be appropriate for all use cases.
This EIP proposes a light-weight abstraction layer for a standard account metadata registry interface. This abstraction layer can sit on top of claims registries like EIP-735 and EIP-780 or others as the attribute registry curator selects trusted data sources.
## Specification
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->
The Attribute Registry interface contains four functions, outlined as follows:
```solidity
/**
* @title EIP-1616 Attribute Registry Standard interface. EIP-165 ID: 0x5f46473f
*/
interface AttributeRegistryInterface {
function hasAttribute(address account, uint256 attributeTypeID) external view returns (bool);
function getAttributeValue(address account, uint256 attributeTypeID) external view returns (uint256);
function countAttributeTypes() external view returns (uint256);
function getAttributeTypeID(uint256 index) external view returns (uint256);
}
```
Contracts that comply with the Attribute Registry EIP MUST implement the above interface.
As an additional requirement, the ERC-165 interface MUST be included:
```solidity
/**
* @title EIP-165 interface. EIP-165 ID: 0x01ffc9a7
*/
interface EIP-165 {
/**
* @notice EIP-165 support. Attribute Registry interface ID is 0x5f46473f.
* @param _interfaceID The interface identifier, as specified in EIP-165
* @return True for 0x01ffc9a7 & 0x5f46473f, false for unsupported interfaces.
*/
function supportsInterface(bytes4 _interfaceID) external view returns (bool);
}
```
The implementation MUST follow the specifications described below.
### View Functions
The view functions detailed below MUST be implemented.
#### `hasAttribute` function
```solidity
function hasAttribute(address account, uint256 attributeTypeID) external view returns (bool)
```
Check if an attribute has been assigned to a given account on the registry and is currently valid.
_**NOTE**_: This function MUST return either true or false - i.e. calling this function MUST NOT cause the caller to revert. Implementations that wish to call into another contract during execution of this function MUST catch any `revert` and instead return `false`.
_**NOTE**_: This function MUST return two equal values when performing two directly consecutive function calls with identical `account` and `attributeTypeID` parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information.
#### `getAttributeValue` function
```solidity
function getAttributeValue(address account, uint256 attributeTypeID) external view returns (uint256)
```
Retrieve the `uint256` value of an attribute on a given account on the registry, assuming the attribute is currently valid.
_**NOTE**_: This function MUST revert if a directly preceding or subsequent function call to `hasAttribute` with identical `account` and `attributeTypeID` parameters would return false.
_**NOTE**_: This function MUST return two equal values when performing two directly consecutive function calls with identical `account` and `attributeTypeID` parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information.
#### `countAttributeTypes` function
```solidity
function countAttributeTypes() external view returns (uint256)
```
Retrieve the total number of valid attribute types defined on the registry. Used alongside `getAttributeTypeID` to determine all of the attribute types that are available on the registry.
_**NOTE**_: This function MUST return a positive integer value - i.e. calling this function MUST NOT cause the caller to revert.
_**NOTE**_: This function MUST return a value that encompasses all indexes of attribute type IDs whereby a call to `hasAttribute` on some address with an attribute type ID at the given index would return `true`.
#### `getAttributeTypeID` function
```solidity
function getAttributeTypeID(uint256 index) external view returns (uint256)
```
Retrieve an ID of an attribute type defined on the registry by index. Used alongside `countAttributeTypes` to determine all of the attribute types that are available on the registry.
_**NOTE**_: This function MUST revert if the provided `index` value falls outside of the range of the value returned from a directly preceding or subsequent function call to `countAttributeTypes`. It MUST NOT revert if the provided `index` value falls inside said range.
_**NOTE**_: This function MUST return an `attributeTypeID` value on *some* index if the same `attributeTypeID` value would cause a given call to `hasAttribute` to return `true` when passed as a parameter.
## Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
This standard extends the applicability of metadata assignment to those use cases that are not adequately represented by EIP-735, EIP-780, or similar proposals. Namely, it enforces the constraint of one attribute value per attribute ID per address, as opposed to one value per ID per address *per issuer*.
Aside from the prescribed attribute value, attribute properties are deliberately omitted from the standard. While many attribute registries will require additional metadata on attributes at both the instance and the class level, reliable and flexible interoperability between highly variable registry extensions is facilitated more effectively by enforcing a widely-applicable base layer for attributes.
## Backwards Compatibility
<!--All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
There are no backwards compatibility concerns.
## Test Cases
<!--Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.-->
Targeted test cases with 100% code coverage can be found at [this repository](https://github.com/0age/AttributeRegistry). See [here](https://github.com/TPL-protocol/tpl-contracts) for tests on a more complex contract that implements the application registry interface.
## Implementation
<!--The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
The basic implementation that follows can be found at [this repository](https://github.com/0age/AttributeRegistry) (see [here](https://github.com/TPL-protocol/tpl-contracts/blob/master/contracts/BasicJurisdiction.sol#L399) for an example of a more complex implementing contract):
```solidity
pragma solidity ^0.4.25;
/**
* @title Attribute Registry interface. EIP-165 ID: 0x5f46473f
*/
interface AttributeRegistryInterface {
/**
* @notice Check if an attribute of the type with ID `attributeTypeID` has
* been assigned to the account at `account` and is currently valid.
* @param account address The account to check for a valid attribute.
* @param attributeTypeID uint256 The ID of the attribute type to check for.
* @return True if the attribute is assigned and valid, false otherwise.
* @dev This function MUST return either true or false - i.e. calling this
* function MUST NOT cause the caller to revert.
*/
function hasAttribute(
address account,
uint256 attributeTypeID
) external view returns (bool);
/**
* @notice Retrieve the value of the attribute of the type with ID
* `attributeTypeID` on the account at `account`, assuming it is valid.
* @param account address The account to check for the given attribute value.
* @param attributeTypeID uint256 The ID of the attribute type to check for.
* @return The attribute value if the attribute is valid, reverts otherwise.
* @dev This function MUST revert if a directly preceding or subsequent
* function call to `hasAttribute` with identical `account` and
* `attributeTypeID` parameters would return false.
*/
function getAttributeValue(
address account,
uint256 attributeTypeID
) external view returns (uint256);
/**
* @notice Count the number of attribute types defined by the registry.
* @return The number of available attribute types.
* @dev This function MUST return a positive integer value - i.e. calling
* this function MUST NOT cause the caller to revert.
*/
function countAttributeTypes() external view returns (uint256);
/**
* @notice Get the ID of the attribute type at index `index`.
* @param index uint256 The index of the attribute type in question.
* @return The ID of the attribute type.
* @dev This function MUST revert if the provided `index` value falls outside
* of the range of the value returned from a directly preceding or subsequent
* function call to `countAttributeTypes`. It MUST NOT revert if the provided
* `index` value falls inside said range.
*/
function getAttributeTypeID(uint256 index) external view returns (uint256);
}
/**
* @title A simple example of an Attribute Registry implementation.
*/
contract AttributeRegistry is AttributeRegistryInterface {
// This particular implementation just defines two attribute types.
enum Affiliation { Whitehat, Blackhat }
// Top-level information about attribute types held in a static array.
uint256[2] private _attributeTypeIDs;
// The number of attributes currently issued tracked in a static array.
uint256[2] private _issuedAttributeCounters;
// Issued attributes held in a nested mapping by account & attribute type.
mapping(address => mapping(uint256 => bool)) private _issuedAttributes;
// Issued attribute values held in a nested mapping by account & type.
mapping(address => mapping(uint256 => uint256)) private _issuedAttributeValues;
/**
* @notice The constructor function, defines the two attribute types available
* on this particular registry.
*/
constructor() public {
// Set the attribute type IDs for whitehats (8008) and blackhats (1337).
_attributeTypeIDs = [8008, 1337];
}
/**
* @notice Assign a "whitehat" attribute type to `msg.sender`.
* @dev The function may not be called by accounts with a "blackhat" attribute
* type already assigned. This function is arbitrary and not part of the
* Attribute Registry specification.
*/
function joinWhitehats() external {
// Get the index of the blackhat attribute type on the attribute registry.
uint256 blackhatIndex = uint256(Affiliation.Blackhat);
// Get the attribute type ID of the blackhat attribute type.
uint256 blackhatAttributeTypeID = _attributeTypeIDs[blackhatIndex];
// Do not allow the whitehat attribute to be set if blackhat is already set.
require(
!_issuedAttributes[msg.sender][blackhatAttributeTypeID],
"no blackhats allowed!"
);
// Get the index of the whitehat attribute type on the attribute registry.
uint256 whitehatIndex = uint256(Affiliation.Whitehat);
// Get the attribute type ID of the whitehat attribute type.
uint256 whitehatAttributeTypeID = _attributeTypeIDs[whitehatIndex];
// Mark the attribute as issued on the given address.
_issuedAttributes[msg.sender][whitehatAttributeTypeID] = true;
// Calculate the new number of total whitehat attributes.
uint256 incrementCounter = _issuedAttributeCounters[whitehatIndex] + 1;
// Set the attribute value to the new total assigned whitehat attributes.
_issuedAttributeValues[msg.sender][whitehatAttributeTypeID] = incrementCounter;
// Update the value of the counter for total whitehat attributes.
_issuedAttributeCounters[whitehatIndex] = incrementCounter;
}
/**
* @notice Assign a "blackhat" attribute type to `msg.sender`.
* @dev The function may be called by any account, but assigned "whitehat"
* attributes will be removed. This function is arbitrary and not part of the
* Attribute Registry specification.
*/
function joinBlackhats() external {
// Get the index of the blackhat attribute type on the attribute registry.
uint256 blackhatIndex = uint256(Affiliation.Blackhat);
// Get the attribute type ID of the blackhat attribute type.
uint256 blackhatAttributeTypeID = _attributeTypeIDs[blackhatIndex];
// Mark the attribute as issued on the given address.
_issuedAttributes[msg.sender][blackhatAttributeTypeID] = true;
// Calculate the new number of total blackhat attributes.
uint256 incrementCounter = _issuedAttributeCounters[blackhatIndex] + 1;
// Set the attribute value to the new total assigned blackhat attributes.
_issuedAttributeValues[msg.sender][blackhatAttributeTypeID] = incrementCounter;
// Update the value of the counter for total blackhat attributes.
_issuedAttributeCounters[blackhatIndex] = incrementCounter;
// Get the index of the whitehat attribute type on the attribute registry.
uint256 whitehatIndex = uint256(Affiliation.Whitehat);
// Get the attribute type ID of the whitehat attribute type.
uint256 whitehatAttributeTypeID = _attributeTypeIDs[whitehatIndex];
// Determine if a whitehat attribute type has been assigned.
if (_issuedAttributes[msg.sender][whitehatAttributeTypeID]) {
// If so, delete the attribute.
delete _issuedAttributes[msg.sender][whitehatAttributeTypeID];
// Delete the attribute value as well.
delete _issuedAttributeValues[msg.sender][whitehatAttributeTypeID];
// Set the attribute value to the new total assigned whitehat attributes.
uint256 decrementCounter = _issuedAttributeCounters[whitehatIndex] - 1;
// Update the value of the counter for total whitehat attributes.
_issuedAttributeCounters[whitehatIndex] = decrementCounter;
}
}
/**
* @notice Get the total number of assigned whitehat and blackhat attributes.
* @return Array with counts of assigned whitehat and blackhat attributes.
* @dev This function is arbitrary and not part of the Attribute Registry
* specification.
*/
function totalHats() external view returns (uint256[2]) {
// Return the array containing counter values.
return _issuedAttributeCounters;
}
/**
* @notice Check if an attribute of the type with ID `attributeTypeID` has
* been assigned to the account at `account` and is currently valid.
* @param account address The account to check for a valid attribute.
* @param attributeTypeID uint256 The ID of the attribute type to check for.
* @return True if the attribute is assigned and valid, false otherwise.
* @dev This function MUST return either true or false - i.e. calling this
* function MUST NOT cause the caller to revert.
*/
function hasAttribute(
address account,
uint256 attributeTypeID
) external view returns (bool) {
// Return assignment status of attribute by account and attribute type ID
return _issuedAttributes[account][attributeTypeID];
}
/**
* @notice Retrieve the value of the attribute of the type with ID
* `attributeTypeID` on the account at `account`, assuming it is valid.
* @param account address The account to check for the given attribute value.
* @param attributeTypeID uint256 The ID of the attribute type to check for.
* @return The attribute value if the attribute is valid, reverts otherwise.
* @dev This function MUST revert if a directly preceding or subsequent
* function call to `hasAttribute` with identical `account` and
* `attributeTypeID` parameters would return false.
*/
function getAttributeValue(
address account,
uint256 attributeTypeID
) external view returns (uint256 value) {
// Revert if attribute with given account & attribute type ID is unassigned
require(
_issuedAttributes[account][attributeTypeID],
"could not find a value with the provided account and attribute type ID"
);
// Return the attribute value.
return _issuedAttributeValues[account][attributeTypeID];
}
/**
* @notice Count the number of attribute types defined by the registry.
* @return The number of available attribute types.
* @dev This function MUST return a positive integer value - i.e. calling
* this function MUST NOT cause the caller to revert.
*/
function countAttributeTypes() external view returns (uint256) {
// Return the length of the attribute type IDs array.
return _attributeTypeIDs.length;
}
/**
* @notice Get the ID of the attribute type at index `index`.
* @param index uint256 The index of the attribute type in question.
* @return The ID of the attribute type.
* @dev This function MUST revert if the provided `index` value falls outside
* of the range of the value returned from a directly preceding or subsequent
* function call to `countAttributeTypes`. It MUST NOT revert if the provided
* `index` value falls inside said range.
*/
function getAttributeTypeID(uint256 index) external view returns (uint256) {
// Revert if the provided index is out of range.
require(
index < _attributeTypeIDs.length,
"provided index is outside of the range of defined attribute type IDs"
);
// Return the attribute type ID at the given index in the array.
return _attributeTypeIDs[index];
}
}
```
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
Reference in New Issue View Git Blame Copy Permalink