Function: settleRail(uint256 railId, uint256 untilEpoch)

Settles payments for a rail up to the specified epoch. Settlement may fail to reach the target epoch if either the client lacks the funds to pay up to the current epoch or the validator refuses to settle the entire requested range.

Can only be one of the three participants in the rail, either the payer, payee or operator.

Inputs

• railId

  • Control: Fully controlled by the caller.

  • Constraints: Must reference an active rail (from != address(0)) — caller must be a rail participant (client, operator, or payee).

  • Impact: Selects the rail to settle and determines token/payer/payee/validator context used by downstream logic.

• untilEpoch

  • Control: Fully controlled by the caller.

  • Constraints: Must be ≤ current block.number. Effective target is bounded by rail state — for active rails, min(untilEpoch, payer.lockupLastSettledAt), and for terminated rails, min(untilEpoch, rail.endEpoch).

  • Impact: Upper bound for requested settlement window — influences how much is attempted to be settled.

Branches and code coverage

Intended branches

• Called by client/payer.

  Test coverage

• Called by payee.

  Test coverage

• Called by operator.

  Test coverage

• Called on a terminated rail that is settled, but not finalized.

  Test coverage

• Called on a non-terminated rail.

  Test coverage

Negative behavior

• Caller is not a participant (payer, payee, operator).

  Negative test

• untilEpoch is in the future.

  Negative test

• Rate change queue is empty, but settlement has not progressed (i.e. startEpoch <= rail.settledUpTo).

  Negative test

Function call analysis

• this.burnAndRefundRest(Payments.NETWORK_FEE) -> Payments.burnAndRefundRest

  • What is controllable? N/A.

  • If the return value is controllable, how is it used and how can it go wrong? N/A.

  • What happens if it reverts, reenters or does other unusual control flow? The function consumes and native tokens and send these to the burn address. The remainder is refunded.

• this.settleRailInternal(railId, untilEpoch, skipValidation) -> Payments.settleRailInternal

  • What is controllable? railId and untilEpoch are fully controllable. skipValidation is always false here.

  • If the return value is controllable, how is it used and how can it go wrong? Returns only calculated values that are relayed to the initial caller directly. railId is already assumed valid, but an erroneous one would fail the first isRailTerminated check as addresses would be zero.

  • What happens if it reverts, reenters or does other unusual control flow? Function is internal and only called from non-reentrant functions, where the second caller is an emergency function locked behind operator capabilities.