Merge branch 'feature/new-example-readmes' of github.com:nymtech/nym into feature/new-example-readmes

* consolidated readmes into one root readme with info on the examples

clients/native/README.md

@@ -1,3 +1,4 @@
 # Nym Desktop Client
 
 The Nym Desktop Client communicates with the remote, decentralised nodes which make up the Nym system as a whole. 
+

clients/native/examples/README.md

@@ -0,0 +1,48 @@
+# Nym Desktop Client Code Examples 
+
+This directory contains example code for javascript, python, and rust. Please note that **none of these examples are production-ready**, and are included really just to show how the client interacts with the Nym system. 
+
+> Make sure that you have an instance of the `nym-client` set up and running locally on port 1977 before trying to run any of these examples. 
+
+## Go
+There are two examples here: 
+* `binarysend`, which (as the name suggests) sends a binary file, and 
+* `textsend` which sends a raw text file. 
+
+Both examples send these files over the Nym mixnet to the address of your running Nym client, logging information in your terminal window. 
+
+## Javascript 
+The example included here starts a websocket server on port 8888, the ui of which can be used to send strings over the Nym mixnet to the address of your running Nym client. 
+
+### Prerequisites
+* Reasonably up to date `NodeJS` & `npm` (>= ~v12)
+
+### Running it
+Run the following commands:
+
+```
+# install dependencies
+npm install
+# start a webserver on port 8888 
+npm start 
+```
+
+Then open your browser to `localhost:8888`. 
+
+## Python 
+There are two examples here: 
+* `binarysend`, which (as the name suggests) sends a binary file, and 
+* `textsend` which sends a raw text file. 
+
+Both examples send these files over the Nym mixnet to the address of your running Nym client, logging information in your terminal window. 
+
+Make sure that you have an instance of the `nym-client` set up and running locally on port 1977 before trying to run either of the example scripts. 
+
+## Rust 
+There are two examples here: 
+* `binarysend`, which (as the name suggests) sends a binary file, and 
+* `textsend` which sends a raw text file. 
+
+Both examples send these files over the Nym mixnet to the address of your running Nym client, logging information in your terminal window. 
+
+Make sure that you have an instance of the `nym-client` set up and running locally on port 1977 before trying to run either of the example scripts. 

clients/native/examples/js-examples/websocket/README.md

@@ -1,10 +0,0 @@
-### Prerequisites
-
-* Reasonably up to date Node + `npm`
-
-### Running it
-
-```
-npm install 
-npm start # starts a webserver on port 8888
-```

clients/native/examples/js-examples/websocket/package.json

@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "core-js": "^3.6.5",
-    "html-webpack-plugin": "^4.2.0"
+    "html-webpack-plugin": "^4.2.0",
+    "postcss": "^8.4.5"
   }
 }

clients/native/examples/rust-examples/dummy_file

@@ -0,0 +1,9 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam quis efficitur neque. Quisque aliquet vulputate ante, eget vehicula odio feugiat ac. Nulla ut mattis magna. Aenean tincidunt quis nulla eget eleifend. Cras in pretium sem. Nunc lorem metus, blandit sit amet egestas ut, feugiat quis tellus. Aenean tristique, enim a tincidunt condimentum, eros est blandit nunc, id viverra metus erat at nulla. Vivamus at tellus sodales, feugiat odio vel, laoreet neque. Vivamus posuere nulla ac sodales bibendum.
+
+Vestibulum pulvinar nisi non ultricies egestas. Integer finibus ultrices justo vitae suscipit. Etiam interdum eu justo vel interdum. Morbi sagittis ac nisl quis consequat. Mauris dapibus ut risus ac facilisis. Pellentesque non tortor feugiat, consectetur arcu vel, ullamcorper sapien. Proin sodales purus non orci bibendum, sit amet ultrices justo ullamcorper. Nullam ac risus ac justo ultricies efficitur auctor nec arcu. Etiam sed finibus felis. Suspendisse potenti. Phasellus malesuada velit ac ullamcorper egestas. Sed elementum diam ut est gravida ultricies.
+
+Pellentesque sed metus massa. Cras imperdiet lacus sit amet dolor aliquam, luctus posuere justo hendrerit. Morbi augue ex, gravida a metus sed, scelerisque euismod lacus. Nam consequat sapien ac pellentesque sagittis. Morbi a ultrices massa, vel aliquet ex. Maecenas ac sem diam. Nunc sed erat et ipsum volutpat auctor. Etiam elit felis, commodo vitae ipsum ac, fermentum lobortis arcu. Aliquam eu tempus enim. Curabitur vulputate imperdiet aliquam. Morbi iaculis rhoncus risus at malesuada. Donec accumsan feugiat ligula ut facilisis. Nunc porttitor sit amet est eget malesuada. Sed sed consectetur augue, non dapibus orci. Mauris aliquam pellentesque quam, sit amet pellentesque velit cursus vitae. Morbi sit amet molestie risus.
+
+Nam gravida non ligula a egestas. Fusce sodales, purus id rhoncus mattis, purus est vehicula urna, vel finibus augue velit et est. Donec dictum erat eleifend lobortis iaculis. Praesent id venenatis ante. Donec feugiat, ipsum eget porttitor pulvinar, nisl odio posuere lorem, ut placerat elit nulla a ligula. Suspendisse nec nibh tincidunt, sollicitudin mi a, volutpat ligula. In maximus quam lacus, eget semper dolor sagittis sit amet.
+
+In vitae hendrerit est, quis facilisis dui. In eu ante enim. Nullam hendrerit odio sit amet odio tincidunt eleifend. Aliquam erat volutpat. Curabitur commodo, purus pharetra lobortis rhoncus, tortor massa imperdiet nisl, vel dignissim tortor sem at orci. Aliquam maximus lobortis lacus, eu porttitor purus dapibus ut. Praesent at dapibus felis, efficitur blandit tortor. In hac habitasse platea dictumst. Aenean ultrices, nisl a pretium sagittis, tellus sapien mollis erat, eu consectetur erat mauris sed libero. Duis feugiat dapibus mi, vel ornare velit vehicula mattis. Ut suscipit pharetra leo et sollicitudin.

clients/validator/.env.example

@@ -1,6 +0,0 @@
-NYMD_URL=https://sandbox-validator.nymtech.net
-VALIDATOR_API=https://sandbox-validator.nymtech.net/api
-MIXNET_CONTRACT=nymt1ghd753shjuwexxywmgs4xz7x2q732vcnstz02j
-VESTING_CONTRACT=nymt1nc5tatafv6eyq7llkr2gv50ff9e22mnfp9pc5s
-CURRENCY_PREFIX=nymt
-CHAIN_ID=nym-sandbox

clients/validator/README.md

@@ -3,20 +3,26 @@ Nym Validator Client
 
 A TypeScript client for interacting with CosmWasm smart contracts in Nym validators. 
 
+Running examples
+-----------------
+
+With the code checked out, `cd examples`. This folder contains runnable example code that will set up a blockchain and allow you to interact with it through the client. 
+
 Running tests
 -------------
 
-The tests will be separated into three categories: unit, integration and mock.
-
-Currently the command to run all tests: 
-
 ```
 npm test
 ```
 
-The tests require `.env.example` being renamed to `.env`. The variables and their values for these tests are currently pointing to the `nym-sandbox` environment.
+You can also trigger test execution with a test watcher. I don't have the centuries of life left to me that are needed to fight through the arcana of wiring up a working TypeScript mocha triggered execution setup, so for now my Cargo-based hack is:
 
-`Tests are still in development` - the test libary is `jest` and the test script will execute currently with: `--coverage --verbosity false`
+
+```
+cargo watch -s "cd clients/validator && npm test"
+```
+
+It's ugly but works fine if you have Cargo installed. TypeScript setup help happily accepted here. 
 
 Generating Documentation
 ------------------------

clients/validator/jest.config.js

@@ -1,6 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
-  setupFiles: ["dotenv/config"]
-};

clients/validator/package.json

@@ -6,7 +6,9 @@
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "test": "jest --coverage --verbose false",
+    "build": "tsc",
+    "test": "ts-mocha tests/**/*.test.ts",
+    "coverage": "nyc npm test",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "docs": "typedoc --out docs src/index.ts"
@@ -19,21 +21,27 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
-    "@types/jest": "27.4.0",
+    "@types/chai": "^4.2.15",
+    "@types/expect": "^24.3.0",
+    "@types/mocha": "^8.2.1",
     "@typescript-eslint/eslint-plugin": "^5.7.0",
     "@typescript-eslint/parser": "^5.7.0",
+    "chai": "^4.2.0",
     "eslint": "^7.18.0",
     "eslint-config-airbnb": "^19.0.2",
     "eslint-config-airbnb-typescript": "^16.1.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-import-resolver-root-import": "^1.0.4",
     "eslint-plugin-import": "^2.25.3",
+    "eslint-plugin-mocha": "^10.0.3",
     "eslint-plugin-prettier": "^4.0.0",
-    "jest": "^27.4.5",
+    "mocha": "^8.2.1",
+    "moq.ts": "^7.2.0",
+    "nyc": "^15.1.0",
     "prettier": "^2.5.1",
-    "ts-jest": "^27.1.2",
+    "ts-mocha": "^8.0.0",
     "typedoc": "^0.20.27",
-    "typescript": "^4.5.4"
+    "typescript": "^4.1.3"
   },
   "dependencies": {
     "@cosmjs/cosmwasm-stargate": "^0.27.0-rc2",
@@ -43,7 +51,6 @@
     "@cosmjs/stargate": "^0.27.0-rc2",
     "@cosmjs/tendermint-rpc": "^0.27.0-rc2",
     "axios": "^0.21.1",
-    "cosmjs-types": "^0.4.0",
-    "dotenv": "^10.0.0"
+    "cosmjs-types": "^0.4.0"
   }
 }

clients/validator/src/stargate-helper.ts

@@ -2,12 +2,7 @@ import axios from 'axios';
 import { GasPrice } from '@cosmjs/stargate';
 
 export function nymGasPrice(prefix: string): GasPrice {
-  if (typeof prefix === 'string') {
-    return GasPrice.fromString(`0.025u${prefix}`); // TODO: ideally this ugly conversion shouldn't be hardcoded here.
-  }
-  else {
-    throw new Error(`${prefix} is not of type string`);
-  }
+  return GasPrice.fromString(`0.025u${prefix}`); // TODO: ideally this ugly conversion shouldn't be hardcoded here.
 }
 
 export const downloadWasm = async (url: string): Promise<Uint8Array> => {

clients/validator/tests/integration/client.int.test.ts

@@ -1,92 +0,0 @@
-import validatorClient from "../../src/index";
-import { config } from '../test-utils/config';
-
-let client: validatorClient;
-let mnemonic: string;
-
-beforeEach(async () => {
-    mnemonic = validatorClient.randomMnemonic();
-    client = await validatorClient.connect(
-        mnemonic,
-        config.NYMD_URL as string,
-        config.VALIDATOR_API as string,
-        config.CURRENCY_PREFIX as string,
-        config.MIXNET_CONTRACT as string,
-        config.VESTING_CONTRACT as string
-    );
-});
-
-//todos
-//we want to mock the majority of these tests
-//and keep a few integration tests in place
-
-describe("connect to the nym validator client and perform integration tests against the current testnet", () => {
-    test("get cached mixnodes", async () => {
-        try {
-            const response = await client.getCachedMixnodes();
-            //expect all mixnodes to have their owner address
-            response.forEach(mixnodeDetails => {
-                expect(mixnodeDetails.owner).toHaveLength(43)
-            });
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get balance of address and denom of the network", async () => {
-        try {
-            //provide a users address and get their balance
-            //we expect their balance to be zero, as it's a new account
-            const address = await validatorClient.mnemonicToAddress(mnemonic, config.CURRENCY_PREFIX as string);
-            const response = await client.getBalance(address);
-            expect(response.amount).toStrictEqual("0");
-            expect(response.denom).toBe("unymt");
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get minimium pledge amount for a mixnode", async () => {
-        try {
-            const response = await client.minimumMixnodePledge();
-            expect(response.amount).toBe("100000000");
-            expect(response.denom).toBe(config.CURRENCY_PREFIX as string);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get minimium gateway pledge amount", async () => {
-        try {
-            const response = await client.minimumGatewayPledge();
-            expect(response.amount).toBe("100000000");
-            expect(response.denom).toBe(config.CURRENCY_PREFIX as string);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get current mixnet contract address", () => {
-        try {
-            const response = client.mixnetContract;
-            expect(response).toStrictEqual(config.MIXNET_CONTRACT as string)
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get current vesting contract address", () => {
-        try {
-            const response = client.vestingContract;
-            expect(response).toStrictEqual(config.VESTING_CONTRACT as string)
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-});

clients/validator/tests/integration/signing.client.test.ts

@@ -1,66 +0,0 @@
-import SigningClient from '../../src/signing-client';
-import validator from "../../src/index";
-import { CosmWasmClient } from '@cosmjs/cosmwasm-stargate';
-import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
-import { config } from '../test-utils/config';
-
-let cosmWasmClient: CosmWasmClient;
-let signingClient: SigningClient;
-let mnemonic: string;
-
-beforeEach(async () => {
-    cosmWasmClient = await SigningClient.connect(config.NYMD_URL as string);
-    
-    mnemonic = validator.randomMnemonic();
-    const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic)
-    signingClient = await SigningClient.connectWithNymSigner(
-        wallet,
-        config.NYMD_URL as string,
-        config.VALIDATOR_API as string,
-        config.CURRENCY_PREFIX as string);
-});
-
-describe("alternate between the signing clients of nym and perform basic requests", () => {
-    test("retrieve balance using the cosmwasm client", async () => {
-        try {
-            const randomAddress = await validator.mnemonicToAddress(mnemonic, config.CURRENCY_PREFIX as string);
-            const balance  = await cosmWasmClient.getBalance(randomAddress, config.CURRENCY_PREFIX as string);
-            expect(balance.denom).toStrictEqual(config.CURRENCY_PREFIX as string);
-            expect(balance.amount).toStrictEqual("0");
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-    test("get the chain id of the network", async () => {
-        try {
-            //pass these values in environment variables in the future
-            const chainId = await cosmWasmClient.getChainId();
-            expect(chainId).toStrictEqual(config.CHAIN_ID as string);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-    test("get height then search its block", async () => {
-        try {
-            const height = await cosmWasmClient.getHeight()
-            const block = await cosmWasmClient.getBlock(height);
-            expect(block.header.chainId).toStrictEqual(config.CHAIN_ID as string);
-            expect(block.header.height).toStrictEqual(height);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-    test("get current reward pool", async () => {
-        try {
-            //this is due to change due to when rewards get distributed
-            const rewards = await signingClient.getRewardPool(config.MIXNET_CONTRACT as string);
-            expect(rewards).toStrictEqual("250000000000000");
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-});

clients/validator/tests/integration/validator.api.querier.test.ts

@@ -1,70 +0,0 @@
-import ValidatorApiQuerier from '../../src/validator-api-querier';
-import { config } from '../test-utils/config';
-import { now, elapsed} from '../test-utils/utils';
-
-let client: ValidatorApiQuerier;
-
-beforeEach(() => {
-    client = new ValidatorApiQuerier(config.VALIDATOR_API as string);
-});
-
-//todos
-//we want to mock the majority of these tests
-//and keep a few integration tests in place
-
-describe("call out to the validator api and run queries", () => {
-    test.skip("build client and get all mixnodes", async () => {
-        try {
-            //this test was currently ran against a set of prefix data
-            //this will change
-            const ownerAddress = "nymt1ydqkmz0ddpvkd3l0vyf8k5xjrqtcnxxvhlpdsr";
-            let response = await client.getActiveMixnodes();
-            expect(response[0].owner).toStrictEqual(ownerAddress);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get rewarded mixnodes", async () => {
-        try {
-            // we assume that all mixnodes will have their owners address
-            // also active sets will determine rewarded mixnodes
-            let response = await client.getRewardedMixnodes();
-
-            response.forEach(rNode => {
-                expect(rNode.owner.length).toStrictEqual(43);
-            })
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-    test("get cached gateways and it should be six", async () => {
-        try {
-            //current gateways running in sandbox-testnet 6
-            let response = await client.getCachedGateways();
-            expect(response.length).toStrictEqual(6);
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-
-
-    test("get cached mixnodes", async () => {
-        try {
-            const start = now();
-            let response = await client.getCachedMixnodes();
-            response.forEach(mixnode => {
-                expect(mixnode.owner.length).toStrictEqual(43);
-            })
-            console.log(elapsed(start, true));
-        }
-        catch (e) {
-            console.log(e);
-        }
-    });
-});
-

clients/validator/tests/test-utils/config.ts

@@ -1,9 +0,0 @@
-export const config = {
-    NYMD_URL: process.env.NYMD_URL,
-    VALIDATOR_API: process.env.VALIDATOR_API,
-    MIXNET_CONTRACT: process.env.MIXNET_CONTRACT,
-    VESTING_CONTRACT: process.env.MIXNET_CONTRACT,
-    USER_MNEMONIC: process.env.MNEMONIC,
-    CURRENCY_PREFIX: process.env.CURRENCY_PREFIX,
-    CHAIN_ID: process.env.CHAIN_ID
-}

clients/validator/tests/test-utils/utils.ts

@@ -1,17 +0,0 @@
-// timer actions
-// Store current time as `start`
-export const now = (eventName = null) => {
-    if (eventName) {
-        console.log(`Started ${eventName}..`);
-    }
-    return new Date().getTime();
-}
-
-//takes arg of start time 
-export const elapsed = (beginning: number, log = false) => {
-    const duration = new Date().getTime() - beginning;
-    if (log) {
-        console.log(`${duration / 1000}s`);
-    }
-    return duration;
-}

clients/validator/tests/unit/currency.test.ts

@@ -1,10 +0,0 @@
-const currency = require('../../src/currency');
-
-describe("provide unit tests around the the currency module", () => {
-    test.skip("convert to native balance", () => {
-        const decimal = "12.0346";
-        const value = currency.printableBalanceToNative(decimal);
-        expect(value).toStrictEqual("12034600");
-    });
-});
-

clients/validator/tests/unit/stargate.int.test.ts

@@ -1,27 +0,0 @@
-const stargate = require("../../src/stargate-helper");
-import { config } from '../test-utils/config';
-
-describe("test the stargate functions within the client", () => {
-    test("test that the gas price is returned correctly", () => {
-        const nymCurrency = config.CURRENCY_PREFIX as string;
-        const getGasPrice = stargate.nymGasPrice(nymCurrency);
-        expect(getGasPrice.denom).toBe(`u${nymCurrency}`);
-    });
-
-    test("provide invalid type returns an error message", () => {
-        //pass invalid type
-        expect(() => {
-            const nymCurrency = 13;
-            stargate.nymGasPrice(nymCurrency);
-        }).toThrow("13 is not of type string");
-    });
-
-    //provide test for downloading wasm 
-    //mock this test  
-    // test.skip("providing nothing returns", async () => {
-    //     //pass invalid type
-    //     const downloadWasm = stargate.downloadWasm("http://localhost");
-    //     console.log(downloadWasm);
-    // })
-});
-

clients/validator/tests/unit/validator.unit.test.ts

@@ -1,19 +0,0 @@
-import validator from "../../src/index";
-import { config } from '../test-utils/config';
-
-const NETWORK_DENOM = config.CURRENCY_PREFIX as string;
-
-describe("perform basic interactions with the validator", () => {
-    test("build client and get all mixnodes", async () => {
-        const mnemonic = validator.randomMnemonic();
-        const mnemonicCount = mnemonic.split(" ").length;
-        expect(mnemonicCount).toStrictEqual(24);
-    });
-
-    test("build client and get all mixnodes", async () => {
-        const buildMnemonic = validator.randomMnemonic();
-        const mnemonic = await validator.mnemonicToAddress(buildMnemonic, NETWORK_DENOM);
-        expect(mnemonic).toHaveLength(43);
-        expect(mnemonic).toContain(NETWORK_DENOM);
-    });
-});

clients/validator/tsconfig.json

@@ -5,11 +5,7 @@
         "esModuleInterop": true,
         "strict": true,
         "declaration": true,
-        "outDir": "./dist",
-        "types": [
-            "jest",
-            "node",
-        ]
+        "outDir": "./dist"
     },
     "typedocOptions": {
         "entryPoints": [
@@ -20,11 +16,7 @@
     "exclude": [
         "dist",
         "examples",
-        "node_modules"
-    ],
-    "include": [
         "tests",
-        "./tests/*/*.tsx",
-        "./tests/*/*.ts" 
+        "node_modules"
     ]
 }