diff --git a/content/concepts/architecture.md b/content/concepts/architecture.md index 8d483294..ef874097 100644 --- a/content/concepts/architecture.md +++ b/content/concepts/architecture.md @@ -11,34 +11,31 @@ Here is the Ocean architecture. Here’s an overview of the figure. -- The top layer is **applications** like Ocean Market. With these apps, users can onboard services like data, alogrithm, compute-to-data into crypto (publish and mint data NFTs and datatokens), hold datatokens as assets (data wallets), discover assets and buy / sell datatokens for fixed or auto-determined price (data marketplaces), and consume data services (consume datatokens). -- Below that are **libraries** used by the applications: Ocean.js (JavaScript library) and Ocean.py (Python library). This also includes middleware to assist discovery: - - **Aquarius**: Provides metadata cache for faster search by caching on-chain data into elasticsearch - - **Provider**: Facilitates downloading assets, DDO encryption and communicating with `operater-service` for Compute-to-Data jobs. - - **TheGraph**: 3rd party tool -Developers can utilize the libraries to built thier custom applications and marketplaces. -- The lowest level has the **smart contracts** used by the libraries. They’re deployed on Ethereum mainnet, and other compatible networks. To see the list of supported networks click [here](/concepts/networks/). - -The rest of this page elaborates. +- The top layer is **applications** like Ocean Market. With these apps, users can onboard services like data, algorithms, compute-to-data into crypto (publish and mint data NFTs and datatokens), hold datatokens as assets (data wallets), discover assets, and buy/sell datatokens for a fixed or auto-determined price (data marketplaces), and consume data services (consume datatokens). +- Below are **libraries** used by the applications: Ocean.js (JavaScript library) and Ocean.py (Python library). This also includes middleware to assist discovery: + - **Aquarius**: Provides metadata cache for faster search by caching on-chain data into elasticsearch + - **Provider**: Facilitates downloading assets, DDO encryption, and communicating with `operator-service` for Compute-to-Data jobs. + - **The Graph**: It is a 3rd party tool that developers can utilize the libraries to build their custom applications and marketplaces. +- The lowest level has the **smart contracts**. The smart contracts are deployed on the Ethereum mainnet and other compatible networks. Libraries encapsulate the calls to these smart contracts and provide features like publishing new assets, facilitating consumption, managing pricing, and much more. To see the supported networks click [here](/concepts/networks/). ## Data NFTs, Datatokens and Access Control Tools -Data NFTs are based on [ERC721](https://eips.ethereum.org/EIPS/eip-721) standard. The publisher can use Marketplace or client libraries to deploy a new data NFT contract. To save gas fees, it uses [ERC1167](https://eips.ethereum.org/EIPS/eip-1167) proxy approach on the **ERC721 template**. Publisher can then assign manager role to other ethereum addresses who can deploy new datatoken contracts and even mint them. Each Datatoken contract is associated with one data NFT contract. -Click [here](/concepts/datanft-and-datatoken/) to further read about data NFTs and datatokens. +Data NFTs are based on [ERC721](https://eips.ethereum.org/EIPS/eip-721) standard. The publisher can use Marketplace or client libraries to deploy a new Data NFT contract. To save gas fees, it uses [ERC1167](https://eips.ethereum.org/EIPS/eip-1167) proxy approach on the **ERC721 template**. Publisher can then assign manager role to other Ethereum addresses who can deploy new datatoken contracts and even mint them. Each Datatoken contract is associated with one Data NFT contract. +Click [here](/concepts/datanft-and-datatoken/) to further read about Data NFTs and datatokens. -ERC721 data NFTs represent holding copyright / base IP of a data asset, and ERC20 datatokens represent licenses to consume the data asset. +ERC721 Data NFTs represent holding copyright/base IP of a data asset, and ERC20 datatokens represent licenses to consume the data asset. -Datatoken represents the asset which the publisher want to monetize. The asset can be a dataset or an algorithm. The publisher actor holds the asset in Google Drive, Dropbox, AWS S3, on their phone, on their home server, etc. The publisher can optionally use IPFS for a content-addressable URL. Or instead of a file, the publisher may run a compute-to-data service. +Datatoken represents the asset that the publisher wants to monetize. The asset can be a dataset or an algorithm. The publisher actor holds the asset in Google Drive, Dropbox, AWS S3, on their phone, on their home server, etc. The publisher can optionally use IPFS for a content-addressable URL. Or instead of a file, the publisher may run a compute-to-data service. In the **publish** step, the publisher invokes **Ocean Datatoken Factory** to deploy a new datatoken to the chain. To save gas fees, it uses [ERC1167](https://eips.ethereum.org/EIPS/eip-1167) proxy approach on the **ERC20 datatoken template**. The publisher then mints datatokens. -The publisher runs their own **Ocean Provider** or can use one deployed by Ocean Protocol. In the **consume** step, Provider software needs to retrieve the data service URL given a datatoken address. One approach would be for the publisher to run a database; however this adds another dependency. To avoid this, Provider encrypts the URL and it URL on-chain. +The publisher runs their own **Ocean Provider** or can use one deployed by Ocean Protocol. In the **consume** step, Provider software needs to retrieve the data service URL given a datatoken address. One approach would be for the publisher to run a database. However, this adds another dependency. To avoid this, the Provider encrypts the URL and it URL on-chain. To initiate the **consume** step, the data consumer sends 1.0 datatokens to the Provider wallet. Then they make a service request to the Provider. The Provider loads the encrypted URL, decrypts it, and provisions the requested service (send static data, or enable a compute-to-data job). -Instead of running a Provider themselves, the publisher can have a 3rd party like Ocean Market run it. While more convenient, it means that the 3rd party has custody of the private encryption/decryption key (more centralized). Ocean will support more service types and url custody options in the future. +Instead of running a Provider themselves, the publisher can have a 3rd party like Ocean Market to run it. While more convenient, it means that the 3rd party has custody of the private encryption/decryption key (more centralized). Ocean will support more service types and URL custody options in the future. -**Ocean JavaScript and Python libraries** act as drivers for the lower-level contracts. Each library integrates with Ocean Provider to provision & consume data services, and Ocean Aquarius for metadata. **Ocean React hooks** use the JavaScript library, to help build web apps & React Native apps with Ocean. +**Ocean JavaScript and Python libraries** act as drivers for the lower-level contracts. Each library integrates with Ocean Provider to provision & consume data services, and Ocean Aquarius for metadata. @@ -52,7 +49,7 @@ The marketplaces are decentralized (no single owner or controller), and non-cust Ocean Market supports fixed pricing and automatic price discovery. -- For **fixed pricing**, there’s a simple contract for users to buy/sell datatokens for OCEAN, while avoiding custodianship during value transfer. +- For **fixed pricing**, there’s a simple contract for users to buy/sell datatokens for OCEAN while avoiding custodianship during value transfer. - For **automatic price discovery**, Ocean Market uses automated market makers (AMMs) powered by [Balancer](https://www.balancer.finance). Each pool is a datatoken-OCEAN pair. In the Ocean Market GUI, the user adds liquidity then invokes pool creation; the GUI’s React code calls the Ocean JavaScript library, which calls the **Pool Factory** to deploy a **Pool** contract. (The Python library also does this.) Deploying a datatoken pool can be viewed as an “Initial Data Offering” (IDO). Complementary to Ocean Market, Ocean has reference code to ease building **third-party data marketplaces**, such as for logistics ([dexFreight data marketplace](https://blog.oceanprotocol.com/dexfreight-ocean-protocol-partner-to-enable-transportation-logistics-companies-to-monetize-data-7aa839195ac)) or mobility ([Daimler](https://blog.oceanprotocol.com/ocean-protocol-delivers-proof-of-concept-for-daimler-ag-in-collaboration-with-daimler-south-east-564aa7d959ca)). @@ -63,14 +60,14 @@ Complementary to Ocean Market, Ocean has reference code to ease building **third ## Metadata Tools -Metadata (name of dataset, date created etc.) is used by marketplaces for data asset discovery. 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](https://docs.oceanprotocol.com/concepts/did-ddo/). +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](https://docs.oceanprotocol.com/concepts/did-ddo/). The [DDO Metadata documentation](https://docs.oceanprotocol.com/concepts/ddo-metadata/) goes into more depth regarding metadata structure. [OEP8](/concepts/did-ddo/) 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). -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 write fee is paid, there are no further expenses or dev-ops 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 tradeoff compared to alternatives. +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. -Due to the permissionless, decentralized nature of data on 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 [TheGraph](https://www.thegraph.com) to see metadata fields that are 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. diff --git a/content/concepts/datanft-and-datatoken.md b/content/concepts/datanft-and-datatoken.md index e6a77b8d..1090bb29 100644 --- a/content/concepts/datanft-and-datatoken.md +++ b/content/concepts/datanft-and-datatoken.md @@ -1,60 +1,44 @@ --- title: Data NFTs and Datatokens -description: In Ocean Protocol, ERC721 Data NFTs represent holding copyright / base IP of a data asset, and ERC20 datatokens represent licenses to consume the data asset. +description: In Ocean Protocol, ERC721 Data NFTs represent holding copyright/base IP of a data asset, and ERC20 datatokens represent licenses to consume the assets. --- -A non-fungible token stored on the blockchain represents a unique asset. NFTs can represent images, videos, digital art, or any piece of information. NFTs can be traded, and allow transfer of copyright / base IP. [EIP-721](https://eips.ethereum.org/EIPS/eip-721) defines an interface for handling NFTs on EVM-compatible blockchains. The creator of the NFT can deploy a new contract on Ethereum or any Blockchain supporting NFT related interface and also, transfer the ownership of copyright / base IP through transfer transactions. +A non-fungible token stored on the blockchain represents a unique asset. NFTs can represent images, videos, digital art, or any piece of information. NFTs can be traded, and allow transfer of copyright/base IP. [EIP-721](https://eips.ethereum.org/EIPS/eip-721) defines an interface for handling NFTs on EVM-compatible blockchains. The creator of the NFT can deploy a new contract on Ethereum or any Blockchain supporting NFT related interface and also, transfer the ownership of copyright/base IP through transfer transactions. Fungible tokens represent fungible assets. If you have 5 ETH and Alice has 5 ETH, you and Alice could swap your ETH and your final holdings remain the same. They're apples-to-apples. Licenses (contracts) to consume a copyrighted asset are naturally fungible - they can be swapped with each other. ![Data NFT and Datatoken](images/datanft-and-datatoken.png) - ## High-Level Architecture -The image above describes how ERC721 DataNFTs, ERC20 datatokens, and AMMs relate. - -- Bottom: The publisher deploys an ERC721 dataNFT contract representing base IP for the data asset. They are now the manager of the dataNFT. -- Middle: The manager then deploys an ERC20 datatoken contract against the dataNFT. The ERC20 represents a license with specific terms like "can consume for the next 3 days". They could even publish further ERC20 datatoken contracts, to represent different license terms or for compute-to-data. -- Top: The manager then deploys a pool of the datatoken and OCEAN (or H2O), adds initial liquidity, and receives ERC20 pool tokens in return. Others may also add liquidity for receive pool tokens, i.e. become liquidity providers (LPs). +The image above describes how ERC721 Data NFTs, ERC20 datatokens, and AMMs relate. +- Bottom: The publisher deploys an ERC721 Data NFT contract representing the base IP for the data asset. They are now the manager of the Data NFT. +- Middle: The manager then deploys an ERC20 datatoken contract against the Data NFT. The ERC20 represents a license with specific terms like "can consume for the next 3 days". They could even publish further ERC20 datatoken contracts, to represent different license terms or for compute-to-data. +- Top: The manager then deploys a pool of the datatoken and OCEAN (or H2O), adds initial liquidity, and receives ERC20 pool tokens in return. Others may also add liquidity to receive pool tokens, i.e. become liquidity providers (LPs). ## Terminology - **Base IP** means the artifact being copyrighted. Represented by the {ERC721 address, tokenId} from the publish transactions. -- **Base IP holder** means the holder of the Base IP. Represented as the the actor that did the initial "publish" action. +- **Base IP holder** means the holder of the Base IP. Represented as the actor that did the initial "publish" action. - **Sub-licensee** is the holder of the sub-license. Represented as the entity that controls address ERC721.\_owners[tokenId=x]. -- **To Publish**: Claim copyright or exclusive base license -- **To Sub-license**:Transfer one (of many) sub-licenses to new licensee: ERC20.transfer(to=licensee, value=1.0) +- **To Publish**: Claim copyright or exclusive base license. +- **To Sub-license**: Transfer one (of many) sub-licenses to new licensee: ERC20.transfer(to=licensee, value=1.0). ## Implementation in Ocean Protocol -Ocean Protocol defines the [ERC721Factory](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/ERC721Factory.sol) contract, allowing **Base IP holders** to create their ERC721 contract instances on any supported networks. The deployed contract stores Metadata, ownership, sub-license information, permissions. The creator of the contract can also create and mint ERC20 token instances for sub-licensing the **Base IP**. +Ocean Protocol defines the [ERC721Factory](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/ERC721Factory.sol) contract, allowing **Base IP holders** to create their ERC721 contract instances on any supported networks. The deployed contract stores Metadata, ownership, sub-license information, permissions. The contract creator can also create and mint ERC20 token instances for sub-licensing the **Base IP**. ERC721 tokens are non-fungible, thus cannot be used for automatic price discovery like ERC20 tokens. ERC721 and ERC20 combined together can be used for sub-licensing. Ocean Protocol's [ERC721Template](https://github.com/oceanprotocol/contracts/blob/v4main/contracts/templates/ERC721Template.sol) solves this problem by using ERC721 for tokenizing the **Base IP** and tokenizing sub-licenses by using ERC20. Thus, sub-licenses can be traded on any AMM as the underlying contract is ERC20 compliant. -## Roles - -[ERC721Template](https://github.com/oceanprotocol/contracts/blob/v4Hardhat/contracts/templates/ERC721Template.sol) contract defines following roles: - -### NFT Owner - -- NFT Owner is the publisher. I.e. Owner is a public address which transacted with `ERC721Factory` contract and deployed a new `ERC721` contract. -- NFT Owner can assign managers while deploying the contract. -- NFT Owner is also added to the Managers. -- NFT Owner can add/remove Managers. -- Clean all permissions - -### Manager - -- A public address with a `Maganer` role can update the metadata -- Can deploy new ERC20 contract which is associtated with the `ERC721` contract. - ## High-Level Behavior ![Flow](images/use-case.png) -Here's an example. Alice has created a dataset. In step 1, she publishes her dataset with Ocean: this means deploying an ERC721 data NFT contract (claiming copyright / base IP), then an ERC20 datatoken contract (license against base IP). Then in step 2, she mints some ERC20 datatokens and transfers 1.0 of them to Bob's wallet; now he has a license to be able to consume that dataset. +Here's an example. + +- In step 1, Alice **publishes** her dataset with Ocean: this means deploying an ERC721 data NFT contract (claiming copyright/base IP), then an ERC20 datatoken contract (license against base IP). +- In step 2, she **mints** some ERC20 datatokens and **transfers** 1.0 of them to Bob's wallet; now he has a license to be able to consume that dataset. ## Other References diff --git a/content/concepts/did-ddo.md b/content/concepts/did-ddo.md index 435b4a53..842f9963 100644 --- a/content/concepts/did-ddo.md +++ b/content/concepts/did-ddo.md @@ -11,23 +11,23 @@ section: concepts 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. +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 DIDs & DDOs +## Rules for DID & DDO -An _asset_ in Ocean represents a downloadable file, compute service, or similar. Each asset is a _resource_ under control of a _publisher_. The Ocean network itself does _not_ store the actual resource (e.g. files). +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](#metadata) about the asset, and define access in at least one [service](#services). The DDO can only be modified by _owners_ or _delegated users_. +An _asset_ has a DID and DDO. The DDO should include [metadata](#metadata) about the asset, and define access in at least one [service](#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 encrypted using the private key of the _Provider_. To resolve it, a metadata cache like _Aquarius_ must query the provider to decrypt the DDO. +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 complete flow: +Here is the flow: ![DDO flow](images/ddo-flow.png) @@ -62,7 +62,7 @@ In Ocean, a DID is a string that looks like this: did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea ``` -The part after `did:op:` is the the ERC721 contract address(in checksum format) and the chainId (expressed as decimal) the asset has been published to: +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) @@ -128,12 +128,12 @@ Example: An asset of type `algorithm` has additional attributes under `metadata.algorithm`, describing the algorithm and the Docker environment it is supposed to be run under. -| Attribute | Type | Required | Description | -| --------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------ | -| **`language`** | `string` | | Language used to implement the software. | -| **`version`** | `string` | | Version of the software preferably in [SemVer](https://semver.org) notation. E.g. `1.0.0`. | -| **`consumerParameters`** | [Consumer Parameters](#consumer-parameters) | | An object the defines required consumer input before running the algorithm | -| **`container`** | `container` | **✓** | Object describing the Docker container image. See below | +| Attribute | Type | Required | Description | +| ------------------------ | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ | +| **`language`** | `string` | | Language used to implement the software. | +| **`version`** | `string` | | Version of the software preferably in [SemVer](https://semver.org) notation. E.g. `1.0.0`. | +| **`consumerParameters`** | [Consumer Parameters](#consumer-parameters) | | An object the defines required consumer input before running the algorithm | +| **`container`** | `container` | **✓** | Object describing the Docker container image. See below | The `container` object has the following attributes defining the Docker image for running the algorithm: @@ -163,7 +163,7 @@ The `container` object has the following attributes defining the Docker image fo "tag": "latest", "checksum": "44e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550" }, - "consumerParameters":{}, + "consumerParameters": {} } } } @@ -175,18 +175,18 @@ Services define the access for an asset, and each service is represented by its An asset should have at least one service to be actually accessible, and can have as many services which make sense for a specific use case. -| Attribute | Type | Required | Description | -| ---------------------- | --------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| **`id`** | `string` | **✓** | Unique ID | -| **`type`** | `string` | **✓** | Type of service (`access`, `compute`, `wss`, etc. | -| **`name`** | `string` | | Service friendly name | -| **`description`** | `string` | | Service description | -| **`datatokenAddress`** | `string` | **✓** | Datatoken address | -| **`serviceEndpoint`** | `string` | **✓** | Provider URL (schema + host) | -| **`files`** | [Files](#files) | **✓** | Encrypted file URLs. | -| **`timeout`** | `number` | **✓** | Describing how long the service can be used after consumption is initiated. A timeout of `0` represents no time limit. Expressed in seconds. | -| **`compute`** | [Compute](#compute-options) | **✓** (for compute assets only) | If service is of `type` `compute`, holds information about the compute-related privacy settings & resources. | -| **`consumerParameters`** | [Consumer Parameters](#consumer-parameters) | | An object the defines required consumer input before consuming the asset| +| Attribute | Type | Required | Description | +| ------------------------ | ------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| **`id`** | `string` | **✓** | Unique ID | +| **`type`** | `string` | **✓** | Type of service (`access`, `compute`, `wss`, etc. | +| **`name`** | `string` | | Service friendly name | +| **`description`** | `string` | | Service description | +| **`datatokenAddress`** | `string` | **✓** | Datatoken address | +| **`serviceEndpoint`** | `string` | **✓** | Provider URL (schema + host) | +| **`files`** | [Files](#files) | **✓** | Encrypted file URLs. | +| **`timeout`** | `number` | **✓** | Describing how long the service can be used after consumption is initiated. A timeout of `0` represents no time limit. Expressed in seconds. | +| **`compute`** | [Compute](#compute-options) | **✓** (for compute assets only) | If service is of `type` `compute`, holds information about the compute-related privacy settings & resources. | +| **`consumerParameters`** | [Consumer Parameters](#consumer-parameters) | | An object the defines required consumer input before consuming the asset | #### Files @@ -200,8 +200,7 @@ Example: } ``` -During the publish process, file URLs must be encrypted with a respective _Provider_ API call before storing the DDO on-chain. For this an array of objects defining the storage access details are sent. - +During the publish process, file URLs must be encrypted with a respective _Provider_ API call before storing the DDO on-chain. For this an array of objects defining the storage access details are sent. Type of objects supported : @@ -217,11 +216,11 @@ Type of objects supported : ```json [ - { - "type": "url", - "url": "https://url.com/file1.csv", - "method": "GET" - } + { + "type": "url", + "url": "https://url.com/file1.csv", + "method": "GET" + } ] ``` @@ -240,11 +239,11 @@ First class integrations supported in the future : "ipfs"IPFS files - ```json -[ +```json +[ { - "type":"ipfs", - "hash": "XXX" + "type": "ipfs", + "hash": "XXX" } ] ``` @@ -257,23 +256,21 @@ First class integrations supported in the future : "sql"Sql connection, dataset is generated by a query  - A service can contain multiple files, using multiple storage types. Example: ```json [ - { - "type": "url", - "url": "https://url.com/file1.csv", - "method": "GET" - - }, - { - "type": "ipfs", - "hash": "XXXX" - } + { + "type": "url", + "url": "https://url.com/file1.csv", + "method": "GET" + }, + { + "type": "ipfs", + "hash": "XXXX" + } ] ``` @@ -377,7 +374,6 @@ An asset with a service of `type` `compute` has the following additional attribu - The `publisherTrustedAlgorithms ` is an array of objects with the following structure: | Attribute | Type | Required | Description | @@ -443,7 +439,7 @@ Example: ] } ``` - + #### Consumer Parameters Sometimes, you may need some input before downloading a dataset or running an algorithm. @@ -456,27 +452,26 @@ It's an array of elements, each element object defines a field. An element looks like: ```json - { - "name":"hometown", - "type": "text", - "label": "Hometown", - "required": true, - "description":"What is your hometown?", - "default": "Nowhere", - "options": [] - } +{ + "name": "hometown", + "type": "text", + "label": "Hometown", + "required": true, + "description": "What is your hometown?", + "default": "Nowhere", + "options": [] +} ``` where: - - name = defines the parameter name (this is sent as HTTP param or key towards algo) - - type = defines the form type (text, number, select, boolean) - - label = defines the label which is displayed - - required = if this field is mandatory to have a consumer input. - - default = default value - - description = description of this element - - options = for select types, a list of options - +- name = defines the parameter name (this is sent as HTTP param or key towards algo) +- type = defines the form type (text, number, select, boolean) +- label = defines the label which is displayed +- required = if this field is mandatory to have a consumer input. +- default = default value +- description = description of this element +- options = for select types, a list of options Example: @@ -515,7 +510,7 @@ Example: "options": [ { "nodejs" : "I love NodeJs" - }, + }, { "python" : "I love Python" } @@ -525,7 +520,7 @@ Example: ] ``` -Algorithms will have access to a json file located at /data/inputs/algoCustomData.json, which contains the keys/values for input data required. Example: +Algorithms will have access to a JSON file located at /data/inputs/algoCustomData.json, which contains the keys/values for input data required. Example: ```json { @@ -536,7 +531,6 @@ Algorithms will have access to a json file located at /data/inputs/algoCustomDat } ``` - ### Credentials By default, a consumer can access a resource if they have 1 datatoken. _Credentials_ allow the publisher to optionally specify more fine-grained permissions. @@ -622,21 +616,21 @@ Each asset has a state, which is held by the NFT contract. The possible states a The following fields are added by _Aquarius_ in its DDO response for convenience reasons, where an asset returned by _Aquarius_ inherits the DDO fields stored on-chain. -These additional fields are never stored on-chain, and are never taken into consideration when [hashing the DDO](#ddo-hash). +These additional fields are never stored on-chain, and are never taken into consideration when [hashing the DDO](#ddo-checksum). ### NFT The `nft` object contains information about the ERC721 NFT contract which represents the intellectual property of the publisher. -| Attribute | Type | Description | -| ------------- | ---------------------- | ------------------------------------------------------------------------- | -| **`address`** | `string` | Contract address of the deployed ERC721 NFT contract. | -| **`name`** | `string` | Name of NFT set in contract. | -| **`symbol`** | `string` | Symbol of NFT set in contract. | -| **`owner`** | `string` | ETH account address of the NFT owner. | -| **`state`** | `number` | State of the asset reflecting the NFT contract value. See [State](#state) | -| **`created`** | `ISO date/time string` | Contains the date of NFT creation. | -| **`tokenURI`** | `string` | tokenURI | +| Attribute | Type | Description | +| -------------- | ---------------------- | ------------------------------------------------------------------------- | +| **`address`** | `string` | Contract address of the deployed ERC721 NFT contract. | +| **`name`** | `string` | Name of NFT set in contract. | +| **`symbol`** | `string` | Symbol of NFT set in contract. | +| **`owner`** | `string` | ETH account address of the NFT owner. | +| **`state`** | `number` | State of the asset reflecting the NFT contract value. See [State](#state) | +| **`created`** | `ISO date/time string` | Contains the date of NFT creation. | +| **`tokenURI`** | `string` | tokenURI | Example: @@ -735,8 +729,8 @@ Example: The `stats` section contains different statistics fields. -| Attribute | Type | Description | -| -------------- | -------- | ------------------------------------------------------------------------------------------------------------- | +| Attribute | Type | Description | +| ------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | **`orders`** | `number` | How often an asset was ordered, meaning how often it was either downloaded or used as part of a compute job. | Example: @@ -753,123 +747,131 @@ Example: ```json { - "@context": ["https://w3id.org/did/v1"], - "id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123", - "version": "4.0.0", - "chainId": 1, - "nftAddress": "0x123", - "metadata": { - "created": "2020-11-15T12:27:48Z", - "updated": "2021-05-17T21:58:02Z", - "description": "Sample description", - "name": "Sample asset", - "type": "dataset", - "author": "OPF", - "license": "https://market.oceanprotocol.com/terms" - }, - "services": [{ - "id": "1", - "type": "access", - "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735", - "name": "Download service", - "description": "Download service", - "datatokenAddress": "0x123", - "serviceEndpoint": "https://myprovider.com", - "timeout": 0, - "consumerParameters": [{ - "name": "surname", - "type": "text", - "label": "Name", - "required": true, - "default": "NoName", - "description": "Please fill your name" - }, - { - "name": "age", - "type": "number", - "label": "Age", - "required": false, - "default": 0, - "description": "Please fill your age" - } - ] - }, - { - "id": "2", - "type": "compute", - "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735", - "name": "Compute service", - "description": "Compute service", - "datatokenAddress": "0x124", - "serviceEndpoint": "https://myprovider.com", - "timeout": 3600, - "compute": { - "allowRawAlgorithm": false, - "allowNetworkAccess": true, - "publisherTrustedAlgorithmPublishers": ["0x234", "0x235"], - "publisherTrustedAlgorithms": [{ - "did": "did:op:123", - "filesChecksum": "100", - "containerSectionChecksum": "200" - }, - { - "did": "did:op:124", - "filesChecksum": "110", - "containerSectionChecksum": "210" - } - ] - } - } - ], - "credentials": { - "allow": [{ - "type": "address", - "values": ["0x123", "0x456"] - }], - "deny": [{ - "type": "address", - "values": ["0x2222", "0x333"] - }] - }, + "@context": ["https://w3id.org/did/v1"], + "id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123", + "version": "4.0.0", + "chainId": 1, + "nftAddress": "0x123", + "metadata": { + "created": "2020-11-15T12:27:48Z", + "updated": "2021-05-17T21:58:02Z", + "description": "Sample description", + "name": "Sample asset", + "type": "dataset", + "author": "OPF", + "license": "https://market.oceanprotocol.com/terms" + }, + "services": [ + { + "id": "1", + "type": "access", + "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735", + "name": "Download service", + "description": "Download service", + "datatokenAddress": "0x123", + "serviceEndpoint": "https://myprovider.com", + "timeout": 0, + "consumerParameters": [ + { + "name": "surname", + "type": "text", + "label": "Name", + "required": true, + "default": "NoName", + "description": "Please fill your name" + }, + { + "name": "age", + "type": "number", + "label": "Age", + "required": false, + "default": 0, + "description": "Please fill your age" + } + ] + }, + { + "id": "2", + "type": "compute", + "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735", + "name": "Compute service", + "description": "Compute service", + "datatokenAddress": "0x124", + "serviceEndpoint": "https://myprovider.com", + "timeout": 3600, + "compute": { + "allowRawAlgorithm": false, + "allowNetworkAccess": true, + "publisherTrustedAlgorithmPublishers": ["0x234", "0x235"], + "publisherTrustedAlgorithms": [ + { + "did": "did:op:123", + "filesChecksum": "100", + "containerSectionChecksum": "200" + }, + { + "did": "did:op:124", + "filesChecksum": "110", + "containerSectionChecksum": "210" + } + ] + } + } + ], + "credentials": { + "allow": [ + { + "type": "address", + "values": ["0x123", "0x456"] + } + ], + "deny": [ + { + "type": "address", + "values": ["0x2222", "0x333"] + } + ] + }, - "nft": { - "address": "0x123", - "name": "Ocean Protocol Asset v4", - "symbol": "OCEAN-A-v4", - "owner": "0x0000000", - "state": 0, - "created": "2000-10-31T01:30:00", - "tokenURI": "xxx" - }, + "nft": { + "address": "0x123", + "name": "Ocean Protocol Asset v4", + "symbol": "OCEAN-A-v4", + "owner": "0x0000000", + "state": 0, + "created": "2000-10-31T01:30:00", + "tokenURI": "xxx" + }, - "datatokens": [{ - "address": "0x000000", - "name": "Datatoken 1", - "symbol": "DT-1", - "serviceId": "1" - }, - { - "address": "0x000001", - "name": "Datatoken 2", - "symbol": "DT-2", - "serviceId": "2" - } - ], + "datatokens": [ + { + "address": "0x000000", + "name": "Datatoken 1", + "symbol": "DT-1", + "serviceId": "1" + }, + { + "address": "0x000001", + "name": "Datatoken 2", + "symbol": "DT-2", + "serviceId": "2" + } + ], - "event": { - "tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c", - "block": 12831214, - "from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83", - "contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf", - "datetime": "2000-10-31T01:30:00" - }, + "event": { + "tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c", + "block": 12831214, + "from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83", + "contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf", + "datetime": "2000-10-31T01:30:00" + }, - "purgatory": { - "state": false - }, + "purgatory": { + "state": false + }, - "stats": { - "orders": 4 - } + "stats": { + "orders": 4 + } } ``` diff --git a/content/concepts/images/architecture.png b/content/concepts/images/architecture.png index 68c9099f..97084f85 100644 Binary files a/content/concepts/images/architecture.png and b/content/concepts/images/architecture.png differ diff --git a/content/concepts/images/datanft-and-datatoken.png b/content/concepts/images/datanft-and-datatoken.png index e6034d7c..2a0c79fb 100644 Binary files a/content/concepts/images/datanft-and-datatoken.png and b/content/concepts/images/datanft-and-datatoken.png differ diff --git a/content/concepts/images/use-case.png b/content/concepts/images/use-case.png index 3fa83905..a581963f 100644 Binary files a/content/concepts/images/use-case.png and b/content/concepts/images/use-case.png differ diff --git a/content/concepts/roles.md b/content/concepts/roles.md index 69a58a33..8c825a0d 100644 --- a/content/concepts/roles.md +++ b/content/concepts/roles.md @@ -1,6 +1,6 @@ --- title: Data NFTs and datatoken roles -description: The permissions stored on chain in the contracts control the access to the data NFT (ERC721) and datatoken (ERC20) smart contract functions. +description: The permissions stored on chain in the contracts control the access to the data NFT (ERC721) and datatoken (ERC20) smart contract functions. --- The permissions are stored in the data NFT (ERC721) smart contract. The data NFT (ERC721) and datatoken (ERC20) smart contracts both use this information to restrict access to the smart contract functions. The tables below list restricted actions that are accessible only to the allowed users. @@ -8,30 +8,30 @@ The permissions are stored in the data NFT (ERC721) smart contract. The data NFT ## Roles in data NFT (ERC721) smart contract | Action ↓ / Role → | NFT Owner | Manager | ERC20 Deployer | Store Updater | Metadata Updater | -|-----------------------------------|--------------------|--------------------|--------------------|--------------------|--------------------| -| Set token URI | | | | | | +| --------------------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | +| Set token URI | | | | | | | Add manager |
🗸
| | | | | | Remove manager |
🗸
| | | | | | Clean permissions |
🗸
| | | | | | Set base URI |
🗸
| | | | | -| Set MetaData state | | | | |
🗸
| -| Set MetaData | | | | |
🗸
| +| Set Metadata state | | | | |
🗸
| +| Set Metadata | | | | |
🗸
| | Create new Datatoken | | |
🗸
| | | | Executes any other smart contract | |
🗸
| | | | | Set new key-value in store | | | |
🗸
| | ## Roles in datatoken (ERC20) smart contract -| Action ↓ / Role → | ERC20 Deployer | Minter | NFT owner | Fee manager | -|--------------------------------|--------------------------|--------------------------|--------------------------|--------------------------| -| Deploy pool |
🗸
| | | | -| Create Fixed Rate exchange |
🗸
| | | | -| Create Dispenser |
🗸
| | | | -| Add minter |
🗸
| | | | -| Remove minter |
🗸
| | | | -| Add fee manager |
🗸
| | | | -| Remove fee manager |
🗸
| | | | -| Set data |
🗸
| | | | -| Clean permissions | | |
🗸
| | -| Mint | |
🗸
| | | -| Set fee collector | | | |
🗸
| +| Action ↓ / Role → | ERC20 Deployer | Minter | NFT owner | Fee manager | +| --------------------------- | ------------------ | ------------------ | ------------------ | ------------------ | +| Deploy pool |
🗸
| | | | +| Create Fixed Rate exchange |
🗸
| | | | +| Create Dispenser |
🗸
| | | | +| Add minter |
🗸
| | | | +| Remove minter |
🗸
| | | | +| Add fee manager |
🗸
| | | | +| Remove fee manager |
🗸
| | | | +| Set data |
🗸
| | | | +| Clean permissions | | |
🗸
| | +| Mint | |
🗸
| | | +| Set fee collector | | | |
🗸
| diff --git a/data/sidebars/concepts.yml b/data/sidebars/concepts.yml index 98d17377..04ea2055 100644 --- a/data/sidebars/concepts.yml +++ b/data/sidebars/concepts.yml @@ -20,7 +20,7 @@ - group: Specifying Assets items: - - title: DIDs & DDOs + - title: DID & DDO link: /concepts/did-ddo/ - group: Contribute