Closing a channel

A channel holds the payer's money, so the payer needs a way to get the leftover back. The payee holds signed claims, so the payee needs time to cash them first. The closing rules balance the two.

The payee closes. The payee can close the channel at any time. Usually they redeem their last claim and close in the same step. Whatever is left goes back to the payer right away.

The payer closes. The payer can ask to close. If the channel is empty, it closes at once. If it still holds XRP, the request starts a countdown called the settle delay. It is a last call. The payee has at least that long to redeem any claims. After that, the channel is expired.

The settle delay does not slow down payments. Redeeming a claim still takes one ledger, a few seconds. The delay only slows down closing.

A fixed end date. When opening the channel, the payer can set a hard end time. It can never be moved. Once it passes, the channel is expired no matter what.

Expired is not gone. An expired channel stays on the ledger until some transaction touches it. Anyone can send that transaction. The channel then closes and the leftover XRP returns to the payer.

For a payee, the lesson is short. Know the settle delay and any end date before you accept claims. Redeem before they run out. A claim on a closed channel is worth nothing.

A PayChannel has two expiry fields, both in seconds since the Ripple Epoch. Each is compared with the previous ledger's close time.

Expiration is absent when the channel is created.

Source address. It can:

• Send PaymentChannelClaim with tfClose (131072). With no XRP left in the channel, this closes it at once. Otherwise it sets Expiration to the previous ledger's close time plus SettleDelay, unless an earlier Expiration is already set.
• Send PaymentChannelClaim with tfRenew (65536) to clear Expiration.
• Set Expiration with PaymentChannelFund. The new value cannot be earlier than the current Expiration or the previous close time plus SettleDelay, whichever is earliest. A bad value fails with temBAD_EXPIRATION.

In short, the source can move Expiration freely as long as the channel stays open at least SettleDelay seconds after the first attempt to close it.

Destination address. It cannot set Expiration. It can use tfClose to close the channel immediately after processing a claim. Unclaimed XRP is refunded to the source.

Any address. A validly formed PaymentChannelClaim or PaymentChannelFund that accesses an expired channel closes it, with result tesSUCCESS. If the channel is not expired and a third party tries to change it, the result is tecNO_PERMISSION.

On close, Amount minus Balance returns to the source, the entry is deleted and its owner reserve is freed.

SettleDelay is fixed at creation and can be any 32-bit value, zero included. A small value leaves the payee little time to react to a close request.

Deleted destinations. A channel created before fixPayChanRecipientOwnerDir (enabled 2020-05-01) can outlive its destination account. Paying from it then fails with tecNO_DST. Closing it still works.

Read channels with account_channels. It returns amount, balance, settle_delay, public_key, and cancel_after and expiration when set.

Related: Escrow and Token Escrow, Accounts and reserves.