lokinet/doc/dht_v0.txt

DHT messages

these messages can be either wrapped in a LIDM message or sent anonymously over a path

This document is currently out of date (probably)


find introduction message (FIM)

recursively find an IS by SA

{
  A: "F",
  I: 0 or 1 if iterative request,
  R: r_counter,
  S: "<32 bytes SA>",
  T: transaction_id_uint64,
  V: 0
}

Transactions will persist until replied to by a GIM or 60 seconds, whichever
is reached first.

If the timeout is reached before a GIM or the forwarding of the request fails:

* close transaction
* close linked transactions

if R is non-zero and less or equal to than 5:

* decrement R by 1
* open a transaction with id T for sender's RC.k
* pick random dht capable router, F
* generate new transaction id, U
* open a transaction with id U for F.k
* link transaction U to transaction T
* send FIM with transaction id U to F

if R is greater than 5 or less than 0:

* increment shitlist value of sender's RC.k by 1
* if the shitlist value for sender's RC.k is less than 10 reply with a GIM with
  an X
* if the shitlist value for sender's RC.k is equal to or greater than 10 drop
  the message

if R is zero and we have 1 or more IS at position S in dht keyspace:

* reply with a GIM holding the IS who contains the introducer with the highest
  expiration timestamp
 
if R is zero and we do not have any IS at position S in dht keyspace:

* find a router who's RC.k is closest to S, N

if N is our router:

* reply with a GIM with an empty X value

if N is not our router:

* open transaction with id T for sender's RC.k
* generate new transaction id, U
* open transaction with id U for N.k
* link transaction U to transaction T
* forward request to N using transaction id U


got introduction message (GIM)

{
  A: "G",
  I: [IS],
  T: transaction_id_uint64,
  V: 0,
}

if we have a transaction with id T:

* forward the GIM to all linked transactions
* terminate transaction T

when a linked transaction gets a GIM:

* set T to the current transaction id
* foward the GIM to the requester of T


publish introduction message (PIM)

publish one IS to the DHT.

version 0 uses the SA of the IS as the keyspace location.

in the future the location will be determined by the dht kdf
which uses a shared random source to obfuscate keyspace location.


R is currently set to 0 by the sender.

{
  A: "I",
  I: IS,
  R: r_counter,
  S: optional member 0 for immediate store otherwise non zero,
  T: transaction_id_uint64,
  V: 0
}

if R is greater than 0, do a random walk, otherwise if we are
closer to the SA of the IS than anyone else we know in the DHT 
store the IS for later lookup. 
As of protocol version 0, R is always 0.

If S is provided store the IS for later lookup unconditionally, 
decrement S by 1 and forward to dht peer who is next closest to 
the SA of the IS. If S is greater than 3, don't store and discard
this message.


find router contact message (FRCM)

find a router by long term RC.k public key

{
  A: "R",
  I: 0 or 1 if iterative lookup
  K: "<32 byte public key of router>",
  T: transaction_id_uint64,
  V: 0
}

TODO: document me

got router contact message (GRCM)

R is a list containing a single RC if found or is an empty list if not found
sent in reply to FRCM only

{
  A: "S",
  R: [RC],
  T: transaction_id_uint64,
  V: 0
}

* send a GRCM with R to requesters in all linked transactions
* terminate transaction with id T