@rougechain/sdk 0.8.4 → 1.0.0

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <strong>Build quantum-safe dApps on RougeChain</strong><br />
-  Transfers · DEX · NFTs · Shielded Transactions · Bridge · Rollups · Dynamic Fees · Finality Proofs · WebSocket · Mail · Messenger
+  Transfers · DEX · NFTs · Social · Shielded Transactions · Bridge · Rollups · Dynamic Fees · Finality Proofs · WebSocket · Mail · Messenger
 </p>
 
 <p align="center">
@@ -62,6 +62,7 @@ const { balance } = await rc.getBalance(wallet.publicKey);
 | **Shielded** | `rc.shielded` | Private transfers with zk-STARK proofs, shield/unshield XRGE |
 | **Bridge** | `rc.bridge` | ETH ↔ qETH, USDC ↔ qUSDC, XRGE bridge (Base Mainnet/Sepolia) |
 | **Rollup** | `rc` | zk-STARK batch proofs, rollup status, submit transfers |
+| **Social** | `rc.social` | Posts, timeline feed, reposts, likes, follows, comments |
 | **Mail** | `rc.mail` | On-chain encrypted email (`@rouge.quant`) |
 | **Messenger** | `rc.messenger` | E2E encrypted messaging with self-destruct |
 | **Address Resolution** | `rc` | O(1) rouge1↔pubkey resolution via on-chain index |
@@ -335,9 +336,82 @@ const batch = await rc.getRollupBatch(1);
 // { batch_id, transfer_count, proof_size_bytes, proof_time_ms, verified, ... }
 ```
 
+## Social (`rc.social`)
+
+On-chain social layer with posts, threaded replies, reposts, likes, follows, and comments. All write operations require a `wallet` parameter for ML-DSA-65 signed requests.
+
+### Posts & Timeline
+
+```typescript
+// Create a post (max 4000 chars)
+const { post } = await rc.social.createPost(wallet, "Hello RougeChain!");
+
+// Reply to a post (threaded)
+await rc.social.createPost(wallet, "Great point!", post.id);
+
+// Delete your own post
+await rc.social.deletePost(wallet, post.id);
+
+// Get a single post with stats
+const result = await rc.social.getPost(post.id, wallet.publicKey);
+// result.post, result.stats { likes, reposts, replies, liked, reposted }
+
+// Global timeline (all posts, newest first)
+const timeline = await rc.social.getGlobalTimeline(50, 0);
+
+// Following feed (posts from people you follow)
+const feed = await rc.social.getFollowingFeed(wallet, 50, 0);
+
+// User's posts
+const { posts, total } = await rc.social.getUserPosts(userPubKey);
+
+// Get replies to a post
+const replies = await rc.social.getPostReplies(post.id);
+```
+
+### Likes, Reposts & Follows
+
+```typescript
+// Like/unlike a post or track (toggle)
+await rc.social.toggleLike(wallet, postOrTrackId);
+
+// Repost/unrepost (toggle)
+await rc.social.toggleRepost(wallet, post.id);
+
+// Follow/unfollow (toggle)
+await rc.social.toggleFollow(wallet, artistPubKey);
+
+// Get stats
+const stats = await rc.social.getPostStats(post.id, wallet.publicKey);
+const artistStats = await rc.social.getArtistStats(pubkey, wallet.publicKey);
+```
+
+### Comments (Track-level)
+
+```typescript
+// Comment on a track
+const { comment } = await rc.social.postComment(wallet, trackId, "Fire track!");
+
+// Get comments
+const comments = await rc.social.getComments(trackId);
+
+// Delete your comment
+await rc.social.deleteComment(wallet, comment.id);
+```
+
+### Play Counts
+
+```typescript
+// Record a play (debounce client-side, one per session per track)
+await rc.social.recordPlay(wallet, trackId);
+
+// Get track stats (plays, likes, comments)
+const trackStats = await rc.social.getTrackStats(trackId, wallet.publicKey);
+```
+
 ## Mail (`rc.mail`)
 
-On-chain encrypted email with `@rouge.quant` / `@qwalla.mail` addresses.
+On-chain encrypted email with `@rouge.quant` / `@qwalla.mail` addresses. All write operations require a `wallet` parameter for ML-DSA-65 request signing — requests are authenticated via `/api/v2/` endpoints with anti-replay nonce protection.
 
 ### Name Registry
 
@@ -345,17 +419,17 @@ Register a mail name so other users can send you encrypted email. Third-party ap
 
 ```typescript
 // Step 1: Register wallet on the node (required for encryption keys)
-await rc.messenger.registerWallet({
+await rc.messenger.registerWallet(wallet, {
   id: wallet.publicKey,
   displayName: "Alice",
   signingPublicKey: wallet.publicKey,
   encryptionPublicKey: encPubKey,
 });
 
-// Step 2: Register a mail name
-await rc.mail.registerName("alice", wallet.publicKey);
+// Step 2: Register a mail name (signed request)
+await rc.mail.registerName(wallet, "alice", wallet.publicKey);
 
-// Resolve a name → wallet info (includes encryption key)
+// Resolve a name → wallet info (includes encryption key, public data only)
 const resolved = await rc.mail.resolveName("alice");
 // { entry: { name, wallet_id }, wallet: { id, signing_public_key, encryption_public_key } }
 
@@ -363,15 +437,15 @@ const resolved = await rc.mail.resolveName("alice");
 const name = await rc.mail.reverseLookup(wallet.publicKey);
 // "alice"
 
-// Release a name
-await rc.mail.releaseName("alice", wallet.publicKey);
+// Release a name (signed request)
+await rc.mail.releaseName(wallet, "alice");
 ```
 
 ### Sending & Reading Mail
 
 ```typescript
-// Send an encrypted email
-await rc.mail.send({
+// Send an encrypted email (signed, multi-recipient CEK encryption)
+await rc.mail.send(wallet, {
   from: wallet.publicKey,
   to: recipientPubKey,
   subject: "Hello",
@@ -380,52 +454,74 @@ await rc.mail.send({
   encrypted_body: encryptedBody,
 });
 
-// Read inbox
-const inbox = await rc.mail.getInbox(wallet.publicKey);
+// Read inbox (signed request)
+const inbox = await rc.mail.getInbox(wallet);
 
-// Move to trash
-await rc.mail.move(messageId, "trash");
+// Move to trash (signed request)
+await rc.mail.move(wallet, messageId, "trash");
 
-// Mark as read
-await rc.mail.markRead(messageId);
+// Mark as read (signed request)
+await rc.mail.markRead(wallet, messageId);
+
+// Delete (signed request)
+await rc.mail.delete(wallet, messageId);
+```
+
+### Unread Counts
+
+The SDK does not expose a dedicated unread-count endpoint. Derive unread totals client-side from inbox data:
+
+```typescript
+// Mail: count unread inbox items
+const inbox = await rc.mail.getInbox(wallet);
+const unreadMail = inbox.filter((m: any) => {
+  const label = m.label ?? {};
+  return !(label.is_read ?? label.isRead ?? true);
+}).length;
+
+// Messenger: sum unread_count across conversations
+const convos = await rc.messenger.getConversations(wallet);
+const unreadChats = convos.reduce((sum: number, c: any) => {
+  return sum + (c.unread_count ?? c.unreadCount ?? 0);
+}, 0);
 ```
 
 ## Messenger (`rc.messenger`)
 
-End-to-end encrypted messaging with media and self-destruct support.
+End-to-end encrypted messaging with media and self-destruct support. All operations use ML-DSA-65 signed requests via `/api/v2/` endpoints with nonce-based anti-replay protection.
 
 ```typescript
-// Register wallet for messaging
-await rc.messenger.registerWallet({
+// Register wallet for messaging (signed request)
+await rc.messenger.registerWallet(wallet, {
   id: wallet.publicKey,
   displayName: "Alice",
   signingPublicKey: wallet.publicKey,
   encryptionPublicKey: encPubKey,
 });
 
-// Create a conversation
-const result = await rc.messenger.createConversation([
+// Create a conversation (signed request)
+const result = await rc.messenger.createConversation(wallet, [
   wallet.publicKey,
   recipientPubKey,
 ]);
 
-// Fetch conversations (with extended key matching)
-const convos = await rc.messenger.getConversations(wallet.publicKey, {
-  signingPublicKey: wallet.publicKey,
-  encryptionPublicKey: encPubKey,
-});
+// Fetch conversations (signed request)
+const convos = await rc.messenger.getConversations(wallet);
 
-// Send an encrypted message (with optional self-destruct)
-await rc.messenger.sendMessage(conversationId, wallet.publicKey, encryptedContent, {
+// Send an encrypted message (signed, with optional self-destruct)
+await rc.messenger.sendMessage(wallet, conversationId, encryptedContent, {
   selfDestruct: true,
   destructAfterSeconds: 30,
 });
 
-// Read messages
-const messages = await rc.messenger.getMessages(conversationId);
+// Read messages (signed request)
+const messages = await rc.messenger.getMessages(wallet, conversationId);
+
+// Delete a message (signed request)
+await rc.messenger.deleteMessage(wallet, messageId, conversationId);
 
-// Delete a message
-await rc.messenger.deleteMessage(messageId);
+// Delete a conversation (signed request)
+await rc.messenger.deleteConversation(wallet, conversationId);
 ```
 
 ## Shielded Transactions (`rc.shielded`)
@@ -447,7 +543,7 @@ const stats = await rc.shielded.getStats();
 // Check if a nullifier has been spent
 const { spent } = await rc.shielded.isNullifierSpent(note.nullifier);
 
-// Private transfer (requires STARK proof from Rust prover)
+// Private transfer (STARK proof generated by WASM prover in browser or Rust prover on node)
 await rc.shielded.transfer(wallet, {
   nullifiers: [note.nullifier],
   outputCommitments: [recipientCommitment],
@@ -545,6 +641,7 @@ import type {
   ShieldedNote,
   RollupStatus, RollupBatchResult, RollupSubmitParams, RollupSubmitResult,
   FeeInfo, FinalityProof, MintTokenParams, VoteMessage, WsSubscribeMessage,
+  SocialPost, PostStats, TrackStats, ArtistStats, SocialComment,
 } from "@rougechain/sdk";
 ```
 
@@ -553,6 +650,9 @@ import type {
 - **Post-quantum cryptography** — All signatures use ML-DSA-65 (CRYSTALS-Dilithium), resistant to quantum computer attacks
 - **Client-side signing** — Private keys never leave your application
 - **No key storage** — The SDK does not store or transmit keys
+- **Signed API requests** — All mail, messenger, and name registry operations use ML-DSA-65 signed requests with timestamp validation and nonce-based anti-replay protection
+- **Multi-recipient CEK encryption** — Mail content is encrypted once with a random AES-256 key, KEM-wrapped individually per recipient via ML-KEM-768
+- **TOFU key verification** — Public key fingerprints (SHA-256) are tracked for key change detection
 
 ## Links
 

package/dist/index.cjs

@@ -286,6 +286,9 @@ function createSignedPushUnregister(wallet) {
     type: "push_unregister"
   });
 }
+function signRequest(wallet, payload) {
+  return buildAndSign(wallet, payload);
+}
 var COMMITMENT_DOMAIN = new TextEncoder().encode("ROUGECHAIN_COMMITMENT_V1");
 var NULLIFIER_DOMAIN = new TextEncoder().encode("ROUGECHAIN_NULLIFIER_V1");
 function generateRandomness() {
@@ -959,17 +962,10 @@ var MailClient = class {
   constructor(rc) {
     this.rc = rc;
   }
-  // --- Name Registry ---
-  async registerName(name, walletId) {
-    try {
-      const data = await this.rc.post("/names/register", {
-        name,
-        walletId
-      });
-      return { success: data.success === true, error: data.error, data };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
+  // --- Name Registry (signed) ---
+  async registerName(wallet, name, walletId) {
+    const signed = signRequest(wallet, { name, walletId });
+    return this.rc.submitTx("/v2/names/register", signed);
   }
   async resolveName(name) {
     try {
@@ -992,85 +988,71 @@ var MailClient = class {
       return null;
     }
   }
-  async releaseName(name, walletId) {
-    try {
-      const res = await this.rc.fetchFn(
-        `${this.rc.baseUrl}/names/release`,
-        {
-          method: "DELETE",
-          headers: { ...this.rc.headers, "Content-Type": "application/json" },
-          body: JSON.stringify({ name, walletId })
-        }
-      );
-      const data = await res.json();
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
+  async releaseName(wallet, name) {
+    const signed = signRequest(wallet, { name });
+    return this.rc.submitTx("/v2/names/release", signed);
+  }
+  // --- Mail (signed) ---
+  async send(wallet, params) {
+    const signed = signRequest(wallet, {
+      fromWalletId: params.from,
+      toWalletIds: [params.to],
+      subjectEncrypted: params.encrypted_subject,
+      bodyEncrypted: params.encrypted_body,
+      contentSignature: params.body,
+      replyToId: params.reply_to_id,
+      hasAttachment: false
+    });
+    return this.rc.submitTx("/v2/mail/send", signed);
   }
-  // --- Mail ---
-  async send(params) {
+  async getInbox(wallet) {
+    const signed = signRequest(wallet, { folder: "inbox" });
     try {
-      const data = await this.rc.post("/mail/send", params);
-      return { success: data.success === true, error: data.error, data };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post("/v2/mail/folder", signed);
+      return data.messages ?? [];
+    } catch {
+      return [];
     }
   }
-  async getInbox(walletId) {
-    const data = await this.rc.get(
-      `/mail/inbox?walletId=${encodeURIComponent(walletId)}`
-    );
-    return data.messages ?? [];
-  }
-  async getSent(walletId) {
-    const data = await this.rc.get(
-      `/mail/sent?walletId=${encodeURIComponent(walletId)}`
-    );
-    return data.messages ?? [];
-  }
-  async getTrash(walletId) {
-    const data = await this.rc.get(
-      `/mail/trash?walletId=${encodeURIComponent(walletId)}`
-    );
-    return data.messages ?? [];
-  }
-  async getMessage(id) {
-    return this.rc.get(`/mail/message/${encodeURIComponent(id)}`);
-  }
-  async move(messageId, folder) {
+  async getSent(wallet) {
+    const signed = signRequest(wallet, { folder: "sent" });
     try {
-      const data = await this.rc.post("/mail/move", {
-        messageId,
-        folder
-      });
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post("/v2/mail/folder", signed);
+      return data.messages ?? [];
+    } catch {
+      return [];
     }
   }
-  async markRead(messageId) {
+  async getTrash(wallet) {
+    const signed = signRequest(wallet, { folder: "trash" });
     try {
-      const data = await this.rc.post("/mail/read", {
-        messageId
-      });
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post("/v2/mail/folder", signed);
+      return data.messages ?? [];
+    } catch {
+      return [];
     }
   }
-  async delete(id) {
+  async getMessage(wallet, messageId) {
+    const signed = signRequest(wallet, { messageId });
     try {
-      const res = await this.rc.fetchFn(
-        `${this.rc.baseUrl}/mail/${encodeURIComponent(id)}`,
-        { method: "DELETE", headers: this.rc.headers }
-      );
-      const data = await res.json();
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post("/v2/mail/message", signed);
+      return data.message ?? null;
+    } catch {
+      return null;
     }
   }
+  async move(wallet, messageId, folder) {
+    const signed = signRequest(wallet, { messageId, folder });
+    return this.rc.submitTx("/v2/mail/move", signed);
+  }
+  async markRead(wallet, messageId) {
+    const signed = signRequest(wallet, { messageId });
+    return this.rc.submitTx("/v2/mail/read", signed);
+  }
+  async delete(wallet, messageId) {
+    const signed = signRequest(wallet, { messageId });
+    return this.rc.submitTx("/v2/mail/delete", signed);
+  }
 };
 var MessengerClient = class {
   constructor(rc) {
@@ -1080,77 +1062,71 @@ var MessengerClient = class {
     const data = await this.rc.get("/messenger/wallets");
     return data.wallets ?? [];
   }
-  async registerWallet(opts) {
+  async registerWallet(wallet, opts) {
+    const signed = signRequest(wallet, {
+      id: opts.id,
+      displayName: opts.displayName,
+      signingPublicKey: opts.signingPublicKey,
+      encryptionPublicKey: opts.encryptionPublicKey,
+      discoverable: opts.discoverable ?? true
+    });
+    return this.rc.submitTx("/v2/messenger/wallets/register", signed);
+  }
+  async getConversations(wallet) {
+    const signed = signRequest(wallet, {});
     try {
-      const data = await this.rc.post("/messenger/wallets/register", opts);
-      return { success: data.success === true, error: data.error, data };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post(
+        "/v2/messenger/conversations/list",
+        signed
+      );
+      return data.conversations ?? [];
+    } catch {
+      return [];
     }
   }
-  async getConversations(walletId, opts = {}) {
-    const params = new URLSearchParams({ walletId });
-    if (opts.signingPublicKey) params.set("signingPublicKey", opts.signingPublicKey);
-    if (opts.encryptionPublicKey) params.set("encryptionPublicKey", opts.encryptionPublicKey);
-    const data = await this.rc.get(
-      `/messenger/conversations?${params.toString()}`
-    );
-    return data.conversations ?? [];
+  async createConversation(wallet, participantIds, opts = {}) {
+    const signed = signRequest(wallet, {
+      participantIds,
+      name: opts.name,
+      isGroup: opts.isGroup ?? false
+    });
+    return this.rc.submitTx("/v2/messenger/conversations", signed);
   }
-  async createConversation(participants) {
+  async getMessages(wallet, conversationId) {
+    const signed = signRequest(wallet, { conversationId });
     try {
-      const data = await this.rc.post("/messenger/conversations", {
-        participants
-      });
-      return { success: data.success === true, error: data.error, data };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
+      const data = await this.rc.post(
+        "/v2/messenger/messages/list",
+        signed
+      );
+      return data.messages ?? [];
+    } catch {
+      return [];
     }
   }
-  async getMessages(conversationId) {
-    const data = await this.rc.get(
-      `/messenger/messages?conversationId=${encodeURIComponent(conversationId)}`
-    );
-    return data.messages ?? [];
+  async sendMessage(wallet, conversationId, encryptedContent, opts = {}) {
+    const signed = signRequest(wallet, {
+      conversationId,
+      encryptedContent,
+      contentSignature: opts.contentSignature ?? "",
+      messageType: opts.messageType ?? "text",
+      selfDestruct: opts.selfDestruct ?? false,
+      destructAfterSeconds: opts.destructAfterSeconds,
+      spoiler: opts.spoiler ?? false
+    });
+    return this.rc.submitTx("/v2/messenger/messages", signed);
   }
-  async sendMessage(conversationId, senderWalletId, encryptedContent, opts = {}) {
-    try {
-      const data = await this.rc.post("/messenger/messages", {
-        conversationId,
-        senderWalletId,
-        encryptedContent,
-        signature: opts.signature ?? "",
-        messageType: opts.messageType ?? "text",
-        selfDestruct: opts.selfDestruct ?? false,
-        destructAfterSeconds: opts.destructAfterSeconds,
-        spoiler: opts.spoiler ?? false
-      });
-      return { success: data.success === true, error: data.error, data };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
+  async deleteMessage(wallet, messageId, conversationId) {
+    const signed = signRequest(wallet, { messageId, conversationId });
+    return this.rc.submitTx("/v2/messenger/messages/delete", signed);
   }
-  async deleteMessage(messageId) {
-    try {
-      const res = await this.rc.fetchFn(
-        `${this.rc.baseUrl}/messenger/messages/${encodeURIComponent(messageId)}`,
-        { method: "DELETE", headers: this.rc.headers }
-      );
-      const data = await res.json();
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
+  async deleteConversation(wallet, conversationId) {
+    const signed = signRequest(wallet, { conversationId });
+    return this.rc.submitTx("/v2/messenger/conversations/delete", signed);
   }
-  async markRead(messageId) {
-    try {
-      const data = await this.rc.post("/messenger/messages/read", {
-        messageId
-      });
-      return { success: data.success === true, error: data.error };
-    } catch (e) {
-      return { success: false, error: e instanceof Error ? e.message : String(e) };
-    }
+  async markRead(wallet, messageId, conversationId) {
+    const signed = signRequest(wallet, { messageId, conversationId });
+    return this.rc.submitTx("/v2/messenger/messages/read", signed);
   }
 };
 var ShieldedClient = class {
@@ -1486,6 +1462,7 @@ exports.keypairFromMnemonic = keypairFromMnemonic;
 exports.mnemonicToMLDSASeed = mnemonicToMLDSASeed;
 exports.pubkeyToAddress = pubkeyToAddress;
 exports.serializePayload = serializePayload;
+exports.signRequest = signRequest;
 exports.signTransaction = signTransaction;
 exports.validateMnemonic = validateMnemonic;
 exports.verifyTransaction = verifyTransaction;