---
# System prepended metadata

title: UCAN Routing

---

# UCAN Routing

## Motivation

UCAN invocations address executing actors by [did:key][] identifiers which is great as they could provide invoked capabilities across various transports and addresses. However there is downside local IPFS node or a gateway MAY NOT know the address for the audience [did:key][].

## Proposal

#### did:key to did:dns mapping

We could embed [did:key][] to [did:dns][] mapping in UCAN "fct" field. This in turn could allow UCAN executor / router to resolve addrss for the given [did:key][] to forward invocation.

However this has several downsides:

1. Introduces extra indirection. Router now needs to:
      1. Fetch various DNS records (as per [did:dns] spec) to assemble DID document.
      2. Find routing address(es) in the DID document.

   Where any of those steps could fail.

2. DID document may change in the future making routing info inside the UCAN invalid.
3. Introduces additional complexity.


#### Routing capabilities

Alternatively we could borrow from Zero-Configuration [DNS Service Discovery (DNS-SD)][dns-sd] and define capabilities corresponding to service query and announcements.

UCAN base service MUST implement `service/info` capability that any client COULD invoke with own DID in `with` field in order to to obtain service (routing) info:

```interface
interface ServiceInfo {
  can: "service/info"
  with: DID // user did:key
}
```

Service MUST respond by delegating `service/register` capability to an issuer _(did:key of the iss that invoked `service/info`)_ with the routing information

```ts
interface ServiceProvide {
  can: "service/register",
  with: DID // service did:key
  capabilities: Link // provided capabilities
  at: Multiaddr[]
}
```

:::info
Delegated `service/register` capability is effectively a routing information for the service that had been signed by the `did:key` it belongs to. It is also a capability that can be invoked to register routing information with UCAN routing service.
:::

It may not be completely obivous but this allows "embedding routing" information in a UCAN. More specifically client could send **service/register** capability along with e.g. **store/add** capability to an arbitrary UCAN getway / router which in turn could:

1. Locally cache routing info for the "store/add" providing service with provided "service/register" capability.
2. Resolve routing info for "store/add" provider to route request to it.



[did:key]:https://w3c-ccg.github.io/did-method-key/
[did:dns]:https://danubetech.github.io/did-method-dns/
[dns-sd]:https://datatracker.ietf.org/doc/html/rfc6763#section-3