Specification of decentralized identifiers for assets in Ocean Protocol using the DDO standard.
The below diagram shows the high-level DDO schema depicting the content of each data structure and the relations between them.
Please note that some data structures apply only on certain types of services or assets.
A DDO in Ocean has these required attributes:
This object holds information describing the actual asset.
* Required
** Required for algorithms only
Services define the access for an asset, and each service is represented by its respective datatoken.
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.
* Required
** Required for compute assets only
The files field is returned as a string which holds the encrypted file URLs.
By default, a consumer can access a resource if they have 1 datatoken. Credentials allow the publisher to optionally specify more fine-grained permissions.
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.
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).
Only credentials that can be proven are supported. This includes Ethereum public addresses and in the future and more.
Ocean also supports deny credentials: if a consumer has any of these credentials, they can not access the resource.
Here's an example object with both allow and deny entries:
In order to ensure the integrity of the DDO, a checksum is computed for each DDO:
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.
Aquarius should always verify the checksum after data is decrypted via a Provider API call.
Each asset has a state, which is held by the NFT contract. The possible states are:
States details:
Active: Assets in the "Active" state are fully functional and available for discovery in Ocean Market, and other components. Users can search for, view, and interact with these assets. Ordering is allowed, which means users can place orders to purchase or access the asset's services.
End-of-life: Assets in the "End-of-life" state remain discoverable but cannot be ordered. This state indicates that the assets are usually deprecated or outdated, and they are no longer actively promoted or maintained.
Deprecated (by another asset): This state indicates that another asset has deprecated the current asset. Deprecated assets are not discoverable, and ordering is not allowed. Similar to the "End-of-life" state, deprecated assets are not listed under the owner's profile.
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 .
The datatokens array contains information about the ERC20 datatokens attached to .
Indexed Metadata contains off-chain data that helps storing assets pricing details and displaying them properly within decenterlized applications.
Indexed Metadata is composed of the following objects:
NFT
Event
Purgatory
Stats
When hashing is performed against a document, indexedMeatadata object has to be removed from the DDO structure, its off-chain data being stored and maintained only in the Indexer database, within DDO collection.
The nft object contains information about the ERC721 NFT contract which represents the intellectual property of the publisher.
The event section contains information about the last transaction that created or updated the DDO.
Contains information about an asset's purgatory status defined in . Marketplace interfaces are encouraged to prevent certain user actions like adding liquidity on assets in purgatory.
The stats section contains a list of different statistics fields.
For algorithms and datasets that are used for compute to data, there are additional fields and objects within the DDO structure that you need to consider. These include:
compute attributes
publisherTrustedAlgorithms
consumerParameters
Details for each of these are explained on the .
The below diagram shows the detailed DDO schema depicting the content of each data structure and the relations between them.
Please note that some data structures apply only on certain types of services or assets.
nftAddress
string
NFT contract linked to this asset
metadata
Stores an object describing the asset.
services
Stores an array of services defining access to the asset.
credentials
Describes the credentials needed to access a dataset in addition to the services definition.
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.
contentLanguage
string
The language of the content. Use one of the language codes from the
tags
Array of string
Array of keywords or tags used to describe this content. Empty by default.
categories
Array of string
Array of categories associated to the asset. Note: recommended to use tags instead of this.
additionalInformation
Object
Stores additional information, this is customizable by publisher
algorithm**
Information about asset of type algorithm
datatokenAddress*
string
Datatoken
serviceEndpoint*
string
Provider URL (schema + host)
files*
Encrypted file.
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**
If service is of type compute, holds information about the compute-related privacy settings & resources.
consumerParameters
An object the defines required consumer input before consuming the asset
additionalInformation
Object
Stores additional information, this is customizable by publisher
2
Deprecated (by another asset)
No
No
No
3
Revoked by publisher
No
No
No
4
Ordering is temporary disabled
Yes
No
Yes
5
Asset unlisted.
No
Yes
Yes
Revoked by publisher: When an asset is revoked by its publisher, it means that the publisher has explicitly revoked access or ownership rights to the asset. Revoked assets are not discoverable, and ordering is not allowed.
Ordering is temporarily disabled: Assets in this state are still discoverable, but ordering functionality is temporarily disabled. Users can view the asset and gather information, but they cannot place orders at that moment. However, these assets are still listed under the owner's profile.
Asset unlisted: Assets in the "Asset unlisted" state are not discoverable. However, users can still place orders for these assets, making them accessible. Unlisted assets are listed under the owner's profile, allowing users to view and access them.
state
number
State of the asset reflecting the NFT contract value. See
created
ISO date/time string
Contains the date of NFT creation.
tokenURI
string
tokenURI
orders
number
How often an asset was ordered, meaning how often it was either downloaded or used as part of a compute job.
prices
array
Pricing schemas list for this datatoken (a fixedrate and dispenser can co-exist for the same datatoken).
type
string
Static values: "fixedrate", "dispenser".
price
string
Price for schema (for dispenser is default "0").
contract
string
Contract address of pricing schema contract.
token
string
Basetoken for fixedrate, Datatoken for dispenser.
exchangeId
string
Just for fixedrate.
@context
Array of string
Contexts used for validation.
id
string
Computed as sha256(address of ERC721 contract + chainId).
version
string
Version information in SemVer notation referring to this DDO spec version, like 4.1.0.
chainId
number
Stores the chainId of the network the DDO was published to.
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.
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.
id*
string
Unique ID
type*
string
Type of service access, compute, wss etc.
name
string
Service friendly name
description
string
Service description
0
Active
Yes
Yes
Yes
1
End-of-life
Yes
No
No
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.
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
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.
datatokenAddress
string
Datatoken address which has the pricing schema attached.
name
string
Name of the datatoken with pricing schema.
symbol
string
Symbol of the datatoken with pricing schema.
serviceId
string
Service ID of the datatoken with pricing schema.
{
"@context": ["https://w3id.org/did/v1"],
"id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
"version": "4.1.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"]
}
]
},
"indexedMetadata": {
"stats": [
{
"datatokenAddress": "0x35f74f653Dcb291838aa8AF8Be1E1eF30e749bb7",
"name": "BDT1",
"symbol": "DT1",
"serviceId": "0",
"orders": 1,
// this service has one dispenser available
"prices": [
{
"type": "dispenser",
"price": "0",
"contract": "0x457"
}
]
},
{
"datatokenAddress": "0x34e84f653Dcb291838aa8AF8Be1E1eF30e749ba0",
"name": "BDT2",
"symbol": "DT2",
"serviceId": "1",
"orders": 5,
// this service accepts OCEAN for payment, costs 1 token per access
"prices":
[
{
"type": "fixedrate",
"price": "1",
"token":"0x967da4048cD07aB37855c090aAF366e4ce1b9F48",
"contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48", "exchangeId": "23434"
}
]
},
{
"datatokenAddress": "0x1234565",
"name": "BDT3",
"symbol": "DT3",
"serviceId": "2",
"orders": 5,
// this service accepts either 2 OCEAN or 1 FETCH for payment
"prices":
[
{
"type": "fixedrate",
"price": "2",
"token":"0x967da4048cD07aB37855c090aAF366e4ce1b9F48",
"contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48",
"exchangeId": "23434"
},
{
"type": "fixedrate",
"price": "1",
"token":"0xaea46A60368A7bD060eec7DF8CBa43b7EF41Ad85",
"contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48",
"exchangeId": "4535"
}
]
}
],
"nft": {
"address": "0x123",
"name": "Ocean Protocol Asset",
"symbol": "OCEAN-A",
"owner": "0x0000000",
"state": 0,
"created": "2000-10-31T01:30:00",
"tokenURI": "xxx"
},
"event": {
"tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
"block": 12831214,
"from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
"contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
"datetime": "2000-10-31T01:30:00"
},
"purgatory": {
"state": false
}
},
"datatokens": [
{
"address": "0x000000",
"name": "Datatoken 1",
"symbol": "DT-1",
"serviceId": "1"
},
{
"address": "0x000001",
"name": "Datatoken 2",
"symbol": "DT-2",
"serviceId": "2"
}
]
}{
"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"
}
}{
"files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735"
}{
"credentials": {
"allow": [
{
"type": "address",
"values": ["0x123", "0x456"]
}
],
"deny": [
{
"type": "address",
"values": ["0x2222", "0x333"]
}
]
}
}const checksum = sha256(JSON.stringify(ddo));event MetadataCreated(
address indexed createdBy,
uint8 state,
string decryptorUrl,
bytes flags,
bytes data,
bytes metaDataHash,
uint256 timestamp,
uint256 blockNumber
);
event MetadataUpdated(
address indexed updatedBy,
uint8 state,
string decryptorUrl,
bytes flags,
bytes data,
bytes metaDataHash,
uint256 timestamp,
uint256 blockNumber
);{
"datatokens": [
{
"address": "0x000000",
"name": "Datatoken 1",
"symbol": "DT-1",
"serviceId": "1"
},
{
"address": "0x000001",
"name": "Datatoken 2",
"symbol": "DT-2",
"serviceId": "2"
}
]
}{
"nft": {
"address": "0x000000",
"name": "Ocean Protocol Asset",
"symbol": "OCEAN-A",
"owner": "0x0000000",
"state": 0,
"created": "2000-10-31T01:30:00Z"
}
}{
"event": {
"tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
"block": 12831214,
"from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
"contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
"datetime": "2000-10-31T01:30:00"
}
}{
"purgatory": {
"state": true,
"reason": "Copyright violation"
}
}{
"purgatory": {
"state": false
}
}{
"stats":
[
{
"datatokenAddress": "0x123",
"name": "Branin dataset: DT1",
"symbol": "DT1",
"serviceId": "0",
"orders": 1,
"prices":
[
{
"type": "fixedrate", // or "dispenser"
"price": "123",
"contract": "<contractAddress>",
"token": "0x89777", // token accepted for payment
"exchangeId": "xx" // only for fre, this is exhangeID
}
]
}
]
}