Skip to content

Add optional service endpoint discovery extension #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chongkan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add optional service endpoint discovery extension #43

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions did-pkh-method-draft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,81 @@ intended for local-only usage.
No deletion possible. `did:pkh` DID Documents, like [`did:key`] documents,
are intended for local-only usage.

## Service Endpoint Discovery (Optional Extension)

The core `did:pkh` method is generative and does not include service endpoints.
However, implementations MAY extend the resolved DID Document with service
endpoints discovered from external sources. This section defines a standard
mechanism for this extension.

### Motivation

Service endpoints enable credential exchange, encrypted messaging, and domain
verification. Without them, `did:pkh` holders can authenticate and sign, but
cannot be discovered for richer interactions (e.g., "send a VP request to this
DID").

### Discovery via Well-Known endpoint

A `did:pkh` resolver MAY query a well-known endpoint to discover service
endpoints for a given blockchain address:

```
GET https://<service-registry>/.well-known/did-pkh-services/<caip-10-address>
```

The response is a JSON array of [DID Core services](https://www.w3.org/TR/did-core/#services):

```json
[
{
"id": "#didcomm-1",
"type": "DIDCommMessaging",
"serviceEndpoint": {
"uri": "https://example.com/didcomm",
"accept": ["didcomm/v2"]
}
},
{
"id": "#credential-exchange",
"type": "CredentialExchange",
"serviceEndpoint": "https://example.com/presentations"
}
]
```

The resolver appends these to the generated DID Document's `service` array.

### Discovery via linked DID

Alternatively, if the resolver supports `alsoKnownAs` resolution (see above),
service endpoints can be inherited from the linked DID. For example:

1. Resolve `did:pkh:solana:...:CKg5d12J...`
2. Follow `alsoKnownAs` → `did:sns:alice.sol`
3. Resolve `did:sns:alice.sol` and extract its service endpoints
4. The `did:pkh` holder's services are those of the linked DID

This approach requires no additional infrastructure — the linked DID provides
the service discovery.

### Resolution options

The `resolutionOptions` parameter MAY include:

| Option | Type | Description |
|---|---|---|
| `serviceDiscovery` | boolean | Enable/disable service endpoint discovery (default: false) |
| `serviceRegistryUrl` | string | URL of the well-known service registry |

When `serviceDiscovery` is false (default), the DID Document is purely
generative — identical to the current behavior. This preserves backwards
compatibility.

> NOTE: Service endpoint discovery is OPTIONAL and non-normative. It does not
> change the core `did:pkh` resolution algorithm. Implementations that do not
> support this extension produce the same DID Documents as before.

## Security & Privacy Considerations (non-normative)

There are a number of security and privacy considerations that implementers
Expand Down