From 01b3204a498c41e77f3b914bfabd48255b631ffe Mon Sep 17 00:00:00 2001 From: Lorexia Date: Wed, 11 Oct 2023 14:47:33 +0200 Subject: [PATCH] Update docs: reorder pages, examples, fetch checker --- .../docs/code-snippets/mixfetchurl.tsx | 4 +- sdk/typescript/docs/pages/FAQ/general.mdx | 2 +- sdk/typescript/docs/pages/_meta.json | 1 + sdk/typescript/docs/pages/examples/_meta.json | 4 +- sdk/typescript/docs/pages/index.mdx | 2 +- sdk/typescript/docs/pages/installation.mdx | 57 +++++++------- .../docs/pages/{FAQ => }/integrations.mdx | 15 ++-- .../docs/pages/playground/_meta.json | 6 +- sdk/typescript/docs/pages/start.mdx | 74 +++++++++---------- 9 files changed, 83 insertions(+), 82 deletions(-) rename sdk/typescript/docs/pages/{FAQ => }/integrations.mdx (98%) diff --git a/sdk/typescript/docs/code-snippets/mixfetchurl.tsx b/sdk/typescript/docs/code-snippets/mixfetchurl.tsx index c89e7b79f5..161400728d 100644 --- a/sdk/typescript/docs/code-snippets/mixfetchurl.tsx +++ b/sdk/typescript/docs/code-snippets/mixfetchurl.tsx @@ -16,8 +16,8 @@ export const GitHubRepoSearch = () => { // Construct the search URL const searchUrl = `https://github.com/search?q=repo:${matchedRepo} fetch(&type=code`; - // Redirect the user to the search results page - window.location.href = searchUrl; + // Redirect the user to a new search results page + window.open(searchUrl, "_blank"); }; return ( diff --git a/sdk/typescript/docs/pages/FAQ/general.mdx b/sdk/typescript/docs/pages/FAQ/general.mdx index b0417bdb5f..f319dfe6d0 100644 --- a/sdk/typescript/docs/pages/FAQ/general.mdx +++ b/sdk/typescript/docs/pages/FAQ/general.mdx @@ -7,7 +7,7 @@ If you would like to integrate parts of the Nym stack to your existing app, plea ##### For builders: ###### SDKs -If you’re looking to build or ‘Nymify’ existing solutions, read on: For developing in Rust or TS/JS, then the Nym SDKs are your go-to. Please visit the [RUST SDK documentation](https://nymtech.net/developers/tutorials/rust-sdk.html) for more RUST-related information and tutorials. +If you’re looking to build or ‘Nymify’ existing solutions, read on: For developing in Rust or TS/JS, then the Nym SDKs are your go-to. Please visit the [Rust SDK documentation](https://nymtech.net/developers/tutorials/rust-sdk.html) for more Rust-related information and tutorials. Stay on this page, the [TS SDK handbook](../) (you are here) for using the TypeScript SDK. These SDKs abstract away much of the messaging and core logic from your app, and allow you to run a Nym client as part of your application process, instead of having to run them separately. In short, they simplify building Nym clients into your project. diff --git a/sdk/typescript/docs/pages/_meta.json b/sdk/typescript/docs/pages/_meta.json index 678ed0bb56..d66720a97d 100644 --- a/sdk/typescript/docs/pages/_meta.json +++ b/sdk/typescript/docs/pages/_meta.json @@ -1,6 +1,7 @@ { "index": "Introduction", "overview": "SDK overview", + "integrations": "Nym integrations", "installation": "Installation", "start": "Getting started", "examples": "Step-by-step examples", diff --git a/sdk/typescript/docs/pages/examples/_meta.json b/sdk/typescript/docs/pages/examples/_meta.json index 630b32b2cf..fd79b8ef06 100644 --- a/sdk/typescript/docs/pages/examples/_meta.json +++ b/sdk/typescript/docs/pages/examples/_meta.json @@ -1,6 +1,6 @@ { - "nym-smart-contracts": "1. Nym Smart Contracts", + "mix-fetch": "1. mixFetch", "mixnet": "2. Mixnet Client", - "mix-fetch": "3. mixFetch", + "nym-smart-contracts": "3. Nym Smart Contracts", "cosmos-kit": "4. Cosmos Kit" } diff --git a/sdk/typescript/docs/pages/index.mdx b/sdk/typescript/docs/pages/index.mdx index f48da16649..1cd5a8f2b6 100644 --- a/sdk/typescript/docs/pages/index.mdx +++ b/sdk/typescript/docs/pages/index.mdx @@ -10,7 +10,7 @@ If you're new to the Nym ecosystem and want to better understand the mixnet, exp For a more in-depth exploration of Nym's architecture, clients, nodes, and SDK examples, please refer to the [Technical Documentation](https://nymtech.net/docs/) section. -If you'd like to build your own app or integrate pieces of the Nym infrastructure using RUST, please use our [RUST SDK documentation](https://nymtech.net/developers/tutorials/rust-sdk.html). +If you'd like to build your own app or integrate pieces of the Nym infrastructure using Rust, please use our [Rust SDK documentation](https://nymtech.net/developers/tutorials/rust-sdk.html). If you're looking for information and setup guides for the various pieces of Nym mixnet infrastructure (mix nodes, gateways, network requesters) and Nyx blockchain validators, then have a look at our [Operators Guide](https://nymtech.net/operators/introduction.html). diff --git a/sdk/typescript/docs/pages/installation.mdx b/sdk/typescript/docs/pages/installation.mdx index 06b0e1e897..7a2a52a39f 100644 --- a/sdk/typescript/docs/pages/installation.mdx +++ b/sdk/typescript/docs/pages/installation.mdx @@ -15,6 +15,37 @@ The different modules in the Typescript SDK allow developers to start building b npm install @nymproject/contract-clients @cosmjs/cosmwasm-stargate @cosmjs/proto-signing @nymproject/sdk-full-fat @nymproject/mix-fetch-full-fat ``` +## MixFetch +#### Overview +MixFetch is a drop-in replacement for [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) that sends HTTP requests through the Nym mixnet. It does this by grabbing the same arguments as traditional fetch and constructing a SOCKS5 request that will be made to the destination host on the Internet via a [SOCKS5](https://nymtech.net/developers/quickstart/socks-proxy.html) [Network Requester](https://nymtech.net/docs/nodes/network-requester.html). + +#### Installation: MixFetch package +In order to fetch data through mixFetch you'll need to use the [`MixFetch package`](https://www.npmjs.com/package/@nymproject/mix-fetch). + +First install the package and its dependencies: + +```bash +npm install @nymproject/mix-fetch-full-fat +``` + +## Mixnet +#### Overview +The [Nym mixnet](https://nymtech.net/docs/architecture/network-overview.html) provides extremely robust protection against network-level surveillance. It splits data into smaller, identically sized,[Sphinx encrypted packet](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf), which are then mixed in with dummy traffic and dispersed through Nym nodes around the world at randomised intervals. Finally these are decrypted and reassembled, preventing the observation of metadata and providing pattern privacy so that it cannot be determined who is communicating with whom. The Nym mixnet is based on a modified version of the [Loopix design](https://www.usenix.org/sites/default/files/conference/protected-files/usenixsecurity17_slides_piotrowska.pdf). + +*You can explore the Nym mixnet using the [mixnet explorer](https://nymtech.net/docs/explorers/mixnet-explorer.html) here.* + + +#### Installation: Mixnet Client +In order to send or receive traffic over the mixnet, you'll need to use the [`Mixnet Client`](https://www.npmjs.com/package/@nymproject/sdk). + +First install the package and its dependencies: + +```bash +npm install @nymproject/sdk-full-fat +``` + + + ## Nym Smart Contracts #### Overview The Nyx blockchain is a general-purpose CosmWasm-enabled smart contract platform, and the home of the smart contracts which keep track of the mixnet, amongst others. @@ -33,33 +64,7 @@ First install the package and its dependencies from Cosmos Stargate: npm install @nymproject/contract-clients @cosmjs/cosmwasm-stargate @cosmjs/proto-signing ``` -## Mixnet -#### Overview -The [Nym mixnet](https://nymtech.net/docs/architecture/network-overview.html) provides extremely robust protection against network-level surveillance. splits data into smaller, identically sized,[Sphinx encrypted packet](https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf), which are then mixed in with dummy traffic and dispersed through Nym nodes around the world at randomised intervals. Finally these are decrypted and reassembled, preventing the observation of metadata and providing pattern privacy so that it cannot be determined who is communicating with whom. The Nym mixnet is based on a modified version of the [Loopix design](https://www.usenix.org/sites/default/files/conference/protected-files/usenixsecurity17_slides_piotrowska.pdf). - -*You can explore the Nym mixnet using the [mixnet explorer](https://nymtech.net/docs/explorers/mixnet-explorer.html) here.* -#### Installation: Mixnet Client -In order to send or receive traffic over the mixnet, you'll need to use the [`Mixnet Client`](https://www.npmjs.com/package/@nymproject/sdk). - -First install the package and its dependencies: - -```bash -npm install @nymproject/sdk-full-fat -``` - -## MixFetch -#### Overview -MixFetch is a drop-in replacement for [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) that sends HTTP requests through the Nym mixnet. It does this by grabbing the same arguments as traditional fetch and constructing a SOCKS5 request that will be made to the destination host on the Internet via a [SOCKS5](https://nymtech.net/developers/quickstart/socks-proxy.html) [Network Requester](https://nymtech.net/docs/nodes/network-requester.html). - -#### Installation: MixFetch package -In order to fetch data through mixFetch you'll need to use the [`MixFetch package`](https://www.npmjs.com/package/@nymproject/mix-fetch). - -First install the package and its dependencies: - -```bash -npm install @nymproject/mix-fetch-full-fat -``` diff --git a/sdk/typescript/docs/pages/FAQ/integrations.mdx b/sdk/typescript/docs/pages/integrations.mdx similarity index 98% rename from sdk/typescript/docs/pages/FAQ/integrations.mdx rename to sdk/typescript/docs/pages/integrations.mdx index 267b803a9f..ea87b1dcea 100644 --- a/sdk/typescript/docs/pages/FAQ/integrations.mdx +++ b/sdk/typescript/docs/pages/integrations.mdx @@ -1,15 +1,9 @@ import Box from '@mui/material/Box'; -import { GitHubRepoSearch } from '../../code-snippets/mixfetchurl'; +import { GitHubRepoSearch } from '../code-snippets/mixfetchurl'; # 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 +### 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: __1. Does your app rely on using `fetch` for its network traffic and remote connections?__ @@ -105,3 +99,8 @@ Again, as detailed in the [FAQ](../FAQ/general): ``` +### Other 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; diff --git a/sdk/typescript/docs/pages/playground/_meta.json b/sdk/typescript/docs/pages/playground/_meta.json index 76d1fa39df..09149f2a76 100644 --- a/sdk/typescript/docs/pages/playground/_meta.json +++ b/sdk/typescript/docs/pages/playground/_meta.json @@ -1,7 +1,7 @@ { - "mixnodes": "1. Query mixnet contract for a list of mix nodes", - "wallet": "1.2. Basic wallet operations", + "mixfetch": "1. Use mixFetch", "traffic": "2. Send traffic over the mixnet", - "mixfetch": "3. Use mixFetch", + "mixnodes": "3.1. Query mixnet contract for a list of mix nodes", + "wallet": "3.2. Basic wallet operations", "cosmos-kit": "4. Cosmos Kit" } diff --git a/sdk/typescript/docs/pages/start.mdx b/sdk/typescript/docs/pages/start.mdx index daada99b2a..be611faf3b 100644 --- a/sdk/typescript/docs/pages/start.mdx +++ b/sdk/typescript/docs/pages/start.mdx @@ -1,28 +1,27 @@ import { Callout } from 'nextra/components' -## Nym Smart Contracts -After having installed your client from the [`Contract Clients`](https://www.npmjs.com/package/@nymproject/contract-clients) to query any of the Nym smart contracts, you can import the packages and execute some methods, signing them with a mnemonic: -````js -import { contracts } from '@nymproject/contract-clients'; -import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate"; -import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"; +## MixFetch -async function main() { - // Generate a signer from a mnemonic - const signer = await DirectSecp256k1HdWallet.fromMnemonic("..."); - const accounts = await signer.getAccounts(); +Use the [`mixFetch`](https://www.npmjs.com/package/@nymproject/mix-fetch) package as a drop-in replacement for `fetch`to send HTTP requests over the Nym mixnet: - // Make a signing client for the Nym Mixnet contract on mainnet - const cosmWasmSigningClient = await SigningCosmWasmClient.connectWithSigner("https://rpc.nymtech.net:443", signer); - const client = new contracts.Mixnet.MixnetClient(cosmWasmSigningClient, accounts[0].address, 'n17srjznxl9dvzdkpwpw24gg668wc73val88a6m5ajg6ankwvz9wtst0cznr'); +```ts +import { mixFetch } from '@nymproject/mix-fetch'; - // Delegate 1 NYM to mixnode with id 100 - const result = await client.delegateToMixnode({ mixId: 100 }, 'auto', undefined, [{ amount: `${1_000_000}`, denom: 'unym' }]); +// HTTP GET +const response = await mixFetch('https://nymtech.net'); +const html = await response.text(); - console.log(`Tx Hash = ${result.transactionHash}`); -}; -```` +// HTTP POST +const apiResponse = await mixFetch('https://api.example.com', { + method: 'POST', + body: JSON.stringify({ foo: 'bar' }), + headers: { [`Content-Type`]: 'application/json', Authorization: `Bearer ${AUTH_TOKEN}` } +}); +``` + +Check the [standard allowed list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to see +if the host you want to `mixFetch` from is whitelisted. ## Mixnet Client After instantiating the [`Mixnet Client`](https://www.npmjs.com/package/@nymproject/sdk), you can use it and send messages to yourself and output them in the console by following these steps: @@ -58,29 +57,26 @@ const main = async () => { }; ```` -## MixFetch - -Use the [`mixFetch`](https://www.npmjs.com/package/@nymproject/mix-fetch) package as a drop-in replacement for `fetch`to send HTTP requests over the Nym mixnet: - -```ts -import { mixFetch } from '@nymproject/mix-fetch'; - -// HTTP GET -const response = await mixFetch('https://nymtech.net'); -const html = await response.text(); - -// HTTP POST -const apiResponse = await mixFetch('https://api.example.com', { - method: 'POST', - body: JSON.stringify({ foo: 'bar' }), - headers: { [`Content-Type`]: 'application/json', Authorization: `Bearer ${AUTH_TOKEN}` } -}); -``` - -Check the [standard allowed list](https://nymtech.net/.wellknown/network-requester/standard-allowed-list.txt) to see -if the host you want to `mixFetch` from is whitelisted. +## Nym Smart Contracts +After having installed your client from the [`Contract Clients`](https://www.npmjs.com/package/@nymproject/contract-clients) to query any of the Nym smart contracts, you can import the packages and execute some methods, signing them with a mnemonic: +````js +import { contracts } from '@nymproject/contract-clients'; +import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate"; +import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"; +async function main() { + // Generate a signer from a mnemonic + const signer = await DirectSecp256k1HdWallet.fromMnemonic("..."); + const accounts = await signer.getAccounts(); + // Make a signing client for the Nym Mixnet contract on mainnet + const cosmWasmSigningClient = await SigningCosmWasmClient.connectWithSigner("https://rpc.nymtech.net:443", signer); + const client = new contracts.Mixnet.MixnetClient(cosmWasmSigningClient, accounts[0].address, 'n17srjznxl9dvzdkpwpw24gg668wc73val88a6m5ajg6ankwvz9wtst0cznr'); + // Delegate 1 NYM to mixnode with id 100 + const result = await client.delegateToMixnode({ mixId: 100 }, 'auto', undefined, [{ amount: `${1_000_000}`, denom: 'unym' }]); + console.log(`Tx Hash = ${result.transactionHash}`); +}; +````