@lit-protocol/lit-venues 0.2.0 → 0.2.1

package/README.md

@@ -1,63 +1,32 @@
 # @lit-protocol/lit-venues
 
-Native exchange venue connectors for Lit Actions / Flows. Binance (+ binance.us),
-Coinbase Advanced Trade, and Hyperliquid perps behind one small, auditable,
-ccxt-shaped interface.
-
-> Ported from the Chipotle/lit-node-express runtime repo, where it was developed
-> against the Lit Action sandbox. The connectors are **plain library code** — not
-> a runtime primitive — so they live as a standalone package here in flows. The
-> two TEE-side primitives they can use (`Lit.Actions.proxiedFetch` for egress and
-> the email-approval ops) are part of the **Chipotle runtime**, not this package;
-> a flow reaches them by executing on a Chipotle environment that has them.
+Native exchange venue connectors for Lit Actions. Binance (+ binance.us), Coinbase Advanced Trade, and Hyperliquid perps behind one small, auditable, ccxt-shaped interface. Part of `plans/ccxt-venue-layer-and-email-approval.md` (D1, D8).
 
 Design constraints, by construction:
 
-- **Action-runtime portable.** Only `fetch` + plain JS — no Node built-ins, no
-  `Buffer`, no WebCrypto assumptions. Request signing (HMAC-SHA256, Ed25519,
-  ES256 JWT, EIP-712/secp256k1) uses bundled `@noble/hashes` + `@noble/curves`.
-- **Quota-aware.** Single-symbol market lookups (`fetchMarket`), no full-market
-  loads, small responses — designed for the 50-outbound-fetch / 1MB-response
-  action limits. Pre-fetched rules can be injected via `markets` to spend zero
-  fetches.
-- **Exact decimals.** Amounts/prices are decimal strings end to end; `addDec` /
-  `subDec` / `roundDownToIncrement` do scaled-BigInt math. Hyperliquid's signed
-  action hash commits to `wireDecimal`-normalized strings — no float ever
-  touches an order.
-- **Egress-ready.** A `proxy` config routes through the in-TEE
-  `Lit.Actions.proxiedFetch` op (provided by the Chipotle runtime); inert
-  elsewhere.
-
-## Build
-
-This package builds to an IIFE bundle (for inlining into a flow's action code,
-which runs as a plain script, not a module) and an ESM build:
-
-```sh
-npm install
-npm test         # vitest — signing pinned to Binance docs / RFC 8032 / Hyperliquid SDK vectors
-npm run build    # esbuild → dist/lit-venues.iife.js (+ .mjs), prints size + sha384
-npm run typecheck
-```
+- **Action-runtime portable.** Only `fetch` + plain JS — no Node built-ins, no `Buffer`, no WebCrypto assumptions. Request signing (HMAC-SHA256, Ed25519, ES256 JWT, EIP-712/secp256k1) uses bundled `@noble/hashes` + `@noble/curves`.
+- **Quota-aware.** Single-symbol market lookups (`fetchMarket`), no full-market loads, small responses — designed for the 50-outbound-fetch / 1MB-response action limits. Pre-fetched rules can be injected via `markets` to spend zero fetches.
+- **Exact decimals.** Amounts/prices are decimal strings end to end; `addDec` / `subDec` / `roundDownToIncrement` do scaled-BigInt math. Hyperliquid's signed action hash commits to `wireDecimal`-normalized strings — no float ever touches an order.
+- **Egress-ready.** A `proxy` config routes through the in-TEE `Lit.Actions.proxiedFetch` op (plan D4/M2); inert elsewhere.
 
-## Usage inside a flow's Lit Action (inline bundle, v0)
+## Usage inside a Lit Action (inline bundle, v0)
 
 ```js
-// dist/lit-venues.iife.js concatenated above the action → global `LitVenues`
+// dist/lit-venues.iife.js pasted/concatenated above this line → global `LitVenues`
 async function main({ sealedCreds }) {
   const creds = JSON.parse(await Lit.Actions.Decrypt(sealedCreds)); // venue-credentials-v1
   const binance = LitVenues.createVenue({
     venueId: 'binance',
     sandbox: true, // spot testnet
     credentials: { apiKey: creds.apiKey, secret: creds.secret, keyType: creds.keyType },
-    proxy: creds.egress?.proxyUrl, // routes via Lit.Actions.proxiedFetch; inert without it
+    proxy: creds.egress?.proxyUrl,
   });
-  return { balances: await binance.fetchBalances() };
+  const balances = await binance.fetchBalances();
+  return { balances };
 }
 ```
 
-PKP-native venues need no sealed credential — the signing key is the
-action-bound TEE key:
+PKP-native venues need no sealed credential at all — the signing key is the action-bound TEE key:
 
 ```js
 async function main() {
@@ -73,50 +42,33 @@ async function main() {
 }
 ```
 
-Once published, the ESM build (`dist/lit-venues.mjs`) becomes importable via an
-integrity-pinned CDN import path instead of inlining.
+Once published, the ESM build (`dist/lit-venues.mjs`) becomes importable via the integrity-pinned jsDelivr import path instead of inlining.
+
+## Commands
+
+```sh
+npm install
+npm test         # vitest — signing pinned to Binance docs / RFC 8032 / Hyperliquid SDK vectors
+npm run build    # esbuild → dist/lit-venues.iife.js (+ .mjs), prints size + sha384
+npm run typecheck
+node scripts/verify-live.mjs   # live conformance against REAL exchange APIs (public always; authed when keys present)
+```
+
+The M0 spike (`e2e/tests/api/lit-venues-spike.spec.ts`) executes the IIFE bundle inside a real Lit Action and fetches public tickers — including a Binance-testnet probe that doubles as the egress-geography measurement (HTTP 451 ⇒ US egress, route via proxy per plan D4).
 
 ## Surface
 
 `createVenue({ venueId, credentials?, sandbox?, proxy?, fetchImpl?, nowMs?, markets?, signFn?, slippageBps?, builder? })` → `VenueClient`:
 `fetchTicker`, `fetchMarket`, `fetchBalances`, `createOrder`, `cancelOrder`, `fetchOpenOrders`, `fetchMyTrades`,
-plus the optional perp surface: `fetchPositions`, `setLeverage`, `fetchFundingRate`.
+plus the optional perp surface (plan D8): `fetchPositions`, `setLeverage`, `fetchFundingRate`.
 
-Errors are `VenueError` with a unified taxonomy: `auth`, `insufficient_funds`,
-`bad_symbol`, `rate_limited`, `venue_unavailable`, `invalid_request`, `unknown`
-(plus `httpStatus` / raw `venueCode`).
+Errors are `VenueError` with a unified taxonomy: `auth`, `insufficient_funds`, `bad_symbol`, `rate_limited`, `venue_unavailable`, `invalid_request`, `unknown` (plus `httpStatus` / raw `venueCode`).
 
-Amounts/prices are **decimal strings** end to end — use `LitVenues.addDec` /
-`subDec` / `roundDownToIncrement`, never floats.
+Venue notes:
 
-## Venue notes
-
-- **binance** — `sandbox: true` → `testnet.binance.vision`. HMAC by default; set
-  `keyType: 'ed25519'` for Binance's recommended self-generated keys (PKCS8 PEM,
-  hex, or base64). binance.com geo-blocks US egress (451) — route through the
-  egress proxy or use the spot testnet.
+- **binance** — `sandbox: true` → `testnet.binance.vision`. HMAC by default; set `keyType: 'ed25519'` for Binance's recommended self-generated keys (PKCS8 PEM, hex, or base64 accepted). binance.com geo-blocks US egress (451) — the error message says so explicitly.
 - **binanceus** — separate venue id, no testnet.
-- **coinbase** — Advanced Trade with CDP keys (ES256 JWT; no Ed25519 here). PEMs
-  accepted with real newlines OR the literal `\n` of the CDP JSON download. **No
-  sandbox** — `sandbox: true` throws. Market BUY orders take `quoteAmount`.
-- **hyperliquid** — PKP-native perps: no API key; every trading action is an
-  EIP-712 signature (msgpack action hash → phantom agent, chainId 1337), pinned
-  byte-for-byte to the official SDK's test vectors in
-  `test/hyperliquid-signing.test.ts`. `sandbox: true` →
-  `api.hyperliquid-testnet.xyz`. Reads work with `accountAddress` alone; trading
-  needs `privateKey` (or a custom `signFn`). When the key is a registered agent
-  (API wallet), reads auto-resolve its MASTER. `approveAgent()` lets a master key
-  grant the PKP trade-only powers — agents structurally cannot withdraw.
-  `fetchBalances` merges perp equity + spot USDC. Market orders are aggressive IOC
-  limits (`slippageBps`, default 5%) obeying 5-sig-fig / szDecimals rules.
-
-Withdrawal endpoints are deliberately absent (policy-gated sweeps go through the
-Chipotle runtime's email-approval primitive).
-
-## What stayed in the Chipotle runtime repo
-
-- `op_lit_proxied_fetch` (`Lit.Actions.proxiedFetch`) — in-TEE egress op (Rust).
-- The email-approval ops + `ApprovalService` (in-TEE attestation verify).
-- The chipotle SDK quickstart examples (CID-pinned PKP setup scripts).
-
-Those are runtime/SDK concerns, not portable library code, so they remain there.
+- **coinbase** — Advanced Trade with CDP keys (ES256 JWT; Coinbase does not support Ed25519 here). PEMs are accepted with real newlines OR the literal `\n` sequences of the CDP JSON download. No sandbox exists; `sandbox: true` throws rather than pretending. Market BUY orders take `quoteAmount` (quote-asset size) per Advanced Trade semantics.
+- **hyperliquid** — PKP-native perps (plan D8): no API key; every trading action is an EIP-712 signature (msgpack action hash → phantom agent, chainId 1337), pinned byte-for-byte to the official SDK's test vectors in `test/hyperliquid-signing.test.ts`. `sandbox: true` → `api.hyperliquid-testnet.xyz` (full lifecycle testable). Reads work with `accountAddress` alone; trading needs `privateKey` (or a custom `signFn`). When the key is a registered agent (API wallet), reads auto-resolve its MASTER via the venue's `userRole` lookup (cached) — agent accounts themselves are always empty. `approveAgent()` lets a master key grant the PKP trade-only powers — agents structurally cannot withdraw, transfer, or move USDC between balance classes. On **unified accounts** (the venue's newer default) perps margin directly from the unified/spot balance and manual spot↔perp transfers are disabled; on legacy split accounts the master moves margin via the user-signed `usdClassTransfer`. `fetchBalances` therefore merges both pools: one USDC row (perp equity + spot USDC, `free` preferring the venue's available-after-maintenance figure) plus any other spot coins; positions read the perp clearinghouse. Market orders are aggressive IOC limits (`slippageBps`, default 5%); prices obey the 5-sig-fig and `MAX_DECIMALS − szDecimals` rules (integers always valid); sizes are quantized to `szDecimals`. Optional `builder` attaches a builder-code fee to orders.
+
+Withdrawal endpoints are deliberately absent (plan: policy-gated sweeps go through the email-approval primitive).

package/dist/lit-venues.iife.js

@@ -3693,6 +3693,7 @@ var LitVenues = (() => {
     const bytes = b64decode(s);
     if (bytes.length === 32) return bytes;
     if (bytes.length === 48 && findSeq(bytes, PKCS8_ED25519_PREFIX) === 0) return bytes.subarray(16);
+    if (bytes.length === 64) return bytes.subarray(0, 32);
     throw new Error("lit-venues: unsupported Ed25519 private key format");
   }
   var EC_KEY_MARKER = [2, 1, 1, 4, 32];
@@ -3752,6 +3753,26 @@ var LitVenues = (() => {
     const sig = p2562.sign(sha2562(utf8ToBytes(signingInput)), priv);
     return `${signingInput}.${b64urlEncode(sig.toCompactRawBytes())}`;
   }
+  function edDsaJwt(input) {
+    const nowSec = Math.floor((input.nowMs ?? Date.now()) / 1e3);
+    const header = {
+      alg: "EdDSA",
+      kid: input.keyName,
+      nonce: input.nonce ?? randomHex(16),
+      typ: "JWT"
+    };
+    const payload = {
+      iss: "cdp",
+      nbf: nowSec,
+      exp: nowSec + (input.ttlSec ?? 120),
+      sub: input.keyName,
+      uri: input.uri
+    };
+    const signingInput = b64urlEncode(utf8ToBytes(JSON.stringify(header))) + "." + b64urlEncode(utf8ToBytes(JSON.stringify(payload)));
+    const seed = parseEd25519PrivateKey(input.privateKey);
+    const sig = ed25519.sign(utf8ToBytes(signingInput), seed);
+    return `${signingInput}.${b64urlEncode(sig)}`;
+  }
 
   // src/venues/binance.ts
   var BASES = {
@@ -4007,12 +4028,14 @@ var LitVenues = (() => {
         if (!creds?.apiKey || !creds.secret) {
           throw new VenueError(this.venueId, "auth", "this call requires credentials (CDP key name + private key)");
         }
-        headers.Authorization = `Bearer ${es256Jwt({
+        const jwtInput = {
           keyName: creds.apiKey,
           privateKey: creds.secret,
           uri: `${method} ${HOST}${path}`,
           nowMs: this.now()
-        })}`;
+        };
+        const token = creds.keyType === "eddsa-jwt" ? edDsaJwt(jwtInput) : es256Jwt(jwtInput);
+        headers.Authorization = `Bearer ${token}`;
       }
       let body;
       if (opts.body !== void 0) {

package/dist/lit-venues.mjs

@@ -3628,6 +3628,7 @@ function parseEd25519PrivateKey(input) {
   const bytes = b64decode(s);
   if (bytes.length === 32) return bytes;
   if (bytes.length === 48 && findSeq(bytes, PKCS8_ED25519_PREFIX) === 0) return bytes.subarray(16);
+  if (bytes.length === 64) return bytes.subarray(0, 32);
   throw new Error("lit-venues: unsupported Ed25519 private key format");
 }
 var EC_KEY_MARKER = [2, 1, 1, 4, 32];
@@ -3687,6 +3688,26 @@ function es256Jwt(input) {
   const sig = p2562.sign(sha2562(utf8ToBytes(signingInput)), priv);
   return `${signingInput}.${b64urlEncode(sig.toCompactRawBytes())}`;
 }
+function edDsaJwt(input) {
+  const nowSec = Math.floor((input.nowMs ?? Date.now()) / 1e3);
+  const header = {
+    alg: "EdDSA",
+    kid: input.keyName,
+    nonce: input.nonce ?? randomHex(16),
+    typ: "JWT"
+  };
+  const payload = {
+    iss: "cdp",
+    nbf: nowSec,
+    exp: nowSec + (input.ttlSec ?? 120),
+    sub: input.keyName,
+    uri: input.uri
+  };
+  const signingInput = b64urlEncode(utf8ToBytes(JSON.stringify(header))) + "." + b64urlEncode(utf8ToBytes(JSON.stringify(payload)));
+  const seed = parseEd25519PrivateKey(input.privateKey);
+  const sig = ed25519.sign(utf8ToBytes(signingInput), seed);
+  return `${signingInput}.${b64urlEncode(sig)}`;
+}
 
 // src/venues/binance.ts
 var BASES = {
@@ -3942,12 +3963,14 @@ var CoinbaseClient = class {
       if (!creds?.apiKey || !creds.secret) {
         throw new VenueError(this.venueId, "auth", "this call requires credentials (CDP key name + private key)");
       }
-      headers.Authorization = `Bearer ${es256Jwt({
+      const jwtInput = {
         keyName: creds.apiKey,
         privateKey: creds.secret,
         uri: `${method} ${HOST}${path}`,
         nowMs: this.now()
-      })}`;
+      };
+      const token = creds.keyType === "eddsa-jwt" ? edDsaJwt(jwtInput) : es256Jwt(jwtInput);
+      headers.Authorization = `Bearer ${token}`;
     }
     let body;
     if (opts.body !== void 0) {

package/package.json

@@ -1,45 +1,24 @@
 {
   "name": "@lit-protocol/lit-venues",
-  "version": "0.2.0",
-  "description": "Native exchange venue connectors for Lit Actions (Binance, Coinbase, Hyperliquid). REST-only, fetch-based, noble crypto inlined — no Node built-ins.",
+  "version": "0.2.1",
+  "description": "Native exchange venue connectors for Lit Actions (Binance, Coinbase). REST-only, fetch-based, noble crypto inlined — no Node built-ins.",
   "type": "module",
   "main": "./dist/lit-venues.mjs",
+  "files": ["dist"],
+  "publishConfig": { "access": "public" },
   "scripts": {
     "build": "node scripts/bundle.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": [
-    "lit-protocol",
-    "flows",
-    "venues",
-    "binance",
-    "coinbase",
-    "hyperliquid",
-    "ccxt"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/LIT-Protocol/flows"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist"
-  ],
   "dependencies": {
     "@noble/curves": "^1.9.0",
     "@noble/hashes": "^1.8.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.9.3",
     "esbuild": "^0.25.0",
-    "typescript": "^5.7.0",
+    "typescript": "^5.6.3",
     "undici": "^8.4.1",
     "vitest": "^3.0.0"
   }