commit 5f42dddc2fed3a488be44f0317da77692ce91dfa
parent 9c8096bc033985fdfb1247a2275ced82253bc8c9
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Fri, 23 Dec 2022 18:14:26 +0900
Reorder terminology alphabetically
Diffstat:
1 file changed, 80 insertions(+), 78 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -156,108 +156,76 @@
when, they appear in all capitals, as shown here.
</t>
</section>
- <section>
- <name>Structure of This Document</name>
- <t>
- <xref target="terminology"/> gives an overview of the terminology used in
- this document.
- <xref target="architecture"/> then describes the overall architecture and
- the scope of this specification.
- <xref target="overlay"/> describes the application API, which clarifies
- the semantics provided by R<sup>5</sup>N for applications
- and thus is crucial as it motivates the rest of the design.
- <xref target="underlay"/> describes the underlay interface. This is the
- abstraction that applications must provide to R<sup>5</sup>N
- and thus a prerequisite for using the DHT.
- Before a DHT is usable, it must be bootstrapped.
- Bootstrapping is described in <xref target="bootstrapping"/>.
- Bloom filters, a key data structure used in various
- places, are introduced in <xref target="bloom_filters" />
- The central operation of a DHT is routing, which is
- detailed in <xref target="routing"/>. The processing of the various
- network messages is described in <xref target="p2p_messages"/>. Handling
- of Blocks, including validation and storage are described
- in <xref target="blockstorage"/>. General security considerations are detailed
- in <xref target="security" />. IANA and GANA registry updates are listed
- in <xref target="iana" /> and <xref target="gana"/>. The document concludes with test
- vectors in <xref target="testvectors"/> and appendices with references.
- </t>
- </section>
- </section>
- <section anchor="terminology">
+ <section anchor="terminology">
<name>Terminology</name>
<dl>
- <dt>Peer:</dt>
- <dd>
- A host that is participating in the overlay. Peers are
- responsible for holding some portion of the data that has been
- stored in the overlay, and they are responsible for routing
- messages on behalf of other hosts as needed by the Routing
- Algorithm.
- </dd>
- <dt>Peer ID:</dt>
- <dd>
- The <tt>Peer ID</tt> is the public key which is used to authenticate
- a peer in the underlay.
- The Peer ID is the public key of the corresponding
- Ed25519<xref target="ed25519" /> peer private key.
-
- </dd>
- <dt>Peer Address:</dt>
- <dd>
- The <tt>Peer Address</tt> is the identifier used on the Overlay
- to address a peer.
- It is a SHA-512 hash of the <tt>Peer ID</tt>.
- </dd>
- <dt>Key</dt>
+ <dt>Applications</dt>
<dd>
- 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
- stored under the same key. <tt>Peer Addresses</tt> are valid keys.
+ Applications are components which directly use the DHT overlay
+ interfaces. Possible applications include the GNU Name System
+ <xref target="I-D.draft-schanzen-gns"/> and the CADET transport system
+ <xref target="cadet"/>.
</dd>
- <dt>Neighbor:</dt>
+ <dt>Application API</dt>
<dd>
- A neighbor is a peer which is directly able to communicate
- with our peer via the <tt>Underlay Interface</tt>.
+ The application API exposes the core operations of the DHT overlay
+ to applications.
+ This includes storing blocks in the DHT and retrieving blocks from the DHT.
</dd>
- <dt>Block:</dt>
+ <dt>Block</dt>
<dd>
Variable-size unit of payload stored in the DHT
under a <tt>Key</tt>. Commonly also called a "value" when talking
about a DHT as a "key-value store".
</dd>
+ <dt>Block Storage</dt>
+ <dd>
+ The <tt>Block Storage</tt> component is used to persist and manage
+ <tt>Block</tt> data by peers.
+ It includes logic for enforcing storage quotas, caching strategies and
+ data validation.
+ </dd>
<dt>Block-Type:</dt>
<dd>
A unique 32-bit value identifying the data format of a <tt>Block</tt>.
- Block-Types are either private or allocated by GANA (see <xref target="gana"/>).
+ Block-Types are either private or allocated by GANA (see
+ <xref target="gana"/>).
</dd>
- <dt>Block Storage</dt>
+ <dt>Key</dt>
<dd>
- The <tt>Block Storage</tt> component is used to persist and manage <tt>Block</tt> data
- by peers. It includes logic for enforcing storage quotas, caching strategies and
- data validation.
+ 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
+ stored under the same key. <tt>Peer Addresses</tt> are valid keys.
</dd>
- <dt>Responsible Peer:</dt>
+ <dt>Message Processing</dt>
<dd>
- The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as defined by
- the <tt>SelectClosestPeer(K, P)</tt> algorithm (see <xref target="routing"/>.
+ The Message Processing component processes requests from and
+ generates responses to applications and the underlay network.
</dd>
- <dt>Applications</dt>
+ <dt>Neighbor</dt>
<dd>
- Applications are components which directly use the DHT overlay
- interfaces. Possible applications include the GNU Name System
- <xref target="I-D.draft-schanzen-gns"/> and the CADET transport system
- <xref target="cadet"/>.
+ A neighbor is a peer which is directly able to communicate
+ with our peer via the <tt>Underlay Interface</tt>.
</dd>
- <dt>Application API</dt>
+ <dt>Peer</dt>
<dd>
- The application API exposes the core operations of the DHT overlay
- to applications.
- This includes storing blocks in the DHT and retrieving blocks from the DHT.
+ A host that is participating in the overlay. Peers are
+ responsible for holding some portion of the data that has been
+ stored in the overlay, and they are responsible for routing
+ messages on behalf of other hosts as needed by the Routing
+ Algorithm.
</dd>
- <dt>Message Processing</dt>
+ <dt>Peer Address</dt>
<dd>
- The Message Processing component processes requests from and
- generates responses to applications and the underlay network.
+ The <tt>Peer Address</tt> is the identifier used on the Overlay
+ to address a peer.
+ It is a SHA-512 hash of the <tt>Peer ID</tt>.
+ </dd>
+ <dt>Peer ID</dt>
+ <dd>
+ The <tt>Peer ID</tt> is the public key which is used to authenticate
+ a peer in the underlay.
+ The Peer ID is the public key of the corresponding
+ Ed25519<xref target="ed25519" /> peer private key.
</dd>
<dt>Routing</dt>
<dd>
@@ -265,6 +233,12 @@
routing and peer selection logic. It facilitates the R<sup>5</sup>N routing
algorithm with required data structures and algorithms.
</dd>
+ <dt>Responsible Peer</dt>
+ <dd>
+ The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as
+ defined by the <tt>SelectClosestPeer(K, P)</tt> algorithm (see
+ <xref target="routing"/>.
+ </dd>
<dt>Underlay Interface</dt>
<dd>
The Underlay Interface is an abstraction layer on top of the
@@ -273,6 +247,34 @@
TCP, UDP and TLS or advanced protocols such as GNUnet, I2P or Tor.
</dd>
</dl>
+ </section>
+ <section>
+ <name>Structure of This Document</name>
+ <t>
+ <xref target="terminology"/> gives an overview of the terminology used in
+ this document.
+ <xref target="architecture"/> then describes the overall architecture and
+ the scope of this specification.
+ <xref target="overlay"/> describes the application API, which clarifies
+ the semantics provided by R<sup>5</sup>N for applications
+ and thus is crucial as it motivates the rest of the design.
+ <xref target="underlay"/> describes the underlay interface. This is the
+ abstraction that applications must provide to R<sup>5</sup>N
+ and thus a prerequisite for using the DHT.
+ Before a DHT is usable, it must be bootstrapped.
+ Bootstrapping is described in <xref target="bootstrapping"/>.
+ Bloom filters, a key data structure used in various
+ places, are introduced in <xref target="bloom_filters" />
+ The central operation of a DHT is routing, which is
+ detailed in <xref target="routing"/>. The processing of the various
+ network messages is described in <xref target="p2p_messages"/>. Handling
+ of Blocks, including validation and storage are described
+ in <xref target="blockstorage"/>. General security considerations are detailed
+ in <xref target="security" />. IANA and GANA registry updates are listed
+ in <xref target="iana" /> and <xref target="gana"/>. The document concludes with test
+ vectors in <xref target="testvectors"/> and appendices with references.
+ </t>
+ </section>
</section>
<section anchor="architecture" numbered="true" toc="default">
<name>Architecture</name>
