Skip to main content

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

The reef-fiber repository shows a real build week:
  • 94779db Build Reef payment diagnostics platform
  • 16f02b5 Separate optional CCH coverage from readiness
  • 8495206 Fix optional coverage expectation
  • 64be5d3 Publish Reef hosted demo
  • 0557e19 Bound persistence write amplification
  • dfabc2b Meet production storage growth budget
  • 41acc1d Rewrite Reef operator README
  • b8e9cb5 rebuild Reef docs and secure local settings
  • 4eef65a Build Reef diagnostics platform and hosted deployment
  • fdb8810 Generate Prisma client during production build
  • 5b3029d docs: polish hosted Reef documentation
Read technically, that arc is about four things:
  • 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_info for node identity and release posture;
  • list_peers for connected peer evidence;
  • list_channels for channel lifecycle, readiness, asset, counterparty, and funding outpoint evidence;
  • list_payments and get_payment for retained payment rows;
  • parse_invoice for invoice amount/payee interpretation when available;
  • build_router for read-authorized candidate route validation;
  • graph_nodes and graph_channels for local routing topology;
  • optional get_cch_order when the connected FNN build exposes CCH state.
Those reads are not interchangeable. A channel row is local node evidence. A graph row is routing topology evidence. A payment row is historical attempt evidence. A parsed invoice is request evidence. A CCH order is cross-chain order evidence. Reef only becomes useful when those objects stay separate long enough to explain what each one proves. That is the technical shift from Week 9 to Week 10. Week 9 said the source boundary must be honest. Week 10 built the object graph that makes that honesty operational.

Payment failure is a route problem, not just a status

A failed Fiber payment can say failed, 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?
The answer can still be low confidence. That is acceptable if the reason is technical. For example, Reef can classify a failed retained attempt as route unavailable when Fiber gives the attempted route and error text, while still saying failed-hop attribution is unknown because the node did not expose it. The distinction matters. Public route shape does not prove private liquidity. A later successful payment does not prove which hop recovered. An attempted route does not automatically prove the failed edge. Reef should preserve those limits instead of smoothing them away.

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 as get_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.
That is a concrete CKB/Fiber bridge. The payment-channel network is not floating above CKB. Its channel readiness story still has a chain evidence path.

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.
If 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_changes for store-change events;
  • Fiber logs for redacted operational timeline rows;
  • public routing data only when local graph evidence is missing.
These sources improve confidence, but they do not replace primary objects. Missing metrics should become a source gap, not invented counters. Missing logs should mean no log timeline, not manufactured events. Public topology can help route context, but it cannot prove private remote liquidity.

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.
That is how Reef can compare success -> failed routed attempt -> recovered success without turning the database into an unbounded log sink.

What to build locally this week

Run the Week 10 exercises from the Reef build-contracts package:
The scripts are dry-run. They do not require a Fiber node, funded wallet, private key, hosted Reef deployment, or credentials. Read them in order:
  • 37-reef-fiber-object-model.ts
  • 38-payment-route-diagnostics.ts
  • 39-ckb-cch-evidence-boundary.ts
  • 40-observation-storage-budget.ts
Together they model the technical Week 10 build:
  • 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.
Week 10 is where the hackathon build stopped being a dashboard concept and became a CKB/Fiber diagnostics system.