update readme

README.md

@@ -1,3 +1,29 @@
 # clocktower
 
-meow meow meow
+clocktower is a python package implementing efficient strategies for executing adaptive timing side
+channel attacks. the goal is to use statistics to guide public input guesses in order to reveal the
+secret with a given level of statistical significance in a minimum number of rounds. the current
+strategy already significantly outperforms the naive non-adaptive strategy, and thus can be used as
+a framework for mounting attacks
+
+## howto
+
+currently the model is that a correct guess will result in a longer time taken to execute, and all
+incorrect guesses will take the same (lower) time to execute  
+more abstraction is planned for different target models
+
+```
+import clocktower
+
+# default input space: 0-255
+# default significance level: 0.01
+mgr = clocktower.ClocktowerManager()
+
+# when next_guess() returns None, the algoritm has a statistically significant answer
+while (guess := mgr.next_guess()) is not None:
+    # execute the guess and get the result
+    timing_value = run_attack(guess)
+    mgr.update(guess, timing_value)
+
+print(mgr.get_best_guess())
+```

clocktower/__init__.py

@@ -1,4 +1,4 @@
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, Optional, Tuple
 
 import numpy as np
 # import numpy.typing as npt

setup.py

@@ -6,7 +6,7 @@ with open("README.md", "r") as f:
 setup(
     name='clocktower',
     version='0.1',
-    description='Sample text',
+    description='optimal adaptive timing side channel attacks',
     long_description=long_description,
     long_description_content_type='text/markdown',
     url='https://awoo.systems',