fix rpc doc gen

Author: chenyukang

Cargo.toml

@@ -8,6 +8,7 @@ members = [
     "crates/fiber-wasm-db-common",
     "crates/fiber-types",
 ]
+exclude = ["rpc-doc-gen"]
 resolver = "2"
 default-members = ["crates/fiber-bin", "crates/fiber-lib"]
 [profile.release]

Makefile

@@ -67,14 +67,14 @@ coverage-generate-report:
 
 coverage: coverage-run-unittests coverage-collect-data coverage-generate-report
 
-RPC_GEN_VERSION = 0.1.17
+RPC_GEN_VERSION = 0.1.18
 .PHONY: gen-rpc-doc
 gen-rpc-doc:
 	@if ! command -v fiber-rpc-gen >/dev/null 2>&1 || [ "$$(fiber-rpc-gen --version | awk '{print $$2}')" != "$(RPC_GEN_VERSION)" ]; then \
         echo "Installing fiber-rpc-gen $(RPC_GEN_VERSION)..."; \
         cargo install fiber-rpc-gen --version $(RPC_GEN_VERSION) --force; \
 	fi
-	fiber-rpc-gen ./crates/fiber-lib/src/
+	fiber-rpc-gen ./crates/fiber-lib/src/ --extra-types-dir ./crates/fiber-types/src/
 	if grep -q "TODO: add desc" ./crates/fiber-lib/src/rpc/README.md; then \
         echo "Warning: There are 'TODO: add desc' in src/rpc/README.md, please add documentation comments to resolve them"; \
 		exit 1; \

crates/fiber-lib/src/rpc/README.md

@@ -76,6 +76,7 @@ You may refer to the e2e test cases in the `tests/bruno/e2e` directory for examp
     * [Type `Currency`](#type-currency)
     * [Type `GetPaymentCommandResult`](#type-getpaymentcommandresult)
     * [Type `Hash256`](#type-hash256)
+    * [Type `HashAlgorithm`](#type-hashalgorithm)
     * [Type `HopHint`](#type-hophint)
     * [Type `HopRequire`](#type-hoprequire)
     * [Type `Htlc`](#type-htlc)
@@ -390,7 +391,7 @@ Adds a TLC to a channel.
 * `amount` - <em>`u128`</em>, The amount of the TLC
 * `payment_hash` - <em>[Hash256](#type-hash256)</em>, The payment hash of the TLC
 * `expiry` - <em>`u64`</em>, The expiry of the TLC
-* `hash_algorithm` - <em>`Option<HashAlgorithm>`</em>, The hash algorithm of the TLC
+* `hash_algorithm` - <em>Option<[HashAlgorithm](#type-hashalgorithm)></em>, The hash algorithm of the TLC
 
 ##### Returns
 
@@ -528,7 +529,7 @@ Get the node information.
 * `channel_count` - <em>`u32`</em>, The number of channels associated with the node, serialized as a hexadecimal string.
 * `pending_channel_count` - <em>`u32`</em>, The number of pending channels associated with the node, serialized as a hexadecimal string.
 * `peers_count` - <em>`u32`</em>, The number of peers connected to the node, serialized as a hexadecimal string.
-* `udt_cfg_infos` - <em>`UdtCfgInfos`</em>, Configuration information for User-Defined Tokens (UDT) associated with the node.
+* `udt_cfg_infos` - <em>[UdtCfgInfos](#type-udtcfginfos)</em>, Configuration information for User-Defined Tokens (UDT) associated with the node.
 
 ---
 
@@ -556,7 +557,7 @@ Generates a new invoice.
 * `final_expiry_delta` - <em>`Option<u64>`</em>, The final HTLC timeout of the invoice, in milliseconds.
  Minimal value is 16 hours, and maximal value is 14 days.
 * `udt_type_script` - <em>`Option<Script>`</em>, The UDT type script of the invoice.
-* `hash_algorithm` - <em>`Option<HashAlgorithm>`</em>, The hash algorithm of the invoice.
+* `hash_algorithm` - <em>Option<[HashAlgorithm](#type-hashalgorithm)></em>, The hash algorithm of the invoice.
 * `allow_mpp` - <em>`Option<bool>`</em>, Whether allow payment to use MPP
 * `allow_trampoline_routing` - <em>`Option<bool>`</em>, Whether allow payment to use trampoline routing
 
@@ -1089,7 +1090,7 @@ The attributes of the invoice
 * `FallbackAddr` - <em>`String`</em>, The fallback address of the invoice
 * `UdtScript` - <em>[CkbScript](#type-ckbscript)</em>, The udt type script of the invoice
 * `PayeePublicKey` - <em>`PublicKey`</em>, The payee public key of the invoice
-* `HashAlgorithm` - <em>`HashAlgorithm`</em>, The hash algorithm of the invoice
+* `HashAlgorithm` - <em>[HashAlgorithm](#type-hashalgorithm)</em>, The hash algorithm of the invoice
 * `Feature` - <em>`Vec<String>`</em>, The feature flags of the invoice
 * `PaymentSecret` - <em>[Hash256](#type-hash256)</em>, The payment secret of the invoice
 ---
@@ -1302,6 +1303,18 @@ A 256-bit hash digest, used as identifier of channel, payment, transaction hash
 
 
 
+---
+
+<a id="#type-hashalgorithm"></a>
+### Type `HashAlgorithm`
+
+HashAlgorithm is the hash algorithm used in the hash lock.
+
+
+#### Enum with values of
+
+* `CkbHash` - The default hash algorithm, CkbHash
+* `Sha256` - The sha256 hash algorithm
 ---
 
 <a id="#type-hophint"></a>
@@ -1388,7 +1401,7 @@ The Node information.
  When a Node is online this timestamp will be updated to the latest value.
 * `chain_hash` - <em>[Hash256](#type-hash256)</em>, The chain hash of the node.
 * `auto_accept_min_ckb_funding_amount` - <em>`u64`</em>, The minimum CKB funding amount for automatically accepting open channel requests.
-* `udt_cfg_infos` - <em>`UdtCfgInfos`</em>, The UDT configuration infos of the node.
+* `udt_cfg_infos` - <em>[UdtCfgInfos](#type-udtcfginfos)</em>, The UDT configuration infos of the node.
 ---
 
 <a id="#type-paymentcustomrecords"></a>
@@ -1563,7 +1576,7 @@ Data needed to authorize and execute a Time-Locked Contract (TLC) settlement tra
 #### Fields
 
 * `tlc_id` - <em>[TLCId](#type-tlcid)</em>, The ID of the TLC (either offered or received)
-* `hash_algorithm` - <em>`HashAlgorithm`</em>, The hash algorithm used for the TLC
+* `hash_algorithm` - <em>[HashAlgorithm](#type-hashalgorithm)</em>, The hash algorithm used for the TLC
 * `payment_amount` - <em>`u128`</em>, The amount of CKB/UDT involved in the TLC
 * `payment_hash` - <em>[Hash256](#type-hash256)</em>, The hash of the payment preimage
 * `expiry` - <em>`u64`</em>, The expiry time for the TLC in milliseconds
@@ -1604,9 +1617,9 @@ The UDT argument info which is used to identify the UDT configuration
 #### Fields
 
 * `name` - <em>`String`</em>, The name of the UDT.
-* `script` - <em>`UdtScript`</em>, The script of the UDT.
+* `script` - <em>[UdtScript](#type-udtscript)</em>, The script of the UDT.
 * `auto_accept_amount` - <em>`Option<u128>`</em>, The minimum amount of the UDT that can be automatically accepted.
-* `cell_deps` - <em>`Vec<UdtDep>`</em>, The cell deps of the UDT.
+* `cell_deps` - <em>Vec<[UdtDep](#type-udtdep)></em>, The cell deps of the UDT.
 ---
 
 <a id="#type-udtcelldep"></a>
@@ -1638,7 +1651,7 @@ Udt script on-chain dependencies.
 
 #### Fields
 
-* `cell_dep` - <em>`Option<UdtCellDep>`</em>, cell dep described by out_point.
+* `cell_dep` - <em>Option<[UdtCellDep](#type-udtcelldep)></em>, cell dep described by out_point.
 * `type_id` - <em>`Option<Script>`</em>, cell dep described by type ID.
 ---
 

crates/fiber-types/src/cch.rs

@@ -8,13 +8,13 @@ use lightning_invoice::Bolt11Invoice;
 use serde::{Deserialize, Serialize};
 use serde_with::{serde_as, DisplayFromStr};
 
-/// The status of a cross-chain hub order.
+/// The status of a cross-chain hub order, will update as the order progresses.
 #[derive(Debug, Copy, Clone, Serialize, Deserialize, Eq, PartialEq)]
 #[serde(rename_all = "snake_case")]
 pub enum CchOrderStatus {
     /// Order is created and waiting for the incoming invoice to collect enough TLCs.
     Pending = 0,
-    /// The incoming invoice collected the required TLCs.
+    /// The incoming invoice collected the required TLCs and is ready to send outgoing payment to obtain the preimage.
     IncomingAccepted = 1,
     /// The outgoing payment is in flight.
     OutgoingInFlight = 2,

crates/fiber-types/src/channel.rs

@@ -103,12 +103,12 @@ bitflags! {
 // TLC types
 // ============================================================
 
-/// The id of a TLC, it can be either offered or received.
+/// The id of a tlc, it can be either offered or received.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Ord, Hash)]
 pub enum TLCId {
-    /// Offered TLC id
+    /// Offered tlc id
     Offered(u64),
-    /// Received TLC id
+    /// Received tlc id
     Received(u64),
 }
 
@@ -178,12 +178,12 @@ pub enum InboundTlcStatus {
     RemoveAckConfirmed,
 }
 
-/// The status of a TLC
+/// The status of a tlc
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
 pub enum TlcStatus {
-    /// Outbound TLC
+    /// Outbound tlc
     Outbound(OutboundTlcStatus),
-    /// Inbound TLC
+    /// Inbound tlc
     Inbound(InboundTlcStatus),
 }
 

crates/fiber-types/src/invoice.rs

@@ -217,7 +217,7 @@ pub fn parse_hrp(input: &str) -> Result<(Currency, Option<u128>), InvoiceError>
 // Invoice status
 // ============================================================
 
-/// The status of a CKB invoice.
+/// The currency of the invoice, can also used to represent the CKB network chain.
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize)]
 pub enum CkbInvoiceStatus {
     /// The invoice is open and can be paid.
@@ -248,7 +248,7 @@ impl Display for CkbInvoiceStatus {
 // Currency
 // ============================================================
 
-/// The currency of the invoice, can also represent the CKB network chain.
+/// The currency of the invoice, can also used to represent the CKB network chain.
 #[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize, Default)]
 pub enum Currency {
     /// The mainnet currency of CKB.
@@ -374,7 +374,7 @@ pub struct CkbScript(#[serde_as(as = "EntityHex")] pub PackedScript);
 // InvoiceSignature
 // ============================================================
 
-/// Recoverable signature for an invoice.
+/// Recoverable signature
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct InvoiceSignature(pub RecoverableSignature);
 

crates/fiber-types/src/payment.rs

@@ -14,12 +14,23 @@ use strum::{AsRefStr, EnumString};
 // Payment status
 // ============================================================
 
-/// The status of a payment.
+/// The status of a payment, will update as the payment progresses.
+/// The transfer path for payment status is `Created -> Inflight -> Success | Failed`.
+///
+/// **MPP Behavior**: A single session may involve multiple attempts (HTLCs) to fulfill the total amount.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
 pub enum PaymentStatus {
+    /// Initial status. A payment session is created, but no HTLC has been dispatched.
     Created,
+    /// The first hop AddTlc is sent successfully and waiting for the response.
+    ///
+    /// > **MPP Logic**: Status `Inflight` means at least one attempt is still not in `Success`, payment needs more retrying or waiting for HTLC settlement.
     Inflight,
+    /// The payment is finished. All related HTLCs are successfully settled,
+    /// and the aggregate amount equals the total requested amount.
     Success,
+    /// The payment session has terminated. HTLCs have failed and the target
+    /// amount cannot be fulfilled after exhausting all retries.
     Failed,
 }
 
@@ -1022,16 +1033,16 @@ pub struct RemoveTlcFulfill {
 
 use crate::U128Hex;
 
-/// The node and channel information in a payment route hop.
+/// The node and channel information in a payment route hop
 #[serde_as]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct SessionRouteNode {
-    /// The public key of the node.
+    /// the public key of the node
     pub pubkey: Pubkey,
-    /// The amount for this hop.
+    /// the amount for this hop
     #[serde_as(as = "U128Hex")]
     pub amount: u128,
-    /// The channel outpoint for this hop.
+    /// the channel outpoint for this hop
     #[serde_as(as = "EntityHex")]
     pub channel_outpoint: OutPoint,
 }
@@ -1042,16 +1053,15 @@ pub struct SessionRouteNode {
 
 use crate::U64Hex;
 
-/// A router hop information for a payment.
-/// A payment router is an array of RouterHop.
-/// A router hop generally implies hop `target` will receive `amount_received` with `channel_outpoint` of channel.
-/// Improper hop hint may make payment fail, for example the specified channel does not have enough capacity.
+/// A router hop information for a payment, a paymenter router is an array of RouterHop,
+/// a router hop generally implies hop `target` will receive `amount_received` with `channel_outpoint` of channel.
+/// Improper hop hint may make payment fail, for example the specified channel do not have enough capacity.
 #[serde_as]
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
 pub struct RouterHop {
     /// The node that is sending the TLC to the next node.
     pub target: Pubkey,
-    /// The channel of this hop used to receive TLC.
+    /// The channel of this hop used to receive TLC
     #[serde_as(as = "EntityHex")]
     pub channel_outpoint: OutPoint,
     /// The amount that the source node will transfer to the target node.
@@ -1166,12 +1176,13 @@ impl From<molecule_fiber::RemoveTlcReason> for RemoveTlcReason {
 
 /// The router is a list of nodes that the payment will go through.
 /// We store in the payment session and then will use it to track the payment history.
+/// The router is a list of nodes that the payment will go through.
 /// For example:
 ///    `A(amount, channel) -> B -> C -> D`
 /// means A will send `amount` with `channel` to B.
 #[derive(Clone, Debug, Serialize, Deserialize, Default)]
 pub struct SessionRoute {
-    /// The nodes in the route.
+    /// the nodes in the route
     pub nodes: Vec<SessionRouteNode>,
 }
 

crates/fiber-types/src/primitives.rs

@@ -158,8 +158,8 @@ impl From<bitcoin::hashes::sha256::Hash> for Hash256 {
 
 const PUBKEY_SIZE: usize = 33;
 
-/// The public key for a Node.
-/// It stores the serialized form ([u8; 33]) directly for fast comparison and hashing.
+/// The public key for a Node
+/// It stores the serialized form ([u8; 33]) directly for fast comparison and hashing
 #[serde_as]
 #[derive(Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Pubkey(#[serde_as(as = "IfIsHumanReadable<SliceHexNoPrefix, [_; 33]>")] pub [u8; 33]);
@@ -313,7 +313,7 @@ impl TryFrom<molecule_fiber::Pubkey> for Pubkey {
 // Privkey
 // ============================================================
 
-/// A wrapper for secp256k1 secret key.
+/// A wrapper for secp256k1 secret key
 #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
 pub struct Privkey(pub secp256k1::SecretKey);