Reconciling TLCs After Force Close
Week 12 followed a Fiber channel back to CKB at the settlement boundary. Week 13 stays at that boundary, but narrows the question:After a force close, what can an operator safely say about each time-locked conditional payment?
The answer is deliberately more careful than a channel-level label. A party can unlock value while another TLC remains pending. A payment hash can appear in more than one context. A collector can see the same close several times. A historical record can lack the preimage needed to explain the outcome. In each case, a broad “settled” label risks transferring evidence from one conditional payment to another.
The thesis for the week is:
A force-close reconciliation is only as trustworthy as its exact TLC-to-proof mapping.
Start from the CKB boundary
CKB is a cell model: state changes by consuming live cells and creating replacement outputs. Scripts validate whether that transition is allowed. A transaction can also carry witnesses, and the CKB VM gives scripts access to relevant cell data and witness data during validation. The official How CKB Works guide is the primary conceptual source for those boundaries. That matters here because a force close is not merely a dashboard event. It creates an on-chain transition whose cells, scripts, and witnesses are the proof boundary. A local reconciler may read decoded results from a trusted collector, but it must not pretend that a cached status string is stronger evidence than the on-chain transition it summarizes. Fiber is an off-chain payment-channel network built on CKB. Its channel model keeps frequent balance updates off-chain and returns to CKB for opening, closing, settlement, or dispute. The official What Is Fiber? explainer gives the high-level payment-channel and hashlock/timelock context. Its discussion is useful for mental models; it is not a wire-format specification.TLC identity is more than a number
An operator might first see a TLC identifier such as42 and try to use it as a lookup key. That is not enough.
For a conservative teaching model, a TLC identity is the tuple:
channel + commitment + direction + TLC ID
Direction matters. An offered TLC with numeric ID 42 and a received TLC with numeric ID 42 are distinct conditional payments. A proof for one must not settle the other. The same rule applies to a sibling TLC whose ID differs by one digit, or to a record from another commitment version.
The payment hash is an additional full-width check, not a shortcut. The teaching fixtures accept only canonical 32-byte hex hashes (exactly 64 hexadecimal characters), then compare the decoded full value. A 20-byte prefix that happens to match, a short/odd string, or an invalid suffix is not a proof that two hashes are identical. The Week 13 fixture deliberately creates two different 32-byte values with the same first 20 bytes, then rejects cross-mapping. This is a small example of a general rule: abbreviated identifiers are useful in a UI, but unsafe as a reconciliation key.
A proof needs lineage before it needs an outcome
The mapping cannot start at a payment hash. It begins with the cells that establish the force-close path:funding outpoint -> commitment output -> successor output
The local mapping fixture checks both predecessor links, then requires an authenticated, later pending-TLC snapshot for that commitment output. The commitment carries a teaching-model digest of the ordered TLC list, so a newly authenticated reordered list still fails. Its witness index selects one pending TLC from that exact order. Only then do direction-aware TLC ID, the committed hash algorithm, and the full payment hash have a chance to agree.
This sequence rejects an unrelated lookalike cell, a wrong funding predecessor, a successor from another commitment, an out-of-range witness index, a reordered snapshot, an unauthenticated snapshot, a mismatched full hash, and a prefix-only collision. It also shows why reserved party balance unlock tags 0xFE and 0xFF cannot erase the pending TLC list: those unlocks are not a per-TLC proof.
Outcomes need an explicit unknown state
The local exercises use three outcomes:Fulfilledmeans one exact proof maps to the TLC and a supplied preimage hashes to the full payment hash.SettledWithoutPreimagemeans one exact proof maps to the TLC but the teaching fixture contains no preimage. It is intentionally not promoted to fulfillment.Unknowncovers missing proof, hash mismatch, or more than one exact candidate.
Correlation must have more than a hash
A preimage or payment hash is meaningful only in context. A payment session, tenant, exact TLC key, channel, proof ID, committed hash algorithm, and expected full hash together create a safer application correlation boundary. That prevents a particularly tempting error: an unrelated payment session with the same hash must not cause this session to become fulfilled. The data may be genuine, but it is not necessarily evidence for the payment being explained. The reconciliation fixture keeps actual TLC, channel, payment, invoice, optional CCH, and ordinary preimage-store records. It validates the discovered preimage against the full hash using the record’s committed algorithm before it mutates any state. When present, a correlated outgoing CCH record moves from in-flight to success with the TLC, payment, and invoice; a mismatched CCH leaves all records untouched. Missing proof data or a mismatched full hash producesUnknown, persists no preimage, and leaves the linked records unchanged. The HMAC used by the lineage fixture is deliberately a teaching substitute for an authenticated collector boundary; it is not a statement about Fiber RPC authentication or CKB witness encoding.
Tenant isolation is the same kind of boundary. A valid proof or observation for one tenant must not appear in another tenant’s query results. It is application policy, not chain consensus, but it is essential if an operator-facing service stores more than one customer’s evidence.
Replays are normal, not exceptional
On-chain indexers, RPC retries, reconnecting collectors, and delayed snapshots can all repeat an observation. The correct response is idempotency: preserve the observation for auditability if needed, but apply its logical transition once. The proof store is tenant-scoped and keyed bynode ID + channel ID + direction-aware TLC ID. Its tx observation ID makes repeated discovery idempotent. A proof stored for tenant A cannot resolve or mutate tenant B’s otherwise similar TLC. In this teaching policy, conflicting candidates seen before a TLC resolves make the result Unknown; a later distinct candidate after fulfillment is quarantined for audit rather than replacing already-applied authoritative evidence.
The same discipline governs preimage retention. Same-hash sibling TLCs still require separate exact proofs. Retain the preimage until each sibling has resolved. A legacy no-preimage record remains readable but has the Unknown outcome and cannot trigger garbage collection. The final audit prints accepted proofs, rejected evidence, logical transitions, retained preimages, and unknown outcomes.
What Week 13 verifies—and what it teaches
The source boundary is important enough to name plainly.
The verified behavior in scope is modest: Fiber v0.9.0’s release notes say it added on-chain TLC settlement support for force-closed channels. The scripts do not claim to decode Fiber witness formats, validate a real CKB transaction, define Fiber’s complete state machine, or establish a production retention policy. They are deterministic teaching models for the conservative application rules around those real boundaries.
What to build locally this week
Run the force-close TLC reconciliation package:49-force-close-tlc-outcomes.tsseparates fulfilled, no-preimage, and unknown outcomes while retaining pending TLCs after a party unlock.50-exact-tlc-proof-mapping.tsfollows funding-outpoint lineage into a commitment and successor output, then maps an authenticated ordered snapshot and witness index to one exact direction-aware TLC and full hash.51-correlated-state-reconciliation.tsreconciles actual TLC, channel, payment, invoice, optional CCH, and preimage-store records only from exact tenant/session/proof/hash evidence.52-idempotent-replay-and-retention.tsuses tenant-scoped exact proof keys, an idempotent tx-observation boundary, same-hash sibling retention, legacyUnknownhandling, and a final audit.