Skip to main content

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 as 42 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:
  • Fulfilled means one exact proof maps to the TLC and a supplied preimage hashes to the full payment hash.
  • SettledWithoutPreimage means one exact proof maps to the TLC but the teaching fixture contains no preimage. It is intentionally not promoted to fulfillment.
  • Unknown covers missing proof, hash mismatch, or more than one exact candidate.
This is not a claim that these are Fiber’s complete protocol-level outcome names. It is an operator-facing safety model. Its purpose is to prevent optimistic inference when the evidence is missing or ambiguous. A party-level unlock also does not close the case for every TLC. It says something about that party’s unlock path. Pending TLC rows must remain present until their own proof mappings are reconciled.

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 produces Unknown, 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 by node 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:
The scripts use only deterministic local fixtures and Node’s built-in crypto. They do not need a Fiber node, private key, funded wallet, CKB RPC, or broadcast path. Read them in order:
  • 49-force-close-tlc-outcomes.ts separates fulfilled, no-preimage, and unknown outcomes while retaining pending TLCs after a party unlock.
  • 50-exact-tlc-proof-mapping.ts follows 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.ts reconciles actual TLC, channel, payment, invoice, optional CCH, and preimage-store records only from exact tenant/session/proof/hash evidence.
  • 52-idempotent-replay-and-retention.ts uses tenant-scoped exact proof keys, an idempotent tx-observation boundary, same-hash sibling retention, legacy Unknown handling, and a final audit.
Week 13 therefore closes the loop on the settlement boundary: CKB tells us where the force-close proof lives, Fiber supplies the payment-channel context, and the operator application must preserve exact identity and honest uncertainty between them.