From c9a42684a18645345b36fb75ff1225c17f4a2505 Mon Sep 17 00:00:00 2001 From: yukang Date: Sat, 11 Jan 2025 17:15:37 +0800 Subject: [PATCH] fix RPC document issue --- Makefile | 2 +- src/cch/order.rs | 1 + src/ckb/config.rs | 1 + src/fiber/graph.rs | 9 +- src/fiber/hash_algorithm.rs | 3 + src/fiber/types.rs | 2 + src/invoice/invoice_impl.rs | 7 + src/rpc/README.md | 646 ++++++++++++++++++++---------------- src/rpc/payment.rs | 26 +- 9 files changed, 390 insertions(+), 307 deletions(-) diff --git a/Makefile b/Makefile index f5f5475f8..6f9e477d3 100644 --- a/Makefile +++ b/Makefile @@ -56,7 +56,7 @@ coverage: coverage-run-unittests coverage-collect-data coverage-generate-report .PHONY: gen-rpc-doc gen-rpc-doc: $(if $(shell command -v fiber-rpc-gen),,cargo install fiber-rpc-gen --force) - /Users/yukang/code/rpc-doc-gen/target/debug/fiber-rpc-gen ./src/ + fiber-rpc-gen ./src/ if grep -q "TODO: add desc" ./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; \ diff --git a/src/cch/order.rs b/src/cch/order.rs index c2c45b207..17c57c877 100644 --- a/src/cch/order.rs +++ b/src/cch/order.rs @@ -12,6 +12,7 @@ use crate::{ invoice::{Currency, InvoiceBuilder}, }; +/// 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 { diff --git a/src/ckb/config.rs b/src/ckb/config.rs index 19f50b743..e9bf2432f 100644 --- a/src/ckb/config.rs +++ b/src/ckb/config.rs @@ -187,6 +187,7 @@ pub struct UdtArgInfo { pub cell_deps: Vec, } +/// The UDT configurations #[derive(Serialize, Deserialize, Clone, Debug, Default, Eq, PartialEq, Hash)] pub struct UdtCfgInfos(pub Vec); diff --git a/src/fiber/graph.rs b/src/fiber/graph.rs index dc080291f..cf8c23e0c 100644 --- a/src/fiber/graph.rs +++ b/src/fiber/graph.rs @@ -1126,15 +1126,16 @@ pub trait NetworkGraphStateStore { fn get_payment_history_results(&self) -> Vec<(OutPoint, Direction, TimedResult)>; } +/// The status of a payment, will update as the payment progresses. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub enum PaymentSessionStatus { - // initial status, payment session is created, no HTLC is sent + /// initial status, payment session is created, no HTLC is sent Created, - // the first hop AddTlc is sent successfully and waiting for the response + /// the first hop AddTlc is sent successfully and waiting for the response Inflight, - // related HTLC is successfully settled + /// related HTLC is successfully settled Success, - // related HTLC is failed + /// related HTLC is failed Failed, } diff --git a/src/fiber/hash_algorithm.rs b/src/fiber/hash_algorithm.rs index acc572bff..33826af9b 100644 --- a/src/fiber/hash_algorithm.rs +++ b/src/fiber/hash_algorithm.rs @@ -4,12 +4,15 @@ use ckb_types::packed; use serde::{Deserialize, Serialize}; use thiserror::Error; +/// HashAlgorithm is the hash algorithm used in the hash lock. #[repr(u8)] #[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default, Hash)] #[serde(rename_all = "snake_case")] pub enum HashAlgorithm { + /// The default hash algorithm, CkbHash #[default] CkbHash = 0, + /// The sha256 hash algorithm Sha256 = 1, } diff --git a/src/fiber/types.rs b/src/fiber/types.rs index f5b92089f..65a9247e5 100644 --- a/src/fiber/types.rs +++ b/src/fiber/types.rs @@ -135,6 +135,7 @@ impl AsRef<[u8; 32]> for Privkey { } } +/// A 256-bit hash digest, used as identifier of channnel, payment, transaction hash etc. #[serde_as] #[derive(Copy, Clone, Serialize, Deserialize, Hash, Eq, PartialEq, Default)] pub struct Hash256(#[serde_as(as = "SliceHex")] [u8; 32]); @@ -267,6 +268,7 @@ impl Privkey { } } +/// The public key for a Node #[derive(Copy, Clone, Debug, PartialOrd, Ord, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Pubkey(pub PublicKey); diff --git a/src/invoice/invoice_impl.rs b/src/invoice/invoice_impl.rs index 23ef131e0..eb2d7b7f3 100644 --- a/src/invoice/invoice_impl.rs +++ b/src/invoice/invoice_impl.rs @@ -59,8 +59,11 @@ impl Display for CkbInvoiceStatus { /// The currency of the invoice, can also used to represent the CKB network chain. #[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize)] pub enum Currency { + /// The mainnet currency of CKB. Fibb, + /// The testnet currency of the CKB network. Fibt, + /// The devnet currency of the CKB network. Fibd, } @@ -136,10 +139,14 @@ pub struct InvoiceData { #[serde_as] #[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)] pub struct CkbInvoice { + /// The currency of the invoice pub currency: Currency, #[serde_as(as = "Option")] + /// The amount of the invoice pub amount: Option, + /// The signature of the invoice pub signature: Option, + /// The invoice data, including the payment hash, timestamp and other attributes pub data: InvoiceData, } diff --git a/src/rpc/README.md b/src/rpc/README.md index 373bf72e7..b3fa1b80f 100644 --- a/src/rpc/README.md +++ b/src/rpc/README.md @@ -45,18 +45,21 @@ You may refer to the e2e test cases in the `tests/bruno/e2e` directory for examp * [Method `disconnect_peer`](#peer-disconnect_peer) * [RPC Types](#rpc-types) + * [Type `CchOrderStatus`](#type-cchorderstatus) * [Type `Channel`](#type-channel) * [Type `ChannelInfo`](#type-channelinfo) - * [Type `ChannelState`](#type-channelstate) + * [Type `CkbInvoice`](#type-ckbinvoice) + * [Type `CkbInvoiceStatus`](#type-ckbinvoicestatus) + * [Type `Currency`](#type-currency) + * [Type `Hash256`](#type-hash256) + * [Type `HashAlgorithm`](#type-hashalgorithm) * [Type `HopHint`](#type-hophint) - * [Type `NewInvoiceParams`](#type-newinvoiceparams) * [Type `NodeInfo`](#type-nodeinfo) * [Type `PaymentSessionStatus`](#type-paymentsessionstatus) + * [Type `Pubkey`](#type-pubkey) * [Type `RemoveTlcReason`](#type-removetlcreason) - * [Type `UdtArgInfo`](#type-udtarginfo) - * [Type `UdtCellDep`](#type-udtcelldep) * [Type `UdtCfgInfos`](#type-udtcfginfos) - * [Type `UdtScript`](#type-udtscript) + ## RPC Modules @@ -71,22 +74,25 @@ Send BTC to a address. ##### Params -* `btc_pay_req` - String, Bitcoin payment request string -* `currency` - Currency, Request currency +* `btc_pay_req` - `String`, Bitcoin payment request string +* `currency` - [Currency](#type-currency), Request currency ##### Returns -* `timestamp` - u64, Seconds since epoch when the order is created -* `expiry` - u64, Seconds after timestamp that the order expires -* `ckb_final_tlc_expiry_delta` - u64, The minimal expiry in seconds of the final TLC in the CKB network -* `currency` - Currency, Request currency -* `wrapped_btc_type_script` - ckb_jsonrpc_types::Script, Wrapped BTC type script -* `btc_pay_req` - String, Payment request for BTC -* `ckb_pay_req` - String, Payment request for CKB -* `payment_hash` - String, Payment hash for the HTLC for both CKB and BTC. -* `amount_sats` - u128, Amount required to pay in Satoshis, including fee -* `fee_sats` - u128, Fee in Satoshis -* `status` - CchOrderStatus, Order status +* `timestamp` - `u64`, Seconds since epoch when the order is created +* `expiry` - `u64`, Seconds after timestamp that the order expires +* `ckb_final_tlc_expiry_delta` - `u64`, The minimal expiry in seconds of the final TLC in the CKB network +* `currency` - [Currency](#type-currency), Request currency +* `wrapped_btc_type_script` - `ckb_jsonrpc_types::Script`, Wrapped BTC type script +* `btc_pay_req` - `String`, Payment request for BTC +* `ckb_pay_req` - `String`, Payment request for CKB +* `payment_hash` - `String`, Payment hash for the HTLC for both CKB and BTC. +* `amount_sats` - `u128`, Amount required to pay in Satoshis, including fee +* `fee_sats` - `u128`, Fee in Satoshis +* `status` - [CchOrderStatus](#type-cchorderstatus), Order status + +--- + @@ -96,24 +102,27 @@ Receive BTC from a payment hash. ##### Params -* `payment_hash` - String, Payment hash for the HTLC for both CKB and BTC. -* `channel_id` - Hash256, Channel ID for the CKB payment. -* `amount_sats` - u128, How many satoshis to receive, excluding cross-chain hub fee. -* `final_tlc_expiry` - u64, Expiry set for the HTLC for the CKB payment to the payee. +* `payment_hash` - `String`, Payment hash for the HTLC for both CKB and BTC. +* `channel_id` - [Hash256](#type-hash256), Channel ID for the CKB payment. +* `amount_sats` - `u128`, How many satoshis to receive, excluding cross-chain hub fee. +* `final_tlc_expiry` - `u64`, Expiry set for the HTLC for the CKB payment to the payee. ##### Returns -* `timestamp` - u64, Seconds since epoch when the order is created -* `expiry` - u64, Seconds after timestamp that the order expires -* `ckb_final_tlc_expiry_delta` - u64, The minimal expiry in seconds of the final TLC in the CKB network -* `wrapped_btc_type_script` - ckb_jsonrpc_types::Script, Wrapped BTC type script -* `btc_pay_req` - String, Payment request for BTC -* `payment_hash` - String, Payment hash for the HTLC for both CKB and BTC. -* `channel_id` - Hash256, Channel ID for the CKB payment. -* `tlc_id` - `Option`, TLC ID for the CKB payment. -* `amount_sats` - u128, Amount will be received by the payee -* `fee_sats` - u128, Fee in Satoshis -* `status` - CchOrderStatus, Order status +* `timestamp` - `u64`, Seconds since epoch when the order is created +* `expiry` - `u64`, Seconds after timestamp that the order expires +* `ckb_final_tlc_expiry_delta` - `u64`, The minimal expiry in seconds of the final TLC in the CKB network +* `wrapped_btc_type_script` - `ckb_jsonrpc_types::Script`, Wrapped BTC type script +* `btc_pay_req` - `String`, Payment request for BTC +* `payment_hash` - `String`, Payment hash for the HTLC for both CKB and BTC. +* `channel_id` - [Hash256](#type-hash256), Channel ID for the CKB payment. +* `tlc_id` - `Option`, TLC ID for the CKB payment. +* `amount_sats` - `u128`, Amount will be received by the payee +* `fee_sats` - `u128`, Fee in Satoshis +* `status` - [CchOrderStatus](#type-cchorderstatus), Order status + +--- + @@ -123,21 +132,24 @@ Get receive BTC order by payment hash. ##### Params -* `payment_hash` - String, Payment hash for the HTLC for both CKB and BTC. +* `payment_hash` - `String`, Payment hash for the HTLC for both CKB and BTC. ##### Returns -* `timestamp` - u64, Seconds since epoch when the order is created -* `expiry` - u64, Seconds after timestamp that the order expires -* `ckb_final_tlc_expiry_delta` - u64, The minimal expiry in seconds of the final TLC in the CKB network -* `wrapped_btc_type_script` - ckb_jsonrpc_types::Script, Wrapped BTC type script -* `btc_pay_req` - String, Payment request for BTC -* `payment_hash` - String, Payment hash for the HTLC for both CKB and BTC. -* `channel_id` - Hash256, Channel ID for the CKB payment. -* `tlc_id` - `Option`, TLC ID for the CKB payment. -* `amount_sats` - u128, Amount will be received by the payee -* `fee_sats` - u128, Fee in Satoshis -* `status` - CchOrderStatus, Order status +* `timestamp` - `u64`, Seconds since epoch when the order is created +* `expiry` - `u64`, Seconds after timestamp that the order expires +* `ckb_final_tlc_expiry_delta` - `u64`, The minimal expiry in seconds of the final TLC in the CKB network +* `wrapped_btc_type_script` - `ckb_jsonrpc_types::Script`, Wrapped BTC type script +* `btc_pay_req` - `String`, Payment request for BTC +* `payment_hash` - `String`, Payment hash for the HTLC for both CKB and BTC. +* `channel_id` - [Hash256](#type-hash256), Channel ID for the CKB payment. +* `tlc_id` - `Option`, TLC ID for the CKB payment. +* `amount_sats` - `u128`, Amount will be received by the payee +* `fee_sats` - `u128`, Fee in Satoshis +* `status` - [CchOrderStatus](#type-cchorderstatus), Order status + +--- + @@ -152,30 +164,33 @@ Attempts to open a channel with a peer. ##### Params -* `peer_id` - PeerId, The peer ID to open a channel with, the peer must be connected through the [connect_peer](#peer-connect_peer) rpc first. -* `funding_amount` - u128, The amount of CKB or UDT to fund the channel with. -* `public` - `Option`, 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. -* `funding_udt_type_script` - `Option