From 27386c12484e771a3bf49e840478c17f2bc6334c Mon Sep 17 00:00:00 2001
From: Tim Ruffing <me@real-or-random.org>
Date: Tue, 1 Oct 2024 16:25:56 +0200
Subject: [PATCH] docstring: Improve docstring of hostpubkey_gen

---
 README.md                       | 22 +++++++++++++++-------
 python/chilldkg_ref/chilldkg.py | 22 +++++++++++++++-------
 2 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index a7f755d..e536c44 100644
--- a/README.md
+++ b/README.md
@@ -589,7 +589,15 @@ def hostpubkey_gen(hostseckey: bytes) -> bytes
 
 Compute the participant's host public key from the host secret key.
 
-This is the long-term cryptographic identity of the participant.
+The host public key is the long-term cryptographic identity of the
+participant.
+
+This function interprets `hostseckey` as big-endian integer, and computes
+the corresponding "plain" public key in compressed serialization (33 bytes,
+starting with 0x02 or 0x03). This is the key generation procedure
+traditionally used in Bitcoin, e.g., for ECDSA. In other words, this
+function is equivalent to `IndividualPubkey` as defined in [[BIP327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki#key-generation-of-an-individual-signer)].
+TODO Refer to the FROST signing BIP instead, once that one has a number.
 
 *Arguments*:
 
@@ -599,16 +607,16 @@ This is the long-term cryptographic identity of the participant.
   successful participant in a session can be recovered from (a backup
   of) the key and per-session recovery data.
 
-  The same secret key (and thus host public key) can be used in
-  multiple DKG sessions. A host public key can be correlated to the
-  threshold public key resulting from a DKG session only by parties
-  who observed the session, namely the participants, the coordinator
-  (and any eavesdropper).
+  The same host secret key (and thus the same host public key) can be
+  used in multiple DKG sessions. A host public key can be correlated
+  to the threshold public key resulting from a DKG session only by
+  parties who observed the session, namely the participants, the
+  coordinator (and any eavesdropper).
 
 
 *Returns*:
 
-  The host public key.
+  The host public key (33 bytes).
 
 
 *Raises*:
diff --git a/python/chilldkg_ref/chilldkg.py b/python/chilldkg_ref/chilldkg.py
index 0d94d0a..6c21034 100644
--- a/python/chilldkg_ref/chilldkg.py
+++ b/python/chilldkg_ref/chilldkg.py
@@ -126,7 +126,15 @@ def certeq_coordinator_step(sigs: List[bytes]) -> bytes:
 def hostpubkey_gen(hostseckey: bytes) -> bytes:
     """Compute the participant's host public key from the host secret key.
 
-    This is the long-term cryptographic identity of the participant.
+    The host public key is the long-term cryptographic identity of the
+    participant.
+
+    This function interprets `hostseckey` as big-endian integer, and computes
+    the corresponding "plain" public key in compressed serialization (33 bytes,
+    starting with 0x02 or 0x03). This is the key generation procedure
+    traditionally used in Bitcoin, e.g., for ECDSA. In other words, this
+    function is equivalent to `IndividualPubkey` as defined in [[BIP327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki#key-generation-of-an-individual-signer)].
+    TODO Refer to the FROST signing BIP instead, once that one has a number.
 
     Arguments:
         hostseckey: This participant's long-term secret key (32 bytes).
@@ -135,14 +143,14 @@ def hostpubkey_gen(hostseckey: bytes) -> bytes:
             successful participant in a session can be recovered from (a backup
             of) the key and per-session recovery data.
 
-            The same secret key (and thus host public key) can be used in
-            multiple DKG sessions. A host public key can be correlated to the
-            threshold public key resulting from a DKG session only by parties
-            who observed the session, namely the participants, the coordinator
-            (and any eavesdropper).
+            The same host secret key (and thus the same host public key) can be
+            used in multiple DKG sessions. A host public key can be correlated
+            to the threshold public key resulting from a DKG session only by
+            parties who observed the session, namely the participants, the
+            coordinator (and any eavesdropper).
 
     Returns:
-        The host public key.
+        The host public key (33 bytes).
 
     Raises:
         SecretKeyError: If the length of `hostseckey` is not 32 bytes.