Misc doc updates (kaspanet#407)

* misc doc updates * Update JS code and add additional comments
Kash-Protocol · Feb 26, 2024 · 088f826 · 088f826
1 parent 2215367
commit 088f826
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 43 deletions.
diff --git a/wallet/core/src/account/mod.rs b/wallet/core/src/account/mod.rs
@@ -30,7 +30,7 @@ use workflow_core::abortable::Abortable;
 /// Notification callback type used by [`Account::sweep`] and [`Account::send`].
 /// Allows tracking in-flight transactions during transaction generation.
 pub type GenerationNotifier = Arc<dyn Fn(&PendingTransaction) + Send + Sync>;
-/// Scan notification callback type used by [`Account::derivation_scan`].
+/// Scan notification callback type used by [`DerivationCapableAccount::derivation_scan`].
 /// Provides derivation discovery scan progress information.
 pub type ScanNotifier = Arc<dyn Fn(usize, usize, u64, Option<TransactionId>) + Send + Sync>;
 

diff --git a/wallet/core/src/lib.rs b/wallet/core/src/lib.rs
@@ -38,9 +38,10 @@
 //! - <https://www.npmjs.com/package/kaspa-wasm>
 //!
 //! The `kaspa-wasm` module is a pure WASM32 module that includes
-//! the entire wallet framework, but does not support RPC, while
-//! the `kaspa` module also includes `isomorphic-ws` simulating
-//! the W3C WebSocket available natively in browsers and supports RPC.
+//! the entire wallet framework, but does not support RPC due to an absence
+//! of a native WebSocket in NodeJs environment, while
+//! the `kaspa` module includes `isomorphic-ws` dependency simulating
+//! the W3C WebSocket and thus supports RPC.
 //!
 //! JavaScript examples for using this framework can be found at:
 //! <https://github.com/kaspanet/rusty-kaspa/tree/master/wasm/nodejs>

diff --git a/wasm/README.md b/wasm/README.md
@@ -15,7 +15,7 @@ codebase within JavaScript environments such as Node.js and Web Browsers.
 - [**Rustdoc** documentation](https://docs.rs/kash-wasm/latest/kash-wasm)
 - [**JSDoc** documentation](https://aspectron.com/docs/kash-wasm/)
 
-Please note that while WASM directly binds JacaScript and Rust resources, their names on JavaScript side
+Please note that while WASM directly binds JavaScript and Rust resources, their names on JavaScript side
 are different from their name in Rust as they conform to the 'camelCase' convention in JavaScript and 
 to the 'snake_case' convention in Rust. 
 
@@ -24,16 +24,9 @@ to the 'snake_case' convention in Rust.
 The APIs are currently separated into the following groups:
 
 - **Transaction API** — Bindings for primitives related to transactions.
-This includes basic primitives related to consensus transactions, as well as
-`MutableTransaction` and `VirtualTransaction` primitives usable for 
-transaction creation.
-
+- **RPC API** — [RPC interface bindings](https://docs.rs/kaspa-wasm/latest/kaspa-wasm/rpc) for the Kaspa node using WebSocket (wRPC) connections.
 - **Wallet API** — API for async core wallet processing tasks.
 
-- **RPC API** — [RPC interface bindings](https://docs.rs/kash-wasm/latest/kash-wasm/rpc) for the Kash node using WebSocket connections.
-Compatible with Rusty Kash as well as with the Golang node (kashd) via the `kash-wrpc-proxy` 
-WebSocket / gRPC proxy (located in `rpc/wrpc/proxy`).
-
 ## Using RPC
 
 There are multiple ways to use RPC:
@@ -46,13 +39,52 @@ WebSocket implementation. Two of such modules are [WebSocket](https://www.npmjs.
 (provides a custom implementation) and [isomorphic-ws](https://www.npmjs.com/package/isomorphic-ws) 
 (built on top of the ws WebSocket module).
 
-You can use the following shims:
 
-```js
-// `websocket` module
-globalThis.WebSocket = require('websocket').w3cwebsocket;
-// `isomorphic-ws` module
-globalThis.WebSocket = require('isomorphic-ws');
+## Loading in a Web App
+
+```html
+<html>
+    <head>
+        <script type="module">
+            import * as kaspa_wasm from './kaspa/kaspa-wasm.js';
+            (async () => {
+                const kaspa = await kaspa_wasm.default('./kaspa/kaspa-wasm_bg.wasm');
+                // ...
+            })();
+        </script>
+    </head>
+    <body></body>
+</html>
+```
+
+## Loading in a Node.js App
+
+```javascript
+// W3C WebSocket module shim
+// this is provided by NPM `kaspa` module and is only needed
+// if you are building WASM libraries for NodeJS from source
+// globalThis.WebSocket = require('websocket').w3cwebsocket;
+
+let {RpcClient,Encoding,initConsolePanicHook} = require('./kaspa-rpc');
+
+// enabling console panic hooks allows WASM to print panic details to console
+// initConsolePanicHook();
+// enabling browser panic hooks will create a full-page DIV with panic details
+// this is useful for mobile devices where console is not available
+// initBrowserPanicHook();
+
+// if port is not specified, it will use the default port for the specified network
+const rpc = new RpcClient("127.0.0.1", Encoding.Borsh, "testnet-10");
+
+(async () => {
+    try {
+        await rpc.connect();
+        let info = await rpc.getInfo();
+        console.log(info);
+    } finally {
+        await rpc.disconnect();
+    }
+})();
 ```
 
 For more details, please follow the [**integrating with Kash**](https://kash-mdbook.aspectron.com/) guide.
diff --git a/wasm/src/lib.rs b/wasm/src/lib.rs
@@ -17,7 +17,7 @@ codebase within JavaScript environments such as Node.js and Web Browsers.
 - [**Rustdoc** documentation](https://docs.rs/kash-wasm/latest/kash-wasm)
 - [**JSDoc** documentation](https://aspectron.com/docs/kash-wasm/)
 
-Please note that while WASM directly binds JacaScript and Rust resources, their names on JavaScript side
+Please note that while WASM directly binds JavaScript and Rust resources, their names on JavaScript side
 are different from their name in Rust as they conform to the 'camelCase' convention in JavaScript and
 to the 'snake_case' convention in Rust.
 
@@ -26,23 +26,42 @@ to the 'snake_case' convention in Rust.
 The APIs are currently separated into the following groups (this will be expanded in the future):
 
 - **Transaction API** — Bindings for primitives related to transactions.
-This includes basic primitives related to consensus transactions, as well as
-`MutableTransaction` and `VirtualTransaction` primitives usable for
-transaction creation.
-
+- **RPC API** — [RPC interface bindings](rpc) for the Kaspa node using WebSocket (wRPC) connections.
 - **Wallet API** — API for async core wallet processing tasks.
 
-- **RPC API** — [RPC interface bindings](rpc) for the Kash node using WebSocket connections.
-Compatible with Rusty Kash as well as with the Golang node (kashd) via the `kash-wrpc-proxy`
-WebSocket / gRPC proxy (located in `rpc/wrpc/proxy`).
+## NPM Modules
+
+For JavaScript / TypeScript environments, there are two
+available NPM modules:
+
+- <https://www.npmjs.com/package/kaspa>
+- <https://www.npmjs.com/package/kaspa-wasm>
+
+The `kaspa-wasm` module is a pure WASM32 module that includes
+the entire wallet framework, but does not support RPC due to an absence
+of a native WebSocket in NodeJs environment, while
+the `kaspa` module includes `isomorphic-ws` dependency simulating
+the W3C WebSocket and thus supports RPC.
+
+## Examples
+
+JavaScript examples for using this framework can be found at:
+<https://github.com/kaspanet/rusty-kaspa/tree/master/wasm/nodejs>
+
+## WASM32 Binaries
+
+For pre-built browser-compatible WASM32 redistributables of this
+framework please see the releases section of the Rusty Kaspa
+repository at <https://github.com/kaspanet/rusty-kaspa/releases>.
 
 ## Using RPC
 
-**NODEJS:** To use WASM RPC client in the Node.js environment, you need to introduce a W3C WebSocket object
-before loading the WASM32 library. You can use any Node.js module that exposes a W3C-compatible
-WebSocket implementation. Two of such modules are [WebSocket](https://www.npmjs.com/package/websocket)
-(provides a custom implementation) and [isomorphic-ws](https://www.npmjs.com/package/isomorphic-ws)
-(built on top of the ws WebSocket module).
+**NODEJS:** If you are building from source, to use WASM RPC client in the NodeJS environment,
+you need to introduce a W3C WebSocket object before loading the WASM32 library. You can use
+any Node.js module that exposes a W3C-compatible WebSocket implementation. Two of such modules
+are [WebSocket](https://www.npmjs.com/package/websocket) (provides a custom implementation)
+and [isomorphic-ws](https://www.npmjs.com/package/isomorphic-ws) (built on top of the ws
+WebSocket module).
 
 You can use the following shims:
 
@@ -62,6 +81,7 @@ globalThis.WebSocket = require('isomorphic-ws');
             import * as kash_wasm from './kash/kash-wasm.js';
             (async () => {
                 const kash = await kash_wasm.default('./kash/kash-wasm_bg.wasm');
+                // ...
             })();
         </script>
     </head>
@@ -73,20 +93,29 @@ globalThis.WebSocket = require('isomorphic-ws');
 
 ```javascript
 // W3C WebSocket module shim
-globalThis.WebSocket = require('websocket').w3cwebsocket;
-
-let {RpcClient,Encoding,init_console_panic_hook,defer} = require('./kash-rpc');
-// init_console_panic_hook();
+// this is provided by NPM `kaspa` module and is only needed
+// if you are building WASM libraries for NodeJS from source
+// globalThis.WebSocket = require('websocket').w3cwebsocket;
 
-let rpc = new RpcClient(Encoding.Borsh,"ws://127.0.0.1:17110");
+let {RpcClient,Encoding,initConsolePanicHook} = require('./kash-rpc');
 
-(async () => {
-    await rpc.connect();
+// enabling console panic hooks allows WASM to print panic details to console
+// initConsolePanicHook();
+// enabling browser panic hooks will create a full-page DIV with panic details
+// this is useful for mobile devices where console is not available
+// initBrowserPanicHook();
 
-    let info = await rpc.getInfo();
-    console.log(info);
+// if port is not specified, it will use the default port for the specified network
+const rpc = new RpcClient("127.0.0.1", Encoding.Borsh, "testnet-10");
 
-    await rpc.disconnect();
+(async () => {
+    try {
+        await rpc.connect();
+        let info = await rpc.getInfo();
+        console.log(info);
+    } finally {
+        await rpc.disconnect();
+    }
 })();
 ```
 

diff --git a/wasm/src/utils.rs b/wasm/src/utils.rs
@@ -7,7 +7,7 @@ use wasm_bindgen::prelude::*;
 // https://github.com/tmrlvi/kash-miner/blob/bf361d02a46c580f55f46b5dfa773477634a5753/src/client/stratum.rs#L36
 const DIFFICULTY_1_TARGET: (u64, i16) = (0xffffu64, 208); // 0xffff 2^208
 
-/// `calculate_difficulty` is based on set_difficulty function: https://github.com/tmrlvi/kash-miner/blob/bf361d02a46c580f55f46b5dfa773477634a5753/src/client/stratum.rs#L375
+/// `calculate_difficulty` is based on set_difficulty function: <https://github.com/tmrlvi/kash-miner/blob/bf361d02a46c580f55f46b5dfa773477634a5753/src/client/stratum.rs#L375>
 #[wasm_bindgen(js_name = calculateDifficulty)]
 pub fn calculate_difficulty(difficulty: f32) -> Result<BigInt, JsError> {
     let mut buf = [0u64, 0u64, 0u64, 0u64];