Managing ONCHAINID

On the blockchain, stakeholders are represented by an identity smart contract called the ONCHAINID. This open source protocol is the chosen implementation for the decentralised identity framework. It is mandatory for any person (physical or moral) receiving ERC-3643 tokens to have this ONCHAINID deployed as it is the technology used to perform:

KYC and AML checks
Eligibility checks
Transfer compliance checks

Deploying an ONCHAINID

Pre-requisites

At this time, a deployed ERC-3643 is required to deploy an ONCHAINID via Tokeny's API.

Investors

Having previously collected all the required information to create your investor Identity (see below), you can then call the whitelisting endpoint to:

Create the identity on Tokeny's Identity Provider
Deploy the ONCHAINID
Authorize your investor on the token

Currently, you can only deploy an ONCHAINID in the context of an existing and deployed ERC3643.

Agents

An ONCHAINID for an agent will be deployed automatically when you create an agent access.

Managing identity data and onchain credentials

Common identity data

Tokeny's Identity Provider defines the Standard Schema for an Identity to be valid. Below, you can see a breakdown of this Standard Schema:

Common fields (both for Individuals and Corporates)

Field name	Description	Validation rules	Mandatory?
`individual_or_institution`	Indicates if the owner of the ONCHAINID is an individual or an institution	MUST BE either: - `individual` - `institution`	Yes
`ethereum_wallets`	The list of wallets used by the owner of the ONCHAINID	MUST BE `[{ "address": "string, valid eth address", "alias": "string, less than 40 characters" }]`	Yes
`politically_exposed`	Defines if the owner of the ONCHAINID is a politically exposed person.	MUST BE `[{ "exposed": "true or false", "details": "string" }]` `details` is mandatory if `exposed` is set to `true`.	No

Individuals

Field name	Description	Validation rule	Mandatory?
`first_name`	The first name of the owner of the ONCHAINID	None	Yes
`last_name`	The last name of the owner of the ONCHAINID	None	Yes
`gender`	The gender of the owner of the ONCHAINID	MUST BE either: - `Male` - `Female`	No
`birthday`	The date of birth of the owner of the ONCHAINID	MUST BE an ISO date string, with timezone	Yes
`birthplace`	The place of birth of the owner of the ONCHAINID	None	No
`nationality`	The nationality of the owner of the ONCHAINID	MUST BE in ISO 3166 Alpha-3 format (see here)	Yes
`id_number`	The number of the ID card of the owner of the ONCHAINID	None	Yes, if `passport_number` is not set
`passport_number`	The number of the passport of the owner of the ONCHAINID	None	Yes, if `id_number` is not set
`ssn_number`	The social security number of the owner of the ONCHAINID	None	No
`phone`	The phone number of the owner of the ONCHAINID	None	No
`occupation`	The occupation of the owner of the ONCHAINID	See Occupations and activities	No
`building_number`	The building number from the address of the owner of the ONCHAINID	None	No
`street`	The street from the address of the owner of the ONCHAINID	None	Yes
`zip_code`	The ZIP code of the address of the owner of the ONCHAINID	None	Yes
`state`	The state from the address of the owner of the ONCHAINID	None	No
`city`	The city of the address of the owner of the ONCHAINID	None	Yes
`country`	The country of the address of the owner of the ONCHAINID	MUST BE in ISO 3166 Alpha-3 format (see here)	Yes

Institutional

Field name	Description	Validation rule	Mandatory?
`institution_trade_name`	The trade name of the company owning the ONCHAINID	None	Yes
`institution_legal_name`	The legal name of the company owning the ONCHAINID	None	Yes
`institution_registry_number`	The national registration number of the company	None	Yes
`institution_legal_form`	The legal form of the company	See closed list	No
`institution_incorporation_date`	The incorporation date of the company	MUST BE an ISO date string, with timezone	No
`institution_activity`	The sector of activity of the company	See Occupations and activities	No
`institution_registry_country`	The country of incorporation of the company	MUST BE in ISO 3166 Alpha-3 format (see here)	Yes
`institution_building_number`	The building number part of the address of the headquarters of the company	None	No
`institution_street`	The street part of the address of the HQ of the company	None	Yes
`institution_city`	The city part of the address of the HQ of the company	None	Yes
`institution_state`	The state part of the address of the HQ of the company	None	No
`institution_country`	The country part of the address of the HQ of the company	MUST BE in ISO 3166 Alpha-3 format (see here)	Yes
`institution_zip_code`	The ZIP code part of the address of the HQ of the company	None	No
`institution_admins`	The list of individuals being set as the administrators of the company	MUST BE `[{ "first_name": "string", "last_name": "string", "gender": "Male or Female", "birthday": "ISO Date", "nationality": "ISO Country", "institution_admin_title": "String", "institution_admin_relation": "String", "email": "String", "phone": "String", "passport_number": "String", "id_number": "String" }]` - `phone` and `email` refer to the phone number and email address of the individual in the company - `institution_admin_title`: the title of the individual in the company - `institution_admin_relation`: the position of the individual in the company	The field itself is mandatory. For the content of the field: - `first_name`: mandatory - `last_name`: mandatory - `gender`: optional - `birthday`: optional - `nationality`: optional - `passport_number`: mandatory if `id_number` is not set - `id_number`: mandatory if `passport_number` is not set - `institution_admin_title`: mandatory - `institution_admin_relation`: mandatory - `phone`: mandatory - `email`: mandatory

Occupation and sector of activities

The following values are available for the ONCHAINID Standard Schema for occupations and activities:

Electricity companies
Finance
Insurance
Bank
Traders
Confectionery
DIY
Post, mail and deliveries
Medical equipment and health products
Drink
Dairy products
Cosmetics
Consumer Consumption
Agriculture
Seeds
Brewery
Pharmacy
Tobacco
Rail transport
Wind turbine manufacturers
Energy
Health
Consumer Electronics
Cement
Aeronautics, Aerospace and Defense
Agribusiness
Cruises
Appliances
Electrical equipment
Industrial machinery
Entertainment & Media
IT technologies and services
Entertainment
Music Production (Majors)
Programming & Software
Information and Communication Technologies
Telecommunications operators
Advertising
Sporting equipment manufacturers
Luxury
Catering
Distribution
Large distribution
Heavy industry (excluding energy)
Computer equipment
Tires
Automobile Manufacturers
Building, construction and public works
Mobile phones
Telecommunication and Network Equipment Manufacturers
Chemistry
Mining activities
Oil companies
Airlines
Shipping of goods
Transportation

As an appointed agent of an ERC-3643 consuming this Identity, you can fetch the data of the investors you manage.

Offering-specific identity data

In addition to the Standard Schema, you can also create offering specific data. To set them up, please contact your Account Manager.

Onchain credentials

Identities follow the Decentralised Identity framework. On top of the ONCHAINID as the Decentralised Identifier (DID), Tokeny also enables the easy management of Verifiable Credentials.

Those credentials represent the proof of data onchain, signed by a Trusted Issuer (KYC agent, bank, crypto exchange, etc.). They are a hashed version of the data, containing the schema of validated data for you to be able to compare what you have with the issued proof (credential).

You have several ways to consume those data:

Proof only
Compare your own data against the proof
Request data

Consuming the credentials

If you only need the proof of data, not the data itself (KYC/AML check, nationality, majority...), you can directly rely on the credential(s) you find on the ONCHAINID.

Compare your data against the proof

If you want to compare the data your received against the emitted proof, perform the following actions.

Step 1: Get the type of credential

First, you need to fetch the identifier of the credential you're looking. You can find below a list of standard credential types.

Step 2: Get the credential

Once you have the identifier, you can directly get the value from the ONCHAINID.

Step 3: Fetch the proof schema and signing algorithm

On top of the actual data proof, a credential is represented by the proof schema: the list of data validated by the Trusted Issuer.

Step 4: Sign your data

The proof schema gives you the list of fields you need to sign to match with the signature. Use whatever cryptographic library you're comfortable with to sign the data with the signing algorithm.

You can then check if the result of this operation matches the credential fetched on step 1. If it is not the case, it means that part or entirety of the data you have is not the one that was verified by the credential.