solana-messenger-sdk 1.2.0 → 1.2.1

package/SPEC.md

@@ -0,0 +1,324 @@
+# solana-messenger
+
+Encrypted messaging protocol on Solana. Servers, channels, DMs — fully on-chain, no backend required. Just pubkeys and math.
+
+**Program (mainnet & devnet):** `msg1SxLsvf1ZL374noHwUWcVYjPsNSNwKb3xphg6Lxf`
+
+## Architecture
+
+### Hierarchy
+
+```
+Server (Discord workspace)
+├── Public Channels (visible to all server members)
+├── Private Channels (invite-only, own encryption key)
+└── Server Members (with role + key wraps)
+
+Standalone Channel (group DM, no server)
+├── Channel Members (with key wraps)
+└── Messages
+
+Direct Messages (wallet-to-wallet, permanent)
+```
+
+### Key Registry
+
+Every user registers an encryption public key on-chain:
+
+- **Identity wallet (A):** Signs transactions, pays fees. Can be custodial (Privy/Turnkey).
+- **Encryption keypair (B):** Generated locally, never leaves the agent. Used for encrypt/decrypt.
+- **Registry PDA:** `seeds = ["messenger", A]` stores B's public key + min_fee.
+
+### Encryption Model
+
+**Direct Messages:** NaCl box (X25519-XSalsa20-Poly1305) with Diffie-Hellman shared secret between sender and recipient encryption keys.
+
+**Server/Channel Messages:** NaCl secretbox (XSalsa20-Poly1305) with a shared symmetric key:
+
+- **Public channels** use the **server key** — one key per server version, wrapped once per ServerMember.
+- **Private channels** have their **own key** — independent of server key, wrapped per ChannelMember.
+- **Key rotation** happens on member removal or voluntary leave (forward secrecy).
+- **New members** receive wraps for all historical key versions (Slack-style full history).
+- **Messages** are lightweight: `ciphertext + nonce + key_version`. No per-message key wraps.
+
+### Discovery (Zero Backend)
+
+With just wallet key A + encryption key B, a client can surface everything:
+
+| What | Method |
+|---|---|
+| My servers | `getProgramAccounts` filter `ServerMember.member == me` |
+| My private channels | `getProgramAccounts` filter `ChannelMember.member == me` |
+| Server's public channels | `getProgramAccounts` filter `Channel.server_id == X` |
+| My DMs | `getSignaturesForAddress(myWallet)` on program |
+| Current channel version | Highest `key_wraps.version` in my ChannelMember |
+
+### Payer Separation (Relay Support)
+
+All instructions support a **separate payer** account, enabling relay/gasless architectures where a backend pays transaction costs on behalf of users.
+
+### Fee System
+
+- **Protocol fee:** Global fee per message, set by platform authority. Goes to fee vault.
+- **Recipient fee (min_fee):** Per-recipient fee for DMs, set by each user on their registry.
+
+## On-Chain Program (Anchor/Rust)
+
+### Instructions
+
+#### Platform Config
+
+```rust
+pub fn initialize_config(ctx, fee_vault: Pubkey, protocol_fee: u64)
+pub fn update_config(ctx, fee_vault: Option<Pubkey>, protocol_fee: Option<u64>)
+```
+
+#### Identity
+
+```rust
+pub fn register(ctx, encryption_pubkey: Pubkey)
+pub fn update_encryption_key(ctx, new_key: Pubkey)
+pub fn set_min_fee(ctx, min_fee: u64)
+pub fn deregister(ctx)
+```
+
+#### Direct Messages
+
+```rust
+pub fn send_message(ctx, recipient: Pubkey, ciphertext: Vec<u8>, nonce: [u8; 24])
+```
+
+Fees: protocol fee → vault, recipient min_fee → recipient wallet.
+
+#### Servers
+
+```rust
+// Create server. Creator becomes owner with initial key wrap.
+// remaining_accounts[0] = owner's ServerMember PDA
+pub fn create_server(ctx, server_id: Pubkey, name: [u8; 32],
+    owner_key_wrap: Vec<u8>, owner_key_nonce: [u8; 24])
+
+// Admin/owner invites a member, wrapping server keys for them.
+// remaining_accounts[0] = new member's ServerMember PDA
+pub fn invite_to_server(ctx, new_member: Pubkey,
+    key_wraps: Vec<Vec<u8>>, key_nonces: Vec<[u8; 24]>)
+
+// Remove member + rotate server key.
+// remaining_accounts: [removed ServerMember, ...remaining ServerMember PDAs]
+pub fn remove_server_member(ctx, removed_member: Pubkey,
+    new_key_wraps: Vec<Vec<u8>>, new_key_nonces: Vec<[u8; 24]>)
+
+// Leave voluntarily + rotate server key for remaining members.
+// remaining_accounts: [my ServerMember, ...remaining ServerMember PDAs]
+pub fn leave_server(ctx,
+    new_key_wraps: Vec<Vec<u8>>, new_key_nonces: Vec<[u8; 24]>)
+
+pub fn update_server(ctx, name: [u8; 32])
+
+// Close server + all ServerMembers via remaining_accounts
+pub fn close_server(ctx, member_pubkeys: Vec<Pubkey>)
+```
+
+#### Channels
+
+```rust
+// Create channel (standalone or within a server).
+// For server channels: remaining_accounts[0] = creator's ServerMember PDA (auth)
+// Then ChannelMember PDAs for private channels.
+pub fn create_channel(ctx, channel_id: Pubkey, server_id: Option<Pubkey>,
+    channel_type: u8, members: Vec<Pubkey>,
+    key_wraps: Vec<Vec<u8>>, key_nonces: Vec<[u8; 24]>)
+
+// Send message. key_version = which key version encrypted this message.
+// For public channels: remaining_accounts[0] = sender's ServerMember PDA
+pub fn send_channel_message(ctx, ciphertext: Vec<u8>, nonce: [u8; 24], key_version: u32)
+
+// Add members to private channel with all historical key versions.
+pub fn add_channel_members(ctx, new_members: Vec<Pubkey>,
+    key_wraps: Vec<Vec<Vec<u8>>>, key_nonces: Vec<Vec<[u8; 24]>>)
+
+// Remove members + rotate channel key (creates new Channel PDA at version+1).
+pub fn remove_channel_members(ctx, remove_list: Vec<Pubkey>,
+    new_key_wraps: Vec<Vec<u8>>, new_key_nonces: Vec<[u8; 24]>)
+
+pub fn close_channel(ctx)
+```
+
+### Accounts
+
+```rust
+PlatformConfig    // PDA: ["config"]
+  authority: Pubkey, fee_vault: Pubkey, protocol_fee: u64, updated_at: i64
+
+EncryptionRegistry // PDA: ["messenger", owner]
+  owner: Pubkey, encryption_key: Pubkey, min_fee: u64, created_at: i64, updated_at: i64
+
+Server            // PDA: ["server", server_id]
+  server_id: Pubkey, owner: Pubkey, name: [u8; 32], created_at: i64, updated_at: i64
+
+ServerMember      // PDA: ["server_member", server_id, member]
+  server_id: Pubkey, member: Pubkey, role: u8, key_wraps: Vec<KeyWrap>, joined_at: i64
+
+Channel           // PDA: ["channel", channel_id, version_bytes]
+  channel_id: Pubkey, server_id: Option<Pubkey>, creator: Pubkey,
+  version: u32, channel_type: u8, members: Vec<Pubkey>, created_at: i64, updated_at: i64
+
+ChannelMember     // PDA: ["channel_member", channel_id, member]
+  channel_id: Pubkey, member: Pubkey, key_wraps: Vec<KeyWrap>, joined_at: i64
+
+KeyWrap { version: u32, wrapped_key: Vec<u8>, nonce: [u8; 24] }
+```
+
+### Events
+
+```rust
+MessageSent {
+  sender: Pubkey, recipient: Pubkey,
+  ciphertext: Vec<u8>, nonce: [u8; 24], timestamp: i64
+}
+
+ChannelMessageSent {
+  sender: Pubkey, channel_id: Pubkey,
+  version: u32,        // channel version (PDA version)
+  key_version: u32,    // which key version was used to encrypt
+  ciphertext: Vec<u8>, nonce: [u8; 24], timestamp: i64
+}
+```
+
+### Roles
+
+| Value | Role | Permissions |
+|-------|------|-------------|
+| 0 | Member | Send messages |
+| 1 | Admin | Invite/remove members |
+| 2 | Owner | Full control, cannot be removed |
+
+### Channel Types
+
+| Value | Type | Key Source | Members Vec |
+|-------|------|-----------|-------------|
+| 0 | Private | Own channel key (ChannelMember wraps) | Populated |
+| 1 | Public | Server key (ServerMember wraps) | Empty |
+
+### Errors
+
+| Code | Name | Description |
+|------|------|-------------|
+| 6000 | MessageTooLarge | Ciphertext exceeds 900 bytes |
+| 6001 | EmptyMessage | Ciphertext is empty |
+| 6002 | InvalidFeeVault | Fee vault doesn't match platform config |
+| 6003 | InvalidRecipient | Recipient wallet doesn't match registry owner |
+| 6004 | TooManyMembers | Channel exceeds 256 members |
+| 6005 | EmptyGroup | Must have at least one member |
+| 6006 | CreatorNotInMembers | Creator must be in members list |
+| 6007 | NotGroupMember | Sender is not a member |
+| 6008 | KeyWrapMismatch | Key wraps count doesn't match |
+| 6009 | MemberRecordMismatch | Member record count mismatch |
+| 6010 | InvalidMemberRecord | Invalid member record PDA |
+| 6011 | AlreadyMember | Already a member |
+| 6012 | Unauthorized | Insufficient permissions |
+| 6013 | CannotRemoveOwner | Cannot remove server owner |
+| 6014 | PublicRequiresServer | Public channels require a server |
+| 6015 | PublicNoMembers | Public channels don't use member lists |
+
+### Security Model
+
+- **Public channel sender verification:** `send_channel_message` requires sender's ServerMember PDA for public channels.
+- **Server channel creation:** `create_channel` requires creator's ServerMember PDA when `server_id` is set.
+- **Admin verification:** `remove_server_member` verifies admin's ServerMember PDA via derivation.
+- **Key rotation on removal AND leave:** Both `remove_server_member` and `leave_server` rotate the server key.
+- **Forward secrecy:** After key rotation, removed members cannot decrypt new messages.
+- **Full history access:** New members receive all historical key wraps — past messages are readable.
+- **On-chain immutability:** Messages are permanent events. Protocol cannot enforce retroactive deletion.
+
+## TypeScript SDK (`solana-messenger-sdk`)
+
+Pure `@solana/kit` v2 — no Anchor client-side dependency.
+
+### Setup
+
+```typescript
+import { SolanaMessenger } from "solana-messenger-sdk";
+
+const messenger = new SolanaMessenger({
+  apiKey: process.env.HELIUS_API_KEY!,
+  keypair: keypairBytes,
+});
+
+await messenger.init();
+```
+
+### Direct Messages
+
+```typescript
+await messenger.send(recipientAddress, "Hello!");
+const messages = await messenger.read({ limit: 10 });
+const unsub = await messenger.listen((msg) => console.log(msg.text));
+```
+
+### Servers
+
+```typescript
+// Create server (you become owner)
+const { serverId, serverPda, signature } = await messenger.createServer("My Server");
+
+// Invite member (admin wraps keys for them)
+await messenger.inviteToServer(serverId, memberAddress, [serverKey]);
+
+// Leave server (rotates key for remaining members)
+await messenger.leaveServer(serverId, [remainingMember1, remainingMember2]);
+```
+
+### Channels
+
+```typescript
+// Private channel (standalone group DM)
+const { channelId, channelPda } = await messenger.createChannel({
+  members: [myAddress, friend1, friend2],
+});
+
+// Public channel in a server
+const { channelId: pubId } = await messenger.createChannel({
+  serverId,
+  channelType: ChannelType.Public,
+  members: [],
+});
+
+// Send message
+await messenger.sendChannelMessage({
+  channelPda,
+  message: "Hello team!",
+  channelKey,
+  keyVersion: 0,
+  senderServerMemberPda, // required for public channels
+});
+
+// Add/remove members (creator only)
+await messenger.addChannelMembers(channelPda, channelId, [newMember], [allKeyVersions]);
+const { newChannelPda } = await messenger.removeChannelMembers(
+  channelId, currentVersion, [removedMember], [remainingMembers]
+);
+```
+
+### Identity
+
+```typescript
+await messenger.register(encryptionPubkey);
+await messenger.setMinFee(10000); // lamports to message me
+const encKey = await messenger.lookupEncryptionKey(walletAddress);
+```
+
+## Cost
+
+- **Send DM:** ~5000 lamports tx fee + protocol fee + recipient min_fee
+- **Send channel message:** ~5000 lamports tx fee + protocol fee
+- **Register:** ~0.001 SOL rent
+- **Create server:** ~0.001 SOL rent (Server) + ~0.002 SOL rent (ServerMember)
+- **Create channel:** ~0.06 SOL rent (Channel, max member allocation)
+- **All rent is reclaimable on close.**
+
+## Dependencies
+
+- `@solana/kit` — Solana web3 v2
+- `tweetnacl` — NaCl encryption
+- `helius-sdk` — Helius RPC + enhanced APIs