Update Payment Status After On-Chain Settlement

[doitian]

Problem Statement

When Watchtower settles TLCs:

• The Watchtower detects TLC statuses and preimages from on-chain settlement transactions.
• It stores this information in its local store.
• However, the payment status in the Fiber node’s main store is not updated.
• As a result, the CCH (Cross-Chain Hub) does not receive a preimage notification.
• The CCH continues to wait for the preimage to settle the incoming payment—even though the outgoing payment has already been settled—leading to asset loss.

Current Architecture

Components

1. Fiber Node Store: Main database storing payment sessions, preimages, and payment status

   • Emits StoreChange events when preimages are inserted
   • CCH's CchFiberStoreWatcher subscribes to these events

2. Watchtower Store: Separate database for watchtower-specific data

   • Stores channel monitoring data
   • Stores settled TLC (update_tlc_settled) and preimages (insert_watch_preimage())
   • Does not trigger events in Fiber node's main store

3. Watchtower Actor: Monitors channels and settles TLCs on-chain

   • Periodically checks for commitment transactions
   • Discovers preimages from settlement transaction witnesses
   • Calls find_preimages() which stores TLC statuses and preimages in watchtower store

4. CCH Component: Manages cross-chain orders

   • Listens to StoreChange::PutPreimage events from Fiber store
   • Updates order state machine when preimages are received
   • Requires preimage to complete orders

Quick Workaround

A temporary workaround exists where CCH can also watch watchtower preimage store events. However, this requires:

• Watchtower to be started alongside Fiber node
• CCH to subscribe to watchtower store events

[doitian]

Proposed Solutions

Solution 1: Fiber Node Queries Watchtower Actor

Recommended

Approach: Fiber node periodically queries the watchtower actor (locally or via RPC) to check whether TLCs are settled on-chain.

Pros:

• Clean separation of concerns
• Works with both local and remote watchtower
• Watchtower remains independent
• No changes to watchtower's core functionality
• Reuse existing data flows that Fiber node sends pending TLC sets to watchtower via RPC

Cons:

• Requires periodic polling (latency)

Implementation Details:

1. Add RPC method to query TLC settled status and TLC preimages.
2. Periodic sync TLC status when TLC is about to expire.

Solution 2: Always Start Core Watchtower

Approach: Always start a lightweight "core watchtower" component within Fiber node to monitor settled TLCs, even when a standalone watchtower service is also running.

Architecture:

Fiber Node
  ├── Core Watchtower (always running)
  │     └── Monitors and notify TLC on-chain settlements
  └── Standalone Watchtower (optional)
        └── Can reuse core watchtower code
        └── Full watchtower functionality

Pros:

• Less dpendency on the standalong watchtower

Cons:

• Still depends on CKB RPC to poll the status.
• Duplicate monitoring if standalone watchtower also running

Solution 3: Watchtower Pushes Status to Fiber Node

Approach: Watchtower actively pushes TLC settlement status (including preimages) back to Fiber node when discoveries are made.

Pros:

• Real-time updates (no polling)
• Watchtower controls when to notify
• Works with remote watchtower services

Cons:

• It breaks the assumption that when standlone watchtower is deployed, the fiber node is not always online.
• It adds bi-direct dependencies between fiber and watchtower.