• Didactyl — Nostr Subscriptions
  • Overview
  • Startup Sequence
  • Subscription Categories
    • 1. Admin Context Subscription
    • 2. Self-Skill Subscription
    • 3. DM Subscriptions
    • 4. Trigger Subscriptions
  • Subscription Parameters
  • Subscription Lifecycle
  • Summary Table
  • Related Documentation

§Didactyl — Nostr Subscriptions

§Overview

Didactyl maintains persistent websocket subscriptions to Nostr relays for the lifetime of the process. Subscriptions are opened during startup and are never closed — the relay pool keeps them alive, automatically reconnecting and resubscribing when relays drop.

All subscriptions are created via nostr_relay_pool_subscribe() from nostr_core_lib and are sent to every relay in the configured relay list.

§Startup Sequence

The subscriptions are opened in a specific order during main() startup. The diagram below shows the full sequence:

flowchart TD
    A[nostr_handler_init] --> B[Connect to all relays]
    B --> C[nostr_handler_reconcile_startup_events]
    C --> D[Publish startup events to relays]
    D --> E[trigger_manager_init]
    E --> F[trigger_manager_load_from_startup_events]
    F --> G["Subscribe: Admin Context"]
    G --> H["Subscribe: Self Skills"]
    H --> I[Send startup DM to admin]
    I --> J["Subscribe: DMs"]
    J --> K[Enter main poll loop]
    K --> L["Poll: nostr_handler_poll + trigger_manager_poll + http_api_poll"]

    style F fill:#2a7,stroke:#333,color:#fff
    style G fill:#27a,stroke:#333,color:#fff
    style H fill:#27a,stroke:#333,color:#fff
    style J fill:#27a,stroke:#333,color:#fff

§Subscription Categories

§1. Admin Context Subscription

Function: nostr_handler_subscribe_admin_context() in src/nostr_handler.c When: During startup, before self-skill subscription Condition: Only if admin_context.enabled is true in config

This creates up to two persistent subscriptions for the admin’s pubkey:

§Profile Subscription

Tracks the admin’s profile metadata, contact list (WoT), and relay preferences. Used to build agent context about who the admin is.

§Kind 1 Notes Subscription

Tracks the admin’s recent public notes. Used for agent context and as the event source for triggered skills that watch admin posts.

§2. Self-Skill Subscription

Function: nostr_handler_subscribe_self_skills() in src/nostr_handler.c When: During startup, after admin context subscription

This is the core skill awareness subscription. It serves three purposes:

1. Cache population — Every arriving event is stored in the in-memory self-skill cache via self_skill_cache_upsert_event_locked(), making skills available for LLM tool calls and context building.

2. Live trigger registration — When a kind 31123 or 31124 event arrives with trigger=nostr-subscription and a valid filter tag, register_trigger_from_self_skill_event() immediately calls trigger_manager_add() to create a persistent trigger subscription. This means skills published from any client are automatically activated without restart.

3. Deferred bulk load — After EOSE, the on_self_skill_eose callback fires trigger_manager_load_from_skills() as a one-time bulk scan of the adoption list. This catches any skills that were already cached before the per-event path was wired up.

§3. DM Subscriptions

Function: nostr_handler_subscribe_dms() in src/nostr_handler.c When: During startup, after self-skill subscription and startup DM Required: Yes — startup fails if DM subscription cannot be created

Creates one or two subscriptions depending on the configured DM protocol:

§NIP-04 DM Subscription

§NIP-17 DM Subscription

§4. Trigger Subscriptions

Function: register_trigger_subscription_locked() in src/trigger_manager.c When: Dynamically, whenever a trigger is registered via trigger_manager_add() Created by: nostr_handler_subscribe_with_filter() wrapper

Each active trigger gets its own persistent subscription based on the skill’s filter tag:

When an event matches the filter, maybe_fire_trigger_locked() checks cooldown and dedup, then executes the trigger action (LLM or template).

Trigger subscriptions are created at three points:

• Startup config scan — trigger_manager_load_from_startup_events() parses startup_events[] from config for skills with trigger tags
• Live self-skill event — register_trigger_from_self_skill_event() in the self-skill subscription callback
• EOSE bulk load — trigger_manager_load_from_skills() after self-skill EOSE
• Runtime tool call — skill_create tool with trigger parameters

§Subscription Parameters

All subscriptions share these common pool parameters:

§Subscription Lifecycle

flowchart LR
    INIT["Process Start"] --> CONNECT["Connect Relays"]
    CONNECT --> SUB["Open Subscriptions"]
    SUB --> LIVE["Live Event Stream"]
    LIVE --> |"Relay disconnects"| RECON["Auto-Reconnect"]
    RECON --> |"Relay reconnects"| RESUB["Auto-Resubscribe"]
    RESUB --> LIVE
    LIVE --> |"SIGINT/SIGTERM"| SHUT["Shutdown"]
    SHUT --> CLOSE["Close All + Cleanup"]

Subscriptions are never manually closed during normal operation. The relay pool handles reconnection and resubscription transparently. On shutdown, trigger_manager_cleanup() closes trigger subscriptions and nostr_handler_cleanup() destroys the pool.

§Summary Table

§Related Documentation

• Skills — Skill event format and trigger tags
• Tools — skill_create tool with trigger parameters
• API — trigger_list and trigger_status endpoints