jaelis-node 2.0.0 → 2.2.0

package/README.md

@@ -16,6 +16,17 @@ Official external node software for the **JAELIS Blockchain** network. Run your
 
 This is similar to running `geth --syncmode light` for Ethereum.
 
+## AI Agent Quick Start
+
+Get a named node running in 2 commands:
+
+```bash
+npm install -g jaelis-node
+jaelis-node --name "MY-AGENT" --network testnet
+```
+
+Your agent node will sync with the JAELIS testnet, expose a local RPC at `http://localhost:8545`, and persist its name across restarts.
+
 ## Quick Start
 
 ### Install Globally
@@ -30,8 +41,11 @@ 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
 
 # Custom RPC port
 jaelis-node --port 8546
@@ -80,6 +94,7 @@ const balance = await jaelis.getBalance('jae1qwertyuiop...'); // JAELIS native a
 | `-n, --network <network>` | Network to connect to (`testnet` or `mainnet`) | `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 (e.g., `MARBIT`, `my-agent`) | Auto-generated ID |
 | `--no-rpc` | Disable local RPC server | Enabled |
 
 ## Programmatic Usage
@@ -92,6 +107,7 @@ async function main() {
         network: 'testnet',
         rpcPort: 8545,
         dataDir: './my-jaelis-data',
+        nodeName: 'MY-AGENT',    // Name your node
         enableRpc: true
     });
 
@@ -157,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?
 
@@ -222,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

@@ -10,8 +10,9 @@
  *   jaelis-node --network mainnet    # Start on mainnet
  *   jaelis-node --port 8546          # Custom RPC port
  *   jaelis-node --data-dir ./mydata  # Custom data directory
+ *   jaelis-node --name MARBIT        # Name your node
  *
- * @version 2.0.0
+ * @version 2.2.0
  */
 
 'use strict';
@@ -20,7 +21,7 @@ const { Command } = require('commander');
 const { JaelisNode } = require('../lib/node');
 
 // Version check - notify if update available
-const VERSION = '2.0.0';
+const VERSION = '2.2.0';
 checkForUpdates();
 
 // CLI setup
@@ -33,6 +34,7 @@ program
     .option('-n, --network <network>', 'Network to connect to (testnet or mainnet)', 'testnet')
     .option('-p, --port <port>', 'Local RPC port', '8545')
     .option('-d, --data-dir <dir>', 'Data directory for local storage')
+    .option('--name <name>', 'Custom node name (e.g., MARBIT, my-agent)')
     .option('--no-rpc', 'Disable local RPC server')
     .parse(process.argv);
 
@@ -44,6 +46,7 @@ async function main() {
         network: options.network,
         rpcPort: parseInt(options.port, 10),
         dataDir: options.dataDir,
+        nodeName: options.name || null,
         enableRpc: options.rpc !== false
     });
 
@@ -66,7 +69,8 @@ async function main() {
         // Print status every 30 seconds
         setInterval(() => {
             const status = node.getStatus();
-            console.log(`[STATUS] Block: ${status.currentBlock} | Uptime: ${status.uptimeFormatted} | RPC Requests: ${status.stats.rpcRequests}`);
+            const nameTag = status.nodeName ? `${status.nodeName} | ` : '';
+            console.log(`[STATUS] ${nameTag}Block: ${status.currentBlock} | Uptime: ${status.uptimeFormatted} | RPC Requests: ${status.stats.rpcRequests}`);
         }, 30000);
 
     } catch (error) {

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.0.0
+ * @version 2.2.0
  */
 
 'use strict';
@@ -41,6 +41,7 @@ class JaelisNode extends EventEmitter {
      * @param {string} options.dataDir - Data directory for local storage
      * @param {number} options.rpcPort - Local RPC port (default: 8545)
      * @param {boolean} options.enableRpc - Enable local RPC server (default: true)
+     * @param {string} options.nodeName - Custom node name (e.g., 'MARBIT')
      */
     constructor(options = {}) {
         super();
@@ -56,8 +57,9 @@ class JaelisNode extends EventEmitter {
         this.rpcPort = options.rpcPort || 8545;
         this.enableRpc = options.enableRpc !== false;
 
-        // Node state
+        // Node identity
         this.nodeId = this._generateNodeId();
+        this.nodeName = options.nodeName || this._loadNodeName();
         this.startTime = null;
         this.isRunning = false;
         this.isSyncing = false;
@@ -84,6 +86,35 @@ class JaelisNode extends EventEmitter {
         return 'jaelis_' + crypto.randomBytes(8).toString('hex');
     }
 
+    /**
+     * Load persisted node name from data directory
+     */
+    _loadNodeName() {
+        try {
+            const fs = require('fs');
+            const path = require('path');
+            const nameFile = path.join(this.dataDir, 'node-name.json');
+            const data = JSON.parse(fs.readFileSync(nameFile, 'utf8'));
+            return data.name || null;
+        } catch (e) {
+            return null;
+        }
+    }
+
+    /**
+     * Persist node name to data directory
+     */
+    _saveNodeName() {
+        if (!this.nodeName) return;
+        try {
+            const fs = require('fs');
+            const path = require('path');
+            fs.mkdirSync(this.dataDir, { recursive: true });
+            const nameFile = path.join(this.dataDir, 'node-name.json');
+            fs.writeFileSync(nameFile, JSON.stringify({ name: this.nodeName, setAt: Date.now() }));
+        } catch (e) {}
+    }
+
     /**
      * Start the node
      */
@@ -92,10 +123,16 @@ class JaelisNode extends EventEmitter {
             throw new Error('Node is already running');
         }
 
+        // Persist node name if provided
+        this._saveNodeName();
+
         console.log('');
         console.log('═══════════════════════════════════════════════════════════════');
-        console.log('                    JAELIS EXTERNAL NODE v2.0.0');
+        console.log('                    JAELIS EXTERNAL NODE v2.2.0');
         console.log('═══════════════════════════════════════════════════════════════');
+        if (this.nodeName) {
+        console.log(`   Node Name:  ${this.nodeName}`);
+        }
         console.log(`   Network:    ${this.networkConfig.name}`);
         console.log(`   Chain ID:   ${this.networkConfig.chainId}`);
         console.log(`   Node ID:    ${this.nodeId}`);
@@ -215,6 +252,7 @@ class JaelisNode extends EventEmitter {
 
         return {
             nodeId: this.nodeId,
+            nodeName: this.nodeName || null,
             network: this.network,
             chainId: this.networkConfig.chainId,
             isRunning: this.isRunning,
@@ -223,7 +261,7 @@ class JaelisNode extends EventEmitter {
             uptimeFormatted: this._formatUptime(uptime),
             currentBlock: this.storage?.getLatestBlockNumber() || 0,
             stats: this.stats,
-            version: '2.0.0',
+            version: '2.2.0',
             rpcPort: this.enableRpc ? this.rpcPort : null
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaelis-node",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "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": {