mirror of
https://github.com/oceanprotocol/docs.git
synced 2024-11-26 19:49:26 +01:00
GITBOOK-487: Split the identifiers and metadata page
This commit is contained in:
Ana Loznianu
gitbook-bot
parent
85646a001a
commit
2408985b25
@ -40,11 +40,11 @@
|
||||
* [Roles](developers/contracts/roles.md)
|
||||
* [Pricing Schemas](developers/asset-pricing.md)
|
||||
* [Fees](developers/fees.md)
|
||||
* [Metadata](developers/contracts/metadata.md)
|
||||
* [Revenue](developers/contracts/revenue.md)
|
||||
* [Fractional Ownership](developers/fractional-ownership.md)
|
||||
* [Community Monetization](developers/community-monetization.md)
|
||||
* [Identifiers & Metadata](developers/Identifiers-Metadata.md)
|
||||
* [Metadata](developers/metadata.md)
|
||||
* [Identifiers](developers/identifiers.md)
|
||||
* [DDO Specification](developers/ddo-specification.md)
|
||||
* [Storage Specifications](developers/storage-specifications.md)
|
||||
* [Fine-Grained Permissions](developers/Fine-Grained-Permissions.md)
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
---
|
||||
title: Identifiers & Metadata
|
||||
slug: /concepts/did-ddo/
|
||||
section: concepts
|
||||
description: >-
|
||||
Specification of decentralized identifiers for assets in Ocean Protocol using
|
||||
the DID & DDO standards.
|
||||
---
|
||||
|
||||
# Identifiers & Metadata
|
||||
|
||||
### Identifiers
|
||||
|
||||
In Ocean, we use decentralized identifiers (DIDs) to identify your asset within the network. Decentralized identifiers (DIDs) are a type of identifier that enables verifiable, decentralized digital identity. In contrast to typical, centralized identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID, the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject.
|
||||
|
||||
A DID in Ocean looks like this:
|
||||
|
||||
```
|
||||
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
The part after `did:op:` is the ERC721 contract address(in checksum format) and the chainId (expressed as a decimal) the asset has been published to:
|
||||
|
||||
```js
|
||||
const checksum = sha256(ERC721 contract address + chainId)
|
||||
console.log(checksum)
|
||||
// 0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
DIDs in ocean follow [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
|
||||
|
||||
{% embed url="https://www.youtube.com/watch?t=95s&v=I06AUNt7ee8" %}
|
||||
What is a DID and DDO?
|
||||
{% endembed %}
|
||||
|
||||
### Metadata
|
||||
|
||||
#### Overview
|
||||
|
||||
This document describes how Ocean assets follow the DID/DDO specification, such that Ocean assets can inherit DID/DDO benefits and enhance interoperability. DIDs and DDOs follow the [specification defined by the World Wide Web Consortium (W3C)](https://w3c-ccg.github.io/did-spec/).
|
||||
|
||||
Decentralized identifiers (DIDs) are a type of identifier that enable verifiable, decentralized digital identity. Each DID is associated with a unique entity, and DIDs may represent humans, objects, and more.
|
||||
|
||||
A DID Document (DDO) is a JSON blob that holds information about the DID. Given a DID, a _resolver_ will return the DDO of that DID.
|
||||
|
||||
#### Rules for DID & DDO
|
||||
|
||||
An _asset_ in Ocean represents a downloadable file, compute service, or similar. Each asset is a _resource_ under the control of a _publisher_. The Ocean network itself does _not_ store the actual resource (e.g. files).
|
||||
|
||||
An _asset_ has a DID and DDO. The DDO should include [metadata](did-ddo.md#metadata) about the asset, and define access in at least one [service](did-ddo.md#services). Only _owners_ or _delegated users_ can modify the DDO.
|
||||
|
||||
All DDOs are stored on-chain in encrypted form to be fully GDPR-compatible. A metadata cache like _Aquarius_ can help in reading, decrypting, and searching through encrypted DDO data from the chain. Because the file URLs are encrypted on top of the full DDO encryption, returning unencrypted DDOs e.g. via an API is safe to do as the file URLs will still stay encrypted.
|
||||
|
||||
#### Publishing & Retrieving DDOs
|
||||
|
||||
The DDO is stored on-chain as part of the NFT contract and stored in encrypted form using the private key of the _Provider_. To resolve it, a metadata cache like _Aquarius_ must query the provider to decrypt the DDO.
|
||||
|
||||
Here is the flow:
|
||||
|
||||
<figure><img src="../.gitbook/assets/DDO Flow.jpg" alt=""><figcaption><p>DDO Flow</p></figcaption></figure>
|
||||
@ -10,7 +10,7 @@ The V4 smart contracts have been deployed across multiple [networks](../../disco
|
||||
|
||||
### [**Data NFTs**](data-nfts.md) **for Enhanced Data IP Management**
|
||||
|
||||
In Ocean V3, the publication of a dataset involved deploying an ERC20 "datatoken" contract along with relevant [metadata](metadata.md). This process allowed the dataset publisher to claim copyright or exclusive rights to the underlying Intellectual Property (IP). Upon obtaining 1.0 ERC20 datatokens for a particular dataset, users were granted a license to consume that dataset, utilizing the Ocean infrastructure by spending the obtained datatokens.
|
||||
In Ocean V3, the publication of a dataset involved deploying an ERC20 "datatoken" contract along with relevant [metadata](../metadata.md). This process allowed the dataset publisher to claim copyright or exclusive rights to the underlying Intellectual Property (IP). Upon obtaining 1.0 ERC20 datatokens for a particular dataset, users were granted a license to consume that dataset, utilizing the Ocean infrastructure by spending the obtained datatokens.
|
||||
|
||||
However, Ocean V3 faced limitations in terms of flexibility. It lacked support for different licenses associated with the same base IP, such as 1-day versus 1-month access, and the transferability of the base IP was not possible. Additionally, the ERC20 datatoken template was hardcoded, restricting customization options.
|
||||
|
||||
|
||||
@ -1,54 +0,0 @@
|
||||
# Metadata
|
||||
|
||||
|
||||
|
||||
Imagine you're searching for data on Spanish almond production within a dApp operating within the Ocean ecosystem, managed by a European fruit and nut association. This hypothetical dApp may host a vast collection of datasets, making it essential to have a way to identify the relevant ones. One effective approach is to have metadata associated with each dataset to serve as valuable information about the data itself.
|
||||
|
||||
Metadata plays a **crucial role** in asset **discovery**, providing essential information such as **asset type, name, creation date, and licensing details**. Each data asset can have a [decentralized identifier (DID)](../Identifiers-Metadata.md) that resolves to a DID document ([DDO](../ddo-specification.md)) containing associated metadata. The DDO is essentially [JSON](https://www.json.org/) filling in metadata fields. To understand working with OCEAN DIDs, you can refer to the [DID documentation](../Identifiers-Metadata.md). For a more comprehensive understanding of metadata structure, the [DDO Specification](../ddo-specification.md) documentation provides in-depth information.
|
||||
|
||||
In general, any dApp within the Ocean ecosystem is required to store metadata for every listed dataset. It's important to note that dApps do not necessarily need to possess the datasets themselves; they primarily focus on storing and managing the associated metadata. While specific metadata requirements may vary, certain fundamental pieces of metadata, including:
|
||||
|
||||
* **name**, e.g. “Largueta Almond Production: 1995 to 2005”
|
||||
* **dateCreated**, e.g. “2007–01–20”
|
||||
* **datePublished**, e.g. “2022–11–10T12:32:15Z”
|
||||
* **author**, e.g. “Spanish Almond Board”
|
||||
* **license**, e.g. “SAB Data License v4”
|
||||
* **price**, e.g. “0”
|
||||
* technical information about the **files**, such as the content type.
|
||||
|
||||
Other metadata might also be available. For example:
|
||||
|
||||
* **categories**, e.g. \[“agriculture”, “economics”]
|
||||
* **tags**, e.g. \[“Europe”, “Italy”, “nuts”, “almonds”]
|
||||
* **description**, e.g. “2002 Italian almond production statistics for 14 varieties and 20 regions.”
|
||||
* **additionalInformation** can be used to store any other facts about the asset.
|
||||
|
||||
|
||||
|
||||
```solidity
|
||||
/**
|
||||
* @dev setMetaData
|
||||
* Creates or update Metadata for Aqua(emit event)
|
||||
Also, updates the METADATA_DECRYPTOR key
|
||||
* @param _metaDataState metadata state
|
||||
* @param _metaDataDecryptorUrl decryptor URL
|
||||
* @param _metaDataDecryptorAddress decryptor public key
|
||||
* @param flags flags used by Aquarius
|
||||
* @param data data used by Aquarius
|
||||
* @param _metaDataHash hash of clear data (before the encryption, if any)
|
||||
* @param _metadataProofs optional signatures of entitys who validated data (before the encryption, if any)
|
||||
*/
|
||||
function set metadata(uint8 _metaDataState, string calldata _metaDataDecryptorUrl
|
||||
, string calldata _metaDataDecryptorAddress, bytes calldata flags,
|
||||
bytes calldata data,bytes32 _metaDataHash, metaDataProof[] memory _metadataProofs) external {
|
||||
require(
|
||||
permissions[msg.sender].updateMetadata,
|
||||
"ERC721Template: NOT METADATA_ROLE"
|
||||
);
|
||||
_setMetaData(_metaDataState, _metaDataDecryptorUrl, _metaDataDecryptorAddress,flags,
|
||||
data,_metaDataHash, _metadataProofs);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
@ -118,7 +118,7 @@ function removeFromCreateERC20List(address _allowedAddress) public {
|
||||
|
||||
### Metadata Updater
|
||||
|
||||
There is also a specific role for updating the metadata. The [Metadata](metadata.md) updater has the ability to update the information about the data asset (title, description, sample data etc) that is displayed to the user on the asset detail page within the market.
|
||||
There is also a specific role for updating the metadata. The [Metadata](../metadata.md) updater has the ability to update the information about the data asset (title, description, sample data etc) that is displayed to the user on the asset detail page within the market.
|
||||
|
||||
To add/remove a metadata updater, the manager can use the [addToMetadataList](https://github.com/oceanprotocol/contracts/blob/9e29194d910f28a4f0ef17ce6dc8a70741f63309/contracts/utils/ERC721RolesAddress.sol#L164)/[removeFromMetadataList](https://github.com/oceanprotocol/contracts/blob/9e29194d910f28a4f0ef17ce6dc8a70741f63309/contracts/utils/ERC721RolesAddress.sol#L183) functions from the ERC721RolesAddress.
|
||||
|
||||
|
||||
36
developers/identifiers.md
Normal file
36
developers/identifiers.md
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Identifiers & Metadata
|
||||
slug: /concepts/did-ddo/
|
||||
section: concepts
|
||||
description: >-
|
||||
Specification of decentralized identifiers for assets in Ocean Protocol using
|
||||
the DID & DDO standards.
|
||||
---
|
||||
|
||||
# Identifiers
|
||||
|
||||
### Identifiers
|
||||
|
||||
In Ocean, we use decentralized identifiers (DIDs) to identify your asset within the network. Decentralized identifiers (DIDs) are a type of identifier that enables verifiable, decentralized digital identity. In contrast to typical, centralized identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID, the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject.
|
||||
|
||||
A DID in Ocean looks like this:
|
||||
|
||||
```
|
||||
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
The part after `did:op:` is the ERC721 contract address(in checksum format) and the chainId (expressed as a decimal) the asset has been published to:
|
||||
|
||||
```js
|
||||
const checksum = sha256(ERC721 contract address + chainId)
|
||||
console.log(checksum)
|
||||
// 0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
DIDs in ocean follow [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
|
||||
|
||||
{% embed url="https://www.youtube.com/watch?t=95s&v=I06AUNt7ee8" %}
|
||||
What is a DID and DDO?
|
||||
{% endembed %}
|
||||
|
||||
###
|
||||
92
developers/metadata.md
Normal file
92
developers/metadata.md
Normal file
@ -0,0 +1,92 @@
|
||||
# Metadata
|
||||
|
||||
|
||||
|
||||
Imagine you're searching for data on Spanish almond production within a dApp operating within the Ocean ecosystem, managed by a European fruit and nut association. This hypothetical dApp may host a vast collection of datasets, making it essential to have a way to identify the relevant ones. One effective approach is to have metadata associated with each dataset to serve as valuable information about the data itself.
|
||||
|
||||
Metadata plays a **crucial role** in asset **discovery**, providing essential information such as **asset type, name, creation date, and licensing details**. Each data asset can have a [decentralized identifier (DID)](identifiers.md) that resolves to a DID document ([DDO](ddo-specification.md)) containing associated metadata. The DDO is essentially [JSON](https://www.json.org/) filling in metadata fields. To understand working with OCEAN DIDs, you can refer to the [DID documentation](identifiers.md). For a more comprehensive understanding of metadata structure, the [DDO Specification](ddo-specification.md) documentation provides in-depth information.
|
||||
|
||||
In general, any dApp within the Ocean ecosystem is required to store metadata for every listed dataset. It's important to note that dApps do not necessarily need to possess the datasets themselves; they primarily focus on storing and managing the associated metadata. While specific metadata requirements may vary, certain fundamental pieces of metadata, including:
|
||||
|
||||
* **name**, e.g. “Largueta Almond Production: 1995 to 2005”
|
||||
* **dateCreated**, e.g. “2007–01–20”
|
||||
* **datePublished**, e.g. “2022–11–10T12:32:15Z”
|
||||
* **author**, e.g. “Spanish Almond Board”
|
||||
* **license**, e.g. “SAB Data License v4”
|
||||
* **price**, e.g. “0”
|
||||
* technical information about the **files**, such as the content type.
|
||||
|
||||
Other metadata might also be available. For example:
|
||||
|
||||
* **categories**, e.g. \[“agriculture”, “economics”]
|
||||
* **tags**, e.g. \[“Europe”, “Italy”, “nuts”, “almonds”]
|
||||
* **description**, e.g. “2002 Italian almond production statistics for 14 varieties and 20 regions.”
|
||||
* **additionalInformation** can be used to store any other facts about the asset.
|
||||
|
||||
|
||||
|
||||
```solidity
|
||||
/**
|
||||
* @dev setMetaData
|
||||
* Creates or update Metadata for Aqua(emit event)
|
||||
Also, updates the METADATA_DECRYPTOR key
|
||||
* @param _metaDataState metadata state
|
||||
* @param _metaDataDecryptorUrl decryptor URL
|
||||
* @param _metaDataDecryptorAddress decryptor public key
|
||||
* @param flags flags used by Aquarius
|
||||
* @param data data used by Aquarius
|
||||
* @param _metaDataHash hash of clear data (before the encryption, if any)
|
||||
* @param _metadataProofs optional signatures of entitys who validated data (before the encryption, if any)
|
||||
*/
|
||||
function set metadata(uint8 _metaDataState, string calldata _metaDataDecryptorUrl
|
||||
, string calldata _metaDataDecryptorAddress, bytes calldata flags,
|
||||
bytes calldata data,bytes32 _metaDataHash, metaDataProof[] memory _metadataProofs) external {
|
||||
require(
|
||||
permissions[msg.sender].updateMetadata,
|
||||
"ERC721Template: NOT METADATA_ROLE"
|
||||
);
|
||||
_setMetaData(_metaDataState, _metaDataDecryptorUrl, _metaDataDecryptorAddress,flags,
|
||||
data,_metaDataHash, _metadataProofs);
|
||||
}TODO: Add information ab
|
||||
```
|
||||
|
||||
Overview
|
||||
|
||||
This document describes how Ocean assets follow the DID/DDO specification, such that Ocean assets can inherit DID/DDO benefits and enhance interoperability. DIDs and DDOs follow the [specification defined by the World Wide Web Consortium (W3C)](https://w3c-ccg.github.io/did-spec/).
|
||||
|
||||
Decentralized identifiers (DIDs) are a type of identifier that enable verifiable, decentralized digital identity. Each DID is associated with a unique entity, and DIDs may represent humans, objects, and more.
|
||||
|
||||
A DID Document (DDO) is a JSON blob that holds information about the DID. Given a DID, a _resolver_ will return the DDO of that DID.
|
||||
|
||||
|
||||
|
||||
Decentralized identifiers (DIDs) are a type of identifier that enable verifiable, decentralized digital identity. Each DID is associated with a unique entity, and DIDs may represent humans, objects, and more.
|
||||
|
||||
A DID Document (DDO) is a JSON blob that holds information about the DID. Given a DID, a _resolver_ will return the DDO of that DID.
|
||||
|
||||
#### Rules for DID & DDO
|
||||
|
||||
An _asset_ in Ocean represents a downloadable file, compute service, or similar. Each asset is a _resource_ under the control of a _publisher_. The Ocean network itself does _not_ store the actual resource (e.g. files).
|
||||
|
||||
An _asset_ has a DID and DDO. The DDO should include [metadata](did-ddo.md#metadata) about the asset, and define access in at least one [service](did-ddo.md#services). Only _owners_ or _delegated users_ can modify the DDO.
|
||||
|
||||
All DDOs are stored on-chain in encrypted form to be fully GDPR-compatible. A metadata cache like _Aquarius_ can help in reading, decrypting, and searching through encrypted DDO data from the chain. Because the file URLs are encrypted on top of the full DDO encryption, returning unencrypted DDOs e.g. via an API is safe to do as the file URLs will still stay encrypted.
|
||||
|
||||
#### Publishing & Retrieving DDOs
|
||||
|
||||
The DDO is stored on-chain as part of the NFT contract and stored in encrypted form using the private key of the _Provider_. To resolve it, a metadata cache like _Aquarius_ must query the provider to decrypt the DDO.
|
||||
|
||||
Here is the flow:
|
||||
|
||||
<figure><img src="../.gitbook/assets/DDO Flow.jpg" alt=""><figcaption><p>DDO Flow</p></figcaption></figure>
|
||||
|
||||
out:
|
||||
|
||||
|
||||
|
||||
* add details of the parameters of the setmetadata function
|
||||
* when you make the ddo, you build it as json then the provider encrypts it
|
||||
* Flags - info if it is encrypted or not. 
|
||||
* We use a certain ddo structure but nobody stops you to do your own ddo that has the structure you want. You need your own aqua
|
||||
* example on how to call it from ocean.py and ocean.js
|
||||
|
||||
@ -24,11 +24,8 @@ Read on, anon, if you are interested in the security details!
|
||||
These guys know what's up
|
||||
{% endembed %}
|
||||
|
||||
When you publish your asset as an NFT, then the URL/TX ID/CID required to access the asset is encrypted and stored as a part of the NFT's [DDO](../../developers/Identifiers-Metadata.md) on the blockchain. Buyers don't have access directly to this information, but they interact with the [Provider](https://github.com/oceanprotocol/provider#provider), which decrypts the DDO and acts as a proxy to serve the asset. 
|
||||
When you publish your asset as an NFT, then the URL/TX ID/CID required to access the asset is encrypted and stored as a part of the NFT's [DDO](../../developers/identifiers.md) on the blockchain. Buyers don't have access directly to this information, but they interact with the [Provider](https://github.com/oceanprotocol/provider#provider), which decrypts the DDO and acts as a proxy to serve the asset.
|
||||
|
||||
We recommend implementing a security policy that allows **only the Provider's IP address to access the file** and blocks requests from other unauthorized actors is recommended. Since not all hosting services provide this feature, **you must carefully consider the security features while choosing a hosting service.**
|
||||
|
||||
⚠️ **Please use a proper hosting solution to keep your files.** Systems like `Google Drive` are not specifically designed for this use case. They include various virus checks and rate limiters that prevent the `Provider` to download the asset once it was purchased.
|
||||
|
||||
|
||||
|
||||
⚠️ **Please use a proper hosting solution to keep your files.** Systems like `Google Drive` are not specifically designed for this use case. They include various virus checks and rate limiters that prevent the `Provider` to download the asset once it was purchased.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user