gennet.js 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# gennet.js
+
+Client library for [GenNet](https://github.com/cryptagoEU/gennet.js) — interact with GenNet nodes via JSON-RPC.
+
+- Zero runtime dependencies
+- Browser + Node.js compatible
+- WebSocket & HTTP providers
+- Full TypeScript support (ESM + CJS)
+- Subscriptions (logs, messages, mempool)
+
+## Installation
+
+```bash
+npm install gennet.js
+```
+
+## Quick Start
+
+```typescript
+import { GenNet } from 'gennet.js';
+
+const gennet = new GenNet('ws://localhost:18789');
+await gennet.connect();
+
+// Node info
+const info = await gennet.admin.nodeInfo();
+console.log(info.address, info.peers);
+
+// Send encrypted message
+await gennet.net.send('0xRecipientAddress', 'Hello!');
+
+// Disconnect
+gennet.disconnect();
+```
+
+## Providers
+
+gennet.js auto-detects the provider from the URL:
+
+```typescript
+// WebSocket (supports subscriptions)
+const gennet = new GenNet('ws://localhost:18789');
+
+// HTTP (stateless, no subscriptions)
+const gennet = new GenNet('http://localhost:18790');
+```
+
+You can also pass a custom provider:
+
+```typescript
+import { GenNet, WebSocketProvider } from 'gennet.js';
+
+const provider = new WebSocketProvider('ws://localhost:18789');
+const gennet = new GenNet(provider);
+```
+
+## API
+
+### admin
+
+```typescript
+await gennet.admin.nodeInfo();                // Node status, peers, uptime, modules
+await gennet.admin.shutdown();                // Shutdown the gateway
+await gennet.admin.modules();                 // List all modules and their state
+await gennet.admin.startModule('net');        // Start a module
+await gennet.admin.stopModule('net');         // Stop a module
+```
+
+### net
+
+```typescript
+await gennet.net.peers();                                   // List known peers
+await gennet.net.connect('/ip4/127.0.0.1/tcp/9000/p2p/…');  // Connect to peer
+await gennet.net.send('0x…', 'Hello');                       // Send encrypted message
+await gennet.net.peerAgent('0x…', 'What is 2+2?');           // Remote agent execution
+```
+
+### personal
+
+```typescript
+await gennet.personal.newIdentity('password');   // Create new identity
+await gennet.personal.listIdentities();          // List keystore identities
+```
+
+### agent
+
+```typescript
+await gennet.agent.run('What is 2+2?');   // Run local agent prompt
+```
+
+### mempool
+
+```typescript
+await gennet.mempool.broadcast('Hello network!');   // Broadcast via GossipSub
+```
+
+### Subscriptions
+
+Subscriptions are available over WebSocket. Topics: `logs`, `messages`, `mempool`.
+
+```typescript
+const sub = await gennet.subscribe('messages', (data) => {
+  console.log('New message:', data);
+});
+
+// Unsubscribe
+await sub.unsubscribe();
+```
+
+### Raw RPC
+
+For methods not covered by the namespaces:
+
+```typescript
+const result = await gennet.request('custom_method', { key: 'value' });
+```
+
+## Error Handling
+
+RPC errors throw a typed `RpcError`:
+
+```typescript
+import { RpcError } from 'gennet.js';
+
+try {
+  await gennet.net.send('0xInvalid', 'Hello');
+} catch (err) {
+  if (err instanceof RpcError) {
+    console.error(err.message, err.code);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,311 @@
+'use strict';
+
+class RpcError extends Error {
+  code;
+  data;
+  constructor(message, code, data) {
+    super(message);
+    this.name = "RpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+let requestId = 0;
+class HttpProvider {
+  url;
+  constructor(url) {
+    this.url = url;
+  }
+  get connected() {
+    return true;
+  }
+  async request(method, params) {
+    const id = ++requestId;
+    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const res = await fetch(this.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+    if (!res.ok) {
+      throw new RpcError(`HTTP ${res.status}: ${res.statusText}`, -32e3);
+    }
+    const json = await res.json();
+    if ("error" in json) {
+      const err = json.error;
+      throw new RpcError(err.message, err.code, err.data);
+    }
+    return json.result;
+  }
+  // HTTP unterstützt keine Push-Notifications
+  on(_event, _listener) {
+  }
+  off(_event, _listener) {
+  }
+  disconnect() {
+  }
+}
+
+const DEFAULT_TIMEOUT = 3e4;
+class WebSocketProvider {
+  url;
+  timeout;
+  ws = null;
+  requestId = 0;
+  pending = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  connectPromise = null;
+  constructor(url, timeout = DEFAULT_TIMEOUT) {
+    this.url = url;
+    this.timeout = timeout;
+  }
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  async connect() {
+    if (this.connected) return;
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.url);
+      this.ws.onopen = () => {
+        this.connectPromise = null;
+        resolve();
+      };
+      this.ws.onerror = (ev) => {
+        this.connectPromise = null;
+        reject(new Error(`WebSocket-Verbindung fehlgeschlagen: ${this.url} (${ev})`));
+      };
+      this.ws.onmessage = (ev) => {
+        this.handleMessage(typeof ev.data === "string" ? ev.data : String(ev.data));
+      };
+      this.ws.onclose = () => {
+        this.connectPromise = null;
+        for (const [id, req] of this.pending) {
+          clearTimeout(req.timer);
+          req.reject(new Error("WebSocket-Verbindung geschlossen"));
+          this.pending.delete(id);
+        }
+      };
+    });
+    return this.connectPromise;
+  }
+  async request(method, params) {
+    if (!this.connected) {
+      await this.connect();
+    }
+    const id = ++this.requestId;
+    const payload = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new RpcError(`Timeout nach ${this.timeout}ms f\xFCr ${method}`, -32e3));
+      }, this.timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(payload);
+    });
+  }
+  on(_event, listener) {
+    this.listeners.add(listener);
+  }
+  off(_event, listener) {
+    this.listeners.delete(listener);
+  }
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+  // ── Private ────────────────────────────────────────────────
+  handleMessage(raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.id !== void 0 && ("result" in msg || "error" in msg)) {
+      const response = msg;
+      const pending = this.pending.get(response.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pending.delete(response.id);
+        if ("error" in response) {
+          const err = response.error;
+          pending.reject(new RpcError(err.message, err.code, err.data));
+        } else {
+          pending.resolve(response.result);
+        }
+      }
+      return;
+    }
+    if ("method" in msg && "params" in msg) {
+      const notification = msg;
+      for (const listener of this.listeners) {
+        listener(notification);
+      }
+    }
+  }
+}
+
+class Admin {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Node-Info: Status, PeerId, Adresse, Peers, Uptime, Module. */
+  async nodeInfo() {
+    return await this.provider.request("admin_nodeInfo");
+  }
+  /** Gateway herunterfahren. */
+  async shutdown() {
+    return await this.provider.request("admin_shutdown");
+  }
+  /** Alle Module und ihren Status auflisten. */
+  async modules() {
+    return await this.provider.request("admin_modules");
+  }
+  /** Ein Modul starten. */
+  async startModule(name) {
+    return await this.provider.request("admin_startModule", { name });
+  }
+  /** Ein Modul stoppen. */
+  async stopModule(name) {
+    return await this.provider.request("admin_stopModule", { name });
+  }
+}
+
+class Net {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Alle bekannten Peers auflisten. */
+  async peers() {
+    return await this.provider.request("net_peers");
+  }
+  /** Mit einem Peer über Multiaddr verbinden. */
+  async connect(multiaddr) {
+    return await this.provider.request("net_connect", { multiaddr });
+  }
+  /** Verschlüsselte Nachricht an einen Peer senden. */
+  async send(address, text) {
+    return await this.provider.request("net_send", { address, text });
+  }
+  /** Agent-Prompt auf einem Remote-Peer ausführen (ECIES-verschlüsselt). */
+  async peerAgent(address, prompt) {
+    return await this.provider.request("net_peerAgent", { address, prompt });
+  }
+}
+
+class Personal {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Neue Identität erstellen und im Keystore speichern. */
+  async newIdentity(password) {
+    return await this.provider.request("personal_newIdentity", { password });
+  }
+  /** Alle Identitäten im Keystore auflisten. */
+  async listIdentities() {
+    return await this.provider.request("personal_listIdentities");
+  }
+}
+
+class Agent {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Agent-Loop mit einem Prompt ausführen. */
+  async run(input) {
+    return await this.provider.request("agent_run", { input });
+  }
+}
+
+class Mempool {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /** Nachricht ans Netzwerk broadcasten (GossipSub). */
+  async broadcast(message) {
+    return await this.provider.request("mempool_broadcast", { message });
+  }
+}
+
+class GenNet {
+  admin;
+  net;
+  personal;
+  agent;
+  mempool;
+  provider;
+  constructor(providerOrUrl) {
+    if (typeof providerOrUrl === "string") {
+      this.provider = GenNet.createProvider(providerOrUrl);
+    } else {
+      this.provider = providerOrUrl;
+    }
+    this.admin = new Admin(this.provider);
+    this.net = new Net(this.provider);
+    this.personal = new Personal(this.provider);
+    this.agent = new Agent(this.provider);
+    this.mempool = new Mempool(this.provider);
+  }
+  /** Verbindung herstellen (nur bei WebSocket nötig). */
+  async connect() {
+    if (this.provider.connect) {
+      await this.provider.connect();
+    }
+  }
+  /** Verbindung schließen. */
+  disconnect() {
+    this.provider.disconnect();
+  }
+  /** Ob eine aktive Verbindung besteht. */
+  get connected() {
+    return this.provider.connected;
+  }
+  /**
+   * Subscription starten (nur WebSocket).
+   * Topics: 'logs', 'messages', 'mempool'.
+   */
+  async subscribe(topic, callback) {
+    const subId = await this.provider.request("gennet_subscribe", [topic]);
+    const listener = (notification) => {
+      if (notification.method === "gennet_subscription" && notification.params.subscription === subId) {
+        callback(notification.params.result);
+      }
+    };
+    this.provider.on("notification", listener);
+    return {
+      id: subId,
+      unsubscribe: async () => {
+        this.provider.off("notification", listener);
+        return await this.provider.request("gennet_unsubscribe", [subId]);
+      }
+    };
+  }
+  /** Raw JSON-RPC Request (für erweiterte Nutzung). */
+  async request(method, params) {
+    return this.provider.request(method, params);
+  }
+  // ── Private ────────────────────────────────────────────────
+  static createProvider(url) {
+    if (url.startsWith("ws://") || url.startsWith("wss://")) {
+      return new WebSocketProvider(url);
+    }
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      return new HttpProvider(url);
+    }
+    throw new Error(`Unbekanntes URL-Schema: ${url} (erwartet: ws://, wss://, http://, https://)`);
+  }
+}
+
+exports.Admin = Admin;
+exports.Agent = Agent;
+exports.GenNet = GenNet;
+exports.HttpProvider = HttpProvider;
+exports.Mempool = Mempool;
+exports.Net = Net;
+exports.Personal = Personal;
+exports.RpcError = RpcError;
+exports.WebSocketProvider = WebSocketProvider;

package/dist/index.d.cts

@@ -0,0 +1,261 @@
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown> | unknown[];
+}
+interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result: unknown;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params: {
+        subscription: string;
+        result: unknown;
+    };
+}
+declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(message: string, code: number, data?: unknown);
+}
+type GatewayState = 'INITIALIZING' | 'READY' | 'RUNNING' | 'STOPPED';
+interface ModuleInfo {
+    name: string;
+    version: string;
+    state: string;
+    status?: string;
+}
+interface NodeInfo {
+    state: GatewayState;
+    peerId: string | null;
+    address: string;
+    peers: number;
+    knownPeers: number;
+    uptime: number;
+    multiaddrs: string[];
+    tcpAddrs: string[];
+    circuitAddrs: string[];
+    relay: boolean;
+    listenPort: number;
+    datadir: string;
+    modules: ModuleInfo[];
+}
+interface PeerInfo {
+    peerId: string;
+    address: string;
+    multiaddr: string;
+    connected: boolean;
+}
+interface AgentResult {
+    ok: boolean;
+    response?: string;
+    toolCalls?: Array<{
+        name: string;
+    }>;
+    tokensUsed?: {
+        input: number;
+        output: number;
+    };
+    error?: string;
+}
+interface IdentityInfo {
+    index: number;
+    address: string;
+    filename: string;
+}
+type SubscriptionTopic = 'logs' | 'messages' | 'mempool';
+interface Subscription {
+    id: string;
+    unsubscribe: () => Promise<boolean>;
+}
+interface Provider {
+    /** JSON-RPC Request senden und auf Response warten. */
+    request(method: string, params?: Record<string, unknown> | unknown[]): Promise<unknown>;
+    /** Listener für Push-Notifications (Subscriptions). */
+    on(event: 'notification', listener: (notification: JsonRpcNotification) => void): void;
+    /** Listener entfernen. */
+    off(event: 'notification', listener: (notification: JsonRpcNotification) => void): void;
+    /** Verbindung schließen. */
+    disconnect(): void;
+    /** Verbindung herstellen (bei WebSocket). */
+    connect?(): Promise<void>;
+    /** Ob eine aktive Verbindung besteht. */
+    readonly connected: boolean;
+}
+
+/** admin Namespace — Node-Administration. */
+declare class Admin {
+    private readonly provider;
+    constructor(provider: Provider);
+    /** Node-Info: Status, PeerId, Adresse, Peers, Uptime, Module. */
+    nodeInfo(): Promise<NodeInfo>;
+    /** Gateway herunterfahren. */
+    shutdown(): Promise<{
+        ok: boolean;
+    }>;
+    /** Alle Module und ihren Status auflisten. */
+    modules(): Promise<{
+        modules: ModuleInfo[];
+    }>;
+    /** Ein Modul starten. */
+    startModule(name: string): Promise<{
+        name: string;
+        state: string;
+    }>;
+    /** Ein Modul stoppen. */
+    stopModule(name: string): Promise<{
+        name: string;
+        state: string;
+    }>;
+}
+
+/** net Namespace — P2P-Netzwerk. */
+declare class Net {
+    private readonly provider;
+    constructor(provider: Provider);
+    /** Alle bekannten Peers auflisten. */
+    peers(): Promise<{
+        peers: PeerInfo[];
+    }>;
+    /** Mit einem Peer über Multiaddr verbinden. */
+    connect(multiaddr: string): Promise<{
+        peerId: string;
+        connected: boolean;
+    }>;
+    /** Verschlüsselte Nachricht an einen Peer senden. */
+    send(address: string, text: string): Promise<{
+        sent: boolean;
+        to: string;
+    }>;
+    /** Agent-Prompt auf einem Remote-Peer ausführen (ECIES-verschlüsselt). */
+    peerAgent(address: string, prompt: string): Promise<AgentResult>;
+}
+
+/** personal Namespace — Identity/Keystore-Management. */
+declare class Personal {
+    private readonly provider;
+    constructor(provider: Provider);
+    /** Neue Identität erstellen und im Keystore speichern. */
+    newIdentity(password: string): Promise<{
+        address: string;
+        path: string;
+    }>;
+    /** Alle Identitäten im Keystore auflisten. */
+    listIdentities(): Promise<{
+        identities: IdentityInfo[];
+    }>;
+}
+
+/** agent Namespace — Lokaler AI-Agent. */
+declare class Agent {
+    private readonly provider;
+    constructor(provider: Provider);
+    /** Agent-Loop mit einem Prompt ausführen. */
+    run(input: string): Promise<AgentResult>;
+}
+
+/** mempool Namespace — Transaction Mempool. */
+declare class Mempool {
+    private readonly provider;
+    constructor(provider: Provider);
+    /** Nachricht ans Netzwerk broadcasten (GossipSub). */
+    broadcast(message: string): Promise<{
+        sent: boolean;
+        taskId: string;
+    }>;
+}
+
+/**
+ * GenNet Client — Hauptklasse für die Interaktion mit einem GenNet-Node.
+ *
+ * @example
+ * ```typescript
+ * const gennet = new GenNet('ws://localhost:18789');
+ * await gennet.connect();
+ *
+ * const info = await gennet.admin.nodeInfo();
+ * const peers = await gennet.net.peers();
+ * await gennet.net.send('0x...', 'Hello');
+ *
+ * const sub = await gennet.subscribe('messages', (data) => console.log(data));
+ * await sub.unsubscribe();
+ *
+ * gennet.disconnect();
+ * ```
+ */
+declare class GenNet {
+    readonly admin: Admin;
+    readonly net: Net;
+    readonly personal: Personal;
+    readonly agent: Agent;
+    readonly mempool: Mempool;
+    private readonly provider;
+    constructor(providerOrUrl: string | Provider);
+    /** Verbindung herstellen (nur bei WebSocket nötig). */
+    connect(): Promise<void>;
+    /** Verbindung schließen. */
+    disconnect(): void;
+    /** Ob eine aktive Verbindung besteht. */
+    get connected(): boolean;
+    /**
+     * Subscription starten (nur WebSocket).
+     * Topics: 'logs', 'messages', 'mempool'.
+     */
+    subscribe(topic: SubscriptionTopic, callback: (data: unknown) => void): Promise<Subscription>;
+    /** Raw JSON-RPC Request (für erweiterte Nutzung). */
+    request(method: string, params?: Record<string, unknown> | unknown[]): Promise<unknown>;
+    private static createProvider;
+}
+
+/**
+ * WebSocket Provider — nutzt native WebSocket API (Browser + Node 22+).
+ * Unterstützt Subscriptions via Push-Notifications.
+ */
+declare class WebSocketProvider implements Provider {
+    private readonly url;
+    private readonly timeout;
+    private ws;
+    private requestId;
+    private pending;
+    private listeners;
+    private connectPromise;
+    constructor(url: string, timeout?: number);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    request(method: string, params?: Record<string, unknown> | unknown[]): Promise<unknown>;
+    on(_event: 'notification', listener: (notification: JsonRpcNotification) => void): void;
+    off(_event: 'notification', listener: (notification: JsonRpcNotification) => void): void;
+    disconnect(): void;
+    private handleMessage;
+}
+
+/**
+ * HTTP Provider — fetch-basiert, browser-kompatibel.
+ * Unterstützt keine Subscriptions (kein Push-Kanal).
+ */
+declare class HttpProvider implements Provider {
+    private readonly url;
+    constructor(url: string);
+    get connected(): boolean;
+    request(method: string, params?: Record<string, unknown> | unknown[]): Promise<unknown>;
+    on(_event: 'notification', _listener: (notification: JsonRpcNotification) => void): void;
+    off(_event: 'notification', _listener: (notification: JsonRpcNotification) => void): void;
+    disconnect(): void;
+}
+
+export { Admin, Agent, GenNet, HttpProvider, Mempool, Net, Personal, RpcError, WebSocketProvider };
+export type { AgentResult, GatewayState, IdentityInfo, JsonRpcErrorResponse, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccessResponse, ModuleInfo, NodeInfo, PeerInfo, Provider, Subscription, SubscriptionTopic };