Skip to content

Conversation

@ben-kaufman
Copy link
Contributor

@ben-kaufman ben-kaufman commented Nov 21, 2025

This PR migrates the tag metadata system from Room database to bitkit-core library's PreActivityMetadata system and improves transfer activity handling throughout the app.

Similar to: synonymdev/bitkit-ios#219 synonymdev/bitkit-ios#226 synonymdev/bitkit-ios#229

Description

Migration from Room TagMetadata to PreActivityMetadata:

  • Removed Room-based tag metadata storage (TagMetadataDao, TagMetadataEntity, and extensions)
  • Created new PreActivityMetadataRepo that interfaces with CoreService.activity for metadata management
  • PreActivityMetadata now stores more information including payment hash, txId, address, receive/transfer flags, fee rate, and channel ID
  • All metadata operations now go through the core library instead of direct database access
  • Database schema updated to version 5

Enhanced Transfer Activity Handling:

  • Improved tracking of transfer activities (channel opens/closes, LSP orders) using isTransfer flag in PreActivityMetadata
  • Updated ActivityRepo to properly handle transfer metadata when syncing activities
  • Enhanced WalletRepo with better pre-activity metadata integration for transfers
  • CoreService now provides activity service methods for metadata management
  • Added transfer-specific UI indicators and improved activity detail display for transfers

Testing Focus Areas:

  1. Tag Management:

    • Add/remove tags to transactions and payments
    • Verify tags persist across app restarts
    • Test tag backup/restore functionality
  2. Transfer Activities:

    • Create channel orders and verify they appear as "Transfer to Spending"
    • Open manual channels and check activity labeling
    • Close channels (cooperative/force) and verify "Transfer to Savings" display
    • Confirm transfer activities show correct metadata in detail view
  3. Activity Detail Screen:

    • View various activity types (onchain, lightning, transfers)
    • Check that all metadata displays correctly
    • Verify transfer-specific UI elements appear for transfer activities

Fixes #322

@ben-kaufman ben-kaufman force-pushed the use-preactivity-metadata branch from f781983 to 9ee1001 Compare November 21, 2025 19:03
@jvsena42
Copy link
Member

Starting review

@jvsena42
Copy link
Member

jvsena42 commented Nov 24, 2025

@ben-kaufman please add this issue to the description if the PR solves it
#322

Copy link
Member

@jvsena42 jvsena42 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested:

  • Install over an old version ✅
  • reset and recover -> should recover tags ❌
tag-not-applyed.webm
  • Close channel -> should display transfer activity ✅
  • Open channel with external node -> should display transfer activity

onChain

onchain-receive.webm
  • Scan qr -> attach tag -> send -> Activity has tags ✅

Lighting

  • Create invoice -> attach tag -> receive payment -> Activity has tags ✅
  • Scan qr -> attach tag -> send -> Activity has tags ✅

@ben-kaufman
Copy link
Contributor Author

ben-kaufman commented Nov 24, 2025

reset and recover -> should recover tags ❌

This actually shouldn't be related to this PR, since changes here are only about pre-activity, but tags in existing activities are saved in the activity itself. I'll check the issue though but maybe better in another PR.

Create invoice -> attach tag -> receive payment ->#322

Hmm this seems to not happen consistently, checking.

@ben-kaufman
Copy link
Contributor Author

@jvsena42 issue with onchain invoice should be fixed now

@synonymdev synonymdev deleted a comment from claude bot Nov 24, 2025
@synonymdev synonymdev deleted a comment from claude bot Nov 24, 2025
@synonymdev synonymdev deleted a comment from claude bot Nov 24, 2025
@synonymdev synonymdev deleted a comment from claude bot Nov 24, 2025
@ben-kaufman
Copy link
Contributor Author

@jvsena42 I opened #479 which fixes the backup and restore issue.

Copy link
Member

@jvsena42 jvsena42 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Retested the two failing points

Copy link
Collaborator

@ovitrif ovitrif left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome work!

Couldn't find any issue neither in code nor in my tests.

My Tests:

  • tag existing sent and received activity for onchain and for LN 🟢
  • tag LN and Onchain during send 🟢
  • add tags to LN and Onchain during receive, then scan with iOS & receive the payments 🟢
  • backup, wipe & restore 🟢
  • transfer to savings activity 🟢
  • check lightning connections list & detail 🟢
  • transfer to spending activity 🟢
  • re-check lightning connections list & detail 🟢
  • backup, wipe & restore: recheck connections, tags, activity 🟢
  • open manual channel ⚫ couldn't test, encountered issues connecting to my LND peer in bitkit-docker 🤷🏻

@claude
Copy link

claude bot commented Nov 24, 2025

Pull Request Review: Tag Metadata Migration to PreActivityMetadata

Overview

This PR successfully migrates tag metadata from Room database to the bitkit-core PreActivityMetadata system and enhances transfer activity handling. The code quality is generally good with comprehensive test coverage (+623 lines of new tests). However, I've identified several issues that should be addressed before merging.

⚠️ Critical Issues

1. Race Condition in Tag Migration (ActivityRepo.kt:327-365)

Location: replaceActivity method

Issue: Tags are migrated but if addTagsToActivity fails, the error is silently ignored:

val tags = coreService.activity.tags(activityIdToDelete)
addTagsToActivity(activityId = id, tags = tags)  // Failure ignored!

markActivityAsRemovedFromMempool(activityIdToDelete).onFailure { e ->
    // ... error handling
}
Result.success(Unit)  // Returns success even if tags failed

Impact: Tags can be silently lost during activity replacements.

Fix: Check the result and handle failures:

addTagsToActivity(activityId = id, tags = tags).onFailure { e ->
    Logger.error("Failed to migrate tags from $activityIdToDelete to $id", e, context = TAG)
    // Consider whether this should fail the entire operation
}

2. N+1 Query Problem in Address Lookup (CoreService.kt:486-495)

Location: findAddressInPreActivityMetadata

Issue: Makes a database query for EACH output in a transaction:

for (output in txDetails.vout) {
    val address = output.scriptpubkey_address ?: continue
    val metadata = coreService.activity.getPreActivityMetadata(
        searchKey = address, 
        searchByAddress = true
    )  // Query per output!
}

Impact: Significant performance degradation for transactions with many outputs.

Fix: Implement batch lookup:

private suspend fun findAddressInPreActivityMetadata(txDetails: TxDetails): String? {
    val addresses = txDetails.vout.mapNotNull { it.scriptpubkey_address }
    if (addresses.isEmpty()) return null
    
    // Add batch query method to core service
    val allMetadata = coreService.activity.getPreActivityMetadataByAddresses(addresses)
    return addresses.firstOrNull { address ->
        allMetadata[address]?.isReceive == true
    }
}

3. Performance Issue in Replacement Transaction Marking (CoreService.kt:661-703)

Location: markReplacementTransactionsAsRemoved

Issue: Fetches ALL onchain activities and iterates through them:

val allActivities = getActivities(
    filter = ActivityFilter.ONCHAIN,
    limit = UInt.MAX_VALUE  // All activities!
)

Impact: Very slow for wallets with many transactions; could cause ANR.

Fix: Add database index on boostTxIds or implement a direct query to find activities where boostTxIds contains the original transaction ID.

🐛 High Priority Bugs

4. Race Condition in Channel State Reads (ActivityRepo.kt:143-183)

Issue: Channel state is read multiple times without synchronization:

// Read 1:
val channels = lightningRepo.lightningState.value.channels

// ... later in findOpenChannelForTransaction ...
// Read 2:
val orders = blocktankRepo.blocktankState.value.orders

// ... later in findClosedChannelForTransaction ...
// Read 3:
val closedChannels = getClosedChannels(SortDirection.DESC).getOrNull()

Impact: If channel state changes between reads, could match wrong channels or miss matches entirely.

Fix: Snapshot all state at the start of findChannelsForPayments.

5. Tag Migration Data Loss (WalletRepo.kt:98-121)

Issue: Tags are read from old payment ID, but old metadata is deleted before confirming new metadata is saved:

val tagsToMigrate = /* ... get from old payment ID ... */
clearBip21State()  // Deletes old metadata here
// ... operations that could fail ...
persistPreActivityMetadata(newPaymentId, tagsToMigrate, newBip21Url)  // Could fail

Impact: Tags lost if any error occurs between clearing and persisting.

Fix: Only delete old metadata after confirming new metadata is successfully saved.

6. Timestamp Edge Case Handling (ActivityRepo.kt:391-394)

Issue: Null timestamp defaults to 0, which always triggers boost:

if ((newOnChainActivity.v1.updatedAt ?: 0u) > pendingBoostActivity.updatedAt) {
    cacheStore.removeActivityFromPendingBoost(pendingBoostActivity)
    return@onSuccess
}

Impact: Activities with null updatedAt will always be boosted.

Fix: Handle null explicitly:

val activityUpdatedAt = newOnChainActivity.v1.updatedAt
if (activityUpdatedAt != null && activityUpdatedAt > pendingBoostActivity.updatedAt) {
    cacheStore.removeActivityFromPendingBoost(pendingBoostActivity)
    return@onSuccess
}

🔒 Security Concerns

7. Input Validation Missing (PreActivityMetadataRepo.kt, WalletRepo.kt)

Issue: Payment IDs and tags accepted without validation.

Risk: Data integrity issues; potential XSS if tags displayed in web views.

Fix: Add validation:

private fun validatePaymentId(id: String): Boolean {
    return id.isNotBlank() && id.length <= 256 && id.matches(Regex("[a-zA-Z0-9]+"))
}

private fun sanitizeTag(tag: String): String {
    return tag.trim()
        .take(50)  // Max length
        .replace(Regex("[^a-zA-Z0-9\\s-_]"), "")
}

8. Sensitive Data in Logs

Issue: Payment hashes, addresses, and amounts logged at INFO/DEBUG level throughout.

Example: CoreService.kt:389, PreActivityMetadataRepo.kt:146

Risk: Privacy exposure if logs are collected/shared.

Fix: Use VERBOSE level for sensitive data; truncate payment hashes: paymentHash.take(8)...

📝 Code Quality Issues

9. Complex Nested Logic (ActivityRepo.kt:143-166)

Issue: findOpenChannelForTransaction has three return paths with similar null returns but different meanings:

channels.firstOrNull { channel -> ... }?.channelId
    ?: run {
        val matchingOrder = orders.firstOrNull { ... } ?: return null
        val orderChannel = matchingOrder.channel ?: return null
        channels.firstOrNull { ... }?.channelId
    }

Recommendation: Extract to named functions and add logging for each path to improve debuggability.

10. Silent Error Swallowing (WalletRepo.kt:132-138)

Issue: Payment hash extraction failures silently return null:

val paymentHash = runCatching {
    when (val decoded = decode(bip21Url)) {
        is Scanner.Lightning -> decoded.invoice.paymentHash.toHex()
        is Scanner.OnChain -> decoded.extractLightningHash()
        else -> null
    }
}.getOrNull()  // Error swallowed

Recommendation: Log failures to help diagnose BIP21 generation issues.

11. Inconsistent Concurrency Strategy (CoreService.kt:382-401)

Issue: Chunks processed sequentially, but payments within chunks processed in parallel:

payments.chunked(CHUNK_SIZE).forEach { chunk ->  // Sequential
    chunk.map { payment ->
        async { ... }  // Parallel
    }.awaitAll()
}

Recommendation: Document why this hybrid approach is needed, or simplify by fully parallelizing if order doesn't matter.

✅ Test Coverage Gaps

Missing Tests:

  1. Concurrent operations: Multiple simultaneous tag additions/removals
  2. Channel matching: Tests with various channel states and edge cases
  3. Tag migration failures: Partial failures (old deleted, new creation fails)
  4. Performance: Large datasets (1000+ activities, 100+ channels)
  5. Integration: End-to-end flows across PreActivityMetadataRepo → ActivityRepo → WalletRepo
  6. Time edge cases: Extreme timestamp values (far future, null timestamps)

🎯 Recommendations

Before Merging:

  1. ✅ Fix tag migration race condition (Android - Project setup #1)
  2. ✅ Implement batch address lookup (POC wake2pay from notification #2)
  3. ✅ Optimize replacement transaction marking (Android - Migrate to ldk-node #3)
  4. ✅ Add input validation (Setup Keychain #7)
  5. ✅ Fix timestamp edge case handling (Migrate channels from LDK to ldk-node #6)

High Priority:

  1. Fix channel matching race conditions (Migrate to ldk-node #4)
  2. Fix tag migration data loss (Android - LDK state & Slashtags metadata #5)
  3. Add proper error logging for silent failures (chore: Merge BT notifications changes from deps/bdk-1.0 to master #10)
  4. Reduce sensitive data in logs (BDK 1.0.0-alpha.11 #8)

Medium Priority:

  1. Refactor complex nested logic (Blocktank Push Notifications #9)
  2. Document concurrency strategy (Business Logic Data Modeling #11)
  3. Add missing test coverage
  4. Consider adding database indexes for boostTxIds

📊 Overall Assessment

Code Quality: ⭐⭐⭐⭐ (4/5) - Well-structured with good separation of concerns

Test Coverage: ⭐⭐⭐⭐ (4/5) - Comprehensive unit tests, needs more integration tests

Performance: ⭐⭐⭐ (3/5) - Several potential bottlenecks identified

Security: ⭐⭐⭐ (3/5) - Needs input validation and privacy improvements

This is a solid architectural improvement that properly migrates to bitkit-core. The critical issues around race conditions and performance should be addressed before merging, but the overall direction is excellent. The test coverage is impressive (+623 lines) and shows careful attention to correctness.

Great work on this migration! Let me know if you'd like me to elaborate on any of these points or if you have questions about the recommended fixes.

@synonymdev synonymdev deleted a comment from claude bot Nov 24, 2025
@ovitrif ovitrif merged commit c93b451 into master Nov 24, 2025
16 of 17 checks passed
@ovitrif ovitrif deleted the use-preactivity-metadata branch November 24, 2025 17:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tag set upfront on the receive BTC invoice is not displayed on incoming transaction

4 participants