Introduction
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.
Concept
Overview
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.
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.
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
| 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
Docs
- 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
Rules
Templates
- 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
History
Indexes
Timeseries
Notifications
- 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.