Module `Channel`

Module Channel

RPC module for channel management.

Method open_channel

Attempts to open a channel with a peer.

Params

• pubkey - Pubkey, The public key of the peer to open a channel with. The peer must be connected through the connect_peer rpc first.
• 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

• pubkey - Option<[Pubkey](#type-pubkey)>, The public key 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
• 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](#type-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, default value is true
• 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

---

Method open_channel_with_external_funding

Opens a channel with external funding. The node will negotiate the channel with the peer, but the user must sign the funding transaction themselves using their own wallet.

This is useful when the user wants to fund a channel from an external wallet rather than having the node sign with its internal key.

Returns the final unsigned funding transaction after internal tx collaboration has frozen the structure. The user must sign it and submit it with submit_signed_funding_tx without changing the transaction structure.

Params

• pubkey - Pubkey, The identity public key of the peer to open a channel with. The peer must already be connected through the connect_peer rpc first.
• 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 - Script, The script used to receive the channel balance when the channel is closed. This is REQUIRED for external funding.
• funding_lock_script - Script, The lock script that controls the funding cells. The node will collect cells with this lock script to build the funding transaction. The user must be able to sign for this lock script.
• funding_lock_script_cell_deps - Option<Vec<CellDep>>, Optional extra cell deps required by funding_lock_script. This is useful for custom wallet lock scripts whose deps are not part of the genesis defaults.
• 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.
• 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

• channel_id - Hash256, The channel ID of the channel being opened.
• unsigned_funding_tx - Transaction, The final unsigned funding transaction that needs to be signed.

---

Method submit_signed_funding_tx

Submits a signed funding transaction for an externally funded channel.

After calling open_channel_with_external_funding, the user signs the returned final negotiated unsigned transaction with their wallet and submits it here. The signed transaction should be directly broadcastable and will not be structurally modified.

External signers must keep inputs, outputs, outputs_data, and cell_deps unchanged. See the external funding guide for signing details and examples.

Params

• channel_id - Hash256, The channel ID returned from open_channel_with_external_funding.
• signed_funding_tx - Transaction, The signed funding transaction.

Returns

• channel_id - Hash256, The channel ID.
• funding_tx_hash - Hash256, The hash of the funding transaction that was submitted.