Skip to main content

Quickstart

Get started with KILT by following this guide. You'll learn to:

  1. Import the KILT SDK into your project
  2. Connect to the KILT blockchain
  3. Query a web3name to retrieve its DID
  4. Verify a credential using a DID service

This quickstart guide provides hands-on experience to enhance your understanding of KILT. Basic knowledge of JavaScript and command-line tools is recommended. For more in-depth tutorials, we'll suggest additional guides.

Setup​

Let's start by creating a new project from scratch. Create a new project in a fresh directory by running mkdir kilt-rocks && cd kilt-rocks.

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

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

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

Once you've imported the SDK, you'll gain access to KILT's functionalities. Now, let's create a new file containing the TypeScript compiler configuration.

touch tsconfig.json

Inside the tsconfig.json file, include the following configuration:

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

This will set the module option to "CommonJS" for TypeScript compilation.

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 execute 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​

To perform operations that rely on the KILT blockchain, such as querying and verifying a credential, it's essential to connect to the KILT blockchain. Within the same main function, configure the SDK to connect to a KILT node using the Kilt.connect() method:

Peregrine is the development blockchain. For testing and development purposes connect to this network.
const api = await Kilt.connect('wss://peregrine.kilt.io/')

To ensure proper cleanup, call the Kilt.disconnect() function at the bottom of the main function:

await Kilt.disconnect()

By adding await Kilt.disconnect() at the end of the main function, you ensure that the connection to the blockchain node is properly closed when the script finishes executing. This helps maintain the integrity of your application and is a good practice to follow.

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

Query a KILT Identity​

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 api = Kilt.ConfigService.get('api')

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 {
  const { attester, revoked } = await Kilt.Credential.verifyCredential(
    credential
  )

  // Verify that the credential is not revoked. Exception caught by the catch {} block below.
  if (revoked) {
    throw new Error('The credential has been revoked, hence it is not valid.')
  }
  console.log(
    `John Doe's credential is valid and has been attested by ${attester}!`,
    JSON.stringify(credential, null, 2)
  )
} catch {
  console.log("John Doe's credential is not valid.")
}

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

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.