From a2ca65447b99b2a1c1dd6fca9464ca4ab743b0e7 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 10 Oct 2024 16:51:39 +0200 Subject: [PATCH] diagram + concepts overview --- .../developers/concepts/message-queue.md | 2 -- .../pages/developers/concepts/messages.mdx | 13 +++----- .../concepts/required-architecture.md | 32 +++++++++++++++++-- 3 files changed, 33 insertions(+), 14 deletions(-) diff --git a/documentation/docs/pages/developers/concepts/message-queue.md b/documentation/docs/pages/developers/concepts/message-queue.md index 54c8ceb035..e312592912 100644 --- a/documentation/docs/pages/developers/concepts/message-queue.md +++ b/documentation/docs/pages/developers/concepts/message-queue.md @@ -7,5 +7,3 @@ As such, you need to be careful to keep the process managing your clients alive Accidentally dropping a client before your message has been sent is something that is possible and should be avoided (see the [troubleshooting guide](../rust/mixnet/troubleshooting) for more on this) but is easy to avoid simply by remembering to: - keep your client process alive, even if you are not expecting a reply to your message - (in the case of the SDKs) properly disconnecting your client in order to make sure that the message queue is flushed of Sphinx packets with actual payloads. - -TODO DIAGRAM diff --git a/documentation/docs/pages/developers/concepts/messages.mdx b/documentation/docs/pages/developers/concepts/messages.mdx index dbe01e1ae4..be839c7766 100644 --- a/documentation/docs/pages/developers/concepts/messages.mdx +++ b/documentation/docs/pages/developers/concepts/messages.mdx @@ -1,6 +1,6 @@ # Message-based Paradigm -For the moment, Mixnet clients work assuming they will have atomic messages given to them to packetise, encrypt, and send through the Mixnet looking something like this: +For the moment, Mixnet clients work assuming they will be piped atomic messages looking something like this: ``` MixnetMessage { @@ -10,7 +10,9 @@ MixnetMessage { } ``` -Likewise, they assume that once they have received and decrypted a Sphinx packet, reconstruct messages with a structure something like this: +That the client will then encrypt as Sphinx packets and send through the Mixnet. + +Likewise, they assume that once they have received and decrypted a Sphinx packet, they will kick back a reconstructed message to the rest of your app logic that look something like: ``` ReconstructedMessage { @@ -19,15 +21,8 @@ ReconstructedMessage { } ``` -Examples for: -- [Standalone Websocket Client](../clients/websocket) -- [Rust SDK Client](../rust) -- [TS SDK Client](../typescript) - This is obviously quite different to e.g. simply being able to read/write from a stream returned from a function call to create a TCP connection, but there are several approaches that developers can take to dealing with this right now. -_We are planning future developments to make a more developer-friendly interface for our clients, but this will not be released before early/mid 2025_. - ## Message Abstractions - Rust/Go/C++ developers can use the `TcpProxy` [stream abstraction](../rust/tcpproxy). - Developers who are using Typescript/Javascript can also avoid having to deal directly with messages via using [MixFetch](../typescript/examples/mix-fetch). diff --git a/documentation/docs/pages/developers/concepts/required-architecture.md b/documentation/docs/pages/developers/concepts/required-architecture.md index 7154e986eb..a8be69985a 100644 --- a/documentation/docs/pages/developers/concepts/required-architecture.md +++ b/documentation/docs/pages/developers/concepts/required-architecture.md @@ -9,15 +9,41 @@ Nym clients on 'both sides' of the Mixnet. > We haven't yet tried to integrate a fully P2P application using anonymous replies: reach out if you are trying / have ideas! -That's it - so long as you have a Nym client, you can communicate with other Nym clients through the Mixnet. The content of your message payloads is up to you. +That's it - so long as you have a Nym client, you can communicate with other Nym clients through the Mixnet. The content of your message payloads is up to you, and you can approach funneling traffic through the Mixnet as a black box if you want! -TODO DIAGRAM +```mermaid +--- +config: + theme: neo-dark + layout: elk +title: The 'Black Box' Approach +--- +flowchart TB + subgraph Local Machine[Local Machine] + A[Application Logic] + B[Nym Client] + end + + A <-->|Bytes| B + B <-->|Sphinx Packets| Mixnet + + Mixnet{Mixnet Nodes} + + subgraph Remote Machine + C[Application Logic] + D[Nym Client] + end + + C <-->|Bytes| D + D <-->|Sphinx Packets| Mixnet +``` ## What don't I need (but is maybe nice to have)? -You **do not need to run any infrastructure to integrate Mixnet functionality** and can basically use the Mixnet as a black box if you want to. +You **do not need to run any infrastructure to integrate Mixnet functionality**. That said, if you are expecting a lot of traffic and perhaps don't want to rely on other people's Gateway infrastructure, you could run your own. However, this is something that is more in the 'nice to have'/'quality of service' category, and is not necessarily expected when starting to build on Nym. Furthermore, if our tokenomic incentives are working as they should, Gateway uptimes should be so good as to not require this regardless! ## What do I definitely not need? - To run a Mix Node. Defining which Mix Nodes you want to run traffic through is, although [technically possible](../rust/mixnet/examples/custom-topology), **only to be used in testing or research scenarios**; limiting the potential paths of your packets to a subset of the overall Mixnet topology is effectively reducing your anonymity set, and potentially leaking this subset through e.g. having the calculation logic open sourced is even worse. The best performing Mix Nodes are selected to route traffic per epoch, and will be used by your Nym clients when routing packets. - To run a Validator / NymAPI instance. +- `NYM` tokens: for the moment the Mixnet is free to use. Developers will have access to a Credential faucet once the [zk-nym](../../network/cryptography/zk-nym) scheme is enabled in mainnet.