Skip to content

Latest commit

 

History

History
127 lines (83 loc) · 8.59 KB

driver-development.md

File metadata and controls

127 lines (83 loc) · 8.59 KB
Raw

Universal Resolver — Driver Development

Introduction

The Universal Resolver wraps an API around a number of co-located Docker containers running DID-method-specific drivers. Additional DID methods can be supported as they are developed by the community. The contribution for a new DID method driver consists of a Docker image which exposes an HTTP interface for resolving DIDs. New contributions are submitted as Pull Requests to the Universal Resolver (this) repository.

An example driver is available here.

An example PR for contributing a driver is available here.

Driver Interface

Your driver will be invoked via an HTTP GET call to:

http://<your-image-url>/1.0/identifiers/<your-did>

Your driver will receive an Accept header with the value application/ld+json, and it should return either a valid DID Document or a DID Resolution Result in the HTTP body. Your driver should also return an appropriate value in the Content-Type header, such as application/did+ld+json.

A Swagger API definition is available here.

For more information about this interface, see the DID Resolution specification.

Driver Rules

  • The DID method implemented by the driver must have a specification that is registered in the DID Method Registry of the W3C DID WG.
  • Multiple drivers for the same DID method are allowed and can be listed in the README, but only one can be included in the configuration. In this case, the DIF I&D WG will choose a default.
  • Contact information must be provided when contributing a driver (either email address, or Github/Gitlab/Bitbucket handle).
  • Driver source code must be publicly available and fully open-source under a permissive license (Apache 2.0 preferred).
  • Driver source code may optionally be hosted at DIF (as a contribution to the I&D WG).
  • Driver image must be published on a publicly accessible container registry.
  • Driver image hosted on Dockerhub should have Expanded Support for Open Source Software Projects to avoid hitting Dockerhub pull limits.
  • Driver image should be tested both as standalone Docker container, and as part of the Universal Resolver with docker-compose.

How to

How to contribute a driver

Create a PR that edits the following files in the Universal Resolver root directory and uni-resolver-web's application.yml:

  • docker-compose.yml (add your driver, if it has a Docker image)
    • image - your Docker image name
    • ports - incremented port number exposed by your Docker image
    • environment - optional environment variables supported by your Docker image
    • uni-resolver-web service - add an environment variable for your drivers URL into the uni-resolver-web service definition at the top of this file. This can be used to inject the driver URL at runtime and override the default hard coded value in the application.yml. The variable name should follow the convention of uniresolver_web_driver_url_did_<your-did-method-identifier> to avoid conflicts.
  • application.yml (add your driver)
    • pattern - regular expression for matching your DID method
    • url - this should be in the format of a spring property placeholder to allow possible injection of the URL at runtime. The placeholder should use the environment variable specified in the docker-compose.yml for your driver and provide a default endpoint of your Docker compose service name or external resolver endpoint. The general spring placeholder format to use is ${uniresolver_web_driver_url_did_<your-did-method-identifier>:<default-static-url>}.
    • testIdentifiers - list of example DIDs that your driver can resolve
  • .env
    • list environment variables (if any) with default values
  • README.md (insert a line to the driver table)
    • driver name (e.g. did-example), with link to driver source code
    • driver version (e.g. 0.1), should match Docker image version
    • DID method spec version (e.g. 0.1), with link to DID method spec (or mark "missing")
    • Docker image name (e.g. exampleorg/uni-resolver-driver-did-example) with link to hosted Docker image
    • contact information

Your driver is expected to be well-documented, tested, and working before you submit a PR. The documentation for your driver should be clear enough to explain how to run your driver, how to troubleshoot it, and a process for updating the driver over time.

How to update a driver

Contributors should keep their drivers up-to-date as changes happen to the DID Core spec and the DID method spec. Driver implementers MUST specify a Docker image version, and not use :latest.

In order to update a driver, simply submit a new PR that increments the Docker image version and updates the relevant files (see above in the "How to contribute a driver" section).

How we handle problems with drivers

If your Docker image exists and starts, but your example DIDs cannot be resolved or your driver produces invalid responses:

  • You will be contacted and given 30 days to fix the problem; after that, your driver will be removed.
  • You are welcome to still fix the problem later and re-contribute your driver.

If your Docker image does not exist:

  • Your driver will be removed immediately.
  • You are welcome to still fix the problem later and re-contribute your driver.

If your driver does not fulfill the Driver Rules:

  • You will be contacted and given 30 days to fix the problem; after that, your driver will be removed.
  • You are welcome to still fix the problem later and re-contribute your driver.

How to test a driver locally

Once your driver is implemented and published as a Docker container, you may want to test that it is running properly within the Universal Resolver.

To do so, follow these steps:

  • Clone the Universal Resolver (this) repository:

    git clone https://github.com/decentralized-identity/universal-resolver
cd universal-resolver/

  • Make the required changes mentioned above ("How to contribute a driver") to the .env, application.yml and docker-compose.yml files.

  • Pull remote docker images

      docker compose -f docker-compose.yml pull

  • Build uni-resolver-web locally:

    docker build -f ./uni-resolver-web/docker/Dockerfile . -t universalresolver/uni-resolver-web

  • Run the uni-resolver-web locally:

    docker compose -f docker-compose.yml up

    It's also possible to only start a subset of service, by specifying a list after. Ex: docker compose -f docker-compose.yml up uni-resolver-web driver-did-prism

After each local change, you must rebuild uni-resolver-web locally. If you pull docker images, it will overwrite the local uni-resolver-web, so you must rebuild again after pulling.

You can now resolve DID Documents via curl commands as documented in the Quick Start notes.

Additional Notes

  • Depending on the DID method, oftentimes DID drivers will need to read some decentralized ledger or distributed filesystem (the "target system") in order to resolve a DID. Each driver may decide how it will communicate with its respective target system. For those drivers performing operations on DLT's, the driver may do so via web API, communicating with a remote node, running a full node, or another experimental configuration.
  • The detailed definition for the DID Resolution HTTP(S) binding can be found here.