diff --git a/.github/workflows/cd-docs.yml b/.github/workflows/cd-docs.yml index 97150e29c8..07d8483839 100644 --- a/.github/workflows/cd-docs.yml +++ b/.github/workflows/cd-docs.yml @@ -6,20 +6,27 @@ on: jobs: build: runs-on: arc-ubuntu-20.04 + defaults: + run: + working-directory: documentation/docs steps: - uses: actions/checkout@v4 - name: Install Dependencies (Linux) run: sudo apt-get update && sudo apt-get install -y build-essential curl wget libssl-dev libudev-dev squashfs-tools protobuf-compiler git python3 && sudo apt-get update --fix-missing - name: Install pip3 - run: sudo apt install -y python3-pip + run: sudo apt install -y python3-pip - name: Install Python3 modules run: sudo pip3 install pandas tabulate - name: Install rsync run: sudo apt-get install rsync - uses: rlespinasse/github-slug-action@v3.x + - name: Setup pnpm + uses: pnpm/action-setup@v4.0.0 + with: + version: 9 - uses: actions/setup-node@v4 with: - node-version: 18 + node-version: 20 - name: Install Rust stable uses: actions-rs/toolchain@v1 with: @@ -29,33 +36,13 @@ jobs: with: command: build args: --workspace --release - - name: Install mdbook and plugins - run: cd documentation && ./install_mdbook_deps.sh - - name: Remove existing Nym config directory (`~/.nym/`) - run: cd documentation && ./remove_existing_config.sh - continue-on-error: false -# This is the original flow -# - name: Build all projects in documentation/ & move to ~/dist/docs/ -# run: cd documentation && ./build_all_to_dist.sh - -# This is a workaround replacement which builds on the last working commit b332a6b55668f60988e36961f3f62a794ba82ddb and then on current branch - - name: Save current branch to ~/current_branch - run: git rev-parse --abbrev-ref HEAD > ~/current_branch - - name: Git pull, reset & switch to b332a6b55668f60988e36961f3f62a794ba82ddb - run: git pull && git reset --hard && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb - - name: Build all projects in documentation/ & move to ~/dist/docs/ from b332a6b55668f60988e36961f3f62a794ba82ddb - run: cd documentation && ./build_all_to_dist.sh - - name: Switch to current branch - run: git checkout $echo "$(cat ~/current_branch)" - - name: Build all projects in documentation/ & move to ~/dist/docs/ on current branch - run: cd documentation && ./build_all_to_dist.sh && rm ~/current_branch - -# End of replacemet - - - name: Post process - run: cd documentation && ./post_process.sh - continue-on-error: false + - name: Install project dependencies + run: pnpm i + - name: Build project + run: pnpm run build + - name: Move files to /dist/ + run: ../scripts/move-to-dist.sh - name: Create Vercel project file uses: mobiledevops/secret-to-file-action@v1 diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml index 602df75b44..307df47733 100644 --- a/.github/workflows/ci-docs.yml +++ b/.github/workflows/ci-docs.yml @@ -3,28 +3,35 @@ name: ci-docs on: workflow_dispatch: push: - branches-ignore: master + branches-ignore: [master] paths: - - 'documentation/docs/**' - - '.github/workflows/ci-docs.yml' + - "documentation/docs/**" + - ".github/workflows/ci-docs.yml" jobs: build: runs-on: arc-ubuntu-20.04 + defaults: + run: + working-directory: documentation/docs steps: - uses: actions/checkout@v4 - name: Install Dependencies (Linux) run: sudo apt-get update && sudo apt-get install -y build-essential curl wget libssl-dev libudev-dev squashfs-tools protobuf-compiler git python3 && sudo apt-get update --fix-missing - name: Install pip3 - run: sudo apt install -y python3-pip + run: sudo apt install -y python3-pip - name: Install Python3 modules run: sudo pip3 install pandas tabulate - name: Install rsync run: sudo apt-get install rsync - uses: rlespinasse/github-slug-action@v3.x + - name: Setup pnpm + uses: pnpm/action-setup@v4.0.0 + with: + version: 9 - uses: actions/setup-node@v4 with: - node-version: 18 + node-version: 20 - name: Install Rust stable uses: actions-rs/toolchain@v1 with: @@ -34,30 +41,13 @@ jobs: with: command: build args: --workspace --release - - name: Install mdbook and plugins - run: cd documentation && ./install_mdbook_deps.sh - - name: Remove existing Nym config directory (`~/.nym/`) - run: cd documentation && ./remove_existing_config.sh - continue-on-error: false - -# This is the original flow -# - name: Build all projects in documentation/ & move to ~/dist/docs/ -# run: cd documentation && ./build_all_to_dist.sh - -# This is a workaround replacement which builds on the last working commit b332a6b55668f60988e36961f3f62a794ba82ddb and then on current branch - - name: Save current branch to ~/current_branch - run: git rev-parse --abbrev-ref HEAD > ~/current_branch - - name: Git pull, reset & switch to b332a6b55668f60988e36961f3f62a794ba82ddb - run: git pull && git reset --hard && git checkout b332a6b55668f60988e36961f3f62a794ba82ddb - - name: Build all projects in documentation/ & move to ~/dist/docs/ from b332a6b55668f60988e36961f3f62a794ba82ddb - run: cd documentation && ./build_all_to_dist.sh - - - name: Switch to current branch - run: git checkout $echo "$(cat ~/current_branch)" - - name: Build all projects in documentation/ & move to ~/dist/docs/ on current branch - run: cd documentation && ./build_all_to_dist.sh && rm ~/current_branch -# End of replacemet + - name: Install project dependencies + run: pnpm i + - name: Build project + run: pnpm run build + - name: Move files to /dist/ + run: ../scripts/move-to-dist.sh - name: Deploy branch to CI www continue-on-error: true @@ -68,5 +58,5 @@ jobs: SOURCE: "dist/docs/" REMOTE_HOST: ${{ secrets.CI_WWW_REMOTE_HOST }} REMOTE_USER: ${{ secrets.CI_WWW_REMOTE_USER }} - TARGET: ${{ secrets.CI_WWW_REMOTE_TARGET }}/docs-${{ env.GITHUB_REF_SLUG }} + TARGET: ${{ secrets.CI_WWW_REMOTE_TARGET }}/docs-nextra-${{ env.GITHUB_REF_SLUG }} EXCLUDE: "/node_modules/" diff --git a/.github/workflows/ci-sdk-docs-typescript.yml b/.github/workflows/ci-sdk-docs-typescript.yml deleted file mode 100644 index 836150ad23..0000000000 --- a/.github/workflows/ci-sdk-docs-typescript.yml +++ /dev/null @@ -1,79 +0,0 @@ -name: ci-sdk-docs-typescript - -on: - pull_request: - paths: - - "sdk/typescript/**" - - "wasm/**" - - '.github/workflows/ci-sdk-docs-typescript.yml' - -jobs: - build: - runs-on: custom-linux - steps: - - uses: actions/checkout@v4 - - name: Install rsync - run: sudo apt-get install rsync - continue-on-error: true - - uses: rlespinasse/github-slug-action@v3.x - - uses: actions/setup-node@v4 - with: - node-version: 18.17 - - name: Install Rust stable - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - - name: Setup yarn - run: npm install -g yarn - - - name: Set up Go - uses: actions/setup-go@v5 - with: - go-version: '1.20' - - - name: Install wasm-pack - run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - - - name: Install wasm-opt - uses: ./.github/actions/install-wasm-opt - with: - version: '116' - - - name: Build branch WASM packages - run: make sdk-wasm-build - - - name: Install - run: yarn - - name: Build - run: yarn docs:prod:build - - name: Deploy branch to CI www (docs) - continue-on-error: true - uses: easingthemes/ssh-deploy@main - env: - SSH_PRIVATE_KEY: ${{ secrets.CI_WWW_SSH_PRIVATE_KEY }} - ARGS: "-rltgoDzvO --delete" - SOURCE: "dist/ts/" - REMOTE_HOST: ${{ secrets.CI_WWW_REMOTE_HOST }} - REMOTE_USER: ${{ secrets.CI_WWW_REMOTE_USER }} - TARGET: ${{ secrets.CI_WWW_REMOTE_TARGET }}/sdk-ts-docs-${{ env.GITHUB_REF_SLUG }} - EXCLUDE: "/dist/, /node_modules/" - - name: Matrix - Node Install - run: npm install - working-directory: .github/workflows/support-files - - name: Matrix - Send Notification - env: - NYM_NOTIFICATION_KIND: ts-packages - NYM_PROJECT_NAME: "sdk-ts-docs" - NYM_CI_WWW_BASE: "${{ secrets.NYM_CI_WWW_BASE }}/docs/sdk/typescript" - NYM_CI_WWW_LOCATION: "sdk-ts-docs-${{ env.GITHUB_REF_SLUG }}" - GIT_COMMIT_MESSAGE: "${{ github.event.head_commit.message }}" - GIT_BRANCH: "${GITHUB_REF##*/}" - IS_SUCCESS: "${{ job.status == 'success' }}" - MATRIX_SERVER: "${{ secrets.MATRIX_SERVER }}" - MATRIX_ROOM: "${{ secrets.MATRIX_ROOM }}" - MATRIX_USER_ID: "${{ secrets.MATRIX_USER_ID }}" - MATRIX_TOKEN: "${{ secrets.MATRIX_TOKEN }}" - MATRIX_DEVICE_ID: "${{ secrets.MATRIX_DEVICE_ID }}" - uses: docker://keybaseio/client:stable-node - with: - args: .github/workflows/support-files/notifications/entry_point.sh diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 1dba8fca5c..cf7f19aac1 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -4,7 +4,9 @@ on: pull_request: branches: - develop - - 'release/**' + - "release/**" + paths-ignore: + - "documentation/**" types: - labeled - unlabeled diff --git a/Cargo.lock b/Cargo.lock index 4c65c456de..f9a88a1aa5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -430,6 +430,14 @@ version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0" +[[package]] +name = "autodoc" +version = "0.1.0" +dependencies = [ + "env_logger 0.11.5", + "log", +] + [[package]] name = "axum" version = "0.6.20" @@ -2354,6 +2362,19 @@ dependencies = [ "termcolor", ] +[[package]] +name = "env_logger" +version = "0.11.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13fa619b91fb2381732789fc5de83b45675e882f66623b7d8cb4f643017018d" +dependencies = [ + "anstream", + "anstyle", + "env_filter", + "humantime 2.1.0", + "log", + ] + [[package]] name = "envy" version = "0.4.2" @@ -7467,7 +7488,7 @@ version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "926d36b9553851b8b0005f1275891b392ee4d2d833852c417ed025477350fb9d" dependencies = [ - "env_logger", + "env_logger 0.7.1", "log", ] diff --git a/Cargo.toml b/Cargo.toml index 7c323a3d31..7a9c4d623d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -98,6 +98,7 @@ members = [ "common/wasm/utils", "common/wireguard", "common/wireguard-types", + # "documentation/autodoc", "explorer-api", "explorer-api/explorer-api-requests", "explorer-api/explorer-client", @@ -203,7 +204,7 @@ axum-extra = "0.9.4" base64 = "0.22.1" bincode = "1.3.3" bip39 = { version = "2.0.0", features = ["zeroize"] } -bit-vec = "0.7.0" # can we unify those? +bit-vec = "0.7.0" # can we unify those? bitvec = "1.0.0" blake3 = "1.5.4" bloomfilter = "1.0.14" diff --git a/documentation/.gitignore b/documentation/.gitignore new file mode 100644 index 0000000000..95b579c427 --- /dev/null +++ b/documentation/.gitignore @@ -0,0 +1 @@ +todo.md diff --git a/documentation/README.md b/documentation/README.md index 66293cf92f..de968a158c 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,30 +1,53 @@ -# Documentation +# Nym Docs v2 + +This is v2 of the nym docs, condensed from various mdbooks projects that we had previously. + +These docs are hosted at [nymtech.net/docs](www.nymtech.net/docs). ## Doc projects -Each directory contains a readme with more information about running and contributing to the projects. Each is built with [`mdbook`](https://rust-lang.github.io/mdBook/index.html) - use `mdbook serve` to build and serve them (defaults to `localhost:3000`). -* `docs` contains technical documentation hosted at [https://nymtech.net/docs](https://nymtech.net/docs) -* `dev-portal` contains developer documentation hosted at [https://nymtech.net/developers](https://nymtech.net/developers) -* `operators` contains node setup and maintenance guides hosted at [https://nymtech.net/operators](https://nymtech.net/operators) +`docs/pages/` contains several subdirs, each hosting a subsection of the docs: +* `network` contains key concepts, cryptosystems, architecture. +* `developers` contains key concepts for developers, required architecture, and Rust/Typescript SDK docs. +* `operators` contains node setup and maintenance guides. + +## Local development +### Dependencies +Our `prebuild` script relies on the following: +- `python` +- `pip` +- [`pandas`](https://pandas.pydata.org/) +- [`tabulate`](https://pypi.org/project/tabulate/) +- `jq` + +Otherwise make sure to have `node` installed. -> If you are looking for the Typescript SDK documentation located at [sdk.nymtech.net](https://sdk.nymtech.net) this can be found in `../sdk/typescript/docs/` +### Serve Local (Hot Reload) +```sh +pnpm i +pnpm run dev +``` -## Contribution -* If you wish to add to the documentation please create a PR against this repo. -* If you are **adding a plugin dependency** make sure to also **add that to the list of plugins in `install_mdbook_deps.sh` line 12**. +Open `http://localhost:3000`. -## 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 +```sh +pnpm run build +``` -* The following scripts are used by the `ci-dev.yml` and `cd-dev.yml` scripts (located in `../.github/workflows/`): - * `build_all_to_dist.sh` is used for building all mdbook projects and moving the rendered html to `../dist/` to be rsynced with various servers. - * `install_mdbook_deps.sh` checks for an existing install of mdbook (and plugins), uninstalls them, and then installs them on a clean slate. This is to avoid weird dependency clashes if relying on an existing mdbook version. - * `post_process.sh` is used to post process CSS/image/href links for serving several mdbooks from a subdirectory. - * `removed_existing_config.sh` is used to check for existing nym client/node config files on the CI/CD server and remove it if it exists. This is to mitigate issues with `mdbook-cmdrun` where e.g. a node is already initialised, and the command fails. +The static output will be in `./out`; -## CI/CD -Deployment of the docs is partially automated and partially manual. -* `ci-docs.yml` will run on pushes to all branches **apart from `master`** -* `cd-docs.yml` must be run manually. This pushes to a staging branch which then must be manually promoted to production. +## Contribution +* If you wish to add to the documentation please create a PR against this repo, with a `patch` against `develop`. + +## Scripts +* There are several autogenerated command files for clients and binaries. These are generated with `generate:commands`, which runs the `autodoc` rust binary, moves the files to their required places, and then if there is an update, commits them to git. This is for remote deployments. +* Python scripts TODO + +### Autodoc +`autodoc` is a script that generates markdown files containing commands and their output (both command and `--help` output). For the moment the binaries and their commands are manually configured in the script. + +## CI/CD +TODO ## Licensing and copyright information This is a monorepo and components that make up Nym as a system are licensed individually, so for accurate information, please check individual files. @@ -36,4 +59,3 @@ As a general approach, licensing is as follows this pattern: * Nym applications and binaries are [GPL-3.0-only](https://www.gnu.org/licenses/) * Used libraries and different components are [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) or [MIT](https://mit-license.org/) - diff --git a/documentation/autodoc/.gitignore b/documentation/autodoc/.gitignore new file mode 100644 index 0000000000..6c2b344c84 --- /dev/null +++ b/documentation/autodoc/.gitignore @@ -0,0 +1 @@ +autodoc-generated-markdown/* diff --git a/documentation/autodoc/Cargo.toml b/documentation/autodoc/Cargo.toml new file mode 100644 index 0000000000..4ff2ee8761 --- /dev/null +++ b/documentation/autodoc/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "autodoc" +version = "0.1.0" +authors.workspace = true +repository.workspace = true +homepage.workspace = true +documentation.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +env_logger = "0.11.3" +log.workspace = true diff --git a/documentation/autodoc/README.md b/documentation/autodoc/README.md new file mode 100644 index 0000000000..66ed20eeb1 --- /dev/null +++ b/documentation/autodoc/README.md @@ -0,0 +1,44 @@ +# Autodoc + +WIP command output documentation generator. Run via `../scripts/next-scripts/autodoc.sh` to create a bunch of markdown files which are then moved around for importing into the documentation. + +## `Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }` +If you run into this error, make sure that you have the following directory structure: + +```sh +autodoc/ +├── autodoc-generated-markdown/ +│ └── commands/ +├── Cargo.toml +├── README.md +└── src + └── main.rs +``` + +And if you don't - create it and re-run. + +If you are encountering this error with this dir structure in place, check that all Nym binaries that are listed in `main.rs` also exist in `nym/target/release/`. + +Run this crate on its own with `debug` logging and it should panic on the missing binary: + +```sh + RUST_LOG="debug" cargo run --release + Finished `release` profile [optimized] target(s) in 0.20s + Running `/home/______/src/nym/target/release/autodoc` +[2024-10-23T08:11:01Z DEBUG autodoc] now running Some( + "nym-api", + ) +[2024-10-23T08:11:01Z DEBUG autodoc] stderr: " 2024-10-23T08:11:01.981Z INFO nym_api > Starting nym api...\n" +[2024-10-23T08:11:01Z DEBUG autodoc] stderr: " 2024-10-23T08:11:01.985Z INFO nym_api > Starting nym api...\n" +[2024-10-23T08:11:01Z INFO autodoc] SKIPPING ../../target/release/nym-api init +[2024-10-23T08:11:01Z INFO autodoc] creating own file for ../../target/release/nym-api init --help +[2024-10-23T08:11:01Z DEBUG autodoc] stderr: " 2024-10-23T08:11:01.993Z INFO nym_api > Starting nym api...\n" + +< snip > + +[2024-10-23T08:11:02Z DEBUG autodoc] now running Some( + "nym-cli", + ) +Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info-help.md new file mode 100644 index 0000000000..db52a92b4e --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-api build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info.md b/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info.md new file mode 100644 index 0000000000..c04a06ee09 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-api-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-api +Build Timestamp: 2024-10-09T13:56:14.428750844Z +Build Version: 1.1.42 +Commit SHA: fac373c1db4fa5389ba61de7943c77023467bccb +Commit Date: 2024-10-09T14:59:40.000000000+02:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-api-commands.md b/documentation/autodoc/autodoc-generated-markdown/nym-api-commands.md new file mode 100644 index 0000000000..185d88277b --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-api-commands.md @@ -0,0 +1,95 @@ +# `nym-api` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +2024-10-29T09:51:44.008469Z  INFO nym-api/src/main.rs:41: Starting nym api... +Usage: nym-api [OPTIONS] + +Commands: + init Initialise a Nym Api instance with persistent config.toml file + run Run the Nym Api with provided configuration optionally overriding set parameters + build-info Show build information of this binary + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the Nym API [env: NYMAPI_CONFIG_ENV_FILE_ARG=] + --no-banner + A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) [env: NYMAPI_NO_BANNER_ARG=] + -h, --help + Print help + -V, --version + Print version +``` + +### `init` +```sh +2024-10-29T09:51:44.013292Z  INFO nym-api/src/main.rs:41: Starting nym api... +Initialise a Nym Api instance with persistent config.toml file + +Usage: nym-api init [OPTIONS] + +Options: + --id + Id of the nym-api we want to initialise. if unspecified, a default value will be used. default: "default" [env: NYMAPI_ID_ARG=] [default: default] + -m, --enable-monitor + Specifies whether network monitoring is enabled on this API default: false [env: NYMAPI_ENABLE_MONITOR_ARG=] + -r, --enable-rewarding + Specifies whether network rewarding is enabled on this API default: false [env: NYMAPI_ENABLE_REWARDING_ARG=] + --nyxd-validator + Endpoint to nyxd instance used for contract information. default: http://localhost:26657 [env: NYMAPI_NYXD_VALIDATOR_ARG=] + --mnemonic + Mnemonic of the network monitor used for sending rewarding and zk-nyms transactions default: None [env: NYMAPI_MNEMONIC_ARG=] + --enable-zk-nym + Flag to indicate whether credential signer authority is enabled on this API default: false [env: NYMAPI_ENABLE_ZK_NYM_ARG=] + --announce-address + Announced address that is going to be put in the DKG contract where zk-nym clients will connect to obtain their credentials default: None [env: NYMAPI_ANNOUNCE_ADDRESS_NYM_ARG=] + --monitor-credentials-mode + Set this nym api to work in a enabled credentials that would attempt to use gateway with the bandwidth credential requirement [env: NYMAPI_MONITOR_CREDENTIALS_MODE_ARG=] + --bind-address + Socket address this api will use for binding its http API. default: `127.0.0.1:8080` in `debug` builds and `0.0.0.0:8080` in `release` + -h, --help + Print help +``` + +### `run` +```sh +2024-10-29T09:51:44.032688Z  INFO nym-api/src/main.rs:41: Starting nym api... +Run the Nym Api with provided configuration optionally overriding set parameters + +Usage: nym-api run [OPTIONS] + +Options: + --id + Id of the nym-api we want to run.if unspecified, a default value will be used. default: "default" [env: NYMAPI_ID_ARG=] [default: default] + -m, --enable-monitor + Specifies whether network monitoring is enabled on this API default: None - config value will be used instead [env: NYMAPI_ENABLE_MONITOR_ARG=] [possible values: true, false] + -r, --enable-rewarding + Specifies whether network rewarding is enabled on this API default: None - config value will be used instead [env: NYMAPI_ENABLE_REWARDING_ARG=] [possible values: true, false] + --nyxd-validator + Endpoint to nyxd instance used for contract information. default: None - config value will be used instead [env: NYMAPI_NYXD_VALIDATOR_ARG=] + --mnemonic + Mnemonic of the network monitor used for sending rewarding and zk-nyms transactions default: None - config value will be used instead [env: NYMAPI_MNEMONIC_ARG=] + --enable-zk-nym + Flag to indicate whether coconut signer authority is enabled on this API default: None - config value will be used instead [env: NYMAPI_ENABLE_ZK_NYM_ARG=] [possible values: true, false] + --announce-address + Announced address that is going to be put in the DKG contract where zk-nym clients will connect to obtain their credentials default: None - config value will be used instead [env: NYMAPI_ANNOUNCE_ADDRESS_ARG=] + --monitor-credentials-mode + Set this nym api to work in a enabled credentials that would attempt to use gateway with the bandwidth credential requirement default: None - config value will be used instead [env: NYMAPI_MONITOR_CREDENTIALS_MODE_ARG=] [possible values: true, false] + --bind-address + Socket address this api will use for binding its http API. default: `127.0.0.1:8080` in `debug` builds and `0.0.0.0:8080` in `release` + -h, --help + Print help +``` + +### `build-info` +```sh +2024-10-29T09:51:44.037915Z  INFO nym-api/src/main.rs:41: Starting nym api... +Show build information of this binary + +Usage: nym-api build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-api-init-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-api-init-help.md new file mode 100644 index 0000000000..bd4c714a28 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-api-init-help.md @@ -0,0 +1,25 @@ +```sh +Initialise a Nym Api instance with persistent config.toml file + +Usage: nym-api init [OPTIONS] + +Options: + --id + Id of the nym-api we want to initialise. if unspecified, a default value will be used. default: "default" [default: default] + -m, --enable-monitor + Specifies whether network monitoring is enabled on this API default: false + -r, --enable-rewarding + Specifies whether network rewarding is enabled on this API default: false + --nyxd-validator + Endpoint to nyxd instance used for contract information. default: http://localhost:26657 + --mnemonic + Mnemonic of the network monitor used for sending rewarding and zk-nyms transactions default: None + --enable-zk-nym + Flag to indicate whether credential signer authority is enabled on this API default: false + --announce-address + Announced address that is going to be put in the DKG contract where zk-nym clients will connect to obtain their credentials default: None + --monitor-credentials-mode + Set this nym api to work in a enabled credentials that would attempt to use gateway with the bandwidth credential requirement + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info-help.md new file mode 100644 index 0000000000..f65dc4e7c4 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info.md new file mode 100644 index 0000000000..a0c7d2c612 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-client +Build Timestamp: 2024-10-09T13:56:14.428750844Z +Build Version: 1.1.39 +Commit SHA: fac373c1db4fa5389ba61de7943c77023467bccb +Commit Date: 2024-10-09T14:59:40.000000000+02:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-completions-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-completions-help.md new file mode 100644 index 0000000000..f09b17f785 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-completions-help.md @@ -0,0 +1,11 @@ +```sh +Generate shell completions + +Usage: nym-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec-help.md new file mode 100644 index 0000000000..ecce720ea9 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec-help.md @@ -0,0 +1,8 @@ +```sh +Generate Fig specification + +Usage: nym-client generate-fig-spec + +Options: + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec.md new file mode 100644 index 0000000000..154c25a968 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-generate-fig-spec.md @@ -0,0 +1,585 @@ +```sh +const completion: Fig.Spec = { + name: "nym-native-client", + description: "Implementation of the Nym Client", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket (if applicable) to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-credential", + description: "Import a pre-generated credential", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "show-ticketbooks", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "import-credential", + description: "Import a pre-generated credential", + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "show-ticketbooks", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-import-credential-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-import-credential-help.md new file mode 100644 index 0000000000..2e1b652e39 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-import-credential-help.md @@ -0,0 +1,15 @@ +```sh +Import a pre-generated credential + +Usage: nym-client import-credential --id <--credential-data |--credential-path > + +Options: + --id + Id of client that is going to import the credential + --credential-data + Explicitly provide the encoded credential data (as base58) + --credential-path + Specifies the path to file containing binary credential data + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-init-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-init-help.md new file mode 100644 index 0000000000..3d58fe52c2 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-init-help.md @@ -0,0 +1,27 @@ +```sh +Initialise a Nym client. Do this first! + +Usage: nym-client init [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we are going to connect to + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket (if applicable) to listen on in all subsequent runs + --host + Ip for the socket (if applicable) to listen for requests + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-list-gateways-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-list-gateways-help.md new file mode 100644 index 0000000000..2cddc84edc --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-list-gateways-help.md @@ -0,0 +1,10 @@ +```sh +List all registered with gateways + +Usage: nym-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-run-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-run-help.md new file mode 100644 index 0000000000..deb33eab62 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-run-help.md @@ -0,0 +1,21 @@ +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket to listen on + --host + Ip for the socket (if applicable) to listen for requests + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-client-switch-gateway-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-client-switch-gateway-help.md new file mode 100644 index 0000000000..53277ffdd2 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-client-switch-gateway-help.md @@ -0,0 +1,10 @@ +```sh +Change the currently active gateway. Note that you must have already registered with the new gateway! + +Usage: nym-client switch-gateway --id --gateway-id + +Options: + --id Id of client we want to list gateways for + --gateway-id Id of the gateway we want to switch to + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information-help.md new file mode 100644 index 0000000000..8a54a3c853 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information-help.md @@ -0,0 +1,12 @@ +```sh +Show bonding information of this node depending on its currently selected mode + +Usage: nym-node bonding-information [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --mode [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway] + -o, --output Specify the output format of the bonding information (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information.md new file mode 100644 index 0000000000..edc2294fb2 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-bonding-information.md @@ -0,0 +1,3 @@ +```sh +2024-10-22T13:00:32.542213Z ERROR nym-node/src/config/upgrade_helpers.rs:16: Failed to finish upgrade - failed to load config file using path '/home/m/.nym/nym-nodes/default-nym-node/config/config.toml'. detailed message: No such file or directory (os error 2) +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info-help.md new file mode 100644 index 0000000000..0f369b8537 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-node build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info.md new file mode 100644 index 0000000000..8113e9c0a8 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-node +Build Timestamp: 2024-10-09T13:56:14.428750844Z +Build Version: 1.1.6 +Commit SHA: fac373c1db4fa5389ba61de7943c77023467bccb +Commit Date: 2024-10-09T14:59:40.000000000+02:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-commands.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-commands.md new file mode 100644 index 0000000000..f305d5c6eb --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-commands.md @@ -0,0 +1,237 @@ +# `nym-node` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +Usage: nym-node [OPTIONS] + +Commands: + build-info Show build information of this binary + bonding-information Show bonding information of this node depending on its currently selected mode + node-details Show details of this node + migrate Attempt to migrate an existing mixnode or gateway into a nym-node + run Start this nym-node + sign Use identity key of this node to sign provided message + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the nym-node and overrides any preconfigured values [env: NYMNODE_CONFIG_ENV_FILE_ARG=] + --no-banner + Flag used for disabling the printed banner in tty [env: NYMNODE_NO_BANNER=] + -h, --help + Print help + -V, --version + Print version +``` + +### `build-info` +```sh +Show build information of this binary + +Usage: nym-node build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `bonding-information` +```sh +Show bonding information of this node depending on its currently selected mode + +Usage: nym-node bonding-information [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --mode [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway] + -o, --output Specify the output format of the bonding information (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `node-details` +```sh +Show details of this node + +Usage: nym-node node-details [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + -o, --output Specify the output format of the node details (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `migrate` +```sh +Attempt to migrate an existing mixnode or gateway into a nym-node + +Usage: nym-node migrate [OPTIONS] <--id |--config-file > + +Arguments: + Type of node (mixnode or gateway) to migrate into a nym-node [possible values: mixnode, gateway] + +Options: + --id + Id of the node that's going to get migrated + --config-file + Path to a configuration file of the node that's going to get migrated + --preserve-id + Specify whether to preserve id of the imported node + --public-ips + Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=] + --hostname + Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=] + --location + Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=] + --http-bind-address + Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=] + --landing-page-assets-path + Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=] + --http-access-token + An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=] + --expose-system-info + Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false] + --expose-system-hardware + Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false] + --expose-crypto-hardware + Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false] + --mixnet-bind-address + Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=] + --mixnet-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=] + --nym-api-urls + Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=] + --nyxd-urls + Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=] + --wireguard-enabled + Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false] + --wireguard-bind-address + Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=] + --wireguard-private-ip + Private IP address of the wireguard gateway. default: `10.1.0.1` [env: NYMNODE_WG_IP=] + --wireguard-announced-port + Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=] + --wireguard-private-network-prefix + The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=] + --verloc-bind-address + Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=] + --verloc-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=] + --entry-bind-address + Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=] + --announce-ws-port + Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=] + --announce-wss-port + If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=] + --enforce-zk-nyms + Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false] + --mnemonic + Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=] + --upstream-exit-policy-url + Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=] + --open-proxy + Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false] + -h, --help + Print help +``` + +### `run` +```sh +Start this nym-node + +Usage: nym-node run [OPTIONS] + +Options: + --id + Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file + Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --accept-operator-terms-and-conditions + Explicitly specify whether you agree with the terms and conditions of a nym node operator as defined at [env: NYMNODE_ACCEPT_OPERATOR_TERMS=] + --deny-init + Forbid a new node from being initialised if configuration file for the provided specification doesn't already exist [env: NYMNODE_DENY_INIT=] + --init-only + If this is a brand new nym-node, specify whether it should only be initialised without actually running the subprocesses [env: NYMNODE_INIT_ONLY=] + --local + Flag specifying this node will be running in a local setting [env: NYMNODE_LOCAL=] + --mode + Specifies the current mode of this nym-node [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway] + -w, --write-changes + If this node has been initialised before, specify whether to write any new changes to the config file [env: NYMNODE_WRITE_CONFIG_CHANGES=] + --bonding-information-output + Specify output file for bonding information of this nym-node, i.e. its encoded keys. NOTE: the required bonding information is still a subject to change and this argument should be treated only as a preview of future features [env: NYMNODE_BONDING_INFORMATION_OUTPUT=] + -o, --output + Specify the output format of the bonding information (`text` or `json`) [env: NYMNODE_OUTPUT=] [default: text] [possible values: text, json] + --public-ips + Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=] + --hostname + Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=] + --location + Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=] + --http-bind-address + Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=] + --landing-page-assets-path + Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=] + --http-access-token + An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=] + --expose-system-info + Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false] + --expose-system-hardware + Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false] + --expose-crypto-hardware + Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false] + --mixnet-bind-address + Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=] + --mixnet-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=] + --nym-api-urls + Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=] + --nyxd-urls + Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=] + --wireguard-enabled + Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false] + --wireguard-bind-address + Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=] + --wireguard-private-ip + Private IP address of the wireguard gateway. default: `10.1.0.1` [env: NYMNODE_WG_IP=] + --wireguard-announced-port + Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=] + --wireguard-private-network-prefix + The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=] + --verloc-bind-address + Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=] + --verloc-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=] + --entry-bind-address + Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=] + --announce-ws-port + Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=] + --announce-wss-port + If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=] + --enforce-zk-nyms + Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false] + --mnemonic + Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=] + --upstream-exit-policy-url + Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=] + --open-proxy + Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false] + -h, --help + Print help +``` + +### `sign` +```sh +Use identity key of this node to sign provided message + +Usage: nym-node sign [OPTIONS] <--text |--contract-msg > + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --text Signs an arbitrary piece of text with your identity key + --contract-msg Signs a transaction-specific payload, that is going to be sent to the smart contract, with your identity key + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-migrate-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-migrate-help.md new file mode 100644 index 0000000000..ee32ab638b --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-migrate-help.md @@ -0,0 +1,68 @@ +```sh +Attempt to migrate an existing mixnode or gateway into a nym-node + +Usage: nym-node migrate [OPTIONS] <--id |--config-file > + +Arguments: + Type of node (mixnode or gateway) to migrate into a nym-node [possible values: mixnode, gateway] + +Options: + --id + Id of the node that's going to get migrated + --config-file + Path to a configuration file of the node that's going to get migrated + --preserve-id + Specify whether to preserve id of the imported node + --public-ips + Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=] + --hostname + Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=] + --location + Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=] + --http-bind-address + Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=] + --landing-page-assets-path + Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=] + --http-access-token + An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=] + --expose-system-info + Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false] + --expose-system-hardware + Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false] + --expose-crypto-hardware + Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false] + --mixnet-bind-address + Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=] + --nym-api-urls + Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=] + --nyxd-urls + Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=] + --wireguard-enabled + Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false] + --wireguard-bind-address + Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=] + --wireguard-private-ip + Private IP address of the wireguard gateway. default: `10.1.0.1` [env: NYMNODE_WG_IP=] + --wireguard-announced-port + Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=] + --wireguard-private-network-prefix + The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=] + --verloc-bind-address + Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=] + --entry-bind-address + Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=] + --announce-ws-port + Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=] + --announce-wss-port + If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=] + --enforce-zk-nyms + Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false] + --mnemonic + Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=] + --upstream-exit-policy-url + Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=] + --open-proxy + Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false] + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details-help.md new file mode 100644 index 0000000000..cad77bc2a8 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details-help.md @@ -0,0 +1,11 @@ +```sh +Show details of this node + +Usage: nym-node node-details [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + -o, --output Specify the output format of the node details (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details.md new file mode 100644 index 0000000000..c2b0a34c97 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-node-details.md @@ -0,0 +1,3 @@ +```sh +2024-10-22T13:00:32.562750Z ERROR nym-node/src/config/upgrade_helpers.rs:16: Failed to finish upgrade - failed to load config file using path '/home/m/.nym/nym-nodes/default-nym-node/config/config.toml'. detailed message: No such file or directory (os error 2) +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-node-sign-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-node-sign-help.md new file mode 100644 index 0000000000..5d26baf2f2 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-node-sign-help.md @@ -0,0 +1,13 @@ +```sh +Use identity key of this node to sign provided message + +Usage: nym-node sign [OPTIONS] <--text |--contract-msg > + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --text Signs an arbitrary piece of text with your identity key + --contract-msg Signs a transaction-specific payload, that is going to be sent to the smart contract, with your identity key + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-add-gateway-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-add-gateway-help.md new file mode 100644 index 0000000000..ee209bdcb0 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-add-gateway-help.md @@ -0,0 +1,15 @@ +```sh +Add new gateway to this client + +Usage: nym-socks5-client add-gateway [OPTIONS] --id + +Options: + --id Id of client we want to add gateway for + --gateway-id Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead + --force-tls-gateway Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --set-active Specify whether this new gateway should be set as the active one + --nym-apis Comma separated list of rest endpoints of the API validators + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info-help.md new file mode 100644 index 0000000000..000204a113 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-socks5-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info.md new file mode 100644 index 0000000000..dbf3e77072 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-socks5-client +Build Timestamp: 2024-10-09T13:56:14.428750844Z +Build Version: 1.1.39 +Commit SHA: fac373c1db4fa5389ba61de7943c77023467bccb +Commit Date: 2024-10-09T14:59:40.000000000+02:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-completions-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-completions-help.md new file mode 100644 index 0000000000..8b780c6f17 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-completions-help.md @@ -0,0 +1,11 @@ +```sh +Generate shell completions + +Usage: nym-socks5-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec-help.md new file mode 100644 index 0000000000..94340b5898 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec-help.md @@ -0,0 +1,8 @@ +```sh +Generate Fig specification + +Usage: nym-socks5-client generate-fig-spec + +Options: + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec.md new file mode 100644 index 0000000000..b76ef9d558 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-generate-fig-spec.md @@ -0,0 +1,619 @@ +```sh +const completion: Fig.Spec = { + name: "nym-socks5-client", + description: "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + }, + }, + { + name: "--use-reply-surbs", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_reply_surbs", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--use-anonymous-replies", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_anonymous_replies", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + isOptional: true, + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--geo-routing", + description: "Set geo-aware mixnode selection when sending mixnet traffic, for experiments only", + hidden: true, + isRepeatable: true, + args: { + name: "geo_routing", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: "--medium-toggle", + description: "Enable medium mixnet traffic, for experiments only. This includes things like disabling cover traffic, no per hop delays, etc", + }, + { + name: "--outfox", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "import-credential", + description: "Import a pre-generated credential", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "show-ticketbooks", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "import-credential", + description: "Import a pre-generated credential", + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "show-ticketbooks", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-import-credential-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-import-credential-help.md new file mode 100644 index 0000000000..2f7303c2e3 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-import-credential-help.md @@ -0,0 +1,15 @@ +```sh +Import a pre-generated credential + +Usage: nym-socks5-client import-credential --id <--credential-data |--credential-path > + +Options: + --id + Id of client that is going to import the credential + --credential-data + Explicitly provide the encoded credential data (as base58) + --credential-path + Specifies the path to file containing binary credential data + -h, --help + Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-init-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-init-help.md new file mode 100644 index 0000000000..b69ef5f77c --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-init-help.md @@ -0,0 +1,44 @@ +```sh +Initialise a Nym client. Do this first! + +Usage: nym-socks5-client init [OPTIONS] --id --provider + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we are going to connect to + + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --provider + Address of the socks5 provider to send messages to + + --use-reply-surbs + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + -p, --port + Port for the socket to listen on in all subsequent runs + + --host + The custom host on which the socks5 client will be listening for requests + + -o, --output + [default: text] + [possible values: text, json] + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-list-gateways-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-list-gateways-help.md new file mode 100644 index 0000000000..86921bcf67 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-list-gateways-help.md @@ -0,0 +1,10 @@ +```sh +List all registered with gateways + +Usage: nym-socks5-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-run-help.md b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-run-help.md new file mode 100644 index 0000000000..2ffccb39ce --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nym-socks5-client-run-help.md @@ -0,0 +1,34 @@ +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-socks5-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --use-anonymous-replies + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + --provider + Address of the socks5 provider to send messages to + + -p, --port + Port for the socket to listen on + + --host + The custom host on which the socks5 client will be listening for requests + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-add-upgrade-help.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-add-upgrade-help.md new file mode 100644 index 0000000000..b88f5e1052 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-add-upgrade-help.md @@ -0,0 +1,19 @@ +```sh +Queues up another upgrade for the associated daemon + +Usage: nymvisor add-upgrade [OPTIONS] --upgrade-name + +Arguments: + Path to the daemon's upgrade executable + +Options: + --upgrade-name Name of this upgrade + --force Overwrite existing upgrade binary / upgrade-info.json file + --add-binary Indicate that this command should only add binary to an *existing* scheduled upgrade + --now Force the upgrade to happen immediately + --publish-date Specifies the publish date metadata field of this upgrade. If unset, the current time will be used + --upgrade-time Specifies the time at which the provided upgrade will be performed (RFC3339 formatted). If left unset, the upgrade will be performed in 15min + --upgrade-delay Specifies delay until the provided upgrade is going to get performed. If let unset, the upgrade will be performed in 15min + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info-help.md new file mode 100644 index 0000000000..3a5ccb9b5b --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nymvisor build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info.md new file mode 100644 index 0000000000..f0a0032042 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nymvisor +Build Timestamp: 2024-10-09T13:56:14.428750844Z +Build Version: 0.1.5 +Commit SHA: fac373c1db4fa5389ba61de7943c77023467bccb +Commit Date: 2024-10-09T14:59:40.000000000+02:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-commands.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-commands.md new file mode 100644 index 0000000000..9d0ee36f56 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-commands.md @@ -0,0 +1,154 @@ +# `nymvisor` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +Usage: nymvisor [OPTIONS] + +Commands: + init Initialise a nymvisor instance with persistent Config.toml file + run Run the associated daemon with the preconfigured settings + build-info Show build information of this binary + daemon-build-info Show build information of the associated daemon + add-upgrade Queues up another upgrade for the associated daemon + config Show configuration options being used by this instance of nymvisor + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the nymvisor and overrides any preconfigured values + -h, --help + Print help + -V, --version + Print version +``` + +### `init` +```sh +Initialise a nymvisor instance with persistent Config.toml file + +Usage: nymvisor init [OPTIONS] + +Arguments: + Path to the daemon's executable + +Options: + --id + ID specifies the human readable ID of this particular nymvisor instance. Can be overridden with $NYMVISOR_ID environmental variable + --upstream-base-upgrade-url + Sets the base url of the upstream source for obtaining upgrade information for the deaemon. It will be used fo constructing the full url, i.e. $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL/$DAEMON_NAME/upgrade-info.json Can be overridden with $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL environmental variable + --upstream-polling-rate + Specifies the rate of polling the upstream url for upgrade information. default: 1h Can be overridden with $NYMVISOR_UPSTREAM_POLLING_RATE + --disable-nymvisor-logs + If enabled, this will disable `nymvisor` logs (but not the underlying process) Can be overridden with $NYMVISOR_DISABLE_LOGS environmental variable + --upgrade-data-directory + Set custom directory for upgrade data - binaries and upgrade plans. If not set, the global nymvisors' data directory will be used instead. Can be overridden with $NYMVISOR_UPGRADE_DATA_DIRECTORY environmental variable + --daemon-home + The location where the `nymvisor/` directory is kept that contains the auxiliary files associated with the underlying daemon, such as any backups or current version information. (e.g. $HOME/.nym/nym-api/my-nym-api, $HOME/.nym/mixnodes/my-mixnode, etc.). Can be overridden with $DAEMON_HOME environmental variable + --daemon-absolute-upstream-upgrade-url + Override url to the upstream source for upgrade plans for this daeamon. The Url has to point to an endpoint containing a valid [`UpgradeInfo`] json. Note: if set this takes precedence over `upstream_base_upgrade_url` Can be overridden with $DAEMON_ABSOLUTE_UPSTREAM_UPGRADE_URL environmental variable + --allow-download-upgrade-binaries + If set to true, this will enable auto-downloading of new binaries using the url provided in the `upgrade-info.json` Can be overridden with $DAEMON_ALLOW_BINARIES_DOWNLOAD environmental variable [possible values: true, false] + --enforce-download-checksum + If enabled nymvisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If disabled, nymvisor will not require a checksum to be provided, but still check the checksum if one is provided. Can be overridden with $DAEMON_ENFORCE_DOWNLOAD_CHECKSUM environmental variable [possible values: true, false] + --restart-daemon-after-upgrade + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (if disabled), nymvisor will stop running after an upgrade and will require the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. Can be overridden with $DAEMON_RESTART_AFTER_UPGRADE environmental variable [possible values: true, false] + --restart-daemon-on-failure + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags after it has crashed Can be overridden with $DAEMON_RESTART_ON_FAILURE environmental variable + --on-failure-daemon-restart-delay + If `restart_on_failure` is enabled, the following value defines the amount of time `nymvisor` shall wait before restarting the subprocess. Can be overridden with $DAEMON_FAILURE_RESTART_DELAY environmental variable + --max-daemon-startup-failures + Defines the maximum number of startup failures the subprocess can experience in a quick succession before no further restarts will be attempted and `nymvisor` will exit. Can be overridden with $DAEMON_MAX_STARTUP_FAILURES environmental variable + --startup-period-duration + Defines the length of time during which the subprocess is still considered to be in the startup phase when its failures are going to be considered in `max_startup_failures`. Can be overridden with $DAEMON_STARTUP_PERIOD_DURATION environmental variable + --daemon-shutdown-grace-period + Specifies the amount of time `nymvisor` is willing to wait for the subprocess to undergo graceful shutdown after receiving an interrupt (for either an upgrade or shutdown of the `nymvisor` itself) Once the time passes, a kill signal is going to be sent instead. Can be overridden with $DAEMON_SHUTDOWN_GRACE_PERIOD environmental variable + --daemon-backup-data-directory + Set custom backup directory for daemon data. If not set, the daemon's home directory will be used instead. Can be overridden with $DAEMON_BACKUP_DATA_DIRECTORY environmental variable + --unsafe-skip-backup + If enabled, `nymvisor` will perform upgrades directly without performing any backups. default: false Can be overridden with $DAEMON_UNSAFE_SKIP_BACKUP environmental variable + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` + +### `run` +```sh +Run the associated daemon with the preconfigured settings + +Usage: nymvisor run [DAEMON_ARGS]... + +Arguments: + [DAEMON_ARGS]... + +Options: + -h, --help Print help +``` + +### `build-info` +```sh +Show build information of this binary + +Usage: nymvisor build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` +Example output: +```sh + +Binary Name: nymvisor +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 0.1.8 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` + +### `daemon-build-info` +```sh +Show build information of the associated daemon + +Usage: nymvisor daemon-build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `add-upgrade` +```sh +Queues up another upgrade for the associated daemon + +Usage: nymvisor add-upgrade [OPTIONS] --upgrade-name + +Arguments: + Path to the daemon's upgrade executable + +Options: + --upgrade-name Name of this upgrade + --force Overwrite existing upgrade binary / upgrade-info.json file + --add-binary Indicate that this command should only add binary to an *existing* scheduled upgrade + --now Force the upgrade to happen immediately + --publish-date Specifies the publish date metadata field of this upgrade. If unset, the current time will be used + --upgrade-time Specifies the time at which the provided upgrade will be performed (RFC3339 formatted). If left unset, the upgrade will be performed in 15min + --upgrade-delay Specifies delay until the provided upgrade is going to get performed. If let unset, the upgrade will be performed in 15min + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `config` +```sh +Show configuration options being used by this instance of nymvisor + +Usage: nymvisor config [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-config-help.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-config-help.md new file mode 100644 index 0000000000..696d346802 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-config-help.md @@ -0,0 +1,9 @@ +```sh +Show configuration options being used by this instance of nymvisor + +Usage: nymvisor config [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-daemon-build-info-help.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-daemon-build-info-help.md new file mode 100644 index 0000000000..c89ba02c59 --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-daemon-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of the associated daemon + +Usage: nymvisor daemon-build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/autodoc/autodoc-generated-markdown/nymvisor-init-help.md b/documentation/autodoc/autodoc-generated-markdown/nymvisor-init-help.md new file mode 100644 index 0000000000..8e373fc42c --- /dev/null +++ b/documentation/autodoc/autodoc-generated-markdown/nymvisor-init-help.md @@ -0,0 +1,48 @@ +```sh +Initialise a nymvisor instance with persistent Config.toml file + +Usage: nymvisor init [OPTIONS] + +Arguments: + Path to the daemon's executable + +Options: + --id + ID specifies the human readable ID of this particular nymvisor instance. Can be overridden with $NYMVISOR_ID environmental variable + --upstream-base-upgrade-url + Sets the base url of the upstream source for obtaining upgrade information for the deaemon. It will be used fo constructing the full url, i.e. $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL/$DAEMON_NAME/upgrade-info.json Can be overridden with $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL environmental variable + --upstream-polling-rate + Specifies the rate of polling the upstream url for upgrade information. default: 1h Can be overridden with $NYMVISOR_UPSTREAM_POLLING_RATE + --disable-nymvisor-logs + If enabled, this will disable `nymvisor` logs (but not the underlying process) Can be overridden with $NYMVISOR_DISABLE_LOGS environmental variable + --upgrade-data-directory + Set custom directory for upgrade data - binaries and upgrade plans. If not set, the global nymvisors' data directory will be used instead. Can be overridden with $NYMVISOR_UPGRADE_DATA_DIRECTORY environmental variable + --daemon-home + The location where the `nymvisor/` directory is kept that contains the auxiliary files associated with the underlying daemon, such as any backups or current version information. (e.g. $HOME/.nym/nym-api/my-nym-api, $HOME/.nym/mixnodes/my-mixnode, etc.). Can be overridden with $DAEMON_HOME environmental variable + --daemon-absolute-upstream-upgrade-url + Override url to the upstream source for upgrade plans for this daeamon. The Url has to point to an endpoint containing a valid [`UpgradeInfo`] json. Note: if set this takes precedence over `upstream_base_upgrade_url` Can be overridden with $DAEMON_ABSOLUTE_UPSTREAM_UPGRADE_URL environmental variable + --allow-download-upgrade-binaries + If set to true, this will enable auto-downloading of new binaries using the url provided in the `upgrade-info.json` Can be overridden with $DAEMON_ALLOW_BINARIES_DOWNLOAD environmental variable [possible values: true, false] + --enforce-download-checksum + If enabled nymvisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If disabled, nymvisor will not require a checksum to be provided, but still check the checksum if one is provided. Can be overridden with $DAEMON_ENFORCE_DOWNLOAD_CHECKSUM environmental variable [possible values: true, false] + --restart-daemon-after-upgrade + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (if disabled), nymvisor will stop running after an upgrade and will require the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. Can be overridden with $DAEMON_RESTART_AFTER_UPGRADE environmental variable [possible values: true, false] + --restart-daemon-on-failure + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags after it has crashed Can be overridden with $DAEMON_RESTART_ON_FAILURE environmental variable + --on-failure-daemon-restart-delay + If `restart_on_failure` is enabled, the following value defines the amount of time `nymvisor` shall wait before restarting the subprocess. Can be overridden with $DAEMON_FAILURE_RESTART_DELAY environmental variable + --max-daemon-startup-failures + Defines the maximum number of startup failures the subprocess can experience in a quick succession before no further restarts will be attempted and `nymvisor` will exit. Can be overridden with $DAEMON_MAX_STARTUP_FAILURES environmental variable + --startup-period-duration + Defines the length of time during which the subprocess is still considered to be in the startup phase when its failures are going to be considered in `max_startup_failures`. Can be overridden with $DAEMON_STARTUP_PERIOD_DURATION environmental variable + --daemon-shutdown-grace-period + Specifies the amount of time `nymvisor` is willing to wait for the subprocess to undergo graceful shutdown after receiving an interrupt (for either an upgrade or shutdown of the `nymvisor` itself) Once the time passes, a kill signal is going to be sent instead. Can be overridden with $DAEMON_SHUTDOWN_GRACE_PERIOD environmental variable + --daemon-backup-data-directory + Set custom backup directory for daemon data. If not set, the daemon's home directory will be used instead. Can be overridden with $DAEMON_BACKUP_DATA_DIRECTORY environmental variable + --unsafe-skip-backup + If enabled, `nymvisor` will perform upgrades directly without performing any backups. default: false Can be overridden with $DAEMON_UNSAFE_SKIP_BACKUP environmental variable + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` diff --git a/documentation/autodoc/src/main.rs b/documentation/autodoc/src/main.rs new file mode 100644 index 0000000000..fda48a85f7 --- /dev/null +++ b/documentation/autodoc/src/main.rs @@ -0,0 +1,347 @@ +use log::{debug, info}; +use std::fs::File; +use std::io::{self, Write}; +use std::process::{Command, Output}; +use std::{fs, vec}; + +const WRITE_PATH: &str = "./autodoc-generated-markdown/"; +const COMMAND_PATH: &str = "./autodoc-generated-markdown/commands/"; + +fn main() -> io::Result<()> { + env_logger::init(); + + // TODO if this balloons write automated way of grabbing commands from crates. + let commands_with_subcommands = vec![ + ( + "../../target/release/nym-api", + vec!["init", "run", "build-info"], + ), + ( + "../../target/release/nym-client", + vec![ + "init", + "run", + "import-credential", + "list-gateways", + "switch-gateway", + "build-info", + "completions", + "generate-fig-spec", + ], + ), + ( + "../../target/release/nym-socks5-client", + vec![ + "init", + "run", + "import-credential", + "list-gateways", + "add-gateway", + "build-info", + "completions", + "generate-fig-spec", + ], + ), + ( + "../../target/release/nym-node", + vec![ + "build-info", + "bonding-information", + "node-details", + "migrate", + "run", + "sign", + ], + ), + ( + "../../target/release/nymvisor", + vec![ + "init", + "run", + "build-info", + "daemon-build-info", + "add-upgrade", + "config", + ], + ), + ]; + + let commands_with_subsubcommands = vec![( + "../../target/release/nym-cli", + vec![ + ( + "account", + vec!["create", "balance", "pub-key", "send", "send-multiple"], + ), + ("signature", vec!["sign", "verify"]), + ( + "ecash", + vec![ + "issue-ticket-book", + "recover-ticket-book", + "import-ticket-book", + ], + ), + ( + "coconut", + vec![ + "generate-freepass", + "issue-credentials", + "recover-credentials", + "import-credential", + ], + ), + ("block", vec!["get", "time", "current-height"]), + ( + "cosmwasm", + vec![ + "upload", + "init", + "generate-init-message", + "migrate", + "execute", + ], + ), + ("tx", vec!["get", "query"]), + ( + "vesting-schedule", + vec!["create", "query", "vested-balance", "withdraw-vested"], + ), + ("mixnet", vec!["query", "delegators", "operators"]), + ("generate-fig", vec![""]), + ], + )]; + + for (main_command, subcommands) in commands_with_subcommands { + let last_word = get_last_word_from_filepath(main_command); + debug!("now running {last_word:#?}"); + + if !fs::metadata(WRITE_PATH) + .map(|metadata| metadata.is_dir()) + .unwrap_or(false) + { + fs::create_dir_all(WRITE_PATH)?; + } + + let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?; + writeln!( + file, + "# {} Binary Commands (Autogenerated)", + format!("`{}`", last_word.unwrap()) + )?; + writeln!( + file, + "\nThese docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script." + )?; + let output = Command::new(main_command).arg("--help").output()?; + write_output_to_file(&mut file, output)?; + + for subcommand in subcommands { + // single file + execute_command(&mut file, main_command, subcommand, None)?; + // file per command + execute_command_own_file(main_command, subcommand)?; + } + } + + // nym-cli has subsubcommands so needs its own loop + for (main_command, subcommands) in &commands_with_subsubcommands { + let last_word = get_last_word_from_filepath(main_command); + debug!("now running {last_word:#?}"); + let mut file = File::create(format!("{}/{}-commands.md", WRITE_PATH, last_word.unwrap()))?; + writeln!( + file, + "# {} Binary Commands (Autogenerated)", + format!("`{}`", last_word.unwrap()) + )?; + writeln!( + file, + "\nThese docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script." + )?; + let output = Command::new(main_command).arg("--help").output()?; + + write_output_to_file(&mut file, output)?; + + for (subcommand, subsubcommands) in subcommands { + writeln!(file, "\n## `{}` ", subcommand)?; + let output = Command::new(main_command) + .arg(subcommand) + .arg("--help") + .output()?; + if !output.stdout.is_empty() { + write_output_to_file(&mut file, output)?; + } else { + debug!("empty stdout - nothing to write"); + } + for subsubcommand in subsubcommands { + execute_command(&mut file, main_command, subcommand, Some(subsubcommand))?; + } + } + } + Ok(()) +} + +fn get_last_word_from_filepath(filepath: &str) -> Option<&str> { + let parts: Vec<&str> = filepath.split('/').collect(); + parts.last().copied() +} + +fn execute_command_own_file(main_command: &str, subcommand: &str) -> io::Result<()> { + // this check is basically checking for the rare commands (rn just one) that start a process with no params + // perhaps if this list grows we could just add a timeout and shunt the running and writing + // into a thread with a timeout or something but for right now its fine / thats overkill + if get_last_word_from_filepath(main_command).unwrap() == "nym-node" && subcommand == "run" + || get_last_word_from_filepath(main_command).unwrap() == "nym-api" && subcommand == "run" + || get_last_word_from_filepath(main_command).unwrap() == "nymvisor" && subcommand == "run" + { + info!("SKIPPING {} {}", main_command, subcommand); + } else { + let last_word = get_last_word_from_filepath(main_command); + let output = Command::new(main_command).arg(subcommand).output()?; + if !output.stdout.is_empty() { + info!("creating own file for {} {}", main_command, subcommand,); + if !fs::metadata(WRITE_PATH) + .map(|metadata| metadata.is_dir()) + .unwrap_or(false) + { + fs::create_dir_all(COMMAND_PATH)?; + } + let mut file = File::create(format!( + "{}/{}-{}.md", + COMMAND_PATH, + last_word.unwrap(), + subcommand + ))?; + write_output_to_file(&mut file, output)?; + + // execute help + info!( + "creating own file for {} {} --help", + main_command, subcommand, + ); + if !fs::metadata(COMMAND_PATH) + .map(|metadata| metadata.is_dir()) + .unwrap_or(false) + { + fs::create_dir_all(COMMAND_PATH)?; + } + let mut help_file = File::create(format!( + "{}/{}-{}-help.md", + COMMAND_PATH, + last_word.unwrap(), + subcommand + ))?; + + let output = Command::new(main_command) + .arg(subcommand) + .arg("--help") + .output()?; + if !output.stdout.is_empty() { + write_output_to_file(&mut help_file, output)?; + } else { + debug!("empty stdout - nothing to write"); + } + } else { + info!( + "creating own file for {} {} --help", + main_command, subcommand, + ); + if !fs::metadata(COMMAND_PATH) + .map(|metadata| metadata.is_dir()) + .unwrap_or(false) + { + fs::create_dir_all(COMMAND_PATH)?; + } + let mut help_file = File::create(format!( + "{}/{}-{}-help.md", + COMMAND_PATH, + last_word.unwrap(), + subcommand + ))?; + + let output = Command::new(main_command) + .arg(subcommand) + .arg("--help") + .output()?; + write_output_to_file(&mut help_file, output)?; + debug!("empty stdout - nothing to write"); + } + } + Ok(()) +} + +fn execute_command( + file: &mut File, + main_command: &str, + subcommand: &str, + subsubcommand: Option<&str>, +) -> io::Result<()> { + // checking for the nym-cli subsubcommands + if subsubcommand.is_some() { + writeln!(file, "\n### `{} {}`", subcommand, subsubcommand.unwrap())?; + + info!("executing {} {} --help ", main_command, subcommand); + let output = Command::new(main_command) + .arg(subcommand) + .arg(subsubcommand.unwrap()) + .arg("--help") + .output()?; + if !output.stdout.is_empty() { + write_output_to_file(file, output)?; + } else { + debug!("empty stdout - nothing to write"); + } + // just subcommands + } else { + writeln!(file, "\n### `{}`", subcommand)?; + + // execute help + let output = Command::new(main_command) + .arg(subcommand) + .arg("--help") + .output()?; + if !output.stdout.is_empty() { + write_output_to_file(file, output)?; + } else { + debug!("empty stdout - nothing to write"); + } + + // then execute w/out help: the majority of functions will fail since you're not passing + // required params but thats fine as we can just not render stderr into the final file. + // + // this check is basically checking for the rare commands (rn just one) that start a process with no params + // perhaps if this list grows we could just add a timeout and shunt the running and writing + // into a thread with a timeout or something but for right now its fine / thats overkill + if get_last_word_from_filepath(main_command).unwrap() == "nym-node" + || get_last_word_from_filepath(main_command).unwrap() == "nym-api" + || get_last_word_from_filepath(main_command).unwrap() == "nymvisor" + && subcommand == "run" + { + info!("SKIPPING {} {}", main_command, subcommand); + } else { + info!("executing {} {}", main_command, subcommand); + let output = Command::new(main_command).arg(subcommand).output()?; + if !output.stdout.is_empty() { + writeln!(file, "Example output:")?; + write_output_to_file(file, output)?; + } else { + debug!("empty stdout - nothing to write"); + if !&output.stderr.is_empty() { + debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr)); + } + } + } + } + Ok(()) +} + +fn write_output_to_file(file: &mut File, output: Output) -> io::Result<()> { + writeln!(file, "```sh")?; + file.write_all(&output.stdout)?; + writeln!(file, "```")?; + + if !&output.stderr.is_empty() { + debug!("stderr: {:#?}", String::from_utf8_lossy(&output.stderr)); + } + Ok(()) +} diff --git a/documentation/operators/src/nodes/setup.md b/documentation/backup-pages/bak-setup.mdx similarity index 93% rename from documentation/operators/src/nodes/setup.md rename to documentation/backup-pages/bak-setup.mdx index 8b6a53d84d..10f6e30644 100644 --- a/documentation/operators/src/nodes/setup.md +++ b/documentation/backup-pages/bak-setup.mdx @@ -1,3 +1,49 @@ +{/* +import { MyTab } from '../../../../components/operators/nodes/node-run-command-tabs' +import Mixnode from './snippets/mixnode-run-tab-snippet.mdx'; +import EntryGateway from './snippets/entry-gateway-run-tab-snippet.mdx'; +import ExitGateway from './snippets/exit-gateway-run-tab-snippet.mdx'; +*/} +import { Callout } from 'nextra/components' +import { CCallout } from '@coreui/react' +import { Tabs } from 'nextra/components'; +import { RunTabs } from '../../../../components/operators/nodes/node-run-command-tabs2'; +import { MyTab } from '../../../../components/operators/nodes/node-run-command-tabs'; +import Mixnode from './snippets/mixnode-run-tab-snippet.mdx'; +import { VarInfo } from '../../../../components/variable-info.tsx'; + + + + You can always use `--help` flag to see the commands or arguments associated with a given command. + + + + + +If you are a `nym-mixnode` or `nym-gateway` operator and you are not familiar with the binary changes called *Project Smoosh*, you can read the archived [Smoosh FAQ](../archive/faq/smoosh-faq.md) page. + + +## Tab version 1 + +Using `MyTab` from `'../../../../components/operators/nodes/node-run-command-tabs'` + + +mixnode, + exit-gateway, + entry-gateway + ]} defaultIndex="1"> + + is a package manager for the JavaScript programming language. + is a software packaging system. + + +## Tab version 2 + +Using `RunTab` from `'../../../../components/operators/nodes/node-run-command-tabs2'` + + + # Nym Node Setup & Run This documentation page provides a guide on how to set up and run a [NYM NODE](nym-node.md), along with explanations of available flags, commands, and examples. @@ -269,6 +315,9 @@ In this example we run the node with custom `--id` without initialising, using ` ./nym-node run --mode mixnode --id --deny-init --accept-operator-terms-and-conditions ``` + + + ### Migrate ```admonish caution diff --git a/documentation/operators/src/testing/docker-monitor.md b/documentation/backup-pages/docker-monitor.md similarity index 100% rename from documentation/operators/src/testing/docker-monitor.md rename to documentation/backup-pages/docker-monitor.md diff --git a/documentation/build_all_to_dist.sh b/documentation/build_all_to_dist.sh deleted file mode 100755 index 63833c4359..0000000000 --- a/documentation/build_all_to_dist.sh +++ /dev/null @@ -1,51 +0,0 @@ -#!/usr/bin/env bash - -set -o errexit -set -o nounset -set -o pipefail - -# this is a script called by the github CI and CD workflows to build all 3 docs projects -# and move them to /dist/ in the root of the monorepo. They are rsynced to various servers -# from there by subsequent workflow tasks. - -# array of project dirs -declare -a projects=("docs" "dev-portal" "operators") - -# check you're calling from the right place -if [ $(pwd | awk -F/ '{print $NF}') != "documentation" ] -then - echo "failure: please run script from documentation/" -else - for i in "${projects[@]}" - do - # cd to project dir - cd "./$i" && - # little sanity checks - echo $(pwd) && echo $(mdbook --version) && - # clean old book - echo "cleaning old book" - rm -rf ./book/ - # build book - # mdbook test || true - mdbook build - # check for destination, if ! then mkdir & check again else echo thumbs up - if [ ! -d ../../dist/docs/$i ]; then - echo "dest doesn't exist: creating dir" - mkdir -p ../../dist/docs/$i - fi - if [ -d ../../dist/docs/$i ]; then - echo "cp destination exists, all good" - fi - # clean old dist/$i - rm -rf ../../dist/docs/$i - # move newly rendered book/ to dist - rsync -r ./book/html/ ../../dist/docs/$i - # sanity check - ls -laF ../../dist/docs/ - # cd back to ../documentation/ - cd ../ - done - # rename for server paths - rm -rf ../dist/docs/developers - mv ../dist/docs/dev-portal ../dist/docs/developers -fi diff --git a/documentation/bump_versions.sh b/documentation/bump_versions.sh deleted file mode 100755 index 8b1f68e1f8..0000000000 --- a/documentation/bump_versions.sh +++ /dev/null @@ -1,45 +0,0 @@ -#!/usr/bin/env bash - -set -o errexit -set -o nounset -set -o pipefail - -# takes one manadatory arg and one optional arg: wallet release and minimum rust versions -# it then uses sed to bump them in the three book.toml files. -# -# e.g if the upcoming wallet release version was 1.2.9 you'd run this as: -# `./bump_versions.sh "1.2.9"` -# -# you can also set the minumum rust version by passing an optional additional argument: -# `./bump_versions.sh "1.2.9" "1.67"` - -# array of project dirs -declare -a projects=("docs" "dev-portal" "operators") - -# check number of args passed -if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; -then - echo "failure: please pass at least 1 and at most 2 args: " - echo "./bump_version.sh [OPTIONAL]" - exit 0 -fi - -# check you're calling from the right place -if [ $(pwd | awk -F/ '{print $NF}') != "documentation" ] -then - echo "failure: please run script from documentation/" - exit 0 -else - ## now loop through the above array sed-ing the variable values in the book.toml files - for i in "${projects[@]}" - do - # sed the vars in the book.toml file for each project - echo "setting wallet version in $i/" - sed -i 's/wallet_release_version =.*/wallet_release_version = "'$2'"/' "$i"/book.toml - if [ "$3" ] - then - echo "setting minimum rust version in $i/" - sed -i 's/minimum_rust_version = .*/minimum_rust_version = "'$3'"/' "$i"/book.toml - fi - done -fi diff --git a/documentation/dev-portal/.gitignore b/documentation/dev-portal/.gitignore deleted file mode 100644 index 1451d34afd..0000000000 --- a/documentation/dev-portal/.gitignore +++ /dev/null @@ -1,24 +0,0 @@ -# Generated by Cargo -# will have compiled files and executables -/target/ - -# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries -# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html -Cargo.lock - -# These are backup files generated by rustfmt -**/*.rs.bk - -# Book specific -book - -# OSX -.DS_Store - -theme/ -theme -theme/* - -.idea - -notes \ No newline at end of file diff --git a/documentation/dev-portal/LICENSE b/documentation/dev-portal/LICENSE deleted file mode 100644 index 261eeb9e9f..0000000000 --- a/documentation/dev-portal/LICENSE +++ /dev/null @@ -1,201 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/documentation/dev-portal/README.md b/documentation/dev-portal/README.md deleted file mode 100644 index 0b53b8e984..0000000000 --- a/documentation/dev-portal/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Nym Developer Portal -Developer Portal for the Nym privacy platform built using the [mdBook](https://rust-lang.github.io/mdBook/) docs framework. Deployed version can be found [here](https://nymtech.net/developers). - -## Contributing -Contributions to our documentation are very welcome. Please work on your contribution in either a `feature/` or `chore/` branch from `master` and target your pull request at `master`. - -Changes merged to `master` will be autodeployed to the production site. - -### Adding community projects and resources -If you have built a project with Nym or are compiling and writing resources about Nym, we want to include your work in the `community-resources/` section to share with the rest of the community! Just follow the existing formatting and add your project to the page, then put in a pull request. - -## Variables -There are some variables that are shared across this book, such as the current latest software version. - -Variables are denoted in the `.md` files wrapped in `{{}}` (e.g `{{wallet_release_version}}`), and are located in the `book.toml` file under the `[preprocessor.variables.variables]` heading. If you are changing something like the software release version, minimum code versions in prerequisites, etc, **check in here first!** - -## Building -When working locally, it is recommended that you use `mdbook serve` to have a local version of the docs served on `localhost:3000`, with hot reloading on any changes made to files in the `src/` directory. - -You can find other commands in the [mdBook CLI tool docs](https://rust-lang.github.io/mdBook/cli/index.html). - -### I tried to edit files in `theme/` and they aren't taking effect / `mdbook serve` causes a looping reload on file changes after changing fields in `[preprocessor.theme]` config - -Looping reload is a known issue with the `mdbook-theme` preprocessor used for the table of contents and layout of these docs. As outlined in the `mdbook-theme` [readme](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) one way to mitigate this is to set `turn-off = true` under `[preprocessor.theme]`. This means that `mdbook serve` or `mdbook watch` ignores changes to the `theme/` directory, which is the source of the looping reload. If you have changed or commented out this line, reintroduce it to remove the looping reload. If you are trying to edit the theme of the docs and want to apply the change, see [here](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) for more info on how to remove the block, change the theme, and reintroduce the block. diff --git a/documentation/dev-portal/book.toml b/documentation/dev-portal/book.toml deleted file mode 100644 index e4bf22202c..0000000000 --- a/documentation/dev-portal/book.toml +++ /dev/null @@ -1,118 +0,0 @@ -[book] -title = "Nym Docs" -authors = ["Max Hampshire, Serinko, Alexia Lorenza Martinel"] -description = "Nym technical documentation" -language = "en" -multilingual = false # for the moment - ideally work on chinese, brazillian ,portugese spanish next -src = "src" - -[rust] -edition = "2018" - -################# -# PREPROCESSORS # -################# - -[preprocessor.theme] -pagetoc = true -sidebar-width = "280px" -content-max-width = "80%" -root-font-size = "70%" -# if you need to change anything in the index.hbs file you need to turn this to `false`, rebuild the book, -# probably remove the additional `comment` that gets appended to the header, and then change this back to `true`. -# this is because of a bug in the `mdbook-theme` plugin -turn-off = true - - -[preprocessor.admonish] -command = "mdbook-admonish" -assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install` - -# https://gitlab.com/tglman/mdbook-variables/ -[preprocessor.variables.variables] -minimum_rust_version = "1.66" -wallet_release_version = "1.2.8" -# nym-vpn related variables -nym_vpn_releases = "https://github.com/nymtech/nym-vpn-client/releases" -nym_vpn_form_url = "https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2" - -# versions are pulled by cmdrun now -# nym_vpn_gui_version = "0.0.6" -# nym_vpn_cli_version = "0.0.4" - -[preprocessor.last-changed] -command = "mdbook-last-changed" -renderer = ["html"] - -# used for grabbing output of binary commands for automation https://github.com/FauconFan/mdbook-cmdrun -[preprocessor.cmdrun] - -# more pre-processor plugins to look into from https://github.com/rust-lang/mdBook/wiki/Third-party-plugins & https://lib.rs/keywords/mdbook-preprocessor -# mdbook-i18n - -######### -# BUILD # -######### - -[build] -build-dir = "book" # the directory where the output is placed -create-missing = true # whether or not to create missing pages -use-default-preprocessors = true # use the default preprocessors -extra-watch-dirs = [] # directories to watch for triggering builds - -########## -# OUTPUT # -########## - -[output.html] -theme = "themes" -default-theme = "coal" -preferred-dark-theme = "coal" -curly-quotes = true -copy-fonts = true -no-section-label = false -additional-css = [ - "./themes/custom.css", - "./themes/mdbook-admonish.css", - "./themes/pagetoc.css", -] -additional-js = ["./themes/pagetoc.js"] -git-repository-url = "https://github.com/nymtech/nym" -git-repository-icon = "fa-github" -input-404 = "not-found.md" - -[output.html.fold] -enable = true # whether or not to enable section folding -level = 0 # the depth to start folding - -# controlling rust sample code blocks -[output.html.playground] -editable = false # allows editing the source code -copyable = true # include the copy button for copying code snippets -copy-js = true # includes the JavaScript for the code editor -line-numbers = true # displays line numbers for editable code -runnable = true # displays a run button for rust code - -# options for the built in text search -[output.html.search] -enable = true # enables the search feature -limit-results = 30 # maximum number of search results -teaser-word-count = 30 # number of words used for a search result teaser -use-boolean-and = true # multiple search terms must all match -boost-title = 2 # ranking boost factor for matches in headers -boost-hierarchy = 1 # ranking boost factor for matches in page names -boost-paragraph = 1 # ranking boost factor for matches in text -expand = true # partial words will match longer terms -heading-split-level = 3 # link results to heading levels -copy-js = true # include Javascript code for search - -[output.linkcheck] -warning-policy = "warn" - -[output.html.redirect] -"/faq/general-faq.html" = "https://nymtech.net/developers/faq/integrations-faq.html" -"/tutorials/simple-service-provider/user-client.html" = "https://nymtech.net/developers/examples/custom-services.html" -"/quickstart/socks-proxy.html" = "https://nymtech.net/developers/clients/socks5/setup.html" -"/tutorials/matrix.html" = "https://nymtech.net/developers/archive/nym-connect.html#matrix-element-via-nymconnect" -"/tutorials/monero.html" = "https://nymtech.net/developers/archive/nym-connect.html#monero-wallet-via-nymconnect" -"/tutorials/telegram.html" = "https://nymtech.net/developers/archive/nym-connect.html#telegram-via-nymconnect" diff --git a/documentation/dev-portal/diagrams/example-app-flow-init.md b/documentation/dev-portal/diagrams/example-app-flow-init.md deleted file mode 100644 index a378925a1f..0000000000 --- a/documentation/dev-portal/diagrams/example-app-flow-init.md +++ /dev/null @@ -1,24 +0,0 @@ - +-----------+ - | Gateway | - +-----------+ - ^ - | - | - | - | - | - | - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine \ No newline at end of file diff --git a/documentation/dev-portal/diagrams/mixnet-traffic-flow.md b/documentation/dev-portal/diagrams/mixnet-traffic-flow.md deleted file mode 100644 index fbb0a4caaf..0000000000 --- a/documentation/dev-portal/diagrams/mixnet-traffic-flow.md +++ /dev/null @@ -1,33 +0,0 @@ - - +----------+ +----------+ +----------+ - | Mix Node |<-----------> | Mix Node |<----------->| Mix Node | - | Layer 1 | | Layer 2 | | Layer 3 | - +----------+ +----------+ +----------+ - ^ ^ - | | - | | - v v - +--------------+ +-----------------+ - | Your gateway | | Service gateway | - +--------------+ +-----------------+ - ^ ^ - | | - | | - v v - +-------------------+ +-------------------+ - | +---------------+ | | +---------------+ | - | | Nym client | | | | Nym Client | | - | +---------------+ | | +---------------+ | - | ^ | | ^ | - | | | | | | - | | | | | | - | v | | v | - | +---------------+ | | +---------------+ | - | | Your app code | | | | Service Code | | - | +---------------+ | | +---------------+ | - +-------------------+ +-------------------+ - Your Local Machine** Service Provider Machine** - - -** note that depending on the technical setup, the Nym client running on these machines may -be either a seperate process or embedded in the same process as the app code via one of our SDKs. \ No newline at end of file diff --git a/documentation/dev-portal/diagrams/send-to-ourselves.md b/documentation/dev-portal/diagrams/send-to-ourselves.md deleted file mode 100644 index 218a9d3330..0000000000 --- a/documentation/dev-portal/diagrams/send-to-ourselves.md +++ /dev/null @@ -1,34 +0,0 @@ - - +----------+ +----------+ +----------+ - | Mix Node |<-----------> | Mix Node |<----------->| Mix Node | - | Layer 1 | | Layer 2 | | Layer 3 | - +----------+ +----------+ +----------+ - ^ ^ - | | - |<--------------------------------------------------+ - | - v - +--------------+ - | Your gateway | - +--------------+ - ^ - | - | - v - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine** - - -** note that depending on the technical setup, the Nym client running on this machine may -be either a seperate process or embedded in the same process as the app code via one of our SDKs. \ No newline at end of file diff --git a/documentation/dev-portal/diagrams/templates/local-machine.md b/documentation/dev-portal/diagrams/templates/local-machine.md deleted file mode 100644 index fa63a5cbff..0000000000 --- a/documentation/dev-portal/diagrams/templates/local-machine.md +++ /dev/null @@ -1,14 +0,0 @@ -+-------------------+ -| +---------------+ | -| | Nym client | | -| +---------------+ | -| ^ | -| | | -| | | -| | | -| v | -| +---------------+ | -| | Your app code | | -| +---------------+ | -+-------------------+ - Your Local Machine \ No newline at end of file diff --git a/documentation/dev-portal/diagrams/templates/service-machine.md b/documentation/dev-portal/diagrams/templates/service-machine.md deleted file mode 100644 index f9acb9d1e9..0000000000 --- a/documentation/dev-portal/diagrams/templates/service-machine.md +++ /dev/null @@ -1,15 +0,0 @@ -+-------------------+ -| +---------------+ | -| | Nym client | | -| +---------------+ | -| ^ | -| | | -| | | -| | | -| v | -| +---------------+ | -| | Service code | | -| +---------------+ | -+-------------------+ - Service Machine - \ No newline at end of file diff --git a/documentation/dev-portal/src/SUMMARY.md b/documentation/dev-portal/src/SUMMARY.md deleted file mode 100644 index 70b789373e..0000000000 --- a/documentation/dev-portal/src/SUMMARY.md +++ /dev/null @@ -1,67 +0,0 @@ -# -- [Introduction](introduction.md) -- [Clients Overview - Start Here!](clients-overview.md) - -# SDKs -- [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) - - [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) -- [Typescript SDK](sdk/typescript.md) - -# Binaries -- [Pre-built Binaries](binaries/pre-built-binaries.md) -- [Building from Source](binaries/building-nym.md) - -# Standalone Clients -- [Websocket Client](clients/websocket-client.md) - - [Setup & Run](clients/websocket/setup.md) - - [Configuration](clients/websocket/config.md) - - [Using Your Client](clients/websocket/usage.md) - - [Examples](clients/websocket/examples.md) -- [Socks5 Client](clients/socks5-client.md) - - [Setup & Run](clients/socks5/setup.md) - - [Using Your Client](clients/socks5/usage.md) -- [Webassembly Client](clients/webassembly-client.md) - -# Tutorials -- [Stub: Updates Coming Soon!](./tutorials/coming-soon.md) - -# Code Examples -- [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)) -- [Payment Integration](integrations/payment-integration.md) - -# FAQ -- [Integrations](faq/integrations-faq.md) - -# User Manuals -- [NymVPN beta](nymvpn/intro.md) - - [CLI](nymvpn/cli.md) ---- - -# Archive -- [NymConnect Setup](archive/nym-connect.md) - ---- - -# Misc. -- [Code of Conduct](coc.md) -- [Licensing](licensing.md) ---- diff --git a/documentation/dev-portal/src/binaries/pre-built-binaries.md b/documentation/dev-portal/src/binaries/pre-built-binaries.md deleted file mode 100644 index 269c26276c..0000000000 --- a/documentation/dev-portal/src/binaries/pre-built-binaries.md +++ /dev/null @@ -1,6 +0,0 @@ -# Pre-built Binaries - -The [Github releases page](https://github.com/nymtech/nym/releases) has pre-built binaries which should work on Ubuntu 20.04 and other Debian-based systems, but at this stage cannot be guaranteed to work everywhere. - -If the pre-built binaries don't work or are unavailable for your system, you will need to build the platform yourself. - diff --git a/documentation/dev-portal/src/clients-overview.md b/documentation/dev-portal/src/clients-overview.md deleted file mode 100644 index 616ddc797e..0000000000 --- a/documentation/dev-portal/src/clients-overview.md +++ /dev/null @@ -1,49 +0,0 @@ -# Clients Overview - -A large proportion of the Nym mixnet's functionality is implemented client-side. - -Clients perform the following actions on behalf of users: - -* determine network topology - what mixnodes exist, what their keys are, etc. -* register with a gateway -* authenticate with a gateway -* receive and decrypt messages from the gateway -* create layer-encrypted Sphinx packets -* send Sphinx packets with real messages -* send Sphinx packet _cover traffic_ when no real messages are being sent -* retransmit un-acknowledged packet sends - 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. - -> As a developer, you'll want to use a Nym client to send your application network traffic through the mixnet; whether that is an RPC call, a TCP connection request, or treating it like a UDP pipe, you need to send whatever bytes your app needs to send through it. However, unlike (e.g.) a TCP Socket, Nym client communication is message-based, so you cannot (yet) simply plug-and-play using the mixnet as a seamless drop-in replacement. We are currently working on stream-like abstractions for ease of integration with the Rust SDK. - -## Types of Nym clients -At present, there are three Nym clients: - -- the websocket (native) client -- the SOCKS5 client -- the wasm (webassembly) client - -You need to choose which one you want incorporate into your app. Which one you use will depend largely on your preferred programming style and the purpose of your app. - -### The websocket client -Your first option is the native websocket client (`nym-client`). This is a compiled program that can run on Linux, Mac OS X, and Windows machines. It can be run as a persistent process on a desktop or server machine. You can connect to it with **any language that supports websockets**. - -> Rust developers can import websocket client functionality into their code via the [Rust SDK](sdk/rust/rust.md). - -### The webassembly client -If you're working in JavaScript or Typescript in the browser, or building an [edge computing](https://en.wikipedia.org/wiki/Edge_computing) app, you'll likely want to choose the webassembly client. - -It's packaged and [available on the npm registry](https://www.npmjs.com/package/@nymproject/nym-client-wasm), so you can `npm install` it into your JavaScript or TypeScript application. - -> The webassembly client is most easily used via the [Typescript SDK](sdk/typescript.md). Typescript developers who wish to send API requests through the mixnet can can also check the [`mixfetch`]() package. - -### The SOCKS5 client -The `nym-socks5-client` is useful for allowing existing applications to use the Nym mixnet without any code changes. All that's necessary is that they can use one of the SOCKS5, SOCKS4a, or SOCKS4 proxy protocols (which many applications can - crypto wallets, browsers, chat applications etc). - -When used as a standalone client, it's less flexible as a way of writing custom applications than the other clients, but able to be used to proxy application traffic through the mixnet without having to make any code changes. - -> Rust developers can import socks client functionality into their code via the [Rust SDK](sdk/rust/rust.md). - -## 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/dev-portal/src/clients/overview.md b/documentation/dev-portal/src/clients/overview.md deleted file mode 100644 index fcce9eb8bb..0000000000 --- a/documentation/dev-portal/src/clients/overview.md +++ /dev/null @@ -1,45 +0,0 @@ -# Clients Overview - -A large proportion of the Nym mixnet's functionality is implemented client-side. - -Clients perform the following actions on behalf of users: - -* determine network topology - what mixnodes exist, what their keys are, etc. -* register with a gateway -* authenticate with a gateway -* receive and decrypt messages from the gateway -* create layer-encrypted Sphinx packets -* send Sphinx packets with real messages -* send Sphinx packet _cover traffic_ when no real messages are being sent -* retransmit un-acknowledged packet sends - 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. - -## Types of Nym clients -At present, there are three Nym clients: - -- the websocket (native) client -- the SOCKS5 client -- the wasm (webassembly) client - -You need to choose which one you want incorporate into your app. Which one you use will depend largely on your preferred programming style and the purpose of your app. - -### The websocket client -Your first option is the native websocket client (`nym-client`). This is a compiled program that can run on Linux, Mac OS X, and Windows machines. It can be run as a persistent process on a desktop or server machine. You can connect to it with **any language that supports websockets**. - -> Rust developers can import websocket client functionality into their code via the [Rust SDK](../sdk/rust/rust.md). - -### The webassembly client -If you're working in JavaScript or Typescript in the browser, or building an [edge computing](https://en.wikipedia.org/wiki/Edge_computing) app, you'll likely want to choose the webassembly client. - -It's packaged and [available on the npm registry](https://www.npmjs.com/package/@nymproject/nym-client-wasm), so you can `npm install` it into your JavaScript or TypeScript application. - -> The webassembly client is most easily used via the [Typescript SDK](../sdk/typescript.md). Typescript developers who wish to send API requests through the mixnet can can also check the [`mixfetch`]() package. - -### The SOCKS5 client -The `nym-socks5-client` is useful for allowing existing applications to use the Nym mixnet without any code changes. All that's necessary is that they can use one of the SOCKS5, SOCKS4a, or SOCKS4 proxy protocols (which many applications can - crypto wallets, browsers, chat applications etc). - -When used as a standalone client, it's less flexible as a way of writing custom applications than the other clients, but able to be used to proxy application traffic through the mixnet without having to make any code changes. - -_Rust developers can import socks client functionality into their code via the [Rust SDK](../sdk/rust/rust.md)_. - -## 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/dev-portal/src/clients/socks5-client.md b/documentation/dev-portal/src/clients/socks5-client.md deleted file mode 100644 index b72298df75..0000000000 --- a/documentation/dev-portal/src/clients/socks5-client.md +++ /dev/null @@ -1,71 +0,0 @@ -# Socks5 Client - -> The Nym Socks5 Client was built in the [building nym](../binaries/building-nym.md) section. If you haven't yet built Nym and want to run the code on this page, go there first. - -**To install and operate `nym-socks5-client`, visit [Setup & Run](socks5/setup.md) and [Using Your Client](socks5/usage.md) pages.** - -## Current version - -``` - -``` - -## What is this client for? - -Many existing applications are able to use either the SOCKS4, SOCKS4A, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this: - -``` - External Systems: - +--------------------+ - |------>| Monero blockchain | - | +--------------------+ - | +--------------------+ - |------>| Email server | - | +--------------------+ - | +--------------------+ - |------>| RPC endpoint | - | +--------------------+ - | +--------------------+ - |------>| Website | - | +--------------------+ - | +--------------------+ - +----------------------------------+ |------>| etc... | - | Mixnet: | | +--------------------+ - | * Gateway your client is | | - | connected to | +--------------------+ | - | * Mix nodes 1 -> 3 |<-------->| Network requester |<------+ - | * Gateway that network | +--------------------+ - | requester is connected to | - +----------------------------------+ - ^ - | - | - | - | - v - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine -``` - -There are 2 pieces of software that work together to send SOCKS traffic through the mixnet: the `nym-socks5-client`, and the `nym-network-requester`. - -The `nym-socks5-client` allows you to do the following from your local machine: -* Take a TCP data stream from a application that can send traffic via SOCKS5. -* Chop up the TCP stream into multiple Sphinx packets, assigning sequence numbers to them, while leaving the TCP connection open for more data -* Send the Sphinx packets through the Nym Network. Packets are shuffled and mixed as they transit the mixnet. - -The `nym-network-requester` then reassembles the original TCP stream using the packets' sequence numbers, and make the intended request. It will then chop up the response into Sphinx packets and send them back through the mixnet to your `nym-socks5-client`. The application will then receive its data, without even noticing that it wasn't talking to a "normal" SOCKS5 proxy! - -Since the introduction of `nym-node` binary, `nym-network-requester` is incorporated in every node running in `exit-gateway` mode. The narrow whitelist was exchanged for a less restrictive Nym [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt), where except the IPs and ports all internet access is permitted. `nym-socks5-client` users can find a full list of Network Requester addresses on [Nym Harbourmaster](https://harbourmaster.nymtech.net/) under tab called *SOCKS5 NETWORK REQUESTERS*. diff --git a/documentation/dev-portal/src/clients/socks5/setup.md b/documentation/dev-portal/src/clients/socks5/setup.md deleted file mode 100644 index 26dc0fda7a..0000000000 --- a/documentation/dev-portal/src/clients/socks5/setup.md +++ /dev/null @@ -1,159 +0,0 @@ -# Setup & Run Nym Socks5 Client - -> `nym-socks5-client` now also supports SOCKS4 and SOCKS4A protocols as well as SOCKS5. - -The Nym socks5 client allows you to proxy traffic from a desktop application through the mixnet, meaning you can send and receive information from remote application servers without leaking metadata which can be used to deanonymise you, even if you're using an encrypted application such as Signal. - -```admonish info -Since the beginning of 2024 NymConnect is no longer maintained. Nym is developing a new client called [NymVPN](https://nymvpn.com), an application routing all users traffic thorugh the mixnet. -If users want to route their traffic through socks5 we advice to use this client. If you want to run deprecated NymConnect, visit [NymConnect archive page](../../archive/nym-connect.md) with setup and application examples. -``` - -## Setup - -### Download or compile socks5 client - -If you are using OSX or a Debian-based operating system, you can download the `nym-socks5-client` binary from our [Github releases page](https://github.com/nymtech/nym/releases). - -If you are using a different operating system, head over to the [Building from Source](https://nymtech.net/docs/binaries/building-nym.html) page for instructions on how to build the repository from source. - -### Initialise Socks5 Client - -To initialise your `nym-socks5-client` you need to have an address of a Network Requester (NR). Nowadays NR is part of every Exit Gateway (`nym-node --mode exit-gateway`). The easiest way to get a NR address is to visit [harbourmaster.nymtech.net](https://harbourmaster.nymtech.net/) and open the tab called *SOCKS5 NETWORK REQUESTERS*. There you can filter the NR by Gateways identity address, and other options. - -Use the following command to initialise `nym-socs5-client` where `` can be anything you want (it's only for local config file storage identification and never shared on the network) and `` is suplemented with a NR address: - -``` -./nym-socks5-client init --id --provider -``` - -~~~admonish tip -Another option to find a NR address associated with a Gateway is to query nodes [*Self Described* API endpoint](https://validator.nymtech.net/api/v1/gateways/described) where the NR address is noted like in this example: -```sh -"network_requester": { - "address": "CyuN49nkyeuiLohSpV5A1MbSqcugHLJQ95B5HooCpjv8.CguTh45Vp99QuGWZRBKpBjZDQbsJaHaXqAMGyc4Qhkzp@2w5RduXRqxKgHt1wtp4qGA4AfXaBj8TuUj1LvcPe2Ea1", - "uses_exit_policy": true -} -``` -~~~ - -## Run - -Now your client is initialised, start it with the following: - -``` -./nym-socks5-client run --id -``` - -## Useful commands - -### Viewing Command `--help` - -You can check that your binaries are properly compiled with: - -``` -./nym-socks5-client --help -``` - -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - -You can check the necessary parameters for the available commands by running: - -``` -./nym-socks5-client --help -``` -For example `./nym-socks5-client run --help` will return all options associated with `run` command. - -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - -### `build-info` - -A `build-info` command prints the build information like commit hash, rust version, binary version just like what command `--version` does. However, you can also specify an `--output=json` flag that will format the whole output as a json, making it an order of magnitude easier to parse. - -### Flags & Arguments - -* `--id`: A local identifier so that you can name your clients and keep track of them on your local system; it is **never** transmitted over the network. - -* `--use-reply-surbs`: This field denotes whether you wish to send [SURBs](https://nymtech.net/docs/architecture/traffic-flow.md#private-replies-using-surbs) along with your request. It defaults to `false` and must be explicitly set to `true` to activate. - -* `--use-anonymous-replies `: Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. - -* `--gateway`: By default your client will choose a random gateway to connect to. However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client: - -* `--latency-based-selection`: This flag will choose a gateway based on its location relative to your client. This argument means that to select a gateway, your client will: - * fetch a list of all availiable gateways - * send few ping messages to all of them, and measure response times. - * create a weighted distribution to randomly choose one, favouring ones with lower latency. - -> Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms - -## Configuring `nym-socks5-client` - -When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/socks5-clients//`. - -``` -tree $HOME/.nym/socks5-clients/ -├── config -│   └── config.toml -└── data - ├── ack_key.pem - ├── credentials_database.db - ├── gateways_registrations.sqlite - ├── persistent_reply_store.sqlite - ├── private_encryption.pem - ├── private_identity.pem - ├── public_encryption.pem - └── public_identity.pem -``` - -The `config.toml` file contains client configuration options, while the two `pem` files contain client key information. - -The generated files contain the client name, public/private keypairs, and gateway address. The name `` in the example above is just a local identifier so that you can name your clients. - -### Configuring your client for Docker - -By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`. - -You can set this via the `--host` flag during either the `init` or `run` commands. - -Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process. - -### Automating your socks5 client with systemd - -Create a service file for the socks5 client at `/etc/systemd/system/nym-socks5-client.service`: - -```ini -[Unit] -Description=Nym Socks5 Client -StartLimitInterval=350 -StartLimitBurst=10 - -[Service] -User=nym # replace this with whatever user you wish -LimitNOFILE=65536 -ExecStart=/home/nym/nym-socks5-client run --id -KillSignal=SIGINT -Restart=on-failure -RestartSec=30 - -[Install] -WantedBy=multi-user.target -``` - -Now enable and start your socks5 client: - -``` -systemctl enable nym-socks5-client.service -systemctl start nym-socks5-client.service - -# you can always check your socks5 client has succesfully started with: -systemctl status nym-socks5-client.service -``` diff --git a/documentation/dev-portal/src/clients/socks5/usage.md b/documentation/dev-portal/src/clients/socks5/usage.md deleted file mode 100644 index f05c594ef0..0000000000 --- a/documentation/dev-portal/src/clients/socks5/usage.md +++ /dev/null @@ -1,33 +0,0 @@ -# Using Your Client - -## Proxying traffic -After completing the steps above, your local `nym-socks5-client` will be listening on `localhost:1080` ready to proxy traffic to the Network Requester set as the `--provider` when initialising. - -When trying to connect your app, generally the proxy settings are found in `settings->advanced` or `settings->connection`. - -Here is an example of setting the proxy connecting in Blockstream Green: - -![Blockstream Green settings](../../images/blockstream-green.gif) - -Most wallets and other applications will work basically the same way: find the network proxy settings, enter the proxy url (host: **localhost**, port: **1080**). - -In some other applications, this might be written as **localhost:1080** if there's only one proxy entry field. - -## Supported Applications - -Any application which can be redirected over Socks5 proxy should work. Nym community has been successfully running over Nym Mixnet these applications: - -- Bitcoin Electrum wallet -- Monero wallet (GUI and CLI with monerod) -- Telegram chat -- Element/Matrix chat -- Firo wallet -- Blockstream Green - -> DarkFi's ircd chat was previously supported: they have moved to DarkIrc: whether the existing integration work is still operational needs to be tested. - -Keep in mind that Nym has been developing a new client **[NymVPN](https://nymvpn.com) (GUI and CLI) routing all users traffic through the Mixnet.** - -## Further reading - -If you want to dig more into the architecture and use of the socks5 client check out its documentation [here](https://nymtech.net/docs/clients/socks5-client.html). diff --git a/documentation/dev-portal/src/clients/webassembly-client.md b/documentation/dev-portal/src/clients/webassembly-client.md deleted file mode 100644 index f6a0aa55c2..0000000000 --- a/documentation/dev-portal/src/clients/webassembly-client.md +++ /dev/null @@ -1,22 +0,0 @@ -# Webassembly Client - -The Nym webassembly client allows any webassembly-capable runtime to build and send Sphinx packets to the Nym network, for uses in edge computing and browser-based applications. - -This is currently packaged and distributed for ease of use via the [Nym Typescript SDK library](../sdk/typescript.md). **We imagine most developers will use this client via the SDK for ease.** - -The webassembly client allows for the easy creation of Sphinx packets from within mobile apps and browser-based client-side apps (including Electron or similar). - -## Building apps with Webassembly Client - -Check out the [Typescript SDK docs](https://sdk.nymtech.net) for examples of usage. - -There are also example applications located in the `clients/webassembly` directory in the main Nym platform codebase. - -## Think about what you're sending! -```admonish caution -Think about what information your app sends. That goes for whatever you put into your Sphinx packet messages as well as what your app's environment may leak. -``` - -Whenever you write client PEAPPs using HTML/JavaScript, we recommend that you do not load external resources from CDNs. Webapp developers do this all the time, to save load time for common resources, or just for convenience. But when you're writing privacy apps it's better not to make these kinds of requests. Pack everything locally. - -If you use only local resources within your Electron app or your browser extensions, explicitly encoding request data in a Sphinx packet does protect you from the normal leakage that gets sent in a browser HTTP request. [There's a lot of stuff that leaks when you make an HTTP request from a browser window](https://panopticlick.eff.org/). Luckily, all that metadata and request leakage doesn't happen in Nym, because you're choosing very explicitly what to encode into Sphinx packets, instead of sending a whole browser environment by default. diff --git a/documentation/dev-portal/src/clients/websocket-client.md b/documentation/dev-portal/src/clients/websocket-client.md deleted file mode 100644 index add7ef24dc..0000000000 --- a/documentation/dev-portal/src/clients/websocket-client.md +++ /dev/null @@ -1,13 +0,0 @@ -# Websocket Client - -> The Nym Websocket Client was built in the [building nym](../binaries/building-nym.md) section. If you haven't yet built Nym and want to run the code on this page, go there first. - -## Current version -``` - -``` - -You can run this client as a standalone process and pipe traffic into it to be sent through the mixnet. This is useful if you're building an application in a language other than Typescript or Rust and cannot utilise one of the SDKs. - -You can find the code for this client [here](https://github.com/nymtech/nym/tree/develop/clients/native). - diff --git a/documentation/dev-portal/src/events/hcpp23-max.md b/documentation/dev-portal/src/events/hcpp23-max.md deleted file mode 100644 index 441094bb80..0000000000 --- a/documentation/dev-portal/src/events/hcpp23-max.md +++ /dev/null @@ -1,33 +0,0 @@ -# HCPP23 - Building with Nym workshop - -This is a *reference page*, to see the entire presentation join Max's talk at [HCPP 2023](https://resistance.hcpp.cz/) on [Satuday](https://cfp.paralelnipolis.cz/hcpp23/talk/LLPWXW/). - -## Mixnet architecture - -* [Mixnet motivations](https://nymtech.net/developers/infrastructure/nym.html) -* [Mixnet architecture overview](https://nymtech.net/docs/architecture/network-overview.html) -* [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) -* [Tor + VPN comparison](https://nymtech.net/developers/infrastructure/nym-vs-others.html) -* [Addressing system](https://nymtech.net/docs/clients/addressing-system.html) - -## Clients - -* [Clients overview](https://nymtech.net/docs/clients/overview.html) - -## SDKs - -* [Rust SDK](https://nymtech.net/docs/sdk/rust.html) -* [Typescript SDK](https://sdk.nymtech.net/) - -### Rust examples - -* [Libp2p examples](https://github.com/nymtech/nym/tree/develop/sdk/rust/nym-sdk/examples) -* [Lighthouse PoC](https://github.com/ChainSafe/lighthouse/blob/nym/USE_NYM.md) -* [Dev tutoral: chain service](https://nymtech.net/developers/tutorials/cosmos-service/intro.html) -* [Community: Darkfi over Nym](https://darkrenaissance.github.io/darkfi/clients/nym_outbound.html?highlight=nym#3--run) - -### Typescript - -* [Mixfetch NPM](https://www.npmjs.com/package/@nymproject/mix-fetch) -* [Interactive Typescript SDK docs](https://sdk.nymtech.net) - diff --git a/documentation/dev-portal/src/events/hcpp23-serinko.md b/documentation/dev-portal/src/events/hcpp23-serinko.md deleted file mode 100644 index 4fda998fae..0000000000 --- a/documentation/dev-portal/src/events/hcpp23-serinko.md +++ /dev/null @@ -1,323 +0,0 @@ -# HCPP 2023 - Securing the Lunarpunks Workshop - -[Serinko's](https://resistance.hcpp.cz/) [workshop](ttps://cfp.paralelnipolis.cz/hcpp23/talk/LLPWXW/) will introduce ***why*** and ***how to use [Nym](https://nymtech.net) platform as a network protection*** layer when using some of our favorite privacy applications. This page serves as an accessible guide alongside the talk and it includes all the steps, pre-requisities and dependencies needed. Preferably the users interested in this setup start downloading and building the tools before the workshop or in the beginning of it. We can use the limited time for questions and addressing problems. This guide will stay online after the event just in case people were not finished and want to catch up later. - -This page is a *how to guide* so it contains the setup only, to see the entire presentation join in at [HCPP 2023](https://resistance.hcpp.cz/) on [Sunday](https://cfp.paralelnipolis.cz/hcpp23/talk/LLPWXW/). - -## Preparation - -During this workshop we will introduce [NymConnect](https://nymtech.net/developers/quickstart/nymconnect-gui.html) and [Socks5 client](https://nymtech.net/docs/clients/socks5-client.html). The difference between them is that the Socks5 client does everything Nymconnect does, but it has more optionality and it's run from a commandline. NymConnect is a one-button GUI application that wraps around the `nym-socks5-client` for proxying application traffic through the Mixnet. - -We will learn how to run through [Nym Mixnet](https://nymtech.net/docs/architecture/network-overview.html) the following applications: Electrum Bitcoin wallet, Monero wallet (desktop and CLI), Matrix (Element app) and ircd chat. For those who want to run ircd through the Mixnet, `nym-socks5-client` client is a must. For all other applications you can choose if you settle with our slick app NymConnect which does all the job in the background or you prefer Socks5 client. - -> Any syntax in `<>` brackets is a user's/version unique variable. Exchange with a corresponding name without the `<>` brackets. - -## NymConnect Installation - -NymConnect application is for everyone who does not want to install and run `nym-socks5-client`. NymConnect is plug-and-play, fast and easy use. Electrum Bitcoin wallet, Monero wallet (desktop and CLI) and Matrix (Element app) connects through NymConnect automatically to the Mixnet. - -1. [Download](https://nymtech.net/download/nymconnect) NymConnect -2. On Linux and Mac, make executable by opening terminal in the same directory and run: - -```sh -chmod +x ./nym-connect_.AppImage -``` - -3. Start the application -4. Click on `Connect` button to initialise the connection with the Mixnet -5. Anytime you'll need to setup Host and Port in your applications, click on `IP` and `Port` to copy the values to clipboard -6. In case you have problems such as `Gateway Issues`, try to reconnect or restart the application - -## Connect Privacy Enhanced Applications (PEApps) - -For simplification in this guide we connect Electrum, Monero wallet and Matrix (Element) using NymConnect and ircd over `nym-socks5-client`. Of course if your choice is to run `nym-socks5-client` all these apps will connect through that and you don't need to install NymConnect. - -```admonish info -This guide aims to connect your favourite applications to Nym Mixnet, therefore we do not include detailed guides on how to install them, only reference to the source pages. -``` - -### Electrum Bitcoin wallet via NymConnect - -To download Electrum visit the [official webpage](https://electrum.org/#download). To connect to the Mixnet follow these steps: - -1. Start and connect [NymConnect](./hcpp23-serinko.html#nymconnect-installation) (or [`nym-socks5-client`](./hcpp23-serinko.html#building-nym-platform)) -2. Start your Electrum Bitcoin wallet -3. Go to: *Tools* -> *Network* -> *Proxy* -4. Set *Use proxy* to ✅, choose `SOCKS5` from the drop-down and add the values from your NymConnect application -5. Now your Electrum Bitcoin wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. - -![Electrum Bitcoin wallet setup](../images/electrum_tutorial/electrum.gif) - -### Monero wallet via NymConnect - -To download Monero wallet visit [getmonero.org](https://www.getmonero.org/downloads/). To connect to the Mixnet follow these steps: - -1. Start and connect [NymConnect](./hcpp23-serinko.html#nymconnect-installation) (or [`nym-socks5-client`](./hcpp23-serinko.html#building-nym-platform)) -2. Start your Monero wallet -3. Go to: *Settings* -> *Interface* -> *Socks5 proxy* -> Add values: IP address `127.0.0.1`, Port `1080` (the values copied from NymConnect) -5. Now your Monero wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. - -![Monero wallet setup](../images/monero_tutorial/monero-gui-NC.gif) - -If you prefer to run Monero-CLI wallet with Monerod, please check out [this guide](https://nymtech.net/developers/tutorials/monero.html#how-can-i-use-monero-over-the-nym-mixnet). - -### Matrix (Element) via NymConnect - -To download Element (chat client for Matrix) visit [element.io](https://element.io/download). To connect to the Mixnet follow these steps: - -1. Start and connect [NymConnect](./hcpp23-serinko.html#nymconnect-installation) (or [`nym-socks5-client`](./hcpp23-serinko.html#building-nym-platform)) -2. Start `element-desktop` with `--proxy-server` argument: - -**Linux** - -```sh -element-desktop --proxy-server=socks5://127.0.0.1:1080 -``` - -**Mac** - -```sh -open -a Element --args --proxy-server=socks5://127.0.0.1:1080 -``` - -To setup your own alias or key-binding see our [*Matrix NymConnect Integration* guide](https://nymtech.net/developers/tutorials/matrix.html#optimise-setup-with-a-keybinding--alias). - - -## Building Nym Platform - -If you prefer to run to run `nym-socks5-client` the possibility is to download the pre-build binary or build the entire platform. To run ircd through the Mixnet `nym-socks5-client` and `nym-network-requester` are mandatory. Before you start with download and installation, make sure you are on the same machine from which you will connect to ircd. - -We recommend to clone and build the entire platform instead of individual binaries as it offers an easier update and more options down the road, however it takes a basic command-line knowledge and more time. The [Nym platform](https://github.com/nymtech/nym) is written in Rust. For that to work we will need a few pre-requisities. If you prefer to download individual pre-build binaries, skip this part and go directly [that chapter](./hcpp23-serinko.html#pre-built-binaries). - -### Prerequisites -- Debian/Ubuntu: `pkg-config`, `build-essential`, `libssl-dev`, `curl`, `jq`, `git` - -```sh -apt install pkg-config build-essential libssl-dev curl jq git -``` - -- Arch/Manjaro: `base-devel` - -```sh -pacman -S base-devel -``` - -- Mac OS X: `pkg-config` , `brew`, `openss1`, `protobuf`, `curl`, `git` -Running the following the script installs Homebrew and the above dependencies: - -```sh -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` - -- `Rust & cargo >= {{minimum_rust_version}}` - -We recommend using the [Rust shell script installer](https://www.rust-lang.org/tools/install). Installing cargo from your package manager (e.g. `apt`) is not recommended as the packaged versions are usually too old. - -If you really don't want to use the shell script installer, the [Rust installation docs](https://forge.rust-lang.org/infra/other-installation-methods.html) contain instructions for many platforms. - -### Download and Compile Nym - -The following commands will compile binaries into the `nym/target/release` directory: - -```sh -rustup update -git clone https://github.com/nymtech/nym.git -cd nym -git checkout master # master branch has the latest release version: `develop` will most likely be incompatible with deployed public networks -cargo build --release # build your binaries with **mainnet** configuration -``` - -Quite a bit of stuff gets built. The key working parts for the workshop are: - -* [socks5 client](https://nymtech.net/docs/clients/socks5-client.html): `nym-socks5-client` -* [network requester](https://nymtech.net/operators/nodes/network-requester-setup.html): `nym-network-requester` - -## Pre-built Binaries - -The [Github releases page](https://github.com/nymtech/nym/releases) has pre-built binaries which should work on Ubuntu 20.04 and other Debian-based systems, but at this stage cannot be guaranteed to work everywhere. - -**Download:** Find the binary of your choice, right click on the binary, select *Copy Link*. This will save the binary `` to clipboard. Run the following commands on your machine: - -``` -wget # to download the binary -``` - -If the pre-built binaries don't work or are unavailable for your system, you will need to [build the platform](./hcpp23-serinko.html#building-nym-platform) yourself. - -All Nym binaries must first be made executable. - -To make a binary executable, open terminal in the same directory and run: - -```sh -chmod +x ./ -# for example: chmod +x ./nym-network-requester -``` - -## Initialize Socks5 Client and Network Requester - -Whether you build the entire platform or downloaded binaries, `nym-socks5-client` and `nym-network-requester` need to be initialised with `init` before being `run`. - -In your terminal navigate to the directory where you have your `nym-socks5-client` and `nym-network-requester`. In case you built the entire platform it's in `nym/target/release`. - -```sh -# change directory from nym repo -cd target/release -``` - -**Network Requester** - -The `init` command is usually where you pass flags specifying configuration arguments such as the gateway you wish to communicate with, the ports you wish your binary to listen on, etc. - -The `init` command will also create the necessary keypairs and configuration files at `~/.nym///` if these files do not already exist. **It will NOT overwrite existing keypairs if they are present.** - -To run [ircd](https://darkrenaissance.github.io/darkfi/clients/nym_outbound.html) through the Mixnet you need to run your own [Network Requester](https://nymtech.net/operators/nodes/network-requester-setup.html) and add known peer's domains/addresses to `~/.nym/service-providers/network-requester//data/allowed.list`. For all other applications `nym-socks5-client` (or NymCOnnect) is enough, no need to initialize and run `nym-network-requester`. - -Here are the steps to initialize `nym-network-requester`: - -```sh -# open the directory with your binaries -./nym-network-requester init --id -``` -This will print you information about your client `
`, it will look like: -```sh -The address of this client is: 8hUvtEyZK8umsdxxPS2BizQhEDmbNeXEPBZLgscE57Zh.5P2bWn6WybVL8QgoPEUHf6h2zXktmwrWaqaucEBZy7Vb@5vC8spDvw5VDQ8Zvd9fVvBhbUDv9jABR4cXzd4Kh5vz -``` - -**Socks5 Client** - -If you run `nym-socks5-client` instead of NymConnect, you can choose your `--provider` [here](https://explorer.nymtech.net/network-components/service-providers) or leave that flag empty and your client will chose one randomly. To run ircd, you will need to connect it to your `nym-network-requester` by using your `
` for your `nym-socks5-client` initialisation and add a flag `--use-reply-surbs true`. Run the command in the next terminal window: - -```sh -# to connect to your nym-network-requester as a provider for ircd -./nym-socks5-client init --use-reply-surbs true --id --provider
- -# simple socks5 client init (random provider) for other apps -./nym-socks5-client init --id -``` - -```admonish info -You can reconfigure your binaries at any time by editing the config file located at `~/.nym/service-providers///config/config.toml` and restarting the binary process. -``` - -**Run Clients** - -Once you have run `init`, you can start your binary with the `run` command, accompanied by the `id` of the binary that you specified. - -This `id` is **never** transmitted over the network, and is used to select which local config and key files to use for startup. - -```sh -# network requester -./nym-network-requester run --id - -# socks5 client (in other terminal window) -./nym-socks5-client run --id -``` - -**Troubleshooting** - -In case your `nym-socks5-client` has a problem to connect to your `nym-network-requester` try to setup a firewall by running these commands: - -```sh -# check if you have ufw installed -ufw version - -# if it is not installed, install with -sudo apt install ufw -y - -# enable ufw -sudo ufw enable - -# check the status of the firewall -sudo ufw status - -# open firewall ports for network requester -sudo ufw allow 22,9000/tcp - -# re-check the ufw status -sudo ufw status -``` - -Restart your network requester. - - -## ircd - -[Dark.fi](htps://dark.fi) built a fully anonymous and p2p instance of IRC chat called [ircd](https://darkrenaissance.github.io/darkfi/misc/ircd/ircd.html). The team is just finishing their new instance of the program darkirc which we hope to see in production soon. - -```admonish info -It is highly recomended to install [dark.fi architecture](https://github.com/darkrenaissance/darkfi) prior to the workshop following the [documentation](https://darkrenaissance.github.io/darkfi/misc/ircd/ircd.html) so we have enough time for the network configuration. -``` - -### Configuration - -Make sure to have [ircd installed](https://darkrenaissance.github.io/darkfi/misc/ircd/ircd.html) on the same machine like your `nym-socks5-client` (`nym-network-requester` can run anywhere). - -Currently `nym-network-requester` automatically connnects only to the [whitelisted URLs](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt). This will [change soon](https://nymtech.net/operators/faq/smoosh-faq.html) into a more opened setup. This list can be changed by an operator running a node. - -**Edit allowed.list** - -1. Open a text editor and add: -```yaml -dasman.xyz -``` -2. Save it as `allowed.list` in `~/.nym/service-providers/network-requester//data/` -3. Restart your `nym-network-requester` -```sh -./nym-network-requester run --id -``` -4. Make sure both `nym-socks5-client` and `nym-network-requester` are running and connected - -**ircd setup** - -In case your ircd has problems to start or connect, run the following: - -```sh -# cd to darkfi repo -git pull -git checkout c4b78ead5111b0423fca3bd53cb7185acd6f0faa - -# compile ircd -make ircd - -# in case of dependency error: "failed to load source for dependency `halo2_gadgets`" -rm Cargo.lock -make ircd - -# remove the config file (rename it if you want to safe any values first) -rm ~/.config/darkfi/ircd_config.toml - -# rerun ircd to generate new config file -./ircd - -# add your custom values from the old config file -``` - -5. Open `~/.config/darkfi/ircd_config.toml` -6. Coment the line with `seeds` -7. Add line: -```yaml -peers = ["nym://dasman.xyz:25552"] -``` -8. Change `outbond_transports` to: -```yaml -outbond_transports = ["nym"] -``` -9. Make sure that -```yaml -outbound_connections = 0 -``` -10. Save and restart `ircd` - -Observe the ircd deamon to see that the communication is running through the mixnet. - -## Bonus: Join hcpp23 channel - -Now, when your Darkfi's ircd runs through Nym Mixnet, you can join public and fully anonymous channel `#hcpp23`. To do so, follow one of the two possibilities: - -1. Run a command in your weechat: -```sh -/join #hcpp23 -``` -2. Open `~/.config/darkfi/ircd_config.toml` and add `"#hcpp23"` to the `autojoin = []` brackets, save and restart ircd. - - diff --git a/documentation/dev-portal/src/events/web3-privacy.md b/documentation/dev-portal/src/events/web3-privacy.md deleted file mode 100644 index 83fd723719..0000000000 --- a/documentation/dev-portal/src/events/web3-privacy.md +++ /dev/null @@ -1,38 +0,0 @@ -# Web3 Privacy Now - Nym for Ethereum validator privacy - -Serinko's presentation on [Web3Privacy Now: Community 1st](https://lu.ma/web3privacynow_rome) introduces ***why network privacy matters*** for ETH 2.0 validators' security and decentralisation. - -This page serves as an accessible list of references mentioned during the talk. - -## References - -### Mixnet architecture - -* [Mixnet motivations](https://nymtech.net/developers/infrastructure/nym.html) -* [Mixnet architecture overview](https://nymtech.net/docs/architecture/network-overview.html) -* [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) -* [Tor + VPN comparison](https://nymtech.net/developers/infrastructure/nym-vs-others.html) -* [Addressing system](https://nymtech.net/docs/clients/addressing-system.html) - -### Nym \<\> ETH 2.0 - -* [Chainsafe Rust libp2p Nym intergration repo](https://github.com/ChainSafe/rust-libp2p-nym) -* [rust-libp2p-nym Transport Specification](https://hackmd.io/@nZ-twauPRISEa6G9zg3XRw/HkE8sHuns) -* [Lighthouse PoC](https://github.com/ChainSafe/lighthouse/blob/nym/USE_NYM.md) -* [Nym \<\> Aztec partnership](https://blog.nymtech.net/nym-partners-with-aztec-to-provide-integral-infrastructure-privacy-in-ethereum-chains-694963c55192) - -### Rust Examples - -* [Dev tutorial: chain service](https://nymtech.net/developers/tutorials/cosmos-service/intro.html) - -### Clients - -* [Clients overview](https://nymtech.net/docs/clients/overview.html) - -### Nym Docs - -* [Nym Developer Portal](https://nymtech.net/developers) -* [Nym Operators Guide](https://nymtech.net/operators) -* [Nym technical Documentation](https://nymtech.net/docs) - - diff --git a/documentation/dev-portal/src/examples/browser-only.md b/documentation/dev-portal/src/examples/browser-only.md deleted file mode 100644 index 01472bef22..0000000000 --- a/documentation/dev-portal/src/examples/browser-only.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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. - -- Oreowallet have integrated `mixFetch` into their browser-extension wallet to run transactions through the mixnet. - - [Codebase](https://github.com/oreoslabs/oreowallet-extension/tree/mixFetch) - -- [NoTrustVerify](https://notrustverify.ch/) 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/) - - [Codebase](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 deleted file mode 100644 index 94ff743464..0000000000 --- a/documentation/dev-portal/src/examples/custom-services.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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. - -> The current model of relying on a Service Provider has some issues, such as additional complexity in deployment and maintenance, as well as creating potential chokepoints for app traffic. Work is going on (in the open in our [monorepo](https://github.com/nymtech/nym) ofc) to start removing this requirement as much as possible, by allowing for the creation of packet-contents in such a way that the existing Network Requester/Exit Gateway infrastructure can support network requests in a similar way to `mixFetch`. More on this as and when it is released. - -- [Nym Zcash RPC demo](https://github.com/nymtech/nym-zcash-rpc-demo), although used to only pipe RPC traffic, is a proof of concept 'generic' mixnet piping example which exposes a TPC Socket on the client side for incoming traffic, pipes this through the mixnet, and then streams TCP packets 'out' the other side. A good example of non-app-specific traffic transport which developers could also quite easily use as a template for their own app-specific work. - - [Codebase](https://github.com/nymtech/nym-zcash-rpc-demo) - -- 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](https://notrustverify.ch/), 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/monorepo-examples.md b/documentation/dev-portal/src/examples/monorepo-examples.md deleted file mode 100644 index ad04287f20..0000000000 --- a/documentation/dev-portal/src/examples/monorepo-examples.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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/using-nrs.md b/documentation/dev-portal/src/examples/using-nrs.md deleted file mode 100644 index badcb7e7b7..0000000000 --- a/documentation/dev-portal/src/examples/using-nrs.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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 - now embeded in `nym-node` running as `exit-gateway`. - -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 - - -> 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 - - - - -- 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) diff --git a/documentation/dev-portal/src/faq/integrations-faq.md b/documentation/dev-portal/src/faq/integrations-faq.md deleted file mode 100644 index 71f833c864..0000000000 --- a/documentation/dev-portal/src/faq/integrations-faq.md +++ /dev/null @@ -1,198 +0,0 @@ -# Integrations FAQ - -On this page, you'll find links and frequently asked questions on how to get started on integrating your project with Nym's Mixnet and its blockchain, Nyx. - -## Links -### General Info -* [Nym Website](https://nymtech.net/) -* [Nym Mixnet Explorer](https://explorer.nymtech.net/) -* [Nyx Block Explorer](https://nym.explorers.guru/) - -### Codebase Info -* [Nym Platform Monorepo](https://github.com/nymtech/nym/) -* [Nym Project](https://github.com/nymtech/) - -### Documentation Info -* [Documentation](https://nymtech.net/docs/) -* Developer Portal - you are currently viewing the Developer Portal - -## Wallet Installation -The Nym wallet can be downloaded [here](https://nymtech.net/download/). - -You can find all the instructions related to setting up your wallet in the [docs](https://nymtech.net/docs/wallet/desktop-wallet.html), as well as instructions on how to build the wallet if there is not a downloadable version built for your operating system. - -### What are the machine hardware requirements for Nym Wallet? -About 16GB of RAM is recommended for the wallet. However you can expect an average memory usage of ~100MB. - - -## Interacting with the Nyx blockchain -### Where can I find information on the blockchain, such as RPC endpoints? -You can find most information required for integration in the [Cosmos Chain Registry](https://github.com/cosmos/chain-registry/blob/master/nyx/chain.json) and [Keplr Chain Registry](https://github.com/chainapsis/keplr-chain-registry/blob/main/cosmos/nyx.json) repositories. - -### How can I use `JSON-RPC` methods to interact with the Nyx blockchain? -There are multiple ways to use `JSON-RPC` methods to interact with the Nyx blockchain. Which method you use will depend on the type of application you are integrating Nyx interactions into. - -1. The standalone `nyxd` binary can be used for CLI wallets, interacting with smart contracts via the CLI, setting up RPC nodes, and even running validators. This is a version of the Cosmos Hub's `gaiad` binary compiled with Nyx chain configuration, and is written in `Go`. Instructions on setting up the `nyxd` binary can be found [here](https://nymtech.net/docs/nyx/interacting-with-chain.html). This is recommended for more complex commands. For full documentation check the [`gaiad documentation`](https://hub.cosmos.network/main/hub-overview/overview.html#). - -2. `CosmJS` is a Typescript library allowing for developers to interact with CosmosSDK blockchains from a Javascript or Typescript project. You can find it on Github [here](https://github.com/cosmos/cosmjs) and an explainer of its functionality [in the Cosmos Developer Portal](https://tutorials.cosmos.network/tutorials/7-cosmjs/1-cosmjs-intro.html). You can find a list of example apps which use CosmJS [here](https://codesandbox.io/examples/package/@cosmjs/stargate). - -3. The `Nym-CLI` tool, a standalone rust binary which can be built and used according to the [docs](https://nymtech.net/docs/tools/nym-cli.html) can be used in much the same way as `nyxd`. It is a bit simpler to use than the `nyxd` binary, but is not recommended for complex queries, and not all commands are currently implemented. A list of Nym CLI commands and example usage can be found [here](https://nymtech.net/docs/tools/nym-cli.html) - -### How do I generate an address/mnemonic for users to interact with? -**Nyxd** - -Use the following command, replacing `your_id` with the ID you want to use for your keypair: -``` -./nyxd keys add your_id --chain-id=nyx --gas=auto --gas-adjustment=1.4 --fees=7000unym -``` - -**Nym-CLI** -``` -./nym-cli account create -``` - -Both methods will generate a keypair and log the mnemonic in the console. - -**CosmJS** - -You can find example code for keypair generation [here](https://tutorials.cosmos.network/tutorials/7-cosmjs/2-first-steps.html#testnet-preparation). - -### How to get block information like block height, block hash, block time as so on? -**Nyxd** - -You would use one of the subcommands returned by this command: -``` -./nyxd query tx --chain-id=nyx --gas=auto --gas-adjustment=1.4 --fees=7000unym -``` - -**Nym-CLI** -``` -./nym-cli block current-height -``` - -**CosmJS** - -`CosmJS` documentation can be found [here](https://cosmos.github.io/cosmjs/). We will be working on example code blocks soon. - -### How to get account/address balance to check there is enough coins to withdraw? -**Nyxd** -``` -./nyxd query bank balances
--chain-id=nyx --gas=auto --gas-adjustment=1.4 --fees=7000unym -``` - -**Nym-CLI** -``` -./nym-cli account balance -``` - -**CosmJS** - -`CosmJS` documentation can be found [here](https://cosmos.github.io/cosmjs/). We will be working on example code blocks soon. - -### How do I transfer tokens to another address? -**Nyxd** -``` -./nyxd tx bank send [from_key_or_address] [to_address] [amount] --chain-id=nyx --gas=auto --gas-adjustment=1.4 --fees=7000unym -``` - -**Nym-CLI** -``` -./nym-cli account send TARGET_ADDRESS AMOUNT -``` -**CosmJS** - -`CosmJS` documentation can be found [here](https://cosmos.github.io/cosmjs/). We will be working on example code blocks soon. - -### Does the address support the inclusion of a `memo` or `destinationTag` when doing the transfer? -Yes, it is supported. - -### Can I use my Ledger hardware wallet to interact with the Nyx blockchain? -Yes. Follow the instructions in the [Ledger support for Nyx documentation](https://nymtech.net/docs/nyx/ledger-live.html). - -### Where can I find network details such as deployed smart contract addresses? -In the [`network defaults`](https://github.com/nymtech/nym/blob/master/common/network-defaults/src/mainnet.rs) file. - -## `NYM` Token -The token used to reward mixnet infrastructure operators - `NYM` - is one of the native tokens of the Nyx blockchain. The other token is `NYX`. - -`NYM` is used to incentivise the mixnet, whereas `NYX` is used to secure the Nyx blockchain via Validator staking. - -> Integration with Nym's technology stack will most likely involve using `NYM` if you do need to interact with the Nyx blockchain and transfer tokens. - -### I've seen an ERC20 representation of `NYM` on Ethereum - what's this and how do I use it? - -We use the [Gravity Bridge](https://github.com/Gravity-Bridge) blockchain to bridge an ERC20 representation of `NYM` between the Cosmos ecosystem of IBC-enabled chains and Ethereum mainnet. Gravity Bridge is its own IBC-enabled CosmosSDK chain, which interacts with a smart contract deployed on Ethereum mainnet. - -> The ERC20 representation of `NYM` **cannot** be used with the mixnet; only the native Cosmos representation is usable for staking or bonding nodes. - -If you need to transfer tokens across the bridge, we recommend users use Cosmostation's [spacestation.zone](https://spacestation.zone/) dApp with Metamask and Keplr. - -### What is Circulating Supply and how to find out the distribution amount? - -Circulating supply is the total number of available `NYM`. `NYM` is currently present on the IBC-enabled Nyx blockchain, as well as in ERC20 form on Ethereum Mainnet. - -The Validator API endpoints can be found via the [Swagger Documentation](https://validator.nymtech.net/api/swagger/index.html). The following endpoints can be called to retrieve the correct distribution amount and circulating supply within Nym. - -Using this API endpoint returns information about the circulating supply of Nym tokens: - -``` -/circulating-supply -``` -Query Response: - - { - "total_supply": { - "denom": "unym", - "amount": "1000000000000000" - }, - "mixmining_reserve": { - "denom": "unym", - "amount": "241105338883248" - }, - "vesting_tokens": { - "denom": "unym", - "amount": "390255200928865" - }, - "circulating_supply": { - "denom": "unym", - "amount": "368639460187887" - } - } - -- `total_supply`- The total number of NYM tokens that have been created and can exist, including those that are currently in circulation and those that are reserved for various purposes. - -- `mixmining_reserved`- The number of NYM tokens that are reserved for the mixnet miners who help to power the Nym network. - -- `vesting_tokens`- The number of NYM tokens that are subject to vesting, meaning they are gradually released over time to certain stakeholders such as the team, advisors, and early investors. - -- `circulating_supply`- The number of NYM tokens that are currently in circulation and available to be traded on the open market, which is calculated by subtracting the `mixmining_reserved` and `vesting_tokens` from the `total_supply`. - -Using this API endpoint returns the current value of the total supply of NYM tokens: - -``` -/circulating-supply/total-supply-value -``` -Query Response: - - 1000000000.0 - -> The maximum number of `NYM` tokens that can ever be created is 1 billion. - -Using this API endpoint returns the current value of the circulating supply of NYM tokens: - -``` -/circulating-supply/circulating-supply-value -``` -Query Response: - - 368639460.187887 - -> This refers to the present quantity of `NYM` tokens that are actively in circulation. - - -## Sending traffic through the Nym mixnet -### Is the mixnet free to use? -For the moment then yes, the mixnet is free to use. There are no limits on the amount of traffic that an app can send through the mixnet. - -### Do I need to run my own gateway to send application traffic through the mixnet? -No, although we do recommend that apps that wish to integrate look into running some of their own infrastructure such as gateways in order to assure uptime. diff --git a/documentation/dev-portal/src/faq/rewards-faq.md b/documentation/dev-portal/src/faq/rewards-faq.md deleted file mode 100644 index ecf1ceda7e..0000000000 --- a/documentation/dev-portal/src/faq/rewards-faq.md +++ /dev/null @@ -1,49 +0,0 @@ -# Rewards FAQ - -On this page you will find important information about participation in community activities which involve NYM token rewards, such as contests, giveaways, and promotions. Before participating in any such activity, make sure to read this page carefully. - -### Am I eligible to participate? What are the conditions? - -Participation in any program or community activity involving NYM token rewards is only available to individuals who do not reside in locations that makes them ineligible to participate and/or receive prizes, including: - -The USA, Central African Republic, Cuba, Iran, Iraq, Lebanon, Libya, North Korea, Somalia, South Sudan, Sudan, Syria, Venezuela, Yemen, and Russian occupied regions of Ukraine (including Crimea, and parts of Donetsk and Luhansk). - -Be nice and play fair! Nym reserves the right to determine the final outcome of its programs and community activities and disqualify any participants without prior notice or recourse for any reason, including fraudulent behavior and failure to adhere to the [Nym Code of Conduct](https://nymtech.net/docs/coc.html). - -### I won NYM rewards. How can I claim them? - -First things first: congratulations! We hope you had some fun in the process. A Nym Community Manger will tag you on Telegram or Discord - send them a private message to start the claim process. You will receive your unique reward ID and detailed instructions on how to use it to claim your rewards. **Remember: we never DM you first!** - -**Note: you have 2 weeks to claim your rewards! If we don't hear from you, your reward ID will expire.** - -### Do I need to pass KYC? - -Before receiving NYM token rewards, you are required to successfully complete KYC verification with Synaps, our KYC provider. You only need to do this once! - -### This is my first time - How do I pass KYC? - -To claim your rewards, you will be asked to provide your email address. If you haven't passed KYC yet, your email address will be added to our KYC whitelist and you will receive a welcome email from Synaps with instructions on how to start the KYC process. Once you complete KYC and provide a valid Nym wallet address, your rewards will be transferred to your wallet automatically. - -**Note: it may take up to 2 weeks for your email address to get whitelisted. Be patient and keep an eye on your inbox!** - -To receive your tokens, you will need a Nym wallet address. If you don't already have one, [download](https://nymtech.net/download/) the Nym wallet and create an account. You can copy your wallet address from the "receive" tab of the wallet. Make sure to keep your mnemonic safe, as losing that means losing your tokens. - -**Tip: If you are not sure you have completed Nym KYC before, visit our KYC portal on [Synaps](https://nym-kyc.synaps.me/signup) and try to log in with your email.** - -### I have already passed KYC on Synaps. What do I need to do next? - -If you have successfully completed KYC on Synaps earlier and provided your Nym wallet address, you are all set - we will send you a link so you can claim your rewards. - -**Note: after claiming your NYM rewards, it may take up to 3 weeks for the tokens to be transferred to your wallet. Be patient and keep an eye on your wallet!** - -### I received my NYM tokens. What can I do with them? - - We're glad you asked! The Nym network is the most robust privacy infrastructure the world has ever seen, and the NYM token is how you can access its [utility](https://www.youtube.com/watch?v=G1qrYlyFt48): - -* As a user, [unparalleled privacy](https://www.youtube.com/watch?v=SQHF4LkX7M8) for your communications -* As a [mix node operator](https://medium.com/nymtech/nym-mixnodes-deep-dive-d2b91917f097), rewards for your crucial role in operating our decentralized privacy infrastructure -* As a [delegator](https://medium.com/nymtech/want-to-stake-in-nym-here-is-how-to-choose-a-mix-node-to-delegate-nym-to-c3b862add165), rewards for securing the Nym network and ensuring outstanding quality of service - -Using the Nym network is free for now, but user fees will be introduced in the future and those will be paid in NYM tokens, so set them aside! And until then, you can contribute to running our decentralized infrastructure and earn mix mining rewards by setting up Nym mix nodes and bonding your tokens to them. You don't need to run nodes to contribute to the security and performance of the Nym network though. You can pledge your trust in someone else's node by delegating your NYM tokens to it, and receive a share of their mix mining rewards. - -You can find out more about how staking works in [this](https://www.youtube.com/watch?v=PcNGcTwlm0I) video from our Chief Scientist Claudia Diaz and if you need help setting up your mix node, choosing one to delegate your tokens to, or anything else, our community is there to help on [Discord](https://nymtech.net/go/discord) and [Telegram](https://t.me/nymchan). diff --git a/documentation/dev-portal/src/glossary.md b/documentation/dev-portal/src/glossary.md deleted file mode 100644 index 2e969c84b0..0000000000 --- a/documentation/dev-portal/src/glossary.md +++ /dev/null @@ -1,106 +0,0 @@ -# Glossary - -__Familiarise yourself with Nym's specific terms and jargon through our glossary, making your understanding of Nym technology more enjoyable and educational.__ - -## A -**[Address](https://nymtech.net/docs/stable/integrations/addresses-in-nym/)** - A unique string of characters generated from a client keypair. Used to identify clients in the mixnet. - -**[Ack](https://nymtech.net/docs/architecture/traffic-flow.html#acks--package-retransmission)** - Short for "acknowledgement". Whenever a hop is completed, the recieving node will send back an 'ack', so that the sending node knows that the packet was recieved. - -**Attacker** - A person or entity who attempts to gain unauthorised access to a computer system, network, or other information resource. - -## B -**Binary** - Is a type of computer file that contains machine code, which is a set of instructions that a computer can execute directly. The file consists of a series of 1s and 0s, which are the two digits used in the binary number system. - -**Blockchain** - A distributed database that maintains a continuously growing list of ordered records, called blocks. - -## C -**[Coconut](https://nymtech.net/docs/stable/coconut/)** - A distributed cryptographic signing scheme providing a high degree of privacy for its users. - -**[CLI](https://nymtech.net/docs/stable/nym-cli/)** - A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. - -**Credentials** - Unique values that prove the legitimacy of a user or individual. - -**Centralisation** - Refers to the concentration of control of an activity or organisation under a single authority, or small group of authorities. - -**[CosmWasm](https://cosmwasm.com)** - Cosmos WebAssembly is a WebAssembly (Wasm) interpreter that is used in the Cosmos SDK, a framework for building decentralised applications (dApps) on the Cosmos network. It allows us to write smart contracts in Rust and then compile them to webassembly to be uploaded on the blockchain. - -## D -**DAO** - Stands for Decentralised Autonomous Organisation. A type of organisation made up of smart contracts on a blockchain. It operates on a set of rules encoded in a computer program, and is governed by the people who use it, rather than by a central authority. - -**[Delegating NYM](https://medium.com/coinmonks/what-you-have-to-know-about-staking-and-delegating-458b6d2300a5)** - Similar to bonding but by non-operators and as proof of their trust in a node operator providing a good quality of service. - -**Decentralisation** - Refers to the transfer of control and decision-making from a centralised entity (individual, organization, or group thereof) to a distributed network. - -## E -**Encryption** - The process of encoding information. - -## G -**[Gateways](https://blog.nymtech.net/gateways-to-privacy-51196005bf5)** - The entrance to the mixnet that encrypted packets must pass through before being forwarded to mix nodes. They also act as a sort of mailbox for messages. - -**[Gateway Bonding](https://nymtech.net/docs/stable/run-nym-nodes/nodes/gateways/#bonding-your-gateway)** - The action of node operators to bond their stake (in the form of NYM tokens) to a Gateway in order to join the network topology and begin routing traffic through. - -## I -**IPFS** - Stands for InterPlanetary File System. It's a decentralised, peer-to-peer protocol for sharing and storing files. It is designed to make it easier to share and access large amounts of data in a distributed manner, without the need for a central server or authority - -## M -**[Metadata](https://www.opendatasoft.com/en/blog/what-is-metadata-and-why-is-it-important-data)** - A set of data that describes and gives information about other data such as IP addresses, device types, geolocations etc. - -**[Mixnet](https://nymtech.net/docs/architecture/traffic-flow.html#mixnet-traffic-flow-1)** - A routing protocol which encrypts and mixes Sphinx packet traffic so that it cannot be determined who is communicating with whom. - -**[Mix Nodes](https://blog.nymtech.net/nym-mixnodes-deep-dive-d2b91917f097)** - The backbone of the Nym infrastructure, that are organised in a three-layer network referred to as the mixnet that network traffic passes through. It mixes, hides and reorders traffic and are rewarded in NYM tokens for their quality of service. - -**[Mix node Bonding](https://nymtech.net/docs/stable/run-nym-nodes/nodes/mixnodes/#bonding-your-mix-node)** - The action of node operators bonding their stake (in the form of NYM tokens) to a Mix node in order to join the network topology and begin routing traffic through. - -## N -**[Network Requester](https://nymtech.net/docs/stable/run-nym-nodes/nodes/requester)** - Is a binary that can be ran alongside a Nym Client on a VPS, which allows for private network requests to be made outside the mixnet from you local Nym client - -**Nym** - The in-text name of the organisation. - -**[Nym Typescript SDK](https://nymtech.net/docs/stable/sdk/overview)** - A Typescript software development kit which allows developers to build browser-based Mixnet application. - -**[NYM](https://nymtech.net/docs/stable/nym-cli/#send-tokens-to-an-account)** - Natively distributed token. - -**[Nym Wallet](https://nymtech.net/docs/stable/wallet/)** - The Nym Wallet handles all things regarding handling Nym Tokens about your Nym Node. It is a GUI application that can be downloaded and run on your machine. - -**[Nym Technologies SA](https://nymtech.net)** - The official company name. - -**[Nyx](https://nymtech.net/docs/stable/integrations/payment-integration-overview/)** - A CosmWasm-enabled blockchain smart contracts platform that functions as the backbone of the Nym network, used to keep track and provide the history of the NYM token's transactions. - -## P -**Payload** - The carrying capacity of a packet or other transmission data unit. - -**Pledge** - The number of tokens that are put up by node operators on their nodes as their commitment to provide good quality of service and insure against future bad behaviour. - -**Private Key** - A large numerical value that is used to decrypt data. - -**Proof-of-Mixing** - The reward of NYM tokens is based on the good quality of service carried out by node operators. - -**POC** - Stands for Proof of Concept. It's a demonstration that a proposed product, system, or service can be built and will work as intended. It is a way of testing whether an idea is feasible and likely to succeed. - -**Public Key** - A large numerical value that is used to encrypt data. - -## S -**Sphinx** - A cryptographic message format used to relay anonymised messages within the mixnet, also used by the Lightning Network or something similar. - -**[Socks5](https://en.wikipedia.org/wiki/SOCKS)** - An proxy protocol that exchanges network packets between a client and server through a proxy server. - -**[Service Provider](https://nymtech.net/docs/stable/tutorials/nym-simple-websocket-tutorial/)** - Any type of app that can communicate with the mixnet via a Nym Client. - -**[SURBs](https://nymtech.net/docs/architecture/traffic-flow.html#private-replies-using-surbs)** - Stands for 'Single Use Reply Blocks'. They are a type of crytographic construct used to facilitate secure communication between parties and are designed to allow a sender to send a message to a recipient in sucha a way that the message can only be read by the intended recipient, and cannot be read by anyone else. - -**Sybil** - In the context of computer networks, a Sybil attach is a type of security attack in which an attacker creates multiple fake identities or "sybils" and uses them to manipulate a network thus gaining control of a network by overwhelming it. - -## T -**Tokenomics** - Is the study of the economic and financial aspects of a cryptocurrency or blockchain-based project. It involves the creation, distribution, and management of tokens, which are digital assets that represent a certain value of utility whithin a particular ecosystem. - -## V -**[Validators](https://nymtech.net/docs/stable/run-nym-nodes/nodes/validators/)** - Secures the Nyx blockchain with a staking token, defending the network from attacks. - -**[VPS](https://en.wikipedia.org/wiki/Virtual_private_server)** - Stands for Virtual Private Server. Its a virtual machine that acts as an isolated virtual environment on a physical server operated by a cloud, web or internet hosting provider. - -## W -**Websocket** - A computer communications protocol that provides a full-duplex channel over a single TCP connection. It is designed to be used as a base for real-time, two-way communication between a client and a server over the web. - -## Z -**Zero Knowledge Proofs** - Cryptographic techniques that make it possible to prove something to be true without having to reveal the evidence. diff --git a/documentation/dev-portal/src/images/element_nym_keybind.png b/documentation/dev-portal/src/images/element_nym_keybind.png deleted file mode 100644 index d0bd383494..0000000000 Binary files a/documentation/dev-portal/src/images/element_nym_keybind.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/firo_tutorial/firo.png b/documentation/dev-portal/src/images/firo_tutorial/firo.png deleted file mode 100644 index ed1d7a0789..0000000000 Binary files a/documentation/dev-portal/src/images/firo_tutorial/firo.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/icons/discord_icon.png b/documentation/dev-portal/src/images/icons/discord_icon.png deleted file mode 100644 index 5b5cc32b0e..0000000000 Binary files a/documentation/dev-portal/src/images/icons/discord_icon.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/icons/element_icon.png b/documentation/dev-portal/src/images/icons/element_icon.png deleted file mode 100644 index 7c8db46df7..0000000000 Binary files a/documentation/dev-portal/src/images/icons/element_icon.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/icons/telegram_icon.png b/documentation/dev-portal/src/images/icons/telegram_icon.png deleted file mode 100644 index 0d2249f337..0000000000 Binary files a/documentation/dev-portal/src/images/icons/telegram_icon.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/icons/twitter_icon.png b/documentation/dev-portal/src/images/icons/twitter_icon.png deleted file mode 100644 index 0ae0d42f34..0000000000 Binary files a/documentation/dev-portal/src/images/icons/twitter_icon.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/icons/youtube_icon.png b/documentation/dev-portal/src/images/icons/youtube_icon.png deleted file mode 100644 index 88c0fe1143..0000000000 Binary files a/documentation/dev-portal/src/images/icons/youtube_icon.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ifps-sp-image.png b/documentation/dev-portal/src/images/ifps-sp-image.png deleted file mode 100644 index 12b6b92bba..0000000000 Binary files a/documentation/dev-portal/src/images/ifps-sp-image.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-1.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-1.png deleted file mode 100644 index 983455db54..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-1.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-2.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-2.png deleted file mode 100644 index 71f282a607..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-2.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-3.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-3.png deleted file mode 100644 index ec42093884..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/angular-app-3.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-1.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-1.png deleted file mode 100644 index 1deed94387..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-1.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-2.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-2.png deleted file mode 100644 index a1eb0cb92b..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-2.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-3.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-3.png deleted file mode 100644 index 194b847dd3..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/demo-ipfs-3.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-1.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-1.png deleted file mode 100644 index deed0f7980..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-1.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-2.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-2.png deleted file mode 100644 index b65bf187bc..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-2.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-3.png b/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-3.png deleted file mode 100644 index ed3123ea61..0000000000 Binary files a/documentation/dev-portal/src/images/ipfs-upload-service-tutorial/ipfs-user-client-3.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/matrix.png b/documentation/dev-portal/src/images/matrix.png deleted file mode 100644 index 2ea4ae4bf0..0000000000 Binary files a/documentation/dev-portal/src/images/matrix.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/matrix.webp b/documentation/dev-portal/src/images/matrix.webp deleted file mode 100644 index 4faa931660..0000000000 Binary files a/documentation/dev-portal/src/images/matrix.webp and /dev/null differ diff --git a/documentation/dev-portal/src/images/monero_tutorial/monero-gui-NC.gif b/documentation/dev-portal/src/images/monero_tutorial/monero-gui-NC.gif deleted file mode 100644 index f5ec96f462..0000000000 Binary files a/documentation/dev-portal/src/images/monero_tutorial/monero-gui-NC.gif and /dev/null differ diff --git a/documentation/dev-portal/src/images/monero_tutorial/monero.png b/documentation/dev-portal/src/images/monero_tutorial/monero.png deleted file mode 100644 index 3c7fadd32a..0000000000 Binary files a/documentation/dev-portal/src/images/monero_tutorial/monero.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/nym-client_image.png b/documentation/dev-portal/src/images/nym-client_image.png deleted file mode 100644 index b954e08082..0000000000 Binary files a/documentation/dev-portal/src/images/nym-client_image.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/nym-vs-animation.gif b/documentation/dev-portal/src/images/nym-vs-animation.gif deleted file mode 100644 index 797978d74d..0000000000 Binary files a/documentation/dev-portal/src/images/nym-vs-animation.gif and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/darkfi_over_nym_pp.png b/documentation/dev-portal/src/images/profile_picture/darkfi_over_nym_pp.png deleted file mode 100644 index 9ae44d85c1..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/darkfi_over_nym_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/ethereum_rpc_spook_pp.png b/documentation/dev-portal/src/images/profile_picture/ethereum_rpc_spook_pp.png deleted file mode 100644 index b7a593a68a..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/ethereum_rpc_spook_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/ethereum_transaction_broadcaster_root_pp.png b/documentation/dev-portal/src/images/profile_picture/ethereum_transaction_broadcaster_root_pp.png deleted file mode 100644 index 45755cf565..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/ethereum_transaction_broadcaster_root_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/minibolt_pp.png b/documentation/dev-portal/src/images/profile_picture/minibolt_pp.png deleted file mode 100644 index 455243cc22..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/minibolt_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/nym_dashboard_pp.svg b/documentation/dev-portal/src/images/profile_picture/nym_dashboard_pp.svg deleted file mode 100644 index e91f3abdb4..0000000000 --- a/documentation/dev-portal/src/images/profile_picture/nym_dashboard_pp.svg +++ /dev/null @@ -1,57 +0,0 @@ - - - - - - - - - - - - diff --git a/documentation/dev-portal/src/images/profile_picture/nymdrive_saleel_pp.png b/documentation/dev-portal/src/images/profile_picture/nymdrive_saleel_pp.png deleted file mode 100644 index a2fab0447f..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/nymdrive_saleel_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/nymgraph_pp.png b/documentation/dev-portal/src/images/profile_picture/nymgraph_pp.png deleted file mode 100644 index 411dbec6e0..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/nymgraph_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/nymstr_email_pp.png b/documentation/dev-portal/src/images/profile_picture/nymstr_email_pp.png deleted file mode 100644 index 404b9e2529..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/nymstr_email_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/pastenym_ntv_pp.png b/documentation/dev-portal/src/images/profile_picture/pastenym_ntv_pp.png deleted file mode 100644 index 79df7280f5..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/pastenym_ntv_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/profile_picture/pineappleproxy_pp.png b/documentation/dev-portal/src/images/profile_picture/pineappleproxy_pp.png deleted file mode 100644 index fcb7ab5cd8..0000000000 Binary files a/documentation/dev-portal/src/images/profile_picture/pineappleproxy_pp.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/ssp_image.png b/documentation/dev-portal/src/images/ssp_image.png deleted file mode 100644 index 9a06073927..0000000000 Binary files a/documentation/dev-portal/src/images/ssp_image.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/telegram.png b/documentation/dev-portal/src/images/telegram.png deleted file mode 100644 index e65407a5b6..0000000000 Binary files a/documentation/dev-portal/src/images/telegram.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/telegram.webp b/documentation/dev-portal/src/images/telegram.webp deleted file mode 100644 index b9448ec965..0000000000 Binary files a/documentation/dev-portal/src/images/telegram.webp and /dev/null differ diff --git a/documentation/dev-portal/src/images/tutorial_image_1.png b/documentation/dev-portal/src/images/tutorial_image_1.png deleted file mode 100644 index a9ddda654b..0000000000 Binary files a/documentation/dev-portal/src/images/tutorial_image_1.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/tutorial_image_2.png b/documentation/dev-portal/src/images/tutorial_image_2.png deleted file mode 100644 index 394ace8046..0000000000 Binary files a/documentation/dev-portal/src/images/tutorial_image_2.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/tutorial_image_4.png b/documentation/dev-portal/src/images/tutorial_image_4.png deleted file mode 100644 index 50fcff9ec6..0000000000 Binary files a/documentation/dev-portal/src/images/tutorial_image_4.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/tutorial_image_5.png b/documentation/dev-portal/src/images/tutorial_image_5.png deleted file mode 100644 index 201b36c845..0000000000 Binary files a/documentation/dev-portal/src/images/tutorial_image_5.png and /dev/null differ diff --git a/documentation/dev-portal/src/images/wallet-proxy-settings/blockstream-green.gif b/documentation/dev-portal/src/images/wallet-proxy-settings/blockstream-green.gif deleted file mode 100644 index 33e2725c29..0000000000 Binary files a/documentation/dev-portal/src/images/wallet-proxy-settings/blockstream-green.gif and /dev/null differ diff --git a/documentation/dev-portal/src/info-request.md b/documentation/dev-portal/src/info-request.md deleted file mode 100644 index e3edbdc3de..0000000000 --- a/documentation/dev-portal/src/info-request.md +++ /dev/null @@ -1,14 +0,0 @@ -# Change Service Grantee Information - -If you wish to update any of the following information: - - `Email Address` - - `NYM address` - - `Network Requester` - - `Gateway ID Key` - - `Gateway Address` - - `Service` - - `Payment Address` - -Please reach out either in the `#service-grantees` channel on Discord or on [Matrix](https://matrix.to/#/#nym-community:nymtech.chat). - - diff --git a/documentation/dev-portal/src/infrastructure/node-types.md b/documentation/dev-portal/src/infrastructure/node-types.md deleted file mode 100644 index cb5e9c3d35..0000000000 --- a/documentation/dev-portal/src/infrastructure/node-types.md +++ /dev/null @@ -1,14 +0,0 @@ -# Node Types - -Discover the workings of Nym's privacy-enhancing mixnet infrastructure through the below video, where we break down the different types of nodes and how they each play a crucial role in ensuring secure and anonymous communication. - - - -### 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), 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: -* Explore the [Quickstart](../quickstart/overview.md) options. -* Check out examples of [Community Apps](../community-resources/community-applications-and-guides.md). -* Run through the [Rust SDK](../tutorials/rust-sdk.md) or [Typescript](../tutorials/typescript.md) tutorials. diff --git a/documentation/dev-portal/src/infrastructure/nym.md b/documentation/dev-portal/src/infrastructure/nym.md deleted file mode 100644 index 53bc4b377f..0000000000 --- a/documentation/dev-portal/src/infrastructure/nym.md +++ /dev/null @@ -1,33 +0,0 @@ -# What is Nym? - -Nym is a privacy platform that secures user data and protects against surveillance. It leverages the [mixnet](./node-types.md), a type of overlay network that makes both content and metadata of transactions private through network-level obfuscation and incentivisation, and [Coconut](https://nymtech.net/docs/coconut.html), a privacy technology that creates an application-level private access control layer. Nym also utilises [Nyx](https://blog.nymtech.net/nym-now-supports-smart-contracts-2186da46bc7f), our Cosmos SDK blockchain, to allow for us to use payment tokens in the form of `NYM`, as well as smart contracts, in order to create a robust, decentralised, and secure environment for the mixnet. In a nutshell, Nym is a solution that provides strong privacy protection for users in the digital world. - -> All the technical nuances about Nym platform can come out quite complex at first. Look for any questions in the [FAQ section](../faq/general-faq.md), take part in our [DevRel AMAs](../community-resources/ama.md) or seek support in [Nym's community](https://nymtech.net/community) - -### An overlay network for network-level traffic privacy -Our mixnet design is based on the [Loopix Anonymity System](https://arxiv.org/abs/1703.00536), somewhat modified to provide better quality of service guarantees. - -In this brief video, our Head of Research and creator of the Loopix mixnet paper, Ania Piotrowska, delves into the design of the Loopix mixnet in depth at USENix 2017. - - - - -The Nym mixnet effectively addresses privacy concerns by utilizing network nodes to mix messages, making them unidentifiable to adversaries. Each packet is layer encrypted, and binary-padded so that it's indistinguishable from all other packets. Incoming packets are "mixed" with all other messages inside the node. That is, the node strips one layer of packet encryption, and adds a small random transmission delay, so that messages are not emitted in the same order as which they arrived. - -Next, the message is sent to another mix node, decrypted and mixed again, then to a third mixnode for further mixing. Finally, the message is delivered to its destination gateway. - -As long as there's enough traffic flowing through the nodes, even an adversary who can monitor the entire network cannot trace the packet flow through the system. - -Privacy Enhanced Applications (PEApps) that need to defend against network-level monitoring can utilize the Nym mixnet to protect against network-level surveillance. - -### Revolutionising Privacy: An Incentivized Mixnet, the First of its Kind -Nym is the first mixnet to incentivise its node operators via a cryptocurrency: the `NYM` token. The tokenomic design of Nym ensures that nodes are motivated to provide top-notch performance and robust security, as they are financially rewarded for doing so. The video below contains an explanation of Nym's tokenomic design from Nym's Chief Scientist Claudia Diaz: - - - -### ELI5 Understanding of the Implications of Nym -Nym is a type of technology that is designed to keep your online activities private from surveillance networks which track users of many online services. As well as protecting the contents of your messages - the data - Nym's design means that metadata - data about the data - is also kept private. This means that the location from which you sent your message, the time you did so, and a lot of information about your network connection is kept private: this is information that can be used to deanonymise users of other privacy systems, even if they employ encrypted messaging! - -Nym works by "mixing" your data with other users' data, making it much more difficult for anyone to single out and track just your information. - -This system is unique because it provides an incentive for people to participate and help improve the network, making it stronger and more secure for everyone. By breaking down Nym and understanding its implications, you can see why it's an important tool for anyone who values their privacy online. diff --git a/documentation/dev-portal/src/integrations/integration-options.md b/documentation/dev-portal/src/integrations/integration-options.md deleted file mode 100644 index 5c7d417420..0000000000 --- a/documentation/dev-portal/src/integrations/integration-options.md +++ /dev/null @@ -1,12 +0,0 @@ -# Integration Options -If you've already gone through the different 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. - -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. - -- **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. - -> 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 deleted file mode 100644 index a26f0a885b..0000000000 --- a/documentation/dev-portal/src/integrations/mixnet-integration.md +++ /dev/null @@ -1,175 +0,0 @@ -# Integrating with Nym for network privacy -If you are wanting to integrate Nym by using the Mixnet as a transport layer for application traffic, you will have to run one of the three Nym clients in order to connect to the Mixnet. - -## Connecting applications to the mixnet -### SDK support -If your app is written in Typescript or Rust, then you can use the [Typescript](https://nymtech.net/docs/sdk/typescript.html) or [Rust](https://nymtech.net/docs/sdk/rust.html) SDKs. These SDKs abstract away much of the messaging logic from your app, and allow you to run a Nym client as part of your application process, instead of having to run them seperately. - -### Choosing a client -In order to connect your application to the mixnet, you need to select one of three clients to use. These clients do the majority of the heavy-lifting with regards to cryptographic operations and routing under the hood, and all do basically the same thing: create a connection to a gateway, encrypt and decrypt packets sent to and received from the mixnet, and send cover traffic to hide the flow of actual app traffic from observers. - -As outlined in the [clients overview documentation](https://nymtech.net/docs/clients/overview.html) there are three clients availiable to developers to use when connecting applications to the mixnet: - -#### 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).) - -#### 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. - -It’s packaged and available on the npm registry, so you can npm install it into your JavaScript or TypeScript application. - -The webassembly client is most easily used via the [typescript sdk](https://nymtech.net/docs/sdk/typescript.html). - -You can find example code in the [examples section](https://github.com/nymtech/nym/tree/master/sdk/typescript/examples) of the codebase, and in the [typescript sdk docs](https://nymtech.net/docs/sdk/typescript.html). - -#### SOCKS client -This client is useful for allowing existing applications to use the Nym mixnet without any code changes. All that’s necessary is that they can use one of the SOCKS5, SOCKS4a, or SOCKS4 proxy protocols (which many applications can - crypto wallets, browsers, chat applications etc). - -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. - -You can find examples of how to utilise this client in the [Quickstart](../quickstart/socks-proxy.md) section, and the [SOCKS5 documentation](https://nymtech.net/docs/clients/socks5-client.html). - -## Recommended infrastructure setup -In order to ensure uptime and reliability, it is recommended that you run some pieces of mixnet infrastructure. What infrastructure is necessary to run depends on the architecture of your application, and the endpoints that it needs to hit! - -* If you're running a purely P2P application, then just integrating clients and having some method of sharing addresses should be enough to route your traffic through the mixnet. -* If you're wanting to place the mixnet between your users' application instances and a server-based backend, you can use the [network requester](https://nymtech.net/operators/nodes/network-requester-setup.html) service provider binary to proxy these requests to your application backend, with the mixnet 'between' the user and your service, in order to prevent metadata leakage being broadcast to the internet. -* If you're wanting to route RPC requests through the mixnet to a blockchain, you will need to look into setting up some sort of service that does the transaction broadcasting for you. You can find examples of such projects on the [community applications](../community-resources/community-applications-and-guides.md) page. - -## Example application traffic flow -### Initialization -First, we need to initalise an app and connect it to Nym. - - -``` - +-----------+ - | Gateway | - +-----------+ - ^ - | - | - | - | - | - | - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine -``` - -At the bottom we have an app. It consists of two parts: - -* your application specific logic -* your Nym client - either running as a standalone process, or as part of the process of your app code if you're using an SDK - -Nym apps have a stable, potentially long-lasting relation to a gateway node. A client will register itself with a gateway, and get back an authentication token that it can then use to retrieve messages from the gateway later on. - -Gateways serve a few different functions: - -* they act as an end-to-end encrypted message store in case your app goes offline. -* they send encrypted surb-acks for potentially offline recipients, to ensure reliable message delivery -* they offer a stable addressing location for apps, although the IP may change frequently - -### Sending messages to ourselves -The Nym client part of the app accepts messages from your code and automatically turns it into layer-encrypted Sphinx packets. If your message is too big to fit inside on Sphinx packet, it'll be split into multiple packets with a sequence numbers to ensure reliable automatic reassembly of the full message when it gets to the recipient. - -The app has now connected to the Gateway, but we haven't sent a message to ourselves yet. Let's do that now. - -``` - - +----------+ +----------+ +----------+ - | Mix Node |<-----------> | Mix Node |<----------->| Mix Node | - | Layer 1 | | Layer 2 | | Layer 3 | - +----------+ +----------+ +----------+ - ^ ^ - | | - |<--------------------------------------------------+ - | - v - +--------------+ - | Your gateway | - +--------------+ - ^ - | - | - v - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine** - - -** note that depending on the technical setup, the Nym client running on this machine may -be either a seperate process or embedded in the same process as the app code via one of our SDKs. -``` - -Let's say your code code pokes a message `hello world` into the Nym client. The Nym client automatically wraps that message up into a layer encrypted Sphinx packet, adds some routing information and encryption, and sends it to its own gateway. The gateway strips the first layer of encryption, ending up with the address of the first mixnode it should forward to, and a Sphinx packet. - -The gateway forwards the Sphinx packet containing the `hello world` message. Each mixnode in turn forwards to the next mixnode. The last mixnode forwards to the recipient gateway (in this case, our own gateway since we are sending to ourselves). - -Our app has presumably not gone offline in the short time since the message was sent. So when the gateway receives the packet, it decrypts the packet and sends the (encrypted) content back to our app. - -The Nym client inside the app decrypts the message, and your code receives the message `hello world`, again as a websocket event. - -Messages are end-to-end encrypted. Although the gateway knows our app's IP when it connects, it's unable to read any of the message contents. - -### Sending messages to other apps -The process for sending messages to other apps is exactly the same, you simply specify a different recipient address. Address discovery happens outside the Nym system: in the case of a Service Provider app, the service provider has presumably advertised its own address. If you're sending to a friend of yours, you'll need to get a hold of their address out of band, maybe through a private messaging app such as Signal. - -``` - - +----------+ +----------+ +----------+ - | Mix Node |<-----------> | Mix Node |<----------->| Mix Node | - | Layer 1 | | Layer 2 | | Layer 3 | - +----------+ +----------+ +----------+ - ^ ^ - | | - | | - v v - +--------------+ +-----------------+ - | Your gateway | | Service gateway | - +--------------+ +-----------------+ - ^ ^ - | | - | | - v v - +-------------------+ +-------------------+ - | +---------------+ | | +---------------+ | - | | Nym client | | | | Nym Client | | - | +---------------+ | | +---------------+ | - | ^ | | ^ | - | | | | | | - | | | | | | - | v | | v | - | +---------------+ | | +---------------+ | - | | Your app code | | | | Service Code | | - | +---------------+ | | +---------------+ | - +-------------------+ +-------------------+ - Your Local Machine** Service Provider Machine** - - -** note that depending on the technical setup, the Nym client running on these machines may -be either a seperate process or embedded in the same process as the app code via one of our SDKs. -``` diff --git a/documentation/dev-portal/src/integrations/payment-integration.md b/documentation/dev-portal/src/integrations/payment-integration.md deleted file mode 100644 index 937702a3bd..0000000000 --- a/documentation/dev-portal/src/integrations/payment-integration.md +++ /dev/null @@ -1,16 +0,0 @@ -# Integrating with Nyx for payments - -If you want to integrate with Nym in order to send `NYM` tokens (for instance, if running a `NYM` <-> `BTC` swap application, or using `NYM` for payments), then you will need to interact with the Nyx blockchain. - -Nyx is the blockchain supporting the Nym network, hosting both the `NYM` and `NYX` cryptocurrencies, the CosmWasm smart contracts keeping track of the network, and (coming soon) facilitating zk-Nym credential generation. It is built with the [Cosmos SDK](https://tendermint.com/sdk/). - -### Interacting with the Nyx blockchain -Check out the integration options in the [Integration FAQ](../faq/integrations-faq.md#how-can-i-use-json-rpc-methods-to-interact-with-the-nyx-blockchain). - -### Chain information and RPC endpoints -You can find most information required for integration in the [Cosmos Chain Registry](https://github.com/cosmos/chain-registry/blob/master/nyx/chain.json) and [Keplr Chain Registry](https://github.com/chainapsis/keplr-chain-registry/blob/main/cosmos/nyx.json) repositories. - -## Recommended setup -We recommend that users wanting to integrate with Nyx for cryptocurrency payments set up their own RPC Node, in order to be able to reliably query the blockchain and send transactions without having to worry about relying on 3rd party validators. - -The guide to setting up an RPC node can be found [here](https://nymtech.net/docs/nyx/rpc-node.html). diff --git a/documentation/dev-portal/src/introduction.md b/documentation/dev-portal/src/introduction.md deleted file mode 100644 index 742853c56c..0000000000 --- a/documentation/dev-portal/src/introduction.md +++ /dev/null @@ -1,9 +0,0 @@ -# Introduction - -Welcome to the Nym Developer Portal, containing quickstart resources, user manuals, integration information, and tutorials outlining to start building privacy enhanced apps. - -For more in-depth information about nodes, network traffic flows, clients, coconut etc check out the [docs](https://nymtech.net/docs). - -If you are looking for information and setup guides for the various pieces of Nym mixnet infrastructure (mix nodes, gateways and network requesters) and Nyx blockchain validators see the [Operators Guides](https://nymtech.net/operators) book. - -If you're looking for TypeScript/JavaScript related information such as SDKs to build your own tools, step-by-step tutorials, live playgrounds and more, make sure to check out the [TS SDK Handbook](https://sdk.nymtech.net/). diff --git a/documentation/dev-portal/src/not-found.md b/documentation/dev-portal/src/not-found.md deleted file mode 100644 index 704da5ec19..0000000000 --- a/documentation/dev-portal/src/not-found.md +++ /dev/null @@ -1,11 +0,0 @@ -# Page Not Found - -You seem to have followed a link to a page that no longer exists. Our documentation is changing and growing over time, so this page has most likely been moved somewhere else. - -For node setup guides, see the [Operator Guides book](https://nymtech.net/operators). - -For information on network architecture traffic flow, clients, the SDKs, or interacting with the Nyx blockchain see the [Technical Documentation](https://nymtech.net/docs). - -If you are looking for information on developer tutorials, app guides, and demo and community apps, check the sitemap on the left hand side of the screen. - -If you still can't find what you're looking for get in touch with us via [Matrix](https://matrix.to/#/#nym-community:nymtech.chat). \ No newline at end of file diff --git a/documentation/dev-portal/src/nymvpn/cli.bak b/documentation/dev-portal/src/nymvpn/cli.bak deleted file mode 100644 index f040b9cff2..0000000000 --- a/documentation/dev-portal/src/nymvpn/cli.bak +++ /dev/null @@ -1,35 +0,0 @@ -# NymVPN Command Line Interface (CLI) - -```admonish info -Our alpha testing round is done with participants at live workshop events. This guide will not work for everyone, as the NymVPN source code is not yet publicly accessible. The alpha testing is done on Nym testnet Sandbox environment, this configuration is limited and will not work in the future. - -**If you commit to test NymVPN alpha, please start with the [user research form]({{nym_vpn_form_url}}) where all the steps will be provided**. If you disagree with any of the conditions listed, please leave this page. -``` - -Follow the simple [automated script](#automated-script-for-cli-installation) below to install and run NymVPN CLI. If you prefer to do a manual setup follow the steps in the guide for [Linux](cli-linux.md) or [MacOS](cli-mac.md). - -Visit NymVPN alpha latest [release page]({{nym_vpn_releases}}) to check sha sums or download the binaries directly. - -## Automated Script for CLI Installation - -We wrote a [script](https://gist.github.com/serinko/d65450653d6bbafacbcee71c9cb8fb31) which does download of the CLI, sha256 verification, extraction, installation and configuration for Linux and MacOS users automatically following the steps below: - -1. Open a terminal window in a directory where you want the script and NymVPN CLI binary be downloaded and run -```sh -curl -o execute-nym-vpn-cli-binary.sh -L https://gist.githubusercontent.com/tommyv1987/87267ded27e1eb7651aa9cc745ddf4af/raw/d39f98dbb36ccff761a7e940073388a6fe7b73fe/execute-nym-vpn-cli-binary.sh && chmod u+x execute-nym-vpn-cli-binary.sh && sudo -E ./execute-nym-vpn-cli-binary.sh -``` - -2. Follow the prompts in the program - -3. The script will automatically start the client. Make sure to **turn off any other VPNs** and follow the prompts: - -* It prints a JSON view of existing Gateways and prompt you to: - - *Make sure to use two different Gateways for entry and exit!* - - `enter a gateway ID:` paste one of the values labeled with a key `"identityKey"` printed above (without `" "`) - - `enter an exit address:` paste one of the values labeled with a key `"address"` printed above (without `" "`) - - `do you want five hop or two hop?`: type `five` or `two` - - `enable WireGuard? (yes/no):` if you chose yes, find your private key and wireguard IP [here](https://nymvpn.com/en/alpha) - -To run `nym-vpn-cli` again, reconnect your wifi, move to the directory of your CLI binary `cd ~/nym-vpn-cli-dir` and follow the guide for [Linux](cli-linux.md#run-nymvpn) or [MacOS](cli-mac.md#run-nymvpn). If you find it too difficult, just run this script again - like in step \#3 above. - -In case of errors check out the [troubleshooting](troubleshooting.md) section. diff --git a/documentation/dev-portal/src/nymvpn/images/image1.png b/documentation/dev-portal/src/nymvpn/images/image1.png deleted file mode 100644 index d5f9bcb2f5..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/image1.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/images/image2.png b/documentation/dev-portal/src/nymvpn/images/image2.png deleted file mode 100644 index 14b501383c..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/image2.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/images/image3.png b/documentation/dev-portal/src/nymvpn/images/image3.png deleted file mode 100644 index 51d79d42d7..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/image3.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/images/image4.png b/documentation/dev-portal/src/nymvpn/images/image4.png deleted file mode 100644 index 52f4d7dd20..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/image4.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/images/image5.png b/documentation/dev-portal/src/nymvpn/images/image5.png deleted file mode 100644 index 40b9c3aab8..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/image5.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/images/json.png b/documentation/dev-portal/src/nymvpn/images/json.png deleted file mode 100644 index a64c288169..0000000000 Binary files a/documentation/dev-portal/src/nymvpn/images/json.png and /dev/null differ diff --git a/documentation/dev-portal/src/nymvpn/intro.md b/documentation/dev-portal/src/nymvpn/intro.md deleted file mode 100644 index 738d9e801b..0000000000 --- a/documentation/dev-portal/src/nymvpn/intro.md +++ /dev/null @@ -1,29 +0,0 @@ -# NymVPN beta - -[**NymVPN**](https://nymvpn.com/en) is a client that uses [Nym Mixnet](https://nymtech.net) to anonymise all of a user's internet traffic through either a 5-hop mixnet for a *full network privacy* or the *faster* 2-hop decentralised VPN (with some extra features). - - -**You are invited to take part in the beta testing** of this new application. Register for private testing round at [nymvpn.com](https://nymvpn.com/en), that will grant you access to the [download page](https://nymvpn.com/download). Visit [NymVPN Support & FAQ](https://nymvpn.com/en/support) or join the [NymVPN matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat) if you have any questions, comments or blockers. - -Checkout the [release page](https://github.com/nymtech/nym-vpn-client/releases) for available binaries. - -*NOTE: NymVPN beta is experimental software for testing purposes only.* - - -## NymVPN Overview - -To understand what's under the hood of NymVPN and the mixnet, we recommend interested developers to begin with [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) pages. - -The default setup of NymVPN is to run in 5-hop mode (mixnet): - -``` - ┌─►mix──┐ mix mix - │ │ - Entry │ │ Exit -client ───► Gateway ──┘ mix │ mix ┌─►mix ───► Gateway ───► internet - │ │ - │ │ - mix └─►mix──┘ mix -``` - -Users can switch to 2-hop only mode, which is a faster but less private option. In this mode traffic is only sent between the two gateways, and is not passed through the mixnet. The client than use two wireguard tunnels with the Entry and Exit Gateway nodes, the Exit Gateway one being tunnelled itself through the Entry Gateway tunnel. NymVPN uses Mullvad libraries for wrapping `wireguard-go` and to setup local routing rules to route all traffic to the TUN virtual network device. diff --git a/documentation/dev-portal/src/nymvpn/troubleshooting.md b/documentation/dev-portal/src/nymvpn/troubleshooting.md deleted file mode 100644 index 1ae4046cdb..0000000000 --- a/documentation/dev-portal/src/nymvpn/troubleshooting.md +++ /dev/null @@ -1,97 +0,0 @@ -# Troubleshooting - -Below are listed some points which may need to be addressed when testing NymVPN alpha. If you crashed into any errors which are not listed, please contact us at the testing workshop or in the NymVPN [Matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat). - -#### NymVPN attempts to connect to sandbox testnet - -If you testing the latest versions and you correctly expect the client to run over the mainnet, but it listens to `https://sandbox-nym-api1.nymtech.net`, it's probably because of your previous configuration. - -Check your `config.toml` either in the directory from which you run your client or in `~/.config/nym-vpn/` and remove `sandbox.env` from the config file and folder. - -If the problem persists (probably due to some locally cache) download [`mainnet.env`](https://github.com/nymtech/nym/blob/master/envs/mainnet.env) and save it to the same directory. - -#### Running GUI failed due to `TOML parse error` - -If you see this error when running NymVPN alpha desktop, it's because the older versions needed entry location in `config.toml` configuration file. From `v0.0.3` the entry location is selected directly by the user in the application. This error is due to an old `app-data.toml` config in your computer. - -```sh -2024-02-15T14:25:02.745331Z ERROR read: nym_vpn_desktop::fs::storage: TOML parse error at line 5, column 1 - | -5 | [entry_node_location] - | ^^^^^^^^^^^^^^^^^^^^^ -wanted exactly 1 element, more than 1 element - self=AppStorage { data: AppData { monitoring: None, autoconnect: None, killswitch: None, entry_location_selector: None, ui_theme: None, ui_root_font_size: None, vpn_mode: None, entry_node_location: None, exit_node_location: None }, dir_path: "/home/companero/.local/share/nym-vpn", filename: "app-data.toml", full_path: "/home/companero/.local/share/nym-vpn/app-data.toml" } -Error: TOML parse error at line 5, column 1 - | -5 | [entry_node_location] - | ^^^^^^^^^^^^^^^^^^^^^ -wanted exactly 1 element, more than 1 element -``` - -Simply delete this file `app-data.toml` from the path listed in the error message. In the example above it would be `/home/companero/.local/share/nym-vpn/app-data.toml`. - -The application will create a new one on startup. - -#### Thread `main` panicked - -If you see a message like: -```sh -thread 'main' panicked at /Users/runner/.cargo/git/checkouts/mullvadvpn-app-a575cf705b5dfd76/ccfbaa2/talpid-routing/src/unix.rs:301:30: -``` -Restart your wifi connection and start again. - -#### MacOS alert on NymVPN UI startup - -If you are running NymVPN on mac OS for the first time, you may see this alert message: - -![](images/image3.png) - -1. Head to System Settings -> Privacy & Security and click `Allow anyway` - -![](images/image5.png) - -2. Confirm with your password or TouchID - -3. Possibly you may have to confirm again upon running the application - - diff --git a/documentation/dev-portal/src/sdk/rust/examples/cargo.md b/documentation/dev-portal/src/sdk/rust/examples/cargo.md deleted file mode 100644 index e425e124ed..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/cargo.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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. - -```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", 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", branch = "master" } - -# 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/dev-portal/src/sdk/rust/examples/credential.md b/documentation/dev-portal/src/sdk/rust/examples/credential.md deleted file mode 100644 index f29d6748ba..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/credential.md +++ /dev/null @@ -1,8 +0,0 @@ -# Coconut credential generation -The following code shows how you can use the SDK to create and use a credential 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](https://nymtech.net/docs/coconut.html). diff --git a/documentation/dev-portal/src/sdk/rust/examples/custom-network.md b/documentation/dev-portal/src/sdk/rust/examples/custom-network.md deleted file mode 100644 index ae0f145a3b..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/custom-network.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/keys.md b/documentation/dev-portal/src/sdk/rust/examples/keys.md deleted file mode 100644 index 84746dcfd6..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/keys.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/simple.md b/documentation/dev-portal/src/sdk/rust/examples/simple.md deleted file mode 100644 index 20872ce96b..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/simple.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/socks.md b/documentation/dev-portal/src/sdk/rust/examples/socks.md deleted file mode 100644 index de027e9011..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/socks.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/split-send.md b/documentation/dev-portal/src/sdk/rust/examples/split-send.md deleted file mode 100644 index 6b7cf69789..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/split-send.md +++ /dev/null @@ -1,6 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/storage.md b/documentation/dev-portal/src/sdk/rust/examples/storage.md deleted file mode 100644 index bc68bca9ff..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/storage.md +++ /dev/null @@ -1,6 +0,0 @@ -# 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/dev-portal/src/sdk/rust/examples/surbs.md b/documentation/dev-portal/src/sdk/rust/examples/surbs.md deleted file mode 100644 index d3b6b2da1b..0000000000 --- a/documentation/dev-portal/src/sdk/rust/examples/surbs.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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. - -You can read more about how SURBs function under the hood [here](https://nymtech.net/docs/architecture/traffic-flow.html#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/dev-portal/src/sdk/rust/message-types.md b/documentation/dev-portal/src/sdk/rust/message-types.md deleted file mode 100644 index c5adf83377..0000000000 --- a/documentation/dev-portal/src/sdk/rust/message-types.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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/dev-portal/src/sdk/rust/rust.md b/documentation/dev-portal/src/sdk/rust/rust.md deleted file mode 100644 index 3062e1ff32..0000000000 --- a/documentation/dev-portal/src/sdk/rust/rust.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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. - -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 | -|-----------|---------------------------------------------------------------------------------------|----------| -| 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. - -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: - -```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/dev-portal/src/sdk/typescript.md b/documentation/dev-portal/src/sdk/typescript.md deleted file mode 100644 index ee67c3939a..0000000000 --- a/documentation/dev-portal/src/sdk/typescript.md +++ /dev/null @@ -1,4 +0,0 @@ -# Typescript SDK -The Typescript SDK allows developers to start building browser-based mixnet applications quickly, by simply importing the SDK into their code via NPM as they would any other Typescript library. - -If you'd like to learn more, build apps or integrate Nym components using the TS SDK, visit the dedicated [TS SDK Handbook](https://sdk.nymtech.net/). diff --git a/documentation/dev-portal/src/shipyard/challenges-overview.md b/documentation/dev-portal/src/shipyard/challenges-overview.md deleted file mode 100644 index 4e02f5a797..0000000000 --- a/documentation/dev-portal/src/shipyard/challenges-overview.md +++ /dev/null @@ -1,53 +0,0 @@ -# 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. - -## 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 deleted file mode 100644 index f07f3f22ac..0000000000 --- a/documentation/dev-portal/src/shipyard/general.md +++ /dev/null @@ -1,16 +0,0 @@ -# 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 deleted file mode 100644 index 1f4a901f7a..0000000000 --- a/documentation/dev-portal/src/shipyard/guidelines.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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. - -## How to submit? -Please follow the instructions [here](https://github.com/nymtech/nym/discussions/4143). \ No newline at end of file diff --git a/documentation/dev-portal/src/shipyard/infra.md b/documentation/dev-portal/src/shipyard/infra.md deleted file mode 100644 index 73c3afadb3..0000000000 --- a/documentation/dev-portal/src/shipyard/infra.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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. - -## Node Details: -- NR1 - - Location: Singapore - - Nym Address: `FDeWfd8q686PWLXJDCqNJTCbydTk1KSux5HVftimsPyx.9XyThN4yh92eTMuLp1NvWicRZob8Ei5xpba9dvcMLxcN@9Byd9VAtyYMnbVAcqdoQxJnq76XEg2dbxbiF5Aa5Jj9J` -- NR2 - - Location: Frankfurt - - Nym Address: `BNypKaGiGY8GNRN4gpV95GcaVS8n7CrHuoZNgQ2ezqv2.ACpaixzuaSzuMajVQj6aR7cbpbvp676tm21MiLbX1gni@678qVUJ21uwxZBhp3r56z7GRf6gMh3NYDHruTegPtgMf` \ No newline at end of file diff --git a/documentation/dev-portal/src/tutorials/coming-soon.md b/documentation/dev-portal/src/tutorials/coming-soon.md deleted file mode 100644 index a435e701ef..0000000000 --- a/documentation/dev-portal/src/tutorials/coming-soon.md +++ /dev/null @@ -1,11 +0,0 @@ -# Stub: Updates Coming Soon! - -There is a lot of development work ongoing with our clients; as such the old tutorials that were here got quite out of date. - -However, you can still access the old [tutorial codebases](https://github.com/nymtech/developer-tutorials) as well as the markdown files in the `tutorial-archives/` directory in the [developer portal docs repo](https://github.com/nymtech/nym/tree/develop/documentation/dev-portal/src/tutorials) if you want. - -More up to date tutorials will be coming soon for using RPC and gRPC, `mixfetch`, as well as using the [FFI libraries](https://github.com/nymtech/nym/tree/develop/sdk/ffi) for interacting with the Mixnet via C++ and Go. - -> Developers who are searching for example code can use the following list as the current 'best practices': -> * Generic traffic transport: the [`zcash-rpc-demo`](https://github.com/nymtech/nym-zcash-rpc-demo) repo, although here used to only pipe RPC traffic, is a proof of concept 'generic' mixnet piping example which exposes a TPC Socket on the client side for incoming traffic, pipes this through the mixnet, and then streams TCP packets 'out' the other side. -> * In-browser usage: see the [browser examples](../examples/browser-only.md) page for examples using `mixFetch`. diff --git a/documentation/dev-portal/src/tutorials/telegram.md b/documentation/dev-portal/src/tutorials/telegram.md deleted file mode 100644 index 7d1b447ffc..0000000000 --- a/documentation/dev-portal/src/tutorials/telegram.md +++ /dev/null @@ -1,43 +0,0 @@ -# Telegram NymConnect Integration - -*This is a shortened version of a [Nym Community post](https://blog.nymtech.net/how-to-use-telegram-in-iraq-with-nymconnect-106a3b8dd050) written by Saliveja.* - -![](../images/telegram.png) - -The purpose of the following manual is not to promote Telegram but so people can use it with the Nym mixnet if they wish to, should a situation ask for that. This privacy-enhances Telegram at the network level and allows users to access the application from locations like where the application was banned. - -See also: [Element (Matrix) over the Nym mixnet](./matrix.md): private, decentralised and secure messaging. - -## Setup & Run - -Here’s how to configure Telegram with NymConnect: - -1. **Download and install NymConnect(https://nymtech.net/download-nymconnect/).** - For more releases, check out [Github](https://github.com/nymtech/nym/tags). NymConnect is available for Linux, Windows, and MacOS. - On Linux make sure NymConnect is executable. Opening a terminal in the same directory and run: - ```sh - chmod +x ./ - ``` -2. **Start NymConnect** - Telegram is added to NymConnect by default. -3. **Click connect - the host and port will now be displayed.** -4. **Click on host or port to copy** the value to the clipboard. -5. **Open the Telegram proxy settings.** - Linux: Telegram -> Settings -> Advanced -> Connection type -> Use custom proxy - MacOS: Telegram -> Settings -> Advanced -> Data & Storage -> Connection Type -> Use custom Proxy - Windows: Telegram -> Settings -> Data and Storage -> Use proxy -6. **Add a proxy** with the Add proxy button. -7. **Select SOCKS5** and make sure the port details are the same as those generated by NymConnect. Alternatively, follow this link: https://t.me/socks?server=127.0.0.1&port=1080 -8. **Save the proxy settings** in Telegram. -9. **Telegram is now running through the Nym Mixnet and is privacy-enhanced!** - This allows you to connect from regions which blocked Telegram. -10. Note if you remain idle on Telegram for a while you might lose connectivity and your messages might not get through via SOCKS5 proxy. If that happens reconnect your NymConnect and reset the proxy again. - - -Follow this [video](https://youtu.be/quj8H2qeOwY?t=97) to see the steps on Telegram setup. - - -**Now your Telegram runs over NymConnect.** - -NymConnect is currently available for several applications and service providers. Support for more apps is on the way. For any bug reports or feedback please reach out to us on Telegram or our [Discord](https://nymtech.net/go/discord) server. - diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client-src.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client-src.md deleted file mode 100644 index 85e1d368fb..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client-src.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Client pt2 diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client.md deleted file mode 100644 index c6db01fb6a..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/client.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Client diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/intro.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/intro.md deleted file mode 100644 index 627054da8d..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/intro.md +++ /dev/null @@ -1 +0,0 @@ -# Blockchain Service pt1 diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/lib.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/lib.md deleted file mode 100644 index 4be852e7ae..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/lib.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Lib diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/overview.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/overview.md deleted file mode 100644 index e7bbb2f8f1..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/overview.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorial Overview diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/preparing-env.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/preparing-env.md deleted file mode 100644 index ea95eb3fa8..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/preparing-env.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Environment diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/querying.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/querying.md deleted file mode 100644 index 6830e38016..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/querying.md +++ /dev/null @@ -1 +0,0 @@ -# Querying the Chain diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service-src.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service-src.md deleted file mode 100644 index cc140cc11f..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service-src.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Service pt2 diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service.md b/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service.md deleted file mode 100644 index 1090443702..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/cosmos-service/service.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Service diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/rust-sdk.md b/documentation/dev-portal/src/tutorials/tutorial-archives/rust-sdk.md deleted file mode 100644 index 5aef071e46..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/rust-sdk.md +++ /dev/null @@ -1 +0,0 @@ -# Rust SDK diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/overview.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/overview.md deleted file mode 100644 index e7bbb2f8f1..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/overview.md +++ /dev/null @@ -1 +0,0 @@ -# Tutorial Overview diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env.md deleted file mode 100644 index df2ffc650c..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your User Client Environment diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env2.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env2.md deleted file mode 100644 index 5d9a9d20c7..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/preparating-env2.md +++ /dev/null @@ -1 +0,0 @@ -# Preparing Your Service Provider Environment diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/sending-message.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/sending-message.md deleted file mode 100644 index 05f320eeae..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/sending-message.md +++ /dev/null @@ -1 +0,0 @@ -# Sending a Message Through the Mixnet diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/service-provider.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/service-provider.md deleted file mode 100644 index e69d01ee83..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/service-provider.md +++ /dev/null @@ -1 +0,0 @@ -# Building Your Service Provider diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/simple-service-provider.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/simple-service-provider.md deleted file mode 100644 index 246eebb2f9..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/simple-service-provider.md +++ /dev/null @@ -1 +0,0 @@ -# Simple Service Provider diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/user-client.md b/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/user-client.md deleted file mode 100644 index d8c44a4841..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/simple-service-provider/user-client.md +++ /dev/null @@ -1 +0,0 @@ -# Building Your User Client diff --git a/documentation/dev-portal/src/tutorials/tutorial-archives/typescript.md b/documentation/dev-portal/src/tutorials/tutorial-archives/typescript.md deleted file mode 100644 index 42c9775801..0000000000 --- a/documentation/dev-portal/src/tutorials/tutorial-archives/typescript.md +++ /dev/null @@ -1 +0,0 @@ -# Typescript diff --git a/documentation/dev-portal/themes/css/chrome.css b/documentation/dev-portal/themes/css/chrome.css deleted file mode 100644 index e16262342c..0000000000 --- a/documentation/dev-portal/themes/css/chrome.css +++ /dev/null @@ -1,608 +0,0 @@ -/* CSS for UI elements (a.k.a. chrome) */ - -@import 'variables.css'; - -html { - scrollbar-color: var(--scrollbar) var(--bg); -} -#searchresults a, -.content a:link, -a:visited, -a > .hljs { - color: var(--links); -} - -/* - body-container is necessary because mobile browsers don't seem to like - overflow-x on the body tag when there is a tag. -*/ -#body-container { - /* - This is used when the sidebar pushes the body content off the side of - the screen on small screens. Without it, dragging on mobile Safari - will want to reposition the viewport in a weird way. - */ - overflow-x: clip; -} - -/* Menu Bar */ - -#menu-bar, -#menu-bar-hover-placeholder { - z-index: 101; - margin: auto calc(0px - var(--page-padding)); -} -#menu-bar { - position: relative; - display: flex; - flex-wrap: wrap; - background-color: var(--bg); - border-block-end-color: var(--bg); - border-block-end-width: 1px; - border-block-end-style: solid; -} -#menu-bar.sticky, -.js #menu-bar-hover-placeholder:hover + #menu-bar, -.js #menu-bar:hover, -.js.sidebar-visible #menu-bar { - position: -webkit-sticky; - position: sticky; - top: 0 !important; -} -#menu-bar-hover-placeholder { - position: sticky; - position: -webkit-sticky; - top: 0; - height: var(--menu-bar-height); -} -#menu-bar.bordered { - border-block-end-color: var(--table-border-color); -} -#menu-bar i, #menu-bar .icon-button { - position: relative; - padding: 0 8px; - z-index: 10; - line-height: var(--menu-bar-height); - cursor: pointer; - transition: color 0.5s; -} -@media only screen and (max-width: 420px) { - #menu-bar i, #menu-bar .icon-button { - padding: 0 5px; - } -} - -.icon-button { - border: none; - background: none; - padding: 0; - color: inherit; -} -.icon-button i { - margin: 0; -} - -.right-buttons { - margin: 0 15px; -} -.right-buttons a { - text-decoration: none; -} - -.left-buttons { - display: flex; - margin: 0 5px; -} -.no-js .left-buttons button { - display: none; -} - -.menu-title { - position: absolute; - left: 50%; - display: inline-block; - font-weight: 200; - font-size: 2.4rem; - line-height: var(--menu-bar-height); - text-align: center; - margin: 0; - flex: 1; - white-space: nowrap; - overflow: hidden; - text-overflow: ellipsis; -} -.js .menu-title { - cursor: pointer; -} - -.menu-bar, -.menu-bar:visited, -.nav-chapters, -.nav-chapters:visited, -.mobile-nav-chapters, -.mobile-nav-chapters:visited, -.menu-bar .icon-button, -.menu-bar a i { - color: var(--icons); -} - -.menu-bar i:hover, -.menu-bar .icon-button:hover, -.nav-chapters:hover, -.mobile-nav-chapters i:hover { - color: var(--icons-hover); -} - -/* Nav Icons */ - -.nav-chapters { - font-size: 2.5em; - text-align: center; - text-decoration: none; - - position: fixed; - top: 0; - bottom: 0; - margin: 0; - max-width: auto; - min-width: auto; - - display: flex; - justify-content: center; - align-content: center; - flex-direction: column; - - transition: color 0.5s, background-color 0.5s; -} - -.nav-chapters:hover { - text-decoration: none; - background-color: var(--theme-hover); - transition: background-color 0.15s, color 0.15s; -} - -.nav-wrapper { - margin-block-start: 50px; - display: none; -} - -.mobile-nav-chapters { - font-size: 2.5em; - text-align: center; - text-decoration: none; - width: 90px; - border-radius: 5px; - background-color: var(--sidebar-bg); -} - -/* Only Firefox supports flow-relative values */ -.previous { float: left; } -[dir=rtl] .previous { float: right; } - -/* Only Firefox supports flow-relative values */ -.next { - float: right; - right: var(--page-padding); -} -[dir=rtl] .next { - float: left; - right: unset; - left: var(--page-padding); -} - -/* Use the correct buttons for RTL layouts*/ -[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";} -[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; } - -@media only screen and (max-width: 1080px) { - .nav-wide-wrapper { display: none; } - .nav-wrapper { display: block; } -} - -/* sidebar-visible */ -@media only screen and (max-width: 1380px) { - #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; } - #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; } -} - -/* Inline code */ - -:not(pre) > .hljs { - display: inline; - padding: 0.1em 0.3em; - border-radius: 3px; -} - -:not(pre):not(a) > .hljs { - color: var(--inline-code-color); - overflow-x: initial; -} - -a:hover > .hljs { - text-decoration: underline; -} - -pre { - position: relative; -} -pre > .buttons { - position: absolute; - z-index: 100; - right: 0px; - top: 2px; - margin: 0px; - padding: 2px 0px; - - color: var(--sidebar-fg); - cursor: pointer; - visibility: hidden; - opacity: 0; - transition: visibility 0.1s linear, opacity 0.1s linear; -} -pre:hover > .buttons { - visibility: visible; - opacity: 1 -} -pre > .buttons :hover { - color: var(--sidebar-active); - border-color: var(--icons-hover); - background-color: var(--theme-hover); -} -pre > .buttons i { - margin-inline-start: 8px; -} -pre > .buttons button { - cursor: inherit; - margin: 0px 5px; - padding: 3px 5px; - font-size: 14px; - - border-style: solid; - border-width: 1px; - border-radius: 4px; - border-color: var(--icons); - background-color: var(--theme-popup-bg); - transition: 100ms; - transition-property: color,border-color,background-color; - color: var(--icons); -} -@media (pointer: coarse) { - pre > .buttons button { - /* On mobile, make it easier to tap buttons. */ - padding: 0.3rem 1rem; - } - - .sidebar-resize-indicator { - /* Hide resize indicator on devices with limited accuracy */ - display: none; - } -} -pre > code { - display: block; - padding: 1rem; -} - -/* FIXME: ACE editors overlap their buttons because ACE does absolute - positioning within the code block which breaks padding. The only solution I - can think of is to move the padding to the outer pre tag (or insert a div - wrapper), but that would require fixing a whole bunch of CSS rules. -*/ -.hljs.ace_editor { - padding: 0rem 0rem; -} - -pre > .result { - margin-block-start: 10px; -} - -/* Search */ - -#searchresults a { - text-decoration: none; -} - -mark { - border-radius: 2px; - padding-block-start: 0; - padding-block-end: 1px; - padding-inline-start: 3px; - padding-inline-end: 3px; - margin-block-start: 0; - margin-block-end: -1px; - margin-inline-start: -3px; - margin-inline-end: -3px; - background-color: var(--search-mark-bg); - transition: background-color 300ms linear; - cursor: pointer; -} - -mark.fade-out { - background-color: rgba(0,0,0,0) !important; - cursor: auto; -} - -.searchbar-outer { - margin-inline-start: auto; - margin-inline-end: auto; - max-width: var(--content-max-width); -} - -#searchbar { - width: 100%; - margin-block-start: 5px; - margin-block-end: 0; - margin-inline-start: auto; - margin-inline-end: auto; - padding: 10px 16px; - transition: box-shadow 300ms ease-in-out; - border: 1px solid var(--searchbar-border-color); - border-radius: 3px; - background-color: var(--searchbar-bg); - color: var(--searchbar-fg); -} -#searchbar:focus, -#searchbar.active { - box-shadow: 0 0 3px var(--searchbar-shadow-color); -} - -.searchresults-header { - font-weight: bold; - font-size: 1em; - padding-block-start: 18px; - padding-block-end: 0; - padding-inline-start: 5px; - padding-inline-end: 0; - color: var(--searchresults-header-fg); -} - -.searchresults-outer { - margin-inline-start: auto; - margin-inline-end: auto; - max-width: var(--content-max-width); - border-block-end: 1px dashed var(--searchresults-border-color); -} - -ul#searchresults { - list-style: none; - padding-inline-start: 20px; -} -ul#searchresults li { - margin: 10px 0px; - padding: 2px; - border-radius: 2px; -} -ul#searchresults li.focus { - background-color: var(--searchresults-li-bg); -} -ul#searchresults span.teaser { - display: block; - clear: both; - margin-block-start: 5px; - margin-block-end: 0; - margin-inline-start: 20px; - margin-inline-end: 0; - font-size: 0.8em; -} -ul#searchresults span.teaser em { - font-weight: bold; - font-style: normal; -} - -/* Sidebar */ - -.sidebar { - position: fixed; - left: 0; - top: 0; - bottom: 0; - width: var(--sidebar-width); - font-size: 1em; - box-sizing: border-box; - -webkit-overflow-scrolling: touch; - overscroll-behavior-y: contain; - background-color: var(--sidebar-bg); - color: var(--sidebar-fg); -} -[dir=rtl] .sidebar { left: unset; right: 0; } -.sidebar-resizing { - -moz-user-select: none; - -webkit-user-select: none; - -ms-user-select: none; - user-select: none; -} -.no-js .sidebar, -.js:not(.sidebar-resizing) .sidebar { - transition: transform 0.3s; /* Animation: slide away */ -} -.sidebar code { - line-height: 2em; -} -.sidebar .sidebar-scrollbox { - overflow-y: auto; - position: absolute; - top: 0; - bottom: 0; - left: 0; - right: 0; - padding: 10px 10px; -} -.sidebar .sidebar-resize-handle { - position: absolute; - cursor: col-resize; - width: 0; - right: calc(var(--sidebar-resize-indicator-width) * -1); - top: 0; - bottom: 0; - display: flex; - align-items: center; -} - -.sidebar-resize-handle .sidebar-resize-indicator { - width: 100%; - height: 12px; - background-color: var(--icons); - margin-inline-start: var(--sidebar-resize-indicator-space); -} - -[dir=rtl] .sidebar .sidebar-resize-handle { - left: calc(var(--sidebar-resize-indicator-width) * -1); - right: unset; -} -.js .sidebar .sidebar-resize-handle { - cursor: col-resize; - width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space)); -} -/* sidebar-hidden */ -#sidebar-toggle-anchor:not(:checked) ~ .sidebar { - transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))); - z-index: -1; -} -[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar { - transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))); -} -.sidebar::-webkit-scrollbar { - background: var(--sidebar-bg); -} -.sidebar::-webkit-scrollbar-thumb { - background: var(--scrollbar); -} - -/* sidebar-visible */ -#sidebar-toggle-anchor:checked ~ .page-wrapper { - transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))); -} -[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper { - transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))); -} -@media only screen and (min-width: 620px) { - #sidebar-toggle-anchor:checked ~ .page-wrapper { - transform: none; - margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)); - } - [dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper { - transform: none; - } -} - -.chapter { - list-style: none outside none; - padding-inline-start: 0; - line-height: 2em; -} - -.chapter ol { - width: 100%; -} - -.chapter li { - display: flex; - color: var(--sidebar-non-existant); -} -.chapter li a { - display: block; - padding: 0; - text-decoration: none; - color: var(--sidebar-fg); -} - -.chapter li a:hover { - color: var(--sidebar-active); -} - -.chapter li a.active { - color: var(--sidebar-active); -} - -.chapter li > a.toggle { - cursor: pointer; - display: block; - margin-inline-start: auto; - padding: 0 10px; - user-select: none; - opacity: 0.68; -} - -.chapter li > a.toggle div { - transition: transform 0.5s; -} - -/* collapse the section */ -.chapter li:not(.expanded) + li > ol { - display: none; -} - -.chapter li.chapter-item { - line-height: 1.5em; - margin-block-start: 0.6em; -} - -.chapter li.expanded > a.toggle div { - transform: rotate(90deg); -} - -.spacer { - width: 100%; - height: 3px; - margin: 5px 0px; -} -.chapter .spacer { - background-color: var(--sidebar-spacer); -} - -@media (-moz-touch-enabled: 1), (pointer: coarse) { - .chapter li a { padding: 5px 0; } - .spacer { margin: 10px 0; } -} - -.section { - list-style: none outside none; - padding-inline-start: 20px; - line-height: 1.5em; -} - -/* Theme Menu Popup */ - -.theme-popup { - position: absolute; - left: 10px; - top: var(--menu-bar-height); - z-index: 1000; - border-radius: 4px; - font-size: 0.7em; - color: var(--fg); - background: var(--theme-popup-bg); - border: 1px solid var(--theme-popup-border); - margin: 0; - padding: 0; - list-style: none; - display: none; - /* Don't let the children's background extend past the rounded corners. */ - overflow: hidden; -} -[dir=rtl] .theme-popup { left: unset; right: 10px; } -.theme-popup .default { - color: var(--icons); -} -.theme-popup .theme { - width: 100%; - border: 0; - margin: 0; - padding: 2px 20px; - line-height: 25px; - white-space: nowrap; - text-align: start; - cursor: pointer; - color: inherit; - background: inherit; - font-size: inherit; -} -.theme-popup .theme:hover { - background-color: var(--theme-hover); -} - -.theme-selected::before { - display: inline-block; - content: "✓"; - margin-inline-start: -14px; - width: 14px; -} diff --git a/documentation/dev-portal/themes/css/general.css b/documentation/dev-portal/themes/css/general.css deleted file mode 100644 index df8c1d12d2..0000000000 --- a/documentation/dev-portal/themes/css/general.css +++ /dev/null @@ -1,234 +0,0 @@ -/* Base styles and content styles */ - -@import 'variables.css'; - -:root { - /* Browser default font-size is 16px, this way 1 rem = 10px */ - font-size: 70%; - color-scheme: var(--color-scheme); -} - -html { - font-family: "Open Sans", sans-serif; - color: var(--fg); - background-color: var(--bg); - text-size-adjust: none; - -webkit-text-size-adjust: none; -} - -body { - margin: 0; - font-size: 1.5rem; - overflow-x: hidden; -} - -code { - font-family: var(--mono-font) !important; - font-size: 0.9em; - direction: ltr !important; -} - -/* make long words/inline code not x overflow */ -main { - overflow-wrap: break-word; -} - -/* make wide tables scroll if they overflow */ -.table-wrapper { - overflow-x: auto; -} - -/* Don't change font size in headers. */ -h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { - font-size: unset; -} - -.left { float: left; } -.right { float: right; } -.boring { opacity: 0.6; } -.hide-boring .boring { display: none; } -.hidden { display: none !important; } - -h2, h3 { margin-block-start: 2.5em; } -h4, h5 { margin-block-start: 2em; } - -.header + .header h3, -.header + .header h4, -.header + .header h5 { - margin-block-start: 1em; -} - -h1:target::before, -h2:target::before, -h3:target::before, -h4:target::before, -h5:target::before, -h6:target::before { - display: inline-block; - content: "»"; - margin-inline-start: -30px; - width: 30px; -} - -/* This is broken on Safari as of version 14, but is fixed - in Safari Technology Preview 117 which I think will be Safari 14.2. - https://bugs.webkit.org/show_bug.cgi?id=218076 -*/ -:target { - /* Safari does not support logical properties */ - scroll-margin-top: calc(var(--menu-bar-height) + 0.5em); -} - -.page { - outline: 0; - padding: 0 var(--page-padding); - margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */ -} -.page-wrapper { - box-sizing: border-box; - background-color: var(--bg); -} -.no-js .page-wrapper, -.js:not(.sidebar-resizing) .page-wrapper { - transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */ -} -[dir=rtl] .js:not(.sidebar-resizing) .page-wrapper { - transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */ -} - -.content { - overflow-y: auto; - padding: 0 10px; -} -.content main { - margin-inline-start: auto; - margin-inline-end: auto; - max-width: var(--content-max-width); -} -.content p { line-height: 1.45em; } -.content ol { line-height: 1.45em; } -.content ul { line-height: 1.45em; } -.content a { text-decoration: none; } -.content a:hover { text-decoration: underline; } -.content img, .content video { max-width: 100%; } -.content .header:link, -.content .header:visited { - color: var(--fg); -} -.content .header:link, -.content .header:visited:hover { - text-decoration: none; -} - -table { - margin: 0 auto; - border-collapse: collapse; -} -table td { - padding: 3px 20px; - border: 1px var(--table-border-color) solid; -} -table thead { - background: var(--table-header-bg); -} -table thead td { - font-weight: 700; - border: none; -} -table thead th { - padding: 3px 20px; -} -table thead tr { - border: 1px var(--table-header-bg) solid; -} -/* Alternate background colors for rows */ -table tbody tr:nth-child(2n) { - background: var(--table-alternate-bg); -} - - -blockquote { - margin: 20px 0; - padding: 0 20px; - color: var(--fg); - background-color: var(--quote-bg); - border-block-start: .1em solid var(--quote-border); - border-block-end: .1em solid var(--quote-border); -} - -.warning { - margin: 20px; - padding: 0 20px; - border-inline-start: 2px solid var(--warning-border); -} - -.warning:before { - position: absolute; - width: 3rem; - height: 3rem; - margin-inline-start: calc(-1.5rem - 21px); - content: "ⓘ"; - text-align: center; - background-color: var(--bg); - color: var(--warning-border); - font-weight: bold; - font-size: 2rem; -} - -blockquote .warning:before { - background-color: var(--quote-bg); -} - -kbd { - background-color: var(--table-border-color); - border-radius: 4px; - border: solid 1px var(--theme-popup-border); - box-shadow: inset 0 -1px 0 var(--theme-hover); - display: inline-block; - font-size: var(--code-font-size); - font-family: var(--mono-font); - line-height: 10px; - padding: 4px 5px; - vertical-align: middle; -} - -:not(.footnote-definition) + .footnote-definition, -.footnote-definition + :not(.footnote-definition) { - margin-block-start: 2em; -} -.footnote-definition { - font-size: 0.9em; - margin: 0.5em 0; -} -.footnote-definition p { - display: inline; -} - -.tooltiptext { - position: absolute; - visibility: hidden; - color: #fff; - background-color: #333; - transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */ - left: -8px; /* Half of the width of the icon */ - top: -35px; - font-size: 0.8em; - text-align: center; - border-radius: 6px; - padding: 5px 8px; - margin: 5px; - z-index: 1000; -} -.tooltipped .tooltiptext { - visibility: visible; -} - -.chapter li.part-title { - color: var(--sidebar-fg); - margin: 5px 0px; - font-weight: bold; -} - -.result-no-output { - font-style: italic; -} diff --git a/documentation/dev-portal/themes/css/variables.css b/documentation/dev-portal/themes/css/variables.css deleted file mode 100644 index 51b94cfc5a..0000000000 --- a/documentation/dev-portal/themes/css/variables.css +++ /dev/null @@ -1,287 +0,0 @@ - -/* Globals */ - -:root { - --sidebar-width: 280px; - --sidebar-resize-indicator-width: 8px; - --sidebar-resize-indicator-space: 2px; - --page-padding: 15px; - --content-max-width: 80%; - --menu-bar-height: 40px; - --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; - --code-font-size: 0.875em /* please adjust the ace font size accordingly in editor.js */ - --pagetoc-width: 13%; - --pagetoc-fontsize: 14.5px; -} - -@media only screen and (max-width:1439px) { - :root{ - --content-max-width: 98%; - } -} - -/* Themes */ - -.ayu { - --bg: hsl(210, 25%, 8%); - --fg: #c5c5c5; - - --sidebar-bg: #14191f; - --sidebar-fg: #c8c9db; - --sidebar-non-existant: #5c6773; - --sidebar-active: #ffb454; - --sidebar-spacer: #2d334f; - - --scrollbar: var(--sidebar-fg); - - --icons: #737480; - --icons-hover: #b7b9cc; - - --links: #0096cf; - - --inline-code-color: #ffb454; - - --theme-popup-bg: #14191f; - --theme-popup-border: #5c6773; - --theme-hover: #191f26; - - --quote-bg: hsl(226, 15%, 17%); - --quote-border: hsl(226, 15%, 22%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(210, 25%, 13%); - --table-header-bg: hsl(210, 25%, 28%); - --table-alternate-bg: hsl(210, 25%, 11%); - - --searchbar-border-color: #848484; - --searchbar-bg: #424242; - --searchbar-fg: #fff; - --searchbar-shadow-color: #d4c89f; - --searchresults-header-fg: #666; - --searchresults-border-color: #888; - --searchresults-li-bg: #252932; - --search-mark-bg: #e3b171; - - --color-scheme: dark; -} - -.coal { - --bg: hsl(200, 7%, 8%); - --fg: #98a3ad; - - --sidebar-bg: #292c2f; - --sidebar-fg: #a1adb8; - --sidebar-non-existant: #505254; - --sidebar-active: #3473ad; - --sidebar-spacer: #393939; - - --scrollbar: var(--sidebar-fg); - - --icons: #43484d; - --icons-hover: #b3c0cc; - - --links: #2b79a2; - - --inline-code-color: #c5c8c6; - - --theme-popup-bg: #141617; - --theme-popup-border: #43484d; - --theme-hover: #1f2124; - - --quote-bg: hsl(234, 21%, 18%); - --quote-border: hsl(234, 21%, 23%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(200, 7%, 13%); - --table-header-bg: hsl(200, 7%, 28%); - --table-alternate-bg: hsl(200, 7%, 11%); - - --searchbar-border-color: #aaa; - --searchbar-bg: #b7b7b7; - --searchbar-fg: #000; - --searchbar-shadow-color: #aaa; - --searchresults-header-fg: #666; - --searchresults-border-color: #98a3ad; - --searchresults-li-bg: #2b2b2f; - --search-mark-bg: #355c7d; - - --color-scheme: dark; -} - -.light { - --bg: hsl(0, 0%, 100%); - --fg: hsl(0, 0%, 0%); - - --sidebar-bg: #fafafa; - --sidebar-fg: hsl(0, 0%, 0%); - --sidebar-non-existant: #aaaaaa; - --sidebar-active: #1f1fff; - --sidebar-spacer: #f4f4f4; - - --scrollbar: #8F8F8F; - - --icons: #747474; - --icons-hover: #000000; - - --links: #1f1fff; - - --inline-code-color: #F42C4C; - - --theme-popup-bg: #fafafa; - --theme-popup-border: #cccccc; - --theme-hover: #e6e6e6; - - --quote-bg: hsl(197, 37%, 96%); - --quote-border: hsl(197, 37%, 91%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(0, 0%, 95%); - --table-header-bg: hsl(0, 0%, 80%); - --table-alternate-bg: hsl(0, 0%, 97%); - - --searchbar-border-color: #aaa; - --searchbar-bg: #fafafa; - --searchbar-fg: #000; - --searchbar-shadow-color: #aaa; - --searchresults-header-fg: #666; - --searchresults-border-color: #888; - --searchresults-li-bg: #e4f2fe; - --search-mark-bg: #a2cff5; - - --color-scheme: light; -} - -.navy { - --bg: hsl(226, 23%, 11%); - --fg: #bcbdd0; - - --sidebar-bg: #282d3f; - --sidebar-fg: #c8c9db; - --sidebar-non-existant: #505274; - --sidebar-active: #2b79a2; - --sidebar-spacer: #2d334f; - - --scrollbar: var(--sidebar-fg); - - --icons: #737480; - --icons-hover: #b7b9cc; - - --links: #2b79a2; - - --inline-code-color: #c5c8c6; - - --theme-popup-bg: #161923; - --theme-popup-border: #737480; - --theme-hover: #282e40; - - --quote-bg: hsl(226, 15%, 17%); - --quote-border: hsl(226, 15%, 22%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(226, 23%, 16%); - --table-header-bg: hsl(226, 23%, 31%); - --table-alternate-bg: hsl(226, 23%, 14%); - - --searchbar-border-color: #aaa; - --searchbar-bg: #aeaec6; - --searchbar-fg: #000; - --searchbar-shadow-color: #aaa; - --searchresults-header-fg: #5f5f71; - --searchresults-border-color: #5c5c68; - --searchresults-li-bg: #242430; - --search-mark-bg: #a2cff5; - - --color-scheme: dark; -} - -.rust { - --bg: hsl(60, 9%, 87%); - --fg: #262625; - - --sidebar-bg: #3b2e2a; - --sidebar-fg: #c8c9db; - --sidebar-non-existant: #505254; - --sidebar-active: #e69f67; - --sidebar-spacer: #45373a; - - --scrollbar: var(--sidebar-fg); - - --icons: #737480; - --icons-hover: #262625; - - --links: #2b79a2; - - --inline-code-color: #6e6b5e; - - --theme-popup-bg: #e1e1db; - --theme-popup-border: #b38f6b; - --theme-hover: #99908a; - - --quote-bg: hsl(60, 5%, 75%); - --quote-border: hsl(60, 5%, 70%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(60, 9%, 82%); - --table-header-bg: #b3a497; - --table-alternate-bg: hsl(60, 9%, 84%); - - --searchbar-border-color: #aaa; - --searchbar-bg: #fafafa; - --searchbar-fg: #000; - --searchbar-shadow-color: #aaa; - --searchresults-header-fg: #666; - --searchresults-border-color: #888; - --searchresults-li-bg: #dec2a2; - --search-mark-bg: #e69f67; - - --color-scheme: light; -} - -@media (prefers-color-scheme: dark) { - .light.no-js { - --bg: hsl(200, 7%, 8%); - --fg: #98a3ad; - - --sidebar-bg: #292c2f; - --sidebar-fg: #a1adb8; - --sidebar-non-existant: #505254; - --sidebar-active: #3473ad; - --sidebar-spacer: #393939; - - --scrollbar: var(--sidebar-fg); - - --icons: #43484d; - --icons-hover: #b3c0cc; - - --links: #2b79a2; - - --inline-code-color: #c5c8c6; - - --theme-popup-bg: #141617; - --theme-popup-border: #43484d; - --theme-hover: #1f2124; - - --quote-bg: hsl(234, 21%, 18%); - --quote-border: hsl(234, 21%, 23%); - - --warning-border: #ff8e00; - - --table-border-color: hsl(200, 7%, 13%); - --table-header-bg: hsl(200, 7%, 28%); - --table-alternate-bg: hsl(200, 7%, 11%); - - --searchbar-border-color: #aaa; - --searchbar-bg: #b7b7b7; - --searchbar-fg: #000; - --searchbar-shadow-color: #aaa; - --searchresults-header-fg: #666; - --searchresults-border-color: #98a3ad; - --searchresults-li-bg: #2b2b2f; - --search-mark-bg: #355c7d; - } -} diff --git a/documentation/dev-portal/themes/custom.css b/documentation/dev-portal/themes/custom.css deleted file mode 100644 index 6613d3e08b..0000000000 --- a/documentation/dev-portal/themes/custom.css +++ /dev/null @@ -1,57 +0,0 @@ -:root { - --mono-font: Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace; -} - -.coal { - --fg: #f2f2f2; - --sidebar-fg: #f2f2f2; - --sidebar-active: #fb6e4e; - --icons-hover: #fb6e4e; - --links: #fb6e4e; - - ::selection { - color: #121726; - background-color: #c5573d; - } - - select option { - background-color: #121726; - } -} - -.light { - --sidebar-active: #fb6e4e; - --icons-hover: #fb6e4e; - --links: #fb6e4e; - - ::selection { - color: #f2f2f2; - background-color: #c5573d; - } -} - -/*properly centering the title given the additional header items*/ -.menu-title { - left: 45%; -} - -.menu-bar .a:hover, - -/*necessary because of ^*/ -.right-buttons { - position: absolute; - right: 0; -} - -select { - font-size: 16px; -} - - - -footer { - font-size: 0.8em; - text-align: center; - border-top: 1px solid black; - padding: 5px 0; -} diff --git a/documentation/dev-portal/themes/index.hbs b/documentation/dev-portal/themes/index.hbs deleted file mode 100644 index d0bb54d0c3..0000000000 --- a/documentation/dev-portal/themes/index.hbs +++ /dev/null @@ -1,358 +0,0 @@ - - - - - - {{ title }} - {{#if is_print }} - - {{/if}} - {{#if base_url}} - - {{/if}} - - - - {{> head}} - - - - - - {{#if favicon_svg}} - - {{/if}} - {{#if favicon_png}} - - {{/if}} - - - - {{#if print_enable}} - - {{/if}} - - - - {{#if copy_fonts}} - - {{/if}} - - - - - - - - {{#each additional_css}} - - {{/each}} - - - - - - - -
- - - - - - - - - - - - - - - - - - - -
- -
- {{> header}} - - - - {{#if search_enabled}} - - {{/if}} - - - - -
-
-
-
- -
-
- - {{{ content }}} -
-
-
- - -
-
- - - -
- - {{#if live_reload_endpoint}} - - - {{/if}} - - {{#if playground_line_numbers}} - - {{/if}} - - {{#if playground_copyable}} - - {{/if}} - - {{#if playground_js}} - - - - - - {{/if}} - - {{#if search_js}} - - - - {{/if}} - - - - - - - {{#each additional_js}} - - {{/each}} - - {{#if is_print}} - {{#if mathjax_support}} - - {{else}} - - {{/if}} - {{/if}} - - -
- - diff --git a/documentation/dev-portal/themes/mdbook-admonish.css b/documentation/dev-portal/themes/mdbook-admonish.css deleted file mode 100644 index 45aeff0511..0000000000 --- a/documentation/dev-portal/themes/mdbook-admonish.css +++ /dev/null @@ -1,348 +0,0 @@ -@charset "UTF-8"; -:is(.admonition) { - display: flow-root; - margin: 1.5625em 0; - padding: 0 1.2rem; - color: var(--fg); - page-break-inside: avoid; - background-color: var(--bg); - border: 0 solid black; - border-inline-start-width: 0.4rem; - border-radius: 0.2rem; - box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05), 0 0 0.1rem rgba(0, 0, 0, 0.1); -} -@media print { - :is(.admonition) { - box-shadow: none; - } -} -:is(.admonition) > * { - box-sizing: border-box; -} -:is(.admonition) :is(.admonition) { - margin-top: 1em; - margin-bottom: 1em; -} -:is(.admonition) > .tabbed-set:only-child { - margin-top: 0; -} -html :is(.admonition) > :last-child { - margin-bottom: 1.2rem; -} - -a.admonition-anchor-link { - display: none; - position: absolute; - left: -1.2rem; - padding-right: 1rem; -} -a.admonition-anchor-link:link, a.admonition-anchor-link:visited { - color: var(--fg); -} -a.admonition-anchor-link:link:hover, a.admonition-anchor-link:visited:hover { - text-decoration: none; -} -a.admonition-anchor-link::before { - content: "§"; -} - -:is(.admonition-title, summary.admonition-title) { - position: relative; - min-height: 4rem; - margin-block: 0; - margin-inline: -1.6rem -1.2rem; - padding-block: 0.8rem; - padding-inline: 4.4rem 1.2rem; - font-weight: 700; - background-color: rgba(68, 138, 255, 0.1); - print-color-adjust: exact; - -webkit-print-color-adjust: exact; - display: flex; -} -:is(.admonition-title, summary.admonition-title) p { - margin: 0; -} -html :is(.admonition-title, summary.admonition-title):last-child { - margin-bottom: 0; -} -:is(.admonition-title, summary.admonition-title)::before { - position: absolute; - top: 0.625em; - inset-inline-start: 1.6rem; - width: 2rem; - height: 2rem; - background-color: #448aff; - print-color-adjust: exact; - -webkit-print-color-adjust: exact; - mask-image: url('data:image/svg+xml;charset=utf-8,'); - -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,'); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-size: contain; - content: ""; -} -:is(.admonition-title, summary.admonition-title):hover a.admonition-anchor-link { - display: initial; -} - -details.admonition > summary.admonition-title::after { - position: absolute; - top: 0.625em; - inset-inline-end: 1.6rem; - height: 2rem; - width: 2rem; - background-color: currentcolor; - mask-image: var(--md-details-icon); - -webkit-mask-image: var(--md-details-icon); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-size: contain; - content: ""; - transform: rotate(0deg); - transition: transform 0.25s; -} -details[open].admonition > summary.admonition-title::after { - transform: rotate(90deg); -} - -:root { - --md-details-icon: url("data:image/svg+xml;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,"); -} - -:is(.admonition):is(.admonish-note) { - border-color: #448aff; -} - -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(68, 138, 255, 0.1); -} -:is(.admonish-note) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #448aff; - mask-image: var(--md-admonition-icon--admonish-note); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #00b0ff; -} - -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 176, 255, 0.1); -} -:is(.admonish-abstract, .admonish-summary, .admonish-tldr) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00b0ff; - mask-image: var(--md-admonition-icon--admonish-abstract); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #00b8d4; -} - -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 184, 212, 0.1); -} -:is(.admonish-info, .admonish-todo) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00b8d4; - mask-image: var(--md-admonition-icon--admonish-info); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #00bfa5; -} - -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 191, 165, 0.1); -} -:is(.admonish-tip, .admonish-hint, .admonish-important) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00bfa5; - mask-image: var(--md-admonition-icon--admonish-tip); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #00c853; -} - -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(0, 200, 83, 0.1); -} -:is(.admonish-success, .admonish-check, .admonish-done) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #00c853; - mask-image: var(--md-admonition-icon--admonish-success); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #64dd17; -} - -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(100, 221, 23, 0.1); -} -:is(.admonish-question, .admonish-help, .admonish-faq) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #64dd17; - mask-image: var(--md-admonition-icon--admonish-question); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #ff9100; -} - -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 145, 0, 0.1); -} -:is(.admonish-warning, .admonish-caution, .admonish-attention) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff9100; - mask-image: var(--md-admonition-icon--admonish-warning); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #ff5252; -} - -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 82, 82, 0.1); -} -:is(.admonish-failure, .admonish-fail, .admonish-missing) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff5252; - mask-image: var(--md-admonition-icon--admonish-failure); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #ff1744; -} - -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(255, 23, 68, 0.1); -} -:is(.admonish-danger, .admonish-error) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #ff1744; - mask-image: var(--md-admonition-icon--admonish-danger); - -webkit-mask-image: var(--md-admonition-icon--admonish-danger); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-bug) { - border-color: #f50057; -} - -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(245, 0, 87, 0.1); -} -:is(.admonish-bug) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #f50057; - mask-image: var(--md-admonition-icon--admonish-bug); - -webkit-mask-image: var(--md-admonition-icon--admonish-bug); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -:is(.admonition):is(.admonish-example) { - border-color: #7c4dff; -} - -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(124, 77, 255, 0.1); -} -:is(.admonish-example) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #7c4dff; - mask-image: var(--md-admonition-icon--admonish-example); - -webkit-mask-image: var(--md-admonition-icon--admonish-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) { - border-color: #9e9e9e; -} - -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title) { - background-color: rgba(158, 158, 158, 0.1); -} -:is(.admonish-quote, .admonish-cite) > :is(.admonition-title, summary.admonition-title)::before { - background-color: #9e9e9e; - mask-image: var(--md-admonition-icon--admonish-quote); - -webkit-mask-image: var(--md-admonition-icon--admonish-quote); - mask-repeat: no-repeat; - -webkit-mask-repeat: no-repeat; - mask-size: contain; - -webkit-mask-repeat: no-repeat; -} - -.navy :is(.admonition) { - background-color: var(--sidebar-bg); -} - -.ayu :is(.admonition), -.coal :is(.admonition) { - background-color: var(--theme-hover); -} - -.rust :is(.admonition) { - background-color: var(--sidebar-bg); - color: var(--sidebar-fg); -} -.rust .admonition-anchor-link:link, .rust .admonition-anchor-link:visited { - color: var(--sidebar-fg); -} diff --git a/documentation/dev-portal/themes/pagetoc.css b/documentation/dev-portal/themes/pagetoc.css deleted file mode 100644 index a68e5b8e21..0000000000 --- a/documentation/dev-portal/themes/pagetoc.css +++ /dev/null @@ -1,47 +0,0 @@ -/* src: https://github.com/JorelAli/mdBook-pagetoc */ - -@media only screen and (max-width:1439px) { - .sidetoc { - display: none; - } -} - -@media only screen and (min-width:1440px) { - main { - position: relative; - } - .sidetoc { - margin-left: auto; - margin-right: auto; - /* left: calc(90% + (var(--content-min-width))/4 - 110px); */ - left: 101%; - position: absolute; - font-size: var(--pagetoc-fontsize); - } - .pagetoc { - position: fixed; - width: var(--pagetoc-width); - } - .pagetoc a { - border-left: 1px solid var(--sidebar-bg); - /* color: var(--fg); */ - /* color: var(--sidebar-fg); */ - color: var(--links); - display: block; - padding-bottom: 5px; - padding-top: 5px; - padding-left: 10px; - text-align: left; - text-decoration: none; - font-weight: normal; - background: var(--sidebar-bg); - } - .pagetoc a:hover, - .pagetoc a.active { - background: var(--sidebar-bg); - /* color: var(--sidebar-fg); */ - color: var(--sidebar-active); - font-weight: bold; - font-size: var(--pagetoc-fontsize); - } -} diff --git a/documentation/dev-portal/themes/pagetoc.js b/documentation/dev-portal/themes/pagetoc.js deleted file mode 100644 index b11052427e..0000000000 --- a/documentation/dev-portal/themes/pagetoc.js +++ /dev/null @@ -1,68 +0,0 @@ -// src: https://github.com/JorelAli/mdBook-pagetoc - -// Un-active everything when you click it -Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el, i) { - el.addEventHandler("click", function() { - Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el, i) { - el.classList.remove("active"); - }); - el.classList.add("active"); - }); -}); - -var updateFunction = function() { - - var id; - var elements = document.getElementsByClassName("header"); - Array.prototype.forEach.call(elements, function(el, i) { - if (window.pageYOffset >= el.offsetTop) { - id = el; - } - }); - - Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el, i) { - el.classList.remove("active"); - }); - - Array.prototype.forEach.call(document.getElementsByClassName("pagetoc")[0].children, function(el, i) { - if (id.href.localeCompare(el.href) == 0) { - el.classList.add("active"); - } - }); -}; - -// Populate sidebar on load -window.addEventListener('load', function() { - var pagetoc = document.getElementsByClassName("pagetoc")[0]; - var elements = document.getElementsByClassName("header"); - Array.prototype.forEach.call(elements, function(el, i) { - var link = document.createElement("a"); - - // Indent shows hierarchy - var indent = ""; - switch (el.parentElement.tagName) { - case "H2": - indent = "20px"; - break; - case "H3": - indent = "40px"; - break; - case "H4": - indent = "60px"; - break; - default: - break; - } - - link.appendChild(document.createTextNode(el.text)); - link.style.paddingLeft = indent; - link.href = el.href; - pagetoc.appendChild(link); - }); - updateFunction.call(); -}); - - - -// Handle active elements on scroll -window.addEventListener("scroll", updateFunction); diff --git a/documentation/docs/.gitignore b/documentation/docs/.gitignore index dbccb28516..46f9bd0984 100644 --- a/documentation/docs/.gitignore +++ b/documentation/docs/.gitignore @@ -1,14 +1,6 @@ -# mdbook files -book/ - -# Compiled assets -.sass-cache -_site - -# Developing -todo.md -.idea - -# OSX -.DS_Store +.next +node_modules +out +# the lock file will break Vercel because it may get committed from a machine with a different build architecture +package-lock.json diff --git a/documentation/docs/README.md b/documentation/docs/README.md index 472f219c97..82b2395837 100644 --- a/documentation/docs/README.md +++ b/documentation/docs/README.md @@ -1,42 +1,61 @@ -# Nym Documentation -Documentation for the Nym privacy platform built using the [mdBook](https://rust-lang.github.io/mdBook/) docs framework. +# Nym Docs v2 -Documentation can be viewed at https://nymtech.net/docs +This is v2 of the nym docs, condensed from various mdbooks projects that we had previously. -## Contributing -Contributions to our documentation are very welcome. Please work on your contribution in either a `feature/` or `chore/` branch from `master` and target your pull request at `master`. +These docs are hosted at [nymtech.net/docs](www.nymtech.net/docs). -Since these docs autogenerate command output and import docs from binaries in `target/release` on `build` make sure you're branching off of `master` when making your branch. +## Doc projects +`docs/pages/` contains several subdirs, each hosting a subsection of the docs: +* `network` contains key concepts, cryptosystems, architecture. +* `developers` contains key concepts for developers, required architecture, and Rust/Typescript SDK docs. +* `operators` contains node setup and maintenance guides. -Changes merged to `master` will be autodeployed to the production site. +## Local development +### Dependencies +Our `prebuild` script relies on the following: +- `python` +- `pip` +- [`pandas`](https://pandas.pydata.org/) +- [`tabulate`](https://pypi.org/project/tabulate/) +- `jq` -### Contributing a new translation -To contribute tranlsations in a new language, please get in touch via [Matrix](https://matrix.to/#/#general:nymtech.chat) or [Discord](https://nymtech.net/go/discord). +Otherwise make sure to have `node` installed. -### Variables -There are some variables that are shared across the entire docs site, such as the current latest software version. +### Serve Local (Hot Reload) +```sh +pnpm i +pnpm run dev +``` -Variables are denoted in the `.md` files wrapped in `{{}}` (e.g `{{wallet_release_version}}`), and are located in the `book.toml` file under the `[preprocessor.variables.variables]` heading. If you are changing something like the software release version, minimum code versions in prerequisites, etc, **check in here first!** +Open `http://localhost:3000`. -### Diagrams -Most diagrams are simply ascii. Copies are kept in `/diagrams/` for ease of reproducability. Created using [textik](https://textik.com/#). +## Build +```sh +pnpm run build +``` -### Importing files and auto-generated command output +## Contribution +* If you wish to add to the documentation please create a PR against this repo, with a `patch` against `develop`. -Example files are inserted as per normal with mdbook. +## Scripts +* `generate:commands`: generates command output files for clients and binaries. This script runs the `autodoc` rust binary, moves the files to their required places, and then if there is an update, commits them to git. We commit the files as our remote deployments pull from a git repo. **Only run this script on branches where you want to push e.g. the build info of a binary to production docs**; it will build the monorepo binaries and use their command output for the produced markdown files. +* `generate:tables`: generates various information tables containing some repo-wide variables and information about ISPs. -Some binary command outputs are generated using the [`cmdrun`](https://docs.rs/mdbook-cmdrun/latest/mdbook_cmdrun/) mdbook plugin. +### Autodoc +`autodoc` is a script that generates markdown files containing commands and their output (both command and `--help` output). For the moment the binaries and their commands are manually configured in the script. -## Building -When working locally, it is recommended that you use `mdbook serve` to have a local version of the docs served on `localhost:3000`, with hot reloading on any changes made to files in the `src/` directory. +> **Only run this script on branches where you want to push e.g. the build info of a binary to production docs**; it will build the monorepo binaries and use their command output for the produced markdown files. -You can find other commands in the [mdBook CLI tool docs](https://rust-lang.github.io/mdBook/cli/index.html). +## CI/CD +TODO -### I tried to edit files in `theme/` and they aren't taking effect / `mdbook serve` causes a looping reload on file changes after changing fields in `[preprocessor.theme]` config +## Licensing and copyright information +This is a monorepo and components that make up Nym as a system are licensed individually, so for accurate information, please check individual files. -Looping reload is a known issue with the `mdbook-theme` preprocessor used for the table of contents and layout of these docs. As outlined in the `mdbook-theme` [readme](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) one way to mitigate this is to set `turn-off = true` under `[preprocessor.theme]`. This means that `mdbook serve` or `mdbook watch` ignores changes to the `theme/` directory, which is the source of the looping reload. If you have changed or commented out this line, reintroduce it to remove the looping reload. If you are trying to edit the theme of the docs and want to apply the change, see [here](https://github.com/zjp-CN/mdbook-theme#avoid-repeating-call-on-this-tool-when-mdbook-watch) for more info on how to remove the block, change the theme, and reintroduce the block. +As a general approach, licensing is as follows this pattern: -### Checking the mdBook version -To check the version of mdBook installed on your system, you can use the `mdbook --version` command. This will print the version number of mdBook installed on your system in the terminal. +*

Nym Documentation by Nym Technologies is licensed under CC BY-NC-SA 4.0

-The latest release of the binary of the pre-compiled binaries can be found on [GitHub](https://github.com/rust-lang/mdBook/releases). +* Nym applications and binaries are [GPL-3.0-only](https://www.gnu.org/licenses/) + +* Used libraries and different components are [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) or [MIT](https://mit-license.org/) diff --git a/documentation/docs/book.toml b/documentation/docs/book.toml deleted file mode 100644 index 9fe3643036..0000000000 --- a/documentation/docs/book.toml +++ /dev/null @@ -1,117 +0,0 @@ -[book] -title = "Nym Docs" -authors = ["Max Hampshire, Serinko, Alexia Lorenza Martinel"] -description = "Nym technical documentation" -language = "en" -multilingual = false # for the moment - ideally work on chinese, brazillian portugese, spanish next -src = "src" - -[rust] -edition = "2018" - -################# -# PREPROCESSORS # -################# - -[preprocessor.theme] -pagetoc = true -sidebar-width = "280px" -content-max-width = "80%" -root-font-size = "70%" -# if you need to change anything in the index.hbs file you need to turn this to `false`, rebuild the book, -# probably remove the additional `comment` that gets appended to the header, and then change this back to `true`. -# this is because of a bug in the `mdbook-theme` plugin -turn-off = true - -[preprocessor.admonish] -command = "mdbook-admonish" -assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install` - -# https://gitlab.com/tglman/mdbook-variables/ -[preprocessor.variables.variables] -minimum_rust_version = "1.66" -wallet_release_version = "1.2.8" -# nym-vpn related variables -nym_vpn_latest_binary_url = "https://github.com/nymtech/nym/releases/tag/nym-vpn-alpha-0.0.3" -nym_vpn_form_url = "https://opnform.com/forms/nymvpn-user-research-at-37c3-yccqko-2" - -[preprocessor.last-changed] -command = "mdbook-last-changed" -renderer = ["html"] - -# used for grabbing output of binary commands for automation https://github.com/FauconFan/mdbook-cmdrun -[preprocessor.cmdrun] - -# more pre-processor plugins to look into from https://github.com/rust-lang/mdBook/wiki/Third-party-plugins & https://lib.rs/keywords/mdbook-preprocessor -# mdbook-i18n - -######### -# BUILD # -######### - -[build] -build-dir = "book" # the directory where the output is placed -create-missing = true # whether or not to create missing pages -use-default-preprocessors = true # use the default preprocessors -extra-watch-dirs = [] # directories to watch for triggering builds - -########## -# OUTPUT # -########## - -[output.html] -theme = "themes" -default-theme = "coal" -preferred-dark-theme = "coal" -curly-quotes = true -copy-fonts = true -no-section-label = false -additional-css = [ - "./themes/custom.css", - "./themes/mdbook-admonish.css", - "./themes/pagetoc.css", -] -additional-js = ["./themes/pagetoc.js"] -git-repository-url = "https://github.com/nymtech/nym/documentation/" -git-repository-icon = "fa-github" -input-404 = "not-found.md" - -[output.html.fold] -enable = true # whether or not to enable section folding -level = 0 # the depth to start folding - -# controlling rust sample code blocks -[output.html.playground] -editable = false # allows editing the source code -copyable = true # include the copy button for copying code snippets -copy-js = true # includes the JavaScript for the code editor -line-numbers = true # displays line numbers for editable code -runnable = true # displays a run button for rust code - -# options for the built in text search -[output.html.search] -enable = true # enables the search feature -limit-results = 30 # maximum number of search results -teaser-word-count = 30 # number of words used for a search result teaser -use-boolean-and = true # multiple search terms must all match -boost-title = 2 # ranking boost factor for matches in headers -boost-hierarchy = 1 # ranking boost factor for matches in page names -boost-paragraph = 1 # ranking boost factor for matches in text -expand = true # partial words will match longer terms -heading-split-level = 3 # link results to heading levels -copy-js = true # include Javascript code for search - -[output.linkcheck] -warning-policy = "warn" - -[output.html.redirect] -"/sdk/rust/examples/socks.html" = "https://nymtech.net/developers/sdk/rust/examples/socks.html" -"/clients/overview.html" = "https://nymtech.net/developers/clients-overview.html" -"/sdk/rust/rust.html" = "https://nymtech.net/developers/sdk/rust/rust.html" -"/clients/socks5-client.html" = "https://nymtech.net/developers/clients/socks5-client.html" -"/clients/webassembly-client.html" = "https://nymtech.net/developers/clients/webassembly-client.html" -"/sdk/typescript.html" = "https://sdk.nymtech.net" -"/clients/websocket-client.html" = "https://nymtech.net/developers/clients/websocket-client.html" -"/use-apps/blockstream-green" = "https://nymtech.net/developers/clients/socks5/usage.html" -"/use-apps/telegram" = "https://nymtech.net/developers/archive/nym-connect.html#telegram-via-nymconnect" - diff --git a/sdk/typescript/docs/code-examples/cosmoskit-example-code.mdx b/documentation/docs/code-examples/sdk/typescript/cosmoskit-example-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/cosmoskit-example-code.mdx rename to documentation/docs/code-examples/sdk/typescript/cosmoskit-example-code.mdx diff --git a/sdk/typescript/docs/code-examples/mixfetch-example-code.mdx b/documentation/docs/code-examples/sdk/typescript/mixfetch-example-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/mixfetch-example-code.mdx rename to documentation/docs/code-examples/sdk/typescript/mixfetch-example-code.mdx diff --git a/sdk/typescript/docs/code-examples/mixnodes-example-code.mdx b/documentation/docs/code-examples/sdk/typescript/mixnodes-example-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/mixnodes-example-code.mdx rename to documentation/docs/code-examples/sdk/typescript/mixnodes-example-code.mdx diff --git a/sdk/typescript/docs/code-examples/traffic-example-code.mdx b/documentation/docs/code-examples/sdk/typescript/traffic-example-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/traffic-example-code.mdx rename to documentation/docs/code-examples/sdk/typescript/traffic-example-code.mdx diff --git a/sdk/typescript/docs/code-examples/wallet-connect-code.mdx b/documentation/docs/code-examples/sdk/typescript/wallet-connect-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/wallet-connect-code.mdx rename to documentation/docs/code-examples/sdk/typescript/wallet-connect-code.mdx diff --git a/sdk/typescript/docs/code-examples/wallet-delegations-code.mdx b/documentation/docs/code-examples/sdk/typescript/wallet-delegations-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/wallet-delegations-code.mdx rename to documentation/docs/code-examples/sdk/typescript/wallet-delegations-code.mdx diff --git a/sdk/typescript/docs/code-examples/wallet-sendTokens-code.mdx b/documentation/docs/code-examples/sdk/typescript/wallet-sendTokens-code.mdx similarity index 100% rename from sdk/typescript/docs/code-examples/wallet-sendTokens-code.mdx rename to documentation/docs/code-examples/sdk/typescript/wallet-sendTokens-code.mdx diff --git a/sdk/typescript/docs/code-snippets/mixfetchurl.tsx b/documentation/docs/code-snippets/mixfetchurl.tsx similarity index 100% rename from sdk/typescript/docs/code-snippets/mixfetchurl.tsx rename to documentation/docs/code-snippets/mixfetchurl.tsx diff --git a/documentation/docs/components/accordion-template.tsx b/documentation/docs/components/accordion-template.tsx new file mode 100644 index 0000000000..7b4693538a --- /dev/null +++ b/documentation/docs/components/accordion-template.tsx @@ -0,0 +1,36 @@ +import Accordion from "@mui/material/Accordion"; +import AccordionActions from "@mui/material/AccordionActions"; +import AccordionSummary from "@mui/material/AccordionSummary"; +import AccordionDetails from "@mui/material/AccordionDetails"; +import ExpandMoreIcon from "@mui/icons-material/ExpandMore"; +import { + TableContainer, + Table, + TableBody, + TableCell, + TableRow, + Paper, +} from "@mui/material"; + + + +export const AccordionTemplate = ({ name, children }) => { +return ( +
+ + } + aria-controls="panel1-content" + id="panel1-header" + aria-label="nym-node --help command output" + > + {name} + + + {children} + + +
+ ) +}; + diff --git a/sdk/typescript/docs/components/client/index.ts b/documentation/docs/components/client/index.ts similarity index 100% rename from sdk/typescript/docs/components/client/index.ts rename to documentation/docs/components/client/index.ts diff --git a/sdk/typescript/docs/components/cosmos-kit/data.ts b/documentation/docs/components/cosmos-kit/data.ts similarity index 100% rename from sdk/typescript/docs/components/cosmos-kit/data.ts rename to documentation/docs/components/cosmos-kit/data.ts diff --git a/sdk/typescript/docs/components/cosmos-kit/index.tsx b/documentation/docs/components/cosmos-kit/index.tsx similarity index 100% rename from sdk/typescript/docs/components/cosmos-kit/index.tsx rename to documentation/docs/components/cosmos-kit/index.tsx diff --git a/sdk/typescript/docs/components/cosmos-kit/ledger.tsx b/documentation/docs/components/cosmos-kit/ledger.tsx similarity index 100% rename from sdk/typescript/docs/components/cosmos-kit/ledger.tsx rename to documentation/docs/components/cosmos-kit/ledger.tsx diff --git a/sdk/typescript/docs/components/cosmos-kit/sign.tsx b/documentation/docs/components/cosmos-kit/sign.tsx similarity index 100% rename from sdk/typescript/docs/components/cosmos-kit/sign.tsx rename to documentation/docs/components/cosmos-kit/sign.tsx diff --git a/documentation/docs/components/footer.tsx b/documentation/docs/components/footer.tsx new file mode 100644 index 0000000000..bc6c8e8951 --- /dev/null +++ b/documentation/docs/components/footer.tsx @@ -0,0 +1,21 @@ +import React from "react"; +import Stack from "@mui/material/Stack"; + +const links = [ + ["Matrix", "https://matrix.to/#/#dev:nymtech.chat"], + ["GitHub", "https://nymtech.net/go/github/nym"], + ["Nym Wallet", "https://nymtech.net/download/wallet"], + ["Nym Explorer", "https://explorer.nymtech.net/"], + ["Nym Blog", "https://nymtech.medium.com/"], + ["Twitter", "https://nymtech.net/go/twitter"], + ["Telegram", "https://nymtech.net/go/telegram"], +]; +export const Footer = () => ( + + {links.map((link) => ( + + {link[0]} + + ))} + +); diff --git a/documentation/docs/components/generic-tabs.tsx b/documentation/docs/components/generic-tabs.tsx new file mode 100644 index 0000000000..40cbec3a21 --- /dev/null +++ b/documentation/docs/components/generic-tabs.tsx @@ -0,0 +1,5 @@ +import { Tabs } from 'nextra/components'; + +export const MyTab = ({ name, children }) => ( + {name} {children} +); diff --git a/documentation/docs/components/landing-page.tsx b/documentation/docs/components/landing-page.tsx new file mode 100644 index 0000000000..87b9f29fff --- /dev/null +++ b/documentation/docs/components/landing-page.tsx @@ -0,0 +1,143 @@ +import React from "react"; +import { Box, Grid, Typography } from "@mui/material"; +import useMediaQuery from "@mui/material/useMediaQuery"; +import { useTheme } from "@mui/material/styles"; + +import Image from "next/image"; +import Link from "next/link"; + +import networkDocs from "../public/images/landing/network-docs.png"; +import developerDocs from "../public/images/landing/developer-docs.png"; +import sdkDocs from "../public/images/landing/sdk-docs.png"; +import operatorGuide from "../public/images/landing/operator-guide.png"; +import { t } from "nextra/dist/types-c8e621b7"; +// import networkDocs from "./images/network-docs.png"; +// import developerDocs from "./images/developer-docs.png"; +// import sdkDocs from "./images/sdk-docs.png"; +// import operatorGuide from "./images/operator-guide.png"; + +export const LandingPage = () => { + const theme = useTheme(); + const isTablet = useMediaQuery(theme.breakpoints.up("md")); + const isDesktop = useMediaQuery(theme.breakpoints.up("xl")); + + const squares = [ + { + text: "Network Docs", + description: "Architecture, crypto systems, and how the Mixnet works", + href: "/network", + icon: developerDocs, + }, + { + text: "Operator Guides", + description: + "Guides and maintenance: if you want to run a node, start here", + + href: "/operators/introduction", + icon: operatorGuide, + }, + { + text: "Developer Portal", + description: + "Conceptual overview, clients, and tools for developers and integrations", + + href: "/developers", + icon: networkDocs, + }, + { + text: "SDKs", + description: "Rust and Typescript SDK docs", + + href: "/developers/rust", + icon: sdkDocs, + }, + ]; + + const shortenDescription = (description: string) => { + return description.slice(0, 18) + "..."; + }; + + return ( + + + Nym Docs + + + + Nym is a privacy platform. It provides strong network-level privacy + against sophisticated end-to-end attackers, and anonymous access control + using blinded, re-randomizable, decentralized credentials. Our goal is + to allow developers to build new applications, or upgrade existing apps, + with privacy features unavailable in other systems. + + + {squares.map((square, index) => ( + + + + {square.text} + + + {square.text} + + + + {square.description} + + + + Open + + + + + + ))} + + + ); +}; diff --git a/documentation/docs/components/matrix-link.tsx b/documentation/docs/components/matrix-link.tsx new file mode 100644 index 0000000000..754857688a --- /dev/null +++ b/documentation/docs/components/matrix-link.tsx @@ -0,0 +1,15 @@ +import { Box } from "@mui/material"; +import Image from "next/image"; +import Link from "next/link"; +import matrixLogo from "../public/images/matrix-logo.png"; +export const Matrix = () => { + return ( + + {"Matrix + + ); +}; diff --git a/sdk/typescript/docs/components/mix-fetch.tsx b/documentation/docs/components/mix-fetch.tsx similarity index 61% rename from sdk/typescript/docs/components/mix-fetch.tsx rename to documentation/docs/components/mix-fetch.tsx index 06cbe5fed2..32557baf11 100644 --- a/sdk/typescript/docs/components/mix-fetch.tsx +++ b/documentation/docs/components/mix-fetch.tsx @@ -1,26 +1,25 @@ -import React, { useState } from 'react'; -import CircularProgress from '@mui/material/CircularProgress'; -import Button from '@mui/material/Button'; -import TextField from '@mui/material/TextField'; -import Typography from '@mui/material/Typography'; -import Box from '@mui/material/Box'; -import { mixFetch } from '@nymproject/mix-fetch-full-fat'; -import Stack from '@mui/material/Stack'; -import Paper from '@mui/material/Paper'; -import type { SetupMixFetchOps } from '@nymproject/mix-fetch-full-fat'; +import React, { useState } from "react"; +import CircularProgress from "@mui/material/CircularProgress"; +import Button from "@mui/material/Button"; +import TextField from "@mui/material/TextField"; +import Typography from "@mui/material/Typography"; +import Box from "@mui/material/Box"; +import { mixFetch } from "@nymproject/mix-fetch-full-fat"; +import Stack from "@mui/material/Stack"; +import Paper from "@mui/material/Paper"; +import type { SetupMixFetchOps } from "@nymproject/mix-fetch-full-fat"; -const defaultUrl = 'https://nymtech.net/favicon.svg'; -const args = { mode: 'unsafe-ignore-cors' }; +const defaultUrl = "https://nymtech.net/favicon.svg"; +const args = { mode: "unsafe-ignore-cors" }; const mixFetchOptions: SetupMixFetchOps = { - preferredGateway: '6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B', // with WSS + preferredGateway: "6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B", // with WSS preferredNetworkRequester: - '8rRGWy54oC8drFL9DepMegBt2DLrsqQwCoHMXt9nsnTo.2XjCPVbb4FpQ9hNRcXwb9mTzEAVVk1zf1tcch3wdtNEA@6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B', + "8rRGWy54oC8drFL9DepMegBt2DLrsqQwCoHMXt9nsnTo.2XjCPVbb4FpQ9hNRcXwb9mTzEAVVk1zf1tcch3wdtNEA@6Gb7ftQdKveMjPyrxDXeAtfYAX7Zg5mVZHtnRC5MmZ1B", mixFetchOverride: { requestTimeoutMs: 60_000, }, forceTls: true, // force WSS - extra: {}, }; export const MixFetch = () => { @@ -44,7 +43,7 @@ export const MixFetch = () => { }; return ( -
+
{ defaultValue={defaultUrl} onChange={(e) => setUrl(e.target.value)} /> - diff --git a/sdk/typescript/docs/components/mixnodes.tsx b/documentation/docs/components/mixnodes.tsx similarity index 100% rename from sdk/typescript/docs/components/mixnodes.tsx rename to documentation/docs/components/mixnodes.tsx diff --git a/sdk/typescript/docs/components/npm.tsx b/documentation/docs/components/npm.tsx similarity index 100% rename from sdk/typescript/docs/components/npm.tsx rename to documentation/docs/components/npm.tsx diff --git a/documentation/docs/components/operators/nodes/example_accordion.tsx b/documentation/docs/components/operators/nodes/example_accordion.tsx new file mode 100644 index 0000000000..1d496f09db --- /dev/null +++ b/documentation/docs/components/operators/nodes/example_accordion.tsx @@ -0,0 +1,20 @@ +import {Accordion, AccordionItem} from "@nextui-org/react"; + +export const App = () => { + const defaultContent = + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."; + + return ( + + + {defaultContent} + + + {defaultContent} + + + {defaultContent} + + + ); +} diff --git a/documentation/docs/components/operators/nodes/node-migrate-command-tabs.tsx b/documentation/docs/components/operators/nodes/node-migrate-command-tabs.tsx new file mode 100644 index 0000000000..68a2eda99d --- /dev/null +++ b/documentation/docs/components/operators/nodes/node-migrate-command-tabs.tsx @@ -0,0 +1,21 @@ +import { Tabs } from "nextra/components"; +import Mixnodes from "components/operators/snippets/mixnode-migrate-tab-snippet.mdx"; +import Gateways from "components/operators/snippets/gateway-migrate-tab-snippet.mdx"; + +export const MigrateTabs = () => { + return ( +
+ nym-mixnode, nym-gateway]} + defaultIndex={1} + > + + + + + + + +
+ ); +}; diff --git a/documentation/docs/components/operators/nodes/node-run-command-tabs.tsx b/documentation/docs/components/operators/nodes/node-run-command-tabs.tsx new file mode 100644 index 0000000000..c5482e32c7 --- /dev/null +++ b/documentation/docs/components/operators/nodes/node-run-command-tabs.tsx @@ -0,0 +1,21 @@ +import { Tabs } from 'nextra/components'; +import Mixnodes from 'components/operators/snippets/mixnode-run-tab-snippet.mdx'; +import EntryGateway from 'components/operators/snippets/entry-gateway-run-tab-snippet.mdx'; +import ExitGateway from 'components/operators/snippets/exit-gateway-run-tab-snippet.mdx'; + +export const RunTabs = () => { + + return ( +
+ mixnode, + exit-gateway, + entry-gateway + ]} defaultIndex={1}> + + + + +
+ ) +} diff --git a/documentation/docs/components/operators/snippets/entry-gateway-run-tab-snippet.mdx b/documentation/docs/components/operators/snippets/entry-gateway-run-tab-snippet.mdx new file mode 100644 index 0000000000..677a54a82c --- /dev/null +++ b/documentation/docs/components/operators/snippets/entry-gateway-run-tab-snippet.mdx @@ -0,0 +1,34 @@ +<> +If you run a `nym-node` for the first time, you will need to specify a few parameters, please read the section [Essential Parameters & Variables](#essential-paramteters--varibles) before you start and make sure that your `nym-node` is up to date with the [latest version](https://github.com/nymtech/nym/releases/). + +**Initialise and run:** + +To initialise and test run with yur node with all needed options, use this command: +```sh +./nym-node run --id --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +``` +If you prefer to have a generic local identifier set to `default-nym-node`, skip `--id` option. + +We highly recommend to setup [reverse proxy and WSS](proxy-configuration.md) for `nym-node`. If you haven't configured any of that, skip `--hostname` flag. + +In any case `--public-ips` is a necessity for your node to bond to API and communicate with the internet. + +**Initialise only** without running the node with `--init-only` command : + +Adding `--init-only` option results in `nym-node` initialising a configuration file `config.toml` without running - a good option for an initial node setup. Remember that if you using this flag on a node which already has a config file, this will not over-write the values, unless used with a specified flag `--write-changes` (`-w`) - a good option for introducing changes to your `config.toml` file. + +```sh +./nym-node run --id --init-only --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --wireguard-enabled true +``` + +In the example above we dropped `--accept-operator-terms-and-conditions` as the flag must be added to a running command explicitly and it is not stored in the config, `--init-only` will not run the node. + +**Deny init** + +`--deny-init` was introduced as an additional safety for migration from legacy binaries to `nym-node` to prevent operators initialise over existing nodes. For most of the operators, this flag is not needed. + +In this example we run the node with custom `--id` without initialising, using `--deny-init` command: +```sh +./nym-node run --id --deny-init --mode entry-gateway --accept-operator-terms-and-conditions +``` + diff --git a/documentation/docs/components/operators/snippets/exit-gateway-run-tab-snippet.mdx b/documentation/docs/components/operators/snippets/exit-gateway-run-tab-snippet.mdx new file mode 100644 index 0000000000..cac6b42a7e --- /dev/null +++ b/documentation/docs/components/operators/snippets/exit-gateway-run-tab-snippet.mdx @@ -0,0 +1,35 @@ +<> +If you run a `nym-node` for the first time, you will need to specify a few parameters, please read the section [Essential Parameters & Variables](#essential-paramteters--varibles) before you start and make sure that your `nym-node` is up to date with the [latest version](https://github.com/nymtech/nym/releases/). + +**Initialise and Run** + +To initialise and test run your node, use this command: +```sh +./nym-node run --id --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +``` +If you prefer to have a generic local identifier set to `default-nym-node`, skip `--id` option. + +We highly recommend to setup [reverse proxy and WSS](proxy-configuration.md) for `nym-node`. If you haven't configured any of that, skip `--hostname` flag. + +In any case `--public-ips` is a necessity for your node to bond to API and communicate with the internet. + + +**Initialise only** without running the node with `--init-only` command: + +Adding `--init-only` option results in `nym-node` initialising a configuration file `config.toml` without running - a good option for an initial node setup. Remember that if you using this flag on a node which already has a config file, this will not over-write the values, unless used with a specified flag `--write-changes` (`-w`) - a good option for introducing changes to your `config.toml` file. + +```sh +./nym-node run --id --init-only --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname "" --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --wireguard-enabled true +``` + +In the example above we dropped `--accept-operator-terms-and-conditions` as the flag must be added to a running command explicitly and it is not stored in the config, `--init-only` will not run the node. + +**Deny init** + +`--deny-init` was introduced as an additional safety for migration from legacy binaries to `nym-node` to prevent operators initialise over existing nodes. For most of the operators, this flag is not needed. + +In this example we run the node with custom `--id` without initialising, using `--deny-init` command: +```sh +./nym-node run --id --deny-init --mode exit-gateway --accept-operator-terms-and-conditions +``` + diff --git a/documentation/docs/components/operators/snippets/gateway-migrate-tab-snippet.mdx b/documentation/docs/components/operators/snippets/gateway-migrate-tab-snippet.mdx new file mode 100644 index 0000000000..101dbca21c --- /dev/null +++ b/documentation/docs/components/operators/snippets/gateway-migrate-tab-snippet.mdx @@ -0,0 +1,23 @@ +import { Steps } from 'nextra/components'; + +<> +Migrate your `nym-gateway` to `nym-node --mode entry-gateway` or `--mode exit-gateway` using these commands: + +###### 1. Move relevant info from `config.toml` +```sh +./nym-node migrate --config-file ~/.nym/gateways//config/config.toml gateway +``` + +###### 2. Initialise with new `nym-node` config chosing one of the options below: + +- as `entry-gateway`: +```sh +./nym-node run --id --mode entry-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +``` + +- or as `exit-gateway`: +```sh +./nym-node run --id --mode exit-gateway --public-ips "$(curl -4 https://ifconfig.me)" --hostname --http-bind-address 0.0.0.0:8080 --mixnet-bind-address 0.0.0.0:1789 --location --accept-operator-terms-and-conditions --wireguard-enabled true +``` + + diff --git a/documentation/docs/components/operators/snippets/mixnode-migrate-tab-snippet.mdx b/documentation/docs/components/operators/snippets/mixnode-migrate-tab-snippet.mdx new file mode 100644 index 0000000000..1be3b74a1f --- /dev/null +++ b/documentation/docs/components/operators/snippets/mixnode-migrate-tab-snippet.mdx @@ -0,0 +1,16 @@ +import { Steps } from 'nextra/components'; + +<> +Migrate your `nym-mixnode` to `nym-node --mode mixnode` using these commands: + +###### 1. Move relevant info from `config.toml` +```sh +./nym-node migrate --config-file ~/.nym/mixnodes//config/config.toml mixnode +``` + +###### 2. Initialise with new `nym-node` config +```sh +./nym-node run --mode mixnode --id --location --mixnet-bind-address 0.0.0.0:1789 --http-bind-address 0.0.0.0:8080 --accept-operator-terms-and-conditions +``` + + diff --git a/documentation/docs/components/operators/snippets/mixnode-run-tab-snippet.mdx b/documentation/docs/components/operators/snippets/mixnode-run-tab-snippet.mdx new file mode 100644 index 0000000000..9686aeff17 --- /dev/null +++ b/documentation/docs/components/operators/snippets/mixnode-run-tab-snippet.mdx @@ -0,0 +1,31 @@ +<> +If you run a `nym-node` for the first time, you will need to specify a few parameters, please read the section [Essential Parameters & Variables](#essential-paramteters--varibles) before you start and make sure that your `nym-node` is up to date with the [latest version](https://github.com/nymtech/nym/releases/). + +**Initialise and Run:** + +To initialise and run your node, use this command: + +```sh +./nym-node run --mode mixnode --mixnet-bind-address 0.0.0.0:1789 --verloc-bind-address 0.0.0.0:1790 --http-bind-address 0.0.0.0:8080 --public-ips "$(curl -4 https://ifconfig.me)" --accept-operator-terms-and-conditions +``` + +**Init only** + +Adding `--init-only` option results in `nym-node` initialising a configuration file `config.toml` without running - a good option for an initial node setup. Remember that if you using this flag on a node which already has a config file, this will not over-write the values, unless used with a specified flag `--write-changes` (`-w`) - a good option for introducing changes to your `config.toml` file. + +Initialise only with a custom `--id` and `--init-only` command: +```sh +./nym-node run --mode mixnode --id --init-only --mixnet-bind-address 0.0.0.0:1789 --verloc-bind-address 0.0.0.0:1790 --http-bind-address 0.0.0.0:8080 --public-ips "$(curl -4 https://ifconfig.me)" --accept-operator-terms-and-conditions +``` + +If you prefer to have a generic local identifier set to `default-nym-node`, skip `--id` option. + +**Deny init** + +`--deny-init` was introduced as an additional safety for migration from legacy binaries to `nym-node` to prevent operators initialise over existing nodes. For most of the operators, this flag is not needed. + +In this example we run the node with custom `--id` without initialising, using `--deny-init` command: +```sh +./nym-node run --mode mixnode --id --deny-init --accept-operator-terms-and-conditions +``` + diff --git a/documentation/docs/components/operators/snippets/ports-nym-node.mdx b/documentation/docs/components/operators/snippets/ports-nym-node.mdx new file mode 100644 index 0000000000..d9d2813045 --- /dev/null +++ b/documentation/docs/components/operators/snippets/ports-nym-node.mdx @@ -0,0 +1,13 @@ +Open the needed ports for `nym-node` by running these commands: + +```sh +ufw allow 22/tcp # SSH - you're in control of these ports +ufw allow 80/tcp # HTTP +ufw allow 443/tcp # HTTPS +ufw allow 1789/tcp # Nym specific +ufw allow 1790/tcp # Nym specific +ufw allow 8080/tcp # Nym specific - nym-node-api +ufw allow 9000/tcp # Nym Specific - clients port +ufw allow 9001/tcp # Nym specific - wss port +ufw allow 51822/udp # WireGuard +``` diff --git a/documentation/docs/components/operators/snippets/ports-validator.mdx b/documentation/docs/components/operators/snippets/ports-validator.mdx new file mode 100644 index 0000000000..d118988137 --- /dev/null +++ b/documentation/docs/components/operators/snippets/ports-validator.mdx @@ -0,0 +1,10 @@ +Open the needed ports for `validator` by running these commands: + +```sh +ufw allow 1317 # REST API server endpoint +ufw allow 26656 # Listen for incoming peer connections +ufw allow 26660 # Listen for Prometheus connections +ufw allow 22 # SSH port +ufw allow 80 # http port +ufw allow 443/tcp # https port +``` diff --git a/documentation/docs/components/operators/snippets/update-cli-steps.mdx b/documentation/docs/components/operators/snippets/update-cli-steps.mdx new file mode 100644 index 0000000000..c7b42b3fd0 --- /dev/null +++ b/documentation/docs/components/operators/snippets/update-cli-steps.mdx @@ -0,0 +1,7 @@ +import { Callout } from 'nextra/components'; + +If you want to bond or upgrade your `nym-node` via the CLI, then check out the [relevant section in the Nym CLI](https://nymtech.net/docs/tools/nym-cli.html#upgrade-a-mix-node) docs. + + +If you run in mode `--entry-gateway` or `--exit-gateway`, visit [Nym Harbour Master](https://harbourmaster.nymtech.net/) to get all the probe info about your node directly from API. + diff --git a/documentation/docs/components/operators/snippets/update-desktop-wallet-steps.mdx b/documentation/docs/components/operators/snippets/update-desktop-wallet-steps.mdx new file mode 100644 index 0000000000..ff33b73aad --- /dev/null +++ b/documentation/docs/components/operators/snippets/update-desktop-wallet-steps.mdx @@ -0,0 +1,9 @@ +- Open your Desktop wallet + +- Navigate to the `Bonding` page and click the `Node Settings` link in the top right corner + +![](/images/operators/wallet-screenshots/bonding.png) + +- Update the fields in the `Node Settings` page (usually the field `Version` is the only one to change) and click `Submit changes to the blockchain`. + +![](/images/operators/wallet-screenshots/node_settings.png) diff --git a/documentation/docs/components/outputs/api-scraping-outputs/time-now.md b/documentation/docs/components/outputs/api-scraping-outputs/time-now.md new file mode 100644 index 0000000000..6f5e29204b --- /dev/null +++ b/documentation/docs/components/outputs/api-scraping-outputs/time-now.md @@ -0,0 +1 @@ +Tuesday, October 29th 2024, 09:51:52 UTC diff --git a/documentation/docs/components/outputs/command-outputs/node-api-check-help.md b/documentation/docs/components/outputs/command-outputs/node-api-check-help.md new file mode 100644 index 0000000000..875b2921ae --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/node-api-check-help.md @@ -0,0 +1,17 @@ +```python +usage: Nym-node API check [-h] [-V] + {query_stats,q,query,version_count,v,version} ... + +Run through all endpoints and print results. + +positional arguments: + {query_stats,q,query,version_count,v,version} + query_stats (q, query) + Get all nodes API endpoints + version_count (v, version) + Sum of nodes in given version(s) + +options: + -h, --help show this help message and exit + -V, --version show program's version number and exit +``` diff --git a/documentation/docs/components/outputs/command-outputs/node-api-check-query-help.md b/documentation/docs/components/outputs/command-outputs/node-api-check-query-help.md new file mode 100644 index 0000000000..bfa068ddb0 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/node-api-check-query-help.md @@ -0,0 +1,17 @@ +```python +usage: Nym-node API check query_stats [-h] [--no_routing_history] + [--no_verloc_metrics] [-m] [-o [OUTPUT]] + id + +positional arguments: + id supply nym-node identity key + +options: + -h, --help show this help message and exit + --no_routing_history Display node stats without routing history + --no_verloc_metrics Display node stats without verloc metrics + -m, --markdown Display results in markdown format + -o [OUTPUT], --output [OUTPUT] + Save results to file (in current dir or supply with + path without filename) +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-api-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nym-api-build-info-help.md new file mode 100644 index 0000000000..7ece0cff3a --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-api-build-info-help.md @@ -0,0 +1,10 @@ +```sh +2024-10-29T09:51:44.050179Z  INFO nym-api/src/main.rs:41: Starting nym api... +Show build information of this binary + +Usage: nym-api build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-api-build-info.md b/documentation/docs/components/outputs/command-outputs/nym-api-build-info.md new file mode 100644 index 0000000000..107dd29a8a --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-api-build-info.md @@ -0,0 +1,14 @@ +```sh +2024-10-29T09:51:44.043480Z  INFO nym-api/src/main.rs:41: Starting nym api... + +Binary Name: nym-api +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.45 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-api-help.md b/documentation/docs/components/outputs/command-outputs/nym-api-help.md new file mode 100644 index 0000000000..f46bf78088 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-api-help.md @@ -0,0 +1,20 @@ +```sh +2024-10-29T09:51:53.363364Z  INFO nym-api/src/main.rs:41: Starting nym api... +Usage: nym-api [OPTIONS] + +Commands: + init Initialise a Nym Api instance with persistent config.toml file + run Run the Nym Api with provided configuration optionally overriding set parameters + build-info Show build information of this binary + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the Nym API [env: NYMAPI_CONFIG_ENV_FILE_ARG=] + --no-banner + A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) [env: NYMAPI_NO_BANNER_ARG=] + -h, --help + Print help + -V, --version + Print version +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-api-init-help.md b/documentation/docs/components/outputs/command-outputs/nym-api-init-help.md new file mode 100644 index 0000000000..6427278bdf --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-api-init-help.md @@ -0,0 +1,28 @@ +```sh +2024-10-29T09:51:44.027197Z  INFO nym-api/src/main.rs:41: Starting nym api... +Initialise a Nym Api instance with persistent config.toml file + +Usage: nym-api init [OPTIONS] + +Options: + --id + Id of the nym-api we want to initialise. if unspecified, a default value will be used. default: "default" [env: NYMAPI_ID_ARG=] [default: default] + -m, --enable-monitor + Specifies whether network monitoring is enabled on this API default: false [env: NYMAPI_ENABLE_MONITOR_ARG=] + -r, --enable-rewarding + Specifies whether network rewarding is enabled on this API default: false [env: NYMAPI_ENABLE_REWARDING_ARG=] + --nyxd-validator + Endpoint to nyxd instance used for contract information. default: http://localhost:26657 [env: NYMAPI_NYXD_VALIDATOR_ARG=] + --mnemonic + Mnemonic of the network monitor used for sending rewarding and zk-nyms transactions default: None [env: NYMAPI_MNEMONIC_ARG=] + --enable-zk-nym + Flag to indicate whether credential signer authority is enabled on this API default: false [env: NYMAPI_ENABLE_ZK_NYM_ARG=] + --announce-address + Announced address that is going to be put in the DKG contract where zk-nym clients will connect to obtain their credentials default: None [env: NYMAPI_ANNOUNCE_ADDRESS_NYM_ARG=] + --monitor-credentials-mode + Set this nym api to work in a enabled credentials that would attempt to use gateway with the bandwidth credential requirement [env: NYMAPI_MONITOR_CREDENTIALS_MODE_ARG=] + --bind-address + Socket address this api will use for binding its http API. default: `127.0.0.1:8080` in `debug` builds and `0.0.0.0:8080` in `release` + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-api-init.md b/documentation/docs/components/outputs/command-outputs/nym-api-init.md new file mode 100644 index 0000000000..976a4ae91d --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-api-init.md @@ -0,0 +1,3 @@ +```sh +2024-10-29T09:51:44.019255Z  INFO nym-api/src/main.rs:41: Starting nym api... +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-build-info-help.md new file mode 100644 index 0000000000..f65dc4e7c4 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-build-info.md b/documentation/docs/components/outputs/command-outputs/nym-client-build-info.md new file mode 100644 index 0000000000..8bf2f6fa1c --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-client +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.42 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-completions-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-completions-help.md new file mode 100644 index 0000000000..f09b17f785 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-completions-help.md @@ -0,0 +1,11 @@ +```sh +Generate shell completions + +Usage: nym-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec-help.md new file mode 100644 index 0000000000..ecce720ea9 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec-help.md @@ -0,0 +1,8 @@ +```sh +Generate Fig specification + +Usage: nym-client generate-fig-spec + +Options: + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec.md b/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec.md new file mode 100644 index 0000000000..53d1c326d5 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-generate-fig-spec.md @@ -0,0 +1,818 @@ +```sh +const completion: Fig.Spec = { + name: "nym-native-client", + description: "Implementation of the Nym Client", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket (if applicable) to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: "--standalone", + description: "Specifies whether we're attempting to import a standalone ticketbook (i.e. serialised `IssuedTicketBook`)", + }, + { + name: "--full", + description: "Specifies whether we're attempting to import full ticketboot (i.e. one that **might** contain required global signatures; that is serialised `ImportableTicketBook`)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the key", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the key", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--key-data", + description: "Explicitly provide the encoded key data (as base58)", + isRepeatable: true, + args: { + name: "key_data", + isOptional: true, + }, + }, + { + name: "--key-path", + description: "Specifies the path to file containing binary key data", + isRepeatable: true, + args: { + name: "key_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-import-credential-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-import-credential-help.md new file mode 100644 index 0000000000..2f50fd0537 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-import-credential-help.md @@ -0,0 +1,2 @@ +```sh +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-init-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-init-help.md new file mode 100644 index 0000000000..3d58fe52c2 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-init-help.md @@ -0,0 +1,27 @@ +```sh +Initialise a Nym client. Do this first! + +Usage: nym-client init [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we are going to connect to + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket (if applicable) to listen on in all subsequent runs + --host + Ip for the socket (if applicable) to listen for requests + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-list-gateways-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-list-gateways-help.md new file mode 100644 index 0000000000..2cddc84edc --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-list-gateways-help.md @@ -0,0 +1,10 @@ +```sh +List all registered with gateways + +Usage: nym-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-run-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-run-help.md new file mode 100644 index 0000000000..deb33eab62 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-run-help.md @@ -0,0 +1,21 @@ +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket to listen on + --host + Ip for the socket (if applicable) to listen for requests + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-client-switch-gateway-help.md b/documentation/docs/components/outputs/command-outputs/nym-client-switch-gateway-help.md new file mode 100644 index 0000000000..53277ffdd2 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-client-switch-gateway-help.md @@ -0,0 +1,10 @@ +```sh +Change the currently active gateway. Note that you must have already registered with the new gateway! + +Usage: nym-client switch-gateway --id --gateway-id + +Options: + --id Id of client we want to list gateways for + --gateway-id Id of the gateway we want to switch to + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information-help.md new file mode 100644 index 0000000000..8a54a3c853 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information-help.md @@ -0,0 +1,12 @@ +```sh +Show bonding information of this node depending on its currently selected mode + +Usage: nym-node bonding-information [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --mode [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway] + -o, --output Specify the output format of the bonding information (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information.md b/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information.md new file mode 100644 index 0000000000..b20c9dd9fb --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-bonding-information.md @@ -0,0 +1,3 @@ +```sh +2024-10-29T09:51:44.440498Z ERROR nym-node/src/config/upgrade_helpers.rs:16: Failed to finish upgrade - failed to load config file using path '/home/m/.nym/nym-nodes/default-nym-node/config/config.toml'. detailed message: No such file or directory (os error 2) +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-build-info-help.md new file mode 100644 index 0000000000..0f369b8537 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-node build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-build-info.md b/documentation/docs/components/outputs/command-outputs/nym-node-build-info.md new file mode 100644 index 0000000000..abc2bd416f --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-node +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.9 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-help.md new file mode 100644 index 0000000000..62836e167d --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-help.md @@ -0,0 +1,22 @@ +```sh +Usage: nym-node [OPTIONS] + +Commands: + build-info Show build information of this binary + bonding-information Show bonding information of this node depending on its currently selected mode + node-details Show details of this node + migrate Attempt to migrate an existing mixnode or gateway into a nym-node + run Start this nym-node + sign Use identity key of this node to sign provided message + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the nym-node and overrides any preconfigured values [env: NYMNODE_CONFIG_ENV_FILE_ARG=] + --no-banner + Flag used for disabling the printed banner in tty [env: NYMNODE_NO_BANNER=] + -h, --help + Print help + -V, --version + Print version +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-migrate-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-migrate-help.md new file mode 100644 index 0000000000..b040590c2a --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-migrate-help.md @@ -0,0 +1,72 @@ +```sh +Attempt to migrate an existing mixnode or gateway into a nym-node + +Usage: nym-node migrate [OPTIONS] <--id |--config-file > + +Arguments: + Type of node (mixnode or gateway) to migrate into a nym-node [possible values: mixnode, gateway] + +Options: + --id + Id of the node that's going to get migrated + --config-file + Path to a configuration file of the node that's going to get migrated + --preserve-id + Specify whether to preserve id of the imported node + --public-ips + Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=] + --hostname + Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=] + --location + Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=] + --http-bind-address + Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=] + --landing-page-assets-path + Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=] + --http-access-token + An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=] + --expose-system-info + Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false] + --expose-system-hardware + Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false] + --expose-crypto-hardware + Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false] + --mixnet-bind-address + Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=] + --mixnet-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=] + --nym-api-urls + Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=] + --nyxd-urls + Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=] + --wireguard-enabled + Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false] + --wireguard-bind-address + Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=] + --wireguard-private-ip + Private IP address of the wireguard gateway. default: `10.1.0.1` [env: NYMNODE_WG_IP=] + --wireguard-announced-port + Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=] + --wireguard-private-network-prefix + The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=] + --verloc-bind-address + Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=] + --verloc-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=] + --entry-bind-address + Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=] + --announce-ws-port + Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=] + --announce-wss-port + If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=] + --enforce-zk-nyms + Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false] + --mnemonic + Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=] + --upstream-exit-policy-url + Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=] + --open-proxy + Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false] + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-node-details-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-node-details-help.md new file mode 100644 index 0000000000..cad77bc2a8 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-node-details-help.md @@ -0,0 +1,11 @@ +```sh +Show details of this node + +Usage: nym-node node-details [OPTIONS] + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + -o, --output Specify the output format of the node details (`text` or `json`) [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-node-details.md b/documentation/docs/components/outputs/command-outputs/nym-node-node-details.md new file mode 100644 index 0000000000..768152ed3a --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-node-details.md @@ -0,0 +1,3 @@ +```sh +2024-10-29T09:51:44.459681Z ERROR nym-node/src/config/upgrade_helpers.rs:16: Failed to finish upgrade - failed to load config file using path '/home/m/.nym/nym-nodes/default-nym-node/config/config.toml'. detailed message: No such file or directory (os error 2) +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-run-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-run-help.md new file mode 100644 index 0000000000..29da832b97 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-run-help.md @@ -0,0 +1,83 @@ +```sh +Start this nym-node + +Usage: nym-node run [OPTIONS] + +Options: + --id + Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file + Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --accept-operator-terms-and-conditions + Explicitly specify whether you agree with the terms and conditions of a nym node operator as defined at [env: NYMNODE_ACCEPT_OPERATOR_TERMS=] + --deny-init + Forbid a new node from being initialised if configuration file for the provided specification doesn't already exist [env: NYMNODE_DENY_INIT=] + --init-only + If this is a brand new nym-node, specify whether it should only be initialised without actually running the subprocesses [env: NYMNODE_INIT_ONLY=] + --local + Flag specifying this node will be running in a local setting [env: NYMNODE_LOCAL=] + --mode + Specifies the current mode of this nym-node [env: NYMNODE_MODE=] [possible values: mixnode, entry-gateway, exit-gateway] + -w, --write-changes + If this node has been initialised before, specify whether to write any new changes to the config file [env: NYMNODE_WRITE_CONFIG_CHANGES=] + --bonding-information-output + Specify output file for bonding information of this nym-node, i.e. its encoded keys. NOTE: the required bonding information is still a subject to change and this argument should be treated only as a preview of future features [env: NYMNODE_BONDING_INFORMATION_OUTPUT=] + -o, --output + Specify the output format of the bonding information (`text` or `json`) [env: NYMNODE_OUTPUT=] [default: text] [possible values: text, json] + --public-ips + Comma separated list of public ip addresses that will be announced to the nym-api and subsequently to the clients. In nearly all circumstances, it's going to be identical to the address you're going to use for bonding [env: NYMNODE_PUBLIC_IPS=] + --hostname + Optional hostname associated with this gateway that will be announced to the nym-api and subsequently to the clients [env: NYMNODE_HOSTNAME=] + --location + Optional **physical** location of this node's server. Either full country name (e.g. 'Poland'), two-letter alpha2 (e.g. 'PL'), three-letter alpha3 (e.g. 'POL') or three-digit numeric-3 (e.g. '616') can be provided [env: NYMNODE_LOCATION=] + --http-bind-address + Socket address this node will use for binding its http API. default: `0.0.0.0:8080` [env: NYMNODE_HTTP_BIND_ADDRESS=] + --landing-page-assets-path + Path to assets directory of custom landing page of this node [env: NYMNODE_HTTP_LANDING_ASSETS=] + --http-access-token + An optional bearer token for accessing certain http endpoints. Currently only used for prometheus metrics [env: NYMNODE_HTTP_ACCESS_TOKEN=] + --expose-system-info + Specify whether basic system information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_INFO=] [possible values: true, false] + --expose-system-hardware + Specify whether basic system hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_SYSTEM_HARDWARE=] [possible values: true, false] + --expose-crypto-hardware + Specify whether detailed system crypto hardware information should be exposed. default: true [env: NYMNODE_HTTP_EXPOSE_CRYPTO_HARDWARE=] [possible values: true, false] + --mixnet-bind-address + Address this node will bind to for listening for mixnet packets default: `0.0.0.0:1789` [env: NYMNODE_MIXNET_BIND_ADDRESS=] + --mixnet-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_MIXNET_ANNOUNCE_PORT=] + --nym-api-urls + Addresses to nym APIs from which the node gets the view of the network [env: NYMNODE_NYM_APIS=] + --nyxd-urls + Addresses to nyxd chain endpoint which the node will use for chain interactions [env: NYMNODE_NYXD=] + --wireguard-enabled + Specifies whether the wireguard service is enabled on this node [env: NYMNODE_WG_ENABLED=] [possible values: true, false] + --wireguard-bind-address + Socket address this node will use for binding its wireguard interface. default: `0.0.0.0:51822` [env: NYMNODE_WG_BIND_ADDRESS=] + --wireguard-private-ip + Private IP address of the wireguard gateway. default: `10.1.0.1` [env: NYMNODE_WG_IP=] + --wireguard-announced-port + Port announced to external clients wishing to connect to the wireguard interface. Useful in the instances where the node is behind a proxy [env: NYMNODE_WG_ANNOUNCED_PORT=] + --wireguard-private-network-prefix + The prefix denoting the maximum number of the clients that can be connected via Wireguard. The maximum value for IPv4 is 32 and for IPv6 is 128 [env: NYMNODE_WG_PRIVATE_NETWORK_PREFIX=] + --verloc-bind-address + Socket address this node will use for binding its verloc API. default: `0.0.0.0:1790` [env: NYMNODE_VERLOC_BIND_ADDRESS=] + --verloc-announce-port + If applicable, custom port announced in the self-described API that other clients and nodes will use. Useful when the node is behind a proxy [env: NYMNODE_VERLOC_ANNOUNCE_PORT=] + --entry-bind-address + Socket address this node will use for binding its client websocket API. default: `0.0.0.0:9000` [env: NYMNODE_ENTRY_BIND_ADDRESS=] + --announce-ws-port + Custom announced port for listening for websocket client traffic. If unspecified, the value from the `bind_address` will be used instead [env: NYMNODE_ENTRY_ANNOUNCE_WS_PORT=] + --announce-wss-port + If applicable, announced port for listening for secure websocket client traffic [env: NYMNODE_ENTRY_ANNOUNCE_WSS_PORT=] + --enforce-zk-nyms + Indicates whether this gateway is accepting only coconut credentials for accessing the mixnet or if it also accepts non-paying clients [env: NYMNODE_ENFORCE_ZK_NYMS=] [possible values: true, false] + --mnemonic + Custom cosmos wallet mnemonic used for zk-nym redemption. If no value is provided, a fresh mnemonic is going to be generated [env: NYMNODE_MNEMONIC=] + --upstream-exit-policy-url + Specifies the url for an upstream source of the exit policy used by this node [env: NYMNODE_UPSTREAM_EXIT_POLICY=] + --open-proxy + Specifies whether this exit node should run in 'open-proxy' mode and thus would attempt to resolve **ANY** request it receives [env: NYMNODE_OPEN_PROXY=] [possible values: true, false] + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-node-sign-help.md b/documentation/docs/components/outputs/command-outputs/nym-node-sign-help.md new file mode 100644 index 0000000000..5d26baf2f2 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-node-sign-help.md @@ -0,0 +1,13 @@ +```sh +Use identity key of this node to sign provided message + +Usage: nym-node sign [OPTIONS] <--text |--contract-msg > + +Options: + --id Id of the nym-node to use [env: NYMNODE_ID=] [default: default-nym-node] + --config-file Path to a configuration file of this node [env: NYMNODE_CONFIG=] + --text Signs an arbitrary piece of text with your identity key + --contract-msg Signs a transaction-specific payload, that is going to be sent to the smart contract, with your identity key + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-add-gateway-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-add-gateway-help.md new file mode 100644 index 0000000000..ee209bdcb0 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-add-gateway-help.md @@ -0,0 +1,15 @@ +```sh +Add new gateway to this client + +Usage: nym-socks5-client add-gateway [OPTIONS] --id + +Options: + --id Id of client we want to add gateway for + --gateway-id Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead + --force-tls-gateway Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --set-active Specify whether this new gateway should be set as the active one + --nym-apis Comma separated list of rest endpoints of the API validators + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info-help.md new file mode 100644 index 0000000000..000204a113 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nym-socks5-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info.md new file mode 100644 index 0000000000..6ae9f633fe --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nym-socks5-client +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.42 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-completions-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-completions-help.md new file mode 100644 index 0000000000..8b780c6f17 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-completions-help.md @@ -0,0 +1,11 @@ +```sh +Generate shell completions + +Usage: nym-socks5-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec-help.md new file mode 100644 index 0000000000..94340b5898 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec-help.md @@ -0,0 +1,8 @@ +```sh +Generate Fig specification + +Usage: nym-socks5-client generate-fig-spec + +Options: + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec.md new file mode 100644 index 0000000000..49a1f244a4 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-generate-fig-spec.md @@ -0,0 +1,852 @@ +```sh +const completion: Fig.Spec = { + name: "nym-socks5-client", + description: "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + }, + }, + { + name: "--use-reply-surbs", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_reply_surbs", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--use-anonymous-replies", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_anonymous_replies", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + isOptional: true, + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--geo-routing", + description: "Set geo-aware mixnode selection when sending mixnet traffic, for experiments only", + hidden: true, + isRepeatable: true, + args: { + name: "geo_routing", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: "--medium-toggle", + description: "Enable medium mixnet traffic, for experiments only. This includes things like disabling cover traffic, no per hop delays, etc", + }, + { + name: "--outfox", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: "--standalone", + description: "Specifies whether we're attempting to import a standalone ticketbook (i.e. serialised `IssuedTicketBook`)", + }, + { + name: "--full", + description: "Specifies whether we're attempting to import full ticketboot (i.e. one that **might** contain required global signatures; that is serialised `ImportableTicketBook`)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the key", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the key", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--key-data", + description: "Explicitly provide the encoded key data (as base58)", + isRepeatable: true, + args: { + name: "key_data", + isOptional: true, + }, + }, + { + name: "--key-path", + description: "Specifies the path to file containing binary key data", + isRepeatable: true, + args: { + name: "key_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-import-credential-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-import-credential-help.md new file mode 100644 index 0000000000..2f50fd0537 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-import-credential-help.md @@ -0,0 +1,2 @@ +```sh +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-init-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-init-help.md new file mode 100644 index 0000000000..b69ef5f77c --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-init-help.md @@ -0,0 +1,44 @@ +```sh +Initialise a Nym client. Do this first! + +Usage: nym-socks5-client init [OPTIONS] --id --provider + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we are going to connect to + + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --provider + Address of the socks5 provider to send messages to + + --use-reply-surbs + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + -p, --port + Port for the socket to listen on in all subsequent runs + + --host + The custom host on which the socks5 client will be listening for requests + + -o, --output + [default: text] + [possible values: text, json] + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-list-gateways-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-list-gateways-help.md new file mode 100644 index 0000000000..86921bcf67 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-list-gateways-help.md @@ -0,0 +1,10 @@ +```sh +List all registered with gateways + +Usage: nym-socks5-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nym-socks5-client-run-help.md b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-run-help.md new file mode 100644 index 0000000000..2ffccb39ce --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nym-socks5-client-run-help.md @@ -0,0 +1,34 @@ +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-socks5-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --use-anonymous-replies + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + --provider + Address of the socks5 provider to send messages to + + -p, --port + Port for the socket to listen on + + --host + The custom host on which the socks5 client will be listening for requests + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymv-api-help.md b/documentation/docs/components/outputs/command-outputs/nymv-api-help.md new file mode 100644 index 0000000000..940536d5d0 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymv-api-help.md @@ -0,0 +1,34 @@ +Usage: nym-api [OPTIONS] + +Commands: + init Initialise a Nym Api instance with persistent config.toml file + run Run the Nym Api with provided configuration optionally overriding set parameters + build-info Show build information of this binary + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the Nym API + --no-banner + A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) + -h, --help + Print help + -V, --version + Print version +Usage: nym-api [OPTIONS] + +Commands: + init Initialise a Nym Api instance with persistent config.toml file + run Run the Nym Api with provided configuration optionally overriding set parameters + build-info Show build information of this binary + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the Nym API + --no-banner + A no-op flag included for consistency with other binaries (and compatibility with nymvisor, oops) + -h, --help + Print help + -V, --version + Print version diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-add-upgrade-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-add-upgrade-help.md new file mode 100644 index 0000000000..b88f5e1052 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-add-upgrade-help.md @@ -0,0 +1,19 @@ +```sh +Queues up another upgrade for the associated daemon + +Usage: nymvisor add-upgrade [OPTIONS] --upgrade-name + +Arguments: + Path to the daemon's upgrade executable + +Options: + --upgrade-name Name of this upgrade + --force Overwrite existing upgrade binary / upgrade-info.json file + --add-binary Indicate that this command should only add binary to an *existing* scheduled upgrade + --now Force the upgrade to happen immediately + --publish-date Specifies the publish date metadata field of this upgrade. If unset, the current time will be used + --upgrade-time Specifies the time at which the provided upgrade will be performed (RFC3339 formatted). If left unset, the upgrade will be performed in 15min + --upgrade-delay Specifies delay until the provided upgrade is going to get performed. If let unset, the upgrade will be performed in 15min + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-build-info-help.md new file mode 100644 index 0000000000..3a5ccb9b5b --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of this binary + +Usage: nymvisor build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-build-info.md b/documentation/docs/components/outputs/command-outputs/nymvisor-build-info.md new file mode 100644 index 0000000000..6db90dcec6 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-build-info.md @@ -0,0 +1,13 @@ +```sh + +Binary Name: nymvisor +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 0.1.8 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-config-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-config-help.md new file mode 100644 index 0000000000..696d346802 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-config-help.md @@ -0,0 +1,9 @@ +```sh +Show configuration options being used by this instance of nymvisor + +Usage: nymvisor config [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-daemon-build-info-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-daemon-build-info-help.md new file mode 100644 index 0000000000..c89ba02c59 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-daemon-build-info-help.md @@ -0,0 +1,9 @@ +```sh +Show build information of the associated daemon + +Usage: nymvisor daemon-build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-help.md new file mode 100644 index 0000000000..e4124a3ea9 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-help.md @@ -0,0 +1,20 @@ +```sh +Usage: nymvisor [OPTIONS] + +Commands: + init Initialise a nymvisor instance with persistent Config.toml file + run Run the associated daemon with the preconfigured settings + build-info Show build information of this binary + daemon-build-info Show build information of the associated daemon + add-upgrade Queues up another upgrade for the associated daemon + config Show configuration options being used by this instance of nymvisor + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file + Path pointing to an env file that configures the nymvisor and overrides any preconfigured values + -h, --help + Print help + -V, --version + Print version +``` diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-init-daemon.md b/documentation/docs/components/outputs/command-outputs/nymvisor-init-daemon.md new file mode 100644 index 0000000000..a6ea10e554 --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-init-daemon.md @@ -0,0 +1,6 @@ +2024-10-23T17:45:06.789452Z  INFO tools/nymvisor/src/cli/init.rs:416: enabled nymvisor logging +2024-10-23T17:45:06.789476Z  INFO tools/nymvisor/src/cli/init.rs:419: initialising the nymvisor +2024-10-23T17:45:06.789497Z  INFO get_build_information: tools/nymvisor/src/daemon/mod.rs:63: attempting to obtain daemon build information self.executable_path="./nym-node" +2024-10-23T17:45:06.795736Z  INFO tools/nymvisor/src/cli/init.rs:217: initialising the directory structure +2024-10-23T17:45:06.795827Z  INFO tools/nymvisor/src/cli/init.rs:250: setting up the genesis binary +2024-10-23T17:45:06.796090Z  INFO get_build_information: tools/nymvisor/src/daemon/mod.rs:63: attempting to obtain daemon build information self.executable_path="/home/strix/.nym/nymvisors/data/nym-node/genesis/bin/nym-node" diff --git a/documentation/docs/components/outputs/command-outputs/nymvisor-init-help.md b/documentation/docs/components/outputs/command-outputs/nymvisor-init-help.md new file mode 100644 index 0000000000..8e373fc42c --- /dev/null +++ b/documentation/docs/components/outputs/command-outputs/nymvisor-init-help.md @@ -0,0 +1,48 @@ +```sh +Initialise a nymvisor instance with persistent Config.toml file + +Usage: nymvisor init [OPTIONS] + +Arguments: + Path to the daemon's executable + +Options: + --id + ID specifies the human readable ID of this particular nymvisor instance. Can be overridden with $NYMVISOR_ID environmental variable + --upstream-base-upgrade-url + Sets the base url of the upstream source for obtaining upgrade information for the deaemon. It will be used fo constructing the full url, i.e. $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL/$DAEMON_NAME/upgrade-info.json Can be overridden with $NYMVISOR_UPSTREAM_BASE_UPGRADE_URL environmental variable + --upstream-polling-rate + Specifies the rate of polling the upstream url for upgrade information. default: 1h Can be overridden with $NYMVISOR_UPSTREAM_POLLING_RATE + --disable-nymvisor-logs + If enabled, this will disable `nymvisor` logs (but not the underlying process) Can be overridden with $NYMVISOR_DISABLE_LOGS environmental variable + --upgrade-data-directory + Set custom directory for upgrade data - binaries and upgrade plans. If not set, the global nymvisors' data directory will be used instead. Can be overridden with $NYMVISOR_UPGRADE_DATA_DIRECTORY environmental variable + --daemon-home + The location where the `nymvisor/` directory is kept that contains the auxiliary files associated with the underlying daemon, such as any backups or current version information. (e.g. $HOME/.nym/nym-api/my-nym-api, $HOME/.nym/mixnodes/my-mixnode, etc.). Can be overridden with $DAEMON_HOME environmental variable + --daemon-absolute-upstream-upgrade-url + Override url to the upstream source for upgrade plans for this daeamon. The Url has to point to an endpoint containing a valid [`UpgradeInfo`] json. Note: if set this takes precedence over `upstream_base_upgrade_url` Can be overridden with $DAEMON_ABSOLUTE_UPSTREAM_UPGRADE_URL environmental variable + --allow-download-upgrade-binaries + If set to true, this will enable auto-downloading of new binaries using the url provided in the `upgrade-info.json` Can be overridden with $DAEMON_ALLOW_BINARIES_DOWNLOAD environmental variable [possible values: true, false] + --enforce-download-checksum + If enabled nymvisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If disabled, nymvisor will not require a checksum to be provided, but still check the checksum if one is provided. Can be overridden with $DAEMON_ENFORCE_DOWNLOAD_CHECKSUM environmental variable [possible values: true, false] + --restart-daemon-after-upgrade + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (if disabled), nymvisor will stop running after an upgrade and will require the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. Can be overridden with $DAEMON_RESTART_AFTER_UPGRADE environmental variable [possible values: true, false] + --restart-daemon-on-failure + If enabled, nymvisor will restart the subprocess with the same command-line arguments and flags after it has crashed Can be overridden with $DAEMON_RESTART_ON_FAILURE environmental variable + --on-failure-daemon-restart-delay + If `restart_on_failure` is enabled, the following value defines the amount of time `nymvisor` shall wait before restarting the subprocess. Can be overridden with $DAEMON_FAILURE_RESTART_DELAY environmental variable + --max-daemon-startup-failures + Defines the maximum number of startup failures the subprocess can experience in a quick succession before no further restarts will be attempted and `nymvisor` will exit. Can be overridden with $DAEMON_MAX_STARTUP_FAILURES environmental variable + --startup-period-duration + Defines the length of time during which the subprocess is still considered to be in the startup phase when its failures are going to be considered in `max_startup_failures`. Can be overridden with $DAEMON_STARTUP_PERIOD_DURATION environmental variable + --daemon-shutdown-grace-period + Specifies the amount of time `nymvisor` is willing to wait for the subprocess to undergo graceful shutdown after receiving an interrupt (for either an upgrade or shutdown of the `nymvisor` itself) Once the time passes, a kill signal is going to be sent instead. Can be overridden with $DAEMON_SHUTDOWN_GRACE_PERIOD environmental variable + --daemon-backup-data-directory + Set custom backup directory for daemon data. If not set, the daemon's home directory will be used instead. Can be overridden with $DAEMON_BACKUP_DATA_DIRECTORY environmental variable + --unsafe-skip-backup + If enabled, `nymvisor` will perform upgrades directly without performing any backups. default: false Can be overridden with $DAEMON_UNSAFE_SKIP_BACKUP environmental variable + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` diff --git a/documentation/docs/components/outputs/csv2md-outputs/isp-sheet.md b/documentation/docs/components/outputs/csv2md-outputs/isp-sheet.md new file mode 100644 index 0000000000..b1d4cec752 --- /dev/null +++ b/documentation/docs/components/outputs/csv2md-outputs/isp-sheet.md @@ -0,0 +1,21 @@ +| **ISP** | **Locations** | **Public IPv6** | **Crypto Payments** | **Comments** | **Last Updated** | +|:------------------------------------------------|:---------------------------------------------------------------------------------------------------------|:-------------------------------------|:---------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| +| [AlexHost](https://alexhost.com) | Moldova, Bulgaria, Sweden, Netherlands | Yes, on by default | Yes | They allow TOR Bridges, Relays. Exit nodes are only allowed on dedicated servers (prices start from 26 EUR) | 07/2024 | +| [BitLaunch](https://bitlaunch.io) | Canada, USA, UK | No | Yes | Expensive. Digial Ocean through BitLanch has IPv6 | 05/2024 | +| [Cherry Servers](https://www.cherryservers.com) | Lithuania, Netherlands, USA, Singapore | No | Yes | Issued IP doesn’t match the location offered by the provider. | 05/2024 | +| [Flokinet](https://flokinet.is) | Netherlands, Iceland, Romania,France | Yes, needs a ticket and custom setup | yes, including XMR | Very slow customer support | 05/2024 | +| [HostSailor](https://hostsailor.com) | USA | Yes, based on ticket | Yes | The IPv6 setup needs custom research and is not documented | 05/2024 | +| [Hostiko](https://hostiko.com.ua) | Ukraine, Germany | Yes, on by default | Yes | Ukrainian provider. They allow Exit nodes on Germany boxes but limit the bandwidth, you also have to restrict certain ports like 25 and 587. Make sure you open a ticket. | 07/2024 | +| [Hostinger](https://hostinger.com) | France, Lithuania, India, USA, Brazil | Yes, out of the box | Yes | Crypto payments must be done per each server monthly or annually. | 05/2024 | +| [Hostslick](https://hostslick.com) | Netherlands, Germany | Yes, on by default | Yes | Good amount of bandwidth for the price. Make sure you open the ticket if you want to run Exit node | 07/2024 | +| [Incognet](https://incognet.io) | Netherlands and USA | Yes, on by default | Yes | They allow Tor exit nodes but you must adhere to their rules https://incognet.io/tor-exits | 07/2024 | +| [IsHosting](https://ishosting.com/en) | Brazil, Netherlands | Yes, based on ticket | Yes | Expensive | 05/2024 | +| [Linode](https://linode.com) | USA, Canada, Japan, India, Indonesia, Sweden, Netherlands, Germany, Brazil, France, UK, Australia, Italy | Yes out of the box | No, only through [BitLAunch](https://bitlaunch.io) | IPv6 sometimes need to be re-added in Networking tab, no reboot needed | 05/2024 | +| [LiteServer](https://liteserver.nl) | Netherlands | Yes, on by default | Yes | Very reliable Dutch provider. They do allow Relay nodes but for Exit nodes you need to contact them. Always check T&C https://liteserver.nl/legal | 07/2024 | +| [Mevspace](https://mevspace.com) | Poland | Yes, on by default | Yes | Flexible Polish providers with 3 DCs in Poland. They do allow Tor Exit nodes but you may need a dedicated server for this. Make sure you open a ticket to check. As of today's date, they have 48h for 1 EUR tariff | 07/2024 | +| [Misaka](https://www.misaka.io/) | South Africa | Yes, native support | No | Very Expensive | 05/2024 | +| [Njalla](https://nja.la) | Sweden | Yes | Yes | Privacy vandguards! The biggest VPS 45 is 3 cores only, but it works better than many “larger” servers on the market. | 05/2024 | +| [RDP](https://rdp.sh) | Netherlands, USA, Poland | Yes, on by default | Yes | German provider. Exit nodes are allowed, policy is here https://rdp.sh/docs/faq/tor ports 25,465,587 must be closed. Make sure you open a ticket before running an exit node. | 07/2024 | +| [TerraHost](https://terrahost.no) | Norway | Yes, on by default | Yes | Very reliable Norwegian provider. Only allow exit nodes on Dedicated servers subject to certain caveats (you must open a ticket). Always check T&C https://terrahost.no/avtalebetingelser | 07/2024 | +| [iHostArt](https://ihostart.com) | Romania | Yes, on by default | Yes | Super permissive provider. They do allow Tor Exit/Relay/Bridge. Pro-free speech etc. Recently, IPv6 geolocation was set to North Korea, so be aware. | 07/2024 | +| [vSys Host](https://vsys.host) | Ukraine, Netherlands, USA | Yes, on by default | Yes | Pretty permissive provider registered in Ukraine. Should allow Relay/Exit nodes but nothing in T&C, so better double check. | 07/2024 | diff --git a/documentation/docs/components/outputs/csv2md-outputs/variables.md b/documentation/docs/components/outputs/csv2md-outputs/variables.md new file mode 100644 index 0000000000..b152bd4a2b --- /dev/null +++ b/documentation/docs/components/outputs/csv2md-outputs/variables.md @@ -0,0 +1,23 @@ +| **Flag (Option)** | **Variable** | **Description** | **Syntax example** | +|:-----------------------------------------------|:------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------| +| `-w` or `--write-changes` | *none* | Specify whether to write new changes - the values of other flags in the given command - to the config file | `--write-changes` | +| `--accept-operator-terms-and-conditions` | *none* | A flag added explicitly to `nym-node run` command every time, showing that the operator agreed with [T&Cs](#terms--conditions) | `--accept-operator-terms-and-conditions` | +| `--announce-wss-port` | `` | Port listening to Web Secure Socket, default and recommended `9001` | `9001` | +| *not a flag* | `` | Replace with all flags used to run the binary with a given command | `--id alice_super_node –accept-operator-terms-and-conditions` | +| *not a flag* | ` ` | A name of a binary | `nym-node` | +| `--expose-system-hardware` | `` | Specify whether basic system hardware information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-hardware false` | +| `--expose-system-info` | `` | Specify whether basic system information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-info false` | +| `--hostname` | `` | Your registered DNS domain, asigned to the VPS with `nym-node`. Use without prefix like `http://` or `https://` | `exit-gateway1.squad.nsl` | +| `--http-bind-address` | `` | Socket address this node will use for binding its http API - mandatory! Must be on port `8080`! | `--http-bind-address 0.0.0.0:8080` | +| `--id` | `` | A local only `nym-node` identifier, specified by flag `--id`. Not mandatory as it defaults to `default-nym-node` if not specified. | `--id alice_super_node` | +| *not a flag* | `` | Node public identity key, exposed on the network | `GQvHcg61viyN9brWn1hficjD66Q9TorsLN2CMGJewVfo` | +| `--landing-page-assets-path` | `` | A sub-directory located at `/var/www/` containing html configuration files | `/var/www/exit-gateway1.squad.nsl` | +| `--location` | `` | Location of your node. Formats like 'Jamaica', or two-letter alpha2 (e.g. 'JM'), three-letter alpha3 (e.g. 'JAM') or three-digit numeric-3 (e.g. '388') can be provided. | `--location JAM` | +| `--mixnet-bind-address` | `` | Address to bind to for listening for mixnet packets - mandatory! Must be on port `1789`! | `--mixnet-bind-address 0.0.0.0:1789` | +| `--mode` | `` | A functionality of your `nym-node` in the mixnet - mandatory! Chose from `entry-gateway`, `mixnode` or `exit-gateway` | `--mode exit-gateway` | +| *not a flag* | `` | Version of validator binaries | `v0.43.0` | +| *not a flag* | `` | Specify a full path to the given file, directory or binary behind this variable | `/root/src/nym/target/release/` | +| `--public-ips` | `` | IPv4 of the `nym-node` server - mandatory! Use this address as a `host` value for bonding.Use this address as a `host` value for bonding. | `--public-ips "$(curl -4 https://ifconfig.me)"` | +| *not a flag* | `` | Any text you want to show on the landing page | Welcome to Nym Node, operator contact is example@email.me | +| `--wireguard-enabled` | `` | Specifies whether the wireguard service is enabled, possible values: `true` or `false` - `true` is recommended | `--wireguard-enabled true` | +| `--wireguard-private-ip` | `` | Private IP address of the wireguard gateway. This mandatory field is set to a correct default: `10.1.0.1`, operators upgrading from older versions must overwrite it. | `--wireguard-private-ip 10.1.0.1` | diff --git a/documentation/docs/components/outputs/nyx-outputs/nyx-percent-stake.md b/documentation/docs/components/outputs/nyx-outputs/nyx-percent-stake.md new file mode 100644 index 0000000000..39bbb86bce --- /dev/null +++ b/documentation/docs/components/outputs/nyx-outputs/nyx-percent-stake.md @@ -0,0 +1 @@ +0.64% diff --git a/documentation/docs/components/outputs/nyx-outputs/nyx-total-stake.md b/documentation/docs/components/outputs/nyx-outputs/nyx-total-stake.md new file mode 100644 index 0000000000..e36dbca0e2 --- /dev/null +++ b/documentation/docs/components/outputs/nyx-outputs/nyx-total-stake.md @@ -0,0 +1 @@ +44.811 diff --git a/documentation/docs/components/snippets-general/time-now.mdx b/documentation/docs/components/snippets-general/time-now.mdx new file mode 100644 index 0000000000..11d54a1599 --- /dev/null +++ b/documentation/docs/components/snippets-general/time-now.mdx @@ -0,0 +1,9 @@ + +import TimeNow from 'components/outputs/api-scraping-outputs/time-now.md'; +import { Callout } from 'nextra/components'; + + + +The data on this page were last time updated on . + + diff --git a/documentation/docs/components/snippets-general/varible-info-snippet.mdx b/documentation/docs/components/snippets-general/varible-info-snippet.mdx new file mode 100644 index 0000000000..0886076153 --- /dev/null +++ b/documentation/docs/components/snippets-general/varible-info-snippet.mdx @@ -0,0 +1,6 @@ +import { Callout } from 'nextra/components' + + +Our documentation often refer to syntax annotated in `<>` brackets. We use this expression for variables that are unique to each user (like path, local moniker, versions etcetra). +Any syntax in `<>` brackets needs to be substituted with your correct name or version, without the `<>` brackets. If you are unsure, please check our table of essential [parameters and variables](https://nymtech.net/docs/operators/variables.html). + diff --git a/documentation/docs/components/time-now.tsx b/documentation/docs/components/time-now.tsx new file mode 100644 index 0000000000..01f94797d5 --- /dev/null +++ b/documentation/docs/components/time-now.tsx @@ -0,0 +1,12 @@ + +import { Callout } from 'nextra/components'; +import TimeOutput from 'components/snippets-general/time-now.mdx'; + +export const TimeNow = () => { + +return ( +
+ +
+ ) +} diff --git a/sdk/typescript/docs/components/traffic.tsx b/documentation/docs/components/traffic.tsx similarity index 100% rename from sdk/typescript/docs/components/traffic.tsx rename to documentation/docs/components/traffic.tsx diff --git a/documentation/docs/components/variable-info.tsx b/documentation/docs/components/variable-info.tsx new file mode 100644 index 0000000000..df3e4cc078 --- /dev/null +++ b/documentation/docs/components/variable-info.tsx @@ -0,0 +1,10 @@ +import VariableInfo from './snippets-general/varible-info-snippet.mdx'; + +export const VarInfo = () => { + +return ( +
+ +
+ ) +} diff --git a/sdk/typescript/docs/components/wallet/connect.tsx b/documentation/docs/components/wallet/connect.tsx similarity index 100% rename from sdk/typescript/docs/components/wallet/connect.tsx rename to documentation/docs/components/wallet/connect.tsx diff --git a/sdk/typescript/docs/components/wallet/delegations.tsx b/documentation/docs/components/wallet/delegations.tsx similarity index 100% rename from sdk/typescript/docs/components/wallet/delegations.tsx rename to documentation/docs/components/wallet/delegations.tsx diff --git a/sdk/typescript/docs/components/wallet/sendTokens.tsx b/documentation/docs/components/wallet/sendTokens.tsx similarity index 100% rename from sdk/typescript/docs/components/wallet/sendTokens.tsx rename to documentation/docs/components/wallet/sendTokens.tsx diff --git a/sdk/typescript/docs/components/wallet/utils/wallet.context.tsx b/documentation/docs/components/wallet/utils/wallet.context.tsx similarity index 100% rename from sdk/typescript/docs/components/wallet/utils/wallet.context.tsx rename to documentation/docs/components/wallet/utils/wallet.context.tsx diff --git a/sdk/typescript/docs/components/wallet/utils/wallet.methods.ts b/documentation/docs/components/wallet/utils/wallet.methods.ts similarity index 100% rename from sdk/typescript/docs/components/wallet/utils/wallet.methods.ts rename to documentation/docs/components/wallet/utils/wallet.methods.ts diff --git a/documentation/operators/src/data/isp-sheet.csv b/documentation/docs/data/csv/isp-sheet.csv similarity index 100% rename from documentation/operators/src/data/isp-sheet.csv rename to documentation/docs/data/csv/isp-sheet.csv diff --git a/documentation/docs/data/csv/variables.csv b/documentation/docs/data/csv/variables.csv new file mode 100644 index 0000000000..8abcf6f8f7 --- /dev/null +++ b/documentation/docs/data/csv/variables.csv @@ -0,0 +1,22 @@ +**Flag (Option)** ,**Variable** ,**Description** ,**Syntax example** +`--mode` ,`` ,"A functionality of your `nym-node` in the mixnet - mandatory! Chose from `entry-gateway`, `mixnode` or `exit-gateway` ",`--mode exit-gateway` +`--id` ,`` ,"A local only `nym-node` identifier, specified by flag `--id`. Not mandatory as it defaults to `default-nym-node` if not specified. ",`--id alice_super_node` +`-w` or `--write-changes` ,*none* ,Specify whether to write new changes - the values of other flags in the given command - to the config file ,`--write-changes` +`--accept-operator-terms-and-conditions` ,*none* ,"A flag added explicitly to `nym-node run` command every time, showing that the operator agreed with [T&Cs](#terms--conditions) ",`--accept-operator-terms-and-conditions` +`--public-ips` ,`` ,IPv4 of the `nym-node` server - mandatory! Use this address as a `host` value for bonding.Use this address as a `host` value for bonding. ,"`--public-ips ""$(curl -4 https://ifconfig.me)""` " +`--mixnet-bind-address` ,`` ,Address to bind to for listening for mixnet packets - mandatory! Must be on port `1789`! ,`--mixnet-bind-address 0.0.0.0:1789` +`--http-bind-address` ,`` ,Socket address this node will use for binding its http API - mandatory! Must be on port `8080`! ,`--http-bind-address 0.0.0.0:8080` +`--hostname` ,`` ,"Your registered DNS domain, asigned to the VPS with `nym-node`. Use without prefix like `http://` or `https://` ",`exit-gateway1.squad.nsl` +`--location` ,`` ,"Location of your node. Formats like 'Jamaica', or two-letter alpha2 (e.g. 'JM'), three-letter alpha3 (e.g. 'JAM') or three-digit numeric-3 (e.g. '388') can be provided. ",`--location JAM` +`--wireguard-private-ip` ,`` ,"Private IP address of the wireguard gateway. This mandatory field is set to a correct default: `10.1.0.1`, operators upgrading from older versions must overwrite it. ",`--wireguard-private-ip 10.1.0.1` +`--wireguard-enabled` ,`` ,"Specifies whether the wireguard service is enabled, possible values: `true` or `false` - `true` is recommended ",`--wireguard-enabled true` +`--expose-system-info` ,`` ,"Specify whether basic system information should be exposed. default: `true`, possible values: `true` or `false` ",`--expose-system-info false` +`--expose-system-hardware` ,`` ,"Specify whether basic system hardware information should be exposed. default: `true`, possible values: `true` or `false` ",`--expose-system-hardware false` +*not a flag* ,`` ,"Specify a full path to the given file, directory or binary behind this variable ",`/root/src/nym/target/release/` +`--announce-wss-port`,``,"Port listening to Web Secure Socket, default and recommended `9001`",`9001` +`--landing-page-assets-path`,``,A sub-directory located at `/var/www/` containing html configuration files,`/var/www/exit-gateway1.squad.nsl` +*not a flag* ,` `,A name of a binary,`nym-node` +*not a flag* ,``,Replace with all flags used to run the binary with a given command,`--id alice_super_node –accept-operator-terms-and-conditions` +*not a flag* ,``,Any text you want to show on the landing page ,"Welcome to Nym Node, operator contact is example@email.me" +*not a flag* ,``,Version of validator binaries,`v0.43.0` +*not a flag* ,``,"Node public identity key, exposed on the network",`GQvHcg61viyN9brWn1hficjD66Q9TorsLN2CMGJewVfo` diff --git a/documentation/docs/data/csv/variables.md b/documentation/docs/data/csv/variables.md new file mode 100644 index 0000000000..0266ce7ce2 --- /dev/null +++ b/documentation/docs/data/csv/variables.md @@ -0,0 +1,16 @@ +| Flag (Option) | Variable | Description | Syntax example | +| :-- | :--- | :--- | :--- | +| `--mode` | `` | A functionality of your `nym-node` in the mixnet - mandatory! Chose from `entry-gateway`, `mixnode` or `exit-gateway` | `--mode exit-gateway` | +| `--id` | `` | A local only `nym-node` identifier, specified by flag `--id`. Not mandatory as it defaults to `default-nym-node` if not specified. | `--id alice_super_node` | +| `-w` or `--write-changes` | *none* | Specify whether to write new changes - the values of other flags in the given command - to the config file | `--write-changes` | +| `--accept-operator-terms-and-conditions` | *none* | A flag added explicitly to `nym-node run` command every time, showing that the operator agreed with [T&Cs](#terms--conditions) | `--accept-operator-terms-and-conditions` | +| `--public-ips` | `` | IPv4 of the `nym-node` server - mandatory! Use this address as a `host` value for bonding.Use this address as a `host` value for bonding. | `--public-ips "$(curl -4 https://ifconfig.me)"` | +| `--mixnet-bind-address` | `` | Address to bind to for listening for mixnet packets - mandatory! Must be on port `1789`! | `--mixnet-bind-address 0.0.0.0:1789` | +| `--http-bind-address` | `` | Socket address this node will use for binding its http API - mandatory! Must be on port `8080`! | `--http-bind-address 0.0.0.0:8080` | +| `--hostname` | `` | Your registered DNS domain, asigned to the VPS with `nym-node`. Use without prefix like `http://` or `https://` | `exit-gateway1.squad.nsl` | +| `--location` | `` | Loacation of your node. Formats like 'Jamaica', or two-letter alpha2 (e.g. 'JM'), three-letter alpha3 (e.g. 'JAM') or three-digit numeric-3 (e.g. '388') can be provided. | `--location JAM` | +| `--wireguard-private-ip` | `` | Private IP address of the wireguard gateway. This mandatory field is set to a correct default: `10.1.0.1`, operators upgrading from older versions must overwrite it. | `--wireguard-private-ip 10.1.0.1` | +| `--wireguard-enabled` | `` | Specifies whether the wireguard service is enabled, possible values: `true` or `false` - `true` is recommended | `--wireguard-enabled true` | +| `--expose-system-info` | `` | Specify whether basic system information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-info false` | +| `--expose-system-hardware` | `` | Specify whether basic system hardware information should be exposed. default: `true`, possible values: `true` or `false` | `--expose-system-hardware false` | +| *not a flag* | `` | Specify a full path to the given file, directory or binary behind this variable | `/root/src/nym/target/release/` | diff --git a/documentation/docs/diagrams/mixnet-traffic-flow.md b/documentation/docs/diagrams/mixnet-traffic-flow.md deleted file mode 100644 index 235e047fc0..0000000000 --- a/documentation/docs/diagrams/mixnet-traffic-flow.md +++ /dev/null @@ -1,35 +0,0 @@ - - - - +----------+ +----------+ +----------+ - | Mix Node |<-----------> | Mix Node |<----------->| Mix Node | - | Layer 1 | | Layer 2 | | Layer 3 | - +----------+ +----------+ +----------+ - ^ ^ - | | - | | - v v - +--------------+ +-------------------------+ - | Your gateway | | Service / app's gateway | - +--------------+ +-------------------------+ - ^ ^ - | | - | | - | | - | | - v v - +-------------------+ +-------------------+ - | +---------------+ | | +---------------+ | - | | Nym client | | | | Nym Client | | - | +---------------+ | | +---------------+ | - | ^ | | ^ | - | | | | | | - | | | | | | - | | | | | | - | v | | v | - | +---------------+ | | +---------------+ | - | | Your app code | | | | Service Code | | - | +---------------+ | | +---------------+ | - +-------------------+ +-------------------+ - Your Local Machine Service Provider Machine - \ No newline at end of file diff --git a/documentation/docs/diagrams/package-retransmission.md b/documentation/docs/diagrams/package-retransmission.md deleted file mode 100644 index 7ee9a320de..0000000000 --- a/documentation/docs/diagrams/package-retransmission.md +++ /dev/null @@ -1,14 +0,0 @@ - - +-------------------+ +-------------------+ - | +---------------+ | | | Packet lost in transmission - no ack recieved! - | | Nym client | | | |-------------X - | +-------^-------+ |Send 100 packets | | - | | |----------------->| Gateway your | Resend packet +------------------+ etc... - | | | | client is |------------------>| |------------------> - | | | | connected to | | Mix node layer 1 | - | v | Send 100 acks | |<------------------| | - | +---------------+ |<-----------------| | Send ack +------------------+ - | | Your app code | | | | - | +---------------+ | | | - +-------------------+ +-------------------+ - Your Local Machine diff --git a/documentation/docs/diagrams/socks-client-flow.md b/documentation/docs/diagrams/socks-client-flow.md deleted file mode 100644 index 952061daee..0000000000 --- a/documentation/docs/diagrams/socks-client-flow.md +++ /dev/null @@ -1,43 +0,0 @@ - External Systems: - - +--------------------+ - |------>| Monero blockchain | - | +--------------------+ - | +--------------------+ - |------>| Email server | - | +--------------------+ - | +--------------------+ - |------>| RPC endpoint | - | +--------------------+ - | +--------------------+ - |------>| Website | - | +--------------------+ - | +--------------------+ - +----------------------------------+ |------>| etc... | - | Mixnet: | | +--------------------+ - | * Gateway your client is | | - | connected to | +--------------------+ | - | * Mix nodes 1 -> 3 |<---------->| Network requester |<----+ - | * Gateway that network | +--------------------+ - | requester is connected to | - +----------------------------------+ - ^ - | - | - | - | - v - +-------------------+ - | +---------------+ | - | | Nym client | | - | +---------------+ | - | ^ | - | | | - | | | - | | | - | v | - | +---------------+ | - | | Your app code | | - | +---------------+ | - +-------------------+ - Your Local Machine \ No newline at end of file diff --git a/documentation/docs/diagrams/templates/local-machine.md b/documentation/docs/diagrams/templates/local-machine.md deleted file mode 100644 index fa63a5cbff..0000000000 --- a/documentation/docs/diagrams/templates/local-machine.md +++ /dev/null @@ -1,14 +0,0 @@ -+-------------------+ -| +---------------+ | -| | Nym client | | -| +---------------+ | -| ^ | -| | | -| | | -| | | -| v | -| +---------------+ | -| | Your app code | | -| +---------------+ | -+-------------------+ - Your Local Machine \ No newline at end of file diff --git a/documentation/docs/diagrams/templates/service-machine.md b/documentation/docs/diagrams/templates/service-machine.md deleted file mode 100644 index f9acb9d1e9..0000000000 --- a/documentation/docs/diagrams/templates/service-machine.md +++ /dev/null @@ -1,15 +0,0 @@ -+-------------------+ -| +---------------+ | -| | Nym client | | -| +---------------+ | -| ^ | -| | | -| | | -| | | -| v | -| +---------------+ | -| | Service code | | -| +---------------+ | -+-------------------+ - Service Machine - \ No newline at end of file diff --git a/documentation/docs/last-changed.css b/documentation/docs/last-changed.css deleted file mode 100644 index 0c4228de32..0000000000 --- a/documentation/docs/last-changed.css +++ /dev/null @@ -1,6 +0,0 @@ -footer { - font-size: 0.8em; - text-align: center; - border-top: 1px solid black; - padding: 5px 0; - } \ No newline at end of file diff --git a/sdk/typescript/docs/next-env.d.ts b/documentation/docs/next-env.d.ts similarity index 100% rename from sdk/typescript/docs/next-env.d.ts rename to documentation/docs/next-env.d.ts diff --git a/documentation/docs/next.config.js b/documentation/docs/next.config.js new file mode 100644 index 0000000000..b3c23966a7 --- /dev/null +++ b/documentation/docs/next.config.js @@ -0,0 +1,585 @@ +// const path = require('path'); +// const CopyPlugin = require('copy-webpack-plugin'); + +const withNextra = require("nextra")({ + theme: "nextra-theme-docs", + themeConfig: "./theme.config.tsx", +}); + +const nextra = withNextra(); +nextra.webpack = (config, options) => { + // generate Nextra's webpack config + const newConfig = withNextra().webpack(config, options); + + newConfig.module.rules.push({ + test: /\.txt$/i, + use: "raw-loader", + }); + + // TODO: figure out how to properly bundle WASM and workers with Nextra + // newConfig.plugins.push( + // new CopyPlugin({ + // patterns: [ + // { + // from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*.wasm'), + // to: '[name][ext]', + // context: path.resolve(__dirname, 'out'), + // }, + // { + // from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*worker*.js'), + // to: '[name][ext]', + // context: path.resolve(__dirname, 'out'), + // }, + // ], + // }), + // ); + + return newConfig; +}; + +const config = { + ...nextra, + basePath: "/docs", + async redirects() { + return [ + // network docs + { + source: "/", + destination: "/docs", + basePath: false, + permanent: true, + }, + { + source: "/docs/architecture/nym-vs-others.html", + destination: "/network/architecture/nym-vs-others", + permanent: true, + }, + { + source: "/docs/architecture/traffic-flow.html", + destination: "/network/traffic", + permanent: true, + }, + { + source: "/docs/architecture/addressing-system.html", + destination: "/network/traffic/addressing-system", + permanent: true, + }, + { + source: "/docs/binaries/pre-built-binaries.html", + destination: "/developers/binaries#building-from-source", + permanent: true, + }, + { + source: "/docs/binaries/init-and-config.html", + destination: "/developers/binaries#building-from-source", + permanent: true, + }, + { + source: "/docs/binaries/building-nym.html", + destination: "/developers/binaries#building-from-source", + permanent: true, + }, + { + source: "/docs/nodes/overview.html ", + destination: "/network/architecture/mixnet/nodes", + permanent: true, + }, + { + source: "/docs/wallet/desktop-wallet.html", + destination: + "https://github.com/nymtech/nym/tree/master/nym-wallet#installation-prerequisites---linux--mac", + permanent: true, + }, + { + source: "/docs/wallet/cli-wallet.html", + destination: "/developers/chain/cli-wallet", + permanent: true, + }, + { + source: "/docs/explorers/mixnet-explorer.html", + destination: + "https://github.com/nymtech/nym/tree/master/explorer#nym-network-explorer", + permanent: true, + }, + { + source: "/docs/nyx/interacting-with-chain.html", + destination: "/developers/chain", + permanent: true, + }, + { + source: "/docs/nyx/smart-contracts.html", + destination: "/network/architecture/nyx/smart-contracts", + permanent: true, + }, + { + source: "/docs/nyx/mixnet-contract.html", + destination: + "/network/architecture/nyx/smart-contracts/mixnet-contract", + permanent: true, + }, + { + source: "/docs/nyx/vesting-contract.html", + destination: + "/network/architecture/nyx/smart-contracts/vesting-contract", + permanent: true, + }, + { + source: "/docs/nyx/rpc-node.html", + destination: "/developers/chain/rpc-node", + permanent: true, + }, + { + source: "/docs/nyx/ledger-live.html", + destination: "/developers/chain/ledger-live", + permanent: true, + }, + { + source: "/docs/coconut.html", + destination: "/network/cryptography/zk-nym", + permanent: true, + }, + { + source: "/docs/nyx/bandwidth-credentials.html", + destination: "/network/cryptography/zk-nym", + permanent: true, + }, + { + source: "/docs/tools/nym-cli.html", + destination: "/developers/tools/nym-cli", + permanent: true, + }, + { + source: "/docs/coc.html", + destination: "/network/coc", + permanent: true, + }, + { + source: "/docs/licensing.html", + destination: "/network/licensing", + permanent: true, + }, + // dev docs + { + source: "/developers/clients-overview.html", + destination: "/developers/clients", + permanent: true, + }, + { + source: "/developers/sdk/rust/rust.html", + destination: "/developers/rust", + permanent: true, + }, + { + source: "/developers/sdk/rust/message-types.html", + destination: "/developers/rust/mixnet/message-types", + permanent: true, + }, + { + source: "/developers/sdk/rust/message-helpers.html", + destination: "/developers/rust/mixnet/message-helpers", + permanent: true, + }, + { + source: "/developers/sdk/rust/troubleshooting.html", + destination: "/developers/rust/mixnet/troubleshooting", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples.html", + destination: "/developers/rust/mixnet/examples", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/simple.html", + destination: "/developers/rust/mixnet/examples/simple", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/keys.html", + destination: "/developers/sdk/rust/examples/keys.html", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/storage.html", + destination: + "/developers/rust/mixnet/examples/builders/builder-with-storage", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/surbs.html", + destination: "/developers/rust/mixnet/examples/surbs", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/custom-network.html", + destination: "/developers/rust/mixnet/examples/custom-topology", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/socks.html", + destination: "/developers/rust/mixnet/examples/socks", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/split-send.html", + destination: "/developers/rust/mixnet/examples/split-send", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/credential.html", + destination: "/developers/rust/mixnet", + permanent: true, + }, + { + source: "/developers/sdk/rust/examples/cargo.html", + destination: "/developers/rust/importing", + permanent: true, + }, + { + source: "/developers/sdk/typescript.html", + destination: "/developers/typescript", + permanent: true, + }, + { + source: "/developers/binaries/pre-built-binaries.html", + destination: "/developers/binaries#pre-built-binaries", + permanent: true, + }, + { + source: "/developers/binaries/building-nym.html", + destination: "/developers/binaries", + permanent: true, + }, + { + source: "/developers/clients/websocket-client.html", + destination: "/developers/clients/websocket", + permanent: true, + }, + { + source: "/developers/clients/websocket/setup.html", + destination: "/developers/clients/websocket/setup", + permanent: true, + }, + { + source: "/developers/clients/websocket/config.html", + destination: "/developers/clients/websocket/config", + permanent: true, + }, + { + source: "/developers/clients/websocket/usage.html", + destination: "/developers/clients/websocket/usage", + permanent: true, + }, + { + source: "/developers/clients/websocket/examples.html", + destination: "/developers/clients/websocket/examples", + permanent: true, + }, + { + source: "/developers/clients/socks5-client.html", + destination: "/developers/clients/socks5", + permanent: true, + }, + { + source: "/developers/clients/socks5/setup.html", + destination: "/developers/clients/socks5#client-setup", + permanent: true, + }, + { + source: "/developers/clients/socks5/usage.html", + destination: "/developers/clients/socks5#using-your-socks5-client", + permanent: true, + }, + { + source: "/developers/clients/webassembly-client.html", + destination: "/developers/clients/webassembly-client", + permanent: true, + }, + { + source: "/developers/tutorials/coming-soon.html", + destination: "/developers/rust#", + permanent: true, + }, + { + source: "/developers/integrations/integration-options.html", + destination: "/developers/integrations", + permanent: true, + }, + { + source: "/developers/faq/integrations-faq.html", + destination: "/developers/integrations", + permanent: true, + }, + { + source: "/developers/coc.html", + destination: "/developers/coc", + permanent: true, + }, + { + source: "/developers/licensing.html", + destination: "/developers/licensing", + permanent: true, + }, + { + source: "/developers/nymvpn/intro.html", + destination: "/developers/archive/nymvpn", + permanent: true, + }, + { + source: "/developers/nymvpn/cli.html", + destination: "/developers/nymvpn/cli", + permanent: true, + }, + { + source: "/developers/archive/nym-connect.html", + destination: "/developers/archive/nym-connect", + permanent: true, + }, + { + source: "/developers/examples/custom-services.html", + destination: "/developers/rust/mixnet/other-examples#services", + permanent: true, + }, + { + source: "/developers/examples/browser-only.html", + destination: "/developers/rust/mixnet/other-examples#browser-only", + permanent: true, + }, + { + source: "/developers/examples/using-nrs.html", + destination: "/developers/rust/mixnet/other-examples", + permanent: true, + }, + { + source: "/developers/examples/monorepo-examples.html", + destination: "/developers/rust/mixnet/other-examples", + permanent: true, + }, + { + source: "/developers/integrations", + destination: "/developers/integrations/payment-integration.html", + permanent: true, + }, + // { + // source: "", + // destination: "", + // permanent: true, + // }, + // operators: + // specific urls that have changed + { + source: "/operators/nodes/wallet-preparation.html", + destination: "/operators/nodes/preliminary-steps/wallet-preparation", + permanent: true, + }, + { + source: "/operators/nodes/vps-setup.html", + destination: "/operators/nodes/preliminary-steps/vps-setup", + permanent: true, + }, + { + source: "/operators/nodes/proxy-configuration.html", + destination: + "/operators/nodes/nym-node/configuration/proxy-configuration", + permanent: true, + }, + { + source: "/operators/nodes/bonding.html", + destination: "/operators/nodes/nym-node/bonding", + permanent: true, + }, + { + source: "/operators/nodes/nym-api.html", + destination: "/operators/nodes/validator-setup/nym-api", + permanent: true, + }, + { + source: "/operators/nodes/nyx-configuration.html", + destination: "/operators/nodes/validator-setup/nyx-configuration", + permanent: true, + }, + { + source: "/operators/nodes/manual-upgrade.html", + destination: "/operators/nodes/maintenance/manual-upgrade", + permanent: true, + }, + { + source: "/operators/nodes/nymvisor-upgrade.html", + destination: "/operators/nodes/maintenance/nymvisor-upgrade", + permanent: true, + }, + { + source: "/operators/testing/performance.html", + destination: "/operators/nodes/performance-and-testing", + permanent: true, + }, + { + source: "/operators/testing/gateway-probe.html", + destination: "/operators/nodes/performance-and-testing/gateway-probe", + permanent: true, + }, + { + source: "/operators/testing/node-api-check.html", + destination: "/operators/nodes/performance-and-testing/node-api-check", + permanent: true, + }, + { + source: "/operators/testing/prometheus-grafana.html", + destination: + "/operators/nodes/performance-and-testing/prometheus-grafana", + permanent: true, + }, + { + source: "/operators/testing/explorenym-scripts.html", + destination: + "/operators/nodes/performance-and-testing/prometheus-grafana/explorenym-scripts", + permanent: true, + }, + { + source: "/operators/legal/community-counsel.html", + destination: "/operators/community-counsel", + permanent: true, + }, + { + source: "/operators/legal/exit-gateway.html", + destination: "/operators/community-counsel/exit-gateway", + permanent: true, + }, + { + source: "/operators/legal/isp-list.html", + destination: "/operators/community-counsel/isp-list", + permanent: true, + }, + { + source: "/operators/legal/jurisdictions.html", + destination: "/operators/community-counsel/jurisdictions", + permanent: true, + }, + { + source: "/operators/legal/swiss.html", + destination: "/operators/community-counsel/jurisdictions/swiss", + permanent: true, + }, + { + source: "/operators/legal/united-states.html", + destination: "/operators/community-counsel/jurisdictions/united-states", + permanent: true, + }, + { + source: "/operators/legal/landing-pages.html", + destination: "/operators/community-counsel/landing-pages", + permanent: true, + }, + { + source: "/operators/legal/add-content.html", + destination: "/operators/community-counsel/add-content", + permanent: true, + }, + // since the filepaths are mostly the same, we otherwise just match on old URLs that end with .html + { + source: "/:path*.html", + destination: "/:path*", + permanent: false, + }, + + // TODO these need to go in the config of the existing deployed ts sdk docs to redirect from there + // these assume source basePath = sdk.nymtech.net + // { + // source: "/intro", + // destination: "https://www./developers/typescript", + // permanent: true, + // }, + // { + // source: "/overview", + // destination: "https://www./developers/typescript/overview", + // permanent: true, + // }, + // { + // source: "/integrations", + // destination: "https://www./developers/integrations", + // permanent: true, + // }, + // { + // source: "/installation", + // destination: "https://www./developers/typescript/installation", + // permanent: true, + // }, + // { + // source: "/start", + // destination: "https://www./developers/typescript/start", + // permanent: true, + // }, + // { + // source: "/examples/mix-fetch", + // destination: "https://www.developers/typescript/examples/mix-fetch", + // permanent: true, + // }, + // { + // source: "/examples/mixnet", + // destination: "https://www.//developers/typescript/examples/mixnet", + // permanent: true, + // }, + // { + // source: "/examples/nym-smart-contracts", + // destination: "https://www./developers/typescript/examples/nym-smart-contracts", + // permanent: true, + // }, + // { + // source: "/examples/cosmos-kit", + // destination: "https://www.//developers/typescript/examples/cosmos-kit", + // permanent: true, + // }, + // { + // source: "/playground/mixfetch", + // destination: "https://www./developers/typescript/playground/mixfetch", + // permanent: true, + // }, + // { + // source: "/playground/traffic", + // destination: "https://www./developers/typescript/playground/traffic", + // permanent: true, + // }, + // { + // source: "/playground/mixnodes", + // destination: "https://www./developers/typescript/playground/mixnodes", + // permanent: true, + // }, + // { + // source: "/playground/wallet", + // destination: "https://www./typescript/playground/wallet", + // permanent: true, + // }, + // { + // source: "/playground/cosmos-kit", + // destination: "https://www./developers/typescript/playground/cosmos-kit", + // permanent: true, + // }, + // { + // source: "/bundling/bundling", + // destination: "https://www./developers/typescript/bundling/bundling", + // permanent: true, + // }, + // { + // source: "/bundling/esbuild", + // destination: "https://www./developers/typescript/bundling/esbuild", + // permanent: true, + // }, + // { + // source: "/bundling/webpack", + // destination: "https://www./developers/typescript/bundling/webpack", + // permanent: true, + // }, + // { + // source: "/FAQ/general", + // destination: "https://www./developers/typescript/FAQ", + // permanent: true, + // }, + ]; + }, + images: { + unoptimized: true, + }, + transpilePackages: ["@nymproject/contract-clients"], +}; + +module.exports = config; diff --git a/sdk/typescript/docs/package.json b/documentation/docs/package.json similarity index 71% rename from sdk/typescript/docs/package.json rename to documentation/docs/package.json index abdf67048a..938ed95093 100644 --- a/sdk/typescript/docs/package.json +++ b/documentation/docs/package.json @@ -1,17 +1,22 @@ { - "name": "@nymproject/ts-sdk-docs", - "version": "1.3.0-rc.0", - "description": "Nym Typescript SDK Docs", + "name": "Nym Docs", + "version": "2.0", + "description": "Nym documentation for developers and node operators", "license": "Apache-2.0", "author": "Nym Technologies SA", "scripts": { + "generate:commands": "../scripts/next-scripts/autodoc.sh", + "generate:tables": "../scripts/next-scripts/python-prebuild.sh", + "predev": "../scripts/next-scripts/python-prebuild.sh", "build": "next build", - "dev": "next dev", + "dev": " next dev", "lint": "next lint", "lint:fix": "next lint --fix", "start": "next start" }, "dependencies": { + "@coreui/coreui": "^5.1.2", + "@coreui/react": "^5.4.0", "@cosmjs/amino": "^0.32.2", "@cosmjs/cosmwasm-launchpad": "^0.25.6", "@cosmjs/cosmwasm-stargate": "^0.32.2", @@ -29,14 +34,18 @@ "@mui/icons-material": "^5.14.9", "@mui/lab": "^5.0.0-alpha.145", "@mui/material": "^5.14.8", + "@nextui-org/accordion": "^2.0.40", + "@nextui-org/react": "^2.4.8", "@nymproject/contract-clients": ">=1.2.4-rc.2 || ^1", "@nymproject/mix-fetch-full-fat": ">=1.2.4-rc.2 || ^1", "@nymproject/sdk-full-fat": ">=1.2.4-rc.2 || ^1", + "@types/mdx": "^2.0.13", "chain-registry": "^1.19.0", "cosmjs-types": "^0.9.0", + "lucide-react": "^0.438.0", "next": "^13.4.19", - "nextra": "latest", - "nextra-theme-docs": "latest", + "nextra": "2", + "nextra-theme-docs": "2", "react": "^18.2.0", "react-dom": "^18.2.0", "save": "^2.9.0", diff --git a/sdk/typescript/docs/pages/_app.tsx b/documentation/docs/pages/_app.tsx similarity index 100% rename from sdk/typescript/docs/pages/_app.tsx rename to documentation/docs/pages/_app.tsx diff --git a/documentation/docs/pages/_meta.json b/documentation/docs/pages/_meta.json new file mode 100644 index 0000000000..ba7bdce511 --- /dev/null +++ b/documentation/docs/pages/_meta.json @@ -0,0 +1,31 @@ +{ + "index": { + "display": "hidden" + }, + "network": { + "title": "Network", + "type": "page" + }, + "developers": { + "title": "Developers", + "type": "menu", + "items": { + "developers": { + "title": "Developer Overview", + "href": "/developers/" + }, + "rust": { + "title": "Rust SDK", + "href": "/developers/rust" + }, + "typescript": { + "title": "Typescript SDK", + "href": "/developers/typescript" + } + } + }, + "operators": { + "title": "Operators", + "type": "page" + } +} diff --git a/documentation/docs/pages/developers/_meta.json b/documentation/docs/pages/developers/_meta.json new file mode 100644 index 0000000000..d0103c08a5 --- /dev/null +++ b/documentation/docs/pages/developers/_meta.json @@ -0,0 +1,20 @@ +{ + "index": "Introduction", + "concepts": "Core Concepts", + "binaries": "Binaries", + "integrations": "Integration Options", + "clients": "Clients", + "tools": "Tools", + "chain": "Interacting with Nyx", + "--": { + "type": "separator" + }, + "rust": "Rust SDK", + "typescript": "Typescript SDK", + "---": { + "type": "separator" + }, + "archive": "Archive", + "licensing": "Licensing", + "coc": "Coc" +} diff --git a/documentation/dev-portal/src/archive/nym-connect.md b/documentation/docs/pages/developers/archive/nym-connect.md similarity index 96% rename from documentation/dev-portal/src/archive/nym-connect.md rename to documentation/docs/pages/developers/archive/nym-connect.md index 2dca063dd8..78987b012e 100644 --- a/documentation/dev-portal/src/archive/nym-connect.md +++ b/documentation/docs/pages/developers/archive/nym-connect.md @@ -33,7 +33,7 @@ To download Electrum visit the [official webpage](https://electrum.org/#download 4. Set *Use proxy* to ✅, choose `SOCKS5` from the drop-down and add (copy-paste) the values from your NymConnect application 5. Now your Electrum Bitcoin wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. -![Electrum Bitcoin wallet setup](../images/electrum_tutorial/electrum.gif) +![Electrum Bitcoin wallet setup](/images/developers/electrum.gif) ### Monero wallet via NymConnect @@ -44,7 +44,6 @@ To download Monero wallet visit [getmonero.org](https://www.getmonero.org/downlo 3. Go to: *Settings* -> *Interface* -> *Socks5 proxy* -> Add values: IP address `127.0.0.1`, Port `1080` (the values copied from NymConnect) 5. Now your Monero wallet runs through the Mixnet and it will be connected only if your NymConnect or `nym-socks5-client` are connected. -![Monero wallet setup](../images/monero_tutorial/monero-gui-NC.gif) ### Matrix (Element) via NymConnect diff --git a/documentation/docs/pages/developers/archive/nymvpn.md b/documentation/docs/pages/developers/archive/nymvpn.md new file mode 100644 index 0000000000..02150ffe5a --- /dev/null +++ b/documentation/docs/pages/developers/archive/nymvpn.md @@ -0,0 +1,38 @@ +# NymVPN alpha + +
+ +```admonish tip title="web3summit testing" +**If you testing NymVPN CLI on Web3 Summit Berlin, visit our event page with all info tailored for the event: [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/).** +``` + +**NymVPN alpha** is a client that uses [Nym Mixnet](https://nymtech.net) to anonymise all of a user's internet traffic through either a 5-hop mixnet (for a full network privacy) or the faster 2-hop decentralised VPN (with some extra features). + + +**You are invited to take part in the alpha testing** of this new application. Register for private testing round at [nymvpn.com](https://nymvpn.com/en), that will grant you access to the [download page](https://nymvpn.com/download). Visit [NymVPN Support & FAQ](https://nymvpn.com/en/support) or join the [NymVPN matrix channel](https://matrix.to/#/#NymVPN:nymtech.chat) if you have any questions, comments or blockers. + +Checkout the [release page](https://github.com/nymtech/nym-vpn-client/releases) for available binaries. + +*NOTE: NymVPN alpha is experimental software for testing purposes only.* + + +## NymVPN Overview + +To understand what's under the hood of NymVPN and the mixnet, we recommend interested developers to begin with [Nym network overview](https://nymtech.net/docs/architecture/network-overview.html) and the [Mixnet traffic flow](https://nymtech.net/docs/architecture/traffic-flow.html) pages. + +The default setup of NymVPN is to run in 5-hop mode (mixnet): + +``` + ┌─►mix──┐ mix mix + │ │ + Entry │ │ Exit +client ───► Gateway ──┘ mix │ mix ┌─►mix ───► Gateway ───► internet + │ │ + │ │ + mix └─►mix──┘ mix +``` + +Users can switch to 2-hop only mode, which is a faster but less private option. In this mode traffic is only sent between the two Gateways, and is not passed between Mix Nodes. It uses Mixnet Sphinx packets with shorter, fixed routes, which improve latency, but doesn't offer the same level of protection as the 5 hop mode. + diff --git a/documentation/dev-portal/src/nymvpn/cli-linux.md b/documentation/docs/pages/developers/archive/nymvpn/cli-linux.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/cli-linux.md rename to documentation/docs/pages/developers/archive/nymvpn/cli-linux.md diff --git a/documentation/dev-portal/src/nymvpn/cli-mac.md b/documentation/docs/pages/developers/archive/nymvpn/cli-mac.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/cli-mac.md rename to documentation/docs/pages/developers/archive/nymvpn/cli-mac.md diff --git a/documentation/dev-portal/src/nymvpn/cli.md b/documentation/docs/pages/developers/archive/nymvpn/cli.md similarity index 94% rename from documentation/dev-portal/src/nymvpn/cli.md rename to documentation/docs/pages/developers/archive/nymvpn/cli.md index dc1c2f2238..ae74274cf3 100644 --- a/documentation/dev-portal/src/nymvpn/cli.md +++ b/documentation/docs/pages/developers/archive/nymvpn/cli.md @@ -1,7 +1,7 @@ # NymVPN CLI Guide -```admonish tip title="NymVPN CLI Testnet" -If you testing NymVPN CLI and want to try our Sandbox testnet environment, you can visit an explicit guide at [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/). This page alco contains an auto generating access token button. +```admonish tip title="web3summit testing" +**If you testing NymVPN CLI on Web3 Summit Berlin, visit our event page with all info tailored for the event: [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net/).** ``` ```admonish info @@ -225,7 +225,7 @@ Options: ## Testnet environment -If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done. You can follow the steps below or follow more explicit guide on [nym-vpn-cli.sandbox.nymtech.net](https://nym-vpn-cli.sandbox.nymtech.net), including the access token auto generation button. +If you want to run NymVPN CLI in Nym Sandbox environment, there are a few adjustments to be done: 1. Create Sandbox environment config file by saving [this](https://raw.githubusercontent.com/nymtech/nym/develop/envs/sandbox.env) as `sandbox.env` in the same directory as your NymVPN binaries: ```sh diff --git a/documentation/dev-portal/src/nymvpn/faq.md b/documentation/docs/pages/developers/archive/nymvpn/faq.md similarity index 86% rename from documentation/dev-portal/src/nymvpn/faq.md rename to documentation/docs/pages/developers/archive/nymvpn/faq.md index 64830065ac..d05df2d051 100644 --- a/documentation/dev-portal/src/nymvpn/faq.md +++ b/documentation/docs/pages/developers/archive/nymvpn/faq.md @@ -56,7 +56,7 @@ Project Smoosh is a code name for a process in which different components of Nym ## Exit Gateway -Part of the transition under code name [Project Smoosh](#project-smoosh) is a creation of [Nym Exit Gateway](https://nymtech.net/operators/legal/exit-gateway.html) functionality. The operators running Gateways would have to “open” their nodes to a wider range of online services, in a similar fashion to Tor exit relays. The main change will be to expand the original short [allowed.list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to a more permissive setup. An [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt) will constrain the hosts that the users of the Nym VPN and Mixnet can connect to. This will be done in an effort to protect the operators, as Gateways will act both as SOCKS5 Network Requesters, and exit nodes for IP traffic from Nym VPN and Mixnet clients. +Part of the the transition under code name [Project Smoosh](#project-smoosh) is a creation of [Nym Exit Gateway](https://nymtech.net/operators/legal/exit-gateway.html) functionality. The operators running Gateways would have to “open” their nodes to a wider range of online services, in a similar fashion to Tor exit relays. The main change will be to expand the original short [allowed.list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to a more permissive setup. An [exit policy](https://nymtech.net/.wellknown/network-requester/exit-policy.txt) will constrain the hosts that the users of the Nym VPN and Mixnet can connect to. This will be done in an effort to protect the operators, as Gateways will act both as SOCKS5 Network Requesters, and exit nodes for IP traffic from Nym VPN and Mixnet clients. * Read more how the exit policy gets implemented [here](https://nymtech.net/operators/faq/smoosh-faq.html#how-will-the-exit-policy-be-implemented) * Check out [Nym Operators Legal Forum](https://nymtech.net/operators/legal/exit-gateway.html) diff --git a/documentation/dev-portal/src/nymvpn/gui-linux.md b/documentation/docs/pages/developers/archive/nymvpn/gui-linux.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/gui-linux.md rename to documentation/docs/pages/developers/archive/nymvpn/gui-linux.md diff --git a/documentation/dev-portal/src/nymvpn/gui-mac.md b/documentation/docs/pages/developers/archive/nymvpn/gui-mac.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/gui-mac.md rename to documentation/docs/pages/developers/archive/nymvpn/gui-mac.md diff --git a/documentation/dev-portal/src/nymvpn/gui.md b/documentation/docs/pages/developers/archive/nymvpn/gui.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/gui.md rename to documentation/docs/pages/developers/archive/nymvpn/gui.md diff --git a/documentation/dev-portal/src/nymvpn/testing.md b/documentation/docs/pages/developers/archive/nymvpn/testing.md similarity index 100% rename from documentation/dev-portal/src/nymvpn/testing.md rename to documentation/docs/pages/developers/archive/nymvpn/testing.md diff --git a/documentation/dev-portal/src/binaries/building-nym.md b/documentation/docs/pages/developers/binaries.md similarity index 80% rename from documentation/dev-portal/src/binaries/building-nym.md rename to documentation/docs/pages/developers/binaries.md index 0bbb5e0ed1..fdde2ff3b7 100644 --- a/documentation/dev-portal/src/binaries/building-nym.md +++ b/documentation/docs/pages/developers/binaries.md @@ -1,4 +1,6 @@ -# Building from Source +# Nym Binaries + +## Building from Source > Nym runs on Mac OS X, Linux, and Windows. All nodes **except the Desktop Wallet and NymConnect** on Windows should be considered experimental - it works fine if you're an app developer but isn't recommended for running nodes. @@ -8,7 +10,7 @@ Nym has two main codebases: - the [Nym platform](https://github.com/nymtech/nym), written in Rust. This contains all of our code _except_ for the validators. - the [Nym validators](https://github.com/nymtech/nyxd), written in Go. -> This page details how to build the main Nym platform code. +> This page details how to build the main Nym platform code. **If you want to build and run a validator, [go here](../operators/nodes/validator-setup) instead.** ## Prerequisites - Debian/Ubuntu: `pkg-config`, `build-essential`, `libssl-dev`, `curl`, `jq`, `git` @@ -52,10 +54,11 @@ git checkout master # master branch has the latest release version: `develop` wi cargo build --release # build your binaries with **mainnet** configuration ``` -Quite a bit of stuff gets built. The key working parts for devs are the Client binaries and the CLI tool: +> You cannot build from GitHub's .zip or .tar.gz archive files on the releases page - the Nym build scripts automatically include the current git commit hash in the built binary during compilation, so the build will fail if you use the archive code (which isn't a Git repository). Check the code out from github using `git clone` instead. -* [websocket client](../clients/websocket-client.md): `nym-client` -* [socks5 client](../clients/socks5-client.md): `nym-socks5-client` -* [nym-cli tool](https://nymtech.net/docs/tools/nym-cli.html): `nym-cli` -> You cannot build from GitHub's .zip or .tar.gz archive files on the releases page - the Nym build scripts automatically include the current git commit hash in the built binary during compilation, so the build will fail if you use the archive code (which isn't a Git repository). Check the code out from github using `git clone` instead. +## Pre-built Binaries + +The [Github releases page](https://github.com/nymtech/nym/releases) has pre-built binaries which should work on Ubuntu 20.04 and other Debian-based systems, but at this stage cannot be guaranteed to work everywhere. + +If the pre-built binaries don't work or are unavailable for your system, you will need to build the platform yourself. diff --git a/documentation/docs/src/nyx/interacting-with-chain.md b/documentation/docs/pages/developers/chain.md similarity index 59% rename from documentation/docs/src/nyx/interacting-with-chain.md rename to documentation/docs/pages/developers/chain.md index 5ebd5484bd..03c83aeb0b 100644 --- a/documentation/docs/src/nyx/interacting-with-chain.md +++ b/documentation/docs/pages/developers/chain.md @@ -1,17 +1,15 @@ # Interacting with Nyx Chain and Smart Contracts -There are two options for interacting with the blockchain to send tokens or interact with deployed smart contracts: -* [`Nym-CLI`](../tools/nym-cli.md) tool +There are two options for interacting with the blockchain to send tokens or interact with deployed smart contracts: +* [`Nym-CLI`](../tools/nym-cli.md) tool * `nyxd` binary -## Nym-CLI tool (recommended in most cases) -The `nym-cli` tool is a binary offering a simple interface for interacting with deployed smart contract (for instance, bonding and unbonding a mix node from the CLI), as well as creating and managing accounts and keypairs, sending tokens, and querying the blockchain. +## Nym-CLI tool (recommended in most cases) +The `nym-cli` tool is a binary offering a simple interface for interacting with deployed smart contract (for instance, bonding and unbonding a mix node from the CLI), as well as creating and managing accounts and keypairs, sending tokens, and querying the blockchain. -Instructions on how to do so can be found on the [`nym-cli` docs page](../tools/nym-cli.md), and there are example commands in the [integrations FAQ](https://nymtech.net/developers/faq/integrations-faq.html). - -## Nyxd binary -The `nyxd` binary, although more complex to compile and use, offers the full range of commands availiable to users of CosmosSDK chains. Use this if you are (e.g.) wanting to perform more granular queries about transactions from the CLI. - -You can use the instructions on how to do this on from the [`gaiad` docs page](https://hub.cosmos.network/main/delegators/delegator-guide-cli.html#querying-the-state), and there are example commands in the [integrations FAQ](https://nymtech.net/developers/faq/integrations-faq.html). +Instructions on how to do so can be found on the [`nym-cli` docs page](./tools/nym-cli) +## Nyxd binary +The `nyxd` binary, although more complex to compile and use, offers the full range of commands availiable to users of CosmosSDK chains. Use this if you are (e.g.) wanting to perform more granular queries about transactions from the CLI. +You can use the instructions on how to do this on from the [`gaiad` docs page](https://hub.cosmos.network/main/delegators/delegator-guide-cli.html#querying-the-state). diff --git a/documentation/docs/pages/developers/chain/cli-wallet.md b/documentation/docs/pages/developers/chain/cli-wallet.md new file mode 100644 index 0000000000..9b7d25eb91 --- /dev/null +++ b/documentation/docs/pages/developers/chain/cli-wallet.md @@ -0,0 +1,6 @@ +# CLI Wallet + +If you have already read our [validator setup and maintenance documentation](../../operators/nodes/validator-setup) you will have seen that we compile and use the `nyxd` binary primarily for our validators. This binary can however be used for many other tasks, such as creating and using keypairs for wallets, or automated setups that require the signing and broadcasting of transactions. + +### Using `nyxd` binary as a CLI wallet +You can use the `nyxd` as a minimal CLI wallet if you want to set up an account (or multiple accounts). Just compile the binary as per the documentation, **stopping after** the [building your validator](../../operators/nodes/validator-setup#building-your-validator) step is complete. You can then run `nyxd keys --help` to see how you can set up and store different keypairs with which to interact with the Nyx blockchain. diff --git a/documentation/docs/pages/developers/chain/cosmos-registry.md b/documentation/docs/pages/developers/chain/cosmos-registry.md new file mode 100644 index 0000000000..1165ff1822 --- /dev/null +++ b/documentation/docs/pages/developers/chain/cosmos-registry.md @@ -0,0 +1,2 @@ +# Cosmos Registry +You can find all relevant information (chain info, RPC endpoints, etc) on the [Cosmos Chain Registry](https://github.com/cosmos/chain-registry/tree/master/nyx). diff --git a/documentation/docs/src/nyx/ledger-live.md b/documentation/docs/pages/developers/chain/ledger-live.md similarity index 66% rename from documentation/docs/src/nyx/ledger-live.md rename to documentation/docs/pages/developers/chain/ledger-live.md index 968dd2e25b..8b7fbceaaa 100644 --- a/documentation/docs/src/nyx/ledger-live.md +++ b/documentation/docs/pages/developers/chain/ledger-live.md @@ -1,22 +1,22 @@ # Ledger Live Support -Use the following instructions to interact with the Nyx blockchain - either with deployed smart contracts, or just to send tokens - using your Ledger device to sign transactions. +Use the following instructions to interact with the Nyx blockchain - either with deployed smart contracts, or just to send tokens - using your Ledger device to sign transactions. -## Prerequisites -* Download and install [Ledger Live](https://www.ledger.com/ledger-live). -* Compile the `nyxd` binary as per the instructions [here](https://nymtech.net/operators/nodes/validator-setup.html#building-the-nym-validator). Stop after you can successfully run `nyxd` and get the helptext in your console output. +## Prerequisites +* Download and install [Ledger Live](https://www.ledger.com/ledger-live). +* Compile the `nyxd` binary as per the instructions [here](../../operators/nodes/validator-setup). Stop after you can successfully run `nyxd` and get the helptext in your console output. -## Prepare your Ledger App -* Plug in your Ledger device -* Install the `Cosmos (ATOM)` app by following the instructions [here](https://hub.cosmos.network/main/resources/ledger.html). This app allows you to interact with **any** Cosmos SDK chain - you can manage your ATOM, OSMOSIS, NYM tokens, etc. -* On the device, navigate to the Cosmos app and open it +## Prepare your Ledger App +* Plug in your Ledger device +* Install the `Cosmos (ATOM)` app by following the instructions [here](https://hub.cosmos.network/main/resources/ledger.html). This app allows you to interact with **any** Cosmos SDK chain - you can manage your ATOM, OSMOSIS, NYM tokens, etc. +* On the device, navigate to the Cosmos app and open it -## Create a keypair -Add a reference to the ledger device on your local machine by running the following command in the same directory as your `nyxd` binary: +## Create a keypair +Add a reference to the ledger device on your local machine by running the following command in the same directory as your `nyxd` binary: ``` -nyxd keys add ledger_account --ledger -``` +nyxd keys add ledger_account --ledger +``` ## Command help with `nyxd` More information about each command is available by consulting the help section (`--help`) at each layer of `nyxd`'s commands: @@ -25,7 +25,7 @@ More information about each command is available by consulting the help section # logging top level command help nyxd --help -# logging top level command help for transaction commands +# logging top level command help for transaction commands nyxd tx --help # logging top level command help for transaction commands utilising the 'bank' module @@ -33,7 +33,7 @@ nyxd tx bank --help ``` ## Sending tokens between addresses -Perform a transaction from the CLI with `nyxd`, appending the `--ledger` option to the command. +Perform a transaction from the CLI with `nyxd`, appending the `--ledger` option to the command. As an example, the below command will send 1 `NYM` from the ledger account to the `$DESTINATION_ACCOUNT`: @@ -44,36 +44,35 @@ nyxd tx bank send ledger_account $DESTINATION_ACCOOUNT 1000000unym --ledger --no > When a command is run, the transaction will appear on the Ledger device and will require physical confirmation from the device before being signed. ## Nym-specific transactions -Nym-specific commands and queries, like bonding a mix node or delegating unvested tokens, are available in the `wasm` module, and follow the following pattern: +Nym-specific commands and queries, like bonding a mix node or delegating unvested tokens, are available in the `wasm` module, and follow the following pattern: ``` # Executing commands nyxd tx wasm execute $CONTRACT_ADDRESS $JSON_MSG -# Querying the state of a smart contract +# Querying the state of a smart contract nyxd query wasm contract-state smart $CONTRACT_ADDRESS $JSON_MSG ``` -You can find the value of `$CONTRACT_ADDRESS` in the [`network defaults`](https://github.com/nymtech/nym/blob/release/v1.1.7/common/network-defaults/src/mainnet.rs) file. +You can find the value of `$CONTRACT_ADDRESS` in the [`network defaults`](https://github.com/nymtech/nym/blob/master/common/network-defaults/src/mainnet.rs) file. -The value of `$JSON_MSG` will be a blog of `json` formatted as defined for each command and query. You can find these definitions for the mixnet smart contract [here](https://github.com/nymtech/nym/blob/develop/common/cosmwasm-smart-contracts/mixnet-contract/src/msg.rs) and for the vesting contract [here](https://github.com/nymtech/nym/blob/develop/common/cosmwasm-smart-contracts/vesting-contract/src/messages.rs) under `ExecuteMsg` and `QueryMsg`. +The value of `$JSON_MSG` will be a blog of `json` formatted as defined for each command and query. You can find these definitions for the mixnet smart contract [here](https://github.com/nymtech/nym/blob/master/common/cosmwasm-smart-contracts/mixnet-contract/src/msg.rs) and for the vesting contract [here](https://github.com/nymtech/nym/blob/master/common/cosmwasm-smart-contracts/vesting-contract/src/messages.rs) under `ExecuteMsg` and `QueryMsg`. -### Example command execution: +### Example command execution: #### Delegate to a mix node -You can delegate to a mix node from the CLI using `nyxd` and signing the transaction with your ledger by filling in the values of this example: +You can delegate to a mix node from the CLI using `nyxd` and signing the transaction with your ledger by filling in the values of this example: ``` CONTRACT_ADDRESS=mixnet_contract_address ./nyxd tx wasm execute $CONTRACT_ADDRESS '{"delegate_to_mixnode":{"mix_identity":"MIX_NODE_IDENTITY","amount":{"amount":"100000000000","denom":"unym"}}}' --ledger --from admin --node https://rpc.dev.nymte.ch:443 --gas-prices 0.025unymt --gas auto -b block ``` -> By replacing the value of `CONTRACT_ADDRESS` with the address of the vesting contract, you could use the above command to use tokens held in the vesting contract. +> By replacing the value of `CONTRACT_ADDRESS` with the address of the vesting contract, you could use the above command to use tokens held in the vesting contract. -#### Query a vesting schedule -You can query for (e.g.) seeing the current vesting period of an address by filling in the values of the following: +#### Query a vesting schedule +You can query for (e.g.) seeing the current vesting period of an address by filling in the values of the following: ``` CONTRACT_ADDRESS=vesting_contract_address -nyxd query wasm contract-state smart $CONTRACT_ADDRESS '{"get_current_vesting_period"}:{"address": "address_to_query_for"}' --ledger --from admin --node https://rpc.dev.nymte.ch:443 --chain-id qa-net --gas-prices 0.025unymt --gas auto -b block +nyxd query wasm contract-state smart $CONTRACT_ADDRESS '{"get_current_vesting_period"}:{"address": "address_to_query_for"}' --ledger --from admin --node https://rpc.dev.nymte.ch:443 --chain-id qa-net --gas-prices 0.025unymt --gas auto -b block ``` - diff --git a/documentation/docs/src/nyx/rpc-node.md b/documentation/docs/pages/developers/chain/rpc-node.md similarity index 73% rename from documentation/docs/src/nyx/rpc-node.md rename to documentation/docs/pages/developers/chain/rpc-node.md index 352b689bed..ddd8afc538 100644 --- a/documentation/docs/src/nyx/rpc-node.md +++ b/documentation/docs/pages/developers/chain/rpc-node.md @@ -1,9 +1,9 @@ # RPC Nodes -RPC Nodes (which might otherwise be referred to as 'Lite Nodes' or just 'Full Nodes') differ from Validators in that they hold a copy of the Nyx blockchain, but do **not** participate in consensus / block-production. +RPC Nodes (which might otherwise be referred to as 'Lite Nodes' or just 'Full Nodes') differ from Validators in that they hold a copy of the Nyx blockchain, but do **not** participate in consensus / block-production. -You may want to set up an RPC Node for querying the blockchain, or in order to have an endpoint that your app can use to send transactions. +You may want to set up an RPC Node for querying the blockchain, or in order to have an endpoint that your app can use to send transactions. -In order to set up an RPC Node, simply follow the instructions to set up a [Validator](https://nymtech.net/operators/nodes/validator-setup.html), but **exclude the `nyxd tx staking create-validator` command**. +In order to set up an RPC Node, simply follow the instructions to set up a [Validator](../../operators/nodes/validator-setup), but **exclude the `nyxd tx staking create-validator` command**. If you want to fast-sync your node, check out the Polkachu snapshot and their other [resources](https://polkachu.com/seeds/nym). diff --git a/documentation/docs/pages/developers/clients.mdx b/documentation/docs/pages/developers/clients.mdx new file mode 100644 index 0000000000..b507ecf7be --- /dev/null +++ b/documentation/docs/pages/developers/clients.mdx @@ -0,0 +1,21 @@ +# Types of Nym clients +At present, there are three Nym clients. These are built as standalone binaries when building our codebase, but are most easily accessed through one of our SDKs: + +- the websocket (native) client - most easily accessed via the [Rust SDK](./rust) and [Go/C++ FFI](./rust/ffi). +- the SOCKS5 client - most easily accessed via the [Rust SDK](./rust). +- the wasm (webassembly) client - most easily via the [Typescript SDK](./typescript). + +> For information about the role that clients play within the Nym system and their role when communicating with the Mixnet, see the [Client network docs](../network/architecture/mixnet/clients). + +### The websocket 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**. + +### The webassembly client +If you're working in JavaScript or Typescript in the browser, or building an [edge computing](https://en.wikipedia.org/wiki/Edge_computing) app, you'll likely want to choose the webassembly client. + +It's packaged and [available on the npm registry](https://www.npmjs.com/package/@nymproject/nym-client-wasm), so you can `npm install` it into your JavaScript or TypeScript application. + +### The SOCKS5 client +The `nym-socks5-client` is useful for allowing existing applications to use the Nym mixnet without any code changes. All that's necessary is that they can use one of the SOCKS5, SOCKS4a, or SOCKS4 proxy protocols (which many applications can - crypto wallets, browsers, chat applications etc). + +When used as a standalone client, it's less flexible as a way of writing custom applications than the other clients, but able to be used to proxy application traffic through the mixnet without having to make any code changes. diff --git a/documentation/docs/pages/developers/clients/_meta.json b/documentation/docs/pages/developers/clients/_meta.json new file mode 100644 index 0000000000..4a9fdefe51 --- /dev/null +++ b/documentation/docs/pages/developers/clients/_meta.json @@ -0,0 +1,5 @@ +{ + "socks5": "Socks5 (standalone)", + "webassembly-client": "Webassembly Client", + "websocket": "Websocket (standalone)" +} diff --git a/documentation/docs/pages/developers/clients/socks5.mdx b/documentation/docs/pages/developers/clients/socks5.mdx new file mode 100644 index 0000000000..9a49178094 --- /dev/null +++ b/documentation/docs/pages/developers/clients/socks5.mdx @@ -0,0 +1,193 @@ +# Socks5 Client (Standalone) + +> This client can also be utilised via the [Rust SDK](../rust). + +## What is this client for? +Many existing applications are able to use either the SOCKS4, SOCKS4A, or SOCKS5 proxy protocols. If you want to send such an application's traffic through the mixnet, you can use the `nym-socks5-client` to bounce network traffic through the Nym network, like this: + +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +flowchart TB + subgraph Local Machine[Local Machine] + A[Application Logic] + B[Nym Socks5 Client] + end + A <-->|Bytes| B + B <-->|Sphinx Packets| EG + + subgraph Mixnet Nodes[Mixnet Nodes] + EG[/Entry Gateway/] + M{Mix Nodes 1..3} + ExG[\Exit Gateway\] + end + EG <-->|Sphinx Packets| M + M <-->|Sphinx Packets| ExG + + subgraph External Systems + C[Blockchain RPC] + D[Mail Server] + E[Message Server] + F[etc] + end + C <-->|Bytes| ExG + D <-->|Bytes| ExG + E <-->|Bytes| ExG + F <-->|Bytes| ExG +``` + +There are 2 pieces of software that work together to send SOCKS traffic through the mixnet: the `nym-socks5-client`, and a `nym-node` running as an Exit Gateway. + +> The functionality performed by the Exit Gateway was previously performed by the `nym-network-requester`: this functionality has been migrated into the Exit Gateway mode of the `nym-node`. + +The `nym-socks5-client` allows you to do the following from your local machine: +* Take a TCP data stream from a application that can send traffic via SOCKS5. +* Chop up the TCP stream into multiple Sphinx packets, assigning sequence numbers to them, while leaving the TCP connection open for more data +* Send the Sphinx packets through the Nym Network. Packets are shuffled and mixed as they transit the mixnet. + +The `nym-node` then reassembles the original TCP stream using the packets' sequence numbers, and make the intended request. It will then chop up the response into Sphinx packets and send them back through the mixnet to your `nym-socks5-client`. The application will then receive its data, without even noticing that it wasn't talking to a "normal" SOCKS5 proxy! + + +## Download or compile socks5 client + +If you are using OSX or a Debian-based operating system, you can download the `nym-socks5-client` binary from our [Github releases page](https://github.com/nymtech/nym/releases). + +If you are using a different operating system, or want to build from source, simply use `cargo build --release` from the root of the Nym monorepo. + +## Client setup +### Viewing command help + +You can check that your binaries are properly compiled with: + +``` +./nym-socks5-client --help +``` + +You can check the necessary parameters for the available commands by running: + +``` +./nym-client --help +``` + +### Initialising a new client instance +Before you can use the client, you need to initalise a new instance of it, which can be done with the following command: + +``` +./nym-socks5-client init --id docs-example --use-reply-surbs true --provider Entztfv6Uaz2hpYHQJ6JKoaCTpDL5dja18SuQWVJAmmx.Cvhn9rBJw5Ay9wgHcbgCnVg89MPSV5s2muPV2YF1BXYu@Fo4f4SQLdoyoGkFae5TpVhRVoXCF8UiypLVGtGjujVPf +``` + +The `--id` in the example above is a local identifier so that you can name your clients and keep track of them on your local system; it is **never** transmitted over the network. + +The `--use-reply-surbs` field denotes whether you wish to send [SURBs](../../network/concepts/anonymous-replies) along with your request. It defaults to `false`, we are explicitly setting it as `true`. It defaults to `false` for compatibility with versions of the pre-smoosh `nym-network-requester` binary which will soon be deprecated. + +The `--provider` field needs to be filled with the Nym address of an Exit Gateway that can make network requests on your behalf. You can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/gateways) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/). + +#### Choosing a Gateway +By default - as in the example above - your client will choose a random gateway to connect to. + +However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client: +* If you wish to connect to a specific gateway, you can specify this with the `--gateway` flag when running `init`. +* You can also choose a gateway based on its location relative to your client. This can be done by appending the `--latency-based-selection` flag to your `init` command. This command means that to select a gateway, your client will: + * fetch a list of all availiable gateways + * send few ping messages to all of them, and measure response times. + * create a weighted distribution to randomly choose one, favouring ones with lower latency. + +You can select one from the [mixnet explorer](https://explorer.nymtech.net/network-components/gateways) by copying its `Client ID` and using this as the value of the `--provider` flag. Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/). + +> Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms + +### Configuring your client +When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/socks5-clients//`. + +``` +tree $HOME//.nym/socks5-clients/docs-example +├── config +│   └── config.toml +└── data + ├── ack_key.pem + ├── credentials_database.db + ├── gateway_shared.pem + ├── persistent_reply_store.sqlite + ├── private_encryption.pem + ├── private_identity.pem + ├── public_encryption.pem + └── public_identity.pem + +``` + +The `config.toml` file contains client configuration options, while the two `pem` files contain client key information. + +The generated files contain the client name, public/private keypairs, and gateway address. The name `` in the example above is just a local identifier so that you can name your clients. + +#### Configuring your client for Docker +By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`. + +You can set this via the `--host` flag during either the `init` or `run` commands. + +Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process. + +### Running the socks5 client + +You can run the initialised client by doing this: + +``` +./nym-socks5-client run --id docs-example +``` + +## Automating your socks5 client with systemd + +Create a service file for the socks5 client at `/etc/systemd/system/nym-socks5-client.service`: + +```ini +[Unit] +Description=Nym Socks5 Client +StartLimitInterval=350 +StartLimitBurst=10 + +[Service] +User=nym # replace this with whatever user you wish +LimitNOFILE=65536 +ExecStart=/home/nym/nym-socks5-client run --id +KillSignal=SIGINT +Restart=on-failure +RestartSec=30 + +[Install] +WantedBy=multi-user.target +``` + +Now enable and start your socks5 client: + +``` +systemctl enable nym-socks5-client.service +systemctl start nym-socks5-client.service +# you can always check your socks5 client has succesfully started with: +systemctl status nym-socks5-client.service +``` + +## Using your Socks5 Client + +After completing the steps above, your local Socks5 Client will be listening on `localhost:1080` ready to proxy traffic to the Network Requester set as the `--provider` when initialising. + +When trying to connect your app, generally the proxy settings are found in `settings->advanced` or `settings->connection`. + +Here is an example of setting the proxy connecting in Blockstream Green: + +![Blockstream Green settings](/images/wallet-proxy-settings/blockstream-green.gif) + +Most wallets and other applications will work basically the same way: find the network proxy settings, enter the proxy url (host: **localhost**, port: **1080**). + +In some other applications, this might be written as **localhost:1080** if there's only one proxy entry field. + +## Useful Commands + +**no-banner** + +Adding `--no-banner` startup flag will prevent Nym banner being printed even if run in tty environment. + +**build-info** + +A `build-info` command prints the build information like commit hash, rust version, binary version just like what command `--version` does. However, you can also specify an `--output=json` flag that will format the whole output as a json, making it an order of magnitude easier to parse. diff --git a/documentation/docs/pages/developers/clients/socks5/commands.mdx b/documentation/docs/pages/developers/clients/socks5/commands.mdx new file mode 100644 index 0000000000..1681dadc9b --- /dev/null +++ b/documentation/docs/pages/developers/clients/socks5/commands.mdx @@ -0,0 +1,1040 @@ +# `nym-socks5-client` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address + +Usage: nym-socks5-client [OPTIONS] + +Commands: + init Initialise a Nym client. Do this first! + run Run the Nym client with provided configuration client optionally overriding set parameters + ecash Ecash-related functionalities + list-gateways List all registered with gateways + add-gateway Add new gateway to this client + switch-gateway Change the currently active gateway. Note that you must have already registered with the new gateway! + build-info Show build information of this binary + completions Generate shell completions + generate-fig-spec Generate Fig specification + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file Path pointing to an env file that configures the client + --no-banner Flag used for disabling the printed banner in tty + -h, --help Print help + -V, --version Print version +``` + +### `init` +```sh +Initialise a Nym client. Do this first! + +Usage: nym-socks5-client init [OPTIONS] --id --provider + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we are going to connect to + + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --provider + Address of the socks5 provider to send messages to + + --use-reply-surbs + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + -p, --port + Port for the socket to listen on in all subsequent runs + + --host + The custom host on which the socks5 client will be listening for requests + + -o, --output + [default: text] + [possible values: text, json] + + -h, --help + Print help (see a summary with '-h') +``` + +### `run` +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-socks5-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + + --nym-apis + Comma separated list of rest endpoints of the API validators + + --use-anonymous-replies + Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs. + + Note that some service providers might not support this. + + [possible values: true, false] + + --provider + Address of the socks5 provider to send messages to + + -p, --port + Port for the socket to listen on + + --host + The custom host on which the socks5 client will be listening for requests + + -h, --help + Print help (see a summary with '-h') +``` + +### `import-credential` + +### `list-gateways` +```sh +List all registered with gateways + +Usage: nym-socks5-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `add-gateway` +```sh +Add new gateway to this client + +Usage: nym-socks5-client add-gateway [OPTIONS] --id + +Options: + --id Id of client we want to add gateway for + --gateway-id Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead + --force-tls-gateway Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --set-active Specify whether this new gateway should be set as the active one + --nym-apis Comma separated list of rest endpoints of the API validators + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `build-info` +```sh +Show build information of this binary + +Usage: nym-socks5-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` +Example output: +```sh + +Binary Name: nym-socks5-client +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.42 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` + +### `completions` +```sh +Generate shell completions + +Usage: nym-socks5-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` + +### `generate-fig-spec` +```sh +Generate Fig specification + +Usage: nym-socks5-client generate-fig-spec + +Options: + -h, --help Print help +``` +Example output: +```sh +const completion: Fig.Spec = { + name: "nym-socks5-client", + description: "A SOCKS5 localhost proxy that converts incoming messages to Sphinx and sends them to a Nym address", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + }, + }, + { + name: "--use-reply-surbs", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_reply_surbs", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--use-anonymous-replies", + description: "Specifies whether this client is going to use an anonymous sender tag for communication with the service provider. While this is going to hide its actual address information, it will make the actual communication slower and consume nearly double the bandwidth as it will require sending reply SURBs", + isRepeatable: true, + args: { + name: "use_anonymous_replies", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--provider", + description: "Address of the socks5 provider to send messages to", + isRepeatable: true, + args: { + name: "provider", + isOptional: true, + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "The custom host on which the socks5 client will be listening for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--geo-routing", + description: "Set geo-aware mixnode selection when sending mixnet traffic, for experiments only", + hidden: true, + isRepeatable: true, + args: { + name: "geo_routing", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: "--medium-toggle", + description: "Enable medium mixnet traffic, for experiments only. This includes things like disabling cover traffic, no per hop delays, etc", + }, + { + name: "--outfox", + }, + { + name: ["-h", "--help"], + description: "Print help (see more with '--help')", + }, + ], + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: "--standalone", + description: "Specifies whether we're attempting to import a standalone ticketbook (i.e. serialised `IssuedTicketBook`)", + }, + { + name: "--full", + description: "Specifies whether we're attempting to import full ticketboot (i.e. one that **might** contain required global signatures; that is serialised `ImportableTicketBook`)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the key", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the key", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--key-data", + description: "Explicitly provide the encoded key data (as base58)", + isRepeatable: true, + args: { + name: "key_data", + isOptional: true, + }, + }, + { + name: "--key-path", + description: "Specifies the path to file containing binary key data", + isRepeatable: true, + args: { + name: "key_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/docs/pages/developers/clients/webassembly-client.mdx b/documentation/docs/pages/developers/clients/webassembly-client.mdx new file mode 100644 index 0000000000..71276ef8c1 --- /dev/null +++ b/documentation/docs/pages/developers/clients/webassembly-client.mdx @@ -0,0 +1,22 @@ +# Webassembly Client + +The Nym webassembly client allows any webassembly-capable runtime to build and send Sphinx packets to the Nym network, for uses in edge computing and browser-based applications. + +This is currently packaged and distributed for ease of use via the [Nym Typescript SDK library](../typescript). **We imagine most developers will use this client via the SDK for ease.** + +The webassembly client allows for the easy creation of Sphinx packets from within mobile apps and browser-based client-side apps (including Electron or similar). + +## Building apps with Webassembly Client + +Check out the [Typescript SDK docs](../typescript) for examples of usage. + +## Think about what you're sending! +import { Callout } from 'nextra/components' + + + Think about what information your app sends. That goes for whatever you put into your Sphinx packet messages as well as what your app's environment may leak. + + +Whenever you write client apps using HTML/JavaScript, we recommend that you **do not load external resources from CDNs**. Webapp developers do this all the time, to save load time for common resources, or just for convenience. But when you're writing privacy apps it's better not to make these kinds of requests. Pack everything locally. + +If you use only local resources within your Electron app or your browser extensions, explicitly encoding request data in a Sphinx packet does protect you from the normal leakage that gets sent in a browser HTTP request. [There's a lot of stuff that leaks when you make an HTTP request from a browser window](https://panopticlick.eff.org/). Luckily, all that metadata and request leakage doesn't happen in Nym, because you're choosing very explicitly what to encode into Sphinx packets, instead of sending a whole browser environment by default. diff --git a/documentation/docs/pages/developers/clients/websocket.md b/documentation/docs/pages/developers/clients/websocket.md new file mode 100644 index 0000000000..249df901ad --- /dev/null +++ b/documentation/docs/pages/developers/clients/websocket.md @@ -0,0 +1,13 @@ +# Websocket Client (Standalone) + +> This client can also be utilised via the [Rust SDK](../rust) and [Go/C++ FFI](../rust/ffi). + +You can run this client as a standalone process and pipe traffic into it to be sent through the mixnet. This is useful if you're building an application in a language other than Typescript or Rust and cannot utilise one of the SDKs. + +You can find the code for this client [here](https://github.com/nymtech/nym/tree/master/clients/native). + +## Download or compile client + +If you are using OSX or a Debian-based operating system, you can download the `nym-socks5-client` binary from our [Github releases page](https://github.com/nymtech/nym/releases). + +If you are using a different operating system, or want to build from source, simply use `cargo build --release` from the root of the Nym monorepo. diff --git a/documentation/docs/pages/developers/clients/websocket/commands.mdx b/documentation/docs/pages/developers/clients/websocket/commands.mdx new file mode 100644 index 0000000000..f2c7c7b0e4 --- /dev/null +++ b/documentation/docs/pages/developers/clients/websocket/commands.mdx @@ -0,0 +1,971 @@ +# `nym-client` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +Implementation of the Nym Client + +Usage: nym-client [OPTIONS] + +Commands: + init Initialise a Nym client. Do this first! + run Run the Nym client with provided configuration client optionally overriding set parameters + ecash Ecash-related functionalities + list-gateways List all registered with gateways + add-gateway Add new gateway to this client + switch-gateway Change the currently active gateway. Note that you must have already registered with the new gateway! + build-info Show build information of this binary + completions Generate shell completions + generate-fig-spec Generate Fig specification + help Print this message or the help of the given subcommand(s) + +Options: + -c, --config-env-file Path pointing to an env file that configures the client + --no-banner Flag used for disabling the printed banner in tty + -h, --help Print help + -V, --version Print version +``` + +### `init` +```sh +Initialise a Nym client. Do this first! + +Usage: nym-client init [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we are going to connect to + --force-tls-gateway + Specifies whether the client will attempt to enforce tls connection to the desired gateway + --latency-based-selection + Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket (if applicable) to listen on in all subsequent runs + --host + Ip for the socket (if applicable) to listen for requests + -o, --output + [default: text] [possible values: text, json] + -h, --help + Print help +``` + +### `run` +```sh +Run the Nym client with provided configuration client optionally overriding set parameters + +Usage: nym-client run [OPTIONS] --id + +Options: + --id + Id of client we want to create config for + --gateway + Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened + --nym-apis + Comma separated list of rest endpoints of the API validators + --disable-socket + Whether to not start the websocket [possible values: true, false] + -p, --port + Port for the socket to listen on + --host + Ip for the socket (if applicable) to listen for requests + -h, --help + Print help +``` + +### `import-credential` + +### `list-gateways` +```sh +List all registered with gateways + +Usage: nym-client list-gateways [OPTIONS] --id + +Options: + --id Id of client we want to list gateways for + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` + +### `switch-gateway` +```sh +Change the currently active gateway. Note that you must have already registered with the new gateway! + +Usage: nym-client switch-gateway --id --gateway-id + +Options: + --id Id of client we want to list gateways for + --gateway-id Id of the gateway we want to switch to + -h, --help Print help +``` + +### `build-info` +```sh +Show build information of this binary + +Usage: nym-client build-info [OPTIONS] + +Options: + -o, --output [default: text] [possible values: text, json] + -h, --help Print help +``` +Example output: +```sh + +Binary Name: nym-client +Build Timestamp: 2024-10-29T09:48:31.988049207Z +Build Version: 1.1.42 +Commit SHA: 299552881810511273af13eb135297a4cf7a38de +Commit Date: 2024-10-29T10:48:07.000000000+01:00 +Commit Branch: max/new-docs-framework +rustc Version: 1.80.0 +rustc Channel: stable +cargo Profile: release + +``` + +### `completions` +```sh +Generate shell completions + +Usage: nym-client completions + +Arguments: + [possible values: bash, elvish, fish, power-shell, zsh] + +Options: + -h, --help Print help +``` + +### `generate-fig-spec` +```sh +Generate Fig specification + +Usage: nym-client generate-fig-spec + +Options: + -h, --help Print help +``` +Example output: +```sh +const completion: Fig.Spec = { + name: "nym-native-client", + description: "Implementation of the Nym Client", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we are going to connect to", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket (if applicable) to listen on in all subsequent runs", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway", + ], + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + options: [ + { + name: "--id", + description: "Id of client we want to create config for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway", + description: "Id of the gateway we want to connect to. If overridden, it is user's responsibility to ensure prior registration happened", + isRepeatable: true, + args: { + name: "gateway", + isOptional: true, + }, + }, + { + name: "--nyxd-urls", + description: "Comma separated list of rest endpoints of the nyxd validators", + hidden: true, + isRepeatable: true, + args: { + name: "nyxd_urls", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--enabled-credentials-mode", + description: "Set this client to work in a enabled credentials mode that would attempt to use gateway with bandwidth credential requirement", + hidden: true, + isRepeatable: true, + args: { + name: "enabled_credentials_mode", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: "--disable-socket", + description: "Whether to not start the websocket", + isRepeatable: true, + args: { + name: "disable_socket", + isOptional: true, + suggestions: [ + "true", + "false", + ], + }, + }, + { + name: ["-p", "--port"], + description: "Port for the socket to listen on", + isRepeatable: true, + args: { + name: "port", + isOptional: true, + }, + }, + { + name: "--host", + description: "Ip for the socket (if applicable) to listen for requests", + isRepeatable: true, + args: { + name: "host", + isOptional: true, + }, + }, + { + name: "--fastmode", + description: "Mostly debug-related option to increase default traffic rate so that you would not need to modify config post init", + }, + { + name: "--no-cover", + description: "Disable loop cover traffic and the Poisson rate limiter (for debugging only)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + options: [ + { + name: "--id", + description: "Id of client that is going to display the ticketbook information", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + options: [ + { + name: "--id", + description: "Id of client that is going to import the credential", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--credential-data", + description: "Explicitly provide the encoded credential data (as base58)", + isRepeatable: true, + args: { + name: "credential_data", + isOptional: true, + }, + }, + { + name: "--credential-path", + description: "Specifies the path to file containing binary credential data", + isRepeatable: true, + args: { + name: "credential_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: "--standalone", + description: "Specifies whether we're attempting to import a standalone ticketbook (i.e. serialised `IssuedTicketBook`)", + }, + { + name: "--full", + description: "Specifies whether we're attempting to import full ticketboot (i.e. one that **might** contain required global signatures; that is serialised `ImportableTicketBook`)", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the signatures", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the signatures", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--signatures-data", + description: "Explicitly provide the encoded signatures data (as base58)", + isRepeatable: true, + args: { + name: "signatures_data", + isOptional: true, + }, + }, + { + name: "--signatures-path", + description: "Specifies the path to file containing binary signatures data", + isRepeatable: true, + args: { + name: "signatures_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + options: [ + { + name: "--id", + description: "Id of client that is going to import the key", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--client-config", + description: "Config file of the client that is supposed to use the key", + isRepeatable: true, + args: { + name: "client_config", + template: "filepaths", + }, + }, + { + name: "--key-data", + description: "Explicitly provide the encoded key data (as base58)", + isRepeatable: true, + args: { + name: "key_data", + isOptional: true, + }, + }, + { + name: "--key-path", + description: "Specifies the path to file containing binary key data", + isRepeatable: true, + args: { + name: "key_path", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--version", + hidden: true, + isRepeatable: true, + args: { + name: "version", + isOptional: true, + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + options: [ + { + name: "--id", + description: "Id of client we want to add gateway for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Explicitly specify id of the gateway to register with. If unspecified, a random gateway will be chosen instead", + isRepeatable: true, + args: { + name: "gateway_id", + isOptional: true, + }, + }, + { + name: "--nym-apis", + description: "Comma separated list of rest endpoints of the API validators", + isRepeatable: true, + args: { + name: "nym_apis", + isOptional: true, + }, + }, + { + name: "--custom-mixnet", + description: "Path to .json file containing custom network specification", + hidden: true, + isRepeatable: true, + args: { + name: "custom_mixnet", + isOptional: true, + template: "filepaths", + }, + }, + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: "--force-tls-gateway", + description: "Specifies whether the client will attempt to enforce tls connection to the desired gateway", + }, + { + name: "--latency-based-selection", + description: "Specifies whether the new gateway should be determined based by latency as opposed to being chosen uniformly", + exclusiveOn: [ + "--gateway-id", + ], + }, + { + name: "--set-active", + description: "Specify whether this new gateway should be set as the active one", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + options: [ + { + name: "--id", + description: "Id of client we want to list gateways for", + isRepeatable: true, + args: { + name: "id", + }, + }, + { + name: "--gateway-id", + description: "Id of the gateway we want to switch to", + isRepeatable: true, + args: { + name: "gateway_id", + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "build-info", + description: "Show build information of this binary", + options: [ + { + name: ["-o", "--output"], + isRepeatable: true, + args: { + name: "output", + isOptional: true, + suggestions: [ + "text", + "json", + ], + }, + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "completions", + description: "Generate shell completions", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + args: { + name: "shell", + suggestions: [ + "bash", + "elvish", + "fish", + "power-shell", + "zsh", + ], + }, + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + options: [ + { + name: ["-h", "--help"], + description: "Print help", + }, + ], + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + subcommands: [ + { + name: "init", + description: "Initialise a Nym client. Do this first!", + }, + { + name: "run", + description: "Run the Nym client with provided configuration client optionally overriding set parameters", + }, + { + name: "ecash", + description: "Ecash-related functionalities", + subcommands: [ + { + name: "show-ticket-books", + description: "Display information associated with the imported ticketbooks,", + }, + { + name: "import-ticket-book", + description: "Import a pre-generated ticketbook", + }, + { + name: "import-coin-index-signatures", + description: "Import coin index signatures needed for ticketbooks", + }, + { + name: "import-expiration-date-signatures", + description: "Import expiration date signatures needed for ticketbooks", + }, + { + name: "import-master-verification-key", + description: "Import master verification key needed for ticketbooks", + }, + ], + }, + { + name: "list-gateways", + description: "List all registered with gateways", + }, + { + name: "add-gateway", + description: "Add new gateway to this client", + }, + { + name: "switch-gateway", + description: "Change the currently active gateway. Note that you must have already registered with the new gateway!", + }, + { + name: "build-info", + description: "Show build information of this binary", + }, + { + name: "completions", + description: "Generate shell completions", + }, + { + name: "generate-fig-spec", + description: "Generate Fig specification", + }, + { + name: "help", + description: "Print this message or the help of the given subcommand(s)", + }, + ], + }, + ], + options: [ + { + name: ["-c", "--config-env-file"], + description: "Path pointing to an env file that configures the client", + isRepeatable: true, + args: { + name: "config_env_file", + isOptional: true, + template: "filepaths", + }, + }, + { + name: "--no-banner", + description: "Flag used for disabling the printed banner in tty", + }, + { + name: ["-h", "--help"], + description: "Print help", + }, + { + name: ["-V", "--version"], + description: "Print version", + }, + ], +}; + +export default completion; +``` diff --git a/documentation/dev-portal/src/clients/websocket/config.md b/documentation/docs/pages/developers/clients/websocket/config.md similarity index 100% rename from documentation/dev-portal/src/clients/websocket/config.md rename to documentation/docs/pages/developers/clients/websocket/config.md diff --git a/documentation/dev-portal/src/clients/websocket/examples.md b/documentation/docs/pages/developers/clients/websocket/examples.md similarity index 100% rename from documentation/dev-portal/src/clients/websocket/examples.md rename to documentation/docs/pages/developers/clients/websocket/examples.md diff --git a/documentation/dev-portal/src/clients/websocket/setup.md b/documentation/docs/pages/developers/clients/websocket/setup.md similarity index 77% rename from documentation/dev-portal/src/clients/websocket/setup.md rename to documentation/docs/pages/developers/clients/websocket/setup.md index e682e87175..5c06faa69c 100644 --- a/documentation/dev-portal/src/clients/websocket/setup.md +++ b/documentation/docs/pages/developers/clients/websocket/setup.md @@ -1,4 +1,4 @@ -# Setup & Run +# Setup & Run ## Viewing command help @@ -8,12 +8,6 @@ You can check that your binaries are properly compiled with: ./nym-client --help ``` -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - The two most important commands you will issue to the client are: * `init` - initalise a new client instance. @@ -35,15 +29,9 @@ Initialising a new client instance can be done with the following command: ./nym-client init --id example-client ``` -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - The `--id` in the example above is a local identifier so that you can name your clients; it is **never** transmitted over the network. -There is an optional `--gateway` flag that you can use if you want to use a specific gateway. The supplied argument is the `Identity Key` of the gateway you wish to use, which can be found on the [mainnet Network Explorer](https://explorer.nymtech.net/network-components/gateways) or [Sandbox Testnet Explorer](https://sandbox-explorer.nymtech.net/network-components/gateways) depending on which network you are on. +There is an optional `--gateway` flag that you can use if you want to use a specific gateway. The supplied argument is the `Identity Key` of the gateway you wish to use, which can be found on the [mixnet explorer](https://explorer.nymtech.net/network-components/gateways). Alternatively, you could use [Harbourmaster](https://harbourmaster.nymtech.net/) Not passing this argument will randomly select a gateway for your client. diff --git a/documentation/dev-portal/src/clients/websocket/usage.md b/documentation/docs/pages/developers/clients/websocket/usage.md similarity index 79% rename from documentation/dev-portal/src/clients/websocket/usage.md rename to documentation/docs/pages/developers/clients/websocket/usage.md index ecc157d98d..c258d45abb 100644 --- a/documentation/dev-portal/src/clients/websocket/usage.md +++ b/documentation/docs/pages/developers/clients/websocket/usage.md @@ -3,14 +3,10 @@ The Nym native client exposes a websocket interface that your code connects to. Once you have a websocket connection, interacting with the client involves piping messages down the socket and listening for incoming messages. -# Message Requests -There are a number of message types that you can send up the websocket as defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs): +## Message Requests +There are a number of message types that you can send up the websocket as defined [here](https://github.com/nymtech/nym/blob/master/clients/native/websocket-requests/src/responses.rs#L48). -```rust,noplayground -{{#include ../../../../../clients/native/websocket-requests/src/requests.rs:55:97}} -``` - -## Getting your own address +### Getting your own address When you start your app, it is best practice to ask the native client to tell you what your own address is (from the generated configuration files . If you are running a service, you need to do this in order to know what address to give others. In a client-side piece of code you can also use this as a test to make sure your websocket connection is running smoothly. To do this, send: ```json @@ -32,7 +28,7 @@ See [here](https://github.com/nymtech/nym/blob/93cc281abc2cc951023b51746fa6f2ead > Note that all the pieces of native client example code begin with printing the selfAddress. Examples exist for Rust, Go, Javascript, and Python. -## Sending text +### Sending text If you want to send text information through the mixnet, format a message like this one and poke it into the websocket: ```json @@ -58,7 +54,7 @@ In some applications, e.g. where people are chatting with friends who they know, **If that fits your security model, good. However, will probably be the case that you want to send anonymous replies using Single Use Reply Blocks (SURBs)**. -You can read more about SURBs [here](https://nymtech.net/docs/architecture/traffic-flow.html#private-replies-using-surbs) but in short they are ways for the receiver of this message to anonymously reply to you - the sender - **without them having to know your client address**. +You can read more about SURBs [here](../../network/concepts/anonymous-replies) but in short they are ways for the receiver of this message to anonymously reply to you - the sender - **without them having to know your client address**. Your client will send along a number of `replySurbs` to the recipient of the message. These are pre-addressed Sphinx packets that the recipient can write to the payload of (i.e. write response data to), but not view the final destination of. If the recipient is unable to fit the response data into the bucket of SURBs sent to it, it will use a SURB to request more SURBs be sent to it from your client. @@ -75,7 +71,7 @@ See ['Replying to SURB Messages'](#replying-to-surb-messages) below for an examp Deciding on the amount of SURBs to generate and send along with outgoing messages depends on the expected size of the reply. You might want to send a lot of SURBs in order to make sure you get your response as quickly as possible (but accept the minor additional latency when sending, as your client has to generate and encrypt the packets), or you might just send a few (e.g. 20) and then if your response requires more SURBs, send them along, accepting the additional latency in getting your response. -## Sending binary data +### Sending binary data You can also send bytes instead of JSON. For that you have to send a binary websocket frame containing a binary encoded Nym [`ClientRequest`](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs#L25) containing the same information. @@ -83,7 +79,7 @@ Nym [`ClientRequest`](https://github.com/nymtech/nym/blob/develop/clients/native You can find examples of sending and receiving binary data in the [code examples](https://github.com/nymtech/nym/tree/master/clients/native/examples), and an example project from the Nym community [BTC-BC](https://github.com/sgeisler/btcbc-rs/): Bitcoin transaction transmission via Nym, a client and service provider written in Rust. -## Replying to SURB messages +### Replying to SURB messages Each bucket of `replySURBs`, when received as part of an incoming message, has a unique session identifier, which **only identifies the bucket of pre-addressed packets**. This is necessary to make sure that your app is replying to the correct people with the information meant for them in a situation where multiple clients are sending requests to a single service. Constructing a reply with SURBs looks something like this (where `senderTag` was parsed from the incoming message) @@ -96,7 +92,7 @@ Constructing a reply with SURBs looks something like this (where `senderTag` was } ``` -## Error messages +### Error messages Errors from the app's client, or from the gateway, will be sent down the websocket to your code in the following format: ```json @@ -106,12 +102,18 @@ Errors from the app's client, or from the gateway, will be sent down the websock } ``` -## LaneQueueLength -This is currently only used in the [Socks Client](../socks5-client.md) to keep track of the number of Sphinx packets waiting to be sent to the mixnet via being slotted amongst cover traffic. As this value becomes larger, the client signals to the application it should slow down the speed with which it writes to the proxy. This is to stop situations arising whereby an app connected to the client appears as if it has sent (e.g.) a bunch of messages and is awaiting a reply, when they in fact have not been sent through the mixnet yet. +### LaneQueueLength +This is currently only used in the [Socks Client](../socks5) to keep track of the number of Sphinx packets waiting to be sent to the mixnet via being slotted amongst cover traffic. As this value becomes larger, the client signals to the application it should slow down the speed with which it writes to the proxy. This is to stop situations arising whereby an app connected to the client appears as if it has sent (e.g.) a bunch of messages and is awaiting a reply, when they in fact have not been sent through the mixnet yet. -# Message Responses -Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/responses.rs): +## Message Responses +Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/master/clients/native/websocket-requests/src/responses.rs#L47): -```rust,noplayground -{{#include ../../../../../clients/native/websocket-requests/src/responses.rs:48:53}} +```rust +#[derive(Debug)] +pub enum ServerResponse { + Received(ReconstructedMessage), + SelfAddress(Box), + LaneQueueLength { lane: u64, queue_length: usize }, + Error(error::Error), +} ``` diff --git a/documentation/docs/src/coc.md b/documentation/docs/pages/developers/coc.md similarity index 100% rename from documentation/docs/src/coc.md rename to documentation/docs/pages/developers/coc.md diff --git a/documentation/docs/pages/developers/concepts.mdx b/documentation/docs/pages/developers/concepts.mdx new file mode 100644 index 0000000000..a186e7d819 --- /dev/null +++ b/documentation/docs/pages/developers/concepts.mdx @@ -0,0 +1,5 @@ +# Core Concepts + +We are working on making the Mixnet as easy as possible to use; that said, it is at the moment still quite an unusual system in terms of how it works and the required parts. + +We are working on abstractions to emulate more traditional networking such as reading from / writing to TCP sockets, and have plans to modify the internals of the clients to remove some of the required architecture and slim down the parts required to use the Mixnet. diff --git a/documentation/docs/pages/developers/concepts/_meta.json b/documentation/docs/pages/developers/concepts/_meta.json new file mode 100644 index 0000000000..a2140d915b --- /dev/null +++ b/documentation/docs/pages/developers/concepts/_meta.json @@ -0,0 +1,6 @@ +{ + "required-architecture": "Required Architecture", + "messages": "Message Based Paradigm", + "message-queue": "Message Queue", + "credentials": "Credentials" +} diff --git a/documentation/docs/pages/developers/concepts/credentials.mdx b/documentation/docs/pages/developers/concepts/credentials.mdx new file mode 100644 index 0000000000..c44dc8078e --- /dev/null +++ b/documentation/docs/pages/developers/concepts/credentials.mdx @@ -0,0 +1,15 @@ +import { Callout } from 'nextra/components' + +# Credentials + + + +Right now we are still working on the specifics of how credentials will work for developers; this page serves as a stub with what information we do currently have. + + + +Once the [zk-nym](../../network/cryptography/zk-nym) credential system is turned on, all Nym clients will have to present a valid credential to their Gateway on connection. + +We plan to supply developers with a credential faucet for their applications, and a pay-per-play backend for large existing applications that wish to integrate and supply their users' with credentials under the hood. + +> Remember, due to the [rerandomisation](../../network/cryptography/zk-nym/rerandomise) properties of the zk-nym scheme, that an application supplies a user with a credential in no way affects any privacy properties: the user will always present unlinkable rerandomised credential data to whatever Gateway their app instance connects to! diff --git a/documentation/docs/pages/developers/concepts/message-queue.md b/documentation/docs/pages/developers/concepts/message-queue.md new file mode 100644 index 0000000000..4209631f29 --- /dev/null +++ b/documentation/docs/pages/developers/concepts/message-queue.md @@ -0,0 +1,75 @@ +# Message Queue + +Clients, once connected to the Mixnet, **are always sending traffic into the Mixnet**; as well as the packets that you as a developer are sending from your application logic, they send [cover traffic](../../network/concepts/cover-traffic) at a constant rate defined by a Poisson process. This is part of the network's mitigation of timing attacks. + +There are two constant streams of sphinx packets leaving the client at the rate defined by the Poisson process. +- one that is solely cover traffic +- one that sends a mixture of cover and 'real' traffic + + +```mermaid +--- +config: + theme: neo-dark + layout: elk + +title: Cover Traffic Stream +--- +sequenceDiagram + box Local Machine + participant App Logic + participant Nym Client + end + participant Entry Gateway + + loop Cover Traffic Stream + Nym Client->>Nym Client: Delay + Nym Client->>Entry Gateway: Cover traffic + end + + +``` + +```mermaid +--- +config: + theme: neo-dark + layout: elk + +title: Mixed Stream +--- +sequenceDiagram + box Local Machine + participant App Logic + participant Nym Client + end + participant Entry Gateway + + loop Cover + Real Traffic Stream + Nym Client->>Nym Client: Check internal queue + delay + Nym Client->>Entry Gateway: Cover traffic + alt Packets with App Payload + App Logic-->>Nym Client: Send(bytes): add to internal queue + Nym Client->>Nym Client: Check internal queue: bytes to send + Nym Client->>Nym Client: Encrypt & packetise bytes + Nym Client->>Entry Gateway: Real Packets + Nym Client->>Nym Client: Check internal queue: bytes to send + Nym Client->>Nym Client: Encrypt & packetise bytes + Nym Client->>Entry Gateway: Real Packets + Nym Client->>Nym Client: Check internal queue: queue empty + end + Nym Client->>Nym Client: Delay + Nym Client->>Entry Gateway: Cover traffic + end +``` + +> Since Sphinx packets are indistinguishable to an external observer, the only difference between 'real' and cover traffic is whether the payload is empty or not. This can be only known to the eventual receiver of the packet. + +## What does `send()` do then? + +When passing a message to a client (however you do it, either piping messages from an app to a standalone client or via one of the `send` functions exposed by the SDKs), you are **putting that message into the queue** to be source encrypted and sent in the future, in order to ensure that traffic leaving the client does so in a manner that to an external observer is uniform / does not create any 'burst' or change in traffic timings that could aid traffic analysis. + +## Note on Client Shutdown +Accidentally dropping a client before your message has been sent is something that is possible and should be avoided (see the [troubleshooting guide](../rust/mixnet/troubleshooting) for more on this) but is easy to avoid simply by remembering to: +- keep your client process alive, even if you are not expecting a reply to your message +- (in the case of the SDKs) properly disconnecting your client in order to make sure that the message queue is flushed of Sphinx packets with actual payloads. diff --git a/documentation/docs/pages/developers/concepts/messages.mdx b/documentation/docs/pages/developers/concepts/messages.mdx new file mode 100644 index 0000000000..68e4b6f92c --- /dev/null +++ b/documentation/docs/pages/developers/concepts/messages.mdx @@ -0,0 +1,30 @@ +# Message-based Paradigm + +For the moment, Mixnet clients work assuming they will be piped atomic messages looking something like this: + +``` +MixnetMessage { + Message: Message_Bytes, + To: Nym_Address, + Attached_SURBS: Number_Of_Surbs +} +``` + +That the client will then encrypt as Sphinx packets and send through the Mixnet. + +Likewise, they assume that once they have received and decrypted a Sphinx packet, they will kick back a reconstructed message to the rest of your app logic that look something like: + +``` +ReconstructedMessage { + Message: Message_Bytes, + From: SURB_Sender_Tag +} +``` + +This is obviously quite different to e.g. simply being able to read/write from a stream returned from a function call to create a TCP connection, but there are several approaches that developers can take to dealing with this right now. + +## Message Abstractions +- Rust/Go (and soon C++) developers can use the `TcpProxy` [stream abstraction](../rust/tcpproxy). +- Developers who are using Typescript/Javascript can also avoid having to deal directly with messages via using [MixFetch](../typescript/examples/mix-fetch). +- As can developers who are bundling and running the standalone [socks5 client](../clients/socks5) using some form of init script. +- There is a seperate pair of binaries which other developers can use to run as a persistent secondary proxy process built using the `TcpProxy` abstraction. These simply expose a `localhost` socket port to pipe traffic to and from in the same way as you would a TCP connection and can be found [here](https://github.com/nymtech/standalone-tcp-proxies). diff --git a/documentation/docs/pages/developers/concepts/required-architecture.md b/documentation/docs/pages/developers/concepts/required-architecture.md new file mode 100644 index 0000000000..b12a791a9f --- /dev/null +++ b/documentation/docs/pages/developers/concepts/required-architecture.md @@ -0,0 +1,48 @@ +# Required Application Architecture + +Due to the fact that there are a lot of components that make up the Nym network (the Mixnet, Blockchain, etc) there is often confusion / misunderstandings about what is required to run application traffic through the Mixnet and take advantage of its various privacy properties. + +## What do I need? +Nym clients on 'both sides' of the Mixnet. +- traditional client / server application setups involve having a Nym client on the local 'client' machine, as well as on the 'server' backend your local app/process wants to remotely communicate with. We need to put the Mixnet betwen them to gain the privacy properties as we need our local app to pipe its traffic to its local Nym client and have this traffic encrypted and slotted into the message queue for sending, and our server code to have a Nym client listening out for incoming messages to decrypt, reconstruct, and pass upstream to the server process. The server-side Nym client can then [anonymously reply via SURBs](../../network/traffic/anonymous-replies) to the client-app. +- P2P app setups may differ only insofar as that they probably shouldn't rely on [ephemeral clients](../rust/mixnet/examples/simple) as they will likely need a persistent Nym address - otherwise the logic is the same as client/server apps. + +> We haven't yet tried to integrate a fully P2P application using anonymous replies: reach out if you are trying / have ideas! + +That's it - so long as you have a Nym client, you can communicate with other Nym clients through the Mixnet. The content of your message payloads is up to you, and you can approach funneling traffic through the Mixnet as a black box if you want! + +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +flowchart TB + subgraph Local Machine[Local Machine] + A[Application Logic] + B[Nym Client] + end + + A <-->|Bytes| B + B <-->|Sphinx Packets| Mixnet + + Mixnet{Mixnet Nodes} + + subgraph Remote Machine + C[Application Logic] + D[Nym Client] + end + + C <-->|Bytes| D + D <-->|Sphinx Packets| Mixnet +``` + +## What don't I need (but is maybe nice to have)? +You **do not need to run any infrastructure to integrate Mixnet functionality**. + +That said, if you are expecting a lot of traffic and perhaps don't want to rely on other people's Gateway infrastructure, you could run your own. However, this is something that is more in the 'nice to have'/'quality of service' category, and is not necessarily expected when starting to build on Nym. Furthermore, if our tokenomic incentives are working as they should, Gateway uptimes should be so good as to not require this regardless! + +## What do I definitely not need? +- To run a Mix Node. Defining which Mix Nodes you want to run traffic through is, although [technically possible](../rust/mixnet/examples/custom-topology), **only to be used in testing or research scenarios**; limiting the potential paths of your packets to a subset of the overall Mixnet topology is effectively reducing your anonymity set, and potentially leaking this subset through e.g. having the calculation logic open sourced is even worse. The best performing Mix Nodes are selected to route traffic per epoch, and will be used by your Nym clients when routing packets. +- To run a Validator / NymAPI instance. +- `NYM` tokens: for the moment the Mixnet is free to use. Developers will have access to a Credential faucet once the [zk-nym](../../network/cryptography/zk-nym) scheme is enabled in mainnet. diff --git a/documentation/docs/pages/developers/index.mdx b/documentation/docs/pages/developers/index.mdx new file mode 100644 index 0000000000..9f27706c0d --- /dev/null +++ b/documentation/docs/pages/developers/index.mdx @@ -0,0 +1,7 @@ +# Introduction +Nym's developer documentation covering core concepts of integrating with the Mixnet, interacting with the Nyx blockchain, an overview of the avaliable tools, and our SDK docs. + +## Where to Start? +If you are completely new to Nym, it is suggested to start with the top sections covering the core concepts, integration options, and the clients and tools available to you. + +If you feel like starting with more practical examples, check out the relevent SDK docs in the sidebar to the left. diff --git a/documentation/docs/pages/developers/integrations.mdx b/documentation/docs/pages/developers/integrations.mdx new file mode 100644 index 0000000000..1cc836a296 --- /dev/null +++ b/documentation/docs/pages/developers/integrations.mdx @@ -0,0 +1,41 @@ +import Box from '@mui/material/Box'; +import { Steps } from 'nextra/components' +import { Tabs } from 'nextra/components' +import { GitHubRepoSearch } from '../../code-snippets/mixfetchurl'; + +# Integration Options +Developers might want to either integrate a Mixnet client or just to interact with the blockchain. See the relevant section below. + +### Integrating Mixnet Functionality +There are several options available to developers wanting to embed a Nym client in their application code. + + + + <> + + Rust developers can rely on our Rust SDK to import Nym client functionality into their code. This can either be in the form of a standard message-based client, the `socks5` client, or the `TcpProxy` modules. + + We aim to expose at least the majority of this functionality via FFI to Go and C/C++. This is detailed alongside the Rust SDK components in the [Rust SDK docs](./rust). + + + + + <> + + Typescript and Javascript developers have several options avaliable to them: + - [`mixfetch`](./typescript/examples/mix-fetch) is an almost-dropin replacement for the `fetch` library. The best way to integrate Nym's `mixFetch` into your application will be where external network calls and RPC happens, for example, something in the lines of `sendRawTransaction` if you have an ETH-compatible wallet or `JsonRpcClient` if you use CosmJS. Although you can simply search for any JS `fetch` calls in your code (using our tool below) that are easily replaceable with `mixFetch`, keep in mind that `fetch` is not the only way to make `JSONRPC` or `XHR` calls. We advise to approach the integration process in a semantic way, searching for a module that is the common denominator for external communication in the codebase. Usually these are API controllers, middlewares or repositories. + + + + - Otherwise, a well-modularized JS/TS codebase should permit the integration of one of our other SDK components, which will allow more flexibility and control (or if your codebase is not using something that can be covered by `fetch` for networking). Read more about our different SDK components in the [TS SDK overview page](./typescript/overview). + + + + If your app is not written in any of the supported languages, you might still be able to send traffic through a standalone [socks5 client](./clients/socks5) but will have to think about packaging and bundling the client binary with e.g. a `systemd` file for autostart to run the client as a daemon. If you want to discuss FFI options reach out to us via our public dev channel. + + +### Interacting with Nyx + +If instead of relying on the Mixnet you wish to interact with the Nyx chain, either as a payment processor or to get on-chain events, see [interacting with the chain](./chain). + +> Note that depending on your setup, you might already be able to combine interacting with the chain with using the Mixnet: check the options above for more. diff --git a/documentation/dev-portal/src/licensing.md b/documentation/docs/pages/developers/licensing.md similarity index 100% rename from documentation/dev-portal/src/licensing.md rename to documentation/docs/pages/developers/licensing.md diff --git a/documentation/docs/pages/developers/rust.md b/documentation/docs/pages/developers/rust.md new file mode 100644 index 0000000000..eb2e7bf459 --- /dev/null +++ b/documentation/docs/pages/developers/rust.md @@ -0,0 +1,7 @@ +# Introduction +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. + +Check the [development status](./rust/development-status) page to see the various modules that make up the SDK, and the [FFI](./rust/ffi) page for Go/C++ developers. + +### 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/pages/developers/rust/_meta.json b/documentation/docs/pages/developers/rust/_meta.json new file mode 100644 index 0000000000..3fca1da31f --- /dev/null +++ b/documentation/docs/pages/developers/rust/_meta.json @@ -0,0 +1,8 @@ +{ + "importing": "Importing", + "development-status": "Development Status", + "mixnet": "Mixnet Module", + "tcpproxy": "TcpProxy Module", + "ffi": "FFI", + "tutorials": "Tutorials (Coming Soon)" +} diff --git a/documentation/docs/pages/developers/rust/development-status.md b/documentation/docs/pages/developers/rust/development-status.md new file mode 100644 index 0000000000..71ec96057c --- /dev/null +++ b/documentation/docs/pages/developers/rust/development-status.md @@ -0,0 +1,15 @@ +# Development status +The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases. + +In the future the SDK will be made up of several modules, each of which will allow developers to interact with different parts of Nym infrastructure. + +| Module | Functionality | Released | +|-----------|---------------------------------------------------------------------------------------|----------| +| Mixnet | Create / load clients & keypairs, subscribe to Mixnet events, send & receive messages | ✔️ | +| TcpProxy | Utilise the TcpProxyClient and TcpProxyServer abstractions for streaming | ✔️ | +| Ecash | Create & verify Ecash credentials | ❌ | +| Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain | ❌ | + +The `Mixnet` module currently exposes the logic of two clients: the [websocket client](../clients/websocket), and the [socks client](../clients/socks5). + +The `TcpProxy` module exposes functionality to set up client/server instances that expose a localhost TcpSocket to read/write to. diff --git a/documentation/docs/pages/developers/rust/ffi.mdx b/documentation/docs/pages/developers/rust/ffi.mdx new file mode 100644 index 0000000000..0f4aba8fa0 --- /dev/null +++ b/documentation/docs/pages/developers/rust/ffi.mdx @@ -0,0 +1,60 @@ +import { Callout } from 'nextra/components' + +# FFI Bindings + + + We are working on the intitial versions of the FFI code to allow developers to experiment and get feedback. Please get in touch if you think the FFI bindings are lacking certain functionality. + + +We currently have FFI bindings for Go and C/C++. See the table below to check the coverage of functionality we expect devs would like to see. + +The [`nym/sdk/ffi`](https://github.com/nymtech/nym/tree/master/sdk/ffi) directory has the following structure: + +``` +ffi +├── cpp +├── go +├── README.md +└── shared +``` + +The main functionality of exposed functions will be imported from `sdk/ffi/shared` into `sdk/ffi/` in order to cut down on code duplication, and so that the imported bindings can be language-specific with regards to types and any `unsafe` code that is required, as well as allowing for the use of language-specific FFI libraries in the future (e.g. we are using `uniffi-bindgen-go` for Go, and at the moment have custom C/C++ bindings, which we might in the future replace with `cxx`). + +Furthermore, the `shared/` code makes sure that client access is thread-safe, and that client actions happen in blocking threads on the Rust side of the FFI boundary. + +### Mixnet Module +This is the basic mixnet component of the SDK, exposing client functionality with which people can build custom interfaces with the Mixnet. These functions are exposed to both Go and C/C++ via the `sdk/ffi/shared/` crate. + +| `shared/lib.rs` function | Rust Function | +| ------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `init_ephemeral_internal()` | `MixnetClient::connect_new()` | +| `init_default_storage_internal(config_dir: PathBuf)` | `MixnetClientBuilder::new_with_default_storage(config_dir)` | +| `get_self_address_internal()` | `MixnetClient.nym_address()` | +| `send_message_internal(recipient: Recipient, message: &str)` | `MixnetClient.send_plain_message(recipient, message)` | +| `reply_internal(recipient: AnonymousSenderTag, message: &str)`| `MixnetClient.send_reply(recipient, message)` | + + +> We have also implemented `listen_for_incoming_internal()` which is a wrapper around the Mixnet client's `wait_for_messages()`. This is a helper method for listening out for and handling incoming messages. + +#### Currently Unsupported Functionality +At the time of writing the following functionality is not exposed to the shared FFI library: +- `split_sender()`: the ability to [split a client into sender and receiver](./mixnet/examples/split-send) for concurrent send/receive. +- The use of [custom network topologies](./mixnet/examples/custom-topology). +- `Socks5::new()`: creation and use of the [socks5/4a/4 proxy client](./mixnet/examples/socks). + +### TcpProxy Module +A connection abstraction which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the [message-based](../concepts/messages) format of the underlying client. + + + At the time of writing this functionality is **only** exposed to Go. C/C++ bindings will follow in the future in a larger update to the C FFI. + + + +| `shared/lib.rs` function | Rust Function | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| `proxy_client_new_internal(server_address: Recipient, listen_address: &str, listen_port: &str, close_timeout: u64, env: Option)`| `NymProxyClient::new(server_address, listen_address, listen_port, close_timeout, env)`| +| `proxy_client_new_defaults_internal(server_address, env)` | `NymProxyClient::new_with_defaults(server_address, env)` | +| `proxy_client_run_internal()` | `NymProxyClient.run()` | +| `proxy_server_new_internal(upstream_address: &str, config_dir: &str, env: Option)` | `NymProxyServer::new(upstream_address, config_dir, env)` | +| `proxy_server_run_internal()` | `NymProxyServer.run_with_shutdown()` | +| `proxy_server_address_internal()` | `NymProxyServer.nym_address()` | diff --git a/documentation/docs/pages/developers/rust/importing.md b/documentation/docs/pages/developers/rust/importing.md new file mode 100644 index 0000000000..7a4c9cf918 --- /dev/null +++ b/documentation/docs/pages/developers/rust/importing.md @@ -0,0 +1,11 @@ +# 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. 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. + +```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" } +``` + +Work will occur in the future to break the monorepo down into importable features, in order to reduce the number of dependencies imported by developers. diff --git a/documentation/docs/pages/developers/rust/mixnet.mdx b/documentation/docs/pages/developers/rust/mixnet.mdx new file mode 100644 index 0000000000..a6e6621413 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet.mdx @@ -0,0 +1,5 @@ +# Mixnet Module + +This module exposes the logic of creating and interacting with clients and Mixnet messages. This is recommended for those wanting to either start playing around with the Mixnet and how it works, or build connection logic. + +> For developers wanting something more 'plug and play' we recommend the [`TcpProxy` module](./tcpproxy). diff --git a/documentation/docs/pages/developers/rust/mixnet/_meta.json b/documentation/docs/pages/developers/rust/mixnet/_meta.json new file mode 100644 index 0000000000..4797072ab7 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/_meta.json @@ -0,0 +1,6 @@ +{ + "examples": "Basic Examples", + "message-helpers": "Message Helpers", + "message-types": "Message Types", + "troubleshooting": "Troubleshooting" +} diff --git a/documentation/dev-portal/src/sdk/rust/examples.md b/documentation/docs/pages/developers/rust/mixnet/examples.md similarity index 75% rename from documentation/dev-portal/src/sdk/rust/examples.md rename to documentation/docs/pages/developers/rust/mixnet/examples.md index 648c32fa0d..9bac32f1b1 100644 --- a/documentation/dev-portal/src/sdk/rust/examples.md +++ b/documentation/docs/pages/developers/rust/mixnet/examples.md @@ -1,12 +1,9 @@ # Examples -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: +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 +```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 [here](examples/cargo.md). - +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. diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/_meta.json new file mode 100644 index 0000000000..14d6bc6ff6 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/_meta.json @@ -0,0 +1,10 @@ +{ + "simple": "Simple Send", + "builders": "Builder Patterns", + "testnet": "Configurable Network", + "custom-topology": "Custom Network Topologies", + "split-send": "Concurrent Send & Receive", + "socks": "Socks Proxy", + "storage": "Manually Handle Storage", + "surbs": "Anonymous Replies" +} diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/builders.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders.md new file mode 100644 index 0000000000..ff837d33f1 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/builders.md @@ -0,0 +1,3 @@ +# Builder Patterns + +Since there are two ways of creating an SDK client - ephemeral and with-storage - then there are two ways of applying the Builder Pattern to client creation. diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/builders/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/builders/_meta.json new file mode 100644 index 0000000000..778b1bce9d --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/builders/_meta.json @@ -0,0 +1,4 @@ +{ + "builder": "Ephemeral", + "builder-with-storage": "With Storage" +} diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder-with-storage.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder-with-storage.md new file mode 100644 index 0000000000..88ecf42085 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder-with-storage.md @@ -0,0 +1,72 @@ +# Mixnet Client Builder with Storage + +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. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder_with_storage.rs). + +```rust +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; +use std::path::PathBuf; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Specify some config options + let config_dir = PathBuf::from("/tmp/mixnet-client"); + let storage_paths = mixnet::StoragePaths::new_from_dir(&config_dir).unwrap(); + + // Create the client with a storage backend, and enable it by giving it some paths. If keys + // exists at these paths, they will be loaded, otherwise they will be generated. + let client = mixnet::MixnetClientBuilder::new_with_default_storage(storage_paths) + .await + .unwrap() + .build() + .unwrap(); + + // Now we connect to the mixnet, using keys now stored in the paths provided. + let mut client = client.connect_to_mixnet().await.unwrap(); + + // Be able to get our client address + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send a message throught the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message"); + if let Some(received) = client.wait_for_messages().await { + for r in received { + println!("Received: {}", String::from_utf8_lossy(&r.message)); + } + } + + client.disconnect().await; +} +``` + +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/pages/developers/rust/mixnet/examples/builders/builder.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder.md new file mode 100644 index 0000000000..1dc8da6701 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder.md @@ -0,0 +1,43 @@ +# Mixnet Client Builder + +You can spin up an ephemeral client like so. This client will not have a persistent identity and its keys will be dropped on restart. Since there is currently no way of reconnecting a client that has been disconnected after use, then treat disconnecting a client the same as dropping its keys entirely. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/builder.rs). + +```rust +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Create client builder, including ephemeral keys. The builder can be usable in the context + // where you don't want to connect just yet. + let client = mixnet::MixnetClientBuilder::new_ephemeral() + .build() + .unwrap(); + + // Now we connect to the mixnet, using ephemeral keys already created + let mut client = client.connect_to_mixnet().await.unwrap(); + + // Be able to get our client address + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send a message through the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message"); + if let Some(received) = client.wait_for_messages().await { + for r in received { + println!("Received: {}", String::from_utf8_lossy(&r.message)); + } + } + + client.disconnect().await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology.mdx b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology.mdx new file mode 100644 index 0000000000..1985900b06 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology.mdx @@ -0,0 +1,17 @@ +# Importing and using a custom network topology + +import { Callout } from 'nextra/components' + + + These examples are **not** the same as using a configurable network: these functions define a subset of nodes to use on a given network, whereas the [testnet](./testnet) example is an example of switching to use a different network entirely. The two can be combined, but if you are looking for how to connect your client to a testnet, see the `testnet` file. + + +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). + +There are two ways to do this: + +## Custom Topology Provider +If you are also running a Validator and Nym API for your network, you can specify that endpoint. Clients will then use this endpoint to grab a network topology on startup. You can also use this to specify using a testnet. + +## 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 also overwrite the grabbed topology manually. diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/_meta.json new file mode 100644 index 0000000000..6d62d318f1 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/_meta.json @@ -0,0 +1,4 @@ +{ + "custom-provider": "Custom Topology Provider", + "manual-topology": "Manually Overwrite Topology" +} diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/custom-provider.md b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/custom-provider.md new file mode 100644 index 0000000000..40b4a87f91 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/custom-provider.md @@ -0,0 +1,89 @@ +# Custom Topology Provider + +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). + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/custom_topology_provider.rs) + +```rust +// Copyright 2023 - Nym Technologies SA +// SPDX-License-Identifier: Apache-2.0 + +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; +use nym_topology::provider_trait::{async_trait, TopologyProvider}; +use nym_topology::{nym_topology_from_detailed, NymTopology}; +use url::Url; + +struct MyTopologyProvider { + validator_client: nym_validator_client::client::NymApiClient, +} + +impl MyTopologyProvider { + fn new(nym_api_url: Url) -> MyTopologyProvider { + MyTopologyProvider { + validator_client: nym_validator_client::client::NymApiClient::new(nym_api_url), + } + } + + async fn get_topology(&self) -> NymTopology { + let mixnodes = self + .validator_client + .get_cached_active_mixnodes() + .await + .unwrap(); + + // in our topology provider only use mixnodes that have mix_id divisible by 3 + // and have more than 100k nym (i.e. 100'000'000'000 unym) in stake + // why? because this is just an example to showcase arbitrary uses and capabilities of this trait + let filtered_mixnodes = mixnodes + .into_iter() + .filter(|mix| { + mix.mix_id() % 3 == 0 && mix.total_stake() > "100000000000".parse().unwrap() + }) + .collect::>(); + + let gateways = self.validator_client.get_cached_gateways().await.unwrap(); + + nym_topology_from_detailed(filtered_mixnodes, gateways) + } +} + +#[async_trait] +impl TopologyProvider for MyTopologyProvider { + // this will be manually refreshed on a timer specified inside mixnet client config + async fn get_new_topology(&mut self) -> Option { + Some(self.get_topology().await) + } +} + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + let nym_api = "https://validator.nymtech.net/api/".parse().unwrap(); + let my_topology_provider = MyTopologyProvider::new(nym_api); + + // Passing no config makes the client fire up an ephemeral session and figure things out on its own + let mut client = mixnet::MixnetClientBuilder::new_ephemeral() + .custom_topology_provider(Box::new(my_topology_provider)) + .build() + .unwrap() + .connect_to_mixnet() + .await + .unwrap(); + + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send a message through the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message (ctrl-c to exit)"); + client + .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message))) + .await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/manually-overwrite-topology.md b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/manually-overwrite-topology.md new file mode 100644 index 0000000000..dd150ad35b --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/manually-overwrite-topology.md @@ -0,0 +1,102 @@ +# Manually Overwrite Topology + +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. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_overwrite_topology.rs) + +```rust +// Copyright 2023 - Nym Technologies SA +// SPDX-License-Identifier: Apache-2.0 + +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; +use nym_topology::mix::Layer; +use nym_topology::{mix, NymTopology}; +use std::collections::BTreeMap; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Passing no config makes the client fire up an ephemeral session and figure shit out on its own + let mut client = mixnet::MixnetClient::connect_new().await.unwrap(); + let starting_topology = client.read_current_topology().await.unwrap(); + + // but we don't like our default topology, we want to use only those very specific, hardcoded, nodes: + let mut mixnodes = BTreeMap::new(); + mixnodes.insert( + 1, + vec![mix::Node { + mix_id: 63, + owner: None, + host: "172.105.92.48".parse().unwrap(), + mix_host: "172.105.92.48:1789".parse().unwrap(), + identity_key: "GLdR2NRVZBiCoCbv4fNqt9wUJZAnNjGXHkx3TjVAUzrK" + .parse() + .unwrap(), + sphinx_key: "CBmYewWf43iarBq349KhbfYMc9ys2ebXWd4Vp4CLQ5Rq" + .parse() + .unwrap(), + layer: Layer::One, + version: "1.1.0".into(), + }], + ); + mixnodes.insert( + 2, + vec![mix::Node { + mix_id: 23, + owner: None, + host: "178.79.143.65".parse().unwrap(), + mix_host: "178.79.143.65:1789".parse().unwrap(), + identity_key: "4Yr4qmEHd9sgsuQ83191FR2hD88RfsbMmB4tzhhZWriz" + .parse() + .unwrap(), + sphinx_key: "8ndjk5oZ6HxUZNScLJJ7hk39XtUqGexdKgW7hSX6kpWG" + .parse() + .unwrap(), + layer: Layer::Two, + version: "1.1.0".into(), + }], + ); + mixnodes.insert( + 3, + vec![mix::Node { + mix_id: 66, + owner: None, + host: "139.162.247.97".parse().unwrap(), + mix_host: "139.162.247.97:1789".parse().unwrap(), + identity_key: "66UngapebhJRni3Nj52EW1qcNsWYiuonjkWJzHFsmyYY" + .parse() + .unwrap(), + sphinx_key: "7KyZh8Z8KxuVunqytAJ2eXFuZkCS7BLTZSzujHJZsGa2" + .parse() + .unwrap(), + layer: Layer::Three, + version: "1.1.0".into(), + }], + ); + + // but we like the available gateways, so keep using them! + // (we like them because the author of this example is too lazy to use the same hardcoded gateway + // during client initialisation to make sure we are able to send to ourselves : ) ) + let custom_topology = NymTopology::new(mixnodes, starting_topology.gateways().to_vec()); + + client.manually_overwrite_topology(custom_topology).await; + + // and everything we send now should only ever go via those nodes + + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send a message through the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message (ctrl-c to exit)"); + client + .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message))) + .await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/simple.md b/documentation/docs/pages/developers/rust/mixnet/examples/simple.md new file mode 100644 index 0000000000..9df473686f --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/simple.md @@ -0,0 +1,34 @@ +# 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. + +Simply importing the `nym_sdk` crate into your project allows you to create a client and send traffic through the mixnet. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/simple.rs) + +```rust +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Passing no config makes the client fire up an ephemeral session and figure shit out on its own + let mut client = mixnet::MixnetClient::connect_new().await.unwrap(); + + // Be able to get our client address + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send a message through the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message (ctrl-c to exit)"); + client + .on_messages(|msg| println!("Received: {}", String::from_utf8_lossy(&msg.message))) + .await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/socks.md b/documentation/docs/pages/developers/rust/mixnet/examples/socks.md new file mode 100644 index 0000000000..01ff848513 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/socks.md @@ -0,0 +1,48 @@ +# Socks Proxy + +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. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/socks5.rs) + +```rust +use nym_sdk::mixnet; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + println!("Connecting receiver"); + let mut receiving_client = mixnet::MixnetClient::connect_new().await.unwrap(); + + let socks5_config = mixnet::Socks5::new(receiving_client.nym_address().to_string()); + let sending_client = mixnet::MixnetClientBuilder::new_ephemeral() + .socks5_config(socks5_config) + .build() + .unwrap(); + + println!("Connecting sender"); + let sending_client = sending_client.connect_to_mixnet_via_socks5().await.unwrap(); + + let proxy = reqwest::Proxy::all(sending_client.socks5_url()).unwrap(); + let reqwest_client = reqwest::Client::builder().proxy(proxy).build().unwrap(); + tokio::spawn(async move { + println!("Sending socks5-wrapped http request"); + // Message should be sent through the mixnet, via socks5 + // We don't expect to get anything, as there is no network requester on the other end + reqwest_client.get("https://nymtech.net").send().await.ok() + }); + + println!("Waiting for message"); + if let Some(received) = receiving_client.wait_for_messages().await { + for r in received { + println!( + "Received socks5 message requesting for endpoint: {}", + String::from_utf8_lossy(&r.message[10..27]) + ); + } + } + + receiving_client.disconnect().await; + sending_client.disconnect().await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/split-send.md b/documentation/docs/pages/developers/rust/mixnet/examples/split-send.md new file mode 100644 index 0000000000..b01e3a133b --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/split-send.md @@ -0,0 +1,49 @@ +# 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. You can think of this analogously to spliting a Tcp Stream into read/write. This functionality is also useful for embedding a sending and receiving client into different tasks. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/parallel_sending_and_receiving.rs) + +```rust +// Copyright 2023 - Nym Technologies SA +// SPDX-License-Identifier: Apache-2.0 + +use futures::StreamExt; +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Passing no config makes the client fire up an ephemeral session and figure stuff out on its own + let mut client = mixnet::MixnetClient::connect_new().await.unwrap(); + + // Be able to get our client address + let our_address = *client.nym_address(); + println!("Our client nym address is: {our_address}"); + + let sender = client.split_sender(); + + // receiving task + let receiving_task_handle = tokio::spawn(async move { + if let Some(received) = client.next().await { + println!("Received: {}", String::from_utf8_lossy(&received.message)); + } + + client.disconnect().await; + }); + + // sending task + let sending_task_handle = tokio::spawn(async move { + sender + .send_plain_message(our_address, "hello from a different task!") + .await + .unwrap(); + }); + + // wait for both tasks to be done + println!("waiting for shutdown"); + sending_task_handle.await.unwrap(); + receiving_task_handle.await.unwrap(); +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/storage.md b/documentation/docs/pages/developers/rust/mixnet/examples/storage.md new file mode 100644 index 0000000000..7d82ce2993 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/storage.md @@ -0,0 +1,226 @@ +# Manually Handle 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 these actions. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/manually_handle_storage.rs) + +```rust +use nym_sdk::mixnet::{ + self, ActiveGateway, BadGateway, ClientKeys, EmptyReplyStorage, EphemeralCredentialStorage, + GatewayRegistration, GatewaysDetailsStore, KeyStore, MixnetClientStorage, MixnetMessageSender, +}; +use nym_topology::provider_trait::async_trait; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Just some plain data to pretend we have some external storage that the application + // implementer is using. + let mock_storage = MockClientStorage::empty(); + let mut client = mixnet::MixnetClientBuilder::new_with_storage(mock_storage) + .build() + .unwrap() + .connect_to_mixnet() + .await + .unwrap(); + + // Be able to get our client address + let our_address = client.nym_address(); + println!("Our client nym address is: {our_address}"); + + // Send important info up the pipe to a buddy + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + println!("Waiting for message"); + if let Some(received) = client.wait_for_messages().await { + for r in received { + println!("Received: {}", String::from_utf8_lossy(&r.message)); + } + } + + client.disconnect().await; +} + +#[allow(unused)] +struct MockClientStorage { + pub key_store: MockKeyStore, + pub gateway_details_store: MockGatewayDetailsStore, + pub reply_store: EmptyReplyStorage, + pub credential_store: EphemeralCredentialStorage, +} + +impl MockClientStorage { + fn empty() -> Self { + Self { + key_store: MockKeyStore, + gateway_details_store: MockGatewayDetailsStore, + reply_store: EmptyReplyStorage::default(), + credential_store: EphemeralCredentialStorage::default(), + } + } +} + +impl MixnetClientStorage for MockClientStorage { + type KeyStore = MockKeyStore; + type ReplyStore = EmptyReplyStorage; + type CredentialStore = EphemeralCredentialStorage; + type GatewaysDetailsStore = MockGatewayDetailsStore; + + fn into_runtime_stores(self) -> (Self::ReplyStore, Self::CredentialStore) { + (self.reply_store, self.credential_store) + } + + fn key_store(&self) -> &Self::KeyStore { + &self.key_store + } + + fn reply_store(&self) -> &Self::ReplyStore { + &self.reply_store + } + + fn credential_store(&self) -> &Self::CredentialStore { + &self.credential_store + } + + fn gateway_details_store(&self) -> &Self::GatewaysDetailsStore { + &self.gateway_details_store + } +} + +struct MockKeyStore; + +#[async_trait] +impl KeyStore for MockKeyStore { + type StorageError = MyError; + + async fn load_keys(&self) -> Result { + println!("loading stored keys"); + + Err(MyError) + } + + async fn store_keys(&self, _keys: &ClientKeys) -> Result<(), Self::StorageError> { + println!("storing keys"); + + Ok(()) + } +} + +struct MockGatewayDetailsStore; + +#[async_trait] +impl GatewaysDetailsStore for MockGatewayDetailsStore { + type StorageError = MyError; + + async fn active_gateway(&self) -> Result { + println!("getting active gateway"); + + Err(MyError) + } + + async fn set_active_gateway(&self, _gateway_id: &str) -> Result<(), Self::StorageError> { + println!("setting active gateway"); + + Ok(()) + } + + async fn all_gateways(&self) -> Result, Self::StorageError> { + println!("getting all registered gateways"); + + Err(MyError) + } + + async fn has_gateway_details(&self, _gateway_id: &str) -> Result { + println!("checking for gateway details"); + + Err(MyError) + } + + async fn load_gateway_details( + &self, + _gateway_id: &str, + ) -> Result { + println!("loading gateway details"); + + Err(MyError) + } + + async fn store_gateway_details( + &self, + _details: &GatewayRegistration, + ) -> Result<(), Self::StorageError> { + println!("storing gateway details"); + + Ok(()) + } + + async fn remove_gateway_details(&self, _gateway_id: &str) -> Result<(), Self::StorageError> { + println!("removing gateway details"); + + Ok(()) + } +} + +// +// struct MockReplyStore; +// +// #[async_trait] +// impl ReplyStorageBackend for MockReplyStore { +// type StorageError = MyError; +// +// async fn flush_surb_storage( +// &mut self, +// _storage: &CombinedReplyStorage, +// ) -> Result<(), Self::StorageError> { +// todo!() +// } +// +// async fn init_fresh(&mut self, _fresh: &CombinedReplyStorage) -> Result<(), Self::StorageError> { +// todo!() +// } +// +// async fn load_surb_storage(&self) -> Result { +// todo!() +// } +// } +// +// struct MockCredentialStore; +// +// #[async_trait] +// impl CredentialStorage for MockCredentialStore { +// type StorageError = MyError; +// +// async fn insert_coconut_credential( +// &self, +// _voucher_value: String, +// _voucher_info: String, +// _serial_number: String, +// _binding_number: String, +// _signature: String, +// _epoch_id: String, +// ) -> Result<(), Self::StorageError> { +// todo!() +// } +// +// async fn get_next_coconut_credential(&self) -> Result { +// todo!() +// } +// +// async fn consume_coconut_credential(&self, id: i64) -> Result<(), Self::StorageError> { +// todo!() +// } +// } + +#[derive(thiserror::Error, Debug)] +#[error("foobar")] +struct MyError; + +impl From for MyError { + fn from(_: BadGateway) -> Self { + MyError + } +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/surbs.md b/documentation/docs/pages/developers/rust/mixnet/examples/surbs.md new file mode 100644 index 0000000000..ab8d9abb79 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/surbs.md @@ -0,0 +1,83 @@ +# 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. + +You can read more about how SURBs function under the hood [here](../../../../network/traffic/anonymous-replies). + +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. + +> You can find this code [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/examples/surb_reply.rs) + +```rust +use nym_sdk::mixnet::{ + AnonymousSenderTag, MixnetClientBuilder, MixnetMessageSender, ReconstructedMessage, + StoragePaths, +}; +use std::path::PathBuf; + +#[tokio::main] +async fn main() { + nym_bin_common::logging::setup_logging(); + + // Specify some config options + let config_dir = PathBuf::from("/tmp/surb-example"); + let storage_paths = StoragePaths::new_from_dir(&config_dir).unwrap(); + + // Create the client with a storage backend, and enable it by giving it some paths. If keys + // exists at these paths, they will be loaded, otherwise they will be generated. + let client = MixnetClientBuilder::new_with_default_storage(storage_paths) + .await + .unwrap() + .build() + .unwrap(); + + // Now we connect to the mixnet, using keys now stored in the paths provided. + let mut client = client.connect_to_mixnet().await.unwrap(); + + // Be able to get our client address + let our_address = client.nym_address(); + println!("\nOur client nym address is: {our_address}"); + + // Send a message through the mixnet to ourselves using our nym address + client + .send_plain_message(*our_address, "hello there") + .await + .unwrap(); + + // we're going to parse the sender_tag (AnonymousSenderTag) from the incoming message and use it to 'reply' to ourselves instead of our Nym address. + // we know there will be a sender_tag since the sdk sends SURBs along with messages by default. + println!("Waiting for message\n"); + + // get the actual message - discard the empty vec sent along with a potential SURB topup request + let mut message: Vec = Vec::new(); + while let Some(new_message) = client.wait_for_messages().await { + if new_message.is_empty() { + continue; + } + message = new_message; + break; + } + + let mut parsed = String::new(); + if let Some(r) = message.first() { + parsed = String::from_utf8(r.message.clone()).unwrap(); + } + // parse sender_tag: we will use this to reply to sender without needing their Nym address + let return_recipient: AnonymousSenderTag = message[0].sender_tag.unwrap(); + println!( + "\nReceived the following message: {} \nfrom sender with surb bucket {}", + parsed, return_recipient + ); + + // reply to self with it: note we use `send_str_reply` instead of `send_str` + println!("Replying with using SURBs"); + client + .send_reply(return_recipient, "hi an0n!") + .await + .unwrap(); + + println!("Waiting for message (once you see it, ctrl-c to exit)\n"); + client + .on_messages(|msg| println!("\nReceived: {}", String::from_utf8_lossy(&msg.message))) + .await; +} +``` diff --git a/documentation/docs/pages/developers/rust/mixnet/examples/testnet.mdx b/documentation/docs/pages/developers/rust/mixnet/examples/testnet.mdx new file mode 100644 index 0000000000..78112c7b54 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/examples/testnet.mdx @@ -0,0 +1,44 @@ +# Configurable Network + +If you want to connect your Mixnet client to a different network than Mainnet, simply pull in a file from [`nym/envs`](https://github.com/nymtech/nym/tree/master/envs) as such: + +```rust +use futures::StreamExt; +use nym_network_defaults::setup_env; +use nym_sdk::mixnet; +use nym_sdk::mixnet::MixnetMessageSender; + +// An example of creating a client relying on a testnet, in this case Sandbox. +#[tokio::main] +async fn main() -> anyhow::Result<()> { + nym_bin_common::logging::setup_logging(); + // relative root is `sdk/rust/nym-sdk/` for fallback file path + let env_path = + std::env::var("NYM_ENV_PATH").unwrap_or_else(|_| "../../../envs/sandbox.env".to_string()); + setup_env(Some(&env_path)); + let sandbox_network = mixnet::NymNetworkDetails::new_from_env(); + + let mixnet_client = mixnet::MixnetClientBuilder::new_ephemeral() + .network_details(sandbox_network) + .build()?; + + let mut client = mixnet_client.connect_to_mixnet().await?; + + let our_address = client.nym_address(); + + // Send a message throughout the mixnet to ourselves + client + .send_plain_message(*our_address, "hello there") + .await?; + + println!("Waiting for message"); + if let Some(received) = client.next().await { + println!("Received: {}", String::from_utf8_lossy(&received.message)); + } else { + eprintln!("Failed to receive message."); + } + + client.disconnect().await; + Ok(()) +} +``` diff --git a/documentation/dev-portal/src/sdk/rust/message-helpers.md b/documentation/docs/pages/developers/rust/mixnet/message-helpers.md similarity index 63% rename from documentation/dev-portal/src/sdk/rust/message-helpers.md rename to documentation/docs/pages/developers/rust/mixnet/message-helpers.md index e7ce201fa7..2d2b550f86 100644 --- a/documentation/dev-portal/src/sdk/rust/message-helpers.md +++ b/documentation/docs/pages/developers/rust/mixnet/message-helpers.md @@ -1,10 +1,10 @@ # 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 (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): +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#client-receives-empty-messages-when-listening-for-response). This can be done with something like the helper functions here: ```rust -use nym_sdk::mixnet::ReconstructedMessage; +use nym_sdk::mixnet::ReconstructedMessage; pub async fn wait_for_non_empty_message( client: &mut MixnetClient, @@ -14,7 +14,7 @@ pub async fn wait_for_non_empty_message( return Ok(new_message.pop().unwrap()); } } - + bail!("did not receive any non-empty message") } @@ -23,9 +23,9 @@ pub fn handle_response(message: ReconstructedMessage) -> anyhow::Result anyhow::Result<(RequestTypes, Option)> { @@ -34,21 +34,19 @@ pub fn handle_request( } ``` -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): +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 +// 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 +// Await a non-empty message let received = wait_for_non_empty_message(client).await?; -// Handle the response received (the non-empty message awaited above) +// Handle the response received (the non-empty message awaited above) let sp_response = handle_response(received)?; // Match JSON -> ResponseType @@ -58,13 +56,10 @@ let res = match sp_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. +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](./examples/split-send) 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. +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, so needs to gracefully shutdown. diff --git a/documentation/docs/pages/developers/rust/mixnet/message-types.md b/documentation/docs/pages/developers/rust/mixnet/message-types.md new file mode 100644 index 0000000000..833b1cc3fc --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/message-types.md @@ -0,0 +1,20 @@ +# Message Types + +There are several functions used to send outgoing messages through the Mixnet, each with a different level of customisation: + +- `send(&self, message: InputMessage) -> Result<()>` +Sends a `InputMessage` to the mixnet. This is the most low-level sending function, for full customization. Called by `send_message()`. + +- `send_message(&self, address: Recipient, message: M, surbs: IncludedSurbs) -> Result<()>` +Sends bytes to the supplied Nym address. There is the option to specify the number of reply-SURBs to include. Called by `send_plain_message()`. + +- `send_plain_message(&self, address: Recipient, message: M) -> Result<()>` +Sends data to the supplied Nym address with the default surb behaviour. + +> Note we specify *outgoing* messages above: this is because the SDK assumes that replies will be anonymous via [SURBs](../../../network/traffic/anonymous-replies). + +Replies rely on the creation of an `AnonymousSenderTag` by parsing and storing the `sender_tag` from incoming messages, and using this to reply, instead of the `Receipient` type used by the functions outlined above: + +`send_reply(&self, recipient_tag: AnonymousSenderTag, message: M) -> Result<()>` will send the reply message to the supplied anonymous recipient. + +> You can find all of the function definitions [here](https://github.com/nymtech/nym/blob/master/sdk/rust/nym-sdk/src/mixnet/traits.rs). diff --git a/documentation/dev-portal/src/sdk/rust/troubleshooting.md b/documentation/docs/pages/developers/rust/mixnet/troubleshooting.md similarity index 79% rename from documentation/dev-portal/src/sdk/rust/troubleshooting.md rename to documentation/docs/pages/developers/rust/mixnet/troubleshooting.md index 458a4eaab4..06bba32f6d 100644 --- a/documentation/dev-portal/src/sdk/rust/troubleshooting.md +++ b/documentation/docs/pages/developers/rust/mixnet/troubleshooting.md @@ -1,40 +1,39 @@ # Troubleshooting -Below are several common issues or questions you may have. +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). +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. +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. +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/master/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 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 +cargo run --example builder ``` Becomes: -```sh -RUST_LOG=warn cargo run --example builder +```sh +RUST_LOG=warn cargo run --example builder ``` -You can also make the logging _more_ verbose with: +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. +### 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. +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 @@ -59,7 +58,7 @@ note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace 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: +Using the following piece of code as an example: ```rust use nym_sdk::mixnet::{MixnetClient, MixnetMessageSender, Recipient}; @@ -87,29 +86,29 @@ async fn main() { } ``` -This is a simplified snippet of code for sending a simple hardcoded message with the following command: +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. +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. +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. +**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). +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. +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. +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. +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](../../../network/traffic/anonymous-replies) - 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. +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. +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 +> If you can think of a more succinct or different way of handling this do reach out - we're happy to hear other opinions diff --git a/documentation/docs/pages/developers/rust/tcpproxy.mdx b/documentation/docs/pages/developers/rust/tcpproxy.mdx new file mode 100644 index 0000000000..e4bfac03b1 --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy.mdx @@ -0,0 +1,7 @@ +# TcpProxy Module + +This module exposes the `TcpProxyClient` and the `TcpProxyServer` which can be used to proxy traffic through the Mixnet in a way that is more familiar to developers than the methods exposed by the [`Mixnet` module](./mixnet). + +Both `Client` and `Server` are intended to be initialised and then run in a background thread, exposing a configurable `localhost` socket which developers can read/write/stream to without having to worry about the [message-based](../concepts/messages) nature of sending and receiving traffic to/from the Mixnet. + +> Non-Rust/Go developers who want to experiment with this module can start with the [standalone binaries](../tools/standalone-tcpproxy). diff --git a/documentation/docs/pages/developers/rust/tcpproxy/_meta.json b/documentation/docs/pages/developers/rust/tcpproxy/_meta.json new file mode 100644 index 0000000000..4ee4d522eb --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy/_meta.json @@ -0,0 +1,4 @@ +{ + "architecture": "Architecture", + "examples": "Examples" +} diff --git a/documentation/docs/pages/developers/rust/tcpproxy/architecture.mdx b/documentation/docs/pages/developers/rust/tcpproxy/architecture.mdx new file mode 100644 index 0000000000..862d00c90f --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy/architecture.mdx @@ -0,0 +1,208 @@ +import { Callout } from 'nextra/components' + +# Architecture + +## Motivations +The motivation behind the creation of the `TcpProxy` module is to allow developers to interact with the Mixnet in a way that is far more familiar to them: simply setting up a connection with a transport, being returned a socket, and then being able to stream data to/from it, similar to something like the Tor [`arti`](https://gitlab.torproject.org/tpo/core/arti/-/tree/main/crates/arti-client) client. + + + This is an initial version of the module which we are releasing to developers to experiment with. If you run into problems or any functionality that is missing, do reach out on Matrix and let us know. + + Furthermore we will be working on optimisations to the module over time - most of this will occur under the hood (e.g. implementing a configurable connection pool for the `ProxyClient`), but all updates will occur according to SemVer, so don't worry about breaking changes! + + +## Clients +Each of the sub-modules exposed by the `TcpProxy` deal with Nym clients in a different way. +- the `NymProxyClient` creates an ephemeral client per new TCP connection, which is closed according to the configurable timeout: we map one ephemeral client per TCP connection. This is to deal with multiple simultaneous streams. In the future, this will be superceded by a connection pool in order to speed up new connections. +- the `NymProxyServer` has a single Nym client with a persistent identity. + +## Framing +We are currently relying on the [`tokio::Bytecodec`](https://docs.rs/tokio-util/latest/tokio_util/codec/struct.BytesCodec.html) and [`framedRead`](https://docs.rs/tokio-util/latest/tokio_util/codec/struct.Framed.html) to frame bytes moving through the `NymProxyClient` and `NymProxyServer`. + +> For those interested, under the hood the client uses our own [`NymCodec`](https://github.com/nymtech/nym/blob/27ac34522cf0f8bfe1ca265e0b57ee52f2ded0d2/common/nymsphinx/framing/src/codec.rs) to frame message bytes as Sphinx packet payloads. + +## Sessions & Message Ordering +We have implemented session management and message ordering, where messages are wrapped in a session ID per connection, with individual messages being given an incrememting message ID. Once all the messages have been sent, the `NymProxyClient` then sends a `Close` message as the last outgoing message. This is to notify the `NymProxyServer` that there are no more outbound messages for this session, and that it can trigger the session timeout. + +> Session management and message IDs are necessary since *the Mixnet guarantees message delivery but not message ordering*: in the case of trying to e.g. send gRPC protobuf through the Mixnet, ordering is required so that a buffer is not split across Sphinx packet payloads, and that the 2nd half of the frame is not passed upstream to the gRPC parser before the 1st half, even if it is received first. + +Lets step through a full request/response path between a client process communicating with a remote host via the proxies: + +### Outgoing Client Request +The `NymProxyClient` instance, once initialised and running, listens out for incoming TCP connections on its localhost port. + +On receiving one, it will create a new session ID and packetise the incoming bytes into messages of the following structure: + +```rust +pub struct ProxiedMessage { + message: Payload, + session_id: Uuid, + message_id: u16, +} +``` + +> This code can be found [here](https://github.com/nymtech/nym/blob/develop/sdk/rust/nym-sdk/src/tcp_proxy/utils.rs#L147C1-L152C2) + +And then send these to the Nym address of the `NymProxyServer` instance. Not much to see here regarding message ordering, as the potential for reordering only starts once packets are travelling through the Mixnet. + +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +sequenceDiagram + box Local Machine + participant Client Process + participant NymProxyClient + end + Client Process->>NymProxyClient: Request bytes + NymProxyClient->>NymProxyClient: New session + NymProxyClient->>EntryGateway: Sphinx Packets: Message 1 + EntryGateway-->>NymProxyClient: Acks + NymProxyClient->>EntryGateway: Sphinx Packets: Message 2 + EntryGateway-->>NymProxyClient: Acks + NymProxyClient->>EntryGateway: Sphinx Packets: Message 3 + EntryGateway-->>NymProxyClient: Acks + NymProxyClient->>EntryGateway: Sphinx Packets: Close Message + NymProxyClient->>NymProxyClient: Start Client Close timeout + EntryGateway-->>NymProxyClient: Acks +``` + +### Server Receives Request & Responds + +Here is a diagrammatic representation of a situation in which the request arrives out of order, and how the message buffer deals with this so as not to pass a malformed request upstream to the process running on the same remote host: + +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +sequenceDiagram + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 2 + NymProxyServer-->>Exit Gateway: Acks + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 3 + NymProxyServer-->>Exit Gateway: Acks + loop Message Buffer + NymProxyServer->>NymProxyServer: Wait for Message 1 + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 1 + NymProxyServer-->>Exit Gateway: Acks + NymProxyServer->>NymProxyServer: Message Received: trigger upstream send + end + Note right of NymProxyServer: Note this happens **per session** + NymProxyServer->>Upstream Process: Reconstructed request bytes + Upstream Process->>Upstream Process: Do something with request + Exit Gateway->>NymProxyServer: Sphinx Packets: Message Close + NymProxyServer-->>Exit Gateway: Acks + NymProxyServer->>NymProxyServer: Trigger Client timeout start for session + Upstream Process->>NymProxyServer: Response bytes + NymProxyServer->>NymProxyServer: Write to provided SURB payloads + NymProxyServer->>Exit Gateway: Anonymous replies + + box Remote Host + participant NymProxyServer + participant Upstream Process + end +``` + +> Note that this is per-session, with a session mapped to a single TCP connection. Both the `NymProxyClient` and `Server` are able to handle multiple concurrent connections. + +### Client Receives Response + +The `ProxyClient` deals with incoming traffic in the same way as the `ProxyServer`, with a per-session message queue: + +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +sequenceDiagram + box Local Machine + participant Client Process + participant NymProxyClient + end + Entry Gateway--xNymProxyClient: Sphinx Packets: Reply Message 1 dropped: No Ack! + Entry Gateway->>NymProxyClient: Sphinx Packets: Reply Message 2 + NymProxyClient-->Entry Gateway: Ack + Entry Gateway->>NymProxyClient: Sphinx Packets: Reply Message 3 + NymProxyClient-->Entry Gateway: Ack + Loop Message Buffer: + NymProxyClient->>NymProxyClient: Wait for Message 1 + Entry Gateway->>NymProxyClient: Sphinx Packets: Message 1 + NymProxyClient-->>Entry Gateway: Acks + NymProxyClient->>NymProxyClient: Message Received: trigger send + NymProxyClient->>Client Process: Response bytes + end + Note right of NymProxyClient: Note this happens **per session** +``` + +After receiving the packets, it can then forward the recoded bytes to the requesting process. + +### Full Flow Diagram +```mermaid +--- +config: + theme: neo-dark + layout: elk +--- +sequenceDiagram + box Local Machine + participant Client Process + participant NymProxyClient + end + Client Process->>NymProxyClient: Request bytes + NymProxyClient->>NymProxyClient: New session + NymProxyClient->>Entry Gateway: Sphinx Packets: Message 1 + Entry Gateway-->>NymProxyClient: Acks + NymProxyClient->>Entry Gateway: Sphinx Packets: Message 2 + Entry Gateway-->>NymProxyClient: Acks + NymProxyClient->>Entry Gateway: Sphinx Packets: Message 3 + Entry Gateway-->>NymProxyClient: Acks + NymProxyClient->>Entry Gateway: Sphinx Packets: Close Message + Entry Gateway-->>NymProxyClient: Acks + + Entry Gateway-->>Mix Nodes: All Packets, Acks, etc + Note right of Mix Nodes: We are omitting the 3 hops etc for brevity here + Mix Nodes-->> Exit Gateway: All Packets, Acks, etc + + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 2 + NymProxyServer-->>Exit Gateway: Acks + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 3 + NymProxyServer-->>Exit Gateway: Acks + loop Message Buffer + NymProxyServer->>NymProxyServer: Wait for Message 1 + Exit Gateway->>NymProxyServer: Sphinx Packets: Message 1 + NymProxyServer-->>Exit Gateway: Acks + NymProxyServer->>NymProxyServer: Message Received: trigger upstream send + end + Note right of NymProxyServer: Note this happens **per session** + NymProxyServer->>Upstream Process: Reconstructed request bytes + Upstream Process->>Upstream Process: Do something with request + Exit Gateway->>NymProxyServer: Sphinx Packets: Close Message + NymProxyServer-->>Exit Gateway: Acks + NymProxyServer->>NymProxyServer: Trigger Client timeout start for session + Upstream Process->>NymProxyServer: Response bytes + NymProxyServer->>NymProxyServer: Write to provided SURB payloads + NymProxyServer->>Exit Gateway: Anonymous replies + box Remote Host + participant NymProxyServer + participant Upstream Process + end + + + Entry Gateway--xNymProxyClient: Sphinx Packets: Reply Message 1 dropped: No Ack! + Entry Gateway->>NymProxyClient: Sphinx Packets: Reply Message 2 + NymProxyClient-->Entry Gateway: Ack + Entry Gateway->>NymProxyClient: Sphinx Packets: Reply Message 3 + NymProxyClient-->Entry Gateway: Ack + Loop Message Buffer: + NymProxyClient->>NymProxyClient: Wait for Message 1 + Entry Gateway->>NymProxyClient: Sphinx Packets: Message 1 + NymProxyClient-->>Entry Gateway: Acks + NymProxyClient->>NymProxyClient: Message Received: trigger send + NymProxyClient->>Client Process: Response bytes + end + Note right of NymProxyClient: Note this happens **per session** +``` diff --git a/documentation/docs/pages/developers/rust/tcpproxy/examples/_meta.json b/documentation/docs/pages/developers/rust/tcpproxy/examples/_meta.json new file mode 100644 index 0000000000..925cba8b48 --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy/examples/_meta.json @@ -0,0 +1,4 @@ +{ + "singleconn": "Single Connection", + "multiconn": "Multi Connection" +} diff --git a/documentation/docs/pages/developers/rust/tcpproxy/examples/multiconn.mdx b/documentation/docs/pages/developers/rust/tcpproxy/examples/multiconn.mdx new file mode 100644 index 0000000000..3a97858119 --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy/examples/multiconn.mdx @@ -0,0 +1,154 @@ +# Multi Connection Example + +This example starts off several Tcp connections on a loop to a remote endpoint: in this case the `TcpListener` behind the `NymProxyServer` instance on the echo server found in +[`nym/tools/echo-server/`](https://github.com/nymtech/nym/tree/develop/tools/echo-server). It pipes a few messages to it, logs the replies, and keeps track of the number of replies received per connection. + +> You can find this code [here](https://github.com/nymtech/nym/blob/develop/sdk/rust/nym-sdk/examples/tcp_proxy_multistream.rs) + +```rust +use nym_sdk::mixnet::Recipient; +use nym_sdk::tcp_proxy; +use rand::rngs::SmallRng; +use rand::Rng; +use rand::SeedableRng; +use serde::{Deserialize, Serialize}; +use std::env; +use tokio::io::AsyncWriteExt; +use tokio::net::TcpStream; +use tokio::signal; +use tokio_stream::StreamExt; +use tokio_util::codec; + +#[derive(Serialize, Deserialize, Debug)] +struct ExampleMessage { + message_id: i8, + message_bytes: Vec, + tcp_conn: i8, +} + +// To run: +// - run the echo server with `cargo run` +// - run this example with `cargo run --example tcp_proxy_multistream -- ` e.g. +// cargo run --example tcp_proxy_multistream -- DMHyxo8n6sKWHHTVvjRVDxDSMX8gYXRU1AQ6UpwsrWiB.6STYCWGWyRxqn2juWdgjMkAMsT9EaAzPpLWq5zkS68MB@CJG5zTcmoLijmDrtAiLV9PZHxNz8LQu6hmgA89V2RxxL ../../../envs/canary.env 8080 +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let server_address = env::args().nth(1).expect("Server address not provided"); + let server: Recipient = + Recipient::try_from_base58_string(&server_address).expect("Invalid server address"); + + // Comment this out to just see println! statements from this example. + // Nym client logging is very informative but quite verbose. + // The Message Decay related logging gives you an ideas of the internals of the proxy message ordering: you need to switch + // to DEBUG to see the contents of the msg buffer, sphinx packet chunking, etc. + tracing_subscriber::fmt() + .with_max_level(tracing::Level::INFO) + .init(); + + let env_path = env::args().nth(2).expect("Env file not specified"); + let env = env_path.to_string(); + + let listen_port = env::args().nth(3).expect("Port not specified"); + + // Within the TcpProxyClient, individual client shutdown is triggered by the timeout. + let proxy_client = + tcp_proxy::NymProxyClient::new(server, "127.0.0.1", &listen_port, 45, Some(env)).await?; + + tokio::spawn(async move { + proxy_client.run().await?; + Ok::<(), anyhow::Error>(()) + }); + + println!("waiting for everything to be set up.."); + tokio::time::sleep(tokio::time::Duration::from_secs(5)).await; + println!("done. sending bytes"); + + // In the info traces you will see the different session IDs being set up, one for each TcpStream. + for i in 0..4 { + let conn_id = i; + println!("Starting TCP connection {}", conn_id); + let local_tcp_addr = format!("127.0.0.1:{}", listen_port.clone()); + tokio::spawn(async move { + // Now the client and server proxies are running we can create and pipe traffic to/from + // a socket on the same port as our ProxyClient instance as if we were just communicating + // between a client and host via a normal TcpStream - albeit with a decent amount of additional latency. + // + // The assumption regarding integration is that you know what you're sending, and will do proper + // framing before and after, know what data types you're expecting; the proxies are just piping bytes + // back and forth using tokio's `Bytecodec` under the hood. + + let stream = TcpStream::connect(local_tcp_addr).await?; + let (read, mut write) = stream.into_split(); + + // Lets just send a bunch of messages to the server with variable delays between them, with a message and tcp connection ids to keep track of ordering on the server side (for illustrative purposes **only**; keeping track of anonymous replies is handled by the proxy under the hood with Single Use Reply Blocks (SURBs); for this illustration we want some kind of app-level message id, but irl most of the time you'll probably be parsing on e.g. the incoming response type instead) + tokio::spawn(async move { + for i in 0..4 { + let mut rng = SmallRng::from_entropy(); + let delay: f64 = rng.gen_range(2.5..5.0); + tokio::time::sleep(tokio::time::Duration::from_secs_f64(delay)).await; + let random_bytes = gen_bytes_fixed(i as usize); + let msg = ExampleMessage { + message_id: i, + message_bytes: random_bytes, + tcp_conn: conn_id, + }; + let serialised = bincode::serialize(&msg)?; + write + .write_all(&serialised) + .await + .expect("couldn't write to stream"); + println!( + ">> client sent {}: {} bytes on conn {}", + &i, + msg.message_bytes.len(), + &conn_id + ); + } + Ok::<(), anyhow::Error>(()) + }); + + tokio::spawn(async move { + let mut reply_counter = 0; + let codec = codec::BytesCodec::new(); + let mut framed_read = codec::FramedRead::new(read, codec); + while let Some(Ok(bytes)) = framed_read.next().await { + match bincode::deserialize::(&bytes) { + Ok(msg) => { + println!( + "<< client received {}: {} bytes on conn {}", + msg.message_id, + msg.message_bytes.len(), + msg.tcp_conn + ); + reply_counter += 1; + println!( + "tcp connection {} replies received {}/4", + msg.tcp_conn, reply_counter + ); + } + Err(e) => { + println!("<< client received something that wasn't an example message of {} bytes. error: {}", bytes.len(), e); + } + } + } + }); + Ok::<(), anyhow::Error>(()) + }); + let mut rng = SmallRng::from_entropy(); + let delay: f64 = rng.gen_range(4.5..7.0); + tokio::time::sleep(tokio::time::Duration::from_secs_f64(delay)).await; + } + + // Once timeout is passed, you can either wait for graceful shutdown or just hard stop it. + signal::ctrl_c().await?; + println!("CTRL+C received, shutting down"); + Ok(()) +} + +// emulate a series of small messages followed by a closing larger one +fn gen_bytes_fixed(i: usize) -> Vec { + let amounts = [10, 15, 50, 1000]; + let len = amounts[i]; + let mut rng = rand::thread_rng(); + (0..len).map(|_| rng.gen::()).collect() +} +``` diff --git a/documentation/docs/pages/developers/rust/tcpproxy/examples/singleconn.mdx b/documentation/docs/pages/developers/rust/tcpproxy/examples/singleconn.mdx new file mode 100644 index 0000000000..1ee1196868 --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy/examples/singleconn.mdx @@ -0,0 +1,195 @@ +# Single Connection Example + +This is a basic example which opens a single TCP connection and writes a bunch of messages between a client and some 'echo server' logic, so only uses a single session under the hood and doesn't really show off the message ordering capabilities; this is mainly just a quick introductory illustration on how: +- the mixnet does message ordering +- the NymProxyClient and NymProxyServer can be hooked into and used to communicate between two otherwise pretty vanilla TcpStreams + +For a more irl example check the [multi connection example](./multiconn). + +> You can find this code [here](https://github.com/nymtech/nym/blob/develop/sdk/rust/nym-sdk/examples/tcp_proxy_single_connection.rs) + +```rust +use nym_sdk::tcp_proxy; +use rand::rngs::SmallRng; +use rand::{Rng, SeedableRng}; +use serde::{Deserialize, Serialize}; +use std::env; +use std::fs; +use std::sync::atomic::{AtomicU8, Ordering}; +use tokio::io::AsyncWriteExt; +use tokio::net::{TcpListener, TcpStream}; +use tokio::signal; +use tokio_stream::StreamExt; +use tokio_util::codec; + +#[derive(Serialize, Deserialize, Debug)] +struct ExampleMessage { + message_id: i8, + message_bytes: Vec, +} + + +// Run this with: +// `cargo run --example tcp_proxy_single_connection ` e.g. +// `cargo run --example tcp_proxy_single_connection 8081 ../../../envs/canary.env 8080 ` +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // Keep track of sent/received messages + let counter = AtomicU8::new(0); + + // Comment this out to just see println! statements from this example, as Nym client logging is very informative but quite verbose. + // The Message Decay related logging gives you an ideas of the internals of the proxy message ordering. To see the contents of the msg buffer, sphinx packet chunking, etc change the tracing::Level to DEBUG. + tracing_subscriber::fmt() + .with_max_level(tracing::Level::INFO) + .init(); + + let server_port = env::args() + .nth(1) + .expect("Server listen port not specified"); + let upstream_tcp_addr = format!("127.0.0.1:{}", server_port); + + // This dir gets cleaned up at the end: NOTE if you switch env between tests without letting the file do the automatic cleanup, make sure to manually remove this directory up before running again, otherwise your client will attempt to use these keys for the new env + let home_dir = dirs::home_dir().expect("Unable to get home directory"); + let conf_path = format!("{}/tmp/nym-proxy-server-config", home_dir.display()); + + let env_path = env::args().nth(2).expect("Env file not specified"); + let env = env_path.to_string(); + let client_port = env::args().nth(3).expect("Port not specified"); + + let mut proxy_server = + tcp_proxy::NymProxyServer::new(&upstream_tcp_addr, &conf_path, Some(env_path.clone())) + .await?; + let proxy_nym_addr = proxy_server.nym_address(); + + // We'll run the instance with a long timeout since we're sending everything down the same Tcp connection, so should be using a single session. + // Within the TcpProxyClient, individual client shutdown is triggered by the timeout. + let proxy_client = + tcp_proxy::NymProxyClient::new(*proxy_nym_addr, "127.0.0.1", &client_port, 60, Some(env)) + .await?; + + tokio::spawn(async move { + proxy_server.run_with_shutdown().await?; + Ok::<(), anyhow::Error>(()) + }); + + tokio::spawn(async move { + proxy_client.run().await?; + Ok::<(), anyhow::Error>(()) + }); + + // 'Server side' thread: echo back incoming as response to the messages sent in the 'client side' thread below + tokio::spawn(async move { + let listener = TcpListener::bind(upstream_tcp_addr).await?; + loop { + let (socket, _) = listener.accept().await.unwrap(); + let (read, mut write) = socket.into_split(); + let codec = codec::BytesCodec::new(); + let mut framed_read = codec::FramedRead::new(read, codec); + while let Some(Ok(bytes)) = framed_read.next().await { + match bincode::deserialize::(&bytes) { + Ok(msg) => { + println!( + "<< server received {}: {} bytes", + msg.message_id, + msg.message_bytes.len() + ); + let msg = ExampleMessage { + message_id: msg.message_id, + message_bytes: msg.message_bytes, + }; + let serialised = bincode::serialize(&msg)?; + write + .write_all(&serialised) + .await + .expect("couldnt send reply"); + println!( + ">> server sent {}: {} bytes", + msg.message_id, + msg.message_bytes.len() + ); + } + Err(e) => { + println!("<< server received something that wasn't an example message of {} bytes. error: {}", bytes.len(), e); + } + } + } + } + #[allow(unreachable_code)] + Ok::<(), anyhow::Error>(()) + }); + + // Just wait for Nym clients to connect, TCP clients to bind, etc. + println!("waiting for everything to be set up.."); + tokio::time::sleep(tokio::time::Duration::from_secs(5)).await; + println!("done. sending bytes"); + + // Now the client and server proxies are running we can create and pipe traffic to/from + // a socket on the same port as our ProxyClient instance as if we were just communicating + // between a client and host via a normal TcpStream - albeit with a decent amount of additional latency. + // + // The assumption regarding integration is that you know what you're sending, and will do proper + // framing before and after, know what data types you're expecting, etc; the proxies are just piping bytes + // back and forth using tokio's `Bytecodec` under the hood. + let local_tcp_addr = format!("127.0.0.1:{}", client_port); + let stream = TcpStream::connect(local_tcp_addr).await?; + let (read, mut write) = stream.into_split(); + + // 'Client side' thread; lets just send a bunch of messages to the server with variable delays between them, with an id to keep track of ordering in the printlns; the mixnet only guarantees message delivery, not ordering. You might not be necessarily streaming traffic in this manner IRL, but this example is a good illustration of how messages travel through the mixnet. + // - On the level of individual messages broken into multiple packets, the Proxy abstraction deals with making sure that everything is sent between the sockets in the corrent order. + // - On the level of different messages, this is not enforced: you might see in the logs that message 1 arrives at the server and is reconstructed after message 2. + tokio::spawn(async move { + let mut rng = SmallRng::from_entropy(); + for i in 0..10 { + let random_bytes = gen_bytes_fixed(i as usize); + let msg = ExampleMessage { + message_id: i, + message_bytes: random_bytes, + }; + let serialised = bincode::serialize(&msg)?; + write + .write_all(&serialised) + .await + .expect("couldn't write to stream"); + println!(">> client sent {}: {} bytes", &i, msg.message_bytes.len()); + let delay = rng.gen_range(3.0..7.0); + tokio::time::sleep(tokio::time::Duration::from_secs_f64(delay)).await; + } + Ok::<(), anyhow::Error>(()) + }); + + let codec = codec::BytesCodec::new(); + let mut framed_read = codec::FramedRead::new(read, codec); + while let Some(Ok(bytes)) = framed_read.next().await { + match bincode::deserialize::(&bytes) { + Ok(msg) => { + println!( + "<< client received {}: {} bytes", + msg.message_id, + msg.message_bytes.len() + ); + counter.fetch_add(1, Ordering::SeqCst); + println!( + ":: messages received back: {:?}/10", + counter.load(Ordering::SeqCst) + ); + } + Err(e) => { + println!("<< client received something that wasn't an example message of {} bytes. error: {}", bytes.len(), e); + } + } + } + + // Once timeout is passed, you can either wait for graceful shutdown or just hard stop it. + signal::ctrl_c().await?; + println!(":: CTRL+C received, shutting down + cleanup up proxy server config files"); + fs::remove_dir_all(conf_path)?; + Ok(()) +} + +fn gen_bytes_fixed(i: usize) -> Vec { + let amounts = vec![1, 10, 50, 100, 150, 200, 350, 500, 750, 1000]; + let len = amounts[i]; + let mut rng = rand::thread_rng(); + (0..len).map(|_| rng.gen::()).collect() +} +``` diff --git a/documentation/docs/pages/developers/tools.mdx b/documentation/docs/pages/developers/tools.mdx new file mode 100644 index 0000000000..ccd413c5ba --- /dev/null +++ b/documentation/docs/pages/developers/tools.mdx @@ -0,0 +1,7 @@ +# Tools + +There are a few tools available to developers for chain interaction: the `nym-cli` tool, which operates as an easier-to-use wrapper around `nyxd`, to allow operators to script interactions with their infrastructure (and those who prefer CLI tools ;) ). + +There is also a basic echo server tool which app developers can use as a quick endpoint for traffic testing. This will be deployed onto a persistent public server in the future so devs dont have to run it themselves. + +Finally, there are a pair of standalone versions of the TcpProxy Rust SDK module for developers to begin experimenting with sending app traffic through them mixnet. diff --git a/documentation/docs/pages/developers/tools/_meta.json b/documentation/docs/pages/developers/tools/_meta.json new file mode 100644 index 0000000000..8aa37f3c3b --- /dev/null +++ b/documentation/docs/pages/developers/tools/_meta.json @@ -0,0 +1,5 @@ +{ + "nym-cli": "Nym-cli", + "echo-server": "Echo Server", + "standalone-tcpproxy": "TcpProxy Binaries (Standalone)" +} diff --git a/documentation/docs/pages/developers/tools/echo-server.mdx b/documentation/docs/pages/developers/tools/echo-server.mdx new file mode 100644 index 0000000000..334c14daf0 --- /dev/null +++ b/documentation/docs/pages/developers/tools/echo-server.mdx @@ -0,0 +1,25 @@ +# Echo Server + +There is an initial version of a simple echo server located at [`nym/tools/echo-server`](https://github.com/nymtech/nym/tree/develop/tools/echo-server). + +This is an initial minimal implementation of an echo server built using the [`NymProxyServer`](../rust/tcpproxy) Rust SDK abstraction that, aside from the initialisation and running of a `NymProxyServer` instance in the background, is essentially a vanilla TCP echo server written with `tokio`. + +This server was initially built for the `TcpProxy` tests, but can be useful for developers to need a constant endpoint to ping when developing. In the future this will be deployed to a remote server so developers don't have to run their own. + +## Build +Run `cargo build --release` from `nym/tools/echo-server`. The binary will be in the main workspace `target/release` dir. + +## Run +All the server requires is a port to connect the TCP listener to. If no `` is supplied then the server defaults to using mainnet. + +```sh +echo-server +# e.g. ../../target/release/echo-server 9000 ../../envs/canary.env +``` + +## Logging +Every 10 seconds, the server logs: +- the total number of bytes received since startup +- the total number of bytes sent since startup +- the current number of concurrent connections it has +- the total number of concurrent connections it has diff --git a/documentation/docs/pages/developers/tools/nym-cli.md b/documentation/docs/pages/developers/tools/nym-cli.md new file mode 100644 index 0000000000..bf938f2173 --- /dev/null +++ b/documentation/docs/pages/developers/tools/nym-cli.md @@ -0,0 +1,34 @@ +# Nym-CLI + +## What is this tool for? +This is a CLI tool for interacting with: + +* the Nyx blockchain (account management, querying the chain state, etc) +* the smart contracts deployed on Nyx (bonding and un-bonding mixnodes, collecting rewards, etc) + +It provides a convenient wrapper around the `nymd` client, and has similar functionality to the `nyxd` binary for querying the chain or executing smart contract methods. + +## Building +The `nym-cli` binary can be built by running `cargo build --release` in the `nym/tools/nym-cli` directory. + +## Usage +See the [commands](./nym-cli/commands.mdx) page for an overview of all command options. + +### Staking on someone's behalf (for custodians) + +There is a limitation the staking address can only perform the following actions (and are visible via the Nym Wallet: + +- Bond on the gateway's or mix node's behalf. +- Delegate or Un-delegate (to a mix node in order to begin receiving rewards) +- Claiming the rewards on the account + +```admonish note title="" +The staking address has no ability to withdraw any coins from the parent's account. +``` + +The staking address must maintain the same level of security as the parent mnemonic; while the parent mnemonic's delegations and bonding events will be visible to the parent owner, the staking address will be the only account capable of undoing the bonding and delegating from the mix nodes or gateway. + +Query for staking on behalf of someone else +``` +./nym-cli --mnemonic mixnet delegators delegate --mix-id --identity-key --amount +``` diff --git a/documentation/docs/pages/developers/tools/nym-cli/commands.mdx b/documentation/docs/pages/developers/tools/nym-cli/commands.mdx new file mode 100644 index 0000000000..1117807a5a --- /dev/null +++ b/documentation/docs/pages/developers/tools/nym-cli/commands.mdx @@ -0,0 +1,1107 @@ +# `nym-cli` Binary Commands (Autogenerated) + +These docs are autogenerated by the [`autodocs`](https://github.com/nymtech/nym/tree/max/new-docs-framework/documentation/autodoc) script. +```sh +A client for interacting with Nym smart contracts and the Nyx blockchain + +Usage: nym-cli [OPTIONS] + +Commands: + account Query and manage Nyx blockchain accounts + signature Sign and verify messages + ecash Ecash related stuff + block Query chain blocks + cosmwasm Manage and execute WASM smart contracts + tx Query for transactions + vesting-schedule Create and query for a vesting schedule + mixnet Manage your mixnet infrastructure, delegate stake or query the directory + generate-fig Generates shell completion + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +## `account` +```sh +Query and manage Nyx blockchain accounts + +Usage: nym-cli account [OPTIONS] + nym-cli account + +Commands: + create Create a new mnemonic - note, this account does not appear on the chain until the account id is used in a transaction + balance Gets the balance of an account + pub-key Gets the public key of an account + send Sends tokens to another account + send-multiple Batch multiple token sends + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `account create` +```sh +Create a new mnemonic - note, this account does not appear on the chain until the account id is used in a transaction + +Usage: nym-cli account create [OPTIONS] + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + --word-count + + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `account balance` +```sh +Gets the balance of an account + +Usage: nym-cli account balance [OPTIONS] [ADDRESS] + +Arguments: + [ADDRESS] The account address to get the balance for + +Options: + --denom + Optional currency to show balance for + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --hide-denom + Optionally hide the denom + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --raw + Show as a raw value + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `account pub-key` +```sh +Gets the public key of an account + +Usage: nym-cli account pub-key [OPTIONS] [ADDRESS] + +Arguments: + [ADDRESS] Optionally, show the public key for this account address, otherwise generate the account address from the mnemonic + +Options: + --from-mnemonic + If set, get the public key from the mnemonic, rather than querying for it + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `account send` +```sh +Sends tokens to another account + +Usage: nym-cli account send [OPTIONS] + +Arguments: + The recipient account address + Amount to transfer in micro denomination (e.g. unym or unyx) + +Options: + --denom + Override the denomination + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --memo + + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `account send-multiple` +```sh +Batch multiple token sends + +Usage: nym-cli account send-multiple [OPTIONS] --input + +Options: + --memo + + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --input + Input file path (CSV format) with account/amount pairs to send + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --output + An output file path (CSV format) to create or append a log of results to + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +## `signature` +```sh +Sign and verify messages + +Usage: nym-cli signature [OPTIONS] + nym-cli signature + +Commands: + sign Sign a message + verify Verify a message + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `signature sign` +```sh +Sign a message + +Usage: nym-cli signature sign [OPTIONS] + +Arguments: + The message to sign + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `signature verify` +```sh +Verify a message + +Usage: nym-cli signature verify [OPTIONS] + +Arguments: + The public key of the account, or the account id to query for a public key (NOTE: the account must have signed a message stored on the chain for the public key record to exist) + The signature to verify as hex + The message to verify as a string + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +## `ecash` +```sh +Ecash related stuff + +Usage: nym-cli ecash [OPTIONS] + nym-cli ecash + +Commands: + issue-ticket-book + recover-ticket-book + import-ticket-book + generate-ticket + import-coin-index-signatures + import-expiration-date-signatures + import-master-verification-key + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `ecash issue-ticket-book` +```sh +Usage: nym-cli ecash issue-ticket-book [OPTIONS] <--client-config |--output-file > + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + --ticketbook-type + Specify which type of ticketbook should be issued [default: v1-mixnet-entry] + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --client-config + Config file of the client that is supposed to use the credential + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --output-file + Output file for the ticketbook + --bs58-output + Specifies whether the output file should use binary or bs58 encoded data + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --include-expiration-date-signatures + Specifies whether the file output should contain expiration date signatures + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --include-coin-index-signatures + Specifies whether the file output should contain coin index signatures + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + --include-master-verification-key + Specifies whether the file output should contain master verification key + --bs58-encoded-client-secret + Secret value that's used for deriving underlying ecash keypair + -h, --help + Print help +``` + +### `ecash recover-ticket-book` +```sh +Usage: nym-cli ecash recover-ticket-book [OPTIONS] --client-config + +Options: + --client-config + Config file of the client that is supposed to use the credential + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `ecash import-ticket-book` +```sh +Usage: nym-cli ecash import-ticket-book [OPTIONS] --credentials-store <--credential-data |--credential-path > <--standalone|--full> + +Options: + --credentials-store + Config file of the client that is supposed to use the credential + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --credential-data + Explicitly provide the encoded credential data (as base58) + --credential-path + Specifies the path to file containing binary credential data + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --standalone + Specifies whether we're attempting to import a standalone ticketbook (i.e. serialised `IssuedTicketBook`) + --full + Specifies whether we're attempting to import full ticketboot (i.e. one that **might** contain required global signatures; that is serialised `ImportableTicketBook`) + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +## `coconut` + +### `coconut generate-freepass` + +### `coconut issue-credentials` + +### `coconut recover-credentials` + +### `coconut import-credential` + +## `block` +```sh +Query chain blocks + +Usage: nym-cli block [OPTIONS] + nym-cli block + +Commands: + get Gets a block's details and prints as JSON + time Gets the block time at a height + current-height Gets the current block height + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `block get` +```sh +Gets a block's details and prints as JSON + +Usage: nym-cli block get [OPTIONS] + +Arguments: + The block height + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `block time` +```sh +Gets the block time at a height + +Usage: nym-cli block time [OPTIONS] + +Arguments: + The block height + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `block current-height` +```sh +Gets the current block height + +Usage: nym-cli block current-height [OPTIONS] + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +## `cosmwasm` +```sh +Manage and execute WASM smart contracts + +Usage: nym-cli cosmwasm [OPTIONS] + nym-cli cosmwasm + +Commands: + upload Upload a smart contract WASM blob + init Init a WASM smart contract + generate-init-message Generate an instantiate message + migrate Migrate a WASM smart contract + execute Execute a WASM smart contract method + raw-contract-state Obtain raw contract state of a cosmwasm smart contract + help Print this message or the help of the given subcommand(s) + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `cosmwasm upload` +```sh +Upload a smart contract WASM blob + +Usage: nym-cli cosmwasm upload [OPTIONS] --wasm-path + +Options: + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + --wasm-path + + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --memo + + --nyxd-url + Overrides the nyxd URL provided either as an environment variable NYXD_VALIDATOR or in a config file + --nym-api-url + Overrides the validator API URL provided either as an environment variable API_VALIDATOR or in a config file + --mixnet-contract-address + Overrides the mixnet contract address provided either as an environment variable or in a config file + --vesting-contract-address + Overrides the vesting contract address provided either as an environment variable or in a config file + -h, --help + Print help +``` + +### `cosmwasm init` +```sh +Init a WASM smart contract + +Usage: nym-cli cosmwasm init [OPTIONS] --init-message + +Arguments: + + +Options: + --memo + + --mnemonic + Provide the mnemonic for your account. You can also provide this is an env var called MNEMONIC. + -c, --config-env-file + Overrides configuration as a file of environment variables. Note: individual env vars take precedence over this file. + --label