Skip to content

Commit b013dd0

Browse files
stevenjCrypto2099Ryun1rphair
authored
CIP-0114? | CBOR Tags Registry (#752)
* docs(Tags): Add draft CIP and example registry to demonstrate a potential solution for the CPS problem statement * docs(Tags): fix spelling * docs(Tags): Add link to discussions * Update CIP-xxxx/README.md Co-authored-by: Adam Dean <[email protected]> * Update CIP-xxxx/README.md Co-authored-by: Ryan Williams <[email protected]> * Update CIP-xxxx/README.md Co-authored-by: Robert Phair <[email protected]> * Update CIP-xxxx/README.md Co-authored-by: Robert Phair <[email protected]> * fix(Tags): Reference the related CPS correctly * docs(Tags): Add references section * fix(Tags): Update acceptance criteria * fix(Tags): Renumber the CIP directory to match assigned number * fix(Tags): Date and reference * fix(Tags): Cleanup references in registry.json and the json schema for it * docs(Tags): Add note that unregistered tags MUST NOT be used. * Update CIP-0114/README.md Co-authored-by: Ryan Williams <[email protected]> --------- Co-authored-by: Adam Dean <[email protected]> Co-authored-by: Ryan Williams <[email protected]> Co-authored-by: Robert Phair <[email protected]>
1 parent 1d771f0 commit b013dd0

File tree

3 files changed

+262
-0
lines changed

3 files changed

+262
-0
lines changed

‎CIP-0114/README.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
CIP: 114
3+
Title: CBOR Tags Registry
4+
Status: Proposed
5+
Category: Tools
6+
Authors:
7+
- Steven Johnson <[email protected]>
8+
Implementors: N/A
9+
Discussions:
10+
- https://github.com/cardano-foundation/CIPs/pull/752
11+
Created: 2020-01-25
12+
License: CC-BY-4.0
13+
---
14+
15+
## Abstract
16+
17+
Cardano typically uses CBOR to encode structured data.
18+
For example, the Block data and individual transactions are all CBOR encoded.
19+
20+
CIPs define many of the individual data structures used by both the Ledger and Metadata attached to transactions.
21+
This CIP defines a set of policies for the creation and maintenance of new CBOR tags for Cardano Data structures.
22+
It also collates a list of all currently defined Tags for easy reference.
23+
Finally, it recommends best practice for registering those Tags with IANA.
24+
25+
## Motivation: why is this CIP necessary?
26+
27+
This CIP is motivated by the problems outlined in [CPS-0014].
28+
29+
## Specification
30+
31+
[CBOR] defines a schemaless method of encoding data.
32+
Part of that specification (3.4) defines how generic data can be tagged to assist in the proper interpretation of the encoded data.
33+
Currently all Cardano data structures in both the Ledger and metadata do not widely use Tags.
34+
Nor is there any standardized way to create a new tag for a Cardano data structure.
35+
36+
[IANA] maintains a registry of all [CBOR] Tags.
37+
Anyone can submit a request to register a tag in the range of 32768-18446744073709551615.
38+
These are known as *First Come First Served* tags.
39+
To register a tag, an applicant must demonstrate where the Tag is defined, and also the format of the data.
40+
If the data structure is defined by a CIP, the natural place to define its Tag is also in a CIP.
41+
42+
### Defining Tags
43+
44+
Tags can be defined for any data structure defined by a CIP or commonly used by Cardano.
45+
Examples of commonly used data structures could be those encoded inside the Cardano block or transaction.
46+
Tags should be defined by the following process:
47+
48+
1. If a [CBOR] tag is desired for an application, first the applicant MUST check that one does not already exist.
49+
If it does, then the pre-existing TAG must be used, as well as the defined canonical encoding.
50+
This is to prevent redundant and wasteful re-tagging of the same data structures.
51+
2. Otherwise the application may define a [CBOR] Tag for the necessary data structures as follows:
52+
1. The CIP which defines the data structure can also define a Tag and its encoding in [CBOR]. **(Preferred)**
53+
2. Alternatively, if the data structure is already defined by a CIP, then there are two possibilities.
54+
1. The original CIP is edited to add Tags and their canonical representation in [CBOR].
55+
2. A supplementary CIP can be made that simply defines the TAG and canonical representation.
56+
Such a CIP would reference the original CIP to define the data structure itself.
57+
3. CIP authors would select an unused [CBOR] Tag in the [IANA Registry][IANA], and assign it to their data structure.
58+
1. The CIP should add to its "Path to Active" that the selected Tag/s have been successfully registered with [IANA].
59+
This allows the CIP to be edited with the final Tag once [IANA] have accepted and published the registration.
60+
4. CIP Authors would include in their PR an addition to the Cardano [CBOR Tag Registry](#tag-registry).
61+
62+
### Registration of TAGS with IANA
63+
64+
Registration of the Tag with IANA is the sole responsibility of the CIP author.
65+
CIPs should not proceed to Active if they define unregistered Tags on data structures.
66+
This is to prevent abuse of the Tag number space.
67+
68+
*NOTE: Tags defined by any CIP or marked as not registered with IANA in the `registry.json` MUST NOT be used outside of testing.
69+
Tags not registered with IANA are subject to change during the IANA registration process.*
70+
71+
### Usage of Tags within a CIP
72+
73+
CIPs, such as metadata CIPs can freely define when and how tags are used with any CBOR data structure.
74+
For example, a CIP may require that a particular field is always tagged.
75+
They may also define that a field need not be tagged if it is the typical data structure.
76+
Only less common or unusual data structures would be tagged in this case.
77+
A CIP may also define that Tags are not used, and only the canonical encoding.
78+
79+
### Canonical Encoding
80+
81+
When a Tag is defined, its Canonical encoding must also be defined.
82+
This is to ensure that all data that is tagged is encoded in a uniform manor.
83+
Even if a CIP does NOT use a tag, it should preferably use the canonical encoding for the data structure.
84+
This is to prevent fragmentation and confusion amongst compliant encoders and decoders of the various data structures.
85+
86+
If a pre-existing data structure is being tagged, then its most common current encoding should be used as the Canonical encoding.
87+
It should not be re-defined.
88+
89+
For example `ED25519-BIP32` public keys are commonly encoded as a byte array.
90+
The array is 32 bytes long with the most significant byte of the key appearing first in the array.
91+
If a Tag is defined for this public key, it should simply define the Tag.
92+
Its Canonical encoding MUST follow this common encoding scheme.
93+
94+
If a CIP does not refer to a Tag, nor the Canonical encoding specification for the data structure,
95+
AND it does not define an alternative encoding.
96+
Then the application implementing the encoding should assume it is encoded canonically.
97+
This helps ensure backward compatibility with pre-existing CIPs where Tags are not used.
98+
99+
### Tag Registry
100+
101+
Similar to [CIP-0010] this CIP defines a registry of all known tags.
102+
The format of the registry is defined by the json schema: [CIP Tag Registry Schema].
103+
New entries MUST be added to the [CIP Tag Registry] in a PR for a CIP that first defines a new CBOR Tag.
104+
They MUST be updated when the Tag is accepted or rejected by IANA.
105+
The registry clearly notes if the tag is currently known to be registered or not.
106+
If a Tag is not yet registered then any implementor must be aware that its possible the Tag number could change and is not final.
107+
Unregistered tags MUST not be used in any main net on-chain metadata or data structures.
108+
They should only be used for testing purposes until registration is complete.
109+
110+
## Rationale: how does this CIP achieve its goals?
111+
112+
Creating a [registry][CIP Tag Registry] for `CIP Tag` values has the following benefit:
113+
114+
1) It makes it easy for developers to know which `CIP Tags` to use, and if they have been registered or not.
115+
2) It makes it easy to avoid collisions with other standards that use CIP Tags.
116+
3) It helps CIP authors to find appropriate CIP tags for their use case, or to define new tags.
117+
118+
The process for defining and registering Tags should help provide clarity about how a CIP tag can be defined.
119+
It also provides clarity on the responsibility CIP authors have to register the tags they create.
120+
If a CIP author is not prepared to take on that responsibility they should not create a Tag.
121+
122+
## Path to Active
123+
124+
### Acceptance Criteria
125+
126+
- [ ] [CPS-0014] is accepted.
127+
- [ ] At least 1 CIPs are accepted into the Tag registry for historical tags.
128+
- [ ] At least 1 CIPs are accepted into the Tag registry for new tags.
129+
- [ ] At least 3 CIPs of any kind are accepted into the Tag registry.
130+
131+
### Implementation Plan
132+
133+
- [ ] Author to write the first CBOR tag CIP.
134+
135+
## References
136+
137+
- [CPS-0014 - Register of CBOR Tags for Cardano Data structures][CPS-0014]
138+
- [RFC8949 - Concise Binary Object Representation (CBOR)][CBOR]
139+
- [IANA CBOR Tag Registry][IANA]
140+
141+
## Copyright
142+
143+
This CIP is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode)
144+
145+
[CPS-0014]: https://github.com/cardano-foundation/CIPs/tree/master/CPS-0014
146+
[CBOR]: https://datatracker.ietf.org/doc/rfc8949/
147+
[IANA]: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
148+
[CIP Tag Registry Schema]: ./registry.schema.json
149+
[CIP Tag Registry]: ./registry.json

‎CIP-0114/registry.json

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
[
2+
{
3+
"cbor_tag": 32771,
4+
"iana_registered": false,
5+
"description": "ED25519-BIP32 Private Key",
6+
"cip": "CIP-0115"
7+
},
8+
{
9+
"cbor_tag": 32772,
10+
"iana_registered": false,
11+
"description": "ED25519-BIP32 Extended Private Key",
12+
"cip": "CIP-0115"
13+
},
14+
{
15+
"cbor_tag": 32773,
16+
"iana_registered": false,
17+
"description": "ED25519-BIP32 public-key",
18+
"cip": "CIP-0115"
19+
},
20+
{
21+
"cbor_tag": 32774,
22+
"iana_registered": false,
23+
"description": "ED25519-BIP32 Signature",
24+
"cip": "CIP-0115"
25+
}
26+
]

‎CIP-0114/registry.schema.json

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema",
3+
"$id": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0114/registry.schema.json",
4+
"type": "array",
5+
"title": "CBOR Tag Registry",
6+
"description": "JSON schema for CBOR Tag registry",
7+
"default": [],
8+
"examples": [
9+
[
10+
{
11+
"cbor_tag": 32773,
12+
"iana_registered": false,
13+
"description": "ED25519-BIP32 public-key",
14+
"cip": "CIP-0115"
15+
},
16+
{
17+
"cbor_tag": 32774,
18+
"iana_registered": false,
19+
"description": "ED25519-BIP32 Signature",
20+
"cip": "CIP-0115"
21+
}
22+
]
23+
],
24+
"additionalItems": false,
25+
"items": {
26+
"$id": "#/items",
27+
"anyOf": [
28+
{
29+
"$id": "#/items/anyOf/0",
30+
"type": "object",
31+
"title": "The first anyOf schema",
32+
"description": "An entry in the CBOR Tag registry",
33+
"default": {},
34+
"examples": [
35+
{
36+
"cbor_tag": 32771,
37+
"iana_registered": false,
38+
"description": "ED25519-BIP32 Private Key",
39+
"cip": "CIP-xxxx"
40+
}
41+
],
42+
"required": [
43+
"cbor_tag",
44+
"iana_registered",
45+
"description"
46+
],
47+
"properties": {
48+
"cbor_tag": {
49+
"$id": "#/items/anyOf/0/properties/cbor_tag",
50+
"type": "integer",
51+
"title": "The CBOR Tag number",
52+
"examples": [
53+
32771
54+
]
55+
},
56+
"iana_registered": {
57+
"$id": "#/items/anyOf/0/properties/iana_registered",
58+
"type": "boolean",
59+
"title": "Is the tag registered with IANA. Unregistered tags must not be used as they are subject to change.",
60+
"default": false,
61+
"examples": [
62+
true
63+
]
64+
},
65+
"description": {
66+
"$id": "#/items/anyOf/0/properties/description",
67+
"type": "string",
68+
"title": "The CBOR tag description",
69+
"default": "",
70+
"examples": [
71+
"ED25519-BIP32 Private Key"
72+
]
73+
},
74+
"cip": {
75+
"$id": "#/items/anyOf/0/properties/cip",
76+
"type": "string",
77+
"title": "The CIP which defines the Tag and its canonical encoding",
78+
"examples": [
79+
"CIP-0115"
80+
]
81+
}
82+
},
83+
"additionalProperties": true
84+
}
85+
]
86+
}
87+
}

0 commit comments

Comments
 (0)