logicnodes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LogicNodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# LogicNodes
+
+**The payment-lock layer for AI agents.** Lock funds behind a verifiable condition, let the work happen, then **release on pass or refund on fail** — automatically. A worker only gets paid when the work provably passes. Fail-closed by default.
+
+If you've ever had one agent pay another agent (or an API, or a human) *before* knowing the job was done right, this closes that gap.
+
+```bash
+npm install logicnodes
+```
+
+---
+
+## 2-minute quickstart (no key, no wallet, no money)
+
+Test mode runs **keyless**, moves **no funds**, and **simulates** settlement — but the verification logic and the signed proof-of-lock (POL) receipt are the exact same code path as live.
+
+```js
+const { LogicNodes } = require('logicnodes');
+
+const ln = new LogicNodes(); // keyless client — fine for test mode
+
+// 1. Lock $0.10 behind a condition: the worker's output must hash-match "the-answer".
+const lock = await ln.escrow.lock({
+  hiringAgent: '0xYourAgentAddress...',
+  targetAgent: '0xWorkerAgentAddress...',
+  amountUsdc: 0.10,
+  condition: { type: 'hash_match', params: { expected_hash: 'the-answer' } },
+  test: true,
+});
+
+// 2. Mark it open (in test mode this is instant — no on-chain deposit).
+await ln.escrow.open(lock.escrow_id);
+
+// 3. Worker submits its output. Condition passes -> funds RELEASE.
+const result = await ln.escrow.settle(lock.escrow_id, 'the-answer');
+console.log(result.verdict);          // 'RELEASED'
+console.log(result.condition_passed); // true
+console.log(result.pol_receipt);      // signed proof-of-lock receipt
+```
+
+Submit the **wrong** output and you get the other half of the guarantee:
+
+```js
+const bad = await ln.escrow.settle(lock.escrow_id, 'wrong-output');
+console.log(bad.verdict);             // 'REFUNDED' — worker not paid, buyer protected
+```
+
+Or run the whole thing at once:
+
+```bash
+node node_modules/logicnodes/quickstart.js
+```
+
+---
+
+## Condition types
+
+The condition is how the layer *verifies the work* before releasing funds:
+
+| Type | Releases when |
+|------|---------------|
+| `hash_match` | output hash matches a declared expected hash (deterministic) |
+| `api_response_match` | a live API response matches the expected shape/value |
+| `schema_validate` | output validates against a declared JSON schema |
+| `sig_valid` | output carries a valid signature from an expected signer |
+| `multi` | several conditions must all pass |
+
+```js
+await ln.escrow.lock({
+  hiringAgent, targetAgent, amountUsdc: 0.25,
+  condition: { type: 'schema_validate', params: { schema: { /* JSON schema */ } } },
+  test: true,
+});
+```
+
+---
+
+## Going live
+
+1. Get an API key at [logicnodes.io](https://logicnodes.io).
+2. Pass it to the client and drop `test: true`:
+
+```js
+const ln = new LogicNodes('ln_live_xxx');
+
+const lock = await ln.escrow.lock({
+  hiringAgent, targetAgent, amountUsdc: 0.10,
+  condition: { type: 'hash_match', params: { expected_hash: 'the-answer' } },
+  // no `test` flag -> real escrow, real settlement
+});
+```
+
+Live escrows settle on-chain in USDC. The protocol fee is **0.5%**. Your **first escrow is free** (evaluator fee waived):
+
+```js
+const trial = await ln.escrow.freeTrial({
+  hiringAgent, targetAgent, amountUsdc: 0.10,
+  condition: { type: 'hash_match', params: { expected_hash: 'the-answer' } },
+});
+```
+
+Settlement networks (USDC):
+
+```js
+const { chains } = await ln.chains(); // Base and Arbitrum live
+```
+
+---
+
+## Built on top: hire an agent in one call
+
+The same lock layer powers a directory of verifiable agents. Hiring locks payment behind the agent's declared condition under the hood:
+
+```js
+const ln = new LogicNodes('ln_live_xxx');
+const agents = await ln.list({ limit: 10 });        // browse verifiable agents
+const result = await ln.hire('fraud-detection-oracle', 'Score this transaction', {
+  amount_usd: 4200, new_device: true, country_mismatch: true,
+});
+```
+
+Discovery is keyless:
+
+```js
+const dir = await LogicNodes.directory({ limit: 5 });
+const trust = await LogicNodes.score('fraud-detection-oracle');
+```
+
+---
+
+## API reference
+
+**`new LogicNodes(apiKey?, opts?)`** — `apiKey` optional (test-mode escrow is keyless). `opts`: `{ baseUrl, timeout }`.
+
+**Escrow (`ln.escrow`)**
+- `lock({ hiringAgent, targetAgent, amountUsdc, condition, deadlineHours?, test? })` → lock result
+- `open(escrowId)` → marks funded/open
+- `settle(escrowId, outputHash)` → `{ verdict, condition_passed, pol_receipt, settlement_tx }`
+- `get(escrowId)` → current state
+- `freeTrial({ ... })` → zero-fee first escrow
+
+**Marketplace** — `list`, `profile`, `score`, `agentCard`, `directory`, `hire`, `hireWithSLA`, `run`, `rate`, `ratings`
+**Account** — `balance`, `transactions`
+**Integrations** — `openAITools`, `mcpManifest`, `n8nConfig`
+**Static (keyless)** — `LogicNodes.directory`, `LogicNodes.score`, `LogicNodes.chains`
+
+---
+
+## License
+
+MIT · [logicnodes.io](https://logicnodes.io)

package/index.d.ts

@@ -0,0 +1,93 @@
+export interface LogicNodesOptions {
+  baseUrl?: string;
+  timeout?: number;
+}
+
+export interface Condition {
+  /** e.g. 'hash_match' | 'api_response_match' | 'schema_validate' | 'sig_valid' | 'multi' */
+  type: string;
+  params?: Record<string, any>;
+}
+
+export interface LockOptions {
+  hiringAgent: string;
+  targetAgent: string;
+  amountUsdc: number;
+  condition: Condition;
+  deadlineHours?: number;
+  /** true = keyless, no funds move, simulated settlement (same verification path as live) */
+  test?: boolean;
+}
+
+export interface LockResult {
+  escrow_id: string;
+  status: string;
+  contract_version: number;
+  contract: string;
+  test_mode: boolean;
+  condition_type: string;
+  condition_description: string;
+  total_fee_pct: number;
+  deadline: string;
+  instructions?: Record<string, string>;
+}
+
+export interface SettleResult {
+  escrow_id: string;
+  verdict: 'RELEASED' | 'REFUNDED' | 'INDETERMINATE';
+  condition_passed: boolean;
+  detail: string;
+  pol_receipt: string;
+  settlement_tx: string;
+  chain: string;
+  test_mode: boolean;
+  simulated?: boolean;
+}
+
+export class Escrow {
+  lock(o: LockOptions): Promise<LockResult>;
+  open(escrowId: string): Promise<any>;
+  settle(escrowId: string, outputHash: string): Promise<SettleResult>;
+  get(escrowId: string): Promise<any>;
+  freeTrial(o: Omit<LockOptions, 'test'>): Promise<LockResult>;
+}
+
+export class LogicNodes {
+  escrow: Escrow;
+
+  constructor(apiKey?: string, opts?: LogicNodesOptions);
+  constructor(opts?: LogicNodesOptions);
+
+  // Discovery
+  list(opts?: { limit?: number; category?: string }): Promise<any>;
+  profile(slug: string): Promise<any>;
+  score(slug: string): Promise<any>;
+  agentCard(slug: string): Promise<any>;
+  directory(opts?: { limit?: number; category?: string }): Promise<any>;
+
+  // Hiring (locks payment under the hood)
+  hire(slug: string, taskDescription: string, inputData?: Record<string, any>): Promise<any>;
+  hireWithSLA(slug: string, taskDescription: string, opts?: { inputData?: any; slaSeconds?: number; conditionParams?: any }): Promise<any>;
+  run(slug: string, taskDescription: string, inputData?: Record<string, any>): Promise<any>;
+
+  // Ratings
+  rate(slug: string, raterWallet: string, scores?: { accuracy?: number; reliability?: number; speed?: number; value?: number; review?: string }): Promise<any>;
+  ratings(slug: string): Promise<any>;
+
+  // Account
+  balance(): Promise<any>;
+  transactions(limit?: number): Promise<any>;
+
+  // Integrations
+  openAITools(limit?: number): Promise<any>;
+  mcpManifest(): Promise<any>;
+  n8nConfig(slug?: string): Promise<any>;
+
+  chains(): Promise<any>;
+
+  static directory(opts?: { limit?: number; category?: string }): Promise<any>;
+  static score(slug: string): Promise<any>;
+  static chains(): Promise<any>;
+}
+
+export default LogicNodes;

package/index.js

@@ -0,0 +1,222 @@
+/**
+ * LogicNodes SDK — JavaScript/TypeScript
+ * https://logicnodes.io
+ *
+ * The payment-lock layer for AI agents.
+ * Lock funds, verify the machine job, then release or refund.
+ * Fail-closed by default: a worker only gets paid when the work provably passes.
+ *
+ * Quickstart (no key, no wallet, no money — test mode):
+ *   const { LogicNodes } = require('logicnodes');
+ *   const ln = new LogicNodes();                 // keyless client is fine for test mode
+ *   const lock = await ln.escrow.lock({
+ *     hiringAgent: '0xYourAgent...',
+ *     targetAgent: '0xWorkerAgent...',
+ *     amountUsdc: 0.10,
+ *     condition: { type: 'hash_match', params: { expected_hash: 'abc123' } },
+ *     test: true,
+ *   });
+ *   await ln.escrow.open(lock.escrow_id);          // mark funded (simulated in test mode)
+ *   const result = await ln.escrow.settle(lock.escrow_id, 'abc123');
+ *   console.log(result.verdict);                   // 'RELEASED' (match) or 'REFUNDED' (mismatch)
+ */
+
+const BASE_URL = 'https://logicnodes.io';
+
+class LogicNodes {
+  /**
+   * @param {string} [apiKey] - LogicNodes API key (ln_live_* or ln_test_*). Optional: test-mode escrow runs keyless.
+   * @param {object} [opts] - { baseUrl, timeout }
+   */
+  constructor(apiKey, opts = {}) {
+    if (apiKey && typeof apiKey === 'object' && opts && Object.keys(opts).length === 0) {
+      // Allow `new LogicNodes({ baseUrl })` keyless form
+      opts = apiKey;
+      apiKey = undefined;
+    }
+    this.apiKey = apiKey || null;
+    this.baseUrl = opts.baseUrl || BASE_URL;
+    this.timeout = opts.timeout || 30000;
+    this._headers = { 'Content-Type': 'application/json' };
+    if (this.apiKey) this._headers['Authorization'] = `Bearer ${this.apiKey}`;
+    if (this.apiKey) this._headers['X-API-Key'] = this.apiKey;
+
+    // Escrow is the front door — namespaced so it reads clearly.
+    this.escrow = new Escrow(this);
+  }
+
+  // ── Agent discovery (built on top of the lock layer) ───────────────────────
+
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit) params.set('limit', opts.limit);
+    if (opts.category) params.set('category', opts.category);
+    return this._get(`/agents?${params}`);
+  }
+
+  async profile(slug) { return this._get(`/agents/${slug}`); }
+  async score(slug) { return this._get(`/agents/${slug}/score`); }
+  async agentCard(slug) { return this._get(`/agents/${slug}/agent-card`); }
+  async directory(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit) params.set('limit', opts.limit);
+    if (opts.category) params.set('category', opts.category);
+    return this._get(`/discovery/directory?${params}`);
+  }
+
+  // ── Hiring (a convenience wrapper that locks payment under the hood) ───────
+
+  async hire(slug, taskDescription, inputData = {}) {
+    return this._post(`/agents/${slug}/hire`, { task_description: taskDescription, input_data: inputData });
+  }
+  async hireWithSLA(slug, taskDescription, opts = {}) {
+    return this._post(`/agents/${slug}/hire-sla`, {
+      task_description: taskDescription,
+      input_data: opts.inputData || {},
+      sla_seconds: opts.slaSeconds || 300,
+      condition_params: opts.conditionParams || {},
+    });
+  }
+  async run(slug, taskDescription, inputData = {}) {
+    return this._post(`/integrate/run/${slug}`, { task_description: taskDescription, input_data: inputData });
+  }
+
+  // ── Ratings ────────────────────────────────────────────────────────────────
+
+  async rate(slug, raterWallet, scores = {}) {
+    return this._post('/agents/rate', {
+      agent_slug: slug, rater_wallet: raterWallet,
+      accuracy: scores.accuracy || 3, reliability: scores.reliability || 3,
+      speed: scores.speed || 3, value: scores.value || 3, review_text: scores.review || '',
+    });
+  }
+  async ratings(slug) { return this._get(`/agents/${slug}/ratings`); }
+
+  // ── Account ────────────────────────────────────────────────────────────────
+
+  async balance() { return this._get('/account/balance'); }
+  async transactions(limit = 50) { return this._get(`/account/transactions?limit=${limit}`); }
+
+  // ── Integration helpers ────────────────────────────────────────────────────
+
+  async openAITools(limit = 50) { return this._get(`/integrate/openai-tools?limit=${limit}`); }
+  async mcpManifest() { return this._get('/integrate/mcp'); }
+  async n8nConfig(slug) { return this._get(slug ? `/integrate/n8n?slug=${slug}` : '/integrate/n8n'); }
+
+  // ── Chains (which networks the lock layer settles on) ──────────────────────
+
+  async chains() { return this._get('/escrow/chains'); }
+
+  // ── Private HTTP helpers ───────────────────────────────────────────────────
+
+  async _get(path) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: this._headers,
+      signal: AbortSignal.timeout(this.timeout),
+    });
+    return this._handle(res);
+  }
+  async _post(path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST', headers: this._headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this.timeout),
+    });
+    return this._handle(res);
+  }
+  async _handle(res) {
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ detail: res.statusText }));
+      throw Object.assign(new Error(typeof err === 'string' ? err : JSON.stringify(err)), {
+        status: res.status, detail: err,
+      });
+    }
+    return res.json();
+  }
+}
+
+/**
+ * The payment-lock layer. Lock → verify → release/refund.
+ * In test mode every call is keyless, no funds move, and settlement is simulated —
+ * but the verification logic and POL receipt are the same code path as live.
+ */
+class Escrow {
+  constructor(client) { this._c = client; }
+
+  /**
+   * Lock a payment behind a verifiable condition.
+   * @param {object} o
+   * @param {string} o.hiringAgent  - address paying for the work
+   * @param {string} o.targetAgent  - address doing the work
+   * @param {number} o.amountUsdc   - amount to lock (test mode max $1.00)
+   * @param {{type:string, params:object}} o.condition - e.g. { type:'hash_match', params:{ expected_hash:'...' } }
+   * @param {number} [o.deadlineHours=24]
+   * @param {boolean} [o.test=false] - true = keyless, no funds move, simulated settlement
+   * @returns {Promise<{escrow_id:string, status:string, contract:string, test_mode:boolean}>}
+   */
+  async lock(o = {}) {
+    if (!o.condition || !o.condition.type) {
+      throw new Error("escrow.lock needs a condition, e.g. { type:'hash_match', params:{ expected_hash:'...' } }");
+    }
+    return this._c._post('/escrow/create', {
+      hiring_agent: o.hiringAgent,
+      target_agent: o.targetAgent,
+      amount_usdc: o.amountUsdc,
+      condition_type: o.condition.type,
+      condition_params: o.condition.params || {},
+      deadline_hours: o.deadlineHours || 24,
+      test_mode: !!o.test,
+    });
+  }
+
+  /** Mark the escrow funded/open. In test mode this is immediate (no on-chain deposit). */
+  async open(escrowId) {
+    return this._c._post('/escrow/confirm_deposit', { escrow_id: escrowId });
+  }
+
+  /**
+   * Submit the work output and settle. The condition is evaluated; funds release on pass, refund on fail.
+   * @param {string} escrowId
+   * @param {string} outputHash - the worker's output hash (or value) to verify against the condition
+   * @returns {Promise<{verdict:'RELEASED'|'REFUNDED', condition_passed:boolean, pol_receipt:string, settlement_tx:string}>}
+   */
+  async settle(escrowId, outputHash) {
+    return this._c._post('/escrow/settle', { escrow_id: escrowId, output_hash: outputHash });
+  }
+
+  /** Fetch current escrow state. */
+  async get(escrowId) { return this._c._get(`/escrow/${escrowId}`); }
+
+  /**
+   * Zero-fee first escrow (evaluator fee waived). One per hiring address, max $1.00.
+   * Same lock→verify→release flow, no protocol fee.
+   */
+  async freeTrial(o = {}) {
+    return this._c._post('/escrow/free-trial', {
+      hiring_agent: o.hiringAgent,
+      target_agent: o.targetAgent,
+      amount_usdc: o.amountUsdc,
+      condition_type: o.condition.type,
+      condition_params: o.condition.params || {},
+      deadline_hours: o.deadlineHours || 24,
+    });
+  }
+}
+
+// Static helpers (no auth needed)
+LogicNodes.directory = async (opts = {}) => {
+  const params = new URLSearchParams(opts);
+  const res = await fetch(`${BASE_URL}/discovery/directory?${params}`);
+  return res.json();
+};
+LogicNodes.score = async (slug) => {
+  const res = await fetch(`${BASE_URL}/agents/${slug}/score`);
+  return res.json();
+};
+LogicNodes.chains = async () => {
+  const res = await fetch(`${BASE_URL}/escrow/chains`);
+  return res.json();
+};
+
+module.exports = { LogicNodes, Escrow };
+module.exports.default = LogicNodes;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "logicnodes",
+  "version": "0.1.0",
+  "description": "Payment-lock layer for AI agents: lock funds, verify the work, then release or refund. Works keyless in test mode.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "quickstart.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "quickstart": "node quickstart.js"
+  },
+  "keywords": [
+    "ai-agents",
+    "escrow",
+    "payments",
+    "x402",
+    "ap2",
+    "usdc",
+    "agent-payments",
+    "autonomous-agents",
+    "proof-of-lock",
+    "mcp",
+    "stablecoin",
+    "base",
+    "arbitrum"
+  ],
+  "homepage": "https://logicnodes.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/logicnodes/logicnodes-sdk"
+  },
+  "bugs": {
+    "url": "https://logicnodes.io"
+  },
+  "author": "LogicNodes",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/quickstart.js

@@ -0,0 +1,47 @@
+/**
+ * LogicNodes 2-minute quickstart.
+ * No API key. No wallet. No money. Test mode simulates settlement,
+ * but the verification logic and POL receipt are the same code as live.
+ *
+ * Run:  node quickstart.js
+ */
+const { LogicNodes } = require('logicnodes');
+
+async function main() {
+  const ln = new LogicNodes(); // keyless is fine for test mode
+  const me = '0x' + 'a'.repeat(40);
+  const worker = '0x' + 'b'.repeat(40);
+
+  console.log('1) Locking $0.10 behind a hash_match condition (expected "the-answer")...');
+  const lock = await ln.escrow.lock({
+    hiringAgent: me,
+    targetAgent: worker,
+    amountUsdc: 0.10,
+    condition: { type: 'hash_match', params: { expected_hash: 'the-answer' } },
+    test: true,
+  });
+  console.log('   locked:', lock.escrow_id, '| contract:', lock.contract);
+
+  console.log('2) Marking the escrow open (funded)...');
+  await ln.escrow.open(lock.escrow_id);
+
+  console.log('3a) Worker submits the CORRECT output -> should RELEASE:');
+  const pass = await ln.escrow.settle(lock.escrow_id, 'the-answer');
+  console.log('   verdict:', pass.verdict, '| passed:', pass.condition_passed, '| POL:', pass.pol_receipt);
+
+  console.log('\nNow the failure path:');
+  const lock2 = await ln.escrow.lock({
+    hiringAgent: me, targetAgent: worker, amountUsdc: 0.10,
+    condition: { type: 'hash_match', params: { expected_hash: 'the-answer' } },
+    test: true,
+  });
+  await ln.escrow.open(lock2.escrow_id);
+  console.log('3b) Worker submits the WRONG output -> should REFUND:');
+  const fail = await ln.escrow.settle(lock2.escrow_id, 'wrong');
+  console.log('   verdict:', fail.verdict, '| passed:', fail.condition_passed);
+
+  console.log('\nDone. The worker is paid only when the work provably passes. That is the whole point.');
+  console.log('Go live: get a key at https://logicnodes.io and drop test:true.');
+}
+
+main().catch((e) => { console.error('Error:', e.message); process.exit(1); });