aljaz/python-teos
1
0
Fork 0
mirror of https://github.com/aljazceru/python-teos.git synced 2025-12-17 14:14:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

Adds register docs and removes API readme

Browse Source 
The TEOS-API README is no longer needed after open-sourcing the server
This commit is contained in:
Sergi Delgado Segura
2020-04-04 13:09:19 +02:00
parent 4a65b2524b
commit 7b4ea313c6
2 changed files with 53 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
cli/README.md
View File

@@ -21,15 +21,26 @@ Refer to [INSTALL.md](INSTALL.md)
#### Commands #### Commands
The command line interface has, currently, three commands: The command line interface has, currently, four commands:
- `add_appointment`: registers a json formatted appointment to the tower. - `register`: registers your user with the tower.
- `add_appointment`: sends a json formatted appointment to the tower.
- `get_appointment`: gets json formatted data about an appointment from the tower. - `get_appointment`: gets json formatted data about an appointment from the tower.
- `help`: shows a list of commands or help for a specific command. - `help`: shows a list of commands or help for a specific command.
### register
This commands serves as registration. It sends your public key to the tower to create a subscription (fee atm) and returns a number of available appointment slots in the tower. Toping up the subscription can be done by simply sending a register message again.
Notice that you need to be register before sending any other type of request to the tower.
#### Usage
python teos_cli.py register
### add_appointment ### add_appointment
This command is used to register appointments to the watchtower. Appointments **must** be `json` encoded, and match the following format: This command is used to send appointments to the watchtower. Appointments **must** be `json` encoded, and match the following format:
{ "tx": tx, { "tx": tx,
"tx_id": tx_id, "tx_id": tx_id,
@@ -79,26 +90,42 @@ if `-f, --file` **is** specified, then the command expects a path to a json file
**not_found** **not_found**
[{"locator": appointment_locator, {
"status":"not_found"}] "locator": l,
"status": "not_found"
}
**being_watched** **being_watched**
[{"encrypted_blob": eb, {
"locator": l,
"status": "being_watched",
"appointment":
{
"encrypted_blob": eb,
"end_time": e, "end_time": e,
"locator": appointment_locator, "locator": appointment_locator,
"start_time": s, "start_time": s,
"status": "being_watched", "status": "being_watched",
"to_self_delay": d}] "to_self_delay": d
}
}
**dispute_responded** **dispute_responded**
[{"appointment_end": e, {
"locator": l,
"status": "dispute_responded",
"appointment":
{
"appointment_end": e,
"dispute_txid": dispute_txid, "dispute_txid": dispute_txid,
"locator": appointment_locator, "locator": appointment_locator,
"penalty_rawtx": penalty_rawtx, "penalty_rawtx": penalty_rawtx,
"penalty_txid": penalty_txid, "penalty_txid": penalty_txid,
"status": "dispute_responded"}] "status": "dispute_responded"
}
}
#### Usage #### Usage
@@ -128,8 +155,13 @@ or
python teos_cli.py help command python teos_cli.py help command
## Example ## Example
1. Register with the tower.
1. Generate a new dummy appointment. **Note:** this appointment will never be fulfilled (it will eventually expire) since it does not corresopond to a valid transaction. However it can be used to interact with the Eye of Satoshi's API. ```
python teos_cli.py register
```
2. Generate a new dummy appointment. **Note:** this appointment will never be fulfilled (it will eventually expire) since it does not correspond to a valid transaction. However it can be used to interact with the Eye of Satoshi's API.
``` ```
echo '{"tx": "4615a58815475ab8145b6bb90b1268a0dbb02e344ddd483f45052bec1f15b1951c1ee7f070a0993da395a5ee92ea3a1c184b5ffdb2507164bf1f8c1364155d48bdbc882eee0868ca69864a807f213f538990ad16f56d7dfb28a18e69e3f31ae9adad229e3244073b7d643b4597ec88bf247b9f73f301b0f25ae8207b02b7709c271da98af19f1db276ac48ba64f099644af1ae2c90edb7def5e8589a1bb17cc72ac42ecf07dd29cff91823938fd0d772c2c92b7ab050f8837efd46197c9b2b3f", "tx_id": "0b9510d92a50c1d67c6f7fc5d47908d96b3eccdea093d89bcbaf05bcfebdd951", "start_time": 0, "end_time": 0, "to_self_delay": 20}' > dummy_appointment_data.json echo '{"tx": "4615a58815475ab8145b6bb90b1268a0dbb02e344ddd483f45052bec1f15b1951c1ee7f070a0993da395a5ee92ea3a1c184b5ffdb2507164bf1f8c1364155d48bdbc882eee0868ca69864a807f213f538990ad16f56d7dfb28a18e69e3f31ae9adad229e3244073b7d643b4597ec88bf247b9f73f301b0f25ae8207b02b7709c271da98af19f1db276ac48ba64f099644af1ae2c90edb7def5e8589a1bb17cc72ac42ecf07dd29cff91823938fd0d772c2c92b7ab050f8837efd46197c9b2b3f", "tx_id": "0b9510d92a50c1d67c6f7fc5d47908d96b3eccdea093d89bcbaf05bcfebdd951", "start_time": 0, "end_time": 0, "to_self_delay": 20}' > dummy_appointment_data.json
@@ -137,24 +169,20 @@ or
That will create a json file that follows the appointment data structure filled with dummy data and store it in `dummy_appointment_data.json`. **Note**: You'll need to update the `start_time` and `end_time` to match valid block heights. That will create a json file that follows the appointment data structure filled with dummy data and store it in `dummy_appointment_data.json`. **Note**: You'll need to update the `start_time` and `end_time` to match valid block heights.
2. Send the appointment to the tower API. Which will then start monitoring for matching transactions. 3. Send the appointment to the tower API. Which will then start monitoring for matching transactions.
``` ```
python teos_cli.py add_appointment -f dummy_appointment_data.json python teos_cli.py add_appointment -f dummy_appointment_data.json
``` ```
This returns a appointment locator that can be used to get updates about this appointment from the tower. This returns an appointment locator that can be used to get updates about this appointment from the tower.
3. Test that the tower is still watching the appointment by replacing the appointment locator received into the following command: 4. Test that the tower is still watching the appointment by replacing the appointment locator received into the following command:
``` ```
python teos_cli.py get_appointment <appointment_locator> python teos_cli.py get_appointment <appointment_locator>
``` ```
## the Eye of Satoshi's API
If you wish to read about the underlying API, and how to write your own tool to interact with it, refer to [tEOS-API.md](TEOS-API.md).
## Try our live instance ## Try our live instance
By default, `teos_cli` will connect to your local instance (running on localhost). There are also a couple of live instances running, one for mainet and one for testnet: By default, `teos_cli` will connect to your local instance (running on localhost). There are also a couple of live instances running, one for mainet and one for testnet:

95
cli/TEOS-API.md
View File

@@ -1,95 +0,0 @@
## TEOS-API
### Disclaimer: Everything in here is experimental and subject to change.
The Eye of Satoshi's REST API consists, currently, of two endpoints: `/` and `/get_appointment`
`/` is the default endpoint, and is where the appointments should be sent to. `/` accepts `HTTP POST` requests only, with json request body, where data must match the following format:
{"locator": l, "start_time": s, "end_time": e,
"to_self_delay": d, "encrypted_blob": eb}
We'll discuss the parameters one by one in the following:
The locator, `l`, is the first half of the **dispute transaction id** (i.e. the 16 MSB of the dispute_txid encoded in hex). `type(l) = hex encoded str`
The start\_time, `s`, is the time when the tower will start watching your transaction, and will normally match with whenever you will be offline. `s` is measured in block height, and must be **higher than the current block height**. `type(s) = int`
The end\_time, `e`, is the time where the tower will stop watching your transaction, and will normally match with whenever you should be back online. `e` is also measured in block height, and must be **higher than** `s`. `type(e) = int`
The to\_self\_delay, `d`, is the time the tower would have to respond with the **penalty transaction** once the **dispute transaction** is seen in the blockchain. `d` must match with the `OP_CSV` specified in the dispute transaction. If the dispute_delta does not match the `OP_CSV `, the tower would try to respond with the penalty transaction anyway, but success is not guaranteed. `d` is measured in blocks and should be, at least, `20`. `type(d) = int`
The encrypted\_blob, `eb`, is a data blob containing the `raw penalty transaction` and it is encrypted using `CHACHA20-POLY1305`. The `encryption key` used by the cipher is the sha256 of the **dispute transaction id**, and the `nonce` is a 12-byte long zero byte array:
sk = sha256(unhexlify(secret)).digest()
nonce = bytearray(12) # b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
Finally, the encrypted blob must be hex encoded. `type(eb) = hex encoded str`
The API will return a `application/json` HTTP response code `200/OK` if the appointment is accepted, with the locator encoded in the response text, or a `400/Bad Request` if the appointment is rejected, with the rejection reason encoded in the response text.
### Alpha release restrictions
The alpha release does not have authentication, payments nor rate limiting, therefore some self imposed restrictions apply:
- `start_time` should be within the next 6 blocks `[current_time+1, current_time+6]`.
- `end_time` cannot be bigger than (roughtly) a month. That is `4320` blocks on top of `start_time`.
#### Appointment example
{"locator": "3c3375883f01027e5ca14f9760a8b853824ca4ebc0258c00e7fae4bae2571a80",
"start_time": 1568118,
"end_time": 1568120,
"to_self_delay": 20,
"encrypted_blob": "6c7687a97e874363e1c2b9a08386125e09ea000a9b4330feb33a5c698265f3565c267554e6fdd7b0544ced026aaab73c255bcc97c18eb9fa704d9cc5f1c83adaf921de7ba62b2b6ddb1bda7775288019ec3708642e738eddc22882abf5b3f4e34ef2d4077ed23e135f7fe22caaec845982918e7df4a3f949cadd2d3e7c541b1dbf77daf64e7ed61531aaa487b468581b5aa7b1da81e2617e351c9d5cf445e3391c3fea4497aaa7ad286552759791b9caa5e4c055d1b38adfceddb1ef2b99e3b467dd0b0b13ce863c1bf6b6f24543c30d"}
# Get appointment
`/get_appointment` is an endpoint provided to check the status of the appointments sent to the tower. The endpoint is accessible without any type of authentication for now. `/get_appointment` accepts `HTTP GET` requests only, where the data to be provided must be the **locator** of an appointment. The query must match the following format:
`https://teos_server:teos_port/get_appointment?locator=appointment_locator`
**Appointment can be in three states**:
- `not_found`: meaning the locator is not recognised by the API. This could either mean the locator is wrong, or the appointment has already been fulfilled.
- `being_watched`: the appointment has been accepted by the tower server and it's being watched at the moment. This stage means that the dispute transaction has not been seen yet, and therefore no penalty transaction has been published.
- `dispute_responded`: the dispute was found by the watcher and the corresponding penalty transaction has been broadcast by the node. In this stage the tower is actively monitoring until the penalty transaction reaches enough confirmations and making sure no fork occurs in the meantime.
### Get appointment response formats
`/get_appointment` will always reply with `json` containing the information about the requested appointment. The structure is as follows:
**not_found**
[{"locator": appointment_locator,
"status":"not_found"}]
**being_watched**
[{"encrypted_blob": eb,
"end_time": e,
"locator": appointment_locator,
"start_time": s,
"status": "being_watched",
"to_self_delay": d}]
**dispute_responded**
[{"appointment_end": e,
"dispute_txid": dispute_txid,
"locator": appointment_locator,
"penalty_rawtx": penalty_rawtx,
"penalty_txid": penalty_txid,
"status": "dispute_responded"}]
Notice that the response json always contains a list. Why? It is possible for both parties to send the “same locator” to our service:
Alice wants to hire us to watch Bob’s commitment transaction.
Bob wants to front-run Alice by creating a job for his “commitment transaction” with a bad encrypted blob.
In the above scenario, Bob can hire our service with a bad encrypted blob for the locator that should be used by Alice. Our service will try to decrypt both encrypted blobs, find the valid transaction and send it out. More generally, this potential DoS attack is possible of locators are publicly known (i.e. other watching services).
### Data persistence
The Eye of Satoshi keeps track of the appointment while they are being monitored, but data is wiped once an appointment has been completed with enough confirmations. Notice that during the alpha there will be no authentication, so data may be wiped periodically.