oceanprotocol/docs
1
0
Fork 0
mirror of https://github.com/oceanprotocol/docs.git synced 2024-11-26 19:49:26 +01:00
Code Releases Activity

more copywriting, example updates

Browse Source
This commit is contained in:
Matthias Kretschmann 2021-11-10 17:25:31 +00:00
parent 93ecc527fb
commit d17b583127
Signed by: m
GPG Key ID: 606EEEF3C479A91F
1 changed files with 35 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
content/concepts/did-ddo.md
View File

@ -19,9 +19,9 @@ A DID Document (DDO) is a JSON blob that holds information about the DID. Given
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 control of a _publisher_. The Ocean network itself does _not_ store the actual resource (e.g. files).
An _asset_ should have 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). The DDO can only be modified by _owners_ or _delegated users_.
A metadata cache like _Aquarius_ can help in reading and searching through encrypted DDO data from the chain. 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 ## Publishing & Retrieving DDOs
@ -31,6 +31,9 @@ Here is the complete flow:
![DDO_flow](images/ddo-flow.png) ![DDO_flow](images/ddo-flow.png)
<details>
<summary>UML source</summary>
```text ```text
title DDO flow title DDO flow
@ -47,20 +50,25 @@ Provider -> Aquarius: DDO
Aquarius -> Aquarius : validate DDO Aquarius -> Aquarius : validate DDO
Aquarius -> Aquarius : cache DDO Aquarius -> Aquarius : cache DDO
Aquarius -> Aquarius : enhance cached DDO in response with additional infos like `events` & `stats` Aquarius -> Aquarius : enhance cached DDO in response with additional infos like `events` & `stats`
```
````
</details>
## DID ## DID
In Ocean, a DID is a string that looks like: In Ocean, a DID is a string that looks like this:
```text ```text
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
``` ````
where The part after `did:op:` is the checksum of the ERC721 contract address and the chain the asset has been published to:
```text ```js
0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea = sha256(ERC721 contract address + chainId) const checksum = sha256(ERC721 contract address + chainId)
console.log(checksum)
// 0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
``` ```
It follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme). It follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
@ -185,13 +193,13 @@ Example:
} }
``` ```
During the publish process file URLs need to be encrypted with a respective _Provider_ API call before storing the DDO on-chain. For this an array of strings with one or multiple URLs is what gets encrypted: 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 strings with one or multiple URLs is what gets encrypted and send to _Provider_:
```json ```json
["https://url.com/file1.csv", "https://url.com/file2.csv"] ["https://url.com/file1.csv", "https://url.com/file2.csv"]
``` ```
To get information about the files after encryption, the `/fileinfo` endpoint of _Provider_ must return based on passed DID: To get information about the files after encryption, the `/fileinfo` endpoint of _Provider_ returns based on a passed DID an array of file metadata:
```json ```json
[ [
@ -206,6 +214,8 @@ To get information about the files after encryption, the `/fileinfo` endpoint of
] ]
``` ```
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.
#### Compute Privacy #### Compute Privacy
An asset with a service of `type` `compute` has the following additional attributes under the `privacy` object. This object is required if the asset is of `type` `compute`, but can be omitted for `type` of `access`. An asset with a service of `type` `compute` has the following additional attributes under the `privacy` object. This object is required if the asset is of `type` `compute`, but can be omitted for `type` of `access`.
@ -244,6 +254,7 @@ Example:
"services": [ "services": [
{ {
"type": "access", "type": "access",
"files": "0x044736da6dae39889ff570c34540f24e5e084f...",
"name": "Download service", "name": "Download service",
"description": "Download service", "description": "Download service",
"datatokenAddress": "0x123", "datatokenAddress": "0x123",
@ -252,6 +263,7 @@ Example:
}, },
{ {
"type": "compute", "type": "compute",
"files": "0x6dd05e0edb460623c843a263291ebe757c1eb3...",
"name": "Compute service", "name": "Compute service",
"description": "Compute service", "description": "Compute service",
"datatokenAddress": "0x124", "datatokenAddress": "0x124",
@ -312,26 +324,15 @@ Here's an example object with both `"allow"` and `"deny"` entries:
} }
``` ```
For future usage, we can extend that with different credentials types. ### DDO Checksum
Example: In order to ensure the integrity of the DDO, a checksum is computed for each DDO:
```json
{
"type": "credential3Box",
"values": ["profile1", "profile2"]
}
```
### DDO Hash
In order to ensure the integrity of the DDO, a hash is computed for each DDO:
```js ```js
const hash = sha256(JSON.stringify(ddo)) const checksum = sha256(JSON.stringify(ddo))
``` ```
The hash is used when publishing/update metadata using the `setMetaData` function in the ERC721 contract, and is stored in the event generated by the ERC721 contract: 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:
```solidity ```solidity
event MetadataCreated( event MetadataCreated(
@ -357,7 +358,7 @@ event MetadataUpdated(
); );
``` ```
_Aquarius_ should always check the hash after data is decrypted via a _Provider_ API call, in order to ensure DDO integrity. _Aquarius_ should always verify the checksum after data is decrypted via a _Provider_ API call.
### State ### State
@ -403,16 +404,16 @@ Example:
} }
``` ```
### DataTokens ### Datatokens
The `datatokens` array contains information about the ERC20 datatokens attached to [services](#services). The `datatokens` array contains information about the ERC20 datatokens attached to [asset services](#services).
| Attribute | Type | Description | | Attribute | Type | Description |
| --------------- | -------- | ----------------------------------------------------- | | --------------- | -------- | ------------------------------------------------ |
| **`address`** | `string` | Contract address of the deployed ERC721 NFT contract. | | **`address`** | `string` | Contract address of the deployed ERC20 contract. |
| **`name`** | `string` | Name of NFT set in contract. | | **`name`** | `string` | Name of NFT set in contract. |
| **`symbol`** | `string` | Symbol of NFT set in contract. | | **`symbol`** | `string` | Symbol of NFT set in contract. |
| **`serviceId`** | `string` | ID of the service the datatoken is attached to. | | **`serviceId`** | `string` | ID of the service the datatoken is attached to. |
Example: Example: