jaelis-node 2.1.0 → 2.2.1

package/README.md

@@ -41,8 +41,8 @@ npm install -g jaelis-node
 # Start on testnet (default)
 jaelis-node
 
-# Start on mainnet
-jaelis-node --network mainnet
+# Start on mainnet (coming soon — not yet live)
+# jaelis-node --network mainnet
 
 # Name your node (persists across restarts)
 jaelis-node --name MARBIT
@@ -173,10 +173,10 @@ JAELIS uses the `jaelis_*` namespace for all RPC methods:
 
 ## Network Info
 
-| Network | Chain ID | Main RPC | WebSocket |
-|---------|----------|----------|-----------|
-| Testnet | 4545 | https://rpc.jaelis.io | wss://rpc.jaelis.io/ws |
-| Mainnet | 4547 | https://mainnet.jaelis.io | wss://mainnet.jaelis.io/ws |
+| Network | Chain ID | Main RPC | WebSocket | Status |
+|---------|----------|----------|-----------|--------|
+| Testnet | 4545 | https://rpc.jaelis.io | wss://rpc.jaelis.io/ws | **Active** |
+| Mainnet | 4547 | https://mainnet.jaelis.io | wss://mainnet.jaelis.io/ws | **Coming Soon** |
 
 ## Why Run Your Own Node?
 
@@ -238,6 +238,12 @@ rm -rf ./jaelis-data
 jaelis-node
 ```
 
+## Agent Skills
+
+This package includes a `SKILL.md` file — a standardized skill document that AI agents can consume to learn how to run and manage JAELIS nodes autonomously. Compatible with Claude Code, Cursor, GitHub Copilot, and other agent platforms.
+
+See [SKILL.md](./SKILL.md) for the full agent skill specification.
+
 ## Links
 
 - **SDK:** [npmjs.com/package/jaelis.js](https://www.npmjs.com/package/jaelis.js)

package/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: jaelis-node
+description: "Run your own JAELIS blockchain node — sync with the network, expose local RPC, name your node. Lightweight external node for AI agents and developers."
+metadata:
+  emoji: "🔗"
+  homepage: "https://jaelis.io"
+  requires:
+    bins: ["jaelis-node"]
+---
+
+# JAELIS Node — Agent Skill
+
+Use when the user or agent wants to run their own JAELIS blockchain node: sync with the network, expose a local RPC endpoint, name the node, monitor sync status, or contribute to network decentralization. Running your own node gives you privacy, speed, and independence from public RPC endpoints.
+
+## Getting Started
+
+### Install
+
+```bash
+npm install -g jaelis-node
+```
+
+### Quick Start
+
+```bash
+# Start a named node on testnet (recommended — mainnet is not yet live)
+jaelis-node --name "MY-AGENT" --network testnet
+```
+
+> **Note:** Mainnet is coming soon. Use **testnet** for all current development and testing. Mainnet launch date will be announced by the JAELIS Foundation.
+
+The node will:
+1. Connect to the JAELIS network via WebSocket
+2. Sync and store blocks locally (LevelDB)
+3. Expose a local JSON-RPC server at `http://localhost:8545`
+4. Display sync status every 30 seconds
+
+### Architecture
+
+```
+┌─────────────────┐     WebSocket      ┌───────────────────┐
+│  JAELIS          │ ◄──────────────── │  Your Local Node  │
+│  Main Network    │                    │  (jaelis-node)    │
+│  rpc.jaelis.io   │ ──────────────► │                   │
+└─────────────────┘    newHeads        │  ┌─────────────┐  │
+                       subscription    │  │  LevelDB    │  │
+                                       │  │  Storage    │  │
+┌─────────────────┐     JSON-RPC       │  └─────────────┘  │
+│  Your dApp /    │ ◄──────────────── │                   │
+│  Agent          │    localhost:8545  │  ┌─────────────┐  │
+└─────────────────┘                    │  │  RPC Server │  │
+                                       │  └─────────────┘  │
+                                       └───────────────────┘
+```
+
+---
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n, --network <network>` | Network: `testnet` or `mainnet` (mainnet coming soon) | `testnet` |
+| `-p, --port <port>` | Local RPC server port | `8545` |
+| `-d, --data-dir <dir>` | Data directory for block storage | `./jaelis-data/<network>` |
+| `--name <name>` | Custom node name (persists across restarts) | Auto-generated ID |
+| `--no-rpc` | Disable local RPC server | Enabled |
+| `--version` | Show version | — |
+| `--help` | Show help | — |
+
+---
+
+## Node Naming
+
+Give your node a persistent identity:
+
+```bash
+# Name your node
+jaelis-node --name "MARBIT"
+
+# Name persists across restarts (stored in data dir)
+jaelis-node
+# Output: [STATUS] MARBIT | Block: 12345 | Uptime: 2h 15m 30s | RPC Requests: 42
+```
+
+Node names are stored in `{dataDir}/node-name.json` and persist across restarts. Set once, and it's remembered.
+
+---
+
+## Common Operations
+
+### Start a Node for AI Agent Use
+
+```bash
+# Install globally
+npm install -g jaelis-node
+
+# Start with a name on testnet
+jaelis-node --name "ALPHA-1" --network testnet
+
+# The agent can now connect to http://localhost:8545
+```
+
+### Connect Your dApp or SDK to Local Node
+
+```javascript
+const Jaelis = require('jaelis.js');
+
+// Point SDK at your local node instead of public RPC
+const provider = new Jaelis.Provider('http://localhost:8545');
+
+// All operations now go through your local node
+const blockNumber = await provider.getBlockNumber();
+const balance = await provider.getBalance('0x...');
+```
+
+### Use a Custom Port
+
+```bash
+# If port 8545 is taken
+jaelis-node --name "MY-NODE" --port 8546
+```
+
+### Use Custom Data Directory
+
+```bash
+# Store blocks in a specific location
+jaelis-node --name "MY-NODE" --data-dir /path/to/my-data
+```
+
+### Run Without RPC (Sync Only)
+
+```bash
+# Just sync blocks, don't expose RPC
+jaelis-node --name "SYNC-ONLY" --no-rpc
+```
+
+### Check Node Status via SDK CLI
+
+```bash
+# If you have jaelis.js installed too
+jaelis node status
+jaelis node status --rpc http://localhost:8545
+```
+
+---
+
+## Programmatic Usage
+
+Use `jaelis-node` as a library in your agent code:
+
+```javascript
+const { JaelisNode } = require('jaelis-node');
+
+async function main() {
+    const node = new JaelisNode({
+        network: 'testnet',
+        rpcPort: 8545,
+        dataDir: './my-jaelis-data',
+        nodeName: 'MY-AGENT',
+        enableRpc: true
+    });
+
+    // Event listeners
+    node.on('connected', () => console.log('Connected to network'));
+    node.on('block', (block) => console.log('New block:', block.number));
+    node.on('synced', () => console.log('Fully synced!'));
+    node.on('disconnected', () => console.log('Disconnected'));
+
+    // Start the node
+    await node.start();
+
+    // Get status
+    const status = node.getStatus();
+    console.log('Node:', status.nodeName);
+    console.log('Block:', status.currentBlock);
+    console.log('Syncing:', status.isSyncing);
+    console.log('Uptime:', status.uptimeFormatted);
+
+    // Graceful shutdown
+    process.on('SIGINT', async () => {
+        await node.stop();
+        process.exit(0);
+    });
+}
+
+main();
+```
+
+### JaelisNode Constructor Options
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `network` | string | `'testnet'` or `'mainnet'` | `'testnet'` |
+| `rpcPort` | number | Local RPC port | `8545` |
+| `dataDir` | string | Data directory path | `./jaelis-data/<network>` |
+| `nodeName` | string | Custom node name | Auto-generated |
+| `enableRpc` | boolean | Enable local RPC server | `true` |
+
+### Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `connected` | — | Connected to JAELIS network |
+| `disconnected` | — | Lost connection |
+| `block` | `{ number, hash, ... }` | New block received |
+| `syncing` | `{ syncing, currentBlock, highestBlock }` | Sync status changed |
+| `synced` | — | Fully synced with network |
+| `started` | — | Node started |
+| `stopped` | — | Node stopped |
+
+### getStatus() Return Object
+
+```javascript
+{
+    nodeId: 'jaelis_abc123...',
+    nodeName: 'MARBIT',           // null if no name set
+    network: 'testnet',
+    chainId: 4545,
+    isRunning: true,
+    isSyncing: false,
+    uptime: 135000,               // ms
+    uptimeFormatted: '2m 15s',
+    currentBlock: 12345,
+    stats: {
+        blocksReceived: 100,
+        transactionsRelayed: 5,
+        rpcRequests: 42,
+        peersConnected: 3
+    },
+    version: '2.2.0',
+    rpcPort: 8545
+}
+```
+
+---
+
+## RPC Methods
+
+Once your node is running, it supports these JSON-RPC methods on `http://localhost:<port>`:
+
+### Chain Info
+| Method | Description |
+|--------|-------------|
+| `jaelis_chainId` | Get chain ID (4547 mainnet, 4545 testnet) |
+| `jaelis_blockNumber` | Get latest block number |
+| `jaelis_syncing` | Get sync status |
+
+### Block Queries
+| Method | Description |
+|--------|-------------|
+| `jaelis_getBlockByNumber` | Get block by number |
+| `jaelis_getBlockByHash` | Get block by hash |
+
+### Transaction Queries
+| Method | Description |
+|--------|-------------|
+| `jaelis_getTransactionByHash` | Get transaction details |
+| `jaelis_getTransactionReceipt` | Get transaction receipt |
+| `jaelis_sendRawTransaction` | Submit signed transaction |
+
+### Account Queries (Relayed to Main Network)
+| Method | Description |
+|--------|-------------|
+| `jaelis_getBalance` | Get account balance |
+| `jaelis_getENE` | Get ENE (Ephemeral Network Entropy) |
+| `jaelis_getSigil` | Get SIGIL compute allocation |
+| `jaelis_getCode` | Get contract code |
+| `jaelis_call` | Call contract (read-only) |
+
+### SIGIL Compute
+| Method | Description |
+|--------|-------------|
+| `jaelis_estimateSigil` | Estimate SIGIL for transaction |
+| `jaelis_getSigil` | Get available SIGIL allocation |
+
+> JAELIS has ZERO gas fees. SIGIL represents compute allocation — it's not purchased, it's allocated.
+
+---
+
+## Network Info
+
+| Network | Chain ID | Main RPC | WebSocket | Status |
+|---------|----------|----------|-----------|--------|
+| Testnet | 4545 | `https://rpc.jaelis.io` | `wss://rpc.jaelis.io/ws` | **Active** |
+| Mainnet | 4547 | `https://mainnet.jaelis.io` | `wss://mainnet.jaelis.io/ws` | **Coming Soon** |
+
+> **Important:** Use testnet for now. Mainnet launch will be announced when ready.
+
+---
+
+## Why Run Your Own Node?
+
+1. **Privacy** — RPC requests stay local, not routed through public endpoints
+2. **Speed** — Local reads are instant (no network latency)
+3. **Decentralization** — More nodes = stronger network
+4. **Reliability** — No dependency on public RPC availability
+5. **Agent Autonomy** — Your agent controls its own infrastructure
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Connection refused` | Network unreachable | Check internet connection, verify RPC endpoints |
+| `Port already in use` | Another process on port | Use `--port 8546` |
+| `Unknown network` | Invalid network name | Use `testnet` or `mainnet` |
+| `Failed to start` | Storage or sync error | Delete data dir and restart: `rm -rf ./jaelis-data && jaelis-node` |
+| `Disconnected from network` | WebSocket dropped | Node auto-reconnects. Check internet if persistent |
+
+---
+
+## System Requirements
+
+- **Node.js:** 18.0.0 or higher
+- **Disk Space:** ~1GB testnet, ~10GB mainnet (grows over time)
+- **Memory:** 512MB minimum, 1GB recommended
+- **Network:** Stable internet connection
+
+---
+
+## Data Storage
+
+```
+./jaelis-data/
+  └── testnet/
+      ├── blocks/          # LevelDB database
+      └── node-name.json   # Persisted node name
+```
+
+To reset and resync:
+```bash
+rm -rf ./jaelis-data
+jaelis-node --name "MY-NODE"
+```
+
+---
+
+## Updates
+
+The node checks for updates on startup and notifies if a new version is available.
+
+```bash
+npm update -g jaelis-node
+```
+
+---
+
+## Resources
+
+- **npm:** [npmjs.com/package/jaelis-node](https://www.npmjs.com/package/jaelis-node)
+- **SDK:** [npmjs.com/package/jaelis.js](https://www.npmjs.com/package/jaelis.js)
+- **Website:** [jaelis.io](https://jaelis.io)
+- **Docs:** [docs.jaelis.io](https://docs.jaelis.io)
+- **Explorer:** [explorer.jaelis.io](https://explorer.jaelis.io)
+- **GitHub:** [github.com/jaelis-foundation](https://github.com/jaelis-foundation)

package/bin/jaelis-node.js

@@ -12,7 +12,7 @@
  *   jaelis-node --data-dir ./mydata  # Custom data directory
  *   jaelis-node --name MARBIT        # Name your node
  *
- * @version 2.1.0
+ * @version 2.2.0
  */
 
 'use strict';
@@ -21,7 +21,7 @@ const { Command } = require('commander');
 const { JaelisNode } = require('../lib/node');
 
 // Version check - notify if update available
-const VERSION = '2.1.0';
+const VERSION = '2.2.0';
 checkForUpdates();
 
 // CLI setup

package/lib/node.js

@@ -5,7 +5,7 @@
  * Does NOT contain any internal JAELIS blockchain code.
  * Only implements the network protocol for syncing and RPC.
  *
- * @version 2.1.0
+ * @version 2.2.0
  */
 
 'use strict';
@@ -128,7 +128,7 @@ class JaelisNode extends EventEmitter {
 
         console.log('');
         console.log('═══════════════════════════════════════════════════════════════');
-        console.log('                    JAELIS EXTERNAL NODE v2.1.0');
+        console.log('                    JAELIS EXTERNAL NODE v2.2.0');
         console.log('═══════════════════════════════════════════════════════════════');
         if (this.nodeName) {
         console.log(`   Node Name:  ${this.nodeName}`);
@@ -261,7 +261,7 @@ class JaelisNode extends EventEmitter {
             uptimeFormatted: this._formatUptime(uptime),
             currentBlock: this.storage?.getLatestBlockNumber() || 0,
             stats: this.stats,
-            version: '2.1.0',
+            version: '2.2.0',
             rpcPort: this.enableRpc ? this.rpcPort : null
         };
     }

package/lib/sync.js

@@ -53,8 +53,15 @@ class SyncManager extends EventEmitter {
         // Get local height
         this.localHeight = await this.storage.getLatestBlockNumber();
 
-        // Connect WebSocket
-        await this._connect();
+        // Connect WebSocket — if the endpoint is down, schedule reconnect
+        // instead of crashing the whole process
+        try {
+            await this._connect();
+        } catch (error) {
+            console.error('[SYNC] Initial connection failed:', error.message);
+            this._scheduleReconnect();
+            return;
+        }
 
         // Get network height and start sync
         await this._initialSync();
@@ -98,10 +105,17 @@ class SyncManager extends EventEmitter {
                 });
 
                 this.ws.on('error', (error) => {
+                    console.error('[SYNC] WebSocket error:', error.message);
                     if (!this.isConnected) {
+                        // Initial connection failed — reject the promise so start()
+                        // can catch it and call _scheduleReconnect(). The 'close'
+                        // event will fire next; we return early so it doesn't also
+                        // call _scheduleReconnect a second time.
                         reject(error);
+                        return;
                     }
-                    this.emit('error', error);
+                    // Don't emit('error') — Node crashes if no listener is attached.
+                    // The 'close' event will fire after this and trigger _scheduleReconnect.
                 });
 
             } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaelis-node",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Official JAELIS Blockchain External Node - Connect to the JAELIS network, sync blocks, and expose local RPC for your dApps. Zero gas fees, multi-chain interop.",
   "main": "lib/index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "lib/",
     "bin/",
+    "SKILL.md",
     "README.md"
   ],
   "scripts": {