rework of structure of developers
This commit is contained in:
mfahampshire
@@ -1,7 +1,9 @@
|
||||
{
|
||||
"concepts": "Core Concepts",
|
||||
"integrations": "Integrations",
|
||||
"clients": "Clients",
|
||||
"tools": "Tools",
|
||||
"tutorials": "Tutorials (Coming Soon)",
|
||||
"---": {
|
||||
"type": "separator"
|
||||
},
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Types of Nym clients
|
||||
At present, there are three Nym clients:
|
||||
|
||||
- the websocket (native) client
|
||||
- the SOCKS5 client
|
||||
- the wasm (webassembly) client
|
||||
|
||||
You need to choose which one you want incorporate into your app. Which one you use will depend largely on your preferred programming style and the purpose of your app.
|
||||
|
||||
### The websocket client
|
||||
Your first option is the native websocket client (`nym-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**.
|
||||
|
||||
> Rust developers can import websocket client functionality into their code via the [Rust SDK](../sdk/rust/rust.md).
|
||||
|
||||
### 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 webassembly client is most easily used via the [Typescript SDK](../sdk/typescript.md). Typescript developers who wish to send API requests through the mixnet can can also check the [`mixfetch`]() package.
|
||||
|
||||
### 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.
|
||||
|
||||
_Rust developers can import socks client functionality into their code via the [Rust SDK](../sdk/rust/rust.md)_.
|
||||
@@ -0,0 +1,210 @@
|
||||
# Socks5 Client
|
||||
|
||||
> 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
|
||||
```
|
||||
<!-- 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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Setup
|
||||
|
||||
> `nym-socks5-client` now also supports SOCKS4 and SOCKS4A protocols as well as SOCKS5.
|
||||
|
||||
The Nym socks5 client allows you to proxy traffic from a desktop application through the mixnet, meaning you can send and receive information from remote application servers without leaking metadata which can be used to deanonymise you, even if you're using an encrypted application such as Signal.
|
||||
|
||||
```admonish info
|
||||
Since the beginning of 2024 NymConnect is no longer maintained. Nym is developing a new client called [NymVPN](https://nymvpn.com), an application routing all users traffic thorugh the mixnet.
|
||||
If users want to route their traffic through socks5 we advice to use this client. If you want to run deprecated NymConnect, visit [NymConnect archive page](../../archive/nym-connect.md) with setup and application examples.
|
||||
```
|
||||
|
||||
## Setup and Run
|
||||
|
||||
### Download or compile socks5 client
|
||||
|
||||
If you are using OSX or a Debian-based operating system, you can download the `nym-socks5-client` binary from our [Github releases page](https://github.com/nymtech/nym/releases).
|
||||
|
||||
If you are using a different operating system, head over to the [Building from Source](https://nymtech.net/docs/binaries/building-nym.html) page for instructions on how to build the repository from source.
|
||||
|
||||
### Initialise your socks5 client
|
||||
|
||||
To initialise your `nym-socks5-client` you need to have an address of a Network Requester (NR). Nowadays NR is part of every Exit Gateway (`nym-node --mode exit-gateway`). The easiest way to get a NR address is to visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/) and scroll down to *SOCKS5 Network Requesters* table. There you can filter the NR by Gateways identity address, and other options.
|
||||
|
||||
Use the following command to initialise `nym-socs5-client` where `<ID>` can be anything you want (it's only for local config file storage) and `<PROVIDER>` is suplemented with a NR address:
|
||||
|
||||
```
|
||||
./nym-socks5-client init --id <ID> --provider <PROVIDER>
|
||||
```
|
||||
|
||||
~~~admonish tip
|
||||
Another option to find a NR address associated with a Gateway is to query nodes [*Self Described* API endpoint](https://validator.nymtech.net/api/v1/gateways/described) where the NR address is noted like in this example:
|
||||
```sh
|
||||
"network_requester": {
|
||||
"address": "CyuN49nkyeuiLohSpV5A1MbSqcugHLJQ95B5HooCpjv8.CguTh45Vp99QuGWZRBKpBjZDQbsJaHaXqAMGyc4Qhkzp@2w5RduXRqxKgHt1wtp4qGA4AfXaBj8TuUj1LvcPe2Ea1",
|
||||
"uses_exit_policy": true
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
### Start your socks5 client
|
||||
Now your client is initialised, start it with the following:
|
||||
|
||||
```
|
||||
./nym-socks5-client run --id <ID>
|
||||
```
|
||||
@@ -0,0 +1,33 @@
|
||||
# Using Your Client
|
||||
|
||||
## Proxying traffic
|
||||
After completing the steps above, your local `nym-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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## Supported Applications
|
||||
|
||||
Any application which can be redirected over Socks5 proxy should work. Nym community has been successfully running over Nym Mixnet these applications:
|
||||
|
||||
- Bitcoin Electrum wallet
|
||||
- Monero wallet (GUI and CLI with monerod)
|
||||
- Telegram chat
|
||||
- Element/Matrix chat
|
||||
- Firo wallet
|
||||
- Blockstream Green
|
||||
|
||||
> DarkFi's ircd chat was previously supported: they have moved to DarkIrc: whether the existing integration work is still operational needs to be tested.
|
||||
|
||||
Keep in mind that Nym has been developing a new client **[NymVPN](https://nymvpn.com) (GUI and CLI) routing all users traffic through the Mixnet.**
|
||||
|
||||
## Further reading
|
||||
|
||||
If you want to dig more into the architecture and use of the socks5 client check out its documentation [here](https://nymtech.net/docs/clients/socks5-client.html).
|
||||
@@ -0,0 +1,22 @@
|
||||
# Webassembly Client
|
||||
|
||||
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.**
|
||||
|
||||
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).
|
||||
|
||||
## Building apps with Webassembly Client
|
||||
|
||||
Check out the [Typescript SDK docs](https://sdk.nymtech.net) for examples of usage.
|
||||
|
||||
There are also example applications located in the `clients/webassembly` directory in the main Nym platform codebase.
|
||||
|
||||
## Think about what you're sending!
|
||||
```admonish caution
|
||||
Think about what information your app sends. That goes for whatever you put into your Sphinx packet messages as well as what your app's environment may leak.
|
||||
```
|
||||
|
||||
Whenever you write client PEAPPs using HTML/JavaScript, we recommend that you do not load external resources from CDNs. Webapp developers do this all the time, to save load time for common resources, or just for convenience. But when you're writing privacy apps it's better not to make these kinds of requests. Pack everything locally.
|
||||
|
||||
If you use only local resources within your Electron app or your browser extensions, explicitly encoding request data in a Sphinx packet does protect you from the normal leakage that gets sent in a browser HTTP request. [There's a lot of stuff that leaks when you make an HTTP request from a browser window](https://panopticlick.eff.org/). Luckily, all that metadata and request leakage doesn't happen in Nym, because you're choosing very explicitly what to encode into Sphinx packets, instead of sending a whole browser environment by default.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Websocket Client
|
||||
|
||||
> The Nym Websocket 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
|
||||
```
|
||||
<!-- cmdrun ../../../../target/release/nym-client --version | grep "Build Version" | cut -b 21-26 -->
|
||||
```
|
||||
|
||||
You can run this client as a standalone process and pipe traffic into it to be sent through the mixnet. This is useful if you're building an application in a language other than Typescript or Rust and cannot utilise one of the SDKs.
|
||||
|
||||
You can find the code for this client [here](https://github.com/nymtech/nym/tree/develop/clients/native).
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# Configuration
|
||||
|
||||
## Default listening port
|
||||
The Nym native client exposes a websocket interface that your code connects to. To program your app, choose a websocket library for whatever language you're using. The **default** websocket port is `1977`, you can override that in the client config if you want.
|
||||
|
||||
You can either set this via the `--port` flag at `init` or `run`, or you can manually edit `~/.nym/clients/<CLIENT-ID>/config/config.toml`.
|
||||
|
||||
> Remember to restart your client if you change your listening port via editing your config file.
|
||||
|
||||
## Choosing a Gateway
|
||||
By default 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-routing` flag to your `init` command. This command means that to select a gateway, your client will:
|
||||
* fetch a list of all available 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/clients/<client-name>/`.
|
||||
|
||||
```
|
||||
tree $HOME/<user>/.nym/clients/example-client
|
||||
├── config
|
||||
│ └── config.toml
|
||||
└── data
|
||||
├── ack_key.pem
|
||||
├── gateway_shared.pem
|
||||
├── 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.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Examples
|
||||
The Nym monorepo includes websocket client example code for Rust, Go, Javacript, and Python, all of which can be found [here](https://github.com/nymtech/nym/tree/master/clients/native/examples).
|
||||
|
||||
> Rust users can run the examples with `cargo run --example <rust_file>.rs`, as the examples are not organised in the same way as the other examples, due to already being inside a Cargo project.
|
||||
|
||||
All of these code examples will do the following:
|
||||
* connect to a running websocket client on port `1977`
|
||||
* format a message to send in either JSON or Binary format. Nym messages have defined JSON formats.
|
||||
* send the message into the websocket. The native client packages the message into a Sphinx packet and sends it to the mixnet
|
||||
* wait for confirmation that the message hit the native client
|
||||
* wait to receive messages from other Nym apps
|
||||
|
||||
By varying the message content, you can easily build sophisticated service provider apps. For example, instead of printing the response received from the mixnet, your service provider might take some action on behalf of the user - perhaps initiating a network request, a blockchain transaction, or writing to a local data store.
|
||||
|
||||
<!-- THIS PAGE IS NOT WORKING AT THE MOMENT:
|
||||
> You can find an example of building both frontend and service provider code with the websocket client in the [Simple Service Provider Tutorial](https://nymtech.net/developers/tutorials/simple-service-provider/simple-service-provider.html) in the Developer Portal.
|
||||
-->
|
||||
@@ -0,0 +1,59 @@
|
||||
# Setup & Run
|
||||
|
||||
## Viewing command help
|
||||
|
||||
You can check that your binaries are properly compiled with:
|
||||
|
||||
```
|
||||
./nym-client --help
|
||||
```
|
||||
|
||||
~~~admonish example collapsible=true title="Console output"
|
||||
```
|
||||
<!-- cmdrun ../../../../../target/release/nym-client --help -->
|
||||
```
|
||||
~~~
|
||||
|
||||
The two most important commands you will issue to the client are:
|
||||
|
||||
* `init` - initalise a new client instance.
|
||||
* `run` - run a mixnet client process.
|
||||
|
||||
You can check the necessary parameters for the available commands by running:
|
||||
|
||||
```
|
||||
./nym-client <command> --help
|
||||
```
|
||||
|
||||
## Initialising your client
|
||||
|
||||
Before you can use the client, you need to initalise a new instance of it. Each instance of the client has its own public/private keypair, and connects to its own gateway node. Taken together, these 3 things (public/private keypair + gateway node identity key) make up an app's identity.
|
||||
|
||||
Initialising a new client instance can be done with the following command:
|
||||
|
||||
```
|
||||
./nym-client init --id example-client
|
||||
```
|
||||
|
||||
~~~admonish example collapsible=true title="Console output"
|
||||
```
|
||||
<!-- cmdrun ../../../../../target/release/nym-client init --id example-client -->
|
||||
```
|
||||
~~~
|
||||
|
||||
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.
|
||||
|
||||
Not passing this argument will randomly select a gateway for your client.
|
||||
|
||||
## Running your client
|
||||
You can run the initalised client by doing this:
|
||||
|
||||
```
|
||||
./nym-client run --id example-client
|
||||
```
|
||||
|
||||
When you run the client, it immediately starts generating (fake) cover traffic and sending it to the mixnet.
|
||||
|
||||
When the client is first started, it will reach out to the Nym network's validators, and get a list of available Nym nodes (gateways, mixnodes, and validators). We call this list of nodes the network _topology_. The client does this so that it knows how to connect, register itself with the network, and know which mixnodes it can route Sphinx packets through.
|
||||
@@ -0,0 +1,117 @@
|
||||
# Using Your Client
|
||||
The Nym native client exposes a websocket interface that your code connects to. The **default** websocket port is `1977`, you can override that in the client config if you want.
|
||||
|
||||
Once you have a websocket connection, interacting with the client involves piping messages down the socket and listening for incoming messages.
|
||||
|
||||
# Message Requests
|
||||
There are a number of message types that you can send up the websocket as defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs):
|
||||
|
||||
```rust,noplayground
|
||||
{{#include ../../../../../clients/native/websocket-requests/src/requests.rs:55:97}}
|
||||
```
|
||||
|
||||
## Getting your own address
|
||||
When you start your app, it is best practice to ask the native client to tell you what your own address is (from the generated configuration files <!--add link -->. If you are running a service, you need to do this in order to know what address to give others. In a client-side piece of code you can also use this as a test to make sure your websocket connection is running smoothly. To do this, send:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "selfAddress"
|
||||
}
|
||||
```
|
||||
|
||||
You'll receive a response of the format:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "selfAddress",
|
||||
"address": "your address" // e.g. "71od3ZAupdCdxeFNg8sdonqfZTnZZy1E86WYKEjxD4kj@FWYoUrnKuXryysptnCZgUYRTauHq4FnEFu2QGn5LZWbm"
|
||||
}
|
||||
```
|
||||
|
||||
See [here](https://github.com/nymtech/nym/blob/93cc281abc2cc951023b51746fa6f2ead1f56c46/clients/native/examples/python-examples/websocket/textsend.py#L16C9-L16C9) for an example of this being used.
|
||||
|
||||
> Note that all the pieces of native client example code begin with printing the selfAddress. Examples exist for Rust, Go, Javascript, and Python.
|
||||
|
||||
## Sending text
|
||||
If you want to send text information through the mixnet, format a message like this one and poke it into the websocket:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "send",
|
||||
"message": "the message",
|
||||
"recipient": "71od3ZAupdCdxeFNg8sdonqfZTnZZy1E86WYKEjxD4kj@FWYoUrnKuXryysptnCZgUYRTauHq4FnEFu2QGn5LZWbm"
|
||||
}
|
||||
```
|
||||
|
||||
In some applications, e.g. where people are chatting with friends who they know, you might want to include unencrypted reply information in the message field. This provides an easy way for the receiving chat to then turn around and send a reply message:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "send",
|
||||
"message": {
|
||||
"sender": "198427b63ZAupdCdxeFNg8sdonqfZTnZZy1E86WYKEjxD4kj@FWYoUrnKuXryysptnCZgUYRTauHq4FnEFu2QGn5LZWbm",
|
||||
"chatMessage": "hi julia!"
|
||||
},
|
||||
"recipient": "71od3ZAupdCdxeFNg8sdonqfZTnZZy1E86WYKEjxD4kj@FWYoUrnKuXryysptnCZgUYRTauHq4FnEFu2QGn5LZWbm"
|
||||
}
|
||||
```
|
||||
|
||||
**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**.
|
||||
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "sendAnonymous",
|
||||
"message": "something you want to keep secret",
|
||||
"recipient": "71od3ZAupdCdxeFNg8sdonqfZTnZZy1E86WYKEjxD4kj@FWYoUrnKuXryysptnCZgUYRTauHq4FnEFu2QGn5LZWbm",
|
||||
"replySurbs": 20 // however many reply SURBs to send along with your message
|
||||
}
|
||||
```
|
||||
|
||||
See ['Replying to SURB Messages'](#replying-to-surb-messages) below for an example of how to deal with incoming messages that have SURBs attached.
|
||||
|
||||
Deciding on the amount of SURBs to generate and send along with outgoing messages depends on the expected size of the reply. You might want to send a lot of SURBs in order to make sure you get your response as quickly as possible (but accept the minor additional latency when sending, as your client has to generate and encrypt the packets), or you might just send a few (e.g. 20) and then if your response requires more SURBs, send them along, accepting the additional latency in getting your response.
|
||||
|
||||
## Sending binary data
|
||||
You can also send bytes instead of JSON. For that you have to send a binary websocket frame containing a binary encoded
|
||||
Nym [`ClientRequest`](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs#L25) containing the same information.
|
||||
|
||||
> As a response the `native-client` will send a `ServerResponse` to be decoded. See [Message Responses](#message-responses) below for more.
|
||||
|
||||
You can find examples of sending and receiving binary data in the [code examples](https://github.com/nymtech/nym/tree/master/clients/native/examples), and an example project from the Nym community [BTC-BC](https://github.com/sgeisler/btcbc-rs/): Bitcoin transaction transmission via Nym, a client and service provider written in Rust.
|
||||
|
||||
## Replying to SURB messages
|
||||
Each bucket of `replySURBs`, when received as part of an incoming message, has a unique session identifier, which **only identifies the bucket of pre-addressed packets**. This is necessary to make sure that your app is replying to the correct people with the information meant for them in a situation where multiple clients are sending requests to a single service.
|
||||
|
||||
Constructing a reply with SURBs looks something like this (where `senderTag` was parsed from the incoming message)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "reply",
|
||||
"message": "reply you also want to keep secret",
|
||||
"senderTag": "the sender tag you parsed from the incoming message"
|
||||
}
|
||||
```
|
||||
|
||||
## Error messages
|
||||
Errors from the app's client, or from the gateway, will be sent down the websocket to your code in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"message": "string message"
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
# Message Responses
|
||||
Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/responses.rs):
|
||||
|
||||
```rust,noplayground
|
||||
{{#include ../../../../../clients/native/websocket-requests/src/responses.rs:48:53}}
|
||||
```
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"overview": "Overview",
|
||||
"required-architecture": "Required Architecture",
|
||||
"messages": "Message Based Paradigm",
|
||||
"abstractions": "Connection Abstractions"
|
||||
}
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
stub
|
||||
Reference in New Issue
Block a user