NETSoon

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
WebSocketws://127.0.0.1:4931

Connecting

ts
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()

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.

CommandEffect
{ "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

FilterDelivers
{ "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:

FieldTypeMeaning
version1envelope version
nodestring, optionalthe identity of the node that emitted the event, where one node did
sequenceintegerposition in the stream, increasing by one per event within a streamId
streamIdstringthe stream instance; a new streamId means earlier sequences no longer apply
typestringthe event type, below
slotinteger or nullthe slot the event belongs to; null for stream and window control events
anchor"slot", "window", "consensus", "stream"what atUs is measured from
atUsintegermicroseconds after the anchor
dataobjectthe 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.

anchoratUs measures fromUsed by
slotthe start of the slotslices, commitments, attestations, merge, execution
windowthe window's ParentReadywindow events; Slot.attestationDeadlineUs, Slot.consensusTimeoutUs
consensusthe first slot of the cblockvotes, certificates, Cblock.finalizedUs
streamthe start of the stream or replaystream 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.

typedataMeaning
stream.snapshotNetSnapshotfirst message on connect: the complete current view
stream.resyncreason: "connected", "cursor_expired", "restarted", "filter_changed"; snapshot: NetSnapshotreplace local state with snapshot; sent on subscribe, an expired cursor, a restart or a new filter
stream.heartbeatlatestSlot: integer; status: "live", "stalled", "unavailable"the latest slot and the net's status
stream.errorApiErrorthe stream failed; the error envelope
window.startedWindowa window started: its hub, slots, consensus slots and proposers
slot.startedSlota slot started, still pending
block.sliceproposer: proposer index; slice: Slicea proposer sent a slice: 64 shreds, any 32 rebuild it
commitment.sentCommitmenta proposer sent its signed commitment with its last slice
commitment.arrivedproposer: proposer index; hash: string; arrival: CommitmentArrivala commitment reached a co-proposer, on time or late
attestation.sentAttestationa proposer sent its attestation and released its key
attestation.arrivedattestation: Attestation; validator: string; arrivedUs: integeran attestation reached a validator
slot.agreedagreedSet: array of proposer indexthe slot is agreed on the set P
slot.skippedSkipthe slot will not be executed: the reason and the evidence
block.decryptedproposer: proposer index; transactionIds: hash[]a block of P was decrypted: the transactions it carried
slot.mergedtransactions: MergedTransaction[]the slot's transactions in their one order
slot.scheduledExecutionScheduleAlgorithm 4's placement on the four tracks, with the gaps
slot.executedSlotthe slot executed: the complete slot with its state hash
cblock.assembledCblockfour xblocks, the parent and the state hash form a cblock
cblock.voteVotea validator voted on a cblock
cblock.certificateCertificatevotes reached a threshold: notarization, notar-fallback, fast or slow finalization, or skip
cblock.finalizedCblocka cblock is final
transaction.updatedTransactiona transaction's trail changed
net.countersCountersthe net's counters
lab.updatedLabRuna Fault Lab run changed status
lab.evidenceEvidencea Fault Lab run recorded evidence

Order within one slot

For one slot of a window with three correct proposers, a subscriber sees:

  1. slot.started
  2. block.slice for each slice of each of the three blocks, interleaved as they stream
  3. commitment.sent from each proposer with its last slice, then commitment.arrived at each co-proposer
  4. attestation.sent from each proposer once its exchange closes, then attestation.arrived at validators
  5. slot.agreed with the agreed set, or slot.skipped with the reason
  6. block.decrypted for each block of the agreed set
  7. slot.merged, then slot.scheduled, then slot.executed
  8. after the fourth slot of a cblock: cblock.assembled, cblock.vote events, 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.