[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [local‑first/Timestamp](https://evolu.dev/docs/api-reference/common/local-first/Timestamp) › Timestamp

Defined in: [packages/common/src/local-first/Timestamp.ts:159](https://github.com/evoluhq/evolu/blob/e7144e2bbe9069362b62dec1b64a8aa922b8f1b0/packages/common/src/local-first/Timestamp.ts#L159)

Hybrid Logical Clock timestamp.

Timestamps serve as globally unique, causally ordered identifiers for CRDT
messages in Evolu's sync protocol.

## Why Hybrid Logical Clocks

Evolu uses Hybrid Logical Clocks (HLC), which combine physical time (millis)
with a logical counter. This hybrid approach preserves causality like logical
clocks while staying close to physical time for better human
interpretability.

The counter component ensures causality is maintained even when physical
clocks are imperfect. When clocks drift or operations occur concurrently, the
counter increments to establish a total order. This means Evolu achieves
well-defined, eventually-consistent behavior regardless of physical clock
accuracy.

Vector clocks can accurately track causality and detect concurrent
operations, but they require unbounded space in peer-to-peer systems and
crucially, still don't solve our fundamental problem: when they detect
operations as concurrent, we still need a deterministic way to choose a
winner. Additionally, any deterministic conflict resolution can be gamed by
malicious actors.

HLC timestamps work well in practice because modern device clocks accurately
reflect the order of sequential edits in the common case. Evolu's `maxDrift`
configuration protects against buggy clocks and prevents problematic
future-dated entries from propagating through the network.

## References

- https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
- https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
- https://jaredforsyth.com/posts/hybrid-logical-clocks/
- https://willowprotocol.org/more/timestamps_really/index.html

## Privacy Considerations

Timestamps are metadata visible to relays and collaborators. While it can be
considered a privacy leak, let us explain why it's necessary, and how to
avoid it if maximum privacy is required.

With real-time communication, participants always see activity (receiving
bytes). We cannot trust anyone not to store that information, so explicitly
exposing timestamps doesn't add additional risk.

If we really want not to leak user activity, we can implement a local write
queue:

1. Write changes immediately to a local-only table
2. Periodically and randomly flush messages to sync tables

**Trade-off:** It breaks real-time collaboration.

Another technique is generating fake random activity (dummy messages) to mask
real usage patterns. This preserves real-time collaboration but increases
storage and bandwidth usage.

## Extends

- [`InferType`](https://evolu.dev/docs/api-reference/common/Type/type-aliases/InferType)\<_typeof_ [`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/variables/Timestamp)\>

## Properties

<a id="counter"></a>

### counter

```ts
counter: number &
  Brand<"Int"> &
  Brand<"NonNegative"> &
  Brand<"LessThanOrEqualTo65535"> &
  Brand<"Counter">;
```

#### Inherited from

[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp).[`counter`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp#counter)

---

<a id="millis"></a>

### millis

```ts
millis: number &
  Brand<"Int"> &
  Brand<"NonNegative"> &
  Brand<"LessThan281474976710655"> &
  Brand<"Millis">;
```

#### Inherited from

[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp).[`millis`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp#millis)

---

<a id="nodeid"></a>

### nodeId

```ts
nodeId: string & Brand<"NodeId">;
```

#### Inherited from

[`Timestamp`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp).[`nodeId`](https://evolu.dev/docs/api-reference/common/local-first/Timestamp/interfaces/Timestamp#nodeid)