Added path-build to documentation

- re-structure docs
    - add diagrams
dan 4 months ago committed by Jeff Becker
parent 559fa8aec4
commit 4eb0ee4960
Signed by: jeff
GPG Key ID: 025C02EE3A092F2D

@ -0,0 +1,46 @@
# High-Level Architecture
## Path Building
<p align="center">
<img src="/docs/lokinet_pathbuild_no_steps.png">
Starting from the top, here's a high-level overview of how the lokinet client builds a path to a terminating node
1. Client semi-randomly selects SN's for hops 2 and 3 using Introset Hash Ring (IHR)
- First hop is sticky: upon initialization of lokinet, 4-5 first hops are selected
2. Message sent to hop 1
- Message consists of eight records in a linked list. Four hops are typically used, leaving the last 4 links as dummy records
- Each record contains a TX (upstream) path ID and RX (downstream) path ID
- Each record has a pointer to the next record, except for the final hops' record; the pointer here is recursive, signalling the end of the path-build
3. Hop 2 pops top record, appends metadata, and pushes record to the back of linked list
- Hop adds metadata to the record, such as optional lifetime, pubkey to derive shared secret, etc
4. Steps 2-3 are repeated for the remaining hops until destination is reached
- Final hop reads the recursive pointer signalling the end of the path-build process
5. Upon completion, plain-text reply is propagated backwards, where the client can then decrypt all records
6. Client measures latency
- A) Routing message is sequentially encrypted using hop 4's key through hop 1's key
- At each iteration, the nonce is permuted by XOR'ing the previous nonce with the hash of the secret key of each hop
- B) Routing message is sent s.t. each hop can decrypt, with final hop receiving plain-text
- Each hop appends latency and expiration time data, with the final hop interpreting the plain-text as a routing message and sending it back to the client
7. Introset is published to IHR upon successful completion; introset contains:
- Path ID's of routers
- Latency and expiration time for each hop
- DNS SRV records
- etc
### Failure Cases
1. Next hop is an invalid SN
2. Cannot connect to SN
In either case, the path-build status is sent backwards with an error flag. Once received by the client, metadata related to the prospective path is wiped and the path forgotten

@ -1,19 +0,0 @@
## onion routing overview
<!-- todo: how is traffic transported (encryption, onion etc.) for somebody knowing nothing about LLARP) -->
<!-- todo: are there any techniques available to circumvent blocking of Lokinet traffic? (not at the moment) -->
<!-- todo: how does path multiplexing work? -->
## endpoint zmq api
<!-- todo: endpoint authentication (dns records) -->
## DNS
<!-- todo: how does LN handle DNS requests -->
<!-- todo: how are loki addresses looked up -->
<!-- todo: hoes does ONS work right now (info on lookup redundancy) -->

@ -8,7 +8,7 @@ The `.snode` gtld refers to a router on the network by its public ed25519 key.
The `.loki` gtld refers to clients that publish the existence anonymously to the network by their ed25519 public key. (`.loki` also has the ability to use short names resolved via external consensus method, like a blockchain).
# How Do I use Lokinet?
# How do I use Lokinet?
set system dns resolver to use the dns resolver provided by lokinet, make sure the upstream dns provider that lokinet uses for non lokinet gtlds is set as desired (see lokinet.ini `[dns]` section)
@ -16,7 +16,7 @@ configure exit traffic provider if you want to tunnel ip traffic via lokinet, by
note: per flow (ip+proto/port) isolation is trivial on a technical level but currently not implemented at this time.
# Can I run lokinet on a soho router
# Can I run lokinet on a soho router?
Yes and that is the best way to run it in practice.

@ -30,7 +30,7 @@ You can get the latest stable release for lokinet on windows or macos from https
You do not have to build from source if you do not wish to, we provide [apt](#deb-install) and [rpm](#rpm-install) repos.
#### APT repository <span id="deb-install" />
#### APT Repository <span id="deb-install" />
You can install debian packages from `` by adding the apt repo to your system.

Binary file not shown.


Width:  |  Height:  |  Size: 104 KiB

@ -1,6 +1,5 @@
# How is lokinet different than ...
## Tor Browser
Tor browser is a hardened Firefox Web Browser meant exclusively to surf http(s) sites via Tor. It is meant to be a complete self contained browser you open and run to surf the Web (not the internet) anonymously.

@ -1,8 +1,8 @@
# Lokinet project structure
# Lokinet Project Structure
this codebase is a bit large. this is a high level map of the current code structure.
## lokinet executable main functions `(/daemon)`
## Lokinet executable main functions `(/daemon)`
* `lokinet.cpp`: lokinet daemon executable
* `lokinet.swift`: macos sysex/appex executable
@ -10,14 +10,14 @@ this codebase is a bit large. this is a high level map of the current code struc
* `lokinet-bootstrap.cpp`: legacy util for windows, downloads a bootstrap file via https
## lokinet public headers `(/include)`
## Lokinet public headers `(/include)`
`lokinet.h and lokinet/*.h`: C headers for embedded lokinet
`llarp.hpp`: semi-internal C++ header for lokinet executables
## lokinet core library `(/llarp)`
## Lokinet core library `(/llarp)`
* `/llarp`: contains a few straggling compilation units
* `/llarp/android`: android platform compat shims
@ -49,7 +49,7 @@ this codebase is a bit large. this is a high level map of the current code struc
* `/llarp/win32`: windows specific code
## component relations
## Component relations
### `/llarp/service` / `/llarp/handlers` / `/llarp/exit`
@ -82,7 +82,7 @@ node to node traffic logic and wire protocol dialects
* `//TODO: separte implementation details from interfaces`
## platform contrib code `(/contrib)`
## Platform contrib code `(/contrib)`
grab bag directory for non core related platform specific non source code

@ -2,33 +2,25 @@
This is where Lokinet documentation lives.
[How Do I install Lokinet?](
## Contents:
[How Do I use Lokinet?](
### Local Environment Set-Up
- [Installing Lokinet](
- [Using Lokinet](
## High level
[How is Lokinet different to \[insert network technology name here\] ?](
### High Level Overview
- [Lokinet versus \[insert network technology name here\]](
- [Lokinet architecture](
- [Lokinet and DNS](
- [Limitations of Lokinet](
<!-- [How does Lokinet work?]( -->
[Lokinet and DNS](
[What Lokinet can't do](
## Lokinet Internals
[High level layout of the git repo](
[Build Doxygen Docs for internals](
## Lokinet (SN)Application Developer Portal
[What are "SNApps" and how to develop them.](
[How do I embed lokinet into my application?](
### Lokinet Internals
- [Git repo layout and project structure](
- [Building Doxygen Docs for internals](
### Lokinet (SN)Application Developer Portal
- [SNapps development overview](
- [Embedded Lokinet](