Merge branch 'release/v0.4.0'

Changelog for 0.4.0
Version bump for release 0.4.0
2020-01-28 16:27:15 +00:00 · 2020-01-28 16:26:57 +00:00 · 2020-01-28 16:19:56 +00:00 · 2020-01-28 15:38:33 +00:00 · 2020-01-28 15:38:19 +00:00 · 2020-01-28 15:38:09 +00:00
129 changed files with 14997 additions and 2092 deletions
@@ -0,0 +1,2 @@
+RUST_LOG=info
+RUST_BACKTRACE=1
@@ -1,3 +1,8 @@
-/target
+/targetString
 **/*.rs.bk
-/.idea/
+/*/target
+/test_inbox
+.idea
+target
+.env
+/.vscode/settings.json
@@ -0,0 +1,15 @@
+language: rust
+rust:
+  - stable
+  - beta
+  - nightly
+jobs:
+  allow_failures:
+    - rust: nightly
+  fast_finish: true
+before_script:
+  - rustup component add rustfmt
+script:
+  - cargo build
+  - cargo test
+  - cargo fmt -- --check
@@ -1,12 +1,143 @@
-# nym-client Changelog
+# Changelog

-* removed the `--local` flag
-* introduced `--directory` argument to support arbitrary directory servers. Leaving it out will point the node at the "https://directory.nymtech.net" alpha testnet server
-* IPv6 support
-* client version number is now shown at node start
-* directory server location is now shown at node start
-* decrease default delays
+## [Unreleased](https://github.com/nymtech/nym/tree/HEAD)

-## 0.1.0 - Initial Release
+[Full Changelog](https://github.com/nymtech/nym/compare/0.4.0-rc.2...HEAD)

-* The bare minimum set of features required by a Nym Client
+Nym 0.4.0 Platform
+
+In this release, we're taking a lot more care with version numbers, so that we can ensure upgrade compatibility for mixnodes, providers, clients, and validators more easily. 
+
+This release also integrates a health-checker and network topology refresh into the Nym client, so that the client can intelligently choose paths which route around any non-functional or incompatible nodes. 
+
+## [0.4.0-rc.2](https://github.com/nymtech/nym/tree/0.4.0-rc.2) (2020-01-28)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.4.0-rc.1...0.4.0-rc.2)
+
+**Merged pull requests:**
+
+- Hotfix/semver compatibility [\#106](https://github.com/nymtech/nym/pull/106) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.4.0-rc.1](https://github.com/nymtech/nym/tree/v0.4.0-rc.1) (2020-01-28)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.3.3...v0.4.0-rc.1)
+
+**Closed issues:**
+
+- Check Sphinx packet length in client [\#98](https://github.com/nymtech/nym/issues/98)
+- workflow test [\#97](https://github.com/nymtech/nym/issues/97)
+- Client SemVer [\#85](https://github.com/nymtech/nym/issues/85)
+- Move PemStore [\#74](https://github.com/nymtech/nym/issues/74)
+- Periodic client refresh [\#70](https://github.com/nymtech/nym/issues/70)
+- Logging [\#68](https://github.com/nymtech/nym/issues/68)
+- Nym-client refactor [\#67](https://github.com/nymtech/nym/issues/67)
+- Stop panicking! [\#66](https://github.com/nymtech/nym/issues/66)
+- Fix Mixnode Panic on Sphinx packet replay [\#65](https://github.com/nymtech/nym/issues/65)
+- Convert older code to start using logging [\#35](https://github.com/nymtech/nym/issues/35)
+- Convert to non-url-safe base64 \(everywhere\) [\#28](https://github.com/nymtech/nym/issues/28)
+- If a thread blows at startup, panic the entire application [\#15](https://github.com/nymtech/nym/issues/15)
+- Split provider/mod.rs [\#10](https://github.com/nymtech/nym/issues/10)
+
+**Merged pull requests:**
+
+- Feature/health checker with existing keys [\#105](https://github.com/nymtech/nym/pull/105) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/remove topology equality check [\#104](https://github.com/nymtech/nym/pull/104) ([futurechimp](https://github.com/futurechimp))
+- Feature/base58 [\#102](https://github.com/nymtech/nym/pull/102) ([futurechimp](https://github.com/futurechimp))
+- Feature/panic improvements [\#101](https://github.com/nymtech/nym/pull/101) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/fix sphinx unwraps [\#100](https://github.com/nymtech/nym/pull/100) ([futurechimp](https://github.com/futurechimp))
+- Feature/check packet length [\#99](https://github.com/nymtech/nym/pull/99) ([futurechimp](https://github.com/futurechimp))
+- Feature/version filtering improvements [\#96](https://github.com/nymtech/nym/pull/96) ([futurechimp](https://github.com/futurechimp))
+- Feature/refreshing topology [\#94](https://github.com/nymtech/nym/pull/94) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/consistent logging [\#93](https://github.com/nymtech/nym/pull/93) ([futurechimp](https://github.com/futurechimp))
+- Feature/semver client [\#92](https://github.com/nymtech/nym/pull/92) ([futurechimp](https://github.com/futurechimp))
+- Feature/client refactor [\#91](https://github.com/nymtech/nym/pull/91) ([jstuczyn](https://github.com/jstuczyn))
+- Release builds should no longer silently fail - everything will be im… [\#89](https://github.com/nymtech/nym/pull/89) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.3.3](https://github.com/nymtech/nym/tree/v0.3.3) (2020-01-20)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.3.2...v0.3.3)
+
+**Fixed bugs:**
+
+- Nym client crashing and disconnecting local websocket with complaint about binary data [\#56](https://github.com/nymtech/nym/issues/56)
+
+**Closed issues:**
+
+- Websocket text fix [\#64](https://github.com/nymtech/nym/issues/64)
+- Restore nym-client lib in crate [\#63](https://github.com/nymtech/nym/issues/63)
+- Make websocket not crash on ping or pong messages [\#62](https://github.com/nymtech/nym/issues/62)
+- Messages returned by fetch are base64 encoded [\#55](https://github.com/nymtech/nym/issues/55)
+- Check layer 1 connectivity at client start [\#38](https://github.com/nymtech/nym/issues/38)
+- Check required sfw-provider args [\#27](https://github.com/nymtech/nym/issues/27)
+- Make Electron app work with new Rust mixnet client [\#16](https://github.com/nymtech/nym/issues/16)
+- Take version numbers into account when picking routes [\#14](https://github.com/nymtech/nym/issues/14)
+
+**Merged pull requests:**
+
+- Feature/websocket improvements [\#88](https://github.com/nymtech/nym/pull/88) ([jstuczyn](https://github.com/jstuczyn))
+- Using println rather than log for startup banner, it's not an error [\#87](https://github.com/nymtech/nym/pull/87) ([futurechimp](https://github.com/futurechimp))
+- Feature/nym client lib [\#61](https://github.com/nymtech/nym/pull/61) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.3.2](https://github.com/nymtech/nym/tree/v0.3.2) (2020-01-17)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.3.1...v0.3.2)
+
+**Merged pull requests:**
+
+- Feature/separate presence address [\#59](https://github.com/nymtech/nym/pull/59) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.3.1](https://github.com/nymtech/nym/tree/v0.3.1) (2020-01-16)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.3.0...v0.3.1)
+
+**Merged pull requests:**
+
+- Bugfix/presence client crash [\#58](https://github.com/nymtech/nym/pull/58) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.3.0](https://github.com/nymtech/nym/tree/v0.3.0) (2020-01-14)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.2.0...v0.3.0)
+
+**Closed issues:**
+
+- Error referring to mismatched types caused by topology [\#46](https://github.com/nymtech/nym/issues/46)
+- Provider needs to announce two of its addresses \(+ issue of hardcoded port\) [\#32](https://github.com/nymtech/nym/issues/32)
+- Port run\_network.sh from old Go mixnet [\#30](https://github.com/nymtech/nym/issues/30)
+- Health Checker inside Validator [\#29](https://github.com/nymtech/nym/issues/29)
+- Combine Rust repositories into a single master repo containing multiple crates [\#24](https://github.com/nymtech/nym/issues/24)
+- Fix the version numbers on provider and mixnode [\#23](https://github.com/nymtech/nym/issues/23)
+- Travis releases for Nym [\#22](https://github.com/nymtech/nym/issues/22)
+- Add version number to presence [\#4](https://github.com/nymtech/nym/issues/4)
+- Add version number to presence [\#1](https://github.com/nymtech/nym/issues/1)
+
+**Merged pull requests:**
+
+- Feature/client topology filtering [\#54](https://github.com/nymtech/nym/pull/54) ([jstuczyn](https://github.com/jstuczyn))
+- print public key for nym client tools [\#53](https://github.com/nymtech/nym/pull/53) ([mileschet](https://github.com/mileschet))
+- Showing binding warning on binding to localhost, 0.0.0.0 or 127.0.0.1 [\#52](https://github.com/nymtech/nym/pull/52) ([jstuczyn](https://github.com/jstuczyn))
+- validator: moving sample config files into sample configs directory [\#51](https://github.com/nymtech/nym/pull/51) ([futurechimp](https://github.com/futurechimp))
+- Feature/validator health checker [\#50](https://github.com/nymtech/nym/pull/50) ([jstuczyn](https://github.com/jstuczyn))
+- Improving websocket connection errors [\#49](https://github.com/nymtech/nym/pull/49) ([futurechimp](https://github.com/futurechimp))
+- Feature/crypto crate [\#48](https://github.com/nymtech/nym/pull/48) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/chill log messages [\#43](https://github.com/nymtech/nym/pull/43) ([futurechimp](https://github.com/futurechimp))
+- persistence: improving PEM file reading and parsing failure messages [\#42](https://github.com/nymtech/nym/pull/42) ([futurechimp](https://github.com/futurechimp))
+- Providing a nicer error than "failed on unwrap\(\)" when topology retri… [\#41](https://github.com/nymtech/nym/pull/41) ([futurechimp](https://github.com/futurechimp))
+- Prettying up sfw-provider start sequence a bit. [\#40](https://github.com/nymtech/nym/pull/40) ([futurechimp](https://github.com/futurechimp))
+- Removing the run command from code and documentation [\#39](https://github.com/nymtech/nym/pull/39) ([futurechimp](https://github.com/futurechimp))
+- Feature/script/localnet [\#37](https://github.com/nymtech/nym/pull/37) ([futurechimp](https://github.com/futurechimp))
+- Feature/arguments fix [\#36](https://github.com/nymtech/nym/pull/36) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/crates cleanup [\#34](https://github.com/nymtech/nym/pull/34) ([jstuczyn](https://github.com/jstuczyn))
+- Features/version number to presence [\#25](https://github.com/nymtech/nym/pull/25) ([aniampio](https://github.com/aniampio))
+- Feature/minor client changes [\#7](https://github.com/nymtech/nym/pull/7) ([jstuczyn](https://github.com/jstuczyn))
+
+## [v0.2.0](https://github.com/nymtech/nym/tree/v0.2.0) (2020-01-07)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/0.2.0...v0.2.0)
+
+## [0.2.0](https://github.com/nymtech/nym/tree/0.2.0) (2020-01-06)
+
+[Full Changelog](https://github.com/nymtech/nym/compare/0.1.0...0.2.0)
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*
@@ -1,39 +1,21 @@
-[package]
-build = "build.rs"
-name = "nym-client"
-version = "0.2.0"
-authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
-edition = "2018"
+[profile.release]
+panic = "abort"

-[lib]
-name = "nym_client"
-path = "src/lib.rs"
+[workspace]

-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[dependencies]
-base64 = "0.11.0"
-clap = "2.33.0"
-curve25519-dalek = "1.2.3"
-dirs = "2.0.2"
-futures = "0.3.1"
-hex = "0.4.0"
-pem = "0.7.0"
-rand = "0.7.2"
-rand_distr = "0.2.2"
-reqwest = "0.9.22"
-serde = { version = "1.0.104", features = ["derive"] }
-serde_json = "1.0.44"
-sphinx = { path = "../sphinx" }
-sfw-provider-requests = { path = "../nym-sfw-provider/sfw-provider-requests" }
-tokio = { version = "0.2", features = ["full"] }
-tungstenite = "0.9.2"
-
-# putting this explicitly below everything and most likely, the next time we look into it, it will already have a proper release
-tokio-tungstenite = { git = "https://github.com/dbcfd/tokio-tungstenite", rev="6dc2018cbfe8fe7ddd75ff977343086503135b38" }
-
-[build-dependencies]
-built = "0.3.2"
-
-[dev-dependencies]
-mockito = "0.22.0"
+members = [
+    "common/clients/directory-client",
+    "common/clients/mix-client",
+    "common/clients/provider-client",
+    "common/clients/validator-client",
+    "common/addressing",
+    "common/crypto",
+    "common/healthcheck",
+    "common/pemstore",
+    "common/topology",
+    "mixnode",
+    "nym-client",
+    "sfw-provider",
+    "sfw-provider/sfw-provider-requests",
+    "validator",
+]
@@ -1,10 +1,20 @@
-# Nym Client
+## The Nym Privacy Platform

-The Nym Client communicates with the remote, decentralised nodes which make up the Nym system as a whole. 
+This repository contains the full Nym platform, written in Rust.

-It needs to handle communication with 3 types of remote nodes. Here's the development status of each:
+The platform is composed of multiple Rust crates. Top-level executable binary crates include:

- [ ] Directory nodes
- [ ] Mix nodes
- [ ] Validator nodes
+* mixnode - shuffles [Sphinx](https://github.com/nymtech/sphinx) packets together to provide privacy against network-level attackers.
+* nym-client - an executable which you can build into your own applications. Use it for interacting with Nym nodes.
+* sfw-provider - a store-and-forward service provider. The provider acts sort of like a mailbox for mixnet messages.
+* validator - currently just starting development. Handles consensus ordering of transactions, mixmining, and coconut credential generation and validation. 

+[![Build Status](https://travis-ci.com/nymtech/nym.svg?branch=develop)](https://travis-ci.com/nymtech/nym)
+
+### Building
+
+Platform build instructions are available on [our docs site](https://nymtech.net/docs/mixnet/installation/).
+
+### Developing
+
+There's a `.env.sample-dev` file provided which you can rename to `.env` if you want convenient logging, backtrace, or other environment variables pre-set. The `.env` file is ignored so you don't need to worry about checking it in.
@@ -0,0 +1,11 @@
+[package]
+name = "addressing"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log = "0.4"
+pretty_env_logger = "0.3"
@@ -62,8 +62,8 @@ pub fn encoded_bytes_from_socket_address(address: SocketAddr) -> [u8; 32] {
    address_bytes
 }

-pub fn socket_address_from_encoded_bytes(b: [u8; 32]) -> SocketAddr {
-    let address_type: AddressType = b[0].try_into().unwrap();
+pub fn socket_address_from_encoded_bytes(b: [u8; 32]) -> Result<SocketAddr, AddressTypeError> {
+    let address_type: AddressType = b[0].try_into()?;

    let port: u16 = u16::from_be_bytes([b[1], b[2]]);

@@ -76,5 +76,5 @@ pub fn socket_address_from_encoded_bytes(b: [u8; 32]) -> SocketAddr {
        }
    };

-    SocketAddr::new(ip, port)
+    Ok(SocketAddr::new(ip, port))
 }
@@ -0,0 +1,19 @@
+[package]
+name = "directory-client"
+version = "0.1.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log = "0.4"
+pretty_env_logger = "0.3"
+reqwest = "0.9.22"
+serde = { version = "1.0.104", features = ["derive"] }
+
+## internal
+topology = {path = "../../topology"}
+
+[dev-dependencies]
+mockito = "0.22.0"
@@ -1,22 +1,16 @@
-use crate::clients::directory::requests::health_check_get::{
-    HealthCheckRequester, Request as HealthCheckRequest,
-};
-use crate::clients::directory::requests::metrics_mixes_get::{
-    MetricsMixRequester, Request as MetricsMixRequest,
-};
-use crate::clients::directory::requests::metrics_mixes_post::{
-    MetricsMixPoster, Request as MetricsMixPost,
-};
-use crate::clients::directory::requests::presence_coconodes_post::{
+use crate::requests::health_check_get::{HealthCheckRequester, Request as HealthCheckRequest};
+use crate::requests::metrics_mixes_get::{MetricsMixRequester, Request as MetricsMixRequest};
+use crate::requests::metrics_mixes_post::{MetricsMixPoster, Request as MetricsMixPost};
+use crate::requests::presence_coconodes_post::{
    PresenceCocoNodesPoster, Request as PresenceCocoNodesPost,
 };
-use crate::clients::directory::requests::presence_mixnodes_post::{
+use crate::requests::presence_mixnodes_post::{
    PresenceMixNodesPoster, Request as PresenceMixNodesPost,
 };
-use crate::clients::directory::requests::presence_providers_post::{
+use crate::requests::presence_providers_post::{
    PresenceMixProviderPoster, Request as PresenceProvidersPost,
 };
-use crate::clients::directory::requests::presence_topology_get::{
+use crate::requests::presence_topology_get::{
    PresenceTopologyGetRequester, Request as PresenceTopologyRequest,
 };

@@ -28,6 +22,12 @@ pub struct Config {
    pub base_url: String,
 }

+impl Config {
+    pub fn new(base_url: String) -> Self {
+        Config { base_url }
+    }
+}
+
 pub trait DirectoryClient {
    fn new(config: Config) -> Self;
 }
@@ -0,0 +1,33 @@
+use serde::{Deserialize, Serialize};
+use topology::coco;
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CocoPresence {
+    pub host: String,
+    pub pub_key: String,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl Into<topology::coco::Node> for CocoPresence {
+    fn into(self) -> topology::coco::Node {
+        topology::coco::Node {
+            host: self.host,
+            pub_key: self.pub_key,
+            last_seen: self.last_seen,
+            version: self.version,
+        }
+    }
+}
+
+impl From<topology::coco::Node> for CocoPresence {
+    fn from(cn: coco::Node) -> Self {
+        CocoPresence {
+            host: cn.host,
+            pub_key: cn.pub_key,
+            last_seen: cn.last_seen,
+            version: cn.version,
+        }
+    }
+}
@@ -0,0 +1,49 @@
+use serde::{Deserialize, Serialize};
+use std::convert::TryInto;
+use std::io;
+use std::net::ToSocketAddrs;
+use topology::mix;
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MixNodePresence {
+    pub host: String,
+    pub pub_key: String,
+    pub layer: u64,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl TryInto<topology::mix::Node> for MixNodePresence {
+    type Error = io::Error;
+
+    fn try_into(self) -> Result<topology::mix::Node, Self::Error> {
+        let resolved_hostname = self.host.to_socket_addrs()?.next();
+        if resolved_hostname.is_none() {
+            return Err(io::Error::new(
+                io::ErrorKind::Other,
+                "no valid socket address",
+            ));
+        }
+
+        Ok(topology::mix::Node {
+            host: resolved_hostname.unwrap(),
+            pub_key: self.pub_key,
+            layer: self.layer,
+            last_seen: self.last_seen,
+            version: self.version,
+        })
+    }
+}
+
+impl From<topology::mix::Node> for MixNodePresence {
+    fn from(mn: mix::Node) -> Self {
+        MixNodePresence {
+            host: mn.host.to_string(),
+            pub_key: mn.pub_key,
+            layer: mn.layer,
+            last_seen: mn.last_seen,
+            version: mn.version,
+        }
+    }
+}
@@ -0,0 +1,108 @@
+use crate::requests::presence_topology_get::PresenceTopologyGetRequester;
+use crate::{Client, Config, DirectoryClient};
+use log::*;
+use serde::{Deserialize, Serialize};
+use std::convert::TryInto;
+use topology::coco;
+use topology::mix;
+use topology::provider;
+use topology::NymTopology;
+
+pub mod coconodes;
+pub mod mixnodes;
+pub mod providers;
+
+// Topology shows us the current state of the overall Nym network
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Topology {
+    pub coco_nodes: Vec<coconodes::CocoPresence>,
+    pub mix_nodes: Vec<mixnodes::MixNodePresence>,
+    pub mix_provider_nodes: Vec<providers::MixProviderPresence>,
+}
+
+impl NymTopology for Topology {
+    fn new(directory_server: String) -> Self {
+        debug!("Using directory server: {:?}", directory_server);
+        let directory_config = Config {
+            base_url: directory_server,
+        };
+        let directory = Client::new(directory_config);
+
+        let topology = directory
+            .presence_topology
+            .get()
+            .expect("Failed to retrieve network topology.");
+        topology
+    }
+
+    fn new_from_nodes(
+        mix_nodes: Vec<mix::Node>,
+        mix_provider_nodes: Vec<provider::Node>,
+        coco_nodes: Vec<coco::Node>,
+    ) -> Self {
+        Topology {
+            coco_nodes: coco_nodes.into_iter().map(|node| node.into()).collect(),
+            mix_nodes: mix_nodes.into_iter().map(|node| node.into()).collect(),
+            mix_provider_nodes: mix_provider_nodes
+                .into_iter()
+                .map(|node| node.into())
+                .collect(),
+        }
+    }
+
+    fn mix_nodes(&self) -> Vec<mix::Node> {
+        self.mix_nodes
+            .iter()
+            .filter_map(|x| x.clone().try_into().ok())
+            .collect()
+    }
+
+    fn providers(&self) -> Vec<provider::Node> {
+        self.mix_provider_nodes
+            .iter()
+            .map(|x| x.clone().into())
+            .collect()
+    }
+
+    fn coco_nodes(&self) -> Vec<topology::coco::Node> {
+        self.coco_nodes.iter().map(|x| x.clone().into()).collect()
+    }
+}
+
+#[cfg(test)]
+mod converting_mixnode_presence_into_topology_mixnode {
+    use super::*;
+
+    #[test]
+    fn it_returns_error_on_unresolvable_hostname() {
+        let unresolvable_hostname = "foomp.foomp.foomp:1234";
+
+        let mix_presence = mixnodes::MixNodePresence {
+            host: unresolvable_hostname.to_string(),
+            pub_key: "".to_string(),
+            layer: 0,
+            last_seen: 0,
+            version: "".to_string(),
+        };
+
+        let result: Result<mix::Node, std::io::Error> = mix_presence.try_into();
+        assert!(result.is_err())
+    }
+
+    #[test]
+    fn it_returns_resolved_ip_on_resolvable_hostname() {
+        let resolvable_hostname = "nymtech.net:1234";
+
+        let mix_presence = mixnodes::MixNodePresence {
+            host: resolvable_hostname.to_string(),
+            pub_key: "".to_string(),
+            layer: 0,
+            last_seen: 0,
+            version: "".to_string(),
+        };
+
+        let result: Result<topology::mix::Node, std::io::Error> = mix_presence.try_into();
+        assert!(result.is_ok())
+    }
+}
@@ -0,0 +1,69 @@
+use serde::{Deserialize, Serialize};
+use topology::provider;
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MixProviderPresence {
+    pub client_listener: String,
+    pub mixnet_listener: String,
+    pub pub_key: String,
+    pub registered_clients: Vec<MixProviderClient>,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl Into<topology::provider::Node> for MixProviderPresence {
+    fn into(self) -> topology::provider::Node {
+        topology::provider::Node {
+            client_listener: self.client_listener.parse().unwrap(),
+            mixnet_listener: self.mixnet_listener.parse().unwrap(),
+            pub_key: self.pub_key,
+            registered_clients: self
+                .registered_clients
+                .into_iter()
+                .map(|c| c.into())
+                .collect(),
+            last_seen: self.last_seen,
+            version: self.version,
+        }
+    }
+}
+
+impl From<topology::provider::Node> for MixProviderPresence {
+    fn from(mpn: provider::Node) -> Self {
+        MixProviderPresence {
+            client_listener: mpn.client_listener.to_string(),
+            mixnet_listener: mpn.mixnet_listener.to_string(),
+            pub_key: mpn.pub_key,
+            registered_clients: mpn
+                .registered_clients
+                .into_iter()
+                .map(|c| c.into())
+                .collect(),
+            last_seen: mpn.last_seen,
+            version: mpn.version,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MixProviderClient {
+    pub pub_key: String,
+}
+
+impl Into<topology::provider::Client> for MixProviderClient {
+    fn into(self) -> topology::provider::Client {
+        topology::provider::Client {
+            pub_key: self.pub_key,
+        }
+    }
+}
+
+impl From<topology::provider::Client> for MixProviderClient {
+    fn from(mpc: topology::provider::Client) -> Self {
+        MixProviderClient {
+            pub_key: mpc.pub_key,
+        }
+    }
+}
@@ -1,4 +1,4 @@
-use crate::clients::directory::metrics::PersistedMixMetric;
+use crate::metrics::PersistedMixMetric;

 pub struct Request {
    base_url: String,
@@ -1,4 +1,4 @@
-use crate::clients::directory::metrics::MixMetric;
+use crate::metrics::MixMetric;
 use reqwest::Response;

 pub struct Request {
@@ -69,7 +69,7 @@ mod metrics_get_request {

    #[cfg(test)]
    mod fixtures {
-        use crate::clients::directory::metrics::MixMetric;
+        use crate::metrics::MixMetric;

        pub fn new_metric() -> MixMetric {
            MixMetric {
@@ -1,4 +1,4 @@
-use crate::clients::directory::presence::CocoPresence;
+use crate::presence::coconodes::CocoPresence;
 use reqwest::Response;

 pub struct Request {
@@ -73,13 +73,14 @@ mod metrics_get_request {

    #[cfg(test)]
    mod fixtures {
-        use crate::clients::directory::presence::CocoPresence;
+        use crate::presence::coconodes::CocoPresence;

        pub fn new_presence() -> CocoPresence {
            CocoPresence {
                host: "foo.com".to_string(),
                pub_key: "abc".to_string(),
                last_seen: 666,
+                version: "0.2.0".to_string(),
            }
        }
    }
@@ -1,4 +1,4 @@
-use crate::clients::directory::presence::MixNodePresence;
+use crate::presence::mixnodes::MixNodePresence;
 use reqwest::Response;

 pub struct Request {
@@ -73,7 +73,7 @@ mod metrics_get_request {

    #[cfg(test)]
    mod fixtures {
-        use crate::clients::directory::presence::MixNodePresence;
+        use crate::presence::mixnodes::MixNodePresence;

        pub fn new_presence() -> MixNodePresence {
            MixNodePresence {
@@ -81,6 +81,7 @@ mod metrics_get_request {
                pub_key: "abc".to_string(),
                layer: 1,
                last_seen: 0,
+                version: "0.1.0".to_string(),
            }
        }
    }
@@ -1,4 +1,4 @@
-use crate::clients::directory::presence::MixProviderPresence;
+use crate::presence::providers::MixProviderPresence;
 use reqwest::Response;

 pub struct Request {
@@ -72,13 +72,16 @@ mod metrics_get_request {
    }
    #[cfg(test)]
    mod fixtures {
-        use crate::clients::directory::presence::MixProviderPresence;
+        use crate::presence::providers::MixProviderPresence;

        pub fn new_presence() -> MixProviderPresence {
            MixProviderPresence {
-                host: "foo.com".to_string(),
+                client_listener: "foo.com".to_string(),
+                mixnet_listener: "foo.com".to_string(),
                pub_key: "abc".to_string(),
                registered_clients: vec![],
+                last_seen: 0,
+                version: "0.1.0".to_string(),
            }
        }
    }
@@ -1,4 +1,4 @@
-use crate::clients::directory::presence::Topology;
+use crate::presence::Topology;

 pub struct Request {
    base_url: String,
@@ -75,25 +75,29 @@ mod topology_requests {
                       "host": "3.8.244.109:4000",
                       "pubKey": "AAAAAAAAAAEKwAECSqKy8I8KkSYIBSctxRBRxuR61PpAOwK0UQtkeuPRdwusAyaoBbvv1IBWyMEhvbgT4CtgUnGfYH2s06CIJ09lWWvQ0Jkgthq12mG73H9QSTNM8RITlF1X5ax9BV0EK34M5dUncn1uEYzJzcbaLjUarf2bqoy906dtQpppUWDRLJI6ycw7rKKJ4ZNUhgi4KAEGBsSgLqc0zDKs0rArwouZyz4ofoWnY68mdJKrVy6Zqz83DSdc7B2hqqkHX_Bfeb4SwAEFuhRpy4HfcuxwcRI9sIWMo_LVmbk19g1gfMRlBrmZqoEQL6rDApVLZ9eMp-5IQK8WLlZpWf4Zjy7kZolARAyp_rHUQkH4PrDjgoPrKbm6qK_iejYpL7qx28Q3VeInMpwMIMaSbbW9y36sEVtGc2I0Iu5vS0sp8ESiVlQ5NaBz72deZ8oKJJ4IEPPHP99-b0UQX80fVIrNM88mMzKy0bHri9NFlmIG-e0G1cqmw_ry3XWGQkcr1M5RuNa6oX50w5QawAEVxd5FP5bE8bS4x54Csof11sQWUTwMp6Q7_3H7ZCTSlKSqujlOhmfqSHfGPO2sDIYPHDhDzjakZpKAZWWhn_hiR6DfPpomQ01ZYUhVKKSMxz7_VPjsQplP0bZXA2gfnkADUN8UQ0N9g_usIw73r4aZsOviMsRM8oByvsjVfUWc4_HTLSdnQyImFkHz9CiCmrIYL2dYQRePRatWggvBAyeRzntxI4jDqLKiBdi54ZlAKgV6MCRaJ7Bu7BtmLXrtK4sawAED3QYxuvOSZrbZdUr4yG-U9yVvJ9Klkf-5Mo4EYp3qTL2KBB6_LrZepjAQqp486YkZ03mTIezcsZ48EboXVTWKBZ3QnTI5tX-j4gGxQb7klOJc97qJkDxsvpz4F0ChgCUIZhpIItWHia7_R3Gi-b5siLIdQdUho9isn3kiDGm6t0NED2Bgy3ZxxQwzqsBZm4kPr2_fPX4YyvIoP9895YcGjZyE5iiRC_TE41RJmB1GZYdxegTMq3lNDllKgiqaiPgawAEJASDkmZHTwlg9YOev5OWpQD-FnhPkqVNo_QcDyRu9eoGcWSGFp2sYqjG2SpmiXq0VNnAO7AcKxRzDFu7TjfhlU3Kt0uTKIcrWVU1zFNbJNMjYEq90pp50nowwx8INz20IXET2ZNX6kIXYFCsEvPLZFlG2OoL6xg3uQS1qMl3lIS_VxdO_JfVe0rT65WsJ_P4Nkc1jYiuNPHY6d_iFO0BVYqX0sOCX73GC_TT13BR0jnPwDAVw0rGtYHsXBb8TKOsawAEZIClauuT1V3qOZnb7uRZhFXO-PKTxgc1LCzJt2ChOrMZaBpjlkf3IPpJ2UF4JH4kGaDeBf2k_S-FLAs3drK21efbi5P6_a4QTxAiiRimXGoQIyvOg462s6kP_ZRFufo8YYQHS4olaOeqU4564dNskg_uBPsFMz_2GNOhmn_15cJqP1jfkyD49Z16GTS5YLHgVl9bJKqyvLuypsToLbt1BJzipEP0L2OohuRm-_MvqvwwWKyjNQsubgee1K728d9AawAEBkGggcNVCtXyhoSqi3_w0tVxtkAYeud8sBeAtZHGs06me_QL8co0MFLlO-zdkUb4ZBq08rFEbgLOma8_3whleM8NIPaHNISp1q3IsIhB5zdXcZoGsqLixODBFHtID3YEHAlr4f9T_yh11yJ95xGCl_6Y37hpwLQVGyrfSfccM24mVFqnV3TT5Wdq3ile-jesUx1Q2G1yK_xVqc6itmk-kDuBjyZgzYi1-jsIXAjnhM9G7t8J_Bv5yGGZhLK2dCzM=",
                       "type": "validator",
-                       "lastSeen": 1575915097085539300
+                       "lastSeen": 1575915097085539300,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "3.9.129.61:4000",
                       "pubKey": "AAAAAAAAAAMKwAECSqKy8I8KkSYIBSctxRBRxuR61PpAOwK0UQtkeuPRdwusAyaoBbvv1IBWyMEhvbgT4CtgUnGfYH2s06CIJ09lWWvQ0Jkgthq12mG73H9QSTNM8RITlF1X5ax9BV0EK34M5dUncn1uEYzJzcbaLjUarf2bqoy906dtQpppUWDRLJI6ycw7rKKJ4ZNUhgi4KAEGBsSgLqc0zDKs0rArwouZyz4ofoWnY68mdJKrVy6Zqz83DSdc7B2hqqkHX_Bfeb4SwAEEv6RMevAQmLGkeK0uJKnMPPAtm8GgXjWSQijYdnxlPh5SJSNeJUbPZKWFFWdk8yIFXKa8jnzETtdGFKgUUt5AVUDpTBmEdwaHCzlFhXrttshy0V5OhPUlV8cGABmxbagMYm0bFPg0r-snSkrB9YG6wqJYQVeIMOCGYCPbHmDA8R_0-h8VkRKWs1d9KvQOK4kShqgZtYN71KJW8uDE4q2jsGDVvxFt1AgmU9b93xsXF17KrpZy5WxlLZ73HtnTD_oawAED4vd_rK-Kx_n8x_OdDiiEOPUlYDlDCQUqenU9XHKH3B6ijfkJ368wd3LDDVStjDwNORrAyUSw_VlSNUpd1XLC8d17gTaIq5ZI2fWuwwZaoN1JCsYU8fQ6USgtIehQX7IPP8EkFuNmuCBCmpr4schtYniGe9J8Q4dsV-TYPr2uLJkdx1r7luzF--I22k7NfQQM14QDci_0kgrgmZ54CJGkjXyOhCppBXg3fqLC6aFvT3ZocfiiXBJt0huGgPMDtYsawAECLh8KUdNsDolERwJ8v04bS5jI_KKf7uUnCHWuCELwbJSUI3OK1ufS1qSpauvSzVQSbrhEzrEfwQn4VtxQxJlX4UdDU-R-hafiZvVC6DLLAbuORBAC3FScn9W58CnezH4DvCp_w7nftDfdxeuungbZT9XaxS3iNC6PnFsWF6WM3DxMwrzOrFe6wEEoTSPe1mcUDrtwM5UksIvJr6MBRAXrdl0IdBTQr7cLwKe_KYi4siwdjfJEJtOh7oxQBxBg2UkawAEJAPZK2Gg2MQwpxdDT24lNQHF7FVfkO_LuhJwn0RbwNDSVeA4P6-tWL5TkCpqr8xYHfwQ6Z3ILfpGCZr8PspwIoRzqZHQ16f8Pq9xnr0hLEI9BOQU0FS2EtuyPgju5iwsAJAfehUzu6kNLphuLGsXoIZdXDG5mbylwh9JzAVXTwgaR0hNqyXVJxgbt7jcYaSEBFcMGV-hjXyVVNzBleE-G9o_noI_KWU4Ce7K-qOMcewMKfy_VEw-gVaD6dHz6AMoawAEE9XuOLwRttvKybAssZ9gsK-_YRUwuFOeRDIr3NX___9bx6pCc18adCIlH_8EJWFwXZ05ZpNNE88mYx7ZQ3aqaArZJRoWeZeKhqH_s05V10xbzkYX71G5cqz--8vr9ZlQRb2BeETF_Tdq_PLk7qbT8WTGIoq7ZwyDRQTgzvkCgyzj_hBLh2o7sSVNgUo38SFUTMn7YtvVFYlSrTDE3WKE-T-nh5SWdDBxgDTc3Bw8JpzNH-WkoJ4Lim7sB4Op1gEUawAEW4-kenlffwsNr_3b3aV0YuusLpxB03sxPzQ5B0CWNiVtbja1Z4tWhKGUUrdq_eUgMV0y5Of-BqNi5FspAQnhJBFSSxtOzRGV1h3qyUTksfZyed9z8zPI-ZPP9XXm7hYgJgDz_kxte-NfS9UG9q5AZetHUN4kGxXutjjzfUQZ9yTvhBKgKgTI2Dp_R_jZrWQ8F1BoWzIJzjddT1K2MvCQEkARYw08isbOeFmCwgVUcjxYZO45WyOmLQA7QJRL9WvA=",
                       "type": "validator",
-                       "lastSeen": 1575915097388409000
+                       "lastSeen": 1575915097388409000,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "3.9.222.1:4000",
                       "pubKey": "AAAAAAAAAAQKwAECSqKy8I8KkSYIBSctxRBRxuR61PpAOwK0UQtkeuPRdwusAyaoBbvv1IBWyMEhvbgT4CtgUnGfYH2s06CIJ09lWWvQ0Jkgthq12mG73H9QSTNM8RITlF1X5ax9BV0EK34M5dUncn1uEYzJzcbaLjUarf2bqoy906dtQpppUWDRLJI6ycw7rKKJ4ZNUhgi4KAEGBsSgLqc0zDKs0rArwouZyz4ofoWnY68mdJKrVy6Zqz83DSdc7B2hqqkHX_Bfeb4SwAECh9xcxpjOp1r7kiNIgrI9GgAlvXwgHkTchOxUiyOzTq6FDWdGN64KiC3NDeyGTg8FmzvGzS3jREeJqOdr4G9ZGtWkauAITgLFiH62t-YntRslhr8_1shxlmzKiNKJN_QFflEq79pZIlWtp3N8LIHMvXRtl-zt2DMze4s02XDmEkviyVE4CkQUDtCc-2MfPT4JcmEFqtFIxjrXn18SbYg3c6XUQHsGIkuDrKuCTRlpC8kvmM0uVoIeWdmwDlZk4jUawAEJhRwK5ozjqIWRP1bFzBPS9VhaJnfKU9PeFYtN5beiAHrYr2ylIB3yDfmAQUdKDowDUm5nfJATejEjEnrTGxh70QtfoNV391rSns3F71tBwY62KLaNr8qnVfeSFHV3FcQTMHHF_8mDb5_11Rj6aiMvW0y6eetHo7CDPMdEyDPmok_U2ZM5BzOUnwjT21HtnvcKxKKwHJ_QGfnAHPyDIhNOMgxJCrVazOidLCHeYGpyCLw1ipeTyKOQX0_ByB8dH6AawAEGV1GuF5SSlT67B1ityPJK2ZwXjeeKB4gGdCG3qRtWxLTZfGhVm7YAYm2f5tw_wrsJAZ9FubVhateGg0ZN67NxZtsvOOejXz6743f7ijnQopPgd_8pH-iVf6BEcSO8ZdcHxNRUTayzjVLs99bwMo2zaPevW4X4G_bN4mh---aPkdGYHwaiklzUhqJ-eqycrYAFyjyEXaPBXLQm1rpczqluNvnKbd8Q9LZWukgm7_uWv_HxufIvdWgoq8bAt78UU3oawAEP9VDehhqrQG5-WHMB66XVxo1TgMM8aVV0SwAq3lCRkpiFBz_9kw8T1F9Hx2AiNrEGT1QLbdMkpms1cG_5gBBahQofdt_NmUs1jfTFXY9iyMy1Q7A6ZYaLP8Z6q-orc1cKqySY-BJZQ_CpGFfXS0OVniFDQ6v78ytPK7K-yRgT1PxFgm3rZqrG0Tjbrpsg2PUL5S5fuXfMhUosP0uoLj0D1guWAR9Y7kfFBIXaTSFMoa8fghVBUTRNhK9f72a8SxQawAEOiv71taLjKqaaWQ_QjcDhWbvjG1EnsCyI0toNjGkcF19x4Vk-5NC96_4ioUGz404IC0XN03roRnibRT_78D9vZFVCWCqve9EjdF5TcApx03zIP4JT2g2q0MKIGgGrwt4Pz6LO6yOfMm7B8Yraps8IV-nP1w7K1m9XKP_FvH8egl5GHJe-_omlC2YyL_b28jMLENbxDFD-3KPjZFBhSLrRukX2PlayYTwEiTtokA2R9_11vQvJgP8KFEjGHg6zsAMawAEBn2H_hz2knb8ltnpEA5YSKVcV3nUtojkCNi_WUz7xUKd7efw1oI_lbnKrS7HkyC0JkQUZ1pCWUlSXNmgjMEhsn823a1LFzpV7rOv4vayYvvFX61hB9R78VjpyxJiYpDwRZLiUY3AK4WY8NqFDbjXR7rT4CkFHEf-VhSQQ8ZNvlpod1nmeVQVizHH9e7Tq7wsWz-LWEk3Hx6LmcrgDsL79LZYG9JXU5IdvG8RvLNx9cSwEI8yxcchpISAaot7UoYQ=",
                       "type": "validator",
-                       "lastSeen": 1575915094734973000
+                       "lastSeen": 1575915094734973000,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "3.9.102.214:4000",
                       "pubKey": "AAAAAAAAAAIKwAECSqKy8I8KkSYIBSctxRBRxuR61PpAOwK0UQtkeuPRdwusAyaoBbvv1IBWyMEhvbgT4CtgUnGfYH2s06CIJ09lWWvQ0Jkgthq12mG73H9QSTNM8RITlF1X5ax9BV0EK34M5dUncn1uEYzJzcbaLjUarf2bqoy906dtQpppUWDRLJI6ycw7rKKJ4ZNUhgi4KAEGBsSgLqc0zDKs0rArwouZyz4ofoWnY68mdJKrVy6Zqz83DSdc7B2hqqkHX_Bfeb4SwAEOVCUN3EwiVroS5-TOq2o7hYSxphK9X0G23N-IBZ0Tr1Rl8XEiJ-OEy0rqnAKwmhAZJWnx3u8oXqbZtOWIZmzQSpcoxhgwfhdmTZJCqT2RVzZyeFItX4sVeilEP3z2xdsJs8-a1kg6UZnx1s1BNLBo7eZrreZygWojPCIDBn03fSAflXoVc5PpY2CGy5MA_IgWgSYBHDdoZEtigp_amjqK7Us44Db20XpLxMXfbahiqa7WKNnMgi6Ca2H67VtaaD8awAEF3zbE1nZRAa7a8vbU25c80YBYJBaW8P6FwXQI-K0Xk5MakwYeMMnIrm6w6IS_0XAO5YlD453GLqnxY8H1BEnRpfOnT7PE4el9mJ8MuYQMo6R2up0lGCmYM0YA9FORjroM3ng69SEPfJPCReG7LfJkERl_m2U403ertDRBYrlqCDagDfyI500srBcMrjSvV3oNouyyx3yZUrjLQfbHhDteQFsYdmakJs8Y-Q9-5MXCcrz6Qa4xwv522Euv0CCxkHcawAEYjfsU_zDhUZA1ey1aquWXlFOnx-iEALqxW1slDYHwQ1M2SILc-v_E6i1doa5e_bAZHVezBHFAlaNAVedNyHFFJxYAqAK3hbzbvl2glw3Q6h_rTXElymloqtaqVFIJ-oUWWOHsZBmu8EDA-HzvGCiBa_GbRaVfh2lE4ObeMXoJrEm_5dbxxeEic2l3IYeIz40N9ooQQOkQcOZdY4AXWYCavIAwWEJBjLtptJgCLu9a_zM1S5GsiyJHpdDs46WbP0EawAEWZ-95Sf0YAHujxRNLdXgpqe0ZF8loVwzZfvyMvqaxF1Ug274BqHuY_c5NdPAzuqoTwjfEn8NKEoaNqlumM75FUYbaTd7mXvk4WVYWjVnkO40dfQjRB7DYhvj0LBlbndAJ4wJIA2ilPYgjZsXVbNNh3e2j3u9eABd0VaFMbSb8Sz5_31r8HzoWmPJs3HiyuyANGFUA6CvAnMN6K3b-D8BhFZU_nPUTgu80o8_n6LQt-XWbaC_mTHzsnOjzBiPJxlYawAEW3bmOEtStH2T8q7vMkhchImp2-hg9MFYGBmEe9sSByTn3NUf8eksqXOC1dUjHkXoZm298FgUYLkNdnlxWpf993j5mEDoFxjcTB7scBD7k6nu6Nrs_wK0-seS8gsHrx9UK7GwAsi10q82Cm4PFyAtrWjmy_d9WLHuZt6VIOKunTs8cf0FwNUiMcvZsruqIFJcP7iWxdiFdUkh65P_iCz1ZEjJcj2GEZoq4v3a3by1aizGPaaiKc1jd_T-XJg_YpncawAEWnstu5b9WiZv0x8xfsiMk6YRlU0Cnj5svxLLXz_8drvwAa--GBY5yH0ke2EM6udMEi2EPeFcGTe6Sjs0YEhSbY7Uad_8suD2J4tIWJSWBbiyvh7rSqzv57m7BlsVcHfQJn_wNH-UlC9xkx8vg-LwfN8_FlxvHNPTc7XZG3lKYbwpUWlZxAziOYT1VQ-2K2bQQBBMdix-ht_SjccL1Dc2dP5kDazQ8yZV_8xnyeheazEedWe63uutfkHlZRg9YwP8=",
                       "type": "validator",
-                       "lastSeen": 1575915094967382800
+                       "lastSeen": 1575915094967382800,
+                       "version": "0.1.0"
                     }
                   ],
                   "mixNodes": [
@@ -101,42 +105,49 @@ mod topology_requests {
                       "host": "35.176.155.107:1789",
                       "pubKey": "zSob16499jT7C3S3ky4GihNOjlU6aLfSRkf1xAxOwV0=",
                       "layer": 3,
-                       "lastSeen": 1575915096805374500
+                       "lastSeen": 1575915096805374500,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "18.130.86.190:1789",
                       "pubKey": "vCdpFc0NvW0NSqsuTxtjFtiSY35aXesgT3JNA8sSIXk=",
                       "layer": 1,
-                       "lastSeen": 1575915097370376000
+                       "lastSeen": 1575915097370376000,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "3.10.22.152:1789",
                       "pubKey": "OwOqwWjh_IlnaWS2PxO6odnhNahOYpRCkju50beQCTA=",
                       "layer": 1,
-                       "lastSeen": 1575915097639423500
+                       "lastSeen": 1575915097639423500,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "35.178.213.77:1789",
                       "pubKey": "nkkrUjgL8UJk05QydvWvFSvtRB6nmeV8RMvH5540J3s=",
                       "layer": 2,
-                       "lastSeen": 1575915097895166500
+                       "lastSeen": 1575915097895166500,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "52.56.99.196:1789",
                       "pubKey": "whHuBuEc6zyOZOquKbuATaH4Crml61V_3Y-MztpWhF4=",
                       "layer": 2,
-                       "lastSeen": 1575915096255174700
+                       "lastSeen": 1575915096255174700,
+                       "version": "0.1.0"
                     },
                     {
                       "host": "3.9.12.238:1789",
                       "pubKey": "vk5Sr-Xyi0cTbugACv8U42ZJ6hs6cGDox0rpmXY94Fc=",
                       "layer": 3,
-                       "lastSeen": 1575915096497827600
+                       "lastSeen": 1575915096497827600,
+                       "version": "0.1.0"
                     }
                   ],
                   "mixProviderNodes": [
                     {
-                       "host": "3.8.176.11:1789",
+                       "clientListener": "3.8.176.11:8888",
+                       "mixnetListener": "3.8.176.11:9999",
                       "pubKey": "54U6krAr-j9nQXFlsHk3io04_p0tctuqH71t7w_usgI=",
                       "registeredClients": [
                         {
@@ -248,10 +259,12 @@ mod topology_requests {
                           "pubKey": "COGdpfhmzNGR6YX820GqJIkjOihL8mr6-h-d3JlTDFA="
                         }
                       ],
-                       "lastSeen": 1575915097358694100
+                       "lastSeen": 1575915097358694100,
+                       "version": "0.1.0"
                     },
                     {
-                       "host": "35.178.212.193:1789",
+                       "clientListener": "3.8.176.12:8888",
+                       "mixnetListener": "3.8.176.12:9999",
                       "pubKey": "sA-sxi038pEbGy4lgZWG-RdHHDkA6kZzu44G0LUxFSc=",
                       "registeredClients": [
                         {
@@ -297,7 +310,8 @@ mod topology_requests {
                           "pubKey": "w1bfLpnd3rWu5JczB0nQfnE2S6nUCbx2AA7HDE48DQo="
                         }
                       ],
-                       "lastSeen": 1575915097869025000
+                       "lastSeen": 1575915097869025000,
+                       "version": "0.1.0"
                     }
                   ]
                 }"#.to_string()
@@ -0,0 +1,23 @@
+[package]
+name = "mix-client"
+version = "0.1.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log = "0.4.8"
+pretty_env_logger = "0.3"
+rand = "0.7.2"
+rand_distr = "0.2.2"
+tokio = { version = "0.2", features = ["full"] }
+
+## internal
+addressing = {path = "../../addressing"}
+topology = {path = "../../topology"}
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+# sphinx = { path = "../../../../sphinx"}
+
@@ -1,8 +1,11 @@
-use sphinx::route::NodeAddressBytes;
+use log::*;
 use sphinx::SphinxPacket;
 use std::net::SocketAddr;
 use tokio::prelude::*;

+pub mod packet;
+pub mod poisson;
+
 pub struct MixClient {}

 impl MixClient {
@@ -17,8 +20,7 @@ impl MixClient {
        mix_addr: SocketAddr,
    ) -> Result<(), Box<dyn std::error::Error>> {
        let bytes = packet.to_bytes();
-
-        println!("socket addr: {:?}", mix_addr);
+        debug!("Sending to the following address: {:?}", mix_addr);

        let mut stream = tokio::net::TcpStream::connect(mix_addr).await?;
        stream.write_all(&bytes[..]).await?;
@@ -0,0 +1,82 @@
+use addressing;
+use addressing::AddressTypeError;
+use sphinx::route::{Destination, DestinationAddressBytes, SURBIdentifier};
+use sphinx::SphinxPacket;
+use std::net::SocketAddr;
+use topology::{NymTopology, NymTopologyError};
+
+pub const LOOP_COVER_MESSAGE_PAYLOAD: &[u8] = b"The cake is a lie!";
+pub const LOOP_COVER_MESSAGE_AVERAGE_DELAY: f64 = 2.0;
+
+#[derive(Debug)]
+pub enum SphinxPacketEncapsulationError {
+    NoValidProvidersError,
+    InvalidTopologyError,
+    SphinxEncapsulationError(sphinx::header::SphinxUnwrapError),
+    InvalidFirstMixAddress,
+}
+
+impl From<topology::NymTopologyError> for SphinxPacketEncapsulationError {
+    fn from(_: NymTopologyError) -> Self {
+        use SphinxPacketEncapsulationError::*;
+        InvalidTopologyError
+    }
+}
+
+// it is correct error we're converting from, it just has an unfortunate name
+// related issue: https://github.com/nymtech/sphinx/issues/40
+impl From<sphinx::header::SphinxUnwrapError> for SphinxPacketEncapsulationError {
+    fn from(err: sphinx::header::SphinxUnwrapError) -> Self {
+        use SphinxPacketEncapsulationError::*;
+        SphinxEncapsulationError(err)
+    }
+}
+
+impl From<AddressTypeError> for SphinxPacketEncapsulationError {
+    fn from(_: AddressTypeError) -> Self {
+        use SphinxPacketEncapsulationError::*;
+        InvalidFirstMixAddress
+    }
+}
+
+pub fn loop_cover_message<T: NymTopology>(
+    our_address: DestinationAddressBytes,
+    surb_id: SURBIdentifier,
+    topology: &T,
+) -> Result<(SocketAddr, SphinxPacket), SphinxPacketEncapsulationError> {
+    let destination = Destination::new(our_address, surb_id);
+
+    encapsulate_message(
+        destination,
+        LOOP_COVER_MESSAGE_PAYLOAD.to_vec(),
+        topology,
+        LOOP_COVER_MESSAGE_AVERAGE_DELAY,
+    )
+}
+
+pub fn encapsulate_message<T: NymTopology>(
+    recipient: Destination,
+    message: Vec<u8>,
+    topology: &T,
+    average_delay: f64,
+) -> Result<(SocketAddr, SphinxPacket), SphinxPacketEncapsulationError> {
+    let mut providers = topology.providers();
+    if providers.len() == 0 {
+        return Err(SphinxPacketEncapsulationError::NoValidProvidersError);
+    }
+    // unwrap is fine here as we asserted there is at least single provider
+    let provider = providers.pop().unwrap().into();
+
+    let route = topology.route_to(provider)?;
+
+    let delays = sphinx::header::delays::generate(route.len(), average_delay);
+
+    // build the packet
+    let packet = sphinx::SphinxPacket::new(message, &route[..], &recipient, &delays)?;
+
+    // we know the mix route must be valid otherwise we would have already returned an error
+    let first_node_address =
+        addressing::socket_address_from_encoded_bytes(route.first().unwrap().address.to_bytes())?;
+
+    Ok((first_node_address, packet))
+}
@@ -0,0 +1,9 @@
+use rand_distr::{Distribution, Exp};
+
+pub fn sample(average_delay: f64) -> f64 {
+    // this is our internal code used by our traffic streams
+    // the error is only thrown if average delay is less than 0, which will never happen
+    // so call to unwrap is perfectly safe here
+    let exp = Exp::new(1.0 / average_delay).unwrap();
+    exp.sample(&mut rand::thread_rng())
+}
@@ -0,0 +1,19 @@
+[package]
+name = "provider-client"
+version = "0.1.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+futures = "0.3.1"
+log = "0.4.8"
+pretty_env_logger = "0.3"
+tokio = { version = "0.2", features = ["full"] }
+
+## internal
+sfw-provider-requests = { path = "../../../sfw-provider/sfw-provider-requests" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
@@ -1,4 +1,5 @@
 use futures::io::Error;
+use log::*;
 use sfw_provider_requests::requests::{ProviderRequest, PullRequest, RegisterRequest};
 use sfw_provider_requests::responses::{
    ProviderResponse, ProviderResponseError, PullResponse, RegisterResponse,
@@ -51,13 +52,8 @@ impl ProviderClient {
        our_address: DestinationAddressBytes,
        auth_token: Option<AuthToken>,
    ) -> Self {
-        // DH temporary: the provider's client port is not in the topology, but we can't change that
-        // right now without messing up the existing Go mixnet. So I'm going to hardcode this
-        // for the moment until the Go mixnet goes away.
-        let provider_socket = SocketAddr::new(provider_network_address.ip(), 9000);
-
        ProviderClient {
-            provider_network_address: provider_socket,
+            provider_network_address,
            our_address,
            auth_token,
        }
@@ -69,34 +65,34 @@ impl ProviderClient {

    pub async fn send_request(&self, bytes: Vec<u8>) -> Result<Vec<u8>, ProviderClientError> {
        let mut socket = tokio::net::TcpStream::connect(self.provider_network_address).await?;
-        println!("keep alive: {:?}", socket.keepalive());
-        socket.set_keepalive(Some(Duration::from_secs(2))).unwrap();
+
+        socket.set_keepalive(Some(Duration::from_secs(2)))?;
        socket.write_all(&bytes[..]).await?;
-        if let Err(_e) = socket.shutdown(Shutdown::Write) {
-            // TODO: make it a silent log once we have a proper logging library
-            //            eprintln!("failed to close write part of the socket; err = {:?}", e)
+        if let Err(e) = socket.shutdown(Shutdown::Write) {
+            warn!("failed to close write part of the socket; err = {:?}", e)
        }

        let mut response = Vec::new();
        socket.read_to_end(&mut response).await?;
-        if let Err(_e) = socket.shutdown(Shutdown::Read) {
-            // TODO: make it a silent log once we have a proper logging library
-            //            eprintln!("failed to close read part of the socket; err = {:?}", e)
+        if let Err(e) = socket.shutdown(Shutdown::Read) {
+            debug!("failed to close read part of the socket; err = {:?}. It was probably already closed by the provider", e)
        }

        Ok(response)
    }

    pub async fn retrieve_messages(&self) -> Result<Vec<Vec<u8>>, ProviderClientError> {
-        if self.auth_token.is_none() {
-            return Err(ProviderClientError::EmptyAuthTokenError);
-        }
+        let auth_token = match self.auth_token {
+            Some(token) => token,
+            None => {
+                return Err(ProviderClientError::EmptyAuthTokenError);
+            }
+        };

-        let pull_request = PullRequest::new(self.our_address, self.auth_token.unwrap());
+        let pull_request = PullRequest::new(self.our_address, auth_token);
        let bytes = pull_request.to_bytes();

        let response = self.send_request(bytes).await?;
-        println!("Received the following response: {:?}", response);

        let parsed_response = PullResponse::from_bytes(&response)?;
        Ok(parsed_response.messages)
@@ -115,4 +111,8 @@ impl ProviderClient {

        Ok(parsed_response.auth_token)
    }
+
+    pub fn is_registered(&self) -> bool {
+        self.auth_token.is_some()
+    }
 }
@@ -0,0 +1,11 @@
+[package]
+name = "validator-client"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net>, David Hrycyszyn <dave@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log = "0.4"
+pretty_env_logger = "0.3"
@@ -0,0 +1,7 @@
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn it_works() {
+        assert_eq!(2 + 2, 4);
+    }
+}
@@ -0,0 +1,18 @@
+[package]
+name = "crypto"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bs58 = "0.3.0"
+curve25519-dalek = "1.2.3"
+log = "0.4"
+pretty_env_logger = "0.3"
+rand = "0.7.2"
+rand_os = "0.1"
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
@@ -0,0 +1,39 @@
+use crate::PemStorable;
+
+pub mod x25519;
+
+pub trait MixnetEncryptionKeyPair<Priv, Pub>
+where
+    Priv: MixnetEncryptionPrivateKey,
+    Pub: MixnetEncryptionPublicKey,
+{
+    fn new() -> Self;
+    fn private_key(&self) -> &Priv;
+    fn public_key(&self) -> &Pub;
+    fn from_bytes(priv_bytes: &[u8], pub_bytes: &[u8]) -> Self;
+
+    // TODO: encryption related methods
+}
+
+pub trait MixnetEncryptionPublicKey:
+    Sized + PemStorable + for<'a> From<&'a <Self as MixnetEncryptionPublicKey>::PrivateKeyMaterial>
+{
+    // we need to couple public and private keys together
+    type PrivateKeyMaterial: MixnetEncryptionPrivateKey<PublicKeyMaterial = Self>;
+
+    fn to_bytes(&self) -> Vec<u8>;
+    fn from_bytes(b: &[u8]) -> Self;
+}
+
+pub trait MixnetEncryptionPrivateKey: Sized + PemStorable {
+    // we need to couple public and private keys together
+    type PublicKeyMaterial: MixnetEncryptionPublicKey<PrivateKeyMaterial = Self>;
+
+    /// Returns the associated public key
+    fn public_key(&self) -> Self::PublicKeyMaterial {
+        self.into()
+    }
+
+    fn to_bytes(&self) -> Vec<u8>;
+    fn from_bytes(b: &[u8]) -> Self;
+}
@@ -0,0 +1,99 @@
+use crate::encryption::{
+    MixnetEncryptionKeyPair, MixnetEncryptionPrivateKey, MixnetEncryptionPublicKey,
+};
+use crate::PemStorable;
+use curve25519_dalek::montgomery::MontgomeryPoint;
+use curve25519_dalek::scalar::Scalar;
+
+// TODO: ensure this is a proper name for this considering we are not implementing entire DH here
+
+const CURVE_GENERATOR: MontgomeryPoint = curve25519_dalek::constants::X25519_BASEPOINT;
+
+pub struct KeyPair {
+    pub(crate) private_key: PrivateKey,
+    pub(crate) public_key: PublicKey,
+}
+
+impl MixnetEncryptionKeyPair<PrivateKey, PublicKey> for KeyPair {
+    fn new() -> Self {
+        let mut rng = rand_os::OsRng::new().unwrap();
+        let private_key_value = Scalar::random(&mut rng);
+        let public_key_value = CURVE_GENERATOR * private_key_value;
+
+        KeyPair {
+            private_key: PrivateKey(private_key_value),
+            public_key: PublicKey(public_key_value),
+        }
+    }
+
+    fn private_key(&self) -> &PrivateKey {
+        &self.private_key
+    }
+
+    fn public_key(&self) -> &PublicKey {
+        &self.public_key
+    }
+
+    fn from_bytes(priv_bytes: &[u8], pub_bytes: &[u8]) -> Self {
+        KeyPair {
+            private_key: PrivateKey::from_bytes(priv_bytes),
+            public_key: PublicKey::from_bytes(pub_bytes),
+        }
+    }
+}
+
+// COPY IS DERIVED ONLY TEMPORARILY UNTIL https://github.com/nymtech/nym/issues/47 is fixed
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub struct PrivateKey(pub Scalar);
+
+impl MixnetEncryptionPrivateKey for PrivateKey {
+    type PublicKeyMaterial = PublicKey;
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.0.to_bytes().to_vec()
+    }
+
+    fn from_bytes(b: &[u8]) -> Self {
+        let mut bytes = [0; 32];
+        bytes.copy_from_slice(&b[..]);
+        // due to trait restriction we have no choice but to panic if this fails
+        let key = Scalar::from_canonical_bytes(bytes).unwrap();
+        Self(key)
+    }
+}
+
+impl PemStorable for PrivateKey {
+    fn pem_type(&self) -> String {
+        String::from("X25519 PRIVATE KEY")
+    }
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct PublicKey(pub MontgomeryPoint);
+
+impl<'a> From<&'a PrivateKey> for PublicKey {
+    fn from(pk: &'a PrivateKey) -> Self {
+        PublicKey(CURVE_GENERATOR * pk.0)
+    }
+}
+
+impl MixnetEncryptionPublicKey for PublicKey {
+    type PrivateKeyMaterial = PrivateKey;
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.0.to_bytes().to_vec()
+    }
+
+    fn from_bytes(b: &[u8]) -> Self {
+        let mut bytes = [0; 32];
+        bytes.copy_from_slice(&b[..]);
+        let key = MontgomeryPoint(bytes);
+        Self(key)
+    }
+}
+
+impl PemStorable for PublicKey {
+    fn pem_type(&self) -> String {
+        String::from("X25519 PUBLIC KEY")
+    }
+}
@@ -0,0 +1,162 @@
+use crate::encryption::{
+    MixnetEncryptionKeyPair, MixnetEncryptionPrivateKey, MixnetEncryptionPublicKey,
+};
+use crate::{encryption, PemStorable};
+use bs58;
+use curve25519_dalek::scalar::Scalar;
+use sphinx::route::DestinationAddressBytes;
+
+pub trait MixnetIdentityKeyPair<Priv, Pub>: Clone
+where
+    Priv: MixnetIdentityPrivateKey,
+    Pub: MixnetIdentityPublicKey,
+{
+    fn new() -> Self;
+    fn private_key(&self) -> &Priv;
+    fn public_key(&self) -> &Pub;
+    fn from_bytes(priv_bytes: &[u8], pub_bytes: &[u8]) -> Self;
+
+    // TODO: signing related methods
+}
+
+pub trait MixnetIdentityPublicKey:
+    Sized
+    + PemStorable
+    + Clone
+    + for<'a> From<&'a <Self as MixnetIdentityPublicKey>::PrivateKeyMaterial>
+{
+    // we need to couple public and private keys together
+    type PrivateKeyMaterial: MixnetIdentityPrivateKey<PublicKeyMaterial = Self>;
+
+    fn derive_address(&self) -> DestinationAddressBytes;
+    fn to_bytes(&self) -> Vec<u8>;
+    fn from_bytes(b: &[u8]) -> Self;
+}
+
+pub trait MixnetIdentityPrivateKey: Sized + PemStorable + Clone {
+    // we need to couple public and private keys together
+    type PublicKeyMaterial: MixnetIdentityPublicKey<PrivateKeyMaterial = Self>;
+
+    /// Returns the associated public key
+    fn public_key(&self) -> Self::PublicKeyMaterial {
+        self.into()
+    }
+
+    fn to_bytes(&self) -> Vec<u8>;
+    fn from_bytes(b: &[u8]) -> Self;
+}
+
+// same for validator
+
+// for time being define a dummy identity using x25519 encryption keys (as we've done so far)
+// and replace it with proper keys, like ed25519 later on
+#[derive(Clone)]
+pub struct DummyMixIdentityKeyPair {
+    pub private_key: DummyMixIdentityPrivateKey,
+    pub public_key: DummyMixIdentityPublicKey,
+}
+
+impl MixnetIdentityKeyPair<DummyMixIdentityPrivateKey, DummyMixIdentityPublicKey>
+    for DummyMixIdentityKeyPair
+{
+    fn new() -> Self {
+        let keypair = encryption::x25519::KeyPair::new();
+        DummyMixIdentityKeyPair {
+            private_key: DummyMixIdentityPrivateKey(keypair.private_key),
+            public_key: DummyMixIdentityPublicKey(keypair.public_key),
+        }
+    }
+
+    fn private_key(&self) -> &DummyMixIdentityPrivateKey {
+        &self.private_key
+    }
+
+    fn public_key(&self) -> &DummyMixIdentityPublicKey {
+        &self.public_key
+    }
+
+    fn from_bytes(priv_bytes: &[u8], pub_bytes: &[u8]) -> Self {
+        DummyMixIdentityKeyPair {
+            private_key: DummyMixIdentityPrivateKey::from_bytes(priv_bytes),
+            public_key: DummyMixIdentityPublicKey::from_bytes(pub_bytes),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct DummyMixIdentityPublicKey(encryption::x25519::PublicKey);
+
+impl MixnetIdentityPublicKey for DummyMixIdentityPublicKey {
+    type PrivateKeyMaterial = DummyMixIdentityPrivateKey;
+
+    fn derive_address(&self) -> DestinationAddressBytes {
+        let mut temporary_address = [0u8; 32];
+        let public_key_bytes = self.to_bytes();
+        temporary_address.copy_from_slice(&public_key_bytes[..]);
+
+        temporary_address
+    }
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.0.to_bytes()
+    }
+
+    fn from_bytes(b: &[u8]) -> Self {
+        Self(encryption::x25519::PublicKey::from_bytes(b))
+    }
+}
+
+impl PemStorable for DummyMixIdentityPublicKey {
+    fn pem_type(&self) -> String {
+        format!("DUMMY KEY BASED ON {}", self.0.pem_type())
+    }
+}
+
+impl DummyMixIdentityPublicKey {
+    pub fn to_base58_string(&self) -> String {
+        bs58::encode(&self.to_bytes()).into_string()
+    }
+
+    #[allow(dead_code)]
+    fn from_base58_string(val: String) -> Self {
+        Self::from_bytes(&bs58::decode(&val).into_vec().unwrap())
+    }
+}
+
+// COPY IS DERIVED ONLY TEMPORARILY UNTIL https://github.com/nymtech/nym/issues/47 is fixed
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub struct DummyMixIdentityPrivateKey(pub encryption::x25519::PrivateKey);
+
+impl<'a> From<&'a DummyMixIdentityPrivateKey> for DummyMixIdentityPublicKey {
+    fn from(pk: &'a DummyMixIdentityPrivateKey) -> Self {
+        let private_ref = &pk.0;
+        let public: encryption::x25519::PublicKey = private_ref.into();
+        DummyMixIdentityPublicKey(public)
+    }
+}
+
+impl MixnetIdentityPrivateKey for DummyMixIdentityPrivateKey {
+    type PublicKeyMaterial = DummyMixIdentityPublicKey;
+
+    fn to_bytes(&self) -> Vec<u8> {
+        self.0.to_bytes()
+    }
+
+    fn from_bytes(b: &[u8]) -> Self {
+        Self(encryption::x25519::PrivateKey::from_bytes(b))
+    }
+}
+
+// TODO: this will be implemented differently by using the proper trait
+impl DummyMixIdentityPrivateKey {
+    pub fn as_scalar(self) -> Scalar {
+        let encryption_key = self.0;
+        encryption_key.0
+    }
+}
+
+impl PemStorable for DummyMixIdentityPrivateKey {
+    fn pem_type(&self) -> String {
+        format!("DUMMY KEY BASED ON {}", self.0.pem_type())
+    }
+}
@@ -0,0 +1,9 @@
+pub mod encryption;
+pub mod identity;
+
+// TODO: this trait will need to be moved elsewhere, probably to some 'persistence' crate
+// but since it will need to be used by all identities, it's not really appropriate if it lived in nym-client
+
+pub trait PemStorable {
+    fn pem_type(&self) -> String;
+}
@@ -0,0 +1,33 @@
+[package]
+name = "healthcheck"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+futures = "0.3.1"
+itertools = "0.8.2"
+log = "0.4.8"
+pretty_env_logger = "0.3"
+rand_os = "0.1"
+rand = "0.7.2"
+serde = "1.0.104"
+serde_derive = "1.0.104"
+tokio = { version = "0.2", features = ["full"] }
+
+## internal
+addressing = {path = "../addressing" }
+crypto = { path = "../crypto" }
+directory-client = { path = "../clients/directory-client" }
+mix-client = { path = "../clients/mix-client" }
+provider-client = { path = "../clients/provider-client" }
+sfw-provider-requests = { path = "../../sfw-provider/sfw-provider-requests" }
+topology = {path = "../topology" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+# sphinx = { path = "../../../sphinx"}
+
+[dev-dependencies]
@@ -0,0 +1,15 @@
+use serde_derive::Deserialize;
+
+#[derive(Deserialize, Debug)]
+pub struct HealthCheck {
+    #[serde(rename(deserialize = "directory-server"))]
+    pub directory_server: String,
+
+    pub interval: f64, // in seconds
+
+    #[serde(rename(deserialize = "resolution-timeout"))]
+    pub resolution_timeout: f64, // in seconds
+
+    #[serde(rename(deserialize = "test-packets-per-node"))]
+    pub num_test_packets: usize,
+}
@@ -0,0 +1,117 @@
+use crate::result::HealthCheckResult;
+use crypto::identity::{MixnetIdentityKeyPair, MixnetIdentityPrivateKey, MixnetIdentityPublicKey};
+use directory_client::requests::presence_topology_get::PresenceTopologyGetRequester;
+use directory_client::DirectoryClient;
+use log::{debug, error, info, trace};
+use std::fmt::{Error, Formatter};
+use std::marker::PhantomData;
+use std::time::Duration;
+use topology::NymTopologyError;
+
+pub mod config;
+mod path_check;
+mod result;
+mod score;
+
+#[derive(Debug)]
+pub enum HealthCheckerError {
+    FailedToObtainTopologyError,
+    InvalidTopologyError,
+}
+
+// required by std::error::Error
+impl std::fmt::Display for HealthCheckerError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error> {
+        // just have implementation equivalent to derived debug
+        write!(f, "{:?}", self)
+    }
+}
+
+impl std::error::Error for HealthCheckerError {}
+
+impl From<topology::NymTopologyError> for HealthCheckerError {
+    fn from(_: NymTopologyError) -> Self {
+        use HealthCheckerError::*;
+        InvalidTopologyError
+    }
+}
+
+pub struct HealthChecker<IDPair, Priv, Pub>
+where
+    IDPair: MixnetIdentityKeyPair<Priv, Pub>,
+    Priv: MixnetIdentityPrivateKey,
+    Pub: MixnetIdentityPublicKey,
+{
+    directory_client: directory_client::Client,
+    interval: Duration,
+    num_test_packets: usize,
+    resolution_timeout: Duration,
+    identity_keypair: IDPair,
+
+    _phantom_private: PhantomData<Priv>,
+    _phantom_public: PhantomData<Pub>,
+}
+
+impl<IDPair, Priv, Pub> HealthChecker<IDPair, Priv, Pub>
+where
+    IDPair: crypto::identity::MixnetIdentityKeyPair<Priv, Pub>,
+    Priv: crypto::identity::MixnetIdentityPrivateKey,
+    Pub: crypto::identity::MixnetIdentityPublicKey,
+{
+    pub fn new(config: config::HealthCheck, identity_keypair: IDPair) -> Self {
+        debug!(
+            "healthcheck will be using the following directory server: {:?}",
+            config.directory_server
+        );
+        let directory_client_config = directory_client::Config::new(config.directory_server);
+        HealthChecker {
+            directory_client: directory_client::Client::new(directory_client_config),
+            interval: Duration::from_secs_f64(config.interval),
+            resolution_timeout: Duration::from_secs_f64(config.resolution_timeout),
+            num_test_packets: config.num_test_packets,
+            identity_keypair,
+
+            _phantom_private: PhantomData,
+            _phantom_public: PhantomData,
+        }
+    }
+
+    pub async fn do_check(&self) -> Result<HealthCheckResult, HealthCheckerError> {
+        trace!("going to perform a healthcheck!");
+
+        let current_topology = match self.directory_client.presence_topology.get() {
+            Ok(topology) => topology,
+            Err(err) => {
+                error!("failed to obtain topology - {:?}", err);
+                return Err(HealthCheckerError::FailedToObtainTopologyError);
+            }
+        };
+        trace!("current topology: {:?}", current_topology);
+
+        let mut healthcheck_result = HealthCheckResult::calculate(
+            current_topology,
+            self.num_test_packets,
+            self.resolution_timeout,
+            &self.identity_keypair,
+        )
+        .await;
+        healthcheck_result.sort_scores();
+        Ok(healthcheck_result)
+    }
+
+    pub async fn run(self) -> Result<(), HealthCheckerError> {
+        debug!(
+            "healthcheck will run every {:?} and will send {} packets to each node",
+            self.interval, self.num_test_packets
+        );
+
+        loop {
+            match self.do_check().await {
+                Ok(health) => info!("current network health: \n{}", health),
+                Err(err) => error!("failed to perform healthcheck - {:?}", err),
+            };
+
+            tokio::time::delay_for(self.interval).await;
+        }
+    }
+}
@@ -0,0 +1,280 @@
+use crypto::identity::{MixnetIdentityKeyPair, MixnetIdentityPrivateKey, MixnetIdentityPublicKey};
+use itertools::Itertools;
+use log::{debug, error, info, trace, warn};
+use mix_client::MixClient;
+use provider_client::{ProviderClient, ProviderClientError};
+use sphinx::header::delays::Delay;
+use sphinx::route::{Destination, Node as SphinxNode};
+use std::collections::HashMap;
+use topology::provider;
+
+#[derive(Debug, PartialEq, Clone)]
+pub enum PathStatus {
+    Healthy,
+    Unhealthy,
+    Pending,
+}
+
+pub(crate) struct PathChecker {
+    provider_clients: HashMap<[u8; 32], Option<ProviderClient>>,
+    // currently this is an overkill as MixClient is extremely cheap to create,
+    // however, once we introduce persistent connection between client and layer one mixes,
+    // this will be extremely helpful to have
+    layer_one_clients: HashMap<[u8; 32], Option<MixClient>>,
+    paths_status: HashMap<Vec<u8>, PathStatus>,
+    our_destination: Destination,
+    check_id: [u8; 16],
+}
+
+impl PathChecker {
+    pub(crate) async fn new<IDPair, Priv, Pub>(
+        providers: Vec<provider::Node>,
+        identity_keys: &IDPair,
+        check_id: [u8; 16],
+    ) -> Self
+    where
+        IDPair: MixnetIdentityKeyPair<Priv, Pub>,
+        Priv: MixnetIdentityPrivateKey,
+        Pub: MixnetIdentityPublicKey,
+    {
+        let mut provider_clients = HashMap::new();
+
+        let address = identity_keys.public_key().derive_address();
+
+        for provider in providers {
+            let mut provider_client = ProviderClient::new(provider.client_listener, address, None);
+            let insertion_result = match provider_client.register().await {
+                Ok(token) => {
+                    debug!("registered at provider {}", provider.pub_key);
+                    provider_client.update_token(token);
+                    provider_clients.insert(provider.get_pub_key_bytes(), Some(provider_client))
+                }
+                Err(ProviderClientError::ClientAlreadyRegisteredError) => {
+                    info!("We were already registered");
+                    provider_clients.insert(provider.get_pub_key_bytes(), Some(provider_client))
+                }
+                Err(err) => {
+                    warn!(
+                        "failed to register at provider {} - {:?}",
+                        provider.pub_key, err
+                    );
+                    provider_clients.insert(provider.get_pub_key_bytes(), None)
+                }
+            };
+
+            if insertion_result.is_some() {
+                error!("provider {} already existed!", provider.pub_key);
+            }
+        }
+
+        PathChecker {
+            provider_clients,
+            layer_one_clients: HashMap::new(),
+            our_destination: Destination::new(address, Default::default()),
+            paths_status: HashMap::new(),
+            check_id,
+        }
+    }
+
+    // iteration is used to distinguish packets sent through the same path (as the healthcheck
+    // may try to send say 10 packets through given path)
+    fn unique_path_key(path: &Vec<SphinxNode>, check_id: [u8; 16], iteration: u8) -> Vec<u8> {
+        check_id
+            .iter()
+            .cloned()
+            .chain(std::iter::once(iteration))
+            .chain(
+                path.iter()
+                    .map(|node| node.pub_key.to_bytes().to_vec())
+                    .flatten(),
+            )
+            .collect()
+    }
+
+    pub(crate) fn path_key_to_node_keys(path_key: Vec<u8>) -> Vec<[u8; 32]> {
+        assert_eq!(path_key.len() % 32, 17);
+        path_key
+            .into_iter()
+            .skip(16 + 1) // remove 16 + 1 bytes as it represents check_id and the iteration number which we do not care about now
+            .chunks(32)
+            .into_iter()
+            .map(|key_chunk| {
+                let key_chunk_vec: Vec<_> = key_chunk.collect();
+                let mut key = [0u8; 32];
+                key.copy_from_slice(&key_chunk_vec);
+                key
+            })
+            .collect()
+    }
+
+    fn update_path_statuses(&mut self, messages: Vec<Vec<u8>>) {
+        for msg in messages.into_iter() {
+            // mark path as healthy
+            let previous_status = self.paths_status.insert(msg, PathStatus::Healthy);
+            match previous_status {
+                None => warn!("we received information about unknown path! - perhaps somebody is messing with healthchecker?"),
+                Some(status) => {
+                    if status != PathStatus::Pending {
+                        warn!("we received information about path that WASN'T in PENDING state! (it was in {:?}", status);
+                    }
+                }
+            }
+        }
+    }
+
+    // consume path_checker and return all path statuses
+    pub(crate) fn get_all_statuses(self) -> HashMap<Vec<u8>, PathStatus> {
+        self.paths_status
+    }
+
+    // pull messages from given provider until there are no more 'real' messages
+    async fn resolve_pending_provider_checks(
+        &self,
+        provider_client: &ProviderClient,
+    ) -> Vec<Vec<u8>> {
+        // keep getting messages until we encounter the dummy message
+        let mut provider_messages = Vec::new();
+        loop {
+            match provider_client.retrieve_messages().await {
+                Err(err) => {
+                    error!("failed to fetch provider messages! - {:?}", err);
+                    break;
+                }
+                Ok(messages) => {
+                    let mut should_stop = false;
+                    for msg in messages.into_iter() {
+                        trace!("received provider response: {:?}", msg);
+                        if msg == sfw_provider_requests::DUMMY_MESSAGE_CONTENT {
+                            // finish iterating the loop as the messages might not be ordered
+                            should_stop = true;
+                        } else if msg[..16] != self.check_id {
+                            warn!("received response from previous healthcheck")
+                        } else {
+                            provider_messages.push(msg);
+                        }
+                    }
+                    if should_stop {
+                        break;
+                    }
+                }
+            }
+        }
+        provider_messages
+    }
+
+    pub(crate) async fn resolve_pending_checks(&mut self) {
+        // not sure how to nicely put it into an iterator due to it being async calls
+        let mut provider_messages = Vec::new();
+        for provider_client in self.provider_clients.values() {
+            // if it was none all associated paths were already marked as unhealthy
+            let pc = match provider_client {
+                Some(pc) => pc,
+                None => continue,
+            };
+
+            provider_messages.extend(self.resolve_pending_provider_checks(pc).await);
+        }
+
+        self.update_path_statuses(provider_messages);
+    }
+
+    pub(crate) async fn send_test_packet(&mut self, path: &Vec<SphinxNode>, iteration: u8) {
+        if path.len() == 0 {
+            warn!("trying to send test packet through an empty path!");
+            return;
+        }
+
+        debug!("Checking path: {:?} ({})", path, iteration);
+        let path_identifier = PathChecker::unique_path_key(path, self.check_id, iteration);
+
+        // check if there is even any point in sending the packet
+
+        // does provider exist?
+        let provider_client = self
+            .provider_clients
+            .get(
+                &path
+                    .last()
+                    .expect("We checked the path to contain at least one entry")
+                    .pub_key
+                    .to_bytes(),
+            )
+            .unwrap();
+
+        if provider_client.is_none() {
+            debug!("we can ignore this path as provider itself is inaccessible");
+            if self
+                .paths_status
+                .insert(path_identifier, PathStatus::Unhealthy)
+                .is_some()
+            {
+                panic!("Overwriting path checks!")
+            }
+            return;
+        }
+
+        let layer_one_mix = path
+            .first()
+            .expect("We checked the path to contain at least one entry");
+        let first_node_key = layer_one_mix.pub_key.to_bytes();
+
+        // we generated the bytes data so unwrap is fine
+        let first_node_address =
+            addressing::socket_address_from_encoded_bytes(layer_one_mix.address.to_bytes())
+                .unwrap();
+
+        let first_node_client = self
+            .layer_one_clients
+            .entry(first_node_key)
+            .or_insert(Some(mix_client::MixClient::new()));
+
+        if first_node_client.is_none() {
+            debug!("we can ignore this path as layer one mix is inaccessible");
+            if self
+                .paths_status
+                .insert(path_identifier, PathStatus::Unhealthy)
+                .is_some()
+            {
+                panic!("Overwriting path checks!")
+            }
+            return;
+        }
+
+        // we already checked for 'None' case
+        let first_node_client = first_node_client.as_ref().unwrap();
+
+        let delays: Vec<_> = path.iter().map(|_| Delay::new(0)).collect();
+
+        // all of the data used to create the packet was created by us
+        let packet = sphinx::SphinxPacket::new(
+            path_identifier.clone(),
+            &path[..],
+            &self.our_destination,
+            &delays,
+        )
+        .unwrap();
+
+        debug!("sending test packet to {}", first_node_address);
+        match first_node_client.send(packet, first_node_address).await {
+            Err(err) => {
+                info!("failed to send packet to {} - {}", first_node_address, err);
+                if self
+                    .paths_status
+                    .insert(path_identifier, PathStatus::Unhealthy)
+                    .is_some()
+                {
+                    panic!("Overwriting path checks!")
+                }
+            }
+            Ok(_) => {
+                if self
+                    .paths_status
+                    .insert(path_identifier, PathStatus::Pending)
+                    .is_some()
+                {
+                    panic!("Overwriting path checks!")
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,173 @@
+use crate::path_check::{PathChecker, PathStatus};
+use crate::score::NodeScore;
+use crypto::identity::{MixnetIdentityKeyPair, MixnetIdentityPrivateKey, MixnetIdentityPublicKey};
+use log::{debug, error, info, warn};
+use rand_os::rand_core::RngCore;
+use sphinx::route::NodeAddressBytes;
+use std::collections::HashMap;
+use std::fmt::{Error, Formatter};
+use std::time::Duration;
+use topology::NymTopology;
+
+#[derive(Debug)]
+pub struct HealthCheckResult(Vec<NodeScore>);
+
+impl std::fmt::Display for HealthCheckResult {
+    fn fmt(&self, f: &mut Formatter) -> Result<(), Error> {
+        write!(f, "NETWORK HEALTH\n==============\n")?;
+        for score in self.0.iter() {
+            write!(f, "{}\n", score)?
+        }
+        Ok(())
+    }
+}
+
+impl HealthCheckResult {
+    pub fn sort_scores(&mut self) {
+        self.0.sort();
+    }
+
+    fn zero_score<T: NymTopology>(topology: T) -> Self {
+        warn!("The network is unhealthy, could not send any packets - returning zero score!");
+        let mixes = topology.mix_nodes();
+        let providers = topology.providers();
+
+        let health = mixes
+            .into_iter()
+            .map(|node| NodeScore::from_mixnode(node))
+            .chain(
+                providers
+                    .into_iter()
+                    .map(|node| NodeScore::from_provider(node)),
+            )
+            .collect();
+
+        HealthCheckResult(health)
+    }
+
+    // TODO: that is O(n) so maybe not the most efficient considering it will be called n times...
+    fn node_score(&self, node_key: NodeAddressBytes) -> Option<f64> {
+        self.0
+            .iter()
+            .find(|&node_score| node_score.pub_key() == node_key)
+            .map(|node| node.score())
+    }
+
+    pub fn filter_topology_by_score<T: NymTopology>(
+        &self,
+        topology: &T,
+        score_threshold: f64,
+    ) -> T {
+        let filtered_mix_nodes = topology
+            .mix_nodes()
+            .into_iter()
+            .filter(|node| {
+                match self.node_score(NodeAddressBytes::from_base58_string(node.pub_key.clone())) {
+                    None => {
+                        error!("Unknown node in topology - {:?}", node);
+                        false
+                    }
+                    Some(score) => score > score_threshold,
+                }
+            })
+            .collect();
+
+        let filtered_provider_nodes = topology
+            .providers()
+            .into_iter()
+            .filter(|node| {
+                match self.node_score(NodeAddressBytes::from_base58_string(node.pub_key.clone())) {
+                    None => {
+                        error!("Unknown node in topology - {:?}", node);
+                        false
+                    }
+                    Some(score) => score > score_threshold,
+                }
+            })
+            .collect();
+        // coco nodes remain unchanged as no healthcheck is being run on them or time being
+        let filtered_coco_nodes = topology.coco_nodes();
+
+        T::new_from_nodes(
+            filtered_mix_nodes,
+            filtered_provider_nodes,
+            filtered_coco_nodes,
+        )
+    }
+
+    fn generate_check_id() -> [u8; 16] {
+        let mut id = [0u8; 16];
+        let mut rng = rand_os::OsRng::new().unwrap();
+        rng.fill_bytes(&mut id);
+        id
+    }
+
+    pub async fn calculate<T, IDPair, Priv, Pub>(
+        topology: T,
+        iterations: usize,
+        resolution_timeout: Duration,
+        identity_keys: &IDPair,
+    ) -> Self
+    where
+        T: NymTopology,
+        IDPair: MixnetIdentityKeyPair<Priv, Pub>,
+        Priv: MixnetIdentityPrivateKey,
+        Pub: MixnetIdentityPublicKey,
+    {
+        // currently healthchecker supports only up to 255 iterations - if we somehow
+        // find we need more, it's relatively easy change
+        assert!(iterations <= 255);
+
+        let check_id = Self::generate_check_id();
+
+        let all_paths = match topology.all_paths() {
+            Ok(paths) => paths,
+            Err(_) => return Self::zero_score(topology),
+        };
+
+        // create entries for all nodes
+        let mut score_map = HashMap::new();
+        topology.mix_nodes().into_iter().for_each(|node| {
+            score_map.insert(node.get_pub_key_bytes(), NodeScore::from_mixnode(node));
+        });
+
+        topology.providers().into_iter().for_each(|node| {
+            score_map.insert(node.get_pub_key_bytes(), NodeScore::from_provider(node));
+        });
+
+        let providers = topology.providers();
+
+        let mut path_checker = PathChecker::new(providers, identity_keys, check_id).await;
+        for i in 0..iterations {
+            debug!("running healthcheck iteration {} / {}", i + 1, iterations);
+            for path in &all_paths {
+                path_checker.send_test_packet(&path, i as u8).await;
+                // increase sent count for each node
+                for node in path {
+                    let current_node_score = score_map.get_mut(&node.pub_key.0).unwrap();
+                    current_node_score.increase_sent_packet_count();
+                }
+            }
+        }
+
+        info!(
+            "waiting {:?} for pending requests to resolve",
+            resolution_timeout
+        );
+        tokio::time::delay_for(resolution_timeout).await;
+        path_checker.resolve_pending_checks().await;
+
+        let all_statuses = path_checker.get_all_statuses();
+        for (path_key, status) in all_statuses.into_iter() {
+            let node_keys = PathChecker::path_key_to_node_keys(path_key);
+            for node in node_keys {
+                if status == PathStatus::Healthy {
+                    let current_node_score = score_map.get_mut(&node).unwrap();
+                    current_node_score.increase_received_packet_count();
+                }
+            }
+        }
+
+        HealthCheckResult(score_map.into_iter().map(|(_, v)| v).collect())
+    }
+}
@@ -0,0 +1,166 @@
+use log::error;
+use sphinx::route::NodeAddressBytes;
+use std::cmp::Ordering;
+use std::fmt::Error;
+use std::fmt::Formatter;
+use std::net::SocketAddr;
+use topology::mix;
+use topology::provider;
+
+// TODO: should 'nodetype' really be part of healthcheck::score
+
+#[derive(Debug, Eq, PartialEq, PartialOrd, Ord, Clone, Copy)]
+pub(crate) enum NodeType {
+    Mix,
+    MixProvider,
+}
+
+impl std::fmt::Display for NodeType {
+    fn fmt(&self, f: &mut Formatter) -> Result<(), Error> {
+        match self {
+            NodeType::Mix => write!(f, "Mix"),
+            NodeType::MixProvider => write!(f, "MixProvider"),
+        }
+    }
+}
+
+#[derive(Debug, Eq)]
+pub(crate) struct NodeScore {
+    typ: NodeType,
+    pub_key: NodeAddressBytes,
+    addresses: Vec<SocketAddr>,
+    version: String,
+    layer: String,
+    packets_sent: u64,
+    packets_received: u64,
+}
+
+impl Ord for NodeScore {
+    // order by: version, layer, sent, received, pubkey; ignore addresses
+    fn cmp(&self, other: &Self) -> Ordering {
+        if self.typ > other.typ {
+            return Ordering::Greater;
+        } else if self.typ < other.typ {
+            return Ordering::Less;
+        }
+        if self.version > other.version {
+            return Ordering::Greater;
+        } else if self.version < other.version {
+            return Ordering::Less;
+        }
+        if self.layer > other.layer {
+            return Ordering::Greater;
+        } else if self.layer < other.layer {
+            return Ordering::Less;
+        }
+        if self.packets_sent > other.packets_sent {
+            return Ordering::Greater;
+        } else if self.packets_sent < other.packets_sent {
+            return Ordering::Less;
+        }
+        if self.packets_received > other.packets_received {
+            return Ordering::Greater;
+        } else if self.packets_received < other.packets_received {
+            return Ordering::Less;
+        }
+        if self.pub_key > other.pub_key {
+            return Ordering::Greater;
+        } else if self.pub_key < other.pub_key {
+            return Ordering::Less;
+        }
+
+        Ordering::Equal
+    }
+}
+
+impl PartialOrd for NodeScore {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl PartialEq for NodeScore {
+    fn eq(&self, other: &Self) -> bool {
+        self.typ == other.typ
+            && self.pub_key == other.pub_key
+            && self.addresses == other.addresses
+            && self.version == other.version
+            && self.layer == other.layer
+            && self.packets_sent == other.packets_sent
+            && self.packets_received == other.packets_received
+    }
+}
+
+impl NodeScore {
+    pub(crate) fn from_mixnode(node: mix::Node) -> Self {
+        NodeScore {
+            typ: NodeType::Mix,
+            pub_key: NodeAddressBytes::from_base58_string(node.pub_key),
+            addresses: vec![node.host],
+            version: node.version,
+            layer: format!("layer {}", node.layer),
+            packets_sent: 0,
+            packets_received: 0,
+        }
+    }
+
+    pub(crate) fn from_provider(node: provider::Node) -> Self {
+        NodeScore {
+            typ: NodeType::MixProvider,
+            pub_key: NodeAddressBytes::from_base58_string(node.pub_key),
+            addresses: vec![node.mixnet_listener, node.client_listener],
+            version: node.version,
+            layer: format!("provider"),
+            packets_sent: 0,
+            packets_received: 0,
+        }
+    }
+
+    pub(crate) fn increase_sent_packet_count(&mut self) {
+        self.packets_sent += 1;
+    }
+
+    pub(crate) fn increase_received_packet_count(&mut self) {
+        self.packets_received += 1;
+    }
+
+    pub(crate) fn score(&self) -> f64 {
+        match self.packets_sent {
+            0 => 0.0,
+            _ => (self.packets_received as f64 / self.packets_sent as f64) * 100.0,
+        }
+    }
+
+    pub(crate) fn pub_key(&self) -> NodeAddressBytes {
+        self.pub_key.clone()
+    }
+}
+
+impl std::fmt::Display for NodeScore {
+    fn fmt(&self, f: &mut Formatter) -> Result<(), std::fmt::Error> {
+        let fmtd_addresses = match self.addresses.len() {
+            1 => format!("{}", self.addresses[0]),
+            2 => format!("{}, {}", self.addresses[0], self.addresses[1]),
+            n => {
+                error!(
+                    "could not format score - node has {} addresses while only 1 or 2 are allowed!",
+                    n
+                );
+                return Err(std::fmt::Error);
+            }
+        };
+        let stringified_key = self.pub_key.to_base58_string();
+        write!(
+            f,
+            "({})\t{}/{}\t({}%)\t|| {}\tv{} <{}> - {}",
+            self.typ,
+            self.packets_received,
+            self.packets_sent,
+            self.score(),
+            self.layer,
+            self.version,
+            fmtd_addresses,
+            stringified_key,
+        )
+    }
+}
@@ -0,0 +1,15 @@
+[package]
+name = "pemstore"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+log = "0.4"
+pem = "0.7.0"
+pretty_env_logger = "0.3"
+
+## internal
+crypto = {path = "../crypto"}
@@ -0,0 +1,15 @@
+use std::path::PathBuf;
+
+pub trait PathFinder {
+    fn config_dir(&self) -> PathBuf;
+    fn private_identity_key(&self) -> PathBuf;
+    fn public_identity_key(&self) -> PathBuf;
+
+    // Optional:
+    fn private_encryption_key(&self) -> Option<PathBuf> {
+        None
+    }
+    fn public_encryption_key(&self) -> Option<PathBuf> {
+        None
+    }
+}
@@ -0,0 +1,100 @@
+use crate::pathfinder::PathFinder;
+use pem::{encode, parse, Pem};
+use std::fs::File;
+use std::io;
+use std::io::prelude::*;
+use std::path::PathBuf;
+
+#[allow(dead_code)]
+pub fn read_mix_encryption_keypair_from_disk(_id: String) -> crypto::encryption::x25519::KeyPair {
+    unimplemented!()
+}
+
+pub struct PemStore {
+    config_dir: PathBuf,
+    private_mix_key: PathBuf,
+    public_mix_key: PathBuf,
+}
+
+impl PemStore {
+    pub fn new<P: PathFinder>(pathfinder: P) -> PemStore {
+        PemStore {
+            config_dir: pathfinder.config_dir(),
+            private_mix_key: pathfinder.private_identity_key(),
+            public_mix_key: pathfinder.public_identity_key(),
+        }
+    }
+
+    pub fn read_identity<IDPair, Priv, Pub>(&self) -> io::Result<IDPair>
+    where
+        IDPair: crypto::identity::MixnetIdentityKeyPair<Priv, Pub>,
+        Priv: crypto::identity::MixnetIdentityPrivateKey,
+        Pub: crypto::identity::MixnetIdentityPublicKey,
+    {
+        let private_pem = self.read_pem_file(self.private_mix_key.clone())?;
+        let public_pem = self.read_pem_file(self.public_mix_key.clone())?;
+
+        let key_pair = IDPair::from_bytes(&private_pem.contents, &public_pem.contents);
+
+        if key_pair.private_key().pem_type() != private_pem.tag {
+            return Err(io::Error::new(
+                io::ErrorKind::Other,
+                "unexpected private key pem tag",
+            ));
+        }
+
+        if key_pair.public_key().pem_type() != public_pem.tag {
+            return Err(io::Error::new(
+                io::ErrorKind::Other,
+                "unexpected public key pem tag",
+            ));
+        }
+
+        Ok(key_pair)
+    }
+
+    fn read_pem_file(&self, filepath: PathBuf) -> io::Result<Pem> {
+        let mut pem_bytes = File::open(filepath)?;
+        let mut buf = Vec::new();
+        pem_bytes.read_to_end(&mut buf)?;
+        parse(&buf).map_err(|e| io::Error::new(io::ErrorKind::Other, e))
+    }
+    // This should be refactored and made more generic for when we have other kinds of
+    // KeyPairs that we want to persist (e.g. validator keypairs, or keys for
+    // signing vs encryption). However, for the moment, it does the job.
+    pub fn write_identity<IDPair, Priv, Pub>(&self, key_pair: IDPair) -> io::Result<()>
+    where
+        IDPair: crypto::identity::MixnetIdentityKeyPair<Priv, Pub>,
+        Priv: crypto::identity::MixnetIdentityPrivateKey,
+        Pub: crypto::identity::MixnetIdentityPublicKey,
+    {
+        std::fs::create_dir_all(self.config_dir.clone())?;
+
+        let private_key = key_pair.private_key();
+        let public_key = key_pair.public_key();
+        self.write_pem_file(
+            self.private_mix_key.clone(),
+            private_key.to_bytes(),
+            private_key.pem_type(),
+        )?;
+        self.write_pem_file(
+            self.public_mix_key.clone(),
+            public_key.to_bytes(),
+            public_key.pem_type(),
+        )?;
+        Ok(())
+    }
+
+    fn write_pem_file(&self, filepath: PathBuf, data: Vec<u8>, tag: String) -> io::Result<()> {
+        let pem = Pem {
+            tag,
+            contents: data,
+        };
+        let key = encode(&pem);
+
+        let mut file = File::create(filepath)?;
+        file.write_all(key.as_bytes())?;
+
+        Ok(())
+    }
+}
@@ -0,0 +1,23 @@
+[package]
+name = "topology"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bs58 = "0.3.0"
+itertools = "0.8.2"
+log = "0.4"
+pretty_env_logger = "0.3"
+rand = "0.7.2"
+serde = { version = "1.0.104", features = ["derive"] }
+
+## internal
+addressing = {path = "../addressing"}
+version-checker = {path = "../version-checker" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+# sphinx = { path = "../../../sphinx"}
@@ -0,0 +1,15 @@
+use crate::filter;
+
+#[derive(Debug, Clone)]
+pub struct Node {
+    pub host: String,
+    pub pub_key: String,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl filter::Versioned for Node {
+    fn version(&self) -> String {
+        self.version.clone()
+    }
+}
@@ -0,0 +1,18 @@
+pub trait Versioned: Clone {
+    fn version(&self) -> String;
+}
+
+pub trait VersionFilterable<T> {
+    fn filter_by_version(&self, expected_version: &str) -> Self;
+}
+
+impl<T: Versioned> VersionFilterable<T> for Vec<T> {
+    fn filter_by_version(&self, expected_version: &str) -> Self {
+        self.iter()
+            .filter(|node| {
+                version_checker::is_minor_version_compatible(&node.version(), expected_version)
+            })
+            .cloned()
+            .collect()
+    }
+}
@@ -0,0 +1,126 @@
+use crate::filter::VersionFilterable;
+use itertools::Itertools;
+use rand::seq::IteratorRandom;
+use sphinx::route::Node as SphinxNode;
+use std::cmp::max;
+use std::collections::HashMap;
+
+pub mod coco;
+mod filter;
+pub mod mix;
+pub mod provider;
+
+pub trait NymTopology: Sized + std::fmt::Debug + Send + Sync {
+    fn new(directory_server: String) -> Self;
+    fn new_from_nodes(
+        mix_nodes: Vec<mix::Node>,
+        mix_provider_nodes: Vec<provider::Node>,
+        coco_nodes: Vec<coco::Node>,
+    ) -> Self;
+    fn mix_nodes(&self) -> Vec<mix::Node>;
+    fn providers(&self) -> Vec<provider::Node>;
+    fn coco_nodes(&self) -> Vec<coco::Node>;
+    fn make_layered_topology(&self) -> Result<HashMap<u64, Vec<mix::Node>>, NymTopologyError> {
+        let mut layered_topology: HashMap<u64, Vec<mix::Node>> = HashMap::new();
+        let mut highest_layer = 0;
+        for mix in self.mix_nodes() {
+            // we need to have extra space for provider
+            if mix.layer > sphinx::constants::MAX_PATH_LENGTH as u64 {
+                return Err(NymTopologyError::InvalidMixLayerError);
+            }
+            highest_layer = max(highest_layer, mix.layer);
+
+            let layer_nodes = layered_topology.entry(mix.layer).or_insert(Vec::new());
+            layer_nodes.push(mix);
+        }
+
+        // verify the topology - make sure there are no gaps and there is at least one node per layer
+        let mut missing_layers = Vec::new();
+        for layer in 1..=highest_layer {
+            if !layered_topology.contains_key(&layer) {
+                missing_layers.push(layer);
+            }
+            if layered_topology[&layer].len() == 0 {
+                missing_layers.push(layer);
+            }
+        }
+
+        if missing_layers.len() > 0 {
+            return Err(NymTopologyError::MissingLayerError(missing_layers));
+        }
+
+        Ok(layered_topology)
+    }
+
+    // Tries to get a route through the mix network
+    fn mix_route(&self) -> Result<Vec<SphinxNode>, NymTopologyError> {
+        let mut layered_topology = self.make_layered_topology()?;
+        let num_layers = layered_topology.len();
+        let route = (1..=num_layers as u64)
+            // unwrap is safe for 'remove' as it it failed, it implied the entry never existed
+            // in the map in the first place which would contradict what we've just done
+            .map(|layer| layered_topology.remove(&layer).unwrap()) // for each layer
+            .map(|nodes| nodes.into_iter().choose(&mut rand::thread_rng()).unwrap()) // choose random node
+            .map(|random_node| random_node.into()) // and convert it into sphinx specific node format
+            .collect();
+
+        Ok(route)
+    }
+
+    // Sets up a route to a specific provider
+    fn route_to(&self, provider_node: SphinxNode) -> Result<Vec<SphinxNode>, NymTopologyError> {
+        Ok(self
+            .mix_route()?
+            .into_iter()
+            .chain(std::iter::once(provider_node))
+            .collect())
+    }
+
+    fn all_paths(&self) -> Result<Vec<Vec<SphinxNode>>, NymTopologyError> {
+        let mut layered_topology = self.make_layered_topology()?;
+        let providers = self.providers();
+
+        let sorted_layers: Vec<Vec<SphinxNode>> = (1..=layered_topology.len() as u64)
+            .map(|layer| layered_topology.remove(&layer).unwrap()) // get all nodes per layer
+            .map(|layer_nodes| layer_nodes.into_iter().map(|node| node.into()).collect()) // convert them into 'proper' sphinx nodes
+            .chain(std::iter::once(
+                providers.into_iter().map(|node| node.into()).collect(),
+            )) // append all providers to the end
+            .collect();
+
+        let all_paths = sorted_layers
+            .into_iter()
+            .multi_cartesian_product() // create all possible paths through that
+            .collect();
+
+        Ok(all_paths)
+    }
+
+    fn filter_node_versions(
+        &self,
+        expected_mix_version: &str,
+        expected_provider_version: &str,
+        expected_coco_version: &str,
+    ) -> Self {
+        let mixes = self.mix_nodes().filter_by_version(expected_mix_version);
+        let providers = self
+            .providers()
+            .filter_by_version(expected_provider_version);
+        let cocos = self.coco_nodes().filter_by_version(expected_coco_version);
+
+        Self::new_from_nodes(mixes, providers, cocos)
+    }
+
+    fn can_construct_path_through(&self) -> bool {
+        match self.make_layered_topology() {
+            Ok(_) => true,
+            Err(_) => false,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum NymTopologyError {
+    InvalidMixLayerError,
+    MissingLayerError(Vec<u64>),
+}
@@ -0,0 +1,37 @@
+use crate::filter;
+use sphinx::route::Node as SphinxNode;
+use sphinx::route::NodeAddressBytes;
+use std::net::SocketAddr;
+
+#[derive(Debug, Clone)]
+pub struct Node {
+    pub host: SocketAddr,
+    pub pub_key: String,
+    pub layer: u64,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl Node {
+    pub fn get_pub_key_bytes(&self) -> [u8; 32] {
+        let mut key_bytes = [0; 32];
+        bs58::decode(&self.pub_key).into(&mut key_bytes).unwrap();
+        key_bytes
+    }
+}
+
+impl filter::Versioned for Node {
+    fn version(&self) -> String {
+        self.version.clone()
+    }
+}
+
+impl Into<SphinxNode> for Node {
+    fn into(self) -> SphinxNode {
+        let address_bytes = addressing::encoded_bytes_from_socket_address(self.host);
+        let key_bytes = self.get_pub_key_bytes();
+        let key = sphinx::key::new(key_bytes);
+
+        SphinxNode::new(NodeAddressBytes::from_bytes(address_bytes), key)
+    }
+}
@@ -0,0 +1,43 @@
+use crate::filter;
+use sphinx::route::Node as SphinxNode;
+use sphinx::route::NodeAddressBytes;
+use std::net::SocketAddr;
+
+#[derive(Debug, Clone)]
+pub struct Client {
+    pub pub_key: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct Node {
+    pub client_listener: SocketAddr,
+    pub mixnet_listener: SocketAddr,
+    pub pub_key: String,
+    pub registered_clients: Vec<Client>,
+    pub last_seen: u64,
+    pub version: String,
+}
+
+impl Node {
+    pub fn get_pub_key_bytes(&self) -> [u8; 32] {
+        let mut key_bytes = [0; 32];
+        bs58::decode(&self.pub_key).into(&mut key_bytes).unwrap();
+        key_bytes
+    }
+}
+
+impl filter::Versioned for Node {
+    fn version(&self) -> String {
+        self.version.clone()
+    }
+}
+
+impl Into<SphinxNode> for Node {
+    fn into(self) -> SphinxNode {
+        let address_bytes = addressing::encoded_bytes_from_socket_address(self.mixnet_listener);
+        let key_bytes = self.get_pub_key_bytes();
+        let key = sphinx::key::new(key_bytes);
+
+        SphinxNode::new(NodeAddressBytes::from_bytes(address_bytes), key)
+    }
+}
@@ -0,0 +1,3 @@
+/target
+**/*.rs.bk
+Cargo.lock
@@ -0,0 +1,10 @@
+[package]
+name = "version-checker"
+version = "0.1.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+semver = "0.9.0"
@@ -0,0 +1,69 @@
+use semver::Version;
+
+/// Checks whether given `version` is compatible with a given semantic version requirement `req`
+/// according to major-minor semver rules. The semantic version requirement can be passed as a full,
+/// concrete version number, because that's what we'll have in our Cargo.toml files (e.g. 0.3.2).
+/// The patch number in the requirement gets dropped and replaced with a wildcard (0.3.*) as all
+/// minor versions should be compatible with each other.
+pub fn is_minor_version_compatible(version: &str, req: &str) -> bool {
+    let expected_version = match Version::parse(version) {
+        Ok(v) => v,
+        Err(_) => return false,
+    };
+    let req_version = match Version::parse(req) {
+        Ok(v) => v,
+        Err(_) => return false,
+    };
+
+    expected_version.major == req_version.major && expected_version.minor == req_version.minor
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn version_0_3_0_is_compatible_with_requirement_0_3_x() {
+        assert!(is_minor_version_compatible("0.3.0", "0.3.2"));
+    }
+
+    #[test]
+    fn version_0_3_1_is_compatible_with_minimum_requirement_0_3_x() {
+        assert!(is_minor_version_compatible("0.3.1", "0.3.2"));
+    }
+
+    #[test]
+    fn version_0_3_2_is_compatible_with_minimum_requirement_0_3_x() {
+        assert!(is_minor_version_compatible("0.3.2", "0.3.0"));
+    }
+
+    #[test]
+    fn version_0_2_0_is_not_compatible_with_requirement_0_3_x() {
+        assert!(!is_minor_version_compatible("0.2.0", "0.3.2"));
+    }
+
+    #[test]
+    fn version_0_4_0_is_not_compatible_with_requirement_0_3_x() {
+        assert!(!is_minor_version_compatible("0.4.0", "0.3.2"));
+    }
+
+    #[test]
+    fn version_1_3_2_is_not_compatible_with_requirement_0_3_x() {
+        assert!(!is_minor_version_compatible("1.3.2", "0.3.2"));
+    }
+
+    #[test]
+    fn version_0_4_0_rc_1_is_compatible_with_version_0_4_0_rc_1() {
+        assert!(is_minor_version_compatible("0.4.0-rc.1", "0.4.0-rc.1"));
+    }
+
+    #[test]
+    fn returns_false_on_foo_version() {
+        assert!(!is_minor_version_compatible("foo", "0.3.2"));
+    }
+
+    #[test]
+    fn returns_false_on_bar_version() {
+        assert!(!is_minor_version_compatible("0.3.2", "bar"));
+    }
+}
@@ -0,0 +1,28 @@
+[package]
+build = "build.rs"
+name = "nym-mixnode"
+version = "0.4.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bs58 = "0.3.0"
+clap = "2.33.0"
+curve25519-dalek = "1.2.3"
+dotenv = "0.15.0"
+futures = "0.3.1"
+log = "0.4"
+pretty_env_logger = "0.3"
+tokio = { version = "0.2", features = ["full"] }
+
+## internal
+addressing = {path = "../common/addressing" }
+directory-client = { path = "../common/clients/directory-client" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+
+[build-dependencies]
+built = "0.3.2"
@@ -0,0 +1,11 @@
+# Nym Mixnode
+
+A Rust mixnode implementation.
+
+## Usage
+
+* `nym-mixnode` prints a help message showing usage options
+* `nym-mixnode run --help` prints a help message showing usage options for the run command
+* `nym-mixnode run --layer 1 --host x.x.x.x` will start the mixnode in layer 1 and bind to the specified host IP address. Coordinate with other people in your network to find out which layer needs coverage.
+
+By default, the Nym Mixnode will start on port 1789. If desired, you can change the port using the `--port` option.
@@ -0,0 +1,97 @@
+use clap::{App, Arg, ArgMatches, SubCommand};
+use log::*;
+use std::process;
+
+mod mix_peer;
+mod node;
+
+fn main() {
+    dotenv::dotenv().ok();
+    pretty_env_logger::init();
+
+    let arg_matches = App::new("Nym Mixnode")
+        .version(built_info::PKG_VERSION)
+        .author("Nymtech")
+        .about("Implementation of the Loopix-based Mixnode")
+        .subcommand(
+            SubCommand::with_name("run")
+                .about("Starts the mixnode")
+                .arg(
+                    Arg::with_name("host")
+                        .long("host")
+                        .help("The custom host on which the mixnode will be running")
+                        .takes_value(true)
+                        .required(true),
+                )
+                .arg(
+                    Arg::with_name("port")
+                        .long("port")
+                        .help("The port on which the mixnode will be listening")
+                        .takes_value(true),
+                )
+                .arg(
+                    Arg::with_name("layer")
+                        .long("layer")
+                        .help("The mixnet layer of this particular node")
+                        .takes_value(true)
+                        .required(true),
+                )
+                .arg(
+                    Arg::with_name("announce_host")
+                        .long("announce-host")
+                        .help("The host that will be reported to the directory server")
+                        .takes_value(true)
+                )
+                .arg(
+                    Arg::with_name("announce_port")
+                        .long("announce-port")
+                        .help("The port that will be reported to the directory server")
+                        .takes_value(true)
+                )
+                .arg(
+                    Arg::with_name("directory")
+                        .long("directory")
+                        .help("Address of the directory server the node is sending presence and metrics to")
+                        .takes_value(true),
+                ),
+        )
+        .get_matches();
+
+    if let Err(e) = execute(arg_matches) {
+        error!("{}", e);
+        process::exit(1);
+    }
+}
+
+pub mod built_info {
+    // The file has been placed there by the build script.
+    include!(concat!(env!("OUT_DIR"), "/built.rs"));
+}
+
+fn execute(matches: ArgMatches) -> Result<(), String> {
+    match matches.subcommand() {
+        ("run", Some(m)) => Ok(node::runner::start(m)),
+        _ => Err(usage()),
+    }
+}
+
+fn usage() -> String {
+    banner() + "usage: --help to see available options.\n\n"
+}
+
+fn banner() -> String {
+    format!(
+        r#"
+
+      _ __  _   _ _ __ ___
+     | '_ \| | | | '_ \ _ \
+     | | | | |_| | | | | | |
+     |_| |_|\__, |_| |_| |_|
+            |___/
+
+             (mixnode - version {:})
+
+    "#,
+        built_info::PKG_VERSION
+    )
+}
@@ -0,0 +1,46 @@
+use addressing;
+use addressing::AddressTypeError;
+use sphinx::route::NodeAddressBytes;
+use std::error::Error;
+use std::net::SocketAddr;
+use tokio::prelude::*;
+
+#[derive(Debug)]
+pub struct MixPeer {
+    connection: SocketAddr,
+}
+
+#[derive(Debug)]
+pub enum MixPeerError {
+    InvalidAddressError,
+}
+
+impl From<addressing::AddressTypeError> for MixPeerError {
+    fn from(_: AddressTypeError) -> Self {
+        use MixPeerError::*;
+
+        InvalidAddressError
+    }
+}
+
+impl MixPeer {
+    // note that very soon `next_hop_address` will be changed to `next_hop_metadata`
+    pub fn new(next_hop_address: NodeAddressBytes) -> Result<MixPeer, MixPeerError> {
+        let next_hop_socket_address =
+            addressing::socket_address_from_encoded_bytes(next_hop_address.to_bytes())?;
+        Ok(MixPeer {
+            connection: next_hop_socket_address,
+        })
+    }
+
+    pub async fn send(&self, bytes: Vec<u8>) -> Result<(), Box<dyn Error>> {
+        let next_hop_address = self.connection.clone();
+        let mut stream = tokio::net::TcpStream::connect(next_hop_address).await?;
+        stream.write_all(&bytes).await?;
+        Ok(())
+    }
+
+    pub fn to_string(&self) -> String {
+        self.connection.to_string()
+    }
+}
@@ -0,0 +1,95 @@
+use directory_client::metrics::MixMetric;
+use directory_client::requests::metrics_mixes_post::MetricsMixPoster;
+use directory_client::DirectoryClient;
+use futures::channel::mpsc;
+use futures::lock::Mutex;
+use futures::StreamExt;
+use log::{debug, error};
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+const METRICS_INTERVAL: u64 = 3;
+
+#[derive(Debug)]
+pub struct MetricsReporter {
+    received: u64,
+    sent: HashMap<String, u64>,
+}
+
+impl MetricsReporter {
+    pub(crate) fn new() -> Self {
+        MetricsReporter {
+            received: 0,
+            sent: HashMap::new(),
+        }
+    }
+
+    pub(crate) fn add_arc_mutex(self) -> Arc<Mutex<Self>> {
+        Arc::new(Mutex::new(self))
+    }
+
+    async fn increment_received_metrics(metrics: Arc<Mutex<MetricsReporter>>) {
+        let mut unlocked = metrics.lock().await;
+        unlocked.received += 1;
+    }
+
+    pub(crate) async fn run_received_metrics_control(
+        metrics: Arc<Mutex<MetricsReporter>>,
+        mut rx: mpsc::Receiver<()>,
+    ) {
+        while let Some(_) = rx.next().await {
+            MetricsReporter::increment_received_metrics(metrics.clone()).await;
+        }
+    }
+
+    async fn increment_sent_metrics(metrics: Arc<Mutex<MetricsReporter>>, sent_to: String) {
+        let mut unlocked = metrics.lock().await;
+        let receiver_count = unlocked.sent.entry(sent_to).or_insert(0);
+        *receiver_count += 1;
+    }
+
+    pub(crate) async fn run_sent_metrics_control(
+        metrics: Arc<Mutex<MetricsReporter>>,
+        mut rx: mpsc::Receiver<String>,
+    ) {
+        while let Some(sent_metric) = rx.next().await {
+            MetricsReporter::increment_sent_metrics(metrics.clone(), sent_metric).await;
+        }
+    }
+
+    async fn acquire_and_reset_metrics(
+        metrics: Arc<Mutex<MetricsReporter>>,
+    ) -> (u64, HashMap<String, u64>) {
+        let mut unlocked = metrics.lock().await;
+        let received = unlocked.received;
+
+        let sent = std::mem::replace(&mut unlocked.sent, HashMap::new());
+        unlocked.received = 0;
+
+        (received, sent)
+    }
+
+    pub(crate) async fn run_metrics_sender(
+        metrics: Arc<Mutex<MetricsReporter>>,
+        cfg: directory_client::Config,
+        pub_key_str: String,
+    ) {
+        let delay_duration = Duration::from_secs(METRICS_INTERVAL);
+        let directory_client = directory_client::Client::new(cfg);
+        loop {
+            tokio::time::delay_for(delay_duration).await;
+            let (received, sent) =
+                MetricsReporter::acquire_and_reset_metrics(metrics.clone()).await;
+
+            match directory_client.metrics_post.post(&MixMetric {
+                pub_key: pub_key_str.clone(),
+                received,
+                sent,
+            }) {
+                Err(err) => error!("failed to send metrics - {:?}", err),
+                Ok(_) => debug!("sent metrics information"),
+            }
+        }
+    }
+}
@@ -0,0 +1,292 @@
+use crate::mix_peer::MixPeer;
+use crate::node;
+use crate::node::metrics::MetricsReporter;
+use curve25519_dalek::montgomery::MontgomeryPoint;
+use curve25519_dalek::scalar::Scalar;
+use futures::channel::mpsc;
+use futures::lock::Mutex;
+use futures::SinkExt;
+use log::*;
+use sphinx::header::delays::Delay as SphinxDelay;
+use sphinx::{ProcessedPacket, SphinxPacket};
+use std::net::SocketAddr;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::prelude::*;
+use tokio::runtime::Runtime;
+
+mod metrics;
+mod presence;
+pub mod runner;
+
+pub struct Config {
+    announce_address: String,
+    directory_server: String,
+    layer: usize,
+    public_key: MontgomeryPoint,
+    secret_key: Scalar,
+    socket_address: SocketAddr,
+}
+
+impl Config {
+    pub fn public_key_string(&self) -> String {
+        let key_bytes = self.public_key.to_bytes().to_vec();
+        bs58::encode(&key_bytes).into_string()
+    }
+}
+
+#[derive(Debug)]
+pub enum MixProcessingError {
+    SphinxRecoveryError,
+    ReceivedFinalHopError,
+    SphinxProcessingError,
+    InvalidHopAddress,
+}
+
+impl From<sphinx::ProcessingError> for MixProcessingError {
+    // for time being just have a single error instance for all possible results of sphinx::ProcessingError
+    fn from(_: sphinx::ProcessingError) -> Self {
+        use MixProcessingError::*;
+
+        SphinxRecoveryError
+    }
+}
+
+struct ForwardingData {
+    packet: SphinxPacket,
+    delay: SphinxDelay,
+    recipient: MixPeer,
+    sent_metrics_tx: mpsc::Sender<String>,
+}
+
+// TODO: this will need to be changed if MixPeer will live longer than our Forwarding Data
+impl ForwardingData {
+    fn new(
+        packet: SphinxPacket,
+        delay: SphinxDelay,
+        recipient: MixPeer,
+        sent_metrics_tx: mpsc::Sender<String>,
+    ) -> Self {
+        ForwardingData {
+            packet,
+            delay,
+            recipient,
+            sent_metrics_tx,
+        }
+    }
+}
+
+// ProcessingData defines all data required to correctly unwrap sphinx packets
+struct ProcessingData {
+    secret_key: Scalar,
+    received_metrics_tx: mpsc::Sender<()>,
+    sent_metrics_tx: mpsc::Sender<String>,
+}
+
+impl ProcessingData {
+    fn new(
+        secret_key: Scalar,
+        received_metrics_tx: mpsc::Sender<()>,
+        sent_metrics_tx: mpsc::Sender<String>,
+    ) -> Self {
+        ProcessingData {
+            secret_key,
+            received_metrics_tx,
+            sent_metrics_tx,
+        }
+    }
+
+    fn add_arc_mutex(self) -> Arc<Mutex<Self>> {
+        Arc::new(Mutex::new(self))
+    }
+}
+
+struct PacketProcessor;
+
+impl PacketProcessor {
+    pub async fn process_sphinx_data_packet(
+        packet_data: &[u8],
+        processing_data: Arc<Mutex<ProcessingData>>,
+    ) -> Result<ForwardingData, MixProcessingError> {
+        // we received something resembling a sphinx packet, report it!
+        let processing_data = processing_data.lock().await;
+        let mut received_metrics_tx = processing_data.received_metrics_tx.clone();
+
+        // if unwrap failed it means our metrics reporter died, so we should exit application and
+        // force restart
+        if received_metrics_tx.send(()).await.is_err() {
+            error!("failed to send metrics data to the controller - the underlying thread probably died!");
+            std::process::exit(1);
+        }
+
+        let packet = SphinxPacket::from_bytes(packet_data.to_vec())?;
+        let (next_packet, next_hop_address, delay) =
+            match packet.process(processing_data.secret_key) {
+                Ok(ProcessedPacket::ProcessedPacketForwardHop(packet, address, delay)) => {
+                    (packet, address, delay)
+                }
+                Ok(_) => return Err(MixProcessingError::ReceivedFinalHopError),
+                Err(e) => {
+                    warn!("Failed to unwrap Sphinx packet: {:?}", e);
+                    return Err(MixProcessingError::SphinxProcessingError);
+                }
+            };
+
+        let next_mix = match MixPeer::new(next_hop_address) {
+            Ok(next_mix) => next_mix,
+            Err(_) => return Err(MixProcessingError::InvalidHopAddress),
+        };
+
+        let fwd_data = ForwardingData::new(
+            next_packet,
+            delay,
+            next_mix,
+            processing_data.sent_metrics_tx.clone(),
+        );
+        Ok(fwd_data)
+    }
+
+    async fn wait_and_forward(mut forwarding_data: ForwardingData) {
+        let delay_duration = Duration::from_nanos(forwarding_data.delay.get_value());
+        tokio::time::delay_for(delay_duration).await;
+
+        if forwarding_data
+            .sent_metrics_tx
+            .send(forwarding_data.recipient.to_string())
+            .await
+            .is_err()
+        {
+            error!("failed to send metrics data to the controller - the underlying thread probably died!");
+            std::process::exit(1);
+        }
+
+        trace!("RECIPIENT: {:?}", forwarding_data.recipient);
+        match forwarding_data
+            .recipient
+            .send(forwarding_data.packet.to_bytes())
+            .await
+        {
+            Ok(()) => (),
+            Err(e) => {
+                warn!(
+                    "failed to write bytes to next mix peer. err = {:?}",
+                    e.to_string()
+                );
+            }
+        }
+    }
+}
+
+// the MixNode will live for whole duration of this program
+pub struct MixNode {
+    directory_server: String,
+    network_address: SocketAddr,
+    public_key: MontgomeryPoint,
+    secret_key: Scalar,
+    // TODO: use it later to enforce forward travel
+    //    layer: usize,
+}
+
+impl MixNode {
+    pub fn new(config: &Config) -> Self {
+        MixNode {
+            directory_server: config.directory_server.clone(),
+            network_address: config.socket_address,
+            secret_key: config.secret_key,
+            public_key: config.public_key,
+            //            layer: config.layer,
+        }
+    }
+
+    async fn process_socket_connection(
+        mut socket: tokio::net::TcpStream,
+        processing_data: Arc<Mutex<ProcessingData>>,
+    ) {
+        let mut buf = [0u8; sphinx::PACKET_SIZE];
+
+        // In a loop, read data from the socket and write the data back.
+        loop {
+            match socket.read(&mut buf).await {
+                // socket closed
+                Ok(n) if n == 0 => {
+                    trace!("Remote connection closed.");
+                    return;
+                }
+                Ok(_) => {
+                    let fwd_data = match PacketProcessor::process_sphinx_data_packet(
+                        buf.as_ref(),
+                        processing_data.clone(),
+                    )
+                    .await
+                    {
+                        Ok(fwd_data) => fwd_data,
+                        Err(e) => {
+                            warn!("failed to process sphinx packet: {:?}", e);
+                            return;
+                        }
+                    };
+                    PacketProcessor::wait_and_forward(fwd_data).await;
+                }
+                Err(e) => {
+                    warn!("failed to read from socket; err = {:?}", e);
+                    return;
+                }
+            };
+
+            // Write the some data back
+            if let Err(e) = socket.write_all(b"foomp").await {
+                warn!("failed to write reply to socket; err = {:?}", e);
+                return;
+            }
+        }
+    }
+
+    pub fn start(&self, config: node::Config) -> Result<(), Box<dyn std::error::Error>> {
+        // Create the runtime, probably later move it to MixNode itself?
+        let mut rt = Runtime::new()?;
+
+        let (received_tx, received_rx) = mpsc::channel(1024);
+        let (sent_tx, sent_rx) = mpsc::channel(1024);
+
+        let directory_cfg = directory_client::Config {
+            base_url: self.directory_server.clone(),
+        };
+        let pub_key_str = bs58::encode(&self.public_key.to_bytes().to_vec()).into_string();
+
+        rt.spawn({
+            let presence_notifier = presence::Notifier::new(&config);
+            presence_notifier.run()
+        });
+
+        let metrics = MetricsReporter::new().add_arc_mutex();
+        rt.spawn(MetricsReporter::run_received_metrics_control(
+            metrics.clone(),
+            received_rx,
+        ));
+        rt.spawn(MetricsReporter::run_sent_metrics_control(
+            metrics.clone(),
+            sent_rx,
+        ));
+        rt.spawn(MetricsReporter::run_metrics_sender(
+            metrics,
+            directory_cfg,
+            pub_key_str,
+        ));
+
+        // Spawn the root task
+        rt.block_on(async {
+            let mut listener = tokio::net::TcpListener::bind(self.network_address).await?;
+            let processing_data =
+                ProcessingData::new(self.secret_key, received_tx, sent_tx).add_arc_mutex();
+
+            loop {
+                let (socket, _) = listener.accept().await?;
+
+                let thread_processing_data = processing_data.clone();
+                tokio::spawn(async move {
+                    MixNode::process_socket_connection(socket, thread_processing_data).await;
+                });
+            }
+        })
+    }
+}
@@ -0,0 +1,47 @@
+use crate::node;
+use directory_client::presence::mixnodes::MixNodePresence;
+use directory_client::requests::presence_mixnodes_post::PresenceMixNodesPoster;
+use directory_client::DirectoryClient;
+use log::{debug, error};
+use std::time::Duration;
+
+pub struct Notifier {
+    pub net_client: directory_client::Client,
+    presence: MixNodePresence,
+}
+
+impl Notifier {
+    pub fn new(node_config: &node::Config) -> Notifier {
+        let config = directory_client::Config {
+            base_url: node_config.directory_server.clone(),
+        };
+        let net_client = directory_client::Client::new(config);
+        let presence = MixNodePresence {
+            host: node_config.announce_address.clone(),
+            pub_key: node_config.public_key_string(),
+            layer: node_config.layer as u64,
+            last_seen: 0,
+            version: env!("CARGO_PKG_VERSION").to_string(),
+        };
+        Notifier {
+            net_client,
+            presence,
+        }
+    }
+
+    pub fn notify(&self) {
+        match self.net_client.presence_mix_nodes_post.post(&self.presence) {
+            Err(err) => error!("failed to send presence - {:?}", err),
+            Ok(_) => debug!("sent presence information"),
+        }
+    }
+
+    pub async fn run(self) {
+        let delay_duration = Duration::from_secs(5);
+
+        loop {
+            self.notify();
+            tokio::time::delay_for(delay_duration).await;
+        }
+    }
+}
@@ -0,0 +1,87 @@
+use crate::banner;
+use crate::node;
+use crate::node::MixNode;
+use clap::ArgMatches;
+use std::net::ToSocketAddrs;
+
+fn print_binding_warning(address: &str) {
+    println!("\n##### WARNING #####");
+    println!(
+        "\nYou are trying to bind to {} - you might not be accessible to other nodes",
+        address
+    );
+    println!("\n##### WARNING #####\n");
+}
+
+pub fn start(matches: &ArgMatches) {
+    println!("{}", banner());
+    println!("Starting mixnode...");
+
+    let config = new_config(matches);
+    println!("Public key: {}", config.public_key_string());
+    println!("Directory server: {}", config.directory_server);
+    println!(
+        "Listening for incoming packets on {}",
+        config.socket_address
+    );
+    println!(
+        "Announcing the following socket address: {}",
+        config.announce_address
+    );
+
+    let mix = MixNode::new(&config);
+    mix.start(config).unwrap();
+}
+
+fn new_config(matches: &ArgMatches) -> node::Config {
+    let host = matches.value_of("host").unwrap();
+    if host == "localhost" || host == "127.0.0.1" || host == "0.0.0.0" {
+        print_binding_warning(host);
+    }
+
+    let port = match matches.value_of("port").unwrap_or("1789").parse::<u16>() {
+        Ok(n) => n,
+        Err(err) => panic!("Invalid port value provided - {:?}", err),
+    };
+
+    let layer = match matches.value_of("layer").unwrap().parse::<usize>() {
+        Ok(n) => n,
+        Err(err) => panic!("Invalid layer value provided - {:?}", err),
+    };
+
+    let socket_address = (host, port)
+        .to_socket_addrs()
+        .expect("Failed to combine host and port")
+        .next()
+        .expect("Failed to extract the socket address from the iterator");
+
+    let announce_host = matches.value_of("announce_host").unwrap_or(host);
+    let announce_port = matches
+        .value_of("announce_port")
+        .map(|port| port.parse::<u16>().unwrap())
+        .unwrap_or(port);
+
+    let _ = (announce_host, announce_port)
+        .to_socket_addrs()
+        .expect("Failed to combine announce host and port")
+        .next()
+        .expect("Failed to extract the announce socket address from the iterator");
+
+    let announce_address = format!("{}:{}", announce_host, announce_port);
+
+    let (secret_key, public_key) = sphinx::crypto::keygen();
+
+    let directory_server = matches
+        .value_of("directory")
+        .unwrap_or("https://directory.nymtech.net")
+        .to_string();
+
+    node::Config {
+        directory_server,
+        layer,
+        public_key,
+        socket_address,
+        announce_address,
+        secret_key,
+    }
+}
@@ -0,0 +1,49 @@
+[package]
+build = "build.rs"
+name = "nym-client"
+version = "0.4.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+name = "nym_client"
+path = "src/lib.rs"
+
+[dependencies]
+bs58 = "0.3.0"
+clap = "2.33.0"
+curve25519-dalek = "1.2.3"
+dirs = "2.0.2"
+dotenv = "0.15.0"
+futures = "0.3.1"
+log = "0.4"
+pem = "0.7.0"
+pretty_env_logger = "0.3"
+reqwest = "0.9.22"
+serde = { version = "1.0.104", features = ["derive"] }
+serde_json = "1.0.44"
+tokio = { version = "0.2", features = ["full"] }
+tungstenite = "0.9.2"
+
+## internal
+addressing = {path = "../common/addressing" }
+crypto = {path = "../common/crypto"}
+directory-client = { path = "../common/clients/directory-client" }
+healthcheck = { path = "../common/healthcheck" }
+mix-client = { path = "../common/clients/mix-client" }
+pemstore = {path = "../common/pemstore"}
+provider-client = { path = "../common/clients/provider-client" }
+sfw-provider-requests = { path = "../sfw-provider/sfw-provider-requests" }
+topology = {path = "../common/topology" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+# sphinx = { path = "../../sphinx"}
+
+# putting this explicitly below everything and most likely, the next time we look into it, it will already have a proper release
+tokio-tungstenite = { git = "https://github.com/snapview/tokio-tungstenite", rev="308d9680c0e59dd1e8651659a775c05df937934e" }
+
+[build-dependencies]
+built = "0.3.2"
@@ -0,0 +1,10 @@
+# Nym Client
+
+The Nym Client communicates with the remote, decentralised nodes which make up the Nym system as a whole. 
+
+It needs to handle communication with 3 types of remote nodes. Here's the development status of each:
+
+- [ ] Directory nodes
+- [ ] Mix nodes
+- [ ] Validator nodes
+
@@ -0,0 +1,5 @@
+use built;
+
+fn main() {
+    built::write_built_file().expect("Failed to acquire build-time information");
+}
@@ -0,0 +1,2 @@
+// The file has been placed there by the build script.
+include!(concat!(env!("OUT_DIR"), "/built.rs"));
@@ -0,0 +1,53 @@
+use crate::client::mix_traffic::MixMessage;
+use crate::client::topology_control::TopologyInnerRef;
+use crate::client::LOOP_COVER_AVERAGE_DELAY;
+use futures::channel::mpsc;
+use log::{error, info, trace, warn};
+use sphinx::route::Destination;
+use std::time::Duration;
+use topology::NymTopology;
+
+pub(crate) async fn start_loop_cover_traffic_stream<T: NymTopology>(
+    tx: mpsc::UnboundedSender<MixMessage>,
+    our_info: Destination,
+    topology_ctrl_ref: TopologyInnerRef<T>,
+) {
+    info!("Starting loop cover traffic stream");
+    loop {
+        trace!("next cover message!");
+        let delay = mix_client::poisson::sample(LOOP_COVER_AVERAGE_DELAY);
+        let delay_duration = Duration::from_secs_f64(delay);
+        tokio::time::delay_for(delay_duration).await;
+
+        let read_lock = topology_ctrl_ref.read().await;
+        let topology = match read_lock.topology.as_ref() {
+            None => {
+                warn!("No valid topology detected - won't send any loop cover message this time");
+                continue;
+            }
+            Some(topology) => topology,
+        };
+
+        let cover_message = match mix_client::packet::loop_cover_message(
+            our_info.address,
+            our_info.identifier,
+            topology,
+        ) {
+            Ok(message) => message,
+            Err(err) => {
+                error!(
+                    "Somehow we managed to create an invalid cover message - {:?}",
+                    err
+                );
+                continue;
+            }
+        };
+
+        // if this one fails, there's no retrying because it means that either:
+        // - we run out of memory
+        // - the receiver channel is closed
+        // in either case there's no recovery and we can only panic
+        tx.unbounded_send(MixMessage::new(cover_message.0, cover_message.1))
+            .unwrap();
+    }
+}
@@ -0,0 +1,37 @@
+use futures::channel::mpsc;
+use futures::StreamExt;
+use log::{debug, error, info, trace};
+use sphinx::SphinxPacket;
+use std::net::SocketAddr;
+
+pub(crate) struct MixMessage(SocketAddr, SphinxPacket);
+
+impl MixMessage {
+    pub(crate) fn new(address: SocketAddr, packet: SphinxPacket) -> Self {
+        MixMessage(address, packet)
+    }
+}
+
+pub(crate) struct MixTrafficController;
+
+impl MixTrafficController {
+    pub(crate) async fn run(mut rx: mpsc::UnboundedReceiver<MixMessage>) {
+        info!("Mix Traffic Controller started!");
+        let mix_client = mix_client::MixClient::new();
+        while let Some(mix_message) = rx.next().await {
+            debug!("Got a mix_message for {:?}", mix_message.0);
+            let send_res = mix_client.send(mix_message.1, mix_message.0).await;
+            match send_res {
+                Ok(_) => {
+                    trace!("sent a mix message");
+                }
+                // TODO: should there be some kind of threshold of failed messages
+                // that if reached, the application blows?
+                Err(e) => error!(
+                    "We failed to send the message to {} :( - {:?}",
+                    mix_message.0, e
+                ),
+            };
+        }
+    }
+}
@@ -0,0 +1,249 @@
+use crate::client::mix_traffic::MixTrafficController;
+use crate::client::received_buffer::ReceivedMessagesBuffer;
+use crate::client::topology_control::TopologyInnerRef;
+use crate::sockets::tcp;
+use crate::sockets::ws;
+use crypto::identity::{MixnetIdentityKeyPair, MixnetIdentityPrivateKey, MixnetIdentityPublicKey};
+use directory_client::presence::Topology;
+use futures::channel::mpsc;
+use futures::join;
+use log::*;
+use sfw_provider_requests::AuthToken;
+use sphinx::route::Destination;
+use std::marker::PhantomData;
+use std::net::SocketAddr;
+use tokio::runtime::Runtime;
+use topology::NymTopology;
+
+mod cover_traffic_stream;
+mod mix_traffic;
+mod provider_poller;
+mod real_traffic_stream;
+pub mod received_buffer;
+pub mod topology_control;
+
+// TODO: all of those constants should probably be moved to config file
+const LOOP_COVER_AVERAGE_DELAY: f64 = 0.5;
+// seconds
+const MESSAGE_SENDING_AVERAGE_DELAY: f64 = 0.5;
+//  seconds;
+const FETCH_MESSAGES_DELAY: f64 = 1.0; // seconds;
+
+const TOPOLOGY_REFRESH_RATE: f64 = 10.0; // seconds
+
+pub enum SocketType {
+    TCP,
+    WebSocket,
+    None,
+}
+
+pub struct NymClient<IDPair, Priv, Pub>
+where
+    IDPair: MixnetIdentityKeyPair<Priv, Pub> + Send + Sync,
+    Priv: MixnetIdentityPrivateKey + Send + Sync,
+    Pub: MixnetIdentityPublicKey + Send + Sync,
+{
+    keypair: IDPair,
+
+    // to be used by "send" function or socket, etc
+    pub input_tx: mpsc::UnboundedSender<InputMessage>,
+
+    input_rx: mpsc::UnboundedReceiver<InputMessage>,
+    socket_listening_address: SocketAddr,
+    directory: String,
+    auth_token: Option<AuthToken>,
+    socket_type: SocketType,
+
+    _phantom_private: PhantomData<Priv>,
+    _phantom_public: PhantomData<Pub>,
+}
+
+#[derive(Debug)]
+pub struct InputMessage(pub Destination, pub Vec<u8>);
+
+impl<IDPair: 'static, Priv: 'static, Pub: 'static> NymClient<IDPair, Priv, Pub>
+where
+    IDPair: MixnetIdentityKeyPair<Priv, Pub> + Send + Sync,
+    Priv: MixnetIdentityPrivateKey + Send + Sync,
+    Pub: MixnetIdentityPublicKey + Send + Sync,
+{
+    pub fn new(
+        keypair: IDPair,
+        socket_listening_address: SocketAddr,
+        directory: String,
+        auth_token: Option<AuthToken>,
+        socket_type: SocketType,
+    ) -> Self {
+        let (input_tx, input_rx) = mpsc::unbounded::<InputMessage>();
+
+        NymClient {
+            keypair,
+            input_tx,
+            input_rx,
+            socket_listening_address,
+            directory,
+            auth_token,
+            socket_type,
+            _phantom_private: PhantomData,
+            _phantom_public: PhantomData,
+        }
+    }
+
+    async fn get_provider_socket_address<T: NymTopology>(
+        &self,
+        topology_ctrl_ref: TopologyInnerRef<T>,
+    ) -> SocketAddr {
+        // this is temporary and assumes there exists only a single provider.
+        topology_ctrl_ref.read().await.topology.as_ref().unwrap()
+            .providers()
+            .first()
+            .expect("Could not get a provider from the initial network topology, are you using the right directory server?")
+            .client_listener
+    }
+
+    pub fn start(self) -> Result<(), Box<dyn std::error::Error>> {
+        info!("Starting nym client");
+        let mut rt = Runtime::new()?;
+
+        // channels for inter-component communication
+
+        // mix_tx is the transmitter for any component generating sphinx packets that are to be sent to the mixnet
+        // they are used by cover traffic stream and real traffic stream
+        // mix_rx is the receiver used by MixTrafficController that sends the actual traffic
+        let (mix_tx, mix_rx) = mpsc::unbounded();
+
+        // poller_input_tx is the transmitter of messages fetched from the provider - used by ProviderPoller
+        // poller_input_rx is the receiver for said messages - used by ReceivedMessagesBuffer
+        let (poller_input_tx, poller_input_rx) = mpsc::unbounded();
+
+        // received_messages_buffer_output_tx is the transmitter for *REQUESTS* for messages contained in ReceivedMessagesBuffer - used by sockets
+        // the requests contain a oneshot channel to send a reply on
+        // received_messages_buffer_output_rx is the received for the said requests - used by ReceivedMessagesBuffer
+        let (received_messages_buffer_output_tx, received_messages_buffer_output_rx) =
+            mpsc::unbounded();
+
+        let self_address = self.keypair.public_key().derive_address();
+
+        // generate same type of keys we have as our identity
+        let healthcheck_keys = IDPair::new();
+
+        // TODO: when we switch to our graph topology, we need to remember to change 'Topology' type
+        let topology_controller =
+            rt.block_on(topology_control::TopologyControl::<Topology, _, _, _>::new(
+                self.directory.clone(),
+                TOPOLOGY_REFRESH_RATE,
+                healthcheck_keys,
+            ));
+
+        let provider_client_listener_address =
+            rt.block_on(self.get_provider_socket_address(topology_controller.get_inner_ref()));
+
+        let mut provider_poller = provider_poller::ProviderPoller::new(
+            poller_input_tx,
+            provider_client_listener_address,
+            self_address,
+            self.auth_token,
+        );
+
+        // registration
+        if let Err(err) = rt.block_on(provider_poller.perform_initial_registration()) {
+            panic!("Failed to perform initial registration: {:?}", err);
+        };
+
+        // setup all of futures for the components running on the client
+
+        // buffer controlling all messages fetched from provider
+        // required so that other components would be able to use them (say the websocket)
+        let received_messages_buffer_controllers_future = rt.spawn(
+            ReceivedMessagesBuffer::new()
+                .start_controllers(poller_input_rx, received_messages_buffer_output_rx),
+        );
+
+        // controller for sending sphinx packets to mixnet (either real traffic or cover traffic)
+        let mix_traffic_future = rt.spawn(MixTrafficController::run(mix_rx));
+
+        // future constantly pumping loop cover traffic at some specified average rate
+        // the pumped traffic goes to the MixTrafficController
+        let loop_cover_traffic_future =
+            rt.spawn(cover_traffic_stream::start_loop_cover_traffic_stream(
+                mix_tx.clone(),
+                Destination::new(self_address, Default::default()),
+                topology_controller.get_inner_ref(),
+            ));
+
+        // cloning arguments required by OutQueueControl; required due to move
+        let input_rx = self.input_rx;
+        let topology_ref = topology_controller.get_inner_ref();
+
+        // future constantly pumping traffic at some specified average rate
+        // if a real message is available on 'input_rx' that might have been received from say
+        // the websocket, the real message is used, otherwise a loop cover message is generated
+        // the pumped traffic goes to the MixTrafficController
+        let out_queue_control_future = rt.spawn(async move {
+            real_traffic_stream::OutQueueControl::new(
+                mix_tx,
+                input_rx,
+                Destination::new(self_address, Default::default()),
+                topology_ref,
+            )
+            .run_out_queue_control()
+            .await
+        });
+
+        // future constantly trying to fetch any received messages from the provider
+        // the received messages are sent to ReceivedMessagesBuffer to be available to rest of the system
+        let provider_polling_future = rt.spawn(provider_poller.start_provider_polling());
+
+        // a temporary workaround for starting socket listener of specified type
+        // in the future the actual socket handler should start THIS client instead
+        match self.socket_type {
+            SocketType::WebSocket => {
+                rt.spawn(ws::start_websocket(
+                    self.socket_listening_address,
+                    self.input_tx,
+                    received_messages_buffer_output_tx,
+                    self_address,
+                    topology_controller.get_inner_ref(),
+                ));
+            }
+            SocketType::TCP => {
+                rt.spawn(tcp::start_tcpsocket(
+                    self.socket_listening_address,
+                    self.input_tx,
+                    received_messages_buffer_output_tx,
+                    self_address,
+                    topology_controller.get_inner_ref(),
+                ));
+            }
+            SocketType::None => (),
+        }
+
+        // future responsible for periodically polling directory server and updating
+        // the current global view of topology
+        let topology_refresher_future = rt.spawn(topology_controller.run_refresher());
+
+        rt.block_on(async {
+            let future_results = join!(
+                received_messages_buffer_controllers_future,
+                mix_traffic_future,
+                loop_cover_traffic_future,
+                out_queue_control_future,
+                provider_polling_future,
+                topology_refresher_future,
+            );
+
+            assert!(
+                future_results.0.is_ok()
+                    && future_results.1.is_ok()
+                    && future_results.2.is_ok()
+                    && future_results.3.is_ok()
+                    && future_results.4.is_ok()
+                    && future_results.5.is_ok()
+            );
+        });
+
+        // this line in theory should never be reached as the runtime should be permanently blocked on traffic senders
+        error!("The client went kaput...");
+        Ok(())
+    }
+}
@@ -0,0 +1,88 @@
+use crate::client::FETCH_MESSAGES_DELAY;
+use futures::channel::mpsc;
+use log::{debug, error, info, trace, warn};
+use provider_client::ProviderClientError;
+use sfw_provider_requests::AuthToken;
+use sphinx::route::DestinationAddressBytes;
+use std::net::SocketAddr;
+use std::time::Duration;
+
+pub(crate) struct ProviderPoller {
+    provider_client: provider_client::ProviderClient,
+    poller_tx: mpsc::UnboundedSender<Vec<Vec<u8>>>,
+}
+
+impl ProviderPoller {
+    pub(crate) fn new(
+        poller_tx: mpsc::UnboundedSender<Vec<Vec<u8>>>,
+        provider_client_listener_address: SocketAddr,
+        client_address: DestinationAddressBytes,
+        auth_token: Option<AuthToken>,
+    ) -> Self {
+        ProviderPoller {
+            provider_client: provider_client::ProviderClient::new(
+                provider_client_listener_address,
+                client_address,
+                auth_token,
+            ),
+            poller_tx,
+        }
+    }
+
+    // This method is only temporary until registration is moved to `client init`
+    pub(crate) async fn perform_initial_registration(&mut self) -> Result<(), ProviderClientError> {
+        debug!("performing initial provider registration");
+
+        if !self.provider_client.is_registered() {
+            let auth_token = match self.provider_client.register().await {
+                // in this particular case we can ignore this error
+                Err(ProviderClientError::ClientAlreadyRegisteredError) => return Ok(()),
+                Err(err) => return Err(err),
+                Ok(token) => token,
+            };
+
+            self.provider_client.update_token(auth_token)
+        } else {
+            warn!("did not perform registration - we were already registered")
+        }
+
+        Ok(())
+    }
+
+    pub(crate) async fn start_provider_polling(self) {
+        info!("Starting provider poller");
+
+        let loop_message = &mix_client::packet::LOOP_COVER_MESSAGE_PAYLOAD.to_vec();
+        let dummy_message = &sfw_provider_requests::DUMMY_MESSAGE_CONTENT.to_vec();
+
+        let delay_duration = Duration::from_secs_f64(FETCH_MESSAGES_DELAY);
+        let extended_delay_duration = Duration::from_secs_f64(FETCH_MESSAGES_DELAY * 10.0);
+
+        loop {
+            debug!("Polling provider...");
+
+            let messages = match self.provider_client.retrieve_messages().await {
+                Err(err) => {
+                    error!("Failed to query the provider for messages: {:?}, ... Going to wait {:?} before retrying", err, extended_delay_duration);
+                    tokio::time::delay_for(extended_delay_duration).await;
+                    continue;
+                }
+                Ok(messages) => messages,
+            };
+
+            let good_messages = messages
+                .into_iter()
+                .filter(|message| message != loop_message && message != dummy_message)
+                .collect();
+            trace!("Obtained the following messages: {:?}", good_messages);
+
+            // if this one fails, there's no retrying because it means that either:
+            // - we run out of memory
+            // - the receiver channel is closed
+            // in either case there's no recovery and we can only panic
+            self.poller_tx.unbounded_send(good_messages).unwrap();
+
+            tokio::time::delay_for(delay_duration).await;
+        }
+    }
+}
@@ -0,0 +1,132 @@
+use crate::client::mix_traffic::MixMessage;
+use crate::client::topology_control::TopologyInnerRef;
+use crate::client::{InputMessage, MESSAGE_SENDING_AVERAGE_DELAY};
+use futures::channel::mpsc;
+use futures::task::{Context, Poll};
+use futures::{Future, Stream, StreamExt};
+use log::{error, info, trace, warn};
+use sphinx::route::Destination;
+use std::pin::Pin;
+use std::time::Duration;
+use tokio::time;
+use topology::NymTopology;
+
+// have a rather low value for test sake
+const AVERAGE_PACKET_DELAY: f64 = 0.1;
+
+pub(crate) struct OutQueueControl<T: NymTopology> {
+    delay: time::Delay,
+    mix_tx: mpsc::UnboundedSender<MixMessage>,
+    input_rx: mpsc::UnboundedReceiver<InputMessage>,
+    our_info: Destination,
+    topology_ctrl_ref: TopologyInnerRef<T>,
+}
+
+pub(crate) enum StreamMessage {
+    Cover,
+    Real(InputMessage),
+}
+
+impl<T: NymTopology> Stream for OutQueueControl<T> {
+    type Item = StreamMessage;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        // it is not yet time to return a message
+        if Pin::new(&mut self.delay).poll(cx).is_pending() {
+            return Poll::Pending;
+        };
+
+        // we know it's time to send a message, so let's prepare delay for the next one
+        // Get the `now` by looking at the current `delay` deadline
+        let now = self.delay.deadline();
+
+        let next_poisson_delay =
+            Duration::from_secs_f64(mix_client::poisson::sample(MESSAGE_SENDING_AVERAGE_DELAY));
+
+        // The next interval value is `next_poisson_delay` after the one that just
+        // yielded.
+        let next = now + next_poisson_delay;
+        self.delay.reset(next);
+
+        // decide what kind of message to send
+        match Pin::new(&mut self.input_rx).poll_next(cx) {
+            // in the case our real message channel stream was closed, we should also indicate we are closed
+            // (and whoever is using the stream should panic)
+            Poll::Ready(None) => Poll::Ready(None),
+
+            // if there's an actual message - return it
+            Poll::Ready(Some(real_message)) => Poll::Ready(Some(StreamMessage::Real(real_message))),
+
+            // otherwise construct a dummy one
+            Poll::Pending => Poll::Ready(Some(StreamMessage::Cover)),
+        }
+    }
+}
+
+impl<T: NymTopology> OutQueueControl<T> {
+    pub(crate) fn new(
+        mix_tx: mpsc::UnboundedSender<MixMessage>,
+        input_rx: mpsc::UnboundedReceiver<InputMessage>,
+        our_info: Destination,
+        topology: TopologyInnerRef<T>,
+    ) -> Self {
+        let initial_delay = time::delay_for(Duration::from_secs_f64(MESSAGE_SENDING_AVERAGE_DELAY));
+        OutQueueControl {
+            delay: initial_delay,
+            mix_tx,
+            input_rx,
+            our_info,
+            topology_ctrl_ref: topology,
+        }
+    }
+
+    pub(crate) async fn run_out_queue_control(mut self) {
+        info!("starting out queue controller");
+        while let Some(next_message) = self.next().await {
+            trace!("created new message");
+            let read_lock = self.topology_ctrl_ref.read().await;
+            let topology = match read_lock.topology.as_ref() {
+                None => {
+                    warn!(
+                        "No valid topology detected - won't send any loop cover message this time"
+                    );
+                    continue;
+                }
+                Some(topology) => topology,
+            };
+
+            let next_packet = match next_message {
+                StreamMessage::Cover => mix_client::packet::loop_cover_message(
+                    self.our_info.address,
+                    self.our_info.identifier,
+                    topology,
+                ),
+                StreamMessage::Real(real_message) => mix_client::packet::encapsulate_message(
+                    real_message.0,
+                    real_message.1,
+                    topology,
+                    AVERAGE_PACKET_DELAY,
+                ),
+            };
+
+            let next_packet = match next_packet {
+                Ok(message) => message,
+                Err(err) => {
+                    error!(
+                        "Somehow we managed to create an invalid traffic message - {:?}",
+                        err
+                    );
+                    continue;
+                }
+            };
+
+            // if this one fails, there's no retrying because it means that either:
+            // - we run out of memory
+            // - the receiver channel is closed
+            // in either case there's no recovery and we can only panic
+            self.mix_tx
+                .unbounded_send(MixMessage::new(next_packet.0, next_packet.1))
+                .unwrap();
+        }
+    }
+}
@@ -0,0 +1,89 @@
+use futures::channel::{mpsc, oneshot};
+use futures::lock::Mutex as FMutex;
+use futures::StreamExt;
+use log::{error, info, trace};
+use std::sync::Arc;
+
+pub type BufferResponse = oneshot::Sender<Vec<Vec<u8>>>;
+
+pub(crate) struct ReceivedMessagesBuffer {
+    inner: Arc<FMutex<Inner>>,
+}
+
+impl ReceivedMessagesBuffer {
+    pub(crate) fn new() -> Self {
+        ReceivedMessagesBuffer {
+            inner: Arc::new(FMutex::new(Inner::new())),
+        }
+    }
+
+    pub(crate) async fn start_controllers(
+        self,
+        poller_rx: mpsc::UnboundedReceiver<Vec<Vec<u8>>>, // to receive new messages
+        query_receiver: mpsc::UnboundedReceiver<BufferResponse>, // to receive requests to acquire all stored messages
+    ) {
+        let input_controller_future = tokio::spawn(Self::run_poller_input_controller(
+            self.inner.clone(),
+            poller_rx,
+        ));
+        let output_controller_future = tokio::spawn(Self::run_query_output_controller(
+            self.inner,
+            query_receiver,
+        ));
+
+        futures::future::select(input_controller_future, output_controller_future).await;
+        panic!("One of the received buffer controllers failed!")
+    }
+
+    pub(crate) async fn run_poller_input_controller(
+        buf: Arc<FMutex<Inner>>,
+        mut poller_rx: mpsc::UnboundedReceiver<Vec<Vec<u8>>>,
+    ) {
+        info!("Started Received Messages Buffer Input Controller");
+
+        while let Some(new_messages) = poller_rx.next().await {
+            Inner::add_new_messages(&*buf, new_messages).await;
+        }
+    }
+
+    pub(crate) async fn run_query_output_controller(
+        buf: Arc<FMutex<Inner>>,
+        mut query_receiver: mpsc::UnboundedReceiver<BufferResponse>,
+    ) {
+        info!("Started Received Messages Buffer Output Controller");
+
+        while let Some(request) = query_receiver.next().await {
+            let messages = Inner::acquire_and_empty(&*buf).await;
+            if let Err(failed_messages) = request.send(messages) {
+                error!(
+                    "Failed to send the messages to the requester. Adding them back to the buffer"
+                );
+                Inner::add_new_messages(&*buf, failed_messages).await;
+            }
+        }
+    }
+}
+
+pub(crate) struct Inner {
+    messages: Vec<Vec<u8>>,
+}
+
+impl Inner {
+    fn new() -> Self {
+        Inner {
+            messages: Vec::new(),
+        }
+    }
+
+    async fn add_new_messages(buf: &FMutex<Self>, msgs: Vec<Vec<u8>>) {
+        trace!("Adding new messages to the buffer! {:?}", msgs);
+        let mut unlocked = buf.lock().await;
+        unlocked.messages.extend(msgs);
+    }
+
+    async fn acquire_and_empty(buf: &FMutex<Self>) -> Vec<Vec<u8>> {
+        trace!("Emptying the buffer and returning all messages");
+        let mut unlocked = buf.lock().await;
+        std::mem::replace(&mut unlocked.messages, Vec::new())
+    }
+}
@@ -0,0 +1,148 @@
+use crate::built_info;
+use crypto::identity::{MixnetIdentityKeyPair, MixnetIdentityPrivateKey, MixnetIdentityPublicKey};
+use healthcheck::HealthChecker;
+use log::{error, info, trace, warn};
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::sync::RwLock as FRwLock;
+use topology::NymTopology;
+
+const NODE_HEALTH_THRESHOLD: f64 = 0.0;
+
+// auxiliary type for ease of use
+pub type TopologyInnerRef<T> = Arc<FRwLock<Inner<T>>>;
+
+pub(crate) struct TopologyControl<T, IDPair, Priv, Pub>
+where
+    T: NymTopology,
+    IDPair: MixnetIdentityKeyPair<Priv, Pub>,
+    Priv: MixnetIdentityPrivateKey,
+    Pub: MixnetIdentityPublicKey,
+{
+    directory_server: String,
+    inner: Arc<FRwLock<Inner<T>>>,
+    health_checker: HealthChecker<IDPair, Priv, Pub>,
+    refresh_rate: f64,
+}
+
+#[derive(Debug)]
+enum TopologyError {
+    HealthCheckError,
+    NoValidPathsError,
+}
+
+impl<T, IDPair, Priv, Pub> TopologyControl<T, IDPair, Priv, Pub>
+where
+    T: NymTopology,
+    IDPair: MixnetIdentityKeyPair<Priv, Pub>,
+    Priv: MixnetIdentityPrivateKey,
+    Pub: MixnetIdentityPublicKey,
+{
+    pub(crate) async fn new(
+        directory_server: String,
+        refresh_rate: f64,
+        identity_keypair: IDPair,
+    ) -> Self {
+        // topology control run a healthcheck to determine healthy-ish nodes:
+        // this is a temporary solution as the healthcheck will eventually be moved to validators
+
+        let healthcheck_config = healthcheck::config::HealthCheck {
+            directory_server: directory_server.clone(),
+            // those are literally irrelevant when running single check
+            interval: 100000.0,
+            resolution_timeout: 5.0,
+            num_test_packets: 2,
+        };
+        let health_checker = healthcheck::HealthChecker::new(healthcheck_config, identity_keypair);
+
+        let mut topology_control = TopologyControl {
+            directory_server,
+            refresh_rate,
+            inner: Arc::new(FRwLock::new(Inner::new(None))),
+            health_checker,
+        };
+
+        // best effort approach to try to get a valid topology after call to 'new'
+        let initial_topology = match topology_control.get_current_compatible_topology().await {
+            Ok(topology) => Some(topology),
+            Err(err) => {
+                error!("Initial topology is invalid - {:?}. Right now it will be impossible to send any packets through the mixnet!", err);
+                None
+            }
+        };
+        topology_control
+            .update_global_topology(initial_topology)
+            .await;
+
+        topology_control
+    }
+
+    async fn get_current_compatible_topology(&self) -> Result<T, TopologyError> {
+        let full_topology = T::new(self.directory_server.clone());
+
+        let healthcheck_result = self.health_checker.do_check().await;
+        let healthcheck_scores = match healthcheck_result {
+            Err(err) => {
+                error!("Error while performing the healthcheck: {:?}", err);
+                return Err(TopologyError::HealthCheckError);
+            }
+            Ok(scores) => scores,
+        };
+
+        let healthy_topology =
+            healthcheck_scores.filter_topology_by_score(&full_topology, NODE_HEALTH_THRESHOLD);
+
+        let versioned_healthy_topology = healthy_topology.filter_node_versions(
+            built_info::PKG_VERSION,
+            built_info::PKG_VERSION,
+            built_info::PKG_VERSION,
+        );
+
+        // make sure you can still send a packet through the network:
+        if !versioned_healthy_topology.can_construct_path_through() {
+            return Err(TopologyError::NoValidPathsError);
+        }
+
+        Ok(versioned_healthy_topology)
+    }
+
+    pub(crate) fn get_inner_ref(&self) -> Arc<FRwLock<Inner<T>>> {
+        self.inner.clone()
+    }
+
+    async fn update_global_topology(&mut self, new_topology: Option<T>) {
+        // acquire write lock
+        let mut write_lock = self.inner.write().await;
+        write_lock.topology = new_topology;
+    }
+
+    pub(crate) async fn run_refresher(mut self) {
+        info!("Starting topology refresher");
+        let delay_duration = Duration::from_secs_f64(self.refresh_rate);
+        loop {
+            trace!("Refreshing the topology");
+            let new_topology_res = self.get_current_compatible_topology().await;
+
+            let new_topology = match new_topology_res {
+                Ok(topology) => Some(topology),
+                Err(err) => {
+                    warn!("the obtained topology seems to be invalid - {:?}, it will be impossible to send packets through", err);
+                    None
+                }
+            };
+
+            self.update_global_topology(new_topology).await;
+            tokio::time::delay_for(delay_duration).await;
+        }
+    }
+}
+
+pub struct Inner<T: NymTopology> {
+    pub topology: Option<T>,
+}
+
+impl<T: NymTopology> Inner<T> {
+    fn new(topology: Option<T>) -> Self {
+        Inner { topology }
+    }
+}
@@ -1,20 +1,18 @@
-use crate::banner;
-use crate::identity::mixnet;
-use crate::persistence::pathfinder::Pathfinder;
-use crate::persistence::pemstore::PemStore;
+use crate::config::persistance::pathfinder::ClientPathfinder;
 use clap::ArgMatches;
+use crypto::identity::MixnetIdentityKeyPair;
+use pemstore::pemstore::PemStore;

 pub fn execute(matches: &ArgMatches) {
-    println!("{}", banner());
    println!("Initialising client...");

    let id = matches.value_of("id").unwrap().to_string(); // required for now
-    let pathfinder = Pathfinder::new(id);
+    let pathfinder = ClientPathfinder::new(id);

    println!("Writing keypairs to {:?}...", pathfinder.config_dir);
-    let mix_keys = mixnet::KeyPair::new();
+    let mix_keys = crypto::identity::DummyMixIdentityKeyPair::new();
    let pem_store = PemStore::new(pathfinder);
-    pem_store.write(mix_keys);
+    pem_store.write_identity(mix_keys).unwrap();

    println!("Client configuration completed.\n\n\n")
 }
@@ -1,4 +1,3 @@
 pub mod init;
-pub mod run;
 pub mod tcpsocket;
 pub mod websocket;
@@ -1,14 +1,11 @@
-use crate::banner;
-use crate::clients::{NymClient, SocketType};
-use crate::persistence::pemstore;
-use crate::sockets::tcp;
-
+use crate::client::{NymClient, SocketType};
+use crate::config::persistance::pathfinder::ClientPathfinder;
 use clap::ArgMatches;
+use crypto::identity::DummyMixIdentityKeyPair;
+use pemstore::pemstore::PemStore;
 use std::net::ToSocketAddrs;

 pub fn execute(matches: &ArgMatches) {
-    println!("{}", banner());
-
    let id = matches.value_of("id").unwrap().to_string();
    let port = match matches.value_of("port").unwrap_or("9001").parse::<u16>() {
        Ok(n) => n,
@@ -29,11 +26,17 @@ pub fn execute(matches: &ArgMatches) {
        .next()
        .expect("Failed to extract the socket address from the iterator");

-    let keypair = pemstore::read_keypair_from_disk(id);
-    let auth_token = None;
+    // TODO: currently we know we are reading the 'DummyMixIdentityKeyPair', but how to properly assert the type?
+    let keypair: DummyMixIdentityKeyPair = PemStore::new(ClientPathfinder::new(id))
+        .read_identity()
+        .unwrap();
+    // TODO: reading auth_token from disk (if exists);

+    println!("Public key: {}", keypair.public_key.to_base58_string());
+
+    let auth_token = None;
    let client = NymClient::new(
-        keypair.public_bytes(),
+        keypair,
        socket_address.clone(),
        directory_server,
        auth_token,
@@ -1,13 +1,11 @@
-use crate::banner;
-use crate::clients::{NymClient, SocketType};
-use crate::persistence::pemstore;
-
+use crate::client::{NymClient, SocketType};
+use crate::config::persistance::pathfinder::ClientPathfinder;
 use clap::ArgMatches;
+use crypto::identity::DummyMixIdentityKeyPair;
+use pemstore::pemstore::PemStore;
 use std::net::ToSocketAddrs;

 pub fn execute(matches: &ArgMatches) {
-    println!("{}", banner());
-
    let id = matches.value_of("id").unwrap().to_string();
    let port = match matches.value_of("port").unwrap_or("9001").parse::<u16>() {
        Ok(n) => n,
@@ -28,11 +26,18 @@ pub fn execute(matches: &ArgMatches) {
        .next()
        .expect("Failed to extract the socket address from the iterator");

-    let keypair = pemstore::read_keypair_from_disk(id);
+    // TODO: currently we know we are reading the 'DummyMixIdentityKeyPair', but how to properly assert the type?
+    let keypair: DummyMixIdentityKeyPair = PemStore::new(ClientPathfinder::new(id))
+        .read_identity()
+        .unwrap();
+
    // TODO: reading auth_token from disk (if exists);
+
+    println!("Public key: {}", keypair.public_key.to_base58_string());
+
    let auth_token = None;
    let client = NymClient::new(
-        keypair.public_bytes(),
+        keypair,
        socket_address,
        directory_server,
        auth_token,
@@ -0,0 +1 @@
+pub mod persistance;
@@ -0,0 +1 @@
+pub mod pathfinder;
@@ -1,21 +1,36 @@
+use pemstore::pathfinder::PathFinder;
 use std::path::PathBuf;

-pub struct Pathfinder {
+pub struct ClientPathfinder {
    pub config_dir: PathBuf,
    pub private_mix_key: PathBuf,
    pub public_mix_key: PathBuf,
 }

-impl Pathfinder {
-    pub fn new(id: String) -> Pathfinder {
+impl ClientPathfinder {
+    pub fn new(id: String) -> Self {
        let os_config_dir = dirs::config_dir().unwrap(); // grabs the OS default config dir
        let config_dir = os_config_dir.join("nym").join("clients").join(id);
        let private_mix_key = config_dir.join("private.pem");
        let public_mix_key = config_dir.join("public.pem");
-        Pathfinder {
+        ClientPathfinder {
            config_dir,
            private_mix_key,
            public_mix_key,
        }
    }
 }
+
+impl PathFinder for ClientPathfinder {
+    fn config_dir(&self) -> PathBuf {
+        self.config_dir.clone()
+    }
+
+    fn private_identity_key(&self) -> PathBuf {
+        self.private_mix_key.clone()
+    }
+
+    fn public_identity_key(&self) -> PathBuf {
+        self.public_mix_key.clone()
+    }
+}
@@ -0,0 +1,4 @@
+pub mod built_info;
+pub mod client;
+pub mod config;
+mod sockets;
@@ -1,16 +1,17 @@
 use clap::{App, Arg, ArgMatches, SubCommand};
-use std::process;

-pub mod clients;
+pub mod built_info;
+pub mod client;
 mod commands;
-mod identity;
-mod persistence;
+pub mod config;
 mod sockets;
-mod utils;

 fn main() {
+    dotenv::dotenv().ok();
+    pretty_env_logger::init();
+
    let arg_matches = App::new("Nym Client")
-        .version("0.1.0")
+        .version(built_info::PKG_VERSION)
        .author("Nymtech")
        .about("Implementation of the Nym Client")
        .subcommand(
@@ -28,22 +29,6 @@ fn main() {
                    .takes_value(true)
                )
        )
-        .subcommand(
-            SubCommand::with_name("run")
-                .about("Run a persistent Nym client process")
-                .arg(Arg::with_name("id")
-                    .long("id")
-                    .help("Id of the nym-mixnet-client we want to run.")
-                    .takes_value(true)
-                    .required(true)
-                )
-                .arg(
-                    Arg::with_name("directory")
-                        .long("directory")
-                        .help("Address of the directory server the client is getting topology from")
-                        .takes_value(true),
-                )
-        )
        .subcommand(
            SubCommand::with_name("tcpsocket")
                .about("Run Nym client that listens for bytes on a TCP socket")
@@ -93,24 +78,26 @@ fn main() {
        )
        .get_matches();

-    if let Err(e) = execute(arg_matches) {
-        println!("{}", e);
-        process::exit(1);
-    }
+    execute(arg_matches);
 }

-pub mod built_info {
-    // The file has been placed there by the build script.
-    include!(concat!(env!("OUT_DIR"), "/built.rs"));
-}
-
-fn execute(matches: ArgMatches) -> Result<(), String> {
+fn execute(matches: ArgMatches) {
    match matches.subcommand() {
-        ("init", Some(m)) => Ok(commands::init::execute(m)),
-        ("run", Some(m)) => Ok(commands::run::execute(m)),
-        ("tcpsocket", Some(m)) => Ok(commands::tcpsocket::execute(m)),
-        ("websocket", Some(m)) => Ok(commands::websocket::execute(m)),
-        _ => Err(usage()),
+        ("init", Some(m)) => {
+            println!("{}", banner());
+            commands::init::execute(m);
+        }
+        ("tcpsocket", Some(m)) => {
+            println!("{}", banner());
+            commands::tcpsocket::execute(m);
+        }
+        ("websocket", Some(m)) => {
+            println!("{}", banner());
+            commands::websocket::execute(m);
+        }
+        _ => {
+            println!("{}", usage());
+        }
    }
 }

@@ -1,17 +1,17 @@
-use crate::clients::directory::presence::Topology;
-use crate::clients::BufferResponse;
-use crate::clients::InputMessage;
+use crate::client::received_buffer::BufferResponse;
+use crate::client::topology_control::TopologyInnerRef;
+use crate::client::InputMessage;
 use futures::channel::{mpsc, oneshot};
 use futures::future::FutureExt;
 use futures::io::Error;
 use futures::SinkExt;
+use log::*;
 use sphinx::route::{Destination, DestinationAddressBytes};
+use std::convert::TryFrom;
 use std::io;
 use std::net::SocketAddr;
 use tokio::prelude::*;
-use std::convert::TryFrom;
-use std::sync::Arc;
-use std::borrow::Borrow;
+use topology::NymTopology;

 const SEND_REQUEST_PREFIX: u8 = 1;
 const FETCH_REQUEST_PREFIX: u8 = 2;
@@ -42,7 +42,6 @@ impl From<io::Error> for TCPSocketError {
    }
 }

-
 enum ClientRequest {
    Send {
        message: Vec<u8>,
@@ -67,7 +66,7 @@ impl TryFrom<&[u8]> for ClientRequest {
            FETCH_REQUEST_PREFIX => Ok(ClientRequest::Fetch),
            GET_CLIENTS_REQUEST_PREFIX => Ok(ClientRequest::GetClients),
            OWN_DETAILS_REQUEST_PREFIX => Ok(ClientRequest::OwnDetails),
-            _ => Err(UnknownRequestError)
+            _ => Err(UnknownRequestError),
        }
    }
 }
@@ -95,60 +94,71 @@ impl ClientRequest {
        recipient_address: DestinationAddressBytes,
        mut input_tx: mpsc::UnboundedSender<InputMessage>,
    ) -> ServerResponse {
-        println!("send handle. sending to: {:?}, msg: {:?}", recipient_address, msg);
+        trace!("sending to: {:?}, msg: {:?}", recipient_address, msg);
+        if msg.len() > sphinx::constants::MAXIMUM_PLAINTEXT_LENGTH {
+            return ServerResponse::Error {
+                message: format!(
+                    "too long message. Sent {} bytes while the maximum is {}",
+                    msg.len(),
+                    sphinx::constants::MAXIMUM_PLAINTEXT_LENGTH
+                )
+                .to_string(),
+            };
+        }
        let dummy_surb = [0; 16];
        let input_msg = InputMessage(Destination::new(recipient_address, dummy_surb), msg);
-
-        println!("ALMOST ABOUT TO SOMEDAY SEND {:?}", input_msg);
        input_tx.send(input_msg).await.unwrap();
-
        ServerResponse::Send
    }

    async fn handle_fetch(mut msg_query: mpsc::UnboundedSender<BufferResponse>) -> ServerResponse {
-        println!("fetch handle");
+        trace!("handle_fetch called");
        let (res_tx, res_rx) = oneshot::channel();
        if msg_query.send(res_tx).await.is_err() {
-            return ServerResponse::Error {
-                message: "Server failed to receive messages".to_string(),
-            };
+            let e = "Nym-client TCP socket failed to receive messages".to_string();
+            error!("{}", e);
+            return ServerResponse::Error { message: e };
        }

-        let messages = res_rx.map(|msg| msg).await;
+        let messages = match res_rx.map(|msg| msg).await {
+            Ok(messages) => messages,
+            Err(e) => {
+                warn!("Failed to fetch client messages - {:?}", e);
+                return ServerResponse::Error {
+                    message: format!("Server failed to receive messages").to_string(),
+                };
+            }
+        };

-        if messages.is_err() {
-            return ServerResponse::Error {
-                message: "Server failed to receive messages".to_string(),
-            };
-        }
-
-        let messages = messages.unwrap();
-        println!("fetched {} messages", messages.len());
-        ServerResponse::Fetch {
-            messages,
-        }
+        trace!("fetched {} messages", messages.len());
+        ServerResponse::Fetch { messages }
    }

-    async fn handle_get_clients(topology: &Topology) -> ServerResponse {
-        println!("get clients handle");
-        let clients = topology
-            .mix_provider_nodes
-            .iter()
-            .flat_map(|provider| provider.registered_clients.iter())
-            .map(|client| base64::decode_config(&client.pub_key, base64::URL_SAFE).unwrap()) // TODO: this can potentially throw an error
-            .collect();
-        ServerResponse::GetClients { clients }
+    async fn handle_get_clients<T: NymTopology>(topology: &TopologyInnerRef<T>) -> ServerResponse {
+        let topology_data = &topology.read().await.topology;
+        match topology_data {
+            Some(topology) => {
+                let clients = topology
+                    .providers()
+                    .iter()
+                    .flat_map(|provider| provider.registered_clients.iter())
+                    .filter_map(|client| bs58::decode(&client.pub_key).into_vec().ok())
+                    .collect();
+                ServerResponse::GetClients { clients }
+            }
+            None => ServerResponse::Error {
+                message: "Invalid network topology".to_string(),
+            },
+        }
    }

    async fn handle_own_details(self_address_bytes: DestinationAddressBytes) -> ServerResponse {
-        println!("own details handle");
        ServerResponse::OwnDetails {
            address: self_address_bytes.to_vec(),
        }
    }
 }

-
 enum ServerResponse {
    Send,
    Fetch { messages: Vec<Vec<u8>> },
@@ -161,10 +171,10 @@ impl Into<Vec<u8>> for ServerResponse {
    fn into(self) -> Vec<u8> {
        match self {
            ServerResponse::Send => b"ok".to_vec(),
-            ServerResponse::Fetch {messages} =>encode_fetched_messages(messages),
-            ServerResponse::GetClients {clients} => encode_list_of_clients(clients),
-            ServerResponse::OwnDetails {address} => address,
-            ServerResponse::Error { message } => message.as_bytes().to_vec()
+            ServerResponse::Fetch { messages } => encode_fetched_messages(messages),
+            ServerResponse::GetClients { clients } => encode_list_of_clients(clients),
+            ServerResponse::OwnDetails { address } => address,
+            ServerResponse::Error { message } => message.as_bytes().to_vec(),
        }
    }
 }
@@ -190,8 +200,8 @@ fn encode_fetched_messages(messages: Vec<Vec<u8>>) -> Vec<u8> {
 }

 fn encode_list_of_clients(clients: Vec<Vec<u8>>) -> Vec<u8> {
-    println!("clients: {:?}", clients);
-    // we can just concat all clients since all of them got to be 32 bytes long
+    debug!("client: {:?}", clients);
+    // we can just concat all client since all of them got to be 32 bytes long
    // (if not, then we have bigger problem somewhere up the line)

    // converts [[1,2,3],[4,5,6],...] into [1,2,3,4,5,6,...]
@@ -204,42 +214,49 @@ impl ServerResponse {
    }
 }

-
-async fn handle_connection(data: &[u8], request_handling_data: RequestHandlingData) -> Result<ServerResponse, TCPSocketError> {
+async fn handle_connection<T: NymTopology>(
+    data: &[u8],
+    request_handling_data: RequestHandlingData<T>,
+) -> Result<ServerResponse, TCPSocketError> {
    let request = ClientRequest::try_from(data)?;
    let response = match request {
        ClientRequest::Send {
            message,
-            recipient_address
-        } => ClientRequest::handle_send(message, recipient_address, request_handling_data.msg_input).await,
+            recipient_address,
+        } => {
+            ClientRequest::handle_send(message, recipient_address, request_handling_data.msg_input)
+                .await
+        }
        ClientRequest::Fetch => ClientRequest::handle_fetch(request_handling_data.msg_query).await,
-        ClientRequest::GetClients => ClientRequest::handle_get_clients(request_handling_data.topology.borrow()).await,
-        ClientRequest::OwnDetails => ClientRequest::handle_own_details(request_handling_data.self_address).await,
+        ClientRequest::GetClients => {
+            ClientRequest::handle_get_clients(&request_handling_data.topology).await
+        }
+        ClientRequest::OwnDetails => {
+            ClientRequest::handle_own_details(request_handling_data.self_address).await
+        }
    };

    Ok(response)
 }

-struct RequestHandlingData {
+struct RequestHandlingData<T: NymTopology> {
    msg_input: mpsc::UnboundedSender<InputMessage>,
    msg_query: mpsc::UnboundedSender<BufferResponse>,
    self_address: DestinationAddressBytes,
-    topology: Arc<Topology>,
+    topology: TopologyInnerRef<T>,
 }

-async fn accept_connection(
+async fn accept_connection<T: 'static + NymTopology>(
    mut socket: tokio::net::TcpStream,
    msg_input: mpsc::UnboundedSender<InputMessage>,
    msg_query: mpsc::UnboundedSender<BufferResponse>,
    self_address: DestinationAddressBytes,
-    topology: Topology,
+    topology: TopologyInnerRef<T>,
 ) {
    let address = socket
        .peer_addr()
        .expect("connected streams should have a peer address");
-    println!("Peer address: {}", address);
-
-    let topology = Arc::new(topology);
+    debug!("Peer address: {}", address);

    let mut buf = [0u8; 2048];

@@ -250,7 +267,7 @@ async fn accept_connection(
        let response = match socket.read(&mut buf).await {
            // socket closed
            Ok(n) if n == 0 => {
-                println!("Remote connection closed.");
+                trace!("Remote connection closed.");
                return;
            }
            Ok(n) => {
@@ -262,29 +279,29 @@ async fn accept_connection(
                };
                match handle_connection(&buf[..n], request_handling_data).await {
                    Ok(res) => res,
-                    Err(e) => ServerResponse::new_error(format!("{:?}", e))
+                    Err(e) => ServerResponse::new_error(format!("{:?}", e)),
                }
            }
            Err(e) => {
-                eprintln!("failed to read from socket; err = {:?}", e);
+                warn!("failed to read from socket; err = {:?}", e);
                return;
            }
        };

        let response_vec: Vec<u8> = response.into();
        if let Err(e) = socket.write_all(&response_vec).await {
-            eprintln!("failed to write reply to socket; err = {:?}", e);
+            warn!("failed to write reply to socket; err = {:?}", e);
            return;
        }
    }
 }

-pub async fn start_tcpsocket(
+pub async fn start_tcpsocket<T: 'static + NymTopology>(
    address: SocketAddr,
    message_tx: mpsc::UnboundedSender<InputMessage>,
    received_messages_query_tx: mpsc::UnboundedSender<BufferResponse>,
    self_address: DestinationAddressBytes,
-    topology: Topology,
+    topology: TopologyInnerRef<T>,
 ) -> Result<(), TCPSocketError> {
    let mut listener = tokio::net::TcpListener::bind(address).await?;

@@ -300,6 +317,6 @@ pub async fn start_tcpsocket(
        ));
    }

-    eprintln!("The tcpsocket went kaput...");
+    error!("The tcpsocket went kaput...");
    Ok(())
-}
+}
@@ -0,0 +1,412 @@
+use crate::client::received_buffer::BufferResponse;
+use crate::client::topology_control::TopologyInnerRef;
+use crate::client::InputMessage;
+use futures::channel::mpsc::{UnboundedReceiver, UnboundedSender};
+use futures::channel::{mpsc, oneshot};
+use futures::future::FutureExt;
+use futures::io::Error;
+use futures::{SinkExt, StreamExt};
+use log::{debug, error, info, trace, warn};
+use serde::{Deserialize, Serialize};
+use sphinx::route::{Destination, DestinationAddressBytes};
+use std::convert::TryFrom;
+use std::io;
+use std::net::SocketAddr;
+use topology::NymTopology;
+use tungstenite::protocol::frame::coding::CloseCode;
+use tungstenite::protocol::{CloseFrame, Message};
+
+struct Connection<T: NymTopology> {
+    address: SocketAddr,
+    msg_input: mpsc::UnboundedSender<InputMessage>,
+    msg_query: mpsc::UnboundedSender<BufferResponse>,
+    rx: UnboundedReceiver<Message>,
+    self_address: DestinationAddressBytes,
+    topology: TopologyInnerRef<T>,
+    tx: UnboundedSender<Message>,
+}
+
+impl<T: NymTopology> Connection<T> {
+    async fn handle_text_message(&self, msg: String) -> ServerResponse {
+        debug!("Handling text message request");
+        trace!("Content: {:?}", msg.clone());
+
+        let request = match ClientRequest::try_from(msg) {
+            Ok(req) => req,
+            Err(err) => {
+                return ServerResponse::Error {
+                    // we failed to parse the request
+                    message: format!("received invalid request. err: {:?}", err),
+                };
+            }
+        };
+
+        match request {
+            ClientRequest::Send {
+                message,
+                recipient_address,
+            } => {
+                ClientRequest::handle_send(message, recipient_address, self.msg_input.clone()).await
+            }
+            ClientRequest::Fetch => ClientRequest::handle_fetch(self.msg_query.clone()).await,
+            ClientRequest::GetClients => ClientRequest::handle_get_clients(&self.topology).await,
+            ClientRequest::OwnDetails => ClientRequest::handle_own_details(self.self_address).await,
+        }
+    }
+
+    // Currently our websocket cannot handle binary data, so just close the connection
+    // with unsupported close code.
+    async fn handle_binary_message(&self, _msg: Vec<u8>) -> Message {
+        debug!("Handling binary message request");
+
+        Message::Close(Some(CloseFrame {
+            code: CloseCode::Unsupported,
+            reason: "binary messages aren't yet supported".into(),
+        }))
+    }
+
+    // As per RFC6455 5.5.2. and 5.5.3.:
+    // Upon receipt of a Ping frame, an endpoint MUST send a Pong frame in response.
+    // A Pong frame sent in response to a Ping frame must have identical
+    // "Application data" as found in the message body of the Ping frame
+    // being replied to.
+    async fn handle_ping_message(&self, msg: Vec<u8>) -> Message {
+        debug!("Handling binary ping request");
+
+        // As per RFC6455 5.5:
+        // All control frames MUST have a payload length of 125 bytes or less
+        if msg.len() > 125 {
+            return Message::Close(Some(CloseFrame {
+                code: CloseCode::Protocol,
+                reason: format!("ping message of length {} sent", msg.len()).into(),
+            }));
+        }
+
+        Message::Pong(msg)
+    }
+
+    // As per RFC6455 5.5.3.:
+    // A Pong frame MAY be sent unsolicited.  This serves as a
+    // unidirectional heartbeat.  A response to an unsolicited Pong frame is
+    // not expected.
+    // Realistically this handler should never be used,
+    // but since we're nice we will reply with a Pong containing original content
+    async fn handle_pong_message(&self, msg: Vec<u8>) -> Message {
+        debug!("Handling pong message request");
+
+        // As per RFC6455 5.5:
+        // All control frames MUST have a payload length of 125 bytes or less
+        if msg.len() > 125 {
+            return Message::Close(Some(CloseFrame {
+                code: CloseCode::Protocol,
+                reason: format!("ping message of length {} sent", msg.len()).into(),
+            }));
+        }
+
+        Message::Pong(msg)
+    }
+
+    // As per RFC6455 5.5.1.:
+    // If an endpoint receives a Close frame and did not previously send a
+    // Close frame, the endpoint MUST send a Close frame in response. (When
+    // sending a Close frame in response, the endpoint typically echos the
+    // status code it received.)
+    async fn handle_close_message(&self, close_frame: Option<CloseFrame<'static>>) -> Message {
+        debug!("Handling close message request");
+
+        Message::Close(close_frame)
+    }
+
+    async fn handle(mut self) {
+        while let Some(msg) = self.rx.next().await {
+            trace!("Received a message from {}: {}", self.address, msg);
+            let response_message = match msg {
+                Message::Text(text_message) => self.handle_text_message(text_message).await.into(),
+                Message::Binary(binary_message) => self.handle_binary_message(binary_message).await,
+                Message::Ping(ping_message) => self.handle_ping_message(ping_message).await,
+                Message::Pong(pong_message) => self.handle_pong_message(pong_message).await,
+                Message::Close(close_frame) => self.handle_close_message(close_frame).await,
+            };
+
+            if let Err(err) = self.tx.unbounded_send(response_message) {
+                error!(
+                    "Failed to send response message to accepted connections handler: {}.\n\
+                     Shutting off the connection handler",
+                    err
+                );
+                return;
+            }
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum WebSocketError {
+    FailedToStartSocketError,
+    UnknownSocketError,
+}
+
+impl From<io::Error> for WebSocketError {
+    fn from(err: Error) -> Self {
+        use WebSocketError::*;
+        match err.kind() {
+            io::ErrorKind::ConnectionRefused => FailedToStartSocketError,
+            io::ErrorKind::ConnectionReset => FailedToStartSocketError,
+            io::ErrorKind::ConnectionAborted => FailedToStartSocketError,
+            io::ErrorKind::NotConnected => FailedToStartSocketError,
+            io::ErrorKind::AddrInUse => FailedToStartSocketError,
+            io::ErrorKind::AddrNotAvailable => FailedToStartSocketError,
+            _ => UnknownSocketError,
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+enum ClientRequest {
+    Send {
+        message: String,
+        recipient_address: String,
+    },
+    Fetch,
+    GetClients,
+    OwnDetails,
+}
+
+impl TryFrom<String> for ClientRequest {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, Self::Error> {
+        serde_json::from_str(&msg)
+    }
+}
+
+impl ClientRequest {
+    async fn handle_send(
+        msg: String,
+        recipient_address: String,
+        mut input_tx: mpsc::UnboundedSender<InputMessage>,
+    ) -> ServerResponse {
+        let message_bytes = msg.into_bytes();
+        if message_bytes.len() > sphinx::constants::MAXIMUM_PLAINTEXT_LENGTH {
+            return ServerResponse::Error {
+                message: format!(
+                    "message too long. Sent {} bytes, but the maximum is {}",
+                    message_bytes.len(),
+                    sphinx::constants::MAXIMUM_PLAINTEXT_LENGTH
+                )
+                .to_string(),
+            };
+        }
+
+        let address_vec = match bs58::decode(&recipient_address).into_vec() {
+            Err(e) => {
+                return ServerResponse::Error {
+                    message: e.to_string(),
+                };
+            }
+            Ok(bytes) => bytes,
+        };
+
+        if address_vec.len() != 32 {
+            return ServerResponse::Error {
+                message: "InvalidDestinationLength".to_string(),
+            };
+        }
+
+        let mut address = [0; 32];
+        address.copy_from_slice(&address_vec);
+
+        let dummy_surb = [0; 16];
+
+        let input_msg = InputMessage(Destination::new(address, dummy_surb), message_bytes);
+        input_tx.send(input_msg).await.unwrap();
+
+        ServerResponse::Send
+    }
+
+    async fn handle_fetch(mut msg_query: mpsc::UnboundedSender<BufferResponse>) -> ServerResponse {
+        let (res_tx, res_rx) = oneshot::channel();
+        if msg_query.send(res_tx).await.is_err() {
+            warn!("Failed to handle_fetch. msg_query.send() is an error.");
+            return ServerResponse::Error {
+                message: "Server failed to receive messages".to_string(),
+            };
+        }
+
+        let messages = match res_rx.map(|msg| msg).await {
+            Ok(messages) => messages,
+            Err(e) => {
+                warn!("Failed to fetch client messages - {:?}", e);
+                return ServerResponse::Error {
+                    message: format!("Server failed to receive messages").to_string(),
+                };
+            }
+        };
+
+        let messages = messages
+            .into_iter()
+            .map(|message| {
+                match std::str::from_utf8(&message) {
+                    Ok(v) => v,
+                    Err(e) => {
+                        error!("Invalid UTF-8 sequence in response message: {}", e);
+                        ""
+                    }
+                }
+                .to_owned()
+            })
+            .collect();
+
+        ServerResponse::Fetch { messages }
+    }
+
+    async fn handle_get_clients<T: NymTopology>(topology: &TopologyInnerRef<T>) -> ServerResponse {
+        let topology_data = &topology.read().await.topology;
+        match topology_data {
+            Some(topology) => {
+                let clients = topology
+                    .providers()
+                    .iter()
+                    .flat_map(|provider| provider.registered_clients.iter())
+                    .map(|client| client.pub_key.clone())
+                    .collect();
+                ServerResponse::GetClients { clients }
+            }
+            None => ServerResponse::Error {
+                message: "Invalid network topology".to_string(),
+            },
+        }
+    }
+
+    async fn handle_own_details(self_address_bytes: DestinationAddressBytes) -> ServerResponse {
+        let self_address = bs58::encode(&self_address_bytes).into_string();
+        ServerResponse::OwnDetails {
+            address: self_address,
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+enum ServerResponse {
+    Send,
+    Fetch { messages: Vec<String> },
+    GetClients { clients: Vec<String> },
+    OwnDetails { address: String },
+    Error { message: String },
+}
+
+impl Into<Message> for ServerResponse {
+    fn into(self) -> Message {
+        // it should be safe to call `unwrap` here as the message is generated by the server
+        // so if it fails (and consequently panics) it's a bug that should be resolved
+        let str_res = serde_json::to_string(&self).unwrap();
+        Message::Text(str_res)
+    }
+}
+
+async fn accept_connection<T: 'static + NymTopology>(
+    stream: tokio::net::TcpStream,
+    msg_input: mpsc::UnboundedSender<InputMessage>,
+    msg_query: mpsc::UnboundedSender<BufferResponse>,
+    self_address: DestinationAddressBytes,
+    topology: TopologyInnerRef<T>,
+) {
+    let address = stream
+        .peer_addr()
+        .expect("connected streams should have a peer address");
+    debug!("Peer address: {}", address);
+
+    let mut ws_stream = tokio_tungstenite::accept_async(stream)
+        .await
+        .expect("Error during the websocket handshake occurred");
+
+    // Create a channel for our stream, which other sockets will use to
+    // send us messages. Then register our address with the stream to send
+    // data to us.
+    let (msg_tx, msg_rx) = futures::channel::mpsc::unbounded();
+    let (response_tx, mut response_rx) = futures::channel::mpsc::unbounded();
+    let conn = Connection {
+        address,
+        rx: msg_rx,
+        tx: response_tx,
+        topology,
+        msg_input,
+        msg_query,
+        self_address,
+    };
+
+    // TODO: make sure this actually doesn't leak memory...
+    tokio::spawn(conn.handle());
+
+    while let Some(message) = ws_stream.next().await {
+        let message = match message {
+            Ok(msg) => msg,
+            Err(err) => {
+                error!("failed to obtain message from websocket stream! stopping connection handler: {}", err);
+                return;
+            }
+        };
+
+        let mut should_close = false;
+        if message.is_close() {
+            should_close = true;
+        }
+
+        if let Err(err) = msg_tx.unbounded_send(message) {
+            error!(
+                "Failed to forward request. Closing the socket connection: {}",
+                err
+            );
+            return;
+        }
+        // if the received message is a close message it means we will reply with a close
+        // or it is a reply to our close, either way as per RFC6455 5.5.1 we should close the
+        // underlying TCP connection:
+        // After both sending and receiving a Close message, an endpoint
+        // considers the WebSocket connection closed and MUST close the
+        // underlying TCP connection. The server MUST close the underlying TCP
+        // connection immediately;
+
+        if let Some(resp) = response_rx.next().await {
+            if let Err(err) = ws_stream.send(resp).await {
+                warn!(
+                    "Failed to send message over websocket: {}. Assuming the connection is dead.",
+                    err
+                );
+                return;
+            }
+        }
+
+        if should_close {
+            info!("Closing the websocket connection");
+            return;
+        }
+    }
+}
+
+pub async fn start_websocket<T: 'static + NymTopology>(
+    address: SocketAddr,
+    message_tx: mpsc::UnboundedSender<InputMessage>,
+    received_messages_query_tx: mpsc::UnboundedSender<BufferResponse>,
+    self_address: DestinationAddressBytes,
+    topology: TopologyInnerRef<T>,
+) -> Result<(), WebSocketError> {
+    let mut listener = tokio::net::TcpListener::bind(address).await?;
+
+    while let Ok((stream, _)) = listener.accept().await {
+        // it's fine to be cloning the channel on all new connection, because in principle
+        // this server should only EVER have a single client connected
+        tokio::spawn(accept_connection(
+            stream,
+            message_tx.clone(),
+            received_messages_query_tx.clone(),
+            self_address,
+            topology.clone(),
+        ));
+    }
+
+    error!("The websocket went kaput...");
+    Ok(())
+}
@@ -0,0 +1,7 @@
+[healthcheck]
+
+#directory-server = "http://localhost:8080"
+directory-server = "https://qa-directory.nymtech.net"
+interval = 10.0
+test-packets-per-node = 2 # in seconds
+resolution-timeout = 5 # in seconds
@@ -0,0 +1,3 @@
+#!/bin/bash
+# set CHANGELOG_GITHUB_TOKEN in your .bashrc file
+github_changelog_generator -u nymtech -p nym --exclude-tags 0.1.0 --token "$CHANGELOG_GITHUB_TOKEN"
@@ -0,0 +1,57 @@
+#!/bin/bash
+
+#// Copyright 2020 The Nym Mixnet Authors
+#//
+#// Licensed under the Apache License, Version 2.0 (the "License");
+#// you may not use this file except in compliance with the License.
+#// You may obtain a copy of the License at
+#//
+#//      http://www.apache.org/licenses/LICENSE-2.0
+#//
+#// Unless required by applicable law or agreed to in writing, software
+#// distributed under the License is distributed on an "AS IS" BASIS,
+#// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#// See the License for the specific language governing permissions and
+#// limitations under the License.
+
+
+echo "Killing old testnet processes..."
+
+killall nym-mixnode
+killall nym-sfw-provider
+
+echo "Press CTRL-C to stop."
+
+cargo build
+
+MAX_LAYERS=3
+NUMMIXES=${1:-3} # Set $NUMMIXES to default of 3, but allow the user to set other values if desired
+
+for (( j=0; j<$NUMMIXES; j++ ))
+
+# Note: to disable logging (or direct it to another output) modify the constant on top of mixnode or provider;
+# Will make it later either configurable by flags or config file.
+do
+    let layer=j%MAX_LAYERS+1
+    $PWD/target/debug/nym-mixnode run --port $((9980+$j)) --host "localhost" --layer $layer --directory http://localhost:8080 &
+    sleep 1
+done
+
+sleep 1
+$PWD/target/debug/nym-sfw-provider run --clientHost "localhost" --mixHost "localhost" --mixPort 9997 --clientPort 9998 --directory http://localhost:8080
+
+# trap call ctrl_c()
+trap ctrl_c SIGINT SIGTERM SIGTSTP
+function ctrl_c() {
+        echo "** Trapped SIGINT, SIGTERM and SIGTSTP"
+        for (( j=0; j<$NUMMIXES; j++ ));
+        do
+            kill_port $((9980+$j))
+        done
+}
+
+function kill_port() {
+    PID=$(lsof -t -i:$1)
+    echo "$PID"
+    kill -TERM $PID || kill -KILL $PID
+}
@@ -0,0 +1,34 @@
+[package]
+build = "build.rs"
+name = "nym-sfw-provider"
+version = "0.4.0"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bs58 = "0.3.0"
+clap = "2.33.0"
+curve25519-dalek = "1.2.3"
+dotenv = "0.15.0"
+futures = "0.3.1"
+log = "0.4"
+pretty_env_logger = "0.3"
+rand = "0.7.2"
+tokio = { version = "0.2.4", features = ["full"] }
+sha2 = "0.8.0"
+serde = { version = "1.0.104", features = ["derive"] }
+serde_json = "1.0.44"
+hmac = "0.7.1"
+
+## internal
+crypto = {path = "../common/crypto"}
+directory-client = { path = "../common/clients/directory-client" }
+sfw-provider-requests = { path = "./sfw-provider-requests" }
+
+## will be moved to proper dependencies once released
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
+
+[build-dependencies]
+built = "0.3.2"
@@ -0,0 +1,2 @@
+# nym-sfw-provider
+A store-and-forward provider for Nym, implemented in Rust
@@ -0,0 +1,5 @@
+use built;
+
+fn main() {
+    built::write_built_file().expect("Failed to acquire build-time information");
+}
@@ -0,0 +1,462 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+[[package]]
+name = "aes-ctr"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "aes-soft 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "aesni 0.6.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "ctr 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "stream-cipher 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "aes-soft"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "block-cipher-trait 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "aesni"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "block-cipher-trait 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "stream-cipher 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "arrayref"
+version = "0.3.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "bitflags"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "blake2"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "byte-tools 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "crypto-mac 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "block-padding 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)",
+ "byte-tools 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "block-cipher-trait"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "block-padding"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "byte-tools 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "byte-tools"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "byteorder"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "c2-chacha"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "ppv-lite86 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "cc"
+version = "1.0.48"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "cfg-if"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "chacha"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "keystream 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "clear_on_drop"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "cc 1.0.48 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "cloudabi"
+version = "0.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "bitflags 1.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "crypto-mac"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "subtle 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "ctr"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "block-cipher-trait 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "stream-cipher 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "curve25519-dalek"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "clear_on_drop 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_core 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "subtle 2.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "digest"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "fake-simd"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "fuchsia-cprng"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "generic-array"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "cfg-if 0.1.10 (registry+https://github.com/rust-lang/crates.io-index)",
+ "libc 0.2.66 (registry+https://github.com/rust-lang/crates.io-index)",
+ "wasi 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "hkdf"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "hmac 0.7.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "hmac"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "crypto-mac 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "keystream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "libc"
+version = "0.2.66"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "lioness"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "arrayref 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)",
+ "blake2 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "chacha 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "keystream 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "opaque-debug"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "rand"
+version = "0.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "getrandom 0.1.13 (registry+https://github.com/rust-lang/crates.io-index)",
+ "libc 0.2.66 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_chacha 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_hc 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "c2-chacha 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "rand_core 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "rand_core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "getrandom 0.1.13 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_distr"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "rand 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_hc"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rand_os"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "cloudabi 0.0.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "fuchsia-cprng 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "libc 0.2.66 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_core 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rdrand 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "winapi 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "rdrand"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "rand_core 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "sfw-provider-requests"
+version = "0.1.0"
+dependencies = [
+ "sphinx 0.1.0",
+]
+
+[[package]]
+name = "sha2"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "block-buffer 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "fake-simd 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "sphinx"
+version = "0.1.0"
+dependencies = [
+ "aes-ctr 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "arrayref 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)",
+ "blake2 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "chacha 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "curve25519-dalek 1.2.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "hkdf 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "hmac 0.7.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lioness 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_distr 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "rand_os 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "sha2 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "stream-cipher"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "subtle"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "subtle"
+version = "2.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "typenum"
+version = "1.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "wasi"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "winapi"
+version = "0.3.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "winapi-i686-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
+ "winapi-x86_64-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[metadata]
+"checksum aes-ctr 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "d2e5b0458ea3beae0d1d8c0f3946564f8e10f90646cf78c06b4351052058d1ee"
+"checksum aes-soft 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)" = "cfd7e7ae3f9a1fb5c03b389fc6bb9a51400d0c13053f0dca698c832bfd893a0d"
+"checksum aesni 0.6.0 (registry+https://github.com/rust-lang/crates.io-index)" = "2f70a6b5f971e473091ab7cfb5ffac6cde81666c4556751d8d5620ead8abf100"
+"checksum arrayref 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)" = "0d382e583f07208808f6b1249e60848879ba3543f57c32277bf52d69c2f0f0ee"
+"checksum bitflags 1.2.1 (registry+https://github.com/rust-lang/crates.io-index)" = "cf1de2fe8c75bc145a2f577add951f8134889b4795d47466a54a5c846d691693"
+"checksum blake2 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)" = "94cb07b0da6a73955f8fb85d24c466778e70cda767a568229b104f0264089330"
+"checksum block-buffer 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)" = "c0940dc441f31689269e10ac70eb1002a3a1d3ad1390e030043662eb7fe4688b"
+"checksum block-cipher-trait 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)" = "1c924d49bd09e7c06003acda26cd9742e796e34282ec6c1189404dee0c1f4774"
+"checksum block-padding 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)" = "fa79dedbb091f449f1f39e53edf88d5dbe95f895dae6135a8d7b881fb5af73f5"
+"checksum byte-tools 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)" = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7"
+"checksum byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)" = "a7c3dd8985a7111efc5c80b44e23ecdd8c007de8ade3b96595387e812b957cf5"
+"checksum c2-chacha 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "214238caa1bf3a496ec3392968969cab8549f96ff30652c9e56885329315f6bb"
+"checksum cc 1.0.48 (registry+https://github.com/rust-lang/crates.io-index)" = "f52a465a666ca3d838ebbf08b241383421412fe7ebb463527bba275526d89f76"
+"checksum cfg-if 0.1.10 (registry+https://github.com/rust-lang/crates.io-index)" = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822"
+"checksum chacha 0.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ddf3c081b5fba1e5615640aae998e0fbd10c24cbd897ee39ed754a77601a4862"
+"checksum clear_on_drop 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "97276801e127ffb46b66ce23f35cc96bd454fa311294bced4bbace7baa8b1d17"
+"checksum cloudabi 0.0.3 (registry+https://github.com/rust-lang/crates.io-index)" = "ddfc5b9aa5d4507acaf872de71051dfd0e309860e88966e1051e462a077aac4f"
+"checksum crypto-mac 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "4434400df11d95d556bac068ddfedd482915eb18fe8bea89bc80b6e4b1c179e5"
+"checksum ctr 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)" = "022cd691704491df67d25d006fe8eca083098253c4d43516c2206479c58c6736"
+"checksum curve25519-dalek 1.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "8b7dcd30ba50cdf88b55b033456138b7c0ac4afdc436d82e1b79f370f24cc66d"
+"checksum digest 0.8.1 (registry+https://github.com/rust-lang/crates.io-index)" = "f3d0c8c8752312f9713efd397ff63acb9f85585afbf179282e720e7704954dd5"
+"checksum fake-simd 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "e88a8acf291dafb59c2d96e8f59828f3838bb1a70398823ade51a84de6a6deed"
+"checksum fuchsia-cprng 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "a06f77d526c1a601b7c4cdd98f54b5eaabffc14d5f2f0296febdc7f357c6d3ba"
+"checksum generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)" = "c68f0274ae0e023facc3c97b2e00f076be70e254bc851d972503b328db79b2ec"
+"checksum getrandom 0.1.13 (registry+https://github.com/rust-lang/crates.io-index)" = "e7db7ca94ed4cd01190ceee0d8a8052f08a247aa1b469a7f68c6a3b71afcf407"
+"checksum hkdf 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)" = "3fa08a006102488bd9cd5b8013aabe84955cf5ae22e304c2caf655b633aefae3"
+"checksum hmac 0.7.1 (registry+https://github.com/rust-lang/crates.io-index)" = "5dcb5e64cda4c23119ab41ba960d1e170a774c8e4b9d9e6a9bc18aabf5e59695"
+"checksum keystream 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "c33070833c9ee02266356de0c43f723152bd38bd96ddf52c82b3af10c9138b28"
+"checksum libc 0.2.66 (registry+https://github.com/rust-lang/crates.io-index)" = "d515b1f41455adea1313a4a2ac8a8a477634fbae63cc6100e3aebb207ce61558"
+"checksum lioness 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "4ae926706ba42c425c9457121178330d75e273df2e82e28b758faf3de3a9acb9"
+"checksum opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "2839e79665f131bdb5782e51f2c6c9599c133c6098982a54c794358bf432529c"
+"checksum ppv-lite86 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)" = "74490b50b9fbe561ac330df47c08f3f33073d2d00c150f719147d7c54522fa1b"
+"checksum rand 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)" = "3ae1b169243eaf61759b8475a998f0a385e42042370f3a7dbaf35246eacc8412"
+"checksum rand_chacha 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)" = "03a2a90da8c7523f554344f921aa97283eadf6ac484a6d2a7d0212fa7f8d6853"
+"checksum rand_core 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)" = "7a6fdeb83b075e8266dcc8762c22776f6877a63111121f5f8c7411e5be7eed4b"
+"checksum rand_core 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)" = "9c33a3c44ca05fa6f1807d8e6743f3824e8509beca625669633be0acbdf509dc"
+"checksum rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)" = "90bde5296fc891b0cef12a6d03ddccc162ce7b2aff54160af9338f8d40df6d19"
+"checksum rand_distr 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "96977acbdd3a6576fb1d27391900035bf3863d4a16422973a409b488cf29ffb2"
+"checksum rand_hc 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c"
+"checksum rand_os 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)" = "7b75f676a1e053fc562eafbb47838d67c84801e38fc1ba459e8f180deabd5071"
+"checksum rdrand 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "678054eb77286b51581ba43620cc911abf02758c91f93f479767aed0f90458b2"
+"checksum sha2 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)" = "7b4d8bfd0e469f417657573d8451fb33d16cfe0989359b93baf3a1ffc639543d"
+"checksum stream-cipher 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)" = "8131256a5896cabcf5eb04f4d6dacbe1aefda854b0d9896e09cb58829ec5638c"
+"checksum subtle 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "2d67a5a62ba6e01cb2192ff309324cb4875d0c451d55fe2319433abe7a05a8ee"
+"checksum subtle 2.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "7c65d530b10ccaeac294f349038a597e435b18fb456aadd0840a623f83b9e941"
+"checksum typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)" = "6d2783fe2d6b8c1101136184eb41be8b1ad379e4657050b8aaff0c79ee7575f9"
+"checksum wasi 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "b89c3ce4ce14bdc6fb6beaf9ec7928ca331de5df7e5ea278375642a2f478570d"
+"checksum winapi 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)" = "8093091eeb260906a183e6ae1abdba2ef5ef2257a21801128899c3fc699229c6"
+"checksum winapi-i686-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+"checksum winapi-x86_64-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
@@ -0,0 +1,10 @@
+[package]
+name = "sfw-provider-requests"
+version = "0.1.0"
+authors = ["Jedrzej Stuczynski <jedrzej.stuczynski@gmail.com>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+sphinx = { git = "https://github.com/nymtech/sphinx", rev="8424f4b0933b4a7f64ae828b2edefc5ba43a9e79" }
@@ -0,0 +1,7 @@
+pub mod requests;
+pub mod responses;
+
+pub const DUMMY_MESSAGE_CONTENT: &[u8] =
+    b"[DUMMY MESSAGE] Wanting something does not give you the right to have it.";
+
+pub type AuthToken = [u8; 32];
--- a/Show More
+++ b/Show More