Technical Overview. Version: 1.0 Date:

Transcription

1 Technical Overview Version: 1.0 Date: Authors Ingemārs Ašmanis Jānis Kiršteins 2018 Notakey Latvia SIA. All Rights Reserved.

2 Abstract ICO Pass is a suite of tools for the gathering, verification and exchange of know-yourcustomer (KYC) information. The target audience are tokensale organizers on the Ethereum blockchain. For each contributor, ICO Pass gathers: full name date of birth mobile phone number nationality and country of residence address of residency photo of ID document photo of person. This information is verified against multiple backing providers (initial version uses Onfido), then it is signed with an ICO Pass key (0x612fadf295ce8bbbcf83ecd5dc2832b5ace583e3), encrypted against the public crowdsale address, and published to IPFS. For tokensale organizers, ICO Pass provides smart contracts with modifiers to verify sender address on time of payment, and a web-application to access and manage the gathered KYC information. No sign-up or up-front work is required. For contributors, ICO Pass publishes a mobile application, which facilitates the gathering of KYC information. Contributors will prove their address ownership via small token ethereum transfers, which will be refunded (minus the network fees). 2

3 Contents 4 Introduction 6 Document Guide 8 Part 1: ICO Pass 20 Part 2: Crowdsale Details 3

4 Introduction While legally KYC checks are increasingly more important, there are many ICO organizers that choose the path of the least resistance (and don t gather KYC information at all). So one of the end goals of ICO Pass is to enable KYC verification as easily as possible for the ICO organizers. Additionally, KYC verification does not guarantee that the ICO organizer will be able to get in touch with the contributor. Should a bank, or a regulatory agency ask for more information regarding a specific contributor, ICO Pass aims to have a way to allow ICO organizers to get in touch with the contributor. Even with contact information and KYC information available, there is the matter of tooling. There are no KYC management systems that can interact with blockchain-based data. Also, different ICOs use different smart contracts to manage their crowdsale. Often crowdsale contracts are audited, and may not be easily changed. Working back from these assumptions, we have decided on a few design goals: payments from non-eligible addresses should be refused at the smart contract level. This will reduce the amount of work required afterwards to refund non-eligible contributors enabling contributor verification should be simple - ideally with no more than just a Solidity function modifier. This should ease auditing constraints. additionally, a proxy contract can be deployed to forward only verified funds. However, since an audited crowdsale would have to audit the whole setup, then a proxy contract does not offer significant advantages over a Solidity function modifier. To satisfy these constraints, the KYC data needs to be queryable from Ethereum. On the blockchain, ICO Pass consists of a suite of contracts, which facilitate: proving ethereum address ownership to a verifier; a claim registry, where subject addresses can be matched to data (signed by a given verifier); Initially ICO organizers who would adopt the ICO Pass, would have to trust the ICO Pass verification key signatures - because there would be no other verifiers. However, in theory, new verifiers could appear and submit information about ethereum addresses. 4

5 Additionally, ICO Pass provides a few non-blockchain services as well: a mobile application for gathering information (including contributor photos); a webservice for interacting with the mobile application, and signing the KYC information gathered with the ICO Pass mobile application. The mobile application will be open-sourced after the ICO Pass crowdsale. At no point will it ask for private keys from the end-user. The webservice, which performs KYC verification and submits signed information to the blockchain, will not be made open-source initially. Since storing data in the blockchain is expensive, most of the data would have to be stored elsewhere. The blockchain-based registry will store only a value, which can be: nationality index as an integer value short text strings for public entity identification URLs to encrypted content of personal information additional Ethereum addresses, e.g. for address linking: An overview: What about non-ethereum funds? Formally, ICO Pass only supports Ethereum addresses. However, cryptocurrencies that use the same elliptic curve for its user keys should be verifiable as well. ICO Pass currently does not support smart contracts for contributor verification on non-ethereum platforms. It has not been tested with Counterparty. 5

6 Document Guide This document will focus on technical aspects of the product. For business analysis see Prospectus. 6

7 Scope This document aims to describe the internal operations of the product. Among other things, this includes: what components the product consists of data flows among the internal components how the KYC checks are carried out how the verified identity is associated with one or more Ethereum addresses how the information is stored and accessed by the ICO organizers This document does not describe non-technical aspects of the product. Non-technical information can be found in the ICO Pass prospectus document which can be found here. Structure The document is divided into multiple parts. The first part describes the workings of the main ICO Pass components - the mobile client, the verification webservice, the KYC providers and the smart contracts used to store and retrieve information about ethereum addresses The second part describes the mechanics of the token sale. Finally, at the end of the document, there are multiple appendices. These include more in-depth explanations, as well as the full source code of the Ethereum smart contracts at the time of publishing this document. 7

8 Part 1: ICO Pass Everything about technical side of ICO Pass - data collection, identity verification and data sharing. 8

9 ICO Pass Public Keys All data, which needs to be signed by ICO Pass, can be validated against the key 0x612fadf295ce8bbbcf83ecd5dc2832b5ace583e3. Smart Contracts There are two type of ethereum programs in the scope of ICO Pass: infrastructure contracts for verifying key holders, publishing signed attributes, attribute lookup, etc. verifier contract - smart contracts and libraries for consuming the ICO Pass information. Infrastructure Contracts The underlying address attribute system is foundational to ICO Pass, but not specific to the scope of ICOs. As such, it is described in a separate document. It is available here: Schemas and Claims ICO Pass uses the following ClaimRegistry claims for ICO contributors: Mandatory Optional For claims, which are used for ICO organizers, please see ICO Organizer Validation. Verifier Contract The verifier contract is meant as an abstract base contract, which includes the function modifier onlyverifiedsenders(address paymentaddress, uint256 nationalityblacklist). The modifier verifies that: 1. the subject address, that is linked to paymentaddress above, has these 2 attributes issued by a trusted verification key (passed in as a constructor parameter the ICO Pass key): 1.1. the report bundle value. The report bundle is a collection of JSON documents, and described together with the verification webservice. This confirms that identification and KYC check has been performed for this subject and that it has required ICO contributor attributes the nationality index value. Described below. 2. the subject does not have a nationality index value that has been blacklisted in parameter nationalityblacklist. 9

10 Attributes signed by unrecognized keys are ignored. Qualified keys are published during the time of verification framework contract deployment and cannot be altered at later point. Optional Modifier (with Agreement Verification) There is another modifier, which includes a third parameter - for ICO contributor agreement signature verification: onlyverifiedsenders(address paymentaddress, uint256 nationalityblacklist, bytes32 hash_with_disclaimer). hash_with_disclaimer is the message, which has to be signed by the subject. The actual signature will be found in the subject s claims in the ClaimRegistry smart contract. The value hash_with_disclaimer already needs to include the prefix used by eth_sign - \x19ethereum Signed Message:\n<message_length>. See ICO Contributor Agreements for more information on how the signature can be associated for the contributor s address. Constructor Parameter address _trustedissueraddr address _claimregistryaddr Description The public key of the verifier, which will have signed off on the KYC information. The address of the ClaimRegistry contract. This contract is described together with other infrastructure contracts. Nationality Verification While typically data is stored off-chain (e.g. the report bundle is a URL to IPFS), nationality (and residency) information is stored on-chain; so that smart contracts can verify it. When ClaimRegistry returns a value, instead of resolving it as a URL (as per the ClaimRegistry documentation), the value can be interpreted as-is. The nationality index is a 1-based index of ISO countries sorted by the ISO 3166 numeric code. E.g. the first countries are Afghanistan (index 1) and Albania (index 2). This is because their respective ISO 3166 codes are 4 and 8 (i.e. the smallest, then the second smallest). 10

11 The last countries are Yemen and Zambia. Sort by this ISO Values Index Numeric code 3-letter code Country 1 4 AFG Afghanistan 2 8 ALB Albania 3 10 ATA Antarctica 4 12 DZA Algeria 5 16 ASM American Samoa 6 20 AND Andorra 7 24 AGO Angola 8 28 ATG Antigua and Barbuda 9 31 AZE Azerbaijan ARG Argentina AUS Australia AUT Austria BHS Bahamas BHR Bahrain BGD Bangladesh There are less than 256 entries in the ISO 3166 list, and the EVM word size is 256 bits. This means that these values can be set and verified with bitmasks. To generate a mask for country with index N: mask = 1 << (N-1) e.g. for China, the index is 44, so the mask is: mask = 1 << (44-1) = Given a country mask (countrymask), and a blacklist mask (blacklistmask), the values are verified with 2 bitwise operations: is_eligible = ( (countrymask XOR blacklistmask) AND countrymask == countrymask ) 11

12 If the same bits are set in both the country mask, and the blacklist mask, the eligibility check will fail. 6th = Andorra Blacklist: American Samoa (5) & Angola (7) While the nationality index is referred to as the nationality, the verification webservice will include residency information in blacklist lookup by consuming the additional residency attribute (if it is available). Agreement Signature Verification The modifier will find all claims for the subject of type Each found claim will be verified to contain the right signature with this procedure: 1. resolve the claim to a bytes32 value (this will be the eth_sign result of the subject s signature operation) 2. extract the v, r and s parameters (see below) 3. perform ecrecover(hash_with_disclaimer, v, r, s) If ecrecover returns true, the modifier stops processing further signature claims. If none of the claims are valid signatures, the modifier fails. Extracting v, r, and s Given the value sigbytes (the byte value of the claim): assembly { r := mload(add(sigbytes, 32)) s := mload(add(sigbytes, 64)) v := and(mload(add(sigbytes, 65)), 255) } 12

13 Mobile Client The mobile client acts as a device for gathering information: it allows taking a photo or video recording of the user it allows taking photos of documents, and immediately giving feedback about the quality it allows verifying the phone number It also offers a way to give easy feedback to the contributor: when the KYC checks are done if more information is required perform ICO address trustworthiness evaluation by indicating that candidate ICO has not been registered Finally, it can automate tasks for the end-user, which improves the user experience. It can perform automated wallet key ownership verification and personal information storage for reuse in subsequent ICOs. First Run When the ICO Pass mobile application is first launched, it will generate an ethereum keypair, and store it in the devices keychain. NOTE: this key is never exposed externally. Then it performs onboarding with the verification webservice. The webservice will send a verification , and an SMS code to the address and phone number supplied by the end user. 13

14 The webservice will send a small amount of ethereum to the internal address. The application will use it to pay for the key ownership proof transaction (see: KeyProof contract in the infrastructure smart contracts documentation). Afterwards, the application will consider the user to be onboarded. Start Ask for Send to verification webservice Ask for confirmation code sent to Ask for phone number Send to verification webservice Ask for confirmation code sent to phone Ask the verification webservice for a unique challenge UUID (and a tiny amount of ethereum to pay for the response transaction) Sign a response with the internal ethereum private key Submit the challenge response to the KeyProof contract This row corresponds to the key ownership proof scenario (see: KeyProof smart contract) User is onboarded 14

15 Submitting Data for ICOs When the end-user wishes to enroll for an ICO, they will have to perform an in-app purchase. The in-app purchase receipt will be sent to the verification webservice, which will validate the receipt. If the receipt is valid, KYC verification will commence. The user will be asked to take a photo of themselves, and of their chosen identity documents. They will also enter their address and date of birth. This information will be re-usable, unless an ICO specifies expiry dates. The verification webservice will use this information to perform KYC verification against multiple sources: is the document valid does the document match the photo of the person is the person in PEP/global sanction lists If the person is in PEP or sanction lists, the identity verification will cease. If the person s document does not match the photo, the verification will cease. If the person s document image is invalid (e.g. invalid machine readable code), can not be scanned, or it is expired, then the verification will cease. Full details about how the KYC checks are carried out, and about all the possible failure cases, can be seen in our GitHub repository. As far as the mobile client is concerned, however, it only gathers data, then sends this data to the verification webservice. For each verification attempt, the webservice can respond (asynchronously) with: ok failed, ineligible (e.g. user is a PEP) failed, please repeat (e.g. user s passport image was too blurry) 15

16 Verification Webservice After the mobile client gathers information, the verification webservice analyzes it and orchestrates the delivery of this information to the recipient (i.e. the ICO organizer). It cross-references the gathered information with multiple backing data providers, and signs it. Then it encrypts this information against the ICO organizer s address, and publishes it to the claim registry. User Mobile ClaimRegistrySC VerificationWS IPFS enter the recipient ICO address read claims signed by ICO Pass display recipient information (e.g. name, green checkmark) enter data (DoB, address, identity documents, photos) an unverified address displays a warning forward all information verify information against backing providers bundle information together and sign result generate bundle encryption key K1 (AES256) encrypt bundle with K1 encrypt K1 against the mobile public key K2 encrypt K2 against the ICO address K3 publish file including (the encrypted bundle, K2 and K3) both parties can now decrypt the data return content hash publish attribute 'reportbundlev1' with the IPFS content URL publish the attribute 'nationalityindex' discard the gathered, unencrypted data status update display results User Mobile ClaimRegistrySC VerificationWS IPFS 16

17 ICO Organizer Validation The same mechanism used to associate KYC information with the contributor address can be leveraged to associate validation information with the organizer (crowdsale) address. The mobile client recognizes specific claims signed by a specific ICO Pass key, and will display this information to the end-user. For details about how claims in general are associated with an ethereum address, see the ClaimRegistry smart contract description in the infrastructure contract documentation. The specific claims, which the mobile client supports and ICO Pass issues, are subject to change (but can always be seen publicly, by examining the ClaimRegistry values for a given address). Initially the claims are: Type Claim name Description IcoOrganizer IcoOrganizer Crowdsale Crowdsale Crowdsale name website_url name website_url agreement_url Name of the organizer Organizer s website Name of the crowdsale Crowdsale-specific website URL of the Contributor Agreement. This is expected to be an HTML document, which will be displayed to the users in-app. The hash of the contents will be signed by the participant, as proof of agreement (see the ICO Contributor Agreements section. 17

18 These attributes are optional. If they are not present (and signed by a recognized ICO Pass key), then the contributor will not be prohibited from sending KYC information to the specified address. ICO Contributor Agreements Optionally, the ICO contributor can sign a message, indicating agreement to the terms of the crowdsale. If the optional claims and are present for a given ICO crowdsale address (and signed by an ICO Pass key), then the following will take place: 1. a hash of the content at the specified address will be hashed: hash = keccak256(content at agreement_url) 2. a modified hash is calculated: hash_with_disclaimer = keccak256( \x19ethereum Signed Message:\n + len(hash) + hash) 3. if hash_with_disclaimer!= required_agreement_hash, then an error is displayed, and the user can not proceed 4. otherwise - if the content hashes match - the agreement is displayed to the end user, and the user is prompted for agreement 5. if the user indicates agreement to the terms, then the hash value is signed: signature = eth_sign(hash). eth_sign takes hash as input, because it will pre-pend the disclaimer itself. The resulting signature value will be stored as the following claim in ClaimRegistry: As such, the verifier contract will be able to ensure only addresses with valid agreement signatures can participate in the crowdsale. Why Two Separate Claims? It is not enough for the ICO organizer to include just the required hash of the agreement, because the participant needs to know what is being signed. It is not enough for the URL to be known, because there is no guarantee that the URL will be resolvable (e.g. the website hosting the agreement becomes unavailable). 18

19 This way with 2 values the end-user can see the agreement contents at the given URL, and the mobile client can hash this content and compare against the pre-specified hash value. If they do not match, the mobile client will assume that the URL was resolved incorrectly, and not allow the end-user to proceed. Changes to agreement are not allowed after registration for the ICO is open as this would introduce several different hash versions. Payment Transaction Processing During Crowdsale (a.k.a. Address Linking) As payment transactions to ICO crowdsale contracts are made from addresses distinct from the ones that have ICO contributor attributes published, infrastructure and verifier contracts include convenience methods for creating, maintaining and discovering address links. Before participation in a crowdsale, contributors are required to link their payment wallet address to his identity address, that is issued during ICO pass application onboarding process. Linking is done by making a payment from candidate payment wallet of ICO contributor to the identity subject address. The amount transferred is not important as the funds will be returned to sender, except gas. This transaction is needed to prove that the same person that has control over identity key on app, has also control over the wallet address, and this is done by signing a generic payment transaction. After payment has been reverted ICO pass application discovers the incoming transaction and offers contributor to link both addresses. Both addresses are stored on blockchain with reference to a corresponding proof transaction. During crowdsale contributors are referenced by their payment wallet addresses and ICO crowdsale contract helper functions automatically takes care of discovering identity subjects, that have ICO contributor attributes issued. In case contributor payment address is not registered, transaction will be reverted. 19

20 ICO pass application allows linking multiple addresses to a single contributor subject address to allow flexible identity reuse in multiple ICOs and also deletion of unused addresses is possible. 20

21 Part 2: Crowdsale Details Technical summary about Token Sale. 21

22 Sale Mechanics Summary: the auction will be a spend-all second-price Dutch auction. The contract will be based on Parity Tehnologies audited crowdsale contract (available from here: The base-contract is modified to use Notakey KYC verification contracts. The goal is to allow the token price be determined by the market. Another goal is specifically to not write a new and unproven crowdsale contract, because it is crucial for the crowdsale contract to be proven and without bugs. The full crowdsale contract is published on GitHub. In this section, the modifications are explained. USDWEI The USDWEI constant is changed to 805 szabo to reflect the Ethereum price as of 1 Jan, 2018 ($1242). Note: the USDWEI constant might be further modified, if the price of Ethereum changes too much before the token sale goes live. The latest changes can be seen at our GitHub repository, in the file SecondPriceAuction.sol calculateendtime The calculateendtime function is modified to reach the auction end-time more rapidly (by a factor of 100). The crowdsale time should range from a bit more than a month (with no contributions) to 2 weeks (reaching the desired contribution size). Here is a chart showing the correlation between contributions and the length of auction: 50 Length of Auction (in Days) 37, , Total Contributions (in eth) 22

23 Audit The crowdsale base contract has been audited. The audit report can be seen here: The changes relevant to ICO Pass - specifically, eligibility verification code - has not been audited yet. These changes should not be able to cause loss of funds to any contributor. ICO Pass changes only affect contributor eligibility modifiers. The ICO Pass verification contracts shall be audited before public release, after the crowdsale. 23

24 For more information contact Janis Kirsteins Chief Executive Officer