Skip to content

Commit f305b75

Browse files
cootrphairCrypto2099
authored
CIP-0155? | SRV Registry (cardano-foundation#1033)
* CIP-???? | SRV * Assigned CIP number 0155 * Addressed @Ryun1 editing comments * Addressed @perturbing editing comments * Use 'Decentralised Protocol' instead of DAP * Added rationale * removed leading zeroes from header CIP number * Update CIP-0155/README.md Co-authored-by: Adam Dean <[email protected]> * Addressed @Quantumplation's review comments * Addressed @abailly's review comments * Addressed @rphair's review comments * Added registry.json and its schema * Addressed @Crypto2099's review comment * Update CIP-0155/README.md Co-authored-by: Robert Phair <[email protected]> * Mithril team approval --------- Co-authored-by: Robert Phair <[email protected]> Co-authored-by: Adam Dean <[email protected]>
1 parent 0fe074e commit f305b75

File tree

3 files changed

+182
-0
lines changed

3 files changed

+182
-0
lines changed

‎CIP-0155/README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
CIP: 155
3+
Title: SRV registry
4+
Status: Proposed
5+
Category: Network
6+
Authors:
7+
- Marcin Szamotulski <[email protected]>
8+
Implementors: N/A
9+
Discussions:
10+
- Submission: https://github.com/cardano-foundation/CIPs/pull/1033
11+
Created: 2025-04-22
12+
License: CC-BY-4.0
13+
---
14+
15+
## Abstract
16+
17+
This CIP defines the procedure for assigning Service Record (SRV) prefixes for Cardano applications (like `cardano-node`, `mithril`, etc.).
18+
19+
This creates a means of sharing authoritative information between SPOs who deploy services and _decentralised protocol_ developers who write them.
20+
21+
## Motivation: why is this CIP necessary?
22+
23+
The **Cardano Ledger** allows the use of SRV records in the **SPO** registration certificate (see [register-stake-pool]).
24+
25+
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.
26+
27+
In this CIP, we propose to make them usable by decentralised applications running on `Cardano`.
28+
29+
30+
All involved parties (SPOs, decentralised protocol developers, etc) need to agree on SRV prefixes used by various decentralised protocols and thus a public registry governed by a public CIP process is required to foster decentralised protocols that co-exist with the **Cardano** network, like **Mithril** (see [CIP#137]).
31+
32+
We consider decentralised protocols as applications, which construct their own network and relay on ledger peers published on the block-chain. This include node implementations, overlay networks like Mithril, or Layer 2 protocols like Hydra.
33+
34+
### Problem
35+
36+
Bootstraping networks requires sharing information about available services.
37+
38+
Historically, this was done by sharing IP or DNS names and PORT numbers (note that `A` or `AAAA` records do not contain PORT numbers), but this approach has its limitations.
39+
SRV records were designed to make deployment independent of hard-coded service end-points (see [RFC#2782] or [cloudflare documentation][srv]). They include PORT numbers together with a DNS name (point to an `A` or `AAAA` record) together with `TTL`, priority, weight, and some other data.
40+
Thus they can be instrumental in `Cardano`, since relays are registered on the blockchain through the registration certificate.
41+
42+
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 decentralised protocol that requires constructing its own network.
43+
44+
SRV provides a mechanism for exposing decentralised protocols co-deployed with a node, like **mithril** or **hydra**.
45+
46+
Making such services discoverable is one of the key features addressed by this CIP.
47+
48+
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.
49+
50+
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.
51+
52+
Decentralised protocol developers SHOULD submit proposals to the SRV Prefix Registry, so SPOs, who deploy them, can have an authoritative information how to do it.
53+
54+
## Specification
55+
56+
### SRV Prefix Registry
57+
58+
The registry is available in `JSON` format [registry.json].
59+
60+
### SRV Prefix Semantics
61+
62+
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>`.
63+
64+
This design allows decentralised protocols 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.
65+
66+
Each prefix SHOULD start with `_cardano._tcp` or `_cardano._udp`, to avoid clashes with services not related to `Cardano`.
67+
68+
#### SRV Registry Rules
69+
70+
* Each decentralised protocol can have at most one entry in the registry.
71+
* A CIP process assigns new entries to [registry.json], after a careful consideration and consultation with all the involved parties (see #acceptance-criteria below).
72+
* Entries cannot be removed, but can be revoked by assigning a `Revoked` status.
73+
This can only happen if a decentralised protocol is no longer supported.
74+
75+
### Example
76+
77+
When registering a cardano pool on `example.com` domain using an `SRV` record, one should use:
78+
```shell
79+
cardano-cli latest stake-pool ... --multi-host-pool-relay example.com
80+
```
81+
(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).
82+
83+
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. Such a query might return:
84+
85+
```
86+
_cardano._tcp.example.com 86400 IN SRV 10 5 3001 cardano.example.com
87+
```
88+
From this, we learn that a Cardano node is available on port `3001` on IPs resolved by a regular DNS query to `cardano.example.com`.
89+
Refer to the [Cloudflare documentation][srv] for a deeper understanding of other fields.
90+
91+
92+
## Rationale: how does this CIP achieve its goals?
93+
94+
This CIP constructs a process to maintain SRV registry, and thus provides authritative information for SPOs and decentralised protocol developers.
95+
96+
97+
## Path to Active
98+
99+
### Acceptance Criteria
100+
101+
The CIP should be accepted by:
102+
103+
* [ ] [**Technical Steering Committee**][tsc]
104+
105+
And when there's no major objection from one of the currently involved parties:
106+
107+
* [x] [**Cardano-Node Team**][cardano-node] accepts the proposal
108+
* [ ] [**Amaru Team**][amaru] accepts the proposal
109+
* [ ] [**Gouroboros Team**][gouroboros] accepts the proposal
110+
* [ ] [**Hydra Team**][hydra] accepts the proposal
111+
* [x] [**Mithril Team**][mithril] accepts the proposal
112+
113+
### Implementation Plan
114+
115+
Each **Cardano** node implementation or other tools which rely on SRV records stored in the ledger should comply with this proposal,
116+
e.g. whenever obtaining _multi-pool relay information_ one needs to prepend a registered prefix before making an SRV query.
117+
118+
119+
## Copyright
120+
121+
This CIP is licensed under [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
122+
123+
[CIP#137]: ../CIP-0137
124+
[register-stake-pool]: https://developers.cardano.org/docs/operate-a-stake-pool/register-stake-pool
125+
[RFC#2782]: https://datatracker.ietf.org/doc/html/rfc2782
126+
[srv]: https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-srv-record/
127+
128+
[amaru]: https://github.com/pragma-org/amaru
129+
[cardano-node]: https://github.com/IntersectMBO/cardano-node
130+
[mithril]: https://github.com/input-output-hk/mithril
131+
[gouroboros]: https://github.com/blinklabs-io/gouroboros
132+
[tsc]: https://docs.intersectmbo.org/intersect-overview/intersect-committees/technical-steering-committee-tsc
133+
[hydra]: https://github.com/cardano-scaling/hydra
134+
[register-stake-pool]: https://developers.cardano.org/docs/operate-a-stake-pool/register-stake-pool/#generate-the-stake-pool-registration-certificate
135+
136+
[registry.json]: ./registry.json

‎CIP-0155/registry.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[
2+
{ "service": "cardano",
3+
"prefix": "_cardano._tcp",
4+
"status": "Active"
5+
},
6+
{ "name": "mithril.dmq",
7+
"prefix": "_dmq._mithril._cardano._tcp",
8+
"status": "Active"
9+
},
10+
{ "name": "mithril.aggregator",
11+
"prefix": "_aggregator._mithril._cardano._tcp",
12+
"status": "Active"
13+
}
14+
]

‎CIP-0155/registry.schema.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0155",
4+
"title": "SRV Registry",
5+
"description": "JSON schema for the SRV registry",
6+
"type": "array",
7+
"items": {
8+
"type": "object",
9+
"properties": {
10+
"service": {
11+
"type": "string",
12+
"description": "A unique identifier for the service name."
13+
},
14+
"prefix": {
15+
"type": "string",
16+
"description": "A unique SRV prefix.",
17+
"maxLength": 255
18+
},
19+
"status": {
20+
"type": "string",
21+
"description": "Status of the entry. Can be one of: \"Active\", \"Revoked\""
22+
}
23+
},
24+
"required": [
25+
"service",
26+
"prefix",
27+
"status"
28+
],
29+
"additionalProperties": false
30+
}
31+
}
32+

0 commit comments

Comments
 (0)