Make a DID reachable over DIDComm

Add your mediator to a hosted DID’s document as a DIDComm service endpoint, so other parties can send the DID DIDComm v2.1 messages.

A DID document lists the service endpoints where the DID can be reached. A DIDCommMessaging endpoint names the mediator that relays DIDComm messages for it. Your VTA writes the endpoint into the DID’s log, and the appliance serves it. For how updates are published, see DID lifecycle.

A DID with no DIDComm endpoint gives other parties nowhere to send messages, even though they can resolve and verify it.

Use this guide when:

• A new application or agent DID needs to receive DIDComm messages.
• An existing hosted DID needs a DIDComm endpoint added or changed.

Prerequisites

• A VTA with a mediator configured, connected to PNM. See Deploy VTA appliance.
• Your appliance registered with your VTA under a server ID, my-webvh in these examples. See Create your first hosted DID.
• The admin role in the DID’s VTA context, my-app in these examples.

Add the endpoint to a new DID

Pass --mediator-service when you create the DID:

pnm did-mgmt dids create \
  --context my-app \
  --server  my-webvh \
  --path    my-agent \
  --mediator-service

Your VTA adds this service to the DID document, using the mediator configured on your VTA:

{
  "id": "did:webvh:Q1abc…:did.example.com:my-agent#vta-didcomm",
  "type": "DIDCommMessaging",
  "serviceEndpoint": [
    { "accept": ["didcomm/v2"], "uri": "<your-vta-mediator-did>" }
  ]
}

To add other service endpoints at the same time, pass them as a JSON array with --services. For example, to also link the DID to your website:

pnm did-mgmt dids create \
  --context my-app \
  --server  my-webvh \
  --path    my-agent \
  --mediator-service \
  --services '[{"id": "{DID}#website", "type": "LinkedDomains", "serviceEndpoint": "https://example.com"}]'

Your VTA replaces {DID} with the new DID once it is created, and adds each entry to the DID document as written. Wrap the JSON in single quotes so your shell passes it unchanged.

Add the endpoint to an existing DID

1. Open the DID’s current document in your editor:

   pnm did-mgmt dids edit --did did:webvh:Q1abc…:did.example.com:my-service

2. Add a service entry to the document, or add to the existing service array. Replace <mediator-did> with your mediator’s DID, and keep the document’s id unchanged:

   "service": [
     {
       "id": "did:webvh:Q1abc…:did.example.com:my-service#didcomm",
       "type": "DIDCommMessaging",
       "serviceEndpoint": [
         { "accept": ["didcomm/v2"], "uri": "<mediator-did>" }
       ]
     }
   ]

3. Save and close the editor. PNM shows the document diff and asks about each WebVH parameter.

4. Confirm the final prompt. Your VTA publishes a new signed version of the DID to the appliance.

To script the change instead, save the updated document to a file and pass it with --document updated-document.json --no-confirm.

Confirm

Test 1: latest log entry lists the DIDComm endpoint

The DID document of each version is in the state field of its log entry. Replace did.example.com with the host of your appliance’s WebVH URL:

curl -s "https://did.example.com/my-agent/did.jsonl" | tail -n 1 | jq '.state.service'

Expected output: an array that includes an entry with "type": "DIDCommMessaging" and your mediator’s DID as uri. A change can take up to 5 minutes to appear, because resolution responses are cached.

Troubleshooting

Next steps

• Troubleshoot DID resolution: check why a DID or its latest version does not resolve.
• Create and manage DIDs: other updates to a hosted DID.

Related

• DID lifecycle: how each new version is validated and served.
• Affinidi DIDComm Mediator: run or choose a mediator.