The TrueTime API: Bounded Uncertainty

1
class TTinterval:
2
    def __init__(self, earliest: int, latest: int):
3
        """
4
        Time interval in microseconds since epoch.
5

6
        The true current time is guaranteed to be somewhere
7
        in [earliest, latest].
8
        """
9
        self.earliest = earliest  # Lower bound
10
        self.latest = latest      # Upper bound
11

12
    @property
13
    def uncertainty(self) -> int:
14
        """The epsilon (ε) uncertainty bound in microseconds."""
15
        return self.latest - self.earliest
16

17
# Example usage
18
interval = TT.now()
19
print(f"Current time is between {interval.earliest} and {interval.latest}")
20
print(f"Uncertainty: ±{interval.uncertainty / 2} μs")
21

22
# Output might be:
23
# Current time is between 1700000000000 and 1700000006000
24
# Uncertainty: ±3000 μs (±3ms)

1
def TT.after(t: int) -> bool:
2
    """
3
    Returns True if 't' is definitely in the past.
4

5
    Implementation: return t < TT.now().earliest
6

7
    If this returns True, we're 100% certain that 't' has passed,
8
    even accounting for clock uncertainty.
9
    """
10
    now = TT.now()
11
    return t < now.earliest
12

13
# Example: Has the transaction commit timestamp passed?
14
commit_timestamp = 1700000000000
15

16
if TT.after(commit_timestamp):
17
    print("Commit timestamp is definitely in the past")
18
    # Safe to make transaction visible to other readers
19
else:
20
    print("Commit timestamp might still be in the future")
21
    # Must wait before exposing this transaction

1
def TT.before(t: int) -> bool:
2
    """
3
    Returns True if 't' is definitely in the future.
4

5
    Implementation: return t > TT.now().latest
6

7
    If this returns True, we're 100% certain that 't' hasn't
8
    happened yet, even accounting for clock uncertainty.
9
    """
10
    now = TT.now()
11
    return t > now.latest
12

13
# Example: Checking if a timestamp is safely in the future
14
future_timestamp = 1700000010000
15

16
if TT.before(future_timestamp):
17
    print("This timestamp is definitely in the future")
18
    # Safe to schedule work for this time
19
else:
20
    print("This timestamp might have already passed")

1
# Server A thinks current time is 100
2
# Server B thinks current time is 105
3
# Both could be wrong by ±100ms!
4

5
# Server A commits transaction at timestamp 100
6
# Server B commits transaction at timestamp 105
7

8
# Question: Which happened first?
9
# Answer: We actually don't know! The uncertainty overlaps.

1
# Server A: TT.now() = [98, 102]  (uncertainty ±2ms)
2
# Server B: TT.now() = [103, 107] (uncertainty ±2ms)
3

4
# These intervals DON'T overlap!
5
# We can definitively say Server A's time is earlier.
6

7
# If Server A uses timestamp 102 (latest bound)
8
# And waits until TT.after(102) is true
9
# Then EVERY server will agree 102 is in the past

1
Time →
2

3
Server A:  [====A====]           actual time: 100.3ms
4
Server B:     [====B====]        actual time: 101.8ms
5
Server C:        [====C====]     actual time: 103.1ms
6

7
Each bracket represents a TrueTime interval [earliest, latest]
8
The true time is somewhere within that interval

1
Server A:  [====A====]|
2
                      t=102
3

4
Server B:     [====B====]
5
              earliest=100
6

7
If Server B.earliest > 102, then we KNOW t is in the past for B

1
# User transfers $100 from Account A to Account B
2
# Account A is in New York datacenter
3
# Account B is in London datacenter
4

5
class DistributedTransfer:
6
    def execute(self):
7
        # Step 1: Get TrueTime interval
8
        interval = TT.now()
9
        tx_timestamp = interval.latest  # Use latest bound
10

11
        print(f"Transaction timestamp: {tx_timestamp}")
12
        print(f"Uncertainty: ±{interval.uncertainty/2}ms")
13

14
        # Step 2: Execute both updates with this timestamp
15
        ny_server.deduct(account_a, 100, tx_timestamp)
16
        london_server.add(account_b, 100, tx_timestamp)
17

18
        # Step 3: Commit wait - ensure timestamp is in the past
19
        while not TT.after(tx_timestamp):
20
            time.sleep(0.001)  # Wait 1ms
21

22
        # Step 4: Now ALL servers agree this is in the past
23
        # Transaction is committed and visible globally!
24
        print(f"Transaction committed at {tx_timestamp}")
25

26
# Run the transfer
27
transfer = DistributedTransfer()
28
transfer.execute()
29

30
# Output:
31
# Transaction timestamp: 1700000006000
32
# Uncertainty: ±3ms
33
# [waits ~3ms for commit]
34
# Transaction committed at 1700000006000