diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 4ffa694cd..01613f9fd 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,6 +2,7 @@ * [Introduction](./intro.md) * [Development Environment](./setup.md) +* [Websocket Interface](./websockets.md) * [Simple Local Testnet](./simple-testnet.md) * [Interop](./interop.md) * [Environment](./interop-environment.md) diff --git a/book/src/websockets.md b/book/src/websockets.md new file mode 100644 index 000000000..2b91bd88f --- /dev/null +++ b/book/src/websockets.md @@ -0,0 +1,108 @@ +# Websocket Interface + +By default, a Lighthouse `beacon_node` exposes a websocket server on `localhost:5053`. + +The following CLI flags control the websocket server: + +- `--no-ws`: disable the websocket server. +- `--ws-port`: specify the listen port of the server. +- `--ws-address`: specify the listen address of the server. + +All clients connected to the websocket server will receive the same stream of events, all triggered +by the `BeaconChain`. Each event is a JSON object with the following schema: + +```json +{ + "event": "string", + "data": "object" +} +``` + +## Events + +The following events may be emitted: + +### Beacon Head Changed + +Occurs whenever the canonical head of the beacon chain changes. + +```json +{ + "event": "beacon_head_changed", + "data": { + "reorg": "boolean", + "current_head_beacon_block_root": "string", + "previous_head_beacon_block_root": "string" + } +} +``` + +### Beacon Finalization + +Occurs whenever the finalized checkpoint of the canonical head changes. + +```json +{ + "event": "beacon_finalization", + "data": { + "epoch": "number", + "root": "string" + } +} +``` + +### Beacon Block Imported + +Occurs whenever the beacon node imports a valid block. + +```json +{ + "event": "beacon_block_imported", + "data": { + "block": "object" + } +} +``` + +### Beacon Block Rejected + +Occurs whenever the beacon node rejects a block because it is invalid or an +error occurred during validation. + +```json +{ + "event": "beacon_block_rejected", + "data": { + "reason": "string", + "block": "object" + } +} +``` + +### Beacon Attestation Imported + +Occurs whenever the beacon node imports a valid attestation. + +```json +{ + "event": "beacon_attestation_imported", + "data": { + "attestation": "object" + } +} +``` + +### Beacon Attestation Rejected + +Occurs whenever the beacon node rejects an attestation because it is invalid or +an error occurred during validation. + +```json +{ + "event": "beacon_attestation_rejected", + "data": { + "reason": "string", + "attestation": "object" + } +} +```