Channel Lifecycle

TL;DR

A channel goes through AwaitingLockin → ChannelReady → Closing → Closed. Each side must reserve 99 CKB. Use list_channels to check the state, and shutdown_channel to close.

A Fiber payment channel goes through several states from creation to closure. Understanding these states is essential for node operators and developers building on Fiber.

Channel States

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Awaiting    │────▶│  Channel     │────▶│   Closing    │
│   Lockin     │     │    Ready     │     │              │
└──────────────┘     └──────┬───────┘     └──────┬───────┘
                           │                     │
                           ▼                     ▼
                    ┌──────────────┐     ┌──────────────┐
                    │   Normal     │     │    Closed    │
                    │  Operation   │     │              │
                    └──────────────┘     └──────────────┘

AwaitingLockin

The channel has been proposed and the funding transaction is being confirmed on-chain. Both parties are exchanging OpenChannel / AcceptChannel messages and signing the funding transaction.

What happens in this state:

1. The initiator sends OpenChannel with channel parameters (funding amount, fee rates, TLC limits)
2. The accepter responds with AcceptChannel
3. Both parties exchange commitment_signed messages (two rounds)
4. Both parties exchange tx_signatures to finalize the funding transaction
5. The funding transaction is broadcast to the CKB network
6. Both parties exchange channel_ready once the funding tx is confirmed

RPC to initiate: open_channel

How long: Depends on CKB block confirmation time (typically a few seconds on testnet)

Common issues:

• If the funding transaction fails to confirm, the channel will time out after funding_timeout_seconds (default: 24 hours)
• If the peer is offline, the channel will stay in AwaitingLockin indefinitely until the peer comes back online

ChannelReady (Open)

The funding transaction is confirmed and the channel is fully operational. Both parties can now make off-chain payments.

What you can do in this state:

• Add TLCs (AddTlc): Lock funds in a time-locked contract for a payment
• Remove TLCs (RemoveTlc): Release funds from a TLC (on success with preimage, or on failure with error code)
• Update channel parameters (update_channel): Change fee rates or TLC limits
• Send payments (send_payment): Initiate a payment through the channel

State updates: Every balance change requires a round of CommitmentSigned / RevokeAndAck between both parties. This two-step process ensures that old states can be revoked — if a party tries to submit an outdated commitment transaction, the other party can punish them using the revocation key.

Closing

One or both parties have initiated channel closure. The final state is being negotiated and the closing transaction will be broadcast on-chain.

How closing works:

1. One party sends a Shutdown message
2. The other party responds with Shutdown
3. Both parties negotiate the closing transaction fee via closing_signed messages
4. Once fee is agreed, the closing transaction is broadcast on-chain

RPC to initiate: shutdown_channel

Cooperative vs. Uncooperative close:

• Cooperative close (normal): Both parties agree on the final balance and fee, then broadcast the closing transaction. Fast and cheap.
• Uncooperative close (force close): One party broadcasts the latest commitment transaction on-chain without the other's cooperation. The other party must wait for the to_self_delay to expire before claiming their funds. This is slower and more expensive.

Closed

The channel has been fully settled on-chain. All funds have been distributed according to the final channel state.

What happens: The closing transaction is confirmed, and each party's funds are available in their CKB wallet. The channel is removed from the active channel list.

Channel Reserve

When a channel is open, each party must maintain a reserve of 99 CKB:

• 98 CKB for the commitment lock occupied capacity
• 1 CKB for the shutdown transaction fee

This reserve ensures there are sufficient funds for on-chain settlement when the channel closes. It is not available for off-chain payments.

Example: If you fund 499 CKB in a channel:

• Your available balance for payments: 499 - 99 = 400 CKB

Channel Parameters

When opening a channel, the following parameters are negotiated:

Monitoring Channel State

Using fnn-cli

# List all channels with their states
fnn-cli channel list_channels

# Check a specific channel
fnn-cli channel list_channels --channel-id 0x...

Using RPC

{
  "jsonrpc": "2.0",
  "method": "list_channels",
  "params": [],
  "id": 1
}

Channel State Names

The state_name field in the response uses SCREAMING_SNAKE_CASE:

Related Topics

• Payment Lifecycle — how payments work within an open channel
• P2P Message Protocol — the protocol-level message details for each transition
• Troubleshooting — common channel-related issues
• Channel Rebalancing — shift liquidity between channels