Skip to content
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

Jump to bottom

CIP-0072 | Off-chain schema versioning and schema adjustments #612

Merged
merged 25 commits into from
Nov 28, 2023
+212 −203
Merged

CIP-0072 | Off-chain schema versioning and schema adjustments #612

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
7c08755
Specify hashing algorithm for rootHash calculation
Oct 23, 2023
a6e01e5
Add off-chain version property
Oct 23, 2023
94e8bbb
Update categories with Lace DApp Store category list
Oct 23, 2023
e1cd6a0
Add DApp screenshot and company detail fields
Oct 24, 2023
e23c91f
Remove duplicated/ambiguous website property
Oct 25, 2023
20c45cd
Add some property length constraints and describe image requirements
Oct 25, 2023
0f47639
Specify property length limit for the rest `social` props
Oct 26, 2023
c0d5c6d
Fix a typo
Oct 27, 2023
d99faad
Enhanced the regex for URLs to be more permissive by allowing ipfs an…
danielmain Nov 2, 2023
32f259e
Removed extra signature in the on-chain metadata
danielmain Nov 9, 2023
9ce8444
Applied suggestions to have flexible social links
danielmain Nov 9, 2023
348186b
Logo and screenshots gives you the posibility to add base64 images an…
danielmain Nov 9, 2023
e45f830
Added examples using the new schema
danielmain Nov 9, 2023
7feba6a
Follow semver for all versions
danielmain Nov 9, 2023
bd7de75
Removed optional links, images only via base64. Added 3 new fields
danielmain Nov 10, 2023
47fd34a
Changed some descriptions and added some mandatory fields
danielmain Nov 10, 2023
0320ebe
Added screenshots as mandatory
danielmain Nov 13, 2023
1dfdec3
Removed ftp for links
danielmain Nov 13, 2023
e271e30
Added short description to be mandatory
danielmain Nov 13, 2023
60a9085
Applied suggestions after review
danielmain Nov 15, 2023
d296278
Bump version to 2.0.0 and removed schema topic in rationale
danielmain Nov 16, 2023
f2615d6
There is no point defining a schema if it can be violated 🤷‍
danielmain Nov 17, 2023
8713cfe
Applied suggestion, we are not signing the off-chain data anymore.
danielmain Nov 17, 2023
950e50e
URL settings simplified
danielmain Nov 21, 2023
b625f34
Fixed version to follow semver
danielmain Nov 21, 2023
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
16 changes: 4 additions & 12 deletions CIP-0072/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Stores and auditors should be able to follow the chain and find when a new dApp

### **On-chain dApp Registration Certificate**

The on-chain dApp registration certificate MUST follow canonical JSON and be serialised according to RFC 8785 (https://www.rfc-editor.org/rfc/rfc8785). This stipulation is to avoid any ambigiutines in the signature calculation.
The on-chain dApp registration certificate MUST follow canonical JSON and be serialised according to RFC 8785 (https://www.rfc-editor.org/rfc/rfc8785).
Copy link

Choose a reason for hiding this comment

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

Since we removed the signature, we don't need to be canonical anymore

Copy link
Contributor

Choose a reason for hiding this comment

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

removed 🙂. Thank you!


```json
{
Expand All @@ -63,12 +63,6 @@ The on-chain dApp registration certificate MUST follow canonical JSON and be ser
"type": {
"action": "REGISTER",
"comment": "New release adding zapping support."
},
"signature": {
"r": "27159ce7d992c98fb04d5e9a59e43e75f77882b676fc6b2ccb8e952c2373da3e",
"s": "16b59ab1a9e349cd68d232f7652f238926dc24a2e435949ebe2e402a6557cfb4",
"algo": "Ed25519−EdDSA",
"pub": "b384b53d5fe9f499ecf088083e505f40d2a6c123bf7201608494fdb89a051b80"
}
}
```
Expand All @@ -83,12 +77,10 @@ The on-chain dApp registration certificate MUST follow canonical JSON and be ser
- *`REGISTER`*: The certificate is asserting that the dApp is registered for the first time or is providing an update.
- *`DE_REGISTER`*: The certificate is asserting that the dApp is deprecated / archived. So, no further dApp's on-chain update is expected.

*`rootHash`*: The hash of the entire offchain metadata tree object. This hash is used by clients to verify the integrity of the metadata tree object. When reading a metadata tree object, the client should calculate the hash of the object and compare it with the `rootHash` property. If the two hashes don't match, the client should discard the object. The metadata tree object is a JSON object that contains the dApp's metadata. The metadata tree object is described in the next section. Please note that off-chain JSON must be converted into RFC 8765 canonical form before taking the hash!
*`rootHash`*: The blake2b-256 hash of the entire offchain metadata tree object. This hash is used by clients to verify the integrity of the metadata tree object. When reading a metadata tree object, the client should calculate the hash of the object and compare it with the `rootHash` property. If the two hashes don't match, the client should discard the object. The metadata tree object is a JSON object that contains the dApp's metadata. The metadata tree object is described in the next section. Please note that off-chain JSON must be converted into RFC 8765 canonical form before taking the hash!
Ryun1 marked this conversation as resolved.
Show resolved Hide resolved

*`metadata`*: An array of links to the dApp's metadata. The metadata is a JSON compatible RFC 8785 object that contains the dApp's metadata.

*`signature`*: The signature of the certificate. The publishers generate the signature is by first turning on-chain JSON into a canonical form (RFC 8765), hashing it with blake2b-256 and generating a signature of the hash. Stores / clients can verify the signature by repeating the process, they can use the public key to verify the signature of the certificate. Fields used for canonical JSON: ["subject", "rootHash", "metadata","type"]. Please note that a signature should be generated of blake2b-256 hash as a byte array, not as a hex represented string(!).

### On-chain Schemas

[On-chain CDDL for registration / de-registration (Version 1)](./version_1_onchain.cddl)
rphair marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -205,9 +197,9 @@ Release Name is a field, which dApp developers can use on top of Release Version
At the begining neither on-chain, nor off-chain JSON has been following RFC 8785 (canonical JSON) but we reached a point that, due to consistency checks, we need to take hash of both on-chain and off-chain and this forced us to stipulate that both on-chain and off-chain metadata documents need to be converted
according to RFC 8785 before taking a blake2b-256 hash of them.

### On-Chain Signature Scope
### Transaction Signature Scope

On-chain part has a signature, which has a role to verify that a certain dApp owner made changes. In the initial version, a blake2b-256 signature was needed only for `rootHash` but following discussion, due to security concerns, decision has been made that the signature should attest the whole on-chain canonical JSON except signature field itself (because it would end up in an infinite recursion).
As any transaction in cardano network has a signature, which has a role to verify that a certain dApp owner made changes.
Copy link
Collaborator

@Ryun1 Ryun1 Nov 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

What is the rationale behind relying on transaction witnesses rather than what was originally proposed?

For me, relying on transaction signatures just adds an extra step to the verification whilst also restricting the type of keys/crypto that can be used. I also liked the property that the one registering did not have to be the one creating and submitting the Tx.

Copy link
Contributor

Choose a reason for hiding this comment

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

Hi @Ryun1 thank u for the review

What is the rationale behind relying on transaction witnesses rather than what was originally proposed?

After evaluating the situation, my colleagues and I found it puzzling to require two signatures 🤷. I reached out to @matiwinnetou for clarification and discovered the additional signature was initially implemented because Blockfrost did not support witness signatures in transaction fetching a year ago. However, I personally believe that our decision should not be solely based on whether Blockfrost supports a feature or not. With tools like cardano-cli, cardano-wallet, Daedalus, and cardano-services that do support witness signatures, it seems more logical and efficient to make this CIP simpler by adhering to this available technology.

Just adds an extra step to the verification whilst also restricting the type of keys/crypto that can be used.

Indeed, our goal is to streamline the process. By focusing on simplification, we can avoid unnecessary steps in verification and avoid limiting the types of keys/crypto that can be used.

I also liked the property that the one registering did not have to be the one creating and submitting the Tx.

While this flexibility might seem advantageous, I view the requirement for the same key used in initial dApp registration for updates (such as domain changes or rebranding) as a beneficial feature. It adds a layer of security and consistency, ensuring that only authorized updates are made to a dApp.


### Who Is The Owner?

Expand Down
78 changes: 56 additions & 22 deletions CIP-0072/version_1_offchain.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type":"object",
"properties": {
"version": {
"type": "integer",
"minimum": 1,
"description": "Off-chain schema version"
},
"subject": {
"type":"string",
"minLength": 1,
Expand All @@ -11,63 +16,92 @@
},
"projectName": {
"type":"string",
"description": "A project name, e.g. My dApp."
"description": "A project name, e.g. My dApp.",
"maxLength": 40
},
"link": {
"type":"string",
"description": "Website presenting a dApp.",
"pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
},
"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])",
"maxLength": 200
},
"logo": {
"type":"string",
"description": "URL to the logo or the base64 encoded image."
"type": "string",
"description": "URL to the logo. Minimum resolution: 512x512px, supported formats: PNG/JPG/SVG, maximum file size: 0.5 MB",
rphair marked this conversation as resolved.
Show resolved Hide resolved
"maxLength": 1000
},
"categories": {
"type":"array",
"items": {
"type": "string",
"enum":["Games", "DeFi", "Gambling", "Exchanges", "Collectibles", "Marketplaces", "Social", "Other"]
"enum": ["DeFi", "Development", "Education", "Games", "Identity", "Marketplace", "NFT", "Other", "Security"]
rphair marked this conversation as resolved.
Show resolved Hide resolved
},
"description": "One or more categories. Category MUST be one of the following schema definition."
},
"screenshots": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])",
"maxLength": 1000,
rphair marked this conversation as resolved.
Show resolved Hide resolved
"description": "Minimum resolution: 1920x1080px, supported formats: PNG/JPG/SVG, maximum file size: 1 MB"
},
"description": "URLs to screenshots of DApp actual pages. We recommend to share screenshots from the dApp usage itself."
},
"social": {
"type":"object",
"properties": {
"website": {
"type":"string",
"description": "dApps website link.",
"pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
"companyName": {
"type": "string",
"description": "Name of the company developing/maintaining the dApp",
"maxLength": 50
},
"companyEmail": {
"type": "string",
"description": "Email of the company developing/maintaining the dApp",
"maxLength": 150,
"format": "email"
},
"companyWebsite": {
"type": "string",
"description": "Website of the company developing/maintaining the dApp",
"maxLength": 200,
"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])"
rphair marked this conversation as resolved.
Show resolved Hide resolved
},
"twitter": {
"X.com": {
"type":"string",
"description": "An optional Twitter link.",
"pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
"description": "An optional X.com link.",
"maxLength": 200,
"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])"
rphair marked this conversation as resolved.
Show resolved Hide resolved
},
"github": {
"type":"string",
"description": "An optional Github link.",
"pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
"maxLength": 200,
"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])"
rphair marked this conversation as resolved.
Show resolved Hide resolved
},
"discord": {
"type":"string",
"description": "An optional Discord link.",
"pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
"maxLength": 200,
Copy link
Contributor

Choose a reason for hiding this comment

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

What is the benefit by limiting this, if this is offchain?

Copy link
Collaborator

Choose a reason for hiding this comment

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

@marcin-mazurek I'd also like to know why this was added. From experience I know in the vast majority of cases it's a sensible limit, and also that the hard limit will make something fail at some future time. What is the actual risk for these values to have an arbitrary & potentially huge length?

"pattern": "((https?|ftp|ipfs|ipns):\/\/[\\u00C0-\\u017F-a-zA-Z0-9])"
rphair marked this conversation as resolved.
Show resolved Hide resolved
}
},
"required": ["website"]
"required": ["companyWebsite"]
},
rphair marked this conversation as resolved.
Show resolved Hide resolved
"description": {
"type": "object",
"properties": {
"short": {
"type": "string",
"description": "Short dApp description (no less than 40 and no longer than 168 characters).",
"description": "Short dApp description.",
"minLength": 40,
"maxLength": 168
},
"long": {
"type": "string",
"description": "An optional long dApp description (no less than 40 and no longer than 1008 characters).",
"description": "An optional long dApp description.",
"minLength": 40,
"maxLength": 1008
}
Expand Down Expand Up @@ -143,8 +177,8 @@
"purposes":{
"type":"array",
"items": {
"type": "string",
"enum":["SPEND", "MINT"]
"type": "string",
"enum":["SPEND", "MINT"]
},
"description": "Purpouses of the script, SPEND or MINT (notice it can be both for some modern Cardano languages)."
},
Expand Down Expand Up @@ -201,7 +235,7 @@
"link",
"social",
"categories",
"description"
"description",
"version"
]
}

9 changes: 1 addition & 8 deletions CIP-0072/version_1_onchain.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,4 @@ registration = {
de-registration = {
action: "DE_REGISTER",
? comment: string,
}

signature = {
r: string,
s: string,
algo: text .regexp "Ed25519-EdDSA",
pub: string,
}
}
39 changes: 1 addition & 38 deletions CIP-0072/version_1_onchain.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,49 +57,12 @@
"required":[
"action"
]
},
"signature":{
"description":"Signature of the blake2b-256 hash of whole canonical (RFC 8785) JSON document (except signature property).",
"type":"object",
"properties":{
"r":{
"type":"string",
"description":"A hex representation of the R component of the signature.",
"minLength": 64,
"maxLength": 64,
"pattern":"^[0-9a-fA-F]{64}$"
},
"s":{
"type":"string",
"description":"A hex representation of the S component of the signature.",
"minLength": 64,
"maxLength": 64,
"pattern":"^[0-9a-fA-F]{64}$"
},
"algo":{
"const":"Ed25519-EdDSA"
},
"pub":{
"type":"string",
"description":"A hex representation of the public key.",
"minLength": 64,
"maxLength": 64,
"pattern":"^[0-9a-fA-F]{64}$"
}
},
"required":[
"r",
"s",
"algo",
"pub"
]
}
},
"required":[
"subject",
"rootHash",
"type",
"signature"
"type"
]
}