TrustedTwin Homepage


Figure 1. Shared object on the Trusted Twin platform.

Shared object concept


This article describes the shared object model and scheme used on the Trusted Twin platform. 

The purpose of this article is to provide system architects and developers with conceptual knowledge required to design solutions on the Trusted Twin platform. For developer resources, please consult the Trusted Twin docs website.

10 min read.


Shared processes and shared objects

Trusted Twin is a developer platform for operational data sharing. It allows customers to store and handle shared objects used in shared processes. 

Shared processes are processes that go beyond a single organization’s scope. They involve multiple, independent partners from various organizations. Shared processes operate on objects that are common for all the cooperating partners. Therefore, these objects are called shared objects.

Shared objects aggregate in real-time operational data essential to the process. These data are provided and used by all partners. As partners can contribute their data independently, the structure of a shared object must be dynamic. And as a shared object is built from data owned by many partners, it has to allow for continuous visibility and access management.

Shared objects on the Trusted Twin platform are inspired by the digital twin concept. Therefore, the main object on the platform, which ties together data provided by partners and acts as a conceptual “bracket” for the data, is called a Twin.


A Twin is the main object of the Trusted Twin platform because it ties together all data provided by partners participating in a shared business process and acts as a conceptual “bracket” for the data.

A Twin can be created by any account on the Trusted Twin platform, and this account becomes the owner of the Twin.

Developer resources
Create a Twin

As the Twin is a “bracket”, the Twin object itself does not store any account’s data. It consists mainly of a public UUID identifier and a public description. Any account that knows the UUID identifier of a Twin can access the Twin and its description.

Figure 2. Twin with a public description and a UUID identifier.

Developer resources
Get a Twin

The Twin owner is the only account allowed to change the Twin description.

Developer resources
Update a Twin

The Twin owner is also the only account allowed to terminate the Twin. Twin termination results in Twin’s status change to “terminated”. However, the Twin is not deleted from the Trusted Twin platform as long as there is data associated with it (i.e., Ledgers or Docs). Partners can still contribute their data to a Twin with the status “terminated”.

Shared object structure

Any account knowing Twin’s UUID identifier can contribute to a Twin and read data from it. 

There are three types of objects related directly to a Twin that accounts can use to store their data. These objects are Identities, Ledgers, and Docs. 

All these objects are subject to visibility and access management which we will discuss in another chapter of this series. Trusted Twin access management and visibility concept.


Identities are used to convert any user-defined identifier into the Twin UUID. Each account can add multiple private or public Identities to a single Twin.

Figure 3. Twin with two Identities.

Developer resources
Create an Identity


Ledgers are used to store information about the state of a Twin. Each account can have exactly one Ledger associated with a single Twin. 

Figure 4. There can be one Ledger per Twin per account. Account 1 owns two Twins (Twin 1 and Twin 2). Twin 1 has one Ledger (‘Ledger A’) belonging to Account 1. Twin 2 has two Ledgers – ‘Ledger B’ belonging to Account 1 and ‘Ledger C’ belonging to Account 2.

A Ledger consists of multiple Entries following a key-value scheme where the value can store any JSON serializable object. Data visibility and access are managed on the Ledger Entry level. 

The value can be provided directly by the Account, through a reference to a value of a different, especially foreign Ledger (value is updated automatically), or through a reference to a different Ledger of the same Account (value is not updated automatically).

Developer resources
Ledger and Ledger Entry structure


Docs are static files of any type (e.g., PDF, CSV, XLS) and size. Each account can attach multiple Docs to a single Twin.

Figure 5. Docs of different formats attached to a Twin.

Developer resources
Attach a Doc

Tips & tricks

  • Identities must be unique only within the Twin context. Therefore, the same Identity can be added by the same Account to many Twins. You can resolve an Identity to identify groups of Twins (the group size is limited to ca. 100 Twins).

Developer resources
Resolve an Identity

  • Ledger entries (reference type) can be used to build graphs of connected Twins which are automatically updated. Trusted Twin ledger concept
  • Ledger entries (include type) can be used to model global parameters or variables. Trusted Twin ledger concept
  • The Indexes service allows for building structured views of the state of multiple Twins in the form of relational database tables. The service configuration allows for setting a Rule for Twin selection as well as the properties (i.e., Ledger Entry values) reflected in the index.

Developer resources
Indexes service

  • The Timeseries service allows for building structured views of the history of multiple Twins in the form of relational database tables. The service configuration allows for selecting Twins, dimensions, and measurements (i.e., Ledger Entry values) reflected in the Timeseries database table. Trusted Twin indexes and time series concept

Developer resources
Timeseries service

Up next/ Next step

Related articles

For more information about how to use the Trusted Twin platform in your application’s architecture or technology stack, please contact