@neuraiproject/neurai-depin-terminal 1.0.1 → 2.0.1

package/src/messaging/MessagePoller.js

@@ -7,6 +7,8 @@
 import { EventEmitter } from 'events';
 import { RPC_METHODS } from '../constants.js';
 import { isEncryptedResponse } from '../utils.js';
+import { MESSAGE_TYPES, normalizeMessageType } from '../domain/messageTypes.js';
+import { RecipientDirectory } from './RecipientDirectory.js';
 
 /**
  * Polls for new DePIN messages at regular intervals
@@ -26,8 +28,9 @@ export class MessagePoller extends EventEmitter {
    * @param {MessageStore} messageStore - Message store instance
    * @param {Object} neuraiDepinMsg - DePIN message library
    * @param {WalletManager} walletManager - Wallet manager instance (for decryption)
+   * @param {RecipientDirectory} [recipientDirectory] - Recipient directory (shared cache)
    */
-  constructor(config, rpcService, messageStore, neuraiDepinMsg, walletManager) {
+  constructor(config, rpcService, messageStore, neuraiDepinMsg, walletManager, recipientDirectory = null) {
     super();
     this.config = config;
     this.rpcService = rpcService;
@@ -37,6 +40,8 @@ export class MessagePoller extends EventEmitter {
     this.intervalId = null;
     this.isPolling = false;
     this.wasDisconnected = false; // Track if we were disconnected
+    this.recipientDirectory = recipientDirectory
+      || new RecipientDirectory(config, rpcService, neuraiDepinMsg);
   }
 
   /**
@@ -263,13 +268,26 @@ export class MessagePoller extends EventEmitter {
         return false; // Not for us or malformed
       }
 
+      const messageType = normalizeMessageType(msg.message_type || msg.messageType);
+      let peerAddress = null;
+
+      if (messageType === MESSAGE_TYPES.PRIVATE) {
+        if (msg.sender === this.walletManager.getAddress()) {
+          peerAddress = await this.resolvePrivatePeerAddress(msg);
+        } else {
+          peerAddress = msg.sender;
+        }
+      }
+
       // Add to store with deduplication
       const isNew = this.messageStore.addMessage({
         sender: msg.sender,
         message: plaintext,
         timestamp: msg.timestamp,
         hash: msg.hash,
-        signature: msg.signature_hex
+        signature: msg.signature_hex,
+        messageType: messageType,
+        peerAddress: peerAddress
       });
 
       if (isNew) {
@@ -286,7 +304,9 @@ export class MessagePoller extends EventEmitter {
           sender: msg.sender,
           message: plaintext,
           timestamp: msg.timestamp,
-          hash: msg.hash
+          hash: msg.hash,
+          messageType: messageType,
+          peerAddress: peerAddress
         });
         return true;
       }
@@ -297,4 +317,113 @@ export class MessagePoller extends EventEmitter {
       return false;
     }
   }
+
+  async resolvePrivatePeerAddress(msg) {
+    const mapped = this.messageStore.getOutgoingPrivateRecipient(msg.hash);
+    if (mapped) {
+      return mapped;
+    }
+
+    const hashes = this.extractRecipientHashes(msg.encrypted_payload_hex);
+    if (!hashes.length) {
+      return null;
+    }
+
+    const map = await this.recipientDirectory.getHashMap();
+    for (const hash of hashes) {
+      const address = map.get(hash);
+      if (address && address !== this.walletManager.getAddress()) {
+        return address;
+      }
+    }
+
+    return null;
+  }
+
+  extractRecipientHashes(encryptedPayloadHex) {
+    const utils = this.neuraiDepinMsg?.utils;
+    if (!utils?.hexToBytes || !utils?.bytesToHex) {
+      return [];
+    }
+
+    try {
+      const hex = this.normalizeHex(encryptedPayloadHex);
+      if (!hex) {
+        return [];
+      }
+      const serialized = utils.hexToBytes(hex);
+      let offset = 0;
+
+      const ephem = this.readVector(serialized, offset);
+      offset = ephem.offset;
+      const payload = this.readVector(serialized, offset);
+      offset = payload.offset;
+      const countRes = this.readCompactSize(serialized, offset);
+      const count = countRes.value;
+      offset = countRes.offset;
+
+      const hashes = [];
+      for (let i = 0; i < count; i += 1) {
+        if (offset + 20 > serialized.length) {
+          break;
+        }
+        const keyId = serialized.slice(offset, offset + 20);
+        offset += 20;
+        const v = this.readVector(serialized, offset);
+        offset = v.offset;
+        hashes.push(utils.bytesToHex(keyId).toLowerCase());
+      }
+      return hashes;
+    } catch (error) {
+      return [];
+    }
+  }
+
+  normalizeHex(hex) {
+    if (typeof hex !== 'string') {
+      return '';
+    }
+    const trimmed = hex.startsWith('0x') ? hex.slice(2) : hex;
+    return trimmed.trim().toLowerCase();
+  }
+
+  readCompactSize(buf, offset) {
+    if (offset >= buf.length) {
+      throw new Error('CompactSize: out of bounds');
+    }
+    const first = buf[offset];
+    if (first < 253) return { value: first, offset: offset + 1 };
+    if (first === 253) {
+      if (offset + 3 > buf.length) throw new Error('CompactSize: truncated uint16');
+      const value = buf[offset + 1] | (buf[offset + 2] << 8);
+      return { value, offset: offset + 3 };
+    }
+    if (first === 254) {
+      if (offset + 5 > buf.length) throw new Error('CompactSize: truncated uint32');
+      const value =
+        (buf[offset + 1]) |
+        (buf[offset + 2] << 8) |
+        (buf[offset + 3] << 16) |
+        (buf[offset + 4] << 24);
+      return { value: value >>> 0, offset: offset + 5 };
+    }
+    if (offset + 9 > buf.length) throw new Error('CompactSize: truncated uint64');
+    let value = 0n;
+    for (let i = 0; i < 8; i += 1) {
+      value |= BigInt(buf[offset + 1 + i]) << (8n * BigInt(i));
+    }
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error('CompactSize: value too large');
+    }
+    return { value: Number(value), offset: offset + 9 };
+  }
+
+  readVector(buf, offset) {
+    const { value: len, offset: afterLen } = this.readCompactSize(buf, offset);
+    if (afterLen + len > buf.length) {
+      throw new Error('Vector: truncated');
+    }
+    const data = buf.slice(afterLen, afterLen + len);
+    return { data, offset: afterLen + len };
+  }
 }

package/src/messaging/MessageSender.js

@@ -1,6 +1,6 @@
 /**
  * Message sender for Neurai DePIN Terminal
- * Handles sending broadcast messages to all token holders
+ * Handles sending broadcast and private messages
  * @module MessageSender
  */
 
@@ -9,10 +9,12 @@ import {
   ERROR_MESSAGES
 } from '../constants.js';
 import { MessageError, DepinError } from '../errors.js';
-import { isPubkeyRevealed, normalizePubkey, hasPrivacyLayer } from '../utils.js';
+import { hasPrivacyLayer } from '../utils.js';
+import { RecipientDirectory } from './RecipientDirectory.js';
+import { MESSAGE_TYPES } from '../domain/messageTypes.js';
 
 /**
- * Sends DePIN messages to all token holders
+ * Sends DePIN messages to token holders or a specific recipient
  */
 export class MessageSender {
   /**
@@ -22,12 +24,15 @@ export class MessageSender {
    * @param {WalletManager} walletManager - Wallet manager instance
    * @param {RpcService} rpcService - RPC service instance
    * @param {Object} neuraiDepinMsg - DePIN message library
+   * @param {RecipientDirectory} [recipientDirectory] - Recipient directory (shared cache)
    */
-  constructor(config, walletManager, rpcService, neuraiDepinMsg) {
+  constructor(config, walletManager, rpcService, neuraiDepinMsg, recipientDirectory = null) {
     this.config = config;
     this.walletManager = walletManager;
     this.rpcService = rpcService;
     this.neuraiDepinMsg = neuraiDepinMsg;
+    this.recipientDirectory = recipientDirectory
+      || new RecipientDirectory(config, rpcService, neuraiDepinMsg);
   }
 
   /**
@@ -40,58 +45,95 @@ export class MessageSender {
 
   /**
    * Get all addresses holding the token
-   * @returns {Promise<Array<string>>} Array of addresses
+   * @returns {Promise<Array<{address: string, pubkey: string}>>} Recipient entries
    * @throws {MessageError} If no token holders found
    */
-  async getTokenHolders() {
-    const rpc = this.getRpc();
-    const addressesData = await rpc(RPC_METHODS.LIST_ADDRESSES_BY_ASSET, [this.config.token]);
-    const addresses = Object.keys(addressesData);
+  async fetchDepinRecipients() {
+    return this.recipientDirectory.fetchEntries();
+  }
 
-    if (addresses.length === 0) {
-      throw new MessageError(ERROR_MESSAGES.NO_TOKEN_HOLDERS);
-    }
+  async refreshRecipientCache(force = false) {
+    return this.recipientDirectory.refresh(force);
+  }
+
+  getCachedRecipientEntries() {
+    return this.recipientDirectory.getCachedEntries();
+  }
 
-    return addresses;
+  getCachedPrivateRecipientAddresses() {
+    return this.recipientDirectory.getCachedAddresses();
   }
 
   /**
-   * Get revealed public keys from addresses
-   * @param {Array<string>} addresses - Array of addresses
+   * Get revealed public keys
    * @returns {Promise<Array<string>>} Array of revealed public keys (normalized)
    * @throws {MessageError} If no recipients with revealed public keys
    */
-  async getRecipientPubkeys(addresses) {
-    const recipientPubKeys = [];
-    const rpc = this.getRpc();
+  async getRecipientPubkeys() {
+    return this.recipientDirectory.getPubkeys();
+  }
 
-    for (const addr of addresses) {
-      try {
-        const res = await rpc(RPC_METHODS.GET_PUBKEY, [addr]);
+  /**
+   * Get revealed public keys with addresses
+   * @returns {Promise<Array<{address: string, pubkey: string}>>} Recipient entries
+   * @throws {MessageError} If no recipients with revealed public keys
+   */
+  async getRecipientEntries() {
+    return this.recipientDirectory.getEntries();
+  }
 
-        if (isPubkeyRevealed(res)) {
-          recipientPubKeys.push(normalizePubkey(res.pubkey));
-        }
-      } catch (error) {
-        // Skip addresses without revealed pubkey
-        continue;
-      }
+  /**
+   * Get recipient addresses eligible for private messages
+   * @returns {Promise<Array<string>>} Array of addresses
+   * @throws {MessageError} If no recipients with revealed public keys
+   */
+  async getPrivateRecipientAddresses() {
+    return this.recipientDirectory.getAddresses();
+  }
+
+  /**
+   * Get revealed public key for a single address
+   * @param {string} address - Recipient address
+   * @returns {Promise<string>} Normalized recipient public key
+   * @throws {MessageError} If pubkey is not revealed or RPC fails
+   */
+  async getRecipientPubkeyForAddress(address) {
+    return this.recipientDirectory.getPubkeyForAddress(address);
+  }
+
+  /**
+   * Parse message input to detect private messages
+   * @param {string} message - Raw message input
+   * @returns {{messageType: string, message: string, recipientAddress: (string|null)}}
+   * @throws {MessageError} If private format is invalid
+   */
+  parseMessageInput(message) {
+    const trimmed = message.trim();
+
+    if (!trimmed.startsWith('@')) {
+      return { messageType: MESSAGE_TYPES.GROUP, message: trimmed, recipientAddress: null };
     }
 
-    if (recipientPubKeys.length === 0) {
-      throw new MessageError(ERROR_MESSAGES.NO_RECIPIENTS);
+    const match = trimmed.match(/^@(\S+)\s+(.+)$/);
+
+    if (!match) {
+      throw new MessageError(ERROR_MESSAGES.INVALID_PRIVATE_MESSAGE_FORMAT);
     }
 
-    return recipientPubKeys;
+    const recipientAddress = match[1];
+    const privateMessage = match[2].trim();
+
+    return { messageType: MESSAGE_TYPES.PRIVATE, message: privateMessage, recipientAddress };
   }
 
   /**
    * Build encrypted DePIN message
    * @param {string} message - Plaintext message
    * @param {Array<string>} recipientPubKeys - Array of recipient public keys
+   * @param {"private"|"group"} messageType - Message type
    * @returns {Promise<Object>} Build result with hex payload
    */
-  async buildEncryptedMessage(message, recipientPubKeys) {
+  async buildEncryptedMessage(message, recipientPubKeys, messageType) {
     return await this.neuraiDepinMsg.buildDepinMessage({
       token: this.config.token,
       senderAddress: this.walletManager.getAddress(),
@@ -99,7 +141,8 @@ export class MessageSender {
       privateKey: this.walletManager.getPrivateKeyHex(),
       timestamp: Math.floor(Date.now() / 1000),
       message: message,
-      recipientPubKeys: recipientPubKeys
+      recipientPubKeys: recipientPubKeys,
+      messageType: messageType
     });
   }
 
@@ -138,13 +181,16 @@ export class MessageSender {
   }
 
   /**
-   * Send a broadcast message to all token holders
+   * Send a group or private message
    * @param {string} message - Plaintext message to send
    * @returns {Promise<Object>} Result object with hash and recipient count
    * @returns {Promise<Object>} result
    * @returns {string} result.hash - Transaction hash
    * @returns {number} result.recipients - Number of recipients
    * @returns {number} result.timestamp - Send timestamp
+   * @returns {"private"|"group"} result.messageType - Message type
+   * @returns {string|null} result.recipientAddress - Target address for private messages
+   * @returns {string} result.messageHash - Message hash used for deduplication
    * @throws {MessageError} If sending fails
    */
   async send(message) {
@@ -158,14 +204,23 @@ export class MessageSender {
         }
       }
 
-      // 1. Get all token holders (broadcast)
-      const addresses = await this.getTokenHolders();
+      const parsed = this.parseMessageInput(message);
+      let recipientPubKeys = [];
 
-      // 2. Get pubkeys from all recipients
-      const recipientPubKeys = await this.getRecipientPubkeys(addresses);
+      if (parsed.messageType === 'private') {
+        const recipientPubkey = await this.getRecipientPubkeyForAddress(parsed.recipientAddress);
+        recipientPubKeys = [recipientPubkey];
+      } else {
+        // 1. Get pubkeys from all recipients (broadcast)
+        recipientPubKeys = await this.getRecipientPubkeys();
+      }
 
       // 3. Build encrypted message
-      const buildResult = await this.buildEncryptedMessage(message, recipientPubKeys);
+      const buildResult = await this.buildEncryptedMessage(
+        parsed.message,
+        recipientPubKeys,
+        parsed.messageType
+      );
 
       // 4. Wrap with server privacy layer if enabled
       const payload = await this.wrapWithPrivacyLayer(buildResult.hex);
@@ -178,8 +233,11 @@ export class MessageSender {
 
       return {
         hash: result.hash || result.txid,
-        recipients: recipientPubKeys.length,
-        timestamp: Math.floor(Date.now() / 1000)
+        recipients: parsed.messageType === 'private' ? 1 : recipientPubKeys.length,
+        timestamp: Math.floor(Date.now() / 1000),
+        messageType: parsed.messageType,
+        recipientAddress: parsed.recipientAddress,
+        messageHash: buildResult.messageHash
       };
     } catch (error) {
       // Mark as disconnected on error

package/src/messaging/MessageStore.js

@@ -19,6 +19,9 @@ export class MessageStore {
 
     /** @type {Set<string>} Set of seen message keys for deduplication */
     this.seenHashes = new Set();
+
+    /** @type {Map<string, string>} Map of outgoing private message hash to recipient */
+    this.outgoingPrivateRecipients = new Map();
   }
 
   /**
@@ -30,6 +33,8 @@ export class MessageStore {
    * @param {number} msg.timestamp - Unix timestamp in seconds
    * @param {string} msg.sender - Sender address
    * @param {string} msg.message - Message content
+   * @param {string} [msg.messageType] - Message type ("group" or "private")
+   * @param {string} [msg.peerAddress] - Peer address for private messages
    * @returns {boolean} True if message is new, false if duplicate
    */
   addMessage(msg) {
@@ -48,6 +53,26 @@ export class MessageStore {
     return true; // New message added
   }
 
+  /**
+   * Register a private message recipient by message hash
+   * @param {string} hash - Message hash
+   * @param {string} recipientAddress - Recipient address
+   */
+  registerOutgoingPrivateMessage(hash, recipientAddress) {
+    if (hash && recipientAddress) {
+      this.outgoingPrivateRecipients.set(hash, recipientAddress);
+    }
+  }
+
+  /**
+   * Get recipient address for a private message hash
+   * @param {string} hash - Message hash
+   * @returns {string|null} Recipient address or null
+   */
+  getOutgoingPrivateRecipient(hash) {
+    return this.outgoingPrivateRecipients.get(hash) || null;
+  }
+
   /**
    * Get all stored messages
    * @returns {Array<Object>} Copy of messages array
@@ -84,6 +109,7 @@ export class MessageStore {
   clear() {
     this.messages = [];
     this.seenHashes.clear();
+    this.outgoingPrivateRecipients.clear();
   }
 
   /**

package/src/messaging/RecipientDirectory.js

@@ -0,0 +1,186 @@
+/**
+ * Recipient directory for DePIN messaging
+ * Shared cache for addresses, pubkeys, and recipient hash lookups.
+ * @module RecipientDirectory
+ */
+
+import {
+  RPC_METHODS,
+  ERROR_MESSAGES,
+  RECIPIENT_CACHE
+} from '../constants.js';
+import { MessageError } from '../errors.js';
+import { normalizePubkey } from '../utils.js';
+
+export class RecipientDirectory {
+  constructor(config, rpcService, neuraiDepinMsg) {
+    this.config = config;
+    this.rpcService = rpcService;
+    this.neuraiDepinMsg = neuraiDepinMsg;
+    this.cache = {
+      entries: [],
+      updatedAt: 0,
+      pending: null
+    };
+    this.hashCache = {
+      map: new Map(),
+      updatedAt: 0,
+      pending: null
+    };
+  }
+
+  getRpc() {
+    return this.rpcService.call.bind(this.rpcService);
+  }
+
+  async fetchEntries() {
+    const rpc = this.getRpc();
+
+    try {
+      const result = await rpc(RPC_METHODS.LIST_DEPIN_ADDRESSES, [this.config.token]);
+
+      if (!Array.isArray(result)) {
+        throw new MessageError('Invalid response from listdepinaddresses');
+      }
+
+      const entries = result
+        .filter((entry) => entry && entry.address && entry.pubkey)
+        .map((entry) => ({
+          address: entry.address,
+          pubkey: normalizePubkey(entry.pubkey)
+        }));
+
+      if (entries.length === 0) {
+        throw new MessageError(ERROR_MESSAGES.NO_RECIPIENTS);
+      }
+
+      return entries;
+    } catch (error) {
+      if (error instanceof MessageError) {
+        throw error;
+      }
+      throw new MessageError(`Failed to fetch recipient list: ${error.message}`);
+    }
+  }
+
+  async refresh(force = false) {
+    const now = Date.now();
+    const hasCache = this.cache.entries.length > 0;
+    const isFresh = now - this.cache.updatedAt < RECIPIENT_CACHE.REFRESH_MS;
+
+    if (!force && hasCache && isFresh) {
+      return this.cache.entries;
+    }
+
+    if (this.cache.pending) {
+      return this.cache.pending;
+    }
+
+    this.cache.pending = (async () => {
+      const entries = await this.fetchEntries();
+      this.cache.entries = entries;
+      this.cache.updatedAt = Date.now();
+      return entries;
+    })();
+
+    try {
+      return await this.cache.pending;
+    } catch (error) {
+      if (hasCache) {
+        return this.cache.entries;
+      }
+      throw error;
+    } finally {
+      this.cache.pending = null;
+    }
+  }
+
+  getCachedEntries() {
+    return this.cache.entries;
+  }
+
+  getCachedAddresses() {
+    if (!this.cache.entries.length) {
+      return [];
+    }
+    return this.cache.entries.map((entry) => entry.address).sort();
+  }
+
+  async getEntries() {
+    return this.refresh();
+  }
+
+  async getAddresses() {
+    const entries = await this.refresh();
+    return entries.map((entry) => entry.address).sort();
+  }
+
+  async getPubkeys() {
+    const entries = await this.refresh();
+    return entries.map((entry) => entry.pubkey);
+  }
+
+  async getPubkeyForAddress(address) {
+    let recipients = await this.refresh();
+    let match = recipients.find((entry) => entry.address === address);
+
+    if (!match) {
+      recipients = await this.refresh(true);
+      match = recipients.find((entry) => entry.address === address);
+    }
+
+    if (!match) {
+      throw new MessageError(`${ERROR_MESSAGES.RECIPIENT_PUBKEY_NOT_REVEALED}: ${address}`);
+    }
+
+    return match.pubkey;
+  }
+
+  async getHashMap(force = false) {
+    const now = Date.now();
+    const hasCache = this.hashCache.map.size > 0;
+    const isFresh = now - this.hashCache.updatedAt < RECIPIENT_CACHE.REFRESH_MS;
+
+    if (!force && hasCache && isFresh) {
+      return this.hashCache.map;
+    }
+
+    if (this.hashCache.pending) {
+      return this.hashCache.pending;
+    }
+
+    this.hashCache.pending = (async () => {
+      const entries = await this.refresh(force);
+      const utils = this.neuraiDepinMsg?.utils;
+      if (!utils?.hexToBytes || !utils?.bytesToHex || !utils?.hash160) {
+        return this.hashCache.map;
+      }
+
+      const nextMap = new Map();
+      for (const entry of entries) {
+        const pubkeyBytes = utils.hexToBytes(entry.pubkey);
+        const hashBytes = await utils.hash160(pubkeyBytes);
+        const hashHex = utils.bytesToHex(hashBytes).toLowerCase();
+        nextMap.set(hashHex, entry.address);
+
+        const reversedHex = utils.bytesToHex(hashBytes.slice().reverse()).toLowerCase();
+        if (!nextMap.has(reversedHex)) {
+          nextMap.set(reversedHex, entry.address);
+        }
+      }
+
+      if (nextMap.size > 0) {
+        this.hashCache.map = nextMap;
+        this.hashCache.updatedAt = Date.now();
+      }
+
+      return this.hashCache.map;
+    })();
+
+    try {
+      return await this.hashCache.pending;
+    } finally {
+      this.hashCache.pending = null;
+    }
+  }
+}