Class Name | DigitalTwin |
Extends | Logger |
Source | digital-twin.ts |
Examples | digital-twin.spec.ts |
TL;DR: usage examples and a data flow can be found here <./digital-twin-usage-examples>
.
A DigitalTwin
is a wrapper, that holds data or references to data. This data can be
- a
Container
_ - This is the most common use case, actual data is stored in the container and theDigitalTwin
merely holds a reference to the container. - an
DigitalTwin
- DigitalTwins can be linked together, so an entry can be anotherDigitalTwin
, which allows to navigate through twins to retrieve data properties from linked twins, seegetEntry <digital-twin_getEntry>
- an identity/account address / a contract address
bytes32
hashes (e.g. file hashes)
new DigitalTwin(options, config);
Create new DigitalTwin
instance. This will not create a smart contract contract but is used to load existing digital twins. To create a new contract, use the static create <digital-twin_create>
function.
options
-DigitalTwinOptions
: runtime-like object with required modulescontractLoader
-ContractLoader
_:ContractLoader
_ instancecryptoProvider
-CryptoProvider
_:CryptoProvider
_ instancedataContract
-DataContract
_:DataContract
_ instancedescription
-Description
_:Description
_ instanceexecutor
-Executor
_:Executor
_ instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
_ (optional): messages with this level will be logged withlog
logLog
-LogLogInterface
_ (optional): container for collecting log messageslogLogLevel
-LogLevel
_ (optional): messages with this level will be pushed tologLog
nameResolver
-NameResolver
_:NameResolver
_ instanceprofile
-Profile
_:Profile
_ instancerightsAndRoles
-RightsAndRoles
_:RightsAndRoles
_ instancesharing
-Sharing
_:Sharing
_ instanceverifications
-Verifications
_:Verifications
_ instanceweb3
-Web3
_:Web3
_ instance
config
-DigitalTwinConfig
: digital twin related configaccountId
-string
: identity or account of user, that interacts with digital twincontainerConfig
-ContainerConfig
: address of aDigitalTwin
instance, can be ENS or contract addressaddress
-string
(optional): address of anDigitalTwin
instance, can be ENS or contract addressdescription
-string
: description has to be passed to.create
to apply it to to contractfactoryAddress
-string
(optional): factory address can be passed to.create
for customer digital twin factory
DigitalTwin
instance
const digitalTwin = new DigitalTwin(
runtime,
{
accountId: '0x0000000000000000000000000000000000000000',
address: 'sample-digital-twin.somewhere.evan',
},
);
DigitalTwin.create(runtime, config);
Create digital twin contract.
Note, that this function is static. It is used on the DigitalTwin
class object and returns a DigitalTwin
class instance.
The options argument has the same structure as the options object that is passed to the constructor as it is used for the new DigitalTwin
instance. The config
argument requires a proper value for the property description
.
options
-ContainerOptions
: runtime-like object with required modulescontractLoader
-ContractLoader
_:ContractLoader
_ instancecryptoProvider
-CryptoProvider
_:CryptoProvider
_ instancedataContract
-DataContract
_:DataContract
_ instancedescription
-Description
_:Description
_ instanceexecutor
-Executor
_:Executor
_ instancenameResolver
-NameResolver
_:NameResolver
_ instancerightsAndRoles
-RightsAndRoles
_:RightsAndRoles
_ instancesharing
-Sharing
_:Sharing
_ instanceverifications
-Verifications
_:Verifications
_ instanceweb3
-Web3
_:Web3
_ instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
_ (optional): messages with this level will be logged withlog
logLog
-LogLogInterface
_ (optional): container for collecting log messageslogLogLevel
-LogLevel
_ (optional): messages with this level will be pushed tologLog
config
-DigitalTwinConfig
: digital twin related configaccountId
-string
: identity or account of user, that interacts with digital twincontainerConfig
-ContainerConfig
: config, that will be used, when containers are createdaddress
-string
(optional): ENS address used for digital twindescription
-string
: description has to be passed to.create
to apply it to to contractfactoryAddress
-string
(optional): factory address can be passed to.create
for customer digital twin factoryplugins
-{ [pluginName: string]: ContainerPlugin }
(optional): set of container plugins that should be applied to the twin directly with the creationg (will be passed to the createContainers function)
Promise
returns DigitalTwin
: new instance bound to new DigitalTwin
const digitalTwin = await DigitalTwin.create(options, config);
console.log(await digitalTwin.getContractAddress());
// Output:
// 0x0000000000000000000000000000000000001234
digitalTwin.createContainers(containers);
Create new Container instances and add them as entry to twin.
When a container entry fetched with getEntry <digital-twin_getEntry>
or getEntry <digital-twin_getEntries>
, the value will become a Container
instance and can be used as such.
containers
-{ [id: string]: Partial<ContainerConfig> }
: object with containers to create, name is used as entry name in twin
Promise
returns { [id: string]: Container }
: map with Container
instances
const containers = await twin.createContainers({
entry1: { template: 'metadata' },
entry2: { template: 'metadata' },
});
digitalTwin.setEntry(name, value, entryType);
Set entry in index contract; entries are unique, setting the same name a second time will overwrite the first value.
name
-string
: entry namevalue
-string
: value to setentryType
-DigitalTwinType
: type of given value
Promise
returns void
: resolved when done
await digitalTwin.setEntry('myId', accountId, DigitalTwinEntryType.AccountId);
console.log((await digitalTwin.getEntry('myId')).value);
// Output:
// 0x0000000000000000000000000000000000000001
digitalTwin.setEntries(arguments);
Set multiple entries at index contract.
entries
-{[id: string]: DigitalTwinIndexEntry}
: entries to set
Promise
returns void
: resolved when done
const sampleContractId = '0x00000000000000000000000000000000c0274ac7';
await digitalTwin.setEntries({
'account': { value: accountId, entryType: DigitalTwinEntryType.AccountId },
'contract': { value: sampleContractId, entryType: DigitalTwinEntryType.GenericContract },
});
const result = (await digitalTwin.getEntries()).map(entry => value);
console.log(result.account.value);
// Output:
// 0x0000000000000000000000000000000000000001
console.log(result.contract.value);
// Output:
// 0x00000000000000000000000000000000c0274ac7
digitalTwin.getEntry(name);
Get single entry from index contract.
When this twin has other twins as its entries, properties from those can be selected by building a path of properties.
For example a twin called car
may have a link to another twin under the name tire
. The twin tire
has an entry called metadata
. It is possible to retrieve this entry from the twin car
with:
const tireMetadata = await car.getEntry('tire/metadata');
name
-string
: entry name or path to data in linked twin
Promise
returns DigitalTwinIndexEntry
: entry object
await digitalTwin.setEntry('myId', accountId, DigitalTwinEntryType.AccountId);
console.log((await digitalTwin.getEntry('myId')).value);
// Output:
// 0x0000000000000000000000000000000000000001
digitalTwin.getEntries();
Get all entries from index contract.
Promise
returns {[id: string]: DigitalTwinIndexEntry}
: key-value map with all entries
const sampleContractId = '0x00000000000000000000000000000000c0274ac7';
await digitalTwin.setEntries({
'account': { value: accountId, entryType: DigitalTwinEntryType.AccountId },
'contract': { value: sampleContractId, entryType: DigitalTwinEntryType.GenericContract },
});
const result = (await digitalTwin.getEntries()).map(entry => value);
console.log(result.account.value);
// Output:
// 0x0000000000000000000000000000000000000001
console.log(result.contract.value);
// Output:
// 0x00000000000000000000000000000000c0274ac7
digitalTwin.addVerifications(verifications);
Add verifications to this twin; this will also add verifications to contract description.
If the calling account is the owner of the identity of the digital twin
- the description will is automatically updated with tags for verifications
- verifications issued with this function will be accepted automatically
See interface DigitalTwinVerificationEntry
for input data format.
verifications
-DigitalTwinVerificationEntry[]
: list of verifications to add
Promise
returns void
: resolved when done
await digitalTwin.addVerifications([{ topic: 'exampleVerification' }]);
digitalTwin.getVerifications();
Gets verifications from description and fetches list of verifications for each of them.
See Verifications
_ documentation for details on output data format.
Promise
returns any
: list of verification lists from Verifications
_, getVerifications
await digitalTwin.addVerifications([{ topic: 'exampleVerification' }]);
const verifications = await digitalTwin.getVerifications());
digitalTwin.getDescription();
Returns description from digital twin.
Promise
returns any
: public part of the description
const description = await container.getDescription();
console.dir(description);
// Output:
// { name: 'test twin',
// description: 'twin from test run',
// author: 'evan GmbH',
// version: '0.1.0',
// dbcpVersion: 2,
// tags: [ 'evan-digital-twin' ],
// identity:
// '0x1a496043385fec8d52f61e2b700413f8e12eb6e7e11649f80c8f4716c1063d06' }
digitalTwin.setDescription(description);
Write given description to digital twins DBCP.
description
-any
: description (public part)
Promise
returns void
: resolved when done
// get current description
const description = await digitalTwin.getDescription();
console.dir(description);
// Output:
// { name: 'test twin',
// description: 'twin from test run',
// author: 'evan GmbH',
// version: '0.1.0',
// dbcpVersion: 2,
// tags: [ 'evan-digital-twin' ],
// identity:
// '0x1a496043385fec8d52f61e2b700413f8e12eb6e7e11649f80c8f4716c1063d06' }
// update description
description.version = '0.1.1';
await digitalTwin.setDescription(description);
// fetch again
console.dir(await digitalTwin.getDescription());
// Output:
// { name: 'test twin',
// description: 'twin from test run',
// author: 'evan GmbH',
// version: '0.1.1',
// dbcpVersion: 2,
// tags: [ 'evan-digital-twin' ],
// identity:
// '0x1a496043385fec8d52f61e2b700413f8e12eb6e7e11649f80c8f4716c1063d06' }
digitalTwin.addAsFavorite();
Add the digital twin with given address to profile.
Promise
returns void
: resolved when done
const digitalTwin = new DigitalTwin(options.config);
if (await digitalTwin.isFavorite()) {
console.log('I know this digital twin!');
} else {
await digitalTwin.addToFavorites();
console.log('bookmarked digital twin');
}
--------------------------------------------------------------------------------.. _digital-twin_getFavorites:
DigitalTwin.getFavorites();
Gets bookmarked twins from profile.
Note, that this function is called on the Class DigitalTwin and not on an instance of it.
options
-ContainerOptions
: runtime-like object with required modulescontractLoader
-ContractLoader
_:ContractLoader
_ instancecryptoProvider
-CryptoProvider
_:CryptoProvider
_ instancedataContract
-DataContract
_:DataContract
_ instancedescription
-Description
_:Description
_ instanceexecutor
-Executor
_:Executor
_ instancenameResolver
-NameResolver
_:NameResolver
_ instancerightsAndRoles
-RightsAndRoles
_:RightsAndRoles
_ instancesharing
-Sharing
_:Sharing
_ instanceverifications
-Verifications
_:Verifications
_ instanceweb3
-Web3
_:Web3
_ instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
_ (optional): messages with this level will be logged withlog
logLog
-LogLogInterface
_ (optional): container for collecting log messageslogLogLevel
-LogLevel
_ (optional): messages with this level will be pushed tologLog
Promise
returns void
: resolved when done
const favorites = await DigitalTwin.getFavorites(options);
console.dir(favorites);
// Output:
// [
// 'example.somewhere.evan',
// 'another.example.somewhere.else.evan',
// '0x0000000000000000000000000000000000001234'
// ]
digitalTwin.isFavorite();
Check if this digital twin is bookmarked in profile.
Promise
returns boolean
: true if bookmarked
const digitalTwin = new DigitalTwin(options.config);
if (await digitalTwin.isFavorite()) {
console.log('I know this digital twin!');
} else {
await digitalTwin.addToFavorites();
console.log('bookmarked digital twin');
}
digitalTwin.removeFromFavorites();
Removes the current twin from the favorites in profile.
Promise
returns void
: resolved when done
const digitalTwin = new DigitalTwin(options.config);
if (await digitalTwin.isFavorite()) {
await digitalTwin.removeFromFavorites();
console.log('removed digital twin from favorites');
}
DigitalTwin.getValidity(options, ensAddress);
Check if a valid contract is located under the specified address, which allows to check for twins before actually loading them.
Return value properties have the following meaning:
valid
:true
if contract could not be found or if it doesn't have the tag "evan-digital-twin"exists
:true
if a contract address could be found at given ENS addresserror
: an error object, if one of the other properties isfalse
Note, that this function is called on the Class DigitalTwin and not on an instance of it.
options
-DigitalTwinOptions
: twin runtime optionscontractLoader
-ContractLoader
_:ContractLoader
_ instancecryptoProvider
-CryptoProvider
_:CryptoProvider
_ instancedataContract
-DataContract
_:DataContract
_ instancedescription
-Description
_:Description
_ instanceexecutor
-Executor
_:Executor
_ instancenameResolver
-NameResolver
_:NameResolver
_ instancerightsAndRoles
-RightsAndRoles
_:RightsAndRoles
_ instancesharing
-Sharing
_:Sharing
_ instanceverifications
-Verifications
_:Verifications
_ instanceweb3
-Web3
_:Web3
_ instancelog
-Function
(optional): function to use for logging:(message, level) => {...}
logLevel
-LogLevel
_ (optional): messages with this level will be logged withlog
logLog
-LogLogInterface
_ (optional): container for collecting log messageslogLogLevel
-LogLevel
_ (optional): messages with this level will be pushed tologLog
ensAddress
-string
: ens address that should be checked
Promise
returns { valid: boolean, exists: boolean, error: Error }
: resolved when done
const { valid } = await DigitalTwin.getValidity(runtime, address);
if (!valid) {
throw new Error(`no valid digital twin found at "${address}"`);
}
digitalTwin.ensureContract();
Check if digital twin contract already has been loaded, load from address / ENS if required. Throws if contract could not be loaded.
This function is more commonly used for internal checks in the DigitalTwin
module. For checking, if a given address can be used, it is recommended to use getValidity <digital-twin_getValidity>
.
Promise
returns void
: resolved when done
let digitalTwin;
try {
digitalTwin = new DigitalTwin(options, config);
await digitalTwin.ensureContract();
// use digital twin
} catch (ex) {
console.error(`could use digital twin; ${ex.message || ex}`);
}
digitalTwin.exportAsTemplate();
Exports the twin template definition for this twin. Includes the twins dbcp descriptions and all plugins, created out of the twin containers definitions. Can also export container values within the plugin definitions.
You can find a sample twin template here: TwinTemplate
_
Promise
returnsDigitalTwinTemplate
: digital twin template definitiondescriptions
-any
: digital twin descriptionplugins
-{ [pluginName: string]: ContainerPlugin }
: plugins for all containers
const configWithTemplate = {
...defaultConfig,
...twinTemplate,
};
const twin = await DigitalTwin.create(runtime, configWithTemplate);
const template = await twin.exportAsTemplate();
console.log(template);
// {
// "description": { ... },
// "plugins": {
// "plugin1": {
// "description": {
// ...
// },
// "template": {
// ...
// }
// },
// "pluginX": {
// ...
// }
// }
// }
digitalTwin.getContractAddress();
Get contract address of underlying DigitalTwin.
Promise
returns string
: contract address
const digitalTwin = new DigitalTwin(options, config);
console.log(await digitalTwin.getContractAddress());
// Output:
// 0x000000000000000000000000000000001d327171
Default description used when no specific description is given to .create <digital-twin_create>
.
console.dir(DigitalTwin.defaultDescription);
// Output:
// {
// name: 'Digital Identity',
// description: 'Digital Identity Contract',
// author: '',
// version: '0.1.0',
// dbcpVersion: 2
// }
possible entry types for entries in index
AccountId
Container
FileHash
GenericContract
Hash
DigitalTwin
config for digital twin
accountId
-string
: account id of user, that interacts with digital twincontainerConfig
-ContainerConfig
: address of aDigitalTwin
instance, can be ENS or contract addressaddress
-string
(optional): address of anDigitalTwin
instance, can be ENS or contract addressdescription
-string
(optional): description has to be passed to.create
to apply it to to contractfactoryAddress
-string
(optional): factory address can be passed to.create
for customer digital twin factory
container for digital twin entry values
entryType
-DigitalTwinEntryType
(optional): type of entry in indexraw
-any
(optional): raw value (bytes32
hash)value
-any
(optional): decrypted/loaded value
data for verifications for digital twins
topic
-string
: name of the verification (full path)descriptionDomain
-string
(optional): domain of the verification, this is a subdomain under 'verifications.evan', so passing 'example' will link verificationsdisableSubVerifications
-boolean
(optional): if true, verifications created under this path are invalid, defaults tofalse
expirationDate
-number
(optional): expiration date, for the verification, defaults to 0 (does not expire)verificationValue
-any
(optional): json object which will be stored in the verification