Feature: Transparent Event Broadcasting Feedback (Complete UI Mode)

[nrobi144]

Problem

Currently, reactions (likes, boosts, zaps, bookmarks) use a fire-and-forget model with optimistic UI updates. Users have no visibility into:

• Whether their event was actually delivered to relays
• Which relays accepted/rejected the event
• Why a relay might have rejected it (AUTH_REQUIRED, rate-limited, etc.)

This creates a "happy path heuristic" where the UI always shows success, even when events fail to propagate.

Proposed Solution

Add transparent broadcasting feedback when FeatureSetType.COMPLETE is enabled:

1. Global Progress Banner (Above Bottom Nav)

┌─────────────────────────────────────────────┐
│                  Feed Content               │
├─────────────────────────────────────────────┤
│ 🔄 Broadcasting Boost (kind 6)      [2/5]  │  ← Compact banner
│ ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │  ← Determinate progress
├─────────────────────────────────────────────┤
│           [Bottom Navigation]               │
└─────────────────────────────────────────────┘

• Shows event type and kind number
• Live progress as relays respond (animated transitions)
• Collapses when multiple events in-flight: "Broadcasting 3 events... [5/15]"

2. Result Snackbar

Success (partial or full):

┌─────────────────────────────────────────────┐
│ ✓ Boost sent to 4/5 relays          [View] │
└─────────────────────────────────────────────┘

Failure (0 relays):

┌─────────────────────────────────────────────┐
│ ✗ Boost failed - 0/5 relays        [Retry] │
└─────────────────────────────────────────────┘

• If 0/5 succeed: don't mark action as complete (button stays unpressed)
• Tappable action opens detail sheet

3. Broadcast Details BottomSheet

┌─────────────────────────────────────────────┐
│  ──────  Broadcast Results                  │
├─────────────────────────────────────────────┤
│  Boost (kind 6) • 4/5 relays                │
├─────────────────────────────────────────────┤
│  ✓ relay.damus.io                           │
│  ✓ nos.lol                                  │
│  ✓ relay.nostr.band                         │
│  ✓ purplepag.es                             │
│  ✗ relay.snort.social    [AUTH_REQUIRED] ↻ │
├─────────────────────────────────────────────┤
│            [Dismiss]  [Retry Failed]        │
└─────────────────────────────────────────────┘

• Shows each relay with status (animated state transitions)
• Error code/message for failures
• Optional: Retry individual relays or all failed
• Optional: Undo/Delete action (sends kind 5 deletion)

---

Technical Implementation

Existing Infrastructure (No Changes Needed)

Component	Location	Purpose
OkMessage	quartz/.../relay/commands/toClient/OkMessage.kt	NIP-20 OK response parsing
RelayInsertConfirmationCollector	quartz/.../relay/client/accessories/	Tracks relay confirmations
sendAndWaitForResponse()	quartz/.../NostrClientSendAndWaitExt.kt	15s timeout, waits for all relays
DeletionEvent	quartz/.../nip09Deletions/DeletionEvent.kt	Kind 5 delete events

New Components

1. BroadcastTracker (State Management)

// Location: amethyst/src/main/java/com/vitorpamplona/amethyst/service/broadcast/

data class BroadcastEvent(
    val id: String,                              // Tracking ID
    val eventId: HexKey,                         // Nostr event ID
    val eventName: String,                       // "Boost", "Reaction", "Bookmark"
    val kind: Int,
    val targetRelays: List<NormalizedRelayUrl>,
    val results: Map<NormalizedRelayUrl, RelayResult> = emptyMap(),
    val status: BroadcastStatus = BroadcastStatus.IN_PROGRESS,
    val startedAt: Long = System.currentTimeMillis()
)

sealed class RelayResult {
    object Success : RelayResult()
    data class Error(val code: String, val message: String?) : RelayResult()
    object Timeout : RelayResult()
}

enum class BroadcastStatus { IN_PROGRESS, SUCCESS, PARTIAL, FAILED }

class BroadcastTracker {
    private val _activeBroadcasts = MutableStateFlow<List<BroadcastEvent>>(emptyList())
    val activeBroadcasts: StateFlow<List<BroadcastEvent>> = _activeBroadcasts.asStateFlow()
    
    private val _completedBroadcast = MutableSharedFlow<BroadcastEvent>()
    val completedBroadcast: SharedFlow<BroadcastEvent> = _completedBroadcast
    
    suspend fun trackBroadcast(
        event: Event,
        eventName: String,
        relays: Set<NormalizedRelayUrl>,
        client: INostrClient
    ): BroadcastResult
    
    fun getDetails(trackingId: String): BroadcastEvent?
    suspend fun retry(trackingId: String, relay: NormalizedRelayUrl? = null)
    fun dismiss(trackingId: String)
}

2. UI Components

Component	File	Description
BroadcastBanner	ui/broadcast/BroadcastBanner.kt	Floating progress indicator
BroadcastSnackbar	ui/broadcast/BroadcastSnackbar.kt	Result notification
BroadcastDetailsSheet	ui/broadcast/BroadcastDetailsSheet.kt	Modal bottom sheet with relay list
RelayResultRow	ui/broadcast/RelayResultRow.kt	Single relay status row

---

Scope

In Scope

• Reactions (kind 7)
• Boosts/Reposts (kind 6)
• Zaps (kind 9735 request)
• Bookmarks (kind 30001)
• Progress indicator with live animated updates
• Result snackbar with tap-to-expand
• Relay status detail sheet
• Retry failed relays
• Only when FeatureSetType.COMPLETE
• 15s timeout for relay responses

Optional (Nice to Have)

• Undo/Delete action (kind 5)
• Persist broadcast history across sessions

Out of Scope

• SIMPLIFIED and PERFORMANCE UI modes (keep fire-and-forget)
• Desktop app (separate implementation later)
• NWC zap response tracking changes

---

Implementation Phases

Phase 1: Core Infrastructure

1. Create BroadcastTracker class
2. Create BroadcastEvent and RelayResult data classes
3. Add to AccountViewModel

Phase 2: UI Components

4. Create BroadcastBanner composable (with animations)
5. Create BroadcastSnackbar composable
6. Create BroadcastDetailsSheet composable

Phase 3: Integration

7. Modify Account publish methods to support tracked mode
8. Wire banner into MainScaffold
9. Add FeatureSetType.COMPLETE gates

Phase 4: Polish

10. Add retry functionality
11. Handle edge cases (offline, rapid actions)
12. Optional: Add delete/undo support

---

References

• NIP-20: Command Results - OK message format
• NIP-09: Event Deletion - Delete events
• Existing code: NostrClientSendAndWaitExt.kt, RelayInsertConfirmationCollector.kt

[nrobi144]

Implementation Progress

Phase 1: Core Infrastructure ✅ COMPLETE

Commit: 3ac8ba669 on branch feat/1682-transparent-broadcast-feedback

Files created:

• amethyst/src/main/java/com/vitorpamplona/amethyst/service/broadcast/BroadcastModels.kt
• amethyst/src/main/java/com/vitorpamplona/amethyst/service/broadcast/BroadcastTracker.kt
• amethyst/src/main/java/com/vitorpamplona/amethyst/ui/broadcast/BroadcastBanner.kt
• amethyst/src/main/java/com/vitorpamplona/amethyst/ui/broadcast/BroadcastSnackbar.kt
• amethyst/src/main/java/com/vitorpamplona/amethyst/ui/broadcast/BroadcastDetailsSheet.kt

Phase 2: Integration 🚧 IN PROGRESS

Completed:

• Added BroadcastTracker to AccountViewModel (line 174)
• Added imports for broadcast classes

Next Steps:

1. Add helper method to Account.kt that creates boost/reaction events without sending (currently boost() creates AND sends in one step)
2. Add boostTracked() method that returns Pair<Event, Set<NormalizedRelayUrl>> for tracked sending
3. Similar pattern for reactTo() - need reactToTracked()
4. Wire BroadcastBanner into MainScaffold above bottom nav
5. Wire BroadcastSnackbarHost to snackbar slot
6. Add FeatureSetType.COMPLETE gate to conditionally use tracked vs fire-and-forget

Key Findings

Existing infrastructure we're building on:

• sendAndWaitForResponse() in NostrClientSendAndWaitExt.kt - 15s timeout, collects OK messages
• OkMessage - NIP-20 response parsing with success flag and error message
• computeMyReactionToNote() - computes relay set for reactions

Current send pattern in Account.kt:

suspend fun boost(note: Note) {
    RepostAction.repost(note, signer)?.let { event ->
        client.send(event, computeMyReactionToNote(note, event))  // fire-and-forget
        cache.justConsumeMyOwnEvent(event)
    }
}

Needed pattern for tracked broadcasting:

// In Account.kt - create event without sending
suspend fun createBoostEvent(note: Note): Pair<Event, Set<NormalizedRelayUrl>>? {
    return RepostAction.repost(note, signer)?.let { event ->
        event to computeMyReactionToNote(note, event)
    }
}

// In AccountViewModel - decide tracked vs fire-and-forget
fun boostTracked(note: Note) = launchSigner {
    if (settings.featureSet == FeatureSetType.COMPLETE) {
        account.createBoostEvent(note)?.let { (event, relays) ->
            val result = broadcastTracker.trackBroadcast(event, "Boost", relays, account.client)
            if (result.isSuccess) {
                account.cache.justConsumeMyOwnEvent(event)
            }
        }
    } else {
        account.boost(note)  // existing fire-and-forget
    }
}

Branch Status

Branch: feat/1682-transparent-broadcast-feedback
Based on: upstream/main (8bbeb9aad)
Commits: 1 (Phase 1 infrastructure)

To continue: git checkout feat/1682-transparent-broadcast-feedback

[nrobi144]

Implementation Status Update

Phase 1 & 2: Core Infrastructure + UI Components ✅ COMPLETE

New Files Created:

File	Purpose
service/broadcast/BroadcastModels.kt	BroadcastEvent, RelayResult, BroadcastStatus data classes
service/broadcast/BroadcastTracker.kt	State management with StateFlow/SharedFlow, 15s timeout, OK message parsing
ui/broadcast/BroadcastBanner.kt	Animated progress indicator above bottom nav
ui/broadcast/BroadcastSnackbar.kt	Result notifications with View/Retry actions
ui/broadcast/BroadcastDetailsSheet.kt	Modal bottom sheet with per-relay status
ui/broadcast/DisplayBroadcastProgress.kt	Wiring component for AppNavigation

Phase 3: Integration ✅ COMPLETE

Modified Files:

File	Changes
Account.kt	Added event creation methods: createBoostEvent(), createReactionEvent(), createAddBookmarkEvent(), createRemoveBookmarkEvent() + consume methods
AccountViewModel.kt	Modified boost(), reactToOrDelete(), addPrivateBookmark(), addPublicBookmark(), removePrivateBookmark(), removePublicBookmark() to use tracked broadcasting when FeatureSetType.COMPLETE
AppNavigation.kt	Added DisplayBroadcastProgress(accountViewModel)

Tracked Actions Summary

Action	Tracked	Notes
Boost (kind 6)	✅	Full tracking with progress
Reaction (kind 7)	✅	Excludes NIP-17 private groups (too complex)
Add Bookmark (kind 30001)	✅	Private and public
Remove Bookmark	✅	Private and public
Zap	❌	Pending - involves Lightning complexity

Key Implementation Details

1. Feature Gate: All tracked broadcasting only activates when settings.isCompleteUIMode() returns true
2. Success Criteria: Event only consumed to local cache if result.isSuccess (at least 1 relay succeeded)
3. Timeout: Uses existing 15s timeout pattern
4. NIP-20 Parsing: Handles OK message success/error codes

Remaining Work

• Implement retry functionality (stubs exist in DisplayBroadcastProgress)
• Add Zap tracking (optional - more complex due to LN flow)
• Testing on device

Branch

feat/1682-transparent-broadcast-feedback

---

Auto-generated progress update