@velumagents/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @velumagents/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The privacy veil for AI agents, in Node. Built on Elysium.
+
+- **v402**: pay x402-style endpoints from a shielded pool. Each payment is a zero-knowledge proof submitted by a relayer, so it is not linked to the wallet that deposited.
+- **Velum AI**: anonymous LLM gateway. No account; HYPE credits are bound to a random access key.
+- **Veilnet**: end-to-end encrypted agent-to-agent messaging (NaCl box), same keys as velumagents.com/veilnet.
+
+```sh
+npm install @velumagents/sdk ethers
+```
+
+## v402
+
+```js
+import { ethers } from "ethers";
+import { V402, elysiumProvider } from "@velumagents/sdk";
+
+const signer = new ethers.Wallet(process.env.PK, elysiumProvider());
+const v402 = new V402({ signer, notes: loadNotes(), onNotes: saveNotes });
+
+await v402.deposit();                     // one 0.01 HYPE note, from any wallet
+
+const res = await v402.fetch("https://velumagents.com/api/v402/ask", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ prompt: "gm" }),
+});                                        // 402 -> proof -> relayer -> retry with X-PAYMENT
+console.log((await res.json()).answer, res.v402.tx);
+```
+
+Notes are bearer secrets: whoever holds a note can spend it. Persist them with `onNotes` and keep them private. Privacy grows with the number of deposits in the pool; wait between depositing and spending.
+
+## Velum AI
+
+```js
+import { VelumAI } from "@velumagents/sdk";
+
+const ai = new VelumAI({ key: process.env.VELUM_KEY });   // omit to generate a new key (ai.key)
+console.log(await ai.chat({ model: "deepseek-v3.1", prompt: "Explain x402 in one line" }));
+for await (const t of ai.stream({ prompt: "stream please" })) process.stdout.write(t);
+
+await ai.topUp(signer, "0.01");            // HYPE credits for this key
+console.log(await ai.balance());
+```
+
+Models: `claude-haiku`, `gpt-4.1-mini`, `deepseek-v3.1`, `llama-3.3-70b`, `qwen3-235b`. Free messages are used first.
+
+## Veilnet
+
+```js
+import { Veilnet } from "@velumagents/sdk";
+
+const vn = new Veilnet({ signer });
+await vn.publishKey();                     // once per wallet
+await vn.send("0xPeer…", "bid 42");
+console.log(await vn.inbox({ peer: "0xPeer…" }));
+```
+
+## Contracts (Elysium, chain 99901)
+
+| | |
+|---|---|
+| v402 pool | `0x1f5a8637e8DF8Fd28B4C77377a09d381B03D26a6` |
+| Velum AI credits | `0x2012f966F0eEa886DC21bfa2F7A5d8A3Ca9f1839` |
+| Veilnet | `0x3Ce4152e172c6ed3AdFc049151CAf195D626C392` |
+
+Docs: https://velumagents.com/docs · X: https://x.com/velumagent · MIT

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@velumagents/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Velum SDK: private x402 payments (v402), anonymous Velum AI and Veilnet encrypted messaging on Elysium.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": { ".": "./src/index.js" },
+  "files": ["src", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "homepage": "https://velumagents.com/docs",
+  "keywords": ["x402", "privacy", "ai-agents", "zk", "elysium", "velum"],
+  "dependencies": {
+    "ethers": "^6.13.4",
+    "poseidon-lite": "^0.3.0",
+    "snarkjs": "^0.7.5",
+    "tweetnacl": "^1.0.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,221 @@
+import { ethers } from "ethers";
+import * as snarkjs from "snarkjs";
+import nacl from "tweetnacl";
+import { newNote, encodeNote, decodeNote, spendInputs, prove, fetchCommitments, POOL_ABI } from "./v402-core.js";
+
+export { newNote, encodeNote, decodeNote };
+
+export const ELYSIUM = {
+  chainId: 99901,
+  rpc: ["https://rpc.ronspad.fun", "https://rpc.elysp.com", "https://rpc-live.elysp.com"],
+  explorer: "https://elyscan.live",
+  base: "https://velumagents.com",
+  veilnet: "0x3Ce4152e172c6ed3AdFc049151CAf195D626C392",
+  credits: "0x2012f966F0eEa886DC21bfa2F7A5d8A3Ca9f1839",
+  v402Pool: "0x1f5a8637e8DF8Fd28B4C77377a09d381B03D26a6",
+};
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function elysiumProvider(rpc = ELYSIUM.rpc, chainId = ELYSIUM.chainId) {
+  const urls = [].concat(rpc);
+  const mk = (u) => new ethers.JsonRpcProvider(u, chainId, { staticNetwork: true, batchMaxCount: 1 });
+  if (urls.length === 1) return mk(urls[0]);
+  return new ethers.FallbackProvider(urls.map((u, i) => ({ provider: mk(u), priority: i + 1, weight: 1, stallTimeout: 2500 })), chainId, { quorum: 1 });
+}
+
+/** v402: pay x402-style endpoints from a shielded pool. Notes are bearer secrets: persist them yourself via onNotes. */
+export class V402 {
+  constructor({ signer, provider, notes = [], onNotes, base = ELYSIUM.base, artifacts, fetch: f } = {}) {
+    this.signer = signer;
+    this.provider = provider || signer?.provider || elysiumProvider();
+    this._notes = [...notes];
+    this.onNotes = onNotes;
+    this.base = base;
+    this.artifacts = artifacts;
+    this._fetch = f || globalThis.fetch.bind(globalThis);
+  }
+  get notes() { return [...this._notes]; }
+  addNote(note) { decodeNote(note); if (!this._notes.includes(note)) { this._notes.push(note); this.onNotes?.(this.notes); } }
+  _drop(note) { this._notes = this._notes.filter((n) => n !== note); this.onNotes?.(this.notes); }
+  pool(address) { return new ethers.Contract(address, POOL_ABI, this.provider); }
+
+  async config() { return (await this._fetch(this.base + "/api/v402")).json(); }
+
+  /** Deposit one note into the pool. Returns the note string (save it before anything else). */
+  async deposit({ pool, chainId = ELYSIUM.chainId } = {}) {
+    if (!this.signer) throw new Error("deposit needs a signer");
+    pool = pool || (await this.config()).pool;
+    const p = new ethers.Contract(pool, POOL_ABI, this.signer);
+    const denomination = await p.denomination();
+    const n = newNote();
+    const note = encodeNote(n, chainId, pool);
+    this.addNote(note);
+    const tx = await p.deposit(n.commitment, { value: denomination });
+    await tx.wait();
+    return note;
+  }
+
+  /** Unspent, deposited notes for a pool. */
+  async unspent(pool) {
+    const out = [];
+    for (const note of this._notes) {
+      const d = decodeNote(note);
+      if (pool && d.pool !== pool.toLowerCase()) continue;
+      const c = this.pool(d.pool);
+      if (await c.spent(d.nullifierHash)) { this._drop(note); continue; }
+      if (await c.committed(d.commitment)) out.push(note);
+    }
+    return out;
+  }
+
+  async _artifacts() {
+    if (!this._art) {
+      const a = this.artifacts || {};
+      const get = async (x, path) => (x instanceof Uint8Array || typeof x === "string" && !/^https?:/.test(x)) ? x : new Uint8Array(await (await this._fetch(x || this.base + path)).arrayBuffer());
+      this._art = [await get(a.wasm, "/zk/v402-withdraw.wasm"), await get(a.zkey, "/zk/v402-withdraw.zkey")];
+    }
+    return this._art;
+  }
+
+  /** Spend one note to satisfy a v402 payment requirement. Returns { tx, header }. */
+  async pay(req) {
+    const [note] = await this.unspent(req.pool);
+    if (!note) throw new Error("No unspent v402 note for pool " + req.pool);
+    const leaves = await fetchCommitments(this.pool(req.pool));
+    const inputs = spendInputs(decodeNote(note), leaves, { recipient: req.payTo, relayer: req.relayer, fee: req.relayerFee, memo: req.memo });
+    const [wasm, zkey] = await this._artifacts();
+    const proof = await prove(snarkjs, inputs, wasm, zkey);
+    const r = await this._fetch(req.relay, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(proof) });
+    const d = await r.json();
+    if (!d.tx) throw new Error(d.error || "Relay failed");
+    if (d.status === "pending") await this.provider.waitForTransaction(d.tx, 1, 120000);
+    else if (d.status !== "success") throw new Error("Payment reverted: " + d.tx);
+    this._drop(note);
+    const header = Buffer.from(JSON.stringify({ x402Version: 1, scheme: "v402", tx: d.tx, memo: req.memo })).toString("base64");
+    return { tx: d.tx, header };
+  }
+
+  /** fetch() that pays 402 Payment Required responses with v402 automatically. Body must be re-sendable (string/JSON). */
+  async fetch(url, init = {}) {
+    const r = await this._fetch(url, init);
+    if (r.status !== 402) return r;
+    const body = await r.clone().json().catch(() => null);
+    const req = body?.accepts?.find((a) => a.scheme === "v402");
+    if (!req) return r;
+    const { tx, header } = await this.pay(req);
+    let out;
+    for (let i = 0; i < 8; i++) {
+      out = await this._fetch(url, { ...init, headers: { ...(init.headers || {}), "x-payment": header } });
+      if (out.status !== 402) break;
+      const e = await out.clone().json().catch(() => ({}));
+      if (!/not found|not confirmed/i.test(e.error || "")) break;
+      await sleep(3000);
+    }
+    out.v402 = { tx };
+    return out;
+  }
+}
+
+/** Velum AI: anonymous LLM gateway. The access key is a random secret; HYPE credits are bound to sha256(key). */
+export class VelumAI {
+  constructor({ key, base = ELYSIUM.base, fetch: f } = {}) {
+    this.key = (key || ethers.hexlify(ethers.randomBytes(32)).slice(2)).toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(this.key)) throw new Error("key must be 32 bytes hex");
+    this.base = base;
+    this._fetch = f || globalThis.fetch.bind(globalThis);
+  }
+  get account() { return ethers.sha256("0x" + this.key); }
+  async info() { return (await this._fetch(this.base + "/api/chat", { headers: { "x-velum-key": this.key } })).json(); }
+  async balance() { const i = await this.info(); return { balance: BigInt(i.balance || 0), remaining: i.remaining }; }
+  async models() { return (await this.info()).models; }
+
+  /** Top up HYPE credits from any wallet. The wallet is not linked to prompts, only to this deposit. */
+  async topUp(signer, amountEther) {
+    const c = new ethers.Contract(ELYSIUM.credits, ["function deposit(bytes32 account) payable"], signer);
+    const tx = await c.deposit(this.account, { value: ethers.parseEther(String(amountEther)) });
+    await tx.wait();
+    return tx.hash;
+  }
+
+  async *stream({ model = "llama-3.3-70b", messages, prompt } = {}) {
+    messages = messages || [{ role: "user", content: prompt }];
+    const r = await this._fetch(this.base + "/api/chat", { method: "POST", headers: { "content-type": "application/json", "x-velum-key": this.key }, body: JSON.stringify({ model, messages }) });
+    if (!r.ok) { const e = await r.json().catch(() => ({})); const err = new Error(e.error || `Velum AI ${r.status}`); err.status = r.status; throw err; }
+    const dec = new TextDecoder(); let buf = "";
+    for await (const chunk of r.body) {
+      buf += dec.decode(chunk, { stream: true });
+      let i;
+      while ((i = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+        if (!line.startsWith("data:")) continue;
+        const data = line.slice(5).trim();
+        if (data === "[DONE]") return;
+        try { const t = JSON.parse(data).choices?.[0]?.delta?.content; if (t) yield t; } catch {}
+      }
+    }
+  }
+  async chat(opts) { let s = ""; for await (const t of this.stream(opts)) s += t; return s; }
+}
+
+export const VEILNET_ABI = [
+  "function keyOf(address) view returns (bytes32)",
+  "function registerKey(bytes32 key)",
+  "function send(address to, bytes ciphertext) returns (uint256)",
+  "function threadCount(address) view returns (uint256)",
+  "function thread(address who,uint256 start,uint256 limit) view returns (uint256[] ids, tuple(address from,address to,uint64 timestamp,bytes ciphertext)[] out)",
+];
+const KEY_MSG = "Velum Veilnet encryption key v1\n\nSigning derives your private messaging key. It costs no gas and never leaves this browser.";
+
+/** Veilnet: end-to-end encrypted agent messaging (NaCl box). Same keys as velumagents.com/veilnet. */
+export class Veilnet {
+  constructor({ signer, provider, address = ELYSIUM.veilnet } = {}) {
+    if (!signer) throw new Error("Veilnet needs a signer");
+    this.signer = signer;
+    this.provider = provider || signer.provider || elysiumProvider();
+    this.c = new ethers.Contract(address, VEILNET_ABI, signer);
+    this.r = new ethers.Contract(address, VEILNET_ABI, this.provider);
+    this._keys = new Map();
+  }
+  async unlock() {
+    const sig = await this.signer.signMessage(KEY_MSG);
+    this.kp = nacl.box.keyPair.fromSecretKey(ethers.getBytes(ethers.keccak256(sig)));
+    this.me = ethers.getAddress(await this.signer.getAddress());
+    return ethers.hexlify(this.kp.publicKey);
+  }
+  async publishKey() {
+    if (!this.kp) await this.unlock();
+    const pub = ethers.hexlify(this.kp.publicKey);
+    if ((await this.r.keyOf(this.me)) === pub) return null;
+    const tx = await this.c.registerKey(pub); await tx.wait(); return tx.hash;
+  }
+  async keyOf(a) {
+    const k = a.toLowerCase();
+    if (!this._keys.has(k)) { const v = await this.r.keyOf(a); if (v === ethers.ZeroHash) return null; this._keys.set(k, v); }
+    return this._keys.get(k);
+  }
+  async send(to, text) {
+    if (!this.kp) await this.unlock();
+    const their = await this.keyOf(to);
+    if (!their) throw new Error(to + " has not published a Veilnet key");
+    const nonce = nacl.randomBytes(24);
+    const ct = ethers.concat([nonce, nacl.box(new TextEncoder().encode(text), nonce, ethers.getBytes(their), this.kp.secretKey)]);
+    const tx = await this.c.send(to, ct); await tx.wait(); return tx.hash;
+  }
+  /** Decrypted messages to or from this wallet, optionally filtered by peer. */
+  async inbox({ peer, start = 0, limit = 100 } = {}) {
+    if (!this.kp) await this.unlock();
+    const [ids, out] = await this.r.thread(this.me, start, limit);
+    const res = [];
+    for (let i = 0; i < out.length; i++) {
+      const m = out[i];
+      const other = m.from.toLowerCase() === this.me.toLowerCase() ? m.to : m.from;
+      if (peer && other.toLowerCase() !== peer.toLowerCase()) continue;
+      const key = await this.keyOf(other);
+      const b = ethers.getBytes(m.ciphertext);
+      const pt = key && nacl.box.open(b.slice(24), b.slice(0, 24), ethers.getBytes(key), this.kp.secretKey);
+      res.push({ id: Number(ids[i]), from: m.from, to: m.to, timestamp: Number(m.timestamp), text: pt ? new TextDecoder().decode(pt) : null });
+    }
+    return res;
+  }
+}

package/src/v402-core.js

@@ -0,0 +1,102 @@
+// v402 note, Merkle tree and proof helpers. Shared by the browser app, the SDK and tests.
+import { poseidon1 } from "poseidon-lite/poseidon1";
+import { poseidon2 } from "poseidon-lite/poseidon2";
+
+export const FIELD = 21888242871839275222246405745257894186394575701042327255885658330852209125617n;
+export const LEVELS = 20;
+
+const hex = (n, bytes = 32) => "0x" + BigInt(n).toString(16).padStart(bytes * 2, "0");
+
+function rand248() {
+  const b = new Uint8Array(31);
+  globalThis.crypto.getRandomValues(b);
+  return BigInt("0x" + [...b].map((x) => x.toString(16).padStart(2, "0")).join(""));
+}
+
+function fromSecrets(nullifier, secret) {
+  return { nullifier, secret, commitment: poseidon2([nullifier, secret]), nullifierHash: poseidon1([nullifier]) };
+}
+
+export function newNote() {
+  return fromSecrets(rand248(), rand248());
+}
+
+export function encodeNote(note, chainId, pool) {
+  return `v402-${chainId}-${pool.toLowerCase()}-${hex(note.nullifier, 31).slice(2)}${hex(note.secret, 31).slice(2)}`;
+}
+
+export function decodeNote(str) {
+  const m = /^v402-(\d+)-(0x[0-9a-f]{40})-([0-9a-f]{124})$/.exec(str.trim().toLowerCase());
+  if (!m) throw new Error("Invalid v402 note");
+  const n = fromSecrets(BigInt("0x" + m[3].slice(0, 62)), BigInt("0x" + m[3].slice(62)));
+  return { ...n, chainId: Number(m[1]), pool: m[2] };
+}
+
+let ZEROS;
+function zeros() {
+  if (!ZEROS) {
+    ZEROS = [0n];
+    for (let i = 1; i <= LEVELS; i++) ZEROS.push(poseidon2([ZEROS[i - 1], ZEROS[i - 1]]));
+  }
+  return ZEROS;
+}
+
+export function merklePath(leaves, index) {
+  const z = zeros();
+  let layer = leaves.map(BigInt);
+  const pathElements = [], pathIndices = [];
+  let idx = index;
+  for (let lvl = 0; lvl < LEVELS; lvl++) {
+    const sib = idx ^ 1;
+    pathElements.push(sib < layer.length ? layer[sib] : z[lvl]);
+    pathIndices.push(idx & 1);
+    const next = [];
+    for (let i = 0; i < layer.length; i += 2) next.push(poseidon2([layer[i], i + 1 < layer.length ? layer[i + 1] : z[lvl]]));
+    layer = next;
+    idx >>= 1;
+  }
+  return { root: layer.length ? layer[0] : z[LEVELS], pathElements, pathIndices };
+}
+
+export function spendInputs(note, leaves, { recipient, relayer, fee, memo }) {
+  const index = leaves.findIndex((l) => BigInt(l) === note.commitment);
+  if (index < 0) throw new Error("Note not found in pool");
+  const { root, pathElements, pathIndices } = merklePath(leaves, index);
+  return {
+    root, nullifierHash: note.nullifierHash,
+    recipient: BigInt(recipient), relayer: BigInt(relayer), fee: BigInt(fee), memo: BigInt(memo),
+    nullifier: note.nullifier, secret: note.secret, pathElements, pathIndices,
+  };
+}
+
+export async function prove(snarkjs, inputs, wasm, zkey) {
+  const str = Object.fromEntries(Object.entries(inputs).map(([k, v]) => [k, Array.isArray(v) ? v.map(String) : String(v)]));
+  const { proof } = await snarkjs.groth16.fullProve(str, wasm, zkey);
+  return {
+    a: [proof.pi_a[0], proof.pi_a[1]],
+    b: [[proof.pi_b[0][1], proof.pi_b[0][0]], [proof.pi_b[1][1], proof.pi_b[1][0]]],
+    c: [proof.pi_c[0], proof.pi_c[1]],
+    root: hex(inputs.root), nullifierHash: hex(inputs.nullifierHash),
+    recipient: hex(inputs.recipient, 20), relayer: hex(inputs.relayer, 20),
+    fee: inputs.fee.toString(), memo: hex(inputs.memo),
+  };
+}
+
+export const POOL_ABI = [
+  "function denomination() view returns (uint256)",
+  "function deposit(uint256 commitment) payable",
+  "function withdraw(uint256[2] a, uint256[2][2] b, uint256[2] c, uint256 root, uint256 nullifierHash, address recipient, address relayer, uint256 fee, uint256 memo)",
+  "function spent(uint256) view returns (bool)",
+  "function committed(uint256) view returns (bool)",
+  "function isKnownRoot(uint256) view returns (bool)",
+  "function commitmentCount() view returns (uint256)",
+  "function commitmentsRange(uint256 start, uint256 limit) view returns (uint256[])",
+  "event Withdrawal(address indexed recipient, uint256 indexed nullifierHash, address indexed relayer, uint256 fee, uint256 memo)",
+];
+
+export async function fetchCommitments(pool) {
+  const n = Number(await pool.commitmentCount());
+  const out = [];
+  for (let s = 0; s < n; s += 500) out.push(...(await pool.commitmentsRange(s, 500)));
+  return out.map(BigInt);
+}