Skip to main content
European CommissionEBSI European Blockchain
Access Help Desk(opens in a new tab)

EBSI DID Resolver

The @cef-ebsi/ebsi-did-resolver library supports the proposed did:ebsi method from EBSI.

The did:ebsi method supports 2 versions:

  • v1, which is meant to be used by Legal Entities.
  • v2, which was used by Natural Persons but is now deprecated. For Natural Persons, the did:key method is preferred.

In order to resolve DID Documents, the EBSI DID resolver requires the did-resolver library, which is the primary interface for resolving DIDs.

Installation​

npm install @cef-ebsi/ebsi-did-resolver

or if you use yarn:

yarn add @cef-ebsi/ebsi-did-resolver

Resolving a DID document​

The library provides different resolvers that are meant to be used through the did-resolver aggregator.

import { Resolver } from "did-resolver";
import { getResolver } from "@cef-ebsi/ebsi-did-resolver";

// You must set the address of the DID Registry to be used in order to resolve Legal Entities DID Documents
const resolverConfig = {
  registry: "https://api-pilot.ebsi.eu/did-registry/v3/identifiers",
};

// getResolver will return an object with a key/value pair of { "ebsi": resolver } where resolver is a function used by the generic DID resolver.
const ebsiResolver = getResolver(resolverConfig);
const didResolver = new Resolver(ebsiResolver);

didResolver
  .resolve("did:ebsi:zub5ZZUfHLLptCduwEy8xRj")
  .then((doc) => console.log);

// You can also use ES7 async/await syntax
const doc = await didResolver.resolve("did:ebsi:zub5ZZUfHLLptCduwEy8xRj");

Legacy resolver​

The legacy EBSI resolver that allows resolving both Legal Entities and Natural Persons DID Documents with the did:ebsi: method is still available through the getLegacyResolver method.

We do not recommend using it.

Natural Persons should use the did:key method and its related resolver.

Resolving Natural Persons DIDs with the legacy resolver​

import { Resolver } from "did-resolver";
import { getLegacyResolver } from "@cef-ebsi/ebsi-did-resolver";

// Example of a JWK shared by a Natural Person
const knownJwk = {
  kty: "EC",
  crv: "secp256k1",
  x: "Gk0927lG8jRAd-6z-jQdhN-pcELMxKEQJRhPuzz4nic",
  y: "zPs6-edBMiY7rOCLBn87Bp2pINeskJV_7KnFd0nNHGQ",
};

// You must provide a set of known JWKs in order to resolve a Natural Person's DID document
const resolverConfig = {
  naturalPersonJwks: [knownJwk],
};

// getLegacyResolver will return an object with a key/value pair of { "ebsi": resolver } where resolver is a function used by the generic DID resolver.
const ebsiResolver = getLegacyResolver(resolverConfig);
const didResolver = new Resolver(ebsiResolver);

didResolver
  .resolve("did:ebsi:zpBqM2DGALyfULDjNTp95cXrSjcNG6b1fYeNZD6WhPEgi")
  .then((doc) => console.log);

// You can also use ES7 async/await syntax
const doc = await didResolver.resolve(
  "did:ebsi:zpBqM2DGALyfULDjNTp95cXrSjcNG6b1fYeNZD6WhPEgi"
);

Creating a DID​

The library exposes a method allowing you to create a DID from the given subject identifier bytes:

For a Legal Entity:

import { util } from "@cef-ebsi/ebsi-did-resolver";
import { randomBytes } from "node:crypto";

const subjectIdentifierBytes = randomBytes(16); // An array of 16 random bytes
const did = util.createDid(subjectIdentifierBytes, "LEGAL_ENTITY");
// Example: "did:ebsi:ztRBFfMCY7VAGHH1Ba8Q5o9"

DEPRECATED: For a Natural Person, based on an existing JWK:

import { util } from "@cef-ebsi/ebsi-did-resolver";
import { base64url, calculateJwkThumbprint } from "jose";

// For a Natural Person, based on an existing JWK
const jwk = {
  kty: "EC",
  crv: "P-256",
  alg: "ES256",
  use: "sig",
  x: "ngy44T1vxAT6Di4nr-UaM9K3Tlnz9pkoksDokKFkmNc",
  y: "QCRfOKlSM31GTkb4JHx3nXB4G_jSPMsbdjzlkT_UpPc",
};
const thumbprint = await calculateJwkThumbprint(jwk, "sha256");
const did = util.createDid(base64url.decode(thumbprint), "NATURAL_PERSON");
// -> "did:ebsi:znxntxQrN369GsNyjFjYb8fuvU7g3sJGyYGwMTcUGdzuy"

As a reminder, the did:ebsi method for Natural Persons is deprecated. Please use the did:key method instead.

Try it online​