@sequence0/agent 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# @sequence0/agent
+
+> Sequence0 Network SDK — Run a FROST threshold signing agent from Node.js, Deno, or browsers.
+
+## Install
+
+```bash
+npm install @sequence0/agent
+```
+
+## Quick Start
+
+```typescript
+import { AgentNode } from '@sequence0/agent';
+
+// 1. Create a node on mainnet
+const node = new AgentNode({ network: 'mainnet' });
+
+// 2. Connect to the relay
+await node.connect();
+
+// 3. Listen for events
+node.on('signing_request', (req) => {
+  console.log('Got signing request:', req.walletId);
+});
+
+node.on('fee_collected', (fee) => {
+  console.log('Earned:', fee.amount, 'ETH');
+});
+
+// 4. Request a signature
+await node.requestSignature('my-wallet', 'cafebabe');
+```
+
+## Network Selection
+
+```typescript
+// Mainnet (production) — chain 800801
+new AgentNode({ network: 'mainnet' });
+
+// Testnet — chain 800800, for development
+new AgentNode({ network: 'testnet' });
+
+// Custom RPC
+new AgentNode({ network: 'mainnet', rpcUrl: 'http://localhost:8545' });
+```
+
+## Networks
+
+| | Mainnet | Testnet |
+|---|---|---|
+| **Chain ID** | 800801 | 800800 |
+| **RPC** | `https://rpc.sequence0.network` | `https://testnet-rpc.sequence0.network` |
+| **WebSocket** | `wss://ws.sequence0.network` | `wss://testnet-ws.sequence0.network` |
+| **Explorer** | `https://explorer.sequence0.network` | `https://testnet.sequence0.network` |
+
+## API
+
+### `AgentNode`
+
+| Method | Description |
+|--------|-------------|
+| `connect(url?)` | Connect to a relay node via WebSocket |
+| `disconnect()` | Disconnect from the relay |
+| `requestSignature(walletId, message)` | Request a threshold signature |
+| `initiateDkg(walletId, participants, threshold)` | Start distributed key generation |
+| `info()` | Get node configuration info |
+| `on(event, handler)` | Subscribe to events |
+| `off(event, handler)` | Unsubscribe from events |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `connected` | WebSocket connected |
+| `disconnected` | WebSocket disconnected |
+| `signing_request` | New signing request received |
+| `signature_complete` | Signature aggregation complete |
+| `dkg_started` | DKG session started |
+| `dkg_complete` | DKG complete, wallet created |
+| `fee_collected` | Fee collected for a signature |
+| `error` | Error occurred |
+
+## Running an Agent Node
+
+### Binary (Recommended for node operators)
+
+```bash
+# Install the Rust agent binary
+curl -sSL https://install.sequence0.network | sh
+
+# Run on mainnet
+sequence0-agent --network mainnet --port 9000 --api-port 8080
+
+# Run on testnet
+sequence0-agent --network testnet --port 9000 --api-port 8080
+```
+
+### Docker
+
+```bash
+docker run sequence0/agent --network mainnet
+```
+
+### Requirements
+
+- 2+ CPU cores, 4GB RAM, 50GB SSD
+- Public IP with ports 9000 (P2P) and 8080 (API) open
+- 0.1 ETH registration fee (one-time)
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @sequence0/agent — High-Level Agent Node
+ *
+ * Wraps the FROST WASM core with WebSocket transport for easy integration.
+ * This is the main API surface for developers using the SDK.
+ *
+ * @example
+ * ```typescript
+ * import { AgentNode } from '@sequence0/agent';
+ *
+ * const node = new AgentNode({ network: 'testnet', threshold: 2, maxSigners: 3 });
+ * await node.connect('ws://18.220.162.112:8080/ws');
+ *
+ * node.on('signing_request', async (req) => {
+ *   console.log('Got signing request:', req.walletId);
+ * });
+ * ```
+ */
+import { NetworkConfig } from './networks.js';
+export interface AgentNodeOptions {
+    /** Network to connect to: 'testnet' or 'mainnet' */
+    network: string;
+    /** FROST threshold (t in t-of-n) */
+    threshold?: number;
+    /** Total participants (n in t-of-n) */
+    maxSigners?: number;
+    /** This agent's FROST participant ID (1-based) */
+    agentId?: number;
+    /** Custom RPC URL (overrides network default) */
+    rpcUrl?: string;
+    /** Custom WebSocket relay URL */
+    wsUrl?: string;
+}
+export type AgentEvent = 'connected' | 'disconnected' | 'signing_request' | 'signature_complete' | 'dkg_started' | 'dkg_complete' | 'fee_collected' | 'error';
+export interface SigningRequest {
+    requestId: string;
+    walletId: string;
+    message: string;
+    participants: string[];
+}
+export interface SignatureResult {
+    requestId: string;
+    walletId: string;
+    signature: string;
+    verified: boolean;
+}
+type EventHandler = (...args: any[]) => void;
+export declare class AgentNode {
+    private config;
+    private networkConfig;
+    private ws;
+    private handlers;
+    private reconnectTimer;
+    private _connected;
+    constructor(options: AgentNodeOptions);
+    /** Get the resolved network configuration */
+    get network(): NetworkConfig;
+    /** Whether the WebSocket is connected */
+    get connected(): boolean;
+    /**
+     * Connect to a Sequence0 relay node via WebSocket
+     * @param url - WebSocket URL (e.g., 'ws://18.220.162.112:8080/ws')
+     */
+    connect(url?: string): Promise<void>;
+    /** Disconnect from the relay */
+    disconnect(): void;
+    /** Register an event handler */
+    on(event: AgentEvent, handler: EventHandler): void;
+    /** Remove an event handler */
+    off(event: AgentEvent, handler: EventHandler): void;
+    /** Send a signing request to the network */
+    requestSignature(walletId: string, message: string): Promise<void>;
+    /** Initiate a DKG session */
+    initiateDkg(walletId: string, participants: string[], threshold: number): Promise<void>;
+    /** Get agent node info */
+    info(): Record<string, any>;
+    private defaultWsUrl;
+    private send;
+    private handleMessage;
+    private emit;
+    private scheduleReconnect;
+}
+export {};

package/dist/agent.js

@@ -0,0 +1,201 @@
+/**
+ * @sequence0/agent — High-Level Agent Node
+ *
+ * Wraps the FROST WASM core with WebSocket transport for easy integration.
+ * This is the main API surface for developers using the SDK.
+ *
+ * @example
+ * ```typescript
+ * import { AgentNode } from '@sequence0/agent';
+ *
+ * const node = new AgentNode({ network: 'testnet', threshold: 2, maxSigners: 3 });
+ * await node.connect('ws://18.220.162.112:8080/ws');
+ *
+ * node.on('signing_request', async (req) => {
+ *   console.log('Got signing request:', req.walletId);
+ * });
+ * ```
+ */
+import { resolveNetwork } from './networks.js';
+export class AgentNode {
+    constructor(options) {
+        this.ws = null;
+        this.handlers = new Map();
+        this.reconnectTimer = null;
+        this._connected = false;
+        this.config = {
+            threshold: 2,
+            maxSigners: 3,
+            agentId: 1,
+            ...options,
+        };
+        this.networkConfig = resolveNetwork(options.network);
+        // Apply custom RPC if provided
+        if (options.rpcUrl) {
+            this.networkConfig = { ...this.networkConfig, rpcUrl: options.rpcUrl };
+        }
+    }
+    /** Get the resolved network configuration */
+    get network() {
+        return this.networkConfig;
+    }
+    /** Whether the WebSocket is connected */
+    get connected() {
+        return this._connected;
+    }
+    /**
+     * Connect to a Sequence0 relay node via WebSocket
+     * @param url - WebSocket URL (e.g., 'ws://18.220.162.112:8080/ws')
+     */
+    async connect(url) {
+        const wsUrl = url || this.config.wsUrl || this.defaultWsUrl();
+        return new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(wsUrl);
+                this.ws.onopen = () => {
+                    this._connected = true;
+                    this.emit('connected', { url: wsUrl, network: this.networkConfig.name });
+                    resolve();
+                };
+                this.ws.onmessage = (event) => {
+                    try {
+                        const data = JSON.parse(event.data);
+                        this.handleMessage(data);
+                    }
+                    catch (e) {
+                        this.emit('error', { type: 'parse_error', detail: e });
+                    }
+                };
+                this.ws.onclose = () => {
+                    this._connected = false;
+                    this.emit('disconnected', {});
+                    this.scheduleReconnect(wsUrl);
+                };
+                this.ws.onerror = (error) => {
+                    this.emit('error', { type: 'ws_error', detail: error });
+                    reject(error);
+                };
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }
+    /** Disconnect from the relay */
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this._connected = false;
+    }
+    /** Register an event handler */
+    on(event, handler) {
+        const existing = this.handlers.get(event) || [];
+        existing.push(handler);
+        this.handlers.set(event, existing);
+    }
+    /** Remove an event handler */
+    off(event, handler) {
+        const existing = this.handlers.get(event) || [];
+        this.handlers.set(event, existing.filter(h => h !== handler));
+    }
+    /** Send a signing request to the network */
+    async requestSignature(walletId, message) {
+        this.send({
+            type: 'sign_request',
+            wallet_id: walletId,
+            message,
+        });
+    }
+    /** Initiate a DKG session */
+    async initiateDkg(walletId, participants, threshold) {
+        this.send({
+            type: 'dkg_initiate',
+            wallet_id: walletId,
+            participants,
+            threshold,
+        });
+    }
+    /** Get agent node info */
+    info() {
+        return {
+            network: this.networkConfig.name,
+            chainId: this.networkConfig.chainId,
+            threshold: this.config.threshold,
+            maxSigners: this.config.maxSigners,
+            agentId: this.config.agentId,
+            connected: this._connected,
+            rpcUrl: this.networkConfig.rpcUrl,
+            contracts: {
+                registry: this.networkConfig.registry,
+                feeCollector: this.networkConfig.feeCollector,
+                walletFactory: this.networkConfig.walletFactory,
+            },
+        };
+    }
+    // ── Private ──
+    defaultWsUrl() {
+        // Derive WS URL from RPC URL
+        const rpc = this.networkConfig.rpcUrl;
+        const host = rpc.replace(/^https?:\/\//, '').replace(/:\d+$/, '').replace(/\/.*$/, '');
+        return `ws://${host}:8080/ws`;
+    }
+    send(data) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Not connected — call connect() first');
+        }
+        this.ws.send(JSON.stringify(data));
+    }
+    handleMessage(data) {
+        const eventType = data.event || data.type;
+        switch (eventType) {
+            case 'SigningStarted':
+                this.emit('signing_request', data);
+                break;
+            case 'SigningComplete':
+                this.emit('signature_complete', data);
+                break;
+            case 'DkgStarted':
+                this.emit('dkg_started', data);
+                break;
+            case 'WalletCreated':
+                this.emit('dkg_complete', data);
+                break;
+            case 'FeeCollected':
+                this.emit('fee_collected', data);
+                break;
+            default:
+                // Pass through unknown events
+                break;
+        }
+    }
+    emit(event, data) {
+        const handlers = this.handlers.get(event) || [];
+        for (const handler of handlers) {
+            try {
+                handler(data);
+            }
+            catch (e) {
+                console.error(`Error in ${event} handler:`, e);
+            }
+        }
+    }
+    scheduleReconnect(url) {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            try {
+                await this.connect(url);
+            }
+            catch {
+                // Will retry on next close
+            }
+        }, 3000);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @sequence0/agent
+ *
+ * Sequence0 Network SDK — FROST threshold signing for Node.js and browsers.
+ * Run a signing agent or integrate threshold signatures into your application.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { AgentNode, TESTNET, MAINNET } from '@sequence0/agent';
+ *
+ * // Connect to testnet
+ * const node = new AgentNode({ network: 'testnet' });
+ * await node.connect();
+ *
+ * // Listen for events
+ * node.on('signing_request', (req) => console.log('Sign:', req));
+ * node.on('fee_collected', (fee) => console.log('Earned:', fee));
+ *
+ * // Request a signature
+ * await node.requestSignature('wallet-id', 'cafebabe');
+ * ```
+ */
+export { AgentNode } from './agent.js';
+export type { AgentNodeOptions, AgentEvent, SigningRequest, SignatureResult } from './agent.js';
+export { TESTNET, MAINNET, resolveNetwork } from './networks.js';
+export type { NetworkConfig } from './networks.js';
+export declare const VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * @sequence0/agent
+ *
+ * Sequence0 Network SDK — FROST threshold signing for Node.js and browsers.
+ * Run a signing agent or integrate threshold signatures into your application.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { AgentNode, TESTNET, MAINNET } from '@sequence0/agent';
+ *
+ * // Connect to testnet
+ * const node = new AgentNode({ network: 'testnet' });
+ * await node.connect();
+ *
+ * // Listen for events
+ * node.on('signing_request', (req) => console.log('Sign:', req));
+ * node.on('fee_collected', (fee) => console.log('Earned:', fee));
+ *
+ * // Request a signature
+ * await node.requestSignature('wallet-id', 'cafebabe');
+ * ```
+ */
+// Agent Node (high-level API)
+export { AgentNode } from './agent.js';
+// Network configurations
+export { TESTNET, MAINNET, resolveNetwork } from './networks.js';
+// Version
+export const VERSION = '0.1.0';

package/dist/networks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @sequence0/agent — Network Configurations
+ *
+ * Testnet and mainnet configs mirroring the Rust NetworkProfile.
+ * Contract addresses, RPC URLs, and chain IDs for each environment.
+ */
+export interface NetworkConfig {
+    name: string;
+    chainId: number;
+    rpcUrl: string;
+    wsUrl: string;
+    registry: string;
+    feeCollector: string;
+    walletFactory: string;
+    bootstrapPeers: string[];
+    signatureFeeWei: bigint;
+    registrationFeeWei: bigint;
+}
+export declare const TESTNET: NetworkConfig;
+export declare const MAINNET: NetworkConfig;
+export declare function resolveNetwork(name: string): NetworkConfig;

package/dist/networks.js

@@ -0,0 +1,43 @@
+/**
+ * @sequence0/agent — Network Configurations
+ *
+ * Testnet and mainnet configs mirroring the Rust NetworkProfile.
+ * Contract addresses, RPC URLs, and chain IDs for each environment.
+ */
+export const TESTNET = {
+    name: 'testnet',
+    chainId: 800800,
+    rpcUrl: 'https://testnet-rpc.sequence0.network',
+    wsUrl: 'wss://testnet-ws.sequence0.network',
+    registry: '0x2d6c5f5f4bf21af697e29472800aa8b930e15e0a',
+    feeCollector: '0x4154a696acfd9bac8eef6f2c8c4dde20e22421b8',
+    walletFactory: '0x9cff7013a9d671f84100f8055a10f8620ae42d3b',
+    bootstrapPeers: [
+        '/ip4/18.220.162.112/tcp/9001',
+        '/ip4/18.220.162.112/tcp/9002',
+        '/ip4/18.220.162.112/tcp/9003',
+    ],
+    signatureFeeWei: 30000000000000n, // 0.00003 ETH
+    registrationFeeWei: 10000000000000000n, // 0.01 ETH
+};
+export const MAINNET = {
+    name: 'mainnet',
+    chainId: 800801,
+    rpcUrl: 'https://rpc.sequence0.network',
+    wsUrl: 'wss://ws.sequence0.network',
+    registry: '0x3d5c81e158b0e30f573a3dae02e58b72b11042ae',
+    feeCollector: '0x73c785d58daa7afeffc071cea373acae8835f9c0',
+    walletFactory: '0x54acfe8c3babed69f251c387971bc4e0cb4c1fe3',
+    bootstrapPeers: [
+        '/ip4/3.148.239.3/tcp/9000',
+    ],
+    signatureFeeWei: 30000000000000n,
+    registrationFeeWei: 100000000000000000n,
+};
+export function resolveNetwork(name) {
+    switch (name.toLowerCase()) {
+        case 'testnet': return TESTNET;
+        case 'mainnet': return MAINNET;
+        default: throw new Error(`Unknown network: ${name}. Use 'testnet' or 'mainnet'.`);
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@sequence0/agent",
+    "version": "0.1.0",
+    "description": "Sequence0 Network — FROST threshold signing agent for Node.js and browsers",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist/",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "node --experimental-wasm-modules test/test.mjs"
+    },
+    "keywords": [
+        "sequence0",
+        "frost",
+        "threshold-signatures",
+        "mpc",
+        "dkg",
+        "web3",
+        "decentralized-signing"
+    ],
+    "author": "Sequence0 Network",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/sequence0-network/agent-node"
+    },
+    "dependencies": {},
+    "devDependencies": {
+        "typescript": "^5.0.0"
+    }
+}