A Companion Guide to “First impressions with ERC 725 and ERC 735 - identity and claims” (Part 1)

1. Introduction

I recently start studying on Security Token Offering (STO) platforms. One of the important step is the identity for investors. This involves some specific process like Know Your Client (KYC), almost a must-have step from regulation.

One platform adopts ERC-725/735 for the identity and claim verification, and this drives me further exploration on what these ERCs (ERC-725, ERC-735) are and how they work. And during survey I found a very good article from Julio Santos, CTO of Fractal with title “First impressions with ERC-725 and ERC-735 — identity and claims” (link). Inside this article there is a demo showing how to incorporate ERC-725/735 into a crowdsale.

The article already provides very good information. Here I wrote this article to serve as a companion guide for those who wish to take a more detail understanding on the implementation.

I first touch the whole process and provide some analysis in the set of contracts. Then I follow the steps described in Julio’s article and do some illustration on how things work. I also use geth client to access the Ethereum simulator (ganache-cli is used) and take a look on what happens after the demo script is done.

2. Overview of Identity and Claims, and ERC-725 and ERC-735

There are already good articles talking about the concepts of identity and claims. Here I just do a quick overview on them. For those already have concepts on these, feel free to skip this and go to next session.

Identity and claim appear far before any decentralized and distributed ledger technologies (of course including blockchain). It always happens in our real life. The emergence of blockchain provides a way of implementation in digital world.

I am not planning to develop the strict definition on the terminology. Rather let’s take a real-life example. Supposed I am stopped by a policeman on the highway and he is checking whether I can drive. I hand him my driving license. Here the whole process looks like this

  • Claim: I am an authorized driver.
  • Claim issuer: Transport Department of the government
  • Verifiable Claim: My driving license
  • Verifier: Policeman

The policeman will inspect my driving license, see something associated with me (for example, a photo on the driving license), and from that physical driving license he believes it is not a fake one. With all these, he is convinced that I as the one in front of him is a person being authorized to drive by the government.

In digital word it is almost the same situation. Besides human inspection, cryptography in particular digital signature is heavily involved.

With blockchain and its decentralization nature, it opens a new direction on how to implement identity and claim in a decentralized environment. To be specific in our discussion, it is how to use Ethereum network to handle identity and claim.

And here comes ERC-725/735.

Fabian Vogelsteller proposed ERC-725 (Identity) and ERC-735 (Claim) back in October, 2017. These ERCs come with a data structure of the subject, and the functions (interfaces only, without actual implementation) and events centering on the subject. Ideally others when implementing ERC-725/735 keep the same data structure, functions and events to achieve a level of interoperability. The success of ERC-20 fungible token is a good example.

An identity in the context of ERC-725/735 can be considered as an entity holding keys and claims together. When a contract is implemented them, it will be a contract of an entity who can sign claims and who can hold claims as proof for other activities.

In ERC-725, the struct Key looks like this.

struct Key {
uint256[] purposes;
uint256 keyType;
bytes32 key;
}

In particular some purposes are defined as Management, Action, Claim and Encryption, with a value representing them. Also “key type” keeps the information about the scheme, such as ECDSA (eccliptic curve digital signature algorithm).

The code comes with functions including getKey(), getKeysByPurpose(), keyHasPurpose() and addKey(). They are designed with the key as “key” in a mapping.

ERC-725 also comes with functions execute() and approve(), which means that this contract can act as a proxy once deployed. An Ethereum account can execute functions on other contracts through this contract, and we will see how it works in Julio’s demo.

ERC-735 is for claim, and here more accurately it is a signed claim by an identity service provider. The struct of Claim looks like this.

struct Claim {
uint256 topic;
uint256 scheme;
address issuer;
bytes signature;
bytes data;
string uri;
}

Again ERC-735 comes with functions getClaim(), getClaimIdsByType(), addClaim(), removeClaim(). It is obvious a Claim ID is defined for each claim, which is keccak256(issuer + topic). This means that with the same issuer and the same topic, the Claim ID will always be the same for all entities.

Similar to other ERC, only function interfaces are defined. It will be up to others to implement the functions detail. We will examine Julio’s implementation and see how the two ERCs are implemented.

3. Quick Flow of Julio’s Example

Julio’s demo is an implementation of ERC725/735, and how to use the claim to participate in a sample crowdsale which requires KYC.

Here we first walk through the flow of the whole demo.

There are three parties in this demonstration.

  • Fractal ID: the identity service provider and in this case as a KYC provider.
  • Very Good Company: a company issuing their tokens and crowdfunding through a crowdsale. The crowdsale requires KYC check, and Very Good Company acknowledges Fractal ID signed claim as a valid KYC.
  • Investor: an investor who is going to participate in the crowdsale of Very Good Company, and obtain the KYC status from Fractal ID
Image for post
Image for post
The three parties in Julio’s demo setup

The flow is like this

  1. Investor applies for KYC from Fractal ID by providing the required information. This part contains off-chain process, and Investor needs to fulfil all the requirement Fractal ID requests before getting a KYC status.
  2. After the required procedures, Fractal ID issues a KYC claim to investor. This claim is signed by Fractal ID. Investor now keeps this KYC claim.
  3. Investor buys tokens from Very Good Company with the KYC claim issued by Fractal ID.
  4. Very Good Company recognizes and accepts KYC claim from Fractal ID, and then issues the tokens to Investor.

4. Examination of Smart Contracts

As mentioned above, ERC725/735 does not provide the implementation of functions. This demo is done through a set of Solidity contracts.

You can download the contracts for reference (link).

Image for post
Image for post
Solidity contract structure

Here is quick notes about each Solidity contract.

These two Solidity contracts are just taken from the ERC with no modification. The actual implementation is on the contracts inheriting them.

KeyHolder.sol is the implementation of ERC725.sol. Some points to note in this contract.

  1. The mapping keys is to keep key (with struct Key defined in ERC725.sol).
  2. The key of this mapping is computed by keccak256(address), the address of the entity who deploys this contract (contract deployer). Therefore the key is a 32-byte (256-bit) associated to an Ethereum address.
  3. That also means this contract, once deployed, can have more keys corresponding to different Ethereum accounts (different addresses, for different purposes).
  4. Constructor will initialize the first mapping: with the key from the contract deployer, and purpose set to 1, that is, a Management key. With this purpose, the contract deployer can perform some additional functions later, such as add key and add claim (implemented in ClaimHolder.sol).
  5. As mentioned, ERC-725 can act as a proxy. KeyHolder.sol implements the required logic for this (struct Execution, approve() and examine()).
  6. The KeyHolder.sol is not used directly. Rather it is inherited again in the ClaimHolder.sol.

ClaimHolder.sol inherits KeyHolder.sol, and implements the functions defined in ERC-735. Some points to note in this contract.

  1. The mapping claims is to keep claim (with struct Claim defined in ERC735.sol).
  2. The key for this mapping, claim ID, is computed by keccak256(issuer, claim type). This means (a) the same issuer and same claim type always have the same claim ID, and (b) the contract, once deployed, can have more than one claims, possibly from same issuer with different claim types, or same claim type (e.g. KYC) from different issuers.
  3. There is no constructor in ClaimHolder: Every claim is added through addClaim().

It is this ClaimHolder.sol to be deployed by anyone who wishes to have an identity in Ethereum network. In this demo both Fractal ID and Investor deploy their own ClaimHolder contract.

VeryGoodCoin.sol is the token contract, inheriting MintableToken.sol from Open Zeppelin. It does nothing more than defining the basic information of the coins (name, symbol, etc). Since our discussion is more on the crowdsale process, we will not touch too much on this token contract.

VeryGoodCrowdsale.sol is the crowdsale contract, inheriting MintedCrowdsale.sol from Open Zeppelin. Customization is needed in order to include the claim validity checking before accepting a token-buy request.

Here is how the validation is implemented.

  1. The function to be overridden is _preValidatePurchase().
  2. In the constructor, the Trusted Claim Holder is required. In this case it is the Fractal ID’s ClaimHolder contract (we will see it in the demo code main.js in next session). By placing this when the contract is deployed, Very Good Crowdsale only accepts claims signed by Fractal ID.
  3. The actual check the validity of claim is done by function claimIsValid(). It will first extract the claim from Investor’s ClaimHolder contract. As Investor may have several claims, only the claim with proper claim ID (computed from the Fractal ID’s ClaimHolder contract and the claim type) is taken out. The information inside the claim then goes through the signature validation. It only returns True when Fractal ID’s Claim Key is the signer for the Investor’s claim.

If it is not clear yet at this point about ClaimHolder contracts from various parties, don’t worry as we will see it step by step in the next session, by walking through the steps in Julio’s demo.

In the next part we will walk through the main.js and see how things are working step-by-step.

Written by

Happy to share what I learn on blockchain. Visit http://www.ledgertech.biz/kcarticles.html for my works. or reach me on https://www.linkedin.com/in/ktam1/.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store