# Fiber Network Node RPC

The RPC module provides a set of APIs for developers to interact with FNN. Please note that APIs are not stable yet and may change in the future.

Allowing arbitrary machines to access the JSON-RPC port (using the `rpc.listening_addr` configuration option) is **dangerous and strongly discouraged**. Please strictly limit the access to only trusted machines.

You may refer to the e2e test cases in the `tests/bruno/e2e` directory for examples of how to use the RPC.

<!--**NOTE:** the content below is generated by gen_doc -->

* [RPC Methods](#rpc-methods)


    * [Module Cch](#module-cch)
        * [Method `send_btc`](#cch-send_btc)
        * [Method `receive_btc`](#cch-receive_btc)
        * [Method `get_receive_btc_order`](#cch-get_receive_btc_order)
    * [Module Channel](#module-channel)
        * [Method `open_channel`](#channel-open_channel)
        * [Method `accept_channel`](#channel-accept_channel)
        * [Method `list_channels`](#channel-list_channels)
        * [Method `commitment_signed`](#channel-commitment_signed)
        * [Method `add_tlc`](#channel-add_tlc)
        * [Method `remove_tlc`](#channel-remove_tlc)
        * [Method `shutdown_channel`](#channel-shutdown_channel)
        * [Method `update_channel`](#channel-update_channel)
        * [Method `send_payment`](#channel-send_payment)
        * [Method `get_payment`](#channel-get_payment)
    * [Module Graph](#module-graph)
        * [Method `graph_nodes`](#graph-graph_nodes)
        * [Method `graph_channels`](#graph-graph_channels)
    * [Module Config](#module-config)
    * [Module Mod](#module-mod)
    * [Module Invoice](#module-invoice)
        * [Method `new_invoice`](#invoice-new_invoice)
        * [Method `parse_invoice`](#invoice-parse_invoice)
        * [Method `get_invoice`](#invoice-get_invoice)
    * [Module Info](#module-info)
        * [Method `node_info`](#info-node_info)
    * [Module Peer](#module-peer)
        * [Method `connect_peer`](#peer-connect_peer)
        * [Method `disconnect_peer`](#peer-disconnect_peer)
    * [Module Utils](#module-utils)
* [RPC Types](#rpc-types)

    * [Type `Channel`](#type-channel)
    * [Type `ChannelInfo`](#type-channelinfo)
    * [Type `InvoiceStatus`](#type-invoicestatus)
    * [Type `NodeInfo`](#type-nodeinfo)
    * [Type `RemoveTlcReason`](#type-removetlcreason)
    * [Type `UdtArgInfo`](#type-udtarginfo)
    * [Type `UdtCellDep`](#type-udtcelldep)
    * [Type `UdtCfgInfos`](#type-udtcfginfos)
    * [Type `UdtScript`](#type-udtscript)
## RPC Modules

<a id="cch"></a>
### Module `Cch`
RPC module for cross chain hub demonstration.
 This is the seccond line


<a id="cch-send_btc"></a>
#### Method `send_btc`

Send BTC to a address.

##### Params

* `btc_pay_req` - String, Bitcoin payment request string
* `currency` - 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` - 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


<a id="cch-receive_btc"></a>
#### Method `receive_btc`

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.

##### Returns

* `timestamp` - u64, Seconds since epoch when the order is created
* `expiry` - u64, Seconds after timestamp that the order expires
* `ckb_final_tlc_expiry` - 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<u64>`, 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


<a id="cch-get_receive_btc_order"></a>
#### Method `get_receive_btc_order`

Get receive BTC order by payment hash.

##### Params

* `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` - 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<u64>`, 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


<a id="channel"></a>
### Module `Channel`
RPC module for channel management.


<a id="channel-open_channel"></a>
#### Method `open_channel`

Attempts to open a channel with a peer.

##### Params

* `peer_id` - PeerId, The peer ID to open a channel with.
* `funding_amount` - u128, The amount of CKB or UDT to fund the channel with.
* `public` - `Option<bool>`, Whether this is a public channel (will be broadcasted to network, and can be used to forward TLCs), an optional parameter (default value false).
* `funding_udt_type_script` - `Option<Script>`, The type script of the UDT to fund the channel with, an optional parameter.
* `shutdown_script` - `Option<Script>`, The script used to receive the channel balance, an optional parameter, default value is the secp256k1_blake160_sighash_all script corresponding to the configured private key.
* `commitment_delay_epoch` - `Option<EpochNumberWithFraction>`, The delay time for the commitment transaction, must be an [EpochNumberWithFraction](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0017-tx-valid-since/e-i-l-encoding.png) in u64 format, an optional parameter, default value is 24 hours.
* `commitment_fee_rate` - `Option<u64>`, The fee rate for the commitment transaction, an optional parameter.
* `funding_fee_rate` - `Option<u64>`, The fee rate for the funding transaction, an optional parameter.
* `tlc_locktime_expiry_delta` - `Option<u64>`, The expiry delta for the TLC locktime, an optional parameter.
* `tlc_min_value` - `Option<u128>`, The minimum value for a TLC, an optional parameter.
* `tlc_max_value` - `Option<u128>`, The maximum value for a TLC, an optional parameter.
* `tlc_fee_proportional_millionths` - `Option<u128>`, The fee proportional millionths for a TLC, an optional parameter.
* `max_tlc_value_in_flight` - `Option<u128>`, The maximum value in flight for TLCs, an optional parameter.
* `max_tlc_number_in_flight` - `Option<u64>`, The maximum number of TLCs that can be accepted, an optional parameter.

##### Returns

* `temporary_channel_id` - Hash256, The temporary channel ID of the channel being opened


<a id="channel-accept_channel"></a>
#### Method `accept_channel`

Accepts a channel opening request from a peer.

##### Params

* `temporary_channel_id` - Hash256, The temporary channel ID of the channel to accept
* `funding_amount` - u128, The amount of CKB or UDT to fund the channel with
* `shutdown_script` - `Option<Script>`, The script used to receive the channel balance, an optional parameter,
 default value is the secp256k1_blake160_sighash_all script corresponding to the configured private key

##### Returns

* `channel_id` - Hash256, The final ID of the channel that was accepted, it's different from the temporary channel ID


<a id="channel-list_channels"></a>
#### Method `list_channels`

Lists all channels.

##### Params

* `peer_id` - `Option<PeerId>`, The peer ID to list channels for, an optional parameter, if not provided, all channels will be listed

##### Returns

* `channels` - `Vec<Channel>`, The list of channels


<a id="channel-commitment_signed"></a>
#### Method `commitment_signed`

Sends a commitment_signed message to the peer.

##### Params

* `channel_id` - Hash256, The channel ID of the channel to send the commitment_signed message to

##### Returns

* None


<a id="channel-add_tlc"></a>
#### Method `add_tlc`

Adds a TLC to a channel.

##### Params

* `channel_id` - Hash256, The channel ID of the channel to add the TLC to
* `amount` - u128, The amount of the TLC
* `payment_hash` - Hash256, The payment hash of the TLC
* `expiry` - LockTime, The expiry of the TLC
* `hash_algorithm` - `Option<HashAlgorithm>`, The hash algorithm of the TLC

##### Returns

* `tlc_id` - u64, The ID of the TLC


<a id="channel-remove_tlc"></a>
#### Method `remove_tlc`

Removes a TLC from a channel.

##### Params

* `channel_id` - Hash256, The channel ID of the channel to remove the TLC from
* `tlc_id` - u64, The ID of the TLC to remove
* `reason` - RemoveTlcReason, The reason for removing the TLC, either a 32-byte hash for preimage fulfillment or an u32 error code for removal

##### Returns

* None


<a id="channel-shutdown_channel"></a>
#### Method `shutdown_channel`

Shuts down a channel.

##### Params

* `channel_id` - Hash256, The channel ID of the channel to shut down
* `close_script` - Script, The script used to receive the channel balance, only support secp256k1_blake160_sighash_all script for now
* `force` - `Option<bool>`, Whether to force the channel to close
* `fee_rate` - u64, The fee rate for the closing transaction, the fee will be deducted from the closing initiator's channel balance

##### Returns

* None


<a id="channel-update_channel"></a>
#### Method `update_channel`

Updates a channel.

##### Params

* `channel_id` - Hash256, The channel ID of the channel to update
* `enabled` - `Option<bool>`, Whether the channel is enabled
* `tlc_locktime_expiry_delta` - `Option<u64>`, The CLTV delta from the current height that should be used to set the timelock for the final hop
* `tlc_minimum_value` - `Option<u128>`, The minimum value for a TLC
* `tlc_maximum_value` - `Option<u128>`, The maximum value for a TLC
* `tlc_fee_proportional_millionths` - `Option<u128>`, The fee proportional millionths for a TLC

##### Returns

* None


<a id="channel-send_payment"></a>
#### Method `send_payment`

Sends a payment to a peer.

##### Params

* `target_pubkey` - `Option<Pubkey>`, the identifier of the payment target
* `amount` - `Option<u128>`, the amount of the payment
* `payment_hash` - `Option<Hash256>`, The hash to use within the payment's HTLC
 FIXME: this should be optional when AMP is enabled
* `final_cltv_delta` - `Option<u64>`, The CLTV delta from the current height that should be used to set the timelock for the final hop
* `invoice` - `Option<String>`, the encoded invoice to send to the recipient
* `timeout` - `Option<u64>`, the payment timeout in seconds, if the payment is not completed within this time, it will be cancelled
* `max_fee_amount` - `Option<u128>`, the maximum fee amounts in shannons that the sender is willing to pay
* `max_parts` - `Option<u64>`, max parts for the payment, only used for multi-part payments
* `keysend` - `Option<bool>`, keysend payment
* `udt_type_script` - `Option<Script>`, udt type script for the payment
* `allow_self_payment` - `Option<bool>`, allow self payment, default is false

##### Returns

* `payment_hash` - Hash256, The payment hash of the payment
* `status` - PaymentSessionStatus, The status of the payment
* `created_at` - u128, The time the payment was created at
* `last_updated_at` - u128, The time the payment was last updated at
* `failed_error` - `Option<String>`, The error message if the payment failed


<a id="channel-get_payment"></a>
#### Method `get_payment`

Retrieves a payment.

##### Params

* `payment_hash` - Hash256, The payment hash of the payment to retrieve

##### Returns

* `payment_hash` - Hash256, The payment hash of the payment
* `status` - PaymentSessionStatus, The status of the payment
* `created_at` - u128, The time the payment was created at
* `last_updated_at` - u128, The time the payment was last updated at
* `failed_error` - `Option<String>`, The error message if the payment failed


<a id="graph"></a>
### Module `Graph`
RPC module for graph management.


<a id="graph-graph_nodes"></a>
#### Method `graph_nodes`

TODO: add desc

##### Params

* `limit` - `Option<u64>`, The maximum number of nodes to return.
* `after` - `Option<JsonBytes>`, The cursor to start returning nodes from.

##### Returns

* `nodes` - `Vec<NodeInfo>`, The list of nodes.
* `last_cursor` - JsonBytes, The last cursor.


<a id="graph-graph_channels"></a>
#### Method `graph_channels`

TODO: add desc

##### Params

* `limit` - `Option<u64>`, The maximum number of channels to return.
* `after` - `Option<JsonBytes>`, The cursor to start returning channels from.

##### Returns

* `channels` - `Vec<ChannelInfo>`, TODO: add desc
* `last_cursor` - JsonBytes, TODO: add desc


<a id="invoice"></a>
### Module `Invoice`
RPC module for invoice management.


<a id="invoice-new_invoice"></a>
#### Method `new_invoice`

Generates a new invoice.

##### Params

* `amount` - u128, The amount of the invoice.
* `description` - `Option<String>`, The description of the invoice.
* `currency` - Currency, The currency of the invoice.
* `payment_preimage` - Hash256, The payment preimage of the invoice.
* `expiry` - `Option<u64>`, The expiry time of the invoice.
* `fallback_address` - `Option<String>`, The fallback address of the invoice.
* `final_cltv` - `Option<u64>`, The final CLTV of the invoice.
* `final_htlc_timeout` - `Option<u64>`, The final HTLC timeout of the invoice.
* `udt_type_script` - `Option<Script>`, The UDT type script of the invoice.
* `hash_algorithm` - `Option<HashAlgorithm>`, The hash algorithm of the invoice.

##### Returns

* `invoice_address` - String, The encoded invoice address.
* `invoice` - CkbInvoice, The invoice.


<a id="invoice-parse_invoice"></a>
#### Method `parse_invoice`

Parses a encoded invoice.

##### Params

* `invoice` - String, The encoded invoice address.

##### Returns

* `invoice` - CkbInvoice, The invoice.


<a id="invoice-get_invoice"></a>
#### Method `get_invoice`

Retrieves an invoice.

##### Params

* `payment_hash` - Hash256, The payment hash of the invoice.

##### Returns

* `invoice_address` - String, The encoded invoice address.
* `invoice` - CkbInvoice, The invoice.
* `status` - InvoiceStatus, The invoice status.


<a id="info"></a>
### Module `Info`
The RPC module for node information.


<a id="info-node_info"></a>
#### Method `node_info`

Get the node information.

##### Params
* None

##### Returns

* `version` - String, The version of the node software.
* `commit_hash` - String, The commit hash of the node software.
* `public_key` - Pubkey, The public key of the node.
* `node_name` - `Option<String>`, The optional name of the node.
* `peer_id` - PeerId, The peer ID of the node, serialized as a string.
* `addresses` - `Vec<MultiAddr>`, A list of multi-addresses associated with the node.
* `chain_hash` - Hash256, The hash of the blockchain that the node is connected to.
* `open_channel_auto_accept_min_ckb_funding_amount` - u64, The minimum CKB funding amount for automatically accepting open channel requests, serialized as a hexadecimal string.
* `auto_accept_channel_ckb_funding_amount` - u64, The CKB funding amount for automatically accepting channel requests, serialized as a hexadecimal string.
* `tlc_locktime_expiry_delta` - u64, The locktime expiry delta for Time-Locked Contracts (TLC), serialized as a hexadecimal string.
* `tlc_min_value` - u128, The minimum value for Time-Locked Contracts (TLC), serialized as a hexadecimal string, `0` means no minimum value limit.
* `tlc_max_value` - u128, The maximum value for Time-Locked Contracts (TLC), serialized as a hexadecimal string, `0` means no maximum value limit.
* `tlc_fee_proportional_millionths` - u128, The fee proportional to the value of Time-Locked Contracts (TLC), expressed in millionths and serialized as a hexadecimal string.
* `channel_count` - u32, The number of channels associated with the node, serialized as a hexadecimal string.
* `pending_channel_count` - u32, The number of pending channels associated with the node, serialized as a hexadecimal string.
* `peers_count` - u32, The number of peers connected to the node, serialized as a hexadecimal string.
* `network_sync_status` - String, The synchronization status of the node within the network.
* `udt_cfg_infos` - UdtCfgInfos, Configuration information for User-Defined Tokens (UDT) associated with the node.


<a id="peer"></a>
### Module `Peer`
RPC module for peer management.


<a id="peer-connect_peer"></a>
#### Method `connect_peer`

Connect to a peer.

##### Params

* `address` - MultiAddr, The address of the peer to connect to.
* `save` - `Option<bool>`, Whether to save the peer address to the peer store.

##### Returns

* None


<a id="peer-disconnect_peer"></a>
#### Method `disconnect_peer`

Disconnect from a peer.

##### Params

* `peer_id` - PeerId, The peer ID of the peer to disconnect.

##### Returns

* None



## RPC Types


<a id="#type-channel"></a>
### Type `Channel`

TODO: add desc


#### Fields

* `channel_id` - Hash256, The channel ID
* `peer_id` - PeerId, The peer ID of the channel
* `funding_udt_type_script` - `Option<Script>`, The UDT type script of the channel
* `state` - ChannelState, The state of the channel
* `local_balance` - u128, The local balance of the channel
* `offered_tlc_balance` - u128, The offered balance of the channel
* `remote_balance` - u128, The remote balance of the channel
* `received_tlc_balance` - u128, The received balance of the channel
* `created_at` - u64, The time the channel was created at

<a id="#type-removetlcreason"></a>
### Type `RemoveTlcReason`

TODO: add desc


#### Enum with values of

* `RemoveTlcFulfill` - , The reason for removing the TLC is that it was fulfilled
* `RemoveTlcFail` - , The reason for removing the TLC is that it failed

<a id="#type-udtscript"></a>
### Type `UdtScript`

TODO: add desc


#### Fields

* `code_hash` - H256, The code hash of the script.
* `hash_type` - ScriptHashType, The hash type of the script.
* `args` - String, The arguments of the script.

<a id="#type-udtcelldep"></a>
### Type `UdtCellDep`

TODO: add desc


#### Fields

* `dep_type` - DepType, The type of the cell dep.
* `tx_hash` - H256, The transaction hash of the cell dep.
* `index` - u32, The index of the cell dep.

<a id="#type-udtarginfo"></a>
### Type `UdtArgInfo`

TODO: add desc


#### Fields

* `name` - String, The name of the UDT.
* `script` - UdtScript, The script of the UDT.
* `auto_accept_amount` - `Option<u128>`, The minimum amount of the UDT that can be automatically accepted.
* `cell_deps` - `Vec<UdtCellDep>`, The cell deps of the UDT.

<a id="#type-udtcfginfos"></a>
### Type `UdtCfgInfos`

TODO: add desc


#### Fields

* `` - `Vec<UdtArgInfo>`, TODO: add desc

<a id="#type-nodeinfo"></a>
### Type `NodeInfo`

TODO: add desc


#### Fields

* `alias` - String, The alias of the node.
* `addresses` - `Vec<MultiAddr>`, The addresses of the node.
* `node_id` - Pubkey, The node ID.
* `timestamp` - u64, The timestamp of the node.
* `chain_hash` - Hash256, The chain hash of the node.
* `auto_accept_min_ckb_funding_amount` - u64, The minimum CKB funding amount for automatically accepting open channel requests.
* `udt_cfg_infos` - UdtCfgInfos, The UDT configuration infos of the node.

<a id="#type-channelinfo"></a>
### Type `ChannelInfo`

TODO: add desc


#### Fields

* `channel_outpoint` - OutPoint, The outpoint of the channel.
* `funding_tx_block_number` - u64, The block number of the funding transaction.
* `funding_tx_index` - u32, The index of the funding transaction.
* `node1` - Pubkey, The node ID of the first node.
* `node2` - Pubkey, The node ID of the second node.
* `last_updated_timestamp` - `Option<u64>`, The last updated timestamp of the channel.
* `created_timestamp` - u64, The created timestamp of the channel.
* `node1_to_node2_fee_rate` - `Option<u64>`, The fee rate from node 1 to node 2.
* `node2_to_node1_fee_rate` - `Option<u64>`, The fee rate from node 2 to node 1.
* `capacity` - u128, The capacity of the channel.
* `chain_hash` - Hash256, The chain hash of the channel.
* `udt_type_script` - `Option<Script>`, The UDT type script of the channel.

<a id="#type-invoicestatus"></a>
### Type `InvoiceStatus`

TODO: add desc


#### Enum with values of

* `Unpaid` - , The invoice is unpaid.
* `Inflight` - , The invoice is in flight.
* `Paid` - , The invoice is paid, the payment is successful.
* `Expired` - , The invoice is expired, can'b be used anymore.