update

content/concepts/did-ddo.md

@@ -78,24 +78,30 @@ It follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-gene
 ## DDO Attributes
 
 
-A DDO has these standard attributes:
+A DDO has these standard attributes (required):
 
 - `@context`   = array, contexts used for validation
 - `id`  = string, computed as sha256(address of ERC721 contract + chainId)
-- `created` = updated by aquarius, contains the date of publishing (block.timestamp)
+- `created` = contains the date of publishing, ISO Date Time Format yyyy-MM-dd'T'HH:mm:ss. SSSXXX — for example, "2000-10-31T01:30:00.000-05:00
-- `updated`  = updated by aquarius, contains the date of the update (block.timestamp)
+- `updated`  = contains the date of last update, ISO Date Time Format
 - `proof` = proof of ownership, optional
 
 
 In Ocean, the DDO also has:
 
-- `version` - stores version information (`v4` for us)
+- `version` - string, stores version information (example: `v4.0.0`)
+- `chainId` - integer, stores chainId of the network used
 - `metadata` - stores metadata information [Metadata](#metadata)
 - `services` - stores an array of services [Services](#services)
 - `credentials` - optional flag, which describes the credentials needed to access a dataset [Credentials](#credentials)
 - `status` -  stores status related fields [Status](#status)
 - `files` and `encryptedFiles` - stores file(s) informations [Files](#files)
+
+
+In addition, Aquarius will add the following objects, which are not taken into account when [DDO hash](#ddo-hash) is calculated:
+
 - `event` - stores the last event information [Event](#event)
+- `stats` - stores several fields for statistics [Stats](#stats)
 
 
 ## Metadata
@@ -106,7 +112,7 @@ The object has the following attributes.
 | ------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`description`**     | Text          | **Yes**       | Details of what the resource is. For a dataset, this attribute explains what the data represents and what it can be used for.|
 | **`copyrightHolder`** | Text          | No       | The party holding the legal copyright. Empty by default.   
-| **`name`**          | Text                  |**Yes**   | Descriptive name or title of the asset.                                                                                                                                                           |
+| **`name`**          | Text                  |**Yes**   | Descriptive name or title of the asset.  |
 | **`type`**          | Text                  |**Yes**   | Asset type. Includes `"dataset"` (e.g. csv file), `"algorithm"` (e.g. Python script). Each type needs a different subset of metadata attributes. |
 | **`author`**        | Text                  |**Yes**   | Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.).                                                                                                                            |
 | **`license`**       | Text                  |**Yes**   | 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". |
@@ -261,8 +267,7 @@ Here's an example object with both `"allow"` and `"deny"` entries.
                "0x456"
             ]
          }
-      ]
+      ],
-      },
       "deny":[
         {
          "type":"address",
@@ -364,3 +369,116 @@ This section is auto-completed by aquarius.
     "chainId": 1,
   }
 ```
+
+## Stats
+
+The `stats` section contains different statics fields
+This section is auto-completed by aquarius.
+
+```json
+{
+  {...},
+  "stats": {
+    "consumes":4
+  }
+```
+
+
+## DDO Hash
+In order to ensure the integrity, a hash is computed for each DDO, following the next steps:
+
+ - remove `event` object from root (if exists)
+ - remove `stats` object from root (if exists)
+ - hash = sha256(JSON.stringify(DDO))
+
+ The hash is used when publishing/update metadata using setMetaData function in ERC721 contract and it is stored in the event generated by the ERC721 contract:
+ ```
+ event MetadataCreated(
+        address indexed createdBy,
+        uint8 state,
+        string decryptorUrl,
+        bytes flags,
+        bytes data,
+        bytes hash,
+        string metaDataDecryptorAddress,
+        uint256 timestamp,
+        uint256 blockNumber
+    );
+    event MetadataUpdated(
+        address indexed updatedBy,
+        uint8 state,
+        string decryptorUrl,
+        bytes flags,
+        bytes data,
+        bytes hash,
+        string metaDataDecryptorAddress,
+        uint256 timestamp,
+        uint256 blockNumber
+    );
+```
+
+Aquarius should always chech the hash after data is decrypted(provider api called), in order to ensure ddo integrity.
+
+
+## Full DDO Example:
+```
+{
+  "@context": ["https://w3id.org/did/v1"],
+  "id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
+  "created": "2020-11-15T12:27:48Z",
+  "updated": "2021-05-17T21:58:02Z",
+  "version": "v4.0.0",
+  "chainId": 1,
+  "metadata":{
+      "description": "Sample description",
+      "name": "Sample asset",
+      "type": "dataset",
+      "author": "OPF",
+      "license": "https://market.oceanprotocol.com/terms",
+   },
+   files:{
+      "files": [
+            {
+              "contentLength": "3975",
+              "contentType": "text/csv"
+            }
+          ],
+      "encryptedFiles": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735",
+   },
+   "services":[
+      {
+         "type":"access",
+         "name":"Download service",
+         "description":"Download service",
+         "datatokenAddress":"0x123",
+         "providerEndpoint":"https://myprovider",
+         "timeout":0
+      }
+   ],
+   "credentials":{
+      "allow":[
+         {
+            "type":"address",
+            "values":[
+               "0x123",
+               "0x456"
+            ]
+         }
+      ],
+      "deny":[
+        {
+         "type":"address",
+         "values":[
+            "0x2222",
+            "0x333"
+         ]
+        }
+      ]
+   },
+   "status": {
+      "status": 0,
+      "isListed": true,
+      "isOrderDisabled": false
+   }
+}
+```