mirror of
https://github.com/oceanprotocol/docs.git
synced 2024-11-26 19:49:26 +01:00
GITBOOK-418: Datatokens Templates page and updates to the metadata
This commit is contained in:
Ana Loznianu
gitbook-bot
parent
dfa50b6281
commit
fcb966bc4a
@ -36,8 +36,8 @@
|
||||
* [Datatokens](developers/contracts/datatokens.md)
|
||||
* [Data NFTs and Datatokens](developers/contracts/datanft-and-datatoken.md)
|
||||
* [Community monetization](developers/contracts/community-monetization.md)
|
||||
* [Metadata](developers/contracts/metadata.md)
|
||||
* [Datatoken Templates](developers/contracts/datatoken-templates.md)
|
||||
* [Metadata](developers/contracts/metadata.md)
|
||||
* [Access Control Tools](developers/contracts/access-control-tools.md)
|
||||
* [Revenue](developers/contracts/revenue.md)
|
||||
* [Roles](developers/contracts/roles.md)
|
||||
|
||||
@ -22,9 +22,9 @@ If you’re part of an established organization or a growing startup, you’ll a
|
||||
|
||||
**In short, if you have data to sell, then Ocean V4 gives you superpowers to scale up and manage your data project. We hope this enables you to bring your data to new audiences and increase your profits.**
|
||||
|
||||
### 2. Running Your Own Data Marketplace
|
||||
### 2. Running Your Own Data dApp
|
||||
|
||||
We have always been super encouraging of anyone who wishes to fork Ocean Market and make their own data marketplace. With the V4 release, we have taken this to the next level and introduced more opportunities and even more fee customization options.
|
||||
We have always been super encouraging of anyone who wishes to build a dApp on top of Ocean or to fork Ocean Market and make their own data marketplace. With the V4 release, we have taken this to the next level and introduced more opportunities and even more fee customization options.
|
||||
|
||||
Unlike in V3, where the fee collection was limited to the consume action with a fixed value of 0.1%, V4 empowers marketplace operators like yourself to have greater flexibility and control over the fees you can charge. This means you can tailor the fee structure to suit your specific needs and ensure the sustainability of your project. **V4 smart contracts enable you to collect a fee not only in consume, but also in fixed-rate exchange, also you can set the fee value.** For more detailed information regarding the fees, we invite you to visit the [fees](../fees.md) page.
|
||||
|
||||
|
||||
@ -1,14 +1,49 @@
|
||||
# Templates
|
||||
---
|
||||
description: Discover all about the extensible & flexible smart contract templates.
|
||||
---
|
||||
|
||||
### TemplateIds
|
||||
# Datatoken Templates
|
||||
|
||||
Each data NFT or a datatoken is cloned from pre-defined template contracts. The _templateId_ parameter refers to the template from which a data NFT or datatoken is created. The templateId can be set while creating data NFT/datatoken. The templateId is stored in the code of the smart contract and can be retrived using `getId()` function. Currently, Ocean protocol supports 1 template type for data NFT and 2 template variants for datatokens, namely: **regular template** and **enterprise template**. Each template supports the same interfaces but differs in the underlying implementation and can have additional features.
|
||||
Each [data NFT](data-nfts.md) or [datatoken](datatokens.md) within Ocean Protocol is generated from pre-defined [template](https://github.com/oceanprotocol/contracts/tree/main/contracts/templates) contracts. The _**templateId**_ parameter specifies the template used for creating a data NFT or datatoken, which can be set during the creation process. The _**templateId**_ is stored within the smart contract code and can be accessed using the [_**getId**_](https://github.com/oceanprotocol/contracts/blob/9e29194d910f28a4f0ef17ce6dc8a70741f63309/contracts/interfaces/IERC20Template.sol#L134)_**()**_ function.
|
||||
|
||||
The only data NFT template currently available has templateId `1` and the source code is available [here](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC721Template.sol).
|
||||
```solidity
|
||||
|
||||
The details regarding currently supported datatoken templates are as follows:
|
||||
it("#getId - should return templateId", async () => {
|
||||
const templateId = 1;
|
||||
assert((await erc20Token.getId()) == templateId);
|
||||
});
|
||||
|
||||
* **Regular template**: The regular template allows users to buy/sell/hold datatokens. The datatokens can be minted by the address having a `MINTER` role, making the supply of datatoken variable. This template is assigned templateID `1` and the source code is available [here](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC20Template.sol).
|
||||
* **Enterprise template**: The enterprise template has additional functions apart from methods in the ERC20 interface. This additional feature allows access to the service by paying in the basetoken instead of datatoken. Internally, the smart contract handles conversion of basetoken to datatoken, initiating an order to access the service, and minting/burning the datatoken. The total supply of the datatoken effectively remains 0 in the case of the enterprise template. This template is assigned templateID `2` and the source code is available [here](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC20TemplateEnterprise.sol).
|
||||
```
|
||||
|
||||
_NOTE: Ocean Protocol might support additional variations of data NFT/datatoken by adding new templates._
|
||||
Currently, Ocean Protocol supports **1** [template](https://github.com/oceanprotocol/contracts/blob/main/contracts/templates/ERC721Template.sol) type for data NFTs and **2** template variants for datatokens: the [**regular template**](https://github.com/oceanprotocol/contracts/blob/main/contracts/templates/ERC20Template.sol) and the [**enterprise template**](https://github.com/oceanprotocol/contracts/blob/main/contracts/templates/ERC20TemplateEnterprise.sol). While these templates share the same interfaces, they differ in their underlying implementation and may offer additional features.
|
||||
|
||||
The details regarding currently supported **datatoken templates** are as follows:
|
||||
|
||||
### **Regular template**
|
||||
|
||||
The regular template allows users to buy/sell/hold datatokens. The datatokens can be minted by the address having a [`MINTER`](roles.md#minter) role, making the supply of datatoken variable. This template is assigned _**templateId**_ `1` and the source code is available [here](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC20Template.sol).
|
||||
|
||||
|
||||
|
||||
### **Enterprise template**
|
||||
|
||||
The enterprise template has additional functions apart from methods in the ERC20 interface. This additional feature allows access to the service by paying in the basetoken instead of the datatoken. Internally, the smart contract handles the conversion of basetoken to datatoken, initiating an order to access the service, and minting/burning the datatoken. The total supply of the datatoken effectively remains 0 in the case of the enterprise template. This template is assigned _**templateId**_ `2` and the source code is available [here](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC20TemplateEnterprise.sol).
|
||||
|
||||
|
||||
|
||||
To identify the template used for a specific asset within the Ocean Protocol, you can easily retrieve this information using any network explorer. Here are the steps to follow:
|
||||
|
||||
1. Visit the network explorer where the asset was published.
|
||||
2. Search for the datatoken address
|
||||
3. Once you have located the datatoken address, click on the contract tab to access more details.
|
||||
4. Within the contract details, we can identify and determine the template used for the asset.
|
||||
|
||||
 
|
||||
|
||||
Let's identify together the template of [this](https://market.oceanprotocol.com/asset/did:op:cd086344c275bc7c560e91d472be069a24921e73a2c3798fb2b8caadf8d245d6) asset published in the Ocean Market: 
|
||||
|
||||
{% @arcade/embed flowId="wxBPSc42eSYUiawSY8rC" url="https://app.arcade.software/share/wxBPSc42eSYUiawSY8rC" %}
|
||||
|
||||
{% hint style="info" %}
|
||||
_Ocean Protocol might support additional variations of data NFT/datatoken by adding new templates._
|
||||
{% endhint %}
|
||||
|
||||
@ -1,13 +1,116 @@
|
||||
# Metadata
|
||||
|
||||
Marketplaces use the Metadata of the asset for discovery. Metadata consists of information like the type of asset, name of the asset, creation date, license, etc. Each data asset can have a [decentralized identifier](https://w3c-ccg.github.io/did-spec/) (DID) that resolves to a DID document (DDO) for associated metadata. The DDO is essentially [JSON](https://www.json.org/) filling in metadata fields. For more details on working with OCEAN DIDs check out the [DID concept documentation](../Identifiers-Metadata.md). The [DDO Metadata documentation](../Identifiers-Metadata.md) goes into more depth regarding metadata structure.
|
||||
In the Ocean V4, you will hear about two metadata fields: 
|
||||
|
||||
[OEP8](../broken-reference/) specifies Ocean metadata schema, including fields that must be filled. It’s based on the public [DataSet schema from schema.org](https://schema.org/Dataset).
|
||||
One set at the NFT level 
|
||||
|
||||
Ocean uses the Ethereum mainnet and other compatible networks as an **on-chain metadata store**, i.e. to store both DID and DDO. This means that once the transaction fee is paid, there are no further expenses or devops work needed to ensure metadata availability into the future, aiding in the discoverability of data assets. It also simplifies integration with the rest of the Ocean system, which is Ethereum-based. Storage cost on Ethereum mainnet is not negligible, but not prohibitive and the other benefits are currently worth the trade-off compared to alternatives.
|
||||
On the NFT itself, there is a [metadata store](https://github.com/oceanprotocol/contracts/blob/9e29194d910f28a4f0ef17ce6dc8a70741f63309/contracts/templates/ERC721Template.sol#L247) used to store the following information.
|
||||
|
||||
This information is used in the discovery process by aquarius and also gives important information about the asset itself. 
|
||||
|
||||
```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 setMetaData(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);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
One set at the DDO level
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
There is a complete list of all the possible metadata in [Ocean Enhancement Proposal #8 (OEP-8)](https://github.com/oceanprotocol/OEPs/tree/master/8), which is based on [schema.org’s Dataset schema](https://schema.org/Dataset). The metadata is stored and sent around inside a [JSON](http://json.org/) object like the following example:
|
||||
|
||||
```json
|
||||
{
|
||||
"curation": {
|
||||
"rating": 0.892,
|
||||
"numVotes": 1040,
|
||||
"isListed": true
|
||||
},
|
||||
"base": {
|
||||
"name": "Madrid Weather forecast",
|
||||
"description": "Weather forecast of Europe/Madrid",
|
||||
"dateCreated": "2019-05-16T12:36:14.535Z",
|
||||
"author": "Norwegian Meteorological Institute",
|
||||
"type": "dataset",
|
||||
"license": "Public Domain",
|
||||
"copyrightHolder": "Norwegian Meteorological Institute",
|
||||
"files": [
|
||||
{
|
||||
"contentLength": "0",
|
||||
"contentType": "text/xml",
|
||||
"compression": "none",
|
||||
"index": 0
|
||||
}
|
||||
],
|
||||
"categories": [
|
||||
"Meteorology"
|
||||
],
|
||||
"tags": ["Europe", "Spain", "Madrid"],
|
||||
"price": "0",
|
||||
"encryptedFiles": "0x7a0d1c66ae861…df43aa9",
|
||||
"checksum": "d7296ccaaec…9cc9adf05faebfca",
|
||||
"datePublished": "2019-05-16T12:41:01Z"
|
||||
},
|
||||
"additionalInformation": {
|
||||
"isUseful": true,
|
||||
"isMagic": false
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
When building dApps, you, as a developer, can leverage the power of metadata in the Ocean Protocol ecosystem. 
|
||||
|
||||
OEP8 specifies the Ocean metadata schema, including the required fields. This schema is based on the public DataSet schema from schema.org. By utilizing Ethereum mainnet and compatible networks as an on-chain metadata store, Ocean ensures the availability and discoverability of data assets. Once the transaction fee is paid, there are no additional expenses or DevOps work required to maintain metadata accessibility in the future. This simplifies integration with the rest of the Ethereum-based Ocean system. Although storage costs on Ethereum mainnet are not negligible, they are manageable and the benefits outweigh the trade-offs compared to alternative solutions.
|
||||
|
||||
Thanks to the permissionless and decentralized nature of data on the Ethereum mainnet, any last mile tool can access metadata. Ocean [Aquarius](../aquarius/) supports different metadata fields for each specific Ocean-based marketplace, and developers can also utilize The Graph to observe metadata fields common across all marketplaces.
|
||||
|
||||
Due to the permissionless, decentralized nature of data on the Ethereum mainnet, any last mile tool can access metadata. **Ocean Aquarius** supports different metadata fields for each different Ocean-based marketplace. Developers could also use [The Graph](https://www.thegraph.com) to see metadata fields that are common across all marketplaces.
|
||||
|
||||
### Third-Party ERC20 Apps & Tools
|
||||
|
||||
The ERC20 nature of datatokens eases composability with other Ethereum tools and apps, including **MetaMask** and **Trezor** as data wallets, DEXes as data exchanges, and more. [This post](https://blog.oceanprotocol.com/ocean-datatokens-from-money-legos-to-data-legos-4f867cec1837) has details.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user