REWORDME: [docs] node to node protocol.

rough draft outline of lokinet's node to node protocol.

docs/node2node.md

@@ -0,0 +1,105 @@
+# node to node messages
+
+
+[summary placeholder]
+
+(todo: fully describe pop and shift mechanism)
+(todo: calcuate optimal data sizes)
+
+
+## streamed requests
+
+direct node to node request/response messages sent on a bidi quic stream.
+
+the stream starts by sending 2 bytes identifying the stream kind of which there are the following:
+
+* network data lookup
+* network data upsert
+* path build
+* path update
+* path stream
+
+### network data lookup stream
+
+used for fetching of:
+
+* pubkey list with unlock times if they are applicable.
+* pubkey list delta given last hash of full list.
+* router contact by snode identity pubkey.
+* router contacts by operator wallet address.
+* look up wallet addresses staked into snode.
+* look up snodes staked by a wallet address.
+
+
+### network data upsert stream
+
+used to upsert (insert/update) records for:
+
+* gossiped router contacts.
+* encrypted introsets.
+* signed service descriptors. (aka the "exit market" metadata).
+
+
+### path builds
+
+#### path build request
+
+we have 8 path build records in a path build, we pop and shift the records and decrypt the record meant for us.
+
+the plainext record contains:
+
+* next hop's pubkey
+* path lifetime
+* signing pubkey used by the path creator to sign updates
+* encryption pubkey to generate shared secret at the path
+* additional extra fields used in the future.
+
+
+(todo: i want to permit multiple kinds of pubkeys for forwards compat)
+
+we could also add an additional list of nonces on the path build that lets us open multiple path streams as we build our path.
+given we provide N nonces in the build we are opening up N path streams as we make our path build. see the path streams section below.
+
+(todo: shrink tx/rx path id to be 8 bytes each?)
+
+#### path build result
+
+(todo: finish this)
+
+### path streams
+
+onion routed persisting stream connection to the pivot router for sending anonymised requests destined for the pivot router.
+
+streams are created for an existing path by opening a "path stream" stream providing the path's tx/rx id and 24 bytes nonce.
+on accepting the stream creation the node will open a "path stream" to their upstream router but with a nonce that is deterministically mutated `new_nonce = nonce ^ hash(nonce)`, this mutation reduces stream corrilation across hops.
+on rejecting the stream creation the node will shutdown the read end of the stream, sending a reply signed by our identity key and then shutting down the write end of the stream (which fully closes the stream).
+if the accepting node is the pivot route it will write. 
+
+a "request stream path result" message has a flag for the result, zero for success and non zero for failure.
+
+(todo: if we use a ring signature on the "request path stream result" message can do a pop and shift on the pubkeys in the ring so that the original requestor can know who rejected/accepted without the intermediate hops knowing who did. would we have to generate derived keys here?)
+(todo: if we use normal signatures here would we want to blind the signing keys some how? rotating blinded keys rachet style)
+
+after built we have a quic substream which will do xchacha20 stream cipher at each hop using the nonce provided in the request. this substream can be used to send consensus data requests to the pivot router.
+
+over this stream once created we will use xchacha20 stream cipher at each hop on all stream data with the nounce provided in the request.
+
+#### path stream requests
+
+we can use path stream to request introsets, publish introsets, look up name hashes, look up services via service discovery, publish service discovery data, and any kinds of future anonymous requests we need to 
+
+### path update
+
+sent on an existing path to update metadata about the path.
+
+lets us close a path prematurely. could let us extend the lifetime of a path. could let us rewire an upstream router and path id at a hop ( this can be used to route around a bad snode without building a full new path ).
+
+(todo: if done wrong path rewiring introduces infinite path extension, we need to figure out how to ensure that cannot happen if we do hop rewriring).
+(todo: path lifetime extension limits are yet to be explored).
+
+lets us possibly set qos on a path (todo: think about per hop qos vs all hop qos, specifically hiding qos from each hop or using the same qos by having it be signed plaintext). 
+
+## lossy traffic
+
+one shot datagrams with a 24 byte nonce and tx/rx path id are sent best effort on an established path with the nonce mutated deterministically and symettric encryption applied. 
+