Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

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_token query parameter, mirroring the api_key mechanism. An Authorization: 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 the console:read scope to open the socket at all; the console:write scope 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 public item, and a team item 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 private item never reaches a team member or viewer: not its claims, its item_hash or 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 hash and hash_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 description of at least 32 characters or non-empty metadata; 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>.burst summary 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 (for subscribe) or as cap_exceeded (for a watch).
  • Per-call stream cap: a single subscribe or unsubscribe may name at most 64 stream ids; a larger array is rejected as invalid.
  • 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 data payload 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 \u escape, 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.