Skip to main content

Quickstart

The following guide will give you a starting point to begin with KILT. You will learn how to:

  1. Import the KILT SDK into a project
  2. Connect to the KILT blockchain
  3. Query a web3name to get its DID
  4. Verify a credential, available via a DID service

After completing the quickstart guide, you should have gained a better understanding of KILT through hands-on experience. The guide requires some experience with javascript and command-line tools. We will recommend guides to other tutorials to dive deeper into some of the topics.

Setup​

We will focus on creating a new project from scratch, which will require a little setup. First, we need to create a new project in a new directory. For this, we run mkdir kilt-rocks && cd kilt-rocks.

From inside the kilt-rocks project directory, install the KILT SDK, Ts-node, Axios and Typescript:

npm init -y
npm install @kiltprotocol/sdk-js axios ts-node typescript

With all the required dependencies set, just create a new (empty) script file with touch quickstart.ts.

After you have imported the SDK you will be able to access the functionalities that KILT provides. We are making a new file that contents the compiler configuration for typescript.

touch tsconfig.json

Inside the tsconfig.json add in the following value:

{
  "compilerOptions": {
    "module": "CommonJS"
  },
}

Let's first declare our main function that will execute our script:

export async function main() {
  console.log('Hello, world!')
}

If the setup is correct you can execute the script by calling the name of the file using Node.

yarn ts-node quickstart.ts

As we will extend the code in this file, you can always excute it with the same command.

Let's get started! 🔥

Import the KILT SDK​

Let's begin by importing the KILT SDK and Axios:

import * as Kilt from '@kiltprotocol/sdk-js'
import axios from 'axios'

Now you are able to access the SDK and all its functionality. We will move onto connecting to the KILT blockchain.

Connect to the KILT Blockchain​

Connecting to and disconnecting from the KILT blockchain is required for any operation that relies on the KILT blockchain, such as querying and verifying a credential.

Still within the same main function, you need to configure the SDK to connect to a KILT node. For this, the SDK exposes Kilt.connect() to configure the address of the node to connect to.

We will use the official Spiritnet address:

await Kilt.connect('wss://spiritnet.kilt.io/')

const api = Kilt.ConfigService.get('api')

After establishing a connection, you have access to the chain, but let's not forget to close any connections when we are done! Connections to blockchain nodes should be dropped when no longer needed: to do that simply call the Kilt.disconnect() function at the bottom of main function.

await Kilt.disconnect()

Congratulations! You have connected to a Spiritnet node. Let's now start querying some data from the chain!

Query the KILT Blockchain​

We will be querying information related to a web3name (john_doe), and using them to retrieve the KILT DID linked to it. In between the Kilt.connect() and Kilt.disconnect() lines, add the following code:

const encodedJohnDoeDetails = await api.call.did.queryByWeb3Name('john_doe')

// This function will throw if johnDoeOwner does not exist
const {
  document: { uri }
} = Kilt.Did.linkedInfoFromChain(encodedJohnDoeDetails)
console.log(`My name is john_doe and this is my DID: "${uri}"`)

Try executing it and check the result.

Did you get the DID? Nice work! You now have john_doe's DID. Now let's see if John Doe has any public KILT credentials that we could retrieve and verify!

Retrieve and Verify a Credential​

A KILT DID can expose services, which allow external resources to be linked to the DID. One type of external resource is represented by, you guessed it, KILT credentials! Therefore, let's see how we can retrieve the services of John Doe's DID and see if they link to any public credentials for us to query and verify.

We will keep adding code below what we just added. The code snippet retrieves the services exposed by the DID we found for john_doe:

const johnDoeDidDocument = await Kilt.Did.resolve(uri)
console.log(`John Doe's DID Document:`)
console.log(JSON.stringify(johnDoeDidDocument, null, 2))

const endpoints = johnDoeDidDocument?.document?.service
if (!endpoints) {
  console.log('No endpoints for the DID.')
  return []
}

console.log('Endpoints:')
console.log(JSON.stringify(endpoints, null, 2))

If the snippet printed some endpoints, congratulations! Let's see if we can find a credential among them.

We can select one of the endpoints and query the URL to see if it returns a KILT credential collection as described in the KiltPublishedCredentialCollectionV1 specification:

const {
  data: [{ credential }]
} = await axios.get<Kilt.KiltPublishedCredentialCollectionV1>(
  endpoints[0].serviceEndpoint[0]
)

If the script completes with no errors, it means that we were able to retrieve the published credential using the URL specified in the service.

We will now have to make sure the credential is valid and has a valid structure.

It is then time to verify the credential. This will be indicated by the result of the verification process as shown in the snippet below:

try {
  await Kilt.Credential.verifyCredential(credential)

  const api = Kilt.ConfigService.get('api')
  const attestationInfo = await api.query.attestation.attestations(
    credential.rootHash
  )
  const attestation = Kilt.Attestation.fromChain(
    attestationInfo,
    credential.rootHash
  )
  // Verify that the credential is not revoked. Exception caught by the catch {} block below.
  if (attestation.revoked) {
    throw new Error('The credential has been revoked, hence it is not valid.')
  }
  console.log(
    "John Doe's credential is valid!",
    JSON.stringify(credential, null, 2)
  )
} catch {
  console.log("John Doe's credential is not valid.")
}

Now excute the script wait to see whether we can successfully retrieve and verify one of John Doe's credentials!

Now it's time to query the credential's rootHash from the blockchain to see if it has been attested by someone:

const encodedAttestationInfo = await api.query.attestation.attestations(
  credential.rootHash
)
// This function will throw if the attestation does not exist.
const attestationInfo = Kilt.Attestation.fromChain(
  encodedAttestationInfo,
  credential.rootHash
)

// Return false if attestation.revoked is true, or true otherwise.
const revokedStatus = !attestationInfo.revoked

console.log('Revoked status of the attestation', revokedStatus)

Now, the last step is to excute the complete script and see if you get a valid attestation for John Doe's credential!

Was it successful? Nice Job!

If you want to explore more of KILT's features, check out our Concepts section. If you want to dive deeper into the SDK, please advance to the next section: the KILT Cookbook.