Ledger structure


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.


Figure 1. Ledger and related services.



A Ledger stores information about the state of the shared object.
Read more: Shared object

Ledger structure

Ledgers are main objects on the Trusted Twin platform used to store information about the state of the shared object. 

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 UUID identifier of the accounts which owns it.

A Ledger is a JSON document that consists of multiple Entries following a key-value scheme. 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 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 data 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 3. Entry structure and related services (History, Timeseries, Notifications).

Entry types

There are three types of Entries:

  • value type Entry,
  • Reference type Entry,
  • Include type Entry.

The Entry type depends on the origin of the value stored in the Entry. Entries of different types can be used to create relationships between objects (i.e., object graphs).
Read more: Object linking

Figure 4. Ledger Entry types.

Entry type Description Value change event origin Most commonly used for
Value Stores a value provided directly by the account. The value change event originates from the account’s requests to the API.  This Entry type is most commonly used to store account’s data. 
Reference Stores 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. 
Include Stores 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 updated automatically upon the source value change.  This Entry type was introduced to support global variables used in multiple Ledgers.

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.
    Read more: File storage (Docs)

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). 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.

For more information about how to use the Trusted Twin platform in your application’s architecture or technology stack, please contact hello@trustedtwin.com or schedule a video consultation with us through Calendly.