Skip to main content

​
Selecting the Exact Force-Close Snapshot

Week 13 established that settlement proof belongs to an exact direction-aware TLC. Week 18 goes beneath that rule: before resolving any TLC, the node must determine which historical commitment state the closing transaction actually published. That distinction matters because a remote peer can force-close with either its pending commitment or its preceding unrevoked commitment. A TLC may exist in one and not the other. Treating current channel memory as the truth can strand a channel waiting for a TLC that was never placed on-chain—or finalize while ignoring one that was. The primary sources are Fiber PR #1649, merged September 10, 2026, and PR #1651, merged earlier that day. These are merged Fiber behavior after v0.9.0, not claims about the v0.9.0 release artifact itself.

​
A commitment number selects history

The closing lock commits to a settlement witness hash, not the complete TLC list. Reconciliation therefore combines on-chain evidence with locally retained Watchtower snapshots:
  1. Parse and validate the commitment lock.
  2. Verify the funding key and funding input lineage.
  3. Read the close direction and commitment number.
  4. Select the matching local, preceding-remote, or pending-remote snapshot.
  5. Hash the selected settlement witness and compare it with the committed hash.
Rebuilding a transaction and comparing its raw hash is not sufficient. Broadcast-time cell_deps, including FundingLock or UDT dependencies, may change the raw transaction without changing the intended historical commitment snapshot. Reconstructing history from current channel state is also unsafe because the channel may have advanced. Exercise 69 models the correct selector. A preceding commitment cannot borrow the pending snapshot, an invalid funding identity is rejected, and permanently missing historical data remains Unknown rather than becoming a guessed success.

​
Recovery evidence must outlive the actor

Once verified, Fiber persists a shutdown settlement record keyed by channel. It binds the closing transaction hash, direction, commitment number, and settlement snapshot. Live actor recovery and offline NetworkActor recovery can then consume the same durable evidence. The deletion order is safety-critical: persist completed channel state -> delete shutdown settlement record Deleting first creates a crash window where the channel is still waiting but its only verified historical snapshot is gone. Exercise 70 injects a crash after the durable channel transition and proves restart can finish cleanup without repeating the logical transition. A corrected verified record may overwrite a stale one, but a mismatched transaction or direction is ignored.

​
Reconcile the published set, not the current set

Suppose the pending commitment contains an offered LocalAnnounced TLC, but the peer publishes the preceding commitment. That TLC is absent from the published snapshot and must not block settlement. The inverse is equally important: a TLC present in the published snapshot remains unresolved even if current local state has lost it. Exercise 72 computes blockers from the authenticated published snapshot. It keeps missing local evidence explicit, ignores pending-only local TLCs when the preceding commitment was published, and treats 0xFE/0xFF party-balance unlocks separately from TLC removal.

​
A preimage is not a forwarding receipt

Payment preimages are stored by full payment hash and are visible to channel actors across the node. Concurrent attempts may share that hash. A preimage learned by one successful attempt therefore does not prove that every upstream forwarding TLC with the same hash succeeded. PR #1651 restricts automatic preimage fulfillment to a received TLC that terminates locally. A TLC is excluded when it is waiting for a downstream AddTlc result, linked to a downstream channel/TLC, already has retryable removal queued, or already has a removal reason. Forwarded TLCs are resolved by their exact downstream removal result. Exercise 71 demonstrates the boundary: the final hop may use its local preimage, while an upstream sibling with the same full hash remains governed by its own downstream outcome.

​
Evidence classifications

The broader CKB transaction model explains why the consumed input and verified witness are the chain evidence. The Nervos Knowledge Base Fiber guide supplies channel context. CKB Quest continues to inspire visible assertions, while Nervos Nation remains optional ecosystem framing.

​
Run the exercises

  • 69-commitment-snapshot-selection.ts selects and authenticates the exact historical commitment snapshot.
  • 70-durable-shutdown-settlement-record.ts persists recovery evidence and proves crash-safe deletion order.
  • 71-local-preimage-scope.ts prevents a node-global same-hash preimage from resolving forwarded TLCs.
  • 72-exact-settlement-recovery-audit.ts audits published blockers, missing local state, pending-only TLCs, and party-balance unlocks.
Week 18 sharpens the course’s central rule: exact TLC identity is necessary, but it is not enough. The TLC must also belong to the exact authenticated commitment history that CKB actually settled.