From 2a4fdc83c4200a09ff5f7dba05d5f3b7e64e302b Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Thu, 26 Sep 2024 19:53:50 +0200 Subject: [PATCH] started moving integrations docs over from ts sdk --- .../docs/pages/developers/integrations.mdx | 14 +++ .../integrations/{todo.md => rust-go-cpp.mdx} | 0 .../pages/developers/integrations/ts-js.mdx | 10 ++ .../pages/sdk/typescript/integrations.mdx | 111 ------------------ 4 files changed, 24 insertions(+), 111 deletions(-) create mode 100644 documentation/docs/pages/developers/integrations.mdx rename documentation/docs/pages/developers/integrations/{todo.md => rust-go-cpp.mdx} (100%) create mode 100644 documentation/docs/pages/developers/integrations/ts-js.mdx delete mode 100644 documentation/docs/pages/sdk/typescript/integrations.mdx diff --git a/documentation/docs/pages/developers/integrations.mdx b/documentation/docs/pages/developers/integrations.mdx new file mode 100644 index 0000000000..897c5fda26 --- /dev/null +++ b/documentation/docs/pages/developers/integrations.mdx @@ -0,0 +1,14 @@ +import Box from '@mui/material/Box'; +import { Steps } from 'nextra/components' +import { Tabs } from 'nextra/components' +import { GitRepoSearch } from '../../code-snippets/mixfetchurl'; + +# Integrations + +There are several options available to developers wanting to embed a Nym client in their application code. + + + See the [Typescript/Javascript](./integrations/ts-js) page. + See the [Rust/Go/C++](./integrations/rust-go-cpp) page. + If your app is not written in any of the supported languages, you might still be able to send traffic through a standalone socks5 client TODO LINK but will have to think about packaging and bundling the client binary with e.g. a `systemd` file for autostart to run the client as a daemon. If you want to discuss FFI options reach out to us via our public dev channel. + diff --git a/documentation/docs/pages/developers/integrations/todo.md b/documentation/docs/pages/developers/integrations/rust-go-cpp.mdx similarity index 100% rename from documentation/docs/pages/developers/integrations/todo.md rename to documentation/docs/pages/developers/integrations/rust-go-cpp.mdx diff --git a/documentation/docs/pages/developers/integrations/ts-js.mdx b/documentation/docs/pages/developers/integrations/ts-js.mdx new file mode 100644 index 0000000000..748e6263a3 --- /dev/null +++ b/documentation/docs/pages/developers/integrations/ts-js.mdx @@ -0,0 +1,10 @@ +import { GitHubRepoSearch } from '../../../code-snippets/mixfetchurl'; +import { Tabs } from 'nextra/components' + +# Typescript/Javascript Applications + +## Relying on `fetch` for network traffic and remote connections? + + 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 above) 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. + While mixFetch is the shortest and easiest way to integrate Nym, a well-modularized JS/TS codebase should permit the integration of one of our SDK components, which will allow more flexibility and control. Read more about our different SDK components in the [TS SDK overview page](). TODO LINK + diff --git a/documentation/docs/pages/sdk/typescript/integrations.mdx b/documentation/docs/pages/sdk/typescript/integrations.mdx deleted file mode 100644 index a0596810be..0000000000 --- a/documentation/docs/pages/sdk/typescript/integrations.mdx +++ /dev/null @@ -1,111 +0,0 @@ -import Box from '@mui/material/Box'; -import { Steps } from 'nextra/components' -import { Tabs } from 'nextra/components' -import { GitHubRepoSearch } from '../../../code-snippets/mixfetchurl'; - -# Integrations page - -## How can I integrate Nym into my app? -If you're unsure where to start, the following set of questions should help you determine which path to follow in regards to integrations with Nym: - - -### Is your app developed in TS/JS or Rust? - - - **Yes - TS/JS or RUST**: If yes, you will either be able to leverage `mixFetch` (go to step 2 below) or the `sdk client` to route app traffic through the mixnet. Note that `mixfetch` currently only works with JS/TS at the moment, as we do not yet have a Rust implementation of it. - **No**: You'll most likely need to use FFI or one of our [standalone clients](https://nymtech.net/developers/integrations/mixnet-integration.html). - - - - -### Does your TS/JS app rely on `fetch` for its network traffic and remote connections? - Check whether `mixFetch` can be used to route your traffic through the mixnet by entering your repository's URL below: - - - - - **Yes - my repo currently uses `fetch`**: 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 above) 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. - **No**: While mixFetch is the shortest and easiest way to integrate Nym, a well-modularized JS/TS or Rust codebase should permit the integration of one of our SDK components, which will allow more flexibility and control. Read more about our different SDK components in the [TS SDK overview page](./overview) and the [Rust SDK documentation](https://nymtech.net/developers/tutorials/rust-sdk.html). - - - - - ### Use one of our standalone Nym clients - If you've answered 'No' to all of the above, you may need to use one of our [standalone clients](https://nymtech.net/docs/clients/overview.html). 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 construct Sphinx packets. While setting up those, and depending on your usecase, you may need to set-up and run a Service Provider. Read below the "How to deal with Service Providers" section for more details. - - - - - - -```ascii - +-----------------------------------+ - | | +---------------------+ - | Is app JS/TS or another language? +-----+|Go / C / C++ / Swift |+----------------------+ - | | +---------------------+ | - +--------+-----------------+--------+ | - | | | - | | | - +----+----+ +--+---+ | - | TS/JS | | Rust |+-------------------------------------+ | - +----+----+ +------+ | | - | | | - +----+------------+---------------------+--------+--------------+ | | - +-----+----+ +--------+ | | | - | Browser | | Server | | | | - +-----+----+ +---+----+ | | | - | | | | | - +-------+--------+ +---+----+ | | | - | HTTP requests | | nodeJS | | | | - +---+-------+--------+----+ +---+----+ | | | - | | | | | | | - +--+--+ +----+----+ +-----+----------+ | | | | - | yes | |websocket| | webRTC or other| | | | | - +--+--+ +----+----+ +------+---------+ | | | | - | | | | | | | -+-----v---+ +-----v-----+ +----v-------+ +--------v---------+ +----v---+ +----v-----+ +--------v---------+ -|mixFetch | |Talk to us | | No support | | mixFetch nodeJS | | TS SDK | | Rust SDK | | FFI* / Nym | -+---------+ +-----------+ +------------+ +------------------+ +--------+ +----------+ | standalone client| - +------------------+ - - * Coming soon™️ - ``` - -## When do I need Service Providers? -If you decide to interact with one of the Nym [standalone clients](https://nymtech.net/docs/clients/overview.html), then you most likely will need to set-up a Service Provider. The need for a Service Provider mostly depends on your app's goal and architecture (and the endpoint it needs to hit). -Again, as detailed in the [FAQ](../FAQ/general): - -- No Service Provider (Network Requester) needed: 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. -- Network Requester needed (existing or own): If you’re wanting to place the mixnet between your users’ application instances and a server-based backend, you will need a Network Requester. In this case, if your app supports SOCKS5, you could either use an existing NR or, if your app supports SOCKS5 but needs more extensive whitelisting, you could use the [network requester service provider binary](https://nymtech.net/operators/nodes/network-requester-setup.html) to proxy these requests to your application backend yourself, with the mixnet ‘between’ the user and your service, in order to prevent metadata leakage being broadcast to the internet. -- Running your own Service Provider: If your usecase is more complex, you’re wanting to route RPC requests through the mixnet to a blockchain for example, 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 page](https://nymtech.net/developers/community-resources/community-applications-and-guides.html). - -``` ascii - +----------------------+ - +----+| App supports SOCKS5? |+-----+ - | +----------------------+ | - +--+--+ +--+--+ - | yes | | no | - +-----+ +-----+ - | | - +------------+ +-----------------------+ - +----+|App use case|+--+ | Set standalone client | - | +------------+ | | + SP | - needs needs +-----------------------+ - | | - +-------+--------+ +---------+---------+ - |simple whitelist| |extensive whitelist| - +----------------+ +-+---------------+-+ - | | -+------------------+ +---------------+ -| use existing NR | | run own NR/SP | -+------------------+ +---------------+ - -``` - - - -## Other resources -If you'd like to learn more about potential integrations, please make sure to read: -- The [integrations FAQ](https://nymtech.net/developers/faq/integrations-faq.html): which lists a set of common questions regarding integrating Nym and Nyx; -- The [mixnet integration page](https://nymtech.net/developers/integrations/mixnet-integration.html): which will help you integrate with Nym to use the mixnet for application traffic; -- The [payment integration page](https://nymtech.net/developers/integrations/payment-integration.html): which will help you integrate with the Nyx blockchain and use Nym for payments;