OriginTrail
Search…
Javascript SDK (dkg.js)
Javascript library for the Decentralized Knowledge Graph.
If you are looking to build Web3 applications on the OriginTrail DKG, the dkg.js SDK library is the best place to start!
The DKG SDK is used together with an OriginTrail node (the node is it's dependency). Therefore you either need to run a node on your local environment or a hosted OT-Node, in order to use the SDK.
This library operates with OriginTrail nodes starting with v6.

Installation

The library can be used both in the browser or in a NodeJS application.

In the Browser

Use the prebuilt dist/dkg.min.js, or build using the DKG.js repository:
1
npm run build
Copied!
Then include dist/dkg.min.js in your html file. This will expose DKG on the window object:
1
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/web3.min.js"></script>
2
<script src="./dist/dkg.min.js"></script>
3
<script>
4
window.addEventListener('load', async function () {
5
// TODO
6
});
7
</script>
Copied!
Make sure to also include Web3.js library as it is a dependency for DKG.js!

In NodeJS apps

Run the command to install dependency from the NPM repository:
1
npm install dkg.js
Copied!
Then include dkg.js in your node file. This will expose DKG on as a variable:
1
const DKG = require('dkg.js');
Copied!

​
πŸ‚
Quickstart

To use the DKG library, you need to connect to a running local or remote OT-Node.
1
const dkg = new DKG({
2
endpoint: '127.0.0.1',
3
port: '8900',
4
useSSL: false,
5
loglevel: 'trace'
6
});
7
​
8
var result = await dkg.nodeInfo();
9
console.log(JSON.stringify(result, null, 2));
Copied!
In the code snippet above, you enter the node's hostname, port, type of protocol, and log level. After connecting to the node, it will log the informations about node, like:
1
{
2
"version": "6.0.0-beta.1.30",
3
"auto_update": false,
4
"telemetry": false
5
}
Copied!
The library has assets and native modules. Assets module is intended for handling assets on the network, while native module is intended for basic protocol operations on the network, such as searching, executing queries and retrieving proofs.

Create an asset

Asset presents a digital or physical object indexed on the DKG. Asset used in this tutorial is maintained by schema.org can be found here.
It follows the standard and contains an object of type Product with its description, name, image, and other details. An extensive documentation for Product class can be found here https://schema.org/Product. The sample dataset values can be referred below:
1
{
2
"@context": "https://schema.org",
3
"@type": "Product",
4
"aggregateRating": {
5
"@type": "AggregateRating",
6
"ratingValue": "3.5",
7
"reviewCount": "11"
8
},
9
"description": "0.7 cubic feet countertop microwave. Has six preset cooking categories and convenience features like Add-A-Minute and Child Lock.",
10
"name": "Kenmore White 17\" Microwave",
11
"image": "kenmore-microwave-17in.jpg",
12
"offers": {
13
"@type": "Offer",
14
"availability": "https://schema.org/InStock",
15
"price": "55.00",
16
"priceCurrency": "USD"
17
},
18
"review": [
19
{
20
"@type": "Review",
21
"author": "Ellie",
22
"datePublished": "2011-04-01",
23
"reviewBody": "The lamp burned out and now I have to replace it.",
24
"name": "Not a happy camper",
25
"reviewRating": {
26
"@type": "Rating",
27
"bestRating": "5",
28
"ratingValue": "1",
29
"worstRating": "1"
30
}
31
},
32
{
33
"@type": "Review",
34
"author": "Lucas",
35
"datePublished": "2011-03-25",
36
"reviewBody": "Great microwave for the price. It is small and fits in my apartment.",
37
"name": "Value purchase",
38
"reviewRating": {
39
"@type": "Rating",
40
"bestRating": "5",
41
"ratingValue": "4",
42
"worstRating": "1"
43
}
44
}
45
]
46
}
Copied!
Index the asset with associated keywords. In this example, the keyword is microwave:
1
var result = await dkg.assets.create({
2
"@context": "https://schema.org",
3
"@type": "Product",
4
"aggregateRating": {
5
"@type": "AggregateRating",
6
"ratingValue": "3.5",
7
"reviewCount": "11"
8
},
9
"description": "0.7 cubic feet countertop microwave. Has six preset cooking categories and convenience features like Add-A-Minute and Child Lock.",
10
"name": "Kenmore White 17\" Microwave",
11
"image": "kenmore-microwave-17in.jpg",
12
"offers": {
13
"@type": "Offer",
14
"availability": "https://schema.org/InStock",
15
"price": "55.00",
16
"priceCurrency": "USD"
17
},
18
"review": [
19
{
20
"@type": "Review",
21
"author": "Ellie",
22
"datePublished": "2011-04-01",
23
"reviewBody": "The lamp burned out and now I have to replace it.",
24
"name": "Not a happy camper",
25
"reviewRating": {
26
"@type": "Rating",
27
"bestRating": "5",
28
"ratingValue": "1",
29
"worstRating": "1"
30
}
31
},
32
{
33
"@type": "Review",
34
"author": "Lucas",
35
"datePublished": "2011-03-25",
36
"reviewBody": "Great microwave for the price. It is small and fits in my apartment.",
37
"name": "Value purchase",
38
"reviewRating": {
39
"@type": "Rating",
40
"bestRating": "5",
41
"ratingValue": "4",
42
"worstRating": "1"
43
}
44
}]
45
}, {
46
keywords: ['microwave'],
47
visibility: 'public'
48
})
49
let ual = result.data.metadata.UALs[0];
50
console.log(ual);
Copied!
After returning the result, the asset's unique identifier (UAL) is logged. The complete response of the method is:
1
{
2
status: 'COMPLETED',
3
data: {
4
id: '0b2f32a380f61fda8a3b2461074183dfbc9e19c0cbb59275969e6370aa5b26cf',
5
rootHash: '94ad72c79a88fd2da048cc8c4b3abbdc2cd507ab4b9fccfacd9eae0f8907dac3',
6
signature: '0x2a036001d2ca32fb2e528d6e8c414ab86f5b000e87558ae9c75a74c46bcd4fc16d47e865412341640b3d81e05fd2e4ed9f96d63188ad28476b276ba1d7c06d581b',
7
metadata: {
8
type: 'Product',
9
UALs: ['aa1bd80f61fda8a3b2461074183dfbc9e19c0cbb59275969e6370aa5b26cf']
10
timestamp: '2022-30-30T13:08:14.770Z',
11
issuer: '0xbd084ab97c704fe4a6d620cb7c30c0be0366646f',
12
visibility: true,
13
dataHash: 'ed13153fa4090eceedf6c1dd1aa030ec45ab75c2f9510c64a2014f1c6424e7dd'
14
},
15
blockchain: {
16
name: 'polygon::testnet',
17
transactionHash: '0x2450007ccaec94e18f2d0ed20e776f05aa43ab6f8480d3ee2d77c61bece71184'
18
}
19
}
20
}
21
​
Copied!

Read an asset from the DKG

Data are persisted on the network by indexing and replicating on the DKG. Assets consist of building blocks entitled as assertions that are immutable and verifiable. Assets could be resolved from the network by using UAL:
1
var productProxy = await dkg.assets.get(ual);
2
​
3
const productData = await productProxy.data.valueOf;
4
console.log(JSON.stringify(productData));
Copied!
The proxy object can access any property in an object except an array (which is case in this tutorial), like:
1
await productProxy.data.name
Copied!
The response response of the asset's data is:
1
{
2
"@context": "https://www.schema.org/",
3
"@graph": [
4
{
5
"aggregateRating": {
6
"id": "_:b1",
7
"ratingValue": "3.5",
8
"reviewCount": "11",
9
"type": "AggregateRating"
10
},
11
"description": "0.7 cubic feet countertop microwave. Has six preset cooking categories and convenience features like Add-A-Minute and Child Lock.",
12
"name": "Kenmore White 17\" Microwave",
13
"offers": {
14
"availability": "https://schema.org/InStock",
15
"id": "_:b2",
16
"price": "55.00",
17
"priceCurrency": "USD",
18
"type": "Offer"
19
},
20
"proof": {
21
"account": "0xE6976A991A9C32aB665E1118Fd7cfDB58A23116d",
22
"hash": "0x7bc087f4ef9d0dc15fef823bff9c78cc5cca8be0a85234afcfd807f412f40877",
23
"id": "_:b3",
24
"signature": "0x13a970137bd89ac8e812aafd049f74c1fa7138b9ed1b94a177a9c02af063038b39086b110b6751d3f18b4ba39cbeaaf506fed386828144f1826a4215a4499abc1c"
25
},
26
"review": [
27
{
28
"author": "Ellie",
29
"datePublished": "2011-04-01",
30
"id": "_:b4",
31
"name": "Not a happy camper",
32
"reviewBody": "The lamp burned out and now I have to replace it.",
33
"reviewRating": {
34
"bestRating": "5",
35
"id": "_:b6",
36
"ratingValue": "1",
37
"type": "Rating",
38
"worstRating": "1"
39
},
40
"type": "Review"
41
},
42
{
43
"author": "Lucas",
44
"datePublished": "2011-03-25",
45
"id": "_:b5",
46
"name": "Value purchase",
47
"reviewBody": "Great microwave for the price. It is small and fits in my apartment.",
48
"reviewRating": {
49
"bestRating": "5",
50
"id": "_:b7",
51
"ratingValue": "4",
52
"type": "Rating",
53
"worstRating": "1"
54
},
55
"type": "Review"
56
}
57
],
58
"type": "Product"
59
},
60
{
61
"id": "_:b1",
62
"ratingValue": "3.5",
63
"reviewCount": "11",
64
"type": "AggregateRating"
65
},
66
{
67
"availability": "https://schema.org/InStock",
68
"id": "_:b2",
69
"price": "55.00",
70
"priceCurrency": "USD",
71
"type": "Offer"
72
},
73
{
74
"account": "0xE6976A991A9C32aB665E1118Fd7cfDB58A23116d",
75
"hash": "0x7bc087f4ef9d0dc15fef823bff9c78cc5cca8be0a85234afcfd807f412f40877",
76
"id": "_:b3",
77
"signature": "0x13a970137bd89ac8e812aafd049f74c1fa7138b9ed1b94a177a9c02af063038b39086b110b6751d3f18b4ba39cbeaaf506fed386828144f1826a4215a4499abc1c"
78
},
79
{
80
"author": "Ellie",
81
"datePublished": "2011-04-01",
82
"id": "_:b4",
83
"name": "Not a happy camper",
84
"reviewBody": "The lamp burned out and now I have to replace it.",
85
"reviewRating": {
86
"bestRating": "5",
87
"id": "_:b6",
88
"ratingValue": "1",
89
"type": "Rating",
90
"worstRating": "1"
91
},
92
"type": "Review"
93
},
94
{
95
"author": "Lucas",
96
"datePublished": "2011-03-25",
97
"id": "_:b5",
98
"name": "Value purchase",
99
"reviewBody": "Great microwave for the price. It is small and fits in my apartment.",
100
"reviewRating": {
101
"bestRating": "5",
102
"id": "_:b7",
103
"ratingValue": "4",
104
"type": "Rating",
105
"worstRating": "1"
106
},
107
"type": "Review"
108
},
109
{
110
"bestRating": "5",
111
"id": "_:b6",
112
"ratingValue": "1",
113
"type": "Rating",
114
"worstRating": "1"
115
},
116
{
117
"bestRating": "5",
118
"id": "_:b7",
119
"ratingValue": "4",
120
"type": "Rating",
121
"worstRating": "1"
122
}
123
]
124
}
Copied!
If JSON-LD type is supported on the network, the document should be framed according to the frame document. Otherwise, the result is framed by using the default (empty) frame document, as shown above.

Update an asset on the DKG

Assets on the DKG can be updated by providing the latest state for the asset:
1
var result = await dkg.assets.update({
2
"@context": "https://schema.org",
3
"@type": "Product",
4
"description": "0.7 cubic feet countertop microwave. Has six preset cooking categories and convenience features like Add-A-Minute and Child Lock.",
5
"name": "Kenmore Black 17\" Microwave",
6
"image": "kenmore-microwave-17in.jpg"
7
}, ual, {
8
keywords: ['microwave'],
9
visibility: 'public'
10
})
Copied!
The result of operation is the same as for create operation. The updated asset has different name, so in order to present the changes, let's retrieve the data from the proxy:
1
console.log(await productProxy.data.valueOf);
Copied!
The latest state of the product is:
1
{
2
"@context": "https://www.schema.org/",
3
"@graph": [
4
{
5
"description": "0.7 cubic feet countertop microwave. Has six preset cooking categories and convenience features like Add-A-Minute and Child Lock.",
6
"name": "Kenmore Black 17\" Microwave",
7
"proof": {
8
"account": "0xE6976A991A9C32aB665E1118Fd7cfDB58A23116d",
9
"hash": "0x7bc087f4ef9d0dc15fef823bff9c78cc5cca8be0a85234afcfd807f412f40877",
10
"id": "_:b1",
11
"signature": "0x13a970137bd89ac8e812aafd049f74c1fa7138b9ed1b94a177a9c02af063038b39086b110b6751d3f18b4ba39cbeaaf506fed386828144f1826a4215a4499abc1c"
12
},
13
"type": "Product"
14
},
15
{
16
"account": "0xE6976A991A9C32aB665E1118Fd7cfDB58A23116d",
17
"hash": "0x7bc087f4ef9d0dc15fef823bff9c78cc5cca8be0a85234afcfd807f412f40877",
18
"id": "_:b1",
19
"signature": "0x13a970137bd89ac8e812aafd049f74c1fa7138b9ed1b94a177a9c02af063038b39086b110b6751d3f18b4ba39cbeaaf506fed386828144f1826a4215a4499abc1c"
20
}
21
]
22
}
Copied!

Search for an entity or an assertion on the DKG

DKG can be searched by keywords for related assets and assertions. Search result consists of elements listed by score and issuer.
Entity search returns latest state of assets indexed by provided keywor:
1
var result = dkg.search({ query: 'ExecutiveAnvil', resultType: 'entities' });
2
console.log(JSON.stringify(result));
Copied!
The result the search is the following:
1
{
2
"@context": {
3
"@vocab": "http://schema.org/",
4
"goog": "http://schema.googleapis.com/",
5
"resultScore": "goog:resultScore",
6
"detailedDescription": "goog:detailedDescription",
7
"EntitySearchResult": "goog:EntitySearchResult",
8
"kg": "http://g.co/kg"
9
},
10
"@type": "ItemList",
11
"itemListElement": [
12
{
13
"@type": "EntitySearchResult",
14
"result": {
15
"@id": "f7fb9c597ec04c1a7a6c1b03f5ef365ac7b47416b23e4c0772195175258266b8",
16
"@type": "PRODUCT",
17
"@context": "https://www.schema.org/",
18
"@graph": [
19
{
20
"type": "Product",
21
"aggregateRating": {
22
"id": "_:b1",
23
"type": "AggregateRating",
24
"ratingValue": "4.4",
25
"reviewCount": "89"
26
},
27
"brand": {
28
"id": "_:b2",
29
"type": "Thing",
30
"name": "ACME"
31
},
32
"description": "Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height.",
33
"image": "http://www.example.com/anvil_executive.jpg",
34
"mpn": "925872",
35
"name": "Executive Anvil",
36
"offers": {
37
"id": "_:b3",
38
"type": "Offer",
39
"availability": "http://schema.org/InStock",
40
"itemCondition": "http://schema.org/UsedCondition",
41
"price": "119.99",
42
"priceCurrency": "USD",
43
"priceValidUntil": "2020-11-05",
44
"seller": {
45
"id": "_:b4",
46
"type": "Organization",
47
"name": "Executive Objects"
48
}
49
}
50
},
51
{
52
"id": "_:b1",
53
"type": "AggregateRating",
54
"ratingValue": "4.4",
55
"reviewCount": "89"
56
},
57
{
58
"id": "_:b2",
59
"type": "Thing",
60
"name": "ACME"
61
},
62
{
63
"id": "_:b3",
64
"type": "Offer",
65
"availability": "http://schema.org/InStock",
66
"itemCondition": "http://schema.org/UsedCondition",
67
"price": "119.99",
68
"priceCurrency": "USD",
69
"priceValidUntil": "2020-11-05",
70
"seller": {
71
"id": "_:b4",
72
"type": "Organization",
73
"name": "Executive Objects"
74
}
75
},
76
{
77
"id": "_:b4",
78
"type": "Organization",
79
"name": "Executive Objects"
80
}
81
]
82
},
83
"issuers": [
84
"0xbd084ab97c704fe4a6d620cb7c30c0be0366646f"
85
],
86
"assertions": [
87
"6b02bc68a44c255c0738b94a72a41ae2c0959e7e6a53554f90ec75ed6d7921de"
88
],
89
"nodes": [
90
"QmdD6AuWRoVpAjkxEtBgeUDUBaddNT3SD2cZo8sMV5CMn6"
91
],
92
"resultScore": 0
93
}
94
]
95
}
Copied!
Assertion search returns assertions metadata of assets indexed by provided keyword:
1
var result = dkg.search({ query: 'ExecutiveAnvil', resultType: 'assertions' });
2
console.log(JSON.stringify(result));
Copied!
The result of Search API route is the following:
1
{
2
"@context": {
3
"@vocab": "http://schema.org/",
4
"goog": "http://schema.googleapis.com/",
5
"resultScore": "goog:resultScore",
6
"detailedDescription": "goog:detailedDescription",
7
"EntitySearchResult": "goog:EntitySearchResult",
8
"kg": "http://g.co/kg"
9
},
10
"@type": "ItemList",
11
"itemListElement": [
12
{
13
"@type": "AssertionSearchResult",
14
"result": {
15
"@id": "6b02bc68a44c255c0738b94a72a41ae2c0959e7e6a53554f90ec75ed6d7921de",
16
"metadata": {
17
"issuer": "0xbd084ab97c704fe4a6d620cb7c30c0be0366646f",
18
"type": "Product",
19
"timestamp": "2021-12-27T16:06:57.912Z",
20
"visibility": true,
21
"dataHash": "ed13153fa4090eceedf6c1dd1aa030ec45ab75c2f9510c64a2014f1c6424e7dd"
22
},
23
"signature": "0xbe37c15aa21835b9fe50b5225cfb61cd8ab3f06374705a91f5a5989105d2d2ec151c8bbb5d0f07c8508d37c77a15ac08456342d156ae52ced4520c15cb94eee91c",
24
"rootHash": "45f04483daac38828d634d404e1a12d60d7b4749813edea7fd8b1701a725f37e"
25
},
26
"nodes": [
27
"QmdD6AuWRoVpAjkxEtBgeUDUBaddNT3SD2cZo8sMV5CMn6"
28
],
29
"resultScore": 0
30
}
31
]
32
}
Copied!

Executing SPARQL queries

Querying the DKG is done by using the SPARQL queries. The SPARQL construct query helps to get the response as a RDF graph. In case you are interested to create your own application, it will return portable graph described by the query:
1
options = {
2
query: `PREFIX schema: <http://schema.org/>
3
CONSTRUCT { ?s ?p ?o }
4
WHERE {
5
GRAPH ?g {
6
?s ?p ?o .
7
?s schema:hasVisibility ?v
8
}
9
}`
10
};
11
​
12
var result = await dkg.query(options)
13
console.log(JSON.stringify(result));
Copied!
The returned responses contain an array of n-quads with predicate schema:hasVisibility:
1
{
2
"status": "COMPLETED",
3
"data": {
4
"response": [
5
"<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasDataHash> \"019042b4b5cb5701579a4fd8e339bed0fa983b06920ed8cd4d5864ffcb01c801\" .",
6
"<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasIssuer> \"0xbd084ab97c704fe4a6d620cb7c30c0be0366646f\" .",
7
"<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasSignature> \"0x1303593aa18a94c54d85649915809f6f3849bd28ad3780b1ce458086f8547e10665dd3d8f2900724853fc5b6c34599d68657fa0f5bb3c7542f02673fc6e609b41b\" .",
8
"<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasTimestamp> \"2021-12-14T12:43:10.742Z\" .",
9
"<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasType> \"default\" .",
10
]
11
}
12
}
Copied!

Validate data integrity

Validate triples that you got performing SPARQL queries. We have chosen two triplets from above query result and we will check their integrity:
1
options = {
2
nquads: [
3
'<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasDataHash> \"019042b4b5cb5701579a4fd8e339bed0fa983b06920ed8cd4d5864ffcb01c801\" .',
4
'<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasIssuer> \"0xbd084ab97c704fe4a6d620cb7c30c0be0366646f\" .'
5
],
6
};
7
​
8
var result = await dkg.validate(options);
9
console.log(JSON.stringify(result));
Copied!
The result presents an array that for each element indicates if the root hash matched or not:
1
[
2
{
3
"triple": "<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasDataHash> \"019042b4b5cb5701579a4fd8e339bed0fa983b06920ed8cd4d5864ffcb01c801\" .",
4
"valid": true
5
},
6
{
7
"triple": "<did:dkg:43a5f8c55600a36882f9bac7c69c05a3e0edd1293b56b8024faf3a29d8157435> <http://schema.org/hasIssuer> \"0xbd084ab97c704fe4a6d620cb7c30c0be0366646f\" .",
8
"valid": true
9
}
10
]
Copied!
More details about the library is available here.
Copy link