update naming

1 files changed, 47 insertions, 11 deletions

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 9d7acc5..1d78c5b 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -160,7 +160,27 @@ Y924NSHMMZ1N1SQCE5TXF93ED6S6JY311K0QT86G9WJC68F6XVZ0 \
         tor+onionv3://rasdflkjasdfliasduf.onion/
          ]]></artwork>
      </figure>
+     <!--
+       1) The current API is always fire+forget, it doesn't allow for flow
+       control. I think we need to add that, possibly for sending and receiving.
 
+       IDK.
+
+2) I'm not sure what to do with the crypto: mandate EdDSA or allow the
+       underlay to do whatever public keys it likes.
+
+       We need keys in the overlay. (Path signatures). Do they need to
+       be the same keys???
+
+3) I think we may want to mandate that the lower layer at least
+authenticate the other peer (i.e. every UDP message could be in
+cleartext, but would need to come with an EdDSA signature, alas 92 byte
+overhead and a signature verification _required_).  Otherwise, I don't
+see how we can offer even the most minimal protections against peer
+       impersonation attacks. WDYT?
+
+       Security considerations? Prerequisites?
+     -->
      <t>
        It is expected that there are basic mechanisms available to
        manage peer connectivity and addressing.
@@ -168,49 +188,65 @@ Y924NSHMMZ1N1SQCE5TXF93ED6S6JY311K0QT86G9WJC68F6XVZ0 \
        procedures and events:
      </t>
      <dl>
-       <dt>PEER_CONNECTED(pk,address)</dt>
+       <dt>PEER_CONNECTED(phash,address)</dt>
        <dd>
          is a signal that allows the DHT to react to peers which connect.
          Such an event triggers, for example, updates in the
          routing table.
        </dd>
-       <dt>PEER_DISCONNECTED(pk,address)</dt>
+       <dt>PEER_DISCONNECTED(phash,address)</dt>
        <dd>
          is a signal that allows the DHT to react to peers which disconnect.
          Such an event triggers, for example, updates in the
          routing table.
        </dd>
-       <dt>CONNECT(address)</dt>
+       <dt>TRY_CONNECT(pid, address)</dt>
        <dd>
          A function which allows a peer to attempt the establishment of
          a connection to another peer using an address.
        </dd>
-       <dt>DISCONNECT(address)</dt>
+       <dt>HOLD(pash)</dt>
+       <dd>
+         A function which tells the underlay to keep a hold on the connection
+         to another peer.
+       </dd>
+       <dt>DROP(pash)</dt>
        <dd>
-         A function which allows a peer to disconnect from
-         another peer.
+         A function which tells the underlay to drop the connection to another
+         peer.
        </dd>
        <dt>RECEIVE(source, message)</dt>
        <dd>
          A function or event that allows the peer to receive protocol
          messages as defined in this document from a connected peer.
        </dd>
-       <dt>SEND(source?, target)</dt>
+       <dt>SEND(target, message)</dt>
        <dd>
          A function that allows a peer to send protocol messages as defined
-         in this document to a connected peer.
+         in this document to a connected peer. If call to SEND fails,
+         the message has not been sent.
        </dd>
        <dt>NETWORK_SIZE_ESTIMATE(N)</dt>
        <dd>
          A function or event that provides estimates on the network size
          for use in the DHT routing algorithms.
        </dd>
-       <dt>ADDRESS_CHANGED(pk, address)</dt>
+       <dt>ADDRESS_ADD(pk, address)</dt>
+       <dd>
+         The underlay signals us that an address was added.
+         This information is used, for example, to publish
+         connectivity as part of the bootstrapping and overlay creation.
+       </dd>
+       <dt>ADDRESS_DELETE(pk, address)</dt>
        <dd>
-         An event that allows the DHT to learn and react to address changes
-         of the peer. This information is used, for example, to publish
+         The underlay signals us that an address was removed.
+         This information is used, for example, to publish
          connectivity as part of the bootstrapping and overlay creation.
        </dd>
+       <dt>VERIFY(blob)</dt>
+       <dd>
+         Signature verification by underlay.
+       </dd>
      </dl>
    </section>
    <section anchor="routing" numbered="true" toc="default">