message: Clarifying `finalization - sla_margin` everywhere

diff:
@@ -6,7 +6,7 @@ This document describes the exit validation (processing) done by the Watcher in
NOTE:
* `eth_exit_finality_margin` margin exit processor (in Ethereum blocks)
* `SLA` Service Level Agreement
-* `sla_margin` margin of service lever agreement validation (in Ethereum blocks)
+* `sla_margin` margin of service level agreement validation (in Ethereum blocks). This is a number of blocks prior to finalization, indicating a period of time that can affect the validity of an exit.
## Notes on the Child Chain Server
@@ -22,7 +22,7 @@ The Child Chain will become invalid if any invalid exit gets finalized.
- the Child Chain server listens to every `InFlightExitPiggybacked` Root Chain event (on outputs) and immediately "spends" the piggybacked outputs - as long as the IFEing tx has been included in the chain and the output exists
There are scenarios, when a race condition/reorg on the root chain might make the Child Chain Server block spending of a particular UTXO **too late**, regardless of the immediacy mentioned above.
-This is acceptable as long as the delay doesn't exceed a predetermined `sla_margin`.
+This is acceptable as long as the delay doesn't exceed `scheduled finalization time` minus the predetermined `sla_margin`.
## Standard Exits
@@ -36,15 +36,15 @@ This is acceptable as long as the delay doesn't exceed a predetermined `sla_marg
### Actions that the Watcher should prompt:
1. If an exit is known to be invalid it should be challenged (almost) immediately
-2. If an exit is invalidated with a transaction submitted within an acceptable `sla_margin` period it must be challenged
-3. If an exit is invalidated with a transaction submitted after an acceptable `sla_margin` period it must be challenged **AND** watcher must prompt an exit **AND** watcher must not allow spending and depositing
+2. If an exit is invalidated with a transaction submitted *before* `finalization - sla_margin`it must be challenged
+3. If an exit is invalidated with a transaction submitted *after* `finalization - sla_margin` it must be challenged **AND** watcher must prompt an exit **AND** watcher must not allow spending and depositing
- because our child chain implementation will never get close to this happening, so it is a symptom of a (subtle) hack attempt on the child chain server.
By "subtle" we mean that it is a hack that counts on getting away with exit invalidation being submitted too late, rather than on just dropping a huge invalid UTXO and attempting to exit from that
-3. If an exit is invalid and remains unchallenged within a short period of time from its finalization, it must be challenged **AND** watcher must not allow spending and depositing, because:
+4. If an exit is invalid and remains unchallenged within a short period of time (`sla_margin`) from its finalization, it must be challenged **AND** watcher must not allow spending and depositing, because:
a. we are running too close to the minimum safety requirements
b. unchallenged exits may break the chain without leaving honest holders with enough time to exit.
This can happen when an exit, a spend that invalidates that exit and an exit of that invalidating spend all coincide and are unchallenged.
-4. (optional) If finalization of an invalid exit occurs, the watcher must prompt an exit without guarantees of recovery of funds
+5. (optional) If finalization of an invalid exit occurs, the watcher must prompt an exit without guarantees of recovery of funds
Conditions 3 and 4 can be represented jointly, by **continuous** (every child block) validation of the exits.
If any exit is invalid and its finalization is near, then actions listed under 3 and 4 should take place.
@@ -54,22 +54,22 @@ All that takes as an assumption that:
- the user needs to have the ability to spend their UTXOs at any time, thereby requiring more stringent validity checking of exits
### Example cases for above actions:
-1. The exit is processed *after* the tx that invalidates it, so it is known to be invalid from the start. Should emit an `:invalid_exit` event.
-2. The exit is processed *before* the tx that invalidates it and the tx is within `sla_margin` period, so the child chain is still valid.
+1. The exit is processed *after* the tx that invalidates it, so it is known to be invalid from the start. Causes an `:invalid_exit` event.
+2. The exit is processed *before* the tx that invalidates it and the tx occurs *before* `finalization - sla_margin`, so the child chain is still valid.
Causes an `:invalid_exit` event.
-3. The exit is processed *before* the tx that invalidates it, but the tx occurs *after* `sla_margin` period, so the child chain is byzantine.
-Causes to emit an `:unchallenged_exit` event.
-3. An invalid exit is still unchallenged after `sla_margin` period, so the child chain is jeopardized.
-Causes to emit an `:unchallenged_exit` event.
-4. (optional) Continuation of cases (1) or (2) where the exit never gets challenged and finalizes.
-Causes to emit an `:invalid_finalization` event
+3. The exit is processed *before* the tx that invalidates it, but the tx occurs *after* `finalization - sla_margin`, so the child chain is byzantine.
+Causes an `:unchallenged_exit` event.
+4. An invalid exit is still unchallenged after `finalization - sla_margin`, so the child chain is jeopardized.
+Causes an `:unchallenged_exit` event.
+5. (optional) Continuation of cases (1) or (2) where the exit never gets challenged and finalizes.
+Causes an `:invalid_finalization` event.
### Solution for above cases:
2. `ExitProcessor` pulls open exit requests from root chain contract logs, as soon as they're `eth_exit_finality_margin` blocks old (~12 blocks)
3. For every open exit request run `State.utxo_exists?` method
* if `true` -> noop,
* if `false` -> emit `:invalid_exit` event which leads to challenge
- * if `false` and there is less than `sla_margin` time till finalization -> `:unchallenged_exit`
+ * if `false` and there is less than `sla_margin` time until finalization -> `:unchallenged_exit`
4. Spend utxos in `State` on exit finalization or challenging
5. `ExitProcessor` recognizes exits that are (as seen at the tip of the root chain) already gone, when pulled from old logs.
This prevents spurious event raising during syncing.


message: Add some missing words and commas

change_type: MODIFY

diff:
@@ -142,11 +142,11 @@ This flow is about the user piggybacking (or not), challenging IFEs and respondi
#### new IFEs, competitors, piggybacks
-Any `InFlightExitStarted` should, after `eth_exit_finality_margin` cause the IFE to be tracked and tx added to something called `TxAppendix`.
+Any `InFlightExitStarted` should, after `eth_exit_finality_margin`, cause the IFE to be tracked and tx added to something called `TxAppendix`.
-Any competitor published should `eth_exit_finality_margin`, be tracked and tx added to `TxAppendix`
+Any competitor published should, after `eth_exit_finality_margin`, be tracked and tx added to `TxAppendix`
-Any piggyback done should `eth_exit_finality_margin`, be taken into account.
+Any piggyback done should, after `eth_exit_finality_margin`, be taken into account.
#### finalization

license: Apache License 2.0

repo: omgnetwork/elixir-omg

original_message: Add some missing words and commas


message: Fix link to MoreVP.md doc

diff:
@@ -108,7 +108,7 @@ Absence of challenges within some period (like `sla_margin`) must result in clie
## In-flight exits
-With MoreVP, we need to handle another type of exit game, which is the in-flight exit game, as specced out [here](docs/morevp.md).
+With MoreVP, we need to handle another type of exit game, which is the in-flight exit game, as specced out [here](morevp.md).
In terms of handling within the Watcher, similar principles will apply:
- we gather and keep in `OMG.Watcher.ExitProcessor`'s persistent state the current state of in-flight txs and exits

original_message: Fix link to MoreVP.md doc


message: Add MoreVP byzantine events

diff:
@@ -267,7 +267,7 @@ Indicates that an invalid exit is occurring. It should be challenged.
```json
{
- "event": "invalid_exit",
+ "event": "unchallenged_exit",
"details": {
"eth_height" : 3521678,
"utxo_pos" : 12,
@@ -286,7 +286,7 @@ Indicates that an invalid exit is dangerously close to finalization and hasn't b
```json
{
- "event": "invalid_exit",
+ "event": "invalid_block",
"details": {
"blockhash" : "DB32876CC6F26E96B9291682F3AF4A04C2AA2269747839F14F1A8C529CF90225",
"blocknum" : 10000,
@@ -302,7 +302,7 @@ A block containing an invalid tx has been processed [are there other reasons a b
```json
{
- "event": "invalid_exit",
+ "event": "block_withholding",
"details": {
"blockhash" : "DB32876CC6F26E96B9291682F3AF4A04C2AA2269747839F14F1A8C529CF90225",
"blocknum" : 10000,
@@ -312,3 +312,110 @@ A block containing an invalid tx has been processed [are there other reasons a b
The ChildChain is withholding a block whose hash has been published on the root chain. User should exit.
+#### `noncanonical_ife`
+> A noncanonical_ife event
+
+```json
+{
+ "event": "noncanonical_ife",
+ "details": {
+ "inflight_blocknum" : 10000,
+ "inflight_tx_index" : 12,
+ "inflight_input_index" : 1,
+ "competing_blocknum" : 10000,
+ "competing_tx_index" : 10,
+ "competing_input_index" : 0,
+ }
+}
+```
+
+An non-canonical in-flight exit has been started. It should be challenged.
+<aside class="warning"> Not Implemented Yet.</aside>
+
+Event details:
+Key | Type | Description
+--------- | ------- | -----------
+inflight_blocknum | integer | Block number of the in-flight transaction
+inflight_tx_index | integer | Index of the in-flight transaction
+inflight_input_index | integer | Index of the double-spent input in the in-flight transaction
+competing_blocknum | integer | Block number of the spending transaction
+competing_tx_index | integer | Index of the spending transaction
+competing_input_index | integer | Index of the double-spent input in the competing transaction
+
+#### `invalid_ife_challenge`
+> A invalid_ife_challenge event
+
+```json
+{
+ "event": "invalid_ife_challenge",
+ "details": {
+ "inflight_blocknum" : 10000,
+ "inflight_tx_index" : 12,
+ }
+}
+```
+
+A canonical in-flight exit has been challenged. The challenge should be responded to.
+<aside class="warning"> Not Implemented Yet.</aside>
+
+Event details:
+Key | Type | Description
+--------- | ------- | -----------
+inflight_blocknum | integer | Block number of the in-flight transaction
+inflight_tx_index | integer | Index of the in-flight transaction
+
+#### `piggyback_available`
+> A piggyback_available event
+
+```json
+{
+ "event": "piggyback_available",
+ "details": {
+ "inflight_blocknum" : 10000,
+ "inflight_tx_index" : 12,
+ "inflight_io_index" : 1
+ }
+}
+```
+
+An in-flight exit has been started and can be piggybacked
+<aside class="warning"> Not Implemented Yet.</aside>
+
+Event details:
+Key | Type | Description
+--------- | ------- | -----------
+inflight_blocknum | integer | Block number of the in-flight transaction
+inflight_tx_index | integer | Index of the in-flight transaction
+inflight_io_index | integer | Index of the input or output that can be exitted.
+
+#### `invalid_piggyback`
+> A invalid_piggyback event
+
+```json
+{
+ "event": "invalid_piggyback",
+ "details": {
+ "type": "output",
+ "inflight_blocknum" : 10000,
+ "inflight_tx_index" : 12,
+ "inflight_io_index" : 1,
+ "spending_blocknum" : 10000,
+ "spending_tx_index" : 10,
+ "spending_input_index" : 0,
+ }
+}
+```
+
+An invalid piggyback is in process. Should be challenged.
+<aside class="warning"> Not Implemented Yet.</aside>
+
+Event details:
+Key | Type | Description
+--------- | ------- | -----------
+type | string | Indicates whether the invalid piggyback is on an "input" or "output"
+inflight_blocknum | integer | Block number of the in-flight transaction
+inflight_tx_index | integer | Index of the in-flight transaction
+inflight_io_index | integer | Index of the input or output of the in-flight transaction
+spending_blocknum | integer | Block number of the spending transaction
+spending_tx_index | integer | Index of the spending transaction
+spending_input_index | integer | Index of the spent input iofn the spending transaction
\ No newline at end of file

original_message: Add MoreVP byzantine events


message: Use `curl` in shell examples

diff:
@@ -6,7 +6,7 @@ API specification of the Watcher's Informational Service
## Account - Get Balance
```shell
-http POST /account.get_balance address=b3256026863eb6ae5b06fa396ab09069784ea8ea
+curl http://localhost:4000/account.get_balance -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
```
```elixir
@@ -42,9 +42,9 @@ Returns the balance of each currency for the given account address
`POST /account.get_balance`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
address | Hex encoded string | Address of the funds owner
@@ -53,7 +53,7 @@ address | Hex encoded string | Address of the funds owner
## Account - Get Utxos
```shell
-http POST /account.get_utxos address=b3256026863eb6ae5b06fa396ab09069784ea8ea
+curl http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
```
```elixir
@@ -89,9 +89,9 @@ Gets all utxos belonging to the given address
`POST /account.get_utxos`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
address | Hex encoded string | Address of the account
limit | Integer | Maximum number of utxos to return (optional)
@@ -101,7 +101,7 @@ limit | Integer | Maximum number of utxos to return (optional)
## Account - Get Transactions
```shell
-http POST /account.get_transactions address=b3256026863eb6ae5b06fa396ab09069784ea8ea
+curl http://localhost:4000/account.get_transactions -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
```
```elixir
@@ -142,9 +142,9 @@ Gets a list of transactions.
`POST /account.get_transactions`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
address | Hex encoded string | Address of the account
limit | Integer | Maximum number of transactions to return (optional)
@@ -154,7 +154,8 @@ limit | Integer | Maximum number of transactions to return (optional)
## Transaction - Get All
```shell
-http POST /transaction.all block=100```
+curl http://localhost:4000/transaction.all -d '{"block": "100", "limit": 50}'
+```
```elixir
// TODO
@@ -207,9 +208,9 @@ Gets a transaction with the given id
`POST /transaction.get`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
block | Integer | Block number to filter by (optional)
address | Hex encoded string | Address to filter by (optional)
@@ -220,7 +221,7 @@ limit | Integer | Maximum number of transactions to return (optional)
## Transaction - Get
```shell
-http POST /transaction.get id=bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d
+curl http://localhost:4000/transaction.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
```
```elixir
@@ -284,9 +285,9 @@ Gets a transaction with the given id
`POST /transaction.get`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
id | Hex encoded string | Hash of the Plasma transaction
@@ -295,7 +296,7 @@ id | Hex encoded string | Hash of the Plasma transaction
## Block - Get all
```shell
-http POST /block.all limit=100
+curl http://localhost:4000/block.all -d '{"limit": 100}'
```
```elixir
@@ -335,9 +336,9 @@ Gets a block with the given id
`POST /block.all`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
limit | Integer | Maximum number of transactions to return (optional)
@@ -347,7 +348,7 @@ limit | Integer | Maximum number of transactions to return (optional)
## Block - Get
```shell
-http POST /block.get id=bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d
+curl http://localhost:4000/block.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
```
```elixir
@@ -379,9 +380,9 @@ Gets a block with the given id
`POST /block.get`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
id | Hex encoded string | Hash of the Plasma block

diff:
## Submit transaction
```shell
-http POST /transaction.submit transaction=f8d083015ba98080808080940000...
+curl http://localhost:4000/transaction.submit -d '{"transaction": "b325602686..."}'
```
```elixir
@@ -28,15 +28,15 @@ http POST /transaction.submit transaction=f8d083015ba98080808080940000...
}
```
-This endpoint submits signed transaction to the child chain
+This endpoint submits a signed transaction to the child chain.
### HTTP Request
`POST /transaction.submit`
-### JSON Body
+### Request Body
-Key | Value | Description
+Attribute | Type | Description
--------- | ------- | -----------
transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and HEX-encoded to string
@@ -46,7 +46,7 @@ transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and H
## Get Block by id
```shell
-http POST /block.get hash=2733e50f526ec2fa19a22b31e8ed50f23cd1fdf94c9154ed3a7609a2f1ff981f
+curl http://localhost:4000/block.get -d '{"hash": "2733e50f526ec2fa19a22b31e8ed50f23cd1fdf94c9154ed3a7609a2f1ff981f}'
```
```elixir
@@ -73,14 +73,14 @@ http POST /block.get hash=2733e50f526ec2fa19a22b31e8ed50f23cd1fdf94c9154ed3a7609
}
```
-This endpoint retrieves a specific block from child chain which hash was published on root chain
+This endpoint retrieves a specific block from child chain by its hash which was published on root chain
### HTTP Request
`POST /block.get`
-### JSON Body
+### Request Body
-Key | Value | Description
+Attribute | Type | Description
--------- | ------- | -----------
hash | Hex encoded string | HEX-encoded hash of the block

diff:
@@ -5,7 +5,7 @@ API specification of the Watcher's security-critical Service
## Account - Get Utxos
```shell
-http POST /account.get_utxos address=b3256026863eb6ae5b06fa396ab09069784ea8ea
+curl http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
```
```elixir
@@ -43,9 +43,9 @@ Gets all utxos belonging to the given address.
`POST /account.get_utxos`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
address | Hex encoded string | Address of the account
limit | Integer | Maximum number of utxos to return (optional)
@@ -55,7 +55,7 @@ limit | Integer | Maximum number of utxos to return (optional)
## Utxo - Get Challenge Data
```shell
-http POST /utxo.get_challenge_data utxo_pos=10001001
+curl http://localhost:4000/utxo.get_challenge_data -d '{"utxo_pos": "10001001"}'
```
```elixir
@@ -88,9 +88,9 @@ Gets challenge data for a given utxo exit
`POST /utxo.get_challenge_data`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
utxo_pos | Integer | Utxo position (encoded as single integer, the way contract represents them)
@@ -99,7 +99,7 @@ utxo_pos | Integer | Utxo position (encoded as single integer, the way contract
## Utxo - Get Exit Data
```shell
-http POST /utxo.get_exit_data utxo_pos=10001001
+curl http://localhost:4000/utxo.get_exit_data -d '{"utxo_pos": "10001001"}'
```
```elixir
@@ -131,9 +131,9 @@ Gets exit data for a given utxo
`POST /utxo.get_exit_data`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
utxo_pos | Integer | Utxo position (encoded as single integer, the way contract represents them)
@@ -142,7 +142,7 @@ utxo_pos | Integer | Utxo position (encoded as single integer, the way contract
## Transaction - Submit
```shell
-http POST /transaction.submit transaction=f8d083015ba98080808080940000...
+curl http://localhost:4000/transaction.submit -d '{"transaction": "f8d083015ba98080808080940000..."}'
```
```elixir
@@ -174,9 +174,9 @@ Watcher passes signed transaction to the child chain only if it's secure (better
`POST /transaction.submit`
-### JSON Body
+### Request Body
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and HEX-encoded to string
@@ -186,7 +186,7 @@ transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and H
## Status
```shell
-http POST /status
+curl -X POST http://localhost:4000/status
```
```elixir
@@ -231,7 +231,7 @@ Gets plasma network and Watcher status
`POST /status`
-### JSON Body
+### Request Body
No parameters are required.
@@ -333,7 +333,7 @@ An non-canonical in-flight exit has been started. It should be challenged.
 Not Implemented Yet.
Event details:
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
inflight_blocknum | integer | Block number of the in-flight transaction
inflight_tx_index | integer | Index of the in-flight transaction
@@ -359,7 +359,7 @@ A canonical in-flight exit has been challenged. The challenge should be responde
 Not Implemented Yet.
Event details:
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
inflight_blocknum | integer | Block number of the in-flight transaction
inflight_tx_index | integer | Index of the in-flight transaction
@@ -382,7 +382,7 @@ An in-flight exit has been started and can be piggybacked
 Not Implemented Yet.
Event details:
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
inflight_blocknum | integer | Block number of the in-flight transaction
inflight_tx_index | integer | Index of the in-flight transaction
@@ -410,7 +410,7 @@ An invalid piggyback is in process. Should be challenged.
 Not Implemented Yet.
Event details:
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
type | string | Indicates whether the invalid piggyback is on an "input" or "output"
inflight_blocknum | integer | Block number of the in-flight transaction

diff:
@@ -53,7 +53,7 @@ The address_spent event informing about that particular address spent funds.
Both event types have the same structure.
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
child_blknum | Integer |
child_txindex | Integer |
@@ -89,7 +89,7 @@ Informs that a new block has been added to the chain.
Both event types have the same structure.
-Key | Type | Description
+Attribute | Type | Description
--------- | ------- | -----------
blknum | Integer |
block_hash | HEX-encoded string |

original_message: Use `curl` in shell examples


message: Add MoreVP inflight_exit calls

diff:
@@ -418,3 +418,274 @@ inflight_io_index | integer | Index of the input or output of the in-flight tran
spending_blocknum | integer | Block number of the spending transaction
spending_tx_index | integer | Index of the spending transaction
spending_input_index | integer | Index of the spent input iofn the spending transaction
+
+
+## Inflight Exit - Get Exit Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "txbytes": "F847010180808080940000...",
+ "sigs": "7C29FB8327F60BBFC62...",
+ "input_txs" : [
+ {
+ "txbytes": "F81891018080808...",
+ "proof": "CEDB8B31D1E4C..."
+ },
+ {
+ "txbytes": "2A03418086001...",
+ "proof": "A67131D1E4C..."
+ }
+ ]
+ }
+}
+```
+
+Gets exit data for an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+txhash | Hex encoded string | The hash of the in-flight transaction
+
+
+
+## Inflight Exit - Get Challenge Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_challenge_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_input_index": 1,
+ "competing_txbytes": "F317010180808080940000...",
+ "competing_input_index": 1,
+ "competing_txid": 2600003920012,
+ "competing_proof": "004C010180808080940000...",
+ "competing_sig": "9A23010180808080940000..."
+ }
+}
+```
+
+Gets challenge data for an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_challenge_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+txhash | Hex encoded string | The hash of the in-flight transaction
+
+
+
+## Inflight Exit - Get Challenge Response Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_challenge_response_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_txid": 2600003920012,
+ "inflight_proof": "004C010180808080940000..."
+ }
+}
+```
+
+Gets the data to respond to a challenge to an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_challenge_response_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+txhash | Hex encoded string | The hash of the in-flight transaction
+
+
+
+## Inflight Exit - Get Piggyback Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_piggyback_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_io_index": 1
+ }
+}
+```
+
+Gets the piggyback data for an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_piggyback_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+txhash | Hex encoded string | The hash of the in-flight transaction
+
+
+
+## Inflight Exit - Get Input Challenge Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"inflight_txhash": "bdf562c24ace..."}, "spending_txhash": "bdf562c24ace..."}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_input_index": 1,
+ "spending_txbytes": "F317010180808080940000...",
+ "spending_input_index": 1,
+ "spending_sig": "9A23010180808080940000..."
+ }
+}
+```
+
+Gets the data to challenge an input piggybacked on an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_input_challenge_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+inflight_txhash | Hex encoded string | The hash of the in-flight transaction
+spending_txhash | Hex encoded string | The hash of the spending transaction
+
+
+
+## Inflight Exit - Get Output Challenge Data
+
+```shell
+curl http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"inflight_txhash": "bdf562c24ace..."}, "spending_txhash": "bdf562c24ace..."}'
+```
+
+```elixir
+// TODO
+```
+
+```javascript
+// TODO
+```
+
+> The above command returns JSON document:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_output_pos": 21000634002,
+ "inflight_proof": "F847010180808080940000...",
+ "spending_txbytes": "F317010180808080940000...",
+ "spending_input_index": 1,
+ "spending_sig": "9A23010180808080940000..."
+ }
+}
+```
+
+Gets the data to challenge an output piggybacked on an in-flight exit
+
+### HTTP Request
+
+`POST /inflight_exit.get_output_challenge_data`
+
+### Request Body
+
+Attribute | Type | Description
+--------- | ------- | -----------
+inflight_txhash | Hex encoded string | The hash of the in-flight transaction
+spending_txhash | Hex encoded string | The hash of the spending transaction
+

original_message: Add MoreVP inflight_exit calls


message: Fix typos in /transaction.all

diff:
@@ -202,11 +202,11 @@ curl http://localhost:4000/transaction.all -d '{"block": "100", "limit": 50}'
}
```
-Gets a transaction with the given id
+Gets all transactions (can be limited with various filters)
### HTTP Request
-`POST /transaction.get`
+`POST /transaction.all`
### Request Body

original_message: Fix typos in /transaction.all


message: Refine IFE related events

diff:
@@ -219,6 +219,28 @@ curl -X POST http://localhost:4000/status
"amount" : 100
}
}
+ ],
+ "inflight_txs": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "input_addresses": [
+ "0x1234..."
+ ],
+ "ouput_addresses": [
+ "0x1234...",
+ "0x7890..."
+ ],
+ }
+ ],
+ "inflight_exits": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "timestamp" : 1544193137,
+ "piggybacked_inputs" : [1],
+ "piggybacked_outputs" : [0, 1]
+ }
]
}
}
@@ -293,7 +315,7 @@ Indicates that an invalid exit is dangerously close to finalization and hasn't b
}
```
-A block containing an invalid tx has been processed [are there other reasons a block can be invalid?]. User should exit.
+An invalid block has been added to the chain. User should exit.
#### `block_withholding`
@@ -318,28 +340,18 @@ The ChildChain is withholding a block whose hash has been published on the root
{
"event": "noncanonical_ife",
"details": {
- "inflight_blocknum" : 10000,
- "inflight_tx_index" : 12,
- "inflight_input_index" : 1,
- "competing_blocknum" : 10000,
- "competing_tx_index" : 10,
- "competing_input_index" : 0,
+ "txbytes": "F3170101C0940000..."
}
}
```
-An non-canonical in-flight exit has been started. It should be challenged.
+An in-flight exit of a non-canonical transaction has been started. It should be challenged.
 Not Implemented Yet.
Event details:
Attribute | Type | Description
--------- | ------- | -----------
-inflight_blocknum | integer | Block number of the in-flight transaction
-inflight_tx_index | integer | Index of the in-flight transaction
-inflight_input_index | integer | Index of the double-spent input in the in-flight transaction
-competing_blocknum | integer | Block number of the spending transaction
-competing_tx_index | integer | Index of the spending transaction
-competing_input_index | integer | Index of the double-spent input in the competing transaction
+txbytes | Hex encoded string | The in-flight transaction that the event relates to
#### `invalid_ife_challenge`
> A invalid_ife_challenge event
@@ -348,8 +360,7 @@ competing_input_index | integer | Index of the double-spent input in the competi
{
"event": "invalid_ife_challenge",
"details": {
- "inflight_blocknum" : 10000,
- "inflight_tx_index" : 12,
+ "txbytes": "F3170101C0940000..."
}
}
```
@@ -360,8 +371,7 @@ A canonical in-flight exit has been challenged. The challenge should be responde
Event details:
Attribute | Type | Description
--------- | ------- | -----------
-inflight_blocknum | integer | Block number of the in-flight transaction
-inflight_tx_index | integer | Index of the in-flight transaction
+txbytes | Hex encoded string | The in-flight transaction that the event relates to
#### `piggyback_available`
> A piggyback_available event
@@ -370,22 +380,22 @@ inflight_tx_index | integer | Index of the in-flight transaction
{
"event": "piggyback_available",
"details": {
- "inflight_blocknum" : 10000,
- "inflight_tx_index" : 12,
- "inflight_io_index" : 1
+ "txbytes": "F3170101C0940000...",
+ "available_outputs" : [0, 1],
+ "available_inputs" : [0, 1]
}
}
```
-An in-flight exit has been started and can be piggybacked
+An in-flight exit has been started and can be piggybacked. If all inputs are owned by the same address, then `available_inputs` will not be present.
 Not Implemented Yet.
Event details:
Attribute | Type | Description
--------- | ------- | -----------
-inflight_blocknum | integer | Block number of the in-flight transaction
-inflight_tx_index | integer | Index of the in-flight transaction
-inflight_io_index | integer | Index of the input or output that can be exitted.
+txbytes | Hex encoded string | The in-flight transaction that the event relates to
+available_outputs | Integer array | The outputs available to be piggybacked
+available_inputs | Integer array | The inputs available to be piggybacked
#### `invalid_piggyback`
> A invalid_piggyback event
@@ -394,13 +404,9 @@ inflight_io_index | integer | Index of the input or output that can be exitted.
{
"event": "invalid_piggyback",
"details": {
- "type": "output",
- "inflight_blocknum" : 10000,
- "inflight_tx_index" : 12,
- "inflight_io_index" : 1,
- "spending_blocknum" : 10000,
- "spending_tx_index" : 10,
- "spending_input_index" : 0,
+ "txbytes": "F3170101C0940000...",
+ "inputs": [1],
+ "outputs": [0]
}
}
```
@@ -411,19 +417,16 @@ An invalid piggyback is in process. Should be challenged.
Event details:
Attribute | Type | Description
--------- | ------- | -----------
-type | string | Indicates whether the invalid piggyback is on an "input" or "output"
-inflight_blocknum | integer | Block number of the in-flight transaction
-inflight_tx_index | integer | Index of the in-flight transaction
-inflight_io_index | integer | Index of the input or output of the in-flight transaction
-spending_blocknum | integer | Block number of the spending transaction
-spending_tx_index | integer | Index of the spending transaction
-spending_input_index | integer | Index of the spent input iofn the spending transaction
+txbytes | Hex encoded string | The in-flight transaction that the event relates to
+inputs | Integer array | A list of invalid piggybacked inputs
+outputs | Integer array | A list of invalid piggybacked outputs
+
## Inflight Exit - Get Exit Data
```shell
-curl http://localhost:4000/inflight_exit.get_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+curl http://localhost:4000/inflight_exit.get_data -d '{"txbytes": "F317010180808080940000..."}'
```
```elixir
@@ -443,15 +446,13 @@ curl http://localhost:4000/inflight_exit.get_data -d '{"txhash": "bdf562c24ace03
"data": {
"txbytes": "F847010180808080940000...",
"sigs": "7C29FB8327F60BBFC62...",
- "input_txs" : [
- {
- "txbytes": "F81891018080808...",
- "proof": "CEDB8B31D1E4C..."
- },
- {
- "txbytes": "2A03418086001...",
- "proof": "A67131D1E4C..."
- }
+ "input_txs_bytes" : [
+ "F81891018080808...",
+ "2A0341808602A01..."
+ ],
+ "input_txs_proofs" : [
+ "CEDB8B31D1E4C...",
+ "A67131D1E904C..."
]
}
}
@@ -467,14 +468,14 @@ Gets exit data for an in-flight exit
Attribute | Type | Description
--------- | ------- | -----------
-txhash | Hex encoded string | The hash of the in-flight transaction
+txbytes | Hex encoded string | The in-flight transaction
-## Inflight Exit - Get Challenge Data
+## Inflight Exit - Get Competitor
```shell
-curl http://localhost:4000/inflight_exit.get_challenge_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+curl http://localhost:4000/inflight_exit.get_competitor -d '{"txbytes": "F3170101C0940000..."}'
```
```elixir
@@ -496,31 +497,31 @@ curl http://localhost:4000/inflight_exit.get_challenge_data -d '{"txhash": "bdf5
"inflight_input_index": 1,
"competing_txbytes": "F317010180808080940000...",
"competing_input_index": 1,
+ "competing_sig": "9A23010180808080940000...",
"competing_txid": 2600003920012,
- "competing_proof": "004C010180808080940000...",
- "competing_sig": "9A23010180808080940000..."
+ "competing_proof": "004C010180808080940000..."
}
}
```
-Gets challenge data for an in-flight exit
+Returns a competitor to an in-flight exit. Note that if the competing transaction has not been put into a block `competing_txid` and `competing_proof` will not be returned.
### HTTP Request
-`POST /inflight_exit.get_challenge_data`
+`POST /inflight_exit.get_competitor`
### Request Body
Attribute | Type | Description
--------- | ------- | -----------
-txhash | Hex encoded string | The hash of the in-flight transaction
+txbytes | Hex encoded string | The in-flight transaction
-## Inflight Exit - Get Challenge Response Data
+## Inflight Exit - Show Canonical
```shell
-curl http://localhost:4000/inflight_exit.get_challenge_response_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+curl http://localhost:4000/inflight_exit.prove_canonical -d '{"txbytes": "F3170101C0940000..."}'
```
```elixir
@@ -545,65 +546,24 @@ curl http://localhost:4000/inflight_exit.get_challenge_response_data -d '{"txhas
}
```
-Gets the data to respond to a challenge to an in-flight exit
-
-### HTTP Request
-
-`POST /inflight_exit.get_challenge_response_data`
-
-### Request Body
-
-Attribute | Type | Description
---------- | ------- | -----------
-txhash | Hex encoded string | The hash of the in-flight transaction
-
-
-
-## Inflight Exit - Get Piggyback Data
-
-```shell
-curl http://localhost:4000/inflight_exit.get_piggyback_data -d '{"txhash": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
-```
-
-```elixir
-// TODO
-```
-
-```javascript
-// TODO
-```
-
-> The above command returns JSON document:
-
-```json
-{
- "version": "1",
- "success": true,
- "data": {
- "inflight_txbytes": "F847010180808080940000...",
- "inflight_io_index": 1
- }
-}
-```
-
-Gets the piggyback data for an in-flight exit
+To respond to a challenge to an in-flight exit, this proves that the transaction has been put into a block (and therefore is canonical).
### HTTP Request
-`POST /inflight_exit.get_piggyback_data`
+`POST /inflight_exit.prove_canonical`
### Request Body
Attribute | Type | Description
--------- | ------- | -----------
-txhash | Hex encoded string | The hash of the in-flight transaction
+txbytes | Hex encoded string | The in-flight transaction
## Inflight Exit - Get Input Challenge Data
```shell
-curl http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"inflight_txhash": "bdf562c24ace..."}, "spending_txhash": "bdf562c24ace..."}'
+curl http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"txbytes": "F3170101C0940000...", "input_index": 1}'
```
```elixir
@@ -630,7 +590,7 @@ curl http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"inflight
}
```
-Gets the data to challenge an input piggybacked on an in-flight exit
+Gets the data to challenge an invalid input piggybacked on an in-flight exit
### HTTP Request
@@ -640,15 +600,15 @@ Gets the data to challenge an input piggybacked on an in-flight exit
Attribute | Type | Description
--------- | ------- | -----------
-inflight_txhash | Hex encoded string | The hash of the in-flight transaction
-spending_txhash | Hex encoded string | The hash of the spending transaction
+txbytes | Hex encoded string | The in-flight transaction
+input_index | Integer | The index of the invalid input
## Inflight Exit - Get Output Challenge Data
```shell
-curl http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"inflight_txhash": "bdf562c24ace..."}, "spending_txhash": "bdf562c24ace..."}'
+curl http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"txbytes": "F3170101C0940000...", "output_index": 0}'
```
```elixir
@@ -676,7 +636,7 @@ curl http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"infligh
}
```
-Gets the data to challenge an output piggybacked on an in-flight exit
+Gets the data to challenge an invalid output piggybacked on an in-flight exit
### HTTP Request
@@ -686,6 +646,5 @@ Gets the data to challenge an output piggybacked on an in-flight exit
Attribute | Type | Description
--------- | ------- | -----------
-inflight_txhash | Hex encoded string | The hash of the in-flight transaction
-spending_txhash | Hex encoded string | The hash of the spending transaction
-
+txbytes | Hex encoded string | The in-flight transaction
+output_index | Integer | The index of the invalid output

original_message: Refine IFE related events


message: Add IFE user scenarios

change_type: ADD

diff:
+# Simple In-flight Exit
+
+Alice sends tokens to Bob in transaction `tx` which has one input and one output. The block is withheld.
+
+Bob calls `watcher/status` and gets a response:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "last_validated_child_block_number": 10000,
+ "last_mined_child_block_timestamp": 1535031020,
+ "last_mined_child_block_number": 11000,
+ "eth_syncing": true,
+ "byzantine_events": [
+ {
+ "event": "block_withholding",
+ "details": {
+ "blockhash" : "DB32876CC6F...",
+ "blocknum" : 10000,
+ }
+ }
+ ],
+ "inflight_txs": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "input_addresses": [
+ "0x1234..."
+ ],
+ "output_addresses": [
+ "0x7890..."
+ ],
+ }
+ ]
+ }
+}
+ ```
+He notices that the chain is byzantine and there is an in-flight transaction with his address as an output.
+
+Bob starts an in-flight exit.
+
+#### 1. Get the exit data
+`/inflight_exit.get_data`
+```json
+ {
+ "txbytes": "F3170101C0940000..."
+ }
+ ```
+
+ response:
+```json
+ {
+ "data": {
+ "txbytes": "F3170101C0940000...",
+ "sigs": "7C29FB8327F60BBFC62...",
+ "input_txs" : [
+ "F81891018080808...",
+ "2A0341808602A01..."
+ ],
+ "input_proofs" : [
+ "CEDB8B31D1E4C...",
+ "A67131D1E904C..."
+ ]
+ }
+ }
+ ```
+
+#### 2. Start the IFE
+```
+RootChain.startInFlightExit(
+ response.data.txbytes,
+ response.data.input_txs,
+ response.data.input_proofs,
+ response.data.sigs,
+ {"value": inFlightExitBond}
+)
+```
+
+#### 3. Piggyback his output
+The second argument is `4` because he is piggybacking the first output.
+```
+RootChain.piggybackInFlightExit(
+ response.data.txbytes,
+ 4,
+ {"value": piggybackBond}
+)
+```
+
+After finalization, if nobody challenges the exit, Bob will exit his output and get his `inFlightExitBond` and `piggybackBond` back.
+
+# Simple In-flight Exit with 2 outputs
+Alice sends tokens to Bob, but this time she includes a change output to herself, so that the transaction `tx1` has 2 outputs.
+
+When Alice calls `watcher/status` she gets this response:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "last_validated_child_block_number": 10000,
+ "last_mined_child_block_timestamp": 1535031020,
+ "last_mined_child_block_number": 11000,
+ "eth_syncing": true,
+ "byzantine_events": [
+ {
+ "event": "block_withholding",
+ "details": {
+ "blockhash" : "DB32876CC6F...",
+ "blocknum" : 10000,
+ }
+ },
+ {
+ "event": "piggyback_available",
+ "details": {
+ "txbytes": "F3170101C0940000...",
+ "available_outputs" : [1]
+ }
+ },
+ ],
+ "inflight_txs": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "input_addresses": [
+ "0x1234..."
+ ],
+ "output_addresses": [
+ "0x7890...",
+ "0x1234..."
+ ],
+ }
+ ],
+ "inflight_exits": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "timestamp" : 1544193137,
+ "piggybacked_outputs" : [0]
+ }
+ ]
+ }
+}
+ ```
+
+Because Bob has already started an exit for the transaction - there is a `piggyback_available` event indicating that `output[1]` can be piggybacked. This output is to Alice's address. Note that as Alice is the sole owner of the inputs, she does not need to piggyback any input.
+
+#### 1. Piggyback her output on the IFE
+The second argument is `5` because Alice is piggybacking the second output.
+```
+RootChain.piggybackInFlightExit(
+ inflight_exits[0].txbytes,
+ 5,
+ {"value": piggybackBond}
+)
+```
+
+After finalization (if nobody challenges the exit) Bob will exit his output and get his `inFlightExitBond` and `piggybackBond` back, Alice will exit her change output and get her `piggybackBond` back.
+
+# Challenge an IFE
+To challenge an IFE we must attempt to prove that it is non-canonical by presenting a competing transaction that also spends one its inputs.
+If the competing transaction has already been included in a block, then we must present its inclusion proof.
+Imagine that Alice's transaction `tx1` in the previous example is a double spend - its `input0` was already spent as `input1` of another transaction `tx0`
+
+Request `watcher/status`:
+
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "last_validated_child_block_number": 10000,
+ "last_mined_child_block_timestamp": 1535031020,
+ "last_mined_child_block_number": 11000,
+ "eth_syncing": true,
+ "byzantine_events": [
+ {
+ "event": "block_withholding",
+ "details": {
+ "blockhash" : "DB32876CC6F...",
+ "blocknum" : 10000,
+ }
+ },
+ {
+ "event": "noncanonical_ife",
+ "details": {
+ "txbytes": "F3170101C0940000..."
+ }
+ },
+ ],
+ "inflight_txs": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "input_addresses": [
+ "0x1234..."
+ ],
+ "output_addresses": [
+ "0x7890...",
+ "0x1234..."
+ ],
+ }
+ ],
+ "inflight_exits": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "timestamp" : 1544193137,
+ "piggybacked_inputs" : [0],
+ "piggybacked_outputs" : [0, 1],
+ }
+ ]
+ }
+}
+ ```
+
+#### 1. Get the competing transaction and its inclusion proof (if available).
+`/inflight_exit.get_competitor`
+```json
+{
+ "txbytes": "F3170101C0940000..."
+}
+```
+
+response:
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_input_index": 0,
+ "competing_txbytes": "F317010180808080940000...",
+ "competing_input_index": 1,
+ "competing_sig": "9A23010180808080940000...",
+ "competing_txid": 2600003920012,
+ "competing_proof": "004C010180808080940000..."
+ }
+}
+```
+Note that if the competing transaction has _not_ been included in a block then its inclusion proof and txid will not be available. In this case, you should pass "" and 0 to `RootChain.challengeInFlightExitNotCanonical()`
+
+#### 2. Challenge the IFE with an included competitor
+```
+tx0_data = response.data
+RootChain.challengeInFlightExitNotCanonical(
+ inflight_txbytes,
+ inflight_input_index,
+ competing_txbytes,
+ competing_input_index,
+ competing_txid,
+ competing_proof,
+ competing_sig
+)
+```
+
+# Respond to an IFE challenge
+To respond to a challenge to an IFE, we need to show that the transaction _is_ included. This situation can arise if the user that started the exit did not see the transaction in a block, but subsequently he or another user _did_ see the transaction being put into a block.
+
+`/watcher/status` response will contain:
+```
+ "byzantine_events": [
+ {
+ "event": "invalid_ife_challenge",
+ "details": {
+ "txbytes": "F3170101C0940000..."
+ }
+ }
+ ]
+```
+
+#### 1. Get the in-flight transaction's inclusion proof.
+
+`/inflight_exit.prove_canonical`
+```json
+{
+ "txbytes": "F3170101C0940000..."
+}
+```
+
+response:
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_txid": 2600003920012,
+ "inflight_proof": "004C010180808080940000..."
+ }
+}
+```
+
+#### 2. Respond to an IFE challenge
+```
+RootChain.challengeInFlightExitNotCanonical(
+ inflight_txbytes,
+ inflight_txid,
+ inflight_proof,
+)
+```
+If this transaction is the oldest competitor then it is canonical and the IFE succeeds - Bob exits his output.
+
+# Challenging a Piggybacked input
+To challenge a piggybacked input we must present a different transaction that spends that input.
+
+`/watcher/status` response will contain:
+```
+ "byzantine_events": [
+ {
+ "event": "invalid_piggyback",
+ "details": {
+ "txbytes": "F3170101C0940000...",
+ "inputs": [1]
+ }
+ }
+ ]
+```
+
+#### 1. Get the transaction that challenges the input
+
+`/inflight_exit.get_input_challenge_data`
+```json
+{
+ "txbytes": "F3170101C0940000...",
+ "input_index": 1
+}
+```
+
+response:
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_input_index": 1,
+ "spending_txbytes": "F317010180808080940000...",
+ "spending_input_index": 1,
+ "spending_sig": "9A23010180808080940000..."
+ }
+}
+```
+
+#### 2. Challenge the input
+```
+RootChain.challengeInFlightExitInputSpent(
+ inflight_tx.txbytes,
+ inflight_tx.input_index,
+ spending_tx.txbytes,
+ spending_tx.input_index,
+ spending_tx.sigs
+)
+```
+
+# Challenging a Piggybacked output
+To challenge a piggybacked output we must present a transaction that spends that output. The inflight transaction must have been put into a block, but the spending transaction does _not_ need to be in a block.
+
+`/watcher/status` response will contain:
+```
+ "byzantine_events": [
+ {
+ "event": "invalid_piggyback",
+ "details": {
+ "txbytes": "F3170101C0940000...",
+ "outputs": [0]
+ }
+ }
+ ]
+```
+
+#### 1. Get the output's proof of inclusion
+`/inflight_exit.get_output_challenge_data`
+```json
+{
+ "txbytes": "F3170101C0940000...",
+ "output_index": 0
+}
+```
+
+response:
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "inflight_txbytes": "F847010180808080940000...",
+ "inflight_output_pos": 21000634002,
+ "inflight_proof": "F847010180808080940000...",
+ "spending_txbytes": "F317010180808080940000...",
+ "spending_input_index": 1,
+ "spending_sig": "9A23010180808080940000..."
+ }
+}
+```
+
+#### 2. Challenge the output
+```
+RootChain.challengeInFlightExitOutputSpent(
+ inflight_tx.txbytes,
+ inflight_tx.output_pos,
+ inflight_tx.proof,
+ spending_tx.txbytes,
+ spending_tx.input_index,
+ spending_tx.sigs
+)
+```

original_message: Add IFE user scenarios


message: Changes from PR comments

diff:
@@ -564,62 +564,4 @@ iex -S mix run --no-start
This repo contains `gh-pages` branch intended to host [Slate-based](#todo) API specification. Branch `gh-pages` is totally diseparated from other development branches and contains just Slate generated page's files.
-## Updating API Specification
-In `docs/api-specs` folder there are numbered markdown files which forms final spec. Whenever API has changed and specs needs to be updated it should be updated along with the feature and push to the development branch.
-
-## Preparation - if you need to generate specs yourself
-
-### Fetch the branch
-Specs page files are separated from the content of other development branches. It makes sens to just fetch only one branch to sepearated folder outside of this repo files.
-
-```
-# somewhere OUTSIDE of this repo root folder
-# clone just `gh-pages` branch
-> git clone git@github.com:omisego/elixir-omg.git --branch gh-pages --single-branch gh_pages
-> cd gh_pages
-> ls
-```
-You should see just website files: html, css ...
-
-### Getting the Slate generator
-Clone [Slate repo] to some other folder outside of this repo and just created gh-pages branch files.
-
-```
-> git clone git@github.com:lord/slate.git slate
-> cd slate
-> bundle install # you need ruby installed
-```
-
-You need to follow above instructions just once
-
-## Generating the specs site
-
-Make sure you've setup you environment first as [above](Getting the Slate generator)
-
-First concat all specs files in appropriate order into one file from which Slate generates the website.
-Navigate to the `slate` folder (see above)
-```
-> cat <this repo root>/docs/api_specs/*.md > ./source/index.html.md
-
-# Run the Slate to generate static website files
-> bundle exec middleman build --clean
-```
-Above will generate static website files in `slate/build` folder
-
-
-You can review generated site locally running `bundle exec middleman server` and openning `http://localhost:4567/` in you web browser.
-
-## Updating specs in gh-pages branch
-
-Assuming you generated website as [above](Generating the specs site)
-Navigate to your `gh_pages` folder
-```
-> copy -r <your slate folder>/build/* .
-
-> git add --all
-> git commit -m "specs: regenerate from <this repo current git-sha>"
-> git push
-```
-
-New version should be visible at `https://omisego.github.io/elixir-omg/#introduction`.
-Well done!
+See [gh-pages README](https://github.com/omisego/elixir-omg/blob/gh-pages/docs/api_specs/README.md) for more details.

diff:
@@ -78,7 +78,59 @@ RootChain.startInFlightExit(
)
```
-#### 3. Piggyback his output
+#### 3. Check status again
+```json
+{
+ "version": "1",
+ "success": true,
+ "data": {
+ "last_validated_child_block_number": 10000,
+ "last_mined_child_block_timestamp": 1535031020,
+ "last_mined_child_block_number": 11000,
+ "eth_syncing": true,
+ "byzantine_events": [
+ {
+ "event": "block_withholding",
+ "details": {
+ "blockhash" : "DB32876CC6F...",
+ "blocknum" : 10000,
+ }
+ },
+ {
+ "event": "piggyback_available",
+ "details": {
+ "txbytes": "F3170101C0940000...",
+ "available_outputs" : [0, 1]
+ }
+ },
+ ],
+ "inflight_txs": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "input_addresses": [
+ "0x1234..."
+ ],
+ "output_addresses": [
+ "0x7890...",
+ "0x1234..."
+ ],
+ }
+ ],
+ "inflight_exits": [
+ {
+ "txhash": "230C450180808080...",
+ "txbytes": "F3170101C0940000...",
+ "eth_height" : 615441,
+ }
+ ]
+ }
+}
+ ```
+
+ Bob sees that his in-flight exit is in progress and he can now piggyback his ouput.
+
+#### 4. Piggyback his output
The second argument is `4` because he is piggybacking the first output.
```
RootChain.piggybackInFlightExit(
@@ -137,7 +189,7 @@ When Alice calls `watcher/status` she gets this response:
{
"txhash": "230C450180808080...",
"txbytes": "F3170101C0940000...",
- "timestamp" : 1544193137,
+ "eth_height" : 615441,
"piggybacked_outputs" : [0]
}
]
@@ -207,7 +259,7 @@ Request `watcher/status`:
{
"txhash": "230C450180808080...",
"txbytes": "F3170101C0940000...",
- "timestamp" : 1544193137,
+ "eth_height" : 615441,
"piggybacked_inputs" : [0],
"piggybacked_outputs" : [0, 1],
}
@@ -335,9 +387,9 @@ response:
"version": "1",
"success": true,
"data": {
- "inflight_txbytes": "F847010180808080940000...",
+ "inflight_txbytes": "F3170101C0940000...",
"inflight_input_index": 1,
- "spending_txbytes": "F317010180808080940000...",
+ "spending_txbytes": "F847010180808080940000...",
"spending_input_index": 1,
"spending_sig": "9A23010180808080940000..."
}
@@ -386,10 +438,10 @@ response:
"version": "1",
"success": true,
"data": {
- "inflight_txbytes": "F847010180808080940000...",
+ "inflight_txbytes": "F3170101C0940000...",
"inflight_output_pos": 21000634002,
- "inflight_proof": "F847010180808080940000...",
- "spending_txbytes": "F317010180808080940000...",
+ "inflight_proof": "03F451067A805540000...",
+ "spending_txbytes": "F847010180808080940000...",
"spending_input_index": 1,
"spending_sig": "9A23010180808080940000..."
}

original_message: Changes from PR comments


message: Add adresses to piggyback_available. Flag inflight_txs as not implemented

diff:
@@ -246,7 +246,17 @@ curl -X POST http://localhost:4000/status
}
```
-Gets plasma network and Watcher status
+Returns information about the current state of the child chain and the watcher.
+
+<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>
+
+<aside class="notice">
+Note that `inflight_txs` will be implemented in a later version.
+</aside>
+
### HTTP Request
@@ -256,11 +266,6 @@ 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 byzantine behaviour and that the user should either exit or challenge.
@@ -381,8 +386,13 @@ txbytes | Hex encoded string | The in-flight transaction that the event relates
"event": "piggyback_available",
"details": {
"txbytes": "F3170101C0940000...",
- "available_outputs" : [0, 1],
- "available_inputs" : [0, 1]
+ "available_outputs" : [
+ {"index": 0, "address": "0x7890..."},
+ {"index": 1, "address": "0x1234..."},
+ ],
+ "available_inputs" : [
+ {"index": 0, "address": "0x1234..."}
+ ],
}
}
```
@@ -394,8 +404,8 @@ Event details:
Attribute | Type | Description
--------- | ------- | -----------
txbytes | Hex encoded string | The in-flight transaction that the event relates to
-available_outputs | Integer array | The outputs available to be piggybacked
-available_inputs | Integer array | The inputs available to be piggybacked
+available_outputs | Object array | The outputs (index and address) available to be piggybacked
+available_inputs | Object array | The inputs (index and address) available to be piggybacked
#### `invalid_piggyback`
> A invalid_piggyback event


message: Remove 'inflight_txs' from scenarios and make sender start the IFE

diff:
# Simple In-flight Exit
-Alice sends tokens to Bob in transaction `tx` which has one input and one output. The block is withheld.
+Alice sends tokens to Bob in transaction `tx` which has one input and 2 outputs, one to Bob and one back to herself as change. The block is withheld.
-Bob calls `watcher/status` and gets a response:
+Alice calls `watcher/status` and gets a response:
```json
{
@@ -21,25 +21,14 @@ Bob calls `watcher/status` and gets a response:
"blocknum" : 10000,
}
}
- ],
- "inflight_txs": [
- {
- "txhash": "230C450180808080...",
- "txbytes": "F3170101C0940000...",
- "input_addresses": [
- "0x1234..."
- ],
- "output_addresses": [
- "0x7890..."
- ],
- }
]
}
}
```
-He notices that the chain is byzantine and there is an in-flight transaction with his address as an output.
+She notices that the chain is byzantine and the transaction she just submitted was not included in a block (therefore it's an in-flight transaction)
+TODO - How does Alice know that her transaction hasn't been included? Does she have to store the details of every transaction she submits until it is put into a block?
-Bob starts an in-flight exit.
+Alice starts an in-flight exit.
#### 1. Get the exit data
`/inflight_exit.get_data`
@@ -100,23 +89,13 @@ RootChain.startInFlightExit(
"event": "piggyback_available",
"details": {
"txbytes": "F3170101C0940000...",
- "available_outputs" : [0, 1]
+ "available_outputs" : [
+ {"index": 0, "address": "0x7890..."},
+ {"index": 1, "address": "0x1234..."},
+ ]
}
},
],
- "inflight_txs": [
- {
- "txhash": "230C450180808080...",
- "txbytes": "F3170101C0940000...",
- "input_addresses": [
- "0x1234..."
- ],
- "output_addresses": [
- "0x7890...",
- "0x1234..."
- ],
- }
- ],
"inflight_exits": [
{
"txhash": "230C450180808080...",
@@ -128,24 +107,22 @@ RootChain.startInFlightExit(
}
```
- Bob sees that his in-flight exit is in progress and he can now piggyback his ouput.
+ Alice sees that her in-flight exit is in progress and she can now piggyback her ouput. Note that as Alice is the sole owner of the inputs, she does not need to piggyback any input.
-#### 4. Piggyback his output
-The second argument is `4` because he is piggybacking the first output.
+#### 4. Piggyback the output
+The second argument is `5` because she is piggybacking the first output.
```
RootChain.piggybackInFlightExit(
response.data.txbytes,
- 4,
+ 5,
{"value": piggybackBond}
)
```
-After finalization, if nobody challenges the exit, Bob will exit his output and get his `inFlightExitBond` and `piggybackBond` back.
-
-# Simple In-flight Exit with 2 outputs
-Alice sends tokens to Bob, but this time she includes a change output to herself, so that the transaction `tx1` has 2 outputs.
+After finalization, if nobody challenges the exit, Alice will exit her output and get her `inFlightExitBond` and `piggybackBond` back.
-When Alice calls `watcher/status` she gets this response:
+#### 5. Bob finds out that he can piggyback his output
+When Bob calls `watcher/status` he gets this response:
```json
{
@@ -168,48 +145,38 @@ When Alice calls `watcher/status` she gets this response:
"event": "piggyback_available",
"details": {
"txbytes": "F3170101C0940000...",
- "available_outputs" : [1]
+ "available_outputs" : [
+ {"index": 0, "address": "0x7890..."},
+ ]
}
},
],
- "inflight_txs": [
- {
- "txhash": "230C450180808080...",
- "txbytes": "F3170101C0940000...",
- "input_addresses": [
- "0x1234..."
- ],
- "output_addresses": [
- "0x7890...",
- "0x1234..."
- ],
- }
- ],
"inflight_exits": [
{
"txhash": "230C450180808080...",
"txbytes": "F3170101C0940000...",
"eth_height" : 615441,
- "piggybacked_outputs" : [0]
+ "piggybacked_outputs" : [1]
}
]
}
}
```
-Because Bob has already started an exit for the transaction - there is a `piggyback_available` event indicating that `output[1]` can be piggybacked. This output is to Alice's address. Note that as Alice is the sole owner of the inputs, she does not need to piggyback any input.
+Because Alice has already started an exit for the transaction there is a `piggyback_available` event indicating that `output[0]` (Bob's address) can be piggybacked.
-#### 1. Piggyback her output on the IFE
-The second argument is `5` because Alice is piggybacking the second output.
+#### 6. Bob Piggybacks his output on the IFE
+The second argument is `4` because Bob is piggybacking the first output.
```
RootChain.piggybackInFlightExit(
inflight_exits[0].txbytes,
- 5,
+ 4,
{"value": piggybackBond}
)
```
-After finalization (if nobody challenges the exit) Bob will exit his output and get his `inFlightExitBond` and `piggybackBond` back, Alice will exit her change output and get her `piggybackBond` back.
+After finalization (if nobody challenges the exit) Bob will exit his output and get his `piggybackBond` back.
+
# Challenge an IFE
To challenge an IFE we must attempt to prove that it is non-canonical by presenting a competing transaction that also spends one its inputs.
@@ -242,19 +209,6 @@ Request `watcher/status`:
}
},
],
- "inflight_txs": [
- {
- "txhash": "230C450180808080...",
- "txbytes": "F3170101C0940000...",
- "input_addresses": [
- "0x1234..."
- ],
- "output_addresses": [
- "0x7890...",
- "0x1234..."
- ],
- }
- ],
"inflight_exits": [
{
"txhash": "230C450180808080...",


message: Add Header curl examples

diff:
@@ -6,7 +6,7 @@ API specification of the Watcher's Informational Service
## Account - Get Balance
```shell
-curl http://localhost:4000/account.get_balance -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/account.get_balance -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
```
```elixir
@@ -53,7 +53,7 @@ address | Hex encoded string | Address of the funds owner
## Account - Get Utxos
```shell
-curl http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
```
```elixir
@@ -101,7 +101,7 @@ limit | Integer | Maximum number of utxos to return (default 200)
## Account - Get Transactions
```shell
-curl http://localhost:4000/account.get_transactions -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/account.get_transactions -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea"}'
```
```elixir
@@ -154,7 +154,7 @@ limit | Integer | Maximum number of transactions to return (default 200)
## Transaction - Get All
```shell
-curl http://localhost:4000/transaction.all -d '{"block": "100", "limit": 50}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/transaction.all -d '{"block": "100", "limit": 50}'
```
```elixir
@@ -221,7 +221,7 @@ limit | Integer | Maximum number of transactions to return (default 200)
## Transaction - Get
```shell
-curl http://localhost:4000/transaction.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/transaction.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
```
```elixir
@@ -296,7 +296,7 @@ id | Hex encoded string | Hash of the Plasma transaction
## Block - Get all
```shell
-curl http://localhost:4000/block.all -d '{"limit": 100}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/block.all -d '{"limit": 100}'
```
```elixir
@@ -348,7 +348,7 @@ limit | Integer | Maximum number of transactions to return (default 200)
## Block - Get
```shell
-curl http://localhost:4000/block.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/block.get -d '{"id": "bdf562c24ace032176e27621073df58ce1c6f65de3b5932343b70ba03c72132d"}'
```
```elixir

diff:
@@ -47,7 +47,7 @@ transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and H
## Get Block by id
```shell
-curl http://localhost:4000/block.get -d '{"hash": "2733e50f526ec2fa19a22b31e8ed50f23cd1fdf94c9154ed3a7609a2f1ff981f}'
+curl -X POST -H "Content-Type: application/json" http://localhost:9656/block.get -d '{"hash": "2733e50f526ec2fa19a22b31e8ed50f23cd1fdf94c9154ed3a7609a2f1ff981f}'
```
```elixir

diff:
@@ -5,7 +5,7 @@ API specification of the Watcher's security-critical Service
## Account - Get Utxos
```shell
-curl http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/account.get_utxos -d '{"address": "b3256026863eb6ae5b06fa396ab09069784ea8ea", "limit": 10}'
```
```elixir
@@ -55,7 +55,7 @@ limit | Integer | Maximum number of utxos to return (default 200)
## Utxo - Get Challenge Data
```shell
-curl http://localhost:4000/utxo.get_challenge_data -d '{"utxo_pos": "10001001"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/utxo.get_challenge_data -d '{"utxo_pos": "10001001"}'
```
```elixir
@@ -99,7 +99,7 @@ utxo_pos | Integer | Utxo position (encoded as single integer, the way contract
## Utxo - Get Exit Data
```shell
-curl http://localhost:4000/utxo.get_exit_data -d '{"utxo_pos": "10001001"}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/utxo.get_exit_data -d '{"utxo_pos": "10001001"}'
```
```elixir
@@ -142,7 +142,7 @@ utxo_pos | Integer | Utxo position (encoded as single integer, the way contract
## Transaction - Submit
```shell
-curl http://localhost:4000/transaction.submit -d '{"transaction": "f8d083015ba98080808080940000..."}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/transaction.submit -d '{"transaction": "f8d083015ba98080808080940000..."}'
```
```elixir
@@ -185,7 +185,7 @@ transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and H
## Status
```shell
-curl -X POST http://localhost:4000/status
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/status
```
```elixir
@@ -436,7 +436,7 @@ outputs | Integer array | A list of invalid piggybacked outputs
## Inflight Exit - Get Exit Data
```shell
-curl http://localhost:4000/inflight_exit.get_data -d '{"txbytes": "F317010180808080940000..."}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/inflight_exit.get_data -d '{"txbytes": "F317010180808080940000..."}'
```
```elixir
@@ -485,7 +485,7 @@ txbytes | Hex encoded string | The in-flight transaction
## Inflight Exit - Get Competitor
```shell
-curl http://localhost:4000/inflight_exit.get_competitor -d '{"txbytes": "F3170101C0940000..."}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/inflight_exit.get_competitor -d '{"txbytes": "F3170101C0940000..."}'
```
```elixir
@@ -531,7 +531,7 @@ txbytes | Hex encoded string | The in-flight transaction
## Inflight Exit - Show Canonical
```shell
-curl http://localhost:4000/inflight_exit.prove_canonical -d '{"txbytes": "F3170101C0940000..."}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/inflight_exit.prove_canonical -d '{"txbytes": "F3170101C0940000..."}'
```
```elixir
@@ -573,7 +573,7 @@ txbytes | Hex encoded string | The in-flight transaction
## Inflight Exit - Get Input Challenge Data
```shell
-curl http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"txbytes": "F3170101C0940000...", "input_index": 1}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/inflight_exit.get_input_challenge_data -d '{"txbytes": "F3170101C0940000...", "input_index": 1}'
```
```elixir
@@ -618,7 +618,7 @@ input_index | Integer | The index of the invalid input
## Inflight Exit - Get Output Challenge Data
```shell
-curl http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"txbytes": "F3170101C0940000...", "output_index": 0}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/inflight_exit.get_output_challenge_data -d '{"txbytes": "F3170101C0940000...", "output_index": 0}'
```
```elixir

original_message: Add Header curl examples


message: Add pagination param to /block.all

diff:
@@ -296,7 +296,7 @@ id | Hex encoded string | Hash of the Plasma transaction
## Block - Get all
```shell
-curl -X POST -H "Content-Type: application/json" http://localhost:4000/block.all -d '{"limit": 100}'
+curl -X POST -H "Content-Type: application/json" http://localhost:4000/block.all -d '{"from_blknum": 68290001, "limit": 2}'
```
```elixir
@@ -330,7 +330,7 @@ curl -X POST -H "Content-Type: application/json" http://localhost:4000/block.all
}
```
-Gets a block with the given id
+Gets all blocks (with a limit on the number of blocks to return).
### HTTP Request
@@ -340,7 +340,8 @@ Gets a block with the given id
Attribute | Type | Description
--------- | ------- | -----------
-limit | Integer | Maximum number of transactions to return (default 200)
+limit | Integer | Maximum number of blocks to return (default 200)
+from_blknum | Integer | The block number of the latest block in the list to be returned. Optional - if not specified, latest block will be the current block. **Not Implemented Yet**

diff:
@@ -107,8 +107,4 @@ The RootChain contract raises certain events on Ethereum
* exit_started
* exit_challenged
* exit_finalized
- * inflight_exit_started
- * inflight_exit_challenged
- * piggyback_to_input
- * piggyback_to_output
* fees_exited

original_message: Add pagination param to /block.all


message: Fix docs links and formatting

diff:
@@ -40,7 +40,7 @@ Attribute | Type | Description
--------- | ------- | -----------
transaction | Hex encoded string | Signed transaction RLP-encoded to bytes and HEX-encoded to string
-Normally you should call the Watcher's (Transaction - Submit)[#] instead of this. The Watcher's version performs various security and validation checks before submitting the transaction, so is much safer. However, if the Watcher is not available this version exists.
+Normally you should call the Watcher's Transaction - Submit instead of this. The Watcher's version performs various security and validation checks before submitting the transaction, so is much safer. However, if the Watcher is not available this version exists.

diff:
@@ -36,7 +36,7 @@ curl -X POST -H "Content-Type: application/json" http://localhost:4000/account.g
```
Gets all utxos belonging to the given address.
- Note that this is a performance intensive call and should only be used if the chain is byzantine and the user needs to retrieve utxo information to be able to exit. Normally an application should use the Informational API's (Account - Get Utxos)[#] This version is provided in case the Informational API is not available.
+ Note that this is a performance intensive call and should only be used if the chain is byzantine and the user needs to retrieve utxo information to be able to exit. Normally an application should use the Informational API's Account - Get Utxos instead. This version is provided in case the Informational API is not available.
### HTTP Request
@@ -354,6 +354,7 @@ An in-flight exit of a non-canonical transaction has been started. It should be
 Not Implemented Yet.
Event details:
+
Attribute | Type | Description
--------- | ------- | -----------
txbytes | Hex encoded string | The in-flight transaction that the event relates to
@@ -374,6 +375,7 @@ A canonical in-flight exit has been challenged. The challenge should be responde
 Not Implemented Yet.
Event details:
+
Attribute | Type | Description
--------- | ------- | -----------
txbytes | Hex encoded string | The in-flight transaction that the event relates to
@@ -401,6 +403,7 @@ An in-flight exit has been started and can be piggybacked. If all inputs are own
 Not Implemented Yet.
Event details:
+
Attribute | Type | Description
--------- | ------- | -----------
txbytes | Hex encoded string | The in-flight transaction that the event relates to
@@ -425,6 +428,7 @@ An invalid piggyback is in process. Should be challenged.
 Not Implemented Yet.
Event details:
+
Attribute | Type | Description
--------- | ------- | -----------
txbytes | Hex encoded string | The in-flight transaction that the event relates to

diff:
@@ -61,8 +61,6 @@ child_block_hash | HEX-encoded string |
submited_at_ethheight | integer |
tx | object | Structure of signed transaction
-Blocks are validated by the Watcher after a short (not-easily-configurable) finality margin. By consequence, above events will be emitted no earlier than that finality margin. In case extra finality is required for high-stakes transactions, the client is free to wait any number of Ethereum blocks (confirmations) on top of submitted_at_ethheight.
-
## Topic `childchain`

diff:
@@ -25,4 +25,4 @@ search: true
This is the HTTP-RPC API for the ChildChain and Watcher.
All calls use HTTP POST and pass options in the request body in JSON format.
-Errors will usually return with HTTP response code 200, and the details of the error in the response body. See (Errors)[#].
+Errors will usually return with HTTP response code 200, and the details of the error in the response body. See [Errors](#errors).

original_message: Fix docs links and formatting


message: Fix: Pass CHILDCHAIN_URL env to watcher in docker-compose

diff:
@@ -45,6 +45,7 @@ services:
- ELIXIR_SERVICE=CHILDCHAIN
- CONTRACT_EXCHANGER_URL=http://docker.for.mac.localhost:5000
- ETHEREUM_RPC_URL=http://docker.for.mac.localhost:8545
+ - CHILDCHAIN_URL=http://docker.for.mac.localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
restart: always
ports:


message: Update docker-compose-linux.yml

diff:
@@ -60,6 +60,7 @@ services:
- ELIXIR_SERVICE=WATCHER
- CONTRACT_EXCHANGER_URL=http://localhost:5000
- ETHEREUM_RPC_URL=http://localhost:8545
+ - CHILDCHAIN_URL=http://localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
- DATABASE_URL=postgres://omisego_dev:omisego_dev@localhost:5432/omisego_dev
restart: always

original_message: Update docker-compose-linux.yml


message: Change CHILDCHAIN_URL to CHILD_CHAIN_URL

diff:
@@ -32,7 +32,7 @@ services:
- ELIXIR_SERVICE=CHILDCHAIN
- CONTRACT_EXCHANGER_URL=http://localhost:5000
- ETHEREUM_RPC_URL=http://localhost:8545
- - CHILDCHAIN_URL=http://localhost:9656
+ - CHILD_CHAIN_URL=http://localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
restart: always
ports:
@@ -56,6 +56,7 @@ services:
- ELIXIR_SERVICE=WATCHER
- CONTRACT_EXCHANGER_URL=http://localhost:5000
- ETHEREUM_RPC_URL=http://localhost:8545
+ - CHILD_CHAIN_URL=http://localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
- DATABASE_URL=postgres://omisego_dev:omisego_dev@localhost:5432/omisego_dev
restart: always

diff:
@@ -66,6 +66,7 @@ services:
- ELIXIR_SERVICE=CHILDCHAIN
- CONTRACT_EXCHANGER_URL=http://docker.for.mac.localhost:5000
- ETHEREUM_RPC_URL=http://docker.for.mac.localhost:8545
+ - CHILD_CHAIN_URL=http://docker.for.mac.localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
restart: always
ports:
@@ -89,7 +90,7 @@ services:
- ELIXIR_SERVICE=WATCHER
- CONTRACT_EXCHANGER_URL=http://docker.for.mac.localhost:5000
- ETHEREUM_RPC_URL=http://docker.for.mac.localhost:8545
- - CHILDCHAIN_URL=http://docker.for.mac.localhost:9656
+ - CHILD_CHAIN_URL=http://docker.for.mac.localhost:9656
- ETHEREUM_NETWORK=LOCALCHAIN
- DATABASE_URL=postgres://omisego_dev:omisego_dev@docker.for.mac.localhost:5432/omisego_dev
restart: always


message: docs: fix incorrect statement in in_flight_exit_scenarios.md

diff:
@@ -110,7 +110,7 @@ RootChain.startInFlightExit(
Alice sees that her in-flight exit is in progress and she can now piggyback her ouput. Note that as Alice is the sole owner of the inputs, she does not need to piggyback any input.
#### 4. Piggyback the output
-The second argument is `5` because she is piggybacking the first output.
+The second argument is `5` because she is piggybacking the second output.
```
RootChain.piggybackInFlightExit(
response.data.txbytes,


message:
docker-compose OS file consolidation
add pseudo-service elixir-omg back into docker-compose file
tell geth websockets which interface to run on
fix docker-compose file typo
merge docker-compose files and update README

old_path: .gitignore

new_path: .gitignore

diff:
@@ -42,3 +42,7 @@ env/
#test files
/apps/omg_child_chain/priv/omisego_operator_test_fees_file*
+
+# VS Code config file
+.vscode/
+

diff:
@@ -69,21 +69,30 @@ However, if you are brave and want to test being a Tesuji Plasma chain operator,
## Service start up using Docker Compose
This is the recommended method of starting the blockchain services, with the auxiliary services automatically provisioned through Docker.
+
Before attempting the start up please ensure that you are not running any services that are listening on the following TCP ports: 9656, 7434, 5000, 8545, 5432, 5433.
All commands should be run from the root of the repo.
**NOTE** known to work with `docker-compose version 1.24.0, build 0aa59064`, version `1.17` has had problems
-### Mac
+To bring the entire system up:
+
+```sh
+docker-compose up
+```
+
+To bring only specific services up (eg: the childchain service):
```sh
-docker-compose -f docker-compose.yml -f docker-compose-full-services-mac.yml up`
+docker-compose up childchain
```
-### Linux
+_(Note: This will also bring up any services childchain depends on.)_
+
+To override and run specific Watcher code use:
```sh
-docker-compose -f docker-compose.yml -f docker-compose-full-services-non-mac.yml up`
+docker-compose -f docker-compose.yml -f docker-compose-watcher.yml up
```
### Get the deployed contract details

change_type: DELETE

diff:
-version: "2.1"
-services:
- geth:
- image: ethereum/client-go:v1.8.21
- entrypoint: /bin/sh -c "apk add curl && geth --targetgaslimit "6200000" --dev --dev.period 1 --rpc --rpcapi personal,web3,eth,net --rpcaddr 0.0.0.0 --rpcvhosts=* --rpcport=8545 --ws --wsorigins='*'"
- ports:
- - "8545:8545"
- healthcheck:
- test: curl docker.for.mac.localhost:8545
- interval: 5s
- timeout: 3s
- retries: 5
-
- elixir-omg:
- build: .
- image: elixir-omg:dockercompose
-
- contractexchanger:
- image: jakebunce/contractexchanger:v0.0.2
- ports:
- - "5000:5000"
- healthcheck:
- test: curl docker.for.mac.localhost:5000
- interval: 5s
- timeout: 3s
- retries: 5
- depends_on:
- geth:
- condition: service_healthy
-
- childchain:
- image: elixir-omg:dockercompose
- entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname childchain' -S mix xomg.child_chain.start --config ~/config.exs"
- environment:
- - MIX_ENV=dev
- - EXIT_PERIOD_SECONDS=86400
- - ELIXIR_SERVICE=CHILDCHAIN
- - CONTRACT_EXCHANGER_URL=http://docker.for.mac.localhost:5000
- - ETHEREUM_RPC_URL=http://docker.for.mac.localhost:8545
- - CHILD_CHAIN_URL=http://docker.for.mac.localhost:9656
- - ETHEREUM_NETWORK=LOCALCHAIN
- restart: always
- ports:
- - "9656:9656"
- healthcheck:
- test: curl docker.for.mac.localhost:9656
- interval: 10s
- timeout: 3s
- retries: 7
- depends_on:
- geth:
- condition: service_healthy
- contractexchanger:
- condition: service_healthy
-
- watcher:
- image: elixir-omg:dockercompose
- entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname watcher' -S mix xomg.watcher.start --convenience --config ~/config_watcher.exs "
- environment:
- - MIX_ENV=dev
- - ELIXIR_SERVICE=WATCHER
- - CONTRACT_EXCHANGER_URL=http://docker.for.mac.localhost:5000
- - ETHEREUM_RPC_URL=http://docker.for.mac.localhost:8545
- - CHILD_CHAIN_URL=http://docker.for.mac.localhost:9656
- - ETHEREUM_NETWORK=LOCALCHAIN
- - DATABASE_URL=postgres://omisego_dev:omisego_dev@docker.for.mac.localhost:5433/omisego_dev
- restart: always
- ports:
- - "7434:7434"
- healthcheck:
- test: curl docker.for.mac.localhost:7434
- interval: 5s
- timeout: 3s
- retries: 5
- depends_on:
- childchain:
- condition: service_healthy

diff:
-version: "2.1"
-services:
- geth:
- image: ethereum/client-go:v1.8.21
- entrypoint: /bin/sh -c "apk add curl && geth --targetgaslimit "6200000" --dev --dev.period 1 --rpc --rpcapi personal,web3,eth,net --rpcaddr 0.0.0.0 --rpcvhosts=* --rpcport=8545 --ws --wsorigins='*'"
- ports:
- - "8545:8545"
- network_mode: "host"
- healthcheck:
- test: curl localhost:8545
- interval: 5s
- timeout: 3s
- retries: 5
-
- contractexchanger:
- image: jakebunce/contractexchanger:v0.0.2
- ports:
- - "5000:5000"
- network_mode: "host"
- healthcheck:
- test: curl localhost:5000
- interval: 5s
- timeout: 3s
- retries: 5
- depends_on:
- geth:
- condition: service_healthy
-
- childchain:
- image: elixir-omg:dockercompose
- entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname childchain' -S mix xomg.child_chain.start --config ~/config.exs"
- environment:
- - MIX_ENV=dev
- - EXIT_PERIOD_SECONDS=86400
- - ELIXIR_SERVICE=CHILDCHAIN
- - CONTRACT_EXCHANGER_URL=http://localhost:5000
- - ETHEREUM_RPC_URL=http://localhost:8545
- - CHILD_CHAIN_URL=http://localhost:9656
- - ETHEREUM_NETWORK=LOCALCHAIN
- restart: always
- ports:
- - "9656:9656"
- network_mode: "host"
- healthcheck:
- test: curl localhost:9656
- interval: 7s
- timeout: 3s
- retries: 15
- depends_on:
- geth:
- condition: service_healthy
- contractexchanger:
- condition: service_healthy
-
- watcher:
- image: elixir-omg:dockercompose
- entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname watcher' -S mix xomg.watcher.start --convenience --config ~/config_watcher.exs"
- environment:
- - MIX_ENV=dev
- - ELIXIR_SERVICE=WATCHER
- - CONTRACT_EXCHANGER_URL=http://localhost:5000
- - ETHEREUM_RPC_URL=http://localhost:8545
- - CHILD_CHAIN_URL=http://localhost:9656
- - ETHEREUM_NETWORK=LOCALCHAIN
- - DATABASE_URL=postgres://omisego_dev:omisego_dev@localhost:5433/omisego_dev
- restart: always
- ports:
- - "7434:7434"
- network_mode: "host"
- healthcheck:
- test: curl localhost:7434
- interval: 5s
- timeout: 3s
- retries: 5
- depends_on:
- childchain:
- condition: service_healthy

diff:
-version: "2.1"
-services:
- watcher:
- image: omisego/watcher:latest
- command: "full_local"
- environment:
- - ETHEREUM_RPC_URL=https://rinkeby.infura.io/v3/<your_api_key>
- - ETHEREUM_WS_RPC_URL=wss://rinkeby.infura.io/ws/v3/<your_api_key>
- - CHILD_CHAIN_URL=http://samrong.omg.network
- - ETHEREUM_NETWORK=RINKEBY
- - RINKEBY_CONTRACT_ADDRESS=0x740ecec4c0ee99c285945de8b44e9f5bfb71eea7
- - RINKEBY_TXHASH_CONTRACT=0x29f8cd44b4b94a148f779105f0e09e06f762b411ebef6c499281b74d45818c1c
- - RINKEBY_AUTHORITY_ADDRESS=0x41863dafbdf8cfc2a33fc38c0b525b6343d857b3
- - DATABASE_URL=postgres://omisego_dev:omisego_dev@localhost:5433/omisego_dev
- - NODE_HOST=127.0.0.1
- restart: always
- ports:
- - "7434:7434"
- network_mode: "host"
- healthcheck:
- test: curl localhost:7434
- interval: 5s
- timeout: 3s
- retries: 5
- depends_on:
- postgres:
- condition: service_healthy

change_type: RENAME

diff:
@@ -7,20 +7,19 @@ services:
context: ./
dockerfile: Dockerfile.watcher
environment:
- - ETHEREUM_RPC_URL=https://rinkeby.infura.io/v3/<your_api_key>
- - ETHEREUM_WS_RPC_URL=wss://rinkeby.infura.io/ws/v3/<your_api_key>
+ - ETHEREUM_RPC_URL=https://rinkeby.infura.io/v3/${INFURA_API_KEY}
+ - ETHEREUM_WS_RPC_URL=wss://rinkeby.infura.io/ws/v3/${INFURA_API_KEY}
- CHILD_CHAIN_URL=http://samrong.omg.network
- ETHEREUM_NETWORK=RINKEBY
- RINKEBY_CONTRACT_ADDRESS=0x740ecec4c0ee99c285945de8b44e9f5bfb71eea7
- RINKEBY_TXHASH_CONTRACT=0x29f8cd44b4b94a148f779105f0e09e06f762b411ebef6c499281b74d45818c1c
- RINKEBY_AUTHORITY_ADDRESS=0x41863dafbdf8cfc2a33fc38c0b525b6343d857b3
- - DATABASE_URL=postgres://omisego_dev:omisego_dev@docker.for.mac.localhost:5433/omisego_dev
+ - DATABASE_URL=postgres://omisego_dev:omisego_dev@postgres:5432/omisego_dev
- NODE_HOST=127.0.0.1
ports:
- "7434:7434"
- network_mode: "host"
healthcheck:
- test: curl docker.for.mac.localhost:7434
+ test: curl watcher:7434
interval: 5s
timeout: 3s
retries: 5

diff:
version: "2.1"
services:
elixir-omg:
+ build: .
+ image: elixir-omg:dockercompose
environment:
DATABASE_URL: postgres://omisego_dev:omisego_dev@postgres:5432/omisego_dev
volumes:

diff:
version: "2.1"
services:
postgres:
- image: postgres
+ image: postgres:9.6.13-alpine
restart: always
ports:
- "5433:5432"
@@ -17,8 +17,89 @@ services:
elixir-omg:
build: .
image: elixir-omg:dockercompose
+
+ geth:
+ image: ethereum/client-go:v1.8.21
+ entrypoint: /bin/sh -c "apk add curl && geth --targetgaslimit "6200000" --dev --dev.period 1 --rpc --rpcapi personal,web3,eth,net --rpcaddr 0.0.0.0 --rpcvhosts=* --rpcport=8545 --ws --wsaddr 0.0.0.0 --wsorigins='*'"
+ ports:
+ - "8545:8545"
+ - "8546:8546"
+ expose:
+ - "8546"
+ - "8545"
+ healthcheck:
+ test: curl geth:8545
+ interval: 5s
+ timeout: 3s
+ retries: 5
+
+ contractexchanger:
+ image: jakebunce/contractexchanger:v0.0.2
+ ports:
+ - "5000:5000"
+ expose:
+ - "5000"
+ healthcheck:
+ test: curl contractexchanger:5000
+ interval: 5s
+ timeout: 3s
+ retries: 5
+ depends_on:
+ geth:
+ condition: service_healthy
+
+ childchain:
+ image: elixir-omg:dockercompose
+ entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname childchain' -S mix xomg.child_chain.start --config ~/config.exs"
+ environment:
+ - MIX_ENV=dev
+ - EXIT_PERIOD_SECONDS=86400
+ - ELIXIR_SERVICE=CHILDCHAIN
+ - CONTRACT_EXCHANGER_URL=http://contractexchanger:5000
+ - ETHEREUM_RPC_URL=http://geth:8545
+ - ETHEREUM_WS_RPC_URL=ws://geth:8546
+ - CHILD_CHAIN_URL=http://childchain:9656
+ - ETHEREUM_NETWORK=LOCALCHAIN
+ restart: always
+ ports:
+ - "9656:9656"
+ expose:
+ - "9656"
+ healthcheck:
+ test: curl childchain:9656
+ interval: 7s
+ timeout: 3s
+ retries: 15
depends_on:
+ geth:
+ condition: service_healthy
+ contractexchanger:
+ condition: service_healthy
+
+ watcher:
+ image: elixir-omg:dockercompose
+ entrypoint: /bin/bash -c "./launcher.py && elixir --erl '-sname watcher' -S mix xomg.watcher.start --convenience --config ~/config_watcher.exs"
+ environment:
+ - MIX_ENV=dev
+ - ELIXIR_SERVICE=WATCHER
+ - CONTRACT_EXCHANGER_URL=http://contractexchanger:5000
+ - ETHEREUM_RPC_URL=http://geth:8545
+ - ETHEREUM_WS_RPC_URL=ws://geth:8546
+ - CHILD_CHAIN_URL=http://childchain:9656
+ - ETHEREUM_NETWORK=LOCALCHAIN
+ - DATABASE_URL=postgres://omisego_dev:omisego_dev@postgres:5432/omisego_dev
+ restart: always
+ ports:
+ - "7434:7434"
+ expose:
+ - "7434"
+ healthcheck:
+ test: curl watcher:7434
+ interval: 5s
+ timeout: 3s
+ retries: 5
+ depends_on:
+ childchain:
+ condition: service_healthy
postgres:
condition: service_healthy
- links:
- - postgres


message: fix broken docker-compose-watcher.yml file

diff:
@@ -81,18 +81,18 @@ To bring the entire system up:
docker-compose up
```
-To bring only specific services up (eg: the childchain service):
+To bring only specific services up (eg: the childchain service, geth, etc...):
```sh
-docker-compose up childchain
+docker-compose up childchain geth ...
```
_(Note: This will also bring up any services childchain depends on.)_
-To override and run specific Watcher code use:
+To run a Watcher only, first make sure you sent an ENV variable called with `INFURA_API_KEY` with your api key and then run:
```sh
-docker-compose -f docker-compose.yml -f docker-compose-watcher.yml up
+docker-compose -f docker-compose-watcher.yml up
```
### Get the deployed contract details

diff:
version: "2.1"
services:
+ postgres:
+ image: postgres:9.6.13-alpine
+ restart: always
+ ports:
+ - "5433:5432"
+ environment:
+ POSTGRES_USER: omisego_dev
+ POSTGRES_PASSWORD: omisego_dev
+ POSTGRES_DB: omisego_dev
+ healthcheck:
+ test: pg_isready -U omisego_dev
+ interval: 5s
+ timeout: 3s
+ retries: 5
+
watcher:
image: omisego/watcher:latest
command: "full_local"
- build:
- context: ./
- dockerfile: Dockerfile.watcher
environment:
- ETHEREUM_RPC_URL=https://rinkeby.infura.io/v3/${INFURA_API_KEY}
- ETHEREUM_WS_RPC_URL=wss://rinkeby.infura.io/ws/v3/${INFURA_API_KEY}


message: updated run_local_watcher docs

diff:
@@ -10,11 +10,10 @@ The `docker-compose` tooling in the root of `elixir-omg` allows users to run the
### Startup
-1) Configure the environment variable `ETHEREUM_RPC_URL=https://rinkeby.infura.io/v3/<your_api_key>` with the RPC connection information
+1) Add an ENV variable `INFURA_API_KEY` to your environment or override the ETHEREUM_RPC_URL completely in the `docker-compose-watcher.yml` file with the RPC connection information.
2) From the root of the `elixir-omg` execute:
-- `docker-compose -f docker-compose.yml -f docker-compose-watcher-mac.yml up watcher postgres` (Mac)
-- `docker-compose -f docker-compose.yml -f docker-compose-watcher-non-mac.yml up watcher postgres` (Linux/Windows)
+- `docker-compose -f docker-compose-watcher.yml up`
Modify the other environment variables for connecting to other networks.

original_message: updated run_local_watcher docs


message: updated testing docs

diff:
@@ -402,12 +402,19 @@ mix deps.compile plasma_contracts
You can setup the docker environment to run testing and development tasks:
+(Note: If they exist, be sure to delete the `deps` and `_build` dirs from your host drive. Otherwise these dirs will get mapped into the docker container and can create build discrepancies and breakages.)
+
```sh
docker-compose -f docker-compose.yml -f docker-compose.dev.yml run --rm --entrypoint bash elixir-omg
```
Once the shell has loaded, you can continue and run additional tasks.
+Get the necessary dependencies for building:
+```bash
+mix deps.get
+```
+
Quick test (no integration tests):
```bash
mix test

original_message: updated testing docs