Attestations
This page describes how users can manage attestations using the Polymesh Token Studio SDK. Attestations are also called "Claims" in the Polymesh and SDK code to align with the W3C standards.
What is an attestation?
Before we go into how to bring in attestations using our SDK, let's cover what an attestation is exactly. Attestations are characteristics that can be attached to a Polymesh DID. These attestations will be used to check if an identity meets token transfer rules at the time of transfer. Attestations can be changed at any time and can be attached to a DID by any approved attestation provider.
Note that attestation providers can be added by token issuers in the token compliance functionality.
Also note that the term "Attestations" is used in the Token Studio and documentation walkthrough; however, our code and SDK uses the W3C standards on Verifiable Credentials where the term "Claims" is used instead of "Attestations." The Polymesh code follows these standards; therefore, attestations are referred to as Claims in the codebase and SDK.
What attestations types are there?
At the moment, Polymesh supports 8 types of attestations:
KYC Verification — An attestation that a Know Your Customer ("KYC") check has been conducted and has a specified expiry date or is valid in perpetuity. A use case for this is that issuers want customers to be vetted by a third party KYC provider to assure that an individual is who they say they are and meet the regulatory requirements set out by the token issuer.
Jurisdiction — An attestation about the country that a DID resides in. A use case for this would be if an issuer does not wish to have individuals or entities from particular countries hold their security token.
Affiliate — An attestation that a DID is related to your company/organization in any way; such as, a Director or Officer, employee, subsidiary, etc.
Accreditation — An attestation that an individual is an Accredited Investor or Experienced Investor. A use case for this is when regulation mandates that only investors with experience or accreditation can get tokens to keep compliant with regulation.
Exempted — A catch-all attestation where a DID may not meet the other claim types but you still want them to be considered with respect to your token rule. A use case for this is if the issuer wants to make sure only specific DIDs can send or receive their token so they write an "Exempted" attestation to those DIDs and make a token rule stating that anyone with an "Exempted" attestation can send or receive their token.
Blocked — An attestation that a DID may be blocked from receiving your security token. A use case is if an issuer wants to make sure a specific DID cannot send or receive their token they can write a "Blocked" attestation to that DID and make a token rule stating that anyone can send receive the token except those with a "Blocked" attestation.
Buy Lock-up — An attestation that an individual or entity may not receive a security token until a specified date. A use case for this is when an individual or entity cannot actually hold the token until a certain date known as the buy lock-up. Currently in Polymesh, token receivers with a buy lock-up date that has not expired yet will not receive tokens and issuers or their agents will need to re-distribute tokens to those individuals or entities when their buy lock-up has expired.
Sell Lock-up — An attestation that an individual or entity may not transfer a security token until a specified date. A use case for this is when an issuer wants a lock on trading of tokens they can use this to avoid having their tokens transferred before the sell date.
Attestations are a great example of how the power of blockchain applies to security tokens. On Polymesh, token issuers or their delegates set token rules based on what attestations they want their tokenholders to have in order to send or receive their tokens and the attestations of these users are checked by the blockchain each time a transfer is attempted. From there, attestations are easy to update; they can be managed for the entire lifecycle of your security token, so as regulations or compliance rules for your token inevitably change, applicable restrictions can be updated to keep your token compliant.
Managing attestation providers
After an issuer configures their security token, they can create a list of Attestation Providers that can write attestations to Polymesh DIDs in the scope of your security token. Attestation Providers are not permanent and can be removed from your security token at any time; you are also able to add more Attestation Providers at any time.
Attestation Providers can be your lawyer, a security token marketplace, a KYC provider or any other 3rd party that you trust to write these attestations.
If there is a need to query the attestations related to your security tokens, the SDK has operations to fetch this data for you. For example if you have a token and DID, you are able to return if there is a trusted attestation issuer attached to that token and what attestations they have written.
How are attestations used
Attestations are useful in combination with rules that are created around token transfer. If a rule isn't set the attestation itself cannot do anything. Token rules are conditions that must be met by a DID in order to send/receive your security token based on attestations. As previously mentioned when going through attestation types/use cases for those attestations a rule at its core uses the attestation type to give the issuer the power to assure that tokens do not end up in the hands of unwanted tokenholders. In the next section you will learn more about rules and what you can do with these rules.
Further technical details
If you need further information on attestation please refer to the API documentation below.
Last updated
