unify RPC public key field names

Rename node_id/public_key RPC output fields to pubkey, sync tests and fiber-js types, regenerate RPC docs, and simplify glossary wording.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: quake

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

@@ -299,7 +299,7 @@ async fn test_rpc_graph() {
     eprintln!("Graph nodes: {:#?}", graph_nodes);
 
     assert!(!graph_nodes.nodes.is_empty());
-    assert!(graph_nodes.nodes.iter().any(|n| n.node_id == node_1.pubkey));
+    assert!(graph_nodes.nodes.iter().any(|n| n.pubkey == node_1.pubkey));
     assert!(graph_nodes
         .nodes
         .iter()
@@ -469,10 +469,10 @@ async fn test_rpc_node_info() {
     assert_eq!(node_info.default_funding_lock_script, Default::default());
 }
 
-/// Test that node_id in node_info RPC and payee_public_key in invoice RPC
+/// Test that pubkey in node_info RPC and payee_public_key in invoice RPC
 /// have the same JSON format (both without "0x" prefix).
 #[tokio::test]
-async fn test_rpc_node_id_and_payee_public_key_same_format() {
+async fn test_rpc_pubkey_and_payee_public_key_same_format() {
     let (nodes, _channels) = create_n_nodes_network_with_params(
         &[(
             (0, 1),
@@ -491,9 +491,9 @@ async fn test_rpc_node_id_and_payee_public_key_same_format() {
 
     // Get node_info raw response
     let node_info_raw = node_0.send_rpc_request_raw("node_info", ()).await.unwrap();
-    let node_id = node_info_raw["node_id"]
+    let pubkey = node_info_raw["pubkey"]
         .as_str()
-        .expect("node_id should be a string");
+        .expect("pubkey should be a string");
 
     // Create an invoice and get raw response
     let new_invoice_params = NewInvoiceParams {
@@ -527,18 +527,18 @@ async fn test_rpc_node_id_and_payee_public_key_same_format() {
 
     // Both should have the same format (without "0x" prefix)
     assert_eq!(
-        node_id, payee_public_key,
-        "node_id and payee_public_key should have the same format.\n\
-         node_id: {}\n\
+        pubkey, payee_public_key,
+        "pubkey and payee_public_key should have the same format.\n\
+         pubkey: {}\n\
          payee_public_key: {}",
-        node_id, payee_public_key
+        pubkey, payee_public_key
     );
 
     // Verify neither has "0x" prefix
     assert!(
-        !node_id.starts_with("0x"),
-        "node_id should not have 0x prefix, got: {}",
-        node_id
+        !pubkey.starts_with("0x"),
+        "pubkey should not have 0x prefix, got: {}",
+        pubkey
     );
     assert!(
         !payee_public_key.starts_with("0x"),

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

@@ -324,7 +324,7 @@ impl Privkey {
 }
 
 /// 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`.
+/// In the RPC interface this value is exposed as fields such as `pubkey`.
 /// 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

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

@@ -515,7 +515,7 @@ 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 this node (secp256k1 compressed, hex string).
+* `pubkey` - <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.
@@ -1370,7 +1370,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 (secp256k1 compressed, hex string), same as `pubkey` in `list_peers`.
+* `pubkey` - <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.
@@ -1428,7 +1428,7 @@ The information about a peer connected to the node.
 
 #### Fields
 
-* `pubkey` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the peer (also known as `node_id`).
+* `pubkey` - <em>[Pubkey](#type-pubkey)</em>, The identity public key of the 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.
@@ -1447,7 +1447,7 @@ A wrapper for secp256k1 secret key
 ### Type `Pubkey`
 
 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`.
+ In the RPC interface this value is exposed as fields such as `pubkey`.
  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

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

@@ -146,7 +146,7 @@ pub struct NodeInfo {
     /// The node features supported by the node.
     pub features: Vec<String>,
     /// The identity public key of the node (secp256k1 compressed, hex string), same as `pubkey` in `list_peers`.
-    pub node_id: Pubkey,
+    pub pubkey: Pubkey,
     #[serde_as(as = "U64Hex")]
     /// 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.
@@ -166,7 +166,7 @@ impl From<super::super::fiber::graph::NodeInfo> for NodeInfo {
             node_name: value.node_name.to_string(),
             version: value.version,
             addresses: value.addresses,
-            node_id: value.node_id,
+            pubkey: value.node_id,
             timestamp: value.timestamp,
             features: value.features.enabled_features_names(),
             chain_hash: get_chain_hash(),

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

@@ -30,7 +30,7 @@ pub struct NodeInfoResult {
     /// 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,
+    pub pubkey: Pubkey,
 
     /// The features supported by the node.
     pub features: Vec<String>,
@@ -137,7 +137,7 @@ impl InfoRpcServerImpl {
             version,
             commit_hash,
             features: response.features.enabled_features_names(),
-            node_id: response.node_id,
+            pubkey: response.node_id,
             node_name: response.node_name.map(|name| name.to_string()),
             addresses: response.addresses,
             chain_hash: response.chain_hash,

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

@@ -31,7 +31,7 @@ pub struct DisconnectPeerParams {
 /// The information about a peer connected to the node.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PeerInfo {
-    /// The identity public key of the peer (also known as `node_id`).
+    /// The identity public key of the peer.
     pub pubkey: Pubkey,
 
     /// The multi-address associated with the connecting peer.

docs/glossary.md

@@ -44,33 +44,12 @@ The "Asset Handling Fee." Intermediate nodes lock up their own liquidity to forw
 ## Watchtower
 Your "Asset Bodyguard." Since channel asset states are stored off-chain, a dishonest partner might try to broadcast an "old agreement" to steal funds while you are offline. A Watchtower monitors the CKB chain 24/7 and automatically intercepts any cheating attempts, punishing the attacker.
 
-## Node Identifiers: Pubkey, Node ID, and Peer ID
+## Node Identifiers: Pubkey and Peer ID
 
-A Fiber node has two forms of identity. They look different, serve different purposes, and are **not interchangeable** in RPC calls.
+Fiber uses two identity forms:
 
-### Pubkey (aka Node ID)
+- **Pubkey**: a 33-byte compressed secp256k1 public key (66-char hex), e.g. `"02ab1234..."`.
+- **Peer ID**: a base58 transport identifier derived from the pubkey.
 
-A 33-byte compressed secp256k1 public key, displayed as a 66-character hex string (e.g. `"02ab1234..."`). This is the cryptographic identity of a node. In the RPC interface it appears under several field names depending on context:
-
-| RPC Field | Used In |
-|-----------|---------|
-| `node_id` | `node_info`, `graph_nodes` |
-| `pubkey` | `list_peers`, `graph_nodes`, `hop_hints` |
-| `target_pubkey` | `send_payment` |
-| `node1` / `node2` | `graph_channels` |
-
-All of the above are the same type (`Pubkey`) and can be used wherever a `Pubkey` is expected.
-
-### Peer ID
-
-A base58-encoded string (e.g. `"QmYJnK7..."`), derived by **hashing** the node's `Pubkey`. This is used by the P2P transport layer to identify network connections. The derivation is one-way: you cannot recover a `Pubkey` from a `Peer ID`.
-
-| RPC Field | Used In |
-|-----------|---------|
-| `peer_id` | `open_channel`, `list_channels`, `disconnect_peer`, `list_peers` |
-
-### Which One to Use?
-
-- **Payment-related RPCs** (`send_payment`, `build_router`, etc.) expect a **`Pubkey`** (hex).
-- **Connection/channel management RPCs** (`open_channel`, `disconnect_peer`, etc.) expect a **`Peer ID`** (base58).
-- The `list_peers` RPC returns **both** `pubkey` and `peer_id` for each connected peer, making it easy to look up either value.
+For RPC usage, treat **`pubkey` as the standard node identity**.  
+`Peer ID` is mainly an internal/P2P transport identifier and is generally not what you pass around in normal RPC workflows.

fiber-js/src/types/graph.ts

@@ -39,7 +39,7 @@ type UdtCfgInfos = UdtArgInfo[];
 interface NodeInfo {
     node_name: string;
     addresses: string[];
-    node_id: HexString;
+    pubkey: HexString;
     timestamp: HexString;
     chain_hash: HexString;
     auto_accept_min_ckb_funding_amount: HexString;

fiber-js/src/types/info.ts

@@ -5,7 +5,7 @@ import { UdtCfgInfos } from "./graph";
 interface NodeInfoResult {
     version: string;
     commit_hash: string;
-    node_id: string;
+    pubkey: string;
     node_name?: string;
     addresses: string[];
     chain_hash: HexString;