1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
# Log Lifecycle
Log lifecycle is a useful concept for outlining expected modes the log can be in, and state transitions between these states.
The lifecycle states outlined below exist either as explicit API constructs or as internal states, but there is no explicit
state stored with the log data.
The requirements for each state are documented, and the log operator takes responsibility to ensure that they only migrate between these states in the supported directions.
[](https://mermaid.live/edit#pako:eNptkj9vwyAQxb8KYqzMkpFKlSp5TIa2W0sHCuf4VHxYcG4aRfnuJXYcJ1WYuPd7B48_B-miB6mlUsoQIwfQYo0NuL0LYGiUM1uGGu022U79rAyJMjwmcIyRxPr1cZJcsDnX0AgkhkQ2iCYSq8z7siqyDej-O22Pk2kHuG1Zf8Xgq8wpfoPaoedWr_rf0jS1fTx8CqWexHPfA3lIt-oGS8BTotl-EUb8MiBkB8QTnNe4xy7lnd1uWQ0BGPyEzsUISqg5xnjYq775dq7p3HqPXZKWy7rWl-ONwJCsZAeps-jLgx5OViO5hQ6M1GXqobFDYCMNHYvVDhzf9uSk5jRAJYfeL88sdWNDLip45Jg20ycZ_0ole0vvMS6eFIdte66Of4uAxnk)
## Terminology
The definitions below will use terms that we'll define here:
- pending: an entry which has been submitted to the log and durably assigned a sequence number, but which has not yet been integrated.
- integrated: a sequenced entry that has been included in the Merkle tree, and a checkpoint committing to it has been created.
## Modes
### `Appender`
The purpose of this mode is to allow entries to be assigned indices by, and integrated into, the log.
This is the "normal" state of most active logs, and is characterized by the writer personality using only the
[`tessera.NewAppender`](https://pkg.go.dev/github.com/transparency-dev/tessera@main#NewAppender)
lifecycle API.
In this mode, storage drivers:
- durably assign and return sequence numbers for entries passed via the `Add` method on the `Appender` struct.
- integrate entries with sequence numbers into the tree, possibly asynchronously.
- periodically publish a new signed `checkpoint` file which commits to the contents of the tree.
This state can start from an empty tree, or from the `Quiescent` state, in which case there can be any number of
entries already in the tree, but they must all be integrated.
The only valid transition outwards is to [`Quiescent`](#Quiescent), and the operator should ensure that
new entries are not being accepted and all pending entries have been integrated before transitioning.
### `Migration`
This mode is used to "import" [tlog-tiles] (or [static-ct]) compliant logs into a Tessera instance.
The most common use case for this mode is migrating a log you operate between different supported Tessera
infrastructure.
This state must start from an empty tree.
It is characterized by the personality that uses only the
[`tessera.NewMigrationTarget`](https://pkg.go.dev/github.com/transparency-dev/tessera@main#MigrationTarget)
lifecycle API.
In this mode, the lifecycle struct will copy entry bundle resources from the source log into the target log, and
locally re-create the merkle tree which commits to them. The resulting root hash should match the root hash of the
source log at the same tree size.
> [!Note]
> This lifecycle mode _does not_, by design, create or publish `checkpoint` files.
>
> For logs being migrated between infrastructure, it is of paramount importance that only one of two logs is canonical
> at any given time in order to avoid inadvertently creating a fork.
> Consequently, Tessera will only create a new `checkpoint` file once the operator has completed the migration of the
> source data into the target log, verified its correctness, and manually switched over to `Appender` mode on the target
> log.
The only valid transition outwards is to [`Quiescent`](#Quiescent), and the operator should ensure that the
migration operation has completed successfully before transitioning.
### `Quiescent`
The purpose of this conceptual mode is to provide a safe intermediate state where the tree and all associated metadata is
up-to-date and self-consistent.
This state may be considered as terminal, e.g. if the log is being frozen or retired.
This state requires [`Migration`](#Migration) or [`Appender`](#Appender) first.
No calls which can modify state should be made while in this mode.
The only valid transitions are to [`Appending`](#Appending) (e.g. when a log migration is complete and the log should
become operational in its new location), or [`Deleted`](#Deleted).
### `Deleted`
Each storage implementation will define instructions for deleting the contents of the log when no longer required.
It can only be reached from the [`Quiescent`](#Quiescent) state.
The concept of a soft-delete is not supported by Tessera, though the deployer may be able to realize this via their own
infrastructure (e.g. by deleting URL mappings to the log handlers).
## Lifecycle in Trillian v1
This lifecycle proposal was inspired by Trillian v1, but simplified as much as possible.
For comparative purposes, the states possible in Trillian are documented below.
Using Trillian log [TreeState](https://github.com/google/trillian/blob/master/trillian.proto#L66) and
[TreeType](https://github.com/google/trillian/blob/master/trillian.proto#L92) as inspiration, the largest conceivable
lifecycle is:
- No log / unknown
- Empty log
- Pre-ordered
- Active
- Draining (this is the only state that allows a back-transition. This can move back to Active)
- Frozen
- No log (deleted)
---
[tlog-tiles]: https://c2sp.org/tlog-tiles
[static-ct]: https://c2sp.org/static-ct
|
