From 02854ae6bbc7f194feb3364549f0b1cbca2c67ca Mon Sep 17 00:00:00 2001
From: yukang <moorekang@gmail.com>
Date: Tue, 26 Sep 2023 10:25:19 +0800
Subject: [PATCH] fix SubscriptionRpc document issue

---
 rpc/README.md                  | 116 +++++++++++++++++++++++++++++++++
 rpc/src/module/subscription.rs |  25 ++++---
 2 files changed, 132 insertions(+), 9 deletions(-)

diff --git a/rpc/README.md b/rpc/README.md
index 93a1253817..dfe55f2855 100644
--- a/rpc/README.md
+++ b/rpc/README.md
@@ -4835,6 +4835,122 @@ socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x
     * `topic`: `string`
 * result: `string`
 
+Subscribes to a topic.
+
+###### Params
+
+*   `topic` - Subscription topic (enum: new_tip_header | new_tip_block | new_transaction | proposed_transaction | rejected_transaction)
+
+###### Returns
+
+This RPC returns the subscription ID as the result. CKB node will push messages in the subscribed topics to the current RPC connection. The subscript ID is also attached as `params.subscription` in the push messages.
+
+Example push message:
+
+
+```
+{
+  "jsonrpc": "2.0",
+  "method": "subscribe",
+  "params": {
+    "result": { ... },
+    "subscription": "0x2a"
+  }
+}
+```
+
+
+###### Topics
+
+###### `new_tip_header`
+
+Whenever there’s a block that is appended to the canonical chain, the CKB node will publish the block header to subscribers.
+
+The type of the `params.result` in the push message is [`HeaderView`](#type-headerview).
+
+###### `new_tip_block`
+
+Whenever there’s a block that is appended to the canonical chain, the CKB node will publish the whole block to subscribers.
+
+The type of the `params.result` in the push message is [`BlockView`](#type-blockview).
+
+###### `new_transaction`
+
+Subscribers will get notified when a new transaction is submitted to the pool.
+
+The type of the `params.result` in the push message is [`PoolTransactionEntry`](#type-pooltransactionentry).
+
+###### `proposed_transaction`
+
+Subscribers will get notified when an in-pool transaction is proposed by chain.
+
+The type of the `params.result` in the push message is [`PoolTransactionEntry`](#type-pooltransactionentry).
+
+###### `rejected_transaction`
+
+Subscribers will get notified when a pending transaction is rejected by tx-pool.
+
+The type of the `params.result` in the push message is an array contain:
+
+The type of the `params.result` in the push message is a two-elements array, where
+
+*   the first item type is [`PoolTransactionEntry`](#type-pooltransactionentry), and
+
+*   the second item type is [`PoolTransactionReject`](#type-pooltransactionreject).
+
+###### Examples
+
+Subscribe Request
+
+
+```
+{
+  "id": 42,
+  "jsonrpc": "2.0",
+  "method": "subscribe",
+  "params": [
+    "new_tip_header"
+  ]
+}
+```
+
+
+Subscribe Response
+
+
+```
+{
+  "id": 42,
+  "jsonrpc": "2.0",
+  "result": "0xf3"
+}
+
+Unsubscribe Request
+
+```json
+{
+  "id": 42,
+  "jsonrpc": "2.0",
+  "method": "unsubscribe",
+  "params": [
+    "0xf3"
+  ]
+}
+```
+
+
+Unsubscribe Response
+
+
+```
+{
+ "id": 42,
+ "jsonrpc": "2.0",
+ "result": true
+}
+```
+
+
 
 ## RPC Errors
 
diff --git a/rpc/src/module/subscription.rs b/rpc/src/module/subscription.rs
index d635522e6e..23b463fdc6 100644
--- a/rpc/src/module/subscription.rs
+++ b/rpc/src/module/subscription.rs
@@ -1,5 +1,4 @@
 #![allow(missing_docs)]
-
 use async_trait::async_trait;
 use ckb_async_runtime::Handle;
 use ckb_jsonrpc_types::Topic;
@@ -45,16 +44,14 @@ use tokio::sync::broadcast;
 ///
 /// socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}`)
 /// ```
-///
-///
-
 #[allow(clippy::needless_return)]
 #[rpc]
 #[async_trait]
 pub trait SubscriptionRpc {
     /// Context to implement the subscription RPC.
-    /// type Metadata;
 
+    /// The stream of subscription messages.
+    type S: Stream<Item = PublishMsg<String>> + Send + 'static;
     /// Subscribes to a topic.
     ///
     /// ## Params
@@ -121,7 +118,7 @@ pub trait SubscriptionRpc {
     ///
     /// ## Examples
     ///
-    /// Request
+    /// Subscribe Request
     ///
     /// ```json
     /// {
@@ -134,7 +131,7 @@ pub trait SubscriptionRpc {
     /// }
     /// ```
     ///
-    /// Response
+    /// Subscribe Response
     ///
     /// ```json
     /// {
@@ -142,9 +139,10 @@ pub trait SubscriptionRpc {
     ///   "jsonrpc": "2.0",
     ///   "result": "0xf3"
     /// }
-    /// ```
+    ///
     /// Unsubscribe Request
     ///
+    /// ```json
     /// {
     ///   "id": 42,
     ///   "jsonrpc": "2.0",
@@ -153,9 +151,18 @@ pub trait SubscriptionRpc {
     ///     "0xf3"
     ///   ]
     /// }
+    /// ```
     ///
+    /// Unsubscribe Response
+    ///
+    /// ```json
+    /// {
+    ///  "id": 42,
+    ///  "jsonrpc": "2.0",
+    ///  "result": true
+    /// }
+    /// ```
     ///
-    type S: Stream<Item = PublishMsg<String>> + Send + 'static;
     #[rpc(pub_sub(notify = "subscribe", unsubscribe = "unsubscribe"))]
     fn subscribe(&self, topic: Topic) -> Result<Self::S>;
 }