Get started with SDKs

We assume that you already know the concept of ONT ID and know what ONT ID can do for you. Now you need to use ONT ID to authenticate your users or use ONT ID to manage digital identities for your users. You can start with this document.

We support multiple SDK or RPC methods to apply ONT ID. We use the TypeScript SDK as an example to illustrate how to develop quickly. The following sample code in this document uses the Node environment.

1. Environment Preparation

Please refer to Ontology TS SDK Installation Guide to install the environment.

2. Create Digital Identitiy

2.1 Create Identity

ONT ID is a decentralized identity that manages a user's various digital identity authentications. Digital Identity (Identity) is a core class exported by the ONT SDK. This class contains the ONT ID attribute that represents identity.

📘
For detailed information about digital identity, please refer tothe ONT ID Protocol Specifiction.

You can create an identity through the SDKs. An ONT ID is generated using the user's private key.

The parameters needed are as follows:

privateKey User's privatekey. The private key can be safely generated by the method provided by the SDK.

password The password used to encrypt and decrypt the private key.

label Name of Identity

params The parameter used to encrypt the private key. Optional parameters. Default values of the optional parameters are as follows:

{
    cost: 4096,
    blockSize: 8,
    parallel: 8,
    size: 64
}

import {Identity, Crypto} from 'ontology-ts-sdk';
//generate a random private key
const privateKey = Crypto.PrivateKey.random();

var identity = Identity.create(privateKey, password, label)
console.log(identity.ontid)

2.2 Register the ONT ID to the blockchain

After the identity is created, you need to register the ONT ID to the blockchain, only then will the identity creation by complete.

Sending an ONT ID to the blockchain is a process that requires a transaction to be sent. The transaction object can be constructed by calling the methods provided by the SDKs.

A typical scenario is to construct a transaction object by passing the ONT ID and the user's private key.

Passing the private key has two purposes:

Sign the constructed transaction;
Bind the user's ONT ID to the public key that corresponds to the user's private key. The user can then add other public keys to the ONT ID.

import {OntidContract} from 'ontology-ts-sdk';
import {TransactionBuilder} from 'ontology-ts-sdk'

//suppose we already got a identity
const did = identity.ontid;
//we need the public key, which can be generate from private key
const pk = privateKey.getPublicKey();
const gasPrice = '0';
const gasLimit = '20000;
const tx = OntidContract.buildRegisterOntidTx(did, pk, gasPrice, gasLimit);
Transaction.signTransaction(tx, privateKey);

Transactions that send ONT IDs to the blockchain need a fee. We need to assign a Payer for the transaction and add the Payer's signature. The payer can be the user or the dApp application.

import {TransactionBuilder} from 'ontology-ts-sdk'
//we also need an account to pay for the gas
//supporse we have an account and the privateKey
tx.payer = account.address
//Then sign the transaction with payer's account
//we already got transaction created before,add the signature.
TransactionBuilder.addSign(tx, privateKeyOfAccount)

Now the transaction can be sent to the chain. We have various methods to send the transactions, such as WebSocket, RESTful, and RPC. Here is an example of the RESTful method. We can specify the node to which the transaction is sent, or send the transaction to TestNet.

import {RestClient, CONST} from 'ontology-ts-sdk'

const rest = new RestClient(CONST.TEST_ONT_URL.REST_URL);
rest.sendRawTransaction(tx.serialize()).then(res => {
    console.log(res)
})

The result is as follows:

{ Action: 'sendrawtransaction',
  Desc: 'SUCCESS',
  Error: 0,
  Result: 'dfc598649e0f3d9ff94486a80020a2775e1d474b843255f8680a3ac862c58741',
  Version: '1.0.0' }

If the result is success (Error is 0), the ONT ID is successfully sent to the blockchian. We can query the information about the ONT ID on the blockchain.

The ONT ID creation process is completed when the callback function receives the success information. Then you can use it through the ONT ID.

3. Query on-chain ID DDO

When an ONT ID is successfully registered to the blockchain, there is an ONT ID Object - called DDO - on the blockchain. The easiest way to query DDO is through the Ontology Blockchain Browser. Alternatively, you can query through the SDKs.

The method for querying through the SDKs is as follows:

First, create a transaction:

import {OntidContract} from 'ontology-ts-sdk';
//we use identity's ONT ID to create the transaction
const tx = OntidContract.buildGetDDOTx(identity.ontid)

Sending a transaction or querying a transaction does not require consumption of gas, and there is no need to specify the payer and the signature of the payer. The second parameter of the transaction-sending method indicates whether the pre-executed transaction was sent. The pre-executed transaction runs only on the node that receives it, not waiting for consensus. Pre-executed transactions are generally used to query data.

import {RestClient} from 'ontology-ts-sdk';
const rest = new RestClient();
rest.sendRawTransaction(tx, true).then(res => {
    console.log(res);
}

The result is as follows:

{ Action: 'sendrawtransaction',
      Desc: 'SUCCESS',
      Error: 0,
      Result:
       { State: 1,
         Gas: 20000,
         Result: '26010000002103547c5abdbe66677ba7001cefd773f01a19c6360b15ee51c6db43911f046564fc0000' },
      Version: '1.0.0' }

The result is the serialized DDO (ONT ID object). We can get detailed data through deserialization.

const ddo = DDO.deserialize(response.Result.Result);
console.log(ddo);

4. Authenticate ONT IDs

ONTPass is an open, decentralized authentication service platform that provides KYC (Know Your Customer) services and various user authentication services based on ONT ID and thee Ontology trust ecosystem. Ontology has gathered trust anchors which provide global identity authentication services, including IdentityMind, CFCA, Shangtang Technology, Shufti Pro, etc., as well as email, mobile, and social media authentication methods.

5. Verify verifiable claims

In the previous section we gave examples of how to obtain a third-party-issued identity claim that users can present when they need. At the same time, whether these statements are true or false can be verified by the methods provided by the SDK.

We illustrate the process of verifying a verifiable claim by taking Alice's job hunting as an example.

When Alice hunts for a job in Company B, she provides a digital diploma issued by Fudan University, which is a JSON file that meets the claim format. Company B can verify the claim by calling the ONT SDK. The internal implementation logic of the method is first to obtain the DDO information of the issuer by using the Issuer field in the claim, obtain the public key of the issuer from the DDO information, and check signature-removed content in the claim object, as well as the public key and signature value. If the verification is passed, it indicates that the statement is true and valid.

The input parameter to this method is the JSON string declared by the claim, and the result is Promise. The verification results are processed in the callback method of Promise.

// suppose we have got a claim

const restUrl = 'http://dappnode1.ont.io:20334'; // The restful url of MainNet

// the second parameter decides whether to check the attest status of the claim.
claim.verify(restUrl, false).then( result => {
  console.log(result) // the result is true of false
})

6. Making verifiable claims for users

Your platform can also make verifiable claims for users.

Any ONT ID owner can issue verifiable claims to himself or others.

Government agencies, universities, banks, third-party certification services (such as CA institutions), biometric technology companies, etc., can be used as trust institutions. They can be added as a partner to the Ontology ecosystem.
If you would like to become a authentication service partner, please refer to trust anchor.

We use the digital diploma issued by Fudan University in China as an example to explain how to obtain the identity claim issued by a third party.

Suppose Alice is a student at Fudan University and applies for a digital certificate of her diploma from the university. After the school verifies the identity of Alice, it generates a verifiable claim by calling the API of the SDK, which contains Alice's graduation information and the signature of the statement with the school's private key.

const claim = new Claim({
 messageId, // identical id of the claim
 issuer, // Claim issuer, here is the Fudan University
 subject, // Here is Alice
 issuedAt // Date time of the issue
})
claim.content = { // The specific content of the claim
 Name: 'Alice',
 Age: 22,
......
}
const restUrl = 'http://dappnode1.ont.io:20334'; // The restful url of MainNet
const publicKeyId = 1;
const privateKey = '7c47df9664e7db85c1308c080f398400cb24283f5d922e76b478b5429e821b97'
claim.sign(restUrl, publicKeyId, privateKey).then(res => {
 console.log(res)
})

// claim now is signed

Then we can attest the claim on the blockchain with the ONT SDK.

// suppose we have a signed claim
// we need to pass in the socket url here
const socketUrl = 'ws://dappnode1.ont.io:20335';
const payerAddress = new Address('AdLUBSSHUuFaak9j169hiamXUmPuCTnaRz');
const payerPrivateKey = new PrivateKey('7c47df9664e7db85c1308c080f398400cb24283f5d922e76b478b5429e821b97');
const res = await claim.attest(socketUrl, '500', '20000', payerAddress, payerPrivateKey);
console.log(res);
// now the claim is attested on the blockchain