Create and Resolve DIDs with Onyx

This tutorial guides you through creating a Decentralized Identifier (DID) using the Onyx SSI SDK and resolving it with the Vidos Universal Resolver. You’ll build a simple Node.js application that demonstrates the integration between these two systems, providing a foundation for more complex identity workflows.

Why it matters

In the digital asset economy, secure identity verification is essential. Financial service providers need robust solutions to authenticate traders and assets to manage compliance requirements, mitigate risks, and build trust. Traditional verification methods often come with limitations:

• Time-consuming manual processes
• Error-prone identity checks
• Vulnerability to fraud
• Limited interoperability across systems

Decentralized identifiers (DIDs) and verifiable credentials (VCs) address these challenges by providing a secure, interoperable foundation for digital identity.

Technologies used

This tutorial combines two powerful technologies:

Onyx by J.P. Morgan is a bank-led blockchain platform that builds next-generation financial ecosystems. It provides institutional-grade infrastructure and services for developing purpose-built blockchain applications.

Vidos Universal Resolver enables resolving and validating DIDs across multiple methods, providing interoperability for identity verification across different blockchains and systems.

How they work together

The integration delivers several key benefits:

• Extended capability: Access 5× more DID methods with 86% less integration time using a single line of code
• Enterprise reliability: Benefit from maintained infrastructure that ensures performance, scalability, and stability
• Simplified deployment: Eliminate the need to host multiple Docker containers for different DID methods
• Future-ready design: Stay current with evolving regulatory landscapes and emerging identity standards

Prerequisites

Before starting, ensure you have:

• Node.js version 16 or later (latest LTS version recommended)
• A Vidos account (register here)
• A Vidos Resolver instance (create one here or learn about creation steps
• A Vidos IAM API Key (create one here)

Step 1: Create the project

First, set up a simple Node.js project structure:

mkdir onyx-vidos-example
cd onyx-vidos-example

Initialize the Node.js project:

npm init -y

Create your main file:

touch index.js

Test your setup with a simple script:

index.js

console.log('Hello, Onyx and Vidos!');

Run the project to verify everything works:

node index.js

You should see Hello, Onyx and Vidos! in your terminal.

Step 2: Install dependencies

Add the Onyx SSI SDK to your project:

::: code-group

install @jpmorganchase/onyx-ssi-sdk

:::

Step 3: Create a DID with Onyx SDK

The Onyx SDK supports both did:key and did:ethr methods. For simplicity, we’ll create a did:key identifier.

Replace the contents of index.js with:

index.js

const { KeyDIDMethod } = require('@jpmorganchase/onyx-ssi-sdk');

async function main() {
    const keyDidMethod = new KeyDIDMethod();
    console.log('Creating a new DID...');
    const did = await keyDidMethod.create();
    console.log('Created did: ', did.did);
}

main();

Run the project:

node index.js

You should see output similar to:

Creating a new DID...
Created did:  did:key:z6Mkk9JVjp3naTEX7qZeavHjzZTcsYRZ4K69jZ1HCRXuF6WB

How it works

1. We import the KeyDIDMethod class from the Onyx SDK
2. We create an instance of this class
3. We call the create() method to generate a new random did:key identifier
4. The operation runs inside an async function that executes when the script runs

:::info Note The import statement uses CommonJS syntax (require) instead of ES module syntax (import) because the Onyx SDK has invalid ESM exports. This is a known issue with an open PR: [fix]: update configuration for exporting package #25 :::

Step 4: Create a VidosResolver class

Now we’ll build a wrapper class for the Vidos Universal Resolver API to resolve our DID. Create a new file called VidosResolver.js:

VidosResolver.js

class VidosResolver {
    constructor(resolverInstanceUrl, apiKey) {
        this.resolverInstanceUrl = resolverInstanceUrl;
        this.apiKey = apiKey;
    }

    async resolve(didUrl) {
        const resolutionResponse = await fetch(`${this.resolverInstanceUrl}/${didUrl}`, {
            method: 'GET',
            headers: {
                Authorization: `Bearer ${this.apiKey}`,
            },
        });

        return resolutionResponse.json();
    }
}

module.exports = VidosResolver;

How it works

This class provides a simple interface to the Vidos Universal Resolver:

1. The constructor accepts the resolver URL and your API key
2. The resolve() method takes a DID URL and makes an authenticated request to the resolver
3. It returns the parsed JSON response with the DID Document

Step 5: Configure environment variables

For security, store your Vidos credentials in environment variables rather than hardcoding them. Create a .env file:

.env

VIDOS_RESOLVER_URL=<your Vidos Resolver instance URL>
VIDOS_API_KEY=<your Vidos IAM API Key>

Step 6: Resolve the DID

Now update index.js to use your new resolver class:

index.js

const { KeyDIDMethod } = require('@jpmorganchase/onyx-ssi-sdk');
const VidosResolver = require('./VidosResolver');

async function main() {
    const keyDidMethod = new KeyDIDMethod();
    console.log('Creating a new DID...');
    const did = await keyDidMethod.create();
    console.log('Created did: ', did.did);

    console.log('Creating a new VidosResolver instance...');
    const resolver = new VidosResolver(process.env.VIDOS_RESOLVER_URL, process.env.VIDOS_API_KEY);

    console.log('Resolving the DID using the VidosResolver instance...');
    const resolutionResponse = await resolver.resolve(did.did);
    console.log('Resolution response: ', JSON.stringify(resolutionResponse, null, 2));
}

main();

Run the project with environment variables loaded:

node --env-file .env index.js

You should see a complete DID resolution response that includes:

• DID resolution metadata
• The full DID Document with verification methods
• Additional document metadata

How it works

1. We create a DID using the Onyx SDK, as before
2. We instantiate our VidosResolver with credentials from environment variables
3. We resolve the DID by calling resolver.resolve(did.did)
4. We display the full resolution response, which contains the DID Document

:::info Note The --env-file flag requires Node.js 16.6.0 or later. For older versions, use the dotenv package to load environment variables. :::

Next steps

You’ve successfully created and resolved a DID using the Onyx SSI SDK and Vidos Universal Resolver. This foundation opens up several possibilities:

• Create and issue verifiable credentials
• Build credential presentation workflows
• Implement credential verification with configurable trust requirements
• Create multi-DID method applications with consistent interfaces

The complete source code for this example is available on GitHub: onyx-vidos-example.

Real-world application: Trader authentication

Here’s how this technology can be applied in a financial services context:

Alice, an international trader, needs to execute a trade on Bob’s digital asset management platform built with Onyx. The platform uses DIDs and verifiable credentials for secure authentication:

1. Alice scans a QR code to initiate authentication
2. The platform requests verification of Alice’s identity credentials
3. Alice selects the required credentials from her digital wallet
4. Bob’s platform verifies the credentials using the Vidos Universal Resolver
5. Upon successful verification, Alice can execute permitted trading actions

This workflow provides secure, compliant identity verification while significantly reducing fraud risks and improving the user experience.