archy/core/archipelago/src/swarm/seed_advert.rs

//! Phase 3 discovery — signed Nostr "seed advertisement" events.
//!
//! A node that holds a PUBLIC release / app-image blob (addressed by BLAKE3)
//! announces "I can seed hash H from iroh endpoint E" as a signed, NIP-33
//! addressable Nostr event. **Scope is releases/catalog content ONLY** — never
//! private user blobs (decided 2026-06-16): smallest privacy surface, covers
//! the OTA + app-install use-cases. Discovery queries these events to find
//! swarm seeds for a hash; the iroh provider then dials those endpoints.
//!
//! Event shape (NIP-33 addressable, kind [`ARCHIPELAGO_SEED_KIND`]):
//!   - `d` tag = blake3 hex of the content → one current advert per (author, hash)
//!   - content = `{"v":1,"endpoint_id":"<iroh endpoint id>"}`
//!   - author pubkey = the node's seed-derived Nostr identity (signs the event)
//!
//! Endpoint ids stay opaque strings here so this protocol layer builds/parses/
//! publishes/queries WITHOUT the heavy iroh dep; only the `iroh-swarm`
//! discovery glue parses the string into an `iroh::EndpointId`.

// The publish/query path that calls these lives behind `iroh-swarm` (it needs
// the node's iroh EndpointId), so in the default build they're exercised only
// by unit tests — allow them to stand without a production caller.
#![allow(dead_code)]

use nostr_sdk::{Event, EventBuilder, Filter, Kind, Tag};
use serde::{Deserialize, Serialize};

/// NIP-33 addressable kind for Archipelago seed advertisements.
/// Distinct from the node-discovery app-data kind (30078).
pub const ARCHIPELAGO_SEED_KIND: u16 = 30081;

#[derive(Debug, Clone, Serialize, Deserialize)]
struct AdvertContent {
    v: u8,
    endpoint_id: String,
}

/// Build the (unsigned) advertisement event for `blake3_hex` served from
/// `endpoint_id`. Sign with the node's Nostr key (`.sign_with_keys()` /
/// `.sign()`) or publish via `client.send_event_builder()`.
pub fn advertisement_builder(blake3_hex: &str, endpoint_id: &str) -> EventBuilder {
    let content = serde_json::to_string(&AdvertContent {
        v: 1,
        endpoint_id: endpoint_id.to_string(),
    })
    .expect("serialize advert content");
    EventBuilder::new(Kind::Custom(ARCHIPELAGO_SEED_KIND), content)
        .tag(Tag::identifier(blake3_hex.to_string()))
}

/// Filter matching all current seed advertisements for `blake3_hex` (one per
/// advertising node; NIP-33 latest-replaces per author).
pub fn advertisement_filter(blake3_hex: &str) -> Filter {
    Filter::new()
        .kind(Kind::Custom(ARCHIPELAGO_SEED_KIND))
        .identifier(blake3_hex.to_string())
}

/// Extract the advertised endpoint id from an event, or `None` if it is the
/// wrong kind or malformed.
pub fn parse_endpoint_id(event: &Event) -> Option<String> {
    if event.kind != Kind::Custom(ARCHIPELAGO_SEED_KIND) {
        return None;
    }
    serde_json::from_str::<AdvertContent>(&event.content)
        .ok()
        .map(|c| c.endpoint_id)
        .filter(|s| !s.is_empty())
}

/// Collect the unique advertised endpoint ids across a set of events, skipping
/// malformed ones. Order-preserving, de-duplicated.
pub fn endpoint_ids_from_events<'a>(events: impl IntoIterator<Item = &'a Event>) -> Vec<String> {
    let mut seen = std::collections::HashSet::new();
    let mut out = Vec::new();
    for ev in events {
        if let Some(id) = parse_endpoint_id(ev) {
            if seen.insert(id.clone()) {
                out.push(id);
            }
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use nostr_sdk::Keys;

    #[test]
    fn build_sign_parse_roundtrip() {
        let keys = Keys::generate();
        let hash = "a".repeat(64);
        let endpoint = "node-example-endpoint-id";
        let event = advertisement_builder(&hash, endpoint)
            .sign_with_keys(&keys)
            .unwrap();
        assert_eq!(event.kind, Kind::Custom(ARCHIPELAGO_SEED_KIND));
        assert_eq!(parse_endpoint_id(&event).as_deref(), Some(endpoint));
    }

    #[test]
    fn filter_targets_the_hash_dtag_and_kind() {
        let hash = "b".repeat(64);
        let json = serde_json::to_string(&advertisement_filter(&hash)).unwrap();
        assert!(json.contains(&hash), "filter must target the hash d-tag");
        assert!(json.contains("30081"), "filter must constrain the seed kind");
    }

    #[test]
    fn parse_rejects_wrong_kind_and_empty_endpoint() {
        let keys = Keys::generate();
        let wrong_kind = EventBuilder::new(Kind::Custom(1), "{}")
            .sign_with_keys(&keys)
            .unwrap();
        assert_eq!(parse_endpoint_id(&wrong_kind), None);
        let empty_endpoint = advertisement_builder(&"c".repeat(64), "")
            .sign_with_keys(&keys)
            .unwrap();
        assert_eq!(parse_endpoint_id(&empty_endpoint), None);
    }

    #[test]
    fn dedups_endpoint_ids_across_events() {
        let a = Keys::generate();
        let b = Keys::generate();
        let hash = "d".repeat(64);
        let e1 = advertisement_builder(&hash, "endpoint-A").sign_with_keys(&a).unwrap();
        let e2 = advertisement_builder(&hash, "endpoint-A").sign_with_keys(&b).unwrap();
        let e3 = advertisement_builder(&hash, "endpoint-B").sign_with_keys(&b).unwrap();
        let ids = endpoint_ids_from_events([&e1, &e2, &e3]);
        assert_eq!(ids, vec!["endpoint-A".to_string(), "endpoint-B".to_string()]);
    }
}