Interface Reference

July 7, 2026 · View on GitHub

The canonical reference for everything outside the binary: the gRPC wire surface, the command-line interface, and the published Rust crates. This chapter is descriptive rather than tutorial — for behavior and rationale see Client API and Usage, Consensus Integration, and The Allocator. For deployment shapes and operational tuning see Operations and Deployment.

The wire source of truth lives in the tsoracle-proto and tsoracle-standalone .proto files; the CLI source of truth lives in crates/tsoracle-bin/src/cli.rs; the Rust crate reference lives on docs.rs. Anything stated here that contradicts those sources is a documentation bug — please file an issue.

External interfaces at a glance

Surface	Audience	Source of truth	Reference
gRPC over HTTP/2 — `tsoracle.v1.TsoService`	Applications using `tsoracle-client` or any gRPC client	`crates/tsoracle-proto/proto/tsoracle/v1/tso.proto`	§ gRPC wire reference
gRPC over HTTP/2 — `tsoracle.admin.v1.MembershipAdmin`	Cluster operators (openraft only)	`crates/tsoracle-standalone/proto/admin.proto`	§ Admin gRPC reference
CLI — `tsoracle` binary	Operators running the standalone server	`crates/tsoracle-bin/src/cli.rs`	§ CLI reference
Rust crates on crates.io	Embedders and driver authors	the per-crate `lib.rs`	§ Rust crate API and docs.rs/tsoracle

gRPC wire reference

Service: `tsoracle.v1.TsoService`

Seven RPCs — GetTs (timestamps), GetSeq / GetSeqBatch (gapless sequences), GetCurrentMaxSafe (legacy safe-point reads), AcquireLease, RenewLease, ReleaseLease, and GetSafeFrontier (lease-aware safe-frontier reads). Default port is 50551 (loopback by default; configurable via --listen). The server speaks gRPC over HTTP/2 in either plaintext (h2c) or TLS, controlled by --tls-cert/--tls-key/--tls-client-ca.

RPC: `GetTs`

Allocate count consecutive timestamps. Only the current leader serves this RPC.

Request — GetTsRequest:

Field	Type	Constraint	Meaning
`count`	`uint32` (1)	`>= 1`; upper bound is the 18-bit logical capacity, `LOGICAL_MAX + 1 = 262_144`	Number of consecutive timestamps to allocate.

Response — GetTsResponse (on success):

Field	Type	Meaning
`physical_ms`	`uint64` (1)	46-bit milliseconds-since-Unix-epoch component of the grant.
`logical_start`	`uint32` (2)	18-bit logical counter. The response covers logicals `[logical_start, logical_start + count - 1]` at this `physical_ms`.
`count`	`uint32` (3)	Equals the request's `count`. The server never returns a partial grant.
`epoch_hi`	`uint64` (4)	Upper 64 bits of the 128-bit leader epoch that issued this grant.
`epoch_lo`	`uint64` (5)	Lower 64 bits of the leader epoch. Lexicographic `(epoch_hi, epoch_lo)` order equals numeric order; per-node strictly monotone across leader terms.

Success contract:

Each issued timestamp packs as physical_ms << 18 | logical, where logical ∈ [logical_start, logical_start + count - 1].
Across all successful GetTs responses from any node since cluster genesis, the packed integer values are strictly increasing and unique — no duplicates and no regression, even across leader transitions.
See Monotonicity proof for the argument.

Error statuses returned from GetTs:

`tonic::Code`	When	Trailer
`FAILED_PRECONDITION`	This node is not currently the leader.	`tsoracle-leader-hint-bin`
`INVALID_ARGUMENT`	`count == 0` or `count > LOGICAL_MAX + 1` (i.e. `count > 262_144`).	—
`OUT_OF_RANGE`	The requested grant would exceed the 46-bit `physical_ms` field or the 18-bit logical field.	—
`UNAVAILABLE`	The leader's persist path returned a transient driver error (the window advance did not commit). Clients may retry; `tsoracle-client` does.	—
`INTERNAL`	A bug-class error: window-exhausted with no extension available, persist hardware failure, or a violated allocator invariant. Clients should not retry without inspection.	—

tsoracle-client filters the tsoracle-leader-hint-bin trailer out of FAILED_PRECONDITION errors before surfacing the Status to caller code (it is consumed as a routing hint, not propagated). Other gRPC clients see the trailer as standard binary metadata.

RPC: `GetCurrentMaxSafe`

Read the current safe-point — the highest physical_ms at which any timestamp issued at or before that millisecond is durably backed by the leader's persisted window. External coordinators poll this to fence reads/writes that depend on a durable timestamp watermark.

Request — GetCurrentMaxSafeRequest: empty.

Response — GetCurrentMaxSafeResponse:

Field	Type	Meaning
`max_safe_physical_ms`	`uint64` (1)	Safe-point in physical-millisecond units (not the 64-bit packed form). Equal to `persisted_high_water - window_ahead_ms - 1` on the leader when a window has been admitted; zero otherwise.
`epoch_hi`	`uint64` (2)	Upper 64 bits of the leader epoch attached to this value.
`epoch_lo`	`uint64` (3)	Lower 64 bits of the leader epoch.

Response contract:

Leaders return the authoritative current value.
Followers return max_safe_physical_ms = 0 and the zero epoch. Target the leader for an authoritative value; followers do not redirect this RPC.
A leader that has not yet admitted its first window (cold start before the failover fence completes) also returns 0.
Long-lived pollers should fence stale-leader values by tracking (epoch_hi, epoch_lo) and discarding values from a smaller epoch after a larger one.

This RPC does not return FAILED_PRECONDITION, and the response carries no trailer.

RPC: `GetSeq`

Allocate a contiguous block of count dense ordinals for a named key — a gapless, never-reused run. Only the current leader serves this RPC. Dense support is driver-specific (see Driver Comparison); a driver without it returns UNIMPLEMENTED. This RPC is non-idempotent — see the error table.

Request — GetSeqRequest:

Field	Type	Constraint	Meaning
`key`	`string` (1)	non-empty UTF-8, `<= MAX_SEQ_KEY_LEN` (128 bytes)	Names the independent counter the block is drawn from.
`count`	`uint32` (2)	`>= 1`; upper bound is the server's configured `max_seq_count` (default `65_536`)	Size of the contiguous block to reserve.

Response — GetSeqResponse (on success):

Field	Type	Meaning
`key`	`string` (1)	Echoes the request key.
`start`	`uint64` (2)	First ordinal of the block — the durably-committed pre-advance counter value. The block is `[start, start + count)`.
`count`	`uint32` (3)	Equals the request's `count`. The server never returns a partial grant.
`epoch`	`EpochWire` (4)	The leader epoch that issued the block, bundled as a nested message (always present on success). Same `EpochWire` shape as the leader-hint trailer.

Success contract:

The block is [start, start + count) — every ordinal present, none skipped.
Across all successful GetSeq responses for a given key, the issued ordinals are dense and never reused: each grant begins exactly where the previous one ended, even across leader transitions and restarts. A fresh key starts at 0.
Each key is an independent counter; different keys advance separately.

Error statuses returned from GetSeq:

`tonic::Code`	When	Trailer	Pre-commit-certain?
`FAILED_PRECONDITION`	This node is not the leader (carries the hint), or the dense counter would overflow `u64` (no hint).	`tsoracle-leader-hint-bin` on the not-leader case only	Yes
`INVALID_ARGUMENT`	Empty/oversized `key`, `count == 0`, or `count` over the server's `max_seq_count`.	—	Yes
`RESOURCE_EXHAUSTED`	The number of distinct keys reached the driver's cardinality cap.	—	Yes
`UNIMPLEMENTED`	This consensus driver has no dense-sequence support.	—	Yes (nothing advanced)
`UNAVAILABLE`	A transient driver fault (storage hiccup, momentary quorum loss); the advance did not commit.	—	Yes
`INTERNAL`	A permanent driver fault or violated invariant reached after the request was admitted; the durable advance may have committed.	—	No — ambiguous

Because the dense path is non-idempotent, tsoracle-client treats any post-send failure that is not provably pre-commit-certain (a transport timeout after the request was sent, or INTERNAL) as ClientError::SeqUncertain and does not retry it — the advance may already have committed. Every pre-commit-certain status above is handled or retried normally. See GetSeq — dense, gapless sequences for the caller's reconciliation contract.

RPC: `AcquireLease`

Acquire or idempotently re-acquire a stamping lease for an opaque holder group. Only the current leader serves this RPC.

Request — AcquireLeaseRequest:

Field	Type	Constraint	Meaning
`holder`	`bytes` (1)	1..=128 bytes	Opaque holder-group key; compared only for byte equality.
`holder_epoch`	`uint64` (2)	caller-defined monotone value within `holder`	Equal epoch is idempotent, higher epoch supersedes, lower epoch rejects.
`ttl_ms`	`uint64` (3)	server floor/ceiling, defaults 5s/300s	Requested lease TTL in milliseconds.

Response — AcquireLeaseResponse:

Field	Type	Meaning
`lease_id`	`uint64` (1)	Stable identity for renew/release. Equal to the acquire-time committed high-water value.
`ts_upper_bound`	`uint64` (2)	Highest physical millisecond the holder may stamp.
`expires_at_ms`	`uint64` (3)	Server-clock expiry in unix milliseconds. Expiry is `now_ms >= expires_at_ms`.
`epoch`	`EpochWire` (4)	Leader epoch that granted the lease.

Error statuses returned from AcquireLease:

`tonic::Code`	When	Trailer
`FAILED_PRECONDITION`	This node is not the leader, or the requested holder epoch is stale.	Leader hint on not-leader only
`INVALID_ARGUMENT`	Empty/oversized holder or TTL outside server bounds.	—
`UNIMPLEMENTED`	The consensus driver does not support durable leases.	—
`UNAVAILABLE`	A transient high-water or lease-set persist failure occurred before the grant committed in memory.	—
`INTERNAL`	Permanent driver fault or allocator invariant violation.	—

RPC: `RenewLease`

Advance a live lease's bound and expiry, re-arming its acquire-time TTL.

Request — RenewLeaseRequest: lease_id (uint64, field 1).

Response — RenewLeaseResponse: ts_upper_bound (uint64, field 1), expires_at_ms (uint64, field 2), and epoch (EpochWire, field 3).

Error statuses returned from RenewLease:

`tonic::Code`	When	Trailer
`FAILED_PRECONDITION`	Not leader, expired lease, or superseded lease.	Leader hint on not-leader only
`NOT_FOUND`	Unknown lease id.	—
`UNIMPLEMENTED`	The consensus driver does not support durable leases.	—
`UNAVAILABLE`	Transient persist failure before the renewal committed in memory.	—
`INTERNAL`	Permanent driver fault or invariant violation.	—

RPC: `ReleaseLease`

Surrender a lease immediately. Release is idempotent: unknown, expired, or already-released ids succeed without a durable write.

Request — ReleaseLeaseRequest: lease_id (uint64, field 1).

Response — ReleaseLeaseResponse: empty.

Error statuses returned from ReleaseLease:

`tonic::Code`	When	Trailer
`FAILED_PRECONDITION`	This node is not the leader.	Leader hint
`UNIMPLEMENTED`	The consensus driver does not support durable leases.	—
`UNAVAILABLE`	Transient lease-set persist failure.	—
`INTERNAL`	Permanent driver fault or invariant violation.	—

RPC: `GetSafeFrontier`

Read the lease-aware safe frontier: min(unexpired lease ts_upper_bound values, committed high-water), in physical-millisecond units.

Request — GetSafeFrontierRequest: empty.

Response — GetSafeFrontierResponse:

Field	Type	Meaning
`frontier_physical_ms`	`uint64` (1)	Lease-aware frontier; zero on followers or before a leader admits a window.
`epoch_hi`	`uint64` (2)	Upper 64 bits of the leader epoch.
`epoch_lo`	`uint64` (3)	Lower 64 bits of the leader epoch.

Followers return frontier_physical_ms = 0 and zero epoch, matching GetCurrentMaxSafe; this RPC does not redirect.

Service: `tsoracle.admin.v1.MembershipAdmin`

See § Admin gRPC reference below.

Trailer: `tsoracle-leader-hint-bin`

When GetTs returns FAILED_PRECONDITION, the server attaches a binary metadata trailer named tsoracle-leader-hint-bin whose body is the postcard encoding of a LeaderHint message.

`LeaderHint` field	Type	Semantics
`leader_endpoint`	`optional string` (1)	Scheme-less `host:port` of the leader's `TsoService` endpoint as known to this node. Absent on cold start or right after a leadership change. The string must not carry a `http://` or `https://` scheme — the client rejects a scheme-bearing hint to defend against TLS downgrade.
`leader_epoch`	`optional EpochWire` (2)	The leader's 128-bit epoch, bundled as a nested message so a half-populated epoch is unrepresentable on the wire. Either both halves are present (`epoch.hi`, `epoch.lo`) or neither is.

EpochWire {
    uint64 hi = 1;   // more significant half
    uint64 lo = 2;   // less significant half
}

Contract:

The hint is advisory, not authoritative. A stale hint costs an extra client round-trip; it does not affect correctness.
A hint whose leader_epoch is strictly smaller than the client's cached leader epoch is dropped (the client treats it as evidence of a delayed response from an old term).
The metadata key is suffixed -bin per gRPC convention; consumers must request binary metadata and base64-decode if their gRPC stack does not handle that automatically.

See The leader-hint trailer for the consumption protocol on the client side.

Admin gRPC reference

The membership-admin surface is bound to a separate listen address (--admin-listen), separate from the public TsoService port, and is implemented only by the openraft driver. The file and paxos drivers return UNSUPPORTED for every mutating RPC; ListMembers works on all drivers and reports a fixed view for paxos/file.

All mutating RPCs are idempotent on the target id: re-issuing a successful change is a no-op. The server serializes them on an internal lock — two reconfigurations cannot race. Mutating RPCs are leader-only: a non-leader returns ok=false, error=NOT_LEADER, and (when known) leader_admin_endpoint set to the leader's admin port. The tsoracle admin CLI uses this for one-step re-routing.

Service: `tsoracle.admin.v1.MembershipAdmin`

RPC	Request	Response	Leader-only
`ListMembers`	`ListMembersRequest{}`	`MembershipView`	No
`AddLearner`	`AddLearnerRequest{ id, raft_addr, service_endpoint, admin_endpoint }`	`ChangeResponse`	Yes
`Promote`	`PromoteRequest{ id }`	`ChangeResponse`	Yes
`RemoveNode`	`RemoveNodeRequest{ id }`	`ChangeResponse`	Yes
`ActivateFormat`	`ActivateFormatRequest{ target }`	`ChangeResponse`	Yes

Message: `MembershipView` (returned by `ListMembers`)

Field	Type	Meaning
`members`	`repeated MemberEntry` (1)	The membership as this node currently sees it.
`has_leader`	`bool` (2)	True iff `leader` is meaningful.
`leader`	`uint64` (3)	Cluster-current leader's node id. Meaningful only when `has_leader == true` — consumers must not interpret `leader == 0` as "no leader" (proto3 has no `optional uint64`, so this pair encodes `Option<u64>`).

Message: `MemberEntry`

Field	Type	Meaning
`id`	`uint64` (1)	Cluster-unique node id, stable across address changes.
`role`	`MemberRole` (2)	`VOTER` (counted in quorum) or `LEARNER` (replicates, not in quorum).
`raft_addr`	`string` (3)	`host:port` of the node's openraft peer transport. Consensus traffic.
`service_endpoint`	`string` (4)	Scheme-less `host:port` of the node's public `TsoService` endpoint. What clients use; what leader hints carry.
`admin_endpoint`	`string` (5)	`host:port` of the node's admin gRPC endpoint. What `NOT_LEADER` responses on the admin port redirect to.

The three address fields are required at AddLearner time and stored verbatim in the membership log; the server does not parse or canonicalize them.

Message: `ChangeResponse` (returned by every mutating RPC)

Field	Type	Meaning
`ok`	`bool` (1)	Authoritative success flag. Always check this before reading `error`.
`error`	`AdminErrorKind` (2)	Typed error kind. Meaningful only when `ok == false`.
`leader_admin_endpoint`	`string` (3)	Set when `error == NOT_LEADER` and a leader admin endpoint is known. Empty string means no hint available (cold start or no leader yet).
`message`	`string` (4)	Human-readable detail — for example, the driver's error string when `error == DRIVER`. Empty on success. Suitable for operator display; programmatic dispatch should be on `error`, not on this string.

Enum: `AdminErrorKind`

Value	When
`ADMIN_ERROR_KIND_UNSPECIFIED` (0)	proto3 default. The server never emits this with `ok == false`; the wire never carries `error=UNSPECIFIED` paired with `ok=false`.
`NOT_LEADER` (1)	Mutating RPC reached a follower. `leader_admin_endpoint` carries the leader's admin port when known. Note that `ActivateFormat`'s `NOT_LEADER` always leaves `leader_admin_endpoint` empty (the underlying error is a unit variant).
`UNSUPPORTED` (2)	This driver does not implement runtime membership changes. Returned by `paxos` and `file` for every mutating RPC.
`NOT_MEMBER` (3)	`Promote` against an id not currently in the membership.
`NOT_CAUGHT_UP` (4)	Reserved. The current openraft impl folds learner-not-caught-up into `DRIVER` with the upstream error text; this variant is reserved for a future explicit catch-up check.
`WOULD_LOSE_QUORUM` (5)	`RemoveNode` against the last remaining voter. Other quorum-loss shapes (e.g. removing two of three) are the operator's responsibility.
`TIMEOUT` (6)	Reserved. Not currently produced — the openraft impl folds timeouts into `DRIVER`. Reserved for future explicit-deadline plumbing.
`DRIVER` (7)	Catch-all for an upstream driver error not captured by a typed variant. `message` carries the driver's error string.
`MEMBERS_BELOW_TARGET` (8)	`ActivateFormat` rejected by the all-members gate: at least one member's `max_readable_version` is below the requested `target`.
`TARGET_OUT_OF_RANGE` (9)	`ActivateFormat` apply-arm defense-in-depth: `target` is outside the local binary's readable range.
`MEMBERSHIP_CHANGED` (10)	`ActivateFormat` apply-keyed no-op: the gated set drifted out of the membership by the entry's own log position. Operator re-gates and re-issues.

Adding new variants is backwards compatible: clients that don't recognize a value can fall back to the message field.

RPC details

AddLearner — Idempotent on id: a node already in the membership is a no-op even if the addresses differ. Blocks until the learner is registered. Errors: NOT_LEADER, UNSUPPORTED, DRIVER.
Promote — Idempotent on id (already-voter is a no-op). Errors: NOT_LEADER, NOT_MEMBER, UNSUPPORTED, DRIVER (which today subsumes the upstream "learner not caught up" case).
RemoveNode — Idempotent on id (unknown ids return ok). Refuses to remove the last remaining voter (WOULD_LOSE_QUORUM). Removing the current leader is allowed; openraft commits the removal while still leader, then steps down. Errors: NOT_LEADER, WOULD_LOSE_QUORUM, UNSUPPORTED, DRIVER.
ActivateFormat — Initiate a format-version activation to target. Runs the all-members capability gate, proposes the bump via raft, and reports the apply-keyed outcome. Errors: NOT_LEADER, MEMBERS_BELOW_TARGET, TARGET_OUT_OF_RANGE, MEMBERSHIP_CHANGED, UNSUPPORTED, DRIVER. See Format-migration upgrade for the broader story.

CLI reference

Source of truth: crates/tsoracle-bin/src/cli.rs. The crate is published as tsoracle and produces a single binary, also named tsoracle.

Top-level synopsis

tsoracle [SERVE-FILE-FLAGS]
tsoracle serve file     [SERVE-FILE-FLAGS]
tsoracle serve openraft [SERVE-COMMON-FLAGS] [OPENRAFT-FLAGS]
tsoracle serve paxos    [SERVE-COMMON-FLAGS] [PAXOS-FLAGS]
tsoracle init           --seed-physical-ms <N> [--state-dir <PATH>]
tsoracle admin <SUBCOMMAND> ...      # openraft feature only

Bare tsoracle (no subcommand) is exactly equivalent to tsoracle serve file with all defaults. tsoracle --help and tsoracle <SUBCOMMAND> --help print clap-generated usage; this section is the long-form reference.

Flags shared by every `serve` subcommand

These come from CommonServeArgs. Every serve mode accepts them with the same defaults.

Flag	Type	Default	Meaning
`--listen`	`SocketAddr`	`127.0.0.1:50551`	Client-facing gRPC listen address (the `TsoService` port).
`--window-ahead`	duration (humantime)	`3s`	How far ahead of wall-clock the leader advances its persisted high-water. Higher values reduce extension frequency at the cost of a larger time-to-live for a stale leader's window. See Sizing window_ahead.
`--failover-advance`	duration	`1s`	How far past the recovered high-water the failover fence advances on leadership gain. Must exceed the worst-case wall-clock skew between leaders. See Sizing failover_advance.
`--lease-ttl-floor`	duration	`5s`	Lower bound on requested lease TTLs.
`--lease-ttl-ceiling`	duration	`300s`	Upper bound on requested lease TTLs.
`--log`	string	`info`	`tracing` env-filter directive (`info`, `debug`, `tsoracle_server=debug,info`, etc.).
`--tls-cert`	path	—	PEM server certificate chain for the client gRPC API. Enables TLS on `--listen`.
`--tls-key`	path	—	PEM private key paired with `--tls-cert`.
`--tls-client-ca`	path	—	PEM CA used to verify client certificates. Enables client mTLS on the API port.

--tls-cert and --tls-key must be supplied together; supplying --tls-client-ca without them is an error.

`tsoracle serve file`

Single-node, fsync-durable. The default mode. No replication — losing the node loses availability.

Common flags (above), plus:

Flag	Type	Default	Meaning
`--state-dir`	path	`./tsoracle-data`	Where to persist window state. Created on first start; first run against an empty directory begins at high-water 0.

`tsoracle serve openraft`

HA via openraft. Three or more nodes. Compiled in when the binary is built with the openraft feature (enabled by default on crates.io releases).

Common flags (above), plus:

Flag	Type	Default	Meaning
`--id`	`u64`	required	This node's numeric raft id. Must be unique across the cluster.
`--raft-addr`	`SocketAddr`	required	Bind address for the raft peer transport (consensus traffic). Plaintext on loopback; routable bind requires the `--peer-tls-*` triple or `--allow-insecure-peer`. See Peer-port trust boundary.
`--raft-dir`	path	required	Directory for raft log + state-machine data. Persisted across restarts.
`--bootstrap`	bool	`false`	Initialize the cluster on this node, first boot only. Used exactly once per cluster lifetime.
`--members`	string	—	Initial membership, only valid with `--bootstrap`. Format: `id=raft_host:port/service_host:port/admin_host:port,...`.
`--heartbeat-ms`	`u64`	`250`	Raft heartbeat interval.
`--election-min-ms`	`u64`	`1000`	Lower bound on the randomized election timeout.
`--election-max-ms`	`u64`	`2000`	Upper bound on the randomized election timeout.
`--admin-listen`	`SocketAddr`	—	Bind address for the membership-admin gRPC server. Omitting the flag serves no admin surface. Plaintext on loopback; non-loopback bind requires the `--admin-tls-*` triple.
`--admin-tls-cert`	path	—	PEM server certificate for the admin gRPC server. Enables admin mTLS — needs all three `--admin-tls-*` flags.
`--admin-tls-key`	path	—	PEM private key paired with `--admin-tls-cert`.
`--admin-tls-ca`	path	—	PEM CA used to verify connecting admin clients. Operator-dedicated; not the peer CA.
`--peer-tls-cert`	path	—	PEM node certificate for the peer transport. Enables peer mTLS — needs all three `--peer-tls-*` flags.
`--peer-tls-key`	path	—	PEM private key paired with `--peer-tls-cert`.
`--peer-tls-ca`	path	—	PEM CA used to verify connecting peers. Cluster-dedicated.
`--allow-insecure-peer`	bool	`false`	Opt out of the peer-listener secure-by-default guard. Allows routable bind without `--peer-tls-*`. Matches the helm chart's `tls.allowInsecurePeer`. Intended for single-host dev or service-mesh-terminated mTLS only.

`tsoracle serve paxos`

HA via OmniPaxos. Three or more nodes. Compiled in when the binary is built with the paxos feature (enabled by default on crates.io releases).

Common flags (above), plus:

Flag	Type	Default	Meaning
`--node-id`	`u64`	required	This node's OmniPaxos pid. Must be unique across the cluster.
`--peer-listen`	`SocketAddr`	required	Bind address for the paxos peer transport. Plaintext on loopback; routable bind requires the `--peer-tls-*` triple or `--allow-insecure-peer`. See Peer-port trust boundary.
`--peers`	string	required	Comma-separated `id=host:port` paxos peer addresses. Required at every start, not just bootstrap.
`--tso-peers`	string	required	Comma-separated `id=host:port` tsoracle service addresses (per-node `TsoService` ports), used to populate `LeaderHint` for follower redirects.
`--data-dir`	path	required	Directory for the paxos log + meta.
`--tick-interval`	duration	`20ms`	OmniPaxos tick interval.
`--peer-tls-cert`	path	—	PEM node certificate for the peer transport. Enables peer mTLS — needs all three `--peer-tls-*` flags.
`--peer-tls-key`	path	—	PEM private key paired with `--peer-tls-cert`.
`--peer-tls-ca`	path	—	PEM CA used to verify connecting peers.
`--allow-insecure-peer`	bool	`false`	Opt out of the peer-listener secure-by-default guard. Allows routable bind without `--peer-tls-*`. Matches the helm chart's `tls.allowInsecurePeer`. Intended for single-host dev or service-mesh-terminated mTLS only.

`tsoracle init`

Initialize a fresh file-driver state directory at a seeded high-water. Useful when migrating from a prior timestamp source — see Migration.

Flag	Type	Default	Meaning
`--state-dir`	path	`./tsoracle-data`	Directory to initialize. Must not already contain `file`-driver state.
`--seed-physical-ms`	`u64`	required	High-water to seed. Every subsequent issued timestamp's `physical_ms` will be strictly greater than this value.

`tsoracle admin`

Administer cluster membership over the admin gRPC port. Available only when the binary is built with the openraft feature. Backed by the tsoracle.admin.v1.MembershipAdmin RPCs above.

Each subcommand accepts --endpoint (any node's admin endpoint — e.g. https://127.0.0.1:50561) plus the optional --client-tls-* triple for connecting to an mTLS-enabled admin server.

Common admin-client flags (AdminClientTlsArgs):

Flag	Type	Meaning
`--client-tls-cert`	path	PEM client certificate to present to the admin gRPC server.
`--client-tls-key`	path	PEM private key for `--client-tls-cert`.
`--client-tls-ca`	path	PEM CA used to verify the admin server's certificate.

`tsoracle admin members`

List current members. Answerable by any node.

Flag	Type	Meaning
`--endpoint`	string	Admin endpoint of any node.
`--client-tls-*`	path	See above.

`tsoracle admin add-learner`

Add a non-voting learner.

Flag	Type	Meaning
`--endpoint`	string	Admin endpoint to address. The CLI follows a `NOT_LEADER` redirect to `leader_admin_endpoint`.
`--id`	`u64`	New node's raft id. Cluster-unique.
`--raft-addr`	string	`host:port` of the new node's raft peer transport.
`--service-endpoint`	string	Scheme-less `host:port` of the new node's public `TsoService` endpoint.
`--admin-endpoint`	string	`host:port` of the new node's admin gRPC endpoint.
`--client-tls-*`	path	See above.

`tsoracle admin promote`

Promote a learner to voter.

Flag	Type	Meaning
`--endpoint`	string	Admin endpoint to address. Follows `NOT_LEADER` redirect.
`--id`	`u64`	Id of the learner to promote.
`--client-tls-*`	path	See above.

`tsoracle admin remove`

Remove a node by id (voter or learner).

Flag	Type	Meaning
`--endpoint`	string	Admin endpoint to address. Follows `NOT_LEADER` redirect.
`--id`	`u64`	Id of the node to remove.
`--client-tls-*`	path	See above.

`tsoracle admin activate-format`

Initiate a format-version activation. Runs the all-members capability gate, then proposes the bump via raft.

Flag	Type	Meaning
`--endpoint`	string	Admin endpoint of any cluster member. The CLI does not auto-redirect on `NOT_LEADER` for this RPC — the underlying error variant carries no endpoint hint, so re-issue against a known leader.
`--target`	`u8`	Target format version. Must be within the local binary's readable range and supported by every cluster member.
`--client-tls-*`	path	See above.

Exit codes specific to activate-format:

Code	Meaning
`0`	Success.
`2`	Gate rejected the activation — at least one member's `max_readable_version` is below `--target` (`MEMBERS_BELOW_TARGET`).
`3`	Receiving node is a follower (`NOT_LEADER`).
`4`	Receiving node's local readable range does not include `--target` (`TARGET_OUT_OF_RANGE`).
`1`	Any other failure.

Other admin subcommands use only 0 (success) and 1 (failure).

Rust crate API

Published on crates.io. Generated reference: https://docs.rs/tsoracle (and analogously for each crate below). Where prose chapters complement the generated docs, the third column points at them.

Crate	Role	Companion chapter
`tsoracle`	The CLI binary (this section above). Depends on the crates below.	§ CLI reference
`tsoracle-client`	Async Rust client. The recommended way to call `TsoService` from Rust code.	Client API and Usage, The Client Driver
`tsoracle-server`	The server library. Embed `Server::builder()...build()?.serve_with_shutdown(...)` to host the gRPC service in your own binary.	Architecture Deep Dive, Key Subsystems
`tsoracle-core`	Sync algorithm core: the window allocator. No I/O, no async.	The Allocator
`tsoracle-consensus`	The `ConsensusDriver` trait. Implement this to back tsoracle with your own replicated log.	Consensus Integration
`tsoracle-driver-file`	Single-node fsync-durable driver. The default.	Driver Comparison
`tsoracle-driver-openraft`	Driver wrapping an openraft cluster.	Driver Comparison
`tsoracle-driver-paxos`	Driver wrapping an OmniPaxos cluster.	Driver Comparison
`tsoracle-standalone`	Per-driver bootstrap helpers + peer transport. Used by the CLI binary; also embeddable.	—
`tsoracle-proto`	Generated protobuf types for `tsoracle.v1.TsoService`. Use directly only when bypassing `tsoracle-client`.	§ gRPC wire reference
`tsoracle-codec`	Versioned postcard codec for on-disk and in-meta records.	Format-migration upgrade
`tsoracle-openraft-toolkit`	Lower-level openraft glue, including `LogStoreCodec<C>`. For driver authors and embedders who already host their own openraft.	Consensus Integration
`tsoracle-paxos-toolkit`	Lower-level OmniPaxos glue.	Consensus Integration
`tsoracle-failpoint`, `tsoracle-yieldpoint`	Test-only fault-injection points. Compiled in only when the `failpoints` / `yieldpoints` feature is enabled.	Failpoint Testing, Yield-point Testing

Stability and versioning

The gRPC public service is versioned by package: tsoracle.v1.TsoService. Field numbers are stable; new optional fields may be added within v1. A future breaking wire change would land as tsoracle.v2.
The admin gRPC service is tsoracle.admin.v1.MembershipAdmin. New AdminErrorKind variants may be added within v1 — consumers must fall back to the message field when they encounter an unrecognized enum value, exactly as required by the proto contract.
The Rust crates follow Cargo semver. Each crate is versioned independently; consult the crate's CHANGELOG.md (or the release-plz entries on the GitHub Releases page) for migration notes.
The CLI surface is stable across patch and minor releases of the same crates.io major version of the tsoracle binary crate. Flag removals or rename without alias are major-version events.
On-disk format compatibility is governed by the per-record format_version byte (currently 4). The binary supports a documented [MIN_READABLE_VERSION, MAX_READABLE_VERSION] range so a rolling upgrade can convert in place. See Format-migration upgrade for the full story, including the tsoracle admin activate-format flow that flips the cluster-wide active write version.