From 50e03d08bf09657cf4e1346e482a529ce9b990bc Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 13:18:32 +0200 Subject: [PATCH 01/32] added info on post_process.sh --- documentation/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index 59c5e32133..3defd29526 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -9,5 +9,4 @@ Each directory contains a readme with more information about running and contrib ## Scripts * `bump_versions.sh` allows you to update the ~~`platform_release_version` and~~ `wallet_release_version` variable~~s~~ in the `book.toml` of each mdbook project at once. You can also optionally update the `minimum_rust_version` as well. Helpful for lazy-updating when cutting a new version of the docs. * `build_all_to_dist.sh` is used by the `ci-dev.yml` and `cd-dev.yml` scripts for building all mdbook projects and moving the rendered html to `../dist/` to be rsynced with various servers. - - +* `post_process.sh` is a script called by the github CI and CD workflows to post process CSS/image/href links for serving several mdbooks from a subdirectory. From 2806931ca17198f9f3143f61a35e1eff6053f79c Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:50:03 +0200 Subject: [PATCH 02/32] added new pages --- documentation/dev-portal/book.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/dev-portal/book.toml b/documentation/dev-portal/book.toml index d0dfbe0674..1012ec22f9 100644 --- a/documentation/dev-portal/book.toml +++ b/documentation/dev-portal/book.toml @@ -43,7 +43,7 @@ turn-off = true [preprocessor.admonish] command = "mdbook-admonish" -assets_version = "3.0.0" # do not edit: managed by `mdbook-admonish install` +assets_version = "2.0.1" # do not edit: managed by `mdbook-admonish install` # variables preprocessor: import variables into files # https://gitlab.com/tglman/mdbook-variables/ From 0e1548db72f019d076682d45b3a5f3e36e4973d5 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:50:24 +0200 Subject: [PATCH 03/32] added new pages to summary --- documentation/dev-portal/src/SUMMARY.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md index 5dcbd3ba70..7c9836c58a 100644 --- a/documentation/dev-portal/src/SUMMARY.md +++ b/documentation/dev-portal/src/SUMMARY.md @@ -22,6 +22,13 @@ - [NymConnect Matrix](tutorials/matrix.md) - [NymConnect Telegram](tutorials/telegram.md) +# Code Examples + +- [Rust](examples/rust.md) +- [Typescript](examples/typescript.md) +- [Nym Demos](examples/demos.md) +- [Community Apps](examples/community-apps.md) + # Integrations - [Integration Options](integrations/integration-options.md) @@ -41,7 +48,7 @@ - [Preparing Your Service pt2](tutorials/cosmos-service/service-src.md) - [Querying the Chain](tutorials/cosmos-service/querying.md) - [Typescript](tutorials/typescript.md) - - [Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) + - [[DEPRECATED] Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) - [Tutorial Overview](tutorials/simple-service-provider/overview.md) - [Preparing Your User Client Environment](tutorials/simple-service-provider/preparating-env.md) - [Building Your User Client](tutorials/simple-service-provider/user-client.md) From 7b3a8d5bcd34d01aae9a6bc6b27632b448af74a0 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:50:40 +0200 Subject: [PATCH 04/32] added new examples pages --- documentation/dev-portal/src/examples/community-apps.md | 1 + documentation/dev-portal/src/examples/demos.md | 1 + documentation/dev-portal/src/examples/rust.md | 1 + documentation/dev-portal/src/examples/typescript.md | 1 + 4 files changed, 4 insertions(+) create mode 100644 documentation/dev-portal/src/examples/community-apps.md create mode 100644 documentation/dev-portal/src/examples/demos.md create mode 100644 documentation/dev-portal/src/examples/rust.md create mode 100644 documentation/dev-portal/src/examples/typescript.md diff --git a/documentation/dev-portal/src/examples/community-apps.md b/documentation/dev-portal/src/examples/community-apps.md new file mode 100644 index 0000000000..b6c3fda9c6 --- /dev/null +++ b/documentation/dev-portal/src/examples/community-apps.md @@ -0,0 +1 @@ +# Community Apps diff --git a/documentation/dev-portal/src/examples/demos.md b/documentation/dev-portal/src/examples/demos.md new file mode 100644 index 0000000000..ddcf4dd8c4 --- /dev/null +++ b/documentation/dev-portal/src/examples/demos.md @@ -0,0 +1 @@ +# Nym Demos diff --git a/documentation/dev-portal/src/examples/rust.md b/documentation/dev-portal/src/examples/rust.md new file mode 100644 index 0000000000..2f1d5efed1 --- /dev/null +++ b/documentation/dev-portal/src/examples/rust.md @@ -0,0 +1 @@ +# Rust diff --git a/documentation/dev-portal/src/examples/typescript.md b/documentation/dev-portal/src/examples/typescript.md new file mode 100644 index 0000000000..42c9775801 --- /dev/null +++ b/documentation/dev-portal/src/examples/typescript.md @@ -0,0 +1 @@ +# Typescript From bd10b17272400e80638dce5946986c1ac3952857 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:50:53 +0200 Subject: [PATCH 05/32] update plugin --- documentation/dev-portal/mdbook-admonish.css | 172 ++++++++++--------- 1 file changed, 92 insertions(+), 80 deletions(-) diff --git a/documentation/dev-portal/mdbook-admonish.css b/documentation/dev-portal/mdbook-admonish.css index e0a3365532..244bc9ade7 100644 --- a/documentation/dev-portal/mdbook-admonish.css +++ b/documentation/dev-portal/mdbook-admonish.css @@ -1,18 +1,31 @@ @charset "UTF-8"; :root { - --md-admonition-icon--admonish-note: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-abstract: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-info: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-tip: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-success: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-question: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-warning: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-failure: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-danger: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-bug: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-example: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-quote: url("data:image/svg+xml;charset=utf-8,"); - --md-details-icon: url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--note: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--abstract: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--info: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--tip: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--success: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--question: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--warning: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--failure: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--danger: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--bug: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--example: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--quote: + url("data:image/svg+xml;charset=utf-8,"); + --md-details-icon: + url("data:image/svg+xml;charset=utf-8,"); } :is(.admonition) { @@ -62,7 +75,7 @@ a.admonition-anchor-link::before { content: "§"; } -:is(.admonition-title, summary.admonition-title) { +:is(.admonition-title, summary) { position: relative; min-height: 4rem; margin-block: 0; @@ -73,13 +86,13 @@ a.admonition-anchor-link::before { background-color: rgba(68, 138, 255, 0.1); display: flex; } -:is(.admonition-title, summary.admonition-title) p { +:is(.admonition-title, summary) p { margin: 0; } -html :is(.admonition-title, summary.admonition-title):last-child { +html :is(.admonition-title, summary):last-child { margin-bottom: 0; } -:is(.admonition-title, summary.admonition-title)::before { +:is(.admonition-title, summary)::before { position: absolute; top: 0.625em; inset-inline-start: 1.6rem; @@ -94,7 +107,7 @@ html :is(.admonition-title, summary.admonition-title):last-child { -webkit-mask-size: contain; content: ""; } -:is(.admonition-title, summary.admonition-title):hover a.admonition-anchor-link { +:is(.admonition-title, summary):hover a.admonition-anchor-link { display: initial; } @@ -119,204 +132,204 @@ details[open].admonition > summary.admonition-title::after { transform: rotate(90deg); } -:is(.admonition):is(.admonish-note) { +:is(.admonition):is(.note) { border-color: #448aff; } -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title) { +:is(.note) > :is(.admonition-title, summary) { background-color: rgba(68, 138, 255, 0.1); } -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title)::before { +:is(.note) > :is(.admonition-title, summary)::before { background-color: #448aff; - mask-image: var(--md-admonition-icon--admonish-note); - -webkit-mask-image: var(--md-admonition-icon--admonish-note); + mask-image: var(--md-admonition-icon--note); + -webkit-mask-image: var(--md-admonition-icon--note); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-abstract, .admonish-summary, .admonish-tldr) { +:is(.admonition):is(.abstract, .summary, .tldr) { border-color: #00b0ff; } -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title) { +:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary) { background-color: rgba(0, 176, 255, 0.1); } -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title)::before { +:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary)::before { background-color: #00b0ff; - mask-image: var(--md-admonition-icon--admonish-abstract); - -webkit-mask-image: var(--md-admonition-icon--admonish-abstract); + mask-image: var(--md-admonition-icon--abstract); + -webkit-mask-image: var(--md-admonition-icon--abstract); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-info, .admonish-todo) { +:is(.admonition):is(.info, .todo) { border-color: #00b8d4; } -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title) { +:is(.info, .todo) > :is(.admonition-title, summary) { background-color: rgba(0, 184, 212, 0.1); } -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title)::before { +:is(.info, .todo) > :is(.admonition-title, summary)::before { background-color: #00b8d4; - mask-image: var(--md-admonition-icon--admonish-info); - -webkit-mask-image: var(--md-admonition-icon--admonish-info); + mask-image: var(--md-admonition-icon--info); + -webkit-mask-image: var(--md-admonition-icon--info); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-tip, .admonish-hint, .admonish-important) { +:is(.admonition):is(.tip, .hint, .important) { border-color: #00bfa5; } -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title) { +:is(.tip, .hint, .important) > :is(.admonition-title, summary) { background-color: rgba(0, 191, 165, 0.1); } -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title)::before { +:is(.tip, .hint, .important) > :is(.admonition-title, summary)::before { background-color: #00bfa5; - mask-image: var(--md-admonition-icon--admonish-tip); - -webkit-mask-image: var(--md-admonition-icon--admonish-tip); + mask-image: var(--md-admonition-icon--tip); + -webkit-mask-image: var(--md-admonition-icon--tip); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-success, .admonish-check, .admonish-done) { +:is(.admonition):is(.success, .check, .done) { border-color: #00c853; } -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title) { +:is(.success, .check, .done) > :is(.admonition-title, summary) { background-color: rgba(0, 200, 83, 0.1); } -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title)::before { +:is(.success, .check, .done) > :is(.admonition-title, summary)::before { background-color: #00c853; - mask-image: var(--md-admonition-icon--admonish-success); - -webkit-mask-image: var(--md-admonition-icon--admonish-success); + mask-image: var(--md-admonition-icon--success); + -webkit-mask-image: var(--md-admonition-icon--success); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-question, .admonish-help, .admonish-faq) { +:is(.admonition):is(.question, .help, .faq) { border-color: #64dd17; } -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title) { +:is(.question, .help, .faq) > :is(.admonition-title, summary) { background-color: rgba(100, 221, 23, 0.1); } -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title)::before { +:is(.question, .help, .faq) > :is(.admonition-title, summary)::before { background-color: #64dd17; - mask-image: var(--md-admonition-icon--admonish-question); - -webkit-mask-image: var(--md-admonition-icon--admonish-question); + mask-image: var(--md-admonition-icon--question); + -webkit-mask-image: var(--md-admonition-icon--question); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-warning, .admonish-caution, .admonish-attention) { +:is(.admonition):is(.warning, .caution, .attention) { border-color: #ff9100; } -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title) { +:is(.warning, .caution, .attention) > :is(.admonition-title, summary) { background-color: rgba(255, 145, 0, 0.1); } -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title)::before { +:is(.warning, .caution, .attention) > :is(.admonition-title, summary)::before { background-color: #ff9100; - mask-image: var(--md-admonition-icon--admonish-warning); - -webkit-mask-image: var(--md-admonition-icon--admonish-warning); + mask-image: var(--md-admonition-icon--warning); + -webkit-mask-image: var(--md-admonition-icon--warning); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-failure, .admonish-fail, .admonish-missing) { +:is(.admonition):is(.failure, .fail, .missing) { border-color: #ff5252; } -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title) { +:is(.failure, .fail, .missing) > :is(.admonition-title, summary) { background-color: rgba(255, 82, 82, 0.1); } -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title)::before { +:is(.failure, .fail, .missing) > :is(.admonition-title, summary)::before { background-color: #ff5252; - mask-image: var(--md-admonition-icon--admonish-failure); - -webkit-mask-image: var(--md-admonition-icon--admonish-failure); + mask-image: var(--md-admonition-icon--failure); + -webkit-mask-image: var(--md-admonition-icon--failure); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-danger, .admonish-error) { +:is(.admonition):is(.danger, .error) { border-color: #ff1744; } -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title) { +:is(.danger, .error) > :is(.admonition-title, summary) { background-color: rgba(255, 23, 68, 0.1); } -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title)::before { +:is(.danger, .error) > :is(.admonition-title, summary)::before { background-color: #ff1744; - mask-image: var(--md-admonition-icon--admonish-danger); - -webkit-mask-image: var(--md-admonition-icon--admonish-danger); + mask-image: var(--md-admonition-icon--danger); + -webkit-mask-image: var(--md-admonition-icon--danger); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-bug) { +:is(.admonition):is(.bug) { border-color: #f50057; } -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title) { +:is(.bug) > :is(.admonition-title, summary) { background-color: rgba(245, 0, 87, 0.1); } -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title)::before { +:is(.bug) > :is(.admonition-title, summary)::before { background-color: #f50057; - mask-image: var(--md-admonition-icon--admonish-bug); - -webkit-mask-image: var(--md-admonition-icon--admonish-bug); + mask-image: var(--md-admonition-icon--bug); + -webkit-mask-image: var(--md-admonition-icon--bug); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-example) { +:is(.admonition):is(.example) { border-color: #7c4dff; } -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title) { +:is(.example) > :is(.admonition-title, summary) { background-color: rgba(124, 77, 255, 0.1); } -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title)::before { +:is(.example) > :is(.admonition-title, summary)::before { background-color: #7c4dff; - mask-image: var(--md-admonition-icon--admonish-example); - -webkit-mask-image: var(--md-admonition-icon--admonish-example); + mask-image: var(--md-admonition-icon--example); + -webkit-mask-image: var(--md-admonition-icon--example); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-quote, .admonish-cite) { +:is(.admonition):is(.quote, .cite) { border-color: #9e9e9e; } -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title) { +:is(.quote, .cite) > :is(.admonition-title, summary) { background-color: rgba(158, 158, 158, 0.1); } -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title)::before { +:is(.quote, .cite) > :is(.admonition-title, summary)::before { background-color: #9e9e9e; - mask-image: var(--md-admonition-icon--admonish-quote); - -webkit-mask-image: var(--md-admonition-icon--admonish-quote); + mask-image: var(--md-admonition-icon--quote); + -webkit-mask-image: var(--md-admonition-icon--quote); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; @@ -327,8 +340,7 @@ details[open].admonition > summary.admonition-title::after { background-color: var(--sidebar-bg); } -.ayu :is(.admonition), -.coal :is(.admonition) { +.ayu :is(.admonition), .coal :is(.admonition) { background-color: var(--theme-hover); } From b26f70eb6a48c708cdf11815693c68ad3a6e5034 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:51:05 +0200 Subject: [PATCH 06/32] stripped down + added new links --- .../src/infrastructure/node-types.md | 42 +++---------------- 1 file changed, 5 insertions(+), 37 deletions(-) diff --git a/documentation/dev-portal/src/infrastructure/node-types.md b/documentation/dev-portal/src/infrastructure/node-types.md index e864208cd3..c918c0e6d9 100644 --- a/documentation/dev-portal/src/infrastructure/node-types.md +++ b/documentation/dev-portal/src/infrastructure/node-types.md @@ -4,43 +4,11 @@ Discover the workings of Nym's privacy-enhancing mixnet infrastructure through t -### Mixnet Infrastructure - -There are few types of Nym infrastructure nodes: - -#### Mix Nodes -Mix nodes play a critical role in the Nym network by providing enhanced security and privacy to network content and metadata. They are part of the three-layer mixnet that ensures that communication remains anonymous and untraceable. Mix nodes receive `NYM` tokens as compensation for their quality of service, which is measured by the network validators. - -Mix nodes anonymously relay encrypted Sphinx packets between each other, adding an extra layer of protection by reordering and delaying the packets before forwarding them to the intended recipient. Additionally, cover traffic is maintained through mix nodes sending Sphinx packets to other mix nodes, making it appear as if there is a constant flow of user messages and further protecting the privacy of legitimate data packets. - -With the ability to hide, reorder and add a delay to network traffic, mix nodes make it difficult for attackers to perform time-based correlation attacks and deanonymize users. By consistently delivering high-quality service, mix nodes are rewarded with NYM tokens, reinforcing the integrity of the Nym network. - -#### Gateways -Gateways serve as the point of entry for user data into the mixnet, verifying that users have acquired sufficient NYM-based bandwidth credentials before allowing encrypted packets to be forwarded to mixnodes. They are also responsible for safeguarding against denial of service attacks and act as a message storage for users who may go offline. - -Gateways receive bandwidth credentials from users, which are periodically redeemed for `NYM` tokens as payment for their services. Users have the flexibility to choose a single gateway, split traffic across multiple gateways, run their own gateways, or a combination of these options. - -In addition, gateways also cache messages, functioning as an inbox for users who are offline. By providing secure, reliable access to the mixnet and ensuring that data remains protected, gateways play a crucial role in maintaining the integrity of the Nym network. - -#### Validators -Validators are essential to the security and integrity of the Nym network, tasked with several key responsibilities. They utilize proof-of-stake Sybil defense measures to secure the network and determine which nodes are included within it. Through their collaborative efforts, validators create Coconut threshold credentials which provide anonymous access to network data and resources. - -Validators also play a critical role in maintaining the Nym Cosmos blockchain, a secure, public ledger that records network-wide information such as node public information and keys, network configuration parameters, CosmWasm smart contracts, and `NYM` and credential transactions. - -#### Service Providers -Service Providers are a crucial aspect of the Nym infrastructure that support the application layer of the Nym network. Any application built with Nym will require a Service Provider, which can be created by anyone. Service Providers run a piece of binary code that enables them to handle requests from Nym users or other services, and then make requests to external servers on behalf of the users. - -For example, a Service Provider could receive a request to check a mail server and then forward the response to the user. The presence of Service Providers in the Nym network enhances its security and privacy, making it a reliable and robust platform for anonymous communication and data exchange. - ### Where do I go from here? 💭 -Maybe you would like to concentrate on building a application that uses the mixnet: +For more in-depth information on the network architecture, head to the [Network Overview page](https://nymtech.net/docs/architecture/network-overview.html). -* Explore the Tutorials section of the Developer Portal. Our in-depth tutorial on [Building a Simple Service Provider](../tutorials/simple-service-provider/simple-service-provider.md) give a good understanding of building User Clients and Service Providers in TypeScript, and how to configure Nym Websocket Clients for seamless communication with the mixnet. - -* Get started with using the Nym Mixnet quickly and easily by exploring the [Quickstart](../quickstart/overview.md) options, such a NymConnect, proxying traffic through the Nym Socks5 client, or dive into integrating Nym into your existing application with the [Integrations](../integrations/integration-options.md) section. - -Or perhaps you a developer that would like to run a infrastructure node such as a Gateway, Mix node or Network Requestor: -* Check out the [Network Overview](https://nymtech.net/docs/architecture/network-overview.html) docs page. - -* Take a look at our [Node Setup Guide](https://nymtech.net/operators/nodes/setup-guides.html) with our Nym Docs, containing setup guides for setting up you own infrastructure node. +If you would like to concentrate on building an application that uses the mixnet: +* Get started with using the Nym Mixnet quickly and easily by exploring the [Quickstart](../quickstart/overview.md) options. +* Go the [Tutorials](../tutorials) section . +* Check out examples of [Community Apps](../community-resources/community-applications-and-guides.md). From 0347a2bd892524fb07cfa8ab8cec8fb977f4e121 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 14:51:15 +0200 Subject: [PATCH 07/32] added deprecation warning --- .../simple-service-provider/simple-service-provider.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documentation/dev-portal/src/tutorials/simple-service-provider/simple-service-provider.md b/documentation/dev-portal/src/tutorials/simple-service-provider/simple-service-provider.md index b08d988de2..ece2427041 100644 --- a/documentation/dev-portal/src/tutorials/simple-service-provider/simple-service-provider.md +++ b/documentation/dev-portal/src/tutorials/simple-service-provider/simple-service-provider.md @@ -1,5 +1,12 @@ # Building a Simple Service Provider +```admonish warning +This tutorial was written before the creation of the [Typescript SDK](https://sdk.nymtech.net), and involves running a Nym Client alongside your application processes, instead of relying on the SDK to integrate the Client process into your application logic. + +As such, although this tutorial is still a valid way of approaching building on Nym, it is a little less streamlined than it could be. + +A more streamlined rewrite of this tutorial will be coming soon. +``` This tutorial is the best place to start for developers new to Nym. You will learn how to build a minimum viable privacy-enabled application (PEApp) able to send and receive traffic via the mixnet. This tutorial is less about building an immediately useful application, and more about beginning to understand: From 15af5511399fd1cb1c2abca908e8a7d4686b4e9e Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 24 Oct 2023 15:03:58 +0200 Subject: [PATCH 08/32] smol reword --- documentation/dev-portal/src/infrastructure/node-types.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/dev-portal/src/infrastructure/node-types.md b/documentation/dev-portal/src/infrastructure/node-types.md index c918c0e6d9..ba1a127d37 100644 --- a/documentation/dev-portal/src/infrastructure/node-types.md +++ b/documentation/dev-portal/src/infrastructure/node-types.md @@ -6,9 +6,9 @@ Discover the workings of Nym's privacy-enhancing mixnet infrastructure through t ### Where do I go from here? 💭 -For more in-depth information on the network architecture, head to the [Network Overview page](https://nymtech.net/docs/architecture/network-overview.html). +For more in-depth information on the network architecture, head to the [Network Overview page](https://nymtech.net/docs/architecture/network-overview.html), and check out the [Operators book](https://nymtech.net/operators) if you want to run a node yourself. If you would like to concentrate on building an application that uses the mixnet: -* Get started with using the Nym Mixnet quickly and easily by exploring the [Quickstart](../quickstart/overview.md) options. -* Go the [Tutorials](../tutorials) section . +* Explore the [Quickstart](../quickstart/overview.md) options. * Check out examples of [Community Apps](../community-resources/community-applications-and-guides.md). +* Run through one of the [tutorials](../tutorials). From 5d8c5224ede9718f561304652db0b529a6f8c279 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 15:44:22 +0100 Subject: [PATCH 09/32] added examples pages --- documentation/dev-portal/src/SUMMARY.md | 31 ++++++++++--------- .../dev-portal/src/examples/browser-only.md | 10 ++++++ .../src/examples/custom-services.md | 16 ++++++++++ .../dev-portal/src/examples/demos.md | 1 - .../src/examples/monorepo-examples.md | 5 +++ documentation/dev-portal/src/examples/rust.md | 1 - .../dev-portal/src/examples/typescript.md | 1 - .../dev-portal/src/examples/using-nrs.md | 17 ++++++++++ 8 files changed, 64 insertions(+), 18 deletions(-) create mode 100644 documentation/dev-portal/src/examples/browser-only.md create mode 100644 documentation/dev-portal/src/examples/custom-services.md delete mode 100644 documentation/dev-portal/src/examples/demos.md create mode 100644 documentation/dev-portal/src/examples/monorepo-examples.md delete mode 100644 documentation/dev-portal/src/examples/rust.md delete mode 100644 documentation/dev-portal/src/examples/typescript.md create mode 100644 documentation/dev-portal/src/examples/using-nrs.md diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md index 7c9836c58a..b9909e8190 100644 --- a/documentation/dev-portal/src/SUMMARY.md +++ b/documentation/dev-portal/src/SUMMARY.md @@ -18,21 +18,21 @@ # User Manuals -- [NymConnect Monero](tutorials/monero.md) -- [NymConnect Matrix](tutorials/matrix.md) -- [NymConnect Telegram](tutorials/telegram.md) +- [NymConnect X Monero](tutorials/monero.md) +- [NymConnect X Matrix](tutorials/matrix.md) +- [NymConnect X Telegram](tutorials/telegram.md) # Code Examples -- [Rust](examples/rust.md) -- [Typescript](examples/typescript.md) -- [Nym Demos](examples/demos.md) -- [Community Apps](examples/community-apps.md) +- [Custom Service Providers](examples/custom-services.md) +- [Apps Using Network Requesters](examples/using-nrs.md) +- [Browser only](examples/browser-only.md) +- [Monorepo examples](examples/monorepo-examples.md) # Integrations - [Integration Options](integrations/integration-options.md) -- [Mixnet Integration](integrations/mixnet-integration.md) +[//]: # (- [Mixnet Integration](integrations/mixnet-integration.md)) - [Payment Integration](integrations/payment-integration.md) # Tutorials @@ -47,14 +47,15 @@ - [Preparing Your Service](tutorials/cosmos-service/service.md) - [Preparing Your Service pt2](tutorials/cosmos-service/service-src.md) - [Querying the Chain](tutorials/cosmos-service/querying.md) + - [Typescript](tutorials/typescript.md) - - [[DEPRECATED] Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) - - [Tutorial Overview](tutorials/simple-service-provider/overview.md) - - [Preparing Your User Client Environment](tutorials/simple-service-provider/preparating-env.md) - - [Building Your User Client](tutorials/simple-service-provider/user-client.md) - - [Preparing Your Service Provider Environment](tutorials/simple-service-provider/preparating-env2.md) - - [Building Your Service Provider](tutorials/simple-service-provider/service-provider.md) - - [Sending a Message Through the Mixnet](tutorials/simple-service-provider/sending-message.md) + - [[DEPRECATED] Simple Service Provider](tutorials/simple-service-provider/simple-service-provider.md) + - [Tutorial Overview](tutorials/simple-service-provider/overview.md) + - [Preparing Your User Client Environment](tutorials/simple-service-provider/preparating-env.md) + - [Building Your User Client](tutorials/simple-service-provider/user-client.md) + - [Preparing Your Service Provider Environment](tutorials/simple-service-provider/preparating-env2.md) + - [Building Your Service Provider](tutorials/simple-service-provider/service-provider.md) + - [Sending a Message Through the Mixnet](tutorials/simple-service-provider/sending-message.md) # Events diff --git a/documentation/dev-portal/src/examples/browser-only.md b/documentation/dev-portal/src/examples/browser-only.md new file mode 100644 index 0000000000..9ee22ef1d8 --- /dev/null +++ b/documentation/dev-portal/src/examples/browser-only.md @@ -0,0 +1,10 @@ +# Browser only +With the Typescript SDK you can run a Nym client in a webworker - meaning you can connect to the mixnet through the browser without having to worry about any other code than your web framework. + +- NoTrustVerify have set up an example application using [`mixFetch`](https://sdk.nymtech.net/examples/mix-fetch) to fetch crypto prices from CoinGecko over the mixnet. + - [Website](https://notrustverify.github.io/mixfetch-examples/) + - [Coinbase](https://github.com/notrustverify/mixfetch-examples) + +- There is a coconut-scheme based Credential Library playground [here](https://coco-demo.nymtech.net/). This is a WASM implementation of our Coconut libraries which generate raw Coconut credentials. Test it to create and re-randomize your own credentials. For more information on what is happening here check out the [Coconut docs](https://nymtech.net/docs/coconut.html). + +- You can find a browser-based 'hello world' chat app [here](https://chat-demo.nymtech.net). Either open in two browser windows and send messages to yourself, or share with a friend and send messages to each other through the mixnet. diff --git a/documentation/dev-portal/src/examples/custom-services.md b/documentation/dev-portal/src/examples/custom-services.md new file mode 100644 index 0000000000..ce8262bb36 --- /dev/null +++ b/documentation/dev-portal/src/examples/custom-services.md @@ -0,0 +1,16 @@ +# Custom Services +Custom services involve two pieces of code that communicate via the mixnet: a client, and a custom server/service. This custom service will most likely interact with the wider internet / a clearnet service on your behalf, with the mixnet between you and the service, acting as a privacy shield. + +- PasteNym is a private pastebin alternative. It involves a browser-based frontend utilising the Typescript SDK and a Python-based backend service communicating with a standalone Nym Websocket Client. **If you're a Python developer, start here!**. + - [Frontend codebase](https://github.com/notrustverify/pastenym) + - [Backend codebase](https://github.com/notrustverify/pastenym-frontend) + +- Nostr-Nym is another application written by NoTrustVerify, standing between mixnet users and a Nostr server in order to protect their metadata from being revealed when gossiping. **Useful for Go and Python developers**. + - [Codebase](https://github.com/notrustverify/nostr-nym) + +- Spook and Nym-Ethtx are both examples of Ethereum transaction broadcasters utilising the mixnet, written in Rust. Since they were written before the release of the Rust SDK, they utilise standalone clients to communicate with the mixnet. + - [Spook](https://github.com/EdenBlockVC/spook) (**Typescript**) + - [Nym-Ethtx](https://github.com/noot/nym-ethtx) (**Rust**) + +- NymDrive is an early proof of concept application for privacy-enhanced file storage on IPFS. **JS and CSS**, and a good example of packaging as an Electrum app. + - [Codebase](https://github.com/saleel/nymdrive) diff --git a/documentation/dev-portal/src/examples/demos.md b/documentation/dev-portal/src/examples/demos.md deleted file mode 100644 index ddcf4dd8c4..0000000000 --- a/documentation/dev-portal/src/examples/demos.md +++ /dev/null @@ -1 +0,0 @@ -# Nym Demos diff --git a/documentation/dev-portal/src/examples/monorepo-examples.md b/documentation/dev-portal/src/examples/monorepo-examples.md new file mode 100644 index 0000000000..ad04287f20 --- /dev/null +++ b/documentation/dev-portal/src/examples/monorepo-examples.md @@ -0,0 +1,5 @@ +# Monorepo examples +As well as these examples, there are a bunch of examples for each SDK in the Nym monorepo. + +- [Rust SDK examples](https://github.com/nymtech/nym/tree/develop/sdk/rust/nym-sdk/examples) +- [Typescript SDK examples](https://github.com/nymtech/nym/tree/develop/sdk/typescript/examples) \ No newline at end of file diff --git a/documentation/dev-portal/src/examples/rust.md b/documentation/dev-portal/src/examples/rust.md deleted file mode 100644 index 2f1d5efed1..0000000000 --- a/documentation/dev-portal/src/examples/rust.md +++ /dev/null @@ -1 +0,0 @@ -# Rust diff --git a/documentation/dev-portal/src/examples/typescript.md b/documentation/dev-portal/src/examples/typescript.md deleted file mode 100644 index 42c9775801..0000000000 --- a/documentation/dev-portal/src/examples/typescript.md +++ /dev/null @@ -1 +0,0 @@ -# Typescript diff --git a/documentation/dev-portal/src/examples/using-nrs.md b/documentation/dev-portal/src/examples/using-nrs.md new file mode 100644 index 0000000000..0732340b79 --- /dev/null +++ b/documentation/dev-portal/src/examples/using-nrs.md @@ -0,0 +1,17 @@ +# Apps Using Network Requesters +These applications utilise custom app logic in the user-facing apps in order to communicate using the mixnet as a transport layer, without having to rely on custom server-side logic. Instead, they utilise existing Nym infrastructure - [Network Requesters](https://nymtech.net/operators/nodes/network-requester-setup.html) - with a custom whitelist addition. + +If you are sending 'normal' application traffic, and/or don't require and custom logic to be happening on the 'other side' of the mixnet, this is most likely the best option to take as a developer who wishes to privacy-enhance their application. + +> Nym will soon be switching from a whitelist-based approach to a blocklist-based approach to filtering traffic. As such, it will soon be even easier for developers to utilise the mixnet, as they will not have to run their own NRs or have to add their domains to the whitelist + +- DarkFi over Nym leverages Nym’s mixnet as a pluggable transport for DarkIRC, their p2p IRC variant. Users can anonymously connect to peers over the network, ensuring secure and private communication within the DarkFi ecosystem. Written in **Rust**. + - [Docs](https://darkrenaissance.github.io/darkfi/clients/nym_outbound.html?highlight=nym#3--run) + - [Github](https://github.com/darkrenaissance/darkfi/tree/master/doc) + +- MiniBolt is a complete guide to building a Bitcoin & Lightning full node on a personal computer. It has the capacity to run network traffic (transactions and syncing) over the mixnet, so you can privately sync your node and not expose your home IP to the wider world when interacting with the rest of the network! + - [Docs](https://v2.minibolt.info/bonus-guides/system/nym-mixnet#proxying-bitcoin-core) + - [Codebase](https://github.com/minibolt-guide/minibolt) + +- Email over Nym is a set of configuration options to set up a Network Requester to send and recieve emails over Nym, using something like Thunderbird. + - [Codebase](https://github.com/dial0ut/nymstr-email) \ No newline at end of file From d1160350b273ec27379902a5be66581b7161f370 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 15:44:39 +0100 Subject: [PATCH 10/32] added notepad to gitignore file --- documentation/dev-portal/.gitignore | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/dev-portal/.gitignore b/documentation/dev-portal/.gitignore index c29699d0c0..1451d34afd 100644 --- a/documentation/dev-portal/.gitignore +++ b/documentation/dev-portal/.gitignore @@ -19,4 +19,6 @@ theme/ theme theme/* -.idea \ No newline at end of file +.idea + +notes \ No newline at end of file From 27810d473d131794336edbb64d7d29ee93448997 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 15:45:00 +0100 Subject: [PATCH 11/32] added community examples --- documentation/dev-portal/src/examples/community-apps.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 documentation/dev-portal/src/examples/community-apps.md diff --git a/documentation/dev-portal/src/examples/community-apps.md b/documentation/dev-portal/src/examples/community-apps.md deleted file mode 100644 index b6c3fda9c6..0000000000 --- a/documentation/dev-portal/src/examples/community-apps.md +++ /dev/null @@ -1 +0,0 @@ -# Community Apps From 04fdc1dc60a5b283f5163b962482ccc4dbb6412c Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 15:45:27 +0100 Subject: [PATCH 12/32] streamline integrations files --- .../src/integrations/integration-options.md | 14 +++++++++----- .../src/integrations/mixnet-integration.md | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/documentation/dev-portal/src/integrations/integration-options.md b/documentation/dev-portal/src/integrations/integration-options.md index 56f00a33da..328ec154a3 100644 --- a/documentation/dev-portal/src/integrations/integration-options.md +++ b/documentation/dev-portal/src/integrations/integration-options.md @@ -1,10 +1,14 @@ # Integration Options -If you've already gone through the different [Quick Start](../quickstart/overview.md) options, you have seen the possibilities avaliable to you for quickly connecting existing application code to another Nym process. +If you've already gone through the different [Quick Start](../quickstart/overview.md) options and had a look at the tutorials, you have seen the possibilities available to you for quickly connecting existing application code to another Nym process. -This section assumes you wish to integrate with Nym into your application code. +Below are a resources that will be useful for either beginning to integrate mixnet functionality into existing application code or build a new app using Nym. -The [integrations FAQ](../faq/integrations-faq.md) has a list of common questions regarding integrating with Nym and Nyx, as well as commonly required links. _This is a good place to start to get an overall idea of the tools and software avaliable to you_. +- **We suggest you begin with this [integration decision tree](https://sdk.nymtech.net/integrations)**. This will give you a better idea of what pieces of software (SDKs, standalone clients, service providers) your integration might involve, and what is currently possible to do with as little custom code as possible. + +- The [integrations FAQ](../faq/integrations-faq.md) has a list of common questions regarding integrating with Nym and Nyx, as well as commonly required links. + +- To get an idea of what is possible / has already been built, check the [community applications and resources](../community-resources/community-applications-and-guides.md) page, as well as the [developer tutorials codebase](https://github.com/nymtech/developer-tutorials). + +> If you wish to integrate with the Nyx blockchain to use `NYM` for payments, start with the [payment integration](./payment-integration.md) page. -If you wish to integrate with Nym to use the mixnet for application traffic, start with the [mixnet integration](./mixnet-integration.md) page. -If you wish to integrate with the Nyx blockchain to use `NYM` for payments, start with the [payment integration](./payment-integration.md) page. diff --git a/documentation/dev-portal/src/integrations/mixnet-integration.md b/documentation/dev-portal/src/integrations/mixnet-integration.md index 91e6c2d559..a26f0a885b 100644 --- a/documentation/dev-portal/src/integrations/mixnet-integration.md +++ b/documentation/dev-portal/src/integrations/mixnet-integration.md @@ -13,7 +13,7 @@ As outlined in the [clients overview documentation](https://nymtech.net/docs/cli #### Websocket client Your first option is the native websocket client. This is a compiled program that can run on Linux, Mac OS X, and Windows machines. It runs as a persistent process on a desktop or server machine. You can connect to it with any language that supports websockets. -You can see an example of how to connect to and manage interactions with this client in the [Simple Service Provider tutorial](../tutorials/simple-service-provider/simple-service-provider.md). +[//]: # (You can see an example of how to connect to and manage interactions with this client in the [Simple Service Provider tutorial](../tutorials/simple-service-provider/simple-service-provider.md).) #### Webassembly client If you’re working in JavaScript or Typescript in the browser, or building an edge computing app, you’ll likely want to choose the webassembly client. From 4b23cd94fd1298ee8a54dc43e7c86024b7dc9516 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 15:46:25 +0100 Subject: [PATCH 13/32] streamlined node types --- documentation/dev-portal/src/infrastructure/node-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/dev-portal/src/infrastructure/node-types.md b/documentation/dev-portal/src/infrastructure/node-types.md index ba1a127d37..cb5e9c3d35 100644 --- a/documentation/dev-portal/src/infrastructure/node-types.md +++ b/documentation/dev-portal/src/infrastructure/node-types.md @@ -11,4 +11,4 @@ For more in-depth information on the network architecture, head to the [Network If you would like to concentrate on building an application that uses the mixnet: * Explore the [Quickstart](../quickstart/overview.md) options. * Check out examples of [Community Apps](../community-resources/community-applications-and-guides.md). -* Run through one of the [tutorials](../tutorials). +* Run through the [Rust SDK](../tutorials/rust-sdk.md) or [Typescript](../tutorials/typescript.md) tutorials. From b072a080ae6c32d7ad482f859cf68456bcb51154 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 17:03:37 +0100 Subject: [PATCH 14/32] added shipyard info --- documentation/dev-portal/src/SUMMARY.md | 5 ++ .../src/shipyard/challenges-overview.md | 53 +++++++++++++++++++ .../dev-portal/src/shipyard/general.md | 16 ++++++ .../dev-portal/src/shipyard/guidelines.md | 12 +++++ .../dev-portal/src/shipyard/infra.md | 5 ++ 5 files changed, 91 insertions(+) create mode 100644 documentation/dev-portal/src/shipyard/challenges-overview.md create mode 100644 documentation/dev-portal/src/shipyard/general.md create mode 100644 documentation/dev-portal/src/shipyard/guidelines.md create mode 100644 documentation/dev-portal/src/shipyard/infra.md diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md index b9909e8190..cd930be17a 100644 --- a/documentation/dev-portal/src/SUMMARY.md +++ b/documentation/dev-portal/src/SUMMARY.md @@ -57,6 +57,11 @@ - [Building Your Service Provider](tutorials/simple-service-provider/service-provider.md) - [Sending a Message Through the Mixnet](tutorials/simple-service-provider/sending-message.md) +# Shipyard Builders Hackathon 2023 +- [General Info & Resources](shipyard/general.md) +- [Hackathon Challenges](shipyard/challenges-overview.md) +- [A Note on Infrastructure](shipyard/infra.md) +- [Submission Guidelines](shipyard/guidelines.md) # Events diff --git a/documentation/dev-portal/src/shipyard/challenges-overview.md b/documentation/dev-portal/src/shipyard/challenges-overview.md new file mode 100644 index 0000000000..f4a0be6b92 --- /dev/null +++ b/documentation/dev-portal/src/shipyard/challenges-overview.md @@ -0,0 +1,53 @@ +# Hackathon Challenges +There are a few different challenges to choose from, each with different approaches. It is also recommended to check out the _**Examples**_ directory above for inspiration, and if you have questions ask in the [Builders channel]() on Matrix. + +## Tooling challenge +The tooling challenge involves creating tooling for users, operators, or developers of Nym. + +### Examples of user-centric tools: +- Facilitate onboarding new users more easily to staking their Nym, and understanding the pros and cons, as well as finding a good node to stake on. Examples of tools like this: + - [ExploreNym dashboard](https://explorenym.net/) + +- Show information on a dashboard about the network. NOTE due to the amount of dashboards currently available, we expect a good justification for why / something to set this apart from existing ones e.g. it is presenting information that is not already presented, or it is presented in a different manner, such as a TUI or CLI app instead of a web dashboard - maybe an onion service, or no-JS site for those who do not wish to enable Javascript in their day to day browsing. Examples of tools like this: + - [NTV's node dashboard](https://status.notrustverify.ch/d/CW3L7dVVk/nym-mixnet?orgId=1) + - [IsNymUp dashboard](https://isnymup.com/) + +### Examples of operator-centric tooling: +- An APY calculator for determining different financial outcomes of running a node in different situations. + +- Scripting for updating and maintaining nodes. Examples of tools like this: + - [ExploreNym's bash scripts](https://github.com/ExploreNYM/bash-tool) + +- Scripting for packaging node binaries for different OSes. + +### Examples of developer-centric tooling: +- Tooling for use in development: are there pain points you’ve found when developing apps with Nym that you have created scripts/hacks/workarounds for? Is there a pain point that you’ve thought ‘oh it would be great if I could just do X’? These are often the best places to start for building out developer tooling - if you’ve run into this issue, it's very likely someone else already has, or will! + +- Interacting with one of the SDKs via FFI: perhaps you’re a Go developer who would love to have the functionality of one of the Nym SDKs. Building an FFI tool might be something that would make your life easier, and can be shared with other developers in your situation. + +## Integrations challenge +Integration options for Nym are currently relatively restrictive due to the manner in which Nym handles sending and receiving traffic (as unordered Sphinx packets). This challenge will involve (most likely) implementing custom logic for handling Nym traffic for an existing application. + +There are several potential avenues developers can take here: +- If your application (or the application you wish to modify) is written in either Javascript or Typescript, and relies on the `fetch` library to make API calls, then you can use its drop-in replacement: [`mixfetch`](). Perhaps you wish to interact with Coingecko, or a private search engine like Kagi without leaking your IP and metadata, or an RPC endpoint. + - Example with [NTV’s privacy-preserving Coingecko API](https://github.com/notrustverify/mixfetch-examples) + - [Mixfetch docs examples](https://github.com/nymtech/nym/tree/develop/sdk/typescript/examples) + +- If you instead have an application that is able to use any of the SOCKS5, 4a, or 4 protocols (a rule of thumb: if it can communicate over Tor, it will) then you can experiment with using Nym as the transport layer. + - For Rustaceans, check out our [socks5 rust sdk example](https://nymtech.net/docs/sdk/rust.html#socks-client-example). + - For those of you who aren’t Crustaceans, then you will have to run the [Socks Client]() alongside your application as a separate process. _NOTE If you are taking this route, please make sure to include detailed documentation on how you expect users to do this, as well as including any process management tools, scripts, and configs (e.g. if you use systemd then include the configuration file for the client, as well as initialisation logic) that may streamline this process._ + - [NTV's PasteNym backend](https://github.com/notrustverify/pastenym) is a great example of an application with this architecture. + +- Nym is not only useful for blockchain-related apps, but for anything that requires network level privacy! Email clients, messaging clients, and decentralised storage are all key elements of the privacy-enabled web. Several of these sorts of apps can be found in the [community apps page](../community-resources/community-applications-and-guides.md). + +- There is currently a proof of concept using Rust Libp2p with Nym as a transport layer. Perhaps you can think of an app that uses Gossipsub for p2p communication could benefit from network-level privacy. + - [GossipSub chat example](https://github.com/nymtech/nym/tree/develop/sdk/rust/nym-sdk/examples/libp2p_chat) + - [Chainsafe's Lighthouse Nym PoC](https://github.com/ChainSafe/lighthouse/blob/nym/USE_NYM.md#usage) + +- Alternatively if you know of an app that is written in Rust or TS and could benefit from using Nym, you could fork and modify it using the SDKs. Applications such as: + - Magic Wormhole (has a [rust implementation](https://github.com/magic-wormhole/magic-wormhole.rs)) + - [Qual](https://github.com/qaul/qaul.net) (uses Rust Libp2p) + - [Syncthing](https://github.com/syncthing/syncthing) + +### MiniApp challenge +Write an app, either using one of the SDKs or a standalone client (harder). Think of what you can ‘nymify’ e.g. a version of the [TorBirdy](https://support.torproject.org/glossary/torbirdy/) extension that uses Nym instead of Tor. This is very similar to the Integration challenge in terms of the different potential _architectures_ and approaches, but just for new applications. diff --git a/documentation/dev-portal/src/shipyard/general.md b/documentation/dev-portal/src/shipyard/general.md new file mode 100644 index 0000000000..f07f3f22ac --- /dev/null +++ b/documentation/dev-portal/src/shipyard/general.md @@ -0,0 +1,16 @@ +# General Info & Resources +Discussions and announcements will be taking place in the [builders channel on Matrix](https://matrix.to/#/#shipyardbuilders:nymtech.chat). This channel can be used for all discussions. + +There will be daily office horse between 12-14:00 CET. + +This is an open call and questions will be answered on a first come first serve basis. + +The timetable can be found on the [Shipyard website](https://nymtech.net/learn/shipyard). + +## Links +- You can find **code examples**, **tutorials**, & **quickstart** information here, on the Developer Portal. +- [Rust SDK docs](https://nymtech.net/docs/sdk/rust.html) +- [Typescript SDK docs](https://sdk.nymtech.net) +- [Platform docs](https://nymtech.net/docs) +- [NoTrustVerify's Awesome Nym list](https://github.com/notrustverify/awesome-nym) +- [Builders channel Matrix](https://matrix.to/#/#shipyardbuilders:nymtech.chat) diff --git a/documentation/dev-portal/src/shipyard/guidelines.md b/documentation/dev-portal/src/shipyard/guidelines.md new file mode 100644 index 0000000000..ac8a7b18a8 --- /dev/null +++ b/documentation/dev-portal/src/shipyard/guidelines.md @@ -0,0 +1,12 @@ +# Submission Guidelines +We expect to see the following for submissions: +- Working code demos hosted publicly (Gitlab, Github, some other git instance). +- Quality > quantity here: we’d prefer to see a contained, working, and well documented Proof of Concept over a sprawling and messy app that does more but is poorly explained and presented. _The repo must be open source and able to be used and modified by others. The license is up to you._ +- If you already have existing apps / projects you are more than welcome to extend them, instead of starting from scratch - we will only be looking at the NEW additions to make this fair. If you are doing this, make sure to write a detailed account of what it is you;ve added to the existing project, preferably with the possibility to see the ‘old’ version as well as the new one. +- Proper documentation: + - If an app / tool: + - How do you install and run the code? How is it to be used? + - An overview of the application architecture: what is it doing? Is it relying on other services? + - If a UI-based solution: + - How to run it locally? We are happy to also accept staging deployments as part of the submission (e.g. via Vercel) but this does not replace being able to run it locally. +- Please make sure that your application works on commonly reproducible system environments (e.g. if you’re developing on Artix Linux please check for the necessary dependencies for more common-place OSes such as Debian, or Arch). If you are developing on Windows please make sure that it works on non-Windows machines also. Where possible please try to include build and install instructions for a variety of OSes. diff --git a/documentation/dev-portal/src/shipyard/infra.md b/documentation/dev-portal/src/shipyard/infra.md new file mode 100644 index 0000000000..b5621f6ff6 --- /dev/null +++ b/documentation/dev-portal/src/shipyard/infra.md @@ -0,0 +1,5 @@ +# A Note on Infrastructure +If you are writing an application that requires sending messages through the mixnet, then you will either be relying on existing infrastructure nodes (network requesters), or writing your own custom service (for example, the service written as part of the Rust SDK tutorial). + +If you are relying on network requesters then chances are that the IPs or domains your app relies on will not already be on the whitelist. Ideally, you would [run your own,](https://nymtech.net/operators/nodes/network-requester-setup.html) but we will also run a few nodes in ‘open proxy’ mode and share the addresses so that you can use them when beginning to develop. + From a10ebf342bcd894c96534cbca46a41eadaa5ea9e Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Tue, 31 Oct 2023 17:14:30 +0100 Subject: [PATCH 15/32] tweak --- documentation/dev-portal/src/shipyard/challenges-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/dev-portal/src/shipyard/challenges-overview.md b/documentation/dev-portal/src/shipyard/challenges-overview.md index f4a0be6b92..0a815b2d42 100644 --- a/documentation/dev-portal/src/shipyard/challenges-overview.md +++ b/documentation/dev-portal/src/shipyard/challenges-overview.md @@ -1,5 +1,5 @@ # Hackathon Challenges -There are a few different challenges to choose from, each with different approaches. It is also recommended to check out the _**Examples**_ directory above for inspiration, and if you have questions ask in the [Builders channel]() on Matrix. +There are a few different challenges to choose from, each with different approaches. It is also recommended to check out the _**Examples**_ directory above for inspiration. ## Tooling challenge The tooling challenge involves creating tooling for users, operators, or developers of Nym. From 11e383659969e65cda14a2239af484e898f793ed Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 1 Nov 2023 16:31:02 +0100 Subject: [PATCH 16/32] spellcheck + table format fix --- documentation/docs/src/sdk/rust.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/docs/src/sdk/rust.md b/documentation/docs/src/sdk/rust.md index b62353a9d6..884c71bc9c 100644 --- a/documentation/docs/src/sdk/rust.md +++ b/documentation/docs/src/sdk/rust.md @@ -1,12 +1,12 @@ # Rust SDK -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 seperate 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 seperate console window/tab) and being able to have a single binary for other people to use. +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. ## Development status The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases. -The `nym-sdk` crate is **not yet availiable via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: +The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: ```toml nym-sdk = { git = "https://github.com/nymtech/nym" } @@ -17,10 +17,10 @@ In order to generate the crate docs run `cargo doc --open` from `nym/sdk/rust/ny 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's infrastructure. | Component | Functionality | Released | -| --------- | ------------------------------------------------------------------------------------- | -------- | -| Mixnet | Create / load clients & keypairs, subscribe to Mixnet events, send & receive messages | ✔️ | -| Coconut | Create & verify Coconut credentials | 🛠️ | -| Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain | ❌ | +|-----------|---------------------------------------------------------------------------------------|----------| +| Mixnet | Create / load clients & keypairs, subscribe to Mixnet events, send & receive messages | ✔️ | +| Coconut | Create & verify Coconut credentials | 🛠️ | +| Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain | ❌ | The `mixnet` component currently exposes the logic of two clients: the [websocket client](../clients/websocket-client.md), and the [socks](../clients/socks5-client.md) client. From d0e51df59ad6b3b74b38a8ab465dd7cba252a6f0 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 1 Nov 2023 17:34:55 +0100 Subject: [PATCH 17/32] new directory structure for rust SDK docs --- documentation/docs/src/SUMMARY.md | 13 +++++- documentation/docs/src/clients/overview.md | 4 +- documentation/docs/src/introduction.md | 2 +- documentation/docs/src/sdk/rust/examples.md | 2 + .../docs/src/sdk/rust/message-helpers.md | 2 + .../docs/src/sdk/rust/message-types.md | 7 +++ documentation/docs/src/sdk/{ => rust}/rust.md | 46 +++++++++---------- .../docs/src/sdk/rust/troubleshooting.md | 3 ++ 8 files changed, 52 insertions(+), 27 deletions(-) create mode 100644 documentation/docs/src/sdk/rust/examples.md create mode 100644 documentation/docs/src/sdk/rust/message-helpers.md create mode 100644 documentation/docs/src/sdk/rust/message-types.md rename documentation/docs/src/sdk/{ => rust}/rust.md (86%) create mode 100644 documentation/docs/src/sdk/rust/troubleshooting.md diff --git a/documentation/docs/src/SUMMARY.md b/documentation/docs/src/SUMMARY.md index 8e4f7c6127..b9dd5a4191 100644 --- a/documentation/docs/src/SUMMARY.md +++ b/documentation/docs/src/SUMMARY.md @@ -29,7 +29,18 @@ # SDK - [Typescript SDK](sdk/typescript.md) -- [Rust SDK](sdk/rust.md) +- [Rust SDK](sdk/rust/rust.md) + - [Message Types](sdk/rust/message-types.md) + - [Message Helpers](sdk/rust/message-helpers.md) + - [Troubleshooting](sdk/rust/troubleshooting.md) + - [Examples](sdk/rust/examples.md) + - [Simple Send](sdk/rust/examples/simple.md) + - [Create and Store Keys](sdk/rust/examples/keys.md) + - [Manual Storage](sdk/rust/examples/storage.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) # Wallet - [Desktop Wallet](wallet/desktop-wallet.md) diff --git a/documentation/docs/src/clients/overview.md b/documentation/docs/src/clients/overview.md index c8d2db1503..b9b5686dbd 100644 --- a/documentation/docs/src/clients/overview.md +++ b/documentation/docs/src/clients/overview.md @@ -25,7 +25,7 @@ You need to choose which one you want incorporate into your app. Which one you u ### 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.md)_. +_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. @@ -39,7 +39,7 @@ The `nym-socks5-client` is useful for allowing existing applications to use the 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.md)_. +_Rust developers can import socks client functionality into their code via the [Rust SDK](../sdk/rust/rust.md)_. ## Commonalities between clients All Nym client packages present basically the same capabilities to the privacy application developer. They need to run as a persistent process in order to stay connected and ready to receive any incoming messages from their gateway nodes. They register and authenticate to gateways, and encrypt Sphinx packets. diff --git a/documentation/docs/src/introduction.md b/documentation/docs/src/introduction.md index 9e5912ba07..c9b4c4a7d5 100644 --- a/documentation/docs/src/introduction.md +++ b/documentation/docs/src/introduction.md @@ -15,7 +15,7 @@ If you're specically looking for TypeScript/JavaScript related information such **SDK examples:** * [Typescript SDK](https://sdk.nymtech.net/) -* [Rust SDK](./sdk/rust.md) +* [Rust SDK](sdk/rust/rust.md) **Nyx** * [Interacting with the Nyx chain](./nyx/interacting-with-chain.md) diff --git a/documentation/docs/src/sdk/rust/examples.md b/documentation/docs/src/sdk/rust/examples.md new file mode 100644 index 0000000000..544f7fb418 --- /dev/null +++ b/documentation/docs/src/sdk/rust/examples.md @@ -0,0 +1,2 @@ +# Examples +TODO split examples into subdirectory with their own individual files \ No newline at end of file diff --git a/documentation/docs/src/sdk/rust/message-helpers.md b/documentation/docs/src/sdk/rust/message-helpers.md new file mode 100644 index 0000000000..478e12a7ab --- /dev/null +++ b/documentation/docs/src/sdk/rust/message-helpers.md @@ -0,0 +1,2 @@ +# Message Helpers +TODO pull in dealing with incoming non-empty messages and fn()s from tutorial \ No newline at end of file diff --git a/documentation/docs/src/sdk/rust/message-types.md b/documentation/docs/src/sdk/rust/message-types.md new file mode 100644 index 0000000000..20d959b127 --- /dev/null +++ b/documentation/docs/src/sdk/rust/message-types.md @@ -0,0 +1,7 @@ +# Message Types + +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.md b/documentation/docs/src/sdk/rust/rust.md similarity index 86% rename from documentation/docs/src/sdk/rust.md rename to documentation/docs/src/sdk/rust/rust.md index 884c71bc9c..c593b3aa6e 100644 --- a/documentation/docs/src/sdk/rust.md +++ b/documentation/docs/src/sdk/rust/rust.md @@ -1,20 +1,9 @@ # Rust SDK 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. +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. -## Development status -The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases. - -The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: - -```toml -nym-sdk = { git = "https://github.com/nymtech/nym" } -``` - -In order to generate the crate docs run `cargo doc --open` from `nym/sdk/rust/nym-sdk/` - -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's infrastructure. +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 | |-----------|---------------------------------------------------------------------------------------|----------| @@ -22,18 +11,27 @@ In the future the SDK will be made up of several components, each of which will | Coconut | Create & verify Coconut credentials | 🛠️ | | Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain | ❌ | -The `mixnet` component currently exposes the logic of two clients: the [websocket client](../clients/websocket-client.md), and the [socks](../clients/socks5-client.md) client. +The `mixnet` component currently exposes the logic of two clients: the [websocket client](../../clients/websocket-client.md), and the [socks](../../clients/socks5-client.md) client. The `coconut` component is currently being worked on. Right now it exposes logic allowing for the creation of coconut credentials on the Sandbox testnet. +### Development status +The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases. + +### Installation +The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: + +TODO add note on branch import for stability - `master` should be last release +```toml +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. -### Different message types -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). - ### 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`): @@ -89,7 +87,7 @@ The number of SURBs is set [here](https://github.com/nymtech/nym/blob/master/sdk {{#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). +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: @@ -124,7 +122,7 @@ If you need to split the different actions of your client across different tasks ``` ## Socks client example -There is also the option to embed the [`socks5-client`](../clients/socks5-client.md) into your app code (`examples/socks5.rs`): +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}} @@ -135,10 +133,12 @@ If you are looking at implementing Nym as a transport layer for a crypto wallet ``` ## 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. +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). +You can read more about Coconut credentials (also referred to as `zk-Nym`) [here](../../coconut.md). + + diff --git a/documentation/docs/src/sdk/rust/troubleshooting.md b/documentation/docs/src/sdk/rust/troubleshooting.md new file mode 100644 index 0000000000..c8de2e5e37 --- /dev/null +++ b/documentation/docs/src/sdk/rust/troubleshooting.md @@ -0,0 +1,3 @@ +# Troubleshooting +TODO note on poisson dance and not immediately killing client process +TODO note on listening for non-empty messages and point towards helpers From 8cf0b3adae73040014ab4a2b299b1df3fbb5aac8 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 1 Nov 2023 21:01:47 +0100 Subject: [PATCH 18/32] 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). - From c667bb91c776715c66d447ac5b7faa1f594cffd4 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:24:03 +0100 Subject: [PATCH 19/32] tweak --- documentation/dev-portal/src/shipyard/challenges-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/dev-portal/src/shipyard/challenges-overview.md b/documentation/dev-portal/src/shipyard/challenges-overview.md index 0a815b2d42..4e02f5a797 100644 --- a/documentation/dev-portal/src/shipyard/challenges-overview.md +++ b/documentation/dev-portal/src/shipyard/challenges-overview.md @@ -8,7 +8,7 @@ The tooling challenge involves creating tooling for users, operators, or develop - Facilitate onboarding new users more easily to staking their Nym, and understanding the pros and cons, as well as finding a good node to stake on. Examples of tools like this: - [ExploreNym dashboard](https://explorenym.net/) -- Show information on a dashboard about the network. NOTE due to the amount of dashboards currently available, we expect a good justification for why / something to set this apart from existing ones e.g. it is presenting information that is not already presented, or it is presented in a different manner, such as a TUI or CLI app instead of a web dashboard - maybe an onion service, or no-JS site for those who do not wish to enable Javascript in their day to day browsing. Examples of tools like this: +- Show information on a dashboard about the network. NOTE due to the amount of dashboards currently available, we expect a good justification for why / something to set this apart from existing ones e.g. it is presenting information that is not already presented, or it is presented in a different manner, such as a TUI or CLI app instead of a web dashboard - maybe an onion service, or no-JS site for those who do not wish to enable Javascript in their day-to-day browsing. Examples of tools like this: - [NTV's node dashboard](https://status.notrustverify.ch/d/CW3L7dVVk/nym-mixnet?orgId=1) - [IsNymUp dashboard](https://isnymup.com/) From 6122817ab6018baf6a2d779f6323603a38f2dde9 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:24:25 +0100 Subject: [PATCH 20/32] fixed broken link --- documentation/docs/mdbook-admonish.css | 172 ++++++++++-------- .../docs/src/architecture/traffic-flow.md | 4 +- 2 files changed, 94 insertions(+), 82 deletions(-) diff --git a/documentation/docs/mdbook-admonish.css b/documentation/docs/mdbook-admonish.css index e0a3365532..244bc9ade7 100644 --- a/documentation/docs/mdbook-admonish.css +++ b/documentation/docs/mdbook-admonish.css @@ -1,18 +1,31 @@ @charset "UTF-8"; :root { - --md-admonition-icon--admonish-note: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-abstract: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-info: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-tip: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-success: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-question: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-warning: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-failure: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-danger: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-bug: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-example: url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--admonish-quote: url("data:image/svg+xml;charset=utf-8,"); - --md-details-icon: url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--note: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--abstract: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--info: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--tip: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--success: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--question: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--warning: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--failure: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--danger: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--bug: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--example: + url("data:image/svg+xml;charset=utf-8,"); + --md-admonition-icon--quote: + url("data:image/svg+xml;charset=utf-8,"); + --md-details-icon: + url("data:image/svg+xml;charset=utf-8,"); } :is(.admonition) { @@ -62,7 +75,7 @@ a.admonition-anchor-link::before { content: "§"; } -:is(.admonition-title, summary.admonition-title) { +:is(.admonition-title, summary) { position: relative; min-height: 4rem; margin-block: 0; @@ -73,13 +86,13 @@ a.admonition-anchor-link::before { background-color: rgba(68, 138, 255, 0.1); display: flex; } -:is(.admonition-title, summary.admonition-title) p { +:is(.admonition-title, summary) p { margin: 0; } -html :is(.admonition-title, summary.admonition-title):last-child { +html :is(.admonition-title, summary):last-child { margin-bottom: 0; } -:is(.admonition-title, summary.admonition-title)::before { +:is(.admonition-title, summary)::before { position: absolute; top: 0.625em; inset-inline-start: 1.6rem; @@ -94,7 +107,7 @@ html :is(.admonition-title, summary.admonition-title):last-child { -webkit-mask-size: contain; content: ""; } -:is(.admonition-title, summary.admonition-title):hover a.admonition-anchor-link { +:is(.admonition-title, summary):hover a.admonition-anchor-link { display: initial; } @@ -119,204 +132,204 @@ details[open].admonition > summary.admonition-title::after { transform: rotate(90deg); } -:is(.admonition):is(.admonish-note) { +:is(.admonition):is(.note) { border-color: #448aff; } -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title) { +:is(.note) > :is(.admonition-title, summary) { background-color: rgba(68, 138, 255, 0.1); } -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title)::before { +:is(.note) > :is(.admonition-title, summary)::before { background-color: #448aff; - mask-image: var(--md-admonition-icon--admonish-note); - -webkit-mask-image: var(--md-admonition-icon--admonish-note); + mask-image: var(--md-admonition-icon--note); + -webkit-mask-image: var(--md-admonition-icon--note); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-abstract, .admonish-summary, .admonish-tldr) { +:is(.admonition):is(.abstract, .summary, .tldr) { border-color: #00b0ff; } -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title) { +:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary) { background-color: rgba(0, 176, 255, 0.1); } -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title)::before { +:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary)::before { background-color: #00b0ff; - mask-image: var(--md-admonition-icon--admonish-abstract); - -webkit-mask-image: var(--md-admonition-icon--admonish-abstract); + mask-image: var(--md-admonition-icon--abstract); + -webkit-mask-image: var(--md-admonition-icon--abstract); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-info, .admonish-todo) { +:is(.admonition):is(.info, .todo) { border-color: #00b8d4; } -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title) { +:is(.info, .todo) > :is(.admonition-title, summary) { background-color: rgba(0, 184, 212, 0.1); } -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title)::before { +:is(.info, .todo) > :is(.admonition-title, summary)::before { background-color: #00b8d4; - mask-image: var(--md-admonition-icon--admonish-info); - -webkit-mask-image: var(--md-admonition-icon--admonish-info); + mask-image: var(--md-admonition-icon--info); + -webkit-mask-image: var(--md-admonition-icon--info); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-tip, .admonish-hint, .admonish-important) { +:is(.admonition):is(.tip, .hint, .important) { border-color: #00bfa5; } -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title) { +:is(.tip, .hint, .important) > :is(.admonition-title, summary) { background-color: rgba(0, 191, 165, 0.1); } -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title)::before { +:is(.tip, .hint, .important) > :is(.admonition-title, summary)::before { background-color: #00bfa5; - mask-image: var(--md-admonition-icon--admonish-tip); - -webkit-mask-image: var(--md-admonition-icon--admonish-tip); + mask-image: var(--md-admonition-icon--tip); + -webkit-mask-image: var(--md-admonition-icon--tip); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-success, .admonish-check, .admonish-done) { +:is(.admonition):is(.success, .check, .done) { border-color: #00c853; } -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title) { +:is(.success, .check, .done) > :is(.admonition-title, summary) { background-color: rgba(0, 200, 83, 0.1); } -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title)::before { +:is(.success, .check, .done) > :is(.admonition-title, summary)::before { background-color: #00c853; - mask-image: var(--md-admonition-icon--admonish-success); - -webkit-mask-image: var(--md-admonition-icon--admonish-success); + mask-image: var(--md-admonition-icon--success); + -webkit-mask-image: var(--md-admonition-icon--success); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-question, .admonish-help, .admonish-faq) { +:is(.admonition):is(.question, .help, .faq) { border-color: #64dd17; } -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title) { +:is(.question, .help, .faq) > :is(.admonition-title, summary) { background-color: rgba(100, 221, 23, 0.1); } -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title)::before { +:is(.question, .help, .faq) > :is(.admonition-title, summary)::before { background-color: #64dd17; - mask-image: var(--md-admonition-icon--admonish-question); - -webkit-mask-image: var(--md-admonition-icon--admonish-question); + mask-image: var(--md-admonition-icon--question); + -webkit-mask-image: var(--md-admonition-icon--question); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-warning, .admonish-caution, .admonish-attention) { +:is(.admonition):is(.warning, .caution, .attention) { border-color: #ff9100; } -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title) { +:is(.warning, .caution, .attention) > :is(.admonition-title, summary) { background-color: rgba(255, 145, 0, 0.1); } -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title)::before { +:is(.warning, .caution, .attention) > :is(.admonition-title, summary)::before { background-color: #ff9100; - mask-image: var(--md-admonition-icon--admonish-warning); - -webkit-mask-image: var(--md-admonition-icon--admonish-warning); + mask-image: var(--md-admonition-icon--warning); + -webkit-mask-image: var(--md-admonition-icon--warning); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-failure, .admonish-fail, .admonish-missing) { +:is(.admonition):is(.failure, .fail, .missing) { border-color: #ff5252; } -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title) { +:is(.failure, .fail, .missing) > :is(.admonition-title, summary) { background-color: rgba(255, 82, 82, 0.1); } -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title)::before { +:is(.failure, .fail, .missing) > :is(.admonition-title, summary)::before { background-color: #ff5252; - mask-image: var(--md-admonition-icon--admonish-failure); - -webkit-mask-image: var(--md-admonition-icon--admonish-failure); + mask-image: var(--md-admonition-icon--failure); + -webkit-mask-image: var(--md-admonition-icon--failure); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-danger, .admonish-error) { +:is(.admonition):is(.danger, .error) { border-color: #ff1744; } -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title) { +:is(.danger, .error) > :is(.admonition-title, summary) { background-color: rgba(255, 23, 68, 0.1); } -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title)::before { +:is(.danger, .error) > :is(.admonition-title, summary)::before { background-color: #ff1744; - mask-image: var(--md-admonition-icon--admonish-danger); - -webkit-mask-image: var(--md-admonition-icon--admonish-danger); + mask-image: var(--md-admonition-icon--danger); + -webkit-mask-image: var(--md-admonition-icon--danger); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-bug) { +:is(.admonition):is(.bug) { border-color: #f50057; } -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title) { +:is(.bug) > :is(.admonition-title, summary) { background-color: rgba(245, 0, 87, 0.1); } -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title)::before { +:is(.bug) > :is(.admonition-title, summary)::before { background-color: #f50057; - mask-image: var(--md-admonition-icon--admonish-bug); - -webkit-mask-image: var(--md-admonition-icon--admonish-bug); + mask-image: var(--md-admonition-icon--bug); + -webkit-mask-image: var(--md-admonition-icon--bug); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-example) { +:is(.admonition):is(.example) { border-color: #7c4dff; } -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title) { +:is(.example) > :is(.admonition-title, summary) { background-color: rgba(124, 77, 255, 0.1); } -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title)::before { +:is(.example) > :is(.admonition-title, summary)::before { background-color: #7c4dff; - mask-image: var(--md-admonition-icon--admonish-example); - -webkit-mask-image: var(--md-admonition-icon--admonish-example); + mask-image: var(--md-admonition-icon--example); + -webkit-mask-image: var(--md-admonition-icon--example); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; -webkit-mask-repeat: no-repeat; } -:is(.admonition):is(.admonish-quote, .admonish-cite) { +:is(.admonition):is(.quote, .cite) { border-color: #9e9e9e; } -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title) { +:is(.quote, .cite) > :is(.admonition-title, summary) { background-color: rgba(158, 158, 158, 0.1); } -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title)::before { +:is(.quote, .cite) > :is(.admonition-title, summary)::before { background-color: #9e9e9e; - mask-image: var(--md-admonition-icon--admonish-quote); - -webkit-mask-image: var(--md-admonition-icon--admonish-quote); + mask-image: var(--md-admonition-icon--quote); + -webkit-mask-image: var(--md-admonition-icon--quote); mask-repeat: no-repeat; -webkit-mask-repeat: no-repeat; mask-size: contain; @@ -327,8 +340,7 @@ details[open].admonition > summary.admonition-title::after { background-color: var(--sidebar-bg); } -.ayu :is(.admonition), -.coal :is(.admonition) { +.ayu :is(.admonition), .coal :is(.admonition) { background-color: var(--theme-hover); } diff --git a/documentation/docs/src/architecture/traffic-flow.md b/documentation/docs/src/architecture/traffic-flow.md index 09a2501abd..863a03f577 100644 --- a/documentation/docs/src/architecture/traffic-flow.md +++ b/documentation/docs/src/architecture/traffic-flow.md @@ -5,7 +5,7 @@ When you send data across the internet, it can be recorded by a wide range of ob Even if the content of a network request is encrypted, observers can still see that data was transmitted, its size, frequency of transmission, and gather metadata from unencrypted parts of the data (such as IP routing information). Adversaries may then combine all the leaked information to probabilistically de-anonymize users. -The Nym mixnet provides very strong security guarantees against this sort of surveillance. It _packetizes_ and _mixes_ together IP traffic from many users inside the _mixnet_. +The Nym mixnet provides very strong security guarantees against this sort of surveillance. It _packetises_ and _mixes_ together IP traffic from many users inside the _mixnet_. > If you're into comparisons, the Nym mixnet is conceptually similar to other systems such as Tor, but provides improved protections against end-to-end timing attacks which can de-anonymize users. When Tor was first fielded, in 2002, those kinds of attacks were regarded as science fiction. But the future is now here. @@ -69,7 +69,7 @@ From your Nym client, your encrypted traffic is sent to: Whatever is on the 'other side' of the mixnet from your client, all traffic will travel this way through the mixnet. If you are sending traffic to a service external to Nym (such as a chat application's servers) then your traffic will be sent from the recieving Nym client to an application that will proxy it 'out' of the mixnet to these servers, shielding your metadata from them. P2P (peer-to-peer) applications, unlike the majority of apps, might want to keep all of their traffic entirely 'within' the mixnet, as they don't have to necessarily make outbound network requests to application servers. They would simply have their local application code communicate with their Nym clients, and not forward traffic anywhere 'outside' of the mixnet. ## Acks & Package Retransmission -Whenever a hop is completed, the recieving node will send back an acknowledgement ('ack') so that the sending node knows that the packet was recieved. If it does not recieve an ack after sending, it will resend the packet, as it assumes that the packet was dropped for some reason. This is done under the hood by the binaries themselves, and is never something that developers and node operators have to worry about dealing with themselves. +Whenever a hop is completed, the receiving node will send back an acknowledgement ('ack') so that the sending node knows that the packet was received. If it does not receive an ack after sending, it will resend the packet, as it assumes that the packet was dropped for some reason. This is done under the hood by the binaries themselves, and is never something that developers and node operators have to worry about dealing with themselves. Packet retransmission means that if a client sends 100 packets to a gateway, but only receives an acknowledgement ('ack') for 95 of them, it will resend those 5 packets to the gateway again, to make sure that all packets are received. All nodes in the mixnet support packet retransmission. From aa7dd1ecf96d10f6f90739eea694ea8bee143787 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:24:46 +0100 Subject: [PATCH 21/32] admonish plugin upgrade --- documentation/docs/book.toml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/documentation/docs/book.toml b/documentation/docs/book.toml index 093c35eea0..a11f82cbbd 100644 --- a/documentation/docs/book.toml +++ b/documentation/docs/book.toml @@ -6,6 +6,9 @@ language = "en" multilingual = false # for the moment - ideally work on chinese, brazillian, spanish next src = "src" +[rust] +edition = "2018" + ################# # PREPROCESSORS # ################# @@ -42,7 +45,7 @@ turn-off = true [preprocessor.admonish] command = "mdbook-admonish" -assets_version = "3.0.0" # do not edit: managed by `mdbook-admonish install` +assets_version = "2.0.1" # do not edit: managed by `mdbook-admonish install` # variables preprocessor: import variables into files # https://gitlab.com/tglman/mdbook-variables/ From bc21fa3a7ed611c4a65f5772861f93de86de190f Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:25:10 +0100 Subject: [PATCH 22/32] fix broken imports --- documentation/docs/src/sdk/rust/examples/credential.md | 6 +++--- documentation/docs/src/sdk/rust/examples/custom-network.md | 4 ++-- documentation/docs/src/sdk/rust/examples/keys.md | 2 +- documentation/docs/src/sdk/rust/examples/simple.md | 2 +- documentation/docs/src/sdk/rust/examples/socks.md | 4 ++-- documentation/docs/src/sdk/rust/examples/split-send.md | 2 +- documentation/docs/src/sdk/rust/examples/storage.md | 2 +- documentation/docs/src/sdk/rust/examples/surbs.md | 6 +++--- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/documentation/docs/src/sdk/rust/examples/credential.md b/documentation/docs/src/sdk/rust/examples/credential.md index d0fe29bbbd..e62cfb454a 100644 --- a/documentation/docs/src/sdk/rust/examples/credential.md +++ b/documentation/docs/src/sdk/rust/examples/credential.md @@ -1,9 +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. +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}} +{{#include ../../../../../../sdk/rust/nym-sdk/examples/bandwidth.rs}} ``` -You can read more about Coconut credentials (also referred to as `zk-Nym`) [here](../../coconut.md). +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 index 0ad226f953..ae0f145a3b 100644 --- a/documentation/docs/src/sdk/rust/examples/custom-network.md +++ b/documentation/docs/src/sdk/rust/examples/custom-network.md @@ -7,12 +7,12 @@ There are two ways to do this: 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}} +{{#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}} +{{#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 index 6e2f66d986..84746dcfd6 100644 --- a/documentation/docs/src/sdk/rust/examples/keys.md +++ b/documentation/docs/src/sdk/rust/examples/keys.md @@ -2,7 +2,7 @@ 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}} +{{#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. diff --git a/documentation/docs/src/sdk/rust/examples/simple.md b/documentation/docs/src/sdk/rust/examples/simple.md index b3d5f9d268..20872ce96b 100644 --- a/documentation/docs/src/sdk/rust/examples/simple.md +++ b/documentation/docs/src/sdk/rust/examples/simple.md @@ -4,5 +4,5 @@ Lets look at a very simple example of how you can import and use the websocket c 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}} +{{#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 index 5e81780e2e..de027e9011 100644 --- a/documentation/docs/src/sdk/rust/examples/socks.md +++ b/documentation/docs/src/sdk/rust/examples/socks.md @@ -1,10 +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`): +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}} +{{#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 index 32db90c17c..6b7cf69789 100644 --- a/documentation/docs/src/sdk/rust/examples/split-send.md +++ b/documentation/docs/src/sdk/rust/examples/split-send.md @@ -2,5 +2,5 @@ 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}} +{{#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 index 4d430f36ac..bc68bca9ff 100644 --- a/documentation/docs/src/sdk/rust/examples/storage.md +++ b/documentation/docs/src/sdk/rust/examples/storage.md @@ -2,5 +2,5 @@ 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}} +{{#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 index 013b2e82e4..404d74ba1d 100644 --- a/documentation/docs/src/sdk/rust/examples/surbs.md +++ b/documentation/docs/src/sdk/rust/examples/surbs.md @@ -4,13 +4,13 @@ Both functions used to send messages through the mixnet (`send_message` and `sen 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}} +{{#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). +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}} +{{#include ../../../../../../sdk/rust/nym-sdk/examples/surb-reply.rs}} ``` From 2334109721814bd170e8dc9126b83ac32baebf55 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:25:37 +0100 Subject: [PATCH 23/32] tweak --- documentation/docs/src/sdk/rust/examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/src/sdk/rust/examples.md b/documentation/docs/src/sdk/rust/examples.md index e612a7d59d..648c32fa0d 100644 --- a/documentation/docs/src/sdk/rust/examples.md +++ b/documentation/docs/src/sdk/rust/examples.md @@ -8,5 +8,5 @@ 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. +An example `Cargo.toml` file can be found [here](examples/cargo.md). From 9a592df4f0668df24cbb0fef66142d969189d7e7 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:26:07 +0100 Subject: [PATCH 24/32] updated import info --- documentation/docs/src/sdk/rust/rust.md | 18 +++++++++++++++++- .../docs/src/sdk/rust/troubleshooting.md | 5 +++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/documentation/docs/src/sdk/rust/rust.md b/documentation/docs/src/sdk/rust/rust.md index 2ce11c4ed3..3062e1ff32 100644 --- a/documentation/docs/src/sdk/rust/rust.md +++ b/documentation/docs/src/sdk/rust/rust.md @@ -21,11 +21,27 @@ The SDK is still somewhat a work in progress: interfaces are fairly stable but s ### Installation The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: -TODO add note on branch import for stability - `master` should be last release ```toml nym-sdk = { git = "https://github.com/nymtech/nym" } ``` +By default the above command will import the current `HEAD` of the default branch, which in our case is `develop`. Assuming instead you wish to pull in another branch (e.g. `master` or a particular release) you can specify this like so: + +```toml +# importing HEAD of master branch +nym-sdk = { git = "https://github.com/nymtech/nym", branch = "master" } +# importing HEAD of the third release of 2023, codename 'kinder' +nym-sdk = { git = "https://github.com/nymtech/nym", branch = "release/2023.3-kinder" } +``` + +You can also define a particular git commit to use as your import like so: + +```toml +nym-sdk = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } +``` + +Since the `HEAD` of `master` is always the most recent release, we recommend developers use that for their imports, unless they have a reason to pull in a specific historic version of the code. + ### Generate Crate Docs In order to generate the crate docs run `cargo doc --open` from `nym/sdk/rust/nym-sdk/` diff --git a/documentation/docs/src/sdk/rust/troubleshooting.md b/documentation/docs/src/sdk/rust/troubleshooting.md index c8de2e5e37..51676ff6ec 100644 --- a/documentation/docs/src/sdk/rust/troubleshooting.md +++ b/documentation/docs/src/sdk/rust/troubleshooting.md @@ -1,3 +1,4 @@ # Troubleshooting -TODO note on poisson dance and not immediately killing client process -TODO note on listening for non-empty messages and point towards helpers +TODO note on 'task client is being dropped' +TODO note on poisson dance and not immediately killing client process +TODO note on listening for non-empty messages and point towards helpers From 082886ab19e52ea9824d3ca9c1272c67e6d81977 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 10:35:57 +0100 Subject: [PATCH 25/32] removed todo - checked dependency versioning --- documentation/docs/src/sdk/rust/examples/cargo.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/documentation/docs/src/sdk/rust/examples/cargo.md b/documentation/docs/src/sdk/rust/examples/cargo.md index 4c96e05fc5..e425e124ed 100644 --- a/documentation/docs/src/sdk/rust/examples/cargo.md +++ b/documentation/docs/src/sdk/rust/examples/cargo.md @@ -1,7 +1,6 @@ # 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" @@ -17,13 +16,13 @@ tokio = { version = "1.24.1", features = ["rt-multi-thread", "macros"] } 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" } +nym-sdk = { git = "https://github.com/nymtech/nym", branch = "master" } +nym-sphinx-addressing = { git = "https://github.com/nymtech/nym", branch = "master" } +nym-bin-common = { git = "https://github.com/nymtech/nym", branch = "master" } +nym-sphinx-anonymous-replies = { git = "https://github.com/nymtech/nym", branch = "master" } # 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" } +nym-validator-client = { git = "https://github.com/nymtech/nym", branch = "master" } # If you're building an app with a client and server / serivce this might be a useful structure for your repo [[bin]] From 72553623a76ff15a0b4d040af6dcc90aaee45dab Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 13:10:05 +0100 Subject: [PATCH 26/32] first pass at troubleshooting doc --- .../docs/src/sdk/rust/troubleshooting.md | 117 +++++++++++++++++- 1 file changed, 114 insertions(+), 3 deletions(-) diff --git a/documentation/docs/src/sdk/rust/troubleshooting.md b/documentation/docs/src/sdk/rust/troubleshooting.md index 51676ff6ec..458a4eaab4 100644 --- a/documentation/docs/src/sdk/rust/troubleshooting.md +++ b/documentation/docs/src/sdk/rust/troubleshooting.md @@ -1,4 +1,115 @@ # Troubleshooting -TODO note on 'task client is being dropped' -TODO note on poisson dance and not immediately killing client process -TODO note on listening for non-empty messages and point towards helpers +Below are several common issues or questions you may have. + +If you come across something that isn't explained here, [PRs are welcome](https://github.com/nymtech/nym/issues/new/choose). + +## Verbose `task client is being dropped` logging +### On client shutdown (expected) +If this is happening at the end of your code when disconnecting your client, this is fine; we just have a verbose client! When calling `client.disconnect().await` this is simply informing you that the client is shutting down. + +On client shutdown / disconnect this is to be expected - this can be seen in many of the code examples as well. We use the [`nym_bin_common::logging`](https://github.com/nymtech/nym/blob/develop/common/bin-common/src/logging/mod.rs) import to set logging in our example code. This defaults to `INFO` level. + +If you wish to quickly lower the verbosity of your client process logs when developing you can prepend your command with `RUST_LOG=`. + +If you want to run the `builder.rs` example with only `WARN` level logging and below: + +```sh +cargo run --example builder +``` + +Becomes: + +```sh +RUST_LOG=warn cargo run --example builder +``` + +You can also make the logging _more_ verbose with: + +```sh +RUST_LOG=debug cargo run --example builder +``` + +### Not on client shutdown (unexpected) +If this is happening unexpectedly then you might be shutting your client process down too early. See the [accidentally killing your client process](#accidentally-killing-your-client-process-too-early) below for possible explanations and how to fix this issue. + +[//]: # (TODO note on poisson dance and not immediately killing client process) +## Accidentally killing your client process too early +If you are seeing either of the following errors when trying to run a client, specifically sending a message, then you may be accidentally killing your client process. + +```sh + 2023-11-02T10:31:03.930Z INFO TaskClient-BaseNymClient-real_traffic_controller-ack_control-action_controller > the task client is getting dropped + 2023-11-02T10:31:04.625Z INFO TaskClient-BaseNymClient-received_messages_buffer-request_receiver > the task client is getting dropped + 2023-11-02T10:31:04.626Z DEBUG nym_client_core::client::real_messages_control::acknowledgement_control::input_message_listener > InputMessageListener: Exiting + 2023-11-02T10:31:04.626Z INFO TaskClient-BaseNymClient-real_traffic_controller-ack_control-input_message_listener > the task client is getting dropped + 2023-11-02T10:31:04.626Z INFO TaskClient-BaseNymClient-real_traffic_controller-reply_control > the task client is getting dropped + 2023-11-02T10:31:04.626Z DEBUG nym_client_core::client::real_messages_control > The reply controller has finished execution! + 2023-11-02T10:31:04.626Z DEBUG nym_client_core::client::real_messages_control::acknowledgement_control > The input listener has finished execution! + 2023-11-02T10:31:04.626Z INFO nym_task::manager > All registered tasks succesfully shutdown +``` + +```sh + 2023-11-02T11:22:08.408Z ERROR TaskClient-BaseNymClient-topology_refresher > Assuming this means we should shutdown... + 2023-11-02T11:22:08.408Z ERROR TaskClient-BaseNymClient-mix_traffic_controller > Polling shutdown failed: channel closed + 2023-11-02T11:22:08.408Z INFO TaskClient-BaseNymClient-gateway_transceiver-child > the task client is getting dropped + 2023-11-02T11:22:08.408Z ERROR TaskClient-BaseNymClient-mix_traffic_controller > Assuming this means we should shutdown... +thread 'tokio-runtime-worker' panicked at 'action control task has died: TrySendError { kind: Disconnected }', /home/.local/share/cargo/git/checkouts/nym-fbd2f6ea2e760da9/a800cba/common/client-core/src/client/real_messages_control/message_handler.rs:634:14 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace + 2023-11-02T11:22:08.477Z INFO TaskClient-BaseNymClient-real_traffic_controller-ack_control-input_message_listener > the task client is getting dropped + 2023-11-02T11:22:08.477Z ERROR TaskClient-BaseNymClient-real_traffic_controller-ack_control-input_message_listener > Polling shutdown failed: channel closed + 2023-11-02T11:22:08.477Z ERROR TaskClient-BaseNymClient-real_traffic_controller-ack_control-input_message_listener > Assuming this means we should shutdown... +``` + +Using the following piece of code as an example: + +```rust +use nym_sdk::mixnet::{MixnetClient, MixnetMessageSender, Recipient}; +use clap::Parser; + +#[derive(Debug, Clone, Parser)] +enum Opts { + Client { + recipient: Recipient + } +} + +#[tokio::main] +async fn main() { + let opts: Opts = Parser::parse(); + nym_bin_common::logging::setup_logging(); + + let mut nym_client = MixnetClient::connect_new().await.expect("Could not build Nym client"); + + match opts { + Opts::Client { recipient } => { + nym_client.send_plain_message(recipient, "some message string").await.expect("send failed"); + } + } +} +``` + +This is a simplified snippet of code for sending a simple hardcoded message with the following command: + +```sh +cargo run client +``` + +You might assume that `send`-ing your message would _just work_ as `nym_client.send_plain_message()` is an async function; you might expect that the client will block until the message is actually sent into the mixnet, then shutdown. + +However, this is not true. + +**This will only block until the message is put into client's internal queue**. Therefore in the above example, the client is being shut down before the message is _actually sent to the mixnet_; after being placed in the client's internal queue, there is still work to be done under the hood, such as route encrypting the message and placing it amongst the stream of cover traffic. + +The simple solution? Make sure the program/client stays active, either by calling `sleep`, or listening out for new messages. As sending a one-shot message without listening out for a response is likely not what you'll be doing, then you will be then awaiting a response (see the [message helpers page](message-helpers.md) for an example of this). + +Furthermore, you should always **manually disconnect your client** with `client.disconnect().await` as seen in the code examples. This is important as your client is writing to a local DB and dealing with SURB storage. + +## Client receives empty messages when listening for response +If you are sending out a message, it makes sense for your client to then listen out for incoming messages; this would probably be the reply you get from the service you've sent a message to. + +You might however be receiving messages without data attached to them / empty payloads. This is most likely because your client is receiving a message containing a [SURB request](https://nymtech.net/docs/architecture/traffic-flow.html#private-replies-using-surbs) - a SURB requesting more SURB packets to be sent to the service, in order for them to have enough packets (with a big enough overall payload) to split the entire response to your initial request across. + +Whether the `data` of a SURB request being empty is a feature or a bug is to be decided - there is some discussion surrounding whether we can use SURB requests to send additional data to streamline the process of sending large replies across the mixnet. + +You can find a few helper functions [here](message-helpers.md) to help deal with this issue in the meantime. + +> If you can think of a more succinct or different way of handling this do reach out - we're happy to hear other opinions \ No newline at end of file From a4bb4ec6c52c78ddacbefbaf2b0b9e333df01198 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 13:19:54 +0100 Subject: [PATCH 27/32] first pass at helper messages --- documentation/docs/src/sdk/rust/message-helpers.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/documentation/docs/src/sdk/rust/message-helpers.md b/documentation/docs/src/sdk/rust/message-helpers.md index 478e12a7ab..d783cd2e25 100644 --- a/documentation/docs/src/sdk/rust/message-helpers.md +++ b/documentation/docs/src/sdk/rust/message-helpers.md @@ -1,2 +1,10 @@ # Message Helpers -TODO pull in dealing with incoming non-empty messages and fn()s from tutorial \ No newline at end of file + +## Handling incoming messages +As seen in the [Chain querier tutorial](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/) when listening out for a response to a sent message (e.g. if you have sent a request to a service, and are awaiting the response) you will want to await [non-empty messages (more info on this here)](troubleshooting.md#client-receives-empty-messages-when-listening-for-response). This can be done with something like the helper functions [here](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/src/lib.rs#L71). + +## Iterating over incoming messages +It is recommended to use `nym_client.next().await` over `nym_client.wait_for_messages().await` as the latter will return one message at a time which will probably be easier to deal with. See the [parallel send and receive example](https://github.com/nymtech/nym/blob/2993e85c7a17bd5b68171751a48b731b2394ee03/sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs#L23-L25) for an example. + +## Remember to disconnect your client +You should always **manually disconnect your client** with `client.disconnect().await` as seen in the code examples. This is important as your client is writing to a local DB and dealing with SURB storage. From bcfea21501392732a44bcc6537d6a538ae717553 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 17:13:37 +0100 Subject: [PATCH 28/32] upgraded mdbook-admonish version --- .github/workflows/ci-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml index b503516e70..780e82bdb1 100644 --- a/.github/workflows/ci-docs.yml +++ b/.github/workflows/ci-docs.yml @@ -32,7 +32,7 @@ jobs: - name: Install mdbook plugins run: | cargo install --vers "=0.2.2" mdbook-variables && cargo install \ - --vers "^1.8.0" mdbook-admonish --force && cargo install --vers \ + --vers "^3.0.0" mdbook-admonish --force && cargo install --vers \ "^0.1.2" mdbook-last-changed && cargo install --vers "^0.1.2" mdbook-theme \ && cargo install --vers "^0.7.7" mdbook-linkcheck \ # && cd documentation \ From e9a0c6f8d0011caa0c29b3fd1e0f7d0ade02f555 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 17:13:55 +0100 Subject: [PATCH 29/32] added code example to helpers --- .../docs/src/sdk/rust/message-helpers.md | 62 ++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/documentation/docs/src/sdk/rust/message-helpers.md b/documentation/docs/src/sdk/rust/message-helpers.md index d783cd2e25..e7ce201fa7 100644 --- a/documentation/docs/src/sdk/rust/message-helpers.md +++ b/documentation/docs/src/sdk/rust/message-helpers.md @@ -1,7 +1,67 @@ # Message Helpers ## Handling incoming messages -As seen in the [Chain querier tutorial](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/) when listening out for a response to a sent message (e.g. if you have sent a request to a service, and are awaiting the response) you will want to await [non-empty messages (more info on this here)](troubleshooting.md#client-receives-empty-messages-when-listening-for-response). This can be done with something like the helper functions [here](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/src/lib.rs#L71). +As seen in the [Chain querier tutorial](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/) when listening out for a response to a sent message (e.g. if you have sent a request to a service, and are awaiting the response) you will want to await [non-empty messages (if you don't know why, read the info on this here)](troubleshooting.md#client-receives-empty-messages-when-listening-for-response). This can be done with something like the helper functions [here](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/src/lib.rs#L71): + +```rust +use nym_sdk::mixnet::ReconstructedMessage; + +pub async fn wait_for_non_empty_message( + client: &mut MixnetClient, +) -> anyhow::Result { + while let Some(mut new_message) = client.wait_for_messages().await { + if !new_message.is_empty() { + return Ok(new_message.pop().unwrap()); + } + } + + bail!("did not receive any non-empty message") +} + +pub fn handle_response(message: ReconstructedMessage) -> anyhow::Result { + ResponseTypes::try_deserialize(message.message) +} + +// Note here that the only difference between handling a request and a response +// is that a request will have a sender_tag to parse. +// +// This is used for anonymous replies with SURBs. +pub fn handle_request( + message: ReconstructedMessage, +) -> anyhow::Result<(RequestTypes, Option)> { + let request = RequestTypes::try_deserialize(message.message)?; + Ok((request, message.sender_tag)) +} +``` + +The above helper functions are used as such by the client in tutorial example: it sends a message to the service (what the message is isn't important - just that your client has sent a message _somewhere_ and you are awaiting a response), waits for a _non_empty_ message, then handles it (then logs it - but you can do whatever you want, parse it, etc): + +```rust +// [snip] + +// Send serialised request to service via mixnet what is await-ed here is +// placing the message in the client's message queue, NOT the sending itself. +let _ = client + .send_message(sp_address, message.serialize(), Default::default()) + .await; + +// Await a non-empty message +let received = wait_for_non_empty_message(client).await?; + +// Handle the response received (the non-empty message awaited above) +let sp_response = handle_response(received)?; + +// Match JSON -> ResponseType +let res = match sp_response { + crate::ResponseTypes::Balance(response) => { + println!("{:#?}", response); + response.balance + } +}; + +// [snip] +``` +([repo code on Github here](https://github.com/nymtech/developer-tutorials/blob/0130ee5a61cd6801bdcfc84608b2a520b5392714/rust/chain-query-service/src/client.rs#L19)) ## Iterating over incoming messages It is recommended to use `nym_client.next().await` over `nym_client.wait_for_messages().await` as the latter will return one message at a time which will probably be easier to deal with. See the [parallel send and receive example](https://github.com/nymtech/nym/blob/2993e85c7a17bd5b68171751a48b731b2394ee03/sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs#L23-L25) for an example. From a9c40e76dc05be26d3b905eb63806146be1ddbc2 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 17:17:06 +0100 Subject: [PATCH 30/32] revert previous --- .github/workflows/ci-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml index 780e82bdb1..b503516e70 100644 --- a/.github/workflows/ci-docs.yml +++ b/.github/workflows/ci-docs.yml @@ -32,7 +32,7 @@ jobs: - name: Install mdbook plugins run: | cargo install --vers "=0.2.2" mdbook-variables && cargo install \ - --vers "^3.0.0" mdbook-admonish --force && cargo install --vers \ + --vers "^1.8.0" mdbook-admonish --force && cargo install --vers \ "^0.1.2" mdbook-last-changed && cargo install --vers "^0.1.2" mdbook-theme \ && cargo install --vers "^0.7.7" mdbook-linkcheck \ # && cd documentation \ From d151b907d1fa628e41dd5638822c5437d9718297 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 2 Nov 2023 23:36:14 +0100 Subject: [PATCH 31/32] added open proxies --- documentation/dev-portal/src/shipyard/infra.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documentation/dev-portal/src/shipyard/infra.md b/documentation/dev-portal/src/shipyard/infra.md index b5621f6ff6..21d4af6dba 100644 --- a/documentation/dev-portal/src/shipyard/infra.md +++ b/documentation/dev-portal/src/shipyard/infra.md @@ -3,3 +3,10 @@ If you are writing an application that requires sending messages through the mix If you are relying on network requesters then chances are that the IPs or domains your app relies on will not already be on the whitelist. Ideally, you would [run your own,](https://nymtech.net/operators/nodes/network-requester-setup.html) but we will also run a few nodes in ‘open proxy’ mode and share the addresses so that you can use them when beginning to develop. +## Node Details: +- NR1 + - Location: Singapore + - Nym Address: `FDeWfd8q686PWLXJDCqNJTCbydTk1KSux5HVftimsPyx.9XyThN4yh92eTMuLp1NvWicRZob8Ei5xpba9dvcMLxcN@9Byd9VAtyYMnbVAcqdoQxJnq76XEg2dbxbiF5Aa5Jj9J` +- NR2 + - Location: Frankfurt + - Nym Address: `BNypKaGiGY8GNRN4gpV95GcaVS8n7CrHuoZNgQ2ezqv2ACpaixzuaSzuMajVQj6aR7cbpbvp676tm21MiLbX1gni@678qVUJ21uwxZBhp3r56z7GRf6gMh3NYDHruTegPtgMf` \ No newline at end of file From 50c994d2edfce339d999f3b85ea67101f00aae2f Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Fri, 3 Nov 2023 00:19:33 +0100 Subject: [PATCH 32/32] fixed addr --- documentation/dev-portal/src/shipyard/infra.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/dev-portal/src/shipyard/infra.md b/documentation/dev-portal/src/shipyard/infra.md index 21d4af6dba..73c3afadb3 100644 --- a/documentation/dev-portal/src/shipyard/infra.md +++ b/documentation/dev-portal/src/shipyard/infra.md @@ -9,4 +9,4 @@ If you are relying on network requesters then chances are that the IPs or domain - Nym Address: `FDeWfd8q686PWLXJDCqNJTCbydTk1KSux5HVftimsPyx.9XyThN4yh92eTMuLp1NvWicRZob8Ei5xpba9dvcMLxcN@9Byd9VAtyYMnbVAcqdoQxJnq76XEg2dbxbiF5Aa5Jj9J` - NR2 - Location: Frankfurt - - Nym Address: `BNypKaGiGY8GNRN4gpV95GcaVS8n7CrHuoZNgQ2ezqv2ACpaixzuaSzuMajVQj6aR7cbpbvp676tm21MiLbX1gni@678qVUJ21uwxZBhp3r56z7GRf6gMh3NYDHruTegPtgMf` \ No newline at end of file + - Nym Address: `BNypKaGiGY8GNRN4gpV95GcaVS8n7CrHuoZNgQ2ezqv2.ACpaixzuaSzuMajVQj6aR7cbpbvp676tm21MiLbX1gni@678qVUJ21uwxZBhp3r56z7GRf6gMh3NYDHruTegPtgMf` \ No newline at end of file