OVIP: 12
Title: VASP Directory
Author: Felix Laufenbegr <[email protected]>
Discussions-To: https://community.openvasp.org/#narrow/stream/21-protocol-.2F.20ovip
Status: Accepted
Type: Standard
Created: 2020-06-13
This OVIP specifies the initial implementation of the VASP Registry interface. It provides a centrally managed lookup for linking VASP Identifiers to real world entities using decentral storage and accessibility.
As specified in OVIP-0011 the VASP Directory consists of a lookup smart contract, the VASP Registry, providing a reference to VASP Credentials and a data source for fetching the VASP Credentials. Here the lookup value consists of the Keccak256 hash of the VASP Credentials. The data source will be Ethereum event logs which are emitted when inserting new data.
Note that all roles are represented as Ethereum addresses. This implies that they can take shape as a standard Ethereum address with private key access, but also as a smart contract which could represent more complex access policies (e.g. multisig).
Consumer End-user of the VASP Directory. Wants to retrieve verifiable Credentials.
Administrator Responsible for managing the content of the VASP Directory.
Owner Responsible for managing the lifecycle of the VASP Directory
Signature:
function getCredentialsRef
(
bytes6 vaspId
)
external virtual view
returns (string memory credentialsRef, bytes32 credentialsHash);
Description: This method is inherited from the VASP Registry interface. It is a read-only query that can be executed by anyone. It is used to retrieve a reference to the Credentials and verifiable proof of data integrity.
Behavior: Given a VASP Identifier (vaspID) it returns a tuple of two strings. The first string returned represents the reference for fetching the Credentials, here the tKeccak256 hash of the credentials. The second parameter is also the Keccak256 hash of the credentials and can be used to verify their content. The reason for redundancy is to comply with the VASP Registry interface.
Signature:
function insertCredentials
(
bytes6 vaspId,
string calldata credentials
)
external
Description: This method is used by the administrator to insert new credentials and their SHA256 hash value, credentialsHash for a specific VASP with identifier vaspID.
Behavior: There can only be one lookup value per VASP Identifier. If there is no existing entry for the VASP Identifier, a new entry will be created. If this method is called for a VASP Identifier which already exists, the method should fail. Overwriting of values is only possible by revoking them first. The Keccak256 hash of the credentials is calculated as part of this method and inserted into the Directory. The credentials themselves are not stored explicitly.
Event log:
CredentialsInserted(bytes6 indexed vaspId, bytes32 indexed credentialRef, bytes32 indexed credentialsHash, string credentials);
Signature:
function revokeCredentials
(
bytes6 vaspId
)
external
Description: This method is used by the administrator to revoke the credentials for a specific VASP with identifier vaspID.
Behavior: If there is no existing entry for the VASP Identifier, the method should fail. If this method is called for a VASP Identifier which already exists, the entry in the Directory must be removed.
Event log:
CredentialsRevoked(bytes6 indexed vaspId, bytes32 indexed credentialRef, bytes32 indexed credentialsHash)
function grantAdministratorRole
(
address account
)
external
Description:
Grants administrator role to the specified account
Access:
Can be called only by owner
Use Case:
Called by the owner to grant administrator role to the specified account
function revokeAdministratorRole
(
address account
)
external
Description:
Revokes administrator role from the specified account
Access:
Can be called only by owner
Use Case:
Called by the owner to revoke administrator role from the specified account
function renounceAdministratorRole()
external
Description:
Renounces administrator role for the caller
Access:
Can be called only by administrator
Use Case:
Called by the administrator to renounce his own permissions.
function transferOwnerRole
(
address newOwnerCandidate
)
external
Description:
Sets the specified address as a contract's owner candidate.
Access Can be called only by the owner
Use Case:
Called by the contract owner to prepare the transfer of the contract's ownership to a new owner.
Event log:
OwnerRoleTransferStarted(address indexed currentOwner, address indexed newOwnerCandidate);
function cancelOwnerRoleTransfer()
external
Description:
Cancels ownership transfer.
Access Can be called only by the owner
Use Case:
Called by the contract owner to cancel the transfer of the contract's ownership to a new owner.
Event log:
OwnerRoleTransferCancelled();
function acceptOwnerRole()
external
Description:
Changes the owner of the contract.
Access Can be called only by the new owner candidate
Use Case:
Called by the future owner in order to accept transfer of the contract's ownership.
Event log:
OwnerRoleTransferCompleted(address indexed previousOwner, address indexed newOwner);
function renounceOwnerRole()
external
Description:
Renounces the owner role
Access Can be called only by the owner
Use Case:
Called by the future owner in order to accept transfer of the contract's ownership.
Use Case: Can be called to leave the contract without owner. It will not be possible to call functions callable only by the owner anymore.
function terminate
(
address payable recipient
)
external
Description:
Frees memory allocated by the contract and transfers all potentially accidentally funds send to the contract to recipient.
Use Case:
End the lifecycle of the VASP Index without preserving the existing mapping. Invalidates and obsoletes existing entries.
The specification proposed in this OVIP present a previously not specified part of the protocol. Client implementations that do not follow this standard will still be compatible with the network. Thus this OVIP is backwards compatible.