Implement base line for tests on the validator ts client

- This will need to be separated and configured accordingly 
- This was a quick spin up, using jest as a library to implement some coverage
- Further things to be refined - mocks, more coverage, better configuration, clean up methods, improve env vars

.env.sample-dev

@@ -0,0 +1,5 @@
+// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+RUST_LOG=info
+RUST_BACKTRACE=1

.github/CODEOWNERS

@@ -0,0 +1,40 @@
+# Lines starting with '#' are comments.
+# Each line is a file pattern followed by one or more owners.
+
+# More details are here: https://help.github.com/articles/about-codeowners/
+
+# The '*' pattern is global owners.
+
+# Order is important. The last matching pattern has the most precedence.
+# The folders are ordered as follows:
+
+# In each subsection folders are ordered first by depth, then alphabetically.
+# This should make it easy to add new rules without breaking existing ones.
+
+# Something weird not covered by anything else
+* @futurechimp @mmsinclair
+
+# Rust rules:
+*.rs @durch @futurechimp @jstuczyn @neacsu
+Cargo.* @durch @futurechimp @jstuczyn @neacsu
+
+# JS rules:
+*.js @mmsinclair @fmtabbara @Aid19801
+*.ts @mmsinclair @fmtabbara @Aid19801
+*.tsx @mmsinclair @fmtabbara @Aid19801
+*.jsx @mmsinclair @fmtabbara @Aid19801
+
+# Something looking like possible documentation rules:
+*.md @mfahampshire
+
+# our docker scripts
+/docker/ @neacsu
+
+# if there are any changes in the core crypto, I feel like Ania should take a look:
+/common/crypto/ @aniampio
+/common/nymsphinx/ @aniampio
+
+# Explorer and wallet should probably get looked by the product team
+/explorer/ @nymtech/product 
+/nym-wallet/ @nymtech/product 
+/wallet-web/ @nymtech/product

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Suggest an enhancement to the product
+title: "[Feature Request]"
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is...
+
+**Is your request a feature not related to an existing problem? A new feature.**
+For example. 
+- Given I am using the nym wallet
+- When I transfer nym tokens across the network
+- Then I want to have an url link in the wallet which navigates outside the application to the nym-explorer
+
+**Where does the feature fit in the Nym real estate?**
+- Application / UI 
+
+**What is this solving?**
+How will this improve the product...
+
+**Is this an update to packages or libraries?**
+If so, please list them. If not, please ignore this section.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/report.md

@@ -0,0 +1,43 @@
+---
+name: Report
+about: To help identify and reproduce issues
+title: "[Issue]"
+labels: bug, bug-needs-triage, qa
+assignees: tommyv1987
+
+---
+
+**Describe the issue**
+A clear and concise description of what the issue is...
+
+**Expected behaviour**
+A clear and concise description of what you expected to happen...
+
+**Stack Traces**
+If there are stack traces or logs, please provide them here...
+
+**Steps to Reproduce**
+Steps to reproduce the behaviour, if you're familiar with BDD syntax, please write it in this style:
+- Given I was doing X
+- And I installed Y
+- When I actioned Y
+- Then I expect Z
+
+*An example:*
+- Given I was setting up a mix-node following the instructions in the docs
+- And I successfully bonded my node via the the wallet
+- When I went to start my mixnode
+- Then I was presented with an error
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem...
+
+**Which area of Nym were you using?**
+ - UI: [e.g. Websites - network-explorer, nym-website]
+ - Application: [e.g Gateway, Client, Wallet]
+ - OS: [e.g. Ubuntu 20.x, MacOs Big Sur, Windows 10]
+ - Browser: [e.g Chrome (if applicable)]
+ - Version: [e.g. nym binary(0.11.0), browser(94.0)]
+
+**Additional context**
+Please provide any other information

.github/workflows/build.yml

@@ -0,0 +1,102 @@
+name: Continuous integration
+
+on:
+  push:
+    paths-ignore:
+      - 'explorer/**'
+  pull_request:
+    paths-ignore:
+      - 'explorer/**'
+
+jobs:
+  matrix_prep:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      # creates the matrix strategy from build_matrix_includes.json
+      - uses: actions/checkout@v2
+      - id: set-matrix
+        uses: JoshuaTheMiller/conditional-build-matrix@main
+        with:
+          inputFile: '.github/workflows/build_matrix_includes.json'
+          filter: '[?runOnEvent==`${{ github.event_name }}` || runOnEvent==`always`]'
+  build:
+    needs: matrix_prep
+    strategy:
+      matrix: ${{fromJson(needs.matrix_prep.outputs.matrix)}}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.rust == 'nightly' || matrix.rust == 'beta' || matrix.os == 'windows-latest' }}
+    steps:
+      - name: Install Dependencies (Linux)
+        run: sudo apt-get update && sudo apt-get install libwebkit2gtk-4.0-dev build-essential curl wget libssl-dev libgtk-3-dev squashfs-tools
+        if: matrix.os == 'ubuntu-latest'
+
+      - name: Check out repository code
+        uses: actions/checkout@v2
+
+      - name: Install rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ matrix.rust }}
+          override: true
+          components: rustfmt, clippy
+
+      - name: Build all binaries
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --all
+
+      - name: Run all tests
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --all
+
+      - name: Check formatting
+        uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all -- --check
+
+      - uses: actions-rs/clippy-check@v1
+        name: Clippy checks
+#        if: matrix.os == 'ubuntu-latest' && matrix.rust == 'stable'
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          args: --all-features
+
+      - name: Run clippy
+        uses: actions-rs/cargo@v1
+        if: ${{ matrix.rust != 'nightly' }}
+        with:
+          command: clippy
+          args: -- -D warnings
+
+#        COCONUT stuff
+      - name: Reclaim some disk space (because Windows is being annoying)
+        uses: actions-rs/cargo@v1
+        if: ${{ matrix.os == 'windows-latest' }}
+        with:
+          command: clean
+
+      - name: Build all binaries with coconut enabled
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --all --features=coconut
+
+      - name: Run all tests with coconut enabled
+        uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --all --features=coconut
+
+      - name: Run clippy with coconut enabled
+        uses: actions-rs/cargo@v1
+        if: ${{ matrix.rust != 'nightly' }}
+        with:
+          command: clippy
+          args: --features=coconut -- -D warnings

.github/workflows/build_matrix_includes.json

@@ -0,0 +1,50 @@
+[
+  {
+    "os":"ubuntu-latest",
+    "rust":"stable",
+    "runOnEvent":"always"
+  },
+
+  {
+    "os":"windows-latest",
+    "rust":"stable",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "os":"macos-latest",
+    "rust":"stable",
+    "runOnEvent":"pull_request"
+  },
+
+  {
+    "os":"ubuntu-latest",
+    "rust":"beta",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "os":"windows-latest",
+    "rust":"beta",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "os":"macos-latest",
+    "rust":"beta",
+    "runOnEvent":"pull_request"
+  },
+
+  {
+    "os":"ubuntu-latest",
+    "rust":"nightly",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "os":"windows-latest",
+    "rust":"nightly",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "os":"macos-latest",
+    "rust":"nightly",
+    "runOnEvent":"pull_request"
+  }
+]

.github/workflows/contract_matrix_includes.json

@@ -0,0 +1,14 @@
+[
+  {
+    "rust":"stable",
+    "runOnEvent":"always"
+  },
+  {
+    "rust":"beta",
+    "runOnEvent":"pull_request"
+  },
+  {
+    "rust":"nightly",
+    "runOnEvent":"pull_request"
+  }
+]

.github/workflows/contracts.yml

@@ -0,0 +1,64 @@
+name: Contracts
+
+on:
+  push:
+    paths-ignore:
+      - 'explorer/**'
+  pull_request:
+    paths-ignore:
+      - 'explorer/**'
+
+jobs:
+  matrix_prep:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+    steps:
+      # creates the matrix strategy from build_matrix_includes.json
+      - uses: actions/checkout@v2
+      - id: set-matrix
+        uses: JoshuaTheMiller/conditional-build-matrix@main
+        with:
+          inputFile: '.github/workflows/contract_matrix_includes.json'
+          filter: '[?runOnEvent==`${{ github.event_name }}` || runOnEvent==`always`]'
+  contracts:
+    # since it's going to be compiled into wasm, there's absolutely
+    # no point in running CI on different OS-es
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.rust == 'nightly' }}
+    needs: matrix_prep
+    strategy:
+      matrix: ${{fromJson(needs.matrix_prep.outputs.matrix)}}
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{ matrix.rust }}
+          target: wasm32-unknown-unknown
+          override: true
+          components: rustfmt, clippy
+
+      - uses: actions-rs/cargo@v1
+        env:
+          RUSTFLAGS: '-C link-arg=-s'
+        with:
+          command: build
+          args: --manifest-path contracts/Cargo.toml --all --target wasm32-unknown-unknown
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: test
+          args: --manifest-path contracts/Cargo.toml
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --manifest-path contracts/Cargo.toml --all -- --check
+
+      - uses: actions-rs/cargo@v1
+        if: ${{ matrix.rust != 'nightly' }}
+        with:
+          command: clippy
+          args: --manifest-path contracts/Cargo.toml --all -- -D warnings

.github/workflows/network-explorer-lint.yml

@@ -0,0 +1,23 @@
+name: Linting for Network Explorer (eslint/prettier)
+
+on:
+  pull_request:
+    paths:
+      - 'explorer/**'
+
+defaults:
+  run:
+    working-directory: explorer
+
+jobs:
+  build:
+    runs-on: custom-runner-linux
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14'
+      - run: npm install
+      - name: Run ESLint
+        # GitHub should automatically annotate the PR
+        run: npm run lint

.github/workflows/network-explorer.yml

@@ -0,0 +1,59 @@
+name: CI for Network Explorer
+
+on:
+  push:
+    paths:
+      - 'explorer/**'
+
+defaults:
+  run:
+    working-directory: explorer
+
+jobs:
+  build:
+    runs-on: custom-runner-linux
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install rsync
+      run: sudo apt-get install rsync
+    - uses: rlespinasse/github-slug-action@v3.x
+    - uses: actions/setup-node@v2
+      with:
+        node-version: '14'
+    - run: npm install
+      continue-on-error: true
+    - name: Set environment from the example
+      run: cp .env.prod .env
+    - run: npm run test
+      continue-on-error: true
+    - run: npm run build
+      continue-on-error: true
+    - name: Deploy branch to CI www
+      continue-on-error: true
+      uses: easingthemes/ssh-deploy@main
+      env:
+        SSH_PRIVATE_KEY: ${{ secrets.CI_WWW_SSH_PRIVATE_KEY }}
+        ARGS: "-rltgoDzvO --delete"
+        SOURCE: "explorer/dist/"
+        REMOTE_HOST: ${{ secrets.CI_WWW_REMOTE_HOST }}
+        REMOTE_USER: ${{ secrets.CI_WWW_REMOTE_USER }}
+        TARGET: ${{ secrets.CI_WWW_REMOTE_TARGET }}/network-explorer-${{ env.GITHUB_REF_SLUG }}
+        EXCLUDE: "/dist/, /node_modules/"
+    - name: Keybase - Node Install
+      run: npm install
+      working-directory: .github/workflows/support-files/messages
+    - name: Keybase - Send Notification
+      env:
+        NYM_PROJECT_NAME: "Network Explorer"
+        NYM_CI_WWW_BASE: "${{ secrets.NYM_CI_WWW_BASE }}"
+        NYM_CI_WWW_LOCATION: "network-explorer-${{ env.GITHUB_REF_SLUG }}"
+        GIT_COMMIT_MESSAGE: "${{ github.event.head_commit.message }}"
+        GIT_BRANCH: "${GITHUB_REF##*/}"
+        KEYBASE_NYMBOT_USERNAME: "${{ secrets.KEYBASE_NYMBOT_USERNAME }}"
+        KEYBASE_NYMBOT_PAPERKEY: "${{ secrets.KEYBASE_NYMBOT_PAPERKEY }}"
+        KEYBASE_NYMBOT_TEAM: "${{ secrets.KEYBASE_NYMBOT_TEAM }}"
+        KEYBASE_NYM_CHANNEL: "ci-network-explorer"
+        IS_SUCCESS: "${{ job.status == 'success' }}"
+      uses: docker://keybaseio/client:stable-node
+      with:
+        args: .github/workflows/support-files/messages/entry_point_notifications.sh

.github/workflows/nym-wallet-publish.yml

@@ -0,0 +1,12 @@
+name: Publish Nym Wallet
+on:
+  push:
+    tags:
+      - nym-wallet-*
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run a one-line script
+        run: echo Hello, world!

.github/workflows/nym-wallet-types.yml

@@ -0,0 +1,29 @@
+name: Generate TS types
+
+on:
+  push:
+    paths-ignore:
+      - "explorer/**"
+  pull_request:
+    paths-ignore:
+      - "explorer/**"
+
+jobs:
+  nym-wallet-types:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'pull_request' }}
+    steps:
+      - name: Prepare
+        run: sudo apt-get update && sudo apt-get install -y libpango1.0-dev libatk1.0-dev libgdk-pixbuf2.0-dev libsoup2.4-dev librust-gdk-dev libwebkit2gtk-4.0-dev
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - name: Generate TS
+        run: cd nym-wallet/src-tauri && cargo test
+      - uses: EndBug/add-and-commit@v7.2.1 # https://github.com/marketplace/actions/add-commit
+        with:
+          add: '["nym-wallet"]'
+          message: "[ci skip] Generate TS types"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/nym_wallet.yml

@@ -0,0 +1,77 @@
+name: Webdriverio tests for nym wallet
+
+on:
+  push:
+    paths:
+      - "nym-wallet/**"
+
+defaults:
+  run:
+    working-directory: nym-wallet
+
+jobs:
+  test:
+    name: wallet tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Tauri dependencies
+        run: >
+          sudo apt-get update &&
+          sudo apt-get install -y
+          libgtk-3-dev
+          libgtksourceview-3.0-dev
+          webkit2gtk-4.0
+          libappindicator3-dev
+          webkit2gtk-driver
+          xvfb
+
+      - name: Install minimal stable
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+
+      - name: Node v16
+        uses: actions/setup-node@v1
+        with:
+          node-version: 16.x
+
+      - name: Install yarn for building application
+        run: yarn install
+
+      - name: Build application
+        run: yarn run webpack:build & yarn run tauri:build
+
+      - name: Check binary exists
+        run: |
+          cd target/release/
+          (test -f nym-wallet && echo nym binary exists) || echo wallet does not exist
+
+      - name: Install dependencies
+        run: yarn install
+        working-directory: nym-wallet/webdriver
+
+      - name: Remove existing user datafile
+        uses: JesseTG/rm@v1.0.2
+        with:
+          path: nym-wallet/webdriver/common/data/user-data.json
+
+      - name: Create user data json file
+        id: create-json
+        uses: jsdaniell/create-json@1.1.2
+        with:
+          name: "user-data.json"
+          json: ${{ secrets.WALLET_USERDATA }}
+          dir: "nym-wallet/webdriver/common/data/"
+
+      - name: Install tauri-driver
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: tauri-driver
+
+      - name: Launch tests
+        run: xvfb-run yarn test:runall
+        working-directory: nym-wallet/webdriver

.github/workflows/support-files/messages/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.idea

.github/workflows/support-files/messages/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2
+}

.github/workflows/support-files/messages/entry_point_notifications.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+# pass exit codes out to GitHub Actions
+set -euxo pipefail
+
+# change to the directory that contains this script
+cd "${0%/*}"
+
+# run the node script
+node send_message.js

.github/workflows/support-files/messages/failure

@@ -0,0 +1,11 @@
+🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥
+> :rocket: {{ env.NYM_PROJECT_NAME }}
+> 🔴 **FAILURE** :cry:
+> `branch` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/tree/{{ env.GIT_BRANCH_NAME }}
+> `commit` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/commit/{{ env.GITHUB_SHA }}
+> `build ` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/actions/runs/{{ env.GITHUB_RUN_ID }}
+
+Commit message:
+```
+{{ env.GIT_COMMIT_MESSAGE }}
+```

.github/workflows/support-files/messages/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "send-keybase-message",
+  "description": "Sends a notification message with the keybase package that fails when piped into the keybase CLI",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "format": "prettier --write send_message.js"
+  },
+  "dependencies": {
+    "handlebars": "^4.7.7",
+    "keybase-bot": "^3.6.1"
+  },
+  "devDependencies": {
+    "prettier": "2.3.2"
+  }
+}

.github/workflows/support-files/messages/send_message.js

@@ -0,0 +1,69 @@
+const Bot = require('keybase-bot');
+const Handlebars = require('handlebars');
+const fs = require('fs');
+
+async function main() {
+  const data = { env: process.env };
+  // const data = { ...PASTE TEST DATA HERE ... }; // -- DEV: uncomment to set test data
+
+  // validation of environment
+  if(!(process.env.NYM_PROJECT_NAME || data.env.NYM_PROJECT_NAME)) {
+    throw new Error('Please set env var NYM_PROJECT_NAME with the project name for displaying in notification messages');
+  }
+  const keybaseChannel = process.env.KEYBASE_NYM_CHANNEL || data.env.KEYBASE_NYM_CHANNEL;
+  if(!keybaseChannel) {
+    throw new Error('Please set env var KEYBASE_NYM_CHANNEL with the channel name for the notification message');
+  }
+
+  // extract the git branch name
+  const GIT_BRANCH_NAME = (process.env.GITHUB_REF || data.env.GITHUB_REF).split('/').slice(2).join('/');
+
+  data.env.GIT_BRANCH_NAME = GIT_BRANCH_NAME;
+  const source = fs
+    .readFileSync(process.env.IS_SUCCESS === 'true' ? 'success' : 'failure')
+    .toString();
+  const template = Handlebars.compile(source);
+  const result = template(data);
+
+  // -- DEV: uncomment to show what is available in the handlebars template / show the result
+  // console.dir({ data }, { depth: null });
+  // console.log(result);
+
+  const bot = new Bot();
+  try {
+    const username = process.env.KEYBASE_NYMBOT_USERNAME;
+    const paperkey = process.env.KEYBASE_NYMBOT_PAPERKEY;
+
+    if(!username) {
+      throw new Error('Username is not defined. Please set env var KEYBASE_NYMBOT_USERNAME');
+    }
+    if(!paperkey) {
+      throw new Error('Paperkey is not defined. Please set env var KEYBASE_NYMBOT_PAPERKEY');
+    }
+
+    console.log(`Initialising keybase with user "${username}" and key: "${'*'.repeat(paperkey.length)}"...`);
+    await bot.init(username, paperkey, { verbose: false });
+
+    const channel = {
+      name: 'nymtech_bot',
+      membersType: 'team',
+      topicName: keybaseChannel,
+      topic_type: 'CHAT',
+    };
+    const message = {
+      body: result,
+    };
+
+    console.log(`Sending to ${channel.name}#${channel.topicName}...`);
+    await bot.chat.send(channel, message);
+
+    console.log('Message sent!');
+  } catch (error) {
+    console.error(error);
+    process.exitCode = -1;
+  } finally {
+    await bot.deinit();
+  }
+}
+
+main();

.github/workflows/support-files/messages/success

@@ -0,0 +1,11 @@
+🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩
+> :rocket: {{ env.NYM_PROJECT_NAME }}  ➡️➡️➡️➡️➡️ **View output:** https://{{ env.NYM_CI_WWW_LOCATION }}.{{ env.NYM_CI_WWW_BASE }}/
+> ✅ **SUCCESS**
+> `branch` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/tree/{{ env.GIT_BRANCH_NAME }}
+> `commit` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/commit/{{ env.GITHUB_SHA }}
+> `build ` {{ env.GITHUB_SERVER_URL }}/{{ env.GITHUB_REPOSITORY }}/actions/runs/{{ env.GITHUB_RUN_ID }}
+
+Commit message:
+```
+{{ env.GIT_COMMIT_MESSAGE }}
+```

.github/workflows/wasm_client_build.yml

@@ -0,0 +1,48 @@
+name: Wasm Client
+
+on:
+  pull_request:
+    paths-ignore:
+      - 'explorer/**'
+
+jobs:
+  wasm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          target: wasm32-unknown-unknown
+          override: true
+          components: rustfmt, clippy
+
+# token credentials (non-coconut) don't work for wasm right now
+#      - uses: actions-rs/cargo@v1
+#        with:
+#          command: build
+#          args: --manifest-path clients/webassembly/Cargo.toml --target wasm32-unknown-unknown
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --manifest-path clients/webassembly/Cargo.toml --target wasm32-unknown-unknown --features=coconut
+
+# for some reason this does not seem to work correctly, leave it for later, building is good enough for now
+#      - uses: actions-rs/cargo@v1
+#        with:
+#          command: test
+#          args: --manifest-path clients/webassembly/Cargo.toml --target wasm32-unknown-unknown
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --manifest-path clients/webassembly/Cargo.toml -- --check
+
+# for some reason this does not seem to work correctly, leave it for later, building is good enough for now
+#      - uses: actions-rs/cargo@v1
+#        with:
+#          command: clippy
+#          args: --manifest-path clients/webassembly/Cargo.toml --target wasm32-unknown-unknown -- -D warnings

.github_changelog_generator

@@ -0,0 +1,3 @@
+unreleased=true
+future-release=v0.12.0
+since-tag=v0.11.0

.gitignore

@@ -1,3 +1,38 @@
-/target
+// Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: CC0-1.0
+
+/targetString
 **/*.rs.bk
-/.idea/
+/*/target
+/test_inbox
+.idea
+target
+.env
+/.vscode/settings.json
+validator/.vscode
+sample-configs/validator-config.toml
+scripts/deploy_qa.sh
+scripts/run_gate.sh
+scripts/run_mix.sh
+scripts/start_local_tmux_network.sh
+/.floo
+/.flooignore
+qa-v4-topology.json
+qa-v6-topology.json
+v4-topology.json
+v6-topology.json
+/explorer/downloads/topology.json
+/explorer/public/downloads/mixmining.json
+/explorer/public/downloads/topology.json
+/nym-wallet/dist/*
+/clients/validator/examples/nym-driver-example/current-contract.txt
+validator-api/v4.json
+validator-api/v6.json
+**/node_modules
+validator-api/keypair
+contracts/mixnet/code_id
+contracts/mixnet/Justfile
+contracts/mixnet/Makefile
+validator-config
+*.patch
+validator-api-config.toml

.reuse/dep5

@@ -0,0 +1,9 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: nym
+Upstream-Contact: Nym Technologies SA <contact@nymtech.net>
+Source: https://github.com/nymtech/nym
+
+
+Files: *clients/* *common/* *explorer/*
+Copyright: 2020, Nym Technologies SA <contact@nymtech.net>
+License: Apache-2.0

.ruby-version

@@ -0,0 +1 @@
+2.7.5

CHANGELOG.md

@@ -1,12 +1,247 @@
-# 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
+## [v0.12.0](https://github.com/nymtech/nym/tree/v0.12.0) (2021-12-21)
 
-## 0.1.0 - Initial Release
+[Full Changelog](https://github.com/nymtech/nym/compare/v0.11.0...v0.12.0)
 
-* The bare minimum set of features required by a Nym Client
+**Implemented enhancements:**
+
+- Introduces query for contract build information [\#919](https://github.com/nymtech/nym/pull/919) ([jstuczyn](https://github.com/jstuczyn))
+
+**Fixed bugs:**
+
+- Mixnodes - claim tokens scenario does not work with telegram bot [\#938](https://github.com/nymtech/nym/issues/938)
+- \[Issue\]"create account" button does not work on Ubuntu 20.04.03 LTS [\#916](https://github.com/nymtech/nym/issues/916)
+- \[Issue\] NodeJS 17.1.0 and webpack issues causing nym-wallet build to fail on Pop!OS 21.04\(Ubuntu\) [\#914](https://github.com/nymtech/nym/issues/914)
+- Prevent overwriting of Mixnodes if the mixnode is already bonded [\#912](https://github.com/nymtech/nym/issues/912)
+- Pasting mnemonic doesn't work on MacOS [\#908](https://github.com/nymtech/nym/issues/908)
+- Wallet - investigate nav freezes [\#716](https://github.com/nymtech/nym/issues/716)
+- Wallet - Fix console errors [\#707](https://github.com/nymtech/nym/issues/707)
+- Fixed invalid nodes being counted twice in unroutable category [\#963](https://github.com/nymtech/nym/pull/963) ([jstuczyn](https://github.com/jstuczyn))
+- Don't reset total delegation on mixnode rebond [\#940](https://github.com/nymtech/nym/pull/940) ([jstuczyn](https://github.com/jstuczyn))
+- Bugfix/remove mixnode bonding overwrite [\#917](https://github.com/nymtech/nym/pull/917) ([jstuczyn](https://github.com/jstuczyn))
+- Fixes crash condition in validator API when calculating last day uptime [\#909](https://github.com/nymtech/nym/pull/909) ([jstuczyn](https://github.com/jstuczyn))
+- Bugfix/monitor initial values wait [\#907](https://github.com/nymtech/nym/pull/907) ([jstuczyn](https://github.com/jstuczyn))
+- Bug fix: Network Explorer: Add freegeoip API key and split out tasks for country distributions  [\#806](https://github.com/nymtech/nym/pull/806) ([mmsinclair](https://github.com/mmsinclair))
+- Explorer API: port test now split out address resolution and add units tests [\#755](https://github.com/nymtech/nym/pull/755) ([mmsinclair](https://github.com/mmsinclair))
+
+**Closed issues:**
+
+- Feature gate `ts-rs` everywhere and only build use it to export types during CI runs [\#893](https://github.com/nymtech/nym/issues/893)
+- Error when init Nym client for Nym requester [\#800](https://github.com/nymtech/nym/issues/800)
+- Website updates - Add new team members and translations [\#775](https://github.com/nymtech/nym/issues/775)
+- Update Run Nym Nodes Documentation [\#773](https://github.com/nymtech/nym/issues/773)
+- Upgrade `prost` to 0.8 [\#768](https://github.com/nymtech/nym/issues/768)
+- How can I get 100punk\(Version: 0.11.0\) [\#743](https://github.com/nymtech/nym/issues/743)
+- Wallet - Fix Bond Form validation issue [\#717](https://github.com/nymtech/nym/issues/717)
+- help!!! [\#712](https://github.com/nymtech/nym/issues/712)
+- UX feature request: show all delegated nodes in wallet [\#711](https://github.com/nymtech/nym/issues/711)
+- UX feature request: add current balance on wallet pages [\#710](https://github.com/nymtech/nym/issues/710)
+- got sign issue from bot  [\#709](https://github.com/nymtech/nym/issues/709)
+- As a wallet user, I would like to be able to log out of the wallet [\#706](https://github.com/nymtech/nym/issues/706)
+- As a wallet user, I would like to have a "receive" page where I can see my own wallet address [\#705](https://github.com/nymtech/nym/issues/705)
+- Update native client/socks client/mixnode/gateway `upgrade` command [\#689](https://github.com/nymtech/nym/issues/689)
+- Update mixnode/gateway/client to use query for cached nodes rather than use validator [\#688](https://github.com/nymtech/nym/issues/688)
+- '--directory' not expected error starting local mixnet [\#520](https://github.com/nymtech/nym/issues/520)
+- nym-socks5-client is painfully slow [\#495](https://github.com/nymtech/nym/issues/495)
+- nym-socks5-client crash after opening Keybase team "Browse all channels" [\#494](https://github.com/nymtech/nym/issues/494)
+- Mixed Content problem [\#400](https://github.com/nymtech/nym/issues/400)
+- Gateway disk quota [\#137](https://github.com/nymtech/nym/issues/137)
+- Simplify message encapsulation with regards to topology  [\#127](https://github.com/nymtech/nym/issues/127)
+- Create constants for cli argument names [\#115](https://github.com/nymtech/nym/issues/115)
+- Using Blake3 as a hash function [\#103](https://github.com/nymtech/nym/issues/103)
+- Validator should decide which layer a node is in [\#86](https://github.com/nymtech/nym/issues/86)
+- Clean shutdown for all processes [\#73](https://github.com/nymtech/nym/issues/73)
+- Client API consistency [\#71](https://github.com/nymtech/nym/issues/71)
+- Simplify concurrency with a proper actor framework [\#31](https://github.com/nymtech/nym/issues/31)
+- Database for gateway [\#11](https://github.com/nymtech/nym/issues/11)
+
+**Merged pull requests:**
+
+- Fix success view messages. [\#990](https://github.com/nymtech/nym/pull/990) ([tommyv1987](https://github.com/tommyv1987))
+- Feature/enable signature check [\#989](https://github.com/nymtech/nym/pull/989) ([neacsu](https://github.com/neacsu))
+- Update mixnet contract address [\#988](https://github.com/nymtech/nym/pull/988) ([neacsu](https://github.com/neacsu))
+- Fix verloc print [\#987](https://github.com/nymtech/nym/pull/987) ([neacsu](https://github.com/neacsu))
+- Feature/refactor mixnet contract test helpers [\#986](https://github.com/nymtech/nym/pull/986) ([futurechimp](https://github.com/futurechimp))
+- Making the terminology consistent between mixnode/gateway output and … [\#985](https://github.com/nymtech/nym/pull/985) ([futurechimp](https://github.com/futurechimp))
+- Feature/add wallet to gateway init [\#984](https://github.com/nymtech/nym/pull/984) ([futurechimp](https://github.com/futurechimp))
+- Feature/add wallet address to init [\#982](https://github.com/nymtech/nym/pull/982) ([futurechimp](https://github.com/futurechimp))
+- Update message to bond mixnode [\#981](https://github.com/nymtech/nym/pull/981) ([tommyv1987](https://github.com/tommyv1987))
+- Bump version to 0.12.0 [\#980](https://github.com/nymtech/nym/pull/980) ([neacsu](https://github.com/neacsu))
+- Feature/rename erc20 [\#979](https://github.com/nymtech/nym/pull/979) ([neacsu](https://github.com/neacsu))
+- Removed web wallet [\#978](https://github.com/nymtech/nym/pull/978) ([futurechimp](https://github.com/futurechimp))
+- Network Explorer: fix uptime history display to use new API response [\#977](https://github.com/nymtech/nym/pull/977) ([mmsinclair](https://github.com/mmsinclair))
+- Make develop branch agnostic of the network [\#976](https://github.com/nymtech/nym/pull/976) ([neacsu](https://github.com/neacsu))
+- Fix windows fmt [\#975](https://github.com/nymtech/nym/pull/975) ([neacsu](https://github.com/neacsu))
+- Feature/wallet settings area [\#974](https://github.com/nymtech/nym/pull/974) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/node info command [\#972](https://github.com/nymtech/nym/pull/972) ([jstuczyn](https://github.com/jstuczyn))
+- Use the renamed balance function [\#971](https://github.com/nymtech/nym/pull/971) ([neacsu](https://github.com/neacsu))
+- Introduced 'version' command to all relevant binaries [\#969](https://github.com/nymtech/nym/pull/969) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/new testnet wallet updates [\#968](https://github.com/nymtech/nym/pull/968) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/optional bandwidth bypass [\#965](https://github.com/nymtech/nym/pull/965) ([jstuczyn](https://github.com/jstuczyn))
+- Additional tauri commands to get bond details [\#964](https://github.com/nymtech/nym/pull/964) ([jstuczyn](https://github.com/jstuczyn))
+- Fix topology log [\#962](https://github.com/nymtech/nym/pull/962) ([neacsu](https://github.com/neacsu))
+- Network Explorer: configure URLs with `.env` file [\#960](https://github.com/nymtech/nym/pull/960) ([mmsinclair](https://github.com/mmsinclair))
+- Add custom denom balance query [\#957](https://github.com/nymtech/nym/pull/957) ([neacsu](https://github.com/neacsu))
+- Feature/ts client update [\#956](https://github.com/nymtech/nym/pull/956) ([jstuczyn](https://github.com/jstuczyn))
+- Check the response for multiple sends [\#955](https://github.com/nymtech/nym/pull/955) ([neacsu](https://github.com/neacsu))
+- Feature/vesting to wallet [\#954](https://github.com/nymtech/nym/pull/954) ([durch](https://github.com/durch))
+- Bugfix/rewarding fixes [\#953](https://github.com/nymtech/nym/pull/953) ([jstuczyn](https://github.com/jstuczyn))
+- Bump next from 11.1.1 to 11.1.3 in /wallet-web [\#952](https://github.com/nymtech/nym/pull/952) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Different workshare calculations for rewarded vs active set [\#951](https://github.com/nymtech/nym/pull/951) ([durch](https://github.com/durch))
+- Feature/simulate [\#950](https://github.com/nymtech/nym/pull/950) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/profit margin percent config [\#949](https://github.com/nymtech/nym/pull/949) ([durch](https://github.com/durch))
+- Run CI for all contracts in one workflow [\#948](https://github.com/nymtech/nym/pull/948) ([durch](https://github.com/durch))
+- Desktop Wallet UI Updates [\#947](https://github.com/nymtech/nym/pull/947) ([fmtabbara](https://github.com/fmtabbara))
+- Docker updates [\#946](https://github.com/nymtech/nym/pull/946) ([tommyv1987](https://github.com/tommyv1987))
+- Add VestingExecute and VestingQuery client traits [\#944](https://github.com/nymtech/nym/pull/944) ([durch](https://github.com/durch))
+- Removed reliance on cosmrs fork [\#943](https://github.com/nymtech/nym/pull/943) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/terminology update [\#941](https://github.com/nymtech/nym/pull/941) ([jstuczyn](https://github.com/jstuczyn))
+- Check the response for other transactions as well [\#937](https://github.com/nymtech/nym/pull/937) ([neacsu](https://github.com/neacsu))
+- Allow proxy gateway bonding [\#936](https://github.com/nymtech/nym/pull/936) ([durch](https://github.com/durch))
+- Feature/pre cosmrs updates [\#935](https://github.com/nymtech/nym/pull/935) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/client on behalf [\#934](https://github.com/nymtech/nym/pull/934) ([neacsu](https://github.com/neacsu))
+- Webpack wallet prod configuration [\#933](https://github.com/nymtech/nym/pull/933) ([tommyv1987](https://github.com/tommyv1987))
+- Adding tx\_hash to wallet response [\#932](https://github.com/nymtech/nym/pull/932) ([futurechimp](https://github.com/futurechimp))
+- Release/1.0.0 pre1 [\#931](https://github.com/nymtech/nym/pull/931) ([durch](https://github.com/durch))
+- Feature/identity verification [\#930](https://github.com/nymtech/nym/pull/930) ([jstuczyn](https://github.com/jstuczyn))
+- Move cleaned up smart contracts to main code repo  [\#929](https://github.com/nymtech/nym/pull/929) ([mfahampshire](https://github.com/mfahampshire))
+- Feature/mixnet contract further adjustments [\#928](https://github.com/nymtech/nym/pull/928) ([jstuczyn](https://github.com/jstuczyn))
+- typo copy change for nodemap [\#926](https://github.com/nymtech/nym/pull/926) ([Aid19801](https://github.com/Aid19801))
+- Feature/UI enhancements for Desktop Wallet [\#925](https://github.com/nymtech/nym/pull/925) ([fmtabbara](https://github.com/fmtabbara))
+- Fixing some clippy warnings [\#922](https://github.com/nymtech/nym/pull/922) ([futurechimp](https://github.com/futurechimp))
+- Fixing go warning re unused btc lib [\#921](https://github.com/nymtech/nym/pull/921) ([futurechimp](https://github.com/futurechimp))
+- quick fix adding dimensions to nodemap page for consistency [\#920](https://github.com/nymtech/nym/pull/920) ([Aid19801](https://github.com/Aid19801))
+- Bump nth-check from 2.0.0 to 2.0.1 in /nym-wallet [\#918](https://github.com/nymtech/nym/pull/918) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Fix Mobile View for MUI data-grid \(CARD 108\) [\#915](https://github.com/nymtech/nym/pull/915) ([Aid19801](https://github.com/Aid19801))
+- Feature/total delegation bucket [\#913](https://github.com/nymtech/nym/pull/913) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/faucet page react [\#911](https://github.com/nymtech/nym/pull/911) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/mixnet contract refactor [\#910](https://github.com/nymtech/nym/pull/910) ([futurechimp](https://github.com/futurechimp))
+- Update README.md [\#905](https://github.com/nymtech/nym/pull/905) ([tommyv1987](https://github.com/tommyv1987))
+- BUG: Bond cell denom  [\#904](https://github.com/nymtech/nym/pull/904) ([Aid19801](https://github.com/Aid19801))
+- Explorer UI tests missing data-testid [\#903](https://github.com/nymtech/nym/pull/903) ([tommyv1987](https://github.com/tommyv1987))
+- Fix up Nym-Wallet README.md [\#899](https://github.com/nymtech/nym/pull/899) ([tommyv1987](https://github.com/tommyv1987))
+- Feature/batch delegator rewarding [\#898](https://github.com/nymtech/nym/pull/898) ([jstuczyn](https://github.com/jstuczyn))
+- Bug mapp nodemap [\#897](https://github.com/nymtech/nym/pull/897) ([Aid19801](https://github.com/Aid19801))
+- Bug fix/macos keyboard shortcuts [\#896](https://github.com/nymtech/nym/pull/896) ([fmtabbara](https://github.com/fmtabbara))
+- Add a Mobile Nav to the Network Explorer [\#895](https://github.com/nymtech/nym/pull/895) ([Aid19801](https://github.com/Aid19801))
+- Only use ts-rs in tests [\#894](https://github.com/nymtech/nym/pull/894) ([durch](https://github.com/durch))
+- Fix network monitor template [\#892](https://github.com/nymtech/nym/pull/892) ([neacsu](https://github.com/neacsu))
+- remove delegation and undelegation from gateways [\#891](https://github.com/nymtech/nym/pull/891) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/nym wallet rename [\#890](https://github.com/nymtech/nym/pull/890) ([futurechimp](https://github.com/futurechimp))
+- Change MixnodeDetail page's datagrid into a reuseable table component [\#887](https://github.com/nymtech/nym/pull/887) ([Aid19801](https://github.com/Aid19801))
+- GitHub Actions: only run job to generate types when not in a PR [\#886](https://github.com/nymtech/nym/pull/886) ([mmsinclair](https://github.com/mmsinclair))
+- Adding data-test-ids for the explorer [\#885](https://github.com/nymtech/nym/pull/885) ([tommyv1987](https://github.com/tommyv1987))
+- Fix path for github action running tauri-wallet-tests [\#884](https://github.com/nymtech/nym/pull/884) ([tommyv1987](https://github.com/tommyv1987))
+- Reverted gateway registration handshake to its 0.11.0 version [\#882](https://github.com/nymtech/nym/pull/882) ([jstuczyn](https://github.com/jstuczyn))
+- Network Explorer [\#881](https://github.com/nymtech/nym/pull/881) ([mmsinclair](https://github.com/mmsinclair))
+- Feature/rewarding interval updates [\#880](https://github.com/nymtech/nym/pull/880) ([jstuczyn](https://github.com/jstuczyn))
+- Put client\_address and id in the correct order [\#875](https://github.com/nymtech/nym/pull/875) ([neacsu](https://github.com/neacsu))
+- remove gateway selection on delegation and undelegation pages [\#873](https://github.com/nymtech/nym/pull/873) ([fmtabbara](https://github.com/fmtabbara))
+- Set MSRV on all binaries to 1.56 [\#872](https://github.com/nymtech/nym/pull/872) ([jstuczyn](https://github.com/jstuczyn))
+- add native window items \(copy/paste\) via tauri [\#871](https://github.com/nymtech/nym/pull/871) ([fmtabbara](https://github.com/fmtabbara))
+- Remove stale migration code [\#868](https://github.com/nymtech/nym/pull/868) ([neacsu](https://github.com/neacsu))
+- Fixed most recent nightly clippy warnings [\#865](https://github.com/nymtech/nym/pull/865) ([jstuczyn](https://github.com/jstuczyn))
+- Active sets =\> Rewarded + Active/Idle sets [\#864](https://github.com/nymtech/nym/pull/864) ([jstuczyn](https://github.com/jstuczyn))
+- Chore/cosmrs update [\#862](https://github.com/nymtech/nym/pull/862) ([jstuczyn](https://github.com/jstuczyn))
+- Made daily uptime calculation be independent of epoch rewarding [\#860](https://github.com/nymtech/nym/pull/860) ([jstuczyn](https://github.com/jstuczyn))
+- Removed epoch rewarding variance [\#857](https://github.com/nymtech/nym/pull/857) ([jstuczyn](https://github.com/jstuczyn))
+- Removed gateway rewarding and delegation [\#856](https://github.com/nymtech/nym/pull/856) ([jstuczyn](https://github.com/jstuczyn))
+- Update feature-request template [\#855](https://github.com/nymtech/nym/pull/855) ([tommyv1987](https://github.com/tommyv1987))
+- Update issue templates [\#854](https://github.com/nymtech/nym/pull/854) ([tommyv1987](https://github.com/tommyv1987))
+- Overflow checks in release [\#846](https://github.com/nymtech/nym/pull/846) ([jstuczyn](https://github.com/jstuczyn))
+- fix delegate success overflow [\#842](https://github.com/nymtech/nym/pull/842) ([fmtabbara](https://github.com/fmtabbara))
+- Feature NYM wallet webdriverio test [\#841](https://github.com/nymtech/nym/pull/841) ([tommyv1987](https://github.com/tommyv1987))
+- Update nym\_wallet.yml [\#840](https://github.com/nymtech/nym/pull/840) ([tommyv1987](https://github.com/tommyv1987))
+- Feature/vouchers [\#837](https://github.com/nymtech/nym/pull/837) ([aniampio](https://github.com/aniampio))
+- Apply readable ids to elements on Nym Wallet [\#836](https://github.com/nymtech/nym/pull/836) ([tommyv1987](https://github.com/tommyv1987))
+- Feature/removal of monitor good nodes [\#833](https://github.com/nymtech/nym/pull/833) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/bandwidth token [\#832](https://github.com/nymtech/nym/pull/832) ([neacsu](https://github.com/neacsu))
+- update app name and icons [\#831](https://github.com/nymtech/nym/pull/831) ([fmtabbara](https://github.com/fmtabbara))
+- Create nym-wallet-tests.yml [\#829](https://github.com/nymtech/nym/pull/829) ([tommyv1987](https://github.com/tommyv1987))
+- Updated CODEOWNERS [\#828](https://github.com/nymtech/nym/pull/828) ([jstuczyn](https://github.com/jstuczyn))
+- Tauri wallet [\#827](https://github.com/nymtech/nym/pull/827) ([fmtabbara](https://github.com/fmtabbara))
+- Flag to only run coconut-related functionalities [\#824](https://github.com/nymtech/nym/pull/824) ([jstuczyn](https://github.com/jstuczyn))
+- Change false to true, as for mixnodes [\#822](https://github.com/nymtech/nym/pull/822) ([neacsu](https://github.com/neacsu))
+- Feature locked client-side bandwidth metering [\#820](https://github.com/nymtech/nym/pull/820) ([jstuczyn](https://github.com/jstuczyn))
+- Fixed most recent nightly clippy warnings [\#817](https://github.com/nymtech/nym/pull/817) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/resending rewards on timeout [\#810](https://github.com/nymtech/nym/pull/810) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/coconut feature [\#805](https://github.com/nymtech/nym/pull/805) ([jstuczyn](https://github.com/jstuczyn))
+- Tokenomics rewards [\#802](https://github.com/nymtech/nym/pull/802) ([durch](https://github.com/durch))
+- Rocket picking up environment from Rocket.toml again [\#801](https://github.com/nymtech/nym/pull/801) ([jstuczyn](https://github.com/jstuczyn))
+- Remove migration code [\#796](https://github.com/nymtech/nym/pull/796) ([neacsu](https://github.com/neacsu))
+- Removes code of executed migrations [\#793](https://github.com/nymtech/nym/pull/793) ([jstuczyn](https://github.com/jstuczyn))
+- Bugfix/validator api windows build [\#791](https://github.com/nymtech/nym/pull/791) ([jstuczyn](https://github.com/jstuczyn))
+- Removed SQLx offline mode artifact [\#790](https://github.com/nymtech/nym/pull/790) ([jstuczyn](https://github.com/jstuczyn))
+- Created getters for AccountData [\#787](https://github.com/nymtech/nym/pull/787) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/migrate hidden delegations [\#786](https://github.com/nymtech/nym/pull/786) ([neacsu](https://github.com/neacsu))
+- Feature/persistent gateway storage [\#784](https://github.com/nymtech/nym/pull/784) ([jstuczyn](https://github.com/jstuczyn))
+- Replaced unwrap\_or\_else with unwrap\_or\_default [\#780](https://github.com/nymtech/nym/pull/780) ([jstuczyn](https://github.com/jstuczyn))
+- Add block\_height method to Delegation [\#778](https://github.com/nymtech/nym/pull/778) ([durch](https://github.com/durch))
+- Make fee helpers public [\#777](https://github.com/nymtech/nym/pull/777) ([durch](https://github.com/durch))
+- re-enable bonding [\#776](https://github.com/nymtech/nym/pull/776) ([fmtabbara](https://github.com/fmtabbara))
+- Explorer-api: add API resource to show the delegations for each mix node [\#774](https://github.com/nymtech/nym/pull/774) ([mmsinclair](https://github.com/mmsinclair))
+- add app alert [\#772](https://github.com/nymtech/nym/pull/772) ([fmtabbara](https://github.com/fmtabbara))
+- Migrate legacy delegation data [\#771](https://github.com/nymtech/nym/pull/771) ([durch](https://github.com/durch))
+- Adding deps for building the Tauri wallet under Ubuntu [\#770](https://github.com/nymtech/nym/pull/770) ([futurechimp](https://github.com/futurechimp))
+- remove alert [\#767](https://github.com/nymtech/nym/pull/767) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/consumable bandwidth [\#766](https://github.com/nymtech/nym/pull/766) ([neacsu](https://github.com/neacsu))
+- Update coconut-rs and use hash\_to\_scalar from there [\#765](https://github.com/nymtech/nym/pull/765) ([neacsu](https://github.com/neacsu))
+- Feature/active sets [\#764](https://github.com/nymtech/nym/pull/764) ([jstuczyn](https://github.com/jstuczyn))
+- add app alert banner [\#762](https://github.com/nymtech/nym/pull/762) ([fmtabbara](https://github.com/fmtabbara))
+- Updated cosmos-sdk [\#761](https://github.com/nymtech/nym/pull/761) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/bond blockstamp [\#760](https://github.com/nymtech/nym/pull/760) ([neacsu](https://github.com/neacsu))
+- Feature/revert migration code [\#759](https://github.com/nymtech/nym/pull/759) ([neacsu](https://github.com/neacsu))
+- Bump next from 11.1.0 to 11.1.1 in /wallet-web [\#758](https://github.com/nymtech/nym/pull/758) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Add block\_height in the Delegation structure as well [\#757](https://github.com/nymtech/nym/pull/757) ([neacsu](https://github.com/neacsu))
+- Feature/add blockstamp [\#756](https://github.com/nymtech/nym/pull/756) ([neacsu](https://github.com/neacsu))
+- NetworkMonitorBuilder - starting the monitor after rocket has launched [\#754](https://github.com/nymtech/nym/pull/754) ([jstuczyn](https://github.com/jstuczyn))
+- Enabled validators api argument [\#753](https://github.com/nymtech/nym/pull/753) ([jstuczyn](https://github.com/jstuczyn))
+- Correctly bounding nominator of uptime calculation [\#752](https://github.com/nymtech/nym/pull/752) ([jstuczyn](https://github.com/jstuczyn))
+- Fixed argument parsing for ipv6 'good' topology [\#751](https://github.com/nymtech/nym/pull/751) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/rust rewarding [\#750](https://github.com/nymtech/nym/pull/750) ([jstuczyn](https://github.com/jstuczyn))
+- Revert "Migration commit, will be reverted after the testnet contract… [\#749](https://github.com/nymtech/nym/pull/749) ([neacsu](https://github.com/neacsu))
+- Feature/get own delegations [\#748](https://github.com/nymtech/nym/pull/748) ([neacsu](https://github.com/neacsu))
+- Feature/more reliable uptime calculation [\#747](https://github.com/nymtech/nym/pull/747) ([jstuczyn](https://github.com/jstuczyn))
+- Update template toml key [\#746](https://github.com/nymtech/nym/pull/746) ([neacsu](https://github.com/neacsu))
+- Feature/cred after handshake [\#745](https://github.com/nymtech/nym/pull/745) ([neacsu](https://github.com/neacsu))
+- Reinstate the POST method blind\_sign [\#744](https://github.com/nymtech/nym/pull/744) ([neacsu](https://github.com/neacsu))
+- explorer-api: add pending field to port check response [\#742](https://github.com/nymtech/nym/pull/742) ([mmsinclair](https://github.com/mmsinclair))
+- Feature/use delegation rates [\#741](https://github.com/nymtech/nym/pull/741) ([neacsu](https://github.com/neacsu))
+- Feature/copy to clipboard [\#740](https://github.com/nymtech/nym/pull/740) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/update wallet with stake rates [\#739](https://github.com/nymtech/nym/pull/739) ([neacsu](https://github.com/neacsu))
+- Add stake reward rates and bump version of client [\#738](https://github.com/nymtech/nym/pull/738) ([neacsu](https://github.com/neacsu))
+- Bump next from 10.1.3 to 11.1.0 in /wallet-web [\#737](https://github.com/nymtech/nym/pull/737) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Feature/nymd client integration [\#736](https://github.com/nymtech/nym/pull/736) ([jstuczyn](https://github.com/jstuczyn))
+- Bug/fix parking lot on wasm [\#735](https://github.com/nymtech/nym/pull/735) ([neacsu](https://github.com/neacsu))
+- Explorer API: add new HTTP resource to decorate mix nodes with geoip locations [\#734](https://github.com/nymtech/nym/pull/734) ([mmsinclair](https://github.com/mmsinclair))
+- Feature/completing nymd client api [\#732](https://github.com/nymtech/nym/pull/732) ([jstuczyn](https://github.com/jstuczyn))
+- Explorer API - add port check and node description/stats proxy [\#731](https://github.com/nymtech/nym/pull/731) ([mmsinclair](https://github.com/mmsinclair))
+- Feature/nymd client fee handling [\#730](https://github.com/nymtech/nym/pull/730) ([jstuczyn](https://github.com/jstuczyn))
+- Update DelegationCheck.tsx [\#725](https://github.com/nymtech/nym/pull/725) ([jessgess](https://github.com/jessgess))
+- Rust nymd/cosmwasm client [\#724](https://github.com/nymtech/nym/pull/724) ([jstuczyn](https://github.com/jstuczyn))
+- Removed wasm feature bypassing cyclic dependencies [\#723](https://github.com/nymtech/nym/pull/723) ([jstuczyn](https://github.com/jstuczyn))
+- Updated used sphinx dependency to the most recent revision [\#722](https://github.com/nymtech/nym/pull/722) ([jstuczyn](https://github.com/jstuczyn))
+- update state management and validation [\#721](https://github.com/nymtech/nym/pull/721) ([fmtabbara](https://github.com/fmtabbara))
+- Add Network Explorer API [\#720](https://github.com/nymtech/nym/pull/720) ([futurechimp](https://github.com/futurechimp))
+- Feature/superbuild [\#719](https://github.com/nymtech/nym/pull/719) ([jstuczyn](https://github.com/jstuczyn))
+- remove console log [\#718](https://github.com/nymtech/nym/pull/718) ([fmtabbara](https://github.com/fmtabbara))
+- Bug/form validation [\#715](https://github.com/nymtech/nym/pull/715) ([fmtabbara](https://github.com/fmtabbara))
+- Warnings with identities of good nodes failing checks [\#714](https://github.com/nymtech/nym/pull/714) ([jstuczyn](https://github.com/jstuczyn))
+- Removed all sphinx key caching from mixnodes and gateways [\#713](https://github.com/nymtech/nym/pull/713) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/receive coins page + UI tweaks [\#704](https://github.com/nymtech/nym/pull/704) ([fmtabbara](https://github.com/fmtabbara))
+- Allow users to sign out [\#703](https://github.com/nymtech/nym/pull/703) ([fmtabbara](https://github.com/fmtabbara))
+- Feature/docker improvements [\#702](https://github.com/nymtech/nym/pull/702) ([neacsu](https://github.com/neacsu))
+- Exposed API port on the validator [\#701](https://github.com/nymtech/nym/pull/701) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/default values [\#700](https://github.com/nymtech/nym/pull/700) ([neacsu](https://github.com/neacsu))
+- Cleaned up dependencies of our typescript client [\#699](https://github.com/nymtech/nym/pull/699) ([jstuczyn](https://github.com/jstuczyn))
+- Bond and delegation alerts [\#698](https://github.com/nymtech/nym/pull/698) ([fmtabbara](https://github.com/fmtabbara))
+- Bugfix/network monitor version check [\#697](https://github.com/nymtech/nym/pull/697) ([jstuczyn](https://github.com/jstuczyn))
+- Feature/other containers [\#692](https://github.com/nymtech/nym/pull/692) ([neacsu](https://github.com/neacsu))
+- Using validator API instead of nymd [\#690](https://github.com/nymtech/nym/pull/690) ([futurechimp](https://github.com/futurechimp))
+- Hang coconut issuance off the validator-api [\#679](https://github.com/nymtech/nym/pull/679) ([durch](https://github.com/durch))
+- Update hmac and blake3 [\#673](https://github.com/nymtech/nym/pull/673) ([durch](https://github.com/durch))
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

Cargo.toml

@@ -1,39 +1,68 @@
-[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"
+# Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+# SPDX-License-Identifier: Apache-2.0
 
-[lib]
-name = "nym_client"
-path = "src/lib.rs"
+[profile.release]
+panic = "abort"
+opt-level = "s"
+overflow-checks = true
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+[profile.dev]
+panic = "abort"
 
-[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"
+[workspace]
 
-# 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" }
+members = [
+    "clients/client-core",
+    "clients/native",
+    "clients/native/websocket-requests",
+    "clients/socks5",
+    "clients/tauri-client/src-tauri",
+    "clients/webassembly",
+    "common/client-libs/gateway-client",
+    "common/client-libs/mixnet-client",
+    "common/client-libs/validator-client",
+    "common/coconut-interface",
+    "common/config",
+    "common/credentials",
+    "common/crypto",
+    "common/bandwidth-claim-contract",
+    "common/mixnet-contract",
+    "common/mixnode-common",
+    "common/network-defaults",
+    "common/nonexhaustive-delayqueue",
+    "common/nymcoconut",
+    "common/nymsphinx",
+    "common/nymsphinx/acknowledgements",
+    "common/nymsphinx/addressing",
+    "common/nymsphinx/anonymous-replies",
+    "common/nymsphinx/chunking",
+    "common/nymsphinx/cover",
+    "common/nymsphinx/forwarding",
+    "common/nymsphinx/framing",
+    "common/nymsphinx/params",
+    "common/nymsphinx/types",
+    "common/pemstore",
+    "common/socks5/proxy-helpers",
+    "common/socks5/requests",
+    "common/topology",
+    "common/wasm-utils",
+    "explorer-api",
+    "gateway",
+    "gateway/gateway-requests",
+    "mixnode",
+    "service-providers/network-requester",
+    "validator-api",
+]
 
-[build-dependencies]
-built = "0.3.2"
+default-members = [
+    "clients/native",
+    "clients/socks5",
+#    "clients/webassembly",
+    "gateway",
+    "service-providers/network-requester",
+    "mixnode",
+    "validator-api",
+    "explorer-api",
+]
 
-[dev-dependencies]
-mockito = "0.22.0"
+exclude = ["explorer", "contracts", "tokenomics-py"]

LICENSES/Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

LICENSES/CC0-1.0.txt

@@ -0,0 +1,36 @@
+
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights.
+
+    1. Copyright and Related Rights. A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following:
+        i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work;
+        ii. moral rights retained by the original author(s) and/or performer(s);
+        iii. publicity and privacy rights pertaining to a person's image or likeness depicted in a Work;
+        iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below;
+        v. rights protecting the extraction, dissemination, use and reuse of data in a Work;
+        vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and
+        vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof.
+    2. Waiver. To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose.
+    3. Public License Fallback. Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose.
+    4. Limitations and Disclaimers.
+        a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document.
+        b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law.
+        c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work.
+        d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work.
+
+Standard License Header
+
+There is no standard license header for the license
+
+

LICENSES/MIT.txt

@@ -0,0 +1,14 @@
+
+MIT License
+
+Copyright (c) <year> <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Standard License Header
+
+There is no standard license header for the license
+

Makefile

@@ -0,0 +1,45 @@
+all: clippy-all test fmt
+happy: clippy-happy test fmt
+clippy-all: clippy-all-main clippy-all-contracts clippy-all-wallet
+clippy-happy: clippy-happy-main clippy-happy-contracts clippy-happy-wallet
+test: test-main test-contracts test-wallet
+fmt: fmt-main fmt-contracts fmt-wallet
+
+clippy-happy-main:
+	cargo clippy
+
+clippy-happy-contracts:
+	cargo clippy --manifest-path contracts/Cargo.toml --target wasm32-unknown-unknown
+
+clippy-happy-wallet: 
+	cargo clippy --manifest-path nym-wallet/Cargo.toml
+
+clippy-all-main:
+	cargo clippy --all-features -- -D warnings 
+
+clippy-all-contracts:
+	cargo clippy --manifest-path contracts/Cargo.toml --all-features --target wasm32-unknown-unknown -- -D warnings
+
+clippy-all-wallet: 
+	cargo clippy --manifest-path nym-wallet/Cargo.toml --all-features -- -D warnings
+
+test-main:
+	cargo test --all-features
+
+test-contracts:
+	cargo test --manifest-path contracts/Cargo.toml --all-features
+
+test-wallet:
+	cargo test --manifest-path nym-wallet/Cargo.toml --all-features
+
+fmt-main:
+	cargo fmt --all
+
+fmt-contracts:
+	cargo fmt --manifest-path contracts/Cargo.toml --all
+
+fmt-wallet:
+	cargo fmt --manifest-path nym-wallet/Cargo.toml --all
+
+wasm:
+	RUSTFLAGS='-C link-arg=-s' cargo build --manifest-path contracts/Cargo.toml --release --target wasm32-unknown-unknown

README.md

@@ -1,10 +1,76 @@
-# Nym Client
+<!--
+Copyright 2020 - Nym Technologies SA <contact@nymtech.net>
+SPDX-License-Identifier: Apache-2.0
+-->
 
-The Nym Client communicates with the remote, decentralised nodes which make up the Nym system as a whole. 
+## The Nym Privacy Platform
 
-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
+* nym-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.
+* nym-socks5-client - a Socks5 proxy you can run on your machine, and use with existing applications
+* nym-gateway - acts sort of like a mailbox for mixnet messages, removing the need for directly delivery to potentially offline or firewalled devices.
+* nym-network-monitor - sends packets through the full system to check that they are working as expected, and stores node uptime histories as the basis of a rewards system ("mixmining" or "proof-of-mixing").
+* nym-explorer - a (projected) block explorer and (existing) mixnet viewer.
+* nym-wallet - a desktop wallet implemented using the [Tauri](https://tauri.studio/en/docs/about/intro) framework. 
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0)
+[![Build Status](https://img.shields.io/github/workflow/status/nymtech/nym/Continuous%20integration/develop?style=for-the-badge&logo=github-actions)](https://github.com/nymtech/nym/actions?query=branch%3Adevelop)
+
+
+### Building
+
+Platform build instructions are available on [our docs site](https://nymtech.net/docs/0.11.0/overview/index/).
+
+### 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.
+
+### Developer chat
+
+You can chat to us in [Keybase](https://keybase.io). Download their chat app, then click **Teams -> Join a team**. Type **nymtech.friends** into the team name and hit **continue**. For general chat, hang out in the **#general** channel. Our development takes places in the **#dev** channel. Node operators should be in the **#node-operators** channel.
+
+### Rewards
+
+Node, node operator and delegator rewards are determined according to the principles laid out in the section 6 of [Nym Whitepaper](https://nymtech.net/nym-whitepaper.pdf). Below is a TLDR of the variables and formulas involved in calculating the epoch rewards. Initial reward pool is set to 250 million Nym, making the circulating supply 750 million Nym.
+
+|Symbol|Definition|
+|---|---|
+|<img src="https://render.githubusercontent.com/render/math?math=R">|global share of rewards available, starts at 2% of the reward pool. 
+|<img src="https://render.githubusercontent.com/render/math?math=R_{i}">|node reward for mixnode `i`.
+|<img src="https://render.githubusercontent.com/render/math?math=\sigma_{i}">|ratio of total node stake (node bond + all delegations) to the token circulating supply.
+|<img src="https://render.githubusercontent.com/render/math?math=\lambda_{i}">|ratio of stake operator has pledged to their node to the token circulating supply.
+|<img src="https://render.githubusercontent.com/render/math?math=\omega_{i}">|fraction of total effort undertaken by node `i`, set to `1/k`.
+|<img src="https://render.githubusercontent.com/render/math?math=k">|number of nodes stakeholders are incentivised to create, set by the validators, a matter of governance. Currently determined by the `reward set` size, and set to 720 in testnet Sandbox.
+|<img src="https://render.githubusercontent.com/render/math?math=\alpha">|Sybil attack resistance parameter - the higher this parameter is set the stronger the reduction in competitivness gets for a Sybil attacker.
+|<img src="https://render.githubusercontent.com/render/math?math=PM_{i}">|declared profit margin of operator `i`, defaults to 10% in.
+|<img src="https://render.githubusercontent.com/render/math?math=PF_{i}">|uptime of node `i`, scaled to 0 - 1, for the rewarding epoch
+|<img src="https://render.githubusercontent.com/render/math?math=PP_{i}">|cost of operating node `i` for the duration of the rewarding eopoch, set to 40 NYMT.
+
+Node reward for node `i` is determined as:
+
+<img src="https://render.githubusercontent.com/render/math?math=R_{i}=PF_{i} \cdot R \cdot (\sigma^'_{i} \cdot \omega_{i} \cdot k %2b \alpha \cdot \lambda^'_{i} \cdot \sigma^'_{i} \cdot k)/(1 %2b \alpha)">
+
+where:
+
+<img src="https://render.githubusercontent.com/render/math?math=\sigma^'_{i} = min\{\sigma_{i}, 1/k\}">
+
+and
+
+<img src="https://render.githubusercontent.com/render/math?math=\lambda^'_{i} = min\{\lambda_{i}, 1/k\}">
+
+Operator of node `i` is credited with the following amount:
+
+<img src="https://render.githubusercontent.com/render/math?math=min\{PP_{i},R_{i})\} %2b max\{0, (PM_{i} %2b (1 - PM_{i}) \cdot \lambda_{i}/\delta_{i}) \cdot (R_{i} - PP_{i})\}">
+
+Delegate with stake `s` recieves:
+
+<img src="https://render.githubusercontent.com/render/math?math=max\{0, (1-PM_{i}) \cdot (s^'/\sigma_{i}) \cdot (R_{i} - PP_{i})\}">
+
+where `s'` is stake `s` scaled over total token circulating supply.
+
+### Licensing and copyright information
+
+This program is available as open source under the terms of the Apache 2.0 license. However, some elements are being licensed under CC0-1.0 and MIT. For accurate information, please check individual files.
 

build.rs

@@ -1,5 +0,0 @@
-use built;
-
-fn main() {
-    built::write_built_file().expect("Failed to acquire build-time information");
-}

clients/client-core/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "client-core"
+version = "0.12.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]
+dirs = "3.0"
+futures = "0.3"
+humantime-serde = "1.0"
+log = "0.4"
+rand = { version = "0.7.3", features = ["wasm-bindgen"] }
+serde = { version = "1.0", features = ["derive"] }
+sled = "0.34"
+tokio = { version = "1.4", features = ["macros"] }
+url = { version ="2.2", features = ["serde"] }
+
+# internal
+config = { path = "../../common/config" }
+crypto = { path = "../../common/crypto" }
+gateway-client = { path = "../../common/client-libs/gateway-client" }
+gateway-requests = { path = "../../gateway/gateway-requests" }
+nonexhaustive-delayqueue = { path = "../../common/nonexhaustive-delayqueue" }
+nymsphinx = { path = "../../common/nymsphinx" }
+pemstore = { path = "../../common/pemstore" }
+topology = { path = "../../common/topology" }
+validator-client = { path = "../../common/client-libs/validator-client" }
+
+[dev-dependencies]
+tempfile = "3.1.0"
+
+[features]
+coconut = []

clients/client-core/src/client/cover_traffic_stream.rs

@@ -0,0 +1,172 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::mix_traffic::BatchMixMessageSender;
+use crate::client::topology_control::TopologyAccessor;
+use futures::task::{Context, Poll};
+use futures::{Future, Stream, StreamExt};
+use log::*;
+use nymsphinx::acknowledgements::AckKey;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::cover::generate_loop_cover_packet;
+use nymsphinx::utils::sample_poisson_duration;
+use rand::{rngs::OsRng, CryptoRng, Rng};
+use std::pin::Pin;
+use std::sync::Arc;
+use tokio::task::JoinHandle;
+use tokio::time;
+
+pub struct LoopCoverTrafficStream<R>
+where
+    R: CryptoRng + Rng,
+{
+    /// Key used to encrypt and decrypt content of an ACK packet.
+    ack_key: Arc<AckKey>,
+
+    /// Average delay an acknowledgement packet is going to get delay at a single mixnode.
+    average_ack_delay: time::Duration,
+
+    /// Average delay a data packet is going to get delay at a single mixnode.
+    average_packet_delay: time::Duration,
+
+    /// Average delay between sending subsequent cover packets.
+    average_cover_message_sending_delay: time::Duration,
+
+    /// Internal state, determined by `average_message_sending_delay`,
+    /// used to keep track of when a next packet should be sent out.
+    next_delay: Pin<Box<time::Sleep>>,
+
+    /// Channel used for sending prepared sphinx packets to `MixTrafficController` that sends them
+    /// out to the network without any further delays.
+    mix_tx: BatchMixMessageSender,
+
+    /// Represents full address of this client.
+    our_full_destination: Recipient,
+
+    /// Instance of a cryptographically secure random number generator.
+    rng: R,
+
+    /// Accessor to the common instance of network topology.
+    topology_access: TopologyAccessor,
+}
+
+impl<R> Stream for LoopCoverTrafficStream<R>
+where
+    R: CryptoRng + Rng + Unpin,
+{
+    // Item is only used to indicate we should create a new message rather than actual cover message
+    // reason being to not introduce unnecessary complexity by having to keep state of topology
+    // mutex when trying to acquire it. So right now the Stream trait serves as a glorified timer.
+    // Perhaps this should be changed in the future.
+    type Item = ();
+
+    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 self.next_delay.as_mut().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 avg_delay = self.average_cover_message_sending_delay;
+        let now = self.next_delay.deadline();
+        let next_poisson_delay = sample_poisson_duration(&mut self.rng, avg_delay);
+
+        // The next interval value is `next_poisson_delay` after the one that just
+        // yielded.
+        let next = now + next_poisson_delay;
+        self.next_delay.as_mut().reset(next);
+
+        Poll::Ready(Some(()))
+    }
+}
+
+// obviously when we finally make shared rng that is on 'higher' level, this should become
+// generic `R`
+impl LoopCoverTrafficStream<OsRng> {
+    pub fn new(
+        ack_key: Arc<AckKey>,
+        average_ack_delay: time::Duration,
+        average_packet_delay: time::Duration,
+        average_cover_message_sending_delay: time::Duration,
+        mix_tx: BatchMixMessageSender,
+        our_full_destination: Recipient,
+        topology_access: TopologyAccessor,
+    ) -> Self {
+        let rng = OsRng;
+
+        LoopCoverTrafficStream {
+            ack_key,
+            average_ack_delay,
+            average_packet_delay,
+            average_cover_message_sending_delay,
+            next_delay: Box::pin(time::sleep(Default::default())),
+            mix_tx,
+            our_full_destination,
+            rng,
+            topology_access,
+        }
+    }
+
+    async fn on_new_message(&mut self) {
+        trace!("next cover message!");
+
+        // TODO for way down the line: in very rare cases (during topology update) we might have
+        // to wait a really tiny bit before actually obtaining the permit hence messing with our
+        // poisson delay, but is it really a problem?
+        let topology_permit = self.topology_access.get_read_permit().await;
+        // the ack is sent back to ourselves (and then ignored)
+        let topology_ref_option = topology_permit.try_get_valid_topology_ref(
+            &self.our_full_destination,
+            Some(&self.our_full_destination),
+        );
+        if topology_ref_option.is_none() {
+            warn!("No valid topology detected - won't send any loop cover message this time");
+            return;
+        }
+        let topology_ref = topology_ref_option.unwrap();
+
+        let cover_message = generate_loop_cover_packet(
+            &mut self.rng,
+            topology_ref,
+            &*self.ack_key,
+            &self.our_full_destination,
+            self.average_ack_delay,
+            self.average_packet_delay,
+        )
+        .expect("Somehow failed to generate a loop cover message with a valid topology");
+
+        // 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(vec![cover_message]).unwrap();
+
+        // TODO: I'm not entirely sure whether this is really required, because I'm not 100%
+        // sure how `yield_now()` works - whether it just notifies the scheduler or whether it
+        // properly blocks. So to play it on the safe side, just explicitly drop the read permit
+        drop(topology_permit);
+
+        // JS: due to identical logical structure to OutQueueControl::on_message(), this is also
+        // presumably required to prevent bugs in the future. Exact reason is still unknown to me.
+        tokio::task::yield_now().await;
+    }
+
+    async fn run(&mut self) {
+        // we should set initial delay only when we actually start the stream
+        self.next_delay = Box::pin(time::sleep(sample_poisson_duration(
+            &mut self.rng,
+            self.average_cover_message_sending_delay,
+        )));
+
+        while self.next().await.is_some() {
+            self.on_new_message().await;
+        }
+    }
+
+    pub fn start(mut self) -> JoinHandle<()> {
+        tokio::spawn(async move {
+            self.run().await;
+        })
+    }
+}

clients/client-core/src/client/inbound_messages.rs

@@ -0,0 +1,33 @@
+use futures::channel::mpsc;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::anonymous_replies::ReplySurb;
+
+pub type InputMessageSender = mpsc::UnboundedSender<InputMessage>;
+pub type InputMessageReceiver = mpsc::UnboundedReceiver<InputMessage>;
+
+#[derive(Debug)]
+pub enum InputMessage {
+    Fresh {
+        recipient: Recipient,
+        data: Vec<u8>,
+        with_reply_surb: bool,
+    },
+    Reply {
+        reply_surb: ReplySurb,
+        data: Vec<u8>,
+    },
+}
+
+impl InputMessage {
+    pub fn new_fresh(recipient: Recipient, data: Vec<u8>, with_reply_surb: bool) -> Self {
+        InputMessage::Fresh {
+            recipient,
+            data,
+            with_reply_surb,
+        }
+    }
+
+    pub fn new_reply(reply_surb: ReplySurb, data: Vec<u8>) -> Self {
+        InputMessage::Reply { reply_surb, data }
+    }
+}

clients/client-core/src/client/key_manager.rs

@@ -0,0 +1,156 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::config::persistence::key_pathfinder::ClientKeyPathfinder;
+use crypto::asymmetric::{encryption, identity};
+use gateway_requests::registration::handshake::SharedKeys;
+use log::*;
+use nymsphinx::acknowledgements::AckKey;
+use rand::{CryptoRng, RngCore};
+use std::io;
+use std::sync::Arc;
+
+// Note: to support key rotation in the future, all keys will require adding an extra smart pointer,
+// most likely an AtomicCell, or if it doesn't work as I think it does, a Mutex. Although I think
+// AtomicCell includes a Mutex implicitly if the underlying type does not work atomically.
+// And I guess there will need to be some mechanism for a grace period when you can still
+// use the old key after new one was issued.
+
+// Remember that Arc<T> has Deref implementation for T
+pub struct KeyManager {
+    /// identity key associated with the client instance.
+    identity_keypair: Arc<identity::KeyPair>,
+
+    /// encryption key associated with the client instance.
+    encryption_keypair: Arc<encryption::KeyPair>,
+
+    /// shared key derived with the gateway during "registration handshake"
+    gateway_shared_key: Option<Arc<SharedKeys>>,
+
+    /// key used for producing and processing acknowledgement packets.
+    ack_key: Arc<AckKey>,
+}
+
+// The expected flow of a KeyManager "lifetime" is as follows:
+/*
+   1. ::new() is called during client-init
+   2. after gateway registration is completed [in init] ::insert_gateway_shared_key() is called
+   3. ::store_keys() is called before init finishes execution.
+   4. ::load_keys() is called at the beginning of each subsequent client-run
+   5. [not implemented] ::rotate_keys() is called periodically during client-run I presume?
+*/
+
+impl KeyManager {
+    // this is actually **NOT** dead code
+    // I have absolutely no idea why the compiler insists it's unused. The call happens during client::init::execute
+    #[allow(dead_code)]
+    /// Creates new instance of a [`KeyManager`]
+    pub fn new<R>(rng: &mut R) -> Self
+    where
+        R: RngCore + CryptoRng,
+    {
+        KeyManager {
+            identity_keypair: Arc::new(identity::KeyPair::new(rng)),
+            encryption_keypair: Arc::new(encryption::KeyPair::new(rng)),
+            gateway_shared_key: None,
+            ack_key: Arc::new(AckKey::new(rng)),
+        }
+    }
+
+    // this is actually **NOT** dead code
+    // I have absolutely no idea why the compiler insists it's unused. The call happens during client::init::execute
+    #[allow(dead_code)]
+    /// After shared key with the gateway is derived, puts its ownership to this instance of a [`KeyManager`].
+    pub fn insert_gateway_shared_key(&mut self, gateway_shared_key: Arc<SharedKeys>) {
+        self.gateway_shared_key = Some(gateway_shared_key)
+    }
+
+    /// Loads previously stored keys from the disk.
+    pub fn load_keys(client_pathfinder: &ClientKeyPathfinder) -> io::Result<Self> {
+        let identity_keypair: identity::KeyPair =
+            pemstore::load_keypair(&pemstore::KeyPairPath::new(
+                client_pathfinder.private_identity_key().to_owned(),
+                client_pathfinder.public_identity_key().to_owned(),
+            ))?;
+        let encryption_keypair: encryption::KeyPair =
+            pemstore::load_keypair(&pemstore::KeyPairPath::new(
+                client_pathfinder.private_encryption_key().to_owned(),
+                client_pathfinder.public_encryption_key().to_owned(),
+            ))?;
+
+        let gateway_shared_key: SharedKeys =
+            pemstore::load_key(&client_pathfinder.gateway_shared_key().to_owned())?;
+
+        let ack_key: AckKey = pemstore::load_key(&client_pathfinder.ack_key().to_owned())?;
+
+        // TODO: ack key is never stored so it is generated now. But perhaps it should be stored
+        // after all for consistency sake?
+        Ok(KeyManager {
+            identity_keypair: Arc::new(identity_keypair),
+            encryption_keypair: Arc::new(encryption_keypair),
+            gateway_shared_key: Some(Arc::new(gateway_shared_key)),
+            ack_key: Arc::new(ack_key),
+        })
+    }
+
+    // this is actually **NOT** dead code
+    // I have absolutely no idea why the compiler insists it's unused. The call happens during client::init::execute
+    #[allow(dead_code)]
+    /// Stores all available keys on the disk.
+    // While perhaps there is no much point in storing the `AckKey` on the disk,
+    // it is done so for the consistency sake so that you wouldn't require an rng instance
+    // during `load_keys` to generate the said key.
+    pub fn store_keys(&self, client_pathfinder: &ClientKeyPathfinder) -> io::Result<()> {
+        pemstore::store_keypair(
+            self.identity_keypair.as_ref(),
+            &pemstore::KeyPairPath::new(
+                client_pathfinder.private_identity_key().to_owned(),
+                client_pathfinder.public_identity_key().to_owned(),
+            ),
+        )?;
+        pemstore::store_keypair(
+            self.encryption_keypair.as_ref(),
+            &pemstore::KeyPairPath::new(
+                client_pathfinder.private_encryption_key().to_owned(),
+                client_pathfinder.public_encryption_key().to_owned(),
+            ),
+        )?;
+
+        pemstore::store_key(self.ack_key.as_ref(), client_pathfinder.ack_key())?;
+
+        match self.gateway_shared_key.as_ref() {
+            None => warn!("No gateway shared key available to store!"),
+            Some(gate_key) => {
+                pemstore::store_key(gate_key.as_ref(), client_pathfinder.gateway_shared_key())?
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Gets an atomically reference counted pointer to [`identity::KeyPair`].
+    pub fn identity_keypair(&self) -> Arc<identity::KeyPair> {
+        Arc::clone(&self.identity_keypair)
+    }
+
+    /// Gets an atomically reference counted pointer to [`encryption::KeyPair`].
+    pub fn encryption_keypair(&self) -> Arc<encryption::KeyPair> {
+        Arc::clone(&self.encryption_keypair)
+    }
+
+    /// Gets an atomically reference counted pointer to [`SharedKey`].
+    // since this function is not fully public, it is not expected to be used externally and
+    // hence it's up to us to ensure it's called in correct context
+    pub fn gateway_shared_key(&self) -> Arc<SharedKeys> {
+        Arc::clone(
+            self.gateway_shared_key
+                .as_ref()
+                .expect("tried to unwrap empty gateway key!"),
+        )
+    }
+
+    /// Gets an atomically reference counted pointer to [`AckKey`].
+    pub fn ack_key(&self) -> Arc<AckKey> {
+        Arc::clone(&self.ack_key)
+    }
+}

clients/client-core/src/client/mix_traffic.rs

@@ -0,0 +1,79 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use futures::channel::mpsc;
+use futures::StreamExt;
+use gateway_client::GatewayClient;
+use log::*;
+use nymsphinx::forwarding::packet::MixPacket;
+use tokio::task::JoinHandle;
+
+pub type BatchMixMessageSender = mpsc::UnboundedSender<Vec<MixPacket>>;
+pub type BatchMixMessageReceiver = mpsc::UnboundedReceiver<Vec<MixPacket>>;
+
+const MAX_FAILURE_COUNT: usize = 100;
+
+pub struct MixTrafficController {
+    // TODO: most likely to be replaced by some higher level construct as
+    // later on gateway_client will need to be accessible by other entities
+    gateway_client: GatewayClient,
+    mix_rx: BatchMixMessageReceiver,
+
+    // TODO: this is temporary work-around.
+    // in long run `gateway_client` will be moved away from `MixTrafficController` anyway.
+    consecutive_gateway_failure_count: usize,
+}
+
+impl MixTrafficController {
+    pub fn new(
+        mix_rx: BatchMixMessageReceiver,
+        gateway_client: GatewayClient,
+    ) -> MixTrafficController {
+        MixTrafficController {
+            gateway_client,
+            mix_rx,
+            consecutive_gateway_failure_count: 0,
+        }
+    }
+
+    async fn on_messages(&mut self, mut mix_packets: Vec<MixPacket>) {
+        debug_assert!(!mix_packets.is_empty());
+
+        let result = if mix_packets.len() == 1 {
+            let mix_packet = mix_packets.pop().unwrap();
+            self.gateway_client.send_mix_packet(mix_packet).await
+        } else {
+            self.gateway_client
+                .batch_send_mix_packets(mix_packets)
+                .await
+        };
+
+        match result {
+            Err(e) => {
+                error!("Failed to send sphinx packet(s) to the gateway! - {:?}", e);
+                self.consecutive_gateway_failure_count += 1;
+                if self.consecutive_gateway_failure_count == MAX_FAILURE_COUNT {
+                    // todo: in the future this should initiate a 'graceful' shutdown or try
+                    // to reconnect?
+                    panic!("failed to send sphinx packet to the gateway {} times in a row - assuming the gateway is dead. Can't do anything about it yet :(", MAX_FAILURE_COUNT)
+                }
+            }
+            Ok(_) => {
+                trace!("We *might* have managed to forward sphinx packet(s) to the gateway!");
+                self.consecutive_gateway_failure_count = 0;
+            }
+        }
+    }
+
+    pub async fn run(&mut self) {
+        while let Some(mix_packets) = self.mix_rx.next().await {
+            self.on_messages(mix_packets).await;
+        }
+    }
+
+    pub fn start(mut self) -> JoinHandle<()> {
+        tokio::spawn(async move {
+            self.run().await;
+        })
+    }
+}

clients/client-core/src/client/mod.rs

@@ -0,0 +1,8 @@
+pub mod cover_traffic_stream;
+pub mod inbound_messages;
+pub mod key_manager;
+pub mod mix_traffic;
+pub mod real_messages_control;
+pub mod received_buffer;
+pub mod reply_key_storage;
+pub mod topology_control;

clients/client-core/src/client/real_messages_control/acknowledgement_control/acknowledgement_listener.rs

@@ -0,0 +1,76 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::action_controller::{Action, ActionSender};
+use futures::StreamExt;
+use gateway_client::AcknowledgementReceiver;
+use log::*;
+use nymsphinx::{
+    acknowledgements::{identifier::recover_identifier, AckKey},
+    chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID},
+};
+use std::sync::Arc;
+
+/// Module responsible for listening for any data resembling acknowledgements from the network
+/// and firing actions to remove them from the 'Pending' state.
+pub(super) struct AcknowledgementListener {
+    ack_key: Arc<AckKey>,
+    ack_receiver: AcknowledgementReceiver,
+    action_sender: ActionSender,
+}
+
+impl AcknowledgementListener {
+    pub(super) fn new(
+        ack_key: Arc<AckKey>,
+        ack_receiver: AcknowledgementReceiver,
+        action_sender: ActionSender,
+    ) -> Self {
+        AcknowledgementListener {
+            ack_key,
+            ack_receiver,
+            action_sender,
+        }
+    }
+
+    async fn on_ack(&mut self, ack_content: Vec<u8>) {
+        debug!("Received an ack");
+        let frag_id = match recover_identifier(&self.ack_key, &ack_content)
+            .map(FragmentIdentifier::try_from_bytes)
+        {
+            Some(Ok(frag_id)) => frag_id,
+            _ => {
+                warn!("Received invalid ACK!"); // should we do anything else about that?
+                return;
+            }
+        };
+
+        // if we received an ack for cover message or a reply there will be nothing to remove,
+        // because nothing was inserted in the first place
+        if frag_id == COVER_FRAG_ID {
+            trace!("Received an ack for a cover message - no need to do anything");
+            return;
+        } else if frag_id.is_reply() {
+            info!("Received an ack for a reply message - no need to do anything! (don't know what to do!)");
+            // TODO: probably there will need to be some extra procedure here, something to notify
+            // user that his reply reached the recipient (since we got an ack)
+            return;
+        }
+
+        trace!("Received {} from the mix network", frag_id);
+
+        self.action_sender
+            .unbounded_send(Action::new_remove(frag_id))
+            .unwrap();
+    }
+
+    pub(super) async fn run(&mut self) {
+        debug!("Started AcknowledgementListener");
+        while let Some(acks) = self.ack_receiver.next().await {
+            // realistically we would only be getting one ack at the time
+            for ack in acks {
+                self.on_ack(ack).await;
+            }
+        }
+        error!("TODO: error msg. Or maybe panic?")
+    }
+}

clients/client-core/src/client/real_messages_control/acknowledgement_control/action_controller.rs

@@ -0,0 +1,264 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::PendingAcknowledgement;
+use crate::client::real_messages_control::acknowledgement_control::RetransmissionRequestSender;
+use futures::channel::mpsc::{self, UnboundedReceiver, UnboundedSender};
+use futures::StreamExt;
+use log::*;
+use nonexhaustive_delayqueue::{Expired, NonExhaustiveDelayQueue, QueueKey, TimerError};
+use nymsphinx::chunking::fragment::FragmentIdentifier;
+use nymsphinx::Delay as SphinxDelay;
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+pub(crate) type ActionSender = UnboundedSender<Action>;
+
+// The actual data being sent off as well as potential key to the delay queue
+type PendingAckEntry = (Arc<PendingAcknowledgement>, Option<QueueKey>);
+
+// we can either:
+// - have a completely new set of packets we just sent and need to create entries for
+// - received an ack so we want to remove an entry
+// - start a retransmission timer for sending the packet into the network (on either first try or retransmission)
+// - update the internal sphinx delay of an expired packet
+pub(crate) enum Action {
+    /// Inserts new `PendingAcknowledgement`s into the 'shared' state.
+    /// Initiated by `InputMessageListener`
+    InsertPending(Vec<PendingAcknowledgement>),
+
+    /// Removes given `PendingAcknowledgement` from the 'shared' state. Also cancels the retransmission timer.
+    /// Initiated by `AcknowledgementListener`
+    RemovePending(FragmentIdentifier),
+
+    /// Starts the retransmission timer on given `PendingAcknowledgement` with the `Duration` based on
+    /// its internal data.
+    /// Initiated by `SentNotificationListener`
+    /// Can also be initiated by `RetransmissionRequestListener` in the rare cases of invalid Topology.
+    StartTimer(FragmentIdentifier),
+
+    /// Updates the expected delay of given `PendingAcknowledgement` with the new provided `SphinxDelay`.
+    /// Initiated by `RetransmissionRequestListener`
+    UpdateDelay(FragmentIdentifier, SphinxDelay),
+}
+
+impl Action {
+    pub(crate) fn new_insert(pending_acks: Vec<PendingAcknowledgement>) -> Self {
+        Action::InsertPending(pending_acks)
+    }
+
+    pub(crate) fn new_remove(frag_id: FragmentIdentifier) -> Self {
+        Action::RemovePending(frag_id)
+    }
+
+    pub(crate) fn new_start_timer(frag_id: FragmentIdentifier) -> Self {
+        Action::StartTimer(frag_id)
+    }
+
+    pub(crate) fn new_update_delay(frag_id: FragmentIdentifier, delay: SphinxDelay) -> Self {
+        Action::UpdateDelay(frag_id, delay)
+    }
+}
+
+/// Configurable parameters of the `ActionController`
+pub(super) struct Config {
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the additive part `b`
+    ack_wait_addition: Duration,
+
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the multiplier `a`
+    ack_wait_multiplier: f64,
+}
+
+impl Config {
+    pub(super) fn new(ack_wait_addition: Duration, ack_wait_multiplier: f64) -> Self {
+        Config {
+            ack_wait_addition,
+            ack_wait_multiplier,
+        }
+    }
+}
+
+pub(super) struct ActionController {
+    /// Configurable parameters of the `ActionController`
+    config: Config,
+
+    /// Contains a map between `FragmentIdentifier` and its full `PendingAcknowledgement` as well as
+    /// key to its `AckDelayQueue` entry if it was started.
+    pending_acks_data: HashMap<FragmentIdentifier, PendingAckEntry>,
+
+    // This structure ensures that we will EITHER handle expired timer or a received action and NEVER both
+    // at the same time hence getting rid of one possible race condition that we suffered from in the
+    // previous version.
+    /// DelayQueue with all `PendingAcknowledgement` that are waiting to be either received or
+    /// retransmitted if their timer fires up.
+    pending_acks_timers: NonExhaustiveDelayQueue<FragmentIdentifier>,
+
+    /// Channel for receiving `Action`s from other modules.
+    incoming_actions: UnboundedReceiver<Action>,
+
+    /// Channel for notifying `RetransmissionRequestListener` about expired acknowledgements.
+    retransmission_sender: RetransmissionRequestSender,
+}
+
+impl ActionController {
+    pub(super) fn new(
+        config: Config,
+        retransmission_sender: RetransmissionRequestSender,
+    ) -> (Self, ActionSender) {
+        let (sender, receiver) = mpsc::unbounded();
+        (
+            ActionController {
+                config,
+                pending_acks_data: HashMap::new(),
+                pending_acks_timers: NonExhaustiveDelayQueue::new(),
+                incoming_actions: receiver,
+                retransmission_sender,
+            },
+            sender,
+        )
+    }
+
+    fn handle_insert(&mut self, pending_acks: Vec<PendingAcknowledgement>) {
+        for pending_ack in pending_acks {
+            let frag_id = pending_ack.message_chunk.fragment_identifier();
+            trace!("{} is inserted", frag_id);
+
+            if self
+                .pending_acks_data
+                .insert(frag_id, (Arc::new(pending_ack), None))
+                .is_some()
+            {
+                panic!("Tried to insert duplicate pending ack")
+            }
+        }
+    }
+
+    fn handle_start_timer(&mut self, frag_id: FragmentIdentifier) {
+        trace!("{} is starting its timer", frag_id);
+
+        if let Some((pending_ack_data, queue_key)) = self.pending_acks_data.get_mut(&frag_id) {
+            if queue_key.is_some() {
+                // this branch should be IMPOSSIBLE under ANY condition. It would imply starting
+                // timer TWICE for the SAME PendingAcknowledgement
+                panic!("Tried to start an already started ack timer!")
+            }
+            let timeout = (pending_ack_data.delay.clone() * self.config.ack_wait_multiplier)
+                .to_duration()
+                + self.config.ack_wait_addition;
+
+            let new_queue_key = self.pending_acks_timers.insert(frag_id, timeout);
+            *queue_key = Some(new_queue_key)
+        } else {
+            debug!(
+                "Tried to START TIMER on pending ack that is already gone! - {}",
+                frag_id
+            );
+        }
+    }
+
+    fn handle_remove(&mut self, frag_id: FragmentIdentifier) {
+        trace!("{} is getting removed", frag_id);
+
+        match self.pending_acks_data.remove(&frag_id) {
+            None => {
+                debug!(
+                    "Tried to REMOVE pending ack that is already gone! - {}",
+                    frag_id
+                );
+            }
+            Some((_, queue_key)) => {
+                if let Some(queue_key) = queue_key {
+                    // there are no possible checks here, we must GUARANTEE that we NEVER try
+                    // to remove an entry that doesn't exist (and we MUST GUARANTEE that
+                    // we do not have a stale key)
+                    self.pending_acks_timers.remove(&queue_key);
+                // remove timer
+                } else {
+                    // I'm not 100% sure if having a `None` key is even possible here
+                    // (REMOVE would have to be called before START TIMER),
+                    debug!(
+                        "Tried to REMOVE pending ack without TIMER active - {}",
+                        frag_id
+                    );
+                }
+            }
+        }
+    }
+
+    // initiated basically as a first step of retransmission. At first data has its delay updated
+    // (as new sphinx packet was created with new expected delivery time)
+    fn handle_update_delay(&mut self, frag_id: FragmentIdentifier, delay: SphinxDelay) {
+        trace!("{} is updating its delay", frag_id);
+        // TODO: is it possible to solve this without either locking or temporarily removing the value?
+        if let Some((pending_ack_data, queue_key)) = self.pending_acks_data.remove(&frag_id) {
+            // this Action is triggered by `RetransmissionRequestListener` which held the other potential
+            // reference to this Arc. HOWEVER, before the Action was pushed onto the queue, the reference
+            // was dropped hence this unwrap is safe.
+            let mut inner_data = Arc::try_unwrap(pending_ack_data).unwrap();
+            inner_data.update_delay(delay);
+
+            self.pending_acks_data
+                .insert(frag_id, (Arc::new(inner_data), queue_key));
+        } else {
+            debug!(
+                "Tried to UPDATE TIMER on pending ack that is already gone! - {}",
+                frag_id
+            );
+        }
+    }
+
+    // note: when the entry expires it's automatically removed from pending_acks_timers
+    fn handle_expired_ack_timer(
+        &mut self,
+        expired_ack: Result<Expired<FragmentIdentifier>, TimerError>,
+    ) {
+        // I'm honestly not sure how to handle it, because getting it means other things in our
+        // system are already misbehaving. If we ever see this panic, then I guess we should worry
+        // about it. Perhaps just reschedule it at later point?
+        let frag_id = expired_ack
+            .expect("Tokio timer returned an error!")
+            .into_inner();
+
+        trace!("{} has expired", frag_id);
+
+        if let Some((pending_ack_data, queue_key)) = self.pending_acks_data.get_mut(&frag_id) {
+            if queue_key.is_none() {
+                // this branch should be IMPOSSIBLE under ANY condition. It would imply the timeout
+                // happened before it even started.
+                panic!("Ack expired before it was even scheduled!")
+            }
+            *queue_key = None;
+            // downgrading an arc and then upgrading vs cloning is difference of 30ns vs 15ns
+            // so it's literally a NO difference while it might prevent us from unnecessarily
+            // resending data (in maybe 1 in 1 million cases, but it's something)
+            self.retransmission_sender
+                .unbounded_send(Arc::downgrade(pending_ack_data))
+                .unwrap()
+        } else {
+            // this shouldn't cause any issues but shouldn't have happened to begin with!
+            error!("An already removed pending ack has expired")
+        }
+    }
+
+    fn process_action(&mut self, action: Action) {
+        match action {
+            Action::InsertPending(pending_acks) => self.handle_insert(pending_acks),
+            Action::RemovePending(frag_id) => self.handle_remove(frag_id),
+            Action::StartTimer(frag_id) => self.handle_start_timer(frag_id),
+            Action::UpdateDelay(frag_id, delay) => self.handle_update_delay(frag_id, delay),
+        }
+    }
+
+    pub(super) async fn run(&mut self) {
+        loop {
+            // at some point there will be a global shutdown signal here as the third option
+            tokio::select! {
+                // we NEVER expect for ANY sender to get dropped so unwrap here is fine
+                action = self.incoming_actions.next() => self.process_action(action.unwrap()),
+                // pending ack queue Stream CANNOT return a `None` so unwrap here is fine
+                expired_ack = self.pending_acks_timers.next() => self.handle_expired_ack_timer(expired_ack.unwrap())
+            }
+        }
+    }
+}

clients/client-core/src/client/real_messages_control/acknowledgement_control/input_message_listener.rs

@@ -0,0 +1,191 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::action_controller::{Action, ActionSender};
+use super::PendingAcknowledgement;
+use crate::client::reply_key_storage::ReplyKeyStorage;
+use crate::client::{
+    inbound_messages::{InputMessage, InputMessageReceiver},
+    real_messages_control::real_traffic_stream::{BatchRealMessageSender, RealMessage},
+    topology_control::TopologyAccessor,
+};
+use futures::StreamExt;
+use log::*;
+use nymsphinx::anonymous_replies::ReplySurb;
+use nymsphinx::preparer::MessagePreparer;
+use nymsphinx::{acknowledgements::AckKey, addressing::clients::Recipient};
+use rand::{CryptoRng, Rng};
+use std::sync::Arc;
+
+/// Module responsible for dealing with the received messages: splitting them, creating acknowledgements,
+/// putting everything into sphinx packets, etc.
+/// It also makes an initial sending attempt for said messages.
+pub(super) struct InputMessageListener<R>
+where
+    R: CryptoRng + Rng,
+{
+    ack_key: Arc<AckKey>,
+    ack_recipient: Recipient,
+    input_receiver: InputMessageReceiver,
+    message_preparer: MessagePreparer<R>,
+    action_sender: ActionSender,
+    real_message_sender: BatchRealMessageSender,
+    topology_access: TopologyAccessor,
+    reply_key_storage: ReplyKeyStorage,
+}
+
+impl<R> InputMessageListener<R>
+where
+    R: CryptoRng + Rng,
+{
+    // at this point I'm not entirely sure how to deal with this warning without
+    // some considerable refactoring
+    #[allow(clippy::too_many_arguments)]
+    pub(super) fn new(
+        ack_key: Arc<AckKey>,
+        ack_recipient: Recipient,
+        input_receiver: InputMessageReceiver,
+        message_preparer: MessagePreparer<R>,
+        action_sender: ActionSender,
+        real_message_sender: BatchRealMessageSender,
+        topology_access: TopologyAccessor,
+        reply_key_storage: ReplyKeyStorage,
+    ) -> Self {
+        InputMessageListener {
+            ack_key,
+            ack_recipient,
+            input_receiver,
+            message_preparer,
+            action_sender,
+            real_message_sender,
+            topology_access,
+            reply_key_storage,
+        }
+    }
+
+    // we require topology for replies to generate surb_acks
+    async fn handle_reply(&mut self, reply_surb: ReplySurb, data: Vec<u8>) -> Option<RealMessage> {
+        let topology_permit = self.topology_access.get_read_permit().await;
+        let topology = match topology_permit.try_get_valid_topology_ref(&self.ack_recipient, None) {
+            Some(topology_ref) => topology_ref,
+            None => {
+                warn!("Could not process the message - the network topology is invalid");
+                return None;
+            }
+        };
+
+        match self
+            .message_preparer
+            .prepare_reply_for_use(data, reply_surb, topology, &self.ack_key)
+            .await
+        {
+            Ok((mix_packet, reply_id)) => {
+                // TODO: later probably write pending ack here
+                // and deal with them....
+                // ... somehow
+                Some(RealMessage::new(mix_packet, reply_id))
+            }
+            Err(err) => {
+                // TODO: should we have some mechanism to indicate to the user that the `reply_surb`
+                // could be reused since technically it wasn't used up here?
+                warn!("failed to deal with received reply surb - {:?}", err);
+                None
+            }
+        }
+    }
+
+    async fn handle_fresh_message(
+        &mut self,
+        recipient: Recipient,
+        content: Vec<u8>,
+        with_reply_surb: bool,
+    ) -> Option<Vec<RealMessage>> {
+        let topology_permit = self.topology_access.get_read_permit().await;
+        let topology = match topology_permit
+            .try_get_valid_topology_ref(&self.ack_recipient, Some(&recipient))
+        {
+            Some(topology_ref) => topology_ref,
+            None => {
+                warn!("Could not process the message - the network topology is invalid");
+                return None;
+            }
+        };
+
+        // split the message, attach optional reply surb
+        let (split_message, reply_key) = self
+            .message_preparer
+            .prepare_and_split_message(content, with_reply_surb, topology)
+            .expect("somehow the topology was invalid after all!");
+
+        if let Some(reply_key) = reply_key {
+            self.reply_key_storage
+                .insert_encryption_key(reply_key)
+                .expect("Failed to insert surb reply key to the store!")
+        }
+
+        // encrypt chunks, put them inside sphinx packets and generate acks
+        let mut pending_acks = Vec::with_capacity(split_message.len());
+        let mut real_messages = Vec::with_capacity(split_message.len());
+        for message_chunk in split_message {
+            // we need to clone it because we need to keep it in memory in case we had to retransmit
+            // it. And then we'd need to recreate entire ACK again.
+            let chunk_clone = message_chunk.clone();
+            let prepared_fragment = self
+                .message_preparer
+                .prepare_chunk_for_sending(chunk_clone, topology, &self.ack_key, &recipient)
+                .await
+                .unwrap();
+
+            real_messages.push(RealMessage::new(
+                prepared_fragment.mix_packet,
+                message_chunk.fragment_identifier(),
+            ));
+
+            pending_acks.push(PendingAcknowledgement::new(
+                message_chunk,
+                prepared_fragment.total_delay,
+                recipient,
+            ));
+        }
+
+        // tells the controller to put this into the hashmap
+        self.action_sender
+            .unbounded_send(Action::new_insert(pending_acks))
+            .unwrap();
+
+        Some(real_messages)
+    }
+
+    async fn on_input_message(&mut self, msg: InputMessage) {
+        let real_messages = match msg {
+            InputMessage::Fresh {
+                recipient,
+                data,
+                with_reply_surb,
+            } => {
+                self.handle_fresh_message(recipient, data, with_reply_surb)
+                    .await
+            }
+            InputMessage::Reply { reply_surb, data } => self
+                .handle_reply(reply_surb, data)
+                .await
+                .map(|message| vec![message]),
+        };
+
+        // there's no point in trying to send nothing
+        if let Some(real_messages) = real_messages {
+            // tells real message sender (with the poisson timer) to send this to the mix network
+            self.real_message_sender
+                .unbounded_send(real_messages)
+                .unwrap();
+        }
+    }
+
+    pub(super) async fn run(&mut self) {
+        debug!("Started InputMessageListener");
+        while let Some(input_msg) = self.input_receiver.next().await {
+            self.on_input_message(input_msg).await;
+        }
+        error!("TODO: error msg. Or maybe panic?")
+    }
+}

clients/client-core/src/client/real_messages_control/acknowledgement_control/mod.rs

@@ -0,0 +1,276 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use self::{
+    acknowledgement_listener::AcknowledgementListener, action_controller::ActionController,
+    input_message_listener::InputMessageListener,
+    retransmission_request_listener::RetransmissionRequestListener,
+    sent_notification_listener::SentNotificationListener,
+};
+use super::real_traffic_stream::BatchRealMessageSender;
+use crate::client::reply_key_storage::ReplyKeyStorage;
+use crate::client::{inbound_messages::InputMessageReceiver, topology_control::TopologyAccessor};
+use futures::channel::mpsc;
+use gateway_client::AcknowledgementReceiver;
+use log::*;
+use nymsphinx::{
+    acknowledgements::AckKey,
+    addressing::clients::Recipient,
+    chunking::fragment::{Fragment, FragmentIdentifier},
+    preparer::MessagePreparer,
+    Delay as SphinxDelay,
+};
+use rand::{CryptoRng, Rng};
+use std::{
+    sync::{Arc, Weak},
+    time::Duration,
+};
+use tokio::task::JoinHandle;
+
+mod acknowledgement_listener;
+mod action_controller;
+mod input_message_listener;
+mod retransmission_request_listener;
+mod sent_notification_listener;
+
+/// Channel used for indicating that the particular `Fragment` should be retransmitted.
+type RetransmissionRequestSender = mpsc::UnboundedSender<Weak<PendingAcknowledgement>>;
+
+/// Channel used for receiving data about particular `Fragment` that should be retransmitted.
+type RetransmissionRequestReceiver = mpsc::UnboundedReceiver<Weak<PendingAcknowledgement>>;
+
+/// Channel used for signalling that the particular `Fragment` (associated with the `FragmentIdentifier`)
+/// is done being delayed and is about to be sent to the mix network.
+pub(super) type SentPacketNotificationSender = mpsc::UnboundedSender<FragmentIdentifier>;
+
+/// Channel used for receiving signals about the particular `Fragment` (associated with the `FragmentIdentifier`)
+/// that it is about to be sent to the mix network and its timeout timer should be started.
+type SentPacketNotificationReceiver = mpsc::UnboundedReceiver<FragmentIdentifier>;
+
+/// Structure representing a data `Fragment` that is on-route to the specified `Recipient`
+#[derive(Debug)]
+pub(crate) struct PendingAcknowledgement {
+    message_chunk: Fragment,
+    delay: SphinxDelay,
+    recipient: Recipient,
+}
+
+impl PendingAcknowledgement {
+    /// Creates new instance of `PendingAcknowledgement` using the provided data.
+    fn new(message_chunk: Fragment, delay: SphinxDelay, recipient: Recipient) -> Self {
+        PendingAcknowledgement {
+            message_chunk,
+            delay,
+            recipient,
+        }
+    }
+
+    fn update_delay(&mut self, new_delay: SphinxDelay) {
+        self.delay = new_delay;
+    }
+}
+
+/// AcknowledgementControllerConnectors represents set of channels for communication with
+/// other parts of the system in order to support acknowledgements and retransmission.
+pub(super) struct AcknowledgementControllerConnectors {
+    /// Channel used for forwarding prepared sphinx messages into the poisson sender
+    /// to be sent to the mix network.
+    real_message_sender: BatchRealMessageSender,
+
+    /// Channel used for receiving raw messages from a client. The messages need to be put
+    /// into sphinx packets first.
+    input_receiver: InputMessageReceiver,
+
+    /// Channel used for receiving notification about particular packet being sent off to the
+    /// mix network (i.e. it was done being delayed by whatever value was determined in the poisson
+    /// sender)
+    sent_notifier: SentPacketNotificationReceiver,
+
+    /// Channel used for receiving acknowledgements from the mix network.
+    ack_receiver: AcknowledgementReceiver,
+}
+
+impl AcknowledgementControllerConnectors {
+    pub(super) fn new(
+        real_message_sender: BatchRealMessageSender,
+        input_receiver: InputMessageReceiver,
+        sent_notifier: SentPacketNotificationReceiver,
+        ack_receiver: AcknowledgementReceiver,
+    ) -> Self {
+        AcknowledgementControllerConnectors {
+            real_message_sender,
+            input_receiver,
+            sent_notifier,
+            ack_receiver,
+        }
+    }
+}
+
+/// Configurable parameters of the `AcknowledgementController`
+pub(super) struct Config {
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the additive part `b`
+    ack_wait_addition: Duration,
+
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the multiplier `a`
+    ack_wait_multiplier: f64,
+
+    /// Average delay an acknowledgement packet is going to get delayed at a single mixnode.
+    average_ack_delay: Duration,
+
+    /// Average delay a data packet is going to get delayed at a single mixnode.
+    average_packet_delay: Duration,
+}
+
+impl Config {
+    pub(super) fn new(
+        ack_wait_addition: Duration,
+        ack_wait_multiplier: f64,
+        average_ack_delay: Duration,
+        average_packet_delay: Duration,
+    ) -> Self {
+        Config {
+            ack_wait_addition,
+            ack_wait_multiplier,
+            average_ack_delay,
+            average_packet_delay,
+        }
+    }
+}
+
+pub(super) struct AcknowledgementController<R>
+where
+    R: CryptoRng + Rng,
+{
+    acknowledgement_listener: Option<AcknowledgementListener>,
+    input_message_listener: Option<InputMessageListener<R>>,
+    retransmission_request_listener: Option<RetransmissionRequestListener<R>>,
+    sent_notification_listener: Option<SentNotificationListener>,
+    action_controller: Option<ActionController>,
+}
+
+impl<R> AcknowledgementController<R>
+where
+    R: 'static + CryptoRng + Rng + Clone + Send,
+{
+    pub(super) fn new(
+        config: Config,
+        rng: R,
+        topology_access: TopologyAccessor,
+        ack_key: Arc<AckKey>,
+        ack_recipient: Recipient,
+        reply_key_storage: ReplyKeyStorage,
+        connectors: AcknowledgementControllerConnectors,
+    ) -> Self {
+        let (retransmission_tx, retransmission_rx) = mpsc::unbounded();
+
+        let action_config =
+            action_controller::Config::new(config.ack_wait_addition, config.ack_wait_multiplier);
+        let (action_controller, action_sender) =
+            ActionController::new(action_config, retransmission_tx);
+
+        let message_preparer = MessagePreparer::new(
+            rng,
+            ack_recipient,
+            config.average_packet_delay,
+            config.average_ack_delay,
+        );
+
+        // will listen for any acks coming from the network
+        let acknowledgement_listener = AcknowledgementListener::new(
+            Arc::clone(&ack_key),
+            connectors.ack_receiver,
+            action_sender.clone(),
+        );
+
+        // will listen for any new messages from the client
+        let input_message_listener = InputMessageListener::new(
+            Arc::clone(&ack_key),
+            ack_recipient,
+            connectors.input_receiver,
+            message_preparer.clone(),
+            action_sender.clone(),
+            connectors.real_message_sender.clone(),
+            topology_access.clone(),
+            reply_key_storage,
+        );
+
+        // will listen for any ack timeouts and trigger retransmission
+        let retransmission_request_listener = RetransmissionRequestListener::new(
+            Arc::clone(&ack_key),
+            ack_recipient,
+            message_preparer,
+            action_sender.clone(),
+            connectors.real_message_sender,
+            retransmission_rx,
+            topology_access,
+        );
+
+        // will listen for events indicating the packet was sent through the network so that
+        // the retransmission timer should be started.
+        let sent_notification_listener =
+            SentNotificationListener::new(connectors.sent_notifier, action_sender);
+
+        AcknowledgementController {
+            acknowledgement_listener: Some(acknowledgement_listener),
+            input_message_listener: Some(input_message_listener),
+            retransmission_request_listener: Some(retransmission_request_listener),
+            sent_notification_listener: Some(sent_notification_listener),
+            action_controller: Some(action_controller),
+        }
+    }
+
+    pub(super) async fn run(&mut self) {
+        let mut acknowledgement_listener = self.acknowledgement_listener.take().unwrap();
+        let mut input_message_listener = self.input_message_listener.take().unwrap();
+        let mut retransmission_request_listener =
+            self.retransmission_request_listener.take().unwrap();
+        let mut sent_notification_listener = self.sent_notification_listener.take().unwrap();
+        let mut action_controller = self.action_controller.take().unwrap();
+
+        // the below are log messages are errors as at the current stage we do not expect any of
+        // the task to ever finish. This will of course change once we introduce
+        // graceful shutdowns.
+        let ack_listener_fut = tokio::spawn(async move {
+            acknowledgement_listener.run().await;
+            error!("The acknowledgement listener has finished execution!");
+            acknowledgement_listener
+        });
+        let input_listener_fut = tokio::spawn(async move {
+            input_message_listener.run().await;
+            error!("The input listener has finished execution!");
+            input_message_listener
+        });
+        let retransmission_req_fut = tokio::spawn(async move {
+            retransmission_request_listener.run().await;
+            error!("The retransmission request listener has finished execution!");
+            retransmission_request_listener
+        });
+        let sent_notification_fut = tokio::spawn(async move {
+            sent_notification_listener.run().await;
+            error!("The sent notification listener has finished execution!");
+            sent_notification_listener
+        });
+        let action_controller_fut = tokio::spawn(async move {
+            action_controller.run().await;
+            error!("The controller has finished execution!");
+            action_controller
+        });
+
+        // technically we don't have to bring `AcknowledgementController` back to a valid state
+        // but we can do it, so why not? Perhaps it might be useful if we wanted to allow
+        // for restarts of certain modules without killing the entire process.
+        self.acknowledgement_listener = Some(ack_listener_fut.await.unwrap());
+        self.input_message_listener = Some(input_listener_fut.await.unwrap());
+        self.retransmission_request_listener = Some(retransmission_req_fut.await.unwrap());
+        self.sent_notification_listener = Some(sent_notification_fut.await.unwrap());
+        self.action_controller = Some(action_controller_fut.await.unwrap());
+    }
+
+    #[allow(dead_code)]
+    pub(super) fn start(mut self) -> JoinHandle<Self> {
+        tokio::spawn(async move {
+            self.run().await;
+            self
+        })
+    }
+}

clients/client-core/src/client/real_messages_control/acknowledgement_control/retransmission_request_listener.rs

@@ -0,0 +1,130 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::action_controller::{Action, ActionSender};
+use super::PendingAcknowledgement;
+use super::RetransmissionRequestReceiver;
+use crate::client::{
+    real_messages_control::real_traffic_stream::{BatchRealMessageSender, RealMessage},
+    topology_control::TopologyAccessor,
+};
+use futures::StreamExt;
+use log::*;
+use nymsphinx::preparer::MessagePreparer;
+use nymsphinx::{acknowledgements::AckKey, addressing::clients::Recipient};
+use rand::{CryptoRng, Rng};
+use std::sync::{Arc, Weak};
+
+// responsible for packet retransmission upon fired timer
+pub(super) struct RetransmissionRequestListener<R>
+where
+    R: CryptoRng + Rng,
+{
+    ack_key: Arc<AckKey>,
+    ack_recipient: Recipient,
+    message_preparer: MessagePreparer<R>,
+    action_sender: ActionSender,
+    real_message_sender: BatchRealMessageSender,
+    request_receiver: RetransmissionRequestReceiver,
+    topology_access: TopologyAccessor,
+}
+
+impl<R> RetransmissionRequestListener<R>
+where
+    R: CryptoRng + Rng,
+{
+    pub(super) fn new(
+        ack_key: Arc<AckKey>,
+        ack_recipient: Recipient,
+        message_preparer: MessagePreparer<R>,
+        action_sender: ActionSender,
+        real_message_sender: BatchRealMessageSender,
+        request_receiver: RetransmissionRequestReceiver,
+        topology_access: TopologyAccessor,
+    ) -> Self {
+        RetransmissionRequestListener {
+            ack_key,
+            ack_recipient,
+            message_preparer,
+            action_sender,
+            real_message_sender,
+            request_receiver,
+            topology_access,
+        }
+    }
+
+    async fn on_retransmission_request(&mut self, timed_out_ack: Weak<PendingAcknowledgement>) {
+        let timed_out_ack = match timed_out_ack.upgrade() {
+            Some(timed_out_ack) => timed_out_ack,
+            None => {
+                debug!("We received an ack JUST as we were about to retransmit [1]");
+                return;
+            }
+        };
+        let packet_recipient = &timed_out_ack.recipient;
+        let chunk_clone = timed_out_ack.message_chunk.clone();
+        let frag_id = chunk_clone.fragment_identifier();
+
+        let topology_permit = self.topology_access.get_read_permit().await;
+        let topology_ref = match topology_permit
+            .try_get_valid_topology_ref(&self.ack_recipient, Some(packet_recipient))
+        {
+            Some(topology_ref) => topology_ref,
+            None => {
+                warn!("Could not retransmit the packet - the network topology is invalid");
+                // we NEED to start timer here otherwise we will have this guy permanently stuck in memory
+                self.action_sender
+                    .unbounded_send(Action::new_start_timer(frag_id))
+                    .unwrap();
+                return;
+            }
+        };
+
+        let prepared_fragment = self
+            .message_preparer
+            .prepare_chunk_for_sending(chunk_clone, topology_ref, &self.ack_key, packet_recipient)
+            .await
+            .unwrap();
+
+        // if we have the ONLY strong reference to the ack data, it means it was removed from the
+        // pending acks
+        if Arc::strong_count(&timed_out_ack) == 1 {
+            // while we were messing with topology, wrapping data in sphinx, etc. we actually received
+            // this ack after all! no need to retransmit then
+            debug!("We received an ack JUST as we were about to retransmit [2]");
+            return;
+        }
+        // we no longer need the reference - let's drop it so that if somehow `UpdateTimer` action
+        // reached the controller before this function terminated, the controller would not panic.
+        drop(timed_out_ack);
+
+        let new_delay = prepared_fragment.total_delay;
+
+        // We know this update will be reflected by the `StartTimer` Action performed when this
+        // message is sent through the mix network.
+        // Reason being: UpdateTimer is now pushed onto the Action queue and `StartTimer` will
+        // only be pushed when the below `RealMessage` (which we are about to create)
+        // is sent to the `OutQueueControl` and has gone through its internal queue
+        // with the additional poisson delay.
+        // And since Actions are executed in order `UpdateTimer` will HAVE TO be executed before `StartTimer`
+        self.action_sender
+            .unbounded_send(Action::new_update_delay(frag_id, new_delay))
+            .unwrap();
+
+        // send to `OutQueueControl` to eventually send to the mix network
+        self.real_message_sender
+            .unbounded_send(vec![RealMessage::new(
+                prepared_fragment.mix_packet,
+                frag_id,
+            )])
+            .unwrap();
+    }
+
+    pub(super) async fn run(&mut self) {
+        debug!("Started RetransmissionRequestListener");
+        while let Some(timed_out_ack) = self.request_receiver.next().await {
+            self.on_retransmission_request(timed_out_ack).await;
+        }
+        error!("TODO: error msg. Or maybe panic?")
+    }
+}

clients/client-core/src/client/real_messages_control/acknowledgement_control/sent_notification_listener.rs

@@ -0,0 +1,52 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::action_controller::{Action, ActionSender};
+use super::SentPacketNotificationReceiver;
+use futures::StreamExt;
+use log::*;
+use nymsphinx::chunking::fragment::{FragmentIdentifier, COVER_FRAG_ID};
+
+/// Module responsible for starting up retransmission timers.
+/// It is required because when we send our packet to the `real traffic stream` controlled
+/// by a poisson timer, there's no guarantee the message will be sent immediately, so we might
+/// accidentally fire retransmission way quicker than we should have.
+pub(super) struct SentNotificationListener {
+    sent_notifier: SentPacketNotificationReceiver,
+    action_sender: ActionSender,
+}
+
+impl SentNotificationListener {
+    pub(super) fn new(
+        sent_notifier: SentPacketNotificationReceiver,
+        action_sender: ActionSender,
+    ) -> Self {
+        SentNotificationListener {
+            sent_notifier,
+            action_sender,
+        }
+    }
+
+    async fn on_sent_message(&mut self, frag_id: FragmentIdentifier) {
+        if frag_id == COVER_FRAG_ID {
+            trace!("sent off a cover message - no need to start retransmission timer!");
+            return;
+        } else if frag_id.is_reply() {
+            debug!("sent off a reply message - no need to start retransmission timer!");
+            // TODO: probably there will need to be some extra procedure here, like it would
+            // be nice to know that our reply actually reached the recipient (i.e. we got the ack)
+            return;
+        }
+        self.action_sender
+            .unbounded_send(Action::new_start_timer(frag_id))
+            .unwrap();
+    }
+
+    pub(super) async fn run(&mut self) {
+        debug!("Started SentNotificationListener");
+        while let Some(frag_id) = self.sent_notifier.next().await {
+            self.on_sent_message(frag_id).await;
+        }
+        error!("TODO: error msg. Or maybe panic?")
+    }
+}

clients/client-core/src/client/real_messages_control/mod.rs

@@ -0,0 +1,178 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// INPUT: InputMessage from user
+// INPUT2: Acks from mix
+// OUTPUT: MixMessage to mix traffic
+
+use self::{
+    acknowledgement_control::AcknowledgementController, real_traffic_stream::OutQueueControl,
+};
+use crate::client::real_messages_control::acknowledgement_control::AcknowledgementControllerConnectors;
+use crate::client::reply_key_storage::ReplyKeyStorage;
+use crate::client::{
+    inbound_messages::InputMessageReceiver, mix_traffic::BatchMixMessageSender,
+    topology_control::TopologyAccessor,
+};
+use futures::channel::mpsc;
+use gateway_client::AcknowledgementReceiver;
+use log::*;
+use nymsphinx::acknowledgements::AckKey;
+use nymsphinx::addressing::clients::Recipient;
+use rand::{rngs::OsRng, CryptoRng, Rng};
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::task::JoinHandle;
+
+mod acknowledgement_control;
+mod real_traffic_stream;
+
+// TODO: ack_key and self_recipient shouldn't really be part of this config
+pub struct Config {
+    /// Key used to decrypt contents of received SURBAcks
+    ack_key: Arc<AckKey>,
+
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the additive part `b`
+    ack_wait_addition: Duration,
+
+    /// Given ack timeout in the form a * BASE_DELAY + b, it specifies the multiplier `a`
+    ack_wait_multiplier: f64,
+
+    /// Address of `this` client.
+    self_recipient: Recipient,
+
+    /// Average delay between sending subsequent packets from this client.
+    average_message_sending_delay: Duration,
+
+    /// Average delay a data packet is going to get delayed at a single mixnode.
+    average_packet_delay_duration: Duration,
+
+    /// Average delay an acknowledgement packet is going to get delayed at a single mixnode.
+    average_ack_delay_duration: Duration,
+}
+
+impl Config {
+    pub fn new(
+        ack_key: Arc<AckKey>,
+        ack_wait_multiplier: f64,
+        ack_wait_addition: Duration,
+        average_ack_delay_duration: Duration,
+        average_message_sending_delay: Duration,
+        average_packet_delay_duration: Duration,
+        self_recipient: Recipient,
+    ) -> Self {
+        Config {
+            ack_key,
+            ack_wait_addition,
+            ack_wait_multiplier,
+            self_recipient,
+            average_message_sending_delay,
+            average_packet_delay_duration,
+            average_ack_delay_duration,
+        }
+    }
+}
+
+pub struct RealMessagesController<R>
+where
+    R: CryptoRng + Rng,
+{
+    out_queue_control: Option<OutQueueControl<R>>,
+    ack_control: Option<AcknowledgementController<R>>,
+}
+
+// obviously when we finally make shared rng that is on 'higher' level, this should become
+// generic `R`
+impl RealMessagesController<OsRng> {
+    pub fn new(
+        config: Config,
+        ack_receiver: AcknowledgementReceiver,
+        input_receiver: InputMessageReceiver,
+        mix_sender: BatchMixMessageSender,
+        topology_access: TopologyAccessor,
+        reply_key_storage: ReplyKeyStorage,
+    ) -> Self {
+        let rng = OsRng;
+
+        let (real_message_sender, real_message_receiver) = mpsc::unbounded();
+        let (sent_notifier_tx, sent_notifier_rx) = mpsc::unbounded();
+
+        let ack_controller_connectors = AcknowledgementControllerConnectors::new(
+            real_message_sender,
+            input_receiver,
+            sent_notifier_rx,
+            ack_receiver,
+        );
+
+        let ack_control_config = acknowledgement_control::Config::new(
+            config.ack_wait_addition,
+            config.ack_wait_multiplier,
+            config.average_ack_delay_duration,
+            config.average_packet_delay_duration,
+        );
+
+        let ack_control = AcknowledgementController::new(
+            ack_control_config,
+            rng,
+            topology_access.clone(),
+            Arc::clone(&config.ack_key),
+            config.self_recipient,
+            reply_key_storage,
+            ack_controller_connectors,
+        );
+
+        let out_queue_config = real_traffic_stream::Config::new(
+            config.average_ack_delay_duration,
+            config.average_packet_delay_duration,
+            config.average_message_sending_delay,
+        );
+
+        let out_queue_control = OutQueueControl::new(
+            out_queue_config,
+            Arc::clone(&config.ack_key),
+            sent_notifier_tx,
+            mix_sender,
+            real_message_receiver,
+            rng,
+            config.self_recipient,
+            topology_access,
+        );
+
+        RealMessagesController {
+            out_queue_control: Some(out_queue_control),
+            ack_control: Some(ack_control),
+        }
+    }
+
+    pub(super) async fn run(&mut self) {
+        let mut out_queue_control = self.out_queue_control.take().unwrap();
+        let mut ack_control = self.ack_control.take().unwrap();
+
+        // the below are log messages are errors as at the current stage we do not expect any of
+        // the task to ever finish. This will of course change once we introduce
+        // graceful shutdowns.
+        let out_queue_control_fut = tokio::spawn(async move {
+            out_queue_control.run_out_queue_control().await;
+            error!("The out queue controller has finished execution!");
+            out_queue_control
+        });
+        let ack_control_fut = tokio::spawn(async move {
+            ack_control.run().await;
+            error!("The acknowledgement controller has finished execution!");
+            ack_control
+        });
+
+        // technically we don't have to bring `RealMessagesController` back to a valid state
+        // but we can do it, so why not? Perhaps it might be useful if we wanted to allow
+        // for restarts of certain modules without killing the entire process.
+        self.out_queue_control = Some(out_queue_control_fut.await.unwrap());
+        self.ack_control = Some(ack_control_fut.await.unwrap());
+    }
+
+    pub fn start(mut self) -> JoinHandle<Self> {
+        tokio::spawn(async move {
+            self.run().await;
+            self
+        })
+    }
+}

clients/client-core/src/client/real_messages_control/real_traffic_stream.rs

@@ -0,0 +1,269 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::mix_traffic::BatchMixMessageSender;
+use crate::client::real_messages_control::acknowledgement_control::SentPacketNotificationSender;
+use crate::client::topology_control::TopologyAccessor;
+use futures::channel::mpsc;
+use futures::task::{Context, Poll};
+use futures::{Future, Stream, StreamExt};
+use log::*;
+use nymsphinx::acknowledgements::AckKey;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::chunking::fragment::FragmentIdentifier;
+use nymsphinx::cover::generate_loop_cover_packet;
+use nymsphinx::forwarding::packet::MixPacket;
+use nymsphinx::utils::sample_poisson_duration;
+use rand::{CryptoRng, Rng};
+use std::collections::VecDeque;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::time;
+
+/// Configurable parameters of the `OutQueueControl`
+pub(crate) struct Config {
+    /// Average delay an acknowledgement packet is going to get delay at a single mixnode.
+    average_ack_delay: Duration,
+
+    /// Average delay a data packet is going to get delay at a single mixnode.
+    average_packet_delay: Duration,
+
+    /// Average delay between sending subsequent packets.
+    average_message_sending_delay: Duration,
+}
+
+impl Config {
+    pub(crate) fn new(
+        average_ack_delay: Duration,
+        average_packet_delay: Duration,
+        average_message_sending_delay: Duration,
+    ) -> Self {
+        Config {
+            average_ack_delay,
+            average_packet_delay,
+            average_message_sending_delay,
+        }
+    }
+}
+
+pub(crate) struct OutQueueControl<R>
+where
+    R: CryptoRng + Rng,
+{
+    /// Configurable parameters of the `ActionController`
+    config: Config,
+
+    /// Key used to encrypt and decrypt content of an ACK packet.
+    ack_key: Arc<AckKey>,
+
+    /// Channel used for notifying of a real packet being sent out. Used to start up retransmission timer.
+    sent_notifier: SentPacketNotificationSender,
+
+    /// Internal state, determined by `average_message_sending_delay`,
+    /// used to keep track of when a next packet should be sent out.
+    next_delay: Pin<Box<time::Sleep>>,
+
+    /// Channel used for sending prepared sphinx packets to `MixTrafficController` that sends them
+    /// out to the network without any further delays.
+    mix_tx: BatchMixMessageSender,
+
+    /// Channel used for receiving real, prepared, messages that must be first sufficiently delayed
+    /// before being sent out into the network.
+    real_receiver: BatchRealMessageReceiver,
+
+    /// Represents full address of this client.
+    our_full_destination: Recipient,
+
+    /// Instance of a cryptographically secure random number generator.
+    rng: R,
+
+    /// Accessor to the common instance of network topology.
+    topology_access: TopologyAccessor,
+
+    /// Buffer containing all real messages received. It is first exhausted before more are pulled.
+    received_buffer: VecDeque<RealMessage>,
+}
+
+pub(crate) struct RealMessage {
+    mix_packet: MixPacket,
+    fragment_id: FragmentIdentifier,
+}
+
+impl RealMessage {
+    pub(crate) fn new(mix_packet: MixPacket, fragment_id: FragmentIdentifier) -> Self {
+        RealMessage {
+            mix_packet,
+            fragment_id,
+        }
+    }
+}
+
+// messages are already prepared, etc. the real point of it is to forward it to mix_traffic
+// after sufficient delay
+pub(crate) type BatchRealMessageSender = mpsc::UnboundedSender<Vec<RealMessage>>;
+type BatchRealMessageReceiver = mpsc::UnboundedReceiver<Vec<RealMessage>>;
+
+pub(crate) enum StreamMessage {
+    Cover,
+    Real(Box<RealMessage>),
+}
+
+impl<R> Stream for OutQueueControl<R>
+where
+    R: CryptoRng + Rng + Unpin,
+{
+    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 self.next_delay.as_mut().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 avg_delay = self.config.average_message_sending_delay;
+        let now = self.next_delay.deadline();
+        let next_poisson_delay = sample_poisson_duration(&mut self.rng, avg_delay);
+
+        // The next interval value is `next_poisson_delay` after the one that just
+        // yielded.
+        let next = now + next_poisson_delay;
+        self.next_delay.as_mut().reset(next);
+
+        // check if we have anything immediately available
+        if let Some(real_available) = self.received_buffer.pop_front() {
+            return Poll::Ready(Some(StreamMessage::Real(Box::new(real_available))));
+        }
+
+        // decide what kind of message to send
+        match Pin::new(&mut self.real_receiver).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 are more messages available, return first one and store the rest
+            Poll::Ready(Some(real_messages)) => {
+                self.received_buffer = real_messages.into();
+                // we MUST HAVE received at least ONE message
+                Poll::Ready(Some(StreamMessage::Real(Box::new(
+                    self.received_buffer.pop_front().unwrap(),
+                ))))
+            }
+
+            // otherwise construct a dummy one
+            Poll::Pending => Poll::Ready(Some(StreamMessage::Cover)),
+        }
+    }
+}
+
+impl<R> OutQueueControl<R>
+where
+    R: CryptoRng + Rng + Unpin,
+{
+    // at this point I'm not entirely sure how to deal with this warning without
+    // some considerable refactoring
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn new(
+        config: Config,
+        ack_key: Arc<AckKey>,
+        sent_notifier: SentPacketNotificationSender,
+        mix_tx: BatchMixMessageSender,
+        real_receiver: BatchRealMessageReceiver,
+        rng: R,
+        our_full_destination: Recipient,
+        topology_access: TopologyAccessor,
+    ) -> Self {
+        OutQueueControl {
+            config,
+            ack_key,
+            sent_notifier,
+            next_delay: Box::pin(time::sleep(Default::default())),
+            mix_tx,
+            real_receiver,
+            our_full_destination,
+            rng,
+            topology_access,
+            received_buffer: VecDeque::with_capacity(0), // we won't be putting any data into this guy directly
+        }
+    }
+
+    fn sent_notify(&self, frag_id: FragmentIdentifier) {
+        // well technically the message was not sent just yet, but now it's up to internal
+        // queues and client load rather than the required delay. So realistically we can treat
+        // whatever is about to happen as negligible additional delay.
+        trace!("{} is about to get sent to the mixnet", frag_id);
+        self.sent_notifier.unbounded_send(frag_id).unwrap();
+    }
+
+    async fn on_message(&mut self, next_message: StreamMessage) {
+        trace!("created new message");
+
+        let next_message = match next_message {
+            StreamMessage::Cover => {
+                // TODO for way down the line: in very rare cases (during topology update) we might have
+                // to wait a really tiny bit before actually obtaining the permit hence messing with our
+                // poisson delay, but is it really a problem?
+                let topology_permit = self.topology_access.get_read_permit().await;
+                // the ack is sent back to ourselves (and then ignored)
+                let topology_ref_option = topology_permit.try_get_valid_topology_ref(
+                    &self.our_full_destination,
+                    Some(&self.our_full_destination),
+                );
+                if topology_ref_option.is_none() {
+                    warn!(
+                        "No valid topology detected - won't send any loop cover message this time"
+                    );
+                    return;
+                }
+                let topology_ref = topology_ref_option.unwrap();
+
+                generate_loop_cover_packet(
+                    &mut self.rng,
+                    topology_ref,
+                    &*self.ack_key,
+                    &self.our_full_destination,
+                    self.config.average_ack_delay,
+                    self.config.average_packet_delay,
+                )
+                .expect("Somehow failed to generate a loop cover message with a valid topology")
+            }
+            StreamMessage::Real(real_message) => {
+                self.sent_notify(real_message.fragment_id);
+                real_message.mix_packet
+            }
+        };
+
+        // 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(vec![next_message]).unwrap();
+
+        // JS: Not entirely sure why or how it fixes stuff, but without the yield call,
+        // the UnboundedReceiver [of mix_rx] will not get a chance to read anything
+        // JS2: Basically it was the case that with high enough rate, the stream had already a next value
+        // ready and hence was immediately re-scheduled causing other tasks to be starved;
+        // yield makes it go back the scheduling queue regardless of its value availability
+        tokio::task::yield_now().await;
+    }
+
+    // Send messages at certain rate and if no real traffic is available, send cover message.
+    async fn run_normal_out_queue(&mut self) {
+        // we should set initial delay only when we actually start the stream
+        self.next_delay = Box::pin(time::sleep(sample_poisson_duration(
+            &mut self.rng,
+            self.config.average_message_sending_delay,
+        )));
+
+        while let Some(next_message) = self.next().await {
+            self.on_message(next_message).await;
+        }
+    }
+
+    pub(crate) async fn run_out_queue_control(&mut self) {
+        debug!("Starting out queue controller...");
+        self.run_normal_out_queue().await
+    }
+}

clients/client-core/src/client/received_buffer.rs

@@ -0,0 +1,362 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::reply_key_storage::ReplyKeyStorage;
+use crypto::asymmetric::encryption;
+use crypto::symmetric::stream_cipher;
+use crypto::Digest;
+use futures::channel::mpsc;
+use futures::lock::Mutex;
+use futures::StreamExt;
+use gateway_client::MixnetMessageReceiver;
+use log::*;
+use nymsphinx::anonymous_replies::{encryption_key::EncryptionKeyDigest, SurbEncryptionKey};
+use nymsphinx::params::{ReplySurbEncryptionAlgorithm, ReplySurbKeyDigestAlgorithm};
+use nymsphinx::receiver::{MessageReceiver, MessageRecoveryError, ReconstructedMessage};
+use std::collections::HashSet;
+use std::sync::Arc;
+use tokio::task::JoinHandle;
+
+// Buffer Requests to say "hey, send any reconstructed messages to this channel"
+// or to say "hey, I'm going offline, don't send anything more to me. Just buffer them instead"
+pub type ReceivedBufferRequestSender = mpsc::UnboundedSender<ReceivedBufferMessage>;
+pub type ReceivedBufferRequestReceiver = mpsc::UnboundedReceiver<ReceivedBufferMessage>;
+
+// The channel set for the above
+pub type ReconstructedMessagesSender = mpsc::UnboundedSender<Vec<ReconstructedMessage>>;
+pub type ReconstructedMessagesReceiver = mpsc::UnboundedReceiver<Vec<ReconstructedMessage>>;
+
+struct ReceivedMessagesBufferInner {
+    messages: Vec<ReconstructedMessage>,
+    local_encryption_keypair: Arc<encryption::KeyPair>,
+
+    // TODO: looking how it 'looks' here, perhaps `MessageReceiver` should be renamed to something
+    // else instead.
+    message_receiver: MessageReceiver,
+    message_sender: Option<ReconstructedMessagesSender>,
+
+    // TODO: this will get cleared upon re-running the client
+    // but perhaps it should be changed to include timestamps of when the message was reconstructed
+    // and every now and then remove ids older than X
+    recently_reconstructed: HashSet<i32>,
+}
+
+impl ReceivedMessagesBufferInner {
+    fn process_received_fragment(&mut self, raw_fragment: Vec<u8>) -> Option<ReconstructedMessage> {
+        let fragment_data = match self
+            .message_receiver
+            .recover_plaintext(self.local_encryption_keypair.private_key(), raw_fragment)
+        {
+            Err(e) => {
+                warn!("failed to recover fragment data: {:?}. The whole underlying message might be corrupted and unrecoverable!", e);
+                return None;
+            }
+            Ok(frag_data) => frag_data,
+        };
+
+        if nymsphinx::cover::is_cover(&fragment_data) {
+            trace!("The message was a loop cover message! Skipping it");
+            return None;
+        }
+
+        let fragment = match self.message_receiver.recover_fragment(&fragment_data) {
+            Err(e) => {
+                warn!("failed to recover fragment from raw data: {:?}. The whole underlying message might be corrupted and unrecoverable!", e);
+                return None;
+            }
+            Ok(frag) => frag,
+        };
+
+        if self.recently_reconstructed.contains(&fragment.id()) {
+            debug!("Received a chunk of already re-assembled message ({:?})! It probably got here because the ack got lost", fragment.id());
+            return None;
+        }
+
+        // if we returned an error the underlying message is malformed in some way
+        match self.message_receiver.insert_new_fragment(fragment) {
+            Err(err) => match err {
+                MessageRecoveryError::MalformedReconstructedMessage(message_sets) => {
+                    // TODO: should we really insert reconstructed sets? could this be abused for some attack?
+                    for set_id in message_sets {
+                        if !self.recently_reconstructed.insert(set_id) {
+                            // or perhaps we should even panic at this point?
+                            error!("Reconstructed another message containing already used set id!")
+                        }
+                    }
+                    None
+                }
+                _ => unreachable!(
+                    "no other error kind should have been returned here! If so, it's a bug!"
+                ),
+            },
+            Ok(reconstruction_result) => match reconstruction_result {
+                Some((reconstructed_message, used_sets)) => {
+                    for set_id in used_sets {
+                        if !self.recently_reconstructed.insert(set_id) {
+                            // or perhaps we should even panic at this point?
+                            error!("Reconstructed another message containing already used set id!")
+                        }
+                    }
+                    Some(reconstructed_message)
+                }
+                None => None,
+            },
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+// Note: you should NEVER create more than a single instance of this using 'new()'.
+// You should always use .clone() to create additional instances
+struct ReceivedMessagesBuffer {
+    inner: Arc<Mutex<ReceivedMessagesBufferInner>>,
+
+    /// Storage containing keys to all [`ReplySURB`]s ever sent out that we did not receive back.
+    // There's no need to put it behind a Mutex since it's already properly concurrent
+    reply_key_storage: ReplyKeyStorage,
+}
+
+impl ReceivedMessagesBuffer {
+    fn new(
+        local_encryption_keypair: Arc<encryption::KeyPair>,
+        reply_key_storage: ReplyKeyStorage,
+    ) -> Self {
+        ReceivedMessagesBuffer {
+            inner: Arc::new(Mutex::new(ReceivedMessagesBufferInner {
+                messages: Vec::new(),
+                local_encryption_keypair,
+                message_receiver: MessageReceiver::new(),
+                message_sender: None,
+                recently_reconstructed: HashSet::new(),
+            })),
+            reply_key_storage,
+        }
+    }
+
+    async fn disconnect_sender(&mut self) {
+        let mut guard = self.inner.lock().await;
+        if guard.message_sender.is_none() {
+            // in theory we could just ignore it, but that situation should have never happened
+            // in the first place, so this way we at least know we have an important bug to fix
+            panic!("trying to disconnect non-existent sender!")
+        }
+        guard.message_sender = None;
+    }
+
+    async fn connect_sender(&mut self, sender: ReconstructedMessagesSender) {
+        let mut guard = self.inner.lock().await;
+        if guard.message_sender.is_some() {
+            // in theory we could just ignore it, but that situation should have never happened
+            // in the first place, so this way we at least know we have an important bug to fix
+            panic!("trying overwrite an existing sender!")
+        }
+
+        // while we're at it, also empty the buffer if we happened to receive anything while
+        // no sender was connected
+        let stored_messages = std::mem::take(&mut guard.messages);
+        if !stored_messages.is_empty() {
+            if let Err(err) = sender.unbounded_send(stored_messages) {
+                error!(
+                    "The sender channel we just received is already invalidated - {:?}",
+                    err
+                );
+                // put the values back to the buffer
+                // the returned error has two fields: err: SendError and val: T,
+                // where val is the value that was failed to get sent;
+                // it's returned by the `into_inner` call
+                guard.messages = err.into_inner();
+                return;
+            }
+        }
+        guard.message_sender = Some(sender);
+    }
+
+    async fn add_reconstructed_messages(&mut self, msgs: Vec<ReconstructedMessage>) {
+        debug!("Adding {:?} new messages to the buffer!", msgs.len());
+        trace!("Adding new messages to the buffer! {:?}", msgs);
+        self.inner.lock().await.messages.extend(msgs)
+    }
+
+    fn process_received_reply(
+        reply_ciphertext: &[u8],
+        reply_key: SurbEncryptionKey,
+    ) -> Option<ReconstructedMessage> {
+        let zero_iv = stream_cipher::zero_iv::<ReplySurbEncryptionAlgorithm>();
+
+        let mut reply_msg = stream_cipher::decrypt::<ReplySurbEncryptionAlgorithm>(
+            reply_key.inner(),
+            &zero_iv,
+            reply_ciphertext,
+        );
+        if let Err(err) = MessageReceiver::remove_padding(&mut reply_msg) {
+            warn!("Received reply had malformed padding! - {:?}", err);
+            None
+        } else {
+            // TODO: perhaps having to say it doesn't have a surb an indication the type should be changed?
+            Some(ReconstructedMessage {
+                message: reply_msg,
+                reply_surb: None,
+            })
+        }
+    }
+
+    async fn handle_new_received(&mut self, msgs: Vec<Vec<u8>>) {
+        debug!(
+            "Processing {:?} new message that might get added to the buffer!",
+            msgs.len()
+        );
+
+        let mut completed_messages = Vec::new();
+        let mut inner_guard = self.inner.lock().await;
+
+        let reply_surb_digest_size = ReplySurbKeyDigestAlgorithm::output_size();
+
+        // first check if this is a reply or a chunked message
+        // TODO: verify with @AP if this way of doing it is safe or whether it could
+        // cause some attacks due to, I don't know, stupid edge case collisions?
+        // Update: this DOES introduce a possible leakage: https://github.com/nymtech/nym/issues/296
+        for msg in msgs {
+            let possible_key_digest =
+                EncryptionKeyDigest::clone_from_slice(&msg[..reply_surb_digest_size]);
+
+            // check first `HasherOutputSize` bytes if they correspond to known encryption key
+            // if yes - this is a reply message
+
+            // TODO: this might be a bottleneck - since the keys are stored on disk we, presumably,
+            // are doing a disk operation every single received fragment
+            if let Some(reply_encryption_key) = self
+                .reply_key_storage
+                .get_and_remove_encryption_key(possible_key_digest)
+                .expect("storage operation failed!")
+            {
+                if let Some(completed_message) = Self::process_received_reply(
+                    &msg[reply_surb_digest_size..],
+                    reply_encryption_key,
+                ) {
+                    completed_messages.push(completed_message)
+                }
+            } else {
+                // otherwise - it's a 'normal' message
+                if let Some(completed_message) = inner_guard.process_received_fragment(msg) {
+                    completed_messages.push(completed_message)
+                }
+            }
+        }
+
+        if !completed_messages.is_empty() {
+            if let Some(sender) = &inner_guard.message_sender {
+                trace!("Sending reconstructed messages to announced sender");
+                if let Err(err) = sender.unbounded_send(completed_messages) {
+                    warn!("The reconstructed message receiver went offline without explicit notification (relevant error: - {:?})", err);
+                    // make sure to drop the lock to not deadlock
+                    // (it is required by `add_reconstructed_messages`)
+                    inner_guard.message_sender = None;
+                    drop(inner_guard);
+                    self.add_reconstructed_messages(err.into_inner()).await;
+                }
+            } else {
+                // make sure to drop the lock to not deadlock
+                // (it is required by `add_reconstructed_messages`)
+                drop(inner_guard);
+                trace!("No sender available - buffering reconstructed messages");
+                self.add_reconstructed_messages(completed_messages).await;
+            }
+        }
+    }
+}
+
+pub enum ReceivedBufferMessage {
+    // Signals a websocket connection (or a native implementation) was established and we should stop buffering messages,
+    // and instead send them directly to the received channel
+    ReceiverAnnounce(ReconstructedMessagesSender),
+
+    // Explicit signal that Receiver connection will no longer accept messages
+    ReceiverDisconnect,
+}
+
+struct RequestReceiver {
+    received_buffer: ReceivedMessagesBuffer,
+    query_receiver: ReceivedBufferRequestReceiver,
+}
+
+impl RequestReceiver {
+    fn new(
+        received_buffer: ReceivedMessagesBuffer,
+        query_receiver: ReceivedBufferRequestReceiver,
+    ) -> Self {
+        RequestReceiver {
+            received_buffer,
+            query_receiver,
+        }
+    }
+
+    fn start(mut self) -> JoinHandle<()> {
+        tokio::spawn(async move {
+            while let Some(request) = self.query_receiver.next().await {
+                match request {
+                    ReceivedBufferMessage::ReceiverAnnounce(sender) => {
+                        self.received_buffer.connect_sender(sender).await;
+                    }
+                    ReceivedBufferMessage::ReceiverDisconnect => {
+                        self.received_buffer.disconnect_sender().await
+                    }
+                }
+            }
+        })
+    }
+}
+
+struct FragmentedMessageReceiver {
+    received_buffer: ReceivedMessagesBuffer,
+    mixnet_packet_receiver: MixnetMessageReceiver,
+}
+
+impl FragmentedMessageReceiver {
+    fn new(
+        received_buffer: ReceivedMessagesBuffer,
+        mixnet_packet_receiver: MixnetMessageReceiver,
+    ) -> Self {
+        FragmentedMessageReceiver {
+            received_buffer,
+            mixnet_packet_receiver,
+        }
+    }
+    fn start(mut self) -> JoinHandle<()> {
+        tokio::spawn(async move {
+            while let Some(new_messages) = self.mixnet_packet_receiver.next().await {
+                self.received_buffer.handle_new_received(new_messages).await;
+            }
+        })
+    }
+}
+
+pub struct ReceivedMessagesBufferController {
+    fragmented_message_receiver: FragmentedMessageReceiver,
+    request_receiver: RequestReceiver,
+}
+
+impl ReceivedMessagesBufferController {
+    pub fn new(
+        local_encryption_keypair: Arc<encryption::KeyPair>,
+        query_receiver: ReceivedBufferRequestReceiver,
+        mixnet_packet_receiver: MixnetMessageReceiver,
+        reply_key_storage: ReplyKeyStorage,
+    ) -> Self {
+        let received_buffer =
+            ReceivedMessagesBuffer::new(local_encryption_keypair, reply_key_storage);
+
+        ReceivedMessagesBufferController {
+            fragmented_message_receiver: FragmentedMessageReceiver::new(
+                received_buffer.clone(),
+                mixnet_packet_receiver,
+            ),
+            request_receiver: RequestReceiver::new(received_buffer, query_receiver),
+        }
+    }
+
+    pub fn start(self) {
+        // TODO: should we do anything with JoinHandle(s) returned by start methods?
+        self.fragmented_message_receiver.start();
+        self.request_receiver.start();
+    }
+}

clients/client-core/src/client/reply_key_storage.rs

@@ -0,0 +1,94 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use log::*;
+use nymsphinx::anonymous_replies::{
+    encryption_key::EncryptionKeyDigest, encryption_key::Unsigned, SurbEncryptionKey,
+    SurbEncryptionKeySize,
+};
+use std::path::Path;
+
+#[derive(Debug)]
+pub enum ReplyKeyStorageError {
+    DbReadError(sled::Error),
+    DbWriteError(sled::Error),
+    DbOpenError(sled::Error),
+}
+
+/// Permanent storage for keys in all sent [`ReplySURB`]
+///
+/// Each sent out [`ReplySURB`] has a new key associated with it that is going to be used for
+/// payload encryption. In order to -decrypt whatever reply we receive, we need to know which
+/// key to use for that purpose. We do it based on received `H(t)` which has to be included
+/// with each reply.
+/// Moreover, there is no restriction when the [`ReplySURB`] might get used so we need to
+/// have a permanent storage for all the keys that we might ever see in the future.
+#[derive(Debug, Clone)]
+pub struct ReplyKeyStorage {
+    db: sled::Db,
+}
+
+impl ReplyKeyStorage {
+    pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, ReplyKeyStorageError> {
+        let db = match sled::open(path) {
+            Err(e) => return Err(ReplyKeyStorageError::DbOpenError(e)),
+            Ok(db) => db,
+        };
+
+        Ok(ReplyKeyStorage { db })
+    }
+
+    fn read_encryption_key(&self, raw_key: sled::IVec) -> SurbEncryptionKey {
+        let key_bytes_ref = raw_key.as_ref();
+        // if this fails it means we have some database corruption and we
+        // absolutely can't continue
+
+        if key_bytes_ref.len() != SurbEncryptionKeySize::to_usize() {
+            error!("REPLY KEY STORAGE DATA CORRUPTION - ENCRYPTION KEY HAS INVALID LENGTH");
+            panic!("REPLY KEY STORAGE DATA CORRUPTION - ENCRYPTION KEY HAS INVALID LENGTH");
+        }
+
+        // this can only fail if the bytes have invalid length but we already asserted it
+        SurbEncryptionKey::try_from_bytes(key_bytes_ref).unwrap()
+    }
+
+    // TOOD: perhaps we could also store some part of original message here too?
+    pub fn insert_encryption_key(
+        &mut self,
+        encryption_key: SurbEncryptionKey,
+    ) -> Result<(), ReplyKeyStorageError> {
+        let digest = encryption_key.compute_digest();
+
+        let insertion_result = match self.db.insert(digest.to_vec(), encryption_key.to_bytes()) {
+            Err(e) => Err(ReplyKeyStorageError::DbWriteError(e)),
+            Ok(existing_key) => {
+                if existing_key.is_some() {
+                    panic!("HASH COLLISION DETECTED")
+                };
+                Ok(())
+            }
+        };
+
+        // TODO: perhaps we could implement some batching mechanism to avoid frequent flushes?
+        self.db.flush().unwrap();
+        insertion_result
+    }
+
+    // Once we use key once, we do not expect to use it again
+    pub fn get_and_remove_encryption_key(
+        &self,
+        key_digest: EncryptionKeyDigest,
+    ) -> Result<Option<SurbEncryptionKey>, ReplyKeyStorageError> {
+        let removal_result = match self.db.remove(&key_digest.to_vec()) {
+            Err(e) => Err(ReplyKeyStorageError::DbReadError(e)),
+            Ok(existing_key) => {
+                Ok(existing_key.map(|existing_key| self.read_encryption_key(existing_key)))
+            }
+        };
+
+        // TODO: not sure how to feel about flushing it every single time here...
+        // same with insertion
+        self.db.flush().unwrap();
+        removal_result
+    }
+}

clients/client-core/src/client/topology_control.rs

@@ -0,0 +1,314 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use log::*;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::params::DEFAULT_NUM_MIX_HOPS;
+use rand::seq::SliceRandom;
+use rand::thread_rng;
+use std::ops::Deref;
+use std::sync::Arc;
+use std::time;
+use std::time::Duration;
+use tokio::sync::{RwLock, RwLockReadGuard};
+use tokio::task::JoinHandle;
+use topology::{nym_topology_from_bonds, NymTopology};
+use url::Url;
+
+// I'm extremely curious why compiler NEVER complained about lack of Debug here before
+#[derive(Debug)]
+pub struct TopologyAccessorInner(Option<NymTopology>);
+
+impl AsRef<Option<NymTopology>> for TopologyAccessorInner {
+    fn as_ref(&self) -> &Option<NymTopology> {
+        &self.0
+    }
+}
+
+impl TopologyAccessorInner {
+    fn new() -> Self {
+        TopologyAccessorInner(None)
+    }
+
+    fn update(&mut self, new: Option<NymTopology>) {
+        self.0 = new;
+    }
+}
+
+pub struct TopologyReadPermit<'a> {
+    permit: RwLockReadGuard<'a, TopologyAccessorInner>,
+}
+
+impl<'a> Deref for TopologyReadPermit<'a> {
+    type Target = TopologyAccessorInner;
+
+    fn deref(&self) -> &Self::Target {
+        &self.permit
+    }
+}
+
+impl<'a> TopologyReadPermit<'a> {
+    /// Using provided topology read permit, tries to get an immutable reference to the underlying
+    /// topology. For obvious reasons the lifetime of the topology reference is bound to the permit.
+    pub(super) fn try_get_valid_topology_ref(
+        &'a self,
+        ack_recipient: &Recipient,
+        packet_recipient: Option<&Recipient>,
+    ) -> Option<&'a NymTopology> {
+        // Note: implicit deref with Deref for TopologyReadPermit is happening here
+        let topology_ref_option = self.permit.as_ref();
+        match topology_ref_option {
+            None => None,
+            Some(topology_ref) => {
+                // see if it's possible to route the packet to both gateways
+                if !topology_ref.can_construct_path_through(DEFAULT_NUM_MIX_HOPS)
+                    || !topology_ref.gateway_exists(ack_recipient.gateway())
+                    || if let Some(packet_recipient) = packet_recipient {
+                        !topology_ref.gateway_exists(packet_recipient.gateway())
+                    } else {
+                        false
+                    }
+                {
+                    None
+                } else {
+                    Some(topology_ref)
+                }
+            }
+        }
+    }
+}
+
+impl<'a> From<RwLockReadGuard<'a, TopologyAccessorInner>> for TopologyReadPermit<'a> {
+    fn from(read_permit: RwLockReadGuard<'a, TopologyAccessorInner>) -> Self {
+        TopologyReadPermit {
+            permit: read_permit,
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct TopologyAccessor {
+    // `RwLock` *seems to* be the better approach for this as write access is only requested every
+    // few seconds, while reads are needed every single packet generated.
+    // However, proper benchmarks will be needed to determine if `RwLock` is indeed a better
+    // approach than a `Mutex`
+    inner: Arc<RwLock<TopologyAccessorInner>>,
+}
+
+impl TopologyAccessor {
+    pub fn new() -> Self {
+        TopologyAccessor {
+            inner: Arc::new(RwLock::new(TopologyAccessorInner::new())),
+        }
+    }
+
+    pub async fn get_read_permit(&self) -> TopologyReadPermit<'_> {
+        self.inner.read().await.into()
+    }
+
+    async fn update_global_topology(&self, new_topology: Option<NymTopology>) {
+        self.inner.write().await.update(new_topology);
+    }
+
+    // only used by the client at startup to get a slightly more reasonable error message
+    // (currently displays as unused because health checker is disabled due to required changes)
+    pub async fn is_routable(&self) -> bool {
+        match &self.inner.read().await.0 {
+            None => false,
+            Some(ref topology) => topology.can_construct_path_through(DEFAULT_NUM_MIX_HOPS),
+        }
+    }
+}
+
+impl Default for TopologyAccessor {
+    fn default() -> Self {
+        TopologyAccessor::new()
+    }
+}
+
+pub struct TopologyRefresherConfig {
+    validator_api_urls: Vec<Url>,
+    refresh_rate: time::Duration,
+    client_version: String,
+}
+
+impl TopologyRefresherConfig {
+    pub fn new(
+        validator_api_urls: Vec<Url>,
+        refresh_rate: time::Duration,
+        client_version: String,
+    ) -> Self {
+        TopologyRefresherConfig {
+            validator_api_urls,
+            refresh_rate,
+            client_version,
+        }
+    }
+}
+
+pub struct TopologyRefresher {
+    validator_client: validator_client::ApiClient,
+    client_version: String,
+
+    validator_api_urls: Vec<Url>,
+    topology_accessor: TopologyAccessor,
+    refresh_rate: Duration,
+
+    currently_used_api: usize,
+    was_latest_valid: bool,
+}
+
+impl TopologyRefresher {
+    pub fn new(mut cfg: TopologyRefresherConfig, topology_accessor: TopologyAccessor) -> Self {
+        cfg.validator_api_urls.shuffle(&mut thread_rng());
+
+        TopologyRefresher {
+            validator_client: validator_client::ApiClient::new(cfg.validator_api_urls[0].clone()),
+            client_version: cfg.client_version,
+            validator_api_urls: cfg.validator_api_urls,
+            topology_accessor,
+            refresh_rate: cfg.refresh_rate,
+            currently_used_api: 0,
+            was_latest_valid: true,
+        }
+    }
+
+    fn use_next_validator_api(&mut self) {
+        if self.validator_api_urls.len() == 1 {
+            warn!("There's only a single validator API available - it won't be possible to use a different one");
+            return;
+        }
+
+        self.currently_used_api = (self.currently_used_api + 1) % self.validator_api_urls.len();
+        self.validator_client
+            .change_validator_api(self.validator_api_urls[self.currently_used_api].clone())
+    }
+
+    /// Verifies whether nodes a reasonably distributed among all mix layers.
+    ///
+    /// In ideal world we would have 33% nodes on layer 1, 33% on layer 2 and 33% on layer 3.
+    /// However, this is a rather unrealistic expectation, instead we check whether there exists
+    /// a layer with more than 66% of nodes or with fewer than 15% and if so, we trigger a failure.
+    ///
+    /// # Arguments
+    ///
+    /// * `topology`: active topology constructed from validator api data
+    /// * `mixnodes_count`: total number of active mixnodes
+    fn check_layer_distribution(
+        &self,
+        active_topology: &NymTopology,
+        mixnodes_count: usize,
+    ) -> bool {
+        let mixes = active_topology.mixes();
+        if active_topology.gateways().is_empty() {
+            return false;
+        }
+
+        // trivial check to see if have at least a single node on each layer (regardless of active set size)
+        if mixes.get(&1).is_none() || mixes.get(&2).is_none() || mixes.get(&3).is_none() {
+            return false;
+        }
+
+        let upper_bound = (mixnodes_count as f32 * 0.66) as usize;
+        let lower_bound = (mixnodes_count as f32 * 0.15) as usize;
+
+        let layer1 = mixes.get(&1).unwrap().len();
+        let layer2 = mixes.get(&2).unwrap().len();
+        let layer3 = mixes.get(&3).unwrap().len();
+
+        if layer1 < lower_bound || layer1 > upper_bound {
+            warn!(
+                "nodes: {}, layer1: {}, layer2: {}, layer3: {}",
+                mixnodes_count, layer1, layer2, layer3
+            );
+            return false;
+        }
+
+        if layer2 < lower_bound || layer2 > upper_bound {
+            warn!(
+                "nodes: {}, layer1: {}, layer2: {}, layer3: {}",
+                mixnodes_count, layer1, layer2, layer3
+            );
+            return false;
+        }
+
+        if layer3 < lower_bound || layer3 > upper_bound {
+            warn!(
+                "nodes: {}, layer1: {}, layer2: {}, layer3: {}",
+                mixnodes_count, layer1, layer2, layer3
+            );
+            return false;
+        }
+
+        true
+    }
+
+    async fn get_current_compatible_topology(&self) -> Option<NymTopology> {
+        // TODO: optimization for the future:
+        // only refresh mixnodes on timer and refresh gateways only when
+        // we have to send to a new, unknown, gateway
+
+        let mixnodes = match self.validator_client.get_cached_active_mixnodes().await {
+            Err(err) => {
+                error!("failed to get network mixnodes - {}", err);
+                return None;
+            }
+            Ok(mixes) => mixes,
+        };
+
+        let gateways = match self.validator_client.get_cached_gateways().await {
+            Err(err) => {
+                error!("failed to get network gateways - {}", err);
+                return None;
+            }
+            Ok(gateways) => gateways,
+        };
+
+        let mixnodes_count = mixnodes.len();
+        let topology =
+            nym_topology_from_bonds(mixnodes, gateways).filter_system_version(&self.client_version);
+
+        if !self.check_layer_distribution(&topology, mixnodes_count) {
+            warn!("The current filtered active topology has extremely skewed layer distribution. It cannot be used.");
+            None
+        } else {
+            Some(topology)
+        }
+    }
+
+    pub async fn refresh(&mut self) {
+        trace!("Refreshing the topology");
+        let new_topology = self.get_current_compatible_topology().await;
+
+        if new_topology.is_none() {
+            self.use_next_validator_api();
+        }
+
+        if new_topology.is_none() && self.was_latest_valid {
+            // if we failed to grab this topology, but the one before it was alright, let's assume
+            // validator had a tiny hiccup and use the old data
+            warn!("we're going to keep on using the old topology for this iteration");
+            self.was_latest_valid = false;
+            return;
+        } else if new_topology.is_some() {
+            self.was_latest_valid = true;
+        }
+
+        self.topology_accessor
+            .update_global_topology(new_topology)
+            .await;
+    }
+
+    pub async fn is_topology_routable(&self) -> bool {
+        self.topology_accessor.is_routable().await
+    }
+
+    pub fn start(mut self) -> JoinHandle<()> {
+        tokio::spawn(async move {
+            loop {
+                tokio::time::sleep(self.refresh_rate).await;
+                self.refresh().await;
+            }
+        })
+    }
+}

clients/client-core/src/config/mod.rs

@@ -0,0 +1,484 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use config::defaults::*;
+use config::NymConfig;
+use serde::{Deserialize, Serialize};
+use std::marker::PhantomData;
+use std::path::PathBuf;
+use std::time::Duration;
+use url::Url;
+
+pub mod persistence;
+
+pub const MISSING_VALUE: &str = "MISSING VALUE";
+
+// 'DEBUG'
+const DEFAULT_ACK_WAIT_MULTIPLIER: f64 = 1.5;
+
+const DEFAULT_ACK_WAIT_ADDITION: Duration = Duration::from_millis(1_500);
+const DEFAULT_LOOP_COVER_STREAM_AVERAGE_DELAY: Duration = Duration::from_millis(200);
+const DEFAULT_MESSAGE_STREAM_AVERAGE_DELAY: Duration = Duration::from_millis(20);
+const DEFAULT_AVERAGE_PACKET_DELAY: Duration = Duration::from_millis(50);
+const DEFAULT_TOPOLOGY_REFRESH_RATE: Duration = Duration::from_secs(5 * 60); // every 5min
+const DEFAULT_TOPOLOGY_RESOLUTION_TIMEOUT: Duration = Duration::from_millis(5_000);
+// Set this to a high value for now, so that we don't risk sporadic timeouts that might cause
+// bought bandwidth tokens to not have time to be spent; Once we remove the gateway from the
+// bandwidth bridging protocol, we can come back to a smaller timeout value
+const DEFAULT_GATEWAY_RESPONSE_TIMEOUT: Duration = Duration::from_secs(5 * 60);
+
+pub fn missing_string_value() -> String {
+    MISSING_VALUE.to_string()
+}
+
+#[derive(Debug, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Config<T> {
+    client: Client<T>,
+
+    #[serde(default)]
+    logging: Logging,
+    #[serde(default)]
+    debug: Debug,
+}
+
+impl<T: NymConfig> Config<T> {
+    pub fn new<S: Into<String>>(id: S) -> Self {
+        let mut cfg = Config::default();
+        cfg.with_id(id);
+        cfg
+    }
+
+    pub fn with_id<S: Into<String>>(&mut self, id: S) {
+        let id = id.into();
+
+        // identity key setting
+        if self.client.private_identity_key_file.as_os_str().is_empty() {
+            self.client.private_identity_key_file =
+                self::Client::<T>::default_private_identity_key_file(&id);
+        }
+        if self.client.public_identity_key_file.as_os_str().is_empty() {
+            self.client.public_identity_key_file =
+                self::Client::<T>::default_public_identity_key_file(&id);
+        }
+
+        // encryption key setting
+        if self
+            .client
+            .private_encryption_key_file
+            .as_os_str()
+            .is_empty()
+        {
+            self.client.private_encryption_key_file =
+                self::Client::<T>::default_private_encryption_key_file(&id);
+        }
+        if self
+            .client
+            .public_encryption_key_file
+            .as_os_str()
+            .is_empty()
+        {
+            self.client.public_encryption_key_file =
+                self::Client::<T>::default_public_encryption_key_file(&id);
+        }
+
+        // shared gateway key setting
+        if self.client.gateway_shared_key_file.as_os_str().is_empty() {
+            self.client.gateway_shared_key_file =
+                self::Client::<T>::default_gateway_shared_key_file(&id);
+        }
+
+        // ack key setting
+        if self.client.ack_key_file.as_os_str().is_empty() {
+            self.client.ack_key_file = self::Client::<T>::default_ack_key_file(&id);
+        }
+
+        if self
+            .client
+            .reply_encryption_key_store_path
+            .as_os_str()
+            .is_empty()
+        {
+            self.client.reply_encryption_key_store_path =
+                self::Client::<T>::default_reply_encryption_key_store_path(&id);
+        }
+
+        #[cfg(not(feature = "coconut"))]
+        if self
+            .client
+            .backup_bandwidth_token_keys_dir
+            .as_os_str()
+            .is_empty()
+        {
+            self.client.backup_bandwidth_token_keys_dir =
+                self::Client::<T>::default_backup_bandwidth_token_keys_dir(&id);
+        }
+
+        self.client.id = id;
+    }
+
+    pub fn with_testnet_mode(&mut self, testnet_mode: bool) {
+        self.client.testnet_mode = testnet_mode;
+    }
+
+    pub fn with_gateway_id<S: Into<String>>(&mut self, id: S) {
+        self.client.gateway_id = id.into();
+    }
+
+    pub fn with_gateway_listener<S: Into<String>>(&mut self, gateway_listener: S) {
+        self.client.gateway_listener = gateway_listener.into();
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    pub fn with_eth_private_key<S: Into<String>>(&mut self, eth_private_key: S) {
+        self.client.eth_private_key = eth_private_key.into();
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    pub fn with_eth_endpoint<S: Into<String>>(&mut self, eth_endpoint: S) {
+        self.client.eth_endpoint = eth_endpoint.into();
+    }
+
+    pub fn set_custom_validator_apis(&mut self, validator_api_urls: Vec<Url>) {
+        self.client.validator_api_urls = validator_api_urls;
+    }
+
+    pub fn set_high_default_traffic_volume(&mut self) {
+        self.debug.average_packet_delay = Duration::from_millis(10);
+        self.debug.loop_cover_traffic_average_delay = Duration::from_millis(2000000); // basically don't really send cover messages
+        self.debug.message_sending_average_delay = Duration::from_millis(4); // 250 "real" messages / s
+    }
+
+    pub fn set_custom_version(&mut self, version: &str) {
+        self.client.version = version.to_string();
+    }
+
+    pub fn get_id(&self) -> String {
+        self.client.id.clone()
+    }
+
+    pub fn get_testnet_mode(&self) -> bool {
+        self.client.testnet_mode
+    }
+
+    pub fn get_nym_root_directory(&self) -> PathBuf {
+        self.client.nym_root_directory.clone()
+    }
+
+    pub fn get_private_identity_key_file(&self) -> PathBuf {
+        self.client.private_identity_key_file.clone()
+    }
+
+    pub fn get_public_identity_key_file(&self) -> PathBuf {
+        self.client.public_identity_key_file.clone()
+    }
+
+    pub fn get_private_encryption_key_file(&self) -> PathBuf {
+        self.client.private_encryption_key_file.clone()
+    }
+
+    pub fn get_public_encryption_key_file(&self) -> PathBuf {
+        self.client.public_encryption_key_file.clone()
+    }
+
+    pub fn get_gateway_shared_key_file(&self) -> PathBuf {
+        self.client.gateway_shared_key_file.clone()
+    }
+
+    pub fn get_reply_encryption_key_store_path(&self) -> PathBuf {
+        self.client.reply_encryption_key_store_path.clone()
+    }
+
+    pub fn get_ack_key_file(&self) -> PathBuf {
+        self.client.ack_key_file.clone()
+    }
+
+    pub fn get_validator_api_endpoints(&self) -> Vec<Url> {
+        self.client.validator_api_urls.clone()
+    }
+
+    pub fn get_gateway_id(&self) -> String {
+        self.client.gateway_id.clone()
+    }
+
+    pub fn get_gateway_listener(&self) -> String {
+        self.client.gateway_listener.clone()
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    pub fn get_backup_bandwidth_token_keys_dir(&self) -> PathBuf {
+        self.client.backup_bandwidth_token_keys_dir.clone()
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    pub fn get_eth_endpoint(&self) -> String {
+        self.client.eth_endpoint.clone()
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    pub fn get_eth_private_key(&self) -> String {
+        self.client.eth_private_key.clone()
+    }
+
+    // Debug getters
+    pub fn get_average_packet_delay(&self) -> Duration {
+        self.debug.average_packet_delay
+    }
+
+    pub fn get_average_ack_delay(&self) -> Duration {
+        self.debug.average_ack_delay
+    }
+
+    pub fn get_ack_wait_multiplier(&self) -> f64 {
+        self.debug.ack_wait_multiplier
+    }
+
+    pub fn get_ack_wait_addition(&self) -> Duration {
+        self.debug.ack_wait_addition
+    }
+
+    pub fn get_loop_cover_traffic_average_delay(&self) -> Duration {
+        self.debug.loop_cover_traffic_average_delay
+    }
+
+    pub fn get_message_sending_average_delay(&self) -> Duration {
+        self.debug.message_sending_average_delay
+    }
+
+    pub fn get_gateway_response_timeout(&self) -> Duration {
+        self.debug.gateway_response_timeout
+    }
+
+    pub fn get_topology_refresh_rate(&self) -> Duration {
+        self.debug.topology_refresh_rate
+    }
+
+    pub fn get_topology_resolution_timeout(&self) -> Duration {
+        self.debug.topology_resolution_timeout
+    }
+
+    pub fn get_version(&self) -> &str {
+        &self.client.version
+    }
+}
+
+impl<T: NymConfig> Default for Config<T> {
+    fn default() -> Self {
+        Config {
+            client: Client::<T>::default(),
+            logging: Default::default(),
+            debug: Default::default(),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize, PartialEq, Serialize)]
+pub struct Client<T> {
+    /// Version of the client for which this configuration was created.
+    #[serde(default = "missing_string_value")]
+    version: String,
+
+    /// ID specifies the human readable ID of this particular client.
+    id: String,
+
+    /// Indicates whether this client is running in a testnet mode, thus attempting
+    /// to claim bandwidth without presenting bandwidth credentials.
+    #[serde(default)]
+    testnet_mode: bool,
+
+    /// Addresses to APIs running on validator from which the client gets the view of the network.
+    validator_api_urls: Vec<Url>,
+
+    /// Path to file containing private identity key.
+    private_identity_key_file: PathBuf,
+
+    /// Path to file containing public identity key.
+    public_identity_key_file: PathBuf,
+
+    /// Path to file containing private encryption key.
+    private_encryption_key_file: PathBuf,
+
+    /// Path to file containing public encryption key.
+    public_encryption_key_file: PathBuf,
+
+    /// Path to file containing shared key derived with the specified gateway that is used
+    /// for all communication with it.
+    gateway_shared_key_file: PathBuf,
+
+    /// Path to file containing key used for encrypting and decrypting the content of an
+    /// acknowledgement so that nobody besides the client knows which packet it refers to.
+    ack_key_file: PathBuf,
+
+    /// Full path to file containing reply encryption keys of all reply-SURBs we have ever
+    /// sent but not received back.
+    reply_encryption_key_store_path: PathBuf,
+
+    /// gateway_id specifies ID of the gateway to which the client should send messages.
+    /// If initially omitted, a random gateway will be chosen from the available topology.
+    gateway_id: String,
+
+    /// Address of the gateway listener to which all client requests should be sent.
+    gateway_listener: String,
+
+    /// Path to directory containing public/private keys used for bandwidth token purchase.
+    /// Those are saved in case of emergency, to be able to reclaim bandwidth tokens.
+    /// The public key is the name of the file, while the private key is the content.
+    #[cfg(not(feature = "coconut"))]
+    backup_bandwidth_token_keys_dir: PathBuf,
+
+    /// Ethereum private key.
+    #[cfg(not(feature = "coconut"))]
+    eth_private_key: String,
+
+    /// Address to an Ethereum full node.
+    #[cfg(not(feature = "coconut"))]
+    eth_endpoint: String,
+
+    /// nym_home_directory specifies absolute path to the home nym Clients directory.
+    /// It is expected to use default value and hence .toml file should not redefine this field.
+    nym_root_directory: PathBuf,
+
+    #[serde(skip)]
+    super_struct: PhantomData<*const T>,
+}
+
+impl<T: NymConfig> Default for Client<T> {
+    fn default() -> Self {
+        // there must be explicit checks for whether id is not empty later
+        Client {
+            version: env!("CARGO_PKG_VERSION").to_string(),
+            id: "".to_string(),
+            testnet_mode: false,
+            validator_api_urls: default_api_endpoints(),
+            private_identity_key_file: Default::default(),
+            public_identity_key_file: Default::default(),
+            private_encryption_key_file: Default::default(),
+            public_encryption_key_file: Default::default(),
+            gateway_shared_key_file: Default::default(),
+            ack_key_file: Default::default(),
+            reply_encryption_key_store_path: Default::default(),
+            gateway_id: "".to_string(),
+            gateway_listener: "".to_string(),
+            #[cfg(not(feature = "coconut"))]
+            backup_bandwidth_token_keys_dir: Default::default(),
+            #[cfg(not(feature = "coconut"))]
+            eth_private_key: "".to_string(),
+            #[cfg(not(feature = "coconut"))]
+            eth_endpoint: "".to_string(),
+            nym_root_directory: T::default_root_directory(),
+            super_struct: Default::default(),
+        }
+    }
+}
+
+impl<T: NymConfig> Client<T> {
+    fn default_private_identity_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("private_identity.pem")
+    }
+
+    fn default_public_identity_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("public_identity.pem")
+    }
+
+    fn default_private_encryption_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("private_encryption.pem")
+    }
+
+    fn default_public_encryption_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("public_encryption.pem")
+    }
+
+    fn default_gateway_shared_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("gateway_shared.pem")
+    }
+
+    fn default_ack_key_file(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("ack_key.pem")
+    }
+
+    fn default_reply_encryption_key_store_path(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("reply_key_store")
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    fn default_backup_bandwidth_token_keys_dir(id: &str) -> PathBuf {
+        T::default_data_directory(Some(id)).join("backup_bandwidth_token_keys")
+    }
+}
+
+#[derive(Debug, Default, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Logging {}
+
+#[derive(Debug, Deserialize, PartialEq, Serialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct Debug {
+    /// The parameter of Poisson distribution determining how long, on average,
+    /// sent packet is going to be delayed at any given mix node.
+    /// So for a packet going through three mix nodes, on average, it will take three times this value
+    /// until the packet reaches its destination.
+    #[serde(with = "humantime_serde")]
+    average_packet_delay: Duration,
+
+    /// The parameter of Poisson distribution determining how long, on average,
+    /// sent acknowledgement is going to be delayed at any given mix node.
+    /// So for an ack going through three mix nodes, on average, it will take three times this value
+    /// until the packet reaches its destination.
+    #[serde(with = "humantime_serde")]
+    average_ack_delay: Duration,
+
+    /// Value multiplied with the expected round trip time of an acknowledgement packet before
+    /// it is assumed it was lost and retransmission of the data packet happens.
+    /// In an ideal network with 0 latency, this value would have been 1.
+    ack_wait_multiplier: f64,
+
+    /// Value added to the expected round trip time of an acknowledgement packet before
+    /// it is assumed it was lost and retransmission of the data packet happens.
+    /// In an ideal network with 0 latency, this value would have been 0.
+    #[serde(with = "humantime_serde")]
+    ack_wait_addition: Duration,
+
+    /// The parameter of Poisson distribution determining how long, on average,
+    /// it is going to take for another loop cover traffic message to be sent.
+    #[serde(with = "humantime_serde")]
+    loop_cover_traffic_average_delay: Duration,
+
+    /// The parameter of Poisson distribution determining how long, on average,
+    /// it is going to take another 'real traffic stream' message to be sent.
+    /// If no real packets are available and cover traffic is enabled,
+    /// a loop cover message is sent instead in order to preserve the rate.
+    #[serde(with = "humantime_serde")]
+    message_sending_average_delay: Duration,
+
+    /// How long we're willing to wait for a response to a message sent to the gateway,
+    /// before giving up on it.
+    #[serde(with = "humantime_serde")]
+    gateway_response_timeout: Duration,
+
+    /// The uniform delay every which clients are querying the directory server
+    /// to try to obtain a compatible network topology to send sphinx packets through.
+    #[serde(with = "humantime_serde")]
+    topology_refresh_rate: Duration,
+
+    /// During topology refresh, test packets are sent through every single possible network
+    /// path. This timeout determines waiting period until it is decided that the packet
+    /// did not reach its destination.
+    #[serde(with = "humantime_serde")]
+    topology_resolution_timeout: Duration,
+}
+
+impl Default for Debug {
+    fn default() -> Self {
+        Debug {
+            average_packet_delay: DEFAULT_AVERAGE_PACKET_DELAY,
+            average_ack_delay: DEFAULT_AVERAGE_PACKET_DELAY,
+            ack_wait_multiplier: DEFAULT_ACK_WAIT_MULTIPLIER,
+            ack_wait_addition: DEFAULT_ACK_WAIT_ADDITION,
+            loop_cover_traffic_average_delay: DEFAULT_LOOP_COVER_STREAM_AVERAGE_DELAY,
+            message_sending_average_delay: DEFAULT_MESSAGE_STREAM_AVERAGE_DELAY,
+            gateway_response_timeout: DEFAULT_GATEWAY_RESPONSE_TIMEOUT,
+            topology_refresh_rate: DEFAULT_TOPOLOGY_REFRESH_RATE,
+            topology_resolution_timeout: DEFAULT_TOPOLOGY_RESOLUTION_TIMEOUT,
+        }
+    }
+}

clients/client-core/src/config/persistence/key_pathfinder.rs

@@ -0,0 +1,66 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::config::Config;
+use config::NymConfig;
+use std::path::{Path, PathBuf};
+
+#[derive(Debug)]
+pub struct ClientKeyPathfinder {
+    identity_private_key: PathBuf,
+    identity_public_key: PathBuf,
+    encryption_private_key: PathBuf,
+    encryption_public_key: PathBuf,
+    gateway_shared_key: PathBuf,
+    ack_key: PathBuf,
+}
+
+impl ClientKeyPathfinder {
+    pub fn new(id: String) -> Self {
+        let os_config_dir = dirs::config_dir().expect("no config directory known for this OS"); // grabs the OS default config dir
+        let config_dir = os_config_dir.join("nym").join("clients").join(id);
+        ClientKeyPathfinder {
+            identity_private_key: config_dir.join("private_identity.pem"),
+            identity_public_key: config_dir.join("public_identity.pem"),
+            encryption_private_key: config_dir.join("public_encryption.pem"),
+            encryption_public_key: config_dir.join("private_encryption.pem"),
+            gateway_shared_key: config_dir.join("gateway_shared.pem"),
+            ack_key: config_dir.join("ack_key.pem"),
+        }
+    }
+
+    pub fn new_from_config<T: NymConfig>(config: &Config<T>) -> Self {
+        ClientKeyPathfinder {
+            identity_private_key: config.get_private_identity_key_file(),
+            identity_public_key: config.get_public_identity_key_file(),
+            encryption_private_key: config.get_private_encryption_key_file(),
+            encryption_public_key: config.get_public_encryption_key_file(),
+            gateway_shared_key: config.get_gateway_shared_key_file(),
+            ack_key: config.get_ack_key_file(),
+        }
+    }
+
+    pub fn private_identity_key(&self) -> &Path {
+        &self.identity_private_key
+    }
+
+    pub fn public_identity_key(&self) -> &Path {
+        &self.identity_public_key
+    }
+
+    pub fn private_encryption_key(&self) -> &Path {
+        &self.encryption_private_key
+    }
+
+    pub fn public_encryption_key(&self) -> &Path {
+        &self.encryption_public_key
+    }
+
+    pub fn gateway_shared_key(&self) -> &Path {
+        &self.gateway_shared_key
+    }
+
+    pub fn ack_key(&self) -> &Path {
+        &self.ack_key
+    }
+}

clients/client-core/src/config/persistence/mod.rs

@@ -0,0 +1,4 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod key_pathfinder;

clients/client-core/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod client;
+pub mod config;

clients/native/Cargo.toml

@@ -0,0 +1,57 @@
+[package]
+name = "nym-client"
+version = "0.12.1"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>", "Jędrzej Stuczyński <andrew@nymtech.net>"]
+edition = "2018"
+rust-version = "1.56"
+
+# 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]
+# dependencies to review:
+futures = "0.3" # bunch of futures stuff, however, now that I think about it, it could perhaps be completely removed
+# the AsyncRead, AsyncWrite, Stream, Sink, etc. traits could be used from tokio
+# channels should really be replaced with crossbeam due to that implementation being more efficient
+# and the single instance of abortable we have should really be refactored anyway
+url = "2.2"
+
+clap = "2.33.0" # for the command line arguments
+dirs = "3.0" # for determining default store directories in config
+dotenv = "0.15.0" # for obtaining environmental variables (only used for RUST_LOG for time being)
+log = "0.4" # self explanatory
+pretty_env_logger = "0.4" # for formatting log messages
+rand = { version = "0.7.3", features = ["wasm-bindgen"] } # rng-related traits + some rng implementation to use
+serde = { version = "1.0.104", features = ["derive"] } # for config serialization/deserialization
+sled = "0.34" # for storage of replySURB decryption keys
+tokio = { version = "1.4", features = ["rt-multi-thread", "net", "signal"] } # async runtime
+tokio-tungstenite = "0.14" # websocket
+
+## internal
+client-core = { path = "../client-core" }
+coconut-interface = { path = "../../common/coconut-interface", optional = true }
+credentials = { path = "../../common/credentials", optional = true }
+config = { path = "../../common/config" }
+crypto = { path = "../../common/crypto" }
+gateway-client = { path = "../../common/client-libs/gateway-client" }
+gateway-requests = { path = "../../gateway/gateway-requests" }
+nymsphinx = { path = "../../common/nymsphinx" }
+pemstore = { path = "../../common/pemstore" }
+topology = { path = "../../common/topology" }
+websocket-requests = { path = "websocket-requests" }
+validator-client = { path = "../../common/client-libs/validator-client" }
+version-checker = { path = "../../common/version-checker" }
+network-defaults = { path = "../../common/network-defaults" }
+
+[features]
+coconut = ["coconut-interface", "credentials", "gateway-requests/coconut", "gateway-client/coconut"]
+eth = []
+
+[dev-dependencies]
+serde_json = "1.0" # for the "textsend" example
+
+[build-dependencies]
+vergen = { version = "5", default-features = false, features = ["build", "git", "rustc", "cargo"] }

clients/native/README.md

@@ -0,0 +1,3 @@
+# Nym Desktop Client
+
+The Nym Desktop Client communicates with the remote, decentralised nodes which make up the Nym system as a whole. 

clients/native/build.rs

@@ -0,0 +1,8 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use vergen::{vergen, Config};
+
+fn main() {
+    vergen(Config::default()).expect("failed to extract build metadata")
+}

clients/native/examples/dummy_file

@@ -0,0 +1,9 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam quis efficitur neque. Quisque aliquet vulputate ante, eget vehicula odio feugiat ac. Nulla ut mattis magna. Aenean tincidunt quis nulla eget eleifend. Cras in pretium sem. Nunc lorem metus, blandit sit amet egestas ut, feugiat quis tellus. Aenean tristique, enim a tincidunt condimentum, eros est blandit nunc, id viverra metus erat at nulla. Vivamus at tellus sodales, feugiat odio vel, laoreet neque. Vivamus posuere nulla ac sodales bibendum.
+
+Vestibulum pulvinar nisi non ultricies egestas. Integer finibus ultrices justo vitae suscipit. Etiam interdum eu justo vel interdum. Morbi sagittis ac nisl quis consequat. Mauris dapibus ut risus ac facilisis. Pellentesque non tortor feugiat, consectetur arcu vel, ullamcorper sapien. Proin sodales purus non orci bibendum, sit amet ultrices justo ullamcorper. Nullam ac risus ac justo ultricies efficitur auctor nec arcu. Etiam sed finibus felis. Suspendisse potenti. Phasellus malesuada velit ac ullamcorper egestas. Sed elementum diam ut est gravida ultricies.
+
+Pellentesque sed metus massa. Cras imperdiet lacus sit amet dolor aliquam, luctus posuere justo hendrerit. Morbi augue ex, gravida a metus sed, scelerisque euismod lacus. Nam consequat sapien ac pellentesque sagittis. Morbi a ultrices massa, vel aliquet ex. Maecenas ac sem diam. Nunc sed erat et ipsum volutpat auctor. Etiam elit felis, commodo vitae ipsum ac, fermentum lobortis arcu. Aliquam eu tempus enim. Curabitur vulputate imperdiet aliquam. Morbi iaculis rhoncus risus at malesuada. Donec accumsan feugiat ligula ut facilisis. Nunc porttitor sit amet est eget malesuada. Sed sed consectetur augue, non dapibus orci. Mauris aliquam pellentesque quam, sit amet pellentesque velit cursus vitae. Morbi sit amet molestie risus.
+
+Nam gravida non ligula a egestas. Fusce sodales, purus id rhoncus mattis, purus est vehicula urna, vel finibus augue velit et est. Donec dictum erat eleifend lobortis iaculis. Praesent id venenatis ante. Donec feugiat, ipsum eget porttitor pulvinar, nisl odio posuere lorem, ut placerat elit nulla a ligula. Suspendisse nec nibh tincidunt, sollicitudin mi a, volutpat ligula. In maximus quam lacus, eget semper dolor sagittis sit amet.
+
+In vitae hendrerit est, quis facilisis dui. In eu ante enim. Nullam hendrerit odio sit amet odio tincidunt eleifend. Aliquam erat volutpat. Curabitur commodo, purus pharetra lobortis rhoncus, tortor massa imperdiet nisl, vel dignissim tortor sem at orci. Aliquam maximus lobortis lacus, eu porttitor purus dapibus ut. Praesent at dapibus felis, efficitur blandit tortor. In hac habitasse platea dictumst. Aenean ultrices, nisl a pretium sagittis, tellus sapien mollis erat, eu consectetur erat mauris sed libero. Duis feugiat dapibus mi, vel ornare velit vehicula mattis. Ut suscipit pharetra leo et sollicitudin.

clients/native/examples/go-examples/websocket/binary/binarysend.go

@@ -0,0 +1,217 @@
+package main
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io/ioutil"
+
+	"github.com/gorilla/websocket"
+)
+
+// request tags
+const sendRequestTag = 0x00
+const replyRequestTag = 0x01
+const selfAddressRequestTag = 0x02
+
+// response tags
+const errorResponseTag = 0x00
+const receivedResponseTag = 0x01
+const selfAddressResponseTag = 0x02
+
+func makeSelfAddressRequest() []byte {
+	return []byte{selfAddressRequestTag}
+}
+
+func parseSelfAddressResponse(rawResponse []byte) []byte {
+	if len(rawResponse) != 97 || rawResponse[0] != selfAddressResponseTag {
+		panic("Received invalid response")
+	}
+	return rawResponse[1:]
+}
+
+func makeSendRequest(recipient []byte, message []byte, withReplySurb bool) []byte {
+	messageLen := make([]byte, 8)
+	binary.BigEndian.PutUint64(messageLen, uint64(len(message)))
+
+	surbByte := byte(0)
+	if withReplySurb {
+		surbByte = 1
+	}
+
+	out := []byte{sendRequestTag, surbByte}
+	out = append(out, recipient...)
+	out = append(out, messageLen...)
+	out = append(out, message...)
+
+	return out
+}
+
+func makeReplyRequest(message []byte, replySURB []byte) []byte {
+	messageLen := make([]byte, 8)
+	binary.BigEndian.PutUint64(messageLen, uint64(len(message)))
+
+	surbLen := make([]byte, 8)
+	binary.BigEndian.PutUint64(surbLen, uint64(len(replySURB)))
+
+	out := []byte{replyRequestTag}
+	out = append(out, surbLen...)
+	out = append(out, replySURB...)
+	out = append(out, messageLen...)
+	out = append(out, message...)
+
+	return out
+}
+
+func parseReceived(rawResponse []byte) ([]byte, []byte) {
+	if rawResponse[0] != receivedResponseTag {
+		panic("Received invalid response!")
+	}
+
+	hasSurb := false
+	if rawResponse[1] == 1 {
+		hasSurb = true
+	} else if rawResponse[1] == 0 {
+		hasSurb = false
+	} else {
+		panic("malformed received response!")
+	}
+
+	data := rawResponse[2:]
+	if hasSurb {
+		surbLen := binary.BigEndian.Uint64(data[:8])
+		other := data[8:]
+
+		surb := other[:surbLen]
+		msgLen := binary.BigEndian.Uint64(other[surbLen : surbLen+8])
+
+		if len(other[surbLen+8:]) != int(msgLen) {
+			panic("invalid msg len")
+		}
+
+		msg := other[surbLen+8:]
+		return msg, surb
+	} else {
+		msgLen := binary.BigEndian.Uint64(data[:8])
+		other := data[8:]
+
+		if len(other) != int(msgLen) {
+			panic("invalid msg len")
+		}
+
+		msg := other[:msgLen]
+		return msg, nil
+	}
+}
+
+func sendBinaryWithoutReply() {
+	uri := "ws://localhost:1977"
+
+	conn, _, err := websocket.DefaultDialer.Dial(uri, nil)
+	if err != nil {
+		panic(err)
+	}
+	defer conn.Close()
+
+	selfAddressRequest := makeSelfAddressRequest()
+	if err = conn.WriteMessage(websocket.BinaryMessage, selfAddressRequest); err != nil {
+		panic(err)
+	}
+	_, receivedResponse, err := conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+	selfAddress := parseSelfAddressResponse(receivedResponse)
+
+	readData, err := ioutil.ReadFile("dummy_file")
+	if err != nil {
+		panic(err)
+	}
+
+	sendRequest := makeSendRequest(selfAddress, readData, false)
+	fmt.Printf("sending content of 'dummy file' over the mix network...\n")
+	if err = conn.WriteMessage(websocket.BinaryMessage, sendRequest); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedResponse, err = conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+
+	fileData, replySURB := parseReceived(receivedResponse)
+	if replySURB != nil {
+		panic("did not expect a replySURB!")
+	}
+	fmt.Printf("writing the file back to the disk!\n")
+	ioutil.WriteFile("received_file_no_reply", fileData, 0644)
+}
+
+func sendBinaryWithReply() {
+	uri := "ws://localhost:1977"
+
+	conn, _, err := websocket.DefaultDialer.Dial(uri, nil)
+	if err != nil {
+		panic(err)
+	}
+	defer conn.Close()
+
+	selfAddressRequest := makeSelfAddressRequest()
+	if err = conn.WriteMessage(websocket.BinaryMessage, selfAddressRequest); err != nil {
+		panic(err)
+	}
+	_, receivedResponse, err := conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+	selfAddress := parseSelfAddressResponse(receivedResponse)
+
+	readData, err := ioutil.ReadFile("dummy_file")
+	if err != nil {
+		panic(err)
+	}
+
+	sendRequest := makeSendRequest(selfAddress, readData, true)
+	fmt.Printf("sending content of 'dummy file' over the mix network...\n")
+	if err = conn.WriteMessage(websocket.BinaryMessage, sendRequest); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedResponse, err = conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+
+	fileData, replySURB := parseReceived(receivedResponse)
+
+	fmt.Printf("writing the file back to the disk!\n")
+	ioutil.WriteFile("received_file_withreply", fileData, 0644)
+
+	replyMessage := []byte("hello from reply SURB! - thanks for sending me the file!")
+	replyRequest := makeReplyRequest(replyMessage, replySURB)
+
+	fmt.Printf("sending '%v' (using reply SURB) over the mix network...\n", string(replyMessage))
+	if err = conn.WriteMessage(websocket.BinaryMessage, replyRequest); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedResponse, err = conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+
+	receivedMessage, replySURB := parseReceived(receivedResponse)
+	if replySURB != nil {
+		panic("did not expect a replySURB!")
+	}
+
+	fmt.Printf("received %v from the mix network!\n", string(receivedMessage))
+
+}
+
+func main() {
+	// sendBinaryWithoutReply()
+	sendBinaryWithReply()
+}

clients/native/examples/go-examples/websocket/binary/dummy_file

@@ -0,0 +1,9 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam quis efficitur neque. Quisque aliquet vulputate ante, eget vehicula odio feugiat ac. Nulla ut mattis magna. Aenean tincidunt quis nulla eget eleifend. Cras in pretium sem. Nunc lorem metus, blandit sit amet egestas ut, feugiat quis tellus. Aenean tristique, enim a tincidunt condimentum, eros est blandit nunc, id viverra metus erat at nulla. Vivamus at tellus sodales, feugiat odio vel, laoreet neque. Vivamus posuere nulla ac sodales bibendum.
+
+Vestibulum pulvinar nisi non ultricies egestas. Integer finibus ultrices justo vitae suscipit. Etiam interdum eu justo vel interdum. Morbi sagittis ac nisl quis consequat. Mauris dapibus ut risus ac facilisis. Pellentesque non tortor feugiat, consectetur arcu vel, ullamcorper sapien. Proin sodales purus non orci bibendum, sit amet ultrices justo ullamcorper. Nullam ac risus ac justo ultricies efficitur auctor nec arcu. Etiam sed finibus felis. Suspendisse potenti. Phasellus malesuada velit ac ullamcorper egestas. Sed elementum diam ut est gravida ultricies.
+
+Pellentesque sed metus massa. Cras imperdiet lacus sit amet dolor aliquam, luctus posuere justo hendrerit. Morbi augue ex, gravida a metus sed, scelerisque euismod lacus. Nam consequat sapien ac pellentesque sagittis. Morbi a ultrices massa, vel aliquet ex. Maecenas ac sem diam. Nunc sed erat et ipsum volutpat auctor. Etiam elit felis, commodo vitae ipsum ac, fermentum lobortis arcu. Aliquam eu tempus enim. Curabitur vulputate imperdiet aliquam. Morbi iaculis rhoncus risus at malesuada. Donec accumsan feugiat ligula ut facilisis. Nunc porttitor sit amet est eget malesuada. Sed sed consectetur augue, non dapibus orci. Mauris aliquam pellentesque quam, sit amet pellentesque velit cursus vitae. Morbi sit amet molestie risus.
+
+Nam gravida non ligula a egestas. Fusce sodales, purus id rhoncus mattis, purus est vehicula urna, vel finibus augue velit et est. Donec dictum erat eleifend lobortis iaculis. Praesent id venenatis ante. Donec feugiat, ipsum eget porttitor pulvinar, nisl odio posuere lorem, ut placerat elit nulla a ligula. Suspendisse nec nibh tincidunt, sollicitudin mi a, volutpat ligula. In maximus quam lacus, eget semper dolor sagittis sit amet.
+
+In vitae hendrerit est, quis facilisis dui. In eu ante enim. Nullam hendrerit odio sit amet odio tincidunt eleifend. Aliquam erat volutpat. Curabitur commodo, purus pharetra lobortis rhoncus, tortor massa imperdiet nisl, vel dignissim tortor sem at orci. Aliquam maximus lobortis lacus, eu porttitor purus dapibus ut. Praesent at dapibus felis, efficitur blandit tortor. In hac habitasse platea dictumst. Aenean ultrices, nisl a pretium sagittis, tellus sapien mollis erat, eu consectetur erat mauris sed libero. Duis feugiat dapibus mi, vel ornare velit vehicula mattis. Ut suscipit pharetra leo et sollicitudin.

clients/native/examples/go-examples/websocket/go.mod

@@ -0,0 +1,7 @@
+module github.com/nymtech/nym/clients/native/examples/go
+
+go 1.14
+
+require (
+	github.com/gorilla/websocket v1.4.2
+)

clients/native/examples/go-examples/websocket/go.sum

@@ -0,0 +1,37 @@
+github.com/aead/siphash v1.0.1/go.mod h1:Nywa3cDsYNNK3gaciGTWPwHt0wlpNV15vwmswBAUSII=
+github.com/btcsuite/btcd v0.20.1-beta/go.mod h1:wVuoA8VJLEcwgqHBwHmzLRazpKxTv13Px/pDuV7OomQ=
+github.com/btcsuite/btclog v0.0.0-20170628155309-84c8d2346e9f/go.mod h1:TdznJufoqS23FtqVCzL0ZqgP5MqXbb4fg/WgDys70nA=
+github.com/btcsuite/btcutil v0.0.0-20190425235716-9e5f4b9a998d/go.mod h1:+5NJ2+qvTyV9exUAL/rxXi3DcLg2Ts+ymUAY5y4NvMg=
+github.com/btcsuite/btcutil v1.0.2 h1:9iZ1Terx9fMIOtq1VrwdqfsATL9MC2l8ZrUY6YZ2uts=
+github.com/btcsuite/btcutil v1.0.2/go.mod h1:j9HUFwoQRsZL3V4n+qG+CUnEGHOarIxfC3Le2Yhbcts=
+github.com/btcsuite/go-socks v0.0.0-20170105172521-4720035b7bfd/go.mod h1:HHNXQzUsZCxOoE+CPiyCTO6x34Zs86zZUiwtpXoGdtg=
+github.com/btcsuite/goleveldb v0.0.0-20160330041536-7834afc9e8cd/go.mod h1:F+uVaaLLH7j4eDXPRvw78tMflu7Ie2bzYOH4Y8rRKBY=
+github.com/btcsuite/snappy-go v0.0.0-20151229074030-0bdef8d06723/go.mod h1:8woku9dyThutzjeg+3xrA5iCpBRH8XEEg3lh6TiUghc=
+github.com/btcsuite/websocket v0.0.0-20150119174127-31079b680792/go.mod h1:ghJtEyQwv5/p4Mg4C0fgbePVuGr935/5ddU9Z3TmDRY=
+github.com/btcsuite/winsvc v1.0.0/go.mod h1:jsenWakMcC0zFBFurPLEAyrnc/teJEM1O46fmI40EZs=
+github.com/davecgh/go-spew v0.0.0-20171005155431-ecdeabc65495/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/gorilla/websocket v1.4.2 h1:+/TMaTYc4QFitKJxsQ7Yye35DkWvkdLcvGKqM+x0Ufc=
+github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
+github.com/jessevdk/go-flags v0.0.0-20141203071132-1679536dcc89/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI=
+github.com/jrick/logrotate v1.0.0/go.mod h1:LNinyqDIJnpAur+b8yyulnQw/wDuN1+BYKlTRt3OuAQ=
+github.com/kkdai/bstream v0.0.0-20161212061736-f391b8402d23/go.mod h1:J+Gs4SYgM6CZQHDETBtE9HaSEkGmuNXF86RwHhHUvq4=
+github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/ginkgo v1.7.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
+github.com/onsi/gomega v1.4.3/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
+golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20200115085410-6d4e4cb37c7d/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
+gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

clients/native/examples/go-examples/websocket/text/dummy_file

@@ -0,0 +1,9 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam quis efficitur neque. Quisque aliquet vulputate ante, eget vehicula odio feugiat ac. Nulla ut mattis magna. Aenean tincidunt quis nulla eget eleifend. Cras in pretium sem. Nunc lorem metus, blandit sit amet egestas ut, feugiat quis tellus. Aenean tristique, enim a tincidunt condimentum, eros est blandit nunc, id viverra metus erat at nulla. Vivamus at tellus sodales, feugiat odio vel, laoreet neque. Vivamus posuere nulla ac sodales bibendum.
+
+Vestibulum pulvinar nisi non ultricies egestas. Integer finibus ultrices justo vitae suscipit. Etiam interdum eu justo vel interdum. Morbi sagittis ac nisl quis consequat. Mauris dapibus ut risus ac facilisis. Pellentesque non tortor feugiat, consectetur arcu vel, ullamcorper sapien. Proin sodales purus non orci bibendum, sit amet ultrices justo ullamcorper. Nullam ac risus ac justo ultricies efficitur auctor nec arcu. Etiam sed finibus felis. Suspendisse potenti. Phasellus malesuada velit ac ullamcorper egestas. Sed elementum diam ut est gravida ultricies.
+
+Pellentesque sed metus massa. Cras imperdiet lacus sit amet dolor aliquam, luctus posuere justo hendrerit. Morbi augue ex, gravida a metus sed, scelerisque euismod lacus. Nam consequat sapien ac pellentesque sagittis. Morbi a ultrices massa, vel aliquet ex. Maecenas ac sem diam. Nunc sed erat et ipsum volutpat auctor. Etiam elit felis, commodo vitae ipsum ac, fermentum lobortis arcu. Aliquam eu tempus enim. Curabitur vulputate imperdiet aliquam. Morbi iaculis rhoncus risus at malesuada. Donec accumsan feugiat ligula ut facilisis. Nunc porttitor sit amet est eget malesuada. Sed sed consectetur augue, non dapibus orci. Mauris aliquam pellentesque quam, sit amet pellentesque velit cursus vitae. Morbi sit amet molestie risus.
+
+Nam gravida non ligula a egestas. Fusce sodales, purus id rhoncus mattis, purus est vehicula urna, vel finibus augue velit et est. Donec dictum erat eleifend lobortis iaculis. Praesent id venenatis ante. Donec feugiat, ipsum eget porttitor pulvinar, nisl odio posuere lorem, ut placerat elit nulla a ligula. Suspendisse nec nibh tincidunt, sollicitudin mi a, volutpat ligula. In maximus quam lacus, eget semper dolor sagittis sit amet.
+
+In vitae hendrerit est, quis facilisis dui. In eu ante enim. Nullam hendrerit odio sit amet odio tincidunt eleifend. Aliquam erat volutpat. Curabitur commodo, purus pharetra lobortis rhoncus, tortor massa imperdiet nisl, vel dignissim tortor sem at orci. Aliquam maximus lobortis lacus, eu porttitor purus dapibus ut. Praesent at dapibus felis, efficitur blandit tortor. In hac habitasse platea dictumst. Aenean ultrices, nisl a pretium sagittis, tellus sapien mollis erat, eu consectetur erat mauris sed libero. Duis feugiat dapibus mi, vel ornare velit vehicula mattis. Ut suscipit pharetra leo et sollicitudin.

clients/native/examples/go-examples/websocket/text/textsend.go

@@ -0,0 +1,134 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/gorilla/websocket"
+)
+
+func getSelfAddress(conn *websocket.Conn) string {
+	selfAddressRequest, err := json.Marshal(map[string]string{"type": "selfAddress"})
+	if err != nil {
+		panic(err)
+	}
+
+	if err = conn.WriteMessage(websocket.TextMessage, []byte(selfAddressRequest)); err != nil {
+		panic(err)
+	}
+
+	responseJSON := make(map[string]interface{})
+	err = conn.ReadJSON(&responseJSON)
+	if err != nil {
+		panic(err)
+	}
+
+	return responseJSON["address"].(string)
+}
+
+func sendTextWithoutReply() {
+	message := "Hello Nym!"
+
+	uri := "ws://localhost:1977"
+
+	conn, _, err := websocket.DefaultDialer.Dial(uri, nil)
+	if err != nil {
+		panic(err)
+	}
+	defer conn.Close()
+
+	selfAddress := getSelfAddress(conn)
+	fmt.Printf("our address is: %v\n", selfAddress)
+	sendRequest, err := json.Marshal(map[string]interface{}{
+		"type":          "send",
+		"recipient":     selfAddress,
+		"message":       message,
+		"withReplySurb": false,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("sending '%v' (*without* reply SURB) over the mix network...\n", message)
+	if err = conn.WriteMessage(websocket.TextMessage, []byte(sendRequest)); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedMessage, err := conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("received %v from the mix network!\n", string(receivedMessage))
+}
+
+func sendTextWithReply() {
+	message := "Hello Nym!"
+
+	uri := "ws://localhost:1977"
+
+	conn, _, err := websocket.DefaultDialer.Dial(uri, nil)
+	if err != nil {
+		panic(err)
+	}
+	defer conn.Close()
+
+	selfAddress := getSelfAddress(conn)
+	fmt.Printf("our address is: %v\n", selfAddress)
+	sendRequest, err := json.Marshal(map[string]interface{}{
+		"type":          "send",
+		"recipient":     selfAddress,
+		"message":       message,
+		"withReplySurb": true,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("sending '%v' (*with* reply SURB) over the mix network...\n", message)
+	if err = conn.WriteMessage(websocket.TextMessage, []byte(sendRequest)); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedMessage, err := conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("received %v from the mix network!\n", string(receivedMessage))
+
+	receivedMessageJSON := make(map[string]interface{})
+	if err := json.Unmarshal(receivedMessage, &receivedMessageJSON); err != nil {
+		panic(err)
+	}
+
+	// use the received surb to send an anonymous reply!
+	replySurb := receivedMessageJSON["replySurb"]
+	replyMessage := "hello from reply SURB!"
+
+	reply, err := json.Marshal(map[string]interface{}{
+		"type":      "reply",
+		"message":   replyMessage,
+		"replySurb": replySurb,
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("sending '%v' (using reply SURB) over the mix network...\n", replyMessage)
+	if err = conn.WriteMessage(websocket.TextMessage, []byte(reply)); err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("waiting to receive a message from the mix network...\n")
+	_, receivedMessage, err = conn.ReadMessage()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("received %v from the mix network!\n", string(receivedMessage))
+}
+
+func main() {
+	// sendTextWithoutReply()
+	sendTextWithReply()
+}

clients/native/examples/js-examples/websocket/.gitignore

@@ -0,0 +1,2 @@
+dist/bundle.js
+node_modules

clients/native/examples/js-examples/websocket/README.md

@@ -0,0 +1,10 @@
+### Prerequisites
+
+* Reasonably up to date Node + `npm`
+
+### Running it
+
+```
+npm install 
+npm start # starts a webserver on port 8888
+```

clients/native/examples/js-examples/websocket/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nym-client-websocket-demo",
+  "version": "0.7.0",
+  "description": "Connect to a local Nym client, send and retrieve from the Nym network. ",
+  "private": true,
+  "scripts": {
+    "build": "webpack",
+    "start": "webpack-dev-server"
+  },
+  "keywords": [
+    "nym",
+    "anonymity",
+    "mixnet",
+    "client",
+    "rust",
+    "websockets"
+  ],
+  "author": "Dave Hrycyszyn",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "autoprefixer": "^10.2.6",
+    "clean-webpack-plugin": "^3.0.0",
+    "webpack": "^4.42.1",
+    "webpack-cli": "^3.3.11",
+    "webpack-dev-server": "^3.11.0"
+  },
+  "dependencies": {
+    "core-js": "^3.6.5",
+    "html-webpack-plugin": "^4.2.0"
+  }
+}

clients/native/examples/js-examples/websocket/src/index.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nym Client Demo</title>
+</head>
+
+<body>
+    <label for="fname">Text to send: </label><input type="text" id="sendtext" name="sendtext" value="Hello mixnet!">
+    <input type="checkbox" id="with-surb" name="with-surb">
+    <label for="with-surb"> Attach Reply SURB </label><br>
+
+    <button id="send-button">Send</button>
+
+    <p>Send messages to the mixnet using the "send" button.</p>
+    <p><span style='color: blue;'>Sent</span> messages show in blue, <span style='color: green;'>received</span>
+        messages show in green.</p>
+
+    <hr>
+    <p>
+        <span id="output"></div>
+    </p>
+</body>
+
+</html>

clients/native/examples/js-examples/websocket/src/index.js

@@ -0,0 +1,173 @@
+var ourAddress;
+var connection;
+
+// Please note that this javascript is extremely bad, it's only purpose is to show some basic API calls, not how
+// a proper application should have been written.
+
+async function main() {
+    var port = '1977' // client websocket listens on 1977 by default, change if yours is different
+    var localClientUrl = "ws://127.0.0.1:" + port;
+
+    // Set up and handle websocket connection to our desktop client.
+    connection = await connectWebsocket(localClientUrl).then(function (c) {
+        return c;
+    }).catch(function (err) {
+        display("Websocket connection error. Is the client running with <pre>--connection-type WebSocket</pre> on port " + port + "?");
+    })
+    connection.onmessage = function (e) {
+        handleResponse(e);
+    };
+
+    sendSelfAddressRequest();
+
+    // Set up the send button
+    const sendButton = document.querySelector('#send-button');
+    sendButton.onclick = function () {
+        sendMessageToMixnet();
+    }
+}
+
+// Handle any messages that come back down the websocket. 
+function handleResponse(resp) {
+    // hacky workaround for receiving pushed 'text' messages,
+    // basically we can either receive proper server responses, i.e. 'error', 'send', 'selfAddress'
+    // or actual messages, without any framing, so they do not have 'type' field
+    try {
+        let response = JSON.parse(resp.data);
+        if (response.type == "error") {
+            displayJsonResponseWithoutReply("Server responded with error: " + response.message);
+        } else if (response.type == "selfAddress") {
+            displayJsonResponseWithoutReply(response);
+            ourAddress = response.address;
+            display("Our address is:  " + ourAddress + ", we will now send messages to ourself.");
+        } else if (response.type == "received") {
+            handleReceivedTextMessage(response)
+        }
+    } catch (_) {
+        displayJsonResponseWithoutReply(resp.data)
+    }
+}
+
+
+function handleReceivedTextMessage(message) {
+    console.log("received a message!")
+    const text = message.message
+    const replySurb = message.replySurb
+
+    if (replySurb != null) {
+        displayJsonResponseWithReply(text, replySurb)
+    } else {
+        displayJsonResponseWithoutReply(text)
+    }
+}
+
+// Send a message to the mixnet. 
+function sendMessageToMixnet() {
+    const sendText = document.getElementById("sendtext").value;
+    const surbCheckbox = document.querySelector('#with-surb');
+    const attachReplySURB = surbCheckbox.checked;
+
+    const message = {
+        type: "send",
+        message: sendText,
+        recipient: ourAddress,
+        withReplySurb: attachReplySURB,
+    }
+
+    displayJsonResponseWithoutReply(message);
+    connection.send(JSON.stringify(message));
+}
+
+function sendReplyMessageToMixnet(messageContent, replySurb) {
+    const message = {
+        type: "reply",
+        message: messageContent,
+        replySurb: replySurb,
+    }
+
+    displayJsonResponseWithoutReply(message);
+    connection.send(JSON.stringify(message));
+}
+
+// Send a message to the mixnet client, asking what our own address is. 
+// In this simplistic demo, we'll just use our own address to send ourselves messages. 
+//
+// In a real application, you might want to ensure that somebody else got your
+// address so that they could send messages to you. 
+function sendSelfAddressRequest() {
+    var selfAddress = {
+        type: "selfAddress"
+    }
+    displayJsonSend(selfAddress);
+    connection.send(JSON.stringify(selfAddress));
+}
+
+function display(message) {
+    document.getElementById("output").innerHTML += "<p>" + message + "</p >";
+}
+
+function displayJsonSend(message) {
+    let sendDiv = document.createElement("div")
+    let paragraph = document.createElement("p")
+    paragraph.setAttribute('style', 'color: blue')
+    let paragraphContent = document.createTextNode("sent >>> " + JSON.stringify(message))
+    paragraph.appendChild(paragraphContent)
+
+    sendDiv.appendChild(paragraph)
+    document.getElementById("output").appendChild(sendDiv)
+}
+
+function displayJsonResponseWithoutReply(message) {
+    let receivedDiv = document.createElement("div")
+    let paragraph = document.createElement("p")
+    paragraph.setAttribute('style', 'color: green')
+    let paragraphContent = document.createTextNode("received >>> " + JSON.stringify(message) + "(NO REPLY AVAILABLE)")
+    paragraph.appendChild(paragraphContent)
+
+    receivedDiv.appendChild(paragraph)
+    document.getElementById("output").appendChild(receivedDiv)
+}
+
+function displayJsonResponseWithReply(message, replySurb) {
+    let replyBox = document.createElement("input")
+    replyBox.setAttribute('type', 'text');
+    replyBox.setAttribute('value', 'type your anonymous reply here!');
+    replyBox.setAttribute('size', 50);
+
+    let sendButton = document.createElement("button")
+    let buttonText = document.createTextNode("Send")
+    sendButton.appendChild(buttonText)
+
+    sendButton.onclick = () => {
+        sendReplyMessageToMixnet(replyBox.value, replySurb)
+    }
+
+    let receivedDiv = document.createElement("div")
+    let paragraph = document.createElement("p")
+    paragraph.setAttribute('style', 'color: green')
+    let paragraphContent = document.createTextNode("received >>> " + JSON.stringify(message) + "(HERE BE SURB)")
+    paragraph.appendChild(paragraphContent)
+
+    receivedDiv.appendChild(paragraph)
+    receivedDiv.appendChild(replyBox)
+    receivedDiv.appendChild(sendButton)
+
+    document.getElementById("output").appendChild(receivedDiv)
+}
+
+// Connect to a websocket. 
+function connectWebsocket(url) {
+    return new Promise(function (resolve, reject) {
+        var server = new WebSocket(url);
+        server.onopen = function () {
+            resolve(server);
+        };
+        server.onerror = function (err) {
+            reject(err);
+        };
+
+    });
+}
+
+// Start it!
+main();

clients/native/examples/js-examples/websocket/webpack.config.js

@@ -0,0 +1,25 @@
+const autoprefixer = require('autoprefixer');
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const { CleanWebpackPlugin } = require('clean-webpack-plugin');
+
+module.exports = {
+    entry: './src/index.js',
+    output: {
+        filename: 'bundle.js',
+        // path: path.resolve(__dirname, 'dist'),
+    },
+    plugins: [
+        new CleanWebpackPlugin(),
+        new HtmlWebpackPlugin({
+            hash: true,
+            template: './src/index.html',
+            filename: '.././dist/index.html' //relative to root of the application
+        })
+    ],
+    devServer: {
+        contentBase: path.join(__dirname, 'dist'),
+        compress: true,
+        port: 8888
+    }
+};

clients/native/examples/python-examples/websocket/Pipfile

@@ -0,0 +1,14 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+base58 = "*"
+websockets = "*"
+asyncio = "*"
+
+[requires]
+python_version = "3.8"

clients/native/examples/python-examples/websocket/Pipfile.lock

@@ -0,0 +1,78 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "f72ba1bebddbc91273647a33428eb911071d256cf3fc20e04f51060a7610f293"
+        },
+        "pipfile-spec": 6,
+        "requires": {
+            "python_version": "3.8"
+        },
+        "sources": [
+            {
+                "name": "pypi",
+                "url": "https://pypi.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {
+        "asyncio": {
+            "hashes": [
+                "sha256:83360ff8bc97980e4ff25c964c7bd3923d333d177aa4f7fb736b019f26c7cb41",
+                "sha256:b62c9157d36187eca799c378e572c969f0da87cd5fc42ca372d92cdb06e7e1de",
+                "sha256:c46a87b48213d7464f22d9a497b9eef8c1928b68320a2fa94240f969f6fec08c",
+                "sha256:c4d18b22701821de07bd6aea8b53d21449ec0ec5680645e5317062ea21817d2d"
+            ],
+            "index": "pypi",
+            "version": "==3.4.3"
+        },
+        "base58": {
+            "hashes": [
+                "sha256:4c7f5687da771b519cf86b3236250e7c3543368c576404c9fe2d992a287666e0",
+                "sha256:c83584a8b917dc52dd634307137f2ad2721a9efb4f1de32fc7eaaaf87844177e"
+            ],
+            "index": "pypi",
+            "version": "==2.0.0"
+        },
+        "websockets": {
+            "hashes": [
+                "sha256:0dd4eb8e0bbf365d6f652711ce21b8fd2b596f873d32aabb0fbb53ec604418cc",
+                "sha256:1d0971cc7251aeff955aa742ec541ee8aaea4bb2ebf0245748fbec62f744a37e",
+                "sha256:1d6b4fddb12ab9adf87b843cd4316c4bd602db8d5efd2fb83147f0458fe85135",
+                "sha256:230a3506df6b5f446fed2398e58dcaafdff12d67fe1397dff196411a9e820d02",
+                "sha256:276d2339ebf0df4f45df453923ebd2270b87900eda5dfd4a6b0cfa15f82111c3",
+                "sha256:2cf04601633a4ec176b9cc3d3e73789c037641001dbfaf7c411f89cd3e04fcaf",
+                "sha256:3ddff38894c7857c476feb3538dd847514379d6dc844961dc99f04b0384b1b1b",
+                "sha256:48c222feb3ced18f3dc61168ca18952a22fb88e5eb8902d2bf1b50faefdc34a2",
+                "sha256:51d04df04ed9d08077d10ccbe21e6805791b78eac49d16d30a1f1fe2e44ba0af",
+                "sha256:597c28f3aa7a09e8c070a86b03107094ee5cdafcc0d55f2f2eac92faac8dc67d",
+                "sha256:5c8f0d82ea2468282e08b0cf5307f3ad022290ed50c45d5cb7767957ca782880",
+                "sha256:7189e51955f9268b2bdd6cc537e0faa06f8fffda7fb386e5922c6391de51b077",
+                "sha256:7df3596838b2a0c07c6f6d67752c53859a54993d4f062689fdf547cb56d0f84f",
+                "sha256:826ccf85d4514609219725ba4a7abd569228c2c9f1968e8be05be366f68291ec",
+                "sha256:836d14eb53b500fd92bd5db2fc5894f7c72b634f9c2a28f546f75967503d8e25",
+                "sha256:85db8090ba94e22d964498a47fdd933b8875a1add6ebc514c7ac8703eb97bbf0",
+                "sha256:85e701a6c316b7067f1e8675c638036a796fe5116783a4c932e7eb8e305a3ffe",
+                "sha256:900589e19200be76dd7cbaa95e9771605b5ce3f62512d039fb3bc5da9014912a",
+                "sha256:9147868bb0cc01e6846606cd65cbf9c58598f187b96d14dd1ca17338b08793bb",
+                "sha256:9e7fdc775fe7403dbd8bc883ba59576a6232eac96dacb56512daacf7af5d618d",
+                "sha256:ab5ee15d3462198c794c49ccd31773d8a2b8c17d622aa184f669d2b98c2f0857",
+                "sha256:ad893d889bc700a5835e0a95a3e4f2c39e91577ab232a3dc03c262a0f8fc4b5c",
+                "sha256:b2e71c4670ebe1067fa8632f0d081e47254ee2d3d409de54168b43b0ba9147e0",
+                "sha256:b43b13e5622c5a53ab12f3272e6f42f1ce37cd5b6684b2676cb365403295cd40",
+                "sha256:b4ad84b156cf50529b8ac5cc1638c2cf8680490e3fccb6121316c8c02620a2e4",
+                "sha256:be5fd35e99970518547edc906efab29afd392319f020c3c58b0e1a158e16ed20",
+                "sha256:caa68c95bc1776d3521f81eeb4d5b9438be92514ec2a79fececda814099c8314",
+                "sha256:d144b350045c53c8ff09aa1cfa955012dd32f00c7e0862c199edcabb1a8b32da",
+                "sha256:d2c2d9b24d3c65b5a02cac12cbb4e4194e590314519ed49db2f67ef561c3cf58",
+                "sha256:e9e5fd6dbdf95d99bc03732ded1fc8ef22ebbc05999ac7e0c7bf57fe6e4e5ae2",
+                "sha256:ebf459a1c069f9866d8569439c06193c586e72c9330db1390af7c6a0a32c4afd",
+                "sha256:f31722f1c033c198aa4a39a01905951c00bd1c74f922e8afc1b1c62adbcdd56a",
+                "sha256:f68c352a68e5fdf1e97288d5cec9296664c590c25932a8476224124aaf90dbcd"
+            ],
+            "index": "pypi",
+            "version": "==9.1"
+        }
+    },
+    "develop": {}
+}

clients/native/examples/python-examples/websocket/binarysend.py

@@ -0,0 +1,139 @@
+import asyncio
+import websockets
+from pathlib import Path
+import struct
+
+# request tags
+SEND_REQUEST_TAG = 0x00
+REPLY_REQUEST_TAG = 0x01
+SELF_ADDRESS_REQUEST_TAG = 0x02
+
+# response tags
+ERROR_RESPONSE_TAG = 0x00
+RECEIVED_RESPONSE_TAG = 0x01
+SELF_ADDRESS_RESPONSE_TAG = 0x02
+
+
+def make_self_address_request() -> bytes:
+    return bytes([SELF_ADDRESS_REQUEST_TAG])
+
+
+def parse_self_address_response(raw_response: bytes) -> bytes:
+    if len(raw_response) != 97 or raw_response[0] != SELF_ADDRESS_RESPONSE_TAG:
+        print('Received invalid response!')
+        raise
+
+    return raw_response[1:]
+
+
+def make_send_request(recipient: bytes, message: bytes, with_reply_surb: bool) -> bytes:
+    # a big endian uint64
+    message_len = len(message).to_bytes(length=8, byteorder='big', signed=False)
+
+    return bytes([SEND_REQUEST_TAG]) + bytes([with_reply_surb]) + recipient + message_len + message
+
+
+def make_reply_request(message: bytes, reply_surb: bytes) -> bytes:
+    message_len = len(message).to_bytes(length=8, byteorder='big', signed=False)
+    surb_len = len(reply_surb).to_bytes(length=8, byteorder='big', signed=False)
+
+    return bytes([REPLY_REQUEST_TAG]) + surb_len + reply_surb + message_len + message
+
+
+# it should have structure of RECEIVED_RESPONSE_TAG || with_reply || (surb_len || surb) || msg_len || msg
+# where surb_len || surb is only present if 'with_reply' is true
+def parse_received(raw_response: bytes) -> (bytes, bytes):
+    if raw_response[0] != RECEIVED_RESPONSE_TAG:
+        print('Received invalid response!')
+        raise
+
+    if raw_response[1] == 1:
+        has_surb = True
+    elif raw_response[1] == 0:
+        has_surb = False
+    else:
+        print("malformed received response!")
+        raise
+
+    data = raw_response[2:]
+    if has_surb:
+        (surb_len,), other = struct.unpack(">Q", data[:8]), data[8:]
+        surb = other[:surb_len]
+        (msg_len,) = struct.unpack(">Q", other[surb_len:surb_len + 8])
+
+        if len(other[surb_len + 8:]) != msg_len:
+            print("invalid msg len")
+            raise
+
+        msg = other[surb_len + 8:]
+        return msg, surb
+    else:
+        (msg_len,), other = struct.unpack(">Q", data[:8]), data[8:]
+        if len(other) != msg_len:
+            print("invalid msg len")
+            raise
+
+        msg = other[:msg_len]
+        return msg, None
+
+
+async def send_file_with_reply():
+    uri = "ws://localhost:1977"
+    async with websockets.connect(uri) as websocket:
+        self_address_req = make_self_address_request()
+        await websocket.send(self_address_req)
+
+        self_address = parse_self_address_response(await websocket.recv())
+        file_data = Path('dummy_file').read_bytes()
+
+        send_request = make_send_request(self_address, file_data, True)
+        print("sending content of 'dummy_file' over the mix network...")
+        await websocket.send(send_request)
+
+        print("waiting to receive the 'dummy_file' from the mix network...")
+        received_response = await websocket.recv()
+        received_file, surb = parse_received(received_response)
+
+        with open("received_file_withreply", "wb") as output_file:
+            print("writing the file back to the disk!")
+            output_file.write(received_file)
+
+        reply_message = b"hello from reply SURB! - thanks for sending me the file!"
+        reply_request = make_reply_request(reply_message, surb)
+
+        print("sending '{}' (using reply SURB!) over the mix network...".format(reply_message))
+        await websocket.send(reply_request)
+
+        print("waiting to receive a message from the mix network...")
+        received_response = await websocket.recv()
+        received_msg, surb = parse_received(received_response)
+        assert surb is None  # no surbs in replies!
+
+        print("received '{}' from the mix network".format(received_msg))
+
+
+async def send_file_without_reply():
+    uri = "ws://localhost:1977"
+    async with websockets.connect(uri) as websocket:
+        self_address_req = make_self_address_request()
+        await websocket.send(self_address_req)
+
+        self_address = parse_self_address_response(await websocket.recv())
+        file_data = Path('dummy_file').read_bytes()
+
+        send_request = make_send_request(self_address, file_data, False)
+        print("sending content of 'dummy_file' over the mix network...")
+        await websocket.send(send_request)
+
+        print("waiting to receive the 'dummy_file' from the mix network...")
+        received_response = await websocket.recv()
+        received_file, surb = parse_received(received_response)
+        assert surb is None  # we didn't attach a surb so we expect a None here!
+
+        with open("received_file_noreply", "wb") as output_file:
+            print("writing the file back to the disk!")
+            output_file.write(received_file)
+
+
+# asyncio.get_event_loop().run_until_complete(send_file_without_reply())
+asyncio.get_event_loop().run_until_complete(send_file_with_reply())

clients/native/examples/python-examples/websocket/dummy_file

@@ -0,0 +1,9 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam quis efficitur neque. Quisque aliquet vulputate ante, eget vehicula odio feugiat ac. Nulla ut mattis magna. Aenean tincidunt quis nulla eget eleifend. Cras in pretium sem. Nunc lorem metus, blandit sit amet egestas ut, feugiat quis tellus. Aenean tristique, enim a tincidunt condimentum, eros est blandit nunc, id viverra metus erat at nulla. Vivamus at tellus sodales, feugiat odio vel, laoreet neque. Vivamus posuere nulla ac sodales bibendum.
+
+Vestibulum pulvinar nisi non ultricies egestas. Integer finibus ultrices justo vitae suscipit. Etiam interdum eu justo vel interdum. Morbi sagittis ac nisl quis consequat. Mauris dapibus ut risus ac facilisis. Pellentesque non tortor feugiat, consectetur arcu vel, ullamcorper sapien. Proin sodales purus non orci bibendum, sit amet ultrices justo ullamcorper. Nullam ac risus ac justo ultricies efficitur auctor nec arcu. Etiam sed finibus felis. Suspendisse potenti. Phasellus malesuada velit ac ullamcorper egestas. Sed elementum diam ut est gravida ultricies.
+
+Pellentesque sed metus massa. Cras imperdiet lacus sit amet dolor aliquam, luctus posuere justo hendrerit. Morbi augue ex, gravida a metus sed, scelerisque euismod lacus. Nam consequat sapien ac pellentesque sagittis. Morbi a ultrices massa, vel aliquet ex. Maecenas ac sem diam. Nunc sed erat et ipsum volutpat auctor. Etiam elit felis, commodo vitae ipsum ac, fermentum lobortis arcu. Aliquam eu tempus enim. Curabitur vulputate imperdiet aliquam. Morbi iaculis rhoncus risus at malesuada. Donec accumsan feugiat ligula ut facilisis. Nunc porttitor sit amet est eget malesuada. Sed sed consectetur augue, non dapibus orci. Mauris aliquam pellentesque quam, sit amet pellentesque velit cursus vitae. Morbi sit amet molestie risus.
+
+Nam gravida non ligula a egestas. Fusce sodales, purus id rhoncus mattis, purus est vehicula urna, vel finibus augue velit et est. Donec dictum erat eleifend lobortis iaculis. Praesent id venenatis ante. Donec feugiat, ipsum eget porttitor pulvinar, nisl odio posuere lorem, ut placerat elit nulla a ligula. Suspendisse nec nibh tincidunt, sollicitudin mi a, volutpat ligula. In maximus quam lacus, eget semper dolor sagittis sit amet.
+
+In vitae hendrerit est, quis facilisis dui. In eu ante enim. Nullam hendrerit odio sit amet odio tincidunt eleifend. Aliquam erat volutpat. Curabitur commodo, purus pharetra lobortis rhoncus, tortor massa imperdiet nisl, vel dignissim tortor sem at orci. Aliquam maximus lobortis lacus, eu porttitor purus dapibus ut. Praesent at dapibus felis, efficitur blandit tortor. In hac habitasse platea dictumst. Aenean ultrices, nisl a pretium sagittis, tellus sapien mollis erat, eu consectetur erat mauris sed libero. Duis feugiat dapibus mi, vel ornare velit vehicula mattis. Ut suscipit pharetra leo et sollicitudin.

clients/native/examples/python-examples/websocket/textsend.py

@@ -0,0 +1,77 @@
+import asyncio
+import json
+import websockets
+
+self_address_request = json.dumps({
+    "type": "selfAddress"
+})
+
+
+async def send_text_without_reply():
+    message = "Hello Nym!"
+
+    uri = "ws://localhost:1977"
+    async with websockets.connect(uri) as websocket:
+        await websocket.send(self_address_request)
+        self_address = json.loads(await websocket.recv())
+        print("our address is: {}".format(self_address["address"]))
+
+        text_send = json.dumps({
+            "type": "send",
+            "message": message,
+            "recipient": self_address["address"],
+            "withReplySurb": False,
+        })
+
+        print("sending '{}' (*without* reply SURB) over the mix network...".format(message))
+        await websocket.send(text_send)
+
+        print("waiting to receive a message from the mix network...")
+        received_message = await websocket.recv()
+        print("received '{}' from the mix network".format(received_message))
+
+
+async def send_text_with_reply():
+    message = "Hello Nym!"
+
+    uri = "ws://localhost:1977"
+    async with websockets.connect(uri) as websocket:
+        await websocket.send(self_address_request)
+        self_address = json.loads(await websocket.recv())
+        print("our address is: {}".format(self_address["address"]))
+
+        text_send = json.dumps({
+            "type": "send",
+            "message": message,
+            "recipient": self_address["address"],
+            "withReplySurb": True,
+        })
+
+        print("sending '{}' (*with* reply SURB) over the mix network...".format(message))
+        await websocket.send(text_send)
+
+        print("waiting to receive a message from the mix network...")
+        received_message = json.loads(await websocket.recv())
+        print("received '{}' from the mix network".format(received_message))
+
+        # use the received surb to send an anonymous reply!
+        reply_surb = received_message["replySurb"]
+
+        reply_message = "hello from reply SURB!"
+        reply = json.dumps({
+            "type": "reply",
+            "message": reply_message,
+            "replySurb": reply_surb
+        })
+
+        print("sending '{}' (using reply SURB!) over the mix network...".format(reply_message))
+        await websocket.send(reply)
+
+        print("waiting to receive a message from the mix network...")
+        received_message = await websocket.recv()
+        print("received '{}' from the mix network".format(received_message))
+
+
+
+# asyncio.get_event_loop().run_until_complete(send_text_without_reply())
+asyncio.get_event_loop().run_until_complete(send_text_with_reply())

clients/native/examples/websocket_binarysend.rs

@@ -0,0 +1,119 @@
+use futures::{SinkExt, StreamExt};
+use nymsphinx::addressing::clients::Recipient;
+use tokio::net::TcpStream;
+use tokio_tungstenite::{
+    connect_async, tungstenite::protocol::Message, MaybeTlsStream, WebSocketStream,
+};
+use websocket_requests::{requests::ClientRequest, responses::ServerResponse};
+
+// just helpers functions that work in this very particular context because we are sending to ourselves
+// and hence will always get a response back (i.e. the message we sent)
+async fn send_message_and_get_response(
+    ws_stream: &mut WebSocketStream<MaybeTlsStream<TcpStream>>,
+    req: Vec<u8>,
+) -> ServerResponse {
+    ws_stream.send(Message::Binary(req)).await.unwrap();
+    let raw_message = ws_stream.next().await.unwrap().unwrap();
+    match raw_message {
+        Message::Binary(bin_payload) => ServerResponse::deserialize(&bin_payload).unwrap(),
+        _ => panic!("received an unexpected response type!"),
+    }
+}
+
+async fn get_self_address(ws_stream: &mut WebSocketStream<MaybeTlsStream<TcpStream>>) -> Recipient {
+    let self_address_request = ClientRequest::SelfAddress.serialize();
+    let response = send_message_and_get_response(ws_stream, self_address_request).await;
+
+    match response {
+        ServerResponse::SelfAddress(recipient) => recipient,
+        _ => panic!("received an unexpected response!"),
+    }
+}
+
+async fn send_file_with_reply() {
+    let uri = "ws://localhost:1977";
+    let (mut ws_stream, _) = connect_async(uri).await.unwrap();
+
+    let recipient = get_self_address(&mut ws_stream).await;
+    println!("our full address is: {}", recipient.to_string());
+
+    let read_data = std::fs::read("examples/dummy_file").unwrap();
+
+    let send_request = ClientRequest::Send {
+        recipient,
+        message: read_data,
+        with_reply_surb: true,
+    };
+
+    println!("sending content of 'dummy_file' over the mix network...");
+    let response = send_message_and_get_response(&mut ws_stream, send_request.serialize()).await;
+
+    let received = match response {
+        ServerResponse::Received(received) => received,
+        _ => panic!("received an unexpected response!"),
+    };
+
+    println!("writing the file back to the disk!");
+    std::fs::write("examples/received_file_withreply", received.message).unwrap();
+
+    let reply_message = b"hello from reply SURB! - thanks for sending me the file!".to_vec();
+    let reply_request = ClientRequest::Reply {
+        message: reply_message.clone(),
+        reply_surb: received.reply_surb.unwrap(),
+    };
+
+    println!(
+        "sending {:?} (using reply SURB!) over the mix network...",
+        String::from_utf8(reply_message).unwrap()
+    );
+    let response = send_message_and_get_response(&mut ws_stream, reply_request.serialize()).await;
+    let received = match response {
+        ServerResponse::Received(received) => received,
+        _ => panic!("received an unexpected response!"),
+    };
+
+    println!(
+        "received {:#?} from the mix network!",
+        String::from_utf8(received.message).unwrap()
+    );
+}
+
+async fn send_file_without_reply() {
+    let uri = "ws://localhost:1977";
+    let (mut ws_stream, _) = connect_async(uri).await.unwrap();
+
+    let recipient = get_self_address(&mut ws_stream).await;
+    println!("our full address is: {}", recipient.to_string());
+
+    let read_data = std::fs::read("examples/dummy_file").unwrap();
+
+    let send_request = ClientRequest::Send {
+        recipient,
+        message: read_data,
+        with_reply_surb: false,
+    };
+
+    println!("sending content of 'dummy_file' over the mix network...");
+    let response = send_message_and_get_response(&mut ws_stream, send_request.serialize()).await;
+
+    let received = match response {
+        ServerResponse::Received(received) => received,
+        _ => panic!("received an unexpected response!"),
+    };
+
+    println!("writing the file back to the disk!");
+    std::fs::write("examples/received_file_noreply", received.message).unwrap();
+}
+
+#[tokio::main]
+async fn main() {
+    println!("#############################");
+    println!("Example without using replies");
+
+    send_file_without_reply().await;
+
+    println!("\n\n#############################");
+    println!("Example using replies");
+
+    send_file_with_reply().await;
+}

clients/native/examples/websocket_textsend.rs

@@ -0,0 +1,109 @@
+use futures::{SinkExt, StreamExt};
+use serde_json::json;
+use tokio::net::TcpStream;
+use tokio_tungstenite::{
+    connect_async, tungstenite::protocol::Message, MaybeTlsStream, WebSocketStream,
+};
+
+// PREFACE: in practice I don't see why you would ever want to use text api while in Rust, but example
+// is here for the completion sake
+
+// just helpers functions that work in this very particular context because we are sending to ourselves
+// and hence will always get a response back (i.e. the message we sent)
+async fn send_message_and_get_json_response(
+    ws_stream: &mut WebSocketStream<MaybeTlsStream<TcpStream>>,
+    text_req: String,
+) -> serde_json::Value {
+    ws_stream.send(Message::Text(text_req)).await.unwrap();
+    let raw_message = ws_stream.next().await.unwrap().unwrap();
+    match raw_message {
+        Message::Text(txt_msg) => serde_json::from_str(&txt_msg).unwrap(),
+        _ => panic!("received an unexpected response type!"),
+    }
+}
+
+async fn get_self_address(ws_stream: &mut WebSocketStream<MaybeTlsStream<TcpStream>>) -> String {
+    let self_address_request = json!({ "type": "selfAddress" }).to_string();
+    let response = send_message_and_get_json_response(ws_stream, self_address_request).await;
+
+    response["address"].as_str().unwrap().to_string()
+}
+
+async fn send_text_with_reply() {
+    let message = "Hello Nym!".to_string();
+
+    let uri = "ws://localhost:1977";
+    let (mut ws_stream, _) = connect_async(uri).await.unwrap();
+
+    let recipient = get_self_address(&mut ws_stream).await;
+    println!("our full address is: {}", recipient.to_string());
+
+    let send_request = json!({
+        "type" : "send",
+        "recipient": recipient,
+        "message": message,
+        "withReplySurb": true,
+    });
+
+    println!(
+        "sending {:?} (*with* reply SURB) over the mix network...",
+        message
+    );
+    let response =
+        send_message_and_get_json_response(&mut ws_stream, send_request.to_string()).await;
+
+    let reply_message = "hello from reply SURB!";
+    let reply_request = json!({
+        "type": "reply",
+        "message": reply_message,
+        "replySurb": response["replySurb"]
+    });
+
+    println!(
+        "sending {:?} (using reply SURB!) over the mix network...",
+        reply_message
+    );
+
+    let response =
+        send_message_and_get_json_response(&mut ws_stream, reply_request.to_string()).await;
+    println!("received {:#?} from the mix network!", response.to_string());
+}
+
+async fn send_text_without_reply() {
+    let message = "Hello Nym!".to_string();
+
+    let uri = "ws://localhost:1977";
+    let (mut ws_stream, _) = connect_async(uri).await.unwrap();
+
+    let recipient = get_self_address(&mut ws_stream).await;
+    println!("our full address is: {}", recipient.to_string());
+
+    let send_request = json!({
+        "type" : "send",
+        "recipient": recipient,
+        "message": message,
+        "withReplySurb": false,
+    });
+
+    println!(
+        "sending {:?} (*without* reply SURB) over the mix network...",
+        message
+    );
+    let response =
+        send_message_and_get_json_response(&mut ws_stream, send_request.to_string()).await;
+
+    println!("received {:#?} from the mix network!", response.to_string());
+}
+
+#[tokio::main]
+async fn main() {
+    println!("#############################");
+    println!("Example without using replies");
+
+    send_text_without_reply().await;
+
+    println!("\n\n#############################");
+    println!("Example using replies");
+
+    send_text_with_reply().await;
+}

clients/native/src/client/config/mod.rs

@@ -0,0 +1,122 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::config::template::config_template;
+use client_core::config::Config as BaseConfig;
+pub use client_core::config::MISSING_VALUE;
+use config::defaults::DEFAULT_WEBSOCKET_LISTENING_PORT;
+use config::NymConfig;
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+mod template;
+
+#[derive(Debug, Deserialize, PartialEq, Serialize, Clone, Copy)]
+#[serde(deny_unknown_fields)]
+pub enum SocketType {
+    WebSocket,
+    None,
+}
+
+impl SocketType {
+    pub fn from_string<S: Into<String>>(val: S) -> Self {
+        let mut upper = val.into();
+        upper.make_ascii_uppercase();
+        match upper.as_ref() {
+            "WEBSOCKET" | "WS" => SocketType::WebSocket,
+            _ => SocketType::None,
+        }
+    }
+}
+
+#[derive(Debug, Default, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Config {
+    #[serde(flatten)]
+    base: BaseConfig<Config>,
+
+    socket: Socket,
+}
+
+impl NymConfig for Config {
+    fn template() -> &'static str {
+        config_template()
+    }
+
+    fn default_root_directory() -> PathBuf {
+        dirs::home_dir()
+            .expect("Failed to evaluate $HOME value")
+            .join(".nym")
+            .join("clients")
+    }
+
+    fn root_directory(&self) -> PathBuf {
+        self.base.get_nym_root_directory()
+    }
+
+    fn config_directory(&self) -> PathBuf {
+        self.root_directory()
+            .join(self.base.get_id())
+            .join("config")
+    }
+
+    fn data_directory(&self) -> PathBuf {
+        self.root_directory().join(self.base.get_id()).join("data")
+    }
+}
+
+impl Config {
+    pub fn new<S: Into<String>>(id: S) -> Self {
+        Config {
+            base: BaseConfig::new(id),
+            socket: Default::default(),
+        }
+    }
+
+    pub fn with_socket(mut self, socket_type: SocketType) -> Self {
+        self.socket.socket_type = socket_type;
+        self
+    }
+
+    pub fn with_port(mut self, port: u16) -> Self {
+        self.socket.listening_port = port;
+        self
+    }
+
+    // getters
+    pub fn get_config_file_save_location(&self) -> PathBuf {
+        self.config_directory().join(Self::config_file_name())
+    }
+
+    pub fn get_base(&self) -> &BaseConfig<Self> {
+        &self.base
+    }
+
+    pub fn get_base_mut(&mut self) -> &mut BaseConfig<Self> {
+        &mut self.base
+    }
+
+    pub fn get_socket_type(&self) -> SocketType {
+        self.socket.socket_type
+    }
+
+    pub fn get_listening_port(&self) -> u16 {
+        self.socket.listening_port
+    }
+}
+
+#[derive(Debug, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Socket {
+    socket_type: SocketType,
+    listening_port: u16,
+}
+
+impl Default for Socket {
+    fn default() -> Self {
+        Socket {
+            socket_type: SocketType::WebSocket,
+            listening_port: DEFAULT_WEBSOCKET_LISTENING_PORT,
+        }
+    }
+}

clients/native/src/client/config/template.rs

@@ -0,0 +1,113 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub(crate) fn config_template() -> &'static str {
+    // While using normal toml marshalling would have been way simpler with less overhead,
+    // I think it's useful to have comments attached to the saved config file to explain behaviour of
+    // particular fields.
+    // Note: any changes to the template must be reflected in the appropriate structs.
+    r#"
+# This is a TOML config file.
+# For more information, see https://github.com/toml-lang/toml
+
+##### main base client config options #####
+
+[client]
+# Version of the client for which this configuration was created.
+version = '{{ client.version }}'
+
+# Human readable ID of this particular client.
+id = '{{ client.id }}'
+
+# Indicates whether this client is running in a testnet mode, thus attempting
+# to claim bandwidth without presenting bandwidth credentials.
+testnet_mode = {{ client.testnet_mode }}
+
+# Addresses to APIs running on validator from which the client gets the view of the network.
+validator_api_urls = [
+    {{#each client.validator_api_urls }}
+        '{{this}}',
+    {{/each}}
+]
+
+# Path to file containing private identity key.
+private_identity_key_file = '{{ client.private_identity_key_file }}'
+
+# Path to file containing public identity key.
+public_identity_key_file = '{{ client.public_identity_key_file }}'
+
+# Path to file containing private encryption key.
+private_encryption_key_file = '{{ client.private_encryption_key_file }}'
+
+# Path to file containing public encryption key.
+public_encryption_key_file = '{{ client.public_encryption_key_file }}'
+
+# Full path to file containing reply encryption keys of all reply-SURBs we have ever
+# sent but not received back.
+reply_encryption_key_store_path = '{{ client.reply_encryption_key_store_path }}'
+
+# Path to directory containing public/private keys used for bandwidth token purchase.
+# Those are saved in case of emergency, to be able to reclaim bandwidth tokens.
+# The public key is the name of the file, while the private key is the content.
+backup_bandwidth_token_keys_dir = '{{ client.backup_bandwidth_token_keys_dir }}'
+
+# Ethereum private key.
+eth_private_key = '{{ client.eth_private_key }}'
+
+# Addess to an Ethereum full node.
+eth_endpoint = '{{ client.eth_endpoint }}'
+
+##### additional client config options #####
+
+# ID of the gateway from which the client should be fetching messages.
+gateway_id = '{{ client.gateway_id }}'
+
+# Address of the gateway listener to which all client requests should be sent.
+gateway_listener = '{{ client.gateway_listener }}'
+
+# A gateway specific, optional, base58 stringified shared key used for
+# communication with particular gateway.
+gateway_shared_key_file = '{{ client.gateway_shared_key_file }}'
+
+# Path to file containing key used for encrypting and decrypting the content of an
+# acknowledgement so that nobody besides the client knows which packet it refers to.
+ack_key_file = '{{ client.ack_key_file }}'
+    
+##### advanced configuration options #####
+
+# Absolute path to the home Nym Clients directory.
+nym_root_directory = '{{ client.nym_root_directory }}'
+
+
+##### socket config options #####
+
+[socket]
+
+# allowed values are 'WebSocket' or 'None'
+socket_type = '{{ socket.socket_type }}'
+
+# if applicable (for the case of 'WebSocket'), the port on which the client
+# will be listening for incoming requests
+listening_port = {{ socket.listening_port }}
+
+
+##### logging configuration options #####
+
+[logging]
+
+# TODO
+
+
+##### debug configuration options #####
+# The following options should not be modified unless you know EXACTLY what you are doing
+# as if set incorrectly, they may impact your anonymity.
+
+[debug]
+
+average_packet_delay = '{{ debug.average_packet_delay }}'
+average_ack_delay = '{{ debug.average_ack_delay }}'
+loop_cover_traffic_average_delay = '{{ debug.loop_cover_traffic_average_delay }}'
+message_sending_average_delay = '{{ debug.message_sending_average_delay }}'
+
+"#
+}

clients/native/src/client/mod.rs

@@ -0,0 +1,396 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use client_core::client::cover_traffic_stream::LoopCoverTrafficStream;
+use client_core::client::inbound_messages::{
+    InputMessage, InputMessageReceiver, InputMessageSender,
+};
+use client_core::client::key_manager::KeyManager;
+use client_core::client::mix_traffic::{
+    BatchMixMessageReceiver, BatchMixMessageSender, MixTrafficController,
+};
+use client_core::client::real_messages_control;
+use client_core::client::real_messages_control::RealMessagesController;
+use client_core::client::received_buffer::{
+    ReceivedBufferMessage, ReceivedBufferRequestReceiver, ReceivedBufferRequestSender,
+    ReceivedMessagesBufferController, ReconstructedMessagesReceiver,
+};
+use client_core::client::reply_key_storage::ReplyKeyStorage;
+use client_core::client::topology_control::{
+    TopologyAccessor, TopologyRefresher, TopologyRefresherConfig,
+};
+use client_core::config::persistence::key_pathfinder::ClientKeyPathfinder;
+use crypto::asymmetric::identity;
+use futures::channel::mpsc;
+use gateway_client::bandwidth::BandwidthController;
+use gateway_client::{
+    AcknowledgementReceiver, AcknowledgementSender, GatewayClient, MixnetMessageReceiver,
+    MixnetMessageSender,
+};
+use log::*;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::addressing::nodes::NodeIdentity;
+use nymsphinx::anonymous_replies::ReplySurb;
+use nymsphinx::receiver::ReconstructedMessage;
+
+use crate::client::config::{Config, SocketType};
+use crate::websocket;
+
+pub(crate) mod config;
+
+pub struct NymClient {
+    /// Client configuration options, including, among other things, packet sending rates,
+    /// key filepaths, etc.
+    config: Config,
+
+    /// KeyManager object containing smart pointers to all relevant keys used by the client.
+    key_manager: KeyManager,
+
+    /// Channel used for transforming 'raw' messages into sphinx packets and sending them
+    /// through the mix network.
+    /// It is only available if the client started with the websocket listener disabled.
+    input_tx: Option<InputMessageSender>,
+
+    /// Channel used for obtaining reconstructed messages received from the mix network.
+    /// It is only available if the client started with the websocket listener disabled.
+    receive_tx: Option<ReconstructedMessagesReceiver>,
+}
+
+impl NymClient {
+    pub fn new(config: Config) -> Self {
+        let pathfinder = ClientKeyPathfinder::new_from_config(config.get_base());
+        let key_manager = KeyManager::load_keys(&pathfinder).expect("failed to load stored keys");
+
+        NymClient {
+            config,
+            key_manager,
+            input_tx: None,
+            receive_tx: None,
+        }
+    }
+
+    pub fn as_mix_recipient(&self) -> Recipient {
+        Recipient::new(
+            *self.key_manager.identity_keypair().public_key(),
+            *self.key_manager.encryption_keypair().public_key(),
+            // TODO: below only works under assumption that gateway address == gateway id
+            // (which currently is true)
+            NodeIdentity::from_base58_string(self.config.get_base().get_gateway_id()).unwrap(),
+        )
+    }
+
+    // future constantly pumping loop cover traffic at some specified average rate
+    // the pumped traffic goes to the MixTrafficController
+    fn start_cover_traffic_stream(
+        &self,
+        topology_accessor: TopologyAccessor,
+        mix_tx: BatchMixMessageSender,
+    ) {
+        info!("Starting loop cover traffic stream...");
+
+        LoopCoverTrafficStream::new(
+            self.key_manager.ack_key(),
+            self.config.get_base().get_average_ack_delay(),
+            self.config.get_base().get_average_packet_delay(),
+            self.config
+                .get_base()
+                .get_loop_cover_traffic_average_delay(),
+            mix_tx,
+            self.as_mix_recipient(),
+            topology_accessor,
+        )
+        .start();
+    }
+
+    fn start_real_traffic_controller(
+        &self,
+        topology_accessor: TopologyAccessor,
+        reply_key_storage: ReplyKeyStorage,
+        ack_receiver: AcknowledgementReceiver,
+        input_receiver: InputMessageReceiver,
+        mix_sender: BatchMixMessageSender,
+    ) {
+        let controller_config = real_messages_control::Config::new(
+            self.key_manager.ack_key(),
+            self.config.get_base().get_ack_wait_multiplier(),
+            self.config.get_base().get_ack_wait_addition(),
+            self.config.get_base().get_average_ack_delay(),
+            self.config.get_base().get_message_sending_average_delay(),
+            self.config.get_base().get_average_packet_delay(),
+            self.as_mix_recipient(),
+        );
+
+        info!("Starting real traffic stream...");
+
+        RealMessagesController::new(
+            controller_config,
+            ack_receiver,
+            input_receiver,
+            mix_sender,
+            topology_accessor,
+            reply_key_storage,
+        )
+        .start();
+    }
+
+    // buffer controlling all messages fetched from provider
+    // required so that other components would be able to use them (say the websocket)
+    fn start_received_messages_buffer_controller(
+        &self,
+        query_receiver: ReceivedBufferRequestReceiver,
+        mixnet_receiver: MixnetMessageReceiver,
+        reply_key_storage: ReplyKeyStorage,
+    ) {
+        info!("Starting received messages buffer controller...");
+        ReceivedMessagesBufferController::new(
+            self.key_manager.encryption_keypair(),
+            query_receiver,
+            mixnet_receiver,
+            reply_key_storage,
+        )
+        .start()
+    }
+
+    async fn start_gateway_client(
+        &mut self,
+        mixnet_message_sender: MixnetMessageSender,
+        ack_sender: AcknowledgementSender,
+    ) -> GatewayClient {
+        let gateway_id = self.config.get_base().get_gateway_id();
+        if gateway_id.is_empty() {
+            panic!("The identity of the gateway is unknown - did you run `nym-client` init?")
+        }
+        let gateway_address = self.config.get_base().get_gateway_listener();
+        if gateway_address.is_empty() {
+            panic!("The address of the gateway is unknown - did you run `nym-client` init?")
+        }
+
+        let gateway_identity = identity::PublicKey::from_base58_string(gateway_id)
+            .expect("provided gateway id is invalid!");
+
+        #[cfg(feature = "coconut")]
+        let bandwidth_controller = BandwidthController::new(
+            self.config.get_base().get_validator_api_endpoints(),
+            *self.key_manager.identity_keypair().public_key(),
+        );
+        #[cfg(not(feature = "coconut"))]
+        let bandwidth_controller = BandwidthController::new(
+            self.config.get_base().get_eth_endpoint(),
+            self.config.get_base().get_eth_private_key(),
+            self.config.get_base().get_backup_bandwidth_token_keys_dir(),
+        )
+        .expect("Could not create bandwidth controller");
+
+        let mut gateway_client = GatewayClient::new(
+            gateway_address,
+            self.key_manager.identity_keypair(),
+            gateway_identity,
+            Some(self.key_manager.gateway_shared_key()),
+            mixnet_message_sender,
+            ack_sender,
+            self.config.get_base().get_gateway_response_timeout(),
+            Some(bandwidth_controller),
+        );
+
+        if self.config.get_base().get_testnet_mode() {
+            gateway_client.set_testnet_mode(true)
+        }
+        gateway_client
+            .authenticate_and_start()
+            .await
+            .expect("could not authenticate and start up the gateway connection");
+
+        gateway_client
+    }
+
+    // future responsible for periodically polling directory server and updating
+    // the current global view of topology
+    async fn start_topology_refresher(&mut self, topology_accessor: TopologyAccessor) {
+        let topology_refresher_config = TopologyRefresherConfig::new(
+            self.config.get_base().get_validator_api_endpoints(),
+            self.config.get_base().get_topology_refresh_rate(),
+            env!("CARGO_PKG_VERSION").to_string(),
+        );
+        let mut topology_refresher =
+            TopologyRefresher::new(topology_refresher_config, topology_accessor);
+        // before returning, block entire runtime to refresh the current network view so that any
+        // components depending on topology would see a non-empty view
+        info!("Obtaining initial network topology");
+        topology_refresher.refresh().await;
+
+        // TODO: a slightly more graceful termination here
+        if !topology_refresher.is_topology_routable().await {
+            panic!(
+                "The current network topology seem to be insufficient to route any packets through\
+                - check if enough nodes and a gateway are online"
+            );
+        }
+
+        info!("Starting topology refresher...");
+        topology_refresher.start();
+    }
+
+    // controller for sending sphinx packets to mixnet (either real traffic or cover traffic)
+    // TODO: if we want to send control messages to gateway_client, this CAN'T take the ownership
+    // over it. Perhaps GatewayClient needs to be thread-shareable or have some channel for
+    // requests?
+    fn start_mix_traffic_controller(
+        &mut self,
+        mix_rx: BatchMixMessageReceiver,
+        gateway_client: GatewayClient,
+    ) {
+        info!("Starting mix traffic controller...");
+        MixTrafficController::new(mix_rx, gateway_client).start();
+    }
+
+    fn start_websocket_listener(
+        &self,
+        buffer_requester: ReceivedBufferRequestSender,
+        msg_input: InputMessageSender,
+    ) {
+        info!("Starting websocket listener...");
+
+        let websocket_handler =
+            websocket::Handler::new(msg_input, buffer_requester, self.as_mix_recipient());
+
+        websocket::Listener::new(self.config.get_listening_port()).start(websocket_handler);
+    }
+
+    /// EXPERIMENTAL DIRECT RUST API
+    /// It's untested and there are absolutely no guarantees about it (but seems to have worked
+    /// well enough in local tests)
+    pub fn send_message(&mut self, recipient: Recipient, message: Vec<u8>, with_reply_surb: bool) {
+        let input_msg = InputMessage::new_fresh(recipient, message, with_reply_surb);
+
+        self.input_tx
+            .as_ref()
+            .expect("start method was not called before!")
+            .unbounded_send(input_msg)
+            .unwrap();
+    }
+
+    /// EXPERIMENTAL DIRECT RUST API
+    /// It's untested and there are absolutely no guarantees about it (but seems to have worked
+    /// well enough in local tests)
+    pub fn send_reply(&mut self, reply_surb: ReplySurb, message: Vec<u8>) {
+        let input_msg = InputMessage::new_reply(reply_surb, message);
+
+        self.input_tx
+            .as_ref()
+            .expect("start method was not called before!")
+            .unbounded_send(input_msg)
+            .unwrap();
+    }
+
+    /// EXPERIMENTAL DIRECT RUST API
+    /// It's untested and there are absolutely no guarantees about it (but seems to have worked
+    /// well enough in local tests)
+    /// Note: it waits for the first occurrence of messages being sent to ourselves. If you expect multiple
+    /// messages, you might have to call this function repeatedly.
+    // TODO: I guess this should really return something that `impl Stream<Item=ReconstructedMessage>`
+    pub async fn wait_for_messages(&mut self) -> Vec<ReconstructedMessage> {
+        use futures::StreamExt;
+
+        self.receive_tx
+            .as_mut()
+            .expect("start method was not called before!")
+            .next()
+            .await
+            .expect("buffer controller seems to have somehow died!")
+    }
+
+    /// blocking version of `start` method. Will run forever (or until SIGINT is sent)
+    pub async fn run_forever(&mut self) {
+        self.start().await;
+        if let Err(e) = tokio::signal::ctrl_c().await {
+            error!(
+                "There was an error while capturing SIGINT - {:?}. We will terminate regardless",
+                e
+            );
+        }
+
+        println!(
+            "Received SIGINT - the client will terminate now (threads are not yet nicely stopped, if you see stack traces that's alright)."
+        );
+    }
+
+    pub async fn start(&mut self) {
+        info!("Starting nym client");
+        // channels for inter-component communication
+        // TODO: make the channels be internally created by the relevant components
+        // rather than creating them here, so say for example the buffer controller would create the request channels
+        // and would allow anyone to clone the sender channel
+
+        // sphinx_message_sender 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
+        // sphinx_message_receiver is the receiver used by MixTrafficController that sends the actual traffic
+        let (sphinx_message_sender, sphinx_message_receiver) = mpsc::unbounded();
+
+        // unwrapped_sphinx_sender is the transmitter of mixnet messages received from the gateway
+        // unwrapped_sphinx_receiver is the receiver for said messages - used by ReceivedMessagesBuffer
+        let (mixnet_messages_sender, mixnet_messages_receiver) = mpsc::unbounded();
+
+        // used for announcing connection or disconnection of a channel for pushing re-assembled messages to
+        let (received_buffer_request_sender, received_buffer_request_receiver) = mpsc::unbounded();
+
+        // channels responsible for controlling real messages
+        let (input_sender, input_receiver) = mpsc::unbounded::<InputMessage>();
+
+        // channels responsible for controlling ack messages
+        let (ack_sender, ack_receiver) = mpsc::unbounded();
+        let shared_topology_accessor = TopologyAccessor::new();
+
+        let reply_key_storage =
+            ReplyKeyStorage::load(self.config.get_base().get_reply_encryption_key_store_path())
+                .expect("Failed to load reply key storage!");
+
+        // the components are started in very specific order. Unless you know what you are doing,
+        // do not change that.
+        self.start_topology_refresher(shared_topology_accessor.clone())
+            .await;
+        self.start_received_messages_buffer_controller(
+            received_buffer_request_receiver,
+            mixnet_messages_receiver,
+            reply_key_storage.clone(),
+        );
+
+        let gateway_client = self
+            .start_gateway_client(mixnet_messages_sender, ack_sender)
+            .await;
+
+        self.start_mix_traffic_controller(sphinx_message_receiver, gateway_client);
+        self.start_real_traffic_controller(
+            shared_topology_accessor.clone(),
+            reply_key_storage,
+            ack_receiver,
+            input_receiver,
+            sphinx_message_sender.clone(),
+        );
+
+        self.start_cover_traffic_stream(shared_topology_accessor, sphinx_message_sender);
+
+        match self.config.get_socket_type() {
+            SocketType::WebSocket => {
+                self.start_websocket_listener(received_buffer_request_sender, input_sender)
+            }
+            SocketType::None => {
+                // if we did not start the socket, it means we're running (supposedly) in the native mode
+                // and hence we should announce 'ourselves' to the buffer
+                let (reconstructed_sender, reconstructed_receiver) = mpsc::unbounded();
+
+                // tell the buffer to start sending stuff to us
+                received_buffer_request_sender
+                    .unbounded_send(ReceivedBufferMessage::ReceiverAnnounce(
+                        reconstructed_sender,
+                    ))
+                    .expect("the buffer request failed!");
+
+                self.receive_tx = Some(reconstructed_receiver);
+                self.input_tx = Some(input_sender);
+            }
+        }
+
+        info!("Client startup finished!");
+        info!("The address of this client is: {}", self.as_mix_recipient());
+    }
+}

clients/native/src/commands/init.rs

@@ -0,0 +1,285 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use clap::{App, Arg, ArgMatches};
+use client_core::client::key_manager::KeyManager;
+use client_core::config::persistence::key_pathfinder::ClientKeyPathfinder;
+#[cfg(feature = "coconut")]
+use coconut_interface::{hash_to_scalar, Credential, Parameters};
+use config::NymConfig;
+#[cfg(feature = "coconut")]
+use credentials::coconut::bandwidth::{
+    obtain_signature, prepare_for_spending, BandwidthVoucherAttributes, TOTAL_ATTRIBUTES,
+};
+#[cfg(feature = "coconut")]
+use credentials::obtain_aggregate_verification_key;
+use crypto::asymmetric::{encryption, identity};
+use gateway_client::GatewayClient;
+use gateway_requests::registration::handshake::SharedKeys;
+#[cfg(feature = "coconut")]
+use network_defaults::BANDWIDTH_VALUE;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::addressing::nodes::NodeIdentity;
+use rand::rngs::OsRng;
+use rand::seq::SliceRandom;
+use rand::thread_rng;
+use std::convert::TryInto;
+use std::sync::Arc;
+use std::time::Duration;
+use topology::{filter::VersionFilterable, gateway};
+use url::Url;
+
+use crate::client::config::Config;
+use crate::commands::override_config;
+#[cfg(feature = "eth")]
+#[cfg(not(feature = "coconut"))]
+use crate::commands::{
+    DEFAULT_ETH_ENDPOINT, DEFAULT_ETH_PRIVATE_KEY, ETH_ENDPOINT_ARG_NAME, ETH_PRIVATE_KEY_ARG_NAME,
+    TESTNET_MODE_ARG_NAME,
+};
+
+pub fn command_args<'a, 'b>() -> clap::App<'a, 'b> {
+    let app = App::new("init")
+        .about("Initialise a Nym client. Do this first!")
+        .arg(Arg::with_name("id")
+            .long("id")
+            .help("Id of the nym-mixnet-client we want to create config for.")
+            .takes_value(true)
+            .required(true)
+        )
+        .arg(Arg::with_name("gateway")
+            .long("gateway")
+            .help("Id of the gateway we are going to connect to.")
+            .takes_value(true)
+        )
+        .arg(Arg::with_name("validators")
+                 .long("validators")
+                 .help("Comma separated list of rest endpoints of the validators")
+                 .takes_value(true),
+        )
+        .arg(Arg::with_name("disable-socket")
+            .long("disable-socket")
+            .help("Whether to not start the websocket")
+        )
+        .arg(Arg::with_name("port")
+            .short("p")
+            .long("port")
+            .help("Port for the socket (if applicable) to listen on in all subsequent runs")
+            .takes_value(true)
+        )
+        .arg(Arg::with_name("fastmode")
+            .long("fastmode")
+            .hidden(true) // this will prevent this flag from being displayed in `--help`
+            .help("Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init")
+        );
+    #[cfg(feature = "eth")]
+    #[cfg(not(feature = "coconut"))]
+        let app = app
+        .arg(
+            Arg::with_name(TESTNET_MODE_ARG_NAME)
+                .long(TESTNET_MODE_ARG_NAME)
+                .help("Set this client to work in a testnet mode that would attempt to use gateway without bandwidth credential requirement. If this value is set, --eth_endpoint and --eth_private_key don't need to be set.")
+                .conflicts_with_all(&[ETH_ENDPOINT_ARG_NAME, ETH_PRIVATE_KEY_ARG_NAME])
+        )
+        .arg(Arg::with_name(ETH_ENDPOINT_ARG_NAME)
+            .long(ETH_ENDPOINT_ARG_NAME)
+            .help("URL of an Ethereum full node that we want to use for getting bandwidth tokens from ERC20 tokens. If you don't want to set this value, use --testnet-mode instead")
+            .takes_value(true)
+            .default_value_if(TESTNET_MODE_ARG_NAME, None, DEFAULT_ETH_ENDPOINT)
+            .required(true))
+        .arg(Arg::with_name(ETH_PRIVATE_KEY_ARG_NAME)
+            .long(ETH_PRIVATE_KEY_ARG_NAME)
+            .help("Ethereum private key used for obtaining bandwidth tokens from ERC20 tokens. If you don't want to set this value, use --testnet-mode instead")
+            .takes_value(true)
+            .default_value_if(TESTNET_MODE_ARG_NAME, None, DEFAULT_ETH_PRIVATE_KEY)
+            .required(true)
+        );
+
+    app
+}
+
+// this behaviour should definitely be changed, we shouldn't
+// need to get bandwidth credential for registration
+#[cfg(feature = "coconut")]
+async fn _prepare_temporary_credential(validators: &[Url], raw_identity: &[u8]) -> Credential {
+    let verification_key = obtain_aggregate_verification_key(validators)
+        .await
+        .expect("could not obtain aggregate verification key of validators");
+
+    let params = Parameters::new(TOTAL_ATTRIBUTES).unwrap();
+    let bandwidth_credential_attributes = BandwidthVoucherAttributes {
+        serial_number: params.random_scalar(),
+        binding_number: params.random_scalar(),
+        voucher_value: hash_to_scalar(BANDWIDTH_VALUE.to_be_bytes()),
+        voucher_info: hash_to_scalar(String::from("BandwidthVoucher").as_bytes()),
+    };
+
+    let bandwidth_credential =
+        obtain_signature(&params, &bandwidth_credential_attributes, validators)
+            .await
+            .expect("could not obtain bandwidth credential");
+
+    prepare_for_spending(
+        raw_identity,
+        &bandwidth_credential,
+        &bandwidth_credential_attributes,
+        &verification_key,
+    )
+    .expect("could not prepare out bandwidth credential for spending")
+}
+
+async fn register_with_gateway(
+    gateway: &gateway::Node,
+    our_identity: Arc<identity::KeyPair>,
+) -> Arc<SharedKeys> {
+    let timeout = Duration::from_millis(1500);
+    let mut gateway_client = GatewayClient::new_init(
+        gateway.clients_address(),
+        gateway.identity_key,
+        our_identity.clone(),
+        timeout,
+    );
+    gateway_client
+        .establish_connection()
+        .await
+        .expect("failed to establish connection with the gateway!");
+    gateway_client
+        .perform_initial_authentication()
+        .await
+        .expect("failed to register with the gateway!")
+}
+
+async fn gateway_details(
+    validator_servers: Vec<Url>,
+    chosen_gateway_id: Option<&str>,
+) -> gateway::Node {
+    let validator_api = validator_servers
+        .choose(&mut thread_rng())
+        .expect("The list of validator apis is empty");
+    let validator_client = validator_client::ApiClient::new(validator_api.clone());
+
+    let gateways = validator_client.get_cached_gateways().await.unwrap();
+    let valid_gateways = gateways
+        .into_iter()
+        .filter_map(|gateway| gateway.try_into().ok())
+        .collect::<Vec<gateway::Node>>();
+
+    let filtered_gateways = valid_gateways.filter_by_version(env!("CARGO_PKG_VERSION"));
+
+    // if we have chosen particular gateway - use it, otherwise choose a random one.
+    // (remember that in active topology all gateways have at least 100 reputation so should
+    // be working correctly)
+    if let Some(gateway_id) = chosen_gateway_id {
+        filtered_gateways
+            .iter()
+            .find(|gateway| gateway.identity_key.to_base58_string() == gateway_id)
+            .expect(&*format!("no gateway with id {} exists!", gateway_id))
+            .clone()
+    } else {
+        filtered_gateways
+            .choose(&mut rand::thread_rng())
+            .expect("there are no gateways on the network!")
+            .clone()
+    }
+}
+
+fn show_address(config: &Config) {
+    fn load_identity_keys(pathfinder: &ClientKeyPathfinder) -> identity::KeyPair {
+        let identity_keypair: identity::KeyPair =
+            pemstore::load_keypair(&pemstore::KeyPairPath::new(
+                pathfinder.private_identity_key().to_owned(),
+                pathfinder.public_identity_key().to_owned(),
+            ))
+            .expect("Failed to read stored identity key files");
+        identity_keypair
+    }
+
+    fn load_sphinx_keys(pathfinder: &ClientKeyPathfinder) -> encryption::KeyPair {
+        let sphinx_keypair: encryption::KeyPair =
+            pemstore::load_keypair(&pemstore::KeyPairPath::new(
+                pathfinder.private_encryption_key().to_owned(),
+                pathfinder.public_encryption_key().to_owned(),
+            ))
+            .expect("Failed to read stored sphinx key files");
+        sphinx_keypair
+    }
+
+    let pathfinder = ClientKeyPathfinder::new_from_config(config.get_base());
+    let identity_keypair = load_identity_keys(&pathfinder);
+    let sphinx_keypair = load_sphinx_keys(&pathfinder);
+
+    let client_recipient = Recipient::new(
+        *identity_keypair.public_key(),
+        *sphinx_keypair.public_key(),
+        // TODO: below only works under assumption that gateway address == gateway id
+        // (which currently is true)
+        NodeIdentity::from_base58_string(config.get_base().get_gateway_id()).unwrap(),
+    );
+
+    println!("\nThe address of this client is: {}", client_recipient);
+}
+
+pub async fn execute(matches: ArgMatches<'static>) {
+    println!("Initialising client...");
+
+    let id = matches.value_of("id").unwrap(); // required for now
+
+    let already_init = if Config::default_config_file_path(Some(id)).exists() {
+        println!("Client \"{}\" was already initialised before! Config information will be overwritten (but keys will be kept)!", id);
+        true
+    } else {
+        false
+    };
+
+    let mut config = Config::new(id);
+
+    let mut rng = OsRng;
+
+    // TODO: ideally that should be the last thing that's being done to config.
+    // However, we are later further overriding it with gateway id
+    config = override_config(config, &matches);
+    if matches.is_present("fastmode") {
+        config.get_base_mut().set_high_default_traffic_volume();
+    }
+
+    // if client was already initialised, don't generate new keys, not re-register with gateway
+    // (because this would create new shared key)
+    if !already_init {
+        // create identity, encryption and ack keys.
+        let mut key_manager = KeyManager::new(&mut rng);
+
+        let chosen_gateway_id = matches.value_of("gateway");
+
+        let gateway_details = gateway_details(
+            config.get_base().get_validator_api_endpoints(),
+            chosen_gateway_id,
+        )
+        .await;
+        config
+            .get_base_mut()
+            .with_gateway_id(gateway_details.identity_key.to_base58_string());
+        let shared_keys =
+            register_with_gateway(&gateway_details, key_manager.identity_keypair()).await;
+
+        config
+            .get_base_mut()
+            .with_gateway_listener(gateway_details.clients_address());
+        key_manager.insert_gateway_shared_key(shared_keys);
+
+        let pathfinder = ClientKeyPathfinder::new_from_config(config.get_base());
+        key_manager
+            .store_keys(&pathfinder)
+            .expect("Failed to generated keys");
+        println!("Saved all generated keys");
+    }
+
+    let config_save_location = config.get_config_file_save_location();
+    config
+        .save_to_file(None)
+        .expect("Failed to save the config file");
+    println!("Saved configuration file to {:?}", config_save_location);
+    println!("Using gateway: {}", config.get_base().get_gateway_id(),);
+    println!("Client configuration completed.\n\n\n");
+
+    show_address(&config);
+}

clients/native/src/commands/mod.rs

@@ -0,0 +1,80 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::config::{Config, SocketType};
+use clap::ArgMatches;
+use url::Url;
+
+pub(crate) const TESTNET_MODE_ARG_NAME: &str = "testnet-mode";
+#[cfg(not(feature = "coconut"))]
+pub(crate) const ETH_ENDPOINT_ARG_NAME: &str = "eth_endpoint";
+#[cfg(not(feature = "coconut"))]
+pub(crate) const ETH_PRIVATE_KEY_ARG_NAME: &str = "eth_private_key";
+#[cfg(not(feature = "coconut"))]
+pub(crate) const DEFAULT_ETH_ENDPOINT: &str =
+    "https://rinkeby.infura.io/v3/00000000000000000000000000000000";
+#[cfg(not(feature = "coconut"))]
+pub(crate) const DEFAULT_ETH_PRIVATE_KEY: &str =
+    "0000000000000000000000000000000000000000000000000000000000000001";
+
+pub(crate) mod init;
+pub(crate) mod run;
+pub(crate) mod upgrade;
+
+fn parse_validators(raw: &str) -> Vec<Url> {
+    raw.split(',')
+        .map(|raw_validator| {
+            raw_validator
+                .trim()
+                .parse()
+                .expect("one of the provided validator api urls is invalid")
+        })
+        .collect()
+}
+
+pub(crate) fn override_config(mut config: Config, matches: &ArgMatches) -> Config {
+    if let Some(raw_validators) = matches.value_of("validators") {
+        config
+            .get_base_mut()
+            .set_custom_validator_apis(parse_validators(raw_validators));
+    }
+
+    if let Some(gateway_id) = matches.value_of("gateway") {
+        config.get_base_mut().with_gateway_id(gateway_id);
+    }
+
+    if matches.is_present("disable-socket") {
+        config = config.with_socket(SocketType::None);
+    }
+
+    if let Some(port) = matches.value_of("port").map(|port| port.parse::<u16>()) {
+        if let Err(err) = port {
+            // if port was overridden, it must be parsable
+            panic!("Invalid port value provided - {:?}", err);
+        }
+        config = config.with_port(port.unwrap());
+    }
+
+    #[cfg(not(feature = "coconut"))]
+    if let Some(eth_endpoint) = matches.value_of(ETH_ENDPOINT_ARG_NAME) {
+        config.get_base_mut().with_eth_endpoint(eth_endpoint);
+    } else {
+        config
+            .get_base_mut()
+            .with_eth_endpoint(DEFAULT_ETH_ENDPOINT);
+    }
+    #[cfg(not(feature = "coconut"))]
+    if let Some(eth_private_key) = matches.value_of(ETH_PRIVATE_KEY_ARG_NAME) {
+        config.get_base_mut().with_eth_private_key(eth_private_key);
+    } else {
+        config
+            .get_base_mut()
+            .with_eth_private_key(DEFAULT_ETH_PRIVATE_KEY);
+    }
+
+    if !cfg!(feature = "eth") || matches.is_present(TESTNET_MODE_ARG_NAME) {
+        config.get_base_mut().with_testnet_mode(true)
+    }
+
+    config
+}

clients/native/src/commands/run.rs

@@ -0,0 +1,104 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::config::Config;
+use crate::client::NymClient;
+use crate::commands::override_config;
+#[cfg(feature = "eth")]
+#[cfg(not(feature = "coconut"))]
+use crate::commands::{ETH_ENDPOINT_ARG_NAME, ETH_PRIVATE_KEY_ARG_NAME, TESTNET_MODE_ARG_NAME};
+use clap::{App, Arg, ArgMatches};
+use config::NymConfig;
+use log::*;
+use version_checker::is_minor_version_compatible;
+
+pub fn command_args<'a, 'b>() -> clap::App<'a, 'b> {
+    let app = App::new("run")
+        .about("Run the Nym client with provided configuration client optionally overriding set parameters")
+        .arg(Arg::with_name("id")
+            .long("id")
+            .help("Id of the nym-mixnet-client we want to run.")
+            .takes_value(true)
+            .required(true)
+        )
+        // the rest of arguments are optional, they are used to override settings in config file
+        .arg(Arg::with_name("validators")
+                .long("validators")
+                .help("Comma separated list rest rest endpoints of the validators")
+                .takes_value(true),
+        )
+        .arg(Arg::with_name("gateway")
+            .long("gateway")
+            .help("Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened")
+            .takes_value(true)
+        )
+        .arg(Arg::with_name("disable-socket")
+            .long("disable-socket")
+            .help("Whether to not start the websocket")
+        )
+        .arg(Arg::with_name("port")
+            .short("p")
+            .long("port")
+            .help("Port for the socket (if applicable) to listen on")
+            .takes_value(true)
+        );
+    #[cfg(feature = "eth")]
+    #[cfg(not(feature = "coconut"))]
+        let app = app
+        .arg(
+            Arg::with_name(TESTNET_MODE_ARG_NAME)
+                .long(TESTNET_MODE_ARG_NAME)
+                .help("Set this client to work in a testnet mode that would attempt to use gateway without bandwidth credential requirement. If this value is set, --eth_endpoint and --eth_private_key don't need to be set.")
+                .conflicts_with_all(&[ETH_ENDPOINT_ARG_NAME, ETH_PRIVATE_KEY_ARG_NAME])
+        )
+        .arg(Arg::with_name(ETH_ENDPOINT_ARG_NAME)
+            .long(ETH_ENDPOINT_ARG_NAME)
+            .help("URL of an Ethereum full node that we want to use for getting bandwidth tokens from ERC20 tokens. If you don't want to set this value, use --testnet-mode instead")
+            .takes_value(true))
+        .arg(Arg::with_name(ETH_PRIVATE_KEY_ARG_NAME)
+            .long(ETH_PRIVATE_KEY_ARG_NAME)
+            .help("Ethereum private key used for obtaining bandwidth tokens from ERC20 tokens. If you don't want to set this value, use --testnet-mode instead")
+            .takes_value(true));
+
+    app
+}
+
+// this only checks compatibility between config the binary. It does not take into consideration
+// network version. It might do so in the future.
+fn version_check(cfg: &Config) -> bool {
+    let binary_version = env!("CARGO_PKG_VERSION");
+    let config_version = cfg.get_base().get_version();
+    if binary_version != config_version {
+        warn!("The mixnode binary has different version than what is specified in config file! {} and {}", binary_version, config_version);
+        if is_minor_version_compatible(binary_version, config_version) {
+            info!("but they are still semver compatible. However, consider running the `upgrade` command");
+            true
+        } else {
+            error!("and they are semver incompatible! - please run the `upgrade` command before attempting `run` again");
+            false
+        }
+    } else {
+        true
+    }
+}
+
+pub async fn execute(matches: ArgMatches<'static>) {
+    let id = matches.value_of("id").unwrap();
+
+    let mut config = match Config::load_from_file(Some(id)) {
+        Ok(cfg) => cfg,
+        Err(err) => {
+            error!("Failed to load config for {}. Are you sure you have run `init` before? (Error was: {})", id, err);
+            return;
+        }
+    };
+
+    config = override_config(config, &matches);
+
+    if !version_check(&config) {
+        error!("failed the local version check");
+        return;
+    }
+
+    NymClient::new(config).run_forever().await;
+}

clients/native/src/commands/upgrade.rs

@@ -0,0 +1,171 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::client::config::{Config, MISSING_VALUE};
+use clap::{App, Arg, ArgMatches};
+use config::defaults::default_api_endpoints;
+use config::NymConfig;
+use std::fmt::Display;
+use std::process;
+use version_checker::Version;
+
+#[allow(dead_code)]
+fn fail_upgrade<D1: Display, D2: Display>(from_version: D1, to_version: D2) -> ! {
+    print_failed_upgrade(from_version, to_version);
+    process::exit(1)
+}
+
+fn print_start_upgrade<D1: Display, D2: Display>(from: D1, to: D2) {
+    println!(
+        "\n==================\nTrying to upgrade client from {} to {} ...",
+        from, to
+    );
+}
+
+fn print_failed_upgrade<D1: Display, D2: Display>(from: D1, to: D2) {
+    eprintln!(
+        "Upgrade from {} to {} failed!\n==================\n",
+        from, to
+    );
+}
+
+fn print_successful_upgrade<D1: Display, D2: Display>(from: D1, to: D2) {
+    println!(
+        "Upgrade from {} to {} was successful!\n==================\n",
+        from, to
+    );
+}
+
+fn outdated_upgrade(config_version: &Version, package_version: &Version) -> ! {
+    eprintln!(
+        "Cannot perform upgrade from {} to {}. Your version is too old to perform the upgrade.!",
+        config_version, package_version
+    );
+    process::exit(1)
+}
+
+fn unsupported_upgrade(current_version: &Version, config_version: &Version) -> ! {
+    eprintln!("Cannot perform upgrade from {} to {}. Please let the developers know about this issue if you expected it to work!", config_version, current_version);
+    process::exit(1)
+}
+
+pub fn command_args<'a, 'b>() -> App<'a, 'b> {
+    App::new("upgrade").about("Try to upgrade the client").arg(
+        Arg::with_name("id")
+            .long("id")
+            .help("Id of the nym-client we want to upgrade")
+            .takes_value(true)
+            .required(true),
+    )
+}
+
+fn parse_config_version(config: &Config) -> Version {
+    let version = Version::parse(config.get_base().get_version()).unwrap_or_else(|err| {
+        eprintln!("failed to parse client version! - {:?}", err);
+        process::exit(1)
+    });
+
+    if version.is_prerelease() || !version.build.is_empty() {
+        eprintln!(
+            "Trying to upgrade from a non-released version {}. This is not supported!",
+            version
+        );
+        process::exit(1)
+    }
+
+    version
+}
+
+fn parse_package_version() -> Version {
+    let version = Version::parse(env!("CARGO_PKG_VERSION")).unwrap();
+
+    // technically this is not a correct way of checking it as a released version might contain valid build identifiers
+    // however, we are not using them ourselves at the moment and hence it should be fine.
+    // if we change our mind, we could easily tweak this code
+    if version.is_prerelease() || !version.build.is_empty() {
+        eprintln!(
+            "Trying to upgrade to a non-released version {}. This is not supported!",
+            version
+        );
+        process::exit(1)
+    }
+
+    version
+}
+
+fn minor_0_12_upgrade(
+    mut config: Config,
+    _matches: &ArgMatches,
+    config_version: &Version,
+    package_version: &Version,
+) -> Config {
+    let to_version = if package_version.major == 0 && package_version.minor == 12 {
+        package_version.clone()
+    } else {
+        Version::new(0, 12, 0)
+    };
+
+    print_start_upgrade(&config_version, &to_version);
+
+    println!(
+        "Setting validator API endpoints to {:?}",
+        default_api_endpoints()
+    );
+
+    config
+        .get_base_mut()
+        .set_custom_validator_apis(default_api_endpoints());
+
+    config
+        .get_base_mut()
+        .set_custom_version(to_version.to_string().as_ref());
+
+    config.save_to_file(None).unwrap_or_else(|err| {
+        eprintln!("failed to overwrite config file! - {:?}", err);
+        print_failed_upgrade(&config_version, &to_version);
+        process::exit(1);
+    });
+
+    print_successful_upgrade(config_version, to_version);
+
+    config
+}
+
+fn do_upgrade(mut config: Config, matches: &ArgMatches, package_version: Version) {
+    loop {
+        let config_version = parse_config_version(&config);
+
+        if config_version == package_version {
+            println!("You're using the most recent version!");
+            return;
+        }
+
+        config = match config_version.major {
+            0 => match config_version.minor {
+                9 | 10 => outdated_upgrade(&config_version, &package_version),
+                11 => minor_0_12_upgrade(config, matches, &config_version, &package_version),
+                _ => unsupported_upgrade(&config_version, &package_version),
+            },
+            _ => unsupported_upgrade(&config_version, &package_version),
+        }
+    }
+}
+
+pub fn execute(matches: &ArgMatches) {
+    let package_version = parse_package_version();
+
+    let id = matches.value_of("id").unwrap();
+
+    let existing_config = Config::load_from_file(Some(id)).unwrap_or_else(|err| {
+        eprintln!("failed to load existing config file! - {:?}", err);
+        process::exit(1)
+    });
+
+    if existing_config.get_base().get_version() == MISSING_VALUE {
+        eprintln!("the existing configuration file does not seem to contain version number.");
+        process::exit(1);
+    }
+
+    // here be upgrade path to 0.9.X and beyond based on version number from config
+    do_upgrade(existing_config, matches, package_version)
+}

clients/native/src/lib.rs

@@ -0,0 +1,5 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod client;
+pub mod websocket;

clients/native/src/main.rs

@@ -0,0 +1,108 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use clap::{crate_version, App, ArgMatches};
+
+pub mod client;
+pub mod commands;
+pub mod websocket;
+
+#[tokio::main]
+async fn main() {
+    dotenv::dotenv().ok();
+    setup_logging();
+    println!("{}", banner());
+
+    let arg_matches = App::new("Nym Client")
+        .version(crate_version!())
+        .long_version(&*long_version())
+        .author("Nymtech")
+        .about("Implementation of the Nym Client")
+        .subcommand(commands::init::command_args())
+        .subcommand(commands::run::command_args())
+        .subcommand(commands::upgrade::command_args())
+        .get_matches();
+
+    execute(arg_matches).await;
+}
+
+async fn execute(matches: ArgMatches<'static>) {
+    match matches.subcommand() {
+        ("init", Some(m)) => commands::init::execute(m.clone()).await,
+        ("run", Some(m)) => commands::run::execute(m.clone()).await,
+        ("upgrade", Some(m)) => commands::upgrade::execute(m),
+        _ => println!("{}", usage()),
+    }
+}
+
+fn usage() -> &'static str {
+    "usage: --help to see available options.\n\n"
+}
+
+fn banner() -> String {
+    format!(
+        r#"
+
+      _ __  _   _ _ __ ___
+     | '_ \| | | | '_ \ _ \
+     | | | | |_| | | | | | |
+     |_| |_|\__, |_| |_| |_|
+            |___/
+
+             (client - version {:})
+
+    "#,
+        crate_version!()
+    )
+}
+
+fn long_version() -> String {
+    format!(
+        r#"
+{:<20}{}
+{:<20}{}
+{:<20}{}
+{:<20}{}
+{:<20}{}
+{:<20}{}
+{:<20}{}
+{:<20}{}
+"#,
+        "Build Timestamp:",
+        env!("VERGEN_BUILD_TIMESTAMP"),
+        "Build Version:",
+        env!("VERGEN_BUILD_SEMVER"),
+        "Commit SHA:",
+        env!("VERGEN_GIT_SHA"),
+        "Commit Date:",
+        env!("VERGEN_GIT_COMMIT_TIMESTAMP"),
+        "Commit Branch:",
+        env!("VERGEN_GIT_BRANCH"),
+        "rustc Version:",
+        env!("VERGEN_RUSTC_SEMVER"),
+        "rustc Channel:",
+        env!("VERGEN_RUSTC_CHANNEL"),
+        "cargo Profile:",
+        env!("VERGEN_CARGO_PROFILE"),
+    )
+}
+
+fn setup_logging() {
+    let mut log_builder = pretty_env_logger::formatted_timed_builder();
+    if let Ok(s) = ::std::env::var("RUST_LOG") {
+        log_builder.parse_filters(&s);
+    } else {
+        // default to 'Info'
+        log_builder.filter(None, log::LevelFilter::Info);
+    }
+
+    log_builder
+        .filter_module("hyper", log::LevelFilter::Warn)
+        .filter_module("tokio_reactor", log::LevelFilter::Warn)
+        .filter_module("reqwest", log::LevelFilter::Warn)
+        .filter_module("mio", log::LevelFilter::Warn)
+        .filter_module("want", log::LevelFilter::Warn)
+        .filter_module("tungstenite", log::LevelFilter::Warn)
+        .filter_module("tokio_tungstenite", log::LevelFilter::Warn)
+        .init();
+}

clients/native/src/websocket/handler.rs

@@ -0,0 +1,293 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use client_core::client::{
+    inbound_messages::{InputMessage, InputMessageSender},
+    received_buffer::{
+        ReceivedBufferMessage, ReceivedBufferRequestSender, ReconstructedMessagesReceiver,
+    },
+};
+use futures::channel::mpsc;
+use futures::{SinkExt, StreamExt};
+use log::*;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::anonymous_replies::ReplySurb;
+use nymsphinx::receiver::ReconstructedMessage;
+use tokio::net::TcpStream;
+use tokio_tungstenite::{
+    accept_async,
+    tungstenite::{protocol::Message as WsMessage, Error as WsError},
+    WebSocketStream,
+};
+use websocket_requests::{requests::ClientRequest, responses::ServerResponse};
+
+enum ReceivedResponseType {
+    Binary,
+    Text,
+}
+
+impl Default for ReceivedResponseType {
+    fn default() -> Self {
+        ReceivedResponseType::Binary
+    }
+}
+
+pub(crate) struct Handler {
+    msg_input: InputMessageSender,
+    buffer_requester: ReceivedBufferRequestSender,
+    self_full_address: Recipient,
+    socket: Option<WebSocketStream<TcpStream>>,
+    received_response_type: ReceivedResponseType,
+}
+
+// clone is used to use handler on a new connection, which initially is `None`
+impl Clone for Handler {
+    fn clone(&self) -> Self {
+        Handler {
+            msg_input: self.msg_input.clone(),
+            buffer_requester: self.buffer_requester.clone(),
+            self_full_address: self.self_full_address,
+            socket: None,
+            received_response_type: Default::default(),
+        }
+    }
+}
+
+impl Drop for Handler {
+    fn drop(&mut self) {
+        self.buffer_requester
+            .unbounded_send(ReceivedBufferMessage::ReceiverDisconnect)
+            .expect("the buffer request failed!")
+    }
+}
+
+impl Handler {
+    pub(crate) fn new(
+        msg_input: InputMessageSender,
+        buffer_requester: ReceivedBufferRequestSender,
+        self_full_address: Recipient,
+    ) -> Self {
+        Handler {
+            msg_input,
+            buffer_requester,
+            self_full_address,
+            socket: None,
+            received_response_type: Default::default(),
+        }
+    }
+
+    fn handle_send(
+        &mut self,
+        recipient: Recipient,
+        message: Vec<u8>,
+        with_reply_surb: bool,
+    ) -> Option<ServerResponse> {
+        // the ack control is now responsible for chunking, etc.
+        let input_msg = InputMessage::new_fresh(recipient, message, with_reply_surb);
+        self.msg_input.unbounded_send(input_msg).unwrap();
+
+        None
+    }
+
+    fn handle_reply(&mut self, reply_surb: ReplySurb, message: Vec<u8>) -> Option<ServerResponse> {
+        if message.len() > ReplySurb::max_msg_len(Default::default()) {
+            return Some(ServerResponse::new_error(format!("too long message to put inside a reply SURB. Received: {} bytes and maximum is {} bytes", message.len(), ReplySurb::max_msg_len(Default::default()))));
+        }
+
+        let input_msg = InputMessage::new_reply(reply_surb, message);
+        self.msg_input.unbounded_send(input_msg).unwrap();
+
+        None
+    }
+
+    fn handle_self_address(&self) -> ServerResponse {
+        ServerResponse::SelfAddress(self.self_full_address)
+    }
+
+    fn handle_request(&mut self, request: ClientRequest) -> Option<ServerResponse> {
+        match request {
+            ClientRequest::Send {
+                recipient,
+                message,
+                with_reply_surb,
+            } => self.handle_send(recipient, message, with_reply_surb),
+            ClientRequest::Reply {
+                message,
+                reply_surb,
+            } => self.handle_reply(reply_surb, message),
+            ClientRequest::SelfAddress => Some(self.handle_self_address()),
+        }
+    }
+
+    fn handle_text_message(&mut self, msg: String) -> Option<WsMessage> {
+        debug!("Handling text message request");
+        trace!("Content: {:?}", msg);
+
+        self.received_response_type = ReceivedResponseType::Text;
+        let client_request = ClientRequest::try_from_text(msg);
+
+        let response = match client_request {
+            Err(err) => Some(ServerResponse::Error(err)),
+            Ok(req) => self.handle_request(req),
+        };
+
+        response.map(|resp| WsMessage::text(resp.into_text()))
+    }
+
+    fn handle_binary_message(&mut self, msg: Vec<u8>) -> Option<WsMessage> {
+        debug!("Handling binary message request");
+
+        self.received_response_type = ReceivedResponseType::Binary;
+        let client_request = ClientRequest::try_from_binary(msg);
+
+        let response = match client_request {
+            Err(err) => Some(ServerResponse::Error(err)),
+            Ok(req) => self.handle_request(req),
+        };
+
+        response.map(|resp| WsMessage::Binary(resp.into_binary()))
+    }
+
+    fn handle_ws_request(&mut self, raw_request: WsMessage) -> Option<WsMessage> {
+        // apparently tungstenite auto-handles ping/pong/close messages so for now let's ignore
+        // them and let's test that claim. If that's not the case, just copy code from
+        // old version of this file.
+        match raw_request {
+            WsMessage::Text(text_message) => self.handle_text_message(text_message),
+            WsMessage::Binary(binary_message) => self.handle_binary_message(binary_message),
+            _ => None,
+        }
+    }
+
+    // I'm still not entirely sure why `send_all` requires `TryStream` rather than `Stream`, but
+    // let's just play along for now
+    fn prepare_reconstructed_binary(
+        &self,
+        reconstructed_messages: Vec<ReconstructedMessage>,
+    ) -> Vec<Result<WsMessage, WsError>> {
+        reconstructed_messages
+            .into_iter()
+            .map(ServerResponse::Received)
+            .map(|resp| Ok(WsMessage::Binary(resp.into_binary())))
+            .collect()
+    }
+
+    // I'm still not entirely sure why `send_all` requires `TryStream` rather than `Stream`, but
+    // let's just play along for now
+    fn prepare_reconstructed_text(
+        &self,
+        reconstructed_messages: Vec<ReconstructedMessage>,
+    ) -> Vec<Result<WsMessage, WsError>> {
+        reconstructed_messages
+            .into_iter()
+            .map(ServerResponse::Received)
+            .map(|resp| Ok(WsMessage::Text(resp.into_text())))
+            .collect()
+    }
+
+    async fn push_websocket_received_plaintexts(
+        &mut self,
+        reconstructed_messages: Vec<ReconstructedMessage>,
+    ) -> Result<(), WsError> {
+        // TODO: later there might be a flag on the reconstructed message itself to tell us
+        // if it's text or binary, but for time being we use the naive assumption that if
+        // client is sending Message::Text it expects text back. Same for Message::Binary
+        let response_messages = match self.received_response_type {
+            ReceivedResponseType::Binary => {
+                self.prepare_reconstructed_binary(reconstructed_messages)
+            }
+            ReceivedResponseType::Text => self.prepare_reconstructed_text(reconstructed_messages),
+        };
+
+        let mut send_stream = futures::stream::iter(response_messages);
+        self.socket
+            .as_mut()
+            .unwrap()
+            .send_all(&mut send_stream)
+            .await
+    }
+
+    async fn send_websocket_response(&mut self, msg: WsMessage) -> Result<(), WsError> {
+        match self.socket {
+            // TODO: more closely investigate difference between `Sink::send` and `Sink::send_all`
+            // it got something to do with batching and flushing - it might be important if it
+            // turns out somehow we've got a bottleneck here
+            Some(ref mut ws_stream) => ws_stream.send(msg).await,
+            _ => panic!("impossible state - websocket handshake was somehow reverted"),
+        }
+    }
+
+    async fn next_websocket_request(&mut self) -> Option<Result<WsMessage, WsError>> {
+        match self.socket {
+            Some(ref mut ws_stream) => ws_stream.next().await,
+            None => None,
+        }
+    }
+
+    async fn listen_for_requests(&mut self, mut msg_receiver: ReconstructedMessagesReceiver) {
+        loop {
+            tokio::select! {
+                // we can either get a client request from the websocket
+                socket_msg = self.next_websocket_request() => {
+                    if socket_msg.is_none() {
+                        break;
+                    }
+                    let socket_msg = match socket_msg.unwrap() {
+                        Ok(socket_msg) => socket_msg,
+                        Err(err) => {
+                            warn!("failed to obtain message from websocket stream! stopping connection handler: {}", err);
+                            break;
+                        }
+                    };
+
+                    if socket_msg.is_close() {
+                        break;
+                    }
+
+                    if let Some(response) = self.handle_ws_request(socket_msg) {
+                        if let Err(err) = self.send_websocket_response(response).await {
+                            warn!(
+                                "Failed to send message over websocket: {}. Assuming the connection is dead.",
+                                err
+                            );
+                            break;
+                        }
+                    }
+                }
+                // or a reconstructed mix message that we need to push back to the client
+                mix_messages = msg_receiver.next() => {
+                    let mix_messages = mix_messages.expect(
+                        "mix messages sender was unexpectedly closed! this shouldn't have ever happened!",
+                    );
+                    if let Err(e) = self.push_websocket_received_plaintexts(mix_messages).await {
+                        warn!("failed to send sphinx packets back to the client - {:?}, assuming the connection is dead", e);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    // consume self to make sure `drop` is called after this is done
+    pub(crate) async fn handle_connection(mut self, socket: TcpStream) {
+        let ws_stream = match accept_async(socket).await {
+            Ok(ws_stream) => ws_stream,
+            Err(err) => {
+                warn!("error while performing the websocket handshake - {:?}", err);
+                return;
+            }
+        };
+        self.socket = Some(ws_stream);
+
+        let (reconstructed_sender, reconstructed_receiver) = mpsc::unbounded();
+
+        // tell the buffer to start sending stuff to us
+        self.buffer_requester
+            .unbounded_send(ReceivedBufferMessage::ReceiverAnnounce(
+                reconstructed_sender,
+            ))
+            .expect("the buffer request failed!");
+
+        self.listen_for_requests(reconstructed_receiver).await;
+    }
+}

clients/native/src/websocket/listener.rs

@@ -0,0 +1,94 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use super::handler::Handler;
+use log::*;
+use std::{net::SocketAddr, process, sync::Arc};
+use tokio::io::AsyncWriteExt;
+use tokio::{sync::Notify, task::JoinHandle};
+
+enum State {
+    Connected,
+    AwaitingConnection,
+}
+
+impl State {
+    fn is_connected(&self) -> bool {
+        matches!(self, State::Connected)
+    }
+}
+
+pub(crate) struct Listener {
+    address: SocketAddr,
+    state: State,
+}
+
+impl Listener {
+    pub(crate) fn new(port: u16) -> Self {
+        Listener {
+            // unless we find compelling reason not to, just listen on local only
+            address: SocketAddr::new("127.0.0.1".parse().unwrap(), port),
+            state: State::AwaitingConnection,
+        }
+    }
+
+    pub(crate) async fn run(&mut self, handler: Handler) {
+        let tcp_listener = match tokio::net::TcpListener::bind(self.address).await {
+            Ok(listener) => listener,
+            Err(err) => {
+                error!("Failed to bind to {} - {}. Are you sure nothing else is running on the specified port and your user has sufficient permission to bind to the requested address?", self.address, err);
+                process::exit(1);
+            }
+        };
+
+        let notify = Arc::new(Notify::new());
+
+        loop {
+            tokio::select! {
+                _ = notify.notified() => {
+                    // our connection terminated - we are open to a new one now!
+                    self.state = State::AwaitingConnection;
+                }
+                new_conn = tcp_listener.accept() => {
+                    match new_conn {
+                        Ok((mut socket, remote_addr)) => {
+                            debug!("Received connection from {:?}", remote_addr);
+                            if self.state.is_connected() {
+                                warn!("tried to duplicate!");
+                                // if we've already got a connection, don't allow another one
+                                debug!("but there was already a connection present!");
+                                // while we only ever want to accept a single connection, we don't want
+                                // to leave clients hanging (and also allow for reconnection if it somehow
+                                // was dropped)
+                                match socket.shutdown().await {
+                                    Ok(_) => trace!(
+                                        "closed the connection between attempting websocket handshake"
+                                    ),
+                                    Err(e) => warn!("failed to cleanly close the connection - {:?}", e),
+                                };
+                            } else {
+                                // even though we're spawning a new task with the handler here, we will only ever spawn a single one.
+                                // it's done so that any new connections to this listener could be rejected rather than left
+                                // hanging because the executor doesn't come back here
+                                let notify_clone = Arc::clone(&notify);
+                                let fresh_handler = handler.clone();
+                                tokio::spawn(async move {
+                                    fresh_handler.handle_connection(socket).await;
+                                    notify_clone.notify_one();
+                                });
+                                self.state = State::Connected;
+                            }
+                        }
+                        Err(e) => warn!("failed to get client: {:?}", e),
+                    }
+                }
+            }
+        }
+    }
+
+    pub(crate) fn start(mut self, handler: Handler) -> JoinHandle<()> {
+        info!("Running websocket on {:?}", self.address.to_string());
+
+        tokio::spawn(async move { self.run(handler).await })
+    }
+}

clients/native/src/websocket/mod.rs

@@ -0,0 +1,8 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub(crate) use handler::Handler;
+pub(crate) use listener::Listener;
+
+pub(crate) mod handler;
+pub(crate) mod listener;

clients/native/websocket-requests/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "websocket-requests"
+version = "0.1.0"
+authors = ["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]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+nymsphinx = { path = "../../../common/nymsphinx" }

clients/native/websocket-requests/src/error.rs

@@ -0,0 +1,81 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+use std::fmt;
+
+// no need to go fancy here like we've done in other places.
+#[derive(PartialEq, Clone, Serialize, Deserialize)]
+pub struct Error {
+    pub kind: ErrorKind,
+    pub message: String,
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}:{}", self.kind.as_str(), self.message)
+    }
+}
+
+impl fmt::Debug for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Display::fmt(self, f)
+    }
+}
+
+impl Error {
+    pub fn new(kind: ErrorKind, message: String) -> Self {
+        Error { kind, message }
+    }
+}
+
+#[repr(u8)]
+#[derive(PartialEq, Clone, Serialize, Deserialize)]
+pub enum ErrorKind {
+    /// The received request contained no data.
+    EmptyRequest = 0x01,
+
+    /// The received request did not contain enough data to be fully parsed.
+    TooShortRequest = 0x02,
+
+    /// The received request tag is not defined.
+    UnknownRequest = 0x03,
+
+    /// The received request is malformed.
+    MalformedRequest = 0x04,
+
+    // that's an arbitrary division but let's keep 1-127 (hex 0x01 - 0x7F) values request-specific
+    // and 128-254 (hex 0x80 - 0xFE) for responses
+    /// The received response contained no data.
+    EmptyResponse = 0x80,
+
+    /// The received response did not contain enough data to be fully parsed.
+    TooShortResponse = 0x81,
+
+    /// The received response tag is not defined.
+    UnknownResponse = 0x82,
+
+    /// The received response is malformed.
+    MalformedResponse = 0x83,
+
+    /// The error is due to something else.
+    Other = 0xFF,
+}
+
+impl ErrorKind {
+    pub(crate) fn as_str(&self) -> &'static str {
+        match *self {
+            ErrorKind::EmptyRequest => "received request contained no data",
+            ErrorKind::TooShortRequest => "received request did not contain enough data",
+            ErrorKind::UnknownRequest => "unknown request type",
+            ErrorKind::MalformedRequest => "malformed request",
+
+            ErrorKind::EmptyResponse => "received response contained no data",
+            ErrorKind::TooShortResponse => "received response did not contain enough data",
+            ErrorKind::UnknownResponse => "unknown response type",
+            ErrorKind::MalformedResponse => "malformed response",
+
+            ErrorKind::Other => "other",
+        }
+    }
+}

clients/native/websocket-requests/src/lib.rs

@@ -0,0 +1,7 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+pub mod error;
+pub mod requests;
+pub mod responses;
+mod text;

clients/native/websocket-requests/src/requests.rs

@@ -0,0 +1,355 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// all variable size data is always prefixed with u64 length
+// tags are u8
+
+use crate::error::{self, ErrorKind};
+use crate::text::ClientRequestText;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::anonymous_replies::ReplySurb;
+use std::convert::{TryFrom, TryInto};
+use std::mem::size_of;
+
+/// Value tag representing [`Send`] variant of the [`ClientRequest`]
+pub const SEND_REQUEST_TAG: u8 = 0x00;
+
+/// Value tag representing [`Reply`] variant of the [`ClientRequest`]
+pub const REPLY_REQUEST_TAG: u8 = 0x01;
+
+/// Value tag representing [`SelfAddress`] variant of the [`ClientRequest`]
+pub const SELF_ADDRESS_REQUEST_TAG: u8 = 0x02;
+
+#[allow(non_snake_case)]
+#[derive(Debug)]
+pub enum ClientRequest {
+    Send {
+        recipient: Recipient,
+        message: Vec<u8>,
+        // Perhaps we could change it to a number to indicate how many reply_SURBs we want to include?
+        with_reply_surb: bool,
+    },
+    Reply {
+        message: Vec<u8>,
+        reply_surb: ReplySurb,
+    },
+    SelfAddress,
+}
+
+// we could have been parsing it directly TryFrom<WsMessage>, but we want to retain
+// information about whether it came from binary or text to send appropriate response back
+impl ClientRequest {
+    // SEND_REQUEST_TAG || with_surb || recipient || data_len || data
+    fn serialize_send(recipient: Recipient, data: Vec<u8>, with_reply_surb: bool) -> Vec<u8> {
+        let data_len_bytes = (data.len() as u64).to_be_bytes();
+        std::iter::once(SEND_REQUEST_TAG)
+            .chain(std::iter::once(with_reply_surb as u8))
+            .chain(recipient.to_bytes().iter().cloned()) // will not be length prefixed because the length is constant
+            .chain(data_len_bytes.iter().cloned())
+            .chain(data.into_iter())
+            .collect()
+    }
+
+    // SEND_REQUEST_TAG || with_reply || recipient || data_len || data
+    fn deserialize_send(b: &[u8]) -> Result<Self, error::Error> {
+        // we need to have at least 1 (tag) + 1 (reply flag) + Recipient::LEN + sizeof<u64> bytes
+        if b.len() < 2 + Recipient::LEN + size_of::<u64>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortRequest,
+                "not enough data provided to recover 'send'".to_string(),
+            ));
+        }
+
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], SEND_REQUEST_TAG);
+
+        let with_reply_surb = match b[1] {
+            0 => false,
+            1 => true,
+            n => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedRequest,
+                    format!("invalid reply surb flag {}", n),
+                ))
+            }
+        };
+
+        let mut recipient_bytes = [0u8; Recipient::LEN];
+        recipient_bytes.copy_from_slice(&b[2..2 + Recipient::LEN]);
+        let recipient = match Recipient::try_from_bytes(recipient_bytes) {
+            Ok(recipient) => recipient,
+            Err(err) => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedRequest,
+                    format!("malformed recipient: {:?}", err),
+                ))
+            }
+        };
+
+        let data_len_bytes = &b[2 + Recipient::LEN..2 + Recipient::LEN + size_of::<u64>()];
+        let data_len = u64::from_be_bytes(data_len_bytes.try_into().unwrap());
+        let data = &b[2 + Recipient::LEN + size_of::<u64>()..];
+        if data.len() as u64 != data_len {
+            return Err(error::Error::new(
+                ErrorKind::MalformedRequest,
+                format!(
+                    "data len has inconsistent length. specified: {} got: {}",
+                    data_len,
+                    data.len()
+                ),
+            ));
+        }
+
+        Ok(ClientRequest::Send {
+            with_reply_surb,
+            recipient,
+            message: data.to_vec(),
+        })
+    }
+
+    // REPLY_REQUEST_TAG || surb_len || surb || message_len || message
+    fn serialize_reply(message: Vec<u8>, reply_surb: ReplySurb) -> Vec<u8> {
+        let reply_surb_bytes = reply_surb.to_bytes();
+        let surb_len_bytes = (reply_surb_bytes.len() as u64).to_be_bytes();
+        let message_len_bytes = (message.len() as u64).to_be_bytes();
+
+        std::iter::once(REPLY_REQUEST_TAG)
+            .chain(surb_len_bytes.iter().cloned())
+            .chain(reply_surb_bytes.into_iter())
+            .chain(message_len_bytes.iter().cloned())
+            .chain(message.into_iter())
+            .collect()
+    }
+
+    // REPLY_REQUEST_TAG || surb_len || surb || message_len || message
+    fn deserialize_reply(b: &[u8]) -> Result<Self, error::Error> {
+        // we need to have at the very least 2 * sizeof<u64> bytes (in case, for some peculiar reason
+        // message and reply surb were 0 len - the request would still be malformed, but would in theory
+        // be parse'able)
+        if b.len() < 1 + 2 * size_of::<u64>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortRequest,
+                "not enough data provided to recover 'reply'".to_string(),
+            ));
+        }
+
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], REPLY_REQUEST_TAG);
+
+        let reply_surb_len =
+            u64::from_be_bytes(b[1..1 + size_of::<u64>()].as_ref().try_into().unwrap());
+
+        // make sure we won't go out of bounds here
+        if reply_surb_len > (b.len() - 1 + 2 * size_of::<u64>()) as u64 {
+            return Err(error::Error::new(
+                ErrorKind::MalformedRequest,
+                format!(
+                    "not enough data to recover reply surb with specified length {}",
+                    reply_surb_len
+                ),
+            ));
+        }
+
+        let surb_bound = 1 + size_of::<u64>() + reply_surb_len as usize;
+
+        let reply_surb_bytes = &b[1 + size_of::<u64>()..surb_bound];
+        let reply_surb = match ReplySurb::from_bytes(reply_surb_bytes) {
+            Ok(reply_surb) => reply_surb,
+            Err(err) => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedRequest,
+                    format!("malformed reply surb: {:?}", err),
+                ))
+            }
+        };
+
+        let message_len = u64::from_be_bytes(
+            b[surb_bound..surb_bound + size_of::<u64>()]
+                .as_ref()
+                .try_into()
+                .unwrap(),
+        );
+        let message = &b[surb_bound + size_of::<u64>()..];
+        if message.len() as u64 != message_len {
+            return Err(error::Error::new(
+                ErrorKind::MalformedRequest,
+                format!(
+                    "message len has inconsistent length. specified: {} got: {}",
+                    message_len,
+                    message.len()
+                ),
+            ));
+        }
+        // TODO: should this blow HERE, i.e. during deserialization that the data you're trying
+        // to send via reply is too long?
+
+        Ok(ClientRequest::Reply {
+            reply_surb,
+            message: message.to_vec(),
+        })
+    }
+
+    // SELF_ADDRESS_REQUEST_TAG
+    fn serialize_self_address() -> Vec<u8> {
+        std::iter::once(SELF_ADDRESS_REQUEST_TAG).collect()
+    }
+
+    // SELF_ADDRESS_REQUEST_TAG
+    fn deserialize_self_address(b: &[u8]) -> Self {
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], SELF_ADDRESS_REQUEST_TAG);
+
+        ClientRequest::SelfAddress
+    }
+
+    pub fn serialize(self) -> Vec<u8> {
+        match self {
+            ClientRequest::Send {
+                recipient,
+                message,
+                with_reply_surb,
+            } => Self::serialize_send(recipient, message, with_reply_surb),
+
+            ClientRequest::Reply {
+                message,
+                reply_surb,
+            } => Self::serialize_reply(message, reply_surb),
+
+            ClientRequest::SelfAddress => Self::serialize_self_address(),
+        }
+    }
+
+    pub fn deserialize(b: &[u8]) -> Result<Self, error::Error> {
+        if b.is_empty() {
+            // technically I'm not even sure this can ever be returned, because reading empty
+            // request would imply closed socket, but let's include it for completion sake
+            return Err(error::Error::new(
+                ErrorKind::EmptyRequest,
+                "no data provided".to_string(),
+            ));
+        }
+
+        if b.len() < size_of::<u8>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortRequest,
+                format!(
+                    "not enough data provided to recover request tag. Provided only {} bytes",
+                    b.len()
+                ),
+            ));
+        }
+        let request_tag = b[0];
+
+        // determine what kind of request that is and try to deserialize it
+        match request_tag {
+            SEND_REQUEST_TAG => Self::deserialize_send(b),
+            REPLY_REQUEST_TAG => Self::deserialize_reply(b),
+            SELF_ADDRESS_REQUEST_TAG => Ok(Self::deserialize_self_address(b)),
+            n => Err(error::Error::new(
+                ErrorKind::UnknownRequest,
+                format!("type {}", n),
+            )),
+        }
+    }
+
+    pub fn try_from_binary(raw_req: Vec<u8>) -> Result<Self, error::Error> {
+        Self::deserialize(&raw_req)
+    }
+
+    pub fn try_from_text(raw_req: String) -> Result<Self, error::Error> {
+        // use the intermediate string structure and let serde do bunch of work for us
+        let text_req = ClientRequestText::try_from(raw_req).map_err(|json_err| {
+            error::Error::new(ErrorKind::MalformedRequest, json_err.to_string())
+        })?;
+
+        text_req.try_into()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // very basic tests to check for obvious errors like off by one
+    #[test]
+    fn send_request_serialization_works() {
+        let recipient = Recipient::try_from_base58_string("CytBseW6yFXUMzz4SGAKdNLGR7q3sJLLYxyBGvutNEQV.4QXYyEVc5fUDjmmi8PrHN9tdUFV4PCvSJE1278cHyvoe@4sBbL1ngf1vtNqykydQKTFh26sQCw888GpUqvPvyNB4f").unwrap();
+        let recipient_string = recipient.to_string();
+
+        let send_request_no_surb = ClientRequest::Send {
+            recipient,
+            message: b"foomp".to_vec(),
+            with_reply_surb: false,
+        };
+
+        let bytes = send_request_no_surb.serialize();
+        let recovered = ClientRequest::deserialize(&bytes).unwrap();
+        match recovered {
+            ClientRequest::Send {
+                recipient,
+                message,
+                with_reply_surb,
+            } => {
+                assert_eq!(recipient.to_string(), recipient_string);
+                assert_eq!(message, b"foomp".to_vec());
+                assert!(!with_reply_surb)
+            }
+            _ => unreachable!(),
+        }
+
+        let send_request_surb = ClientRequest::Send {
+            recipient,
+            message: b"foomp".to_vec(),
+            with_reply_surb: true,
+        };
+
+        let bytes = send_request_surb.serialize();
+        let recovered = ClientRequest::deserialize(&bytes).unwrap();
+        match recovered {
+            ClientRequest::Send {
+                recipient,
+                message,
+                with_reply_surb,
+            } => {
+                assert_eq!(recipient.to_string(), recipient_string);
+                assert_eq!(message, b"foomp".to_vec());
+                assert!(with_reply_surb)
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn reply_request_serialization_works() {
+        let reply_surb_string = "CjfVbHbfAjbC3W1BvNHGXmM8KNAnDNYGaHMLqVDxRYeo352csAihstup9bvqXam4dTWgfHak6KYwL9STaxWJ47E8XFZbSEvs7hEsfCkxr6K9WJuSBPK84GDDEvad8ZAuMCoaXsAd5S2Lj9a5eYyzG4SL1jHzhSMni55LyJwumxo1ZTGZNXggxw1RREosvyzNrW9Rsi3owyPqLCwXpiei2tHZty8w8midVvg8vDa7ZEJD842CLv8D4ohynSG7gDpqTrhkRaqYAuz7dzqNbMXLJRM7v823Jn16fA1L7YQxmcaUdUigyRSgTdb4i9ebiLGSyJ1iDe6Acz613PQZh6Ua3bZ2zVKq3dSycpDm9ngarRK4zJrAaUxRkdih8YzW3BY4nL9eqkfKA4N1TWCLaRU7zpSaf8yMEwrAZReU3d5zLV8c5KBfa2w8R5anhQeBojduZEGEad8kkHuKU52Zg93FeWHvH1qgZaEJMHH4nN7gKXz9mvWDhYwyF4vt3Uy2NhCHC3N5pL1gMme27YcoPcTEia1fxKZtnt6rtEozzTrAgCJGswigkFbkafiV5QaJwLKTUxtzhkZ57eEuLPte9UvJHzhhXUQ2CV7R2BUkJjYZy3Zsx6YYvdYWiAFFkWUwNEGA4QpShUHciBfsQVHQ7pN41YcyYUhbywQDFnTVgEmdUZ1XCBi3gyK5U3tDQmFzP1u9m3mWrUA8qB9mRDE7ptNDm5c3c1458L6uXLUth7sdMaa1Was5LCmCdmNDtvNpCDAEt1in6q6mrZFR85aCSU9b1baNGwZoCqPpPvydkVe63gXWoi8ebvdyxARrqACFrSB3ZdY3uJBw8CTMNkKK6MvcefMkSVVsbLd36TQAtYSCqrpiMc5dQuKcEu5QfciwvWYXYx8WFNAgKwP2mv49KCTvfozNDUCbjzDwSx92Zv5zjG8HbFpB13bY9UZGeyTPvv7gGxCzjGjJGbW6FRAheRQaaje5fUgCNM95Tv7wBmAMRHHFgWafeK1sdFH7dtCX9u898HucGTaboSKLsVh8J78gbbkHErwjMh7y9YRkceq5TTYS5da4kHnyNKYWSbxgZrmFg44XGKoeYcqoHB3XTZrdsf7F5fFeNwnihkmADvhAcaxXUmVqq4rQFZH84a1iC3WBWXYcqiZH2L7ujGWV7mMDT4HBEerDYjc8rNY4xGTPfivCrBCJW1i14aqW8xRdsdgTM88eTksvC3WPJLJ7iMzfKXeL7fMW1Ek6QGyQtLBW98vEESpdcDg6DeZ5rMz6VqjTGGqcCaFGfHoqtfxMDaBAEsyQ8h7XDX6dg1wq9wH6j4Tw7Tj1MEv1b8uj5NJkozZdzVdYA2QyE2Dp8vuurQG6uVdTDNww2d88RBQ8sVgjxN8gR45y4woJLhFAaNTAtrY6wDTxyXST13ni6oyqdYxjFVk9Am4v3DzH7Y2K8iRVSHfTk4FRbPULyaeK6wt2anvMJH1XdvVRgc14h67MnBxMgMD1UFk8AErN7CDj26fppe3c5G6KozJe4cSqQUGbBjVzBnrHCruqrfZBn5hNZHTV37bQiomqhRQXohxhuKEnNrGbAe1xNvJr9X";
+        let reply_surb = ReplySurb::from_base58_string(reply_surb_string).unwrap();
+        let reply_request = ClientRequest::Reply {
+            message: b"foomp".to_vec(),
+            reply_surb,
+        };
+
+        let bytes = reply_request.serialize();
+        let recovered = ClientRequest::deserialize(&bytes).unwrap();
+        match recovered {
+            ClientRequest::Reply {
+                reply_surb,
+                message,
+            } => {
+                assert_eq!(reply_surb.to_base58_string(), reply_surb_string);
+                assert_eq!(message, b"foomp".to_vec());
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn self_address_request_serialization_works() {
+        let self_address_request = ClientRequest::SelfAddress;
+        let bytes = self_address_request.serialize();
+        let recovered = ClientRequest::deserialize(&bytes).unwrap();
+        match recovered {
+            ClientRequest::SelfAddress => (),
+            _ => unreachable!(),
+        }
+    }
+}

clients/native/websocket-requests/src/responses.rs

@@ -0,0 +1,392 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// all variable size data is always prefixed with u64 length
+// tags are u8
+
+#![allow(unknown_lints)] // due to using `clippy::branches_sharing_code` which does not exist on `stable` just yet
+
+use crate::error::{self, ErrorKind};
+use crate::text::ServerResponseText;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::anonymous_replies::ReplySurb;
+use nymsphinx::receiver::ReconstructedMessage;
+use std::convert::TryInto;
+use std::mem::size_of;
+
+/// Value tag representing [`Error`] variant of the [`ServerResponse`]
+pub const ERROR_RESPONSE_TAG: u8 = 0x00;
+
+/// Value tag representing [`Received`] variant of the [`ServerResponse`]
+pub const RECEIVED_RESPONSE_TAG: u8 = 0x01;
+
+/// Value tag representing [`SelfAddress`] variant of the [`ServerResponse`]
+pub const SELF_ADDRESS_RESPONSE_TAG: u8 = 0x02;
+
+#[derive(Debug)]
+pub enum ServerResponse {
+    Received(ReconstructedMessage),
+    SelfAddress(Recipient),
+    Error(error::Error),
+}
+
+impl ServerResponse {
+    pub fn new_error<S: Into<String>>(message: S) -> Self {
+        ServerResponse::Error(error::Error {
+            kind: ErrorKind::Other,
+            message: message.into(),
+        })
+    }
+
+    // RECEIVED_RESPONSE_TAG || with_reply || (surb_len || surb) || msg_len || msg
+    fn serialize_received(reconstructed_message: ReconstructedMessage) -> Vec<u8> {
+        let message_len_bytes = (reconstructed_message.message.len() as u64).to_be_bytes();
+        if let Some(reply_surb) = reconstructed_message.reply_surb {
+            let reply_surb_bytes = reply_surb.to_bytes();
+            let surb_len_bytes = (reply_surb_bytes.len() as u64).to_be_bytes();
+
+            // with_reply || surb_len || surb || msg_len || msg
+            std::iter::once(RECEIVED_RESPONSE_TAG)
+                .chain(std::iter::once(true as u8))
+                .chain(surb_len_bytes.iter().cloned())
+                .chain(reply_surb_bytes.iter().cloned())
+                .chain(message_len_bytes.iter().cloned())
+                .chain(reconstructed_message.message.into_iter())
+                .collect()
+        } else {
+            // without_reply || msg_len || msg
+            std::iter::once(RECEIVED_RESPONSE_TAG)
+                .chain(std::iter::once(false as u8))
+                .chain(message_len_bytes.iter().cloned())
+                .chain(reconstructed_message.message.into_iter())
+                .collect()
+        }
+    }
+
+    // RECEIVED_RESPONSE_TAG || with_reply || (surb_len || surb) || msg_len || msg
+    fn deserialize_received(b: &[u8]) -> Result<Self, error::Error> {
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], RECEIVED_RESPONSE_TAG);
+
+        // we must be able to read at the very least if it has a reply_surb and length of some field
+        if b.len() < 2 + size_of::<u64>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortResponse,
+                "not enough data provided to recover 'received'".to_string(),
+            ));
+        }
+
+        let with_reply_surb = match b[1] {
+            0 => false,
+            1 => true,
+            n => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!("invalid reply flag {}", n),
+                ))
+            }
+        };
+
+        // this is a false positive as even though the code is the same, it refers to different things
+        #[allow(clippy::branches_sharing_code)]
+        if with_reply_surb {
+            let reply_surb_len =
+                u64::from_be_bytes(b[2..2 + size_of::<u64>()].as_ref().try_into().unwrap());
+
+            // make sure we won't go out of bounds here
+            if reply_surb_len > (b.len() - 2 + 2 * size_of::<u64>()) as u64 {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    "not enough bytes to read reply_surb bytes!".to_string(),
+                ));
+            }
+
+            let surb_bound = 2 + size_of::<u64>() + reply_surb_len as usize;
+
+            let reply_surb_bytes = &b[2 + size_of::<u64>()..surb_bound];
+            let reply_surb = match ReplySurb::from_bytes(reply_surb_bytes) {
+                Ok(reply_surb) => reply_surb,
+                Err(err) => {
+                    return Err(error::Error::new(
+                        ErrorKind::MalformedResponse,
+                        format!("malformed reply SURB: {:?}", err),
+                    ))
+                }
+            };
+
+            let message_len = u64::from_be_bytes(
+                b[surb_bound..surb_bound + size_of::<u64>()]
+                    .as_ref()
+                    .try_into()
+                    .unwrap(),
+            );
+            let message = &b[surb_bound + size_of::<u64>()..];
+            if message.len() as u64 != message_len {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!(
+                        "message len has inconsistent length. specified: {} got: {}",
+                        message_len,
+                        message.len()
+                    ),
+                ));
+            }
+
+            Ok(ServerResponse::Received(ReconstructedMessage {
+                message: message.to_vec(),
+                reply_surb: Some(reply_surb),
+            }))
+        } else {
+            let message_len =
+                u64::from_be_bytes(b[2..2 + size_of::<u64>()].as_ref().try_into().unwrap());
+            let message = &b[2 + size_of::<u64>()..];
+            if message.len() as u64 != message_len {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!(
+                        "message len has inconsistent length. specified: {} got: {}",
+                        message_len,
+                        message.len()
+                    ),
+                ));
+            }
+
+            Ok(ServerResponse::Received(ReconstructedMessage {
+                message: message.to_vec(),
+                reply_surb: None,
+            }))
+        }
+    }
+
+    // SELF_ADDRESS_RESPONSE_TAG || self_address
+    fn serialize_self_address(address: Recipient) -> Vec<u8> {
+        std::iter::once(SELF_ADDRESS_RESPONSE_TAG)
+            .chain(address.to_bytes().iter().cloned())
+            .collect()
+    }
+
+    // SELF_ADDRESS_RESPONSE_TAG || self_address
+    fn deserialize_self_address(b: &[u8]) -> Result<Self, error::Error> {
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], SELF_ADDRESS_RESPONSE_TAG);
+
+        if b.len() != 1 + Recipient::LEN {
+            return Err(error::Error::new(
+                ErrorKind::TooShortResponse,
+                "not enough data provided to recover 'self_address'".to_string(),
+            ));
+        }
+
+        let mut recipient_bytes = [0u8; Recipient::LEN];
+        recipient_bytes.copy_from_slice(&b[1..1 + Recipient::LEN]);
+
+        let recipient = match Recipient::try_from_bytes(recipient_bytes) {
+            Ok(recipient) => recipient,
+            Err(err) => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!("malformed Recipient: {:?}", err),
+                ))
+            }
+        };
+
+        Ok(ServerResponse::SelfAddress(recipient))
+    }
+
+    // ERROR_RESPONSE_TAG || err_code || msg_len || msg
+    fn serialize_error(error: error::Error) -> Vec<u8> {
+        let message_len_bytes = (error.message.len() as u64).to_be_bytes();
+        std::iter::once(ERROR_RESPONSE_TAG)
+            .chain(std::iter::once(error.kind as u8))
+            .chain(message_len_bytes.iter().cloned())
+            .chain(error.message.into_bytes().into_iter())
+            .collect()
+    }
+
+    // ERROR_RESPONSE_TAG || err_code || msg_len || msg
+    fn deserialize_error(b: &[u8]) -> Result<Self, error::Error> {
+        // this MUST match because it was called by 'deserialize'
+        debug_assert_eq!(b[0], ERROR_RESPONSE_TAG);
+
+        if b.len() < size_of::<u8>() + size_of::<u64>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortResponse,
+                "not enough data provided to recover 'error'".to_string(),
+            ));
+        }
+
+        let error_kind = match b[1] {
+            _ if b[1] == (ErrorKind::EmptyRequest as u8) => ErrorKind::EmptyRequest,
+            _ if b[1] == (ErrorKind::TooShortRequest as u8) => ErrorKind::TooShortRequest,
+            _ if b[1] == (ErrorKind::UnknownRequest as u8) => ErrorKind::UnknownRequest,
+            _ if b[1] == (ErrorKind::MalformedRequest as u8) => ErrorKind::MalformedRequest,
+
+            _ if b[1] == (ErrorKind::EmptyResponse as u8) => ErrorKind::EmptyResponse,
+            _ if b[1] == (ErrorKind::TooShortResponse as u8) => ErrorKind::TooShortResponse,
+            _ if b[1] == (ErrorKind::UnknownResponse as u8) => ErrorKind::UnknownResponse,
+            _ if b[1] == (ErrorKind::MalformedResponse as u8) => ErrorKind::MalformedResponse,
+
+            _ if b[1] == (ErrorKind::Other as u8) => ErrorKind::Other,
+
+            n => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!("invalid error code {}", n),
+                ))
+            }
+        };
+
+        let message_len =
+            u64::from_be_bytes(b[2..2 + size_of::<u64>()].as_ref().try_into().unwrap());
+        let message = &b[2 + size_of::<u64>()..];
+        if message.len() as u64 != message_len {
+            return Err(error::Error::new(
+                ErrorKind::MalformedResponse,
+                format!(
+                    "message len has inconsistent length. specified: {} got: {}",
+                    message_len,
+                    message.len()
+                ),
+            ));
+        }
+
+        let err_message = match String::from_utf8(message.to_vec()) {
+            Ok(msg) => msg,
+            Err(err) => {
+                return Err(error::Error::new(
+                    ErrorKind::MalformedResponse,
+                    format!("malformed error message: {:?}", err),
+                ))
+            }
+        };
+
+        Ok(ServerResponse::Error(error::Error::new(
+            error_kind,
+            err_message,
+        )))
+    }
+
+    pub fn serialize(self) -> Vec<u8> {
+        match self {
+            ServerResponse::Received(reconstructed_message) => {
+                Self::serialize_received(reconstructed_message)
+            }
+            ServerResponse::SelfAddress(address) => Self::serialize_self_address(address),
+            ServerResponse::Error(err) => Self::serialize_error(err),
+        }
+    }
+
+    pub fn deserialize(b: &[u8]) -> Result<Self, error::Error> {
+        if b.is_empty() {
+            // technically I'm not even sure this can ever be returned, because reading empty
+            // request would imply closed socket, but let's include it for completion sake
+            return Err(error::Error::new(
+                ErrorKind::EmptyResponse,
+                "no data provided".to_string(),
+            ));
+        }
+
+        if b.len() < size_of::<u8>() {
+            return Err(error::Error::new(
+                ErrorKind::TooShortResponse,
+                format!(
+                    "not enough data provided to recover response tag. Provided only {} bytes",
+                    b.len()
+                ),
+            ));
+        }
+
+        let response_tag = b[0];
+
+        // determine what kind of response that is and try to deserialize it
+        match response_tag {
+            RECEIVED_RESPONSE_TAG => Self::deserialize_received(b),
+            SELF_ADDRESS_RESPONSE_TAG => Self::deserialize_self_address(b),
+            ERROR_RESPONSE_TAG => Self::deserialize_error(b),
+            n => Err(error::Error::new(
+                ErrorKind::UnknownResponse,
+                format!("type {}", n),
+            )),
+        }
+    }
+
+    pub fn into_binary(self) -> Vec<u8> {
+        self.serialize()
+    }
+
+    pub fn into_text(self) -> String {
+        // use the intermediate string structure and let serde do bunch of work for us
+        let text_resp = ServerResponseText::from(self);
+
+        text_resp.into()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn received_response_serialization_works() {
+        let reply_surb_string = "CjfVbHbfAjbC3W1BvNHGXmM8KNAnDNYGaHMLqVDxRYeo352csAihstup9bvqXam4dTWgfHak6KYwL9STaxWJ47E8XFZbSEvs7hEsfCkxr6K9WJuSBPK84GDDEvad8ZAuMCoaXsAd5S2Lj9a5eYyzG4SL1jHzhSMni55LyJwumxo1ZTGZNXggxw1RREosvyzNrW9Rsi3owyPqLCwXpiei2tHZty8w8midVvg8vDa7ZEJD842CLv8D4ohynSG7gDpqTrhkRaqYAuz7dzqNbMXLJRM7v823Jn16fA1L7YQxmcaUdUigyRSgTdb4i9ebiLGSyJ1iDe6Acz613PQZh6Ua3bZ2zVKq3dSycpDm9ngarRK4zJrAaUxRkdih8YzW3BY4nL9eqkfKA4N1TWCLaRU7zpSaf8yMEwrAZReU3d5zLV8c5KBfa2w8R5anhQeBojduZEGEad8kkHuKU52Zg93FeWHvH1qgZaEJMHH4nN7gKXz9mvWDhYwyF4vt3Uy2NhCHC3N5pL1gMme27YcoPcTEia1fxKZtnt6rtEozzTrAgCJGswigkFbkafiV5QaJwLKTUxtzhkZ57eEuLPte9UvJHzhhXUQ2CV7R2BUkJjYZy3Zsx6YYvdYWiAFFkWUwNEGA4QpShUHciBfsQVHQ7pN41YcyYUhbywQDFnTVgEmdUZ1XCBi3gyK5U3tDQmFzP1u9m3mWrUA8qB9mRDE7ptNDm5c3c1458L6uXLUth7sdMaa1Was5LCmCdmNDtvNpCDAEt1in6q6mrZFR85aCSU9b1baNGwZoCqPpPvydkVe63gXWoi8ebvdyxARrqACFrSB3ZdY3uJBw8CTMNkKK6MvcefMkSVVsbLd36TQAtYSCqrpiMc5dQuKcEu5QfciwvWYXYx8WFNAgKwP2mv49KCTvfozNDUCbjzDwSx92Zv5zjG8HbFpB13bY9UZGeyTPvv7gGxCzjGjJGbW6FRAheRQaaje5fUgCNM95Tv7wBmAMRHHFgWafeK1sdFH7dtCX9u898HucGTaboSKLsVh8J78gbbkHErwjMh7y9YRkceq5TTYS5da4kHnyNKYWSbxgZrmFg44XGKoeYcqoHB3XTZrdsf7F5fFeNwnihkmADvhAcaxXUmVqq4rQFZH84a1iC3WBWXYcqiZH2L7ujGWV7mMDT4HBEerDYjc8rNY4xGTPfivCrBCJW1i14aqW8xRdsdgTM88eTksvC3WPJLJ7iMzfKXeL7fMW1Ek6QGyQtLBW98vEESpdcDg6DeZ5rMz6VqjTGGqcCaFGfHoqtfxMDaBAEsyQ8h7XDX6dg1wq9wH6j4Tw7Tj1MEv1b8uj5NJkozZdzVdYA2QyE2Dp8vuurQG6uVdTDNww2d88RBQ8sVgjxN8gR45y4woJLhFAaNTAtrY6wDTxyXST13ni6oyqdYxjFVk9Am4v3DzH7Y2K8iRVSHfTk4FRbPULyaeK6wt2anvMJH1XdvVRgc14h67MnBxMgMD1UFk8AErN7CDj26fppe3c5G6KozJe4cSqQUGbBjVzBnrHCruqrfZBn5hNZHTV37bQiomqhRQXohxhuKEnNrGbAe1xNvJr9X";
+
+        let received_with_surb = ServerResponse::Received(ReconstructedMessage {
+            message: b"foomp".to_vec(),
+            reply_surb: Some(ReplySurb::from_base58_string(reply_surb_string).unwrap()),
+        });
+        let bytes = received_with_surb.serialize();
+        let recovered = ServerResponse::deserialize(&bytes).unwrap();
+        match recovered {
+            ServerResponse::Received(reconstructed) => {
+                assert_eq!(reconstructed.message, b"foomp".to_vec());
+                assert_eq!(
+                    reconstructed.reply_surb.unwrap().to_base58_string(),
+                    reply_surb_string
+                )
+            }
+            _ => unreachable!(),
+        }
+
+        let received_without_surb = ServerResponse::Received(ReconstructedMessage {
+            message: b"foomp".to_vec(),
+            reply_surb: None,
+        });
+        let bytes = received_without_surb.serialize();
+        let recovered = ServerResponse::deserialize(&bytes).unwrap();
+        match recovered {
+            ServerResponse::Received(reconstructed) => {
+                assert_eq!(reconstructed.message, b"foomp".to_vec());
+                assert!(reconstructed.reply_surb.is_none())
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn self_address_response_serialization_works() {
+        let recipient = Recipient::try_from_base58_string("CytBseW6yFXUMzz4SGAKdNLGR7q3sJLLYxyBGvutNEQV.4QXYyEVc5fUDjmmi8PrHN9tdUFV4PCvSJE1278cHyvoe@4sBbL1ngf1vtNqykydQKTFh26sQCw888GpUqvPvyNB4f").unwrap();
+        let recipient_string = recipient.to_string();
+
+        let self_address_response = ServerResponse::SelfAddress(recipient);
+        let bytes = self_address_response.serialize();
+        let recovered = ServerResponse::deserialize(&bytes).unwrap();
+        match recovered {
+            ServerResponse::SelfAddress(recipient) => {
+                assert_eq!(recipient.to_string(), recipient_string)
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn error_response_serialization_works() {
+        let dummy_error = error::Error::new(ErrorKind::UnknownRequest, "foomp message".to_string());
+        let error_response = ServerResponse::Error(dummy_error.clone());
+        let bytes = error_response.serialize();
+        let recovered = ServerResponse::deserialize(&bytes).unwrap();
+        match recovered {
+            ServerResponse::Error(error) => assert_eq!(error, dummy_error),
+            _ => unreachable!(),
+        }
+    }
+}

clients/native/websocket-requests/src/text.rs

@@ -0,0 +1,140 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use crate::error::ErrorKind;
+use crate::requests::ClientRequest;
+use crate::responses::ServerResponse;
+use nymsphinx::addressing::clients::Recipient;
+use nymsphinx::anonymous_replies::ReplySurb;
+use serde::{Deserialize, Serialize};
+use std::convert::{TryFrom, TryInto};
+
+// local text equivalent of `ClientRequest` for easier serialization + deserialization with serde
+// TODO: figure out if there's an easy way to avoid defining it
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub(super) enum ClientRequestText {
+    #[serde(rename_all = "camelCase")]
+    Send {
+        message: String,
+        recipient: String,
+        with_reply_surb: bool,
+    },
+    SelfAddress,
+    #[serde(rename_all = "camelCase")]
+    Reply {
+        message: String,
+        reply_surb: String,
+    },
+}
+
+impl TryFrom<String> for ClientRequestText {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, Self::Error> {
+        serde_json::from_str(&msg)
+    }
+}
+
+impl TryInto<ClientRequest> for ClientRequestText {
+    type Error = crate::error::Error;
+
+    fn try_into(self) -> Result<ClientRequest, Self::Error> {
+        match self {
+            ClientRequestText::Send {
+                message,
+                recipient,
+                with_reply_surb,
+            } => {
+                let message_bytes = message.into_bytes();
+                let recipient = Recipient::try_from_base58_string(recipient).map_err(|err| {
+                    Self::Error::new(ErrorKind::MalformedRequest, err.to_string())
+                })?;
+
+                Ok(ClientRequest::Send {
+                    message: message_bytes,
+                    recipient,
+                    with_reply_surb,
+                })
+            }
+            ClientRequestText::SelfAddress => Ok(ClientRequest::SelfAddress),
+            ClientRequestText::Reply {
+                message,
+                reply_surb,
+            } => {
+                let message_bytes = message.into_bytes();
+                let reply_surb = ReplySurb::from_base58_string(reply_surb).map_err(|err| {
+                    Self::Error::new(ErrorKind::MalformedRequest, err.to_string())
+                })?;
+
+                Ok(ClientRequest::Reply {
+                    message: message_bytes,
+                    reply_surb,
+                })
+            }
+        }
+    }
+}
+
+// local text equivalent of `ServerResponse` for easier serialization + deserialization with serde
+// TODO: figure out if there's an easy way to avoid defining it
+
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub(super) enum ServerResponseText {
+    #[serde(rename_all = "camelCase")]
+    Received {
+        message: String,
+        reply_surb: Option<String>,
+    },
+    SelfAddress {
+        address: String,
+    },
+    Error {
+        message: String,
+    },
+}
+
+impl TryFrom<String> for ServerResponseText {
+    type Error = serde_json::Error;
+
+    fn try_from(msg: String) -> Result<Self, <ServerResponseText as TryFrom<String>>::Error> {
+        serde_json::from_str(&msg)
+    }
+}
+
+impl From<ServerResponseText> for String {
+    fn from(res: ServerResponseText) -> Self {
+        // per serde_json docs:
+        /*
+        /// Serialization can fail if `T`'s implementation of `Serialize` decides to
+        /// fail, or if `T` contains a map with non-string keys.
+         */
+        // this is not the case here.
+        serde_json::to_string(&res).unwrap()
+    }
+}
+
+impl From<ServerResponse> for ServerResponseText {
+    fn from(resp: ServerResponse) -> Self {
+        match resp {
+            ServerResponse::Received(reconstructed) => {
+                ServerResponseText::Received {
+                    // TODO: ask DH what is more appropriate, lossy utf8 conversion or returning error and then
+                    // pure binary later
+                    message: String::from_utf8_lossy(&reconstructed.message).into_owned(),
+                    reply_surb: reconstructed
+                        .reply_surb
+                        .map(|reply_surb| reply_surb.to_base58_string()),
+                }
+            }
+            ServerResponse::SelfAddress(recipient) => ServerResponseText::SelfAddress {
+                address: recipient.to_string(),
+            },
+            ServerResponse::Error(err) => ServerResponseText::Error {
+                message: err.to_string(),
+            },
+        }
+    }
+}

clients/socks5/Cargo.toml

@@ -0,0 +1,49 @@
+[package]
+name = "nym-socks5-client"
+version = "0.12.1"
+authors = ["Dave Hrycyszyn <futurechimp@users.noreply.github.com>"]
+edition = "2018"
+rust-version = "1.56"
+
+[lib]
+name = "nym_socks5"
+path = "src/lib.rs"
+
+[dependencies]
+clap = "2.33.0"
+dirs = "3.0" # for determining default store directories in config
+dotenv = "0.15.0"
+futures = "0.3"
+log = "0.4"
+pin-project = "1.0"
+pretty_env_logger = "0.4"
+rand = { version = "0.7.3", features = ["wasm-bindgen"] }
+serde = { version = "1.0", features = ["derive"] } # for config serialization/deserialization
+snafu = "0.6"
+tokio = { version = "1.4", features = ["rt-multi-thread", "net", "signal"] }
+url = "2.2"
+
+# internal
+client-core = { path = "../client-core" }
+coconut-interface = { path = "../../common/coconut-interface", optional = true }
+credentials = { path = "../../common/credentials", optional = true }
+config = { path = "../../common/config" }
+crypto = { path = "../../common/crypto" }
+gateway-client = { path = "../../common/client-libs/gateway-client" }
+gateway-requests = { path = "../../gateway/gateway-requests" }
+nymsphinx = { path = "../../common/nymsphinx" }
+ordered-buffer = { path = "../../common/socks5/ordered-buffer" }
+socks5-requests = { path = "../../common/socks5/requests" }
+topology = { path = "../../common/topology" }
+pemstore = { path = "../../common/pemstore" }
+proxy-helpers = { path = "../../common/socks5/proxy-helpers" }
+validator-client = { path = "../../common/client-libs/validator-client" }
+version-checker = { path = "../../common/version-checker" }
+network-defaults = { path = "../../common/network-defaults" }
+
+[features]
+coconut = ["coconut-interface", "credentials", "gateway-requests/coconut", "gateway-client/coconut"]
+eth = []
+
+[build-dependencies]
+vergen = { version = "5", default-features = false, features = ["build", "git", "rustc", "cargo"] }

clients/socks5/build.rs

@@ -0,0 +1,8 @@
+// Copyright 2021 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use vergen::{vergen, Config};
+
+fn main() {
+    vergen(Config::default()).expect("failed to extract build metadata")
+}