module rust docs

cli/src/modules/connect.rs

@@ -14,11 +14,11 @@ impl Connect {
  let (is_public, url) = match arg_or_server_address.as_deref() {
  Some("public") => {
  tprintln!(ctx, "Connecting to a public node");
- (true, Resolver::default().fetch(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?.url)
+ (true, Resolver::default().get_url(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?)
  }
  None => {
  tprintln!(ctx, "No server set, connecting to a public node");
- (true, Resolver::default().fetch(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?.url)
+ (true, Resolver::default().get_url(WrpcEncoding::Borsh, network_id).await.map_err(|e| e.to_string())?)
  }
  Some(url) => {
  (false, wrpc_client.parse_url_with_network_type(url.to_string(), network_id.into()).map_err(|e| e.to_string())?)

components/consensusmanager/src/session.rs

@@ -91,7 +91,7 @@ impl ConsensusInstance {
 
  /// Returns an unguarded *blocking* consensus session. There's no guarantee that data will not be pruned between
  /// two sequential consensus calls. This session doesn't hold the consensus pruning lock, so it should
- /// be preferred upon [`session_blocking`] when data consistency is not important.
+ /// be preferred upon [`session_blocking()`](Self::session_blocking) when data consistency is not important.
  pub fn unguarded_session_blocking(&self) -> ConsensusSessionBlocking<'static> {
  ConsensusSessionBlocking::new_without_session_guard(self.consensus.clone())
  }
@@ -100,7 +100,7 @@ impl ConsensusInstance {
  /// that consensus state is consistent between operations, that is, no pruning was performed between the calls.
  /// The returned object is an *owned* consensus session type which can be cloned and shared across threads.
  /// The sharing ability is useful for spawning blocking operations on a different thread using the same
- /// session object, see [`ConsensusSessionOwned::spawn_blocking`]. The caller is responsible to make sure
+ /// session object, see [`ConsensusSessionOwned::spawn_blocking()`](ConsensusSessionOwned::spawn_blocking). The caller is responsible to make sure
  /// that the overall lifetime of this session is not too long (~2 seconds max)
  pub async fn session(&self) -> ConsensusSessionOwned {
  let g = self.session_lock.read_owned().await;
@@ -109,7 +109,7 @@ impl ConsensusInstance {
 
  /// Returns an unguarded consensus session. There's no guarantee that data will not be pruned between
  /// two sequential consensus calls. This session doesn't hold the consensus pruning lock, so it should
- /// be preferred upon [`session`] when data consistency is not important.
+ /// be preferred upon [`session()`](Self::session) when data consistency is not important.
  pub fn unguarded_session(&self) -> ConsensusSessionOwned {
  ConsensusSessionOwned::new_without_session_guard(self.consensus.clone())
  }
@@ -139,7 +139,8 @@ impl Deref for ConsensusSessionBlocking<'_> {
 }
 
 /// An *owned* consensus session type which can be cloned and shared across threads.
-/// See method `spawn_blocking` within for context on the usefulness of this type
+/// See method `spawn_blocking` within for context on the usefulness of this type.
+/// Please note - you must use [`ConsensusProxy`] type alias instead of this struct.
 #[derive(Clone)]
 pub struct ConsensusSessionOwned {
  _session_guard: Option<SessionOwnedReadGuard>,

consensus/client/src/error.rs

@@ -1,3 +1,5 @@
+//! The [`Error`](enum@Error) enum used by this crate
+
 use thiserror::Error;
 use wasm_bindgen::{JsError, JsValue};
 use workflow_wasm::jserror::JsErrorData;

consensus/client/src/hash.rs

@@ -1,3 +1,10 @@
+//!
+//! WASM bindings for transaction hashers: [`TransactionSigningHash`](native::TransactionSigningHash)
+//! and [`TransactionSigningHashECDSA`](native::TransactionSigningHashECDSA).
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use kaspa_hashes as native;

consensus/client/src/header.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the Block [`Header`] struct.
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::error::Error;
 use js_sys::{Array, Object};
 use kaspa_consensus_core::hashing;
@@ -59,10 +65,15 @@ export interface IRawHeader {
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM (TypeScript) type definition for the Header-like struct: `Header | IHeader | IRawHeader`.
+ /// 
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "Header | IHeader | IRawHeader")]
  pub type HeaderT;
 }
 
+/// Kaspa Block Header
+/// 
 /// @category Consensus
 #[derive(Clone, Debug, Serialize, Deserialize, CastFromJs)]
 #[serde(rename_all = "camelCase")]

consensus/client/src/input.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the client-side [`TransactionInput`] struct used by the client-side [`Transaction`] struct.
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use crate::TransactionOutpoint;
@@ -33,14 +39,21 @@ export interface ITransactionInputVerboseData { }
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM (TypeScript) type representing `ITransactionInput | TransactionInput`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "ITransactionInput | TransactionInput")]
  pub type TransactionInputT;
+ /// WASM (TypeScript) type representing `ITransactionInput[] | TransactionInput[]`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "(ITransactionInput | TransactionInput)[]")]
  pub type TransactionInputArrayAsArgT;
+ /// WASM (TypeScript) type representing `TransactionInput[]`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "TransactionInput[]")]
  pub type TransactionInputArrayAsResultT;
 }
 
+/// Inner type used by [`TransactionInput`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionInputInner {

consensus/client/src/lib.rs

@@ -1,3 +1,17 @@
+//!
+//! # Client-side consensus primitives.
+//! 
+//! This crate offers client-side primitives mirroring the consensus layer of the Kaspa p2p node.
+//! It declares structs such as [`Transaction`], [`TransactionInput`], [`TransactionOutput`], 
+//! [`TransactionOutpoint`], [`UtxoEntry`], and [`UtxoEntryReference`]
+//! that are used by the Wallet subsystem as well as WASM bindings.
+//! 
+//! Unlike raw consensus primitives (used for high-performance DAG processing) the primitives
+//! offered in this crate are designed to be used in client-side applications. Their internal
+//! data is typically wrapped into `Arc<Mutex<T>>`, allowing for easy sharing between 
+//! async / threaded environments and WASM bindings.
+//! 
+
 pub mod error;
 mod imports;
 mod input;

consensus/client/src/outpoint.rs

@@ -1,3 +1,11 @@
+//!
+//! Implementation of the client-side [`TransactionOutpoint`] used by the [`TransactionInput`] struct.
+//! 
+
+#![allow(non_snake_case)]
+
+use cfg_if::cfg_if;
+
 use crate::imports::*;
 use crate::result::Result;
 
@@ -14,6 +22,7 @@ export interface ITransactionOutpoint {
 }
 "#;
 
+/// Inner type used by [`TransactionOutpoint`]
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Ord, PartialOrd)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionOutpointInner {
@@ -110,29 +119,35 @@ impl TransactionOutpoint {
  }
 }
 
-#[cfg_attr(feature = "wasm32-sdk", wasm_bindgen)]
-impl TransactionOutpoint {
- #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(constructor))]
- pub fn ctor(transaction_id: TransactionId, index: u32) -> TransactionOutpoint {
- Self { inner: Arc::new(TransactionOutpointInner { transaction_id, index }) }
- }
-
- #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(js_name = "getId"))]
- pub fn id_string(&self) -> String {
- format!("{}-{}", self.get_transaction_id_as_string(), self.get_index())
- }
+cfg_if! {
+ if #[cfg(feature = "wasm32-sdk")] {
 
- #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(getter, js_name = transactionId))]
- pub fn get_transaction_id_as_string(&self) -> String {
- self.inner().transaction_id.to_string()
- }
-
- #[cfg_attr(feature = "wasm32-sdk", wasm_bindgen(getter, js_name = index))]
- pub fn get_index(&self) -> TransactionIndexType {
- self.inner().index
+ #[wasm_bindgen]
+ impl TransactionOutpoint {
+ #[wasm_bindgen(constructor)]
+ pub fn ctor(transaction_id: TransactionId, index: u32) -> TransactionOutpoint {
+ Self { inner: Arc::new(TransactionOutpointInner { transaction_id, index }) }
+ }
+
+ #[wasm_bindgen(js_name = "getId")]
+ pub fn id_string(&self) -> String {
+ format!("{}-{}", self.get_transaction_id_as_string(), self.get_index())
+ }
+
+ #[wasm_bindgen(getter, js_name = transactionId)]
+ pub fn get_transaction_id_as_string(&self) -> String {
+ self.inner().transaction_id.to_string()
+ }
+
+ #[wasm_bindgen(getter, js_name = index)]
+ pub fn get_index(&self) -> TransactionIndexType {
+ self.inner().index
+ }
+ }
  }
 }
 
+
 impl std::fmt::Display for TransactionOutpoint {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
  let inner = self.inner();

consensus/client/src/output.rs

@@ -1,3 +1,9 @@
+//!
+//! Implementation of the client-side [`TransactionOutput`] used by the [`Transaction`] struct.
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 
 #[wasm_bindgen(typescript_custom_section)]
@@ -28,14 +34,21 @@ export interface ITransactionOutputVerboseData {
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM (TypeScript) type representing `ITransactionOutput | TransactionOutput`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "ITransactionOutput | TransactionOutput")]
  pub type TransactionOutputT;
+ /// WASM (TypeScript) type representing `ITransactionOutput[] | TransactionOutput[]`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "(ITransactionOutput | TransactionOutput)[]")]
  pub type TransactionOutputArrayAsArgT;
+ /// WASM (TypeScript) type representing `TransactionOutput[]`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "TransactionOutput[]")]
  pub type TransactionOutputArrayAsResultT;
 }
 
+/// Inner type used by [`TransactionOutput`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionOutputInner {

consensus/client/src/result.rs

@@ -1 +1,3 @@
+//! [`Result`] type alias that is bound to the [`Error`](super::error::Error) type from this crate.
+
 pub type Result<T, E = super::error::Error> = std::result::Result<T, E>;

consensus/client/src/serializable/mod.rs

@@ -1,3 +1,24 @@
+//! 
+//! # Standardized JSON serialization and deserialization of Kaspa transactions.
+//! 
+//! This module provides standardized JSON serialization and deserialization of 
+//! Kaspa transactions. There are two sub-modules: `numeric` and `string`.
+//! 
+//! The `numeric` module provides serialization and deserialization of transactions
+//! with all large integer values as `bigint` types in WASM or numerical values that
+//! exceed the largest integer that can be represented by the JavaScript `number` type.
+//! 
+//! The `string` module provides serialization and deserialization of transactions
+//! with all large integer values as `string` types. This allows deserialization
+//! via JSON in JavaScript environments and later conversion to `bigint` types.
+//! 
+//! These data structures can be used for manual transport of transactions using JSON.
+//! For more advanced use cases, please refer to `PSKT` in the [`kaspa_wallet_pskt`](https://docs.rs/kaspa_wallet_pskt) 
+//! crate.
+//! 
+
+#![allow(non_snake_case)]
+
 pub mod numeric;
 pub mod string;
 
@@ -80,6 +101,7 @@ export interface ISerializableTransaction {
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM (TypeScript) representation of the `ISerializableTransaction` interface.
  #[wasm_bindgen(extends = js_sys::Array, typescript_type = "ISerializableTransaction")]
  pub type SerializableTransactionT;
 }

consensus/client/src/serializable/numeric.rs

@@ -1,4 +1,10 @@
-//! This module implements the primitives for external transaction signing.
+//! 
+//! This module implements transaction-related primitives for JSON serialization
+//! where all large integer values (`u64`) are serialized to JSON using `serde` and
+//! can exceed the largest integer value representable by the JavaScript `number` type.
+//! (i.e. transactions serialized using this module can not be deserialized in JavaScript
+//! but may be deserialized in other JSON-capable environments that support large integers)
+//! 
 
 use crate::error::Error;
 use crate::imports::*;

consensus/client/src/serializable/string.rs

@@ -1,4 +1,7 @@
-//! This module implements the primitives for external transaction signing.
+//! 
+//! This module implements transaction-related primitives for JSON serialization
+//! where all large integer values (`u64`) are serialized to and from JSON as strings.
+//! 
 
 use crate::imports::*;
 use crate::result::Result;

consensus/client/src/sign.rs

@@ -1,3 +1,7 @@
+//!
+//! Utilities for signing transactions.
+//! 
+
 use crate::transaction::Transaction;
 use core::iter::once;
 use itertools::Itertools;

consensus/client/src/transaction.rs

@@ -1,3 +1,7 @@
+//!
+//! Declares the client-side [`Transaction`] type, which represents a Kaspa transaction.
+//! 
+
 #![allow(non_snake_case)]
 
 use crate::imports::*;
@@ -53,10 +57,13 @@ export interface ITransactionVerboseData {
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM (TypeScript) type representing `ITransaction | Transaction`
+ /// @category Consensus
  #[wasm_bindgen(typescript_type = "ITransaction | Transaction")]
  pub type TransactionT;
 }
 
+/// Inner type used by [`Transaction`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TransactionInner {

consensus/client/src/utils.rs

@@ -1,3 +1,9 @@
+//!
+//! Client-side utility functions and their WASM bindings.
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::result::Result;
 use kaspa_addresses::*;

consensus/client/src/utxo.rs

@@ -1,3 +1,13 @@
+//!
+//! # UTXO client-side data structures.
+//! 
+//! This module provides client-side data structures for UTXO management.
+//! In particular, the [`UtxoEntry`] and [`UtxoEntryReference`] structs
+//! are used to represent UTXO entries in the wallet subsystem and WASM bindings.
+//! 
+
+#![allow(non_snake_case)]
+
 use crate::imports::*;
 use crate::outpoint::{TransactionOutpoint, TransactionOutpointInner};
 use crate::result::Result;
@@ -29,16 +39,22 @@ export interface IUtxoEntry {
 
 #[wasm_bindgen]
 extern "C" {
+ /// WASM type representing an array of [`UtxoEntryReference`] objects (i.e. `UtxoEntryReference[]`)
  #[wasm_bindgen(extends = Array, typescript_type = "UtxoEntryReference[]")]
  pub type UtxoEntryReferenceArrayT;
+ /// WASM type representing a UTXO entry interface (a UTXO-like object)
  #[wasm_bindgen(typescript_type = "IUtxoEntry")]
  pub type IUtxoEntry;
+ /// WASM type representing an array of UTXO entries (i.e. `IUtxoEntry[]`)
  #[wasm_bindgen(typescript_type = "IUtxoEntry[]")]
  pub type IUtxoEntryArray;
 }
 
+/// A UTXO entry Id is a unique identifier for a UTXO entry defined by the `txid+output_index`.
 pub type UtxoEntryId = TransactionOutpointInner;
 
+/// [`UtxoEntry`] struct represents a client-side UTXO entry.
+/// 
 /// @category Wallet SDK
 #[derive(Clone, Debug, Serialize, Deserialize, CastFromJs)]
 #[serde(rename_all = "camelCase")]
@@ -253,6 +269,7 @@ impl PartialOrd for UtxoEntryReference {
  }
 }
 
+/// An extension trait to convert a JS value into a vec of UTXO entry references.
 pub trait TryIntoUtxoEntryReferences {
  fn try_into_utxo_entry_references(&self) -> Result<Vec<UtxoEntryReference>>;
 }