@rougechain/sdk 0.8.3 → 0.9.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 · Mail · Messenger
+  Transfers · DEX · NFTs · Shielded Transactions · Bridge · Rollups · Dynamic Fees · Finality Proofs · WebSocket · Mail · Messenger
 </p>
 
 <p align="center">
@@ -67,6 +67,10 @@ const { balance } = await rc.getBalance(wallet.publicKey);
 | **Address Resolution** | `rc` | O(1) rouge1↔pubkey resolution via on-chain index |
 | **Push Notifications** | `rc` | PQC-signed push token registration (Expo) |
 | **Token Freeze** | `rc` | Creator-only token freeze/pause |
+| **Mintable Tokens** | `rc` | Ongoing token minting with supply cap enforcement |
+| **Dynamic Fees** | `rc` | EIP-1559 base fee, priority tips, fee burning |
+| **Finality Proofs** | `rc` | BFT finality certificates with ≥2/3 validator stake |
+| **WebSocket** | `rc` | Real-time event streaming with topic subscriptions |
 
 ## Wallet & Addresses
 
@@ -122,6 +126,56 @@ await rc.updateTokenMetadata(wallet, {
 
 // Burn tokens
 await rc.burn(wallet, 500);
+
+// Create a mintable token with supply cap
+await rc.createToken(wallet, {
+  name: "Inflation Token",
+  symbol: "INFT",
+  totalSupply: 100_000,
+  mintable: true,
+  maxSupply: 1_000_000,
+});
+
+// Mint additional tokens (creator only)
+await rc.mintTokens(wallet, { symbol: "INFT", amount: 50_000 });
+```
+
+## Dynamic Fees (EIP-1559)
+
+```typescript
+// Get current fee info — base fee adjusts per block
+const fee = await rc.getFeeInfo();
+console.log(`Base fee: ${fee.base_fee} XRGE`);
+console.log(`Suggested total: ${fee.total_fee_suggestion} XRGE`);
+console.log(`Total burned: ${fee.total_fees_burned} XRGE`);
+```
+
+## Finality Proofs
+
+```typescript
+// Get a BFT finality proof for a block height
+const { proof } = await rc.getFinalityProof(42);
+if (proof) {
+  console.log(`Block ${proof.height} finalized with ${proof.voting_stake}/${proof.total_stake} stake`);
+  console.log(`${proof.precommit_votes.length} precommit signatures`);
+}
+```
+
+## WebSocket Subscriptions
+
+```typescript
+// Subscribe to specific topics for real-time events
+const ws = rc.connectWebSocket(["blocks", `account:${wallet.publicKey}`]);
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  if (data.type === "new_block") {
+    console.log(`New block #${data.height}`);
+  }
+};
+
+// Available topics: "blocks", "transactions", "stats",
+// "account:<pubkey>", "token:<symbol>"
 ```
 
 ## DEX (`rc.dex`)
@@ -283,11 +337,41 @@ const batch = await rc.getRollupBatch(1);
 
 ## Mail (`rc.mail`)
 
-On-chain encrypted email with `@rouge.quant` 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
+
+Register a mail name so other users can send you encrypted email. Third-party apps (QWALLA, qRougee, etc.) should call these on wallet creation.
 
 ```typescript
-// Send an encrypted email
-await rc.mail.send({
+// Step 1: Register wallet on the node (required for encryption keys)
+await rc.messenger.registerWallet(wallet, {
+  id: wallet.publicKey,
+  displayName: "Alice",
+  signingPublicKey: wallet.publicKey,
+  encryptionPublicKey: encPubKey,
+});
+
+// Step 2: Register a mail name (signed request)
+await rc.mail.registerName(wallet, "alice", wallet.publicKey);
+
+// 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 } }
+
+// Reverse lookup: wallet ID → name
+const name = await rc.mail.reverseLookup(wallet.publicKey);
+// "alice"
+
+// Release a name (signed request)
+await rc.mail.releaseName(wallet, "alice", wallet.publicKey);
+```
+
+### Sending & Reading Mail
+
+```typescript
+// Send an encrypted email (signed, multi-recipient CEK encryption)
+await rc.mail.send(wallet, {
   from: wallet.publicKey,
   to: recipientPubKey,
   subject: "Hello",
@@ -296,52 +380,55 @@ 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 (signed request)
+await rc.mail.move(wallet, messageId, "trash");
 
-// Move to trash
-await rc.mail.move(messageId, "trash");
+// Mark as read (signed request)
+await rc.mail.markRead(wallet, messageId);
 
-// Mark as read
-await rc.mail.markRead(messageId);
+// Delete (signed request)
+await rc.mail.delete(wallet, messageId);
 ```
 
 ## 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);
 
-// Delete a message
-await rc.messenger.deleteMessage(messageId);
+// Delete a conversation (signed request)
+await rc.messenger.deleteConversation(wallet, conversationId);
 ```
 
 ## Shielded Transactions (`rc.shielded`)
@@ -460,6 +547,7 @@ import type {
   ShieldParams, ShieldedTransferParams, UnshieldParams, ShieldedStats,
   ShieldedNote,
   RollupStatus, RollupBatchResult, RollupSubmitParams, RollupSubmitResult,
+  FeeInfo, FinalityProof, MintTokenParams, VoteMessage, WsSubscribeMessage,
 } from "@rougechain/sdk";
 ```
 
@@ -468,6 +556,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() {
@@ -468,6 +471,19 @@ var RougeChain = class {
   async getFinality() {
     return this.get("/finality");
   }
+  // ===== EIP-1559 Fee Info =====
+  /** Get current EIP-1559 fee information including base fee and suggestions. */
+  async getFeeInfo() {
+    return this.get("/fee");
+  }
+  // ===== BFT Finality Proofs =====
+  /**
+   * Get a BFT finality proof for a specific block height.
+   * Returns the aggregated precommit votes that prove ≥2/3 validator stake agreed.
+   */
+  async getFinalityProof(height) {
+    return this.get(`/finality/${height}`);
+  }
   // ===== Peers =====
   async getPeers() {
     const data = await this.get("/peers");
@@ -553,6 +569,39 @@ var RougeChain = class {
     const tx = createSignedTokenMetadataClaim(wallet, tokenSymbol);
     return this.submitTx("/v2/token/metadata/claim", tx);
   }
+  /**
+   * Mint additional tokens for a mintable token (creator only).
+   * The token must have been created with `mintable: true`.
+   */
+  async mintTokens(wallet, params) {
+    return this.post("/v2/token/mint", {
+      public_key: wallet.publicKey,
+      symbol: params.symbol,
+      amount: params.amount,
+      fee: params.fee ?? 1,
+      signature: ""
+      // Will be signed server-side via PQC verification
+    });
+  }
+  // ===== WebSocket =====
+  /**
+   * Connect to the node's WebSocket and optionally subscribe to specific topics.
+   * Topics: "blocks", "transactions", "stats", "account:<pubkey>", "token:<symbol>"
+   *
+   * @example
+   * const ws = client.connectWebSocket(["blocks", "account:abc123"]);
+   * ws.onmessage = (e) => console.log(JSON.parse(e.data));
+   */
+  connectWebSocket(topics) {
+    const wsUrl = this.baseUrl.replace(/^http/, "ws") + "/ws";
+    const ws = new WebSocket(wsUrl);
+    if (topics && topics.length > 0) {
+      ws.addEventListener("open", () => {
+        ws.send(JSON.stringify({ subscribe: topics }));
+      });
+    }
+    return ws;
+  }
   // ===== Rollup =====
   /** Get the current rollup accumulator status. */
   async getRollupStatus() {
@@ -913,68 +962,97 @@ var MailClient = class {
   constructor(rc) {
     this.rc = rc;
   }
-  async send(params) {
+  // --- 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 {
-      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.get(
+        `/names/resolve/${encodeURIComponent(name.toLowerCase())}`
+      );
+      if (!data.success) return null;
+      return { entry: data.entry, wallet: data.wallet };
+    } catch {
+      return null;
     }
   }
-  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 reverseLookup(walletId) {
+    try {
+      const data = await this.rc.get(
+        `/names/reverse/${encodeURIComponent(walletId)}`
+      );
+      return data.name || null;
+    } catch {
+      return null;
+    }
   }
-  async getTrash(walletId) {
-    const data = await this.rc.get(
-      `/mail/trash?walletId=${encodeURIComponent(walletId)}`
-    );
-    return data.messages ?? [];
+  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);
   }
-  async getMessage(id) {
-    return this.rc.get(`/mail/message/${encodeURIComponent(id)}`);
+  async getInbox(wallet) {
+    const signed = signRequest(wallet, { folder: "inbox" });
+    try {
+      const data = await this.rc.post("/v2/mail/folder", signed);
+      return data.messages ?? [];
+    } catch {
+      return [];
+    }
   }
-  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) {
@@ -984,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 {
@@ -1113,6 +1185,33 @@ var ShieldedClient = class {
     );
     return this.rc.submitTx("/v2/shielded/unshield", tx);
   }
+  // ─── WASM Smart Contracts ──────────────────────────────────────────
+  /** Deploy a WASM smart contract */
+  async deployContract(params) {
+    return this.rc.post("/v2/contract/deploy", params);
+  }
+  /** Call a WASM smart contract method (mutating) */
+  async callContract(params) {
+    return this.rc.post("/v2/contract/call", params);
+  }
+  /** Get contract metadata */
+  async getContract(addr) {
+    return this.rc.get(`/contract/${addr}`);
+  }
+  /** Read contract storage. Omit key for full state dump. */
+  async getContractState(addr, key) {
+    const q = key ? `?key=${encodeURIComponent(key)}` : "";
+    return this.rc.get(`/contract/${addr}/state${q}`);
+  }
+  /** Get contract events */
+  async getContractEvents(addr, limit) {
+    const q = limit ? `?limit=${limit}` : "";
+    return this.rc.get(`/contract/${addr}/events${q}`);
+  }
+  /** List all deployed contracts */
+  async listContracts() {
+    return this.rc.get("/contracts");
+  }
 };
 
 // src/address.ts
@@ -1269,9 +1368,9 @@ var Wallet = class _Wallet {
   /**
    * Generate a new ML-DSA-65 keypair with a BIP-39 mnemonic.
    * The mnemonic is stored on the wallet for backup/recovery.
-   * @param strength 128 = 12 words (default), 256 = 24 words
+   * @param strength 256 = 24 words (default, post-quantum safe), 128 = 12 words
    */
-  static generate(strength = 128) {
+  static generate(strength = 256) {
     const mnemonic = generateMnemonic(strength);
     const { publicKey, secretKey } = keypairFromMnemonic(mnemonic);
     return new _Wallet(publicKey, secretKey, mnemonic);
@@ -1363,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;