docs: improve RPC docs for node identifiers and channel rebalancing

Clarify the distinction between Pubkey (secp256k1 hex) and PeerId (base58
hash) across all RPC doc comments and regenerate README.md. Add detailed
documentation for channel rebalancing via send_payment and
send_payment_with_router. Add a glossary section explaining node identifier
types and a standalone channel-rebalancing guide.

Author: quake

crates/fiber-lib/src/fiber/network.rs

@@ -260,10 +260,11 @@ pub struct NodeInfoResponse {
 #[serde_as]
 #[derive(Clone, Serialize, Deserialize, Debug)]
 pub struct PeerInfo {
-    /// The identity public key of the peer.
+    /// The identity public key of the peer (also known as `node_id`).
     pub pubkey: Pubkey,
 
-    /// The peer ID of the peer
+    /// The peer ID of the peer (base58 string, derived by hashing the `pubkey` above).
+    /// This is used for P2P transport connections, e.g. when calling `open_channel` or `disconnect_peer`.
     #[serde_as(as = "DisplayFromStr")]
     pub peer_id: PeerId,
 

crates/fiber-lib/src/fiber/types.rs

@@ -323,8 +323,13 @@ impl Privkey {
     }
 }
 
-/// The public key for a Node
-/// It stores the serialized form ([u8; 33]) directly for fast comparison and hashing
+/// A compressed secp256k1 public key (33 bytes), used as the primary identity of a node.
+/// In the RPC interface this value is also referred to as `node_id`.
+/// It is serialized as a 66-character hex string (e.g. `"02aaaa..."`) in JSON.
+///
+/// Note: `Pubkey` is different from `PeerId`. A `PeerId` is derived by hashing the
+/// public key and is used only for P2P transport connections. You can obtain both
+/// values from the `list_peers` or `node_info` RPC.
 #[serde_as]
 #[derive(Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Pubkey(#[serde_as(as = "IfIsHumanReadable<SliceHexNoPrefix, [_; 33]>")] pub [u8; 33]);

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

@@ -202,7 +202,9 @@ Attempts to open a channel with a peer.
 
 ##### Params
 
-* `peer_id` - <em>`PeerId`</em>, The peer ID to open a channel with, the peer must be connected through the [connect_peer](#peer-connect_peer) rpc first.
+* `peer_id` - <em>`PeerId`</em>, The peer ID to open a channel with (base58 string, derived from the peer's `Pubkey`).
+ The peer must be connected through the [connect_peer](#peer-connect_peer) rpc first.
+ You can obtain a peer's `peer_id` from the `list_peers` RPC.
 * `funding_amount` - <em>`u128`</em>, The amount of CKB or UDT to fund the channel with.
 * `public` - <em>`Option<bool>`</em>, Whether this is a public channel (will be broadcasted to network, and can be used to forward TLCs), an optional parameter, default value is true.
 * `one_way` - <em>`Option<bool>`</em>, Whether this is a one-way channel (will not be broadcasted to network, and can only be used to send payment one way), an optional parameter, default value is false.
@@ -296,7 +298,8 @@ Lists all channels.
 
 ##### Params
 
-* `peer_id` - <em>`Option<PeerId>`</em>, The peer ID to list channels for, an optional parameter, if not provided, all channels will be listed
+* `peer_id` - <em>`Option<PeerId>`</em>, The peer ID to list channels for (base58 string, derived from the peer's `Pubkey`).
+ An optional parameter, if not provided, all channels will be listed.
 * `include_closed` - <em>`Option<bool>`</em>, Whether to include closed channels in the list, an optional parameter, default value is false
 * `only_pending` - <em>`Option<bool>`</em>, When set to true, only return channels that are still being opened (non-final states:
  negotiating, collaborating on funding tx, signing, awaiting tx signatures, awaiting channel
@@ -513,7 +516,9 @@ Get the node information.
 
 * `version` - <em>`String`</em>, The version of the node software.
 * `commit_hash` - <em>`String`</em>, The commit hash of the node software.
-* `node_id` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the node.
+* `node_id` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of this node (secp256k1 compressed, hex string).
+ This is the same value referred to as `pubkey` in `list_peers` responses.
+ Note: this is different from `peer_id`, which is a base58 hash derived from this key.
 * `features` - <em>`Vec<String>`</em>, The features supported by the node.
 * `node_name` - <em>`Option<String>`</em>, The optional name of the node.
 * `addresses` - <em>`Vec<MultiAddr>`</em>, A list of multi-addresses associated with the node.
@@ -653,7 +658,9 @@ Sends a payment to a peer.
 
 ##### Params
 
-* `target_pubkey` - <em>Option<[Pubkey](#type-pubkey)></em>, the identifier of the payment target
+* `target_pubkey` - <em>Option<[Pubkey](#type-pubkey)></em>, The public key (`Pubkey`) of the payment target node, serialized as a hex string.
+ You can obtain a node's pubkey via the `node_info` or `graph_nodes` RPC.
+ Note: this is the `Pubkey` (secp256k1 public key), not the `PeerId`.
 * `amount` - <em>`Option<u128>`</em>, the amount of the payment, the unit is Shannons for non UDT payment
  If not set and there is a invoice, the amount will be set to the invoice amount
 * `payment_hash` - <em>Option<[Hash256](#type-hash256)></em>, the hash to use within the payment's HTLC.
@@ -676,7 +683,12 @@ Sends a payment to a peer.
  payer to `t1`, and the inner trampoline onion will encode `t1 -> t2 -> ... -> final`.
 * `keysend` - <em>`Option<bool>`</em>, keysend payment
 * `udt_type_script` - <em>`Option<Script>`</em>, udt type script for the payment
-* `allow_self_payment` - <em>`Option<bool>`</em>, allow self payment, default is false
+* `allow_self_payment` - <em>`Option<bool>`</em>, Allow paying yourself through a circular route, default is false.
+ This is useful for **channel rebalancing**: the payment flows out of one channel and
+ back through another, shifting liquidity between your channels without changing your
+ total balance (only routing fees are deducted).
+ Set `target_pubkey` to your own node pubkey and `keysend` to `true` to perform a rebalance.
+ Note: `allow_self_payment` is not compatible with trampoline routing.
 * `custom_records` - <em>Option<[PaymentCustomRecords](#type-paymentcustomrecords)></em>, Some custom records for the payment which contains a map of u32 to Vec<u8>
  The key is the record type, and the value is the serialized data
  For example:
@@ -783,9 +795,19 @@ Builds a router with a list of pubkeys and required channels.
 <a id="payment-send_payment_with_router"></a>
 #### Method `send_payment_with_router`
 
-Sends a payment to a peer with specified router
+Sends a payment to a peer with specified router.
  This method differs from SendPayment in that it allows users to specify a full route manually.
- This can be used for things like rebalancing.
+
+ A typical use case is **channel rebalancing**: you can construct a circular route
+ (your node -> intermediate nodes -> your node) to shift liquidity between your channels.
+
+ To rebalance, follow these steps:
+
+ 1. Call `build_router` with `hops_info` defining the circular route you want,
+    e.g. your_node -> peer_A -> peer_B -> your_node.
+ 2. Call `send_payment_with_router` with the returned `router_hops` and `keysend: true`.
+
+ Only routing fees are deducted; your total balance across channels remains the same.
 
 ##### Params
 
@@ -865,7 +887,7 @@ Disconnect from a peer.
 
 ##### Params
 
-* `peer_id` - <em>`PeerId`</em>, The peer ID of the peer to disconnect.
+* `peer_id` - <em>`PeerId`</em>, The peer ID of the peer to disconnect (base58 string, derived from the peer's `Pubkey`).
 
 ##### Returns
 
@@ -1122,7 +1144,7 @@ The channel data structure
 * `is_one_way` - <em>`bool`</em>, Is this channel one-way?
  Combines with is_acceptor to determine if the channel able to send payment to the counterparty or not.
 * `channel_outpoint` - <em>`Option<OutPoint>`</em>, The outpoint of the channel
-* `peer_id` - <em>`PeerId`</em>, The peer ID of the channel
+* `peer_id` - <em>`PeerId`</em>, The peer ID of the channel counterparty (base58 string, derived from the peer's `Pubkey`).
 * `funding_udt_type_script` - <em>`Option<Script>`</em>, The UDT type script of the channel
 * `state` - <em>[ChannelState](#type-channelstate)</em>, The state of the channel
 * `local_balance` - <em>`u128`</em>, The local balance of the channel
@@ -1155,8 +1177,8 @@ The Channel information.
 #### Fields
 
 * `channel_outpoint` - <em>`OutPoint`</em>, The outpoint of the channel.
-* `node1` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the first node.
-* `node2` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the second node.
+* `node1` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the first node (secp256k1 compressed, hex string).
+* `node2` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the second node (secp256k1 compressed, hex string).
 * `created_timestamp` - <em>`u64`</em>, The created timestamp of the channel, which is the block header timestamp of the block
  that contains the channel funding transaction.
 * `update_info_of_node1` - <em>Option<[ChannelUpdateInfo](#type-channelupdateinfo)></em>, The update info from node1 to node2, e.g. timestamp, fee_rate, tlc_expiry_delta, tlc_minimum_value
@@ -1349,7 +1371,7 @@ The Node information.
 * `version` - <em>`String`</em>, The version of the node.
 * `addresses` - <em>`Vec<MultiAddr>`</em>, The addresses of the node.
 * `features` - <em>`Vec<String>`</em>, The node features supported by the node.
-* `node_id` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the node.
+* `node_id` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the node (secp256k1 compressed, hex string), same as `pubkey` in `list_peers`.
 * `timestamp` - <em>`u64`</em>, The latest timestamp set by the owner for the node announcement.
  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.
@@ -1407,8 +1429,9 @@ The information about a peer connected to the node.
 
 #### Fields
 
-* `pubkey` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the peer.
-* `peer_id` - <em>`PeerId`</em>, The peer ID of the peer
+* `pubkey` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the peer (also known as `node_id`).
+* `peer_id` - <em>`PeerId`</em>, The peer ID of the peer (base58 string, derived by hashing the `pubkey` above).
+ This is used for P2P transport connections, e.g. when calling `open_channel` or `disconnect_peer`.
 * `address` - <em>`MultiAddr`</em>, The multi-address associated with the connecting peer.
  Note: this is only the address which used for connecting to the peer, not all addresses of the peer.
  The `graph_nodes` in Graph rpc module will return all addresses of the peer.
@@ -1426,8 +1449,13 @@ A wrapper for secp256k1 secret key
 <a id="#type-pubkey"></a>
 ### Type `Pubkey`
 
-The public key for a Node
- It stores the serialized form ([u8; 33]) directly for fast comparison and hashing
+A compressed secp256k1 public key (33 bytes), used as the primary identity of a node.
+ In the RPC interface this value is also referred to as `node_id`.
+ It is serialized as a 66-character hex string (e.g. `"02aaaa..."`) in JSON.
+
+ Note: `Pubkey` is different from `PeerId`. A `PeerId` is derived by hashing the
+ public key and is used only for P2P transport connections. You can obtain both
+ values from the `list_peers` or `node_info` RPC.
 
 
 

crates/fiber-lib/src/rpc/channel.rs

@@ -34,7 +34,9 @@ use tentacle::secio::PeerId;
 #[serde_as]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct OpenChannelParams {
-    /// The peer ID to open a channel with, the peer must be connected through the [connect_peer](#peer-connect_peer) rpc first.
+    /// The peer ID to open a channel with (base58 string, derived from the peer's `Pubkey`).
+    /// The peer must be connected through the [connect_peer](#peer-connect_peer) rpc first.
+    /// You can obtain a peer's `peer_id` from the `list_peers` RPC.
     #[serde_as(as = "DisplayFromStr")]
     pub peer_id: PeerId,
 
@@ -162,7 +164,8 @@ pub struct AcceptChannelResult {
 #[serde_as]
 #[derive(Serialize, Deserialize)]
 pub struct ListChannelsParams {
-    /// The peer ID to list channels for, an optional parameter, if not provided, all channels will be listed
+    /// The peer ID to list channels for (base58 string, derived from the peer's `Pubkey`).
+    /// An optional parameter, if not provided, all channels will be listed.
     #[serde_as(as = "Option<DisplayFromStr>")]
     pub peer_id: Option<PeerId>,
     /// Whether to include closed channels in the list, an optional parameter, default value is false
@@ -269,7 +272,7 @@ pub struct Channel {
     #[serde_as(as = "Option<EntityHex>")]
     /// The outpoint of the channel
     pub channel_outpoint: Option<OutPoint>,
-    /// The peer ID of the channel
+    /// The peer ID of the channel counterparty (base58 string, derived from the peer's `Pubkey`).
     #[serde_as(as = "DisplayFromStr")]
     pub peer_id: PeerId,
     /// The UDT type script of the channel

crates/fiber-lib/src/rpc/graph.rs

@@ -145,7 +145,7 @@ pub struct NodeInfo {
     pub addresses: Vec<MultiAddr>,
     /// The node features supported by the node.
     pub features: Vec<String>,
-    /// The identity public key of the node.
+    /// The identity public key of the node (secp256k1 compressed, hex string), same as `pubkey` in `list_peers`.
     pub node_id: Pubkey,
     #[serde_as(as = "U64Hex")]
     /// The latest timestamp set by the owner for the node announcement.
@@ -201,9 +201,9 @@ pub struct ChannelInfo {
     /// The outpoint of the channel.
     #[serde_as(as = "EntityHex")]
     pub channel_outpoint: OutPoint,
-    /// The identity public key of the first node.
+    /// The identity public key of the first node (secp256k1 compressed, hex string).
     pub node1: Pubkey,
-    /// The identity public key of the second node.
+    /// The identity public key of the second node (secp256k1 compressed, hex string).
     pub node2: Pubkey,
     /// The created timestamp of the channel, which is the block header timestamp of the block
     /// that contains the channel funding transaction.

crates/fiber-lib/src/rpc/info.rs

@@ -27,7 +27,9 @@ pub struct NodeInfoResult {
     /// The commit hash of the node software.
     pub commit_hash: String,
 
-    /// The identity public key of the node.
+    /// The identity public key of this node (secp256k1 compressed, hex string).
+    /// This is the same value referred to as `pubkey` in `list_peers` responses.
+    /// Note: this is different from `peer_id`, which is a base58 hash derived from this key.
     pub node_id: Pubkey,
 
     /// The features supported by the node.

crates/fiber-lib/src/rpc/payment.rs

@@ -97,7 +97,9 @@ impl From<PaymentCustomRecords> for crate::fiber::PaymentCustomRecords {
 #[serde_as]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct SendPaymentCommandParams {
-    /// the identifier of the payment target
+    /// The public key (`Pubkey`) of the payment target node, serialized as a hex string.
+    /// You can obtain a node's pubkey via the `node_info` or `graph_nodes` RPC.
+    /// Note: this is the `Pubkey` (secp256k1 public key), not the `PeerId`.
     pub target_pubkey: Option<Pubkey>,
 
     /// the amount of the payment, the unit is Shannons for non UDT payment
@@ -153,7 +155,12 @@ pub struct SendPaymentCommandParams {
     /// udt type script for the payment
     pub udt_type_script: Option<Script>,
 
-    /// allow self payment, default is false
+    /// Allow paying yourself through a circular route, default is false.
+    /// This is useful for **channel rebalancing**: the payment flows out of one channel and
+    /// back through another, shifting liquidity between your channels without changing your
+    /// total balance (only routing fees are deducted).
+    /// Set `target_pubkey` to your own node pubkey and `keysend` to `true` to perform a rebalance.
+    /// Note: `allow_self_payment` is not compatible with trampoline routing.
     pub allow_self_payment: Option<bool>,
 
     /// Some custom records for the payment which contains a map of u32 to Vec<u8>
@@ -316,9 +323,19 @@ trait PaymentRpc {
         params: BuildRouterParams,
     ) -> Result<BuildPaymentRouterResult, ErrorObjectOwned>;
 
-    /// Sends a payment to a peer with specified router
+    /// Sends a payment to a peer with specified router.
     /// This method differs from SendPayment in that it allows users to specify a full route manually.
-    /// This can be used for things like rebalancing.
+    ///
+    /// A typical use case is **channel rebalancing**: you can construct a circular route
+    /// (your node -> intermediate nodes -> your node) to shift liquidity between your channels.
+    ///
+    /// To rebalance, follow these steps:
+    ///
+    /// 1. Call `build_router` with `hops_info` defining the circular route you want,
+    ///    e.g. your_node -> peer_A -> peer_B -> your_node.
+    /// 2. Call `send_payment_with_router` with the returned `router_hops` and `keysend: true`.
+    ///
+    /// Only routing fees are deducted; your total balance across channels remains the same.
     #[method(name = "send_payment_with_router")]
     async fn send_payment_with_router(
         &self,
@@ -366,9 +383,9 @@ where
         self.build_router(params).await
     }
 
-    /// Sends a payment to a peer with specified router
+    /// Sends a payment to a peer with specified router.
     /// This method differs from SendPayment in that it allows users to specify a full route manually.
-    /// This can be used for things like rebalancing.
+    /// This can be used for things like channel rebalancing.
     async fn send_payment_with_router(
         &self,
         params: SendPaymentWithRouterParams,

crates/fiber-lib/src/rpc/peer.rs

@@ -23,7 +23,7 @@ pub struct ConnectPeerParams {
 #[serde_as]
 #[derive(Serialize, Deserialize, Debug)]
 pub struct DisconnectPeerParams {
-    /// The peer ID of the peer to disconnect.
+    /// The peer ID of the peer to disconnect (base58 string, derived from the peer's `Pubkey`).
     #[serde_as(as = "DisplayFromStr")]
     pub peer_id: PeerId,
 }