@neuraiproject/neurai-depin-terminal 1.0.0

package/src/lib/depinMsgLoader.js

@@ -0,0 +1,73 @@
+/**
+ * DePIN message library loader
+ * Loads the IIFE bundle from @neuraiproject/neurai-depin-msg
+ * @module depinMsgLoader
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { LibraryError } from '../errors.js';
+import { ERROR_MESSAGES } from '../constants.js';
+
+// Handle both ESM and CJS (for bundling)
+// We use a check that doesn't trigger esbuild warnings for CJS targets
+const getDirname = () => {
+  try {
+    if (typeof __dirname !== 'undefined') return __dirname;
+    return path.dirname(fileURLToPath(import.meta.url));
+  } catch (e) {
+    return process.cwd();
+  }
+};
+
+const _dirname = getDirname();
+
+/**
+ * Path to the neurai-depin-msg bundle
+ * Checks multiple locations to support both development and bundled environments
+ */
+const possiblePaths = [
+  path.join(_dirname, '../../node_modules/@neuraiproject/neurai-depin-msg/dist/neurai-depin-msg.js'),
+  path.join(_dirname, '../node_modules/@neuraiproject/neurai-depin-msg/dist/neurai-depin-msg.js'),
+  path.join(process.cwd(), 'node_modules/@neuraiproject/neurai-depin-msg/dist/neurai-depin-msg.js')
+];
+
+const BUNDLE_PATH = possiblePaths.find(p => fs.existsSync(p)) || possiblePaths[0];
+
+/**
+ * Load the DePIN message library IIFE bundle into globalThis
+ * The library provides functions for building, encrypting, and decrypting DePIN messages
+ * @returns {Promise<Object>} The neuraiDepinMsg library object
+ * @throws {LibraryError} If bundle not found or fails to load
+ */
+export async function loadDepinMsgLibrary() {
+  // Check if bundle exists
+  if (!fs.existsSync(BUNDLE_PATH)) {
+    throw new LibraryError(
+      'neurai-depin-msg bundle not found. Please run: npm install'
+    );
+  }
+
+  try {
+    // Read bundle code
+    const bundleCode = fs.readFileSync(BUNDLE_PATH, 'utf-8');
+
+    // Execute IIFE in global context
+    // The bundle assigns to globalThis.neuraiDepinMsg
+    const scriptFunction = new Function(bundleCode);
+    scriptFunction();
+
+    // Verify library loaded successfully
+    if (!globalThis.neuraiDepinMsg) {
+      throw new LibraryError(ERROR_MESSAGES.LIBRARY_LOAD_FAILED);
+    }
+
+    return globalThis.neuraiDepinMsg;
+  } catch (error) {
+    if (error instanceof LibraryError) {
+      throw error;
+    }
+    throw new LibraryError(`${ERROR_MESSAGES.LIBRARY_LOAD_FAILED}: ${error.message}`);
+  }
+}

package/src/lib/empty.js

@@ -0,0 +1,2 @@
+// Empty file to stub optional dependencies
+export default {};

package/src/messaging/MessagePoller.js

@@ -0,0 +1,300 @@
+/**
+ * Message poller for Neurai DePIN Terminal
+ * Handles automatic polling for new messages
+ * @module MessagePoller
+ */
+
+import { EventEmitter } from 'events';
+import { RPC_METHODS } from '../constants.js';
+import { isEncryptedResponse } from '../utils.js';
+
+/**
+ * Polls for new DePIN messages at regular intervals
+ * @extends EventEmitter
+ * @fires MessagePoller#message
+ * @fires MessagePoller#poll-complete
+ * @fires MessagePoller#error
+ * @fires MessagePoller#reconnected
+ */
+export class MessagePoller extends EventEmitter {
+  /**
+   * Create a new MessagePoller instance
+   * @param {Object} config - Configuration object
+   * @param {string} config.token - DePIN token name
+   * @param {number} config.pollInterval - Polling interval in milliseconds
+   * @param {RpcService} rpcService - RPC service instance
+   * @param {MessageStore} messageStore - Message store instance
+   * @param {Object} neuraiDepinMsg - DePIN message library
+   * @param {WalletManager} walletManager - Wallet manager instance (for decryption)
+   */
+  constructor(config, rpcService, messageStore, neuraiDepinMsg, walletManager) {
+    super();
+    this.config = config;
+    this.rpcService = rpcService;
+    this.messageStore = messageStore;
+    this.neuraiDepinMsg = neuraiDepinMsg;
+    this.walletManager = walletManager;
+    this.intervalId = null;
+    this.isPolling = false;
+    this.wasDisconnected = false; // Track if we were disconnected
+  }
+
+  /**
+   * Get current RPC client (dynamically to handle reconnections)
+   * @returns {Function} RPC function
+   */
+  getRpc() {
+    return this.rpcService.call.bind(this.rpcService);
+  }
+
+  /**
+   * Start polling at configured interval
+   */
+  start() {
+    if (this.intervalId) {
+      return;
+    }
+    this.poll(); // Initial poll
+    this.intervalId = setInterval(() => this.poll(), this.config.pollInterval);
+  }
+
+  /**
+   * Stop polling
+   */
+  stop() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+
+  /**
+   * Build RPC parameters for depinreceivemsg
+   * Includes incremental timestamp for efficiency
+   * @param {boolean} [forceFullPoll=false] - If true, fetch all messages without timestamp filter
+   * @returns {Array} RPC parameters
+   */
+  buildRpcParams(forceFullPoll = false) {
+    const params = [this.config.token, this.walletManager.getAddress()];
+
+    // If forcing full poll (after reconnection), don't include timestamp
+    if (forceFullPoll) {
+      return params;
+    }
+
+    const lastTimestamp = this.messageStore.getLastTimestamp();
+
+    if (lastTimestamp > 0) {
+      params.push(lastTimestamp);
+    }
+
+    return params;
+  }
+
+  /**
+   * Unwrap server privacy layer if present
+   * @param {Object} result - RPC result
+   * @returns {Promise<Object>} Unwrapped result
+   */
+  async unwrapPrivacyLayer(result) {
+    if (!isEncryptedResponse(result)) {
+      return result;
+    }
+
+    const decryptedJson = await this.neuraiDepinMsg.unwrapMessageFromServer(
+      result.encrypted,
+      this.walletManager.getPrivateKeyHex()
+    );
+
+    return JSON.parse(decryptedJson);
+  }
+
+  /**
+   * Fetch pool information from RPC
+   * @returns {Promise<Object|null>} Pool info or null if failed
+   */
+  async fetchPoolInfo() {
+    try {
+      return await this.rpcService.call(RPC_METHODS.DEPIN_GET_MSG_INFO, []);
+    } catch (error) {
+      return null; // Non-fatal, continue without pool info
+    }
+  }
+
+  /**
+   * Poll for new messages
+   * Emits 'poll-complete' on success, 'error' on failure
+   * Automatically attempts reconnection if disconnected
+   * @returns {Promise<void>}
+   */
+  async poll() {
+    if (this.isPolling) {
+      return; // Avoid concurrent polling
+    }
+
+    this.isPolling = true;
+
+    try {
+      // Do not attempt reconnection here.
+      // Reconnection is handled by the verification loop (aligned with the UI countdown).
+      if (!this.rpcService.isConnected()) {
+        throw new Error('RPC server not available');
+      }
+
+      // Call depinreceivemsg
+      // If recovering from disconnect, do full poll to get all messages
+      const forceFull = this.wasDisconnected;
+      const params = this.buildRpcParams(forceFull);
+      const rpc = this.getRpc();
+      let result = await rpc(RPC_METHODS.DEPIN_RECEIVE_MSG, params);
+
+      // Mark as connected on successful call
+      this.walletManager.connected = true;
+      this.rpcService.connected = true;
+
+      // Unwrap privacy layer if present
+      result = await this.unwrapPrivacyLayer(result);
+
+      // Process messages
+      const messages = Array.isArray(result) ? result : [];
+      let newMessagesCount = 0;
+
+      for (const msg of messages) {
+        const processed = await this.processMessage(msg);
+        if (processed) {
+          newMessagesCount++;
+        }
+      }
+
+      // Get pool info
+      const poolInfo = await this.fetchPoolInfo();
+
+      /**
+       * Poll complete event
+       * @event MessagePoller#poll-complete
+       * @type {Object}
+       * @property {Date} date - Poll completion time
+       * @property {number} newMessages - Number of new messages
+       * @property {number} totalMessages - Total messages in store
+       * @property {Object|null} poolInfo - Pool information from RPC
+       */
+      this.emit('poll-complete', {
+        date: new Date(),
+        newMessages: newMessagesCount,
+        totalMessages: this.messageStore.getCount(),
+        poolInfo: poolInfo
+      });
+
+      // Emit reconnection event only once after successful poll
+      if (this.wasDisconnected) {
+        this.wasDisconnected = false;
+        this.emit('reconnected');
+      }
+
+    } catch (error) {
+      // Mark as disconnected on error
+      this.walletManager.connected = false;
+      this.rpcService.connected = false;
+      this.wasDisconnected = true;
+
+      /**
+       * Error event
+       * @event MessagePoller#error
+       * @type {Error}
+       */
+      this.emit('error', error);
+    } finally {
+      this.isPolling = false;
+    }
+  }
+
+  /**
+   * Reconnected event - emitted when RPC connection is restored
+   * @event MessagePoller#reconnected
+   */
+
+  /**
+   * Validate message has required fields
+   * @param {Object} msg - Message to validate
+   * @returns {boolean} True if valid
+   */
+  isValidMessage(msg) {
+    return Boolean(
+      msg &&
+      msg.hash &&
+      msg.signature_hex &&
+      msg.encrypted_payload_hex
+    );
+  }
+
+  /**
+   * Decrypt message payload
+   * @param {string} encryptedPayloadHex - Encrypted payload in hex format
+   * @returns {Promise<string|null>} Decrypted plaintext or null if failed
+   */
+  async decryptPayload(encryptedPayloadHex) {
+    try {
+      return await this.neuraiDepinMsg.decryptDepinReceiveEncryptedPayload(
+        encryptedPayloadHex,
+        this.walletManager.getPrivateKeyHex()
+      );
+    } catch (error) {
+      return null; // Not for us or malformed
+    }
+  }
+
+  /**
+   * Process a single message
+   * Validates, decrypts, deduplicates, and emits if new
+   * @param {Object} msg - Raw message from RPC
+   * @returns {Promise<boolean>} True if message was new and processed
+   */
+  async processMessage(msg) {
+    try {
+      // Validate required fields
+      if (!this.isValidMessage(msg)) {
+        return false;
+      }
+
+      // Decrypt payload
+      const plaintext = await this.decryptPayload(msg.encrypted_payload_hex);
+
+      if (!plaintext) {
+        return false; // Not for us or malformed
+      }
+
+      // 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
+      });
+
+      if (isNew) {
+        /**
+         * Message event
+         * @event MessagePoller#message
+         * @type {Object}
+         * @property {string} sender - Sender address
+         * @property {string} message - Decrypted message content
+         * @property {number} timestamp - Unix timestamp in seconds
+         * @property {string} hash - Message hash
+         */
+        this.emit('message', {
+          sender: msg.sender,
+          message: plaintext,
+          timestamp: msg.timestamp,
+          hash: msg.hash
+        });
+        return true;
+      }
+
+      return false;
+    } catch (error) {
+      // Error decrypting individual message, skip
+      return false;
+    }
+  }
+}

package/src/messaging/MessageSender.js

@@ -0,0 +1,194 @@
+/**
+ * Message sender for Neurai DePIN Terminal
+ * Handles sending broadcast messages to all token holders
+ * @module MessageSender
+ */
+
+import {
+  RPC_METHODS,
+  ERROR_MESSAGES
+} from '../constants.js';
+import { MessageError, DepinError } from '../errors.js';
+import { isPubkeyRevealed, normalizePubkey, hasPrivacyLayer } from '../utils.js';
+
+/**
+ * Sends DePIN messages to all token holders
+ */
+export class MessageSender {
+  /**
+   * Create a new MessageSender instance
+   * @param {Object} config - Configuration object
+   * @param {string} config.token - DePIN token name
+   * @param {WalletManager} walletManager - Wallet manager instance
+   * @param {RpcService} rpcService - RPC service instance
+   * @param {Object} neuraiDepinMsg - DePIN message library
+   */
+  constructor(config, walletManager, rpcService, neuraiDepinMsg) {
+    this.config = config;
+    this.walletManager = walletManager;
+    this.rpcService = rpcService;
+    this.neuraiDepinMsg = neuraiDepinMsg;
+  }
+
+  /**
+   * Get current RPC client (dynamically to handle reconnections)
+   * @returns {Function} RPC function
+   */
+  getRpc() {
+    return this.rpcService.call.bind(this.rpcService);
+  }
+
+  /**
+   * Get all addresses holding the token
+   * @returns {Promise<Array<string>>} Array of addresses
+   * @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);
+
+    if (addresses.length === 0) {
+      throw new MessageError(ERROR_MESSAGES.NO_TOKEN_HOLDERS);
+    }
+
+    return addresses;
+  }
+
+  /**
+   * Get revealed public keys from addresses
+   * @param {Array<string>} addresses - Array of addresses
+   * @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();
+
+    for (const addr of addresses) {
+      try {
+        const res = await rpc(RPC_METHODS.GET_PUBKEY, [addr]);
+
+        if (isPubkeyRevealed(res)) {
+          recipientPubKeys.push(normalizePubkey(res.pubkey));
+        }
+      } catch (error) {
+        // Skip addresses without revealed pubkey
+        continue;
+      }
+    }
+
+    if (recipientPubKeys.length === 0) {
+      throw new MessageError(ERROR_MESSAGES.NO_RECIPIENTS);
+    }
+
+    return recipientPubKeys;
+  }
+
+  /**
+   * Build encrypted DePIN message
+   * @param {string} message - Plaintext message
+   * @param {Array<string>} recipientPubKeys - Array of recipient public keys
+   * @returns {Promise<Object>} Build result with hex payload
+   */
+  async buildEncryptedMessage(message, recipientPubKeys) {
+    return await this.neuraiDepinMsg.buildDepinMessage({
+      token: this.config.token,
+      senderAddress: this.walletManager.getAddress(),
+      senderPubKey: this.walletManager.getPublicKey(),
+      privateKey: this.walletManager.getPrivateKeyHex(),
+      timestamp: Math.floor(Date.now() / 1000),
+      message: message,
+      recipientPubKeys: recipientPubKeys
+    });
+  }
+
+  /**
+   * Wrap message with server privacy layer if enabled
+   * @param {string} payloadHex - Message payload in hex format
+   * @returns {Promise<string>} Wrapped payload or original if no privacy
+   */
+  async wrapWithPrivacyLayer(payloadHex) {
+    try {
+      const rpc = this.getRpc();
+      const msgInfo = await rpc(RPC_METHODS.DEPIN_GET_MSG_INFO, []);
+
+      if (hasPrivacyLayer(msgInfo)) {
+        return await this.neuraiDepinMsg.wrapMessageForServer(
+          payloadHex,
+          msgInfo.depinpoolpkey,
+          this.walletManager.getAddress()
+        );
+      }
+    } catch (error) {
+      // If depingetmsginfo fails, continue without privacy layer
+    }
+
+    return payloadHex;
+  }
+
+  /**
+   * Submit message to DePIN pool
+   * @param {string} payload - Message payload (potentially wrapped)
+   * @returns {Promise<Object>} Submission result with hash/txid
+   */
+  async submitToPool(payload) {
+    const rpc = this.getRpc();
+    return await rpc(RPC_METHODS.DEPIN_SUBMIT_MSG, [payload]);
+  }
+
+  /**
+   * Send a broadcast message to all token holders
+   * @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
+   * @throws {MessageError} If sending fails
+   */
+  async send(message) {
+    try {
+      // Attempt reconnection if not connected
+      if (!this.rpcService.isConnected()) {
+        const reconnected = await this.rpcService.attemptReconnect(true);
+
+        if (!reconnected) {
+          throw new MessageError('RPC server not available. Cannot send message.');
+        }
+      }
+
+      // 1. Get all token holders (broadcast)
+      const addresses = await this.getTokenHolders();
+
+      // 2. Get pubkeys from all recipients
+      const recipientPubKeys = await this.getRecipientPubkeys(addresses);
+
+      // 3. Build encrypted message
+      const buildResult = await this.buildEncryptedMessage(message, recipientPubKeys);
+
+      // 4. Wrap with server privacy layer if enabled
+      const payload = await this.wrapWithPrivacyLayer(buildResult.hex);
+
+      // 5. Send to pool
+      const result = await this.submitToPool(payload);
+
+      // Mark as connected on successful send
+      this.rpcService.connected = true;
+
+      return {
+        hash: result.hash || result.txid,
+        recipients: recipientPubKeys.length,
+        timestamp: Math.floor(Date.now() / 1000)
+      };
+    } catch (error) {
+      // Mark as disconnected on error
+      this.rpcService.connected = false;
+
+      if (error instanceof DepinError) {
+        throw error;
+      }
+      throw new MessageError(`Failed to send message: ${error.message}`);
+    }
+  }
+}

package/src/messaging/MessageStore.js

@@ -0,0 +1,99 @@
+/**
+ * Message store for Neurai DePIN Terminal
+ * Handles message storage and deduplication
+ * @module MessageStore
+ */
+
+import { createMessageKey } from '../utils.js';
+
+/**
+ * Stores and deduplicates DePIN messages
+ */
+export class MessageStore {
+  /**
+   * Create a new MessageStore instance
+   */
+  constructor() {
+    /** @type {Array<Object>} Stored messages sorted by timestamp */
+    this.messages = [];
+
+    /** @type {Set<string>} Set of seen message keys for deduplication */
+    this.seenHashes = new Set();
+  }
+
+  /**
+   * Add a message to the store with deduplication
+   * Deduplication key format: hash|signature
+   * @param {Object} msg - Message object
+   * @param {string} msg.hash - Message hash
+   * @param {string} msg.signature - Message signature
+   * @param {number} msg.timestamp - Unix timestamp in seconds
+   * @param {string} msg.sender - Sender address
+   * @param {string} msg.message - Message content
+   * @returns {boolean} True if message is new, false if duplicate
+   */
+  addMessage(msg) {
+    const key = createMessageKey(msg.hash, msg.signature);
+
+    if (this.seenHashes.has(key)) {
+      return false; // Duplicate message
+    }
+
+    this.seenHashes.add(key);
+    this.messages.push(msg);
+
+    // Keep messages sorted by timestamp (oldest first)
+    this.messages.sort((a, b) => a.timestamp - b.timestamp);
+
+    return true; // New message added
+  }
+
+  /**
+   * Get all stored messages
+   * @returns {Array<Object>} Copy of messages array
+   */
+  getMessages() {
+    return [...this.messages];
+  }
+
+  /**
+   * Get the latest timestamp from stored messages
+   * Used for incremental polling
+   * @returns {number} Latest timestamp or 0 if no messages
+   */
+  getLastTimestamp() {
+    if (this.messages.length === 0) {
+      return 0;
+    }
+
+    return Math.max(...this.messages.map(m => m.timestamp));
+  }
+
+  /**
+   * Get total count of stored messages
+   * @returns {number} Number of messages
+   */
+  getCount() {
+    return this.messages.length;
+  }
+
+  /**
+   * Clear all stored messages
+   * Useful for testing or resetting state
+   */
+  clear() {
+    this.messages = [];
+    this.seenHashes.clear();
+  }
+
+  /**
+   * Check if a message exists by hash and signature
+   * @param {string} hash - Message hash
+   * @param {string} signature - Message signature
+   * @returns {boolean} True if message exists
+   */
+  hasMessage(hash, signature) {
+    const key = createMessageKey(hash, signature);
+    return this.seenHashes.has(key);
+  }
+}