diff --git a/sdk/typescript/docs/package.json b/sdk/typescript/docs/package.json index fd56bf8024..af8236522c 100644 --- a/sdk/typescript/docs/package.json +++ b/sdk/typescript/docs/package.json @@ -31,7 +31,7 @@ "@nymproject/contract-clients": "^1.2.0-rc.9", "@nymproject/mix-fetch": "^1.2.0-rc.9", "@nymproject/mix-fetch-full-fat": "^1.2.0-rc.9", - "@nymproject/sdk-full-fat": "^1.2.0-rc.9", + "@nymproject/sdk-full-fat": "^1.2.0-rc.10", "chain-registry": "^1.19.0", "cosmjs-types": "^0.8.0", "next": "^13.4.19", diff --git a/sdk/typescript/docs/pages/FAQ/general.mdx b/sdk/typescript/docs/pages/FAQ/general.mdx index 70961a3988..4095c74356 100644 --- a/sdk/typescript/docs/pages/FAQ/general.mdx +++ b/sdk/typescript/docs/pages/FAQ/general.mdx @@ -15,14 +15,20 @@ These SDKs abstract away much of the messaging and core logic from your app, and Alternatively, you can also use one of the three Nym clients to connect your application to the mixnet. 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. You can learn more about the Nym clients [here](https://nymtech.net/developers/integrations/mixnet-integration.html). ###### Network requesters: -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! +Network requesters are a type of Service Provider, that in essence, act as a form of proxy (somewhat analagous to a Tor exit node). If you have access to a server, you can run the Network Requester, which allows Nym users to send outbound requests from their local machine through the mixnet to a server, which then makes the request on their behalf, shielding them (and their metadata) from clearnet, untrusted and unknown infrastructure, such as email or message client servers. + +By default the Network Requester is not an open proxy but rather uses a local and global [allow list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to whitelist host access. + +#### __Which Service Provider to run?__ +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: + +- 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). -- 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 service provider binary](https://nymtech.net/operators/nodes/network-requester-setup.html) 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 page](https://nymtech.net/developers/community-resources/community-applications-and-guides.html). #### __Why gateways?__ -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. +Nym apps have a stable, potentially long-lasting relation to a gateway node. A client will establish a symmetric key share with a gateway that can be verified on subsequent connection attempts. Gateways serve a few different functions: @@ -44,7 +50,7 @@ To avoid the last two, you need to make sure the gateway you are calling is bond #### __How can I check whether the gateway I am connecting to is bonded and not blacklisted?__ -The easiest way of checking what gateway you're registered with is to look at you client address. +The easiest way of checking what gateway you're registered with is to look at your client address. Client addresses are in the format of: `client-id . client-dh @ gateway-id. ` @@ -55,5 +61,9 @@ To illustrate this: `DpB3cHAchJiNBQi5FrZx2csXb1mrHkpYh9Wzf8Rjsuko.ANNWrvHqMYuert - `2BuMSfMW3zpeAjKXyKLhmY4QW1DXurrtSPEJ6CjX3SEh`: is the gateway's identity, which is what you'll need to check the state of the gateway in the [Nym Explorer](https://explorer.nymtech.net/network-components/gateways). -#### __How can I get my service URL whitelisted?__ - +#### __How can I get my service host whitelisted?__ +Currently, the different options are: +- You can get it added to the local list of an existing Network Requester; +- You can ask the Nym team to add it to the global [allow list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) if it's not already there; +- You can run your own Network Requester and locally configure it to allow the hosts you need to connect to; +If you'd like to learn more about Network Requesters and the global allow list, you can [visit this page](https://nymtech.net/operators/nodes/network-requester-setup.html). \ No newline at end of file diff --git a/sdk/typescript/docs/pages/FAQ/integrations.mdx b/sdk/typescript/docs/pages/FAQ/integrations.mdx index a18debad1c..3e65614ae7 100644 --- a/sdk/typescript/docs/pages/FAQ/integrations.mdx +++ b/sdk/typescript/docs/pages/FAQ/integrations.mdx @@ -1 +1,91 @@ -# Integrations page \ No newline at end of file +# Integrations page + +### Existing resources +If you'd like to learn more about potential integrations, please first 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; + +### Integrations options +If you're unsure where to start, the following set of questions should help you determine which path to follow in regards to integrations: + + __1. Does your app mostly rely on the `fetch` method?__ + +If yes, explore implementing `mixfetch`to route app traffic through the mixnet. + +If not: +__2. Is your app developed in TS/JS or Rust?__ + + If yes, you can use one of our SDKs and leverage either `mixfetch`or the `sdk client`to route app traffic through the mixnet. + + If it is developed in another language: + __3. You can use one of our Nym 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. + You can find more information about the different clients and the ways to interact with them [in this page](https://nymtech.net/developers/integrations/mixnet-integration.html). + + +``` +For integration entry points: + + ,----------------------. + |SPA/WebApp fetch-based| + |----------------------| + `----------------------' + | | + yes no + | | + ,--------. ,----------. + |mixFetch| |Rust or TS| + |--------| |----------| ------------------. + `--------' `----------' | + | | + yes----------. no:other language + | | | + | | | + yes:TS/JS yes:RUST | + | | ,----------. + ,------. ,--------. |Nym-client| + |TS SDK| |Rust SDK| |----------| + |------| |--------| | | + `------' `--------' `----------' + + ``` + +### How to deal with Service Providers? + In a nutshell: that depends on your app's goal and architecture (and the endpoint it needs to hit). +Again, as detailed in the FAQ: + +- 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). + +``` + ,--------------------. + |App supports SOCKS5?| + |--------------------| + `--------------------' + | | + yes no + | | + ,------------. ,-----------------. + |App use case| |Set Client + SP | + |------------| |-----------------| + `------------' `-----------------' + | | + needs needs + | | + ,----------------. ,-------------------. + |Simple whitelist| |Extensive whitelist| + |----------------| |-------------------| + `----------------' `-------------------' + | | + | | + ,-----------. ,-------------. + |Existing NR| |Run own SP/NR| + |-----------| |-------------| + `-----------' `-------------' + + +``` + diff --git a/sdk/typescript/docs/pages/examples/mix-fetch.mdx b/sdk/typescript/docs/pages/examples/mix-fetch.mdx index 83d3a4a15e..99270a3a70 100644 --- a/sdk/typescript/docs/pages/examples/mix-fetch.mdx +++ b/sdk/typescript/docs/pages/examples/mix-fetch.mdx @@ -4,15 +4,12 @@ import { Callout } from 'nextra/components' An easy way to secure parts or all of your web app is to replace calls to [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) with `mixFetch`: -Mixfetch works the same as vanilla `fetch` as it's a proxied wrapper around the original function: +MixFetch works the same as vanilla `fetch` as it's a proxied wrapper around the original function. Read [this article](https://blog.nymtech.net/mixfetch-like-the-fetch-api-but-via-the-mixnet-82acfd435c62) to learn more about mixFetch. Sounds great, are there any catches? Well, there are a few (for now): 1. Currently, the operators of Network Requesters that make the final request at the egress part of the Nym Mixnet to the internet use a [standard allow list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) -in combination with their own configuration. If you are trying to access something that is not on the allow list, you -have two choices: -- run your own Network Requester and locally configure it to allow the hosts you need to connect to -- get in touch with us and give us more information about the sites you want included in the standard allow list +in combination with their own configuration. If you are trying to access something that is not on the allow list, please check the FAQ page. 2. We periodically update the CA certificates in `mixFetch` so if you get a certificate error, we may not have the root CA certificate you need in our list. [Send us a PR](https://github.com/nymtech/nym/pulls) if you need changes.