Skip to content

Latest commit

 

History

History
701 lines (468 loc) · 25.6 KB

README.md

File metadata and controls

701 lines (468 loc) · 25.6 KB
Raw

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.

RPC Modules

Module Cch

RPC module for cross chain hub demonstration. This is the seccond line

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

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

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

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.
  • 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.
  • 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 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_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.
  • tlc_min_value - Option<u128>, The minimum value for a TLC our side can receive an optional parameter, default is 0, which means we can receive 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.
  • 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 receive an optional parameter, default is 0, which means we can receive 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.
  • 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 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
  • include_closed - Option<bool>, Whether to include closed channels in the list, an optional parameter, default value is false
Returns
  • channels - Vec<Channel>, The list of channels

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

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 CLTV delta from the current height that should be used to set the timelock for the final hop

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

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
  • 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
  • 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
  • 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 - PaymentSessionStatus, 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

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

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

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.
  • 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_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.
  • 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.
  • 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 - 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_expiry_delta - 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.

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

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.
Returns
  • None

RPC Types

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 is about to drop us, but we store this anyway.
  • Closed - CloseFlags, This channel is closed.

Type Channel

The channel data structure

Fields

  • channel_id - Hash256, The channel ID
  • is_public - bool, Whether the channel is public
  • channel_outpoint - Option<OutPoint>, The outpoint of the channel
  • 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
  • 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

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

Type UdtCellDep

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

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.

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

Type UdtCfgInfos

A list of UDT configuration infos.

Fields

  • `` - Vec<UdtArgInfo>, The list of UDT configuration infos.

Type NodeInfo

The Node information.

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.

Type ChannelInfo

The Channel information.

Fields

  • channel_outpoint - OutPoint, The outpoint of the channel.
  • node1 - Pubkey, The node ID of the first node.
  • node2 - Pubkey, The node ID of the second node.
  • created_timestamp - u64, The created timestamp of the channel, which is the block header timestamp of the block that contains the channel funding transaction.
  • last_updated_timestamp_of_node1 - Option<u64>, The timestamp of the last update to channel by node 1 (e.g. updating fee rate).
  • last_updated_timestamp_of_node2 - Option<u64>, The timestamp of the last update to channel by node 2 (e.g. updating fee rate).
  • fee_rate_of_node1 - Option<u64>, The fee rate set by node 1. This is the fee rate for node 1 to forward tlcs sent from node 2 to node 1.
  • fee_rate_of_node2 - Option<u64>, The fee rate set by node 2. This is the fee rate for node 2 to forward tlcs sent from node 1 to node 2.
  • 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.