Building Reef on Fiber
Week 9 established the rule: every claim needs a source, and every missing source stays visible. Week 10 was spent building against that rule. The important part is not that the project got a new name or a nicer surface. The important part is that Reef became a technical Fiber diagnostic system. It had to read Fiber node state, preserve payment attempts, compare route evidence, check CKB funding transactions, respect optional CCH coverage, and keep enough history to explain what changed between a failed payment and a later recovery. The thesis for the week is:Fiber diagnostics only become useful when payment failure is tied back to channels, routes, peers, CKB funding, and source limits.
That is the Week 10 build lesson.
The commit arc
Thereef-fiber repository shows a real build week:
94779db Build Reef payment diagnostics platform16f02b5 Separate optional CCH coverage from readiness8495206 Fix optional coverage expectation64be5d3 Publish Reef hosted demo0557e19 Bound persistence write amplificationdfabc2b Meet production storage growth budget41acc1d Rewrite Reef operator READMEb8e9cb5 rebuild Reef docs and secure local settings4eef65a Build Reef diagnostics platform and hosted deploymentfdb8810 Generate Prisma client during production build5b3029d docs: polish hosted Reef documentation
- Fiber payment diagnostics became the center.
- CKB funding evidence became part of channel truth.
- CCH was treated as optional capability, not general payment readiness.
- Observation history had to be bounded because diagnostics now retain real node evidence.
Fiber data became the object model
Reef is built around read-only Fiber evidence. The core read path comes from methods such as:node_infofor node identity and release posture;list_peersfor connected peer evidence;list_channelsfor channel lifecycle, readiness, asset, counterparty, and funding outpoint evidence;list_paymentsandget_paymentfor retained payment rows;parse_invoicefor invoice amount/payee interpretation when available;build_routerfor read-authorized candidate route validation;graph_nodesandgraph_channelsfor local routing topology;- optional
get_cch_orderwhen the connected FNN build exposes CCH state.
Payment failure is a route problem, not just a status
A failed Fiber payment can sayfailed, but that is not enough.
Reef has to ask:
- did Fiber retain the payment row?
- did the row include error text?
- did the node expose the attempted route?
- which ordered nodes and channel edges were attempted?
- what receiver amount and fee were expected?
- did the local first hop have a ready channel?
- was the first-hop peer connected?
- did the route asset match the channel asset?
- is the graph fresh enough to trust for route context?
- did Fiber expose a structured failure code or failed-hop attribution?
CKB funding evidence closes the channel loop
Fiber channels ultimately depend on CKB funding transactions. That means a channel diagnostic cannot stop at “ready” or “not ready”. Reef needs to carry the channel outpoint into CKB RPC and ask whether the funding transaction evidence is available. The CKB side uses read-only calls such asget_tip_header for chain health and bounded get_transaction checks for funding outpoints.
This ties the Fiber and CKB layers together:
- Fiber says which channel exists and which funding outpoint it references.
- CKB says whether the referenced transaction can be read from the chain source.
- Reef keeps lookup failures as source status instead of pretending the channel has no funding evidence.
CCH is optional coverage, not generic readiness
The Week 10 CCH commits matter because they prevent a category error. CCH evidence is valuable when the node exposes it, but missing CCH order support should not automatically make every payment diagnostic invalid. Reef separates:- normal Fiber payment readiness;
- CKB channel and funding evidence;
- optional CCH order lookup;
- optional CCH Prometheus/LND tracker evidence.
get_cch_order is unavailable, Reef should report missing CCH capability. It should not turn that into a fake settlement result, and it should not block unrelated Fiber payment readiness unless the environment explicitly requires CCH proof.
That is the same source-backed rule applied to cross-chain state.
Events and metrics are supporting evidence
The main diagnostic path is Fiber RPC plus retained observations, but Week 10 also preserves optional supporting sources:- Prometheus metrics for channel, peer, payment, gossip, and CCH counters;
- WebSocket
subscribe_store_changesfor store-change events; - Fiber logs for redacted operational timeline rows;
- public routing data only when local graph evidence is missing.
Persistence became part of the technical design
Once Reef diagnoses incidents, it needs history. The storage commits are technical, not just operational polish. Retained payment rows, channel snapshots, source statuses, alert lifecycle rows, raw evidence hashes, and incident comparisons can grow quickly if every poll writes everything again. Week 10 therefore had to bound persistence write amplification and meet a production storage growth budget. The technical shape is:- deduplicate observations by content hash;
- keep current raw evidence separate from normalized history;
- preserve enough payment and alert history for incident replay;
- prune retained history transactionally;
- use PostgreSQL so collector and web processes can share durable observations.
What to build locally this week
Run the Week 10 exercises from the Reef build-contracts package:37-reef-fiber-object-model.ts38-payment-route-diagnostics.ts39-ckb-cch-evidence-boundary.ts40-observation-storage-budget.ts
- turn Fiber RPC rows into distinct node, peer, channel, payment, graph, and route objects;
- diagnose a failed payment from attempted route, channel, peer, and graph evidence;
- connect Fiber channel outpoints to CKB funding checks while keeping CCH optional;
- bound retained observation history so real diagnostics can run over time.