Event ID
Permalink to “Event ID”128 Bits
Permalink to “128 Bits”An Event ID is 128 bits in length.
- String encoded as a hex string with Big Endian bytes.
- Applications might use UUID native types like MySQL’s UUID field type, or C#’s Guid class. However, an event ID will not validate to a known UUID version.
Sortable
Permalink to “Sortable”Both byte array and string encoding of Event IDs are sortable. See Ordering for details.
Monotonic
Permalink to “Monotonic”If two events occur at the exact same microsecond, Evently increments the timestamp by one microsecond. Thus, no two events will ever occur at the exact same time. If the current time on the system is behind the last event’s time component, Evently will disregard current time and utilize the time value of the last event time, incrementing the microsecond to move past the previous event time. This will keep the event ledger in order if the clock is reset into the past.
NOTE: this is how Google’s TrueTime works; it does not duplicate timestamps but will increment ahead in case timestamps collide.
Traceable
Permalink to “Traceable”An Event ID can be traced to the event ledger it belongs to, and its place therein. It is a reference to a point in the ledger that marks the event. It also contains a verification checksum to validate the event contents matches the Event ID.
Timestamped
Permalink to “Timestamped”The Event ID can provide the timestamp for when the event was added to the ledger.
Checksummed
Permalink to “Checksummed”The Event ID contains a CRC32C checksum to verify the content of the event. CRC32C is a 32-bit hash and was chosen for these reasons:
- Low probability of collisions, although every hash has collisions.
- Widespread adoption in software languages and hardware. Intel and AMD have CRC32C calculation instructions.
Once computed, a checksum will never change.
Event ID Composition
Permalink to “Event ID Composition”Components
Permalink to “Components”- Timestamp: timestamp is 64 bits
- Checksum: 32 bits
- Ledger ID: 32 bits
Timestamp
Permalink to “Timestamp”The timestamp component is a 64-bit microsecond (µsecond) value in the Unix Epoch. Note that 1 millisecond = 1,000 microseconds. When parsing the timestamp component in the event body to convert to a datetime, verify that your date parsing library can parse more than to the millisecond. Some will not be able to parse microseconds.
Ledger ID
Permalink to “Ledger ID”A Ledger ID is a 32-bit integer. It is computed as a partial checksum of the ledger’s genesis event, ANDed with the Ledger ID version. The genesis event is the ledger’s very first event and does not have a Ledger ID itself for the checksum. As a result, the Ledger ID is computed by following steps 1-4 of the Event checksum algorithm.
Here is an example genesis event:
{
"event": "Ledger Created",
"entities": {
"ledger": "testing⑆preview"
},
"timestamp":"2021-10-03T16:32:12.816530Z",
"meta": {
"actor": "matt"
},
"data": {
"name": "My Ledger",
"description": "This ledger is for my example events."
}
}