docs/content/concepts/did-ddo.md

775 lines
36 KiB
Markdown
Raw Normal View History

2021-08-22 09:43:36 +02:00
---
2021-11-04 14:13:32 +01:00
title: DID & DDO
description: Specification of decentralized identifiers for assets in Ocean Protocol using the DID & DDO standards.
slug: /concepts/did-ddo/
2021-08-22 09:43:36 +02:00
section: concepts
---
2021-11-04 13:29:30 +01:00
**v4.0.0**
2021-08-22 09:43:36 +02:00
## Overview
2021-11-04 14:13:32 +01:00
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/).
2021-11-04 14:13:32 +01:00
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.
2021-11-05 09:44:22 +01:00
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.
2021-11-04 12:23:18 +01:00
## Rules for DIDs & DDOs
2021-11-04 12:11:24 +01:00
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).
2021-11-10 18:25:31 +01:00
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_.
2021-11-04 12:11:24 +01:00
2021-11-10 18:25:31 +01:00
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.
2021-10-05 12:46:19 +02:00
2021-11-04 13:42:52 +01:00
## Publishing & Retrieving DDOs
2021-10-05 12:46:19 +02:00
2021-11-12 15:10:15 +01:00
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.
2021-10-05 12:46:19 +02:00
2021-10-05 12:42:12 +02:00
Here is the complete flow:
2021-11-12 15:10:15 +01:00
![DDO flow](images/ddo-flow.png)
2021-11-04 13:29:30 +01:00
2021-11-10 18:25:31 +01:00
<details>
<summary>UML source</summary>
2021-11-11 15:26:57 +01:00
2021-10-05 12:42:12 +02:00
```text
title DDO flow
User(Ocean library) -> User(Ocean library): Prepare DDO
User(Ocean library) -> Provider: encrypt DDO
Provider -> User(Ocean library): encryptedDDO
User(Ocean library) -> ERC721 contract: publish encryptedDDO
Aquarius <-> ERC721 contract: monitors ERC721 contract and gets MetdadataCreated Event (contains encryptedDDO)
Aquarius -> ERC721 contract: calls getMetaData()
Aquarius -> Provider: decrypt encryptedDDO, signed request using Aquarius's private key
Provider -> ERC721 contract: checks state using getMetaData()
Provider -> Provider: depending on metadataState (expired,retired) and aquarius address, validates the request
Provider -> Aquarius: DDO
Aquarius -> Aquarius : validate DDO
Aquarius -> Aquarius : cache DDO
2021-11-11 15:26:57 +01:00
Aquarius -> Aquarius : enhance cached DDO in response with additional infos like events & stats
```
2021-11-10 18:25:31 +01:00
</details>
2021-10-05 12:42:12 +02:00
2021-11-04 14:13:32 +01:00
## DID
2021-11-10 18:25:31 +01:00
In Ocean, a DID is a string that looks like this:
```text
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
2021-11-11 15:26:57 +01:00
```
2021-10-04 13:28:05 +02:00
2021-12-28 09:24:33 +01:00
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:
2021-11-10 18:25:31 +01:00
```js
const checksum = sha256(ERC721 contract address + chainId)
console.log(checksum)
// 0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
2021-11-04 12:11:24 +01:00
```
2021-11-04 12:11:24 +01:00
It follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
2021-11-04 14:13:32 +01:00
## DDO
2021-11-04 13:29:30 +01:00
A DDO in Ocean has these required attributes:
2021-11-04 18:15:49 +01:00
| Attribute | Type | Description |
| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **`@context`** | Array of `string` | Contexts used for validation. |
| **`id`** | `string` | Computed as `sha256(address of ERC721 contract + chainId)`. |
| **`version`** | `string` | Version information in [SemVer](https://semver.org) notation referring to this DDO spec version, like `4.0.0`. |
| **`chainId`** | `number` | Stores chainId of the network the DDO was published to. |
2021-12-28 09:24:33 +01:00
| **`nftAddress`** | `string` | NFT contract linked to this asset |
2021-11-05 09:44:22 +01:00
| **`metadata`** | [Metadata](#metadata) | Stores an object describing the asset. |
2021-11-04 18:15:49 +01:00
| **`services`** | [Services](#services) | Stores an array of services defining access to the asset. |
| **`credentials`** | [Credentials](#credentials) | Describes the credentials needed to access a dataset in addition to the `services` definition. |
2021-11-04 14:13:32 +01:00
### Metadata
2021-10-04 13:28:05 +02:00
2021-11-04 17:52:56 +01:00
This object holds information describing the actual asset.
2021-11-04 12:11:24 +01:00
2021-11-04 14:22:19 +01:00
| Attribute | Type | Required | Description |
| --------------------------- | ----------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2021-11-12 15:10:15 +01:00
| **`created`** | `ISO date/time string` | | Contains the date of the creation of the dataset content in ISO 8601 format preferably with timezone designators, e.g. `2000-10-31T01:30:00Z`. |
| **`updated`** | `ISO date/time string` | | Contains the date of last update of the dataset content in ISO 8601 format preferably with timezone designators, e.g. `2000-10-31T01:30:00Z`. |
2021-11-04 14:22:19 +01:00
| **`description`** | `string` | **✓** | Details of what the resource is. For a dataset, this attribute explains what the data represents and what it can be used for. |
| **`copyrightHolder`** | `string` | | The party holding the legal copyright. Empty by default. |
| **`name`** | `string` | **✓** | Descriptive name or title of the asset. |
| **`type`** | `string` | **✓** | Asset type. Includes `"dataset"` (e.g. csv file), `"algorithm"` (e.g. Python script). Each type needs a different subset of metadata attributes. |
| **`author`** | `string` | **✓** | Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.). |
| **`license`** | `string` | **✓** | Short name referencing the license of the asset (e.g. Public Domain, CC-0, CC-BY, No License Specified, etc. ). If it's not specified, the following value will be added: "No License Specified". |
| **`links`** | Array of `string` | | Mapping of URL strings for data samples, or links to find out more information. Links may be to either a URL or another asset. |
2021-11-04 17:22:18 +01:00
| **`contentLanguage`** | `string` | | The language of the content. Use one of the language codes from the [IETF BCP 47 standard](https://tools.ietf.org/html/bcp47) |
2021-11-04 14:22:19 +01:00
| **`tags`** | Array of `string` | | Array of keywords or tags used to describe this content. Empty by default. |
2021-11-12 15:10:15 +01:00
| **`categories`** | Array of `string` | | Array of categories associated to the asset. Note: recommended to use `tags` instead of this. |
2021-11-04 14:22:19 +01:00
| **`additionalInformation`** | Object | | Stores additional information, this is customizable by publisher |
| **`algorithm`** | [Algorithm Metadata](#algorithm-metadata) | **✓** (for algorithm assets only) | Information about asset of `type` `algorithm` |
2021-11-04 13:29:30 +01:00
Example:
```json
{
"metadata": {
"created": "2020-11-15T12:27:48Z",
"updated": "2021-05-17T21:58:02Z",
2021-11-04 13:29:30 +01:00
"description": "Sample description",
"name": "Sample asset",
"type": "dataset",
"author": "OPF",
"license": "https://market.oceanprotocol.com/terms"
}
}
```
2021-11-04 14:13:32 +01:00
#### Algorithm Metadata
2021-11-04 20:10:21 +01:00
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`. |
| **`userInput`** | [User Input](#userinput) | | An object the defines required user input before running the algorithm |
| **`container`** | `container` | **✓** | Object describing the Docker container image. See below |
2021-11-04 20:10:21 +01:00
The `container` object has the following attributes defining the Docker image for running the algorithm:
2021-11-04 12:11:24 +01:00
| Attribute | Type | Required | Description |
| ---------------- | -------- | -------- | ----------------------------------------------------------------- |
2021-11-04 13:50:33 +01:00
| **`entrypoint`** | `string` | **✓** | The command to execute, or script to run inside the Docker image. |
| **`image`** | `string` | **✓** | Name of the Docker image. |
| **`tag`** | `string` | **✓** | Tag of the Docker image. |
| **`checksum`** | `string` | **✓** | Checksum of the Docker image. |
2021-09-28 18:07:27 +02:00
2021-11-04 17:22:18 +01:00
```json
{
"metadata": {
2021-11-11 10:54:46 +01:00
"created": "2020-11-15T12:27:48Z",
"updated": "2021-05-17T21:58:02Z",
2021-11-04 17:22:18 +01:00
"description": "Sample description",
"name": "Sample algorithm asset",
"type": "algorithm",
"author": "OPF",
"license": "https://market.oceanprotocol.com/terms",
"algorithm": {
2021-11-04 17:52:56 +01:00
"language": "Node.js",
2021-11-04 20:10:21 +01:00
"version": "1.0.0",
2021-11-04 17:22:18 +01:00
"container": {
2021-11-04 17:52:56 +01:00
"entrypoint": "node $ALGO",
"image": "ubuntu",
"tag": "latest",
"checksum": "44e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550"
},
"userInput":{},
2021-11-04 17:22:18 +01:00
}
}
}
```
2021-11-04 14:13:32 +01:00
### Services
2021-09-28 18:07:27 +02:00
2021-11-04 20:10:21 +01:00
Services define the access for an asset, and each service is represented by its respective datatoken.
2021-11-04 17:52:56 +01:00
2021-11-05 09:44:22 +01:00
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.
2021-11-04 13:20:15 +01:00
2021-11-05 10:01:11 +01:00
| Attribute | Type | Required | Description |
| ---------------------- | --------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
2021-11-10 17:33:59 +01:00
| **`id`** | `string` | **✓** | Unique ID |
2021-11-05 10:01:11 +01:00
| **`type`** | `string` | **✓** | Type of service (`access`, `compute`, `wss`, etc. |
| **`name`** | `string` | | Service friendly name |
| **`description`** | `string` | | Service description |
| **`datatokenAddress`** | `string` | **✓** | Datatoken address |
2021-11-10 17:33:59 +01:00
| **`serviceEndpoint`** | `string` | **✓** | Provider URL (schema + host) |
2021-11-12 15:10:15 +01:00
| **`files`** | [Files](#files) | **✓** | Encrypted file URLs. |
2021-11-05 10:01:11 +01:00
| **`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. |
2021-11-11 15:17:27 +01:00
| **`compute`** | [Compute](#compute-options) | **✓** (for compute assets only) | If service is of `type` `compute`, holds information about the compute-related privacy settings & resources. |
| **`userInput`** | [User Input](#userinput) | | An object the defines required user input before consuming the asset|
2021-09-28 18:07:27 +02:00
2021-11-10 17:33:59 +01:00
#### Files
2021-11-10 14:41:45 +01:00
2021-11-12 15:10:15 +01:00
The `files` field is returned as a `string` which holds the encrypted file URLs.
2021-11-10 14:41:45 +01:00
Example:
```json
{
"files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735"
}
```
2021-12-03 09:30:27 +01:00
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.
2021-12-03 09:37:28 +01:00
2021-12-03 09:30:27 +01:00
Type of objects supported :
<table>
<tr>
2021-12-07 11:06:32 +01:00
<th>Type</th>
2021-12-03 09:30:27 +01:00
<th>Description</th>
<th>Example</th>
</tr>
<td>'url'</td>
<td>Static URL. Contains url and HTTP method</td>
<td>
2021-11-10 14:41:45 +01:00
```json
2021-12-03 09:30:27 +01:00
[
{
2021-12-07 11:06:32 +01:00
"type": "url",
"url": "https://url.com/file1.csv",
"method": "GET"
2021-12-03 09:30:27 +01:00
}
]
```
</td>
</tr></table>
First class integrations supported in the future :
<table>
<tr>
2021-12-07 11:06:32 +01:00
<th>Type</th>
2021-12-03 09:30:27 +01:00
<th>Description</th>
<th>Example</th>
</tr>
<tr>
<td>"ipfs"</td><td>IPFS files</td>
<td>
```json
[
2021-12-07 11:06:32 +01:00
{
"type":"ipfs",
"hash": "XXX"
}
2021-12-03 09:30:27 +01:00
]
2021-11-10 14:41:45 +01:00
```
2021-12-03 09:35:20 +01:00
2021-12-03 09:30:27 +01:00
</td>
<tr><td>"filecoin"</td><td>Filecoin storage</td><td>&nbsp;</td></tr>
<tr><td>"arwave"</td><td>Arwave</td><td>&nbsp;</td></tr>
<tr><td>"storj"</td><td>Storj</td><td>&nbsp;</td></tr>
<tr><td>"sql"</td><td>Sql connection, dataset is generated by a query</td><td>&nbsp;</td></tr>
</table>
A service can contain multiple files, using multiple storage types.
2021-12-03 09:32:15 +01:00
Example:
2021-12-03 09:35:20 +01:00
2021-12-03 09:32:15 +01:00
```json
[
{
2021-12-07 11:06:32 +01:00
"type": "url",
"url": "https://url.com/file1.csv",
"method": "GET"
2021-12-03 09:32:15 +01:00
},
{
2021-12-07 11:06:32 +01:00
"type": "ipfs",
"hash": "XXXX"
2021-12-03 09:32:15 +01:00
}
]
```
2021-11-10 14:41:45 +01:00
2021-12-03 09:39:46 +01:00
To get information about the files after encryption, the `/fileinfo` endpoint of _Provider_ returns based on a passed DID an array of file metadata (based on the file type):
2021-11-10 15:26:43 +01:00
2021-11-10 14:41:45 +01:00
```json
2021-11-10 17:33:59 +01:00
[
{
2021-12-03 09:41:06 +01:00
"type": "url",
2021-11-10 17:33:59 +01:00
"contentLength": 100,
"contentType": "application/json"
},
{
2021-12-07 11:06:32 +01:00
"type": "ipfs",
2021-11-10 17:33:59 +01:00
"contentLength": 130,
"contentType": "application/text"
}
2021-11-10 14:41:45 +01:00
]
```
2021-11-10 18:25:31 +01:00
This only concerns metadata about a file, but never the file URLs. The only way to decrypt them is to exchange at least 1 datatoken based on the respective service pricing scheme.
2021-11-11 10:04:39 +01:00
#### Compute Options
2021-11-11 08:02:12 +01:00
2021-11-11 10:04:39 +01:00
An asset with a service of `type` `compute` has the following additional attributes under the `compute` object. This object is required if the asset is of `type` `compute`, but can be omitted for `type` of `access`.
2021-11-11 08:02:12 +01:00
2021-11-12 15:10:15 +01:00
| Attribute | Type | Required | Description |
| ------------------------------------------ | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`allowRawAlgorithm`** | `boolean` | **✓** | If `true`, any passed raw text will be allowed to run. Useful for an algorithm drag & drop use case, but increases risk of data escape through malicious user input. Should be `false` by default in all implementations. |
| **`allowNetworkAccess`** | `boolean` | **✓** | If `true`, the algorithm job will have network access. |
| **`publisherTrustedAlgorithmPublishers `** | Array of `string` | **✓** | If empty, then any published algorithm is allowed. Otherwise, only published algorithms by some publishers are allowed. |
| **`publisherTrustedAlgorithms `** | Array of `publisherTrustedAlgorithms` | **✓** | If empty, then any published algorithm is allowed. (see below). |
2021-11-11 10:04:39 +01:00
2021-09-28 18:07:27 +02:00
The `publisherTrustedAlgorithms ` is an array of objects with the following structure:
2021-11-12 15:10:15 +01:00
| Attribute | Type | Required | Description |
| ------------------------------ | -------- | -------- | ------------------------------------------------------------------------- |
| **`did`** | `string` | **✓** | The DID of the algorithm which is trusted by the publisher. |
| **`filesChecksum`** | `string` | **✓** | Hash of algorithm's `files` section (as `string`). |
| **`containerSectionChecksum`** | `string` | **✓** | Hash of algorithm's `metadata.algorithm.container` section (as `string`). |
2021-09-28 18:07:27 +02:00
2021-11-04 12:55:05 +01:00
To produce `filesChecksum`:
2021-10-04 13:28:05 +02:00
```js
2021-11-10 17:33:59 +01:00
sha256(JSON.Stringify(algorithm_ddo.services[0].files))
2021-09-28 18:07:27 +02:00
```
2021-11-04 12:55:05 +01:00
To produce `containerSectionChecksum`:
2021-10-04 13:28:05 +02:00
```js
2021-11-04 12:59:20 +01:00
sha256(JSON.Stringify(algorithm_ddo.metadata.algorithm.container))
```
2021-10-04 12:54:02 +02:00
Example:
2021-10-04 13:28:05 +02:00
```json
2021-10-04 12:54:02 +02:00
{
2021-11-04 12:33:01 +01:00
"services": [
{
"id": "1",
2021-11-04 12:33:01 +01:00
"type": "access",
2021-11-10 18:25:31 +01:00
"files": "0x044736da6dae39889ff570c34540f24e5e084f...",
2021-11-04 12:33:01 +01:00
"name": "Download service",
"description": "Download service",
"datatokenAddress": "0x123",
2021-11-10 17:33:59 +01:00
"serviceEndpoint": "https://myprovider.com",
2021-11-04 12:33:01 +01:00
"timeout": 0
},
{
"id": "2",
2021-11-04 12:33:01 +01:00
"type": "compute",
2021-11-10 18:25:31 +01:00
"files": "0x6dd05e0edb460623c843a263291ebe757c1eb3...",
2021-11-04 12:33:01 +01:00
"name": "Compute service",
"description": "Compute service",
"datatokenAddress": "0x124",
2021-11-10 17:33:59 +01:00
"serviceEndpoint": "https://myprovider.com",
2021-11-04 12:33:01 +01:00
"timeout": 0,
2021-11-11 15:17:27 +01:00
"compute": {
"allowRawAlgorithm": false,
"allowNetworkAccess": true,
"publisherTrustedAlgorithmPublishers": ["0x234", "0x235"],
"publisherTrustedAlgorithms": [
2021-11-04 12:33:01 +01:00
{
"did": "did:op:123",
"filesChecksum": "100",
"containerSectionChecksum": "200"
},
{
"did": "did:op:124",
"filesChecksum": "110",
"containerSectionChecksum": "210"
}
]
2021-10-04 12:54:02 +02:00
}
2021-11-04 12:33:01 +01:00
}
]
2021-10-04 12:54:02 +02:00
}
```
[User Input](#userinput)
### User Input
Sometimes, you may need some input before consuming a dataset or running an algorithm.
Examples:
- You want to know the desired sampling interval of data in your dataset, before the user is going to download it. So you will define a field called "sampling", ask the user to enter a value and then this parameter is going to be added to the URL of your dataset
- Before running an algorithm, you need to know how many iterations should the algo perform. You are going to define a field called 'iterations', ask the user to enter a value and this parameter is stored in a specific location in your C2D pod, so algo can read it and use that value.
Object consists of an array , in which each element defines a user required field.
An element looks like:
```json
{
"name":"surname",
"type": "text",
"label": "Name",
"required": true,
"description":"Please fill your name",
"options": []
}
```
where:
- name = defines the parameter name
- 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 user input.
- default = default value
- description = description of this element
- options = for select types, a list of options
2021-10-04 12:54:02 +02:00
Example:
```
[
{
"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"
},
{
"name":"developer",
"type": "boolean",
"label": "Developer",
"required": false,
"default': false
"description":"Are you a developer?"
},
{
"name":"interval",
"type": "select",
"label": "Date",
"required": false,
"default": "nodejs"
"options": [
{
"nodejs" : "I love NodeJs"
},
{
"python" : "I love Python"
}
],
"description": "Do you like NodeJs or Python"
},
]
2021-11-04 14:13:32 +01:00
### Credentials
2021-11-12 15:10:15 +01:00
By default, a consumer can access a resource if they have 1 datatoken. _Credentials_ allow the publisher to optionally specify more fine-grained permissions.
2021-11-12 15:10:15 +01:00
Consider a medical data use case, where only a credentialed EU researcher can legally access a given dataset. Ocean supports this as follows: a consumer can only access the resource if they have 1 datatoken _and_ one of the specified `"allow"` credentials.
2021-11-04 18:15:49 +01:00
This is like going to an R-rated movie, where you can only get in if you show both your movie ticket (datatoken) _and_ some identification showing you're old enough (credential).
2021-11-04 18:15:49 +01:00
Only credentials that can be proven are supported. This includes Ethereum public addresses, and in the future [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) and more.
2021-11-04 12:59:20 +01:00
Ocean also supports `"deny"` credentials: if a consumer has any of these credentials, they can not access the resource.
2021-11-04 12:33:01 +01:00
Here's an example object with both `"allow"` and `"deny"` entries:
```json
2021-09-28 18:07:27 +02:00
{
2021-11-04 12:33:01 +01:00
"credentials": {
"allow": [
{
"type": "address",
"values": ["0x123", "0x456"]
}
],
"deny": [
{
"type": "address",
"values": ["0x2222", "0x333"]
}
]
2021-09-28 18:07:27 +02:00
}
}
```
2021-11-10 18:25:31 +01:00
### DDO Checksum
2021-11-04 12:11:24 +01:00
2021-11-10 18:25:31 +01:00
In order to ensure the integrity of the DDO, a checksum is computed for each DDO:
2021-10-04 13:28:05 +02:00
2021-11-04 12:11:24 +01:00
```js
2021-11-10 18:25:31 +01:00
const checksum = sha256(JSON.stringify(ddo))
2021-11-04 12:11:24 +01:00
```
2021-11-10 18:25:31 +01:00
The checksum hash is used when publishing/updating metadata using the `setMetaData` function in the ERC721 contract, and is stored in the event generated by the ERC721 contract:
2021-11-04 12:11:24 +01:00
```solidity
event MetadataCreated(
address indexed createdBy,
uint8 state,
string decryptorUrl,
bytes flags,
bytes data,
bytes metaDataHash,
uint256 timestamp,
uint256 blockNumber
2021-11-04 14:22:19 +01:00
);
2021-11-04 12:11:24 +01:00
event MetadataUpdated(
address indexed updatedBy,
uint8 state,
string decryptorUrl,
bytes flags,
bytes data,
bytes metaDataHash,
uint256 timestamp,
uint256 blockNumber
2021-11-04 14:22:19 +01:00
);
2021-11-04 12:11:24 +01:00
```
2021-11-10 18:25:31 +01:00
_Aquarius_ should always verify the checksum after data is decrypted via a _Provider_ API call.
2021-11-04 12:11:24 +01:00
2021-11-04 14:13:32 +01:00
### State
Each asset has a state, which is held by the NFT contract. The possible states are:
2021-11-10 17:33:59 +01:00
| State | Description |
| ------- | ------------------------------- |
| **`0`** | Active. |
| **`1`** | End-of-life. |
| **`2`** | Deprecated (by another asset). |
| **`3`** | Revoked by publisher. |
| **`4`** | Ordering is temporary disabled. |
2021-11-04 12:11:24 +01:00
## Aquarius Enhanced DDO Response
2021-11-05 09:44:22 +01:00
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.
2021-11-04 14:13:32 +01:00
These additional fields are never stored on-chain, and are never taken into consideration when [hashing the DDO](#ddo-hash).
2021-11-04 12:11:24 +01:00
2021-11-04 12:55:05 +01:00
### NFT
2021-11-04 20:10:21 +01:00
The `nft` object contains information about the ERC721 NFT contract which represents the intellectual property of the publisher.
2021-11-04 12:55:05 +01:00
2021-11-11 15:17:27 +01:00
| 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) |
2021-11-12 15:10:15 +01:00
| **`created`** | `ISO date/time string` | Contains the date of NFT creation. |
2022-01-31 13:25:56 +01:00
| **`tokenURI`** | `string` | tokenURI |
2021-11-04 12:55:05 +01:00
Example:
```json
{
"nft": {
2021-11-16 17:47:02 +01:00
"address": "0x000000",
2021-11-04 12:55:05 +01:00
"name": "Ocean Protocol Asset v4",
"symbol": "OCEAN-A-v4",
2021-11-10 15:26:43 +01:00
"owner": "0x0000000",
2021-11-11 11:07:13 +01:00
"state": 0,
"created": "2000-10-31T01:30:00Z"
2021-11-04 12:55:05 +01:00
}
}
```
2021-11-10 18:25:31 +01:00
### Datatokens
2021-11-04 12:55:05 +01:00
2021-11-10 18:25:31 +01:00
The `datatokens` array contains information about the ERC20 datatokens attached to [asset services](#services).
2021-11-10 17:33:59 +01:00
2021-11-10 18:25:31 +01:00
| Attribute | Type | Description |
| --------------- | -------- | ------------------------------------------------ |
| **`address`** | `string` | Contract address of the deployed ERC20 contract. |
| **`name`** | `string` | Name of NFT set in contract. |
| **`symbol`** | `string` | Symbol of NFT set in contract. |
| **`serviceId`** | `string` | ID of the service the datatoken is attached to. |
2021-11-04 12:11:24 +01:00
2021-11-04 12:55:05 +01:00
Example:
2021-09-28 18:07:27 +02:00
```json
{
2021-11-10 15:26:43 +01:00
"datatokens": [
2021-11-10 17:33:59 +01:00
{
2021-11-16 17:47:29 +01:00
"address": "0x000000",
2021-11-10 17:33:59 +01:00
"name": "Datatoken 1",
"symbol": "DT-1",
2021-11-10 15:26:43 +01:00
"serviceId": "1"
2021-11-10 17:33:59 +01:00
},
{
"address": "0x000001",
2021-11-10 17:33:59 +01:00
"name": "Datatoken 2",
"symbol": "DT-2",
2021-11-10 15:26:43 +01:00
"serviceId": "2"
2021-11-10 17:33:59 +01:00
}
2021-11-10 15:26:43 +01:00
]
2021-11-04 12:33:01 +01:00
}
2021-11-04 12:11:24 +01:00
```
2021-11-10 15:26:43 +01:00
### Event
2021-11-04 12:11:24 +01:00
2021-11-10 15:26:43 +01:00
The `event` section contains information about the last transaction that created or updated the DDO.
2021-11-04 18:15:49 +01:00
2021-11-04 12:33:01 +01:00
Example:
2021-11-04 12:11:24 +01:00
```json
{
2021-11-10 17:33:59 +01:00
"event": {
"tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
"block": 12831214,
"from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
"contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
"datetime": "2000-10-31T01:30:00"
2021-11-10 17:33:59 +01:00
}
2021-11-04 12:33:01 +01:00
}
2021-09-28 18:07:27 +02:00
```
2021-10-09 13:37:25 +02:00
### Purgatory
Contains information about an asset's purgatory status defined in [`list-purgatory`](https://github.com/oceanprotocol/list-purgatory). Marketplace interfaces are encouraged to prevent certain user actions like adding liquidity on assets in purgatory.
| Attribute | Type | Description |
| ------------ | --------- | --------------------------------------------------------------------------------------------- |
| **`state`** | `boolean` | If `true`, asset is in purgatory. |
| **`reason`** | `string` | If asset is in purgatory, contains the reason for being there as defined in `list-purgatory`. |
Example:
```json
{
"purgatory": {
"state": true,
"reason": "Copyright violation"
}
}
```
```json
{
"purgatory": {
"state": false
}
}
```
2021-11-04 12:55:05 +01:00
### Statistics
2021-10-09 13:37:25 +02:00
2021-11-04 12:55:05 +01:00
The `stats` section contains different statistics fields.
2021-10-09 13:37:25 +02:00
2021-11-04 13:20:15 +01:00
| Attribute | Type | Description |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
2022-02-10 12:25:19 +01:00
| **`orders`** | `number` | How often an asset was ordered, meaning how often it was either downloaded or used as part of a compute job. |
2021-11-04 13:20:15 +01:00
2021-11-04 12:33:01 +01:00
Example:
2021-10-09 13:37:25 +02:00
```json
{
"stats": {
2022-02-10 12:25:19 +01:00
"orders": 4
2021-10-09 13:37:25 +02:00
}
2021-11-04 12:33:01 +01:00
}
2021-10-09 13:37:25 +02:00
```
2021-11-04 14:13:32 +01:00
## Full Enhanced DDO Example
2021-10-09 15:03:02 +02:00
```json
2021-10-09 13:37:25 +02:00
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
2021-11-04 13:20:15 +01:00
"version": "4.0.0",
2021-10-09 13:37:25 +02:00
"chainId": 1,
2021-12-28 09:24:33 +01:00
"nftAddress": "0x123",
2021-11-04 12:11:24 +01:00
"metadata": {
2021-11-11 15:17:27 +01:00
"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"
2021-11-04 12:11:24 +01:00
},
"services": [
{
"id": "1",
2021-11-04 12:11:24 +01:00
"type": "access",
2021-11-10 17:33:59 +01:00
"files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735",
2021-11-04 12:11:24 +01:00
"name": "Download service",
"description": "Download service",
"datatokenAddress": "0x123",
2021-11-10 17:33:59 +01:00
"serviceEndpoint": "https://myprovider.com",
2021-11-04 12:11:24 +01:00
"timeout": 0
2021-11-11 10:04:39 +01:00
},
{
"id": "2",
2021-11-11 10:04:39 +01:00
"type": "compute",
"files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735",
"name": "Compute service",
"description": "Compute service",
"datatokenAddress": "0x124",
"serviceEndpoint": "https://myprovider.com",
"timeout": 3600,
2021-11-11 15:17:27 +01:00
"compute": {
"allowRawAlgorithm": false,
"allowNetworkAccess": true,
"publisherTrustedAlgorithmPublishers": ["0x234", "0x235"],
"publisherTrustedAlgorithms": [
2021-11-11 10:04:39 +01:00
{
"did": "did:op:123",
"filesChecksum": "100",
"containerSectionChecksum": "200"
},
{
"did": "did:op:124",
"filesChecksum": "110",
"containerSectionChecksum": "210"
}
]
}
2021-11-04 12:11:24 +01:00
}
],
"credentials": {
"allow": [
{
"type": "address",
"values": ["0x123", "0x456"]
}
],
"deny": [
{
"type": "address",
"values": ["0x2222", "0x333"]
}
]
},
// Enhanced Aquarius response begins here
2021-11-04 12:55:05 +01:00
"nft": {
2021-12-28 09:24:33 +01:00
"address": "0x123",
2021-11-04 12:55:05 +01:00
"name": "Ocean Protocol Asset v4",
"symbol": "OCEAN-A-v4",
2021-11-10 15:26:43 +01:00
"owner": "0x0000000",
2021-11-11 11:07:13 +01:00
"state": 0,
"created": "2000-10-31T01:30:00",
"tokenURI": "xxx"
2021-11-04 12:11:24 +01:00
},
2021-11-10 17:33:59 +01:00
"datatokens": [
2021-11-04 12:11:24 +01:00
{
"address": "0x000000",
2021-11-10 17:33:59 +01:00
"name": "Datatoken 1",
"symbol": "DT-1",
"serviceId": "1"
2021-11-10 15:26:43 +01:00
},
2021-11-10 17:33:59 +01:00
{
"address": "0x000001",
2021-11-10 17:33:59 +01:00
"name": "Datatoken 2",
"symbol": "DT-2",
"serviceId": "2"
}
],
"event": {
"tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
"block": 12831214,
"from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
"contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
"datetime": "2000-10-31T01:30:00"
2021-11-10 17:33:59 +01:00
},
"purgatory": {
"state": false
},
2021-11-04 12:11:24 +01:00
"stats": {
2022-02-10 12:25:19 +01:00
"orders": 4
2021-11-04 12:11:24 +01:00
}
2021-10-09 13:37:25 +02:00
}
```