mirror of
https://github.com/oceanprotocol/docs.git
synced 2024-11-26 19:49:26 +01:00
more copywriting, example updates
This commit is contained in:
parent
93ecc527fb
commit
d17b583127
GPG Key ID:
606EEEF3C479A91F
@ -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_ 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
|
||||
|
||||
@ -31,6 +31,9 @@ Here is the complete flow:
|
||||
|
||||
|
||||
|
||||
<details>
|
||||
<summary>UML source</summary>
|
||||
|
||||
```text
|
||||
title DDO flow
|
||||
|
||||
@ -47,20 +50,25 @@ Provider -> Aquarius: DDO
|
||||
Aquarius -> Aquarius : validate DDO
|
||||
Aquarius -> Aquarius : cache DDO
|
||||
Aquarius -> Aquarius : enhance cached DDO in response with additional infos like `events` & `stats`
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
</details>
|
||||
|
||||
## DID
|
||||
|
||||
In Ocean, a DID is a string that looks like:
|
||||
In Ocean, a DID is a string that looks like this:
|
||||
|
||||
```text
|
||||
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
|
||||
0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea = sha256(ERC721 contract address + chainId)
|
||||
```js
|
||||
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).
|
||||
@ -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
|
||||
["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
|
||||
[
|
||||
@ -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
|
||||
|
||||
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": [
|
||||
{
|
||||
"type": "access",
|
||||
"files": "0x044736da6dae39889ff570c34540f24e5e084f...",
|
||||
"name": "Download service",
|
||||
"description": "Download service",
|
||||
"datatokenAddress": "0x123",
|
||||
@ -252,6 +263,7 @@ Example:
|
||||
},
|
||||
{
|
||||
"type": "compute",
|
||||
"files": "0x6dd05e0edb460623c843a263291ebe757c1eb3...",
|
||||
"name": "Compute service",
|
||||
"description": "Compute service",
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "credential3Box",
|
||||
"values": ["profile1", "profile2"]
|
||||
}
|
||||
```
|
||||
|
||||
### DDO Hash
|
||||
|
||||
In order to ensure the integrity of the DDO, a hash is computed for each DDO:
|
||||
In order to ensure the integrity of the DDO, a checksum is computed for each DDO:
|
||||
|
||||
```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
|
||||
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
|
||||
|
||||
@ -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 |
|
||||
| --------------- | -------- | ----------------------------------------------------- |
|
||||
| **`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. |
|
||||
| **`serviceId`** | `string` | ID of the service the datatoken is attached to. |
|
||||
| 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. |
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user