Spark Program | CellFlow — Durable CCC Transaction Recovery PoC

DAOs & Funding Spark Program
1

Capture
Capture1906×878 147 KB

Applicant: Dang Ba Ty
Discord: tyforwork
Email: [email protected]
GitHub: tydeptrai21042004 (Dang Ba Ty) · GitHub
Funding requested: $500 USD, payable in equivalent CKB
Duration: 4 weeks
Project type: CKB Developer Infrastructure / Proof of Concept

Project links:

1. Project Overview

CellFlow explores whether a CKB application can safely recover an uncertain transaction after a backend restart and finalize its business operation exactly once, using CCC, PostgreSQL, and independently verifiable CKB chain evidence.

Consider a transaction accepted by a CKB node whose broadcast response is lost. The application cannot safely conclude that the transaction failed. Similarly, receiving a later confirmation is insufficient to prove that every required output Cell assertion has been verified.

CellFlow already implements a recovery and settlement model addressing these failure conditions.

For this Spark proposal, I want to create a small end-to-end CCC reference application demonstrating the model with persistent PostgreSQL state, real CKB Testnet transactions, controlled failure injection, and application-level settlement.

The central question is:

Can another CKB developer integrate CellFlow into a real CCC workflow and recover an uncertain transaction safely, without implementing their own durable transaction-reconciliation system?

The objective is to answer this question through one focused, reproducible experiment rather than expand CellFlow into a larger platform.

2. Applicant Background and Contact

I am Dang Ba Ty, the primary developer of CellFlow, and have been developing CKB-related applications and developer tools through the CKBuilder program.

CellFlow has received technical feedback from CKB community developers, including @alesfer001 and @Xcodes-chain, covering RBF, input conflicts, multiple transaction attempts, settlement assertions, reorg monitoring, and reproducible evidence.

I have incorporated the main architectural corrections into the implementation. The October 28 follow-up review confirmed that the earlier premature-settlement concern had been addressed in the reviewed source paths.

The remaining challenge is demonstrating complete application integration under independently reproducible conditions.

Contact information:

I will be responsible for the CCC integration, PostgreSQL validation, Testnet experiments, documentation, and final report.

3. Problem and Motivation

CCC provides transaction construction and signing, while CKB RPC provides information about transaction and chain state.

However, an application must still decide what to do when a signed transaction has been submitted but its outcome is uncertain.

Consider this scenario:

  1. A user signs a CKB transaction through CCC.

  2. The backend persists the transaction identity and broadcasts it.

  3. The CKB node accepts the transaction.

  4. The successful RPC response is lost.

  5. The application worker restarts.

  6. The application must determine whether the original transaction committed before retrying or finalizing anything.

A second failure can occur after confirmation: the expected output Cell may not yet be verifiable because an RPC query is temporarily unavailable.

Treating either uncertainty as success may cause premature business effects. Treating a lost response as definitive failure can lead to unsafe retries.

These are practical operational problems for applications that integrate CKB transactions with persistent business state.

I developed CellFlow to make these failure boundaries explicit. The next step is to determine whether the resulting integration is practical and reusable for other CKB developers.

4. Proposed Solution

I propose building a minimal reference application demonstrating the complete lifecycle of a real CKB Testnet transaction.

The application will:

  1. Connect a CCC-compatible wallet.

  2. Construct and sign a real CKB Testnet transaction.

  3. Persist the business intent, transaction identity, input references, and signed-payload fingerprint in PostgreSQL before broadcast.

  4. Broadcast the signed transaction through CKB RPC.

  5. Intentionally discard a successful broadcast response in a controlled fault-injection scenario.

  6. Preserve the uncertain submission state.

  7. Restart the application worker and recover the operation from PostgreSQL.

  8. Reconcile the transaction against canonical CKB state.

  9. Verify the configured confirmation policy and expected Cell assertions.

  10. Emit intent.settlement_ready only when all required conditions are satisfied.

  11. Finalize the application’s business operation idempotently, without duplicate execution.

Database Responsibilities

The PoC will demonstrate two logically separate persistence responsibilities using an isolated PostgreSQL instance.

A. CellFlow Operational Database

Stores:

  • business intents and transaction attempts;

  • transaction hashes and input references;

  • submission, chain, and workflow states;

  • reconciliation events and confirmation evidence;

  • expected-Cell assertions;

  • settlement and revocation events;

  • webhook delivery and idempotency records.

B. Reference Application Database

Stores a small application-level business operation that is finalized only after a verified settlement-ready event.

Duplicate events must not apply the same business effect twice.

CKB remains authoritative for transaction confirmation and Cell liveness. PostgreSQL preserves operational history and the application state needed to recover safely across restarts.

5. Technical Architecture

Technology stack:

  • TypeScript / Node.js

  • CKB CCC

  • CKB Testnet JSON-RPC

  • PostgreSQL

  • Existing CellFlow recovery and settlement engine

  • Next.js reference interface

Proposed Workflow

flowchart TD
    A["Connect CCC wallet"] --> B["Build and sign Testnet transaction"]
    B --> C["Persist intent and signed attempt"]
    C --> D[("PostgreSQL: CellFlow operational state")]
    D --> E["Broadcast through CKB RPC"]
    E --> F["Inject lost RPC response"]
    F --> G["SUBMISSION_UNKNOWN"]
    G --> H["Restart backend worker"]
    H --> I["Recover persisted intent"]
    I --> J["Reconcile canonical CKB state"]
    J --> K{"Confirmation policy and required Cell assertions pass?"}
    K -->|No| L["Remain unsettled and retry observation"]
    L --> J
    K -->|Yes| M["intent.settlement_ready"]
    M --> N["Finalize business effect idempotently"]
    N --> O[("PostgreSQL: application business state")]

Core Safety Properties

  • Wallet signing remains outside CellFlow; private keys are never stored by the service.

  • Backend API credentials are not exposed to the browser.

  • A lost broadcast response does not trigger an automatic blind rebroadcast.

  • A pending or unavailable required Cell assertion prevents settlement readiness.

  • Repeated callbacks or retries cannot finalize the same business operation twice.

  • Confirmation depth is treated as a policy, not an absolute finality guarantee.

  • Fault injection is labeled separately from observed CKB network events.

The PoC will reuse CellFlow’s existing recovery engine instead of introducing a second transaction state machine.

6. Current State vs. Funded Work

Already Implemented

The existing CellFlow repository includes:

  • durable transaction intents and multiple transaction attempts;

  • PostgreSQL schema, migrations, and persistence repositories;

  • CCC preparation and tracking utilities;

  • lost-response and RBF recovery logic;

  • expected-Cell verification;

  • settlement-ready and settlement-revoked events;

  • webhook delivery infrastructure;

  • automated regression tests;

  • author-reported real Testnet recovery and RBF experiments;

  • a hosted operator interface and separate interactive simulation.

These features form the existing technical foundation and are not being requested for retroactive funding.

New Work Proposed for Spark

The funding will support combining and validating these components in a new, independently usable reference integration.

The specific new contribution is:

  1. A minimal CCC reference application using the real CellFlow API.

  2. Reproducible PostgreSQL setup covering both operational and application state.

  3. A complete CKB Testnet recovery exercise including lost-response injection and worker restart.

  4. Database-backed verification that business finalization occurs exactly once.

  5. A reproducible evidence package tied to the tested source revision.

  6. External developer feedback on integration difficulty and usefulness.

The goal is to validate integration usability and operational correctness, not expand the existing backend feature set.

7. Execution Plan and Milestones

Total duration: 4 weeks

Milestone Timeline Deliverable
M1 — CCC and PostgreSQL Integration Week 1 Working CCC reference application with durable database records
M2 — Testnet Recovery and Settlement Weeks 2–3 Real Testnet transaction recovery, backend restart, and idempotent finalization
M3 — Independent Validation Week 4 Reproducible evidence, documentation, demo, and developer feedback

M1 — CCC and PostgreSQL Integration

Week 1

  • Provide reproducible PostgreSQL setup and migrations.

  • Integrate a minimal CCC transaction workflow.

  • Connect the reference application to CellFlow without exposing backend credentials.

  • Persist transaction identity before broadcast.

  • Verify that intent and attempt records survive a process restart.

Acceptance criteria:

A reviewer can start the reference application with an isolated database, prepare a signed transaction, and verify that the transaction identity is durably recorded before broadcast.

M2 — Real Testnet Recovery and Settlement

Weeks 2–3

  • Broadcast a real CKB Testnet transaction.

  • Intentionally discard the successful RPC response.

  • Persist SUBMISSION_UNKNOWN.

  • Terminate and restart the reconciliation worker.

  • Recover the original operation from PostgreSQL.

  • Observe canonical confirmation and verify expected Cell assertions.

  • Demonstrate that a pending required assertion does not permit settlement.

  • Emit intent.settlement_ready when all required conditions are satisfied.

  • Verify that the application business effect occurs only once despite repeated event delivery.

Acceptance criteria:

The application recovers the transaction without depending on the original worker’s memory, and finalizes the business operation only after verified settlement readiness.

M3 — Independent Developer Validation

Week 4

  • Finalize the CCC integration guide.

  • Publish exact installation and reproduction commands.

  • Publish Testnet transaction hashes and redacted evidence.

  • Prepare a demo showing success and failure scenarios.

  • Invite at least one external CKB developer to reproduce or evaluate the example.

  • Publish the validation results and final report.

Acceptance criteria:

A reviewer can independently inspect the evidence and execute the documented verification tests. External developer feedback, including unsuccessful attempts or difficulties, will be reported transparently.

8. Funding Breakdown

Total funding requested: $500 USD equivalent in CKB.

Work Package Budget
CCC reference application and integration $175
Reproducible PostgreSQL setup and restart-safe persistence $125
Real Testnet recovery, fault injection, and settlement validation $150
Documentation, demo, and external developer testing $50
Total $500

The funding is intended to support one focused development and validation experiment over four weeks.

Previous CellFlow development, existing PostgreSQL repositories, and already completed recovery functionality are excluded from the requested funding.

I will use existing open-source software and CKB Testnet resources where possible to minimize additional infrastructure expenses.

A public summary of actual fund usage will be provided at completion.

9. Expected Deliverables and How to Verify

Expected Deliverables

Deliverable Acceptance Criteria
CCC reference integration A wallet-signed Testnet transaction can be tracked by CellFlow
PostgreSQL persistence Intent and transaction attempt remain available after worker restart
Lost-response recovery An accepted transaction with a discarded RPC response is recovered without blind rebroadcast
Settlement verification Finalization occurs only after confirmation and required Cell assertions
Application idempotency Duplicate settlement delivery causes no duplicate business effect
Evidence package Public Testnet transactions, source revision, observations, and reproduction commands
Documentation and demo A reviewer can understand and reproduce the flow

How to Verify

From a clean checkout, a reviewer will be able to:

  1. Install pinned dependencies.

  2. Start an isolated PostgreSQL instance.

  3. Apply the database migrations.

  4. Run database integration tests.

  5. Execute deterministic fault-injection and worker-restart tests.

  6. Inspect the published real Testnet transaction evidence.

  7. Optionally repeat the live workflow using a funded CKB Testnet wallet.

The existing repository includes relevant commands such as:

npm run migrate
npm run test:db-integration
npm run evidence:db-restart
npm run validate:testnet-live

The final PoC will provide a documented verification entry point and the configuration needed to run these commands correctly.

Database tests must actually execute against PostgreSQL. A skipped test suite will not count as a successful validation.

Required Observable Results

Scenario Expected Result
CCC transaction prepared Intent and transaction identity persisted
Successful broadcast response discarded SUBMISSION_UNKNOWN
Worker restarted Original operation recovered
Canonical confirmation observed Confirmation evidence persisted
Required Cell assertion still PENDING No settlement_ready
Required assertions VERIFIED One settlement-ready transition
Duplicate business event received One business-state update
Required RPC information unavailable Settlement remains undecided
Source and deployment reviewed Evidence matches the tested source revision

Evidence Package

The final release will contain:

  • exact Git commit and deployment version;

  • network/genesis identity;

  • full public Testnet transaction hashes where safe;

  • timestamped CKB RPC observations;

  • canonical block and confirmation evidence;

  • expected/live-Cell verification results;

  • fault-injection details;

  • redacted PostgreSQL operation and event records;

  • database integration test results;

  • reproducibility instructions and checksums.

Local database and fault-injection tests will be available without real financial expenditure. Repeating the live Testnet experiment will require Testnet CKB and RPC connectivity.

10. CKB Ecosystem Value and Differentiation

CellFlow focuses on a specific operational boundary in CKB applications.

CCC handles transaction construction and wallet signing. CKB RPC provides transaction and chain observations. However, an application still needs to preserve and reconcile its business operation when the transaction submission result is uncertain.

CellFlow addresses this gap by keeping durable transaction attempts, canonical-chain observations, expected-Cell assertions, and settlement readiness separate.

The PoC will use real CKB-specific primitives, including:

  • transaction hashes;

  • input OutPoints;

  • canonical block information;

  • confirmation policies;

  • expected output Cells;

  • current Cell liveness.

It is not intended to replace CCC, a wallet, a CKB indexer, or a general-purpose acceptance testing framework.

The experiment will determine whether the recovery boundary can become a small reusable integration pattern for CKB developers.

A useful result may be a working integration, a simpler API design, or evidence that the abstraction needs improvement. The findings will be shared publicly.

11. Risks and Mitigation

Risk Mitigation
PostgreSQL environment is difficult to reproduce Provide pinned setup, migrations, and isolated database tests
Testnet RPC is temporarily unavailable Preserve real chain evidence and separate deterministic fault-injection tests
Backend restart causes duplicate callbacks Enforce event-ID deduplication and application-level idempotency
CCC integration overlaps existing code Fund the end-to-end reference application, not existing helpers
Reviewers cannot repeat live Testnet transactions Supply read-only evidence and reproducible local tests
Limited external developer participation Record actual outreach and feedback without claiming unverified adoption
Scope expands beyond four weeks Maintain one CCC transaction workflow and defer unrelated features

Out of Scope

This Spark phase will not include:

  • Mainnet production launch;

  • new CKB smart contracts;

  • large-scale hosted-service deployment;

  • a general CKB testing framework;

  • additional wallet integrations;

  • guaranteed protection against all future chain reorganizations;

  • commercial rollout.

The focus remains a single reproducible CCC transaction recovery experiment.

12. Open Source and Reporting

The reference application, relevant implementation changes, tests, documentation, and evidence format will be publicly available in the CellFlow GitHub repository under a clearly stated open-source license.

I will publish weekly progress updates in this Nervos Talk thread and participate in the Spark Committee’s review process.

At completion, I will provide:

  • planned vs. completed deliverables;

  • exact source revision;

  • Testnet transaction and database evidence;

  • integration and reproduction instructions;

  • developer feedback;

  • funding-usage breakdown;

  • technical limitations and lessons learned.

Final Objective

Demonstrate with reproducible evidence that a real CCC transaction can recover from an uncertain broadcast after a PostgreSQL-backed worker restart, and that a CKB application finalizes its business operation only after CellFlow verifies settlement readiness.

This is intended to be a small, practical experiment built on an existing technical foundation, with clear value for CKB developers.

Thank you for considering the proposal. I welcome feedback on the integration boundary, experimental scope, and verification approach.

3 Likes
2

it looks helpful to deploy.

1 Like
3

Thanks you very much !!!