Skip to content

CIP-0155? | SRV Registry #1033

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
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

CIP-0155? | SRV Registry #1033

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
883c52c
CIP-???? | SRV
coot Apr 22, 2025
98adfd8
Assigned CIP number 0155
coot May 28, 2025
b2e1919
Addressed @Ryun1 editing comments
coot May 28, 2025
0d100bb
Addressed @perturbing editing comments
coot May 28, 2025
c278d26
Use 'Decentralised Protocol' instead of DAP
coot May 28, 2025
aa4fd70
Added rationale
coot May 29, 2025
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
133 changes: 133 additions & 0 deletions CIP-0155/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
---
CIP: 0155
Title: SRV registry
Status: Proposed
Category: Network
Authors:
- Marcin Szamotulski <[email protected]>
Implementors: N/A
Discussions:
- [PR](https://github.com/cardano-foundation/CIPs/pull/1033)
Created: 2025-04-22
License: CC-BY-4.0
---

## Abstract

This CIP defines the procedure for assigning Service Record (SRV) prefixes for Cardano applications (like `cardano-node`, `mithril`, etc.).

This means of sharing authoritative information between SPOs who deploy services and _decentralised protocol_ (DP) developers who write them.

## Motivation: why is this CIP necessary?

The **Cardano Ledger** allows the use of SRV records in the **SPO** registration certificate (see [register-stake-pool]).

In this CIP, we propose to make them usable by decentralised applications running on `Cardano`.

Having access to the ledger (either directly or through tools like `cardano-cli`) will allow decentralised protocols developers to construct networks based on registered relays.

All involved parties (SPOs, DP developers, etc) need to agree on SRV prefixes used by various DPs and thus a public registry governed by a public CIP process is required to foster DPs that co-exist with the **Cardano** network, like **Mithril** (see [CIP#137]).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
All involved parties (SPOs, DP developers, etc) need to agree on SRV prefixes used by various DPs and thus a public registry governed by a public CIP process is required to foster DPs that co-exist with the **Cardano** network, like **Mithril** (see [CIP#137]).
All involved parties (SPOs, protocol developers, etc) need to agree on SRV prefixes used by various protocols and thus a public registry governed by a public CIP process is required to foster protocols that co-exist with the **Cardano** network, like **Mithril** (see [CIP#137]).

Also, why not use the blockchain itself to store that information?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This gives greater flexibility to the SPOs and developers.


We consider DPs as applications, which construct their own network and relay on ledger peers published on the block-chain. This include node implementations, or 2nd-layer solutions like Mithril or Hydra.

### Problem

Bootstraping networks requires sharing information about available services.

Historically, this was done by sharing IP or DNS names and PORT numbers, but this approach has its limitations.

SRV records were designed to make deployment independent of hard-coded service end-points (see [RFC#2782]).

Thus they can be instrumental in `Cardano`, since relays are registered on the blockchain through the registration certificate.

By using SRV records in the registration certificate (which is supported by the `cardano-ledger`, but not by `cardano-node`), we wish to solve this problem not just for `Cardano` node implementation, but also for any DP that requires constructing its own network.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean that this is supported by the cardano-ledger but not the cardano-node? As in, there's a field in the SPO registration certificate for it, but the node doesn't actually use that to make SRV requests for peer discovery?

Copy link
Author

@coot coot Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As in, there's a field in the SPO registration certificate for it, but the node doesn't actually use that to make SRV requests for peer discovery?

Yes, you got it right :).


SRV provides a mechanism for exposing DPs co-deployed with a node, like **mithril** or **hydra**.

Making such services discoverable is one of the key features addressed by this CIP.

In this CIP, we propose prefixes for both **Cardano** and **Mithril**; in the future, other services can be registered through a CIP process, thus starting a registry of prefixes used by the **Cardano** ecosystem.

SPOs who deploy services need to configure their system according to the registry, e.g. SPO's cardano relays node MUST be available at `_cardano._tcp.<SPO_DOMAIN_NAME>`, as other nodes on the system will be looking at this address.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It sounds like this sentence is describing the current state, correct? i.e. already the SRV records used by SPOs are expected to / required to begin with _cardano._tcp; and this proposal just changes that from a singular value to a "pre"fix, so it can be extended for other services?

Or is this intended to be a breaking change, where there was no enforcement on the SRV record format so far, and this invalidates those, requiring them to be more consistent?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand this is the desired state. While it's possible today to register a stake pool with a SRV record, there's no particular requirement on the content of this record.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If so, and there's not already a standard / requirement of using the _cardano._tcp prefix, then this represents a much more disruptive change for SPOs, and should be addressed in the implementation plan.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It sounds like this sentence is describing the current state, correct? i

If one has an SRV record that uses a different semantics than what this CIP proposes, it will be broken. However, this doesn't affect cardano-node, as it's not being used. So from the cardano-node perspective: what used to be broken remains broken 😁.


DP developers SHOULD submit proposals to the SRV Prefix Registry, so SPOs, who deploy them, can have an authoritative information how to do it.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
DP developers SHOULD submit proposals to the SRV Prefix Registry, so SPOs, who deploy them, can have an authoritative information how to do it.
Protocol developers SHOULD submit proposals to the SRV Prefix Registry, so SPOs, who deploy them, can have an authoritative information how to do it.

That's where having the "prefix registry" on-chain would be quite helpful. For example, one could imagine a modification to the registry to be a governance action subject to SPOs voting because that's their remit.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Making such a link would be a mistake. Consider a syncing node: depending on the era it would see invalid SRV records depending at which stage of syncing it is. There is a fundamental difference between the stability of deployment configuration and the elasticity of blockchain-stored information.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand your argument: No matter what, if a node is syncing then the information about its peers it can get from the ledger is not current, possibly outdated, etc, so it cannot be used anyhow even in its current form without SRV records.
The information about the (valid) prefixes to use is orthogonal to this problem.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right that reconfiguration of relays does occur, but we don't see stake shifting much, which is even more important for a syncing node due to security reasons.

Note that once committed to a value, changing it would be impossible to do safely, as it would require reconfiguring DNS entries by all SPOs simultaneously.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don't understand how this invalidates my proposal, sorry. It's about storing and retrieving some information for the chain which is assumed to be safe. The DNS will need to be verified anyway hence my other proposal to sign those entries.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will matter for nodes that are syncing recent history (which is the most common scenario for syncing). The value cannot change on-chain, as using a published genesis snapshot will result in invalid domains if SPO switches to the new value in the meantime, and Daedalus nodes won't be able to sync. If they cannot change on-chain, why add the complexity of storing it there in the first place?


## Specification

### SRV Prefix Registry

| **service** | **scope** | **SRV prefix** | **Status** |
|:------------|:--------------| ------------------------------------:|:-----------|
| _cardano_ | | `_cardano._tcp` | Active |
| _mithril_ | _dmq_ | `_.dmq._mithril._cardano._tcp` | Active |
| _mithril_ | _aggregator_ | `_aggregator._mithril._cardano._tcp` | Active |

### SRV Prefix Semantics

When a **cardano** node implementation reads an SRV record from a ledger, it must add the _cardano_ prefix from the table above before making a DNS lookup, e.g. it should do a DNS query for `_cardano._tcp.<srv-record-from-ledger>`.

This design allows DPs to use SRV records registered in the ledger for different purposes, e.g. a **mithril** node can use them to learn about end-points of its network.

Each prefix SHOULD start with `_cardano._tcp` or `_cardano._udp`, to avoid clashes with services not related to `Cardano`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get the semantics of "start with" from context, but it's a bit unintuitive, as _cardano._tcp comes at the end. Would this be well understood well by someone more familiar with DNS than I am?

What should services that plan to be multi-chain use as a prefix? for example, if a decentralized bridge or multi-chain layer zero type protocol with Cardano support; Should they have their own prefix, and avoid this CIP process? or should they have different prefixes for different chains? etc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DNS entries are structured from the most particular to the most general, so mithril.cardano.tcp makes sense and we could imagine an entry for mithril.ergo.tcp for example.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Quantumplation for multi-chain services this process is focused only on cardano side of things, the other side ought to be managed by the other block-chain (unless it's also covered by the CIP process).


#### SRV Registry Rules

* Each DP can have at most one entry in the registry.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This this still relevant? In the example above, Mithril has two entries. Perhaps a bit of detail on what the definitions / intended use of service vs scope are would be helpful.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I'd be keen to remove scope, mithril just has two discoverable services. @jpraynaud are you fine with it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@coot, I guess that @Quantumplation asked for descriptions of the fields service and scope more than removing them.

However, we could remove the scope and create multiple services for Mithril that would lead to the same DNS entries if this makes more sense:

service SRV prefix Status
cardano _cardano._tcp Active
mithril.dmq _.dmq._mithril._cardano._tcp Active
mithril.aggregator _aggregator._mithril._cardano._tcp Active

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd keep it simple and not introduce notions which we're not certain will be helpful in the future. Once a need arises, we'll find an appropriate solution.

* A CIP process assigns new entries, after a careful consideration and consultation with all the involved parties (see #acceptance-criteria below).
* Entries cannot be removed, but can be revoked by assigning a `Revoked` status.
This can only happen if a DP is no longer supported.

### Example

When registering a cardano pool on `example.com` domain using an `SRV` record, one should use:
```shell
cardano-cli latest stake-pool ... --multi-host-pool-relay example.com
```
(see [register-stake-pool]); and configure SRV record at `_cardano._tcp.example.com` to point to **Cardano** relays, `_mithril._tcp.example.com` to point to **Mithril** relays (see [srv], currently under development).

A **Cardano** node implementation when retrieving information from a registration certificate from the ledger will receive `example.com` and it must prepend the `_cardano._tcp` prefix to make an SRV query.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you elaborate a bit this example, to show what the SRV query might return, and what the node might then do with it?

That's a little bit outside of scope for this CIP, as it's just repeating what DNS would do, but I think it would be helpful (and inspirational) to see the example carried through to its conclusion.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are good resources for that, e.g. https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-srv-record. I'll add a link.


It may as well append `.` to indicate it is a top-level query, resulting in querying the `_cardano._tcp.example.com.` domain.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you elaborate on why someone "may as well" do this?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We got this advice from @njd42, if I recall correctly, it will speed up a DNS query.



## Path to Active

### Acceptance Criteria

The CIP should be accepted by:

* [ ] [**Technical Steering Committee**][tsc]

And when there's no major objection from one of the currently involved parties:

* [ ] [**Amaru Team**][amaru] accepts the proposal
* [ ] [**Cardano-Node Team**][cardano-node] accepts the proposal
* [ ] [**Gouroboros Team**][gouroboros] accepts the proposal
* [ ] [**Hydra Team**][hydra] accepts the proposal
* [ ] [**Mithril Team**][mithril] accepts the proposal

### Implementation Plan

Each **Cardano** node implementation or other tools which rely on SRV records stored in the ledger should comply with this proposal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A little more detail here on "comply" would be helpful. What does it mean for Amaru, for example, to "comply" with this proposal?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It means to interpret the entries stored in the ledger according to this CIP, e.g. one needs to pretend _cardano._tcp to multi host pool relay information stored in the ledger (how srv's were called by ledger, don't ask me why the name is so complex).


## Rationale: how does this CIP achieve its goals?

This CIP constructs a process to maintain SRV registry, and thus provides authritative information for SPOs and DP developers.


## Copyright

This CIP is licensed under [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode

[CIP#137]: ../CIP-0137
[register-stake-pool]: https://developers.cardano.org/docs/operate-a-stake-pool/register-stake-pool
[RFC#2782]: https://datatracker.ietf.org/doc/html/rfc2782
[srv]: https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-srv-record/

[amaru]: https://github.com/pragma-org/amaru
[cardano-node]: https://github.com/IntersectMBO/cardano-node
[mithril]: https://github.com/input-output-hk/mithril
[gouroboros]: https://github.com/blinklabs-io/gouroboros
[tsc]: https://docs.intersectmbo.org/intersect-overview/intersect-committees/technical-steering-committee-tsc
[hydra]: https://github.com/cardano-scaling/hydra
[register-stake-pool]: https://developers.cardano.org/docs/operate-a-stake-pool/register-stake-pool/#generate-the-stake-pool-registration-certificate