diff --git a/documentation/docs/pages/developers/clients.mdx b/documentation/docs/pages/developers/clients.mdx index 10de771993..5b5dbca17f 100644 --- a/documentation/docs/pages/developers/clients.mdx +++ b/documentation/docs/pages/developers/clients.mdx @@ -1,9 +1,9 @@ # 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 +- the websocket (native) client - most easily accessed via the [Rust SDK](./rust) and [Go/C++ FFI](./rust/ffi). +- the SOCKS5 client - most easily accessed via the [Rust SDK](./rust) and [Go/C++ FFI](./rust/ffi). +- the wasm (webassembly) client - most easily via the [Typescript SDK](./typescript). > 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). diff --git a/documentation/docs/pages/developers/clients/socks5.mdx b/documentation/docs/pages/developers/clients/socks5.mdx index 6c3efa8c35..36e822b61c 100644 --- a/documentation/docs/pages/developers/clients/socks5.mdx +++ b/documentation/docs/pages/developers/clients/socks5.mdx @@ -90,9 +90,9 @@ Before you can use the client, you need to initalise a new instance of it, which 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 `--use-reply-surbs` field denotes whether you wish to send [SURBs](../../network/concepts/anonymous-replies) along with your request. It defaults to `false`, we are explicitly setting it as `true`. It defaults to `false` for compatibility with versions of the pre-smoosh `nym-network-requester` binary which will soon be deprecated. -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/). +The `--provider` field needs to be filled with the Nym address of an Exit Gateway that can make network requests on your behalf. You can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/). #### Choosing a Gateway By default - as in the example above - your client will choose a random gateway to connect to. @@ -104,6 +104,8 @@ However, there are several options for choosing a gateway, if you do not want on * 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. +You can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/). + > 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 diff --git a/documentation/docs/pages/developers/clients/webassembly-client.mdx b/documentation/docs/pages/developers/clients/webassembly-client.mdx index a98a882885..71276ef8c1 100644 --- a/documentation/docs/pages/developers/clients/webassembly-client.mdx +++ b/documentation/docs/pages/developers/clients/webassembly-client.mdx @@ -2,7 +2,7 @@ The Nym webassembly client allows any webassembly-capable runtime to build and send Sphinx packets to the Nym network, for uses in edge computing and browser-based applications. -This is currently packaged and distributed for ease of use via the [Nym Typescript SDK library](../sdk/typescript.md). **We imagine most developers will use this client via the SDK for ease.** +This is currently packaged and distributed for ease of use via the [Nym Typescript SDK library](../typescript). **We imagine most developers will use this client via the SDK for ease.** The webassembly client allows for the easy creation of Sphinx packets from within mobile apps and browser-based client-side apps (including Electron or similar). diff --git a/documentation/docs/pages/developers/clients/websocket/setup.md b/documentation/docs/pages/developers/clients/websocket/setup.md index 39503c771f..4c780bc76a 100644 --- a/documentation/docs/pages/developers/clients/websocket/setup.md +++ b/documentation/docs/pages/developers/clients/websocket/setup.md @@ -31,7 +31,7 @@ Initialising a new client instance can be done with the following command: The `--id` in the example above is a local identifier so that you can name your clients; it is **never** transmitted over the network. -There is an optional `--gateway` flag that you can use if you want to use a specific gateway. The supplied argument is the `Identity Key` of the gateway you wish to use, which can be found on the [mainnet Network Explorer](https://explorer.nymtech.net/network-components/gateways) or [Sandbox Testnet Explorer](https://sandbox-explorer.nymtech.net/network-components/gateways) depending on which network you are on. +There is an optional `--gateway` flag that you can use if you want to use a specific gateway. The supplied argument is the `Identity Key` of the gateway you wish to use, which can be found on the [mixnet explorer](https://explorer.nymtech.net/network-components/). Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/) Not passing this argument will randomly select a gateway for your client. diff --git a/documentation/docs/pages/developers/clients/websocket/usage.md b/documentation/docs/pages/developers/clients/websocket/usage.md index 5af5cc1dbd..c258d45abb 100644 --- a/documentation/docs/pages/developers/clients/websocket/usage.md +++ b/documentation/docs/pages/developers/clients/websocket/usage.md @@ -54,7 +54,7 @@ In some applications, e.g. where people are chatting with friends who they know, **If that fits your security model, good. However, will probably be the case that you want to send anonymous replies using Single Use Reply Blocks (SURBs)**. -You can read more about SURBs [here](https://nymtech.net/docs/architecture/traffic-flow.html#private-replies-using-surbs) but in short they are ways for the receiver of this message to anonymously reply to you - the sender - **without them having to know your client address**. +You can read more about SURBs [here](../../network/concepts/anonymous-replies) but in short they are ways for the receiver of this message to anonymously reply to you - the sender - **without them having to know your client address**. Your client will send along a number of `replySurbs` to the recipient of the message. These are pre-addressed Sphinx packets that the recipient can write to the payload of (i.e. write response data to), but not view the final destination of. If the recipient is unable to fit the response data into the bucket of SURBs sent to it, it will use a SURB to request more SURBs be sent to it from your client. @@ -103,7 +103,7 @@ Errors from the app's client, or from the gateway, will be sent down the websock ``` ### LaneQueueLength -This is currently only used in the [Socks Client](../socks5-client.md) to keep track of the number of Sphinx packets waiting to be sent to the mixnet via being slotted amongst cover traffic. As this value becomes larger, the client signals to the application it should slow down the speed with which it writes to the proxy. This is to stop situations arising whereby an app connected to the client appears as if it has sent (e.g.) a bunch of messages and is awaiting a reply, when they in fact have not been sent through the mixnet yet. +This is currently only used in the [Socks Client](../socks5) to keep track of the number of Sphinx packets waiting to be sent to the mixnet via being slotted amongst cover traffic. As this value becomes larger, the client signals to the application it should slow down the speed with which it writes to the proxy. This is to stop situations arising whereby an app connected to the client appears as if it has sent (e.g.) a bunch of messages and is awaiting a reply, when they in fact have not been sent through the mixnet yet. ## Message Responses Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/master/clients/native/websocket-requests/src/responses.rs#L47): diff --git a/documentation/docs/pages/developers/concepts/credentials.mdx b/documentation/docs/pages/developers/concepts/credentials.mdx index 59bf32b615..c44dc8078e 100644 --- a/documentation/docs/pages/developers/concepts/credentials.mdx +++ b/documentation/docs/pages/developers/concepts/credentials.mdx @@ -8,8 +8,8 @@ Right now we are still working on the specifics of how credentials will work for -Once the [zk-nym]() credential system is turned on, all Nym clients will have to present a valid credential to their Gateway on connection. +Once the [zk-nym](../../network/cryptography/zk-nym) credential system is turned on, all Nym clients will have to present a valid credential to their Gateway on connection. We plan to supply developers with a credential faucet for their applications, and a pay-per-play backend for large existing applications that wish to integrate and supply their users' with credentials under the hood. -> Remember, due to the [rerandomisation]() properties of the zk-nym scheme, that an application supplies a user with a credential in no way affects any privacy properties: the user will always present unlinkable rerandomised credential data to whatever Gateway their app instance connects to! +> Remember, due to the [rerandomisation](../../network/cryptography/zk-nym/rerandomise) properties of the zk-nym scheme, that an application supplies a user with a credential in no way affects any privacy properties: the user will always present unlinkable rerandomised credential data to whatever Gateway their app instance connects to! diff --git a/documentation/docs/pages/developers/concepts/message-queue.md b/documentation/docs/pages/developers/concepts/message-queue.md index aca97ee392..54c8ceb035 100644 --- a/documentation/docs/pages/developers/concepts/message-queue.md +++ b/documentation/docs/pages/developers/concepts/message-queue.md @@ -1,9 +1,11 @@ # Message Queue -One thing to remember is that clients, once connected to the Mixnet, **are always sending traffic into the Mixnet**; as well as the packets that you as a developer are sending from your application logic, they send [cover traffic]() at a constant rate defined by a Poisson process. This is part of the network's mitigation of timing attacks. +One thing to remember is that clients, once connected to the Mixnet, **are always sending traffic into the Mixnet**; as well as the packets that you as a developer are sending from your application logic, they send [cover traffic](../../network/concepts/cover-traffic) at a constant rate defined by a Poisson process. This is part of the network's mitigation of timing attacks. As such, you need to be careful to keep the process managing your clients alive / running, since when passing a message to a client (however you do it, either piping messages from an app to a standalone client or via one of the `send` functions exposed by the SDKs), you are **putting that message into the queue** to be source encrypted and sent in the future, in order to ensure that traffic leaving the client does so in a manner that to an external observer is uniform / does not create any 'burst' or change in traffic timings that could aid traffic analysis. -Accidentally dropping a client before your message has been sent is something that is possible and should be avoided (see the troubleshooting example TODO LINK for more on this) but is easy to avoid simply by remembering to: +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 a0acfa86a8..dbe01e1ae4 100644 --- a/documentation/docs/pages/developers/concepts/messages.mdx +++ b/documentation/docs/pages/developers/concepts/messages.mdx @@ -20,16 +20,16 @@ ReconstructedMessage { ``` Examples for: -- [Standalone Websocket Client]() TODO LINKS ON ALL -- [Rust SDK Client]() -- [TS SDK Client]() +- [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](./abstractions). -- Developers who are using Typescript/Javascript can also avoid having to deal directly with messages via using [MixFetch]() TODO LINK... -- ... As can developers who are bundling and running the standalone [socks5 client]() using some form of init script. -- There will be a seperate pair of binaries coming soon which other developers can use to run as a persistent secondary proxy process based on the [zcash gRPC demo]() codebase, built using the `TcpProxy` abstraction. These will simply expose a `localhost` socket port to pipe traffic to and from in the same way as you would a TCP connection. +- 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). +- As can developers who are bundling and running the standalone [socks5 client](../clients/socks5) using some form of init script. +- There will be a seperate pair of binaries coming soon which other developers can use to run as a persistent secondary proxy process based on the [zcash gRPC demo](https://github.com/nymtech/nym-zcash-grpc-demo) codebase, built using the `TcpProxy` abstraction. These will simply expose a `localhost` socket port to pipe traffic to and from in the same way as you would a TCP connection. diff --git a/documentation/docs/pages/developers/concepts/required-architecture.md b/documentation/docs/pages/developers/concepts/required-architecture.md index 754f84e936..7154e986eb 100644 --- a/documentation/docs/pages/developers/concepts/required-architecture.md +++ b/documentation/docs/pages/developers/concepts/required-architecture.md @@ -4,8 +4,8 @@ Due to the fact that there are a lot of components that make up the Nym network ## What do I need? Nym clients on 'both sides' of the Mixnet. -- traditional client / server application setups involve having a Nym client on the local 'client' machine, as well as on the 'server' backend your local app/process wants to remotely communicate with. We need to put the Mixnet betwen them to gain the privacy properties as we need our local app to pipe its traffic to its local Nym client and have this traffic encrypted and slotted into the message queue for sending, and our server code to have a Nym client listening out for incoming messages to decrypt, reconstruct, and pass upstream to the server process. The server-side Nym client can then [anonymously reply]() TODO LINK via SURBs to the client-app. -- P2P app setups may differ only insofar as that they probably shouldn't rely on [ephemeral clients]() TODO LINK as they will likely need a persistent Nym address - otherwise the logic is the same as client/server apps. +- traditional client / server application setups involve having a Nym client on the local 'client' machine, as well as on the 'server' backend your local app/process wants to remotely communicate with. We need to put the Mixnet betwen them to gain the privacy properties as we need our local app to pipe its traffic to its local Nym client and have this traffic encrypted and slotted into the message queue for sending, and our server code to have a Nym client listening out for incoming messages to decrypt, reconstruct, and pass upstream to the server process. The server-side Nym client can then [anonymously reply via SURBs](../../network/traffic/anonymous-replies) to the client-app. +- P2P app setups may differ only insofar as that they probably shouldn't rely on [ephemeral clients](../rust/mixnet/examples/simple) as they will likely need a persistent Nym address - otherwise the logic is the same as client/server apps. > We haven't yet tried to integrate a fully P2P application using anonymous replies: reach out if you are trying / have ideas! @@ -19,5 +19,5 @@ 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]() TODO LINK TO CUSTOM TOPOLOGY SDK EXAMPLE, **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 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. diff --git a/documentation/docs/pages/developers/integrations.mdx b/documentation/docs/pages/developers/integrations.mdx index 1468925320..c4419807cd 100644 --- a/documentation/docs/pages/developers/integrations.mdx +++ b/documentation/docs/pages/developers/integrations.mdx @@ -13,11 +13,11 @@ There are several options available to developers wanting to embed a Nym client <> 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. + - [`mixfetch`](./typescript/examples/mix-fetch) 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. - - 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 + - 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](./typescript/overview). @@ -25,15 +25,15 @@ There are several options available to developers wanting to embed a Nym client <> 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. + 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](./rust). - 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 + 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. ### 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. +If instead of relying on the Mixnet you wish to interact with the Nyx chain, either as a payment processor or to get on-chain events, see [interacting with the chain](./chain). > 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.