Console WebSocket Surface
The authenticated multiplexed console WebSocket at /console/websocket, its stream catalog, inbound commands (subscribe, items.create, items.watch), outbound stream events, first-event-immediate burst coalescer, per-connection stream and payload caps, and per-account command and outbound rate limits.
Overview
The console WebSocket is an authenticated, multiplexed real-time surface at
/console/websocket that backs the truestamp console terminal client and any
other client you write by hand. Over a single connection it lets you subscribe to
live streams of platform activity (block lifecycle, entropy observations,
commitments into blocks and into epochs, and your team’s items) and issue a small set of commands,
including submitting a new item for timestamping and watching its lifecycle. The
socket always requires credentials: it accepts either an API key or an OAuth 2.1
bearer access token, and rejects any connection that presents neither. It speaks
the Phoenix Channels V2 wire format (five-element JSON arrays), so it can be driven
from a command-line WebSocket tool as easily as from a purpose-built client.
Connecting and authentication
The surface is a WebSocket upgrade at /console/websocket. You must pin the
Phoenix Channels wire-protocol version in the query string as vsn=2.0.0; this
selects the array-form serializer the surface speaks and is not a Truestamp API
version.
Authentication is mandatory and can be supplied one of two ways:
-
API key as a query parameter on the upgrade URL, the same key format used by the JSON API:
wss://www.truestamp.com/console/websocket?vsn=2.0.0&api_key=truestamp_<token> -
OAuth 2.1 bearer access token. Browsers cannot set request headers on a WebSocket upgrade, so the token is normally supplied as an
access_tokenquery parameter, mirroring theapi_keymechanism. AnAuthorization: Bearer <token>header is also accepted as a fallback for callers that can set headers on the upgrade. Either way, an OAuth connection must carry theconsole:readscope to open the socket at all; theconsole:writescope is checked separately, only when you issue a write command. OAuth is honored only while the server’s OAuth 2.1 authorization server is enabled; when it is off, only API-key connections open.
If neither a valid API key nor a valid token is presented, the upgrade is refused
and the connection closes. On success the server binds your identity and current
team to the connection, and every command and subscription runs authorized against
that context. API-key connections stay open until you close them; OAuth connections
are time-boxed to the access token’s expiry, at which point the server pushes a
token_expired event and closes the channel so the client can reconnect with a
fresh token.
Wire format and the lobby topic
The surface uses Phoenix Channels V2 framing: each message is a five-element JSON
array of the form [join_ref, ref, topic, event, payload]. The ref is a
correlation id you choose; the server echoes it on the matching reply so you can
pair a phx_reply back to the request that produced it. Server-initiated pushes
carry null for both refs.
All commands and stream events flow over one topic, console:lobby, which you join
by sending a phx_join event. The join reply is a welcome envelope containing your
resolved scope (user id, current team id, plan), the stream catalog available to
you, and the server version. A separate console:clock topic on the same socket
emits a one-per-second server time tick and is optional.
Malformed inbound frames (for example multi-line JSON split across several frames, or a stray blank line) are dropped cleanly rather than tearing down the connection, so hand-rolled debugging with a line-oriented tool is forgiving. A frame holding a number of more than 1,024 characters, outside a string, is dropped the same way.
Keeping the connection alive
To hold the socket open through network middlebox idle timeouts, clients should
periodically send a no-op heartbeat frame, roughly every 30 seconds, on the reserved
phoenix topic:
[null, "<ref>", "phoenix", "heartbeat", {}]
The server acknowledges each heartbeat with {"status": "ok", "response": {}}.
Purpose-built clients send this frame automatically, but a hand-rolled client must
send it itself or the connection will silently drop after an idle period.
Stream catalog
Clients subscribe by stream id, never by an internal topic. The catalog is the stable contract. The streams available to every authenticated connection are:
| Stream id | Scope | What it carries |
|---|---|---|
blocks |
global | Internal ledger block lifecycle (creation and later transitions). |
blocks.healing |
global | The hourly block check’s transitions: a block moved forward to committed, or back to finalized. |
beacons |
global | Public beacon projection of newly created blocks (id, hash, previous_hash, timestamp). |
commitments.subjects |
global, team | Merkle inclusion commitments binding a subject into a block: every entropy observation’s, and those of your current team’s items that you can read. |
commitments.blocks |
global | Commitments of blocks into epochs whose hashes Truestamp wrote to Stellar or Bitcoin, sent once the chain holds the epoch’s transaction. |
entropy.nist |
global | NIST beacon entropy observations. |
entropy.stellar |
global | Stellar entropy observations. |
entropy.bitcoin |
global | Bitcoin entropy observations. |
items.team |
team | Item lifecycle events for your current team’s items that you can read. |
items.<item_id> |
per-item | Lifecycle events for a single item you explicitly watch, while you can read it. |
The items.team stream is only offered when your connection has a current team.
The item commitments on commitments.subjects follow your current team the same
way; with no current team the stream carries entropy observations’ commitments only.
Who receives an item’s events
An item’s events (created, updated and deleted), on items.team or on its watch,
and its commitment on commitments.subjects reach you only when you can read the
item under its visibility:
- a
publicitem, and ateamitem of a team you belong to in any role, reach you; - an item you own reaches you whatever its visibility;
- as a team owner or admin you receive every item of the team, private ones included;
- a teammate’s
privateitem never reaches a team member or viewer: not its claims, itsitem_hashor its item code, not its commitment, and not its deletion, so you are never told that a private item you cannot read existed.
The same holds while you watch an item: if it becomes private and you can no
longer read it, its events stop reaching you. Your role in each team is read
when you connect, when you switch team, when you watch an item, and again
whenever one of your memberships changes or is removed, so a demotion or a
removal applies to the next event. Once you are removed from your current team,
items.team and commitments.subjects carry none of its items, public ones
included, as for anyone who was never in it. A team you join while connected is read
when you next switch team or watch an item, or when you reconnect. A deletion
carries only the item’s id. items.team carries only your current team’s
items: a watch you keep after switching team still tells you of its own item,
but never brings that team’s other items onto items.team.
The per-item items.<item_id> streams are dynamic: they appear when you watch an
item and are removed when you unwatch it. Any stream id not in the catalog is
rejected even for an authenticated caller.
Inbound commands
Every command is an event on console:lobby. The server answers with a phx_reply
carrying {"status": "ok" | "error", "response": {...}}.
| Command | Payload | On success |
|---|---|---|
subscribe |
{"streams": [stream_id, ...]} |
{subscribed, rejected, active} |
unsubscribe |
{"streams": [stream_id, ...]} |
{unsubscribed, active} |
subscriptions |
{} |
{active} (the current active set) |
ping |
{} |
{pong: <unix_ms>} |
items.create |
{"claims_json", "watch"?} |
{item: <projection>, watched, claims_jcs, claims_hash} |
items.watch |
{"id": "<item id, item code or item_hash>"} |
{watching, id, item_code} |
items.unwatch |
{"id": "<item_id or item_code from the watch reply>"} |
{unwatching: "<item_id>"} |
scope.switch_team |
{"team_id": "<team_id>"} |
{scope, team, role, streams} |
token.refresh |
{"access_token": "<token>"} |
{exp: <unix>} (OAuth connections only) |
A subscribe call reports which requested streams were accepted, which were
rejected (unknown, not permitted, or over the per-connection stream cap), and the
full active set after the call.
scope.switch_team re-binds the connection to another team you belong to without
dropping the socket: catalog subscriptions are re-pointed at the new team while
per-item watches keep their original binding, so you can watch an item that lives in
a different team. token.refresh is an in-band keep-alive for OAuth connections: it
adopts a freshly minted access token and reschedules the expiry so a long-lived
session does not have to reconnect just because a token rolled over. The replacement
token is re-validated exactly as at connect and must carry console:read and belong
to the same user, so a refresh can never swap identities. API-key connections have no
token to refresh and never expire mid-session, so the command is rejected there.
Submitting an item with items.create
items.create submits a new item for timestamping over
the same connection. The payload is claims_json, a string holding the claims as a
JSON text of at most 65,536 bytes, and an optional watch flag. The claims are
committed exactly as sent, under the same claims rules as the JSON:API, GraphQL and
MCP. They travel as a text because every frame is read by a JSON decoder that keeps
the first of two repeated member names and drops the other, which would hide a repeat
the claims rules refuse.
It has two modes, distinguished by whether the claims hold a hash:
-
External-hash mode: the claims hold
hashandhash_type, which name the algorithm (for example a SHA-256 hex digest of a file you keep yourself). Only the digest and your descriptive claims are submitted; the file itself never leaves your machine.[null, "3", "console:lobby", "items.create", {"claims_json": "{\"name\": \"Quarterly report\", \"description\": \"Q3 financials\", \"hash\": \"ab9d...\", \"hash_type\": \"sha256\"}","watch": true}] -
Claims-as-source-of-truth mode: the claims hold neither. The claims content itself becomes the timestamped data, so the claims need a
descriptionof at least 32 characters or non-emptymetadata; a name-only submission is rejected. The total claims payload is still bounded by the team owner’s plan size budget for claims-only submissions.[null, "3", "console:lobby", "items.create", {"claims_json": "{\"name\": \"Invention disclosure\", \"description\": \"On this day I claim the following invention as my own work.\"}","watch": true}]
The payload takes no other member: one such as name, description, hash or
hash_type is refused with {"code": "invalid"} and a message saying to send
claims_json. No hash type is assumed: a hash without its hash_type inside the
claims is refused like any other half pair. When watch: true, the connection also subscribes
to the new item’s lifecycle so its state transitions arrive as stream pushes on
items.<item_id>. The reply’s watched field reports whether that auto-watch
actually took effect; the item is created either way. The reply also carries
claims_jcs, the exact canonical bytes of the claims, and claims_hash, computed
over them. The resulting item proves the submission window for its data, not a
creation time.
On a validation or authorization failure the reply is
{"status": "error", "response": {"code": ..., "message": ...}}. Claims that break a
rule answer {"code": "invalid"} with claims_reasons, one entry per broken rule,
each with its stable code (the codes the JSON:API returns, such as claims_null or
claims_number_precision), a message naming the fix, and a pointer, a JSON
pointer (RFC 6901) into the claims. A repeated member name, and a number out of range
(one no double holds, or a whole number beyond +-(2^53-1) as canonical form writes
it), point at "", since they are found as the text is read; the message joins the
entries’ messages.
Because writing is a privileged action, items.create on an OAuth connection
requires the console:write scope; without it the reply is
{"code": "insufficient_scope"}. API-key connections are not scope-limited.
Watching an item with items.watch
items.watch adds a per-item subscription after confirming your credentials can
read the item in the connection’s current team. The id is the item’s id (a
UUIDv7), its item code in either case (with at most one hyphen, underscore or space
between its groups of four), or its item_hash, read exactly as sent. If the item
does not exist or you cannot read it, or the value is a code with a typo or no item
reference at all, the reply is {"code": "forbidden"} (the cases are deliberately
indistinguishable). The reply names the item by its id, also as watching, and its
item_code. Once watching, the item’s lifecycle arrives as stream pushes on stream
id items.<item_id>, and each pushed item carries its item_code. items.unwatch
removes the watch, given the id or the item_code the watch reply named; it reads
only the connection’s own watches, never the item, so it works after the item is
deleted. If the connection is already at its per-connection stream cap, the watch is
refused with {"code": "cap_exceeded"}.
Outbound stream events
Every server-initiated resource event on console:lobby is a stream event with a
uniform envelope, so a client can route on kind without inspecting the shape of
data:
[null, null, "console:lobby", "stream", {
"stream": "blocks",
"kind": "block.created",
"at": "2026-04-27T18:32:11.412Z",
"data": { "id": "019d...", "state": "finalized", "block_hash": "61b8...", "merkle_root": "657b..." }
}]
The kind always follows <resource>.<verb>, for example block.created and
block.updated, block_healing.forward and block_healing.reverse,
beacon.created, commitment.created (on both commitment streams; the payload’s
subject_kind says whether the row binds an item, an observation or a block, and
tree_kind whether it binds it into a block or an epoch, with the epoch’s chain),
entropy.created, and item.created / item.updated / item.deleted. The data
map is a small, stable projection of the underlying resource rather than the raw
record, so its shape does not shift when internal fields change. Hash and key-id
fields are lowercase hex strings.
Burst coalescing
Every stream passes through one uniform coalescer so a fast fan-out cannot flood a client. The first event in a short window is pushed immediately, so slow streams pay no latency penalty. Further events that arrive during that window accumulate. When the window closes:
- If nothing else accumulated, nothing more is pushed.
- If exactly one further event accumulated, it is promoted to an ordinary individual push (never a burst-of-one).
- If two or more accumulated, a single
<resource>.burstsummary is pushed instead.
A burst summary carries the count, the window length, first and last timestamps, per-kind and per-state histograms, and a projection of the latest event:
[null, null, "console:lobby", "stream", {
"stream": "items.team",
"kind": "item.burst",
"at": "2026-04-27T18:32:11.500Z",
"data": {
"count": 437,
"window_ms": 500,
"first_at": "2026-04-27T18:32:11.001Z",
"last_at": "2026-04-27T18:32:11.498Z",
"by_kind": { "item.created": 250, "item.updated": 150, "item.deleted": 37 },
"by_state": { "created": 200, "processing": 150, "committed": 87 },
"latest": { "id": "019d...", "state": "committed" }
}
}]
The effect is adaptive: quiet streams like blocks, entropy.*, and
commitments.blocks never produce a burst because their events rarely arrive fast
enough to accumulate, while high-volume streams like items.team during a block
close self-throttle to at most a couple of pushes per second regardless of input
rate.
Limits and back-pressure
The surface applies several defense-in-depth caps that should never fire under normal interactive use. The stream caps are per connection; the two rate limits are per account, so opening more connections does not buy a bigger budget:
- Stream cap: a single connection can hold up to 32 active streams (catalog
streams plus per-item watches). Requests past the cap are reported in
rejected(forsubscribe) or ascap_exceeded(for a watch). - Per-call stream cap: a single
subscribeorunsubscribemay name at most 64 stream ids; a larger array is rejected asinvalid. - Command rate limit: inbound commands are rate limited per account over a short
window, shared across all of your open connections wherever they connect. Exceeding
it replies
{"code": "rate_limited"}. - Outbound rate limit: outbound stream pushes are capped per second per account, again shared across your connections; excess pushes are dropped server-side rather than delivered.
- Payload size guard: an oversized projected
datapayload is replaced with a truncation marker carrying just the id and the original byte size, so a single large record cannot breach the frame budget. - Frame size and idle memory: the socket caps an inbound message at 401,408
bytes, whether it arrives in pieces or as one frame (whose header, up to 14
bytes, counts against the cap): six times the largest claims text, 65,536 bytes,
since a JSON encoder may write any character as a
\uescape, plus 8 KiB for the message around it. The largest claims text fits however your JSON library escapes it. A larger message closes the connection. The socket also hibernates idle connections to shrink their memory footprint.
Treat the exact numbers as tuning parameters that can change; the behaviors above are the contract.
Limitations
The console WebSocket does not verify proofs or expose bulk history; it is a real-time command and subscription surface. It carries live events from the moment you subscribe and does not replay past events, so a client that reconnects must re-issue its subscriptions and treat any gap as an outage to backfill through other means. It exposes only the item write actions listed here (create, watch, unwatch, team switch); richer read and management operations belong to the JSON API and GraphQL surfaces.