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.

We are in a actively developing stage, don't hesitate to report issues or ask for help in the channel of the Nervos dev community.

RPC Methods
RPC Types

RPC Modules

Module `Cch`

RPC module for cross chain hub demonstration.

Method `send_btc`

Creates a CCH order for a BTC Lightning payee.

Params

btc_pay_req - String, Payment request string for the BTC Lightning payee.

The invoice should not be expired soon. The remaining expiry time should be greater than the CCH config min_incoming_invoice_expiry_delta_seconds.

currency - Currency, Request currency

Returns

timestamp - u64, Seconds since epoch when the order is created
expiry_delta_seconds - u64, Relative expiry time in seconds from created_at that the order expires
wrapped_btc_type_script - ckb_jsonrpc_types::Script, Wrapped BTC type script
incoming_invoice - CchInvoice, Generated invoice for the incoming payment
outgoing_pay_req - String, The final payee to accept the payment. It has the different network with incoming invoice.
payment_hash - Hash256, 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

Method `receive_btc`

Creates a CCH order for a CKB Fiber payee.

Params

fiber_pay_req - String, Payment request string for the CKB Fiber payee.

The invoice should not be expired soon. The remaining expiry time should be greater than the CCH config min_incoming_invoice_expiry_delta_seconds.

Returns

timestamp - u64, Seconds since epoch when the order is created
expiry_delta_seconds - u64, Relative expiry time in seconds from created_at that the order expires
wrapped_btc_type_script - ckb_jsonrpc_types::Script, Wrapped BTC type script
incoming_invoice - CchInvoice, Generated invoice for the incoming payment
outgoing_pay_req - String, The final payee to accept the payment. It has the different network with incoming invoice.
payment_hash - Hash256, 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

Method `get_cch_order`

Get a CCH order by payment hash.

Params

payment_hash - Hash256, Payment hash for the HTLC for both CKB and BTC.

Returns

timestamp - u64, Seconds since epoch when the order is created
expiry_delta_seconds - u64, Relative expiry time in seconds from created_at that the order expires
wrapped_btc_type_script - ckb_jsonrpc_types::Script, Wrapped BTC type script
incoming_invoice - CchInvoice, Generated invoice for the incoming payment
outgoing_pay_req - String, The final payee to accept the payment. It has the different network with incoming invoice.
payment_hash - Hash256, 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

Module `Channel`

RPC module for channel management.

Method `open_channel`

Attempts to open a channel with a peer.

Params

peer_id - PeerId, 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 rpc first. You can obtain a peer's peer_id from the list_peers RPC.
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 is true.
one_way - Option<bool>, 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.
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 in u64 format, an optional parameter, default value is 1 epoch, which is 4 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_expiry_delta - Option<u64>, The expiry delta to forward a tlc, in milliseconds, default to 4 hours, which is 4 * 60 * 60 * 1000 milliseconds Expect it >= 2/3 commitment_delay_epoch. This parameter can be updated with rpc update_channel later.
tlc_min_value - Option<u128>, The minimum value for a TLC our side can send, an optional parameter, default is 0, which means we can send any TLC is larger than 0. This parameter can be updated with rpc update_channel later.
tlc_fee_proportional_millionths - Option<u128>, The fee proportional millionths for a TLC, proportional to the amount of the forwarded tlc. The unit is millionths of the amount. default is 1000 which means 0.1%. This parameter can be updated with rpc update_channel later. Not that, we use outbound channel to calculate the fee for TLC forwarding. For example, if we have a path A -> B -> C, then the fee B requires for TLC forwarding, is calculated the channel configuration of B and C, not A and B.
max_tlc_value_in_flight - Option<u128>, The maximum value in flight for TLCs, an optional parameter. This parameter can not be updated after channel is opened.
max_tlc_number_in_flight - Option<u64>, The maximum number of TLCs that can be accepted, an optional parameter, default is 125 This parameter can not be updated after channel is opened.

Returns

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

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
max_tlc_value_in_flight - Option<u128>, The max tlc sum value in flight for the channel, default is u128::MAX This parameter can not be updated after channel is opened.
max_tlc_number_in_flight - Option<u64>, The max tlc number in flight send from our side, default is 125 This parameter can not be updated after channel is opened.
tlc_min_value - Option<u128>, The minimum value for a TLC our side can send, an optional parameter, default is 0, which means we can send any TLC is larger than 0. This parameter can be updated with rpc update_channel later.
tlc_fee_proportional_millionths - Option<u128>, The fee proportional millionths for a TLC, proportional to the amount of the forwarded tlc. The unit is millionths of the amount. default is 1000 which means 0.1%. This parameter can be updated with rpc update_channel later. Not that, we use outbound channel to calculate the fee for TLC forwarding. For example, if we have a path A -> B -> C, then the fee B requires for TLC forwarding, is calculated the channel configuration of B and C, not A and B.
tlc_expiry_delta - Option<u64>, The expiry delta to forward a tlc, in milliseconds, default to 1 day, which is 24 * 60 * 60 * 1000 milliseconds This parameter can be updated with rpc update_channel later.

Returns

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

Method `abandon_channel`

Abandon a channel, this will remove the channel from the channel manager and DB. Only channels not in Ready or Closed state can be abandoned.

Params

channel_id - Hash256, The temporary channel ID or real channel ID of the channel being abandoned

Returns

None

Method `list_channels`

Lists all channels.

Params

peer_id - Option<PeerId>, 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 - Option<bool>, Whether to include closed channels in the list, an optional parameter, default value is false
only_pending - Option<bool>, 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 ready) as well as channels whose opening attempt failed. Default is false. Mutually exclusive with include_closed.

Returns

channels - Vec<Channel>, The list of channels

Method `shutdown_channel`

Shuts down a channel.

Params

channel_id - Hash256, The channel ID of the channel to shut down
close_script - Option<Script>, The script used to receive the channel balance, only support secp256k1_blake160_sighash_all script for now default is default_funding_lock_script in CkbConfig
fee_rate - Option<u64>, The fee rate for the closing transaction, the fee will be deducted from the closing initiator's channel balance default is 1000 shannons/KW
force - Option<bool>, Whether to force the channel to close, when set to false, close_script and fee_rate should be set, default is false. When set to true, close_script and fee_rate will be ignored and will use the default value when opening the channel.

Returns

None

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_expiry_delta - Option<u64>, The expiry delta for the TLC locktime
tlc_minimum_value - Option<u128>, The minimum value for a TLC
tlc_fee_proportional_millionths - Option<u128>, The fee proportional millionths for a TLC

Returns

None

Module `Dev`

RPC module for development purposes, this module is not intended to be used in production. This module will be disabled in release build.

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

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 - u64, The expiry of the TLC
hash_algorithm - Option<HashAlgorithm>, The hash algorithm of the TLC

Returns

tlc_id - u64, The ID of the TLC

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

Method `submit_commitment_transaction`

Submit a commitment transaction to the chain

Params

channel_id - Hash256, Channel ID
commitment_number - u64, Commitment number

Returns

tx_hash - Hash256, Submitted commitment transaction hash

Method `check_channel_shutdown`

Manually trigger CheckShutdownTx on all channels

Params

channel_id - Hash256, Channel ID

Returns

None

Module `Graph`

RPC module for graph management.

Method `graph_nodes`

Get the list of nodes in the network graph.

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.

Method `graph_channels`

Get the list of channels in the network graph.

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>, A list of channels.
last_cursor - JsonBytes, The last cursor for pagination.

Module `Info`

The RPC module for node information.

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.
node_id - Pubkey, 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 - Vec<String>, The features supported by the node.
node_name - Option<String>, The optional name of the node.
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.
default_funding_lock_script - Script, The default funding lock script for the node.
tlc_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) we can send, serialized as a hexadecimal string.
tlc_fee_proportional_millionths - u128, The fee (to forward payments) 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.
udt_cfg_infos - UdtCfgInfos, Configuration information for User-Defined Tokens (UDT) associated with the node.

Module `Invoice`

RPC module for invoice management.

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 - Option<Hash256>, The preimage to settle an incoming TLC payable to this invoice. If preimage is set, hash must be absent. If both preimage and hash are absent, a random preimage is generated.
payment_hash - Option<Hash256>, The hash of the preimage. If hash is set, preimage must be absent. This condition indicates a 'hold invoice' for which the tlc must be accepted and held until the preimage becomes known.
expiry - Option<u64>, The expiry time of the invoice, in seconds.
fallback_address - Option<String>, The fallback address of the invoice.
final_expiry_delta - Option<u64>, The final HTLC timeout of the invoice, in milliseconds. Minimal value is 16 hours, and maximal value is 14 days.
udt_type_script - Option<Script>, The UDT type script of the invoice.
hash_algorithm - Option<HashAlgorithm>, The hash algorithm of the invoice.
allow_mpp - Option<bool>, Whether allow payment to use MPP
allow_trampoline_routing - Option<bool>, Whether allow payment to use trampoline routing

Returns

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

Method `parse_invoice`

Parses a encoded invoice.

Params

invoice - String, The encoded invoice address.

Returns

invoice - CkbInvoice, The invoice.

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 - CkbInvoiceStatus, The invoice status

Method `cancel_invoice`

Cancels an invoice, only when invoice is in status Open can be canceled.

Params

payment_hash - Hash256, The payment hash of the invoice.

Returns

invoice_address - String, The encoded invoice address.
invoice - CkbInvoice, The invoice.
status - CkbInvoiceStatus, The invoice status

Method `settle_invoice`

Settles an invoice by saving the preimage to this invoice.

Params

payment_hash - Hash256, The payment hash of the invoice.
payment_preimage - Hash256, The payment preimage of the invoice.

Returns

None

Module `Payment`

RPC module for channel management.

Method `send_payment`

Sends a payment to a peer.

Params

target_pubkey - Option<Pubkey>, 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 - Option<u128>, 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 - Option<Hash256>, the hash to use within the payment's HTLC. If not set and keysend is set to true, a random hash will be generated. If not set and there is a payment_hash in the invoice, it will be used. Otherwise, payment_hash need to be set.
final_tlc_expiry_delta - Option<u64>, the TLC expiry delta should be used to set the timelock for the final hop, in milliseconds
tlc_expiry_limit - Option<u64>, the TLC expiry limit for the whole payment, in milliseconds, each hop is with a default tlc delta of 1 day suppose the payment router is with N hops, the total tlc expiry limit is at least (N-1) days this is also the default value for the payment if this parameter is not provided
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. Note: In trampoline routing mode, the sender will use the max_fee_amount as the total fee as much as possible.
max_fee_rate - Option<u64>, the maximum fee rate per thousand (‰), default is 5 (0.5%)
max_parts - Option<u64>, max parts for the payment, only used for multi-part payments
trampoline_hops - Option<Vec<Pubkey>>, Optional explicit trampoline hops.

When set to a non-empty list [t1, t2, ...], routing will only find a path from the payer to t1, and the inner trampoline onion will encode t1 -> t2 -> ... -> final.

keysend - Option<bool>, keysend payment
udt_type_script - Option<Script>, udt type script for the payment
allow_self_payment - Option<bool>, 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 - Option<PaymentCustomRecords>, Some custom records for the payment which contains a map of u32 to Vec The key is the record type, and the value is the serialized data For example:

"custom_records": {
   "0x1": "0x01020304",
   "0x2": "0x05060708",
   "0x3": "0x090a0b0c",
   "0x4": "0x0d0e0f10010d090a0b0c"
 }

hop_hints - Option<Vec<HopHint>>, Optional route hints to reach the destination through private channels. Note:
1. this is only used for the private channels with the last hop.
2. hop_hints is only a hint for routing algorithm, it is not a guarantee that the payment will be routed through the specified channels, it is up to the routing algorithm to decide whether to use the hints or not.

For example (pubkey, channel_outpoint, fee_rate, tlc_expiry_delta) suggest path router to use the channel of channel_outpoint at hop with pubkey to forward the payment and the fee rate is fee_rate and tlc_expiry_delta is tlc_expiry_delta.

dry_run - Option<bool>, dry_run for payment, used for check whether we can build valid router and the fee for this payment, it's useful for the sender to double check the payment before sending it to the network, default is false

Returns

payment_hash - Hash256, The payment hash of the payment
status - PaymentStatus, The status of the payment
created_at - u64, The time the payment was created at, in milliseconds from UNIX epoch
last_updated_at - u64, The time the payment was last updated at, in milliseconds from UNIX epoch
failed_error - Option<String>, The error message if the payment failed
fee - u128, fee paid for the payment
custom_records - Option<PaymentCustomRecords>, The custom records to be included in the payment.
routers - Vec<SessionRoute>, The router is a list of nodes that the payment will go through. We store in the payment session and then will use it to track the payment history. The router is a list of nodes that the payment will go through. If the payment adapted MPP (multi-part payment), the routers will be a list of nodes For example: A(amount, channel) -> B -> C -> D means A will send amount with channel to B.

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 - PaymentStatus, The status of the payment
created_at - u64, The time the payment was created at, in milliseconds from UNIX epoch
last_updated_at - u64, The time the payment was last updated at, in milliseconds from UNIX epoch
failed_error - Option<String>, The error message if the payment failed
fee - u128, fee paid for the payment
custom_records - Option<PaymentCustomRecords>, The custom records to be included in the payment.
routers - Vec<SessionRoute>, The router is a list of nodes that the payment will go through. We store in the payment session and then will use it to track the payment history. The router is a list of nodes that the payment will go through. If the payment adapted MPP (multi-part payment), the routers will be a list of nodes For example: A(amount, channel) -> B -> C -> D means A will send amount with channel to B.

Method `build_router`

Builds a router with a list of pubkeys and required channels.

Params

amount - Option<u128>, the amount of the payment, the unit is Shannons for non UDT payment If not set, the minimum routable amount 1 is used
udt_type_script - Option<Script>, udt type script for the payment router
hops_info - Vec<HopRequire>, A list of hops that defines the route. This does not include the source hop pubkey. A hop info is a tuple of pubkey and the channel(specified by channel funding tx) will be used. This is a strong restriction given on payment router, which means these specified hops and channels must be adapted in the router. This is different from hop hints, which maybe ignored by find path. If channel is not specified, find path algorithm will pick a channel within these two peers.

An error will be returned if there is no router could be build from given hops and channels

final_tlc_expiry_delta - Option<u64>, the TLC expiry delta should be used to set the timelock for the final hop, in milliseconds

Returns

router_hops - Vec<RouterHop>, The hops information for router

Method `send_payment_with_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.

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:

Call build_router with hops_info defining the circular route you want, e.g. your_node -> peer_A -> peer_B -> your_node.
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

payment_hash - Option<Hash256>, the hash to use within the payment's HTLC. If not set and keysend is set to true, a random hash will be generated. If not set and there is a payment_hash in the invoice, it will be used. Otherwise, payment_hash need to be set.
router - Vec<RouterHop>, The router to use for the payment
invoice - Option<String>, the encoded invoice to send to the recipient
custom_records - Option<PaymentCustomRecords>, Some custom records for the payment which contains a map of u32 to Vec The key is the record type, and the value is the serialized data. Limits: the sum size of values can not exceed 2048 bytes.

For example:

"custom_records": {
   "0x1": "0x01020304",
   "0x2": "0x05060708",
   "0x3": "0x090a0b0c",
   "0x4": "0x0d0e0f10010d090a0b0c"
 }

keysend - Option<bool>, keysend payment
udt_type_script - Option<Script>, udt type script for the payment
dry_run - Option<bool>, dry_run for payment, used for check whether we can build valid router and the fee for this payment, it's useful for the sender to double check the payment before sending it to the network, default is false

Returns

payment_hash - Hash256, The payment hash of the payment
status - PaymentStatus, The status of the payment
created_at - u64, The time the payment was created at, in milliseconds from UNIX epoch
last_updated_at - u64, The time the payment was last updated at, in milliseconds from UNIX epoch
failed_error - Option<String>, The error message if the payment failed
fee - u128, fee paid for the payment
custom_records - Option<PaymentCustomRecords>, The custom records to be included in the payment.
routers - Vec<SessionRoute>, The router is a list of nodes that the payment will go through. We store in the payment session and then will use it to track the payment history. The router is a list of nodes that the payment will go through. If the payment adapted MPP (multi-part payment), the routers will be a list of nodes For example: A(amount, channel) -> B -> C -> D means A will send amount with channel to B.

Module `Peer`

RPC module for peer management.

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

Method `disconnect_peer`

Disconnect from a peer.

Params

peer_id - PeerId, The peer ID of the peer to disconnect (base58 string, derived from the peer's Pubkey).

Returns

None

Method `list_peers`

List connected peers

Params

None

Returns

peers - Vec<PeerInfo>, A list of connected peers.

Module `Prof`

RPC module for profiling This module require build with pprof feature and debug symbol.

Method `pprof`

Collects a temporary CPU profile and writes a flamegraph SVG to disk.

Params

duration_secs - Option<u64>, Duration to profile in seconds. Defaults 10s.

Returns

path - String, Path of the generated flamegraph SVG.

Module `Watchtower`

RPC module for watchtower related operations

Method `create_watch_channel`

Create a new watched channel

Params

channel_id - Hash256, Channel ID
funding_udt_type_script - Option<Script>, Funding UDT type script
local_settlement_key - Privkey, The local party's private key used to settle the commitment transaction
remote_settlement_key - Pubkey, The remote party's public key used to settle the commitment transaction
local_funding_pubkey - Pubkey, The local party's funding public key
remote_funding_pubkey - Pubkey, The remote party's funding public key
settlement_data - SettlementData, Settlement data

Returns

None

Method `remove_watch_channel`

Remove a watched channel

Params

channel_id - Hash256, Channel ID

Returns

None

Method `update_revocation`

Update revocation

Params

channel_id - Hash256, Channel ID
revocation_data - RevocationData, Revocation data
settlement_data - SettlementData, Settlement data

Returns

None

Method `update_pending_remote_settlement`

Update pending remote settlement

Params

channel_id - Hash256, Channel ID
settlement_data - SettlementData, Settlement data

Returns

None

Method `update_local_settlement`

Update settlement

Params

channel_id - Hash256, Channel ID
settlement_data - SettlementData, Settlement data

Returns

None

Method `create_preimage`

Create preimage

Params

payment_hash - Hash256, Payment hash
preimage - Hash256, Preimage

Returns

None

Method `remove_preimage`

Remove preimage

Params

payment_hash - Hash256, Payment hash

Returns

None

RPC Types

Type `Attribute`

The attributes of the invoice

Enum with values of

FinalHtlcTimeout - u64, This attribute is deprecated since v0.6.0, The final tlc time out, in milliseconds
FinalHtlcMinimumExpiryDelta - u64, The final tlc minimum expiry delta, in milliseconds, default is 1 day
ExpiryTime - Duration, The expiry time of the invoice, in seconds
Description - String, The description of the invoice
FallbackAddr - String, The fallback address of the invoice
UdtScript - CkbScript, The udt type script of the invoice
PayeePublicKey - PublicKey, The payee public key of the invoice
HashAlgorithm - HashAlgorithm, The hash algorithm of the invoice
Feature - Vec<String>, The feature flags of the invoice
PaymentSecret - Hash256, The payment secret of the invoice

Type `CchInvoice`

The generated proxy invoice for the incoming payment.

The JSON representation:

{ "Fiber": String } | { "Lightning": String }

Enum with values of

Fiber - CkbInvoice, Fiber invoice that once paid, the hub will send the outgoing payment to Lightning
Lightning - Bolt11Invoice, Lightning invoice that once paid, the hub will send the outgoing payment to Fiber

Type `CchOrderStatus`

The status of a cross-chain hub order, will update as the order progresses.

Enum with values of

Pending - Order is created and waiting for the incoming invoice to collect enough TLCs.
IncomingAccepted - The incoming invoice collected the required TLCs and is ready to send outgoing payment to obtain the preimage.
OutgoingInFlight - The outgoing payment is in flight.
OutgoingSucceeded - The outgoing payment is settled and preimage has been obtained.
Succeeded - Both payments are settled and the order succeeds.
Failed - Order is failed.

Type `Channel`

The channel data structure

Fields

channel_id - Hash256, The channel ID
is_public - bool, Whether the channel is public
is_acceptor - bool, Is this channel initially inbound? An inbound channel is one where the counterparty is the funder of the channel.
is_one_way - bool, 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 - Option<OutPoint>, The outpoint of the channel
peer_id - PeerId, The peer ID of the channel counterparty (base58 string, derived from the peer's Pubkey).
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
pending_tlcs - Vec<Htlc>, The list of pending tlcs
latest_commitment_transaction_hash - Option<H256>, The hash of the latest commitment transaction
created_at - u64, The time the channel was created at, in milliseconds from UNIX epoch
enabled - bool, Whether the channel is enabled
tlc_expiry_delta - u64, The expiry delta to forward a tlc, in milliseconds, default to 1 day, which is 24 * 60 * 60 * 1000 milliseconds This parameter can be updated with rpc update_channel later.
tlc_fee_proportional_millionths - u128, The fee proportional millionths for a TLC, proportional to the amount of the forwarded tlc. The unit is millionths of the amount. default is 1000 which means 0.1%. This parameter can be updated with rpc update_channel later. Not that, we use outbound channel to calculate the fee for TLC forwarding. For example, if we have a path A -> B -> C, then the fee B requires for TLC forwarding, is calculated the channel configuration of B and C, not A and B.
shutdown_transaction_hash - Option<H256>, The hash of the shutdown transaction
failure_detail - Option<String>, Human-readable reason why the channel opening failed. Only present when the channel is in a failed state (e.g. abandoned or funding aborted).

Type `ChannelInfo`

The Channel information.

Fields

channel_outpoint - OutPoint, The outpoint of the channel.
node1 - Pubkey, The identity public key of the first node (secp256k1 compressed, hex string).
node2 - Pubkey, The identity public key of the second node (secp256k1 compressed, hex string).
created_timestamp - u64, 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 - Option<ChannelUpdateInfo>, The update info from node1 to node2, e.g. timestamp, fee_rate, tlc_expiry_delta, tlc_minimum_value
update_info_of_node2 - Option<ChannelUpdateInfo>, The update info from node2 to node1, e.g. timestamp, fee_rate, tlc_expiry_delta, tlc_minimum_value
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.

Type `ChannelState`

The state of a channel

Enum with values of

NegotiatingFunding - NegotiatingFundingFlags, We are negotiating the parameters required for the channel prior to funding it.
CollaboratingFundingTx - CollaboratingFundingTxFlags, We're collaborating with the other party on the funding transaction.
SigningCommitment - SigningCommitmentFlags, We have collaborated over the funding and are now waiting for CommitmentSigned messages.
AwaitingTxSignatures - AwaitingTxSignaturesFlags, We've received and sent commitment_signed and are now waiting for both party to collaborate on creating a valid funding transaction.
AwaitingChannelReady - AwaitingChannelReadyFlags, We've received/sent funding_created and funding_signed and are thus now waiting on the funding transaction to confirm.
ChannelReady - Both we and our counterparty consider the funding transaction confirmed and the channel is now operational.
ShuttingDown - ShuttingDownFlags, We've successfully negotiated a closing_signed dance. At this point, the ChannelManager
Closed - CloseFlags, This channel is closed.

Type `ChannelUpdateInfo`

The channel update info with a single direction of channel

Fields

timestamp - u64, The timestamp is the time when the channel update was received by the node.
enabled - bool, Whether the channel can be currently used for payments (in this one direction).
outbound_liquidity - Option<u128>, The exact amount of balance that we can send to the other party via the channel.
tlc_expiry_delta - u64, The difference in htlc expiry values that you must have when routing through this channel (in milliseconds).
tlc_minimum_value - u128, The minimum value, which must be relayed to the next hop via the channel
fee_rate - u64, The forwarding fee rate for the channel.

Type `CkbInvoice`

Represents a syntactically and semantically correct lightning BOLT11 invoice

There are three ways to construct a CkbInvoice:

using [CkbInvoiceBuilder]
using str::parse::<CkbInvoice>(&str) (see [CkbInvoice::from_str])

Fields

currency - Currency, The currency of the invoice
amount - Option<u128>, The amount of the invoice
signature - Option<InvoiceSignature>, The signature of the invoice
data - InvoiceData, The invoice data, including the payment hash, timestamp and other attributes

Type `CkbInvoiceStatus`

The currency of the invoice, can also used to represent the CKB network chain.

Enum with values of

Open - The invoice is open and can be paid.
Cancelled - The invoice is cancelled.
Expired - The invoice is expired.
Received - The invoice is received, but not settled yet.
Paid - The invoice is paid.

Type `Currency`

The currency of the invoice, can also used to represent the CKB network chain.

Enum with values of

Fibb - The mainnet currency of CKB.
Fibt - The testnet currency of the CKB network.
Fibd - The devnet currency of the CKB network.

Type `Hash256`

A 256-bit hash digest, used as identifier of channel, payment, transaction hash etc.

Type `HashAlgorithm`

HashAlgorithm is the hash algorithm used in the hash lock.

Enum with values of

CkbHash - The default hash algorithm, CkbHash
Sha256 - The sha256 hash algorithm

Type `HopHint`

A hop hint is a hint for a node to use a specific channel.

Fields

pubkey - Pubkey, The public key of the node
channel_outpoint - OutPoint, The outpoint of the channel
fee_rate - u64, The fee rate to use this hop to forward the payment.
tlc_expiry_delta - u64, The TLC expiry delta to use this hop to forward the payment.

Type `HopRequire`

A hop requirement need to meet when building router, do not including the source node, the last hop is the target node.

Fields

pubkey - Pubkey, The public key of the node
channel_outpoint - Option<OutPoint>, The outpoint for the channel, which means use channel with channel_outpoint to reach this node

Type `Htlc`

The htlc data structure

Fields

id - u64, The id of the htlc
amount - u128, The amount of the htlc
payment_hash - Hash256, The payment hash of the htlc
expiry - u64, The expiry of the htlc
forwarding_channel_id - Option<Hash256>, If this HTLC is involved in a forwarding operation, this field indicates the forwarding channel. For an outbound htlc, it is the inbound channel. For an inbound htlc, it is the outbound channel.
forwarding_tlc_id - Option<u64>, If this HTLC is involved in a forwarding operation, this field indicates the forwarding tlc id.
status - TlcStatus, The status of the htlc

Type `InvoiceData`

The metadata of the invoice

Fields

timestamp - u128, The timestamp of the invoice
payment_hash - Hash256, The payment hash of the invoice
attrs - Vec<Attribute>, The attributes of the invoice, e.g. description, expiry time, etc.

Type `InvoiceSignature`

Recoverable signature

Type `NodeInfo`

The Node information.

Fields

node_name - String, The name of the node.
version - String, The version of the node.
addresses - Vec<MultiAddr>, The addresses of the node.
features - Vec<String>, The node features supported by the node.
node_id - Pubkey, The identity public key of the node (secp256k1 compressed, hex string), same as pubkey in list_peers.
timestamp - u64, 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 - 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.

Type `PaymentCustomRecords`

The custom records to be included in the payment. The key is hex encoded of u32, it's range limited in 0 ~ 65535, and the value is hex encoded of Vec<u8> with 0x as prefix. For example:

"custom_records": {
   "0x1": "0x01020304",
   "0x2": "0x05060708",
   "0x3": "0x090a0b0c",
   "0x4": "0x0d0e0f10010d090a0b0c"
 }

Fields

data - HashMap<u32::Vec<u8>>, The custom records to be included in the payment.

Type `PaymentStatus`

The status of a payment, will update as the payment progresses. The transfer path for payment status is Created -> Inflight -> Success | Failed.

MPP Behavior: A single session may involve multiple attempts (HTLCs) to fulfill the total amount.

Enum with values of

Created - Initial status. A payment session is created, but no HTLC has been dispatched.
Inflight - The first hop AddTlc is sent successfully and waiting for the response.

MPP Logic: Status Inflight means at least one attempt is still not in Success, payment needs more retrying or waiting for HTLC settlement.

Success - The payment is finished. All related HTLCs are successfully settled, and the aggregate amount equals the total requested amount.
Failed - The payment session has terminated. HTLCs have failed and the target amount cannot be fulfilled after exhausting all retries.

Type `PeerInfo`

The information about a peer connected to the node.

Fields

pubkey - Pubkey, The identity public key of the peer (also known as node_id).
peer_id - PeerId, 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 - MultiAddr, 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.

Type `Privkey`

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. 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.

Type `RemoveTlcReason`

The reason for removing a TLC

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

Type `RevocationData`

Data needed to revoke an outdated commitment transaction.

Fields

commitment_number - u64, The commitment transaction version number that was revoked
aggregated_signature - CompactSignature, The aggregated signature from both parties that authorizes the revocation
output - CellOutput, The output cell from the revoked commitment transaction
output_data - Bytes, The associated data for the output cell (e.g., UDT amount for token transfers)

Type `RouterHop`

A router hop information for a payment, a paymenter router is an array of RouterHop, a router hop generally implies hop target will receive amount_received with channel_outpoint of channel. Improper hop hint may make payment fail, for example the specified channel do not have enough capacity.

Fields

target - Pubkey, The node that is sending the TLC to the next node.
channel_outpoint - OutPoint, The channel of this hop used to receive TLC
amount_received - u128, The amount that the source node will transfer to the target node. We have already added up all the fees along the path, so this amount can be used directly for the TLC.
incoming_tlc_expiry - u64, The expiry for the TLC that the source node sends to the target node. We have already added up all the expiry deltas along the path, the only thing missing is current time. So the expiry is the current time plus the expiry delta.

Type `SessionRoute`

The router is a list of nodes that the payment will go through. We store in the payment session and then will use it to track the payment history. The router is a list of nodes that the payment will go through. For example: A(amount, channel) -> B -> C -> D means A will send amount with channel to B.

Fields

nodes - Vec<SessionRouteNode>, the nodes in the route

Type `SessionRouteNode`

The node and channel information in a payment route hop

Fields

pubkey - Pubkey, the public key of the node
amount - u128, the amount for this hop
channel_outpoint - OutPoint, the channel outpoint for this hop

Type `SettlementData`

Data needed to authorize and execute a settlement transaction.

Fields

local_amount - u128, The total amount of CKB/UDT being settled for the local party
remote_amount - u128, The total amount of CKB/UDT being settled for the remote party
tlcs - Vec<SettlementTlc>, The list of pending Time-Locked Contracts (TLCs) included in this settlement

Type `SettlementTlc`

Data needed to authorize and execute a Time-Locked Contract (TLC) settlement transaction.

Fields

tlc_id - TLCId, The ID of the TLC (either offered or received)
hash_algorithm - HashAlgorithm, The hash algorithm used for the TLC
payment_amount - u128, The amount of CKB/UDT involved in the TLC
payment_hash - Hash256, The hash of the payment preimage
expiry - u64, The expiry time for the TLC in milliseconds
local_key - Privkey, The local party's private key used to sign the TLC
remote_key - Pubkey, The remote party's public key used to verify the TLC

Type `TLCId`

The id of a tlc, it can be either offered or received.

Enum with values of

Offered - u64, Offered tlc id
Received - u64, Received tlc id

Type `TlcStatus`

The status of a tlc

Enum with values of

Outbound - OutboundTlcStatus, Outbound tlc
Inbound - InboundTlcStatus, Inbound tlc

Type `UdtArgInfo`

The UDT argument info which is used to identify the UDT configuration

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<UdtDep>, The cell deps of the UDT.

Type `UdtCellDep`

The UDT cell dep which is used to identify the UDT configuration for a Fiber Node

Fields

out_point - OutPointWrapper, The out point of the cell dep.
dep_type - DepType, The type of the cell dep.

Type `UdtCfgInfos`

A list of UDT configuration infos.

Type `UdtDep`

Udt script on-chain dependencies.

Fields

cell_dep - Option<UdtCellDep>, cell dep described by out_point.
type_id - Option<Script>, cell dep described by type ID.

Type `UdtScript`

The UDT script which is used to identify the UDT configuration for a Fiber Node

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.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Fiber Network Node RPC

RPC Modules

Module Cch

Method send_btc

Params

Returns

Method receive_btc

Params

Returns

Method get_cch_order

Params

Returns

Module Channel

Method open_channel

Params

Returns

Method accept_channel

Params

Returns

Method abandon_channel

Params

Returns

Method list_channels

Params

Returns

Method shutdown_channel

Params

Returns

Method update_channel

Params

Returns

Module Dev

Method commitment_signed

Params

Returns

Method add_tlc

Params

Returns

Method remove_tlc

Params

Returns

Method submit_commitment_transaction

Params

Returns

Method check_channel_shutdown

Params

Returns

Module Graph

Method graph_nodes

Params

Returns

Method graph_channels

Params

Returns

Module Info

Method node_info

Params

Returns

Module Invoice

Method new_invoice

Params

Returns

Method parse_invoice

Params

Returns

Method get_invoice

Params

Returns

Method cancel_invoice

Params

Returns

Method settle_invoice

Params

Returns

Module `Cch`

Method `send_btc`

Method `receive_btc`

Method `get_cch_order`

Module `Channel`

Method `open_channel`

Method `accept_channel`

Method `abandon_channel`

Method `list_channels`

Method `shutdown_channel`

Method `update_channel`

Module `Dev`

Method `commitment_signed`

Method `add_tlc`

Method `remove_tlc`

Method `submit_commitment_transaction`

Method `check_channel_shutdown`

Module `Graph`

Method `graph_nodes`

Method `graph_channels`

Module `Info`

Method `node_info`

Module `Invoice`

Method `new_invoice`

Method `parse_invoice`

Method `get_invoice`

Method `cancel_invoice`

Method `settle_invoice`

Module `Payment`

Method `send_payment`

Method `get_payment`

Method `build_router`

Method `send_payment_with_router`

Module `Peer`

Method `connect_peer`

Method `disconnect_peer`

Method `list_peers`

Module `Prof`

Method `pprof`

Module `Watchtower`

Method `create_watch_channel`

Method `remove_watch_channel`

Method `update_revocation`

Method `update_pending_remote_settlement`

Method `update_local_settlement`

Method `create_preimage`

Method `remove_preimage`

Type `Attribute`

Type `CchInvoice`

Type `CchOrderStatus`

Type `Channel`

Type `ChannelInfo`

Type `ChannelState`

Type `ChannelUpdateInfo`