From b31bcaade0c2276e076a9e3bb112e9d0bcb42048 Mon Sep 17 00:00:00 2001
From: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 3 Jan 2022 17:00:36 +0100
Subject: node address

---
 draft-schanzen-r5n.xml | 110 ++++++++++++++++++++++++++-----------------------
 1 file changed, 59 insertions(+), 51 deletions(-)

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index d1039c3..6bd13ed 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -5,8 +5,8 @@
 <!ENTITY RFC3629 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
 <!ENTITY RFC3686 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3686.xml">
 <!ENTITY RFC3826 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3826.xml">
-<!-- <!ENTITY RFC3912 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3912.xml"> -->
 <!ENTITY RFC3986 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
+<!ENTITY RFC4634 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4634.xml">
 <!ENTITY RFC4648 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
 <!ENTITY RFC5869 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml">
 <!ENTITY RFC5890 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml">
@@ -240,7 +240,8 @@ Connectivity | |Underlay|  |Underlay|
      <t>
        In the DHT overlay, a node is addressable by its
        <tt>Node Address</tt>.
-       The <tt>Node Address</tt> is a 512-bit hash of the <tt>Node ID</tt>.
+       The <tt>Node Address</tt> is a SHA-512 hash <xref target="RFC4634"/>
+       of the <tt>Node ID</tt>.
        <!-- FIXME should the node ID be agile? Should the signature then
        also be agile?-->
        <!--The node public key is the public key of the corresponding
@@ -393,66 +394,72 @@ see how we can offer even the most minimal protections against node
        procedures and events:
      </t>
      <dl>
-       <dt>NODE_CONNECTED(NodeID, Address)</dt>
+       <dt><tt>PEER_CONNECTED(P)</tt></dt>
        <dd>
-         is a signal that allows the DHT to react to nodes which connect.
+         is a signal that allows the DHT to react to a newly connected peer
+         <tt>N</tt>.
          Such an event triggers, for example, updates in the
          routing table.
        </dd>
-       <dt>NODE_DISCONNECTED(NodeID, Address)</dt>
+       <dt><tt>PEER_DISCONNECTED(P)</tt></dt>
        <dd>
-         is a signal that allows the DHT to react to nodes which disconnect.
+         is a signal that allows the DHT to react to a recently disconnected
+         peer.
          Such an event triggers, for example, updates in the
          routing table.
        </dd>
-       <dt>TRY_CONNECT(NodeID, Address)</dt>
+       <dt><tt>TRY_CONNECT(N, A)</tt></dt>
        <dd>
-         A function which allows a node to attempt the establishment of
-         a connection to another node using an address.
+         A function which allows the local node to attempt the establishment of
+         a connection to another node <tt>N</tt> using an address <tt>A</tt>.
          When the connection attempt is successful, information on the new
-         peer is offered through the <tt>NODE_CONNECTED</tt> signal.
+         peer is offered through the <tt>PEER_CONNECTED</tt> signal.
        </dd>
-       <dt>HOLD(NodeID)</dt>
+       <dt><tt>HOLD(P)</tt></dt>
        <dd>
          A function which tells the underlay to keep a hold on the connection
-         to another node.
+         to a peer <tt>P</tt>. FIXME what is this needed for?
        </dd>
-       <dt>DROP(NodeID)</dt>
+       <dt><tt>DROP(P)</tt></dt>
        <dd>
-         A function which tells the underlay to drop the connection to another
-         node.
+         A function which tells the underlay to drop the connection to a
+           peer <tt>P</tt>. FIXME what is this needed for?
        </dd>
-       <dt>RECEIVE(NodeID, Message)</dt>
+       <dt><tt>RECEIVE(P, M)</tt></dt>
        <dd>
-         A function or event that allows the node to receive protocol
-         messages as defined in this document from a connected node.
+         A function or event that allows the local node to receive a protocol
+           message <tt>M</tt> as defined in this document from a peer <tt>P</tt>.
        </dd>
-       <dt>SEND(NodeID, Message)</dt>
+       <dt><tt>SEND(P, M)</tt></dt>
        <dd>
-         A function that allows a node to send protocol messages as defined
-         in this document to a connected node. If call to SEND fails,
-         the message has not been sent.
+         A function that allows the local node to send a protocol message
+         <tt>M</tt> as defined in this document to a peer <tt>P</tt>.
+         If call to SEND fails, the message has not been sent.
        </dd>
-       <dt>NETWORK_SIZE_ESTIMATE(N)</dt>
+       <dt><tt>NETWORK_SIZE_ESTIMATE(S)</tt></dt>
        <dd>
          A function or event that provides estimates on the network size
-         for use in the DHT routing algorithms.
+         <tt>S</tt> for use in the DHT routing algorithms.
+         FIXME: What is S and give an example.
        </dd>
-       <dt>ADDRESS_ADD(NodeID, address)</dt>
+       <dt><tt>ADDRESS_ADDED(A)</tt></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.
+         The underlay signals us that an address <tt>A</tt> was added for our
+         local node.
+         This information is used to advertise
+         connectivity information to the local node.
+         <tt>A</tt> is a string suitable for inclusion in a HELLO payload
+         <xref target="hello_block"/>.
        </dd>
-       <dt>ADDRESS_DELETE(NodeID, address)</dt>
+       <dt><tt>ADDRESS_DELETED(A)</tt></dt>
        <dd>
-         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.
+         The underlay signals us that an address <tt>A</tt> was removed.
+         This information is used, for example, to no longer advertise
+         this address.
        </dd>
-       <dt>VERIFY(blob)</dt>
+       <dt><tt>VERIFY(blob)</tt></dt>
        <dd>
-         Signature verification by underlay.
+         Signature verification by underlay. FIXME unclear. Required?
        </dd>
      </dl>
    </section>
@@ -543,14 +550,14 @@ see how we can offer even the most minimal protections against node
        the peer <tt>P</tt>.
        In the following, the wire formats of the messages and the required
        processing are detailed.
-       The local node ID is referred to as <tt>N</tt>.
+       The local node address is referred to as <tt>N</tt>.
      </t>
       <section anchor="p2p_bf" numbered="true" toc="default">
         <name>Bloomfilter</name>
         <t>
           In order to prevent circular routes, GET and PUT messages contain
           a 128-bit Bloom filter (m=128). The Bloom filter is used to detect duplicate
-          node IDs along the route.
+          node addresses along the route.
           A Bloom filter "bf" is initially empty, consisting only of zeroes.
           There are two functions which can be invoked on the Bloom filter:
           BF-SET(bf, e) and BF-TEST(bf, e) where "e" is an element which is to
@@ -659,7 +666,7 @@ END
        </dd>
        <dt>BLOOMFILTER</dt>
        <dd>
-         A bloomfilter (for node IDs) to stop circular routes.
+         A bloomfilter (for node addresses) to stop circular routes.
        </dd>
        <dt>KEY</dt>
        <dd>
@@ -669,7 +676,7 @@ END
        <dt>PUTPATH</dt>
        <dd>
          the variable-length PUT path.
-         The path consists of a list of PATH_LEN node IDs.
+         The path consists of a list of PATH_LEN node addresses.
        </dd>
        <dt>BLOCK</dt>
        <dd>
@@ -703,12 +710,12 @@ END
            it MUST be discarded.
          </li>
          <li>
-           The node ID of the sender peer <tt>P</tt> SHOULD be in <tt>BLOOMFILTER</tt>.
+           The node address of the sender peer <tt>P</tt> SHOULD be in <tt>BLOOMFILTER</tt>.
            If not, the implementation MAY log an error, but MUST continue.
          </li>
          <li>
            If the <tt>RecordRoute</tt> flag is set in OPTIONS,
-           the local node ID MUST be appended to the <tt>PUTPATH</tt>
+           the local node address MUST be appended to the <tt>PUTPATH</tt>
            of the message.
          </li>
          <li>
@@ -724,9 +731,9 @@ END
            number of peers to forward the message to. The implementation MAY
            forward to fewer or no peers in order to handle resource constraints
            such as bandwidth.
-           Finally, the local node ID MUST be added to the
+           Finally, the local node address MUST be added to the
            <tt>BLOOMFILTER</tt> of the forwarded message.
-           For all peers with node ID <tt>P</tt> chosen to forward the message
+           For all peers with node address <tt>P</tt> chosen to forward the message
            to, <tt>SEND(P, PutMessage)</tt> is called.
          </li>
        </ol>
@@ -832,7 +839,7 @@ END
              the message MUST be discarded.
            </li>
            <li>
-             The node ID of the sender peer <tt>P</tt> SHOULD be in the
+             The node address of the sender peer <tt>P</tt> SHOULD be in the
              BLOOMFILTER. If not, the
              implementation MAY log an error, but MUST continue.
            </li>
@@ -871,8 +878,9 @@ END
              number of nodes to forward the message to. The implementation MAY
              forward to fewer or no nodes in order to handle resource constraints
              such as bandwidth.
-               The message BLOOMFILTER MUST be updated with the local node ID <tt>N</tt>.
-             For all peers with node ID <tt>P'</tt> chosen to forward the message
+               The message BLOOMFILTER MUST be updated with the local node 
+             address <tt>N</tt>.
+             For all peers with node address <tt>P'</tt> chosen to forward the message
              to, <tt>SEND(P', PutMessage)</tt> is called.
            </li>
          </ol>
@@ -953,12 +961,12 @@ END
            <dt>PUTPATH</dt>
            <dd>
              the variable-length PUT path.
-             The path consists of a list of PATH_LEN node IDs.
+             The path consists of a list of PATH_LEN node addresses.
            </dd>
            <dt>GETPATH</dt>
            <dd>
              the variable-length PUT path.
-             The path consists of a list of PATH_LEN node IDs.
+             The path consists of a list of PATH_LEN node addresses.
            </dd>
            <dt>BLOCK</dt>
            <dd>
@@ -1210,16 +1218,16 @@ tor+onionv3://rasdflkjasdfliasduf.onion/
    <t>
      In order to find the closest nodes in the network to itself, an
      implementation MUST now periodically send HELLO GET queries for its own
-     node ID.
+     node address.
      Both the "record route" and "find node" message options are set in the
      GET queries in order to learn nodes and network topology from the
      message route and in order to receive approximate replies to the
-     query key (the node ID).
+     query key (the node address).
    </t>
    <t>FIXME: Periodically -> more specific? No. Frequency may be adapted depending on network conditions, known nodes, busy/idle etc.</t>
    <t>
      Any implementation encountering a HELLO GET request initially
-     sends its own node ID if it.
+     sends its own node address if it.
    </t>
  </section>
  <section anchor="security" numbered="true" toc="default">
@@ -1285,7 +1293,7 @@ Purpose | Name            | References | Description
 
        &RFC2119;
        &RFC3629;
-     <!--&RFC3986; URI-->
+       &RFC4634;
        &RFC4648;
        &RFC6940;
        &RFC8126;
-- 
cgit v1.2.3