The attn-framework follows a deterministic lifecycle sequence. Hooks fire in this order:
graph TD
Start([Start]) --> relay_connect[1. on_relay_connect<br/>Connect to Nostr relay]
relay_connect --> subscription[2. on_subscription<br/>Subscription created/confirmed]
subscription --> receive_events[3. Receive Events<br/>on_marketplace_event<br/>on_billboard_event<br/>on_promotion_event<br/>on_attention_event<br/>on_match_event]
receive_events --> match[4. on_match_published<br/>Publish MATCH event]
match --> confirmations[5. Receive Confirmations<br/>on_billboard_confirmation_event<br/>on_attention_confirmation_event]
confirmations --> final[6. on_marketplace_confirmation_event<br/>Publish final MARKETPLACE_CONFIRMATION]
final --> payment[7. on_attention_payment_confirmation_event<br/>Attention owner confirms payment receipt]
subgraph Block Synchronization
block_before[before_block_event]
block_finalized[on_block_event<br/>New Bitcoin block detected]
block_after[after_block_event]
end
block_before --> block_finalized --> block_after
block_finalized --> receive_events
subgraph Standard Nostr Events
profile[on_profile_event<br/>User profile metadata]
relay_list[on_relay_list_event<br/>User relay preferences]
nip51_list[on_nip51_list_event<br/>Trusted/blocked lists]
end
subscription --> profile
subscription --> relay_list
subscription --> nip51_list
subgraph Error Handling
relay_disconnect[on_relay_disconnect]
end
relay_connect -.->|error| relay_disconnect
Connection and subscription management:
Identity event publishing:
Event reception and processing for the attention marketplace. Each event type has before/on/after lifecycle hooks:
Marketplace Events (kind 38188):
Billboard Events (kind 38288):
Promotion Events (kind 38388):
Attention Events (kind 38488):
Match Events (kind 38888):
Billboard Confirmation Events (kind 38588):
Attention Confirmation Events (kind 38688):
Marketplace Confirmation Events (kind 38788):
Attention Payment Confirmation Events (kind 38988):
Bitcoin block processing and synchronization (via City Protocol):
Standard Nostr protocol events for enhanced functionality. Each event type has before/on/after lifecycle hooks:
Profile Events (kind 0):
Relay List Events (kind 10002):
NIP-51 List Events (kind 30000):
Error handling and health monitoring:
Note: The following hooks are defined in the framework but not currently emitted:
Hooks execute in registration order. For each event type, the execution order is:
before_*_event hook fires (if handlers registered)on_*_event hook firesafter_*_event hook fires (if handlers registered)Implementations register handlers that decide what to do when each hook fires. The framework provides the infrastructure; implementations provide the logic.
Fully Implemented Hooks:
on_relay_connect, on_relay_disconnect, on_subscriptionon_profile_publishedbefore_marketplace_event, on_marketplace_event, after_marketplace_eventbefore_billboard_event, on_billboard_event, after_billboard_eventbefore_promotion_event, on_promotion_event, after_promotion_eventbefore_attention_event, on_attention_event, after_attention_eventbefore_match_event, on_match_event, after_match_event, on_match_publishedbefore_billboard_confirmation_event, on_billboard_confirmation_event, after_billboard_confirmation_eventbefore_attention_confirmation_event, on_attention_confirmation_event, after_attention_confirmation_eventbefore_marketplace_confirmation_event, on_marketplace_confirmation_event, after_marketplace_confirmation_eventbefore_attention_payment_confirmation_event, on_attention_payment_confirmation_event, after_attention_payment_confirmation_eventbefore_block_event, on_block_event, after_block_eventbefore_profile_event, on_profile_event, after_profile_eventbefore_relay_list_event, on_relay_list_event, after_relay_list_eventbefore_nip51_list_event, on_nip51_list_event, after_nip51_list_eventDefined but Not Emitted:
on_rate_limit - Hook registration available but never emittedon_health_change - Hook registration available but never emittedon_block_gap_detected - Hook registration available but detection logic not implemented (see TODO.md for implementation details)