Skip to main content

Protocol & API Reference

1. JetStream Streams & KV Buckets​

ResourceTypeStorage / RetentionPurpose
ROGUE_CHATStreamFileStorage, 30d / 100k msgs / 512 MiBPublic channels (rogue.chat.*.msg, rogue.chat.*.delete)
ROGUE_GATEDStreamFileStorage, 30d / 100k msgs / 512 MiBGated channels (rogue.gated.*.msg, rogue.gated.*.delete)
ROGUE_DMStreamFileStorage, 30d / 512 MiBEncrypted E2EE DMs (rogue.dm.<0x>)
ROGUE_CHANNELSKVFileStorageChannel metadata (ChannelMeta JSON)
ROGUE_PRESENCEKVMemoryStorage, 30s TTLActive user presence (active_room, level)
ROGUE_PROFILESKVFileStorageCompressed secp256k1 pubkeys & miner_level
ROGUE_BANSKVFileStoragePermanent bans by lowercase 0x
ROGUE_MUTESKVFileStorage, up to 24h TTLGlobal or per-room mutes

2. Subject Namespace​

  • rogue.auth.nonce — Guest Request/Reply to obtain a single-use 60s challenge.
  • rogue.in.<0x>.chat.<room> — Client/agent ingress for room messages.
  • rogue.in.<0x>.dm.<dest0x> — Client/agent ingress for E2EE DMs.
  • rogue.in.<0x>.cmd.<action> — Ingress RPC commands (rooms, create_room, delete_room, topic, delete_msg, mute, unmute, ban, unban, stats).
  • rogue.chat.<room>.msg / rogue.gated.<room>.msg — Validated v=1 message envelopes.
  • rogue.err.<0x> — Structured Gatekeeper rejection events.

3. ECIES Wire Format (DMs)​

Both Go (rogue-nats) and Rust (rogue-desktop-client) implement the exact same scheme:

  1. Ephemeral secp256k1 keypair (ephem_sk, ephem_pk).
  2. Raw ECDH X-coordinate (32 bytes).
  3. HKDF-SHA256(salt=nil, ikm=shared_x, info="rogue-dm-ecies-v1") → 32-byte AES-256 key.
  4. AES-256-GCM encryption with a random 12-byte nonce.

4. Gatekeeper Error Codes​

CodeMeaning
ERR_BAD_REQUESTMalformed JSON, invalid 0x address, or invalid room name (^[a-z0-9-]{2,32}$)
ERR_BANNEDAddress is permanently banned
ERR_MUTEDAddress is temporarily muted globally or in the target room
ERR_RATE_LIMITPer-address message or room-creation rate limit exceeded
ERR_ROOM_NOT_FOUNDTarget room does not exist
ERR_ROOM_EXISTSRoom name is already taken
ERR_ROOM_LIMITAccount reached maximum 3 active user-created rooms
ERR_FORBIDDENInsufficient MinerLevel, non-admin in #announcements, or not room owner
ERR_INSUFFICIENT_BALANCEMature balance (latest & lookbackBlocks) below threshold
ERR_LINK_RESTRICTEDLinks require >= 10 ROGUE or MinerLevel >= 1 (https:// only)
ERR_INVALID_CONTENTEmpty text, > 2000 chars, or forbidden control/ANSI bytes
ERR_RECIPIENT_PUBKEY_UNKNOWNRecipient has never connected to register their secp256k1 pubkey
ERR_RPC_UNAVAILABLEConfigured Rogue Signal JSON-RPC endpoint failed