From 8cf0b3adae73040014ab4a2b299b1df3fbb5aac8 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 1 Nov 2023 21:01:47 +0100 Subject: [PATCH] first draft of expanded rust stuff --- documentation/docs/src/SUMMARY.md | 2 + documentation/docs/src/sdk/rust/examples.md | 12 +- .../docs/src/sdk/rust/examples/cargo.md | 36 ++++++ .../docs/src/sdk/rust/examples/credential.md | 9 ++ .../src/sdk/rust/examples/custom-network.md | 18 +++ .../docs/src/sdk/rust/examples/keys.md | 28 +++++ .../docs/src/sdk/rust/examples/simple.md | 8 ++ .../docs/src/sdk/rust/examples/socks.md | 10 ++ .../docs/src/sdk/rust/examples/split-send.md | 6 + .../docs/src/sdk/rust/examples/storage.md | 6 + .../docs/src/sdk/rust/examples/surbs.md | 16 +++ .../docs/src/sdk/rust/message-types.md | 4 +- documentation/docs/src/sdk/rust/rust.md | 112 ------------------ 13 files changed, 151 insertions(+), 116 deletions(-) create mode 100644 documentation/docs/src/sdk/rust/examples/cargo.md create mode 100644 documentation/docs/src/sdk/rust/examples/credential.md create mode 100644 documentation/docs/src/sdk/rust/examples/custom-network.md create mode 100644 documentation/docs/src/sdk/rust/examples/keys.md create mode 100644 documentation/docs/src/sdk/rust/examples/simple.md create mode 100644 documentation/docs/src/sdk/rust/examples/socks.md create mode 100644 documentation/docs/src/sdk/rust/examples/split-send.md create mode 100644 documentation/docs/src/sdk/rust/examples/storage.md create mode 100644 documentation/docs/src/sdk/rust/examples/surbs.md diff --git a/documentation/docs/src/SUMMARY.md b/documentation/docs/src/SUMMARY.md index b9dd5a4191..24a625cfb2 100644 --- a/documentation/docs/src/SUMMARY.md +++ b/documentation/docs/src/SUMMARY.md @@ -37,10 +37,12 @@ - [Simple Send](sdk/rust/examples/simple.md) - [Create and Store Keys](sdk/rust/examples/keys.md) - [Manual Storage](sdk/rust/examples/storage.md) + - [Anonymous Replies](sdk/rust/examples/surbs.md) - [Use Custom Network Topology](sdk/rust/examples/custom-network.md) - [Socks Proxy](sdk/rust/examples/socks.md) - [Split Send and Receive](sdk/rust/examples/split-send.md) - [Testnet Bandwidth Cred](sdk/rust/examples/credential.md) + - [Example Cargo file](sdk/rust/examples/cargo.md) # Wallet - [Desktop Wallet](wallet/desktop-wallet.md) diff --git a/documentation/docs/src/sdk/rust/examples.md b/documentation/docs/src/sdk/rust/examples.md index 544f7fb418..e612a7d59d 100644 --- a/documentation/docs/src/sdk/rust/examples.md +++ b/documentation/docs/src/sdk/rust/examples.md @@ -1,2 +1,12 @@ # Examples -TODO split examples into subdirectory with their own individual files \ No newline at end of file + +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 +``` + +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. + +An example `Cargo.toml` file can be found in the examples folder. + diff --git a/documentation/docs/src/sdk/rust/examples/cargo.md b/documentation/docs/src/sdk/rust/examples/cargo.md new file mode 100644 index 0000000000..4c96e05fc5 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/cargo.md @@ -0,0 +1,36 @@ +# Example Cargo File +This file imports the basic requirements for running these pieces of example code, and can be used as the basis for your own cargo project. + +TODO versioning check +```toml +[package] +name = "your_app" +version = "x.y.z" +edition = "2021" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +# Async runtime +tokio = { version = "1.24.1", features = ["rt-multi-thread", "macros"] } +# Used for (de)serialising incoming and outgoing messages +serde = "1.0.152" +serde_json = "1.0.91" +# Nym clients, addressing, etc +nym-sdk = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } +nym-sphinx-addressing = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } +nym-bin-common = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } +nym-sphinx-anonymous-replies = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } +# Additional dependencies if you're interacting with Nyx or another Cosmos SDK blockchain +cosmrs = "=0.14.0" +nym-validator-client = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } + +# If you're building an app with a client and server / serivce this might be a useful structure for your repo +[[bin]] +name = "client" +path = "bin/client.rs" + +[[bin]] +name = "service" +path = "bin/service.rs" +``` \ No newline at end of file diff --git a/documentation/docs/src/sdk/rust/examples/credential.md b/documentation/docs/src/sdk/rust/examples/credential.md new file mode 100644 index 0000000000..d0fe29bbbd --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/credential.md @@ -0,0 +1,9 @@ +# Coconut credential generation +The following code shows how you can use the SDK to create and use a [credential](../../bandwidth-credentials.md) representing paid bandwidth on the Sandbox testnet. + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/bandwidth.rs}} +``` + +You can read more about Coconut credentials (also referred to as `zk-Nym`) [here](../../coconut.md). + diff --git a/documentation/docs/src/sdk/rust/examples/custom-network.md b/documentation/docs/src/sdk/rust/examples/custom-network.md new file mode 100644 index 0000000000..0ad226f953 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/custom-network.md @@ -0,0 +1,18 @@ +# 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) (`examples/custom_topology_provider.rs`). + +There are two ways to do this: + +## Import a custom Nym API endpoint +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): + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/custom_topology_provider.rs}} +``` + +## 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 simply overwrite the grabbed topology manually: + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/manually_overwrite_topology.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/examples/keys.md b/documentation/docs/src/sdk/rust/examples/keys.md new file mode 100644 index 0000000000..6e2f66d986 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/keys.md @@ -0,0 +1,28 @@ +# Key Creation and Use +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 (`examples/builder_with_storage`): + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/builder_with_storage.rs}} +``` + +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 +``` diff --git a/documentation/docs/src/sdk/rust/examples/simple.md b/documentation/docs/src/sdk/rust/examples/simple.md new file mode 100644 index 0000000000..b3d5f9d268 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/simple.md @@ -0,0 +1,8 @@ +# 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 (`examples/simple.rs`). + +Simply importing the `nym_sdk` crate into your project allows you to create a client and send traffic through the mixnet. + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/simple.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/examples/socks.md b/documentation/docs/src/sdk/rust/examples/socks.md new file mode 100644 index 0000000000..5e81780e2e --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/socks.md @@ -0,0 +1,10 @@ +# Socks Proxy +There is also the option to embed the [`socks5-client`](../../clients/socks5-client.md) into your app code (`examples/socks5.rs`): + +```admonish info +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. +``` + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/socks5.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/examples/split-send.md b/documentation/docs/src/sdk/rust/examples/split-send.md new file mode 100644 index 0000000000..32db90c17c --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/split-send.md @@ -0,0 +1,6 @@ +# 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: + +```rust, noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/examples/storage.md b/documentation/docs/src/sdk/rust/examples/storage.md new file mode 100644 index 0000000000..4d430f36ac --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/storage.md @@ -0,0 +1,6 @@ +# Manually Handled 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 the actions taken automatically above (`examples/manually_handle_keys_and_config.rs`) + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/manually_handle_storage.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/examples/surbs.md b/documentation/docs/src/sdk/rust/examples/surbs.md new file mode 100644 index 0000000000..013b2e82e4 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples/surbs.md @@ -0,0 +1,16 @@ +# 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. + +The number of SURBs is set [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/src/mixnet/client.rs#L33). + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/src/mixnet/client.rs:33}} +``` + +You can read more about how SURBs function under the hood [here](../../architecture/traffic-flow.md#private-replies-using-surbs). + +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: + +```rust,noplayground +{{#include ../../../../sdk/rust/nym-sdk/examples/surb-reply.rs}} +``` diff --git a/documentation/docs/src/sdk/rust/message-types.md b/documentation/docs/src/sdk/rust/message-types.md index 20d959b127..c5adf83377 100644 --- a/documentation/docs/src/sdk/rust/message-types.md +++ b/documentation/docs/src/sdk/rust/message-types.md @@ -1,7 +1,5 @@ # Message Types - -TODO expand! - +[//]: # (TODO expand! ) There are two methods for sending messages through the mixnet using your client: * `send_plain_message()` is the most simple: pass the recipient address and the message you wish to send as a string (this was previously `send_str()`). This is a nicer-to-use wrapper around `send_message()`. * `send_message()` allows you to also define the amount of SURBs to send along with your message (which is sent as bytes). diff --git a/documentation/docs/src/sdk/rust/rust.md b/documentation/docs/src/sdk/rust/rust.md index c593b3aa6e..2ce11c4ed3 100644 --- a/documentation/docs/src/sdk/rust/rust.md +++ b/documentation/docs/src/sdk/rust/rust.md @@ -29,116 +29,4 @@ nym-sdk = { git = "https://github.com/nymtech/nym" } ### Generate Crate Docs In order to generate the crate docs run `cargo doc --open` from `nym/sdk/rust/nym-sdk/` -## Websocket client examples -> All the codeblocks below 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. 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. - -### Simple example -Lets look at a very simple example of how you can import and use the websocket client in a piece of Rust code (`examples/simple.rs`): - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/simple.rs}} -``` - -Simply importing the `nym_sdk` crate into your project allows you to create a client and send traffic through the mixnet. - -### Creating and storing keypairs -The example above 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 (`examples/builder_with_storage`): - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/builder_with_storage.rs}} -``` - -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 -``` - -### Manually handling 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 the actions taken automatically above (`examples/manually_handle_keys_and_config.rs`) - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/manually_handle_storage.rs}} -``` - -### Anonymous replies with SURBs -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. - -The number of SURBs is set [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/src/mixnet/client.rs#L33). - - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/src/mixnet/client.rs:33}} -``` - -You can read more about how SURBs function under the hood [here](../../architecture/traffic-flow.md#private-replies-using-surbs). - -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: - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/surb-reply.rs}} -``` - -### 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) (`examples/custom_topology_provider.rs`). - -There are two ways to do this: - -#### Import a custom Nym API endpoint -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): - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/custom_topology_provider.rs}} -``` - -#### 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 simply overwrite the grabbed topology manually: - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/manually_overwrite_topology.rs}} -``` - -### 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: - -```rust, noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs}} -``` - -## Socks client example -There is also the option to embed the [`socks5-client`](../../clients/socks5-client.md) into your app code (`examples/socks5.rs`): - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/socks5.rs}} -``` - -```admonish info -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. -``` - -## Coconut credential generation -The following code shows how you can use the SDK to create and use a [credential](../../bandwidth-credentials.md) representing paid bandwidth on the Sandbox testnet. - -```rust,noplayground -{{#include ../../../../sdk/rust/nym-sdk/examples/bandwidth.rs}} -``` - -You can read more about Coconut credentials (also referred to as `zk-Nym`) [here](../../coconut.md). -