@0xopenseeddev/sdk 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# @0xopenseeddev/sdk
+
+Programmatic SDK for the **OpenSeed** network.  
+Spin up seller nodes, define AI offerings, and orchestrate a local peer network — all from JavaScript.
+
+---
+
+## Installation
+
+The SDK is a workspace package and is available automatically within the monorepo.  
+Import directly from source:
+
+```js
+import { Network, SellerNode, Offering } from './packages/sdk/src/index.js';
+```
+
+Or, if published externally:
+
+```sh
+npm install @0xopenseeddev/sdk
+```
+
+---
+
+## Quick Start
+
+```js
+import { Network, Offering } from '@0xopenseeddev/sdk';
+
+const net = new Network({
+  apiKey:      process.env.OPENROUTER_API_KEY,
+  registryUrl: 'http://localhost:9000'
+});
+
+net
+  .addSeller({
+    port:   8401,
+    peerId: 'my-node-001',
+    offerings: [
+      new Offering('inference')
+        .name('Llama 3 8B')
+        .description('Fast open-source model for everyday tasks.')
+        .services(['llama-3-8b'])
+        .pricing({ inputUsdPerMillion: 0.05, outputUsdPerMillion: 0.05 })
+        .upstreamModel('meta-llama/llama-3-8b-instruct:free')
+    ]
+  });
+
+await net.start();
+// SIGINT / SIGTERM are handled automatically — Ctrl+C shuts everything down cleanly.
+```
+
+---
+
+## API Reference
+
+### `Offering`
+
+Fluent builder for a single capability advertised by a seller node.
+
+```js
+new Offering(capability)
+```
+
+| Argument | Type | Description |
+|---|---|---|
+| `capability` | `'inference' \| 'agent' \| 'tool'` | Capability type |
+
+**Chain methods** (all return `this`):
+
+| Method | Argument | Description |
+|---|---|---|
+| `.name(str)` | `string` | Human-readable offering name |
+| `.description(str)` | `string` | Short description shown to buyers |
+| `.services(ids)` | `string[]` | Model/service IDs buyers request (e.g. `['gpt-4o-mini']`) |
+| `.pricing(p)` | `object` | Pricing in USD per 1M tokens (see below) |
+| `.upstreamModel(str)` | `string` | Model name forwarded upstream (e.g. `'openai/gpt-4o-mini'`) |
+
+**Pricing object:**
+
+```js
+{
+  inputUsdPerMillion:       0.15,  // required
+  cachedInputUsdPerMillion: 0.075, // optional, defaults to inputUsdPerMillion
+  outputUsdPerMillion:      0.60   // required
+}
+```
+
+> `.toJSON()` validates all required fields and throws if anything is missing.
+
+**Example:**
+
+```js
+new Offering('agent')
+  .name('Code Master')
+  .description('Best-in-class coding agent.')
+  .services(['claude-3-5-sonnet'])
+  .pricing({ inputUsdPerMillion: 3.00, cachedInputUsdPerMillion: 1.50, outputUsdPerMillion: 15.00 })
+  .upstreamModel('anthropic/claude-3-5-sonnet')
+```
+
+---
+
+### `SellerNode`
+
+Wraps a forked seller process. Extends `EventEmitter`.
+
+```js
+new SellerNode(opts)
+```
+
+**Options:**
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `peerId` | `string` | ✅ | Unique peer identifier |
+| `port` | `number` | ✅ | HTTP port to listen on |
+| `offerings` | `Offering[]` | ✅ | At least one `Offering` instance |
+| `endpoint` | `string` | — | Public URL buyers connect to (default: `http://localhost:<port>`) |
+| `merchantAddress` | `string` | — | On-chain address for payment receipts |
+| `registryUrl` | `string` | — | Registry base URL (default: `http://localhost:9000`) |
+| `apiKey` | `string` | — | Upstream AI provider key |
+| `upstreamBaseUrl` | `string` | — | Upstream base URL (default: OpenRouter) |
+| `sellerPrivateKey` | `string` | — | Seller private key for on-chain settlement |
+| `contractAddress` | `string` | — | AntseedDeposits contract address |
+| `chainName` | `string` | — | `'base'` \| `'base-sepolia'` \| `'localhost'` |
+| `rpcUrl` | `string` | — | RPC endpoint |
+| `sellerPath` | `string` | — | Override path to seller entry point |
+| `env` | `object` | — | Extra env vars passed to the child process |
+
+**Methods:**
+
+```js
+await node.start()  // fork the process; resolves once forked
+await node.stop()   // send SIGTERM and wait for exit
+node.info()         // { peerId, port, endpoint, running, offerings[] }
+```
+
+**Events:**
+
+```js
+node.on('started', ({ peerId, port }) => { /* process is up and listening */ })
+node.on('error',   (err)             => { /* fork failed */ })
+node.on('exit',    ({ peerId, code, signal }) => { /* process exited */ })
+```
+
+**Example:**
+
+```js
+import { SellerNode, Offering } from '@0xopenseeddev/sdk';
+
+const node = new SellerNode({
+  peerId: 'my-node-001',
+  port:   8401,
+  apiKey: process.env.OPENROUTER_API_KEY,
+  offerings: [
+    new Offering('inference')
+      .name('GPT-4o Mini')
+      .services(['gpt-4o-mini'])
+      .pricing({ inputUsdPerMillion: 0.15, outputUsdPerMillion: 0.60 })
+      .upstreamModel('openai/gpt-4o-mini')
+  ]
+});
+
+node.on('started', () => console.log('Node is ready!'));
+node.on('exit',    ({ code }) => console.log('Exited with code', code));
+
+await node.start();
+
+// Later:
+await node.stop();
+```
+
+---
+
+### `Network`
+
+Orchestrates multiple `SellerNode` instances with shared defaults.  
+Extends `EventEmitter`.
+
+```js
+new Network(defaults?)
+```
+
+**Defaults (applied to every node added via `.addSeller()`):**
+
+| Option | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Upstream AI provider key |
+| `upstreamBaseUrl` | `string` | Upstream base URL |
+| `registryUrl` | `string` | Registry base URL |
+| `merchantAddress` | `string` | Shared merchant address |
+| `env` | `object` | Extra env vars (merged with per-node env) |
+
+**Methods:**
+
+```js
+net.addSeller(opts)  // same opts as SellerNode; returns Network (chainable)
+await net.start()    // start all nodes concurrently; hooks SIGINT/SIGTERM
+await net.stop()     // stop all running nodes concurrently
+net.list()           // array of node.info() for each node
+net.size             // number of nodes
+```
+
+**Events:**
+
+```js
+net.on('node:started', ({ peerId, port }) => { })
+net.on('node:error',   ({ peerId, err })  => { })
+net.on('node:exit',    ({ peerId, code }) => { })
+```
+
+**Example — multi-node simulation:**
+
+```js
+import { Network, Offering } from '@0xopenseeddev/sdk';
+
+const net = new Network({
+  apiKey:      process.env.OPENROUTER_KEY,
+  registryUrl: 'http://localhost:9000',
+  merchantAddress: '0xYourAddress'
+});
+
+net
+  .addSeller({
+    port:   8401,
+    peerId: 'peer-llama-001',
+    offerings: [
+      new Offering('inference')
+        .name('Llama 3 8B')
+        .services(['llama-3-8b'])
+        .pricing({ inputUsdPerMillion: 0.05, outputUsdPerMillion: 0.05 })
+        .upstreamModel('meta-llama/llama-3-8b-instruct:free')
+    ]
+  })
+  .addSeller({
+    port:   8402,
+    peerId: 'peer-gemini-002',
+    offerings: [
+      new Offering('inference')
+        .name('Gemini 2.5 Flash')
+        .services(['gemini-2.5-flash'])
+        .pricing({ inputUsdPerMillion: 0.27, outputUsdPerMillion: 0.27 })
+        .upstreamModel('google/gemini-2.5-flash')
+    ]
+  });
+
+await net.start();
+// Ctrl+C → graceful shutdown of all nodes
+```
+
+---
+
+## Environment Variables
+
+All environment variables from the parent process are inherited by child nodes.  
+The SDK additionally injects the following:
+
+| Variable | Source |
+|---|---|
+| `PEER_ID` | `opts.peerId` |
+| `SELLER_PORT` | `opts.port` |
+| `SELLER_ENDPOINT` | `opts.endpoint` |
+| `REGISTRY_URL` | `opts.registryUrl` |
+| `OFFERINGS` | serialised JSON of offerings |
+| `MERCHANT_ADDRESS` | `opts.merchantAddress` |
+| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | `opts.apiKey` |
+| `UPSTREAM_BASE_URL` | `opts.upstreamBaseUrl` |
+| `SELLER_PRIVATE_KEY` | `opts.sellerPrivateKey` |
+| `CONTRACT_ADDRESS` | `opts.contractAddress` |
+| `CHAIN_NAME` | `opts.chainName` |
+| `RPC_URL` | `opts.rpcUrl` |
+
+---
+
+## Package Layout
+
+```
+packages/sdk/
+├── src/
+│   ├── index.js      ← barrel export
+│   ├── offering.js   ← Offering builder
+│   ├── seller.js     ← SellerNode (fork wrapper)
+│   └── network.js    ← Network (multi-node orchestrator)
+└── package.json
+```
+
+---
+
+## See Also
+
+- [`simulate.js`](../../simulate.js) — live example using the SDK to boot a 3-peer local network
+- [`packages/seller`](../seller) — the seller node implementation the SDK forks
+- [`packages/cli`](../cli) — CLI that also uses the seller node programmatically

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@0xopenseeddev/sdk",
+  "version": "0.1.0",
+  "description": "Programmatic SDK for spawning and managing OpenSeed seller nodes",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./seller": "./src/seller.js",
+    "./network": "./src/network.js"
+  },
+  "scripts": {
+    "build": "echo 'sdk has no build step'"
+  },
+  "keywords": ["openseed", "sdk", "p2p", "ai"],
+  "license": "ISC"
+}

package/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * @0xopenseeddev/sdk — Programmatic SDK for the OpenSeed network.
+ *
+ * Public API:
+ *   - Network   → orchestrate multiple seller nodes
+ *   - SellerNode → spawn a single seller node
+ *   - Offering  → fluent builder for offering definitions
+ */
+
+export { Network }    from './network.js';
+export { SellerNode } from './seller.js';
+export { Offering }   from './offering.js';

package/src/network.js

@@ -0,0 +1,112 @@
+import { EventEmitter } from 'events';
+import { SellerNode } from './seller.js';
+import { Offering } from './offering.js';
+
+/**
+ * Network — manages a group of SellerNode instances.
+ *
+ * Usage:
+ *   const net = new Network({ apiKey: '...', registryUrl: '...' });
+ *   net.addSeller({ peerId: '...', port: 8401, offerings: [...] });
+ *   net.addSeller({ ... });
+ *   await net.start();
+ *   // later:
+ *   await net.stop();
+ *
+ * @extends EventEmitter
+ */
+export class Network extends EventEmitter {
+  /**
+   * @param {object} [defaults] - default values applied to every SellerNode in this network
+   * @param {string} [defaults.apiKey]           - upstream AI provider API key
+   * @param {string} [defaults.upstreamBaseUrl]  - upstream base URL
+   * @param {string} [defaults.registryUrl]      - registry URL
+   * @param {string} [defaults.merchantAddress]  - shared merchant address
+   * @param {object} [defaults.env]              - extra env vars for every node
+   */
+  constructor(defaults = {}) {
+    super();
+    this._defaults = defaults;
+    /** @type {SellerNode[]} */
+    this._nodes = [];
+  }
+
+  /**
+   * Add a seller node to the network.
+   *
+   * @param {object} opts - same options as SellerNode constructor;
+   *   defaults from the Network constructor are merged in (node opts win).
+   * @returns {Network} this (chainable)
+   */
+  addSeller(opts) {
+    const merged = {
+      ...this._defaults,
+      ...opts,
+      env: { ...(this._defaults.env ?? {}), ...(opts.env ?? {}) }
+    };
+    this._nodes.push(new SellerNode(merged));
+    return this;
+  }
+
+  /**
+   * Start all nodes concurrently.
+   * @returns {Promise<Network>} this
+   */
+  async start() {
+    console.log(`[sdk] Starting network with ${this._nodes.length} seller node(s)…`);
+
+    await Promise.all(
+      this._nodes.map(node =>
+        node
+          .start()
+          .then(() => {
+            node.on('started', (info) => {
+              console.log(`[sdk] ✅ ${info.peerId} ready on :${info.port}`);
+              if (info.firstService) {
+                console.log(`[sdk] 💬 Chat: http://localhost:3000/?peer=${info.peerId}&service=${info.firstService}`);
+              }
+              this.emit('node:started', info);
+            });
+            node.on('error', (err) => {
+              console.error(`[sdk] ❌ ${node.peerId} error:`, err.message);
+              this.emit('node:error', { peerId: node.peerId, err });
+            });
+            node.on('exit', (info) => {
+              console.log(`[sdk] 🔴 ${info.peerId} exited (code ${info.code})`);
+              this.emit('node:exit', info);
+            });
+          })
+      )
+    );
+
+    // Gracefully handle SIGINT / SIGTERM at the network level
+    const shutdown = async () => {
+      console.log('\n[sdk] Shutting down network…');
+      await this.stop();
+      process.exit(0);
+    };
+    process.once('SIGINT',  shutdown);
+    process.once('SIGTERM', shutdown);
+
+    return this;
+  }
+
+  /**
+   * Stop all running nodes concurrently.
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    await Promise.all(this._nodes.filter(n => n.running).map(n => n.stop()));
+  }
+
+  /**
+   * Return info for every node.
+   * @returns {object[]}
+   */
+  list() {
+    return this._nodes.map(n => n.info());
+  }
+
+  /** Number of nodes in this network */
+  get size() { return this._nodes.length; }
+}

package/src/offering.js

@@ -0,0 +1,78 @@
+/**
+ * Offering builder — describes one capability a seller node advertises.
+ *
+ * Usage:
+ *   new Offering('inference')
+ *     .name('Llama 3 8B')
+ *     .description('...')
+ *     .services(['llama-3-8b'])
+ *     .pricing({ inputUsdPerMillion: 0.05, outputUsdPerMillion: 0.05 })
+ *     .upstreamModel('meta-llama/llama-3-8b-instruct:free')
+ */
+export class Offering {
+  /**
+   * @param {'inference' | 'agent' | 'tool'} capability
+   */
+  constructor(capability) {
+    this._data = {
+      capability,
+      name: '',
+      description: '',
+      services: [],
+      pricing: {
+        inputUsdPerMillion: 0,
+        cachedInputUsdPerMillion: 0,
+        outputUsdPerMillion: 0
+      },
+      upstreamModel: ''
+    };
+  }
+
+  /** @param {string} name - human-readable offering name */
+  name(name) {
+    this._data.name = name;
+    return this;
+  }
+
+  /** @param {string} desc */
+  description(desc) {
+    this._data.description = desc;
+    return this;
+  }
+
+  /**
+   * @param {string[]} serviceIds - model/service IDs buyers will request
+   */
+  services(serviceIds) {
+    this._data.services = Array.isArray(serviceIds) ? serviceIds : [serviceIds];
+    return this;
+  }
+
+  /**
+   * @param {{ inputUsdPerMillion: number, cachedInputUsdPerMillion?: number, outputUsdPerMillion: number }} p
+   */
+  pricing(p) {
+    this._data.pricing = {
+      inputUsdPerMillion: p.inputUsdPerMillion ?? 0,
+      cachedInputUsdPerMillion: p.cachedInputUsdPerMillion ?? p.inputUsdPerMillion ?? 0,
+      outputUsdPerMillion: p.outputUsdPerMillion ?? 0
+    };
+    return this;
+  }
+
+  /**
+   * @param {string} model - model name to send upstream (e.g. 'openai/gpt-4o-mini')
+   */
+  upstreamModel(model) {
+    this._data.upstreamModel = model;
+    return this;
+  }
+
+  /** @returns {object} plain JSON-serialisable object */
+  toJSON() {
+    if (!this._data.name) throw new Error('Offering is missing a name');
+    if (!this._data.services.length) throw new Error(`Offering "${this._data.name}" has no services`);
+    if (!this._data.upstreamModel) throw new Error(`Offering "${this._data.name}" is missing upstreamModel`);
+    return { ...this._data };
+  }
+}

package/src/seller.js

@@ -0,0 +1,154 @@
+import { fork } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { EventEmitter } from 'events';
+import { Offering } from './offering.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+// Default path to the seller entry point (packages/seller/src/index.js)
+const DEFAULT_SELLER_PATH = resolve(__dirname, '../../seller/src/index.js');
+
+/**
+ * SellerNode — wraps a forked seller process.
+ *
+ * Lifecycle:
+ *   node.start()  → forks the process, registers with registry
+ *   node.stop()   → sends SIGTERM (graceful deregister + close)
+ *   node.on('started' | 'error' | 'exit')  → event hooks
+ *
+ * @extends EventEmitter
+ */
+export class SellerNode extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string}   opts.peerId           - unique peer identifier
+   * @param {number}   opts.port             - HTTP port to listen on
+   * @param {string}   [opts.endpoint]       - public endpoint URL (defaults to http://localhost:<port>)
+   * @param {string}   [opts.merchantAddress]- on-chain address for payment receipts
+   * @param {Offering[]} opts.offerings      - list of Offering instances
+   * @param {string}   [opts.registryUrl]    - registry base URL (default: http://localhost:9000)
+   * @param {string}   [opts.apiKey]         - upstream AI provider key
+   * @param {string}   [opts.upstreamBaseUrl]- upstream base URL (default: openrouter)
+   * @param {string}   [opts.sellerPrivateKey] - seller private key for on-chain settlement
+   * @param {string}   [opts.contractAddress]  - AntseedDeposits contract address
+   * @param {string}   [opts.chainName]        - 'base' | 'base-sepolia' | 'localhost'
+   * @param {string}   [opts.rpcUrl]           - RPC endpoint
+   * @param {string}   [opts.sellerPath]       - override the seller entry point (for testing)
+   * @param {object}   [opts.env]             - additional environment variables to pass
+   */
+  constructor(opts = {}) {
+    super();
+
+    if (!opts.peerId)     throw new Error('SellerNode: opts.peerId is required');
+    if (!opts.port)       throw new Error('SellerNode: opts.port is required');
+    if (!opts.offerings?.length) throw new Error('SellerNode: at least one offering is required');
+
+    this.peerId          = opts.peerId;
+    this.port            = opts.port;
+    this.endpoint        = opts.endpoint        ?? `http://127.0.0.1:${opts.port}`;
+    this.merchantAddress = opts.merchantAddress ?? '';
+    this.registryUrl     = opts.registryUrl     ?? 'http://localhost:9000';
+    this.sellerPath      = opts.sellerPath      ?? DEFAULT_SELLER_PATH;
+
+    // Serialise offerings (calls toJSON() which validates each one)
+    this._offerings = opts.offerings.map(o => o instanceof Offering ? o.toJSON() : o);
+
+    this._env = {
+      ...(opts.env ?? {}),
+      PEER_ID:           this.peerId,
+      SELLER_PORT:       String(this.port),
+      SELLER_ENDPOINT:   this.endpoint,
+      REGISTRY_URL:      this.registryUrl,
+      OFFERINGS:         JSON.stringify(this._offerings),
+      ...(opts.merchantAddress   && { MERCHANT_ADDRESS:    opts.merchantAddress }),
+      ...(opts.apiKey            && { OPENAI_API_KEY:       opts.apiKey, ANTHROPIC_API_KEY: opts.apiKey }),
+      ...(opts.upstreamBaseUrl   && { UPSTREAM_BASE_URL:    opts.upstreamBaseUrl }),
+      ...(opts.sellerPrivateKey  && { SELLER_PRIVATE_KEY:   opts.sellerPrivateKey }),
+      ...(opts.contractAddress   && { CONTRACT_ADDRESS:     opts.contractAddress }),
+      ...(opts.chainName         && { CHAIN_NAME:           opts.chainName }),
+      ...(opts.rpcUrl            && { RPC_URL:              opts.rpcUrl })
+    };
+
+    /** @type {import('child_process').ChildProcess | null} */
+    this._child  = null;
+    this.running = false;
+  }
+
+  /**
+   * Fork the seller process and start the node.
+   * Resolves once the process has been forked (not necessarily listening yet).
+   * Listen for the 'started' event for a best-effort "ready" signal.
+   *
+   * @returns {Promise<SellerNode>} this
+   */
+  async start() {
+    if (this.running) {
+      throw new Error(`SellerNode ${this.peerId} is already running`);
+    }
+
+    const env = { ...process.env, ...this._env };
+
+    this._child = fork(this.sellerPath, [], { env, stdio: 'pipe' });
+    this.running = true;
+
+    // Pipe stdout/stderr and detect "listening" banner
+    this._child.stdout?.on('data', (chunk) => {
+      const text = chunk.toString();
+      process.stdout.write(`[${this.peerId.slice(0, 20)}] ${text}`);
+      if (text.includes('🐜 OpenSeed Seller')) {
+        this.emit('started', { 
+          peerId: this.peerId, 
+          port: this.port,
+          firstService: this._offerings[0]?.services[0]
+        });
+      }
+    });
+
+    this._child.stderr?.on('data', (chunk) => {
+      process.stderr.write(`[${this.peerId.slice(0, 20)}][ERR] ${chunk}`);
+    });
+
+    this._child.on('error', (err) => {
+      this.running = false;
+      this.emit('error', err);
+    });
+
+    this._child.on('exit', (code, signal) => {
+      this.running = false;
+      this._child  = null;
+      this.emit('exit', { peerId: this.peerId, code, signal });
+    });
+
+    return this;
+  }
+
+  /**
+   * Gracefully stop the seller node (sends SIGTERM).
+   * @returns {Promise<void>} resolves once the process exits
+   */
+  stop() {
+    return new Promise((resolve) => {
+      if (!this._child || !this.running) {
+        resolve();
+        return;
+      }
+      this.once('exit', () => resolve());
+      this._child.kill('SIGTERM');
+    });
+  }
+
+  /**
+   * Summary info for logging / dashboards.
+   */
+  info() {
+    return {
+      peerId:      this.peerId,
+      port:        this.port,
+      endpoint:    this.endpoint,
+      running:     this.running,
+      offerings:   this._offerings.map(o => o.name)
+    };
+  }
+}