TrustedTwin Homepage


Figure 1. Ledger and related services (History, Timeseries, Indexes, and Notifications) on the Trusted Twin platform.

Ledger structure concept


This article describes the Ledger Entry structure 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.

5 min read.


A Ledger forms part of a shared object. The shared object concept was described in the Trusted Twin shared object concept article. In this document we will focus on the Ledger and its Entries.

Ledger structure

A Ledger is the main object on the Trusted Twin platform used to store information about a shared object state. 

A Ledger is always attached to a Twin which acts as a “bracket” for data provided by different accounts. Each account can have exactly one Ledger associated with a single Twin. A Ledger can be accessed by providing the UUID identifier of the Twin it is attached to and the UUID4 identifier of the accounts which owns it.

A Ledger is a JSON document that consists of multiple Entries following a key-value scheme where the value can store any JSON serializable object. Access to and visibility of account’s data stored in the Ledger are managed at the Entry level. 

Figure 2. Ledger with Entries.

Entry types

There are three types of Entries. The Entry type depends on the origin of the value stored in the Entry.

Entry typeDescriptionValue change event originMost commonly used for
ValueStores a value provided directly by the account.The value change event originates from the account’s requests to the API. This Entry type is the most commonly used to store account’s data. 
ReferenceStores a reference to a value from a different Ledger belonging to the user’s own account or another account’s Ledger associated with the same or a different Twin.The value change event originates from the change of the referenced value. The value of such an Entry is updated automatically every time the referenced value changes. Reference type Entries are used to build relationships between shared objects (i.e., graphs of Twins) which are updated automatically. 
IncludeStores a reference to a value from a different Ledger of the same account. The value of such an Entry is loaded each time a Ledger is being accessed but is not is not updated automatically upon the source value change. This Entry type was introduced to support global variables used in multiple Ledgers.
Figure 3. Ledger Entry types.

Entry structure

An Entry is a JSON document that stores a single value as well as properties which define the Entry behavior and visibility. 

Developer resources
Ledger and entry overview

A value can store a basic type (e.g., number, string) as well as any JSON serializable object (e.g., list, dictionary).

Properties are used for:

  • managing Entry visibility and access,
  • configuring Entry History service,

Developer resources
History service

  • configuring the Timeseries service,
  • configuring the Notifications (subscribe / notify) service.
Figure 4. Entry structure and related services (History, Timeseries, Notifications).

Tips & tricks

  • A Ledger is designed to store the state of a shared object. Therefore, it should be kept as small as possible. If you need to store large amounts of static data use Docs and links to them rather than storing the data directly in the Ledger.

Developer resources

  • Entries can store as their values any JSON serializable objects. The rules and templates used on the Trusted Twin platform allow for parsing these objects.

Developer resources

  • Reference type Entries are updated automatically each time a referenced Entry changes, so use them together with other services (e.g., History, Indexes, Timeseries, Notifications (subscribe / notify). Otherwise, it is more efficient to access a foreign Entry directly when required.

Developer resources

  • Include type Entries are used most often when access rules or templates used in the Ledger to manage visibility or to configure advanced services need the same global variables for multiple Twins. 
  • Indexes are not defined as a property of a Ledger. However, every value change of an Entry can lead to a corresponding change in the associated Indexes table.

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