Working with the ledger
Bi-temporality
This page covers the bi-temporality feature of the ledger as well as the impact of that feature on the ledger’s data and the queries that can be run against it.
Definition
The ledger supports bi-temporality, which means that each transaction is associated with two timestamps:- Request time: The time at which the transaction was submitted to the ledger. It is usually the machine clock time.
- Transaction time: The time at which the transaction is considered to have occurred.
TX1is submitted on monday, but the transaction time is set to tuesday. The transaction is considered to have occurred on tuesday. We say that the transaction is postdated.TX2is submitted on tuesday, and the transaction time is set to monday. The transaction is considered to have occurred on monday. We say that the transaction is backdated.TX3is submitted on tuesday, and the transaction time is set to tuesday. The transaction is considered to have occurred on tuesday. This is the default behavior.
- Time travel: The ability to query the ledger as it was at a specific point in time.
- Correction of errors: The ability to correct errors in the ledger by backdating or postdating transactions.
- Auditing: The ability to audit the ledger at a specific point in time.
- Data import: The ability to import data from external systems that use different timestamps.
Present time relativity
Because transactions can either be backdated or postdated, the concept of “present time” may not match the current machine clock time. From the point of view of the ledger, the present time is the transaction timestamp the most in the future. In the example above, let’s consider that we only insertedTX1. In that case, the machine clock is on monday, but the present time is tuesday because the transaction time of TX1 is tuesday and it is the most recent transaction.
Implications of bi-temporality
Bi-temporality allows users to insert transaction at any point in time in the past or future. When a user performs a query on the ledger, the ledger state is determined based on the requested point in time. The ledger state is a snapshot of the ledger at the requested point in time, and it includes all transactions that have a transaction time equal to or less than the requested point in time. This capability has some implications discussed below.From now on, we will only consider the transaction time when discussing the ledger state at a specific point in time.
Account and Transaction Metadata
Account and transaction metadata are not fixed in time. When a user queries the ledger at a specific point in time, the metadata associated with accounts and transactions is also determined based on the requested point in time. This means that the metadata associated with an account or transaction can change over time.Example: Fraud management
Let’s consider the following example. Suppose that a fraud engine is integrated with the ledger to flag suspicious account. It does so by addingrisk=high to the account metadata. The fraud team regularly exports the suspicious accounts to an external system for further investigation. The fraud team queries the ledger at specific points in time to get the list of suspicious accounts.
Let’s consider the account customer:123456. At a time t1 the fraud engine marks the account as suspicious by adding risk=high to the account metadata. The fraud team exports the list of suspicious accounts at time t2 and t3. The account will be included in the list of suspicious accounts in both exports.
risk=high metadata from the account at time t4 located between the two exports t2 and t3. It does so by removing the risk metadata using a backdated transaction. In this case, the account will not be included in the list of suspicious accounts in the export at time t3.
Backdated transaction validation
Problem Statement
When a user inserts a transaction with a transaction time in the past, there is a risk that the transaction is invalid because it might yield an invalid state of the ledger. Consider the following example account whose balance evolution is as follows:| Time | Transaction amount | New Balance |
|---|---|---|
| 1 | 100 | 100 |
| 2 | -50 | 50 |
| 3 | -10 | 40 |
| 4 | 50 | 90 |
| 5 | -10 | 80 |
-100. This transaction would yield the following balance evolution:
| Time | Transaction amount | New Balance |
|---|---|---|
| 1 | 100 | 100 |
| 2 | -100 | 0 |
| 3 | -50 | -50 |
| 4 | -10 | -60 |
| 5 | 50 | -10 |
| 6 | -10 | -20 |
-20, which is invalid because the account has a negative balance. This is an example of an invalid backdated transaction.
Now, consider that a user wants to insert a backdated transaction with a transaction time of 2 and an amount of -50, rather than -100. This transaction would yield the following balance evolution:
| Time | Transaction amount | New Balance |
|---|---|---|
| 1 | 100 | 100 |
| 2 | -50 | 50 |
| 3 | -50 | 0 |
| 4 | -10 | -10 |
| 5 | 50 | 40 |
| 6 | -10 | 30 |
30, which is valid because the account has a positive balance. This is an example of a valid backdated transaction.
Note that the intermediate balances might be negative, as it is the case at time 4 in the second example. The ledger does not validate the intermediate states of the ledger, only the final state.