Spark Program | Fiber Weir — Condition-Gated Payment Streams for Fiber Network
1. Project Overview
- Project name: Fiber Weir
- One-sentence summary: A working implementation of a piece of Fiber Network’s own named roadmap item — “programmable conditional payment” — letting a payment stream continue only while an on-chain-verifiable condition holds true, halting and refunding automatically the instant it doesn’t, instead of relying on a party manually confirming delivery.
- Category: Protocol-level infrastructure / primitive, with a working reference implementation (not a consumer app) — the same category as prior successfully-funded infra work in this program (Cross-Chain Hub extensions, zk-Lock, CKB-VM validation).
2. Team Profile
- Core member: Carl — solo developer, project lead and sole contributor.
- Repo: [github.com/oxdev6/fiber-weir]
- Contact: Discord: carlcn6 · Email: [email protected] · Telegram: carl6 · GitHub: @oxdev6
3. Project Background
Fiber Network’s own repository lists, among its stated roadmap items, “programmable conditional payment” — explicitly covering PTLC, hold-invoice application protocols, on-chain contract conditions, and agent fair exchange. This is not an inferred gap; it is the core team’s own, current, public statement of unfinished work, in the same category of evidence that has already grounded successful projects in this program.
Today, Fiber’s hold-invoice mechanism gates payment release on one thing only: whether the payee can reveal a preimage matching a hash committed at invoice creation. This is a secret-knowledge gate — it proves someone knows a number, not that anything specific actually happened. For a streaming payment — pay-per-API-call, pay-per-compute-cycle, pay-per-second of metered service — this means “was the service actually delivered correctly” is left to manual confirmation, off-chain trust, or ad hoc application logic bolted on top. There is no way, today, for the payment mechanism itself to enforce “only continue paying while this on-chain-verifiable condition holds.”
A related, already-live project, AgentPay, gives AI agents wallets and uses Fiber’s existing hold-invoice mechanism to “lock funds until service delivery is confirmed.” Read precisely, “confirmed” there still means a party or process revealing a preimage once it believes delivery happened — the same secret-knowledge mechanic, wrapped in an agent-friendly SDK. AgentPay does not implement on-chain contract conditions, and does not claim to; it is application-layer plumbing built on top of the existing primitive. This project builds the primitive itself — the thing a future AgentPay, or any other consumption-side Fiber application, could build on top of, rather than another application sitting beside it.
This project is explicitly infrastructure, not an application competing for the same attention as another payment gateway or checkout flow. The program’s own recent public guidance (the August 2026 “What Spark Is Not” post) names a specific complaint: too many Fiber submissions sit on the “value circulation side” — another payment entry point — rather than giving Fiber new underlying capability. This project sits on neither side by itself: it is the missing primitive underneath both, demonstrated with one concrete reference implementation to prove it works, not pitched as a consumer product in its own right.
4. Solution
A conditional TLC (time-locked contract) extension: a payment stream where each installment’s release depends on both the existing preimage check and a matched, verifiable condition observation. If the condition stops matching, or the stream reaches its expiry block without a fresh release, the stream halts and unreleased funds become refundable — no manual dispute, no trusted third party confirming delivery after the fact.
Pre-grant work already completed and unit-tested: the off-chain rules governing this — exactly when a release is valid, when a proof is stale, when refund unlocks, how terminal states lock, how predicate commitments are computed and validated at construction — are implemented as a pure state machine (ConditionalPaymentStream) with twelve enforcement claims individually tested. This is the hardest design work: getting the boundary conditions right (freshness, monotonicity, the exact expiry/refund handoff, overflow safety) before any of it touches real infrastructure.
What this grant funds — the part that turns a tested state machine into an enforced protocol feature: none of the above is enforced anywhere yet. There is no conditional branch in Fiber’s actual on-chain lock script, no verifier that observes real CKB state and feeds it into the state machine, no wire schema carrying conditional payment data between peers, and no feature-bit negotiation so peers can even agree to attempt one. The state machine currently governs nothing but its own unit tests. This grant funds the specific, scoped work of connecting it to reality: the on-chain script enforcement, the live verifier, and the wire integration — plus an honestly-scoped RPC surface, SDK, and demo built on top once that connection exists.
Reference implementation, to prove the connected system concretely: a pay-per-successful-API-response stream, where each response batch is signed and the on-chain predicate verifies that signature before a release is permitted.
Named and deferred, not hidden: watchtower support for conditional streams and full state persistence across node restarts are real, non-trivial pieces of work explicitly out of scope for this grant, tracked as future work rather than assumed safe. Concretely, this means the reference implementation and its testnet demonstration are scoped to a channel that stays open and online for the duration of the demo — force-close-mid-stream safety for conditional payments is a known, currently-unresolved gap, named here rather than glossed over.
5. Technical Approach
Stack: Rust, extending nervosnetwork/fiber’s commitment-lock script (in fiber-scripts/contracts/) and crates/fiber-lib/fiber-types directly; TypeScript SDK and a minimal dashboard frontend. Any CKB-side address/cell handling in the SDK or demo frontend uses CCC (CKBers’ Codebase), the current standard — not Lumos, which the ecosystem has officially deprecated.
Current layered state, precisely:
Layer 5: Demo Frontend — NOT BUILT (basic dashboard scaffold exists, no live data)
Layer 4: Client SDK — NOT BUILT
Layer 3: RPC Extension — NOT BUILT
Layer 2: Wire/Actor Integration — NOT BUILT (no conditional fields in TLC/invoice wire types, no feature bit, no conditional branch in the payment actor)
Layer 1: On-chain Lock Script — NOT BUILT (no conditional branch in commitment-lock; no live verifier connecting real CKB state to the state machine)
Layer 0: Off-chain State Machine — DONE. ConditionalPaymentStream (crates/fiber-types/src/conditional.rs), 12/20 enforcement claims implemented and unit-tested per GROUND_TRUTH.md
Ground-truth discipline, already established and to be maintained throughout: the repo’s GROUND_TRUTH.md distinguishes, claim by claim, what’s actually enforced from what’s merely designed — this project continues that discipline rather than abandoning it once funding starts. Every claim that flips from “not implemented” to “implemented” during the grant gets its enforcement pointer and passing test linked in the same file, and docs/fiber-cond-roadmap.md is kept current as the scoped work proceeds.
The actual technical work this grant funds — the project’s own defined integration boundary, not a paraphrase:
“This repository currently contains Fiber’s TLC/hold-invoice settlement machinery but does not contain the active, modifiable
fiber-scriptscontract work needed to enforce a new arbitrary predicate during force-close. This slice deliberately keeps the contract adapter explicit rather than pretending local Rust validation is on-chain enforcement.”
The remaining integration work, in the project’s own words, and in this order of dependency:
- Add a versioned
CommitmentLockwitness variant carrying the predicate commitment. - Add the conditional fields to the invoice/TLC wire schemas with a compatibility/version bit.
- Implement the CKB verifier adapter and use it before
RemoveTlcFulfill. - Update the watchtower settlement witness and deployed testnet script configuration.
- Add a two-node integration test against the upgraded contract.
Honest scoping of item 4 specifically: items 1, 2, 3, and 5 are the committed scope of this grant — they take the already-tested state machine from “validated in isolation” to “enforced on-chain and exercised end-to-end between two real nodes,” which is the core claim of this proposal. Item 4 (the watchtower settlement witness update) is the one item most likely to exceed a 6-week/$1,000 solo scope on top of the other four, and is treated as a best-effort stretch goal, not a committed deliverable — attempted if items 1–3 and 5 land with time to spare, explicitly deferred to follow-on work otherwise. Either way, the demo and its safety claims are scoped to a channel that remains open for the duration of testing; force-close-mid-stream safety is not claimed unless item 4 is actually completed and demonstrated.
Testnet only, never mainnet, within this grant’s scope — the “deployed testnet script configuration” in item 4 refers strictly to Fiber’s existing testnet deployment, not a new mainnet migration.
Item 6, once 1–3 and 5 are real: expose create_conditional_stream/get_stream_status/cancel_stream over RPC, wrap them in a TypeScript SDK, and build the reference pay-per-API-response demo on top, including its failure path.
Explicitly out of scope, stated upfront, per the project’s own stated boundary for this slice: PTLC cryptography, a general oracle framework beyond signature-verification predicates, and — per the existing scope note in the repo — routing, multi-part payments (MPP), UDTs, and trampoline payments, all intentionally excluded from this first slice.
Highest technical risk, named directly: items 1–3 above are exactly the class of work Fiber’s own team has spent significant effort hardening in the existing (non-conditional) settlement path — adding a new branch to a live lock script and the payment actor without introducing a fund-safety regression is real risk, not a formality. Mitigations carried over from the original design and still binding:
- No edits to the existing
commitment-lockscript or payment actor before a written summary of their current behavior exists (docs/existing-settlement-flow.md). - New logic is additive (a new branch/field), never a modification of existing non-conditional paths, so a bug in the new code cannot regress today’s working hash-lock payments.
- A named adversarial test matrix — stale proof, future-dated proof, expiry-boundary release, refund-before-expiry attempt, duplicate/replayed proof, terminal-state re-entry — extending the unit tests already passing in the state machine to the newly-connected on-chain and wire layers.
- Force-close mid-stream is explicitly not claimed safe in this grant, per the watchtower gap named in Section 4 — the adversarial matrix covers correctness of the state machine and its on-chain enforcement while a channel is open, not the dispute path, which remains future work.
- Devnet-only until the full matrix passes; testnet only for the final demo recording; no mainnet within this grant’s scope.
Explicitly out of scope, stated upfront: PTLC cryptography, a general oracle framework beyond signature-verification predicates, watchtower support for conditional streams, and full state persistence across restarts.
6. To-Do List (6-week plan)
Starting point, precisely: the off-chain state machine (ConditionalPaymentStream) is implemented and unit-tested. The remaining work is the project’s own defined integration boundary — five items, with a sixth (RPC/SDK/demo) once those land.
- Week 1 (done, pre-grant): Off-chain state machine and its unit tests;
GROUND_TRUTH.md,docs/fiber-cond.md,docs/fiber-cond-roadmap.mdestablished as the project’s ongoing honesty discipline. - Week 2: Item 1 — versioned
CommitmentLockwitness variant carrying the predicate commitment, unit-tested in isolation against the script. - Week 3: Item 2 — conditional fields added to invoice/TLC wire schemas with a compatibility/version bit. Item 3 begins — CKB verifier adapter construction. Milestone 1.
- Week 4: Item 3 completed — verifier adapter wired in and used before
RemoveTlcFulfill. Item 5 — two-node integration test against the upgraded contract, run to passing on devnet. Milestone 2. - Week 5: Item 4 attempted as a best-effort stretch goal (watchtower settlement witness + testnet script config update) — committed to follow-on work if it doesn’t land cleanly alongside the rest. Item 6 begins: RPC layer and
fiber-weir-sdk. - Week 6: Reference demo completed (signed API-response provider + dashboard), including the on-camera failure-path demonstration on testnet.
GROUND_TRUTH.mdupdated to reflect final, honest claim status — including item 4’s actual outcome, whichever way it went. Milestone 3.
7. Required Funding & Breakdown
-
Requested amount: $1,000 (standard cap for a single technical project).
-
Structure: 20% upfront on approval, remainder released against three milestones, each independently verifiable without a full code review.
-
Upfront — $200 (20%): released on grant approval.
-
Milestone 1 — Witness variant + wire schema + verifier underway — $300: due end of Week 3. Trigger: item 1 (
CommitmentLockwitness variant) complete and unit-tested; item 2 (wire schema fields + version bit) complete; item 3 (verifier adapter) under active construction. Verification: reviewer runs the provided test command and sees pass/fail output directly. -
Milestone 2 — Verifier live, two-node integration passing — $350: due end of Week 4. Trigger: item 3 complete (verifier used before
RemoveTlcFulfill), item 5 complete (two-node integration test passing on devnet). Verification: reviewer watches the recorded two-node test run;GROUND_TRUTH.md’s diff is visible in commit history, claim by claim. -
Milestone 3 — RPC, SDK, demo, honest final ground truth — $150: due end of Week 6. Trigger: item 6 (RPC/SDK/demo) complete, reference demo recorded (happy path and failure path) on testnet, and
GROUND_TRUTH.md/fiber-cond-roadmap.mdupdated to reflect exactly what shipped — including item 4’s actual, honestly-reported outcome. Verification: reviewer watches the two demo videos and runs the SDK example themselves.
8. Deliverables + How to Verify
Deliverables:
- Public repo (already live:
github.com/oxdev6/fiber-weir), MIT-licensed, withGROUND_TRUTH.mdmaintained claim-by-claim throughout the grant, not just at the start. - Conditional branch added to the real
commitment-lockCKB script, unit-tested. - Live verifier connecting real CKB chain state to the existing, already-tested
ConditionalPaymentStreamstate machine. - Wire schema additions (TLC/invoice conditional fields, feature bit) and the conditional branch in the payment actor.
fiber-weir-sdkTypeScript package with a runnable example.- Reference demo (signed API-response provider + dashboard) demonstrating a live conditional stream on testnet, including a deliberate on-camera failure-path demonstration.
How to verify (no code review required):
- Read
GROUND_TRUTH.md’s diff across the grant period directly — each claim’s status change is tied to a specific commit and test, which is a stronger, more precise verification method than a general code review. - Run the on-chain script’s and state machine’s test suites directly — pass/fail output is self-evident.
- Watch the recorded multi-node adversarial test run for Milestone 2.
- Watch the two demo videos (happy path, failure path) for Milestone 3, and run the SDK example against local nodes.
9. Current State vs. Funded Work
- Current state, precisely: repo live at
github.com/oxdev6/fiber-weir. The off-chain state machine (ConditionalPaymentStream) is implemented and unit-tested — commitment matching, mismatched-observation rejection, expiry-triggered refund, and double-release/double-refund prevention on terminal states are all covered. In the project’s own words: “this slice deliberately keeps the contract adapter explicit rather than pretending local Rust validation is on-chain enforcement.” That is the honest line this proposal stands on. - What’s explicitly not built yet: the five-item integration boundary in Section 5 — no
CommitmentLockwitness variant, no wire schema fields, no live verifier, no watchtower settlement update, no two-node integration test. A node today can exercise the state machine’s logic in isolation; it cannot enforce a conditional payment against a real peer or real chain state. - Funded scope: items 1, 2, 3, and 5 of that integration boundary as committed deliverables, item 4 (watchtower) as a named best-effort stretch goal, and item 6 (RPC/SDK/demo) once the rest is real — all detailed week-by-week in Section 6.
- Explicitly out of scope, named rather than hidden: PTLC cryptography, a general oracle framework beyond signature-verification predicates, routing/MPP/UDTs/trampoline payments (per the project’s own existing scope note), and — unless item 4 is actually completed — force-close-mid-stream safety for conditional payments.
10. CKB / Fiber Alignment
This project does not use Fiber as a convenient payment rail for an unrelated idea — it directly implements a named piece of Fiber’s own roadmap (“programmable conditional payment… on-chain contract conditions”), using CKB’s Turing-complete script model to make the condition itself arbitrary and verifiable, not just a clock or a shared secret. It is infrastructure, not another application competing on the same “circulation side” the program has explicitly said it has enough of — it is the missing layer underneath the next generation of consumption-side Fiber applications (metered APIs, agent-to-agent commerce, pay-per-compute services), proven with one concrete, honestly-scoped reference implementation rather than promised in the abstract.