jaelis-node 1.8.0 → 1.9.0

package/README.md

@@ -169,7 +169,24 @@ Options:
 
 ## Block Sync & Node Status
 
-Your node automatically syncs with the JAELIS network:
+Your node automatically syncs with the JAELIS network using **WebSocket push notifications** (like Ethereum's `newHeads` subscription) for real-time updates:
+
+```
+[SYNC] Starting sync from https://rpc.jaelis.io
+[SYNC] Syncing 25 blocks (1 → 25)
+[SYNC] Local height: 25/139
+[SYNC] Syncing 25 blocks (26 → 50)
+...
+[SYNC] Local height: 139/139
+[SYNC] WebSocket connected! Subscribing to newHeads...
+[SYNC] ✓ Subscribed to newHeads (id: 0x1)
+[SYNC] Listening for new blocks via WebSocket...
+```
+
+**Sync Features:**
+- **Smart batching** - 25 blocks during initial sync, reduces as you get closer
+- **WebSocket subscriptions** - Real-time block notifications (no polling!)
+- **Automatic fallback** - Falls back to HTTP polling if WebSocket unavailable
 
 ```bash
 # Check sync status
@@ -215,6 +232,42 @@ curl -X POST https://rpc.jaelis.io \
 }
 ```
 
+## WebSocket Subscriptions
+
+Connect to the WebSocket endpoint for real-time updates:
+
+```javascript
+const WebSocket = require('ws');
+const ws = new WebSocket('wss://rpc.jaelis.io/ws');
+
+ws.on('open', () => {
+    // Subscribe to new block headers
+    ws.send(JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'jaelis_subscribe',
+        params: ['newHeads'],
+        id: 1
+    }));
+});
+
+ws.on('message', (data) => {
+    const msg = JSON.parse(data);
+    if (msg.method === 'jaelis_subscription') {
+        console.log('New block:', msg.params.result.number);
+    }
+});
+```
+
+**Available Subscriptions:**
+| Subscription | Description |
+|--------------|-------------|
+| `newHeads` | New block headers as they're produced (real-time sync) |
+| `newPendingTransactions` | Transaction hashes entering mempool |
+| `logs` | Contract event logs (with filter options) |
+| `syncing` | Sync status changes |
+
+> **Note:** JAELIS uses Proof of Efficient Consensus (PoEC), not mining. Blocks are produced by validators, not mined. The `newHeads` subscription keeps your node synced in real-time.
+
 ## RPC Methods
 
 Your node exposes standard JSON-RPC plus JAELIS-specific methods:

package/bin/jaelis-node.js

@@ -36,16 +36,29 @@ const BANNER = `
 `;
 
 // Network configurations
+// Bootstrap nodes use libp2p multiaddr format: /dns4/host/tcp/port/p2p/PEER_ID
+//
+// IMPORTANT: libp2p requires peer ID for direct dialing!
+// Format: /dns4/rpc.jaelis.io/tcp/30304/p2p/12D3KooW...
+//
+// How it works (like Ethereum):
+// 1. Main node generates persistent peer ID on first run
+// 2. Peer ID is saved to disk (jaelis-data/peer-id.json)
+// 3. Main node logs bootstrap multiaddr on startup
+// 4. Update bootstrapNodes here with that multiaddr
+//
+// If no bootstrap nodes configured, RPC fallback sync is used automatically
 const NETWORKS = {
     testnet: {
         chainId: 4545,
         name: 'JAELIS Testnet',
         symbol: 'tJAELIS',
         rpcUrl: 'https://rpc.jaelis.io',
-        // Bootstrap via DNS - rpc.jaelis.io resolves to 73.116.51.60
-        // No peer ID needed - learned during libp2p handshake
+        // Testnet P2P port: 30304 (mainnet: 30303)
+        // Bootstrap nodes will be added once main node generates peer ID
+        // Until then, nodes sync via RPC fallback (works perfectly)
         bootstrapNodes: [
-            '/dns4/rpc.jaelis.io/tcp/30303'
+            // Will be: '/dns4/rpc.jaelis.io/tcp/30304/p2p/PEER_ID'
         ]
     },
     mainnet: {

package/lib/index.js

@@ -333,6 +333,12 @@ class NodeWalletConfig {
 }
 
 // JAELIS Network Endpoints - users connect here automatically
+// Bootstrap nodes use libp2p multiaddr format: /dns4/host/tcp/port/p2p/PEER_ID
+// External nodes connect via DNS which resolves to the main node's public IP
+//
+// IMPORTANT: Peer ID is required for libp2p dialing!
+// The peer ID is generated on first run and persisted to disk.
+// Main node logs bootstrap info on startup - update this when it changes.
 const JAELIS_NETWORKS = {
     testnet: {
         name: 'JAELIS Testnet',
@@ -341,8 +347,12 @@ const JAELIS_NETWORKS = {
         rpcUrl: 'https://rpc.jaelis.io',
         wsUrl: 'wss://rpc.jaelis.io/ws',
         explorerUrl: 'https://explorer.jaelis.io',
+        // Testnet uses port 30304 (mainnet uses 30303)
+        // Peer ID will be added after main node first run
+        // For now, P2P will fallback to RPC sync until peer ID is configured
         bootstrapNodes: [
-            '/dns4/rpc.jaelis.io/tcp/30303'
+            // Format: /dns4/rpc.jaelis.io/tcp/30304/p2p/PEER_ID
+            // The main node outputs this on startup - update here when available
         ]
     },
     mainnet: {
@@ -1204,8 +1214,9 @@ class EmbeddedBlockchain {
     }
 }
 
-class EmbeddedNetwork {
+class EmbeddedNetwork extends EventEmitter {
     constructor(options = {}) {
+        super();
         this.port = options.port || 30303;
         this.host = options.host || '0.0.0.0';
         this.maxPeers = options.maxPeers || 50;
@@ -1221,16 +1232,24 @@ class EmbeddedNetwork {
     }
 
     async start() {
-        // Try libp2p first, fallback to RPC sync
-        try {
-            await this._startLibp2p();
-            this.isP2PConnected = true;
-            console.log(`[NETWORK] libp2p P2P network started on port ${this.port}`);
-        } catch (err) {
-            console.log(`[NETWORK] P2P failed (${err.message}), using RPC fallback`);
-            await this._startRPCFallback();
-            this.isRPCFallback = true;
-            console.log(`[NETWORK] RPC fallback active - syncing from ${this.remoteRpc}`);
+        // ALWAYS start RPC sync first - this is reliable through Cloudflare
+        // P2P is optional/additional for peer discovery
+        console.log(`[NETWORK] Starting RPC sync from ${this.remoteRpc}`);
+        await this._startRPCFallback();
+        this.isRPCFallback = true;
+
+        // Try P2P alongside (optional - for peer discovery when bootstrap nodes available)
+        if (this.bootstrapNodes && this.bootstrapNodes.length > 0) {
+            try {
+                await this._startLibp2p();
+                this.isP2PConnected = true;
+                console.log(`[NETWORK] P2P network also started on port ${this.port}`);
+            } catch (err) {
+                console.log(`[NETWORK] P2P unavailable (${err.message}), continuing with RPC only`);
+            }
+        } else {
+            console.log(`[NETWORK] No bootstrap nodes configured - using RPC sync only`);
+            console.log(`[NETWORK] This is fine! RPC sync is reliable and works through firewalls.`);
         }
     }
 
@@ -1296,7 +1315,8 @@ class EmbeddedNetwork {
             remoteHeight: 0,
             syncing: false,
             lastSync: null,
-            blocksDownloaded: 0
+            blocksDownloaded: 0,
+            mode: 'polling'  // 'websocket' or 'polling'
         };
 
         // Helper to make RPC calls to remote node
@@ -1322,7 +1342,7 @@ class EmbeddedNetwork {
                     headers: {
                         'Content-Type': 'application/json',
                         'Content-Length': Buffer.byteLength(data),
-                        'User-Agent': 'JAELIS-Node/1.7.0'  // Node sync traffic - exempt from rate limits
+                        'User-Agent': 'JAELIS-Node/1.8.0'  // Node sync traffic
                     }
                 }, (res) => {
                     let body = '';
@@ -1342,44 +1362,52 @@ class EmbeddedNetwork {
             });
         };
 
-        // Sync blocks from remote RPC using JAELIS NATIVE methods
-        const syncFromRPC = async () => {
-            if (this.syncState.syncing) return; // Already syncing
+        // Fetch and add a specific block
+        const fetchBlock = async (blockNum) => {
+            const blockHex = '0x' + blockNum.toString(16);
+            const block = await rpcCall('jaelis_getBlockByNumber', [blockHex, true]);
+            if (block && this.blockchain?.addBlock) {
+                await this.blockchain.addBlock(block);
+                this.syncState.blocksDownloaded++;
+                return true;
+            }
+            return false;
+        };
+
+        // Sync missing blocks (used for both initial sync and catching up)
+        const syncMissingBlocks = async () => {
+            if (this.syncState.syncing) return;
             this.syncState.syncing = true;
 
             try {
-                // 1. Get remote block height using NATIVE jaelis_blockNumber
                 const remoteHeightHex = await rpcCall('jaelis_blockNumber');
                 this.syncState.remoteHeight = parseInt(remoteHeightHex, 16);
-
-                // 2. Get local block height
                 this.syncState.localHeight = this.blockchain?.getHeight?.() || 0;
 
-                // 3. Sync missing blocks (batch of 10 at a time)
-                const blocksToSync = Math.min(10, this.syncState.remoteHeight - this.syncState.localHeight);
+                // Loop until fully synced
+                while (this.syncState.localHeight < this.syncState.remoteHeight) {
+                    const blocksToSync = this.syncState.remoteHeight - this.syncState.localHeight;
 
-                if (blocksToSync > 0) {
-                    console.log(`[SYNC] Syncing blocks ${this.syncState.localHeight + 1} to ${this.syncState.localHeight + blocksToSync} (remote: ${this.syncState.remoteHeight})`);
+                    // Batch size: larger during initial sync, smaller when near tip
+                    const batchSize = blocksToSync > 50 ? 25 : (blocksToSync > 10 ? 10 : blocksToSync);
 
-                    for (let i = 1; i <= blocksToSync; i++) {
-                        const blockNum = this.syncState.localHeight + i;
-                        const blockHex = '0x' + blockNum.toString(16);
+                    if (blocksToSync > 1) {
+                        console.log(`[SYNC] Syncing ${batchSize} blocks (${this.syncState.localHeight + 1} → ${this.syncState.localHeight + batchSize})`);
+                    }
 
-                        // Fetch full block with transactions using NATIVE jaelis_getBlockByNumber
-                        // This returns JAELIS-native fields (lodeUsed, consensus: PoEC, etc.)
-                        const block = await rpcCall('jaelis_getBlockByNumber', [blockHex, true]);
+                    for (let i = 1; i <= batchSize; i++) {
+                        await fetchBlock(this.syncState.localHeight + i);
+                    }
 
-                        if (block) {
-                            // Store block in local blockchain
-                            if (this.blockchain?.addBlock) {
-                                await this.blockchain.addBlock(block);
-                            }
-                            this.syncState.blocksDownloaded++;
-                        }
+                    this.syncState.localHeight += batchSize;
+
+                    if (batchSize > 1) {
+                        console.log(`[SYNC] Local height: ${this.syncState.localHeight}/${this.syncState.remoteHeight}`);
                     }
 
-                    this.syncState.localHeight += blocksToSync;
-                    console.log(`[SYNC] Downloaded ${blocksToSync} blocks. Local height: ${this.syncState.localHeight}`);
+                    // Re-check remote height in case new blocks arrived during sync
+                    const newRemoteHex = await rpcCall('jaelis_blockNumber');
+                    this.syncState.remoteHeight = parseInt(newRemoteHex, 16);
                 }
 
                 this.syncState.lastSync = Date.now();
@@ -1392,20 +1420,167 @@ class EmbeddedNetwork {
             }
         };
 
-        // Initial sync
-        console.log('[SYNC] Starting RPC fallback sync from', this.remoteRpc);
-        await syncFromRPC();
+        // ============================================================
+        // WEBSOCKET SUBSCRIPTION (PREFERRED - like Ethereum newHeads)
+        // ============================================================
+        const tryWebSocketSync = async () => {
+            try {
+                const WebSocket = require('ws');
+                const wsUrl = this.remoteRpc.replace('https://', 'wss://').replace('http://', 'ws://') + '/ws';
+
+                console.log(`[SYNC] Trying WebSocket subscription at ${wsUrl}`);
+
+                return new Promise((resolve, reject) => {
+                    const ws = new WebSocket(wsUrl, {
+                        headers: { 'User-Agent': 'JAELIS-Node/1.8.0' }
+                    });
+
+                    const timeout = setTimeout(() => {
+                        ws.close();
+                        reject(new Error('WebSocket connection timeout'));
+                    }, 10000);
+
+                    ws.on('open', () => {
+                        clearTimeout(timeout);
+                        console.log('[SYNC] WebSocket connected! Subscribing to newHeads...');
+
+                        // Subscribe to new block headers
+                        ws.send(JSON.stringify({
+                            jsonrpc: '2.0',
+                            method: 'jaelis_subscribe',
+                            params: ['newHeads'],
+                            id: 1
+                        }));
+
+                        this.syncState.mode = 'websocket';
+                        this.wsConnection = ws;
+                        resolve(true);
+                    });
+
+                    ws.on('message', async (data) => {
+                        try {
+                            const msg = JSON.parse(data.toString());
+
+                            // Subscription confirmation
+                            if (msg.id === 1 && msg.result) {
+                                console.log(`[SYNC] ✓ Subscribed to newHeads (id: ${msg.result})`);
+                                console.log('[SYNC] Listening for new blocks via WebSocket...');
+                                return;
+                            }
+
+                            // New block notification
+                            if (msg.method === 'jaelis_subscription' && msg.params?.result) {
+                                const header = msg.params.result;
+                                const blockNum = typeof header.number === 'string'
+                                    ? parseInt(header.number, 16)
+                                    : header.number;
+
+                                // Fetch and sync the new block
+                                if (blockNum > this.syncState.localHeight) {
+                                    // If we're behind, catch up first
+                                    await syncMissingBlocks();
+                                }
+
+                                this.syncState.remoteHeight = blockNum;
+                                this.emit('newBlock', header);
+                            }
+                        } catch (e) {
+                            // Ignore parse errors
+                        }
+                    });
+
+                    ws.on('error', (err) => {
+                        clearTimeout(timeout);
+                        reject(err);
+                    });
+
+                    ws.on('close', () => {
+                        console.log('[SYNC] WebSocket disconnected, falling back to polling...');
+                        this.syncState.mode = 'polling';
+                        this.wsConnection = null;
+                        // Fall back to polling
+                        startPolling();
+                    });
+                });
+            } catch (err) {
+                // WebSocket module not available or connection failed
+                return false;
+            }
+        };
+
+        // ============================================================
+        // HTTP POLLING FALLBACK (like traditional Geth sync)
+        // ============================================================
+        const SYNCED_INTERVAL = 6000;  // Poll every 6s when synced (2x block time)
+        const CATCHUP_INTERVAL = 500;  // Fast poll during catchup
+
+        const startPolling = () => {
+            if (this.syncInterval) return; // Already polling
+
+            console.log('[SYNC] Using HTTP polling mode');
+            this.syncState.mode = 'polling';
+
+            let pollInterval = CATCHUP_INTERVAL;
+            let lastHeight = 0;
+
+            const poll = async () => {
+                await syncMissingBlocks();
+
+                // Adjust polling speed based on sync status
+                const isSynced = this.syncState.localHeight >= this.syncState.remoteHeight;
+                const heightChanged = this.syncState.remoteHeight !== lastHeight;
+
+                if (isSynced && !heightChanged && pollInterval !== SYNCED_INTERVAL) {
+                    // Synced and no new blocks - slow down
+                    pollInterval = SYNCED_INTERVAL;
+                    clearInterval(this.syncInterval);
+                    this.syncInterval = setInterval(poll, pollInterval);
+                    console.log(`[SYNC] ✓ Synced at block ${this.syncState.localHeight}. Polling every ${pollInterval/1000}s`);
+                } else if (!isSynced && pollInterval !== CATCHUP_INTERVAL) {
+                    // Falling behind - speed up
+                    pollInterval = CATCHUP_INTERVAL;
+                    clearInterval(this.syncInterval);
+                    this.syncInterval = setInterval(poll, pollInterval);
+                }
+
+                lastHeight = this.syncState.remoteHeight;
+            };
+
+            // Start polling
+            this.syncInterval = setInterval(poll, pollInterval);
+        };
+
+        // ============================================================
+        // INITIAL SYNC
+        // ============================================================
+        console.log('[SYNC] Starting sync from', this.remoteRpc);
+
+        // Do initial block sync first
+        await syncMissingBlocks();
 
-        // Continue syncing every 3 seconds (JAELIS has 3-second blocks)
-        this.syncInterval = setInterval(syncFromRPC, 3000);
+        // Try WebSocket first (like Ethereum pub/sub), fall back to polling
+        const wsSuccess = await tryWebSocketSync().catch(() => false);
+
+        if (!wsSuccess) {
+            console.log('[SYNC] WebSocket unavailable, using HTTP polling');
+            startPolling();
+        }
     }
 
     async stop() {
+        // Close WebSocket connection if active
+        if (this.wsConnection) {
+            this.wsConnection.close();
+            this.wsConnection = null;
+        }
+        // Stop libp2p if active
         if (this.libp2p) {
             await this.libp2p.stop();
         }
+        // Stop polling interval if active
         if (this.syncInterval) {
             clearInterval(this.syncInterval);
+            this.syncInterval = null;
         }
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jaelis-node",
-  "version": "1.8.0",
-  "description": "Official JAELIS Blockchain Node - Universal VM (6 languages), LevelDB state persistence, native jaelis_* RPC, multi-ecosystem compatibility (eth/solana/move/ton/btc/wasm/starknet), Cross-Chain Settlement (30+ chains!), AI-native MCP integration",
+  "version": "1.9.0",
+  "description": "Official JAELIS Blockchain Node - WebSocket real-time sync, Universal VM (6 languages), LevelDB state persistence, native jaelis_* RPC, multi-ecosystem compatibility (eth/solana/move/ton/btc/wasm/starknet), Cross-Chain Settlement (30+ chains!), AI-native MCP integration",
   "main": "lib/index.js",
   "bin": {
     "jaelis-node": "./bin/jaelis-node.js"
@@ -72,7 +72,8 @@
     "express": "^4.18.2",
     "level": "^8.0.0",
     "libp2p": "^1.2.0",
-    "ora": "^5.4.1"
+    "ora": "^5.4.1",
+    "ws": "^8.18.3"
   },
   "files": [
     "bin/",