contextvm_sdk/core/
constants.rs

1//! ContextVM protocol constants
2//!
3//! Event kinds and tag names matching the ContextVM specification.
4//! See: <https://contextvm.org>
5
6/// ContextVM messages (ephemeral events, kind 25910)
7pub const CTXVM_MESSAGES_KIND: u16 = 25910;
8
9/// Encrypted messages using NIP-59 Gift Wrap (kind 1059)
10pub const GIFT_WRAP_KIND: u16 = 1059;
11
12/// Ephemeral variant of NIP-59 Gift Wrap (kind 21059, CEP-19)
13///
14/// Same structure and semantics as kind 1059, but in NIP-01's ephemeral range.
15/// Relays are not expected to store ephemeral events beyond transient forwarding.
16pub const EPHEMERAL_GIFT_WRAP_KIND: u16 = 21059;
17
18/// Replaceable relay list metadata event following NIP-65 (CEP-17)
19pub const RELAY_LIST_METADATA_KIND: u16 = 10002;
20
21/// Server announcement (addressable, kind 11316)
22pub const SERVER_ANNOUNCEMENT_KIND: u16 = 11316;
23
24/// Tools list (addressable, kind 11317)
25pub const TOOLS_LIST_KIND: u16 = 11317;
26
27/// Resources list (addressable, kind 11318)
28pub const RESOURCES_LIST_KIND: u16 = 11318;
29
30/// Resource templates list (addressable, kind 11319)
31pub const RESOURCETEMPLATES_LIST_KIND: u16 = 11319;
32
33/// Prompts list (addressable, kind 11320)
34pub const PROMPTS_LIST_KIND: u16 = 11320;
35
36/// Nostr tag constants
37pub mod tags {
38    /// Public key tag
39    pub const PUBKEY: &str = "p";
40
41    /// Relay URL tag (CEP-17)
42    pub const RELAY: &str = "r";
43
44    /// Event ID tag for correlation
45    pub const EVENT_ID: &str = "e";
46
47    /// Capability tag for pricing metadata
48    pub const CAPABILITY: &str = "cap";
49
50    /// Name tag for server announcements
51    pub const NAME: &str = "name";
52
53    /// Website tag for server announcements
54    pub const WEBSITE: &str = "website";
55
56    /// Picture tag for server announcements
57    pub const PICTURE: &str = "picture";
58
59    /// About tag for server announcements
60    pub const ABOUT: &str = "about";
61
62    /// Support encryption tag
63    pub const SUPPORT_ENCRYPTION: &str = "support_encryption";
64
65    /// Support ephemeral gift wrap kind (21059) for encrypted messages (CEP-19)
66    pub const SUPPORT_ENCRYPTION_EPHEMERAL: &str = "support_encryption_ephemeral";
67
68    /// Support CEP-22 oversized payload transfer via notifications/progress framing
69    pub const SUPPORT_OVERSIZED_TRANSFER: &str = "support_oversized_transfer";
70
71    /// Support CEP-41 open-ended streaming via notifications/progress framing
72    pub const SUPPORT_OPEN_STREAM: &str = "support_open_stream";
73}
74
75/// Maximum message size (1MB)
76pub const MAX_MESSAGE_SIZE: usize = 1024 * 1024;
77
78/// Default LRU cache size for deduplication
79pub const DEFAULT_LRU_SIZE: usize = 5000;
80
81/// Default timeout for network/relay operations (30 seconds)
82pub const DEFAULT_TIMEOUT_MS: u64 = 30_000;
83
84/// Default relay targets for discoverability publication (CEP-17).
85///
86/// These are used as additional publication targets for server metadata,
87/// even when they are not part of the server's operational relay list.
88pub const DEFAULT_BOOTSTRAP_RELAY_URLS: &[&str] = &[
89    "wss://relay.damus.io",
90    "wss://relay.primal.net",
91    "wss://nos.lol",
92    "wss://relay.snort.social/",
93    "wss://nostr.mom/",
94    "wss://nostr.oxtr.dev/",
95];
96
97/// MCP protocol method for the initialization request
98pub const INITIALIZE_METHOD: &str = "initialize";
99
100/// MCP protocol method for the initialized notification
101pub const NOTIFICATIONS_INITIALIZED_METHOD: &str = "notifications/initialized";
102
103/// Sentinel request ID for the announcement auto-publish flow.
104///
105/// Synthetic initialize and capability-list requests use this ID so the
106/// worker routes responses to the announcement handler rather than the
107/// normal client response path.
108pub const ANNOUNCEMENT_REQUEST_ID: &str = "announcement";
109
110/// Kinds that should never be encrypted (public announcements)
111pub const UNENCRYPTED_KINDS: &[u16] = &[
112    SERVER_ANNOUNCEMENT_KIND,
113    TOOLS_LIST_KIND,
114    RESOURCES_LIST_KIND,
115    RESOURCETEMPLATES_LIST_KIND,
116    PROMPTS_LIST_KIND,
117];
118
119/// Return the latest MCP protocol version string
120#[cfg(feature = "rmcp")]
121pub fn mcp_protocol_version() -> &'static str {
122    use std::sync::OnceLock;
123    static VERSION: OnceLock<String> = OnceLock::new();
124    VERSION
125        .get_or_init(|| rmcp::model::ProtocolVersion::LATEST.to_string())
126        .as_str()
127}
128
129/// Return the latest MCP protocol version string
130#[cfg(not(feature = "rmcp"))]
131pub const fn mcp_protocol_version() -> &'static str {
132    "2025-11-25"
133}
134
135// Compile-time range checks (NIP-01 kind ranges).
136// Placed at module level so violations are caught in every build, not just `cargo test`.
137const _: () = {
138    // Ephemeral events: 20000 <= kind < 30000
139    assert!(EPHEMERAL_GIFT_WRAP_KIND >= 20000);
140    assert!(EPHEMERAL_GIFT_WRAP_KIND < 30000);
141    assert!(CTXVM_MESSAGES_KIND >= 20000);
142    assert!(CTXVM_MESSAGES_KIND < 30000);
143    // Replaceable events: 10000 <= kind < 20000
144    assert!(RELAY_LIST_METADATA_KIND >= 10000);
145    assert!(RELAY_LIST_METADATA_KIND < 20000);
146};
147
148#[cfg(test)]
149mod tests {
150    use super::*;
151
152    #[test]
153    fn test_event_kind_values_match_spec() {
154        assert_eq!(CTXVM_MESSAGES_KIND, 25910);
155        assert_eq!(GIFT_WRAP_KIND, 1059);
156        assert_eq!(EPHEMERAL_GIFT_WRAP_KIND, 21059);
157        assert_eq!(RELAY_LIST_METADATA_KIND, 10002);
158        assert_eq!(SERVER_ANNOUNCEMENT_KIND, 11316);
159        assert_eq!(TOOLS_LIST_KIND, 11317);
160        assert_eq!(RESOURCES_LIST_KIND, 11318);
161        assert_eq!(RESOURCETEMPLATES_LIST_KIND, 11319);
162        assert_eq!(PROMPTS_LIST_KIND, 11320);
163    }
164
165    #[test]
166    fn test_tag_values_match_ts_sdk() {
167        assert_eq!(tags::PUBKEY, "p");
168        assert_eq!(tags::RELAY, "r");
169        assert_eq!(tags::EVENT_ID, "e");
170        assert_eq!(tags::CAPABILITY, "cap");
171        assert_eq!(tags::NAME, "name");
172        assert_eq!(tags::WEBSITE, "website");
173        assert_eq!(tags::PICTURE, "picture");
174        assert_eq!(tags::ABOUT, "about");
175        assert_eq!(tags::SUPPORT_ENCRYPTION, "support_encryption");
176        assert_eq!(
177            tags::SUPPORT_ENCRYPTION_EPHEMERAL,
178            "support_encryption_ephemeral"
179        );
180        assert_eq!(
181            tags::SUPPORT_OVERSIZED_TRANSFER,
182            "support_oversized_transfer"
183        );
184    }
185
186    #[test]
187    fn test_announcement_kinds_in_addressable_range() {
188        // NIP-01: addressable events are 30000 <= kind < 40000
189        // However, the spec uses 11316-11320 which are in the replaceable range.
190        // These are parameterized replaceable events per the ContextVM spec.
191        for &kind in UNENCRYPTED_KINDS {
192            assert!(kind >= 11316);
193            assert!(kind <= 11320);
194        }
195    }
196
197    #[test]
198    fn test_bootstrap_relays_are_wss() {
199        for url in DEFAULT_BOOTSTRAP_RELAY_URLS {
200            assert!(
201                url.starts_with("wss://"),
202                "Bootstrap relay must use wss: {url}"
203            );
204        }
205    }
206
207    #[test]
208    fn test_bootstrap_relays_nonempty() {
209        assert!(
210            !DEFAULT_BOOTSTRAP_RELAY_URLS.is_empty(),
211            "Must have at least one bootstrap relay"
212        );
213    }
214
215    #[test]
216    fn test_mcp_method_constants() {
217        assert_eq!(INITIALIZE_METHOD, "initialize");
218        assert_eq!(
219            NOTIFICATIONS_INITIALIZED_METHOD,
220            "notifications/initialized"
221        );
222    }
223
224    #[test]
225    fn test_announcement_request_id() {
226        assert_eq!(ANNOUNCEMENT_REQUEST_ID, "announcement");
227        // Must differ from the stateless synthetic sentinel used by the worker
228        assert_ne!(ANNOUNCEMENT_REQUEST_ID, "contextvm-stateless-init");
229    }
230
231    #[test]
232    fn test_unencrypted_kinds_contains_all_announcements() {
233        assert!(UNENCRYPTED_KINDS.contains(&SERVER_ANNOUNCEMENT_KIND));
234        assert!(UNENCRYPTED_KINDS.contains(&TOOLS_LIST_KIND));
235        assert!(UNENCRYPTED_KINDS.contains(&RESOURCES_LIST_KIND));
236        assert!(UNENCRYPTED_KINDS.contains(&RESOURCETEMPLATES_LIST_KIND));
237        assert!(UNENCRYPTED_KINDS.contains(&PROMPTS_LIST_KIND));
238    }
239
240    #[test]
241    fn test_gift_wrap_not_in_unencrypted() {
242        assert!(!UNENCRYPTED_KINDS.contains(&GIFT_WRAP_KIND));
243        assert!(!UNENCRYPTED_KINDS.contains(&EPHEMERAL_GIFT_WRAP_KIND));
244    }
245}
contextvm_sdk/core/constants.rs

contextvm_sdk/core/
constants.rs
