Docs Reference
Event stream
The Acrux Net WebSocket stream. Every protocol event of every slot as it happens, its envelope, its time anchors, filters and resuming.
The gateway streams every protocol event over a WebSocket: each slice a proposer sends, each commitment and its arrival, each attestation and its key, the agreed set, the merge, the schedule, the execution, every vote and certificate, and every transaction update. /net is drawn from this stream alone.
| Local | |
|---|---|
| WebSocket | ws://127.0.0.1:4931 |
Connecting
import { createGatewayClient, type ProtocolEvent } from '@acrux/contract'
const net = createGatewayClient({ rpcUrl: 'http://127.0.0.1:4930', wsUrl: 'ws://127.0.0.1:4931' })
const sub = net.subscribe({ kind: 'all' }, (event: ProtocolEvent) => {
if (event.type === 'slot.executed') console.log(event.slot, event.data.stateHash)
})
// later
sub.close()const ws = new WebSocket('ws://127.0.0.1:4931')
ws.onopen = () => ws.send(JSON.stringify({ version: 1, type: 'subscribe', filter: { kind: 'all' } }))
ws.onmessage = ({ data }) => {
const event = JSON.parse(data)
// switch on event.type
}On connecting, the gateway sends a stream.snapshot with the complete current view. Every subscribe is answered with a stream.resync carrying a fresh snapshot, or with the retained events after the cursor you name. On any stream.resync, replace your local state with its snapshot.
Commands
A client sends JSON commands on the socket.
| Command | Effect |
|---|---|
{ "version": 1, "type": "subscribe", "filter": … } | start delivery for filter; replaces any earlier filter |
{ "version": 1, "type": "subscribe", "filter": …, "afterSequence": n, "streamId": "…" } | resume: deliver the retained events after sequence n of stream streamId |
{ "version": 1, "type": "unsubscribe" } | stop delivery |
Filters
| Filter | Delivers |
|---|---|
{ "kind": "all" } | every event |
{ "kind": "slots", "from": a, "to": b } | every event whose slot is from a to b inclusive; from must not exceed to |
{ "kind": "transaction", "id": "…" } | transaction.updated for that ID, and the slot.started, block.decrypted, slot.merged, slot.executed and lab.evidence events that contain it |
stream.* events reach every subscriber whatever its filter.
Envelope
Every event has the same envelope:
| Field | Type | Meaning |
|---|---|---|
version | 1 | envelope version |
node | string, optional | the identity of the node that emitted the event, where one node did |
sequence | integer | position in the stream, increasing by one per event within a streamId |
streamId | string | the stream instance; a new streamId means earlier sequences no longer apply |
type | string | the event type, below |
slot | integer or null | the slot the event belongs to; null for stream and window control events |
anchor | "slot", "window", "consensus", "stream" | what atUs is measured from |
atUs | integer | microseconds after the anchor |
data | object | the event's payload, by type |
Time anchors
Times are never wall-clock timestamps; each is microseconds after a protocol event. Each slot carries one UTC wallTime.
anchor | atUs measures from | Used by |
|---|---|---|
slot | the start of the slot | slices, commitments, attestations, merge, execution |
window | the window's ParentReady | window events; Slot.attestationDeadlineUs, Slot.consensusTimeoutUs |
consensus | the first slot of the cblock | votes, certificates, Cblock.finalizedUs |
stream | the start of the stream or replay | stream control |
CommitmentArrival.relativeToStartUs is measured from the receiving proposer's own start[s], the earlier of its own send and the first commitment it received (Hash exchange).
Events
In the order they occur within a slot. Each data type links to its fields.
type | data | Meaning |
|---|---|---|
stream.snapshot | NetSnapshot | first message on connect: the complete current view |
stream.resync | reason: "connected", "cursor_expired", "restarted", "filter_changed"; snapshot: NetSnapshot | replace local state with snapshot; sent on subscribe, an expired cursor, a restart or a new filter |
stream.heartbeat | latestSlot: integer; status: "live", "stalled", "unavailable" | the latest slot and the net's status |
stream.error | ApiError | the stream failed; the error envelope |
window.started | Window | a window started: its hub, slots, consensus slots and proposers |
slot.started | Slot | a slot started, still pending |
block.slice | proposer: proposer index; slice: Slice | a proposer sent a slice: 64 shreds, any 32 rebuild it |
commitment.sent | Commitment | a proposer sent its signed commitment with its last slice |
commitment.arrived | proposer: proposer index; hash: string; arrival: CommitmentArrival | a commitment reached a co-proposer, on time or late |
attestation.sent | Attestation | a proposer sent its attestation and released its key |
attestation.arrived | attestation: Attestation; validator: string; arrivedUs: integer | an attestation reached a validator |
slot.agreed | agreedSet: array of proposer index | the slot is agreed on the set P |
slot.skipped | Skip | the slot will not be executed: the reason and the evidence |
block.decrypted | proposer: proposer index; transactionIds: hash[] | a block of P was decrypted: the transactions it carried |
slot.merged | transactions: MergedTransaction[] | the slot's transactions in their one order |
slot.scheduled | ExecutionSchedule | Algorithm 4's placement on the four tracks, with the gaps |
slot.executed | Slot | the slot executed: the complete slot with its state hash |
cblock.assembled | Cblock | four xblocks, the parent and the state hash form a cblock |
cblock.vote | Vote | a validator voted on a cblock |
cblock.certificate | Certificate | votes reached a threshold: notarization, notar-fallback, fast or slow finalization, or skip |
cblock.finalized | Cblock | a cblock is final |
transaction.updated | Transaction | a transaction's trail changed |
net.counters | Counters | the net's counters |
lab.updated | LabRun | a Fault Lab run changed status |
lab.evidence | Evidence | a Fault Lab run recorded evidence |
Order within one slot
For one slot of a window with three correct proposers, a subscriber sees:
slot.startedblock.slicefor each slice of each of the three blocks, interleaved as they streamcommitment.sentfrom each proposer with its last slice, thencommitment.arrivedat each co-proposerattestation.sentfrom each proposer once its exchange closes, thenattestation.arrivedat validatorsslot.agreedwith the agreed set, orslot.skippedwith the reasonblock.decryptedfor each block of the agreed setslot.merged, thenslot.scheduled, thenslot.executed- after the fourth slot of a cblock:
cblock.assembled,cblock.voteevents,cblock.certificate,cblock.finalized
Slots are pipelined: the next slot's slices stream while the previous slot is merged and executed, so events of neighbouring slots interleave. Order by slot and sequence.
Retention and resuming
The gateway keeps the most recent 24,000 events and 5,000 transaction records. To resume after a disconnect, subscribe with the last sequence and streamId you processed; if the cursor is still retained you receive the events after it, otherwise a stream.resync with a fresh snapshot: reason restarted when the streamId is no longer the gateway's, filter_changed otherwise. A client that falls behind the live stream gets a stream.resync with reason cursor_expired. For the last 64 slots at rest, call getRecentSlots.
stream.heartbeat reports the latest slot and the net's status: live, stalled when slots have stopped arriving, or unavailable. The gateway closes connections that stop reading.
Fault Lab streams
A Fault Lab run's events use the same envelope and types. They are served recorded, as JSON at GET /v1/lab/runs/{id}/events and as server-sent events at GET /v1/lab/runs/{id}/stream.