From 3ee8d9f2cb15e5c9c3adffe0d25d1164d8c5eb5d Mon Sep 17 00:00:00 2001 From: Sergi Delgado Segura Date: Mon, 17 Feb 2020 13:06:19 +0100 Subject: [PATCH 1/4] Fixes common test imports --- test/common/unit/test_appointment.py | 2 +- test/common/unit/test_blob.py | 2 +- test/common/unit/test_encrypted_blob.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/test/common/unit/test_appointment.py b/test/common/unit/test_appointment.py index f83538f..9018505 100644 --- a/test/common/unit/test_appointment.py +++ b/test/common/unit/test_appointment.py @@ -6,7 +6,7 @@ from pytest import fixture from common.appointment import Appointment from common.encrypted_blob import EncryptedBlob -from test.pisa.unit.conftest import get_random_value_hex +from test.common.unit.conftest import get_random_value_hex from common.constants import LOCATOR_LEN_BYTES diff --git a/test/common/unit/test_blob.py b/test/common/unit/test_blob.py index 7172330..cf3e07f 100644 --- a/test/common/unit/test_blob.py +++ b/test/common/unit/test_blob.py @@ -1,7 +1,7 @@ from binascii import unhexlify from common.blob import Blob -from test.pisa.unit.conftest import get_random_value_hex +from test.common.unit.conftest import get_random_value_hex def test_init_blob(): diff --git a/test/common/unit/test_encrypted_blob.py b/test/common/unit/test_encrypted_blob.py index b977dbc..d67cfe1 100644 --- a/test/common/unit/test_encrypted_blob.py +++ b/test/common/unit/test_encrypted_blob.py @@ -1,5 +1,5 @@ from common.encrypted_blob import EncryptedBlob -from test.pisa.unit.conftest import get_random_value_hex +from test.common.unit.conftest import get_random_value_hex def test_init_encrypted_blob(): From 94eb763bacfe57c88b8081268d0cc34b58088f8c Mon Sep 17 00:00:00 2001 From: Sergi Delgado Segura Date: Mon, 17 Feb 2020 13:27:14 +0100 Subject: [PATCH 2/4] PISA server -> teos/tower/the eye of satoshi --- apps/cli/README.md | 36 +++++++++++++-------------- apps/cli/{PISA-API.md => tEOS-API.md} | 20 +++++++-------- 2 files changed, 28 insertions(+), 28 deletions(-) rename apps/cli/{PISA-API.md => tEOS-API.md} (66%) diff --git a/apps/cli/README.md b/apps/cli/README.md index 0e5c825..429549d 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -1,6 +1,6 @@ # wt_cli -`wt_cli` is a command line interface to interact with the PISA WatchTower server, written in Python3. +`wt_cli` is a command line interface to interact with the Eye of Satoshi watchtower server, written in Python3. ## Dependencies Refer to [DEPENDENCIES.md](DEPENDENCIES.md) @@ -23,13 +23,13 @@ Refer to [INSTALL.md](INSTALL.md) The command line interface has, currently, three commands: -- `add_appointment`: registers a json formatted appointment to the PISA server. -- `get_appointment`: gets json formatted data about an appointment from the PISA server. +- `add_appointment`: registers a json formatted appointment to 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. ### add_appointment -This command is used to register appointments to the PISA server. Appointments **must** be `json` encoded, and match the following format: +This command is used to register appointments to the watchtower. Appointments **must** be `json` encoded, and match the following format: { "tx": tx, "tx_id": tx_id, @@ -37,15 +37,15 @@ This command is used to register appointments to the PISA server. Appointments * "end_time": e, "to_self_delay": d } -`tx` **must** be the raw penalty transaction that will be encrypted before sent to the PISA server. `type(tx) = hex encoded str` +`tx` **must** be the raw penalty transaction that will be encrypted before sent to the watchtower. `type(tx) = hex encoded str` `tx_id` **must** match the **commitment transaction id**, and will be used to encrypt the **penalty transaction** and **generate the locator**. `type(tx_id) = hex encoded str` -`s` is the time when the PISA server will start watching your transaction, and will normally match to whenever you will be offline. `s` is measured in block height, and must be **higher than the current block height**. `type(s) = int` +`s` is the time when the watchtower will start watching your transaction, and will normally match to whenever you will be offline. `s` is measured in block height, and must be **higher than the current block height**. `type(s) = int` -`e` is the time where the PISA server 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` +`e` is the time where the watchtower 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` -`d` is the time PISA 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 to\_self\_delay does not match the `OP_CSV`, PISA will 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` +`d` is the time the watchtower 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 to\_self\_delay does not match the `OP_CSV`, the watchtower will 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 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. @@ -68,13 +68,13 @@ if `-f, --file` **is** specified, then the command expects a path to a json file ### get_appointment - This command is used to get information about an specific appointment from the PISA server. + This command is used to get information about an specific appointment from the Eye of Satoshi. **Appointment can be in three states:** -- `not_found`: meaning the locator is not recognised by the tower. This can either mean the locator is wrong, or the appointment has already been fulfilled (the PISA server does not keep track of completed appointments for now). -- `being_watched`: the appointment has been accepted by the PISA 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 broadcast. -- `dispute_responded`: the dispute was found by the watcher and the corresponding penalty transaction has been broadcast by the node. In this stage PISA is actively monitoring until the penalty transaction reaches enough confirmations and making sure no fork occurs in the meantime. +- `not_found`: meaning the locator is not recognised by the tower. This can either mean the locator is wrong, or the appointment has already been fulfilled (the tower does not keep track of completed appointments for now). +- `being_watched`: the appointment has been accepted by the tower 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 broadcast. +- `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. **Response formats** @@ -120,7 +120,7 @@ or ## Example -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 PISA API. +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. ``` echo '{"tx": "4615a58815475ab8145b6bb90b1268a0dbb02e344ddd483f45052bec1f15b1951c1ee7f070a0993da395a5ee92ea3a1c184b5ffdb2507164bf1f8c1364155d48bdbc882eee0868ca69864a807f213f538990ad16f56d7dfb28a18e69e3f31ae9adad229e3244073b7d643b4597ec88bf247b9f73f301b0f25ae8207b02b7709c271da98af19f1db276ac48ba64f099644af1ae2c90edb7def5e8589a1bb17cc72ac42ecf07dd29cff91823938fd0d772c2c92b7ab050f8837efd46197c9b2b3f", "tx_id": "0b9510d92a50c1d67c6f7fc5d47908d96b3eccdea093d89bcbaf05bcfebdd951", "start_time": 0, "end_time": 0, "to_self_delay": 20}' > dummy_appointment_data.json @@ -128,20 +128,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. -2. Send the appointment to the PISA API. Which will then start monitoring for matching transactions. +2. Send the appointment to the tower API. Which will then start monitoring for matching transactions. ``` python wt_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 PISA. + This returns a appointment locator that can be used to get updates about this appointment from the tower. -3. Test that PISA is still watching the appointment by replacing the appointment locator received into the following command: +3. Test that the tower is still watching the appointment by replacing the appointment locator received into the following command: ``` python wt_cli.py get_appointment ``` -## PISA API +## 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 [PISA-API.md](PISA-API.md). +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). diff --git a/apps/cli/PISA-API.md b/apps/cli/tEOS-API.md similarity index 66% rename from apps/cli/PISA-API.md rename to apps/cli/tEOS-API.md index a95697f..b3d78bd 100644 --- a/apps/cli/PISA-API.md +++ b/apps/cli/tEOS-API.md @@ -1,8 +1,8 @@ -## PISA-API +## tEOS-API ### Disclaimer: Everything in here is experimental and subject to change. -The PISA REST API consists, currently, of two endpoints: `/` and `/get_appointment` +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: @@ -13,11 +13,11 @@ 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 PISA server 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 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 PISA server 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 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 PISA 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 `, PISA 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 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: @@ -45,15 +45,15 @@ The alpha release does not have authentication, payments nor rate limiting, ther # Get appointment -`/get_appointment` is an endpoint provided to check the status of the appointments sent to PISA. 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: +`/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://pisa_server:pisa_port/get_appointment?locator=appointment_locator` +`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 PISA 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 PISA is actively monitoring until the penalty transaction reaches enough confirmations and making sure no fork occurs in the meantime. +- `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 @@ -91,6 +91,6 @@ In the above scenario, Bob can hire our service with a bad encrypted blob for th ### Data persistence -PISA 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. +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. From 6970e74da5103bf8e50d51912bda209937818ec7 Mon Sep 17 00:00:00 2001 From: Sergi Delgado Segura Date: Mon, 17 Feb 2020 14:16:58 +0100 Subject: [PATCH 3/4] Fixes outdated messages --- apps/cli/help.py | 8 ++++---- apps/cli/wt_cli.py | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/apps/cli/help.py b/apps/cli/help.py index 030c327..cd32245 100644 --- a/apps/cli/help.py +++ b/apps/cli/help.py @@ -1,11 +1,11 @@ def help_add_appointment(): return ( "NAME:" - "\tpython wt_cli add_appointment - Registers a json formatted appointment to the PISA server." + "\tpython wt_cli add_appointment - Registers a json formatted appointment to the tower." "\n\nUSAGE:" "\tpython wt_cli add_appointment [command options] appointment/path_to_appointment_file" "\n\nDESCRIPTION:" - "\n\n\tRegisters a json formatted appointment to the PISA server." + "\n\n\tRegisters a json formatted appointment to the tower." "\n\tif -f, --file *is* specified, then the command expects a path to a json file instead of a json encoded " "\n\tstring as parameter." "\n\nOPTIONS:" @@ -17,9 +17,9 @@ def help_add_appointment(): def help_get_appointment(): return ( "NAME:" - "\tpython wt_cli get_appointment - Gets json formatted data about an appointment from the PISA server." + "\tpython wt_cli get_appointment - Gets json formatted data about an appointment from the tower." "\n\nUSAGE:" "\tpython wt_cli get_appointment appointment_locator" "\n\nDESCRIPTION:" - "\n\n\tGets json formatted data about an appointment from the PISA server.\n" + "\n\n\tGets json formatted data about an appointment from the tower.\n" ) diff --git a/apps/cli/wt_cli.py b/apps/cli/wt_cli.py index 0f10733..bafc7ef 100644 --- a/apps/cli/wt_cli.py +++ b/apps/cli/wt_cli.py @@ -376,9 +376,9 @@ def show_usage(): "\n\tget_appointment \tGets json formatted data about an appointment from the PISA server." "\n\thelp \t\t\tShows a list of commands or help for a specific command." "\n\nGLOBAL OPTIONS:" - "\n\t-s, --server \tAPI server where to send the requests. Defaults to btc.pisa.watch (modifiable in " - "__init__.py)" - "\n\t-p, --port \tAPI port where to send the requests. Defaults to 9814 (modifiable in __init__.py)" + "\n\t-s, --server \tAPI server where to send the requests. Defaults to https://teos.pisa.watch (modifiable in " + "config.py)" + "\n\t-p, --port \tAPI port where to send the requests. Defaults to 443 (modifiable in conf.py)" "\n\t-d, --debug \tshows debug information and stores it in wt_cli.log" "\n\t-h --help \tshows this message." ) From 3cfe3edfa9c654576558235d33f22cc2156783c8 Mon Sep 17 00:00:00 2001 From: Sergi Delgado Segura Date: Mon, 17 Feb 2020 15:52:10 +0100 Subject: [PATCH 4/4] Typos and PISA-> teos --- apps/cli/README.md | 2 +- apps/cli/wt_cli.py | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/cli/README.md b/apps/cli/README.md index 429549d..1f1f023 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -53,7 +53,7 @@ The API will return a `application/json` HTTP response code `200/OK` if the appo 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`. +- `end_time` cannot be bigger than (roughly) a month. That is `4320` blocks on top of `start_time`. - `encrypted_blob`s are limited to `2 kib`. diff --git a/apps/cli/wt_cli.py b/apps/cli/wt_cli.py index bafc7ef..a0fa971 100644 --- a/apps/cli/wt_cli.py +++ b/apps/cli/wt_cli.py @@ -165,7 +165,7 @@ def add_appointment(args): logger.error("The returned appointment's signature is invalid") return False - logger.info("Appointment accepted and signed by PISA") + logger.info("Appointment accepted and signed by the Eye of Satoshi") # All good, store appointment and signature return save_appointment_receipt(appointment.to_dict(), signature) @@ -232,18 +232,18 @@ def post_appointment(data): None otherwise. """ - logger.info("Sending appointment to PISA") + logger.info("Sending appointment to the Eye of Satoshi") try: add_appointment_endpoint = "{}:{}".format(pisa_api_server, pisa_api_port) return requests.post(url=add_appointment_endpoint, json=json.dumps(data), timeout=5) except ConnectTimeout: - logger.error("Can't connect to PISA API. Connection timeout") + logger.error("Can't connect to the Eye of Satoshi's API. Connection timeout") return None except ConnectionError: - logger.error("Can't connect to PISA API. Server cannot be reached") + logger.error("Can't connect to the Eye of Satoshi's API. Server cannot be reached") return None except requests.exceptions.InvalidSchema: @@ -353,11 +353,11 @@ def get_appointment(locator): return r.json() except ConnectTimeout: - logger.error("Can't connect to PISA API. Connection timeout") + logger.error("Can't connect to the Eye of Satoshi's API. Connection timeout") return None except ConnectionError: - logger.error("Can't connect to PISA API. Server cannot be reached") + logger.error("Can't connect to the Eye of Satoshi's API. Server cannot be reached") return None except requests.exceptions.InvalidSchema: @@ -372,8 +372,8 @@ def show_usage(): "USAGE: " "\n\tpython wt_cli.py [global options] command [command options] [arguments]" "\n\nCOMMANDS:" - "\n\tadd_appointment \tRegisters a json formatted appointment to the PISA server." - "\n\tget_appointment \tGets json formatted data about an appointment from the PISA server." + "\n\tadd_appointment \tRegisters a json formatted appointment with the tower." + "\n\tget_appointment \tGets json formatted data about an appointment from the tower." "\n\thelp \t\t\tShows a list of commands or help for a specific command." "\n\nGLOBAL OPTIONS:" "\n\t-s, --server \tAPI server where to send the requests. Defaults to https://teos.pisa.watch (modifiable in "