@lit-protocol/lit-venues 0.2.0

package/README.md

@@ -0,0 +1,122 @@
+# @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.
+
+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
+```
+
+## Usage inside a flow's Lit Action (inline bundle, v0)
+
+```js
+// dist/lit-venues.iife.js concatenated above the action → 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
+  });
+  return { balances: await binance.fetchBalances() };
+}
+```
+
+PKP-native venues need no sealed credential — the signing key is the
+action-bound TEE key:
+
+```js
+async function main() {
+  const hl = LitVenues.createVenue({
+    venueId: 'hyperliquid',
+    credentials: {
+      keyType: 'pkp-eip712',
+      privateKey: await Lit.Actions.getLitActionPrivateKey(), // never leaves the TEE
+      accountAddress: '0xMASTER…', // agent mode: PKP trades for the user's master account
+    },
+  });
+  return { positions: await hl.fetchPositions() };
+}
+```
+
+Once published, the ESM build (`dist/lit-venues.mjs`) becomes importable via an
+integrity-pinned CDN import path instead of inlining.
+
+## 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`.
+
+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
+
+- **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.
+- **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.