roughly

An asynchronous implementation of the Roughtime protocol for Python.

Implements the experimental Roughtime protocol specified in RFC 10049.

The client and server support Roughtime version 1, with the server preferring it when offered by a client.
Drafts 07 through 19 remain supported for querying servers, and drafts 10 through 19 for running a server. The server also supports queries from Google Roughtime clients.

Quickstart

Installation

You can install roughly from PyPI using your favorite package manager, for example with pip:

pip install roughly
# or with the cli extra
pip install roughly[cli]

As a CLI

Querying

You can use roughly as a command line tool to query Roughtime servers. Install roughly with the cli extra using your favorite CLI package manager, for example with uv (or pipx):

uv tool install roughly[cli]
pipx install roughly[cli]

Then you can query a Roughtime server like so:

roughly query time.teax.dev 2002 84pMADvKUcSOq5RNbVRjVrjiU16Dxo2XV2Qkm+4DRTg=

The default Roughtime port is 5319. This example explicitly uses the server's configured port, 2002.

Or run ecosystem queries (assuming you have an ecosystem.json file):

roughly ecosystem malfeasance
roughly ecosystem state

Running a server

You can also run your own Roughtime server using roughly.

First, generate a keypair:

roughly server keygen

This will output a .env file containing the server's private key.

You can then run the server like so:

ROUGHLY_PRIVATE_KEY="your_private_key_here" roughly -v server run

By default, the server will bind to 0.0.0.0:5319. You can change this using the --host and --port flags. I recommend running the server with verbose logging enabled (-v), so you can see incoming requests and debug any issues. Additionally you might want to consider turning off response greasing while testing using the --no-grease flag.

Every server run option can also be set through an environment variable, named after the flag with a ROUGHLY_ prefix. Check roughly server run --help for more information.

As a library

Querying

roughly can be used as an asynchronous library to query Roughtime servers from your own Python code.

import roughly.client

# <snip!>

response = await roughly.client.send_request(
    host="time.teax.dev",
    port=2002,
    public_key=base64.b64decode(b"84pMADvKUcSOq5RNbVRjVrjiU16Dxo2XV2Qkm+4DRTg="),
)
midpoint = response.signed_response.midpoint
radius = response.signed_response.radius
print(f"time: {midpoint} ± {radius}s")

send_request verifies the response before returning. Any failure raises roughly.errors.VerificationError; malformed packets raise PacketError. Both inherit from RoughtimeError. Once you have a response, true time is somewhere in the range [midpoint - radius, midpoint + radius].

An ecosystem is a list of servers a client can query. roughly.ecosystem provides a flow for querying them and checking for disagreement:

from pathlib import Path
import json

from roughly.ecosystem import (
    confirm_malfeasance,
    load_ecosystem,
    malfeasance_report,
    pick_servers,
    query_servers,
)

ecosystem = load_ecosystem(Path("ecosystem.json"))
selected_servers = await pick_servers(ecosystem)
responses = await query_servers(selected_servers)
report = malfeasance_report(responses, selected_servers)

if confirm_malfeasance(report):
    print("something scary is going on!")
    with open("malfeasance_report.json", "w") as f:
        json.dump(report, f, indent=2)

pick_servers filters down to servers that are actually reachable right now. query_servers returns one (VerifiableResponse, raw_bytes) per server. confirm_malfeasance returns true when the responses can't all be true at the same time.

Running a server

You can also programmatically run your own Roughtime server. Server.create() mints a long-term ed25519 keypair on each call, so for any server clients should be able to keep talking to across restarts, pass private_key=... with a key you've persisted yourself:

import roughly.server

server = roughly.server.Server.create() # generates a fresh keypair
await roughly.server.serve(server)

The reason to use the library directly instead of the CLI is that both roughly.server.Server and roughly.server.UDPHandler are designed to be extended. A sample use case is a deliberately malfeasant server:

import roughly
import roughly.server

class ScaryServer(roughly.server.Server):
    @staticmethod
    def get_time() -> int:
        # return a wrong-ish time
        return int(time.time()) + random.randint(-3600, 3600)

await roughly.server.serve(ScaryServer.create())

Ecosystem

An example ecosystem file can be found at ecosystem.json, I tried my best to include as many servers as I could find.

If you know of any other Roughtime servers, run your own server, or have updated public keys for any of the listed servers, please open a PR or an issue!

Interoperability

The interopability matrix of roughly against Roughtime servers looks like this:

Roughly as a client

Server	Result
butterfield	✅
cloudflare	✅
pyroughtime	✅
roughenough	✅
roughtimed	✅
roughly	✅
tannerryan-roughtime	✅

Roughly as a server

Client	Result
cloudflare	✅
craggy	✅
node-roughtime	✅
pyroughtime	✅
roughenough	✅
roughly	✅
tannerryan-roughtime	✅
vroughtime	✅

draft-7

Support for draft-7 is limited, in the sense that roughly fits responses from draft-7 servers into its current response data structures. This means that some fields that are not present in draft-8+ (such as DUT1, DTAI, and LEAP) will be missing. Additionally draft-7 offered for the precision of radius to be in microseconds, while draft-8+ uses seconds, this precision will be lost when querying draft-7 servers, and be clamped to a minimum of one second.

License

This project is licensed under the MIT License. See the LICENSE file for details.