1 files changed, 9 insertions, 4 deletions

diff --git a/src/btftunnel.h b/src/btftunnel.h
index 1fa4f01..24a7509 100644
--- a/src/btftunnel.h
+++ b/src/btftunnel.h
@@ -10,8 +10,12 @@
 // caller), then BtfClientTunnel connects through the relay, runs the echan
 // handshake, and returns a local SOCKET to hand a new outbound CNode.
 //
-// Service side: after RvServiceRegister pairs us with a client, BtfServiceWrap
-// completes the echan handshake and returns a local SOCKET for an inbound CNode.
+// Service side: RvServiceRegister only registers -- callers must then block in
+// RvServiceWaitPaired until a client is actually paired to them. BtfServiceWrap
+// completes the echan handshake on that paired socket and returns a local
+// SOCKET for an inbound CNode. Wrapping a registered-but-unpaired socket reads
+// the relay's 0x01 pairing byte as the first byte of the client's ephemeral
+// key, which silently corrupts the tunnel instead of failing.
 
 #ifndef BITFLASH_BTFTUNNEL_H
 #define BITFLASH_BTFTUNNEL_H
@@ -39,8 +43,9 @@ btf_socket_t BtfClientTunnel(const char* meeting_host, unsigned short port,
                              const unsigned char target_pubkey[32],
                              const unsigned char service_enc_pub[32]);
 
-// Service: wrap an already-paired rendezvous socket (from RvServiceRegister)
-// with echan using my static x25519 secret, returning a local plaintext SOCKET
+// Service: wrap an already-paired rendezvous socket (RvServiceRegister followed
+// by RvServiceWaitPaired -- the pairing byte MUST already be consumed) with
+// echan using my static x25519 secret, returning a local plaintext SOCKET
 // for an inbound CNode. Consumes `rv` (closed when the tunnel tears down).
 btf_socket_t BtfServiceWrap(RvSocket rv, const unsigned char my_enc_sk[32]);