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

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

Merged
merged 25 commits into from
Nov 28, 2023
Merged

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

Show file tree
Hide file tree
Changes from all 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
92 changes: 48 additions & 44 deletions CIP-0072/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Category: Metadata
Authors:
- Bruno Martins <bruno.martins@iohk.io>
- Mateusz Czeladka <mateusz.czeladka@cardanofoundation.org>
- Daniel Main <daniel.main@iohk.io>
Implementors: ["Lace Wallet dApp Store", "DappsOnCardano dApp Store"]
Discussions:
- https://github.com/cardano-foundation/CIPs/pull/355
Expand Down Expand Up @@ -49,26 +50,21 @@ Stores and auditors should be able to follow the chain and find when a new dApp
- **`integrity`**: The dApp's off-chain metadata should match the metadata **anchored** on-chain.
- **`trust`**: The dApp's certificate should be signed by a trusted entity. It's up to the store/auditor to decide which entities are trusted and they should maintain and publish their own list of trusted entities. Although this entities might be well known, it's not the responsibility of this CIP to maintain this list. These entities could be directly associated with developer/publisher or not.

### **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.
### **On-chain dApp Registration**

```json
{
"subject": "b37aabd81024c043f53a069c91e51a5b52e4ea399ae17ee1fe3cb9c44db707eb",
"rootHash": "7abcda7de6d883e7570118c1ccc8ee2e911f2e628a41ab0685ffee15f39bba96",
"metadata": [
"https://foundation.app/my_dapp_7abcda.json"
"https://foundation.app/my_dapp_7abcda/tart/",
"7abcda7de6d883e7570118c1ccc8ee2e91",
"e4ea399ae17ee1fe3cb9c44db707eb/",
"offchain.json"
],
"type": {
"action": "REGISTER",
"comment": "New release adding zapping support."
},
"signature": {
"r": "27159ce7d992c98fb04d5e9a59e43e75f77882b676fc6b2ccb8e952c2373da3e",
"s": "16b59ab1a9e349cd68d232f7652f238926dc24a2e435949ebe2e402a6557cfb4",
"algo": "Ed25519−EdDSA",
"pub": "b384b53d5fe9f499ecf088083e505f40d2a6c123bf7201608494fdb89a051b80"
}
}
```
Expand All @@ -83,19 +79,17 @@ 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!

*`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.
*`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

*`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(!).
*`metadata`*: Chunks of URLs that make up the dApp's metadata are arranged in an array to accommodate the 64-character limit per chunk, allowing for the support of longer URLs. The metadata itself is a JSON object compatible with RFC 8785, containing detailed information about the dApp

### On-chain Schemas

[On-chain CDDL for registration / de-registration (Version 1)](./version_1_onchain.cddl)
[On-chain CDDL for registration / de-registration (Version 2.0.0)](./version_2.0.0_onchain.cddl)

which also can be expressed using JSON schema:

[dApp on-chain certificate JSON Schema (Version 1)](./version_1_onchain.json)
[dApp on-chain certificate JSON Schema (Version 2.0.0)](./version_2.0.0_onchain.json)

### Metadata Label

Expand All @@ -107,51 +101,65 @@ When submitting the transaction metadata pick the following value for `transacti

The dApp Registration certificate itself doesn't enforce a particular structure to the metadata you might fetch off-chain. However, we recommend that you use the following structure:

[Off-chain dApp Registration certificate schema (Version 1)](./version_1_offchain.json)
[Off-chain dApp Registration certificate schema (Version 2)](./version_2.0.0_offchain.json)

This schema describes the minimum required fields for a store to be able to display and validate your dApp. You can add any other fields you want to the metadata, but we recommend that you use at least the ones described above.
This schema describes the minimum required fields for a store to be able to display and validate your dApp.

### Example

```json
{
"subject": "9SYAJPNN",
"projectName": "My Project",
"link": "https://myProject.app",
"logo": "https://myProject.app/logo.png",
"social": {
"github": "https://mywebsite.com",
"twitter": "https://twitter.com/my_dapp",
"website": "https://github.com/my_dapp"
},
"categories": ["Games"],
"version": "1.0.0",
"subject": "abcdef1234567890",
"projectName": "My dApp",
"link": "https://www.exampledapp.com",
"companyName": "Amazing dApp Inc.",
"companyEmail": "contact@myamazingdapp.com",
"companyWebsite": "https://www.myamazingdapp.com",
"logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUAAA...",
"categories": ["DeFi", "Games"],
"screenshots": [
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."
],
"social": [
{
"name": "GitHub",
"link": "https://github.com/exampledapp"
},
{
"name": "Twitter",
"link": "https://twitter.com/exampledapp"
}
],
"description": {
"short": "A story rich game where choices matter. This game is very addictive to play :)"
"short": "This is a short description of the dApp, giving an overview of its features and capabilities."
},
"releases": [
{
"releaseNumber": "1.0.0",
"releaseName": "V1",
"releaseName": "Initial Release",
"securityVulnerability": false,
"comment": "First major release with all core features.",
"scripts": [
{
"id": "PmNd6w",
"version": 1
"id": "script1",
"version": "1.0.0"
}
]
}
],
"scripts": [
{
"id": "PmNd6w",
"name": "marketplace",
"purposes": ["SPEND"],
"id": "script1",
"name": "Example Script",
"purposes": ["SPEND", "MINT"],
"type": "PLUTUS",
"versions": [
{
"version": 1,
"version": "1.0.0",
"plutusVersion": 1,
"scriptHash": "711dcb4e80d7cd0ed384da5375661cb1e074e7feebd73eea236cd68192",
"contractAddress": "addr1wywukn5q6lxsa5uymffh2esuk8s8fel7a0tna63rdntgrysv0f3ms"
"scriptHash": "abc123"
}
]
}
Expand Down Expand Up @@ -205,9 +213,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 Expand Up @@ -255,10 +263,6 @@ some app that can attest validity and conformance to JSON schema - dApp Registra

We made a decision to change the schema so that scripts and releases are no longer required. This could help to get initial registration from dApp developers faster and some stores simply do not require dApps to add their scripts in order to be listed.

### Schema Version

We discussed and analyzed idea of schema version and or even whole CIP version. It turns out that CIP is already versioned by CIP-??? where ??? is version number. During this CIP being in `PROPOSED` state we reserve our right to make small changes to the schema / document, after CIP becomes active, it will require a new CIP. This is the current process, which other CIPs are also following.

### Tags

We briefly discussed tags and we will likely introduce tags in the future. An array of tags to help stores / dApp developers categories where their dApp should show. This will complement `categories` field.
Expand Down
105 changes: 0 additions & 105 deletions CIP-0072/version_1_onchain.json
View file
Open in desktop

This file was deleted.

Loading