solana-messenger-sdk 1.2.0 → 1.3.0

package/GUIDE.md

@@ -0,0 +1,628 @@
+# Integration Guide — Building on Solana Messenger
+
+This guide walks you through every operation the protocol supports, with code examples and explanations of when and why you'd use each one.
+
+**Program:** `msg1SxLsvf1ZL374noHwUWcVYjPsNSNwKb3xphg6Lxf` (mainnet & devnet)
+
+## Table of Contents
+
+1. [Setup](#setup)
+2. [Identity & Registration](#identity--registration)
+3. [Direct Messages](#direct-messages)
+4. [Servers](#servers)
+5. [Channels](#channels)
+6. [Discovery](#discovery)
+7. [Key Management](#key-management)
+8. [Account Deserialization](#account-deserialization)
+9. [Common Patterns](#common-patterns)
+10. [Architecture Reference](#architecture-reference)
+
+---
+
+## Setup
+
+```typescript
+import { SolanaMessenger, ChannelType } from "solana-messenger-sdk";
+import { readFileSync } from "fs";
+
+// Option 1: Self-custody (you have a keypair file)
+const keypair = new Uint8Array(JSON.parse(readFileSync("~/.config/solana/id.json", "utf-8")));
+const messenger = new SolanaMessenger({
+  apiKey: "YOUR_HELIUS_API_KEY",
+  network: "mainnet", // or "devnet"
+  keypair,
+});
+
+// Option 2: Custodial wallet (Privy, Turnkey, etc.)
+const messenger = new SolanaMessenger({
+  apiKey: "YOUR_HELIUS_API_KEY",
+  walletAddress: "YourCustodialWalletAddress",
+  signer: async (unsignedTx, recentBlockhash, feePayer) => {
+    return await yourCustodialProvider.signTransaction(unsignedTx);
+  },
+});
+
+// Always call init() first — generates encryption key, registers on-chain
+const { encryptionAddress, status } = await messenger.init();
+// status: "registered" | "already_registered" | "updated"
+```
+
+**Why two keys?** Your wallet key (A) signs transactions and can be custodial. Your encryption key (B) is generated locally and never leaves your machine. This means Privy/Turnkey can sign transactions for you but can never read your messages.
+
+---
+
+## Identity & Registration
+
+Every user needs an on-chain encryption key registry before they can send or receive messages.
+
+### Register (automatic via init)
+
+```typescript
+await messenger.init(); // handles registration automatically
+```
+
+`init()` does three things:
+1. Generates a local encryption keypair (stored at `~/.solana-messenger/keys/<address>.json`)
+2. Registers the public key on-chain at PDA `["messenger", walletAddress]`
+3. Loads platform config (fee vault, protocol fee)
+
+### Set spam fee
+
+**When:** You want senders to pay you a fee to send DMs (spam deterrent).
+
+```typescript
+await messenger.setMinFee(10000); // 10,000 lamports (~$0.001) per DM to you
+```
+
+Senders automatically pay this fee when calling `send()`. It goes directly to your wallet.
+
+### Look up someone's encryption key
+
+**When:** You want to verify someone is registered, or you're building custom encryption.
+
+```typescript
+const encKey = await messenger.lookupEncryptionKey("SomeWalletAddress");
+if (!encKey) console.log("User not registered — can't message them");
+```
+
+### Deregister
+
+**When:** You're done with the protocol and want to reclaim rent (~0.001 SOL).
+
+```typescript
+await messenger.deregister();
+```
+
+⚠️ After deregistering, nobody can send you messages until you re-register.
+
+---
+
+## Direct Messages
+
+Wallet-to-wallet encrypted messages. Permanent, protocol-level, nobody can revoke them.
+
+### Send a DM
+
+```typescript
+const signatures = await messenger.send("RecipientAddress", "Hey, what's up?");
+// Returns array of tx signatures (multiple if message was chunked)
+```
+
+The SDK:
+1. Looks up recipient's encryption key from the registry
+2. Performs X25519 Diffie-Hellman key exchange
+3. Encrypts with NaCl box (XSalsa20-Poly1305)
+4. Auto-chunks messages > 661 bytes
+5. Pays protocol fee + recipient min_fee automatically
+
+### Read DMs
+
+```typescript
+const messages = await messenger.read({ limit: 20, since: 1710000000 });
+for (const msg of messages) {
+  console.log(`[${new Date(msg.timestamp * 1000).toISOString()}] ${msg.sender}: ${msg.text}`);
+}
+```
+
+### Listen for DMs in real-time
+
+```typescript
+const unsubscribe = await messenger.listen((msg) => {
+  console.log(`New DM from ${msg.sender}: ${msg.text}`);
+});
+
+// Later: stop listening
+unsubscribe();
+```
+
+Uses WebSocket subscription — ~400ms latency.
+
+---
+
+## Servers
+
+Servers are workspaces (like Discord servers or Slack workspaces). They contain channels and members with roles.
+
+### Create a server
+
+**When:** You want to create a workspace for a team, community, or organization.
+
+```typescript
+const { serverId, serverPda, signature } = await messenger.createServer("My Team");
+```
+
+What happens:
+1. Generates a random server ID (keypair pubkey)
+2. Creates Server PDA at `["server", serverId]`
+3. Creates your ServerMember PDA at `["server_member", serverId, yourWallet]` with role=Owner
+4. Generates the first server encryption key (version 0) and wraps it for you
+
+You're now the **Owner** — full control over the server.
+
+### Invite a member
+
+**When:** You want to add someone to your server. You must be Admin or Owner.
+
+```typescript
+// You need to know the current server keys to wrap them for the new member
+const myMember = await messenger.getServerMember(serverId);
+// Unwrap your server keys first
+const serverKeys = myMember.keyWraps.map(kw => {
+  const key = messenger.unwrapKey(kw.wrappedKey, kw.nonce, adminEncryptionPubkey);
+  if (!key) throw new Error("Failed to unwrap key");
+  return key;
+});
+
+await messenger.inviteToServer(serverId, "NewMemberWallet", serverKeys);
+```
+
+What happens:
+1. Verifies you're Admin/Owner (checks your ServerMember PDA)
+2. Creates a ServerMember for the new member
+3. Wraps ALL historical server key versions for them (so they can read full history)
+4. New member gets role=Member
+
+### Remove a member
+
+**When:** Someone needs to be kicked. Admin/Owner only. **Rotates the server key** so the removed member can't read future messages.
+
+```typescript
+// Get current member list
+const members = await messenger.getServerMembers(serverId);
+const remaining = members
+  .filter(m => m.account.member !== "RemovedMemberWallet")
+  .map(m => m.account.member);
+
+await messenger.removeServerMember(serverId, "RemovedMemberWallet", remaining);
+```
+
+What happens:
+1. Closes the removed member's ServerMember PDA (reclaims rent)
+2. Generates a new server key (version N+1)
+3. Wraps the new key for all remaining members
+4. Removed member still has old keys cached locally (can read old messages) but can't decrypt anything new
+
+### Leave a server
+
+**When:** You want to leave voluntarily. Also rotates the key (forward secrecy).
+
+```typescript
+const members = await messenger.getServerMembers(serverId);
+const remaining = members
+  .filter(m => m.account.member !== myAddress)
+  .map(m => m.account.member);
+
+await messenger.leaveServer(serverId, remaining);
+```
+
+⚠️ The server **owner** cannot leave — transfer ownership first (not yet in SDK, use low-level builders).
+
+### Update server name
+
+```typescript
+await messenger.updateServer(serverId, "New Server Name");
+```
+
+### Close a server
+
+**When:** You're done with the server entirely. Owner only. Reclaims all rent.
+
+```typescript
+const members = await messenger.getServerMembers(serverId);
+const memberAddresses = members.map(m => m.account.member);
+await messenger.closeServer(serverId, memberAddresses);
+```
+
+---
+
+## Channels
+
+Channels are where messages are sent. Two types:
+
+| Type | Key Source | Members | Use Case |
+|------|-----------|---------|----------|
+| **Public** | Server key | All server members | #general, #announcements |
+| **Private** | Own channel key | Invite-only | DM groups, private discussions |
+
+Channels can be **server channels** (belong to a server) or **standalone** (group DMs without a server).
+
+### Create a public channel (in a server)
+
+**When:** You want a channel visible to all server members. Messages encrypted with the server key.
+
+```typescript
+const { channelId, channelPda } = await messenger.createChannel({
+  serverId: serverId,
+  channelType: ChannelType.Public,
+  members: [], // public channels don't need a member list
+});
+```
+
+### Create a private channel (in a server)
+
+**When:** You want an invite-only channel within a server. Has its own encryption key.
+
+```typescript
+const { channelId, channelPda } = await messenger.createChannel({
+  serverId: serverId,
+  channelType: ChannelType.Private,
+  members: [myAddress, member1, member2],
+});
+```
+
+### Create a standalone group DM (no server)
+
+**When:** You want a group chat without the overhead of a full server.
+
+```typescript
+const { channelId, channelPda } = await messenger.createChannel({
+  members: [myAddress, friend1, friend2], // you must be in the list
+});
+```
+
+### Send a message to a channel
+
+**When:** Sending to any channel (public or private).
+
+```typescript
+// For PUBLIC channels: use the server key
+const myServerMember = await messenger.getServerMember(serverId);
+const serverKey = messenger.unwrapKey(
+  myServerMember.keyWraps[keyVersion].wrappedKey,
+  myServerMember.keyWraps[keyVersion].nonce,
+  wrapperEncryptionPubkey,
+);
+const senderServerMemberPda = await deriveServerMemberPda(serverId, myAddress, programId);
+
+await messenger.sendChannelMessage({
+  channelPda,
+  message: "Hello everyone!",
+  channelKey: serverKey,
+  keyVersion: myServerMember.keyWraps.length - 1, // latest version
+  senderServerMemberPda, // REQUIRED for public channels
+});
+
+// For PRIVATE channels: use the channel key
+const myChannelMember = await messenger.getChannelMember(channelId);
+const channelKey = messenger.unwrapKey(
+  myChannelMember.keyWraps[0].wrappedKey,
+  myChannelMember.keyWraps[0].nonce,
+  wrapperEncryptionPubkey,
+);
+
+await messenger.sendChannelMessage({
+  channelPda,
+  message: "Private discussion",
+  channelKey: channelKey,
+  keyVersion: 0,
+  // no senderServerMemberPda needed for private channels
+});
+```
+
+**Key difference:** Public channels require `senderServerMemberPda` — the program verifies you're a server member before accepting the message.
+
+### Read channel messages
+
+```typescript
+const messages = await messenger.readChannelMessages(channelId, channelKey, {
+  limit: 50,
+  since: 1710000000, // unix timestamp
+});
+
+for (const msg of messages) {
+  console.log(`[${msg.sender}] ${msg.text} (key v${msg.keyVersion})`);
+}
+```
+
+### Listen for channel messages in real-time
+
+```typescript
+const unsubscribe = await messenger.listenChannel(channelPda, channelKey, (msg) => {
+  console.log(`${msg.sender}: ${msg.text}`);
+});
+```
+
+### Add members to a private channel
+
+**When:** Inviting new people to an existing private channel. Creator only.
+
+```typescript
+// New members get ALL historical key versions (Slack-style full history)
+await messenger.addChannelMembers(channelPda, channelId, ["NewMember"], [allChannelKeys]);
+```
+
+### Remove members from a private channel
+
+**When:** Kicking someone. Rotates the channel key. Creator only.
+
+```typescript
+const { newChannelPda } = await messenger.removeChannelMembers(
+  channelId,
+  currentVersion,     // current channel version (from channel account)
+  ["RemovedMember"],  // who to remove
+  ["Remaining1", "Remaining2"], // who stays
+);
+// ⚠️ Channel PDA changes! Old PDA is closed, new one at version+1
+```
+
+### Close a channel
+
+```typescript
+await messenger.closeChannel(channelPda, channelId, memberAddresses);
+```
+
+---
+
+## Discovery
+
+**The key promise:** With just your wallet key + encryption key, you can discover everything you're part of — no backend needed.
+
+### Find all my servers
+
+```typescript
+const servers = await messenger.getMyServers();
+for (const { server, account } of servers) {
+  const roleName = ["Member", "Admin", "Owner"][account.role];
+  console.log(`${server.name} — ${roleName} (joined ${new Date(account.joinedAt * 1000).toISOString()})`);
+}
+```
+
+### Find all my private channels
+
+```typescript
+const channels = await messenger.getMyChannels();
+for (const { channel, account } of channels) {
+  if (channel) {
+    const type = channel.channelType === 0 ? "Private" : "Public";
+    console.log(`Channel ${channel.channelId} (${type}, ${channel.members.length} members)`);
+  }
+}
+```
+
+### Find all channels in a server
+
+```typescript
+const channels = await messenger.getServerChannels(serverId);
+for (const { account } of channels) {
+  const type = account.channelType === 0 ? "Private" : "Public";
+  console.log(`${account.channelId} — ${type}, v${account.version}`);
+}
+```
+
+### Find all members of a server
+
+```typescript
+const members = await messenger.getServerMembers(serverId);
+for (const { account } of members) {
+  const roleName = ["Member", "Admin", "Owner"][account.role];
+  console.log(`${account.member} — ${roleName}`);
+}
+```
+
+### Get a specific server/channel/member
+
+```typescript
+const server = await messenger.getServer(serverId);
+const channel = await messenger.getChannel(channelId, version);
+const myServerMember = await messenger.getServerMember(serverId);
+const myChannelMember = await messenger.getChannelMember(channelId);
+```
+
+---
+
+## Key Management
+
+The encryption model uses **shared symmetric keys** wrapped per-member.
+
+### How it works
+
+1. **Server key**: One symmetric key per server version. Stored wrapped in each ServerMember's `keyWraps`.
+2. **Channel key**: One symmetric key per channel version (private channels only). Stored in ChannelMember's `keyWraps`.
+3. **Key rotation**: When a member is removed (or leaves), a NEW key is generated and wrapped for all remaining members. The old key still exists in their records (for reading old messages).
+4. **`keyVersion`**: When sending a message, you specify which key version you used. Readers use this to find the right key wrap to decrypt.
+
+### Unwrap a key
+
+```typescript
+// Get your ServerMember or ChannelMember account
+const myMember = await messenger.getServerMember(serverId);
+
+// Unwrap the latest key
+const latestWrap = myMember.keyWraps[myMember.keyWraps.length - 1];
+const key = messenger.unwrapKey(
+  latestWrap.wrappedKey,
+  latestWrap.nonce,
+  wrapperEncryptionPubkey, // encryption pubkey of whoever wrapped it (admin/creator)
+);
+```
+
+### Who wrapped the key?
+
+The wrapper is whoever called `inviteToServer`, `createServer`, `removeServerMember`, or `leaveServer`. You need their **encryption public key** (from the EncryptionRegistry) to unwrap.
+
+For key wraps created by different people at different times, you may need to try multiple encryption pubkeys. In practice, most servers have one admin who does all invites.
+
+### Key version timeline example
+
+```
+v0: Server created with key K0 (wrapped for owner)
+    → invite member B (K0 wrapped for B)
+    → invite member C (K0 wrapped for C)
+v1: Member C removed → new key K1 (wrapped for owner + B)
+    → C can still read v0 messages, not v1+
+v2: Member B leaves → new key K2 (wrapped for owner only)
+    → B can still read v0-v1 messages, not v2+
+```
+
+---
+
+## Account Deserialization
+
+For custom integrations, you can deserialize raw account data directly:
+
+```typescript
+import {
+  deserializeServer,
+  deserializeServerMember,
+  deserializeChannel,
+  deserializeChannelMember,
+  deserializeEncryptionRegistry,
+  deserializePlatformConfig,
+  ACCOUNT_DISCRIMINATORS,
+} from "solana-messenger-sdk";
+
+// From raw RPC data
+const accountInfo = await rpc.getAccountInfo(address(pda), { encoding: "base64" }).send();
+const data = Buffer.from(accountInfo.value.data[0], "base64");
+const server = deserializeServer(new Uint8Array(data));
+```
+
+### Account layouts
+
+| Account | PDA Seeds | Key Fields |
+|---------|-----------|------------|
+| `Server` | `["server", serverId]` | serverId, owner, name |
+| `ServerMember` | `["server_member", serverId, member]` | serverId, member, role, keyWraps |
+| `Channel` | `["channel", channelId, versionBytes]` | channelId, serverId?, creator, version, channelType, members |
+| `ChannelMember` | `["channel_member", channelId, member]` | channelId, member, keyWraps |
+| `EncryptionRegistry` | `["messenger", owner]` | owner, encryptionKey, minFee |
+| `PlatformConfig` | `["config"]` | authority, feeVault, protocolFee |
+
+---
+
+## Common Patterns
+
+### Pattern: "Show me everything" (first login / new device)
+
+```typescript
+await messenger.init();
+
+// 1. Find all servers
+const servers = await messenger.getMyServers();
+
+// 2. For each server, find channels
+for (const { server, account } of servers) {
+  const channels = await messenger.getServerChannels(server.serverId);
+  console.log(`Server: ${server.name} (${channels.length} channels)`);
+}
+
+// 3. Find standalone group DMs
+const myChannels = await messenger.getMyChannels();
+const groupDMs = myChannels.filter(c => c.channel && !c.channel.serverId);
+
+// 4. DM history
+const dms = await messenger.read({ limit: 50 });
+```
+
+### Pattern: Full server setup
+
+```typescript
+// 1. Create server
+const { serverId } = await messenger.createServer("Acme Corp");
+
+// 2. Create channels
+await messenger.createChannel({ serverId, channelType: ChannelType.Public, members: [] }); // #general
+await messenger.createChannel({ serverId, channelType: ChannelType.Private, members: [myAddr, cofounderAddr] }); // #founders
+
+// 3. Invite team
+const myMember = await messenger.getServerMember(serverId);
+const serverKey = messenger.unwrapKey(myMember.keyWraps[0].wrappedKey, myMember.keyWraps[0].nonce, myEncPubkey);
+await messenger.inviteToServer(serverId, "TeamMember1", [serverKey]);
+await messenger.inviteToServer(serverId, "TeamMember2", [serverKey]);
+```
+
+### Pattern: Offboarding a member
+
+```typescript
+// 1. Remove from server (rotates server key → public channels secured)
+const members = await messenger.getServerMembers(serverId);
+const remaining = members.filter(m => m.account.member !== removedAddr).map(m => m.account.member);
+await messenger.removeServerMember(serverId, removedAddr, remaining);
+
+// 2. Remove from private channels (must do separately!)
+const channels = await messenger.getServerChannels(serverId);
+for (const { account: ch } of channels) {
+  if (ch.channelType === 0 && ch.members.includes(removedAddr)) {
+    const chRemaining = ch.members.filter(m => m !== removedAddr);
+    await messenger.removeChannelMembers(ch.channelId, ch.version, [removedAddr], chRemaining);
+  }
+}
+```
+
+⚠️ **Important:** Removing from a server does NOT automatically remove from private channels. You must do both.
+
+---
+
+## Architecture Reference
+
+### Encryption
+
+| Message Type | Algorithm | Key Source |
+|---|---|---|
+| DM | NaCl box (X25519-XSalsa20-Poly1305) | Diffie-Hellman shared secret |
+| Public channel | NaCl secretbox (XSalsa20-Poly1305) | Server key (from ServerMember.keyWraps) |
+| Private channel | NaCl secretbox (XSalsa20-Poly1305) | Channel key (from ChannelMember.keyWraps) |
+
+### Roles
+
+| Value | Role | Can do |
+|---|---|---|
+| 0 | Member | Send messages |
+| 1 | Admin | Invite/remove members |
+| 2 | Owner | Everything + cannot be removed |
+
+### Events (on-chain)
+
+Messages are emitted as events (not stored in accounts):
+
+```typescript
+// DM event
+{ sender, recipient, ciphertext, nonce, timestamp }
+
+// Channel message event
+{ sender, channelId, version, keyVersion, ciphertext, nonce, timestamp }
+```
+
+### Security model
+
+- **Forward secrecy**: Key rotation on removal AND voluntary leave
+- **Full history**: New members get all historical keys
+- **Public channel auth**: Sender's ServerMember PDA verified on-chain
+- **Server channel auth**: Creator's ServerMember PDA required for channel creation
+- **Admin verification**: PDA derivation check prevents spoofing
+- **On-chain immutability**: Messages are permanent events — protocol cannot enforce deletion
+- **Custody separation**: Signing key (A) ≠ encryption key (B) — custodial wallets can't read messages
+
+### Costs
+
+| Action | Cost |
+|--------|------|
+| Send DM | ~5000 lamports + protocol fee + recipient min_fee |
+| Send channel message | ~5000 lamports + protocol fee |
+| Register | ~0.001 SOL rent (reclaimable) |
+| Create server | ~0.001 SOL rent |
+| Create channel | ~0.06 SOL rent (reclaimable) |
+| ServerMember | ~0.002 SOL rent (reclaimable) |
+| ChannelMember | ~0.002 SOL rent (reclaimable) |
+
+All rent is reclaimable when accounts are closed.