Awesome
cheqd DID Resolver
ℹ️ Overview
DID methods are expected to provide standards-compliant methods of DID and DID Document ("DIDDoc") production. The cheqd DID Resolver is designed to implement the W3C DID Resolution specification for did:cheqd method.
📝 Architecture
The Architecture Decision Record for the cheqd DID Resolver describes the architecture & design decisions for this software package.
✅ Quick Start
If you do not want to install anything and just want to resolve a did:cheqd entry from the ledger, you can load the REST API endpoint for resolver.cheqd.net in your browser.
Or, make a request from terminal to this hosted REST API:
curl -X GET https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47
🛠️ Running your own cheqd DID Resolver using Docker
Spinning up a Docker container from the pre-built did-resolver Docker image on Github is as simple as the command below:
docker compose -f docker/docker-compose.yml up --detach
Configure resolver settings
To configure the resolver, modify the values under the environment section of the Docker Compose file. The values that can be edited are as follows:
MAINNET_ENDPOINT: Mainnet Network endpoint as string with the following format"<networks>,<useTls>,<timeout>. Example:grpc.cheqd.net:443,true,5snetworks: A string specifying the Cosmos SDK gRPC endpoint from which the Resolver pulls data. Format:<resource_url>:<resource_port>useTls: Specify whether gRPC connection to ledger should use secure or insecure pulls. Default istruesince gRPC uses HTTP/2 with TLS as the transport mechanism.timeout: Timeout (in seconds) to wait for before any ledger requests are considered to have time out.
TESTNET_ENDPOINT: Testnet Network endpoint as string with the following format"<networks>,<useTls>,<timeout>. Example:grpc.cheqd.network:443,true,5sRESOLVER_LISTENER`: A string with address and port where the resolver listens for requests from clients.LOG_LEVEL:debug/warn/info/error- to define the application log level.
gRPC Endpoints used by DID Resolver
Our DID Resolver uses the Cosmos gRPC endpoint from cheqd-node to fetch data. Typically, this would be running on port 9090 on a cheqd-node instance.
You can either use public gRPC endpoints for the cheqd network (such as the default ones mentioned above), or point it to your own cheqd-node instance by enabling gRPC in the app.toml configuration file on a node:
[grpc]
# Enable defines if the gRPC server should be enabled.
enable = true
# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9090"
Note: If you're pointing a DID Resolver to your own node instance, by default cheqd-node instance gRPC endpoints are not served up with a TLS certificate. This means the useTls property would need to be set to false, unless you're otherwise using a load balancer that provides TLS connections to the gRPC port.
🧑💻 Building your own Docker image
Using Docker Build
You can build your own image using docker build
docker build --file docker/Dockerfile --target resolver . --tag did-resolver:local
Using Docker Compose Build
Uncomment the build section in the docker/docker-compose.yml file. This relies on the Dockerfile above but uses Docker Compose syntax to customise the build:
build:
context: ../
dockerfile: docker/Dockerfile
target: resolver
image: did-resolver:local
# image: ghcr.io/cheqd/did-resolver:${IMAGE_VERSION}
Make sure you comment out the pre-existing image property that pulls in a container image from Github Container Registry, as shown above.
You can also do just a build with:
docker-compose -f docker/docker-compose.yml --env-file docker/docker-compose.env build --no-cache
Running a custom built image
The instructions to configure and run the resolver are the same as when using the pre-built image.
🌐 Resolving did:cheqd via Universal Resolver
The resolver.cheqd.net API endpoint is run by the cheqd team and only handles did:cheqd credentials.
If you want to resolve DIDs from multiple DID methods, the Universal Resolver project provides a multi DID method resolver.
Using a pre-existing Universal Resolver endpoint
You can make resolution requests to a pre-existing Universal Resolver endpoint, such as dev.uniresolver.io, to their REST API endpoint:
curl -X GET https://resolver.cheqd.net/1.0/identifiers/did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47
Running your own Universal Resolver instance
You can also run your own instance of Universal Resolver, using the Docker Compose file of the project.
The Universal Resolver quick start guide provides instructions on how to do this:
git clone https://github.com/decentralized-identity/universal-resolver
cd universal-resolver/
docker-compose -f docker-compose.yml pull
docker-compose -f docker-compose.yml up
🧪 Running tests
This repository has two kinds of tests:
- Unit tests: Test coverage for internal functions and utilities
- Integration tests: Test coverage for a built version of this software with the ledger.
Prerequisites
Tests are written in Ginkgo, a behaviour-driven test framework for Golang.
To install Ginkgo, run the following command:
go install github.com/onsi/ginkgo/v2/ginkgo@latest
Execute unit tests with Ginkgo
Unit tests can be executed without running a Docker container. To execute all unit tests, use the following command:
ginkgo -r --tags unit --race --randomize-all --randomize-suites --keep-going --trace
The unit tag is specified to only run unit tests.
Execute integration tests with Ginkgo
To run integration tests, it's necessary to have a instance of this DID Resolver running. The easiest way to do this is to use the Docker Compose file under the tests directory, with a few modifications.
If you don't have an already-built Docker image
To build a local image for testing, uncomment the build section in the Docker Compose file. You can modify the build section according to your needs:
build:
context: ../
dockerfile: docker/Dockerfile
target: resolver
If you do have an already-built Docker image
Alternatively, if you want to run tests using an already-built image, just change the image name and tag in the image line in the Docker Compose file:
# image: cheqd/did-resolver:staging-latest
image: cheqd/did-resolver:local
Run the test Docker container
Use Docker Compose to bring the container up (for both scenarios above):
docker compose -f tests/docker-compose-testing.yml up --detach
Execute the integration tests
You can execute the tests as long as you have Ginkgo CLI installed, which targets the tests towards the running Docker container:
ginkgo -r --tags integration --race --randomize-suites --keep-going --trace
Note: By default, the tests target localhost:8080 as the port where it expects the running DID Resolver instance for testing. If your running instance is at a different address, you can override this by setting a value for the TEST_HOST_ADDRESS environment variable before executing the Ginkgo test suite.
export TEST_HOST_ADDRESS="where.is.did.resolver.running:port"
You can also do this inline without exporting the value:
TEST_HOST_ADDRESS="where.is.did.resolver.running:port" ginkgo -r --tags integration --race --randomize-suites --keep-going --trace
(Alternative) Executing tests with Github Actions
All tests are run automatically by the Github Actions test workflow in this repository. Use that workflow for inspiration if you want to customise the test execution; or Ginkgo documentation on how to customise test execution.
You can also directly execute the Github Actions locally using nektos/act.
📖 Documentation
Further documentation on cheqd DID Resolver is available on the cheqd Identity Documentation site. This includes instructions on how to do custom builds using Dockerfile / Docker Compose.
🐞 Bug reports & 🤔 feature requests
If you notice anything not behaving how you expected, or would like to make a suggestion / request for a new feature, please create a new issue and let us know.
💬 Community
Our Discord server is the primary chat channel for the open-source community, software developers, and node operators.
Please reach out to us there for discussions, help, and feedback on the project.
🙋 Find us elsewhere
