Enclave is now The Interfold.
Reference
Dashboard API

Dashboard API

This page describes the JSON API of the local node dashboard. It is for operators who connect a monitoring system or a script to a ciphernode. It lists each endpoint, its query parameters, its response fields, and its errors. To enable the dashboard and open it in a browser, see Node Dashboard.

The source of truth is crates/diagnostics/dashboard/src. An OpenAPI 3.1 description of the same API is at /dashboard-openapi.yaml. You can load this file into OpenAPI tools, for example Swagger UI, or use it to generate a client.

Base URL and access

The node serves the API only when the configuration sets dashboard_port. The base URL is:

http://127.0.0.1:<dashboard_port>

The server binds only to 127.0.0.1. It has no authentication. All endpoints use GET and return JSON. The server can compress a response when the client asks for it.

⚠️

The API returns detailed protocol payloads and node diagnostics. Run the monitoring client on the host of the node, or connect through an SSH tunnel. Do not forward the port to a public interface.

A path that is not an endpoint returns the dashboard HTML page with HTTP 200. A monitoring check must parse the body as JSON. A check of the status code only does not find a wrong path.

Value formats

  • Large on-chain integers are decimal strings. These include bonds, balances, ticket counts, reward amounts, and scores. Convert them before you compare them with a number.
  • A field name that ends in _ms is a Unix time in milliseconds. A field name that ends in _us is a Unix time in microseconds.
  • The response does not include an optional field that has no value. For each field, the tables on this page say if the field can be absent.

Endpoints

EndpointQuery parametersResponseErrors
GET /api/snapshotNoneSnapshot503
GET /api/e3e3_id (required)E3 trace400, 404, 503
GET /api/eventslimit{ "events": [Event, ...] }400, 503
GET /api/logssince, limit, level, target, textLog query result400
GET /api/updatesNoneUpdate statusNone

An error response has this body:

{ "error": "EventStore dashboard query timed out" }
StatusEndpointsCause
400/api/e3, /api/events, /api/logsA required parameter is missing, or a parameter is not a valid number. The body is plain text.
404/api/e3The node has no events for this E3. The error field is unknown E3 <id>.
503/api/snapshot, /api/e3, /api/eventsThe EventStore query failed, or it did not answer in 5 s.

Snapshot

GET /api/snapshot returns the data of the Overview view.

Before it answers, the endpoint reads the new EventStore events of the node. It also reads the operator state from the chain. The node keeps the chain result for 15 s, so a poll interval of 30 to 60 s is sufficient for monitoring.

curl -s http://127.0.0.1:9092/api/snapshot | jq '.network.connected_peers | length'
FieldTypeDescription
nodeNodeIdentity, ports, version, and chains of the node
networkNetworkLive libp2p connection state
protocolProtocolE3 counts and chain state from the EventStore
operatorOperatorOperator state from live chain reads
e3sE3 summary[]Each E3 that the node saw. The most recently active E3 is first.
recent_eventsEvent[]The 40 newest protocol events. The newest event is first.

Node

FieldTypeDescription
node_namestringName of the node
addressstringOperator address
peer_idstringlibp2p peer ID
quic_portintegerQUIC port
dashboard_portintegerDashboard port
versionstringVersion of the interfold binary
chainsarrayOne { "id": <chain ID>, "name": <string> } item for each chain

Network

This data is live connection state. The node does not keep it in the EventStore. The Network reach value on the Overview is the length of connected_peers over configured_peers.

FieldTypeDescription
configured_peersintegerNumber of configured peers
connected_peersarrayOne item for each connected peer. See the next table.
gossip_subscribed_peersintegerNumber of peers that subscribe to the protocol gossip topic
listen_addressesstring[]Multiaddrs that the node listens on
last_errorstringThe latest transport error. Absent when there is no error.

Each item in connected_peers has these fields:

FieldTypeDescription
peer_idstringlibp2p peer ID
remote_addressstringMultiaddr of the peer
directionstringinbound or outbound
connectionsintegerNumber of open connections
connected_at_msintegerTime of the first connection

Protocol

The node calculates these values from its own EventStore events.

FieldTypeDescription
chainsarrayChain state for each chain. See the next table.
e3_totalintegerNumber of E3s that the node saw
e3_activeintegerE3s that still need this node. See the note below the table.
e3_completedintegerE3s with status complete
e3_failedintegerE3s with status failed
e3_degradedintegerE3s with status degraded
events_observedintegerNumber of protocol events in the dashboard projection

e3_active counts the E3s where this node is in the committee, or has a ticket before the committee forms. Of these E3s, it counts each E3 with status active or degraded. It also counts each E3 with status failed for 24 hours after the failure, because slash reports for the E3 can still be due. The 24 hours is an estimate.

Each item in chains has these fields:

FieldTypeDescription
chain_idintegerChain ID
registered_nodesintegerRegistered nodes, from events
active_nodesintegerActive nodes, from events
operator_registeredbooleanThe operator is registered
operator_activebooleanThe operator is active
ticket_balancestringTicket balance. Can be absent.
ciphernode_bondstringCiphernode bond. Can be absent.
bond_ownerstringBond owner address. Can be absent.
exit_unlock_atintegerTime when the exit unlocks. Can be absent.
rewards_creditedReward[]Rewards credited to the operator

Operator

The node reads these values from the chain with RPC calls. It keeps the result for 15 s.

FieldTypeDescription
chainsarrayOne item for each enabled chain with a successful read. See the next table.
errorstringThe failed reads, separated by ; . For example, sepolia: RPC query timed out. Absent when all reads succeed.
updated_at_msintegerTime of the last read. The value is 0 before the first read.

Each item in chains has these fields:

FieldTypeDescription
chain_idintegerChain ID
chain_namestringChain name from the configuration
registered_nodesstringRegistered nodes, as a decimal string
active_nodesstringActive nodes, as a decimal string
operator_registeredbooleanThe operator is registered
operator_activebooleanThe operator is active
operator_eligibleboolean or nullThe result of BondingRegistry.eligibilityAt. It includes the admission cooldown and the admission policy. null when the read fails.
exit_in_progressbooleanThe operator has an exit in the queue
ticket_balancestringTicket balance
available_ticketsstringAvailable tickets
ciphernode_bondstringCiphernode bond
bond_ownerstringBond owner address

E3 trace

GET /api/e3?e3_id=<id> returns the trace of one E3. Use an e3_id value from the snapshot.

The response has all the fields of an E3 summary, and these fields:

FieldTypeDescription
phasesarrayOne item for each phase. See the next table.
committeearray{ address, party_id, score?, expelled } for each committee member
ticketsarray{ node, ticket_id, score } for each sortition ticket
rewardsReward[]Rewards of the E3
reward_allocationsarray{ operator, amount } for each allocation
failureobjectFailure details. Absent when the E3 did not fail.
local_failureobjectFailure that this node reported. Can be absent.
chain_failureobjectFailure that the chain reported. Can be absent.
eventsEvent[]The events of the E3

Each item in phases has these fields:

FieldTypeDescription
idstringPhase. See E3 summary.
labelstringDisplay name, for example DKG · C0
statestringpending, active, complete, failed, or stalled
event_countintegerNumber of events in the phase
sourcesobject{ local, net, evm }: the number of events from each source
errorsintegerNumber of events with the error level
warningsintegerNumber of events with the warn level

A phase has the state stalled when this node reported a local failure in that phase.

E3 summary

FieldTypeDescription
e3_idstringE3 ID
chain_idintegerChain ID
statusstringactive, complete, failed, or degraded
canonical_stagestringStage on the chain: None, Requested, CommitteeFinalized, KeyPublished, CiphertextReady, Complete, or Failed. Can be absent.
current_phasestringrequest, committee, dkg_setup, dkg_shares, key_publication, computation, decryption, or settlement
event_countintegerNumber of events
error_countintegerNumber of events with the error level
warning_countintegerNumber of events with the warn level
committee_sizeintegerNumber of committee members
first_seen_usintegerTime of the first event
last_seen_usintegerTime of the latest event

The status is failed when the chain reports a failure. The status is degraded when this node reports a local failure and the chain does not.

Reward

FieldTypeDescription
accountstringAccount that gets the reward
tokenstringToken address. Can be absent.
amountstringAmount in token base units
claimedbooleanThe reward is claimed

Events

GET /api/events?limit=<n> returns { "events": [...] } with the newest protocol events. The newest event is first. The default limit is 500. The node uses 2,000 for a larger value.

Event

FieldTypeDescription
seqintegerSequence number in the EventStore aggregate
aggregate_idintegerEventStore aggregate
timestamp_usintegerEvent time
logical_counterintegerLogical counter of the hybrid logical clock
producer_fingerprintstringNode ID of the hybrid logical clock, in hexadecimal
blockintegerBlock number. Chain events have it. Can be absent.
sourcestringlocal, network, or evm
producerstringLocal events: the operator address. Chain events: the contract address, or on-chain contract. Network events: node:<producer_fingerprint>.
event_typestringEvent name, for example E3Requested
e3_idstringE3 ID. Can be absent.
phasestringE3 phase. Can be absent.
severitystringdebug, info, warn, or error
event_idstringEvent ID
causation_idstringID of the event that caused this event
origin_idstringID of the root event that caused this event
payloadanyEvent data. The structure depends on event_type.

The net key in the sources object of a phase counts the events with the source network. Node Dashboard lists the events of each severity level.

Logs

GET /api/logs returns operational log entries. The node keeps the 20,000 newest entries in memory. These entries are diagnostics, not protocol records.

ParameterDefaultDescription
sinceNoneReturn entries with seq equal to or larger than this value
limit500Maximum number of entries. The node uses a value from 1 to 2,000.
levelNoneExact level, for example error. The match ignores case. This is not a minimum level: warn does not return error entries.
targetNoneText that the tracing target contains. The match is case-sensitive.
textNoneText that the message, the target, or the fields contain. The match ignores case.

Without since, the response contains the newest matching entries. With since, the response contains the oldest matching entries from that point. In both cases, the entries are in order from oldest to newest. To read new entries in a loop, send the next_cursor value as since in the next request.

FieldTypeDescription
entriesarrayLog entries. See the next table.
next_cursorintegerThe since value for the next request
oldest_cursorintegerSequence number of the oldest entry in memory
total_storedintegerNumber of entries in memory
FieldTypeDescription
seqintegerSequence number
timestamp_msintegerEntry time
levelstringERROR, WARN, INFO, DEBUG, or TRACE
targetstringTracing target, for example a module path
messagestringLog message
nodestringNode name
fieldsobjectStructured fields. Absent when there are none.

When the log collector does not run, the endpoint returns no entries, and each cursor is 0.

Updates

GET /api/updates compares the installed version with the latest stable GitHub release. The node keeps a successful result for 1 hour and a failed result for 5 minutes. The endpoint always returns HTTP 200. A failed check sets error.

FieldTypeDescription
current_versionstringInstalled version
latestobject or null{ tag, name, url, published_at, notes }. null before the first successful check.
update_availablebooleanThe latest release is newer than the installed version
releases_urlstringURL of the GitHub releases page
checked_at_msintegerTime of the last check
errorstringReason of the last failed check. Absent after a successful check.

Next steps