Add Matrix link to navbar

Cargo.lock

@@ -347,6 +347,14 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0"
 
+[[package]]
+name = "autodoc"
+version = "0.1.0"
+dependencies = [
+ "env_logger 0.11.5",
+ "log",
+]
+
 [[package]]
 name = "axum"
 version = "0.6.20"
@@ -2185,6 +2193,16 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "env_filter"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f2c92ceda6ceec50f43169f9ee8424fe2db276791afde7b2cd8bc084cb376ab"
+dependencies = [
+ "log",
+ "regex",
+]
+
 [[package]]
 name = "env_logger"
 version = "0.7.1"
@@ -2208,6 +2226,19 @@ dependencies = [
  "regex",
 ]
 
+[[package]]
+name = "env_logger"
+version = "0.11.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13fa619b91fb2381732789fc5de83b45675e882f66623b7d8cb4f643017018d"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "env_filter",
+ "humantime 2.1.0",
+ "log",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.1"

Cargo.toml

@@ -93,6 +93,7 @@ members = [
     "common/wasm/utils",
     "common/wireguard",
     "common/wireguard-types",
+    "documentation/autodoc",
     "explorer-api",
     "explorer-api/explorer-api-requests",
     "explorer-api/explorer-client",

documentation/autodoc/.gitignore

@@ -0,0 +1 @@
+/autodoc-generated-markdown/*

documentation/autodoc/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "autodoc"
+version = "0.1.0"
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+env_logger = "0.11.3"
+log.workspace = true

documentation/autodoc/README.md

@@ -0,0 +1,4 @@
+# `autodoc`
+
+Command output documentation generator WIP 
+

documentation/autodoc/src/main.rs

@@ -0,0 +1,261 @@
+use log::{debug, info};
+use std::fs::File;
+use std::io::{self, Write};
+use std::process::{Command, Output};
+use std::{fs, vec};
+
+const WRITE_PATH: &str = "./autodoc-generated-markdown/";
+
+fn main() -> io::Result<()> {
+    env_logger::init();
+
+    // TODO if this balloons write automated way of grabbing commands from crates.
+    let commands_with_subcommands = vec![
+        (
+            "../../target/release/nym-api",
+            vec!["init", "run", "build-info"],
+        ),
+        (
+            "../../target/release/nym-client",
+            vec![
+                "init",
+                "run",
+                "import-credential",
+                "list-gateways",
+                "switch-gateway",
+                "build-info",
+                "completions",
+                "generate-fig-spec",
+            ],
+        ),
+        (
+            "../../target/release/nym-socks5-client",
+            vec![
+                "init",
+                "run",
+                "import-credential",
+                "list-gateways",
+                "add-gateway",
+                "build-info",
+                "completions",
+                "generate-fig-spec",
+            ],
+        ),
+        (
+            "../../target/release/nym-node",
+            vec![
+                "build-info",
+                "bonding-information",
+                "node-details",
+                "migrate",
+                "run",
+                "sign",
+            ],
+        ),
+        (
+            "../../target/release/nymvisor",
+            vec![
+                "init",
+                "run",
+                "build-info",
+                "daemon-build-info",
+                "add-upgrade",
+                "config",
+            ],
+        ),
+    ];
+
+    let commands_with_subsubcommands = vec![(
+        "../../target/release/nym-cli",
+        vec![
+            (
+                "account",
+                vec!["create", "balance", "pub-key", "send", "send-multiple"],
+            ),
+            ("signature", vec!["sign", "verify"]),
+            (
+                "ecash",
+                vec![
+                    "issue-ticket-book",
+                    "recover-ticket-book",
+                    "import-ticket-book",
+                ],
+            ),
+            (
+                "coconut",
+                vec![
+                    "generate-freepass",
+                    "issue-credentials",
+                    "recover-credentials",
+                    "import-credential",
+                ],
+            ),
+            ("block", vec!["get", "time", "current-height"]),
+            (
+                "cosmwasm",
+                vec![
+                    "upload",
+                    "init",
+                    "generate-init-message",
+                    "migrate",
+                    "execute",
+                ],
+            ),
+            ("tx", vec!["get", "query"]),
+            (
+                "vesting-schedule",
+                vec!["create", "query", "vested-balance", "withdraw-vested"],
+            ),
+            ("mixnet", vec!["query", "delegators", "operators"]),
+            ("generate-fig", vec![""]),
+        ],
+    )];
+
+    for (main_command, subcommands) in commands_with_subcommands {
+        let last_word = get_last_word_from_filepath(main_command);
+        debug!("now running {last_word:#?}");
+
+        if !fs::metadata(WRITE_PATH)
+            .map(|metadata| metadata.is_dir())
+            .unwrap_or(false)
+        {
+            fs::create_dir_all(WRITE_PATH)?;
+        }
+
+        let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?;
+        writeln!(
+            file,
+            "# {} Binary Commands",
+            format!("`{}`", last_word.unwrap())
+        )?;
+        writeln!(
+            file,
+            "\nThese docs are autogenerated by the `autodocs` script.
+            \n**TODO add link**"
+        )?;
+        let output = Command::new(main_command).arg("--help").output()?;
+        write_output_to_file(&mut file, output)?;
+
+        for subcommand in subcommands {
+            execute_command(&mut file, main_command, subcommand, None)?;
+        }
+    }
+
+    // nym-cli has subsubcommands so needs its own loop
+    for (main_command, subcommands) in &commands_with_subsubcommands {
+        let last_word = get_last_word_from_filepath(main_command);
+        debug!("now running {last_word:#?}");
+        let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?;
+        writeln!(
+            file,
+            "# {} Binary Commands",
+            format!("`{}`", last_word.unwrap())
+        )?;
+        writeln!(
+            file,
+            "\nThese docs are autogenerated by the `autodocs` script.
+            \n**TODO add link**"
+        )?;
+        let output = Command::new(main_command).arg("--help").output()?;
+
+        write_output_to_file(&mut file, output)?;
+
+        for (subcommand, subsubcommands) in subcommands {
+            writeln!(file, "\n### `{}` ", subcommand)?;
+            let output = Command::new(main_command)
+                .arg(subcommand)
+                .arg("--help")
+                .output()?;
+            if !output.stdout.is_empty() {
+                write_output_to_file(&mut file, output)?;
+            } else {
+                debug!("empty stdout - nothing to write");
+            }
+            for subsubcommand in subsubcommands {
+                execute_command(&mut file, main_command, subcommand, Some(subsubcommand))?;
+            }
+        }
+    }
+    Ok(())
+}
+
+fn get_last_word_from_filepath(filepath: &str) -> Option<&str> {
+    let parts: Vec<&str> = filepath.split('/').collect();
+    parts.last().copied()
+}
+
+fn execute_command(
+    file: &mut File,
+    main_command: &str,
+    subcommand: &str,
+    subsubcommand: Option<&str>,
+) -> io::Result<()> {
+    // checking for the nym-cli subsubcommands
+    if subsubcommand.is_some() {
+        writeln!(file, "\n### `{} {}`", subcommand, subsubcommand.unwrap())?;
+
+        info!("executing {} {} --help ", main_command, subcommand);
+        let output = Command::new(main_command)
+            .arg(subcommand)
+            .arg(subsubcommand.unwrap())
+            .arg("--help")
+            .output()?;
+        if !output.stdout.is_empty() {
+            write_output_to_file(file, output)?;
+        } else {
+            debug!("empty stdout - nothing to write");
+        }
+    // just subcommands
+    } else {
+        writeln!(file, "\n### `{}`", subcommand)?;
+
+        // execute help
+        let output = Command::new(main_command)
+            .arg(subcommand)
+            .arg("--help")
+            .output()?;
+        if !output.stdout.is_empty() {
+            write_output_to_file(file, output)?;
+        } else {
+            debug!("empty stdout - nothing to write");
+        }
+
+        // then execute w/out help: the majority of functions will fail since you're not passing
+        // required params but thats fine as we can just not render stderr into the final file.
+        //
+        // this check is basically checking for the rare commands (rn just one) that start a process with no params
+        // perhaps if this list grows we could just add a timeout and shunt the running and writing
+        // into a thread with a timeout or something but for right now its fine / thats overkill
+        if get_last_word_from_filepath(main_command).unwrap() == "nym-node"
+            || get_last_word_from_filepath(main_command).unwrap() == "nym-api"
+            || get_last_word_from_filepath(main_command).unwrap() == "nymvisor"
+                && subcommand == "run"
+        {
+            info!("SKIPPING {} {}", main_command, subcommand);
+        } else {
+            info!("executing {} {}", main_command, subcommand);
+            let output = Command::new(main_command).arg(subcommand).output()?;
+            if !output.stdout.is_empty() {
+                writeln!(file, "Example output:")?;
+                write_output_to_file(file, output)?;
+            } else {
+                debug!("empty stdout - nothing to write");
+                if !&output.stderr.is_empty() {
+                    debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr));
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+fn write_output_to_file(file: &mut File, output: Output) -> io::Result<()> {
+    writeln!(file, "```")?;
+    file.write_all(&output.stdout)?;
+    writeln!(file, "```")?;
+
+    if !&output.stderr.is_empty() {
+        debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr));
+    }
+    Ok(())
+}

documentation/docs/.gitignore

@@ -1,14 +1,6 @@
-# mdbook files
-book/
-
-# Compiled assets
-.sass-cache
-_site
-
-# Developing
-todo.md
-.idea
-
-# OSX
-.DS_Store
+.next
+node_modules
+out
 
+# the lock file will break Vercel because it may get committed from a machine with a different build architecture
+package-lock.json

documentation/docs/README.md

@@ -1,42 +1,24 @@
-# Nym Documentation
-Documentation for the Nym privacy platform built using the [mdBook](https://rust-lang.github.io/mdBook/) docs framework.
+# Nym Docs v2
 
-Documentation can be viewed at https://nymtech.net/docs
+New consolidated version of the nym docs.
 
-## Contributing
-Contributions to our documentation are very welcome. Please work on your contribution in either a `feature/<feature-name>` or `chore/<chore-name>` branch from `master` and target your pull request at `master`.
+## Local development
 
-Since these docs autogenerate command output and import docs from binaries in `target/release` on `build` make sure you're branching off of `master` when making your branch.
+```
+npm i
+npm run dev
+```
 
-Changes merged to `master` will be autodeployed to the production site.
+Open http://localhost:3000 to browse the output that will hot-reload when you make changes.
 
-### Contributing a new translation
-To contribute tranlsations in a new language, please get in touch via [Matrix](https://matrix.to/#/#general:nymtech.chat) or [Discord](https://nymtech.net/go/discord).
+## Build
 
-### Variables
-There are some variables that are shared across the entire docs site, such as the current latest software version.
+```
+npm run build
+```
 
-Variables are denoted in the `.md` files wrapped in `{{}}` (e.g `{{wallet_release_version}}`), and are located in the `book.toml` file under the `[preprocessor.variables.variables]` heading. If you are changing something like the software release version, minimum code versions in prerequisites, etc, **check in here first!**
+The static output will be in `./out`;
 
-### Diagrams
-Most diagrams are simply ascii. Copies are kept in `/diagrams/` for ease of reproducability. Created using [textik](https://textik.com/#).
+## Template details
 
-### Importing files and auto-generated command output
-
-Example files are inserted as per normal with mdbook.
-
-Some binary command outputs are generated using the [`cmdrun`](https://docs.rs/mdbook-cmdrun/latest/mdbook_cmdrun/) mdbook plugin.
-
-## Building
-When working locally, it is recommended that you use `mdbook serve` to have a local version of the docs served on `localhost:3000`, with hot reloading on any changes made to files in the `src/` directory.
-
-You can find other commands in the [mdBook CLI tool docs](https://rust-lang.github.io/mdBook/cli/index.html).
-
-### I tried to edit files in `theme/` and they aren't taking effect / `mdbook serve` causes a looping reload on file changes after changing fields in `[preprocessor.theme]` config
-
-Looping reload is a known issue with the `mdbook-theme` preprocessor used for the table of contents and layout of these docs. As outlined in the `mdbook-theme` [readme](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) one way to mitigate this is to set `turn-off = true` under `[preprocessor.theme]`. This means that `mdbook serve` or `mdbook watch` ignores changes to the `theme/` directory, which is the source of the looping reload. If you have changed or commented out this line, reintroduce it to remove the looping reload. If you are trying to edit the theme of the docs and want to apply the change, see [here](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) for more info on how to remove the block, change the theme, and reintroduce the block.
-
-### Checking the mdBook version
-To check the version of mdBook installed on your system, you can use the `mdbook --version` command. This will print the version number of mdBook installed on your system in the terminal.
-
-The latest release of the binary of the pre-compiled binaries can be found on [GitHub](https://github.com/rust-lang/mdBook/releases).
+This documentation was made with [Nextra](https://nextra.site) using the template from here https://github.com/shuding/nextra-docs-template.

documentation/docs/components/landing-page.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import { Ghost, Zap, Code, Soup } from "lucide-react";
+
+export const LandingPage = () => {
+  const squares = [
+    { text: "Network Docs", href: "/network", Icon: Ghost },
+    {
+      text: "Developers: Core Concepts, Integration Overview, Tools & Tutorials",
+      href: "/developers",
+      Icon: Zap,
+    },
+    { text: "SDKs", href: "/developers/rust", Icon: Code },
+    {
+      text: "Operators: Setup Guides & Maintenance",
+      href: "/operators",
+      Icon: Soup,
+    },
+  ];
+
+  return (
+    <div className="landing-page-container">
+      <p className="landing-page-intro">
+        Nym is a privacy platform. It provides strong network-level privacy
+        against sophisticated end-to-end attackers, and anonymous access control
+        using blinded, re-randomizable, decentralized credentials. Our goal is
+        to allow developers to build new applications, or upgrade existing apps,
+        with privacy features unavailable in other systems.
+      </p>
+
+      <div className="landing-page-grid">
+        {squares.map((square, index) => (
+          <a key={index} href={square.href} className="landing-page-square">
+            <square.Icon className="landing-page-icon" />
+            <span className="landing-page-text">{square.text}</span>
+          </a>
+        ))}
+      </div>
+
+      <style jsx>{`
+        .landing-page-container {
+          max-width: 1200px;
+          margin: 0 auto;
+          padding: 2rem 1rem;
+        }
+        .landing-page-intro {
+          font-size: 1.125rem;
+          margin-bottom: 2rem;
+        }
+        .landing-page-grid {
+          display: grid;
+          grid-template-columns: repeat(2, 1fr);
+          gap: 2rem;
+          max-width: 36rem;
+          margin: 0 auto;
+        }
+        .landing-page-square {
+          background-color: #000000;
+          color: white;
+          padding: 1rem;
+          border-radius: 0.5rem;
+          text-align: center;
+          cursor: pointer;
+          text-decoration: none;
+          transition: box-shadow 0.3s ease;
+          aspect-ratio: 1 / 1;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          border: 3px solid #ff6600;
+          box-shadow: 0 0 10px #ff6600;
+        }
+        .landing-page-square:hover {
+          box-shadow: 0 0 20px #ff6600;
+        }
+        .landing-page-icon {
+          width: 12.5rem;
+          height: 12.5rem;
+          margin-bottom: 0.75rem;
+          color: #ff6600;
+        }
+        .landing-page-text {
+          font-size: 0.875rem;
+          font-weight: 600;
+          color: #ff6600;
+        }
+      `}</style>
+    </div>
+  );
+};

documentation/docs/components/my-tab.tsx

@@ -0,0 +1,6 @@
+import { Tabs } from "nextra/components";
+export const MyTab = ({ name, children }) => (
+  <Tabs.Tab>
+    {name} {children}
+  </Tabs.Tab>
+);

documentation/docs/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@nymproject/ts-sdk-docs",
-  "version": "1.3.0-rc.0",
-  "description": "Nym Typescript SDK Docs",
+  "name": "@nymproject/docs",
+  "version": "1.0.0",
+  "description": "Nym Docs Monorepo",
   "license": "Apache-2.0",
   "author": "Nym Technologies SA",
   "scripts": {
@@ -34,6 +34,7 @@
     "@nymproject/sdk-full-fat": ">=1.2.4-rc.2 || ^1",
     "chain-registry": "^1.19.0",
     "cosmjs-types": "^0.9.0",
+    "lucide-react": "^0.438.0",
     "next": "^13.4.19",
     "nextra": "latest",
     "nextra-theme-docs": "latest",

documentation/docs/pages/_meta.json

@@ -0,0 +1,31 @@
+{
+  "index": {
+    "display": "hidden"
+  },
+  "network": {
+    "title": "Network",
+    "type": "page"
+  },
+  "developers": {
+    "title": "Developers",
+    "type": "menu",
+    "items": {
+      "developers": {
+        "title": "Developer Overview",
+        "href": "/developers/"
+      },
+      "rust": {
+        "title": "Rust SDK",
+        "href": "/developers/rust"
+      },
+      "typescript": {
+        "title": "Typescript SDK",
+        "href": "/developers/typescript"
+      }
+    }
+  },
+  "operators": {
+    "title": "Operators",
+    "type": "page"
+  }
+}

documentation/docs/pages/_meta.json.bak

@@ -0,0 +1,42 @@
+{
+  "network": {
+    "title": "Network",
+    "type": "page"
+  },
+  "developers": {
+    "title": "Developers",
+    "type": "menu",
+    "items": {
+      "concepts": {
+        "title": "Core Concepts",
+        "href": "/developers/concepts"
+      },
+      "integrations": {
+        "title": "Integrations",
+        "href": "/developers/integrations"
+      },
+      "tools": {
+        "title": "Tools",
+        "href": "/developers/tools"
+      }
+    }
+  },
+  "sdk": {
+    "title": "SDKs",
+    "type": "menu",
+    "items": {
+      "rust": {
+        "title": "Rust SDK",
+        "href": "/sdk/rust"
+      },
+      "typescript": {
+        "title": "Typescript SDK",
+        "href": "/sdk/typescript"
+      }
+    }
+  },
+  "operators": {
+    "title": "Operators",
+    "type": "page"
+  }
+}

documentation/docs/pages/_meta.json.bak.bak

@@ -0,0 +1,31 @@
+{
+  "index": {
+    "display": "hidden"
+  },
+  "network": {
+    "title": "Network",
+    "type": "page"
+  },
+  "developers": {
+    "title": "Developers",
+    "type": "page"
+  },
+  "sdk": {
+    "title": "SDKs",
+    "type": "menu",
+    "items": {
+      "rust": {
+        "title": "Rust SDK",
+        "href": "/sdk/rust"
+      },
+      "typescript": {
+        "title": "Typescript SDK",
+        "href": "/sdk/typescript"
+      }
+    }
+  },
+  "operators": {
+    "title": "Operators",
+    "type": "page"
+  }
+}

documentation/docs/pages/developers/_meta.json

@@ -0,0 +1,17 @@
+{
+  "index": "Introduction",
+  "concepts": "Core Concepts",
+  "integrations": "Integration Options",
+  "clients": "Clients",
+  "tools": "Tools",
+  "chain": "Interacting with Nyx",
+  "--": {
+    "type": "separator"
+  },
+  "rust": "Rust SDK",
+  "typescript": "Typescript SDK",
+  "---": {
+    "type": "separator"
+  },
+  "licensing": "Licensing"
+}

documentation/docs/pages/developers/clients.mdx

@@ -0,0 +1,21 @@
+# Types of Nym clients
+At present, there are three standalone Nym clients. These are built as standalone binaries when building our codebase, but are most easily accessed through one of our SDKs:
+
+- the websocket (native) client - most easily accessed via the [Rust SDK]() TODO LINK and Go/C++ FFI TODO LINK
+- the SOCKS5 client - most easily accessed via the [Rust SDK]() TODO LINK and Go/C++ FFI TODO LINK
+- the wasm (webassembly) client - most easily via the [Typescript SDK]() TODO LINK
+
+> For information about the role that clients play within the Nym system and their role when communicating with the Mixnet, see the [Client network docs](../network/architecture/mixnet/clients).
+
+### The websocket client
+This is a compiled program that can run on Linux, Mac OS X, and Windows machines. It can be run as a persistent process on a desktop or server machine. You can connect to it with **any language that supports websockets**.
+
+### The webassembly client
+If you're working in JavaScript or Typescript in the browser, or building an [edge computing](https://en.wikipedia.org/wiki/Edge_computing) app, you'll likely want to choose the webassembly client.
+
+It's packaged and [available on the npm registry](https://www.npmjs.com/package/@nymproject/nym-client-wasm), so you can `npm install` it into your JavaScript or TypeScript application.
+
+### The SOCKS5 client
+The `nym-socks5-client` is useful for allowing existing applications to use the Nym mixnet without any code changes. All that's necessary is that they can use one of the SOCKS5, SOCKS4a, or SOCKS4 proxy protocols (which many applications can - crypto wallets, browsers, chat applications etc).
+
+When used as a standalone client, it's less flexible as a way of writing custom applications than the other clients, but able to be used to proxy application traffic through the mixnet without having to make any code changes.

documentation/docs/pages/developers/clients/socks5.md

@@ -0,0 +1,212 @@
+# Socks5 Client
+
+TODO REMOVE THIS REPLACE WITH A BUILD INSTRUCTIONS DROPDOWN MENU COMPONENT
+> The Nym Socks5 Client was built in the [building nym](../binaries/building-nym.md) section. If you haven't yet built Nym and want to run the code on this page, go there first.
+
+## Current version
+TODO
+```
+<!-- cmdrun ../../../../target/release/nym-socks5-client --version | grep "Build Version" | cut -b 21-26  -->
+```
+
+## What is this client for?
+Many existing applications are able to use either the SOCKS4, SOCKS4A, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this:
+
+```
+                                                                              External Systems:
+                                                                                     +--------------------+
+                                                                             |------>| Monero blockchain  |
+                                                                             |       +--------------------+
+                                                                             |       +--------------------+
+                                                                             |------>|    Email server    |
+                                                                             |       +--------------------+
+                                                                             |       +--------------------+
+                                                                             |------>|    RPC endpoint    |
+                                                                             |       +--------------------+
+                                                                             |       +--------------------+
+                                                                             |------>|       Website      |
+                                                                             |       +--------------------+
+                                                                             |       +--------------------+
+  +----------------------------------+                                       |------>|       etc...       |
+  | Mixnet:                          |                                       |       +--------------------+
+  |       * Gateway your client is   |                                       |
+  |       connected to               |          +--------------------+       |
+  |       * Mix nodes 1 -> 3         |<-------->| Network requester  |<------+
+  |       * Gateway that network     |          +--------------------+
+  |       requester is connected to  |
+  +----------------------------------+
+           ^
+           |
+           |
+           |
+           |
+           v
+ +-------------------+
+ | +---------------+ |
+ | |  Nym client   | |
+ | +---------------+ |
+ |         ^         |
+ |         |         |
+ |         |         |
+ |         |         |
+ |         v         |
+ | +---------------+ |
+ | | Your app code | |
+ | +---------------+ |
+ +-------------------+
+  Your Local Machine
+```
+
+There are 2 pieces of software that work together to send SOCKS traffic through the mixnet: the `nym-socks5-client`, and the `nym-network-requester`.
+
+The `nym-socks5-client` allows you to do the following from your local machine:
+* Take a TCP data stream from a application that can send traffic via SOCKS5.
+* Chop up the TCP stream into multiple Sphinx packets, assigning sequence numbers to them, while leaving the TCP connection open for more data
+* Send the Sphinx packets through the Nym Network. Packets are shuffled and mixed as they transit the mixnet.
+
+The `nym-network-requester` then reassembles the original TCP stream using the packets' sequence numbers, and make the intended request. It will then chop up the response into Sphinx packets and send them back through the mixnet to your  `nym-socks5-client`. The application will then receive its data, without even noticing that it wasn't talking to a "normal" SOCKS5 proxy!
+
+## Client setup
+### Viewing command help
+
+You can check that your binaries are properly compiled with:
+
+```
+./nym-socks5-client --help
+```
+
+~~~admonish example collapsible=true title="Console output"
+```
+<!-- cmdrun ../../../../target/release/nym-socks5-client --help -->
+```
+~~~
+
+You can check the necessary parameters for the available commands by running:
+
+```
+./nym-client <COMMAND> --help
+```
+
+### Initialising a new client instance
+Before you can use the client, you need to initalise a new instance of it, which can be done with the following command:
+
+```
+./nym-socks5-client init --id docs-example --use-reply-surbs true --provider Entztfv6Uaz2hpYHQJ6JKoaCTpDL5dja18SuQWVJAmmx.Cvhn9rBJw5Ay9wgHcbgCnVg89MPSV5s2muPV2YF1BXYu@Fo4f4SQLdoyoGkFae5TpVhRVoXCF8UiypLVGtGjujVPf
+```
+
+~~~admonish example collapsible=true title="Console output"
+```
+<!-- cmdrun ../../../../target/release/nym-socks5-client init --id docs-example --provider Entztfv6Uaz2hpYHQJ6JKoaCTpDL5dja18SuQWVJAmmx.Cvhn9rBJw5Ay9wgHcbgCnVg89MPSV5s2muPV2YF1BXYu@Fo4f4SQLdoyoGkFae5TpVhRVoXCF8UiypLVGtGjujVPf -->
+```
+~~~
+
+The `--id` in the example above is a local identifier so that you can name your clients and keep track of them on your local system; it is **never** transmitted over the network.
+
+The `--use-reply-surbs` field denotes whether you wish to send [SURBs](https://nymtech.net/docs/architecture/traffic-flow.md#private-replies-using-surbs) along with your request. It defaults to `false`, we are explicitly setting it as `true`. It defaults to `false` for compatibility with older versions of the [Network Requester](https://nymtech.net/nodes/network-requester.md).
+
+The `--provider` field needs to be filled with the Nym address of a Network Requester that can make network requests on your behalf. If you don't want to [run your own](https://nymtech.net/operators/nodes/network-requester.md) you can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/service-providers) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [this list](https://harbourmaster.nymtech.net/).
+
+#### Choosing a Gateway
+By default - as in the example above - your client will choose a random gateway to connect to.
+
+However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client:
+* If you wish to connect to a specific gateway, you can specify this with the `--gateway` flag when running `init`.
+* You can also choose a gateway based on its location relative to your client. This can be done by appending the `--latency-based-selection` flag to your `init` command. This command means that to select a gateway, your client will:
+	* fetch a list of all availiable gateways
+	* send few ping messages to all of them, and measure response times.
+	* create a weighted distribution to randomly choose one, favouring ones with lower latency.
+
+> Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms
+
+### Configuring your client
+When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/socks5-clients/<client-name>/`.
+
+```
+tree $HOME/<user>/.nym/socks5-clients/docs-example
+├── config
+│   └── config.toml
+└── data
+    ├── ack_key.pem
+    ├── credentials_database.db
+    ├── gateway_shared.pem
+    ├── persistent_reply_store.sqlite
+    ├── private_encryption.pem
+    ├── private_identity.pem
+    ├── public_encryption.pem
+    └── public_identity.pem
+
+```
+
+The `config.toml` file contains client configuration options, while the two `pem` files contain client key information.
+
+The generated files contain the client name, public/private keypairs, and gateway address. The name `<client_id>` in the example above is just a local identifier so that you can name your clients.
+
+#### Configuring your client for Docker
+By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`.
+
+You can set this via the `--host` flag during either the `init` or `run` commands.
+
+Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process.
+
+### Running the socks5 client
+
+You can run the initialised client by doing this:
+
+```
+./nym-socks5-client run --id docs-example
+```
+
+## Automating your socks5 client with systemd
+
+Create a service file for the socks5 client at `/etc/systemd/system/nym-socks5-client.service`:
+
+```ini
+[Unit]
+Description=Nym Socks5 Client
+StartLimitInterval=350
+StartLimitBurst=10
+
+[Service]
+User=nym # replace this with whatever user you wish
+LimitNOFILE=65536
+ExecStart=/home/nym/nym-socks5-client run --id <your_id>
+KillSignal=SIGINT
+Restart=on-failure
+RestartSec=30
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Now enable and start your socks5 client:
+
+```
+systemctl enable nym-socks5-client.service
+systemctl start nym-socks5-client.service
+# you can always check your socks5 client has succesfully started with:
+systemctl status nym-socks5-client.service
+```
+
+## Using your Socks5 Client
+
+After completing the steps above, your local Socks5 Client will be listening on `localhost:1080` ready to proxy traffic to the Network Requester set as the `--provider` when initialising.
+
+When trying to connect your app, generally the proxy settings are found in `settings->advanced` or `settings->connection`.
+
+Here is an example of setting the proxy connecting in Blockstream Green:
+
+![Blockstream Green settings](../images/wallet-proxy-settings/blockstream-green.gif)
+
+Most wallets and other applications will work basically the same way: find the network proxy settings, enter the proxy url (host: **localhost**, port: **1080**).
+
+In some other applications, this might be written as **localhost:1080** if there's only one proxy entry field.
+
+## Useful Commands
+
+**no-banner**
+
+Adding `--no-banner` startup flag will prevent Nym banner being printed even if run in tty environment.
+
+**build-info**
+
+A `build-info` command prints the build information like commit hash, rust version, binary version just like what command `--version` does. However, you can also specify an `--output=json` flag that will format the whole output as a json, making it an order of magnitude easier to parse.

documentation/docs/pages/developers/concepts.mdx

@@ -0,0 +1,5 @@
+# Core Concepts
+
+We are working on making the Mixnet as easy as possible to use; that said, it is at the moment still quite an unusual system in terms of how it works and the required parts.
+
+We are working on abstractions to emulate more traditional networking such as reading from / writing to TCP sockets, and have plans to modify the internals of the clients to remove some of the required architecture and slim down the parts required to use the Mixnet.

documentation/docs/pages/developers/concepts/_meta.json

@@ -0,0 +1,6 @@
+{
+  "required-architecture": "Required Architecture",
+  "messages": "Message Based Paradigm",
+  "message-queue": "Message Queue",
+  "abstractions": "Connection Abstractions"
+}

documentation/docs/pages/developers/concepts/abstractions.mdx

@@ -0,0 +1 @@
+stub

documentation/docs/pages/developers/concepts/message-queue.md

@@ -0,0 +1,2 @@
+
+2) actually waiting on messages: `send()` **just puts the message in the queue of cover traffic** so dropping a client before its actually sent is something that is possible and should be avoided (see the troubleshooting example TODO LINK) for more on this.

documentation/docs/pages/developers/concepts/messages.mdx

@@ -0,0 +1,3 @@
+stub
+
+1) working on messages not streaming / bytes which can be a pain : check the use of the bytecodec logic in the tcpproxy for looking @ how we handle this there

documentation/docs/pages/developers/concepts/required-architecture.md

@@ -0,0 +1,6 @@
+- what do i need? clients on both sides
+  - take a traditional client / server app setup: we need to put the mixnet betwen them to get the privacy properties, and each of them need a client in order to connect and authenticate with the mixnet to send and receive messages: since a lot of the functionality happens client-side and the sphinx of it all
+
+- what dont i need? to run your own infra
+  - you can basically use the mixnet as a black box
+  - maybe if you're expecting a load of traffic / dont want to rely on other people's gateways, you could run your own and then connect to them specifically (qu: can we configure the client to connect to a particular gateway?)

documentation/docs/pages/developers/index.mdx

@@ -0,0 +1,7 @@
+# Introduction
+Nym's developer documentation covering core concepts of integrating with the Mixnet, interacting with the Nyx blockchain, an overview of the avaliable tools, and our SDK docs.
+
+## Where to Start?
+If you are completely new to Nym, it is suggested to start with the top sections covering the core concepts, integration options, and the clients and tools available to you.
+
+If you feel like starting with more practical examples, check out the relevent SDK docs in the sidebar to the left.

documentation/docs/pages/developers/integrations.mdx

@@ -0,0 +1,39 @@
+import Box from '@mui/material/Box';
+import { Steps } from 'nextra/components'
+import { Tabs } from 'nextra/components'
+import { GitHubRepoSearch } from '../../code-snippets/mixfetchurl';
+
+# Integration Options
+Developers might want to either integrate a Mixnet client or just to interact with the blockchain. See the relevant section below.
+
+### Integrating Mixnet Functionality
+There are several options available to developers wanting to embed a Nym client in their application code.
+
+<Tabs items={['Typescript/Javascript', 'Rust/Go/C++', 'Other']}>
+  <Tabs.Tab >
+    <>
+  Typescript and Javascript developers have several options avaliable to them:
+    - [`mixfetch`]() TODO LINK is an almost-dropin replacement for the `fetch` library. The best way to integrate Nym's `mixFetch` into your application will be where external network calls and RPC happens, for example, something in the lines of `sendRawTransaction` if you have an ETH-compatible wallet or `JsonRpcClient` if you use CosmJS. Although you can simply search for any JS `fetch` calls in your code (using our tool below) that are easily replaceable with `mixFetch`, keep in mind that `fetch` is not the only way to make `JSONRPC` or `XHR` calls. We advise to approach the integration process in a semantic way, searching for a module that is the common denominator for external communication in the codebase. Usually these are API controllers, middlewares or repositories.
+
+  <GitHubRepoSearch />
+
+  - Otherwise, a well-modularized JS/TS codebase should permit the integration of one of our other SDK components, which will allow more flexibility and control (or if your codebase is not using something that can be covered by `fetch` for networking). Read more about our different SDK components in the [TS SDK overview page](). TODO LINK
+
+  </>
+  </Tabs.Tab>
+  <Tabs.Tab>
+  <>
+  Rust developers can rely on our Rust SDK to import Nym client functionality into their code. This can either be in the form of a standard message-based client, the `socks5` client, or the `TcpProxy` modules.
+
+  We aim to expose at least the majority of this functionality via FFI to Go and C/C++. This is detailed alongside the Rust SDK components in the [Rust SDK docs]() TODO LINK.
+
+  </ >
+  </Tabs.Tab>
+  <Tabs.Tab> If your app is not written in any of the supported languages, you might still be able to send traffic through a standalone socks5 client TODO LINK but will have to think about packaging and bundling the client binary with e.g. a `systemd` file for autostart to run the client as a daemon. If you want to discuss FFI options reach out to us via our public dev channel. TODO LINK </Tabs.Tab>
+</Tabs>
+
+### Interacting with Nyx
+
+If instead of relying on the Mixnet you wish to interact with the [Nyx]() TODO LINK chain, either as a payment processor or to get on-chain events, see [interacting with the chain]() TODO LINK.
+
+> Note that depending on your setup, you might already be able to combine interacting with the chain with using the Mixnet: check the options above for more.

documentation/docs/pages/developers/rust.md

@@ -0,0 +1,7 @@
+# Introduction
+The Rust SDK allows developers building applications in Rust to import and interact with Nym clients as they would any other dependency, instead of running the client as a separate process on their machine. This makes both developing and running applications much easier, reducing complexity in the development process (not having to restart another client in a separate console window/tab) and being able to have a single binary for other people to use.
+
+Currently developers can use the Rust SDK to import either websocket client ([`nym-client`](../../clients/websocket-client.md)) or [`socks-client`](../../clients/socks5-client.md) functionality into their Rust code.
+
+### Generate Crate Docs
+In order to generate the crate docs run `cargo doc --open` from `nym/sdk/rust/nym-sdk/`

documentation/docs/pages/developers/rust/_meta.json

@@ -0,0 +1,10 @@
+{
+  "development-status": "Development Status",
+  "importing": "Importing",
+  "examples": "Basic Examples",
+  "message-helpers": "Message Helpers",
+  "message-types": "Message Types",
+  "troubleshooting": "Troubleshooting",
+  "ffi": "FFI",
+  "tutorials": "Tutorials (Coming Soon)"
+}

documentation/docs/pages/developers/rust/development-status.md

@@ -0,0 +1,14 @@
+# Development status
+The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases.
+
+In the future the SDK will be made up of several components, each of which will allow developers to interact with different parts of Nym infrastructure.
+
+| Component | Functionality                                                                         | Released |
+|-----------|---------------------------------------------------------------------------------------|----------|
+| Mixnet    | Create / load clients & keypairs, subscribe to Mixnet events, send & receive messages | ✔️        |
+| Ecash   | Create & verify Ecash credentials                                                       | 🛠️        |
+| Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain                    | ❌        |
+
+The `mixnet` component currently exposes the logic of two clients: the [websocket client]() TODO LINK, and the [socks]() TODO client.
+
+The `ecash` component is currently being worked on. Right now it exposes logic allowing for the creation of Ecash credentials on the Sandbox testnet.

documentation/docs/pages/developers/rust/examples.md

@@ -0,0 +1,9 @@
+# Examples
+
+All the following examples can be found in the `nym-sdk` [examples directory](https://github.com/nymtech/nym/tree/master/sdk/rust/nym-sdk/examples) in the monorepo. Just navigate to `nym/sdk/rust/nym-sdk/examples/` and run the files from there with:
+
+```sh
+cargo run --example <NAME_OF_FILE>
+```
+
+If you wish to run these outside of the workspace - such as if you want to use one as the basis for your own project - then make sure to import the `sdk`, `tokio`, and `nym_bin_common` crates.

documentation/docs/pages/developers/rust/examples/_meta.json

@@ -0,0 +1,9 @@
+{
+  "simple": "Simple Send",
+  "builders": "Builder Patterns",
+  "custom-topology": "Custom Network Topologies",
+  "split-send": "Concurrent Send & Receive",
+  "socks": "Socks Proxy",
+  "storage": "Manually Handle Storage",
+  "surbs": "Anonymous Replies"
+}

documentation/docs/pages/developers/rust/examples/builders.md

@@ -0,0 +1,3 @@
+# Builder Patterns
+
+Since there are two ways of creating an SDK client - ephemeral and with-storage - then there are two ways of applying the Builder Pattern to client creation.

documentation/docs/pages/developers/rust/examples/builders/_meta.json

@@ -0,0 +1,4 @@
+{
+  "builder": "Ephemeral",
+  "builder-with-storage": "With Storage"
+}

documentation/docs/pages/developers/rust/examples/builders/builder-with-storage.md

@@ -0,0 +1,72 @@
+# Mixnet Client Builder with Storage
+
+The previous example involves ephemeral keys - if we want to create and then maintain a client identity over time, our code becomes a little more complex as we need to create, store, and conditionally load these keys.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder_with_storage.rs).
+
+```rust
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+use std::path::PathBuf;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Specify some config options
+    let config_dir = PathBuf::from("/tmp/mixnet-client");
+    let storage_paths = mixnet::StoragePaths::new_from_dir(&config_dir).unwrap();
+
+    // Create the client with a storage backend, and enable it by giving it some paths. If keys
+    // exists at these paths, they will be loaded, otherwise they will be generated.
+    let client = mixnet::MixnetClientBuilder::new_with_default_storage(storage_paths)
+        .await
+        .unwrap()
+        .build()
+        .unwrap();
+
+    // Now we connect to the mixnet, using keys now stored in the paths provided.
+    let mut client = client.connect_to_mixnet().await.unwrap();
+
+    // Be able to get our client address
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send a message throught the mixnet to ourselves
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message");
+    if let Some(received) = client.wait_for_messages().await {
+        for r in received {
+            println!("Received: {}", String::from_utf8_lossy(&r.message));
+        }
+    }
+
+    client.disconnect().await;
+}
+```
+
+As seen in the example above, the `mixnet::MixnetClientBuilder::new()` function handles checking for keys in a storage location, loading them if present, or creating them and storing them if not, making client key management very simple.
+
+Assuming our client config is stored in `/tmp/mixnet-client`, the following files are generated:
+```
+$ tree /tmp/mixnet-client
+
+mixnet-client
+├── ack_key.pem
+├── db.sqlite
+├── db.sqlite-shm
+├── db.sqlite-wal
+├── gateway_details.json
+├── gateway_shared.pem
+├── persistent_reply_store.sqlite
+├── private_encryption.pem
+├── private_identity.pem
+├── public_encryption.pem
+└── public_identity.pem
+
+1 directory, 11 files
+```

documentation/docs/pages/developers/rust/examples/builders/builder.md

@@ -0,0 +1,43 @@
+# Mixnet Client Builder
+
+You can spin up an ephemeral client like so. This client will not have a persistent identity and its keys will be dropped on restart. Since there is currently no way of reconnecting a client that has been disconnected after use, then treat disconnecting a client the same as dropping its keys entirely.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder.rs).
+
+```rust
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Create client builder, including ephemeral keys. The builder can be usable in the context
+    // where you don't want to connect just yet.
+    let client = mixnet::MixnetClientBuilder::new_ephemeral()
+        .build()
+        .unwrap();
+
+    // Now we connect to the mixnet, using ephemeral keys already created
+    let mut client = client.connect_to_mixnet().await.unwrap();
+
+    // Be able to get our client address
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send a message through the mixnet to ourselves
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message");
+    if let Some(received) = client.wait_for_messages().await {
+        for r in received {
+            println!("Received: {}", String::from_utf8_lossy(&r.message));
+        }
+    }
+
+    client.disconnect().await;
+}
+```

documentation/docs/pages/developers/rust/examples/custom-topology.md

@@ -0,0 +1,11 @@
+# Importing and using a custom network topology
+If you want to send traffic through a sub-set of nodes (for instance, ones you control, or a small test setup) when developing, debugging, or performing research, you will need to import these nodes as a custom network topology, instead of grabbing it from the [`Mainnet Nym-API`](https://validator.nymtech.net/api/swagger/index.html).
+
+
+There are two ways to do this:
+
+## Custom Topology Provider
+If you are also running a Validator and Nym API for your network, you can specify that endpoint. Clients will then use this endpoint to grab a network topology on startup. You can also use this to specify using a testnet.
+
+## Import a specific topology manually
+If you aren't running a Validator and Nym API, and just want to import a specific sub-set of mix nodes, you can also overwrite the grabbed topology manually.

documentation/docs/pages/developers/rust/examples/custom-topology/_meta.json

@@ -0,0 +1,4 @@
+{
+  "custom-provider": "Custom Topology Provider",
+  "manual-topology": "Manually Overwrite Topology"
+}

documentation/docs/pages/developers/rust/examples/custom-topology/custom-provider.md

@@ -0,0 +1,89 @@
+# Custom Topology Provider
+
+If you are also running a Validator and Nym API for your network, you can specify that endpoint as such and interact with it as clients usually do (under the hood).
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/custom_topology_provider.rs)
+
+```rust
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+use nym_topology::provider_trait::{async_trait, TopologyProvider};
+use nym_topology::{nym_topology_from_detailed, NymTopology};
+use url::Url;
+
+struct MyTopologyProvider {
+    validator_client: nym_validator_client::client::NymApiClient,
+}
+
+impl MyTopologyProvider {
+    fn new(nym_api_url: Url) -> MyTopologyProvider {
+        MyTopologyProvider {
+            validator_client: nym_validator_client::client::NymApiClient::new(nym_api_url),
+        }
+    }
+
+    async fn get_topology(&self) -> NymTopology {
+        let mixnodes = self
+            .validator_client
+            .get_cached_active_mixnodes()
+            .await
+            .unwrap();
+
+        // in our topology provider only use mixnodes that have mix_id divisible by 3
+        // and have more than 100k nym (i.e. 100'000'000'000 unym) in stake
+        // why? because this is just an example to showcase arbitrary uses and capabilities of this trait
+        let filtered_mixnodes = mixnodes
+            .into_iter()
+            .filter(|mix| {
+                mix.mix_id() % 3 == 0 && mix.total_stake() > "100000000000".parse().unwrap()
+            })
+            .collect::<Vec<_>>();
+
+        let gateways = self.validator_client.get_cached_gateways().await.unwrap();
+
+        nym_topology_from_detailed(filtered_mixnodes, gateways)
+    }
+}
+
+#[async_trait]
+impl TopologyProvider for MyTopologyProvider {
+    // this will be manually refreshed on a timer specified inside mixnet client config
+    async fn get_new_topology(&mut self) -> Option<NymTopology> {
+        Some(self.get_topology().await)
+    }
+}
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    let nym_api = "https://validator.nymtech.net/api/".parse().unwrap();
+    let my_topology_provider = MyTopologyProvider::new(nym_api);
+
+    // Passing no config makes the client fire up an ephemeral session and figure things out on its own
+    let mut client = mixnet::MixnetClientBuilder::new_ephemeral()
+        .custom_topology_provider(Box::new(my_topology_provider))
+        .build()
+        .unwrap()
+        .connect_to_mixnet()
+        .await
+        .unwrap();
+
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send a message through the mixnet to ourselves
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message (ctrl-c to exit)");
+    client
+        .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message)))
+        .await;
+}
+```

documentation/docs/pages/developers/rust/examples/custom-topology/manually-overwrite-topology.md

@@ -0,0 +1,102 @@
+# Manually Overwrite Topology
+
+If you aren't running a Validator and Nym API, and just want to import a specific sub-set of mix nodes, you can simply overwrite the grabbed topology manually.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_overwrite_topology.rs)
+
+```rust
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+use nym_topology::mix::Layer;
+use nym_topology::{mix, NymTopology};
+use std::collections::BTreeMap;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Passing no config makes the client fire up an ephemeral session and figure shit out on its own
+    let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
+    let starting_topology = client.read_current_topology().await.unwrap();
+
+    // but we don't like our default topology, we want to use only those very specific, hardcoded, nodes:
+    let mut mixnodes = BTreeMap::new();
+    mixnodes.insert(
+        1,
+        vec![mix::Node {
+            mix_id: 63,
+            owner: None,
+            host: "172.105.92.48".parse().unwrap(),
+            mix_host: "172.105.92.48:1789".parse().unwrap(),
+            identity_key: "GLdR2NRVZBiCoCbv4fNqt9wUJZAnNjGXHkx3TjVAUzrK"
+                .parse()
+                .unwrap(),
+            sphinx_key: "CBmYewWf43iarBq349KhbfYMc9ys2ebXWd4Vp4CLQ5Rq"
+                .parse()
+                .unwrap(),
+            layer: Layer::One,
+            version: "1.1.0".into(),
+        }],
+    );
+    mixnodes.insert(
+        2,
+        vec![mix::Node {
+            mix_id: 23,
+            owner: None,
+            host: "178.79.143.65".parse().unwrap(),
+            mix_host: "178.79.143.65:1789".parse().unwrap(),
+            identity_key: "4Yr4qmEHd9sgsuQ83191FR2hD88RfsbMmB4tzhhZWriz"
+                .parse()
+                .unwrap(),
+            sphinx_key: "8ndjk5oZ6HxUZNScLJJ7hk39XtUqGexdKgW7hSX6kpWG"
+                .parse()
+                .unwrap(),
+            layer: Layer::Two,
+            version: "1.1.0".into(),
+        }],
+    );
+    mixnodes.insert(
+        3,
+        vec![mix::Node {
+            mix_id: 66,
+            owner: None,
+            host: "139.162.247.97".parse().unwrap(),
+            mix_host: "139.162.247.97:1789".parse().unwrap(),
+            identity_key: "66UngapebhJRni3Nj52EW1qcNsWYiuonjkWJzHFsmyYY"
+                .parse()
+                .unwrap(),
+            sphinx_key: "7KyZh8Z8KxuVunqytAJ2eXFuZkCS7BLTZSzujHJZsGa2"
+                .parse()
+                .unwrap(),
+            layer: Layer::Three,
+            version: "1.1.0".into(),
+        }],
+    );
+
+    // but we like the available gateways, so keep using them!
+    // (we like them because the author of this example is too lazy to use the same hardcoded gateway
+    // during client initialisation to make sure we are able to send to ourselves : )  )
+    let custom_topology = NymTopology::new(mixnodes, starting_topology.gateways().to_vec());
+
+    client.manually_overwrite_topology(custom_topology).await;
+
+    // and everything we send now should only ever go via those nodes
+
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send a message through the mixnet to ourselves
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message (ctrl-c to exit)");
+    client
+        .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message)))
+        .await;
+}
+```

documentation/docs/pages/developers/rust/examples/simple.md

@@ -0,0 +1,34 @@
+# Simple Send
+Lets look at a very simple example of how you can import and use the websocket client in a piece of Rust code.
+
+Simply importing the `nym_sdk` crate into your project allows you to create a client and send traffic through the mixnet.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/simple.rs)
+
+```rust
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Passing no config makes the client fire up an ephemeral session and figure shit out on its own
+    let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
+
+    // Be able to get our client address
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send a message through the mixnet to ourselves
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message (ctrl-c to exit)");
+    client
+        .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message)))
+        .await;
+}
+```

documentation/docs/pages/developers/rust/examples/socks.md

@@ -0,0 +1,48 @@
+# Socks Proxy
+
+If you are looking at implementing Nym as a transport layer for a crypto wallet or desktop app, this is probably the best place to start if they can speak SOCKS5, 4a, or 4.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/socks5.rs)
+
+```rust
+use nym_sdk::mixnet;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    println!("Connecting receiver");
+    let mut receiving_client = mixnet::MixnetClient::connect_new().await.unwrap();
+
+    let socks5_config = mixnet::Socks5::new(receiving_client.nym_address().to_string());
+    let sending_client = mixnet::MixnetClientBuilder::new_ephemeral()
+        .socks5_config(socks5_config)
+        .build()
+        .unwrap();
+
+    println!("Connecting sender");
+    let sending_client = sending_client.connect_to_mixnet_via_socks5().await.unwrap();
+
+    let proxy = reqwest::Proxy::all(sending_client.socks5_url()).unwrap();
+    let reqwest_client = reqwest::Client::builder().proxy(proxy).build().unwrap();
+    tokio::spawn(async move {
+        println!("Sending socks5-wrapped http request");
+        // Message should be sent through the mixnet, via socks5
+        // We don't expect to get anything, as there is no network requester on the other end
+        reqwest_client.get("https://nymtech.net").send().await.ok()
+    });
+
+    println!("Waiting for message");
+    if let Some(received) = receiving_client.wait_for_messages().await {
+        for r in received {
+            println!(
+                "Received socks5 message requesting for endpoint: {}",
+                String::from_utf8_lossy(&r.message[10..27])
+            );
+        }
+    }
+
+    receiving_client.disconnect().await;
+    sending_client.disconnect().await;
+}
+```

documentation/docs/pages/developers/rust/examples/split-send.md

@@ -0,0 +1,49 @@
+# Send and Receive in Different Tasks
+If you need to split the different actions of your client across different tasks, you can do so like this. You can think of this analogously to spliting a Tcp Stream into read/write. This functionality is also useful for embedding a sending and receiving client into different tasks.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs)
+
+```rust
+// Copyright 2023 - Nym Technologies SA <contact@nymtech.net>
+// SPDX-License-Identifier: Apache-2.0
+
+use futures::StreamExt;
+use nym_sdk::mixnet;
+use nym_sdk::mixnet::MixnetMessageSender;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Passing no config makes the client fire up an ephemeral session and figure stuff out on its own
+    let mut client = mixnet::MixnetClient::connect_new().await.unwrap();
+
+    // Be able to get our client address
+    let our_address = *client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    let sender = client.split_sender();
+
+    // receiving task
+    let receiving_task_handle = tokio::spawn(async move {
+        if let Some(received) = client.next().await {
+            println!("Received: {}", String::from_utf8_lossy(&received.message));
+        }
+
+        client.disconnect().await;
+    });
+
+    // sending task
+    let sending_task_handle = tokio::spawn(async move {
+        sender
+            .send_plain_message(our_address, "hello from a different task!")
+            .await
+            .unwrap();
+    });
+
+    // wait for both tasks to be done
+    println!("waiting for shutdown");
+    sending_task_handle.await.unwrap();
+    receiving_task_handle.await.unwrap();
+}
+```

documentation/docs/pages/developers/rust/examples/storage.md

@@ -0,0 +1,226 @@
+# Manually Handle Storage
+If you're integrating mixnet functionality into an existing app and want to integrate saving client configs and keys into your existing storage logic, you can manually perform these actions.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_handle_storage.rs)
+
+```rust
+use nym_sdk::mixnet::{
+    self, ActiveGateway, BadGateway, ClientKeys, EmptyReplyStorage, EphemeralCredentialStorage,
+    GatewayRegistration, GatewaysDetailsStore, KeyStore, MixnetClientStorage, MixnetMessageSender,
+};
+use nym_topology::provider_trait::async_trait;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Just some plain data to pretend we have some external storage that the application
+    // implementer is using.
+    let mock_storage = MockClientStorage::empty();
+    let mut client = mixnet::MixnetClientBuilder::new_with_storage(mock_storage)
+        .build()
+        .unwrap()
+        .connect_to_mixnet()
+        .await
+        .unwrap();
+
+    // Be able to get our client address
+    let our_address = client.nym_address();
+    println!("Our client nym address is: {our_address}");
+
+    // Send important info up the pipe to a buddy
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    println!("Waiting for message");
+    if let Some(received) = client.wait_for_messages().await {
+        for r in received {
+            println!("Received: {}", String::from_utf8_lossy(&r.message));
+        }
+    }
+
+    client.disconnect().await;
+}
+
+#[allow(unused)]
+struct MockClientStorage {
+    pub key_store: MockKeyStore,
+    pub gateway_details_store: MockGatewayDetailsStore,
+    pub reply_store: EmptyReplyStorage,
+    pub credential_store: EphemeralCredentialStorage,
+}
+
+impl MockClientStorage {
+    fn empty() -> Self {
+        Self {
+            key_store: MockKeyStore,
+            gateway_details_store: MockGatewayDetailsStore,
+            reply_store: EmptyReplyStorage::default(),
+            credential_store: EphemeralCredentialStorage::default(),
+        }
+    }
+}
+
+impl MixnetClientStorage for MockClientStorage {
+    type KeyStore = MockKeyStore;
+    type ReplyStore = EmptyReplyStorage;
+    type CredentialStore = EphemeralCredentialStorage;
+    type GatewaysDetailsStore = MockGatewayDetailsStore;
+
+    fn into_runtime_stores(self) -> (Self::ReplyStore, Self::CredentialStore) {
+        (self.reply_store, self.credential_store)
+    }
+
+    fn key_store(&self) -> &Self::KeyStore {
+        &self.key_store
+    }
+
+    fn reply_store(&self) -> &Self::ReplyStore {
+        &self.reply_store
+    }
+
+    fn credential_store(&self) -> &Self::CredentialStore {
+        &self.credential_store
+    }
+
+    fn gateway_details_store(&self) -> &Self::GatewaysDetailsStore {
+        &self.gateway_details_store
+    }
+}
+
+struct MockKeyStore;
+
+#[async_trait]
+impl KeyStore for MockKeyStore {
+    type StorageError = MyError;
+
+    async fn load_keys(&self) -> Result<ClientKeys, Self::StorageError> {
+        println!("loading stored keys");
+
+        Err(MyError)
+    }
+
+    async fn store_keys(&self, _keys: &ClientKeys) -> Result<(), Self::StorageError> {
+        println!("storing keys");
+
+        Ok(())
+    }
+}
+
+struct MockGatewayDetailsStore;
+
+#[async_trait]
+impl GatewaysDetailsStore for MockGatewayDetailsStore {
+    type StorageError = MyError;
+
+    async fn active_gateway(&self) -> Result<ActiveGateway, Self::StorageError> {
+        println!("getting active gateway");
+
+        Err(MyError)
+    }
+
+    async fn set_active_gateway(&self, _gateway_id: &str) -> Result<(), Self::StorageError> {
+        println!("setting active gateway");
+
+        Ok(())
+    }
+
+    async fn all_gateways(&self) -> Result<Vec<GatewayRegistration>, Self::StorageError> {
+        println!("getting all registered gateways");
+
+        Err(MyError)
+    }
+
+    async fn has_gateway_details(&self, _gateway_id: &str) -> Result<bool, Self::StorageError> {
+        println!("checking for gateway details");
+
+        Err(MyError)
+    }
+
+    async fn load_gateway_details(
+        &self,
+        _gateway_id: &str,
+    ) -> Result<GatewayRegistration, Self::StorageError> {
+        println!("loading gateway details");
+
+        Err(MyError)
+    }
+
+    async fn store_gateway_details(
+        &self,
+        _details: &GatewayRegistration,
+    ) -> Result<(), Self::StorageError> {
+        println!("storing gateway details");
+
+        Ok(())
+    }
+
+    async fn remove_gateway_details(&self, _gateway_id: &str) -> Result<(), Self::StorageError> {
+        println!("removing gateway details");
+
+        Ok(())
+    }
+}
+
+//
+// struct MockReplyStore;
+//
+// #[async_trait]
+// impl ReplyStorageBackend for MockReplyStore {
+//     type StorageError = MyError;
+//
+//     async fn flush_surb_storage(
+//         &mut self,
+//         _storage: &CombinedReplyStorage,
+//     ) -> Result<(), Self::StorageError> {
+//         todo!()
+//     }
+//
+//     async fn init_fresh(&mut self, _fresh: &CombinedReplyStorage) -> Result<(), Self::StorageError> {
+//         todo!()
+//     }
+//
+//     async fn load_surb_storage(&self) -> Result<CombinedReplyStorage, Self::StorageError> {
+//         todo!()
+//     }
+// }
+//
+// struct MockCredentialStore;
+//
+// #[async_trait]
+// impl CredentialStorage for MockCredentialStore {
+//     type StorageError = MyError;
+//
+//     async fn insert_coconut_credential(
+//         &self,
+//         _voucher_value: String,
+//         _voucher_info: String,
+//         _serial_number: String,
+//        _binding_number: String,
+//         _signature: String,
+//         _epoch_id: String,
+//     ) -> Result<(), Self::StorageError> {
+//         todo!()
+//     }
+//
+//     async fn get_next_coconut_credential(&self) -> Result<CoconutCredential, Self::StorageError> {
+//         todo!()
+//     }
+//
+//     async fn consume_coconut_credential(&self, id: i64) -> Result<(), Self::StorageError> {
+//         todo!()
+//     }
+// }
+
+#[derive(thiserror::Error, Debug)]
+#[error("foobar")]
+struct MyError;
+
+impl From<BadGateway> for MyError {
+    fn from(_: BadGateway) -> Self {
+        MyError
+    }
+}
+```

documentation/docs/pages/developers/rust/examples/surbs.md

@@ -0,0 +1,83 @@
+# Anonymous Replies with SURBs (Single Use Reply Blocks)
+Both functions used to send messages through the mixnet (`send_message` and `send_plain_message`) send a pre-determined number of SURBs along with their messages by default.
+
+You can read more about how SURBs function under the hood [here](https://nymtech.net/docs/architecture/traffic-flow.html#private-replies-using-surbs). **TODO change link**
+
+In order to reply to an incoming message using SURBs, you can construct a `recipient` from the `sender_tag` sent along with the message you wish to reply to.
+
+> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/surb_reply.rs)
+
+```rust
+use nym_sdk::mixnet::{
+    AnonymousSenderTag, MixnetClientBuilder, MixnetMessageSender, ReconstructedMessage,
+    StoragePaths,
+};
+use std::path::PathBuf;
+
+#[tokio::main]
+async fn main() {
+    nym_bin_common::logging::setup_logging();
+
+    // Specify some config options
+    let config_dir = PathBuf::from("/tmp/surb-example");
+    let storage_paths = StoragePaths::new_from_dir(&config_dir).unwrap();
+
+    // Create the client with a storage backend, and enable it by giving it some paths. If keys
+    // exists at these paths, they will be loaded, otherwise they will be generated.
+    let client = MixnetClientBuilder::new_with_default_storage(storage_paths)
+        .await
+        .unwrap()
+        .build()
+        .unwrap();
+
+    // Now we connect to the mixnet, using keys now stored in the paths provided.
+    let mut client = client.connect_to_mixnet().await.unwrap();
+
+    // Be able to get our client address
+    let our_address = client.nym_address();
+    println!("\nOur client nym address is: {our_address}");
+
+    // Send a message through the mixnet to ourselves using our nym address
+    client
+        .send_plain_message(*our_address, "hello there")
+        .await
+        .unwrap();
+
+    // we're going to parse the sender_tag (AnonymousSenderTag) from the incoming message and use it to 'reply' to ourselves instead of our Nym address.
+    // we know there will be a sender_tag since the sdk sends SURBs along with messages by default.
+    println!("Waiting for message\n");
+
+    // get the actual message - discard the empty vec sent along with a potential SURB topup request
+    let mut message: Vec<ReconstructedMessage> = Vec::new();
+    while let Some(new_message) = client.wait_for_messages().await {
+        if new_message.is_empty() {
+            continue;
+        }
+        message = new_message;
+        break;
+    }
+
+    let mut parsed = String::new();
+    if let Some(r) = message.first() {
+        parsed = String::from_utf8(r.message.clone()).unwrap();
+    }
+    // parse sender_tag: we will use this to reply to sender without needing their Nym address
+    let return_recipient: AnonymousSenderTag = message[0].sender_tag.unwrap();
+    println!(
+        "\nReceived the following message: {} \nfrom sender with surb bucket {}",
+        parsed, return_recipient
+    );
+
+    // reply to self with it: note we use `send_str_reply` instead of `send_str`
+    println!("Replying with using SURBs");
+    client
+        .send_reply(return_recipient, "hi an0n!")
+        .await
+        .unwrap();
+
+    println!("Waiting for message (once you see it, ctrl-c to exit)\n");
+    client
+        .on_messages(|msg| println!("\nReceived: {}", String::from_utf8_lossy(&msg.message)))
+        .await;
+}
+```

documentation/docs/pages/developers/rust/ffi.mdx

@@ -0,0 +1,51 @@
+import { Callout } from 'nextra/components'
+
+# FFI Bindings
+
+<Callout type="info" emoji="ℹ️">
+  We are only working on the intitial versions of the FFI code to allow developers to experiment and get feedback. Please get in touch if you think the FFI bindings are lacking certain functionality.
+</Callout>
+
+We currently have FFI bindings for Go and C/C++. See the table below to check the coverage of functionality we expect devs would like to see.
+
+### Mixnet Module
+This is the basic mixnet component of the SDK, exposing client functionality with which people can build custom interfaces with the Mixnet.
+
+| Rust Function                                    | Go   | C/C++ |
+| :----------------------------------------------- | :--: | ----: |
+| `MixnetClient::connect_new()`                    |  ✔️   |  ✔️  |
+| `MixnetClientBuilder::new_with_default_storage`  |  ✔️   |  ✔️  |
+| `MixnetClientBuilder::OTHERS`  | | |
+| `MixnetClientBuilder::OTHERS`  | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+
+
+> We have also implemented `listen_for_incoming()` which is a wrapper around the Mixnet client's `wait_for_messages()` which is exposed to Go and C/C++. This is a helper method for listening out for and handling incoming messages.
+
+### TcpProxy Module
+A connection abstraction TODO LINK which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the message-based TODO LINK format of the underlying client.
+
+| Rust Function      | Go   | C/C++ |
+| :----------------- | :--: | ----: |
+|                    |      |       |
+|                    |      |       |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+| | | |
+
+
+----------------
+for copypaste
+  ❌  ✔️
+----------------

documentation/docs/pages/developers/rust/ffi/_meta.json

@@ -0,0 +1,4 @@
+{
+  "go": "Go",
+  "cpp": "C/C++"
+}