Byzantine events returned from `status` endpoint
MODIFY
docs/api_specs/includes/watcher_api_specs.md
docs/api_specs/includes/watcher_api_specs.md
@@ -207,7 +207,20 @@ http POST /status
"last_validated_child_block_number": 10000,
"last_mined_child_block_timestamp": 1535031020,
"last_mined_child_block_number": 11000,
- "eth_syncing": true
+ "eth_syncing": true,
+ "byzantine_events":
+ [
+ {
+ "event": "invalid_exit",
+ "details": {
+ "eth_height" : 100,
+ "utxo_pos" : 100,
+ "owner" : "B3256026863EB6AE5B06FA396AB09069784EA8EA",
+ "currency" : "0000000000000000000000000000000000000000",
+ "amount" : 100
+ }
+ }
+ ]
}
}
```
@@ -222,4 +235,77 @@ Gets plasma network and Watcher status
No parameters are required.
+<aside class="warning">
+The most critical function of the Watcher is to monitor the ChildChain and report dishonest activity.
+The user must call the `/status` endpoint periodically to check. Any situation that requires the user to either exit or challenge an invalid exit will be included in the `byzantine_events` field.
+</aside>
+
+### Byzantine events
+All of the following events indicate a byzantine chain and that the user should either exit or challenge.
+
+#### `invalid_exit`
+
+Indicates that an invalid exit is occurring. It should be challenged.
+
+> invalid_exit
+```json
+{
+ "event": "invalid_exit",
+ "details": {
+ "eth_height" : 3521678,
+ "utxo_pos" : 12,
+ "owner" : "B3256026863EB6AE5B06FA396AB09069784EA8EA",
+ "currency" : "0000000000000000000000000000000000000000",
+ "amount" : 100
+ }
+}
+```
+
+
+#### `unchallenged_exit`
+
+Indicates that an invalid exit is dangerously close to finalization and hasn't been challenged. User should exit.
+> unchallenged_exit
+```json
+{
+ "event": "invalid_exit",
+ "details": {
+ "eth_height" : 3521678,
+ "utxo_pos" : 12,
+ "owner" : "B3256026863EB6AE5B06FA396AB09069784EA8EA",
+ "currency" : "0000000000000000000000000000000000000000",
+ "amount" : 100
+ }
+}
+```
+
+#### `invalid_block`
+
+A block containing an invalid tx has been processed [are there other reasons a block can be invalid?]. User should exit.
+
+> invalid_block
+```json
+{
+ "event": "invalid_exit",
+ "details": {
+ "blockhash" : "DB32876CC6F26E96B9291682F3AF4A04C2AA2269747839F14F1A8C529CF90225",
+ "blocknum" : 10000,
+ }
+}
+```
+
+#### `block_withholding`
+
+The ChildChain is withholding a block whose hash has been published on the root chain. User should exit.
+
+> block_withholding
+```json
+{
+ "event": "invalid_exit",
+ "details": {
+ "blockhash" : "DB32876CC6F26E96B9291682F3AF4A04C2AA2269747839F14F1A8C529CF90225",
+ "blocknum" : 10000,
+ }
+}
+```

MODIFY
docs/api_specs/includes/watcher_websocket_specs.md
docs/api_specs/includes/watcher_websocket_specs.md
# Watcher - Events
-The most critical function of the Watcher is to monitor the ChildChain and report any dishonest activity.
<aside class="warning">TODO Explanation of the WebSocket/ Phoenix Channels mechanism used to receive events</aside>
-## Topic `byzantine`
-All of the following events indicate a byzantine chain and that the user should either exit or challenge.
-
-### Event `block_withholding`
-
-Event informing that child chain is withholding block which hash was published on root chain.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-blknum | Integer | Number of plasma block
-
-
-### Event `invalid_block`
-
-Event informing that a particular block is invalid.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-hash | HEX-encoded string | Hash of plasma block
-number | Integer | Number of plasma block
-error_type | String |
-
-
-### Event `invalid_exit`
-
-Event informing that invalid exit has started
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-### Event `unchallenged_exit`
-
-Notifies about an invalid exit, that is dangerously approaching finalization, without being challenged.
-It is a prompt to exit.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-### Event `invalid_in_flight_exit`
-
-Event informing of an invalid in-flight exit, a kmown competitor should be provided.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-### Event `invalid_in_flight_challenge`
-
-Event informing of an invalid in-flight challenge, proof of canonicity should be provided.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-### Event `piggyback_required`
-
-Event informing that a piggyback on an in-flight exit is required
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-### Event `invalid_piggyback`
-
-Event informing of an invalid piggyback. It should be challenged.
-
-> Event type have following structure.
-
-Key | Type | Description
---------- | ------- | -----------
-amount | Integer |
-currency | HEX-encoded string |
-owner | HEX-encoded string |
-utxo_pos | Integer |
-eth_height | Integer |
-
-
-
## Topic `transfer:{address}`
### Events `address_received` and `address_spent`

Byzantine events returned from `status` endpoint