Skip to main content

Well-Known DID Configuration

This is a working draft

The KILT support of the Well-Known DID Configuration uses unpublished specifications and will change in the future.

The Well-Known DID Configuration is implemented as a security measure when setting up the communication session between the dapp and extension. It ensures that the DID the browser extension is communicating to is linked to the domain that is visited by the browser. This rule is currently enforced by the KILT Wallet reference implementation (Sporran Extension), but might be relaxed in the future. The implementation is based on the Well-Known DID Configuration specified by the Decentralized Identity Foundation.

Once a communication session between a dapp and an extension is opened, the extension will query <domain-name>/.well-known/did-configuration.json. This JSON-file must contain a credential presentation that conforms to the Domain Linkage CType.

Set up the Well-Known DID Configuration

For the Well-Known DID Configuration you need to go through the following steps:

  1. Create a full DID
    • You will need the assertionMethodKey a.k.a. attestationKey for signing the credential
    • The authenticationKey is required for signing the transaction
  2. Create a claim
  3. Attest the claim
  4. Create a presentation
  5. Host the presentation on your website at https://<your domain>/.well-known/did-configuration.json

Create a DID

Your dapp needs a DID to identify itself to the extension. If your dapp does not have a DID yet, follow the create a full DID guide. Make sure to create the DID with an assertionMethodKey so that you are able to issue attestations.

Making the claim

After you get a DID, you can make a claim about that DID. The claim has to be based on the Domain Linkage CType:

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

export const domainLinkageCType: Kilt.ICType = {
$id: 'kilt:ctype:0x9d271c790775ee831352291f01c5d04c7979713a5896dcf5e81708184cc5c643',
$schema: '',
title: 'Domain Linkage Credential',
properties: {
id: {
type: 'string'
origin: {
type: 'string'
type: 'object'

The credential is built from the CType, claim contents, and your dapp's unique DID:

const claimContents: Kilt.IClaimContents = {
id: didUri,
origin: ''

const claim = Kilt.Claim.fromCTypeAndClaimContents(
const domainLinkageCredential = Kilt.Credential.fromClaim(claim)

The credential isn't attested yet and is therefore not valid yet.

Self-attesting the credential

A valid credential requires an attestation. Since the website wants to link itself to the DID just created, it has to self-attest the domain linkage credential, i.e., write the credential attestation on chain using the same DID it is trying to link to.

In order to attest the credential we go through the following steps:

  1. calculating the claim hash
  2. creating the attest transaction
  3. authorizing the transaction with your DID
  4. paying for the transaction with a KILT account and submitting it to the chain
const { cTypeHash, claimHash } = Kilt.Attestation.fromCredentialAndDid(
const attestationTx = api.tx.attestation.add(claimHash, cTypeHash, null)

// We authorize the call using the attestation key of the Dapps DID.
const submitTx = await Kilt.Did.authorizeTx(
async ({ data }) => ({
signature: assertionMethodKey.sign(data),
keyType: assertionMethodKey.type

// Since DIDs can not hold any balance, we pay for the transaction using our blockchain account
const result = await Kilt.Blockchain.signAndSubmitTx(submitTx, dappAccount)

if (result.isError) {
console.log('Attestation failed')
} else {
console.log('Attestation successful')

If you want to learn more about attestations you can refer to our concept guide or the cookbook.

Presenting the credential

To use the newly attested credential, we need to derive a presentation from it to host on the dapp website.

// We need the KeyId of the AssertionMethod Key. There is only
// one AssertionMethodKey and its id is stored on the blockchain.
const didResolveResult = await Kilt.Did.resolve(didUri)
if (typeof didResolveResult.document === 'undefined') {
throw new Error('DID must be resolvable (i.e. not deleted)')
const assertionMethodKeyId = didResolveResult.document.assertionMethod[0].id

const domainLinkagePresentation = await Kilt.Credential.createPresentation({
credential: domainLinkageCredential,
signCallback: async ({ data }) => ({
signature: assertionMethodKey.sign(data),
keyType: assertionMethodKey.type,
keyUri: `${didUri}${assertionMethodKeyId}`

The Well-Known DID Configuration specification requires a verifiable credential. For now we have to manually convert our KILT credential into the required format.

const credentialSubject = {
rootHash: domainLinkagePresentation.rootHash

const encodedAttestationDetails = await api.query.attestation.attestations(
const issuer = Kilt.Attestation.fromChain(

const issuanceDate = new Date().toISOString()

const claimerSignature = domainLinkagePresentation.claimerSignature
if (!claimerSignature) {
throw new Error('Claimer signature is required.')

const proof = {
type: 'KILTSelfSigned2020',
proofPurpose: 'assertionMethod',
verificationMethod: claimerSignature.keyUri,
signature: claimerSignature.signature,
challenge: claimerSignature.challenge

const wellKnownDidconfig = {
'@context': '',
linked_dids: [
'@context': [
type: [

Host the Presentation

Now that you generated a presentation, you need to host it in your web app, so that the extension can query the presentation. The extension will make an HTTP GET request to the following URI, and your dapp must respond with the presentation.


How the file is hosted depends on your project setup and is out of scope for this guide.